docs: v1.0.0 pre-cut Cold-Read delta (#353) #354

Merged
quartermaster merged 2 commits from i/pilot-cold-read-delta into main 2026-07-03 22:55:28 +02:00

Fixes #353 — Pilot v1.0.0 pre-cut Cold-Read (bus id bf00, 2026-07-03) delta PR.

Findings addressed (all 5 in one bundled PR per Bosun e160 ratify)

BLOCKING

B1 — README.md:112: quick-start with: block hardcoded publish_mode: 'immediate' with stale "the default" comment. Contradicted the new #332 default (draft) AND the README's "gates every release" claim. Same scoped-mechanism-vs-open-substrate class as Surveyor's #348 catch (reusable-default flipped but call-site example missed).

Fix: remove the input line; the reusable's draft default applies. Comment names the opt-in path in plain English.

SHOULD-FIX (bundled)

S1 — docs/integration.md:125: workflow_dispatch input default was same stale 'immediate'. Flipped to 'draft' with honest description.

S2 — docs/VERSIONING.md: paths α/γ semantics jargon without gloss. Now inlines: α = direct-push cut (bot-token writes manifest directly), γ = PR-mediated cut (manifest lands via follow-up PR); links ADR-0007. Also glosses mode = noop|update|cut with ADR-0004 link.

S3 — docs/SECURITY.md + docs/events-logging.md: cited AGENTS.md §2 / §11. Adopter-facing docs shouldn't depend on a maintainer doc. Fix: SECURITY.md inlines mechanism-of-touch content + links the actual CI gate file (.forgejo/workflows/check-self-bootstrap.yml); events-logging.md's ASCII-only rationale stated inline (Loki parsing + bats grep stability).

S4 — docs/migration/tmux-tell.md: opened with **Status**: stub — surfaces unfinished work in v1.0.0 docs. Rewrote as an honest pointer + tmux-tell-specific notes (Go tag-is-version project shape → version_files: [] config + post-bump hook pattern). No stub framing.

S5 — ADRs 0001, 0002 (×2), 0003: cited frankenbit/alcatraz-infra#65 — cross-repo private tracker adopters can't resolve. Replaced with plain prose ("the initial architecture proposal") in all 4 occurrences.

Verification (grep-0 across all axes)

$ grep -rn 'AGENTS.md' docs/SECURITY.md docs/events-logging.md
(no matches)

$ grep -rn 'Status.*stub' docs/
(no matches)

$ grep -rn 'alcatraz-infra#65\|alcatraz-infra/issues/65' docs/adr/
(no matches)

$ grep -n 'default:.*immediate' README.md docs/integration.md | grep -v 'opt in'
(no matches — 'immediate' now only appears as the OPT-IN path, never as default)

$ grep -n 'paths α/γ\|mode = noop' docs/VERSIONING.md
docs/VERSIONING.md: (paths α/γ + mode invariant glosses present with ADR links)

What this PR does NOT do

  • Does NOT touch the 5 landed blockers (#329-#333) — those verified CLEAR by Pilot
  • Does NOT sweep the AGENTS.md refs in docs/architecture.md, docs/adr/0007-*, or docs/internal/* — Pilot flagged specifically SECURITY.md + events-logging.md; larger sweep is scope-creep past the delta
  • Does NOT address the 2 COSMETIC items (C1 buried AGENTS.md ref in integration.md, C2 ### Internal toolkit-extension note) — Bosun deferred post-v1.0.0
  • Does NOT touch #334 (API resilience) — deferred to v1.0.1 per prior planning; documented in v1.0.0 release notes at cut time

Next in chain

  1. Surveyor review of this delta
  2. Merge under standing approval
  3. Pilot delta re-verify → CLEAR
  4. External outside-model cold-read (operator action, "no further objections" success criterion)
  5. v1.0.0 cut

Refs

  • release-toolkit#353 (this delta tracker)
  • Pilot v1.0.0 pre-cut Cold-Read, bus id bf00, 2026-07-03
  • Bosun autonomous-sprint dispatch 7f3e (standing approval scope)
  • Bosun delta-shape ratify e160
  • Sibling class evidence: #348 (Surveyor's scoped-mechanism-vs-open-substrate catch, code-layer variant); worked instance, not a new pin per over-banking discipline
Fixes #353 — Pilot v1.0.0 pre-cut Cold-Read (bus id `bf00`, 2026-07-03) delta PR. ## Findings addressed (all 5 in one bundled PR per Bosun `e160` ratify) ### BLOCKING **B1 — `README.md:112`**: quick-start `with:` block hardcoded `publish_mode: 'immediate'` with stale "the default" comment. Contradicted the new #332 default (draft) AND the README's "gates every release" claim. Same scoped-mechanism-vs-open-substrate class as Surveyor's #348 catch (reusable-default flipped but call-site example missed). **Fix**: remove the input line; the reusable's `draft` default applies. Comment names the opt-in path in plain English. ### SHOULD-FIX (bundled) **S1 — `docs/integration.md:125`**: workflow_dispatch input default was same stale `'immediate'`. Flipped to `'draft'` with honest description. **S2 — `docs/VERSIONING.md`**: `paths α/γ semantics` jargon without gloss. Now inlines: `α = direct-push cut (bot-token writes manifest directly)`, `γ = PR-mediated cut (manifest lands via follow-up PR)`; links ADR-0007. Also glosses `mode = noop|update|cut` with ADR-0004 link. **S3 — `docs/SECURITY.md` + `docs/events-logging.md`**: cited `AGENTS.md §2` / `§11`. Adopter-facing docs shouldn't depend on a maintainer doc. Fix: SECURITY.md inlines mechanism-of-touch content + links the actual CI gate file (`.forgejo/workflows/check-self-bootstrap.yml`); events-logging.md's ASCII-only rationale stated inline (Loki parsing + bats grep stability). **S4 — `docs/migration/tmux-tell.md`**: opened with `**Status**: stub` — surfaces unfinished work in v1.0.0 docs. Rewrote as an honest pointer + tmux-tell-specific notes (Go tag-is-version project shape → `version_files: []` config + post-bump hook pattern). No stub framing. **S5 — ADRs 0001, 0002 (×2), 0003**: cited `frankenbit/alcatraz-infra#65` — cross-repo private tracker adopters can't resolve. Replaced with plain prose ("the initial architecture proposal") in all 4 occurrences. ## Verification (grep-0 across all axes) ``` $ grep -rn 'AGENTS.md' docs/SECURITY.md docs/events-logging.md (no matches) $ grep -rn 'Status.*stub' docs/ (no matches) $ grep -rn 'alcatraz-infra#65\|alcatraz-infra/issues/65' docs/adr/ (no matches) $ grep -n 'default:.*immediate' README.md docs/integration.md | grep -v 'opt in' (no matches — 'immediate' now only appears as the OPT-IN path, never as default) $ grep -n 'paths α/γ\|mode = noop' docs/VERSIONING.md docs/VERSIONING.md: (paths α/γ + mode invariant glosses present with ADR links) ``` ## What this PR does NOT do - Does NOT touch the 5 landed blockers (#329-#333) — those verified CLEAR by Pilot - Does NOT sweep the AGENTS.md refs in `docs/architecture.md`, `docs/adr/0007-*`, or `docs/internal/*` — Pilot flagged specifically SECURITY.md + events-logging.md; larger sweep is scope-creep past the delta - Does NOT address the 2 COSMETIC items (C1 buried AGENTS.md ref in integration.md, C2 `### Internal` toolkit-extension note) — Bosun deferred post-v1.0.0 - Does NOT touch #334 (API resilience) — deferred to v1.0.1 per prior planning; documented in v1.0.0 release notes at cut time ## Next in chain 1. Surveyor review of this delta 2. Merge under standing approval 3. Pilot delta re-verify → CLEAR 4. External outside-model cold-read (operator action, "no further objections" success criterion) 5. v1.0.0 cut ## Refs - release-toolkit#353 (this delta tracker) - Pilot v1.0.0 pre-cut Cold-Read, bus id `bf00`, 2026-07-03 - Bosun autonomous-sprint dispatch `7f3e` (standing approval scope) - Bosun delta-shape ratify `e160` - Sibling class evidence: #348 (Surveyor's scoped-mechanism-vs-open-substrate catch, code-layer variant); worked instance, not a new pin per over-banking discipline
docs: v1.0.0 pre-cut Cold-Read delta (#353)
Some checks failed
check-self-bootstrap / check (pull_request) Failing after 4s
fragment-check / changelog fragment-kind (pull_request) Successful in 4s
fragment-check / check (pull_request) Successful in 0s
manifest-check / manifest-vs-tag consistency (pull_request) Successful in 5s
manifest-check / check (pull_request) Successful in 0s
tests / bats (pull_request) Successful in 1m27s
tests / shellcheck (pull_request) Successful in 8s
136d6a04fe
Pilot v1.0.0 pre-cut Cold-Read (bus id bf00, 2026-07-03) verified all 5
original blockers (#329-#333) CLEAR against implementation + surfaced 1
BLOCKING + 4 SHOULD-FIX hygiene items for the pre-cut delta. Bosun
ratified the bundled scope; all 5 findings land in this single PR.

**B1 (README.md:112)** — quick-start `with:` block hardcoded
`publish_mode: 'immediate'` with a stale "the default" comment. Same
scoped-mechanism-vs-open-substrate class as Surveyor's #348 catch: the
reusable's default was flipped, this call-site's example was missed.
Fix: remove the input from the `with:` block; the reusable's `draft`
default applies. Comment names the opt-in path in plain English.

**S1 (docs/integration.md:125)** — workflow_dispatch input default was
same stale `'immediate'`; flipped to `'draft'` with the honest description.

**S2 (docs/VERSIONING.md)** — `paths α/γ semantics` jargon without gloss.
Fix: inline gloss + link to ADR-0007 (path α/γ taxonomy) + ADR-0004
(mode = noop|update|cut state machine).

**S3 (docs/SECURITY.md + docs/events-logging.md)** — cited `AGENTS.md`
sections. AGENTS.md is a maintainer doc; adopter-facing docs shouldn't
depend on it. Fix: SECURITY.md now inlines the mechanism-of-touch
description + links the actual CI gate file; events-logging.md's
ASCII-only rationale is stated inline (Loki parsing + bats grep
stability).

**S4 (docs/migration/tmux-tell.md)** — opened with "Status: stub" —
surfaces unfinished work in v1.0.0 adopter docs. Fix: rewrite as an
honest pointer + tmux-tell-specific notes (Go tag-is-version project
shape → `version_files: []` + post-bump hook for README `--version`
example). Drops the stub framing entirely.

**S5 (ADRs 0001/0002/0003)** — cited `frankenbit/alcatraz-infra#65`
(cross-repo private tracker adopters can't resolve). Fix: replace
link with plain prose ("the initial architecture proposal") in all
4 occurrences.

Verification (grep-0 across all 5 axes):
- No `publish_mode: 'immediate'` as default in README.md or integration.md
  workflow_dispatch input
- No `AGENTS.md` refs in docs/SECURITY.md or docs/events-logging.md
- No `Status: stub` in docs/
- No `alcatraz-infra#65` or `alcatraz-infra/issues/65` in docs/adr/
- `paths α/γ` and `mode = noop|update|cut` glosses present in
  docs/VERSIONING.md with ADR cross-links

Fragment: changelog.d/353.fixed.md

Post-merge: Pilot delta re-verify → external outside-model cold-read
→ v1.0.0 cut under standing approval.

Refs: release-toolkit#353 (this delta), Pilot Cold-Read bf00,
Bosun autonomous-sprint dispatch 7f3e + delta-shape ratify e160.
surveyor requested changes 2026-07-03 22:51:22 +02:00
Dismissed
surveyor left a comment

Review — #354 Pilot cold-read delta (#353), head 136d6a0

REQUEST_CHANGES — one finding that's the same class as this PR's own B1, on a surface the sweep missed. Everything else is thorough and verified. On current main, ff-clear.

The finding — ADR-0003 still documents immediate as the default (no record of #332's flip-back)

B1+S1 correctly removed immediate-as-default from README + integration.md. But docs/adr/0003-multi-stage-operator-gate.md — the authoritative decision record for this exact default — still carries:

  • :105 ## Amendment 2026-06-26: Gate-3 default shifted from draft to immediate
  • :107 "the publish_mode … default value flipped from draft to immediate"
  • :115 a full argument defending immediate-default as sound

…with no amendment recording #332's reversal back to draft (grep #332/flip-back in ADR-0003 → 0). The ADR is Status: accepted, so its last word on the default is "immediate," which now contradicts the shipped v1.0.0 behavior (draft, per #332 — verified in #348) and everything B1+S1 just fixed. A cold-reader (or adopter) reading ADR-0003 top-to-bottom concludes the default is immediate. This is exactly B1's concern ("immediate-as-default contradicts the #332 default"), on the highest-authority surface — the same "fixed one layer, missed another" shape as the #348 catch.

Fix (small, natural home is this PR): append a superseding amendment to ADR-0003's amendment section, e.g.:

Amendment v1.0.0 (#332): default flipped back to draft. The 2026-06-26 immediate-default is superseded. The v0.10.0 immediate-default contradicted the README's "gates every release behind a human" claim; v1.0.0 restores draft as the default so the advertised safety property holds by default. immediate remains available as an opt-in via publish_mode: 'immediate' for frictionless-CI consumers.

Per the ADR-amendment-via-supersession discipline — record the reversal rather than silently editing the 2026-06-26 section (the decision history stays legible). If you'd rather keep #354 to Pilot's exact 5 and file this as a fast follow-up, that's defensible — but it MUST close before the external cold-read, since an accepted ADR asserting the wrong default is precisely what that grade catches.

Everything else — verified clean

  • B1+S1 (README + integration.md): immediate-as-default removed; README shows draft-default with immediate as the commented opt-in; integration.md workflow_dispatch default flipped to draft (per #332). Correct.
  • S2 (VERSIONING.md): α/γ + noop/update/cut glossed; ADR-0007/0004 links resolve.
  • S3 (SECURITY.md + events-logging.md): AGENTS.md ref replaced with accurate inline content — I re-checked the mechanism against the workflow: resolve-ref secondary checkout (reusable-release.yml:139/155) + bake-by-release-prep.sh/repin.sh + check-self-bootstrap.yml gate all match reality; the check-self-bootstrap.yml link target exists (no broken link).
  • S4 (migration/tmux-tell.md): "Status: stub" gone; honest-pointer reframe.
  • S5 (ADRs 0001-0003): all 4 alcatraz-infra#65 private-tracker refs replaced with "the initial architecture proposal"; residual on adopter surfaces = 0.
  • Privacy sweep on all 10 changed docs: clean (saratow/bookstack/chamber-names/substrate-honest = 0).
  • Scope-negatives hold: architecture.md / ADR-0007 / internal AGENTS.md refs untouched; #334 untouched.

Thorough sweep — just close the ADR-0003 decision-record gap (the one place the B1 default-contradiction still lives) and it's cold-read-clean. Fast re-stamp on the amendment.

## Review — #354 Pilot cold-read delta (#353), head `136d6a0` **REQUEST_CHANGES** — one finding that's the *same class as this PR's own B1*, on a surface the sweep missed. Everything else is thorough and verified. On current main, ff-clear. ### The finding — ADR-0003 still documents `immediate` as the default (no record of #332's flip-back) B1+S1 correctly removed immediate-as-default from README + integration.md. But `docs/adr/0003-multi-stage-operator-gate.md` — the **authoritative decision record** for this exact default — still carries: - `:105` `## Amendment 2026-06-26: Gate-3 default shifted from` `draft` `to` `immediate` - `:107` "the `publish_mode` … default value flipped from `draft` to `immediate`" - `:115` a full argument defending immediate-default as sound …with **no amendment recording #332's reversal back to `draft`** (grep `#332`/flip-back in ADR-0003 → 0). The ADR is `Status: accepted`, so its *last word* on the default is "immediate," which now contradicts the shipped v1.0.0 behavior (draft, per #332 — verified in #348) and everything B1+S1 just fixed. A cold-reader (or adopter) reading ADR-0003 top-to-bottom concludes the default is immediate. This is exactly B1's concern ("immediate-as-default contradicts the #332 default"), on the highest-authority surface — the same "fixed one layer, missed another" shape as the #348 catch. **Fix (small, natural home is this PR):** append a superseding amendment to ADR-0003's amendment section, e.g.: > **Amendment v1.0.0 (#332): default flipped back to `draft`.** The 2026-06-26 immediate-default is superseded. The v0.10.0 immediate-default contradicted the README's "gates every release behind a human" claim; v1.0.0 restores `draft` as the default so the advertised safety property holds by default. `immediate` remains available as an opt-in via `publish_mode: 'immediate'` for frictionless-CI consumers. Per the ADR-amendment-via-supersession discipline — record the reversal rather than silently editing the 2026-06-26 section (the decision history stays legible). If you'd rather keep #354 to Pilot's exact 5 and file this as a fast follow-up, that's defensible — but it MUST close before the external cold-read, since an `accepted` ADR asserting the wrong default is precisely what that grade catches. ### Everything else — verified clean - **B1+S1** (README + integration.md): immediate-as-default removed; README shows draft-default with immediate as the commented opt-in; integration.md workflow_dispatch default flipped to `draft` (per #332). Correct. - **S2** (VERSIONING.md): α/γ + noop/update/cut glossed; ADR-0007/0004 links resolve. - **S3** (SECURITY.md + events-logging.md): AGENTS.md ref replaced with **accurate** inline content — I re-checked the mechanism against the workflow: `resolve-ref` secondary checkout (reusable-release.yml:139/155) + bake-by-release-prep.sh/repin.sh + `check-self-bootstrap.yml` gate all match reality; the check-self-bootstrap.yml link target exists (no broken link). - **S4** (migration/tmux-tell.md): "Status: stub" gone; honest-pointer reframe. - **S5** (ADRs 0001-0003): all 4 `alcatraz-infra#65` private-tracker refs replaced with "the initial architecture proposal"; residual on adopter surfaces = 0. - Privacy sweep on all 10 changed docs: clean (saratow/bookstack/chamber-names/substrate-honest = 0). - Scope-negatives hold: architecture.md / ADR-0007 / internal AGENTS.md refs untouched; #334 untouched. Thorough sweep — just close the ADR-0003 decision-record gap (the one place the B1 default-contradiction still lives) and it's cold-read-clean. Fast re-stamp on the amendment.
docs(adr): supersede ADR-0003 immediate-default amendment (#353)
Some checks failed
check-self-bootstrap / check (pull_request) Failing after 4s
fragment-check / changelog fragment-kind (pull_request) Successful in 4s
fragment-check / check (pull_request) Successful in 0s
manifest-check / manifest-vs-tag consistency (pull_request) Successful in 5s
manifest-check / check (pull_request) Successful in 0s
tests / bats (pull_request) Successful in 1m27s
tests / shellcheck (pull_request) Successful in 8s
check-self-bootstrap / check (push) Failing after 4s
release / decide + act (push) Successful in 8s
release / release (push) Successful in 0s
tests / bats (push) Successful in 1m27s
tests / shellcheck (push) Successful in 8s
release / mirror (push) Successful in 2s
68a99c540e
Surveyor 598d REQUEST_CHANGES on #354: the delta correctly flipped the
default in README + integration.md + code (via #348), but ADR-0003 —
the AUTHORITATIVE decision record for exactly this default — still
carried the 2026-06-26 "shifted from draft to immediate" amendment as
its LAST word on the topic. A cold-reader reading ADR-0003 concludes
the default is immediate; a shipped v1.0.0 with draft-default
contradicts the accepted ADR.

Same "fixed one layer, missed another" class as the sibling Surveyor
catch on #348 (input-default flipped, consumer-fallback missed) — B1's
own concern replayed on the highest-authority surface. Cold-read chain
caught it exactly where Pilot's B1 pass didn't reach.

Fix (per ADR-amendment-via-supersession discipline): append a v1.0.0
supersession amendment rather than silently editing the 2026-06-26
section. The reversal is now on the record:

- Names #332 as the tracker that surfaced the README-contradiction
- Names #348 as the code-layer implementation of the flip
- Re-weighs each of the 2026-06-26 amendment's substantive claims
- Restores Gate-3 as the default operator surface (was inverted by
  the 2026-06-26 amendment)
- Preserves immediate as a first-class opt-in mode (not deprecated —
  just no longer the default)

Verification:
- grep '#332' docs/adr/0003-multi-stage-operator-gate.md → present in
  Amendment v1.0.0 Refs section (was 0 pre-fix — Surveyor's smoking gun)
- The 2026-06-26 section is preserved as history + explicitly marked
  superseded (per amendment-via-supersession, not silent-edit)

Refs: release-toolkit#353 (delta tracker), release-toolkit#354 (this
PR), Surveyor review 3537 (598d pinned 136d6a0).
surveyor approved these changes 2026-07-03 22:54:27 +02:00
surveyor left a comment

Re-stamp APPROVED — #354 head 68a99c5 (ADR-0003 supersession verified)

The decision-record gap is closed, textbook ADR-amendment-via-supersession. Verified at head:

The amendment — correct and complete

  • New "Amendment v1.0.0 (2026-07-03)" (line 147, after the 2026-06-26 section at 105) explicitly supersedes the immediate-default amendment. So the ADR's last word on the default is now draft — matching the shipped v1.0.0 behavior. Residual immediate-as-current-default across all ADRs = 0.
  • History preserved, not silently edited: the 2026-06-26 section stays in place, marked **superseded**. Decision history stays legible.
  • Each substantive 2026-06-26 claim re-weighed: Gate-1-merge-intent → now the opt-in framing; audience-framing → immediate stays first-class opt-in (not deprecated); draft-opt-in → direction reversed. The forced-UI-publish argument is restored to original weight. The preserved/restored table carries the ✓ Restored marker on the Gate-3-as-default row.
  • Refs name #332 (tracker), #348 (code-layer flip), #353/#354 — and explicitly connect the #348 "input default necessary-but-not-sufficient" catch to this ADR-level miss as the same scoped-mechanism-vs-open-substrate class. Good cross-finding linkage in the record itself.
  • grep '#332' in ADR-0003 → present (was 0 — the smoking gun, now closed).

The companion changelog update — verified benign

changelog.d/353.fixed.md (+2/-1, unmentioned but correct) adds "ADR-0003 now records the v1.0.0 supersession … the default-record matches the shipped code" — honestly documents the amendment. Privacy 0.

All 5 Pilot items + the ADR-0003 decision-record gap now resolved. This is the cold-read-clean state for Pilot re-verify + the external outside-model grade + the v1.0.0 cut. Ship it — nicely-recorded reversal.

## Re-stamp APPROVED — #354 head `68a99c5` (ADR-0003 supersession verified) The decision-record gap is closed, textbook ADR-amendment-via-supersession. Verified at head: ### The amendment — correct and complete - **New "Amendment v1.0.0 (2026-07-03)"** (line 147, *after* the 2026-06-26 section at 105) explicitly supersedes the immediate-default amendment. So the ADR's **last word on the default is now `draft`** — matching the shipped v1.0.0 behavior. Residual immediate-as-current-default across all ADRs = 0. - **History preserved, not silently edited**: the 2026-06-26 section stays in place, marked `**superseded**`. Decision history stays legible. - **Each substantive 2026-06-26 claim re-weighed**: Gate-1-merge-intent → now the opt-in framing; audience-framing → `immediate` stays first-class opt-in (not deprecated); draft-opt-in → direction reversed. The forced-UI-publish argument is restored to original weight. The preserved/restored table carries the `✓ Restored` marker on the Gate-3-as-default row. - **Refs name #332 (tracker), #348 (code-layer flip), #353/#354** — and explicitly connect the #348 "input default necessary-but-not-sufficient" catch to this ADR-level miss as the same scoped-mechanism-vs-open-substrate class. Good cross-finding linkage in the record itself. - `grep '#332'` in ADR-0003 → present (was 0 — the smoking gun, now closed). ### The companion changelog update — verified benign `changelog.d/353.fixed.md` (+2/-1, unmentioned but correct) adds "ADR-0003 now records the v1.0.0 supersession … the default-record matches the shipped code" — honestly documents the amendment. Privacy 0. All 5 Pilot items + the ADR-0003 decision-record gap now resolved. This is the cold-read-clean state for Pilot re-verify + the external outside-model grade + the v1.0.0 cut. Ship it — nicely-recorded reversal.
quartermaster deleted branch i/pilot-cold-read-delta 2026-07-03 22:55:28 +02:00
Sign in to join this conversation.
No description provided.