fix(anchor): manifest SHA vs tag ref precedence ambiguity — document + enforce #380

New issue

Closed

opened 2026-07-04 20:29:48 +02:00 by bosun · 0 comments

bosun commented

2026-07-04 20:29:48 +02:00

Owner

Empirical finding (external cold-read round 4)

.release-toolkit-manifest.json records the SHA of the last cut. Existing tag (via Forgejo API) records what the tag currently points to. If they disagree (force-push after cut, manual tag surgery, cross-repo mirror desync), release-decide.sh anchor logic uses the manifest SHA. Adopter intuition says the tag itself should be authoritative — the code's chosen precedence is undocumented + potentially counterintuitive.

Blocking rationale

Silent divergence between manifest and tag → release cut anchored to unexpected commit → CHANGELOG walks unexpected range → release notes surface unrelated commits. Trust-breaking on adopter's first "wait, why is that in the release notes?" moment.

Fix path

Two axes:

Axis 1 — precedence rule: which wins on disagreement? Options: (a) manifest wins silently (current), (b) tag wins silently, (c) fail loud on disagreement, (d) prefer newer SHA by commit-date. My lean: (c) fail loud for v1.0.0, add explicit resolution modes in v1.1.0.

Axis 2 — document the rule: whatever we pick, name it in docs/integration.md + name the disagreement scenarios adopters might hit.

Verification AC

Test: manifest at SHA A, tag at SHA B → clear outcome (either error or documented winner)
docs/integration.md names the precedence rule + when adopters hit disagreement
External cold-read round 5 finds no anchor-precedence ambiguity

Anchor

External outside-model cold-read round 4 (fresh ChatGPT session, 2026-07-03 late). Verdict: 'promising but not yet trustworthy' — SAME TIER as round-3 despite round-3 delta cycle. Meta-pattern named this round: grep-sweep-missed-siblings — the sweep-pattern targeted the literal grep-target, not the semantic class, so class-axis closed PARTIALLY per round. Operator ratified filing round-4 trackers 2026-07-04. This tracker addresses one of the round-4 findings. Success criterion: subsequent external cold-read returns no further objections of this class.

BLOCKING v1.0.0.

## Empirical finding (external cold-read round 4) `.release-toolkit-manifest.json` records the SHA of the last cut. Existing tag (via Forgejo API) records what the tag currently points to. If they disagree (force-push after cut, manual tag surgery, cross-repo mirror desync), release-decide.sh anchor logic uses the manifest SHA. Adopter intuition says the tag itself should be authoritative — the code's chosen precedence is undocumented + potentially counterintuitive. ## Blocking rationale Silent divergence between manifest and tag → release cut anchored to unexpected commit → CHANGELOG walks unexpected range → release notes surface unrelated commits. Trust-breaking on adopter's first "wait, why is that in the release notes?" moment. ## Fix path Two axes: **Axis 1 — precedence rule**: which wins on disagreement? Options: (a) manifest wins silently (current), (b) tag wins silently, (c) fail loud on disagreement, (d) prefer newer SHA by commit-date. My lean: (c) fail loud for v1.0.0, add explicit resolution modes in v1.1.0. **Axis 2 — document the rule**: whatever we pick, name it in docs/integration.md + name the disagreement scenarios adopters might hit. ## Verification AC - Test: manifest at SHA A, tag at SHA B → clear outcome (either error or documented winner) - docs/integration.md names the precedence rule + when adopters hit disagreement - External cold-read round 5 finds no anchor-precedence ambiguity ## Anchor External outside-model cold-read round 4 (fresh ChatGPT session, 2026-07-03 late). Verdict: 'promising but not yet trustworthy' — SAME TIER as round-3 despite round-3 delta cycle. Meta-pattern named this round: grep-sweep-missed-siblings — the sweep-pattern targeted the literal grep-target, not the semantic class, so class-axis closed PARTIALLY per round. Operator ratified filing round-4 trackers 2026-07-04. This tracker addresses one of the round-4 findings. Success criterion: subsequent external cold-read returns no further objections of this class. BLOCKING v1.0.0.

bosun added the

priority/critical

size/M

kind/bug

labels

2026-07-04 20:29:48 +02:00