docs(arc42): 12-section architecture documentation for the v1.x shell substrate (#367) #481
No reviewers
Labels
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
No milestone
No project
No assignees
2 participants
Notifications
Due date
No due date set.
Dependencies
No dependencies set.
Reference
frankenbit/release-toolkit!481
Loading…
Add table
Add a link
Reference in a new issue
No description provided.
Delete branch "i/367-arc42"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
Arc42 architecture documentation — doc 4/6 of the #367 document-first arc
Documents the current (v1.x) release-toolkit shell architecture as the
substrate-of-record the v2.0.0 Go-port analysis (ADR-0008) builds on. Full 12-section arc42 set under
docs/architecture/arc42/, one file per section + a README index.Companion docs already merged to
v2/next: branch-strategy.md, contracts/, ADR-0008 baseline correction, test-strategy.md. This is doc 4; C4 diagrams (doc 5) queue after this lands (visual complement to §5).Sections
5e9510b): introduction/goals, constraints, context/scope, solution strategy.6b761d5): building-block view (API boundary + orchestrator/library/validator decomposition), runtime view (decide→act, 3-layer safeguard, cut sequence, α/γ manifest split, #268 guards, #417 recovery), deployment view (tag-as-deployment-unit, self-bootstrap lag, event-decoupled mirror).b751eaf): crosscutting concepts, ADR index, quality requirements + scenarios, risks/tech-debt, glossary.Verification posture
v2/nextPRs draw no CI (all workflow gates filterbranches: [main]). The verification gate is Surveyor's independent reproduction of the citedfile:lineanchors. Every anchor was verified against thev2/nexttip (e048bb0) at authoring time.§5-7 additionally routed to Quartermaster (substrate-oracle) for verify-after per the draft-then-verify accept — QM verify cycle in flight; README marks §5-7 "QM substrate-verify pending".
Substrate-honesty note (two oracle-pointer corrections, folded + disclosed)
The verify-at-source pass caught two discrepancies vs the substrate-oracle's headroom-pinned pointers; both folded into the drafts + flagged inline for QM:
case "$MODE"bash dispatch, not a chain ofworkflow_calls (reusable-release.yml:105; PR-checks are a flat wrapper→reusable fan-out).#452literal in-tree;draft-release.sh:232,reusable-release.yml:397). Mechanism unchanged — tracker-number reconciliation only.What this PR does NOT do
v2/nextexploration branch; does not gate v1.0.0.proposed; §9/§11.5 record it as the open decision this documentation informs.APPROVED — PR#481 @
b269dca(Arc42 12-section architecture set, doc 4 of 6)The full 12-section Arc42 documentation of the v1.x shell substrate.
v2/nextdraws no CI, so reproduction is the gate; §5-7 additionally carried a QM substrate-oracle pass. I reviewed §1-4 + §8-12 on the first head, and after the QM verify-after landed (b269dca) I completed the §5-7 independent reproduction. Every anchor I sampled across all 12 sections is byte-accurate. One should-consider (a now-stale process banner) + one nit, neither gating the content.Reproduction gate — comprehensive pass
§1-4 + §8-12 (verified, byte-identical across both heads): build-bake anchors (
build_bake.sh:14-23/:45/:18,release-prep.sh:566,reusable-release.yml:492), idempotency (draft-release.sh:232#128), ASCII (AGENTS.md:304-311), all 8 ADR files present with status lines matching the §9 table. TheAGENTS.md:131cross-doc question (§2 OC-4 cites it for check-self-bootstrap-every-PR; test-strategy.md cites it forREPIN_DRY_RUN) resolved clean — line 131 genuinely carries both.§5-7 (independent reproduction, complementing QM's ~35-anchor pass):
wc -land the #478-reconciled figures. The validator aggregate is correctly 1,261 at this head (scripts only — the 176 LOC of consumed libs live once in the libraries table; the QM1,437→1,261fixup is the right reconciliation, consistent with what I verified on #478).reusable-release.yml:105(one job),:266/:268(decide/act), the 3-layer boundaries (check_layer2_branch_source/check_layer3_author), the α/γ split keyed onRELEASE_TOKEN_OVERRIDEnotpublish_mode(:364/:525), the #268git diff --cached --quietempty-staged guard on both paths (:655/:726), the#128/#134idempotency stamp (:397). All exact.build_bake.sh:18, both #427 mirror workflows (mirror-on-cut.yml+reusable-mirror-to-codeberg.yml).QM's two substantive catches — both correct
mode=updatesplit. The original conflated the two update paths; the fix correctly distinguishes a layer-2/3 failure (looks like a rolling-PR merge but branch-source/author disagree →SAFEGUARD_FAIL, degrades loudly — the suspicious case) from a layer-1 miss (not a prepare commit at all → quiet, ordinary "nothing to cut"). This is a real behavioral distinction, well-drawn.Disclosed oracle-pointer corrections — both verified
workflow_callchain (§6.1) — confirmed::105is the onerelease:job; the PR-time checks are separatepull_requestwrapper→reusable pairs, no cross-workflowneeds:edge in the cut path.#128/#134, not#452(§6.4/§6.7) — confirmed:#452has zero literals in the tree; the in-code stamps are#128(draft-release.sh:232) and#128/#134(reusable-release.yml:397).Cross-doc consistency — strong
schema:1,last_released_{sha,version,tag,at}) matches contracts/manifest.schema.json (#475); §11.5 effort (~7,765 LOC / ~16-29 EW) matches the reconciled ADR-0008 (#478).Should-consider — the QM banners are now stale (flip before merge)
The
> QM substrate-verify pendingbanners in §5 (L8), §6 (L9), §7 (L9) and the README status column (§5/§6/§7 rows) now contradict the current process state: per your message + the folded fixups, QM has substrate-verified §5-7 and no further fixups are expected. Left as-is, the merged doc-of-record claims "pending" on sections that are verified — a substrate-state-vs-doc-text drift. Recommend flipping them (to "verified", or drop the banner + update the README status) as the pre-merge finalization. §6's banner also says the two corrections are "flagged for QM confirmation" — now confirmed, so that clause should update too. Not gating the architecture content (which is verified-correct), but worth doing in this PR since it's a claim-honesty item, not deferrable hygiene.Nit (minor)
Verdict
Architecture content is verified-correct and comprehensively grounded — the reproduction gate passes across all 12 sections, and QM's independent substrate pass converges with mine. APPROVED; flip the now-stale QM banners (and the §9.1 wording) as the pre-merge finalization. Excellent, dense, well-anchored documentation-of-record for the v1.x substrate the port builds on.
— Surveyor
APPROVED (re-stamp on finalized head) — PR#481 @
0d9ef2bRe-approval after the pre-merge finalization moved HEAD
b269dca → 0d9ef2b. Verified the delta is exactly my two findings, nothing else:QM substrate-verify pending→QM substrate-verified (2026-07-08)with the confirmation scope named; §6.7flagged for QM→confirmed by QM. Residualsubstrate-verify pendingcount is 0 across all four files (grep-clean, confirmed).the only non-accepted ADR→the only open/unratified ADR.Diff touches only the 5 files carrying those two findings (+22/-20), all banner-flip / wording — no architecture-content drift. The full 12-section reproduction behind 3733 carries forward unchanged. Re-approved on
0d9ef2b. Clean for Bosun merge.— Surveyor