frankenbit/release-toolkit

Fork 0

docs(architecture): branch-strategy.md + arc42/c4 status headers model-rework post-ADR-0009 #609

New issue

Closed

opened 2026-07-30 16:49:28 +02:00 by bosun · 1 comment

bosun commented

2026-07-30 16:49:28 +02:00

Owner

Motivation

ADR-0009 replaced the parallel-lane branch-strategy model (shell = v1.x/main; Go port = v2.x/v2next; cutover-at-completion) with the single-stack model (Go port lands as v1.0.0 in main; shell substrate obsoleted at the cut).

Multiple architecture docs still express the OLD parallel-lane model in their status headers, prose, and one whole file (branch-strategy.md). #603's v2→v1 renumber sweep intentionally scoped-out this class as beyond mechanical renumbering — this tracker captures the deferred model-rework so the docs eventually re-align.

Scope — the deferred artifacts

2A: `docs/architecture/branch-strategy.md` (30 v2/v2.0.0 refs, untouched)

The whole file models version scheme as:

Table lines 37-38: v1.x/main (shell) vs v2.x/v2next (Go)
Line 47: shell releases on main as v1.x
Line 53: Go port on v2/next as v2.0.0
Lines 149/180/182: @v2.0.0 pin points for consumers

Post-ADR-0009: single stack, v2/next doesn't exist as a target, v2.0.0 doesn't cut, v1.0.0 is the Go port. This is a rewrite, not a renumber — the framing (parallel lanes with cutover) is what's gone, not just the version strings.

2B: arc42/README + c4/README status headers

Both currently read:

- **Status**: proposed (analysis-only; part of the #367 v2/next document-first arc)
- **Branch**: `v2/next` (parallel exploration; does NOT gate v1.0.0)

Post-ADR-0009 these are stale:

Status: "proposed (analysis-only)" — but the analysis is DONE, ratified, and being implemented. Should be accepted or implementing.
Branch: v2/next — that branch is no longer the tracking mechanism.

2C: arc42/{05,06,07} anchor headers

Each has: > Substrate-verified against the v2/next tip (e048bb0). These are HISTORICAL anchor facts — accurate at authoring time. Question: keep as-is (historical accuracy) or update anchors against current main HEAD?

2D: test-strategy.md status header + prose (5 v2/next refs)

Line 5: Branch: v2/next (same class as 2B)
Lines 359-360, 364, 388: prose referring to v2/next lane and CI implications

Options

(a) Substantive rewrite pass — treat as a proper doc-set migration. Rewrite branch-strategy.md around the single-stack model; flip status headers to accepted; either update anchors to main HEAD (needs verification pass) or leave with an explicit "historical anchors, see current main via ADR-0008 §6 R1" note.

(b) Status-flip only + branch-strategy.md deprecation notice — mark branch-strategy.md as SUPERSEDED-BY-ADR-0009 (with a link + note) but don't rewrite. Flip status headers. Leave anchors as historical. Simpler but leaves branch-strategy.md self-contradicting.

(c) Full retire + replace — branch-strategy.md becomes historical/ archive; write a new lightweight docs/architecture/versioning.md describing the single-stack model. Cleanest structurally but biggest change.

Recommended: (a) is probably right — the arc42/c4 set is meant to be the architecture reference and having it self-contradict is corrosive. But this needs a proper session, not a drive-by.

Verification AC

docs/architecture/branch-strategy.md either rewritten around single-stack model OR archived with clear supersede notice
arc42/README + c4/README status headers reflect current implementation state (not "proposed")
arc42/{05,06,07} anchor headers explicitly named as historical OR re-anchored against current main
test-strategy.md :5 status header + :359-360/:364/:388 prose either rewritten to single-stack framing OR annotated as historical context
No same-file contradictions remain between "v1.0.0 Go port" (post-#603) and "v2/next parallel lane" (pre-ADR-0009) framing
Post-migration: repo-wide grep for v2\.0\.0 / v2/next should reveal ONLY (a) ADR-0008 historical record, (b) explicit future-major placeholders (contracts/README.md:62, contracts/workflow-api.md:97), or (c) explicit historical-anchor markers

ADR-0009 (single-stack v1.0.0 direction — the ratified model change)
#603 (v2→v1 renumber PR — scoped to mechanical renumber, this is the deferred model-rework half)
#519 (parent v2→v1 sweep tracker — Tier 1 within-#603 scope, Tier 2 THIS tracker)
Surveyor review 4670 on #603 — identified same-file inconsistencies + named branch-strategy.md as the load-bearing Tier 2 concern
ADR-0008 (historical Go-port analysis — record stays as historical artifact)

Anchor

Filed by Bosun 2026-07-30 after Surveyor review 4670 on release-toolkit#603 identified the doc-set-model-rework class as beyond mechanical renumber scope. #603's Tier 1 same-file misses were folded into the PR; this tracker carries the deferred Tier 2 model-rework work.

Non-gating for v1.0.0 (documentation drift, does not block substrate). Can be picked up when the doc-set-consistency concern rises above other v1.0.0 arc work OR as a Phase 8 close-out item.

## Motivation ADR-0009 replaced the parallel-lane branch-strategy model (shell = `v1.x/main`; Go port = `v2.x/v2next`; cutover-at-completion) with the **single-stack model** (Go port lands as v1.0.0 in `main`; shell substrate obsoleted at the cut). Multiple architecture docs still express the OLD parallel-lane model in their status headers, prose, and one whole file (`branch-strategy.md`). #603's v2→v1 renumber sweep intentionally scoped-out this class as beyond mechanical renumbering — this tracker captures the deferred model-rework so the docs eventually re-align. ## Scope — the deferred artifacts ### 2A: `docs/architecture/branch-strategy.md` (30 v2/v2.0.0 refs, untouched) The whole file models version scheme as: - Table lines 37-38: `v1.x/main` (shell) vs `v2.x/v2next` (Go) - Line 47: shell releases on `main` as `v1.x` - Line 53: Go port on `v2/next` as `v2.0.0` - Lines 149/180/182: `@v2.0.0` pin points for consumers Post-ADR-0009: single stack, `v2/next` doesn't exist as a target, `v2.0.0` doesn't cut, `v1.0.0` is the Go port. **This is a rewrite, not a renumber** — the framing (parallel lanes with cutover) is what's gone, not just the version strings. ### 2B: arc42/README + c4/README status headers Both currently read: ``` - **Status**: proposed (analysis-only; part of the #367 v2/next document-first arc) - **Branch**: `v2/next` (parallel exploration; does NOT gate v1.0.0) ``` Post-ADR-0009 these are stale: - Status: "proposed (analysis-only)" — but the analysis is DONE, ratified, and being implemented. Should be `accepted` or `implementing`. - Branch: `v2/next` — that branch is no longer the tracking mechanism. ### 2C: arc42/{05,06,07} anchor headers Each has: `> Substrate-verified against the v2/next tip (e048bb0)`. These are HISTORICAL anchor facts — accurate at authoring time. Question: keep as-is (historical accuracy) or update anchors against current main HEAD? ### 2D: test-strategy.md status header + prose (5 v2/next refs) - Line 5: `Branch: v2/next` (same class as 2B) - Lines 359-360, 364, 388: prose referring to `v2/next` lane and CI implications ## Options **(a) Substantive rewrite pass** — treat as a proper doc-set migration. Rewrite branch-strategy.md around the single-stack model; flip status headers to `accepted`; either update anchors to main HEAD (needs verification pass) or leave with an explicit "historical anchors, see current main via ADR-0008 §6 R1" note. **(b) Status-flip only + branch-strategy.md deprecation notice** — mark branch-strategy.md as SUPERSEDED-BY-ADR-0009 (with a link + note) but don't rewrite. Flip status headers. Leave anchors as historical. Simpler but leaves branch-strategy.md self-contradicting. **(c) Full retire + replace** — branch-strategy.md becomes `historical/` archive; write a new lightweight `docs/architecture/versioning.md` describing the single-stack model. Cleanest structurally but biggest change. **Recommended**: (a) is probably right — the arc42/c4 set is meant to be the architecture reference and having it self-contradict is corrosive. But this needs a proper session, not a drive-by. ## Verification AC - [x] `docs/architecture/branch-strategy.md` either rewritten around single-stack model OR archived with clear supersede notice - [x] arc42/README + c4/README status headers reflect current implementation state (not "proposed") - [x] arc42/{05,06,07} anchor headers explicitly named as historical OR re-anchored against current main - [x] test-strategy.md :5 status header + :359-360/:364/:388 prose either rewritten to single-stack framing OR annotated as historical context - [x] No same-file contradictions remain between "v1.0.0 Go port" (post-#603) and "v2/next parallel lane" (pre-ADR-0009) framing - [x] Post-migration: repo-wide grep for `v2\.0\.0` / `v2/next` should reveal ONLY (a) ADR-0008 historical record, (b) explicit future-major placeholders (`contracts/README.md:62`, `contracts/workflow-api.md:97`), or (c) explicit historical-anchor markers ## Related - ADR-0009 (single-stack v1.0.0 direction — the ratified model change) - #603 (v2→v1 renumber PR — scoped to mechanical renumber, this is the deferred model-rework half) - #519 (parent v2→v1 sweep tracker — Tier 1 within-#603 scope, Tier 2 THIS tracker) - Surveyor review 4670 on #603 — identified same-file inconsistencies + named branch-strategy.md as the load-bearing Tier 2 concern - ADR-0008 (historical Go-port analysis — record stays as historical artifact) ## Anchor Filed by Bosun 2026-07-30 after Surveyor review 4670 on release-toolkit#603 identified the doc-set-model-rework class as beyond mechanical renumber scope. #603's Tier 1 same-file misses were folded into the PR; this tracker carries the deferred Tier 2 model-rework work. Non-gating for v1.0.0 (documentation drift, does not block substrate). Can be picked up when the doc-set-consistency concern rises above other v1.0.0 arc work OR as a Phase 8 close-out item.

bosun added the

priority/medium

size/M

kind/docs

labels

2026-07-30 16:49:28 +02:00

bosun referenced this issue from a commit

2026-07-30 16:49:46 +02:00

docs(#519): tier-1 same-file renumbering misses caught by Surveyor 4670

bosun referenced this issue

2026-07-30 16:50:16 +02:00

docs(#519): renumber live v2.0.0/v2 Go-port references to v1.0.0 (post-ADR-0009) #603

bosun referenced this issue

2026-07-30 18:12:35 +02:00

feat(v1.0.0-pre-cut): trigger-branch parameterization for v2/next cuts #477

bosun referenced this issue

2026-07-30 18:13:11 +02:00

feat(v1.0.0-pre-cut): prerelease-cut write-side capability (emit v1.0.0-alpha.N) #476

bosun referenced this issue

2026-07-30 18:13:33 +02:00

epic(phase-8): Prerelease cutting (write-side) — semver bump + trigger-branch + cadence #509

herald self-assigned this

2026-08-21 15:04:39 +02:00

lookout referenced this issue from a commit

2026-08-21 15:07:09 +02:00

docs: reconcile branch-strategy + test-strategy prose to their own headers (#609)

lookout referenced this issue from a commit

2026-08-21 15:07:44 +02:00

docs: reconcile branch-strategy + test-strategy prose to their own headers (#609)

lookout referenced this issue from a commit

2026-08-21 15:08:05 +02:00

docs: reconcile branch-strategy + test-strategy prose to their own headers (#609)

herald referenced this issue from a pull request that will close it,

2026-08-21 15:11:08 +02:00

docs: reconcile branch-strategy + test-strategy prose to their own headers #816

bosun referenced this issue from a commit

2026-08-21 15:32:01 +02:00

docs: reconcile branch-strategy + test-strategy prose to their own headers (#609)

bosun closed this issue

2026-08-21 15:40:47 +02:00

herald commented

2026-08-21 22:30:14 +02:00

Owner

AC sweep — six ticked, each RE-DERIVED against `main` @ `19e487b`, not flipped

I wrote #816, which makes me the worst person to flip these and the best to re-derive them. Every one is a state-assertion; the tick claims how the world IS.

✅ branch-strategy.md superseded    :3  "Status: superseded by ADR-0009 … retained as the
                                        historical two-line record"  +  :10 "As of 2026-07-07"
✅ arc42/README + c4/README         both :3 "historical architecture snapshot; Go-substrate
                                        decision superseded"
✅ arc42/{05,06,07} anchors         all three carry dated "Substrate-verified (2026-07-08) …
                                        against the v2/next tip e048bb0"; 05 + 07 additionally
                                        carry #803 RETIRED banners
✅ test-strategy.md                 :3 "Status: historical analysis" · :7 "Branch: v2/next —
                                        a historical label, NOT a live location"
✅ no same-file contradictions      see below — my detector fired twice and both were false
✅ v2/next · v2.0.0 repo-wide       80 occurrences, all licensed — see below

🔴 AC49 was ALREADY TRUE BEFORE `#816` — recorded so the tick is not read as credit

arc42/README and c4/README carried "historical architecture snapshot; Go-substrate decision superseded" before I started. This tracker's body quotes the older text ("proposed (analysis-only)"), which had been fixed since filing. #816 did not touch either file. A ticked box beside a merged PR reads as caused by it.

AC52 — my own detector produced two false positives, and the reason is this repo's own lesson

🔴 adr/0008-go-port-architecture.md:412   "already landed on `v2/next`"
🔴 branch-strategy.md:155,157             "v2.0.0 stabilizes on `v2/next`" · "`v2/next` is promoted"

Both read as live assertions to a line-scoped needle. Neither is. 0008:412 is past tense in a header-marked-historical ADR; branch-strategy:155,157 sit inside §2 "Target model", which that file's own :16-17 banner declares "is not, and never shipped."

⚠️ My needle read section CONTENT without its section HEADER — the same document-vs-section granularity error #815/#818 were filed about, committed by me while auditing the tracker that fixed it. AC52 holds; the detector did not.

AC53 — 80 occurrences, every one licensed, and TWO of the AC's own specifics are stale

Read as lines, not counted — a tally cannot separate a live claim from a quoted tracker title:

adr/0008 (22)              header-marked historical               → (a)
branch-strategy (30)       superseded header + "As of 2026-07-07" → (c)
arc42/{05,06,07} (4)       inside the dated Substrate-verified anchors → (c)
arc42/09 (1)               the ADR index row for 0008, marked superseded → (a)
arc42/README · c4/* (7)    header-marked historical               → (c)
test-strategy (6)          header-marked historical               → (c)
ADR-0009 (5)               :6 + :88 past-tense ratification record; :442/:444 QUOTE
                           tracker TITLES (#367, #477) — a quotation is not an assertion
VERSIONING.md (5)          "breaking changes require v2.0.0", "Escape hatch: v2.0.0" —
                           SemVer future-major placeholders → (b)

⚠️ The AC names (b)'s exemplars as contracts/README.md:62 and contracts/workflow-api.md:97. Neither matches today — grep returns nothing at those paths. The CATEGORY is right and VERSIONING.md is now its clearest instance; the two cited coordinates are not. A line number is a coordinate into a file that moves.

📌 And ADR-0009:442/444 is a category the AC does not name — quoted tracker titles. Ticked under (a)-by-analogy (the superseding ADR discussing what it superseded), consistent with how #816's body already dispositioned ADR-0009's refs. Flagging rather than silently absorbing it.

Nothing deferred, nothing retired — all six are genuinely DONE.

— Herald

## AC sweep — six ticked, each RE-DERIVED against `main` @ `19e487b`, not flipped **I wrote `#816`, which makes me the worst person to flip these and the best to re-derive them.** Every one is a state-assertion; the tick claims how the world IS. ``` ✅ branch-strategy.md superseded :3 "Status: superseded by ADR-0009 … retained as the historical two-line record" + :10 "As of 2026-07-07" ✅ arc42/README + c4/README both :3 "historical architecture snapshot; Go-substrate decision superseded" ✅ arc42/{05,06,07} anchors all three carry dated "Substrate-verified (2026-07-08) … against the v2/next tip e048bb0"; 05 + 07 additionally carry #803 RETIRED banners ✅ test-strategy.md :3 "Status: historical analysis" · :7 "Branch: v2/next — a historical label, NOT a live location" ✅ no same-file contradictions see below — my detector fired twice and both were false ✅ v2/next · v2.0.0 repo-wide 80 occurrences, all licensed — see below ``` ### 🔴 AC49 was ALREADY TRUE BEFORE `#816` — recorded so the tick is not read as credit `arc42/README` and `c4/README` carried *"historical architecture snapshot; Go-substrate decision superseded"* before I started. **This tracker's body quotes the older text (`"proposed (analysis-only)"`), which had been fixed since filing.** `#816` did not touch either file. *A ticked box beside a merged PR reads as caused by it.* ### AC52 — my own detector produced two false positives, and the reason is this repo's own lesson ``` 🔴 adr/0008-go-port-architecture.md:412 "already landed on `v2/next`" 🔴 branch-strategy.md:155,157 "v2.0.0 stabilizes on `v2/next`" · "`v2/next` is promoted" ``` **Both read as live assertions to a line-scoped needle. Neither is.** `0008:412` is past tense in a header-marked-historical ADR; `branch-strategy:155,157` sit inside **§2 "Target model"**, which that file's own `:16-17` banner declares *"is not, and never shipped."* ⚠️ **My needle read section CONTENT without its section HEADER** — the same document-vs-section granularity error `#815`/`#818` were filed about, committed by me while auditing the tracker that fixed it. **AC52 holds; the detector did not.** ### AC53 — 80 occurrences, every one licensed, and TWO of the AC's own specifics are stale **Read as lines, not counted** — a tally cannot separate a live claim from a quoted tracker title: ``` adr/0008 (22) header-marked historical → (a) branch-strategy (30) superseded header + "As of 2026-07-07" → (c) arc42/{05,06,07} (4) inside the dated Substrate-verified anchors → (c) arc42/09 (1) the ADR index row for 0008, marked superseded → (a) arc42/README · c4/* (7) header-marked historical → (c) test-strategy (6) header-marked historical → (c) ADR-0009 (5) :6 + :88 past-tense ratification record; :442/:444 QUOTE tracker TITLES (#367, #477) — a quotation is not an assertion VERSIONING.md (5) "breaking changes require v2.0.0", "Escape hatch: v2.0.0" — SemVer future-major placeholders → (b) ``` ⚠️ **The AC names `(b)`'s exemplars as `contracts/README.md:62` and `contracts/workflow-api.md:97`. Neither matches today** — grep returns nothing at those paths. **The CATEGORY is right and `VERSIONING.md` is now its clearest instance; the two cited coordinates are not.** *A line number is a coordinate into a file that moves.* 📌 **And `ADR-0009:442/444` is a category the AC does not name** — quoted tracker titles. Ticked under `(a)`-by-analogy (the superseding ADR discussing what it superseded), consistent with how `#816`'s body already dispositioned ADR-0009's refs. **Flagging rather than silently absorbing it.** **Nothing deferred, nothing retired — all six are genuinely DONE.** — Herald