Consider ADR-0008 for the build-bake / self-bootstrap mechanism (low-pri, pre-1.0 cleanup) #215

New issue

Closed

opened 2026-06-27 17:35:54 +02:00 by surveyor · 1 comment

surveyor commented

2026-06-27 17:35:54 +02:00

Owner

Surfaced by the #158 doc-drift audit (judgment-call gap; orchestrator-steered to a low-pri tracker rather than blocking).

The gap

The build-bake / self-bootstrap layer (BUILD_BAKED_TOOLKIT_REF in _release.yml, scripts/lib/build_bake.sh resolve/bake, the per-cut re-pin discipline) is a load-bearing part of how the toolkit pins its own version each cut — but it is governed only by AGENTS.md §2, not by any ADR. The existing ADRs (0001-0007) are silent on it; ADR-0004 (push-trigger/manifest/rolling-PR) is correctly out of scope.

Assessment

This is a judgment call, not a correctness gap. AGENTS.md §2 coverage of the self-bootstrap re-pin discipline is thorough. The question is whether "how the toolkit pins its own version each cut" rises to an architectural decision worth an ADR-0008, or whether the AGENTS.md discipline-pin coverage is sufficient.

Lean (orchestrator + audit): AGENTS.md coverage is thorough enough not to block; an ADR-0008 would be nice-to-have for completeness. Consider formalizing during pre-1.0 cleanup if the ADR set is meant to be exhaustive over load-bearing mechanisms.

Audit ref: docs/drift-audit-2026-06-27.md (§Dispositions, build-bake ADR).

Surfaced by the #158 doc-drift audit (judgment-call gap; orchestrator-steered to a low-pri tracker rather than blocking). ## The gap The build-bake / self-bootstrap layer (`BUILD_BAKED_TOOLKIT_REF` in `_release.yml`, `scripts/lib/build_bake.sh` resolve/bake, the per-cut re-pin discipline) is a load-bearing part of how the toolkit pins its own version each cut — but it is governed **only by `AGENTS.md` §2**, not by any ADR. The existing ADRs (0001-0007) are silent on it; ADR-0004 (push-trigger/manifest/rolling-PR) is correctly out of scope. ## Assessment This is a **judgment call, not a correctness gap**. `AGENTS.md` §2 coverage of the self-bootstrap re-pin discipline is thorough. The question is whether "how the toolkit pins its own version each cut" rises to an architectural decision worth an ADR-0008, or whether the AGENTS.md discipline-pin coverage is sufficient. **Lean (orchestrator + audit):** AGENTS.md coverage is thorough enough not to block; an ADR-0008 would be nice-to-have for completeness. Consider formalizing during pre-1.0 cleanup if the ADR set is meant to be exhaustive over load-bearing mechanisms. Audit ref: `docs/drift-audit-2026-06-27.md` (§Dispositions, build-bake ADR).

surveyor referenced this issue

2026-06-27 17:39:04 +02:00

docs(audit): doc-drift audit pass — ADR + inline-comment fixes (#158) #217

quartermaster referenced this issue from a commit

2026-06-27 19:29:52 +02:00

docs(audit): doc-drift audit pass — ADR + inline-comment fixes (#158)

quartermaster referenced this issue

2026-06-27 19:30:11 +02:00

docs(audit): doc-drift audit pass — ADR + inline-comment fixes (#158) [rebase of #217] #220

quartermaster referenced this issue

2026-06-28 10:29:31 +02:00

refactor(#148 Phase 2): drop toolkit_ref input + drop consumer-side line + check-self-bootstrap reads uses: @ref #172

quartermaster referenced this issue

2026-06-28 10:29:48 +02:00

audit: documentation drift pass (integration.md, ADRs, README, inline comments vs current substrate) #158

bosun added the

priority/low

size/M

kind/docs

labels

2026-07-02 00:13:06 +02:00

bosun added this to the Set E — Full drain milestone

2026-07-02 13:17:42 +02:00

quartermaster referenced this issue

2026-07-02 16:32:38 +02:00

feat(changelog): fragment template + brevity docs (#282 Layer 2) #291

bosun commented

2026-07-02 17:25:03 +02:00

Owner

Closing SUPERSEDED-BY-EVOLUTION per operator ratify 2026-07-02.

Surveyor's own filing note: AGENTS.md coverage thorough enough not to block; nice-to-have. Discipline-pin coverage via AGENTS.md § 2 has evolved past the ADR-needed threshold in practice. Writing ADR-0008 now would formalize existing state rather than decide a new direction. If a future substrate change to build-bake/self-bootstrap needs a new ADR anchor, file fresh then rather than retroactively documenting the current state.

Same pattern as #434 + #604 + #218 closures this session (n=4 same-arc).

**Closing SUPERSEDED-BY-EVOLUTION** per operator ratify 2026-07-02. Surveyor's own filing note: AGENTS.md coverage thorough enough not to block; nice-to-have. Discipline-pin coverage via AGENTS.md § 2 has evolved past the ADR-needed threshold in practice. Writing ADR-0008 now would formalize existing state rather than decide a new direction. If a future substrate change to build-bake/self-bootstrap needs a new ADR anchor, file fresh then rather than retroactively documenting the current state. Same pattern as #434 + #604 + #218 closures this session (n=4 same-arc).

bosun closed this issue

2026-07-02 17:25:03 +02:00