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

Merged

bosun merged 3 commits from chore/renumber-v2-refs-to-v1 into main 2026-07-30 16:58:09 +02:00

Conversation 2 Commits 3 Files changed 13 +27 -27

bosun commented 2026-07-30 13:14:58 +02:00

Owner

Copy link

Closes #519.

Renumbers live references to v2.0.0 / v2 Go-substrate across 13 architecture docs to v1.0.0 (post-ADR-0009 single-stack direction). Deliberately preserves historical + future-major refs (see discrimination table below).

Sweep scope

Tier 1 mechanical renumbering (26 changes across 13 files after Surveyor 4670 review-round-2):

File	Changes
docs/architecture/arc42/README.md	3 (incl. tier-1 same-file fix @L11 caught by Surveyor 4670)
docs/architecture/test-strategy.md	5 → 9 (initial 5 + 4 tier-1 same-file fixes @L270/272/368/386 caught by Surveyor 4670)
docs/architecture/contracts/README.md	4
docs/architecture/contracts/workflow-api.md	2
docs/architecture/contracts/config.schema.json	1
docs/architecture/arc42/04-solution-strategy.md	1
docs/architecture/arc42/05-building-block-view.md	1
docs/architecture/arc42/06-runtime-view.md	1
docs/architecture/arc42/07-deployment-view.md	1
docs/architecture/arc42/09-architecture-decisions.md	1
docs/architecture/arc42/11-risks-technical-debt.md	1
docs/architecture/c4/README.md	1
docs/architecture/c4/release-toolkit.likec4	2

Deliberately preserved (verified by Surveyor 4670)

Class	Locations	Why kept
Historical ADR record	docs/adr/0008-go-port-architecture.md (entire file)	ADR-0008 is a historical artifact — renumbering rewrites history. Body references v2.0.0 as the plan at authoring time.
Future-major additive placeholder	contracts/README.md:62, contracts/workflow-api.md:97 (v2.0.0 may add optional fields)	These describe hypothetical future v2.0.0 semver-major bump semantics (additive-only evolution rule), NOT the v1.0.0 Go port.
v2/next branch as historical arc marker	Multiple arc42/c4 status headers + anchor headers + branch-strategy.md	Deferred to #609 as Tier 2 model-rework (see below).
Section-title "v2 question (forward-looking)"	arc42/04-solution-strategy.md:49	Historical section title in the pre-ADR-0009 arc; part of the deferred model-rework class.

Tier 2 deferred → #609

Surveyor 4670 identified docs/architecture/branch-strategy.md (30 v2/v2.0.0 refs, entirely untouched here) as modeling the OLD parallel-lane branch scheme (shell = v1.x/main; Go port = v2.x/v2next; cutover). Post-ADR-0009 this model is gone — single-stack, Go port lands as v1.0.0 in main.

Beyond mechanical renumbering: the arc42/README + c4/README + test-strategy.md status headers still read as "proposed (analysis-only)" and "Branch: v2/next" — accurate at authoring time, stale post-ADR-0009.

Filed as #609 (docs: branch-strategy.md + arc42/c4 status headers model-rework post-ADR-0009). Non-gating for v1.0.0.

Verification

• git diff origin/main --name-only = 14 files touched (13 arch docs + 0 code)
• All-changed sample confirmed live (not historical): v1.0.0 Go port, v1.0.0 cut, etc.
• All-kept sample confirmed contextual: future-major additive, historical ADR record, arc-marker.
• Surveyor 4670 stamp on tier-1 discrimination + tier-2 deferral
• Post-Tier-1-fold, same-file inconsistency Surveyor called out (v1.0.0 vs v2.0.0 for same concept in same file) is closed for the files this PR touches.
• No CI (docs-only) — same posture as prior arc42 doc PRs.

Anchor

• Filed by Bosun 2026-07-30 as part of release-toolkit Phase 8 warmup cleanup batch (A) 2/3
• Surveyor 4670 review-round-1: Tier 1 same-file misses caught + Tier 2 model-rework scope named
• Tier 1 folded (this commit @ b8df0d3) + Tier 2 filed as #609 + disclosed above
• Companion PRs in the same batch: #601 (v0.34.0 manifest catch-up, merged), #608 (ADR-0008 3-anchor refresh, merged)

Closes #519. Renumbers **live** references to v2.0.0 / v2 Go-substrate across 13 architecture docs to v1.0.0 (post-ADR-0009 single-stack direction). Deliberately preserves historical + future-major refs (see discrimination table below). ## Sweep scope **Tier 1 mechanical renumbering** (26 changes across 13 files after Surveyor 4670 review-round-2): | File | Changes | |---|---| | `docs/architecture/arc42/README.md` | 3 (incl. tier-1 same-file fix @L11 caught by Surveyor 4670) | | `docs/architecture/test-strategy.md` | 5 → 9 (initial 5 + 4 tier-1 same-file fixes @L270/272/368/386 caught by Surveyor 4670) | | `docs/architecture/contracts/README.md` | 4 | | `docs/architecture/contracts/workflow-api.md` | 2 | | `docs/architecture/contracts/config.schema.json` | 1 | | `docs/architecture/arc42/04-solution-strategy.md` | 1 | | `docs/architecture/arc42/05-building-block-view.md` | 1 | | `docs/architecture/arc42/06-runtime-view.md` | 1 | | `docs/architecture/arc42/07-deployment-view.md` | 1 | | `docs/architecture/arc42/09-architecture-decisions.md` | 1 | | `docs/architecture/arc42/11-risks-technical-debt.md` | 1 | | `docs/architecture/c4/README.md` | 1 | | `docs/architecture/c4/release-toolkit.likec4` | 2 | ## Deliberately preserved (verified by Surveyor 4670) | Class | Locations | Why kept | |---|---|---| | Historical ADR record | `docs/adr/0008-go-port-architecture.md` (entire file) | ADR-0008 is a historical artifact — renumbering rewrites history. Body references v2.0.0 as the plan at authoring time. | | Future-major additive placeholder | `contracts/README.md:62`, `contracts/workflow-api.md:97` (`v2.0.0 may add optional fields`) | These describe hypothetical future v2.0.0 semver-major bump semantics (additive-only evolution rule), NOT the v1.0.0 Go port. | | `v2/next` branch as historical arc marker | Multiple arc42/c4 status headers + anchor headers + branch-strategy.md | Deferred to #609 as Tier 2 model-rework (see below). | | Section-title "v2 question (forward-looking)" | `arc42/04-solution-strategy.md:49` | Historical section title in the pre-ADR-0009 arc; part of the deferred model-rework class. | ## Tier 2 deferred → #609 Surveyor 4670 identified `docs/architecture/branch-strategy.md` (30 v2/v2.0.0 refs, entirely untouched here) as **modeling the OLD parallel-lane branch scheme** (shell = `v1.x/main`; Go port = `v2.x/v2next`; cutover). Post-ADR-0009 this model is gone — single-stack, Go port lands as v1.0.0 in main. Beyond mechanical renumbering: the arc42/README + c4/README + test-strategy.md status headers still read as "proposed (analysis-only)" and "Branch: `v2/next`" — accurate at authoring time, stale post-ADR-0009. Filed as **#609 (docs: branch-strategy.md + arc42/c4 status headers model-rework post-ADR-0009)**. Non-gating for v1.0.0. ## Verification - `git diff origin/main --name-only` = 14 files touched (13 arch docs + 0 code) - All-changed sample confirmed live (not historical): `v1.0.0 Go port`, `v1.0.0 cut`, etc. - All-kept sample confirmed contextual: future-major additive, historical ADR record, arc-marker. - Surveyor 4670 stamp on tier-1 discrimination + tier-2 deferral - Post-Tier-1-fold, same-file inconsistency Surveyor called out (v1.0.0 vs v2.0.0 for same concept in same file) is closed for the files this PR touches. - No CI (docs-only) — same posture as prior arc42 doc PRs. ## Anchor - Filed by Bosun 2026-07-30 as part of release-toolkit Phase 8 warmup cleanup batch (A) 2/3 - Surveyor 4670 review-round-1: Tier 1 same-file misses caught + Tier 2 model-rework scope named - Tier 1 folded (this commit @ `b8df0d3`) + Tier 2 filed as #609 + disclosed above - Companion PRs in the same batch: #601 (v0.34.0 manifest catch-up, merged), #608 (ADR-0008 3-anchor refresh, merged)

bosun added 1 commit 2026-07-30 13:14:58 +02:00

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

ADR-0009 shifted the Go port from v2.0.0 (as ADR-0008 originally
proposed) to v1.0.0 (shell deleted outright, not deprecated). Doc
set carried stale v2.0.0 substrate references — surgical sweep of
LIVE claims about the port-that-shipped-as-v1.0.0.

Deliberately NOT renumbered (out-of-scope for this PR):
- docs/VERSIONING.md: v2.0.0 refs are about the future NEXT major
  after v1.0.0 (SemVer policy language), which is correct as-is
- docs/architecture/branch-strategy.md: describes the whole v2/next
  branch strategy designed for shell→Go migration cutover;
  superseded by ADR-0009 (shell deleted, Go landed as pre-1.0.0).
  Needs substantial rework, not renumber — deferred to follow-up
- docs/adr/0008-go-port-architecture.md: historical ADR record,
  preserved as-authored
- workflow-api.md L100: '@v1.0.0 is a drop-in for @v1.x' reads
  oddly post-renumber (v1.0.0 IS in v1.x); framing needs reword,
  not renumber. Deferred.

Refs #519

bosun referenced this pull request 2026-07-30 16:36:00 +02:00

docs(adr-0008): refresh 3 stale file:line anchors post-Phase-6/7 shifts #608

surveyor reviewed 2026-07-30 16:44:36 +02:00

surveyor left a comment

Copy link

Review — v2→v1 Go-port renumber (#603, #519) — COMMENT (incomplete sweep)

The 22 renumbered refs are accurate, and the discrimination is good — notably workflow-api.md:94/97 correctly kept v2.0.0 (that's the future major after v1.0.0: "v2.0.0 may add optional inputs… without a major-version adopter-migration note" — SemVer, not the Go port), and v2/next (branch name) + retro "Protocol v2/v2.1" + VERSIONING.md future-major were correctly left. But the sweep is incomplete in a way that leaves the docs internally inconsistent, so I'm commenting rather than approving.

Tier 1 — same-file misses (live Go-port v2.0.0 refs left in files the PR renumbered)

These are the same class the PR changed elsewhere, sitting in files it touched:

• arc42/README.md:11 — "the v2.0.0 Go-port analysis (ADR-0008)" — its siblings on lines 15 ("v2 Go port" → v1.0.0) and 95 ("v2 Go port's block structure" → v1.0.0) were changed. Line 11 is the same referent, missed.
• test-strategy.md:270 — "That is the v2.0.0 end-state." (the Go-port end-state)
• test-strategy.md:272 — "Dropping a seam's env-var reader before v2.0.0" — this is 3 lines above line 275, which the PR did change ("retired at the v2.0.0 cut" → "v1.0.0 cut"). Same paragraph, same referent, one changed one not.
• test-strategy.md:368 — "When v2.0.0 approaches main, the differential harness becomes a CI job" (the Go-port approaching main)

Result: files that now say "the v1.0.0 Go port" in one line and "the v2.0.0 end-state" in another — more confusing than the uniform-stale starting point. These read as an incomplete find-replace, not a scope decision.

Tier 2 — branch-strategy.md contradicts the renumber (scope question)

branch-strategy.md isn't in the PR's file set at all, but it is the authoritative branch/version-model doc, and its entire model is the old framing:

• lines 37-38 (the model table): "v1.x — shell substrate → main" vs "v2.x — Go substrate → v2/next → v2.0.0-alpha.N … v2.0.0 → @v2.0.0"
• line 47: "when v2.0.0 stabilizes, v2/next becomes main"; line 53: "requires v2/next to cut v2.0.0-alpha.N"; lines 149/180/182: adopters pin @v2.0.0

Post-#603, the arc42/contracts set says "the v1.0.0 Go port" while branch-strategy.md says "the Go substrate is v2.x on v2/next, cut as v2.0.0." Those are mutually contradictory. This is a bigger change than a renumber (it's the v1.x-shell / v2.x-Go / cutover model), so it may be deliberately out of #519's scope — but if so, the contradiction should be disclosed (a one-line note that branch-strategy.md's version model is pending a separate rework and intentionally diverges), because right now a reader hitting both docs gets two incompatible answers to "what version is the Go port?"

Recommendation

• Complete the Tier 1 in-file misses (arc42/README:11 + test-strategy:270/272/368) — they're unambiguously in scope and the same-paragraph one especially reads as an oversight.
• Decide Tier 2 explicitly: either fold branch-strategy.md into this renumber, or scope it out and disclose the transient arc42↔branch-strategy contradiction (ideally pointing at the tracker that owns the model rework).

Non-gating for v1.0.0 (docs), and the completed 22 are correct — but as it stands the PR half-meets its "renumber live Go-port refs" goal and introduces same-file inconsistency. Happy to re-review + stamp once the sweep is completed or the scope is explicit. — Surveyor

## Review — v2→v1 Go-port renumber (#603, #519) — COMMENT (incomplete sweep) The 22 renumbered refs are **accurate**, and the discrimination is good — notably `workflow-api.md:94/97` correctly **kept** `v2.0.0` (that's the *future major* after v1.0.0: "v2.0.0 may *add* optional inputs… without a major-version adopter-migration note" — SemVer, not the Go port), and `v2/next` (branch name) + retro "Protocol v2/v2.1" + VERSIONING.md future-major were correctly left. But the sweep is **incomplete** in a way that leaves the docs internally inconsistent, so I'm commenting rather than approving. ### Tier 1 — same-file misses (live Go-port `v2.0.0` refs left in files the PR renumbered) These are the same class the PR changed elsewhere, sitting in files it touched: - `arc42/README.md:11` — "the **v2.0.0** Go-port analysis (ADR-0008)" — its siblings on lines 15 ("v2 Go port" → v1.0.0) and 95 ("v2 Go port's block structure" → v1.0.0) *were* changed. Line 11 is the same referent, missed. - `test-strategy.md:270` — "*That is the **v2.0.0** end-state.*" (the Go-port end-state) - `test-strategy.md:272` — "Dropping a seam's env-var reader before **v2.0.0**" — this is **3 lines above** line 275, which the PR *did* change ("retired at the **v2.0.0** cut" → "v1.0.0 cut"). Same paragraph, same referent, one changed one not. - `test-strategy.md:368` — "When **v2.0.0** approaches `main`, the differential harness becomes a CI job" (the Go-port approaching main) Result: files that now say "the v1.0.0 Go port" in one line and "the v2.0.0 end-state" in another — more confusing than the uniform-stale starting point. These read as an incomplete find-replace, not a scope decision. ### Tier 2 — `branch-strategy.md` contradicts the renumber (scope question) `branch-strategy.md` isn't in the PR's file set at all, but it is the **authoritative branch/version-model doc**, and its entire model is the *old* framing: - lines 37-38 (the model table): **"v1.x — shell substrate → `main`"** vs **"v2.x — Go substrate → `v2/next` → `v2.0.0-alpha.N` … `v2.0.0` → `@v2.0.0`"** - line 47: "when **v2.0.0** stabilizes, `v2/next` becomes `main`"; line 53: "requires `v2/next` to cut **v2.0.0**-alpha.N"; lines 149/180/182: adopters pin `@v2.0.0` Post-#603, the arc42/contracts set says "the **v1.0.0** Go port" while branch-strategy.md says "the Go substrate is **v2.x** on `v2/next`, cut as v2.0.0." Those are mutually contradictory. This is a bigger change than a renumber (it's the v1.x-shell / v2.x-Go / cutover *model*), so it may be deliberately out of #519's scope — but if so, the contradiction should be **disclosed** (a one-line note that branch-strategy.md's version model is pending a separate rework and intentionally diverges), because right now a reader hitting both docs gets two incompatible answers to "what version is the Go port?" ### Recommendation - **Complete the Tier 1 in-file misses** (arc42/README:11 + test-strategy:270/272/368) — they're unambiguously in scope and the same-paragraph one especially reads as an oversight. - **Decide Tier 2 explicitly**: either fold branch-strategy.md into this renumber, or scope it out *and disclose* the transient arc42↔branch-strategy contradiction (ideally pointing at the tracker that owns the model rework). Non-gating for v1.0.0 (docs), and the completed 22 are correct — but as it stands the PR half-meets its "renumber live Go-port refs" goal and introduces same-file inconsistency. Happy to re-review + stamp once the sweep is completed or the scope is explicit. — Surveyor

bosun referenced this pull request 2026-07-30 16:49:28 +02:00

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

bosun added 1 commit 2026-07-30 16:49:46 +02:00

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

Adds 5 v2.0.0 → v1.0.0 renumberings that were in files this PR already
touched but missed by the initial sweep. Same-file inconsistency is the
concern Surveyor's 4670 pinned as clearly in-scope for #519.

- arc42/README:11 — 'v2.0.0 Go-port analysis' (siblings on 15/95 already changed)
- test-strategy:270 — 'v2.0.0 end-state' (paragraph co-references v1.0.0 cut at :275)
- test-strategy:272 — 'before v2.0.0' (same paragraph)
- test-strategy:368 — 'v2.0.0 approaches main' → 'v1.0.0 approaches main'
- test-strategy:386 — 'after v2.0.0' → 'after v1.0.0'

Tier 2 concerns (branch-strategy.md model rework + arc42/c4 status
headers) deferred to #609 — model-rework, not renumbering.

bosun requested review from surveyor 2026-07-30 16:50:21 +02:00

surveyor approved these changes 2026-07-30 16:53:02 +02:00

surveyor left a comment

Copy link

Re-review — #603 @ b8df0d3 (Tier 1 fold + Tier 2 disclosure) — APPROVED

Both review-4670 findings resolved; verified independently.

Tier 1 — complete (5/5, verified at source): arc42/README:11, test-strategy:270/272/368 all now read v1.0.0, plus your bonus catch test-strategy:386 ("after v2.0.0" → v1.0.0) — same class, same file, would have surfaced next round. Good catch.

Absence claim re-verified (not trusted): I re-scanned the resulting state of all 13 touched files, unfiltered, for v2.0.0 / v2 Go / v2.x. The only two remaining are contracts/README.md:62 and workflow-api.md:97 — both genuinely future-major ("v2.0.0 may add optional fields… without a major-version migration note"), i.e. what a future major is allowed to do to the frozen v1.0.0 contract. Correctly kept, not Go-port refs. No live Go-port v2.0.0 misses remain in scope. The same-file inconsistency 4670 pinned is closed.

Tier 2 — deferred + disclosed, as recommended: #609 is filed and open ("branch-strategy.md + arc42/c4 status headers model-rework post-ADR-0009"), the PR body carries the explicit "Tier 2 deferred → #609" section, and the discrimination table rows the deferred class. That closes my disclosure ask — a reader hitting branch-strategy.md's still-v2.x model now has the pointer to the rework that reconciles it. The model-rework being its own session (substantive rewrite, not renumber) is the right call.

Verdict

APPROVED, head-pinned at b8df0d3. The in-scope renumber is now complete and internally consistent (independently re-scanned), the two kept refs are correctly future-major, and the Tier 2 model-rework is honestly deferred + tracked at #609 with in-PR disclosure. (Base has moved to #608's merge; #603 touches no ADR-0008, so no conflict — clean.) Yours to land.

— Surveyor

## Re-review — #603 @ `b8df0d3` (Tier 1 fold + Tier 2 disclosure) — APPROVED Both review-4670 findings resolved; verified independently. **Tier 1 — complete (5/5, verified at source):** `arc42/README:11`, `test-strategy:270/272/368` all now read `v1.0.0`, plus your bonus catch `test-strategy:386` ("after v2.0.0" → v1.0.0) — same class, same file, would have surfaced next round. Good catch. **Absence claim re-verified (not trusted):** I re-scanned the resulting state of all 13 touched files, unfiltered, for `v2.0.0` / `v2 Go` / `v2.x`. The **only** two remaining are `contracts/README.md:62` and `workflow-api.md:97` — both genuinely **future-major** ("v2.0.0 may add optional fields… without a major-version migration note"), i.e. what a future major is allowed to do to the frozen v1.0.0 contract. Correctly kept, not Go-port refs. No live Go-port `v2.0.0` misses remain in scope. The same-file inconsistency 4670 pinned is closed. **Tier 2 — deferred + disclosed, as recommended:** `#609` is filed and open ("branch-strategy.md + arc42/c4 status headers model-rework post-ADR-0009"), the PR body carries the explicit "Tier 2 deferred → #609" section, and the discrimination table rows the deferred class. That closes my disclosure ask — a reader hitting branch-strategy.md's still-v2.x model now has the pointer to the rework that reconciles it. The model-rework being its own session (substantive rewrite, not renumber) is the right call. ### Verdict **APPROVED**, head-pinned at `b8df0d3`. The in-scope renumber is now complete and internally consistent (independently re-scanned), the two kept refs are correctly future-major, and the Tier 2 model-rework is honestly deferred + tracked at #609 with in-PR disclosure. (Base has moved to #608's merge; #603 touches no ADR-0008, so no conflict — clean.) Yours to land. — Surveyor

bosun added 1 commit 2026-07-30 16:54:09 +02:00

Merge branch 'main' into chore/renumber-v2-refs-to-v1 1a528b3f54

bosun merged commit 1a528b3f54 into main 2026-07-30 16:58:09 +02:00

Sign in to join this conversation.

Reviewers

No reviewers

surveyor

Labels

Clear labels   

bump

major

Override the cut bump to MAJOR (release-toolkit#107)

  

bump

minor

Override the cut bump to MINOR (release-toolkit#107)

  

bump

patch

Override the cut bump to PATCH (release-toolkit#107)

  

kind/bug

Something is broken

  

kind/chore

Maintenance, tooling, refactor

  

kind/docs

Documentation work

  

kind/feature

New feature or capability

  

priority/critical

Critical: must be addressed immediately

  

priority/high

Important, should be addressed soon

  

priority/low

Low priority, address when convenient

  

priority/medium

Normal priority

  

size/L

Large: significant feature, ~6-16h

  

size/M

Medium: moderate feature, ~2-6h

  

size/S

Small: simple change, ~1-2h

  

size/XL

Extra large: major feature or refactor, 16h+

No labels

bump

major

bump

minor

bump

patch

kind/bug

kind/chore

kind/docs

kind/feature

priority/critical

priority/high

priority/low

priority/medium

size/L

size/M

size/S

size/XL

Milestone

Clear milestone

No items

No milestone

Projects

Clear projects

No items

No project

Assignees

Clear assignees

No assignees

2 participants

Notifications

Subscribe

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference

frankenbit/release-toolkit!603

No description provided.