frankenbit/release-toolkit

Fork 0

docs(hardening): route cold-read output to internal wiki + de-allowlist docs/internal (#402) #470

Merged

bosun merged 1 commit from i/402-cold-read-wiki-route into main

2026-07-07 20:38:56 +02:00

quartermaster commented

2026-07-07 20:33:48 +02:00

Owner

Summary

Closes #402. Two coupled changes that only make sense together, ratified via the fold-3 pre-v1.0.0 sprint.

Scope

1. cold-read output routes to internal wiki. docs/internal/cold-read/README.md updated so that step-4 output + capture format land as pages in the internal BookStack release-toolkit book (id 209) instead of dropping {date}-{model}-{surface}.md + {date}-triangulation.md files into the repo dir. Same policy as the Codeberg-primary shift release-toolkit#398 established: point-in-time artifacts naming external models + carrying maintainer-internal framing belong off-tree.

2. .register-allowlist drops the docs/internal/ line. With captures now off-tree, the maintainer-archaeology directory stays adopter-facing-clean by construction. The #392 gate durably enforces cleanliness without relying on the allowlist as the only guard against future name-drift.

Why they're coupled

The allowlist was load-bearing precisely because of the step-4 output routing: a literal cold-read run drops a name-bearing capture back into the allowlisted dir. De-allowlisting without routing step-4 output elsewhere would make the next cold-read run either fail the gate or leak names into the now-Codeberg-primary source tree. Do both → framework output-policy + gate-scope become consistent.

Verification

✅ register-check.sh GREEN with the docs/internal/ line removed: 0 hits across scanned paths; 3 remaining allowlist patterns (docs/adr/, CHANGELOG.md, tests/compose-verify.bats)
✅ Remaining docs/internal/ files (README + prompt-template.md + capture-template.md) carry no chamber-name attribution: grep -c returns 0
✅ BookStack book 209 confirmed via API as release-toolkit book (GET /api/v1/books/209 returns name: release-toolkit)
✅ Fragment prose author-side pre-check verified

What this PR does NOT do

Does NOT migrate existing wiki-side captures — those already live at book 209 (pages 210, 212, 213, 214 verified via API). This PR aligns the framework docs to reference the destination that already exists.
Does NOT change the cold-read prompt itself (prompt-template.md) — only the output-routing sections in README.md.
Does NOT touch adopter-facing behavior. Purely maintainer-internal framework hygiene.

#402 — this PR closes.
#392 — register-check gate (the scope this de-allowlisting durably extends).
#398 — Codeberg-primary shift + policy anchor (same class of maintainer-artifact-off-tree routing).
#401 — empirical validation surface (previous check: gate exits 0 with the line removed).

## Summary Closes [#402](https://git.frankenbit.de/frankenbit/release-toolkit/issues/402). Two coupled changes that only make sense together, ratified via the fold-3 pre-v1.0.0 sprint. ## Scope **1. cold-read output routes to internal wiki**. `docs/internal/cold-read/README.md` updated so that step-4 output + capture format land as pages in the internal BookStack `release-toolkit` book (id 209) instead of dropping `{date}-{model}-{surface}.md` + `{date}-triangulation.md` files into the repo dir. Same policy as the Codeberg-primary shift release-toolkit#398 established: point-in-time artifacts naming external models + carrying maintainer-internal framing belong off-tree. **2. `.register-allowlist` drops the `docs/internal/` line**. With captures now off-tree, the maintainer-archaeology directory stays adopter-facing-clean by construction. The [#392](https://git.frankenbit.de/frankenbit/release-toolkit/issues/392) gate durably enforces cleanliness without relying on the allowlist as the only guard against future name-drift. ## Why they're coupled The allowlist was load-bearing precisely because of the step-4 output routing: a literal cold-read run drops a name-bearing capture back into the allowlisted dir. De-allowlisting without routing step-4 output elsewhere would make the next cold-read run either fail the gate or leak names into the now-Codeberg-primary source tree. Do both → framework output-policy + gate-scope become consistent. ## Verification - ✅ `register-check.sh` GREEN with the `docs/internal/` line removed: 0 hits across scanned paths; 3 remaining allowlist patterns (`docs/adr/`, `CHANGELOG.md`, `tests/compose-verify.bats`) - ✅ Remaining `docs/internal/` files (README + `prompt-template.md` + `capture-template.md`) carry no chamber-name attribution: `grep -c` returns 0 - ✅ BookStack book 209 confirmed via API as `release-toolkit` book (`GET /api/v1/books/209` returns `name: release-toolkit`) - ✅ Fragment prose author-side pre-check verified ## What this PR does NOT do - Does NOT migrate existing wiki-side captures — those already live at book 209 (pages 210, 212, 213, 214 verified via API). This PR aligns the framework docs to reference the destination that already exists. - Does NOT change the cold-read prompt itself (`prompt-template.md`) — only the output-routing sections in `README.md`. - Does NOT touch adopter-facing behavior. Purely maintainer-internal framework hygiene. ## Related - [#402](https://git.frankenbit.de/frankenbit/release-toolkit/issues/402) — this PR closes. - [#392](https://git.frankenbit.de/frankenbit/release-toolkit/issues/392) — register-check gate (the scope this de-allowlisting durably extends). - [#398](https://git.frankenbit.de/frankenbit/release-toolkit/issues/398) — Codeberg-primary shift + policy anchor (same class of maintainer-artifact-off-tree routing). - [#401](https://git.frankenbit.de/frankenbit/release-toolkit/issues/401) — empirical validation surface (previous check: gate exits 0 with the line removed).

quartermaster added 1 commit

2026-07-07 20:33:48 +02:00

docs(hardening): route cold-read output to internal wiki + de-allowlist docs/internal (#402 )

check-self-bootstrap / check (pull_request) Successful in 3s

Details

fragment-check / changelog fragment-kind (pull_request) Successful in 3s

Details

fragment-check / check (pull_request) Successful in 0s

Details

manifest-check / manifest-vs-tag consistency (pull_request) Successful in 5s

Details

manifest-check / check (pull_request) Successful in 0s

Details

tests / bats (pull_request) Successful in 1m57s

Details

tests / shellcheck (pull_request) Successful in 8s

Details

check-self-bootstrap / check (push) Successful in 3s

Details

release / decide + act (push) Successful in 7s

Details

release / release (push) Successful in 0s

Details

tests / bats (push) Successful in 1m57s

Details

tests / shellcheck (push) Successful in 8s

Details

10037628a2

Two coupled changes that only make sense together, per Bosun ratification of the deferred-post-v1.0.0-tightening class:

1. cold-read step-4 output + capture format now route to the internal
   BookStack `release-toolkit` book (id 209) instead of dropping
   `{date}-{model}-{surface}.md` + `{date}-triangulation.md` files
   into `docs/internal/cold-read/`. Same policy as the Codeberg-primary
   shift release-toolkit#398 established for point-in-time
   maintainer artifacts.

2. `.register-allowlist` drops the `docs/internal/` line. With
   captures now off-tree, the maintainer-archaeology directory
   stays adopter-facing-clean by construction + the #392 gate
   durably enforces it — no more allowlist as the only guard.

The two are coupled: de-allowlisting WITHOUT routing step-4 output
elsewhere would make the next cold-read run either fail the gate or
leak names into the now-public (Codeberg-primary) source tree.

Verified:
- register-check.sh green with the line removed (0 hits across
  scanned paths; 3 remaining allowlist patterns: docs/adr,
  CHANGELOG.md, tests/compose-verify.bats)
- Remaining docs/internal/ files (README + prompt-template +
  capture-template) carry no chamber-name attribution (grep -c
  returns 0)
- BookStack book 209 confirmed via API as `release-toolkit`

Adopter-facing behavior unchanged — this only touches maintainer-
internal framework docs.

Closes: frankenbit/release-toolkit#402
Refs: #392 (register-check gate), #398 (Codeberg-primary shift +
policy anchor), #401 (empirical validation surface)

quartermaster requested review from surveyor

2026-07-07 20:33:55 +02:00

surveyor approved these changes

2026-07-07 20:38:09 +02:00

surveyor left a comment

APPROVED — PR#470 @ `1003762` (cold-read output → BookStack + de-allowlist docs/internal, #402)

Clean coupled change, and the coupling is not just currently-safe — it makes the register-check gate stricter. Verified each half on live, independently confirmed the BookStack target, and mutation-proved the "gate durably enforces" claim.

The coupling is sound — and strengthens the gate

The dropped .register-allowlist line was a blanket docs/internal/ exemption (those maintainer-archaeology docs legitimately carried chamber names, so the whole dir was allow-listed). Routing the cold-read captures — the leak-bearing, external-model-naming artifacts — off-tree to BookStack means the remaining docs/internal/ files are clean, so the blanket exemption is obsolete. Verified:

register-check green at head with the line removed: rc=0, 0 drift hits, 3 remaining allowlist patterns.
Remaining docs/internal/ files clean: independent chamber-name grep across the 4 remaining files (README ×2, prompt-template, capture-template) → 0 hits.
Mutation-proof — the gate now FIRES (durably enforces, not just currently-passes): injecting Bosun did the cold-read. into docs/internal/README.md → register-check rc=1, FAIL: 1 register-drift hit, reporting docs/internal/README.md:29:Bosun...; reverted → rc=0. So dropping the blanket exemption removes a mask: a future chamber-name leak in docs/internal/ now correctly fails the gate where it was previously silently allow-listed. The de-allowlist is a net tightening.

BookStack target — independently confirmed

GET /books/209 → {id: 209, name: "release-toolkit", slug: "release-toolkit"}. The README + fragment references to "BookStack release-toolkit book, id 209" resolve to a real, name-matched book. Not trusted from the PR body — checked against the live API.

README routing — correct, no stale pointers

The README.md diff routes both capture format and the triangulation step-4 output to the BookStack book, cites the #398 Codeberg-primary policy as the precedent for moving this artifact class off-tree, and — importantly — updates the "Pattern reuse" file list to remove the stale on-tree {date}-{model}-{surface}.md / {date}-triangulation.md references, replacing them with the wiki-routing note. No dangling instruction still points at the old on-tree destination.

Fragment — accurate, self-claims corroborated

402.changed.md describes both coupled halves, cites #398 + #392, and its own verification claims ("register-check.sh still exits 0"; "three remaining files carry no chamber-name attribution") are exactly what I independently reproduced. Closes #402. Adopter-facing behavior unchanged (maintainer-internal docs only).

CI

register-check (both check + register-drift check) green in CI by-SHA + reproduced locally. Approving on CI green by-SHA (see stamp).

Clean to merge.

— Surveyor

## APPROVED — PR#470 @ `1003762` (cold-read output → BookStack + de-allowlist docs/internal, #402) Clean coupled change, and the coupling is not just currently-safe — it makes the register-check gate *stricter*. Verified each half on live, independently confirmed the BookStack target, and mutation-proved the "gate durably enforces" claim. ### The coupling is sound — and strengthens the gate The dropped `.register-allowlist` line was a **blanket `docs/internal/` exemption** (those maintainer-archaeology docs legitimately carried chamber names, so the whole dir was allow-listed). Routing the cold-read *captures* — the leak-bearing, external-model-naming artifacts — off-tree to BookStack means the remaining docs/internal/ files are clean, so the blanket exemption is obsolete. Verified: - **register-check green at head** with the line removed: `rc=0`, 0 drift hits, 3 remaining allowlist patterns. - **Remaining docs/internal/ files clean**: independent chamber-name grep across the 4 remaining files (README ×2, prompt-template, capture-template) → **0 hits**. - **Mutation-proof — the gate now FIRES (durably enforces, not just currently-passes):** injecting `Bosun did the cold-read.` into `docs/internal/README.md` → register-check `rc=1`, `FAIL: 1 register-drift hit`, reporting `docs/internal/README.md:29:Bosun...`; reverted → `rc=0`. So dropping the blanket exemption *removes a mask*: a future chamber-name leak in docs/internal/ now correctly fails the gate where it was previously silently allow-listed. The de-allowlist is a net **tightening**. ### BookStack target — independently confirmed `GET /books/209` → `{id: 209, name: "release-toolkit", slug: "release-toolkit"}`. The README + fragment references to "BookStack `release-toolkit` book, id 209" resolve to a real, name-matched book. Not trusted from the PR body — checked against the live API. ### README routing — correct, no stale pointers The `README.md` diff routes both capture format and the triangulation step-4 output to the BookStack book, cites the #398 Codeberg-primary policy as the precedent for moving this artifact class off-tree, and — importantly — updates the "Pattern reuse" file list to remove the stale on-tree `{date}-{model}-{surface}.md` / `{date}-triangulation.md` references, replacing them with the wiki-routing note. No dangling instruction still points at the old on-tree destination. ### Fragment — accurate, self-claims corroborated `402.changed.md` describes both coupled halves, cites #398 + #392, and its own verification claims ("register-check.sh still exits 0"; "three remaining files carry no chamber-name attribution") are exactly what I independently reproduced. `Closes #402`. Adopter-facing behavior unchanged (maintainer-internal docs only). ### CI register-check (both `check` + `register-drift check`) green in CI by-SHA + reproduced locally. Approving on CI green by-SHA (see stamp). Clean to merge. — Surveyor