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

quartermaster commented

2026-06-27 01:57:26 +02:00

Owner

Why now

Pre-1.0 readiness: 10 cycles of substrate evolution this session (v0.7 → v0.11) + the v0.4.0 architectural arc earlier. Docs may have drifted out of sync with the current substrate; one deliberate audit catches the drift before 1.0 locks in expectations.

Audit surfaces

integration.md vs code

Line-by-line review:

Each documented step against the actual workflow + script behavior
Each documented input/output against the workflow_call schema
Each documented config key against the config.sh parser
Each example command against the actual CLI

Known suspected drift sites:

publish_mode default flip (v0.10.0 — flipped draft→immediate); does integration.md fully reflect the post-flip default?
bump_override semantics post-#107 label-based bump-control (slash namespace, exclusive labels) — does integration.md describe the label mechanism?
ADR-0007 path-α/path-γ split — is the docs framing aligned with the empirical cellblock adoption findings?
Forgejo-specific quirks (secrets: inherit per #135; paths-ignore per #139; default_merge_style per #154)
Idempotency mechanism (#128/#140) — documented? In what depth?
Self-bootstrap re-pin discipline (AGENTS.md §2) — surfaced to integration.md or only in AGENTS.md?

ADRs vs current substrate

Each ADR (0001 through 0007) cross-referenced against current code:

ADR-0001 (language=shell) — still aligned
ADR-0002 (conventional commits) — aligned
ADR-0003 (multi-stage operator gate) — post-publish_mode-flip, the gate-3 framing changed; verify the ADR captures the v0.10.0+ default
ADR-0004 (reusable workflow architecture) — affected by #148 build-bake if it ships; verify currency
ADR-0005 (substrate-honest terminology) — meta-ADR; verify it still describes the convention in use
ADR-0006 (350-line cap + bg-doc convention) — verify the line caps + bg-doc files
ADR-0007 (manifest commit lifecycle) — empirically validated via cellblock; verify the ADR matches the lived experience

Each drift: AMEND the ADR with a "post-v0.X.Y" note OR file a follow-up tracker for substantive realignment.

README vs current substrate

Feature list accuracy (release_types, configuration, etc.)
Quick-start works as described
Links resolve

Inline code comments

Critical comments to verify:

_release.yml step-by-step comments vs actual step behavior
release-prep.sh documentation comments at function-top
release-decide.sh decision-tree comments
manifest-precheck.sh partial-completion-matrix comment (Surveyor 4a44 design point — does the code still embody this?)
AGENTS.md §2 mechanism-of-touch — verify the compose-scripts list (per #124/#147) matches the structural backstop's hardcoded list

Composition

#156 security audit: parallel. Security audit reads code-as-truth; docs-drift reads docs-vs-code. Complementary; might surface the same gaps from different angles.
#157 walkthrough audit: complementary. Walkthrough finds lived-experience gaps; this audit finds silent code-vs-docs drift.
#148 build-bake refactor: if #148 ships first, ADR-0004 needs amendment as part of THAT PR; the audit then verifies. If #148 deferred, the audit just notes the current state.
#155 workflow naming: same — if naming changes, multiple docs need updating in that PR; audit verifies post-change.

Output

docs/drift-audit-2026-06-XX.md capturing each finding
For each substantive drift: either an inline doc fix (small) OR a follow-up tracker (substantive)
ADR amendments as appropriate

Implementation surface

Audit-only:

Surveyor or fresh-eyes reviewer reads each doc against each code section
Drift instances logged
Small drifts: fix-in-place
Substantive drifts: tracker-each + remediate in follow-up PRs

Estimated scope: 4-6 hours of focused work + however many follow-up trackers materialize.

What this PR does NOT do

Does NOT rewrite docs from scratch — surgical drift fixes only
Does NOT change the underlying substrate — captures the lived state; substrate decisions are post-audit
Does NOT cover code-quality / readability concerns — that's a different audit; this is code-vs-docs alignment only

Refs

Operator engagement 2026-06-27: triple-audit suite recommendation accepted
Composition: #156 security, #157 walkthrough, #148 build-bake, #155 workflow naming
Empirical drift surfaces: post-publish_mode flip, post-bump_override-via-labels, post-cellblock-adoption findings

## Why now Pre-1.0 readiness: 10 cycles of substrate evolution this session (v0.7 → v0.11) + the v0.4.0 architectural arc earlier. Docs may have drifted out of sync with the current substrate; one deliberate audit catches the drift before 1.0 locks in expectations. ## Audit surfaces ### integration.md vs code Line-by-line review: - Each documented step against the actual workflow + script behavior - Each documented input/output against the workflow_call schema - Each documented config key against the config.sh parser - Each example command against the actual CLI Known suspected drift sites: - `publish_mode` default flip (v0.10.0 — flipped draft→immediate); does integration.md fully reflect the post-flip default? - `bump_override` semantics post-`#107` label-based bump-control (slash namespace, exclusive labels) — does integration.md describe the label mechanism? - ADR-0007 path-α/path-γ split — is the docs framing aligned with the empirical cellblock adoption findings? - Forgejo-specific quirks (`secrets: inherit` per [#135](https://git.frankenbit.de/frankenbit/release-toolkit/issues/135); paths-ignore per [#139](https://git.frankenbit.de/frankenbit/release-toolkit/issues/139); `default_merge_style` per [#154](https://git.frankenbit.de/frankenbit/release-toolkit/issues/154)) - Idempotency mechanism (#128/#140) — documented? In what depth? - Self-bootstrap re-pin discipline (AGENTS.md §2) — surfaced to integration.md or only in AGENTS.md? ### ADRs vs current substrate Each ADR (0001 through 0007) cross-referenced against current code: - ADR-0001 (language=shell) — still aligned - ADR-0002 (conventional commits) — aligned - ADR-0003 (multi-stage operator gate) — post-publish_mode-flip, the gate-3 framing changed; verify the ADR captures the v0.10.0+ default - ADR-0004 (reusable workflow architecture) — affected by #148 build-bake if it ships; verify currency - ADR-0005 (substrate-honest terminology) — meta-ADR; verify it still describes the convention in use - ADR-0006 (350-line cap + bg-doc convention) — verify the line caps + bg-doc files - ADR-0007 (manifest commit lifecycle) — empirically validated via cellblock; verify the ADR matches the lived experience Each drift: AMEND the ADR with a "post-v0.X.Y" note OR file a follow-up tracker for substantive realignment. ### README vs current substrate - Feature list accuracy (release_types, configuration, etc.) - Quick-start works as described - Links resolve ### Inline code comments Critical comments to verify: - `_release.yml` step-by-step comments vs actual step behavior - `release-prep.sh` documentation comments at function-top - `release-decide.sh` decision-tree comments - `manifest-precheck.sh` partial-completion-matrix comment (Surveyor 4a44 design point — does the code still embody this?) - AGENTS.md §2 mechanism-of-touch — verify the compose-scripts list (per [#124](https://git.frankenbit.de/frankenbit/release-toolkit/issues/124)/[#147](https://git.frankenbit.de/frankenbit/release-toolkit/issues/147)) matches the structural backstop's hardcoded list ## Composition - **[#156 security audit](https://git.frankenbit.de/frankenbit/release-toolkit/issues/156)**: parallel. Security audit reads code-as-truth; docs-drift reads docs-vs-code. Complementary; might surface the same gaps from different angles. - **[#157 walkthrough audit](https://git.frankenbit.de/frankenbit/release-toolkit/issues/157)**: complementary. Walkthrough finds lived-experience gaps; this audit finds silent code-vs-docs drift. - **#148 build-bake refactor**: if #148 ships first, ADR-0004 needs amendment as part of THAT PR; the audit then verifies. If #148 deferred, the audit just notes the current state. - **#155 workflow naming**: same — if naming changes, multiple docs need updating in that PR; audit verifies post-change. ## Output - `docs/drift-audit-2026-06-XX.md` capturing each finding - For each substantive drift: either an inline doc fix (small) OR a follow-up tracker (substantive) - ADR amendments as appropriate ## Implementation surface Audit-only: - Surveyor or fresh-eyes reviewer reads each doc against each code section - Drift instances logged - Small drifts: fix-in-place - Substantive drifts: tracker-each + remediate in follow-up PRs Estimated scope: 4-6 hours of focused work + however many follow-up trackers materialize. ## What this PR does NOT do - **Does NOT rewrite docs from scratch** — surgical drift fixes only - **Does NOT change the underlying substrate** — captures the lived state; substrate decisions are post-audit - **Does NOT cover code-quality / readability concerns** — that's a different audit; this is code-vs-docs alignment only ## Refs - **Operator engagement 2026-06-27**: triple-audit suite recommendation accepted - **Composition**: [#156 security](https://git.frankenbit.de/frankenbit/release-toolkit/issues/156), [#157 walkthrough](https://git.frankenbit.de/frankenbit/release-toolkit/issues/157), [#148 build-bake](https://git.frankenbit.de/frankenbit/release-toolkit/issues/148), [#155 workflow naming](https://git.frankenbit.de/frankenbit/release-toolkit/issues/155) - **Empirical drift surfaces**: post-`publish_mode` flip, post-`bump_override`-via-labels, post-cellblock-adoption findings

quartermaster referenced this issue

2026-06-27 02:05:47 +02:00

audit: cold-read of README.md + other adopter-facing markdown (skeptical-outsider lens) #160

quartermaster referenced this issue

2026-06-27 02:24:30 +02:00

chore(cleanup): ASCII-only sweep + .keep audit (closes #149 + #150 + #151) #161

quartermaster self-assigned this

2026-06-27 12:08:11 +02:00

quartermaster referenced this issue

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

docs: refresh README + integration.md to v0.13.0 + add Phase-2-deprecation caveat (Sprint 5 docs-drift findings) #182

quartermaster referenced this issue from a commit

2026-06-27 12:13:19 +02:00

docs: refresh README + integration.md to v0.13.0 (closes #182)

quartermaster referenced this issue

2026-06-27 12:13:37 +02:00

docs: refresh README + integration.md to v0.13.0 (closes #182) #183

quartermaster referenced this issue from a commit

2026-06-27 12:18:00 +02:00

docs: refresh README + integration.md to v0.13.0 (closes #182)

quartermaster referenced this issue

2026-06-27 15:29:40 +02:00

chore: create kind/priority/size label taxonomy (consistency with cellblock/alcatraz-infra) #201

quartermaster added the

priority/medium

size/M

labels

2026-06-27 16:14:47 +02:00

quartermaster referenced this issue

2026-06-27 16:14:53 +02:00

chore: create kind/priority/size label taxonomy (consistency with cellblock/alcatraz-infra) #201

quartermaster removed their assignment

2026-06-27 16:23:14 +02:00

surveyor was assigned by quartermaster

2026-06-27 16:23:14 +02:00

quartermaster referenced this issue

2026-06-27 17:18:06 +02:00

docs(cold-read): substrate for skeptical-outsider cold-read audits (substrate-prep #160) #211

surveyor referenced this issue

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

release_type python/multi validate as config but version-file extraction is VERSION + package.json only #213

surveyor referenced this issue

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

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

surveyor referenced this issue

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

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

surveyor referenced this issue

2026-06-27 17:49:47 +02:00

Surveyor-authored PRs hit two maintainer-gates (workflow-run approval + review approval) #218

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 commented

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

Author

Owner

Closing — Surveyor completed the docs-drift audit, ADR amendments + inline-comment fixes shipped via #220 (merged 2026-06-27 at 9052eb37, byte-identical-via-rebase of the AGit-flow PR #217), audit-doc landed at docs/drift-audit-2026-06-27.md. The audit-pass itself is done; deferred items (int-1/2/3 integration.md fixes) wait on #212-merge to apply against the post-Herald-polish structure.

Sibling open: #213 (python/multi half-support, code-side), #215 (ADR-0008 consideration), #218 (approver-gate class — durable fix Surveyor surfaced via the audit-PR mechanic friction).

Closing — Surveyor completed the docs-drift audit, ADR amendments + inline-comment fixes shipped via #220 (merged 2026-06-27 at 9052eb37, byte-identical-via-rebase of the AGit-flow PR #217), audit-doc landed at `docs/drift-audit-2026-06-27.md`. The audit-pass itself is done; deferred items (int-1/2/3 integration.md fixes) wait on #212-merge to apply against the post-Herald-polish structure. Sibling open: #213 (python/multi half-support, code-side), #215 (ADR-0008 consideration), #218 (approver-gate class — durable fix Surveyor surfaced via the audit-PR mechanic friction).

quartermaster closed this issue

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

quartermaster referenced this issue

2026-06-28 10:33:04 +02:00

chore(release): v0.16.0 #225

quartermaster referenced this issue

2026-06-28 13:22:03 +02:00

docs: integration.md structural polish bundle (#199 M2/M4-M8 + L1 placeholder nit) #210

surveyor referenced this issue

2026-06-28 13:24:24 +02:00

docs(integration): fix int-1/2/3 doc-drift from #158 audit #228

quartermaster referenced this issue from a commit