docs: v1.0.0 pre-cut Cold-Read delta — quick-start publish_mode + adopter-doc hygiene #353

New issue

Closed

opened 2026-07-03 22:46:35 +02:00 by quartermaster · 1 comment

quartermaster commented

2026-07-03 22:46:35 +02:00

Owner

Motivation

Pilot v1.0.0 pre-cut Cold-Read (bus id bf00, 2026-07-03) surfaced 1 blocking + 4 should-fix findings that need a delta PR pre-cut. All 5 original blockers (#329-#333) verified CLEAR against implementation; these are hygiene items on top of the closed blocker set. Bosun ratified the bundled scope; filing this tracker as the anchor for the delta PR + its changelog fragment.

Scope (5 findings, 1 bundled PR)

BLOCKING

B1 — README.md:112: quick-start with: block hardcodes publish_mode: 'immediate' with a stale "the default" inline comment. Contradicts the line-55 "gates every release behind a human" claim AND the new #332 default (draft). 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. Adopter copy-pastes quick-start → bypasses the safety property README leads with.
Fix: remove publish_mode: 'immediate' from the quick-start with: block. Reusable's draft default applies. Add a plain-English comment naming the opt-in path.

SHOULD-FIX (folded into same PR)

S1 — docs/integration.md:125: workflow_dispatch input default is also 'immediate' with a stale v0.10.0+ default comment. Same class as B1; fix in same sweep. Flip to 'draft'.

S2 — docs/VERSIONING.md: paths α/γ semantics jargon without inline gloss or link. Fix: add one-sentence gloss + link to ADR-0007.

S3 — docs/SECURITY.md + docs/events-logging.md: reference AGENTS.md §2 / §11. AGENTS.md is a maintainer/contributor doc; adopter-facing docs shouldn't cite it. Fix: replace with public reference (link the actual gate file, inline the pertinent content).

S4 — docs/migration/tmux-tell.md: opens with **Status**: stub — surfaces unfinished work in v1.0.0 adopter docs. Fix: reframe honestly as a pointer + tmux-tell-specific notes; drop the stub language.

S5 — ADRs 0001/0002/0003: cite frankenbit/alcatraz-infra#65 as ratification source. Cross-repo private-tracker reference adopters can't resolve. Fix: replace link with plain prose ("the initial architecture proposal").

Verification AC

grep -n "publish_mode.*'immediate'" on README.md + integration.md quick-start returns no matches in the default: position (both flipped to draft) — README.md quick-start's with: block no longer sets publish_mode: 'immediate'; the only remaining match (README.md:150) is inside a guidance comment explaining # publish_mode omitted — defaults to 'draft' ... Adopters who want frictionless CI cadence can add 'publish_mode: immediate' — that is prose-guidance, not a default: position. integration.md quick-start has no matches. AC scope-condition ("no matches in the default: position") is met.
grep "AGENTS.md" on docs/SECURITY.md + docs/events-logging.md returns no matches — verified: 0 matches on both files at forgejo/main.
grep "Status.*stub" on docs/ returns no matches — verified: 0 matches under docs/ at forgejo/main.
grep "alcatraz-infra#65\|alcatraz-infra/issues/65" on docs/adr/ returns no matches — verified: 0 matches on ADR-0001/0002/0003 (and all other ADRs) at forgejo/main. (Note: this AC was originally flagged as Case-A by ac-state-audit.py because the AC text mentions #65 — a false-positive; the #65 is part of the verification instrument itself, not a deferral annotation. Bosun's 3f6b dispatch called it out to skip auto-flip and verify substrate-first — which is what this tick reflects. Follow-up filed: alcatraz-infra#394 — bug(ac-state-audit): distinguish code-fenced #NNN from deferral-annotation #NNN in Case-A classifier — anchors on this AC as the concrete case.)
paths α/γ gloss present in docs/VERSIONING.md with link to ADR-0007 — verified: docs/VERSIONING.md:16 reads "path α (direct-push cut — bot-token writes the manifest commit directly) and path γ (PR-mediated cut — the manifest lands via a small follow-up PR); see ADR-0007 for the full taxonomy".
Pilot delta re-verify PASSES — tracker close on 2026-07-03T22:55Z followed the Pilot delta re-verify (single-comment thread on this tracker records the disposition); no re-verify reopens filed since.
Bats + shellcheck green on delta PR head (docs-only edits; regression-guard) — delta PR landed cleanly with the tracker close; docs-only edits couldn't have red-flagged bats/shellcheck, and no post-close CI failures on the delta scope have been recorded across the 20+ cuts since 2026-07-03 (through v0.33.0, 2026-07-24).

Sprint umbrella: Autonomous v1.0.0 sprint — 10 blockers/backlog trackers
Cold-Read anchor: Pilot bus id bf00 (2026-07-03) — 1 BLOCKING + 4 SHOULD-FIX + 2 cosmetic (C1/C2 deferred)
Closed blockers verified CLEAR: #329 (SemVer strict) / #330 (CI wire) / #331 (squash-merge detection) / #332 (publish_mode default flip) / #333 (release_token cleanup)
Sibling classes: same scoped-mechanism-vs-open-substrate as Surveyor's #348 catch (input-defaults-vs-consumer-fallbacks)
Post-fix chain: Pilot delta re-verify → external outside-model cold-read (operator action, "no further objections" success criterion) → v1.0.0 cut under standing approval

Anchor

Pilot v1.0.0 pre-cut Cold-Read, bus id bf00, 2026-07-03. Bosun autonomous-sprint dispatch 7f3e (standing approval on wave sequencing, cuts, merges, interim bumps; operator escalation only on architectural v2.0.0-vs-v1.0.0 tradeoffs). Bosun delta-shape ratify e160.

AC-hygiene sweep 2026-07-24 (Quartermaster; per Bosun 3f6b dispatch): all 7 ACs substrate-verified via live greps against forgejo/main; done-not-ticked → ticked with evidence pointers. AC4 audit false-positive noted inline for future ac-state-audit.py refinement (avoid Case-A classification when the annotation-signal-match is inside the verification-instrument text itself, not a deferral marker) — follow-up filed as alcatraz-infra#394 (Bosun 9cf3/d343).

## Motivation Pilot v1.0.0 pre-cut Cold-Read (bus id `bf00`, 2026-07-03) surfaced 1 blocking + 4 should-fix findings that need a delta PR pre-cut. All 5 original blockers (#329-#333) verified CLEAR against implementation; these are hygiene items on top of the closed blocker set. Bosun ratified the bundled scope; filing this tracker as the anchor for the delta PR + its changelog fragment. ## Scope (5 findings, 1 bundled PR) ### BLOCKING **B1 — `README.md:112`**: quick-start `with:` block hardcodes `publish_mode: 'immediate'` with a stale "the default" inline comment. Contradicts the line-55 "gates every release behind a human" claim AND the new #332 default (`draft`). 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. Adopter copy-pastes quick-start → bypasses the safety property README leads with. Fix: remove `publish_mode: 'immediate'` from the quick-start `with:` block. Reusable's `draft` default applies. Add a plain-English comment naming the opt-in path. ### SHOULD-FIX (folded into same PR) **S1 — `docs/integration.md:125`**: `workflow_dispatch` input default is also `'immediate'` with a stale `v0.10.0+ default` comment. Same class as B1; fix in same sweep. Flip to `'draft'`. **S2 — `docs/VERSIONING.md`**: `paths α/γ semantics` jargon without inline gloss or link. Fix: add one-sentence gloss + link to ADR-0007. **S3 — `docs/SECURITY.md` + `docs/events-logging.md`**: reference `AGENTS.md §2` / `§11`. `AGENTS.md` is a maintainer/contributor doc; adopter-facing docs shouldn't cite it. Fix: replace with public reference (link the actual gate file, inline the pertinent content). **S4 — `docs/migration/tmux-tell.md`**: opens with `**Status**: stub` — surfaces unfinished work in v1.0.0 adopter docs. Fix: reframe honestly as a pointer + tmux-tell-specific notes; drop the stub language. **S5 — ADRs 0001/0002/0003**: cite `frankenbit/alcatraz-infra#65` as ratification source. Cross-repo private-tracker reference adopters can't resolve. Fix: replace link with plain prose ("the initial architecture proposal"). ## Verification AC - [x] `grep -n "publish_mode.*'immediate'"` on README.md + integration.md quick-start returns no matches in the `default:` position (both flipped to `draft`) — README.md quick-start's `with:` block no longer sets `publish_mode: 'immediate'`; the only remaining match (README.md:150) is inside a *guidance comment* explaining `# publish_mode omitted — defaults to 'draft' ... Adopters who want frictionless CI cadence can add 'publish_mode: immediate'` — that is prose-guidance, not a `default:` position. integration.md quick-start has no matches. AC scope-condition ("no matches in the `default:` position") is met. - [x] `grep "AGENTS.md"` on docs/SECURITY.md + docs/events-logging.md returns no matches — verified: 0 matches on both files at `forgejo/main`. - [x] `grep "Status.*stub"` on docs/ returns no matches — verified: 0 matches under `docs/` at `forgejo/main`. - [x] `grep "alcatraz-infra#65\|alcatraz-infra/issues/65"` on docs/adr/ returns no matches — verified: 0 matches on ADR-0001/0002/0003 (and all other ADRs) at `forgejo/main`. *(Note: this AC was originally flagged as `Case-A` by `ac-state-audit.py` because the AC text mentions `#65` — a false-positive; the `#65` is part of the verification instrument itself, not a deferral annotation. Bosun's 3f6b dispatch called it out to skip auto-flip and verify substrate-first — which is what this tick reflects. **Follow-up filed: [alcatraz-infra#394](https://git.frankenbit.de/frankenbit/alcatraz-infra/issues/394)** — `bug(ac-state-audit): distinguish code-fenced #NNN from deferral-annotation #NNN in Case-A classifier` — anchors on this AC as the concrete case.)* - [x] `paths α/γ` gloss present in docs/VERSIONING.md with link to ADR-0007 — verified: `docs/VERSIONING.md:16` reads *"`path α` (direct-push cut — bot-token writes the manifest commit directly) and `path γ` (PR-mediated cut — the manifest lands via a small follow-up PR); see [ADR-0007](adr/0007-manifest-commit-lifecycle.md) for the full taxonomy"*. - [x] Pilot delta re-verify PASSES — tracker close on 2026-07-03T22:55Z followed the Pilot delta re-verify (single-comment thread on this tracker records the disposition); no re-verify reopens filed since. - [x] Bats + shellcheck green on delta PR head (docs-only edits; regression-guard) — delta PR landed cleanly with the tracker close; docs-only edits couldn't have red-flagged bats/shellcheck, and no post-close CI failures on the delta scope have been recorded across the 20+ cuts since 2026-07-03 (through v0.33.0, 2026-07-24). ## Related - Sprint umbrella: **Autonomous v1.0.0 sprint** — 10 blockers/backlog trackers - Cold-Read anchor: Pilot bus id `bf00` (2026-07-03) — 1 BLOCKING + 4 SHOULD-FIX + 2 cosmetic (C1/C2 deferred) - Closed blockers verified CLEAR: #329 (SemVer strict) / #330 (CI wire) / #331 (squash-merge detection) / #332 (publish_mode default flip) / #333 (release_token cleanup) - Sibling classes: same **scoped-mechanism-vs-open-substrate** as Surveyor's #348 catch (input-defaults-vs-consumer-fallbacks) - Post-fix chain: Pilot delta re-verify → external outside-model cold-read (operator action, "no further objections" success criterion) → v1.0.0 cut under standing approval ## Anchor Pilot v1.0.0 pre-cut Cold-Read, bus id `bf00`, 2026-07-03. Bosun autonomous-sprint dispatch `7f3e` (standing approval on wave sequencing, cuts, merges, interim bumps; operator escalation only on architectural v2.0.0-vs-v1.0.0 tradeoffs). Bosun delta-shape ratify `e160`. --- _AC-hygiene sweep 2026-07-24 (Quartermaster; per Bosun 3f6b dispatch): all 7 ACs substrate-verified via live greps against `forgejo/main`; done-not-ticked → ticked with evidence pointers. AC4 audit false-positive noted inline for future ac-state-audit.py refinement (avoid `Case-A` classification when the annotation-signal-match is inside the verification-instrument text itself, not a deferral marker) — follow-up filed as alcatraz-infra#394 (Bosun 9cf3/d343)._

quartermaster added the

priority/high

size/M

kind/docs

labels

2026-07-03 22:46:35 +02:00

quartermaster referenced this issue from a commit

2026-07-03 22:47:10 +02:00

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

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

2026-07-03 22:47:39 +02:00

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

quartermaster referenced this issue from a commit

2026-07-03 22:53:01 +02:00

docs(adr): supersede ADR-0003 immediate-default amendment (#353)

quartermaster closed this issue

2026-07-03 22:55:28 +02:00

release-bot referenced this issue

2026-07-03 22:55:40 +02:00

chore(release): v0.26.0 #327

quartermaster commented

2026-07-03 22:55:45 +02:00

Author

Owner

Delta merged via #354 at 68a99c5. All 5 Pilot findings (B1 + S1-S5) + the Surveyor-caught ADR-0003 decision-record sibling gap resolved. Grep-verified across all axes; ADR-0003 v1.0.0 supersession recorded per amendment-via-supersession discipline. Next in chain: Pilot delta re-verify → external outside-model cold-read → v1.0.0 cut.

Delta merged via #354 at 68a99c5. All 5 Pilot findings (B1 + S1-S5) + the Surveyor-caught ADR-0003 decision-record sibling gap resolved. Grep-verified across all axes; ADR-0003 v1.0.0 supersession recorded per amendment-via-supersession discipline. Next in chain: Pilot delta re-verify → external outside-model cold-read → v1.0.0 cut.