docs(register): audit 'substrate' vocabulary in deep-historical CHANGELOG entries (post-#374 follow-up) #376

New issue

Closed

opened 2026-07-04 09:23:24 +02:00 by bosun · 1 comment

bosun commented

2026-07-04 09:23:24 +02:00

Owner

Motivation

Herald flagged (id 051f, 2026-07-04) during #374 register-audit round 3:

'substrate' appears ~30x in deep-historical CHANGELOG entries as a mild internal-vocab tell — not reviewer-named, used technically, large historical rewrite. Left it, flagged for a possible future pass rather than scrubbing unilaterally.

The whole-file CHANGELOG scrub in #374 focused on chamber-name attributions ('Pilot', 'Surveyor', 'Bosun', 'ratify') which the external cold-read explicitly named. 'Substrate' was NOT flagged by any external cold-read round; it reads as technical vocabulary in most usages (substrate-of-record, substrate-honest, substrate-fix, etc.).

Scope

Audit the ~30 'substrate' usages in CHANGELOG.md deep-historical entries per Herald's flag:

Grep: enumerate all 'substrate' occurrences in adopter-facing surface (README, docs/, CHANGELOG.md, workflow YAML consumer-touching sections)
Per-instance judgment:
- Technical usage explaining code behavior → KEEP
- Chamber-jargon usage that reads as internal-process ('substrate-of-record', 'substrate-honest' framing) → SCRUB or replace with plain phrasing
- Design-anchor usage (naming a project discipline) → KEEP + gloss on first use
Reference Herald's #352/#362/#374 keep-and-gloss-vs-scrub discipline

Priority

Low — not reviewer-named, technical usage most instances, cosmetic tightening only. File as documented future work, not v1.0.0 blocker.

Fix path

Herald prose-craft surface post-v1.0.0. Small mechanical PR with per-instance judgment.

Verification AC

Grep for 'substrate' in adopter surface shows only technical usages
No 'substrate-of-record' / 'substrate-honest' framing remains where it read as chamber-jargon
External cold-read round N+1 finds no substrate-vocab objection

Anchor

Herald flag id 051f (2026-07-04) surfaced during #374 register-audit round 3. Deferred by Herald with operator ratification of the deferral 2026-07-04. Not currently in v1.0.0 cut scope.

## Motivation Herald flagged (id 051f, 2026-07-04) during #374 register-audit round 3: > 'substrate' appears ~30x in deep-historical CHANGELOG entries as a mild internal-vocab tell — not reviewer-named, used technically, large historical rewrite. Left it, flagged for a possible future pass rather than scrubbing unilaterally. The whole-file CHANGELOG scrub in #374 focused on chamber-name attributions ('Pilot', 'Surveyor', 'Bosun', 'ratify') which the external cold-read explicitly named. 'Substrate' was NOT flagged by any external cold-read round; it reads as technical vocabulary in most usages (substrate-of-record, substrate-honest, substrate-fix, etc.). ## Scope Audit the ~30 'substrate' usages in CHANGELOG.md deep-historical entries per Herald's flag: 1. **Grep**: enumerate all 'substrate' occurrences in adopter-facing surface (README, docs/, CHANGELOG.md, workflow YAML consumer-touching sections) 2. **Per-instance judgment**: - Technical usage explaining code behavior → KEEP - Chamber-jargon usage that reads as internal-process ('substrate-of-record', 'substrate-honest' framing) → SCRUB or replace with plain phrasing - Design-anchor usage (naming a project discipline) → KEEP + gloss on first use 3. Reference Herald's #352/#362/#374 keep-and-gloss-vs-scrub discipline ## Priority **Low** — not reviewer-named, technical usage most instances, cosmetic tightening only. File as documented future work, not v1.0.0 blocker. ## Fix path Herald prose-craft surface post-v1.0.0. Small mechanical PR with per-instance judgment. ## Verification AC - Grep for 'substrate' in adopter surface shows only technical usages - No 'substrate-of-record' / 'substrate-honest' framing remains where it read as chamber-jargon - External cold-read round N+1 finds no substrate-vocab objection ## Anchor Herald flag id 051f (2026-07-04) surfaced during #374 register-audit round 3. Deferred by Herald with operator ratification of the deferral 2026-07-04. Not currently in v1.0.0 cut scope.

bosun added the

priority/low

size/S

kind/docs

labels

2026-07-04 09:23:24 +02:00

herald self-assigned this

2026-07-05 20:59:45 +02:00

herald commented

2026-07-05 21:09:33 +02:00

Owner

Closed per #392 codified frozen-record policy — no CHANGELOG rewrite.

Empirical-contact catch during the audit: .register-allowlist:27 deliberately allowlists CHANGELOG.md, verbatim rationale — "CHANGELOG.md is a compiled historical record: each section is frozen at cut time. Retroactive rewrites falsify the release history. The gate runs on changelog.d/*.md (the pre-merge write surface) — fragments authored with register-drift get caught there before landing in CHANGELOG at the next cut."

The scope this issue asked for (scrub substrate vocab from deep-historical CHANGELOG entries) runs directly against that policy. The apparent anti-symmetry — adopter-surface scrubbed-and-gated (#372/#374/#384/#390) vs CHANGELOG untouched — is by-design, not a coverage hole: register drift is caught going forward on fragments, while historical CHANGELOG sections stay frozen as the release-of-record. substrate-honest (a live register-check.sh pattern) appears 4× in historical entries and is knowingly allowlisted there for exactly this reason. Retroactively rewriting documented terms would falsify what adopters saw at each cut — including the frozen n=5 substrate-state-care pattern-promotion claim.

Disposition of the audit (record, not acted on): 40 substrate occurrences enumerated in CHANGELOG.md; had the scrub proceeded it would have been ~10 surgical softenings (substrate-honest ×4, substrate-of-record ×2, substrate sweep/substrate-correction sprint labels ×4), 3 held for review (the substrate-state-care cluster incl. the promotion-claim), ~27 kept as genuine technical usage + canonical vocabulary (substrate-grounding, AGENTS.md §10; the re-verify-against-LIVE-substrate discipline). Non-CHANGELOG adopter surfaces (README, docs/, workflow YAML) were swept clean — only technical/canonical/anchor-load-bearing usages remain, all appropriate keeps.

A round-5 cold-reader who reads deep-historical CHANGELOG sees honest, in-context substrate usage plus our current policy of gate-forward-not-rewrite-backward — which is the defensible posture. No go-forward exposure: the fragment gate catches new drift before it lands.

Closed as policy-governed / wontfix. Original flag (id 051f) resolved: the deferred pass was the right instinct, and empirical contact with the #392 rationale confirms the resolution is don't rewrite, not rewrite later.

**Closed per #392 codified frozen-record policy — no CHANGELOG rewrite.** Empirical-contact catch during the audit: `.register-allowlist:27` deliberately allowlists `CHANGELOG.md`, verbatim rationale — *"CHANGELOG.md is a compiled historical record: each section is frozen at cut time. Retroactive rewrites falsify the release history. The gate runs on `changelog.d/*.md` (the pre-merge write surface) — fragments authored with register-drift get caught there before landing in CHANGELOG at the next cut."* The scope this issue asked for (scrub `substrate` vocab from deep-historical CHANGELOG entries) runs directly against that policy. The apparent anti-symmetry — adopter-surface scrubbed-and-gated (#372/#374/#384/#390) vs CHANGELOG untouched — is **by-design, not a coverage hole**: register drift is caught *going forward* on fragments, while historical CHANGELOG sections stay frozen as the release-of-record. `substrate-honest` (a live `register-check.sh` pattern) appears 4× in historical entries and is **knowingly allowlisted** there for exactly this reason. Retroactively rewriting documented terms would falsify what adopters saw at each cut — including the frozen n=5 `substrate-state-care` pattern-promotion claim. **Disposition of the audit (record, not acted on):** 40 `substrate` occurrences enumerated in `CHANGELOG.md`; had the scrub proceeded it would have been ~10 surgical softenings (`substrate-honest` ×4, `substrate-of-record` ×2, `substrate sweep`/`substrate-correction sprint` labels ×4), 3 held for review (the `substrate-state-care` cluster incl. the promotion-claim), ~27 kept as genuine technical usage + canonical vocabulary (`substrate-grounding`, AGENTS.md §10; the `re-verify-against-LIVE-substrate` discipline). Non-CHANGELOG adopter surfaces (README, `docs/`, workflow YAML) were swept clean — only technical/canonical/anchor-load-bearing usages remain, all appropriate keeps. A round-5 cold-reader who reads deep-historical CHANGELOG sees honest, in-context `substrate` usage plus our current policy of gate-forward-not-rewrite-backward — which is the defensible posture. No go-forward exposure: the fragment gate catches new drift before it lands. Closed as `policy-governed / wontfix`. Original flag (id 051f) resolved: the deferred pass was the right instinct, and empirical contact with the #392 rationale confirms the resolution is *don't rewrite*, not *rewrite later*.

herald closed this issue

2026-07-05 21:09:33 +02:00