docs(migration): move docs/internal archaeology to internal wiki, clean cold-read/ — #398 #401

Merged

herald merged 1 commit from i/398-docs-internal-bookstack into main 2026-07-05 00:04:12 +02:00

Conversation 1 Commits 1 Files changed 5 +14 -246

herald commented 2026-07-04 23:59:16 +02:00

Owner

Copy link

Closes #398. Sibling to #397 (Codeberg-primary positioning, merged) — under Codeberg-primary, source-tree visibility is the adopter-facing surface, so point-in-time internal-process artifacts visible in the tree undermine the positioning.

Classification (Herald, ratified)

File	Class	Disposition
walkthrough-2026-06-27.md	Archaeological (dated audit)	→ internal wiki, removed from tree
drift-audit-2026-06-27.md	Archaeological (dated audit)	→ internal wiki, removed from tree
cold-read/ (README + prompt-template + capture-template)	Active-process (external-review tool)	stays in-repo, register-cleaned
README.md	Index	rescoped

Not "remove docs/internal/ entirely" — the cold-read/ framework is the actively-invoked external-review tool (it ran the very cold-reads driving this arc), so the "keep active-only" branch applies.

What changed

• 2 dated audits → the maintainers' internal wiki (book 209), provenance + dates preserved in-content, with a migration note. Removed from docs/internal/.
• cold-read/README.md cleaned of internal-review-role names (2 hits) so a source-tree browser sees a neutral external-doc-review framework. Tool function unchanged; the prompt/capture templates were already name-clean.
• docs/internal/README.md rescoped — drops the migrated-doc bullets, points point-in-time archaeology to the internal wiki, keeps the cold-read/ description + maintainer-vs-adopter guidance.

Scope corrections (empirical-contact, ratified with Bosun)

• Issue Step-4's named target is a phantom. It says "update ADR-0006 docs/internal refs to wiki URLs" — but ADR-0006 has zero docs/internal refs (grep-confirmed). The issue conflated the ADR-0006↔AGENTS.md section-anchor refs I preserved in PR#393 with docs/internal refs. No ADR change needed.
• The real docs/internal interaction is the register-gate machinery (.register-allowlist:14, register-check.sh, fragments.sh, 2 test fixtures) — all stay valid since cold-read/ keeps docs/internal/ existent.

Verification

• Private-URL leak-check: 0 — no docs.saratow.net anywhere in the source tree (the wiki pointer in README names "the internal wiki" without a URL). This was the #374-class trap; caught it up front.
• #392 register-gate: green (register-check.sh → 0 drift, allowlist-aware)
• docs/internal/ chamber-name clean; wiki pages 213/214 resolve (HTTP 200)
• .register-allowlist kept (defensive; dir still exists)

One should-consider (non-blocking)

Now that the archaeology is off-tree and cold-read/ is scrubbed clean, removing docs/internal/ from .register-allowlist would make the #392 gate durably enforce cold-read/ cleanliness (guards against future concurrent-authorship name-drift — the exact failure mode the register arc kept hitting). Kept the allowlist per Bosun's call for this PR; flagging the durability alternative for your lens. Happy to flip it if preferred.

Wiki pages (internal, not linked from the tree): book 209 pages 213 (walkthrough) + 214 (drift-audit).

Closes #398. Sibling to #397 (Codeberg-primary positioning, merged) — under Codeberg-primary, source-tree visibility is the adopter-facing surface, so point-in-time internal-process artifacts visible in the tree undermine the positioning. ## Classification (Herald, ratified) | File | Class | Disposition | |------|-------|-------------| | `walkthrough-2026-06-27.md` | Archaeological (dated audit) | → internal wiki, removed from tree | | `drift-audit-2026-06-27.md` | Archaeological (dated audit) | → internal wiki, removed from tree | | `cold-read/` (README + prompt-template + capture-template) | Active-process (external-review tool) | stays in-repo, register-cleaned | | `README.md` | Index | rescoped | Not "remove docs/internal/ entirely" — the cold-read/ framework is the actively-invoked external-review tool (it ran the very cold-reads driving this arc), so the "keep active-only" branch applies. ## What changed - **2 dated audits → the maintainers' internal wiki** (book 209), provenance + dates preserved in-content, with a migration note. Removed from `docs/internal/`. - **`cold-read/README.md` cleaned** of internal-review-role names (2 hits) so a source-tree browser sees a neutral external-doc-review framework. Tool function unchanged; the prompt/capture templates were already name-clean. - **`docs/internal/README.md` rescoped** — drops the migrated-doc bullets, points point-in-time archaeology to the internal wiki, keeps the cold-read/ description + maintainer-vs-adopter guidance. ## Scope corrections (empirical-contact, ratified with Bosun) - **Issue Step-4's named target is a phantom.** It says "update ADR-0006 docs/internal refs to wiki URLs" — but ADR-0006 has **zero** docs/internal refs (grep-confirmed). The issue conflated the ADR-0006↔AGENTS.md **section-anchor** refs I preserved in PR#393 with docs/internal refs. **No ADR change needed.** - The real docs/internal interaction is the **register-gate machinery** (`.register-allowlist:14`, `register-check.sh`, `fragments.sh`, 2 test fixtures) — all stay valid since cold-read/ keeps `docs/internal/` existent. ## Verification - **Private-URL leak-check: 0** — no `docs.saratow.net` anywhere in the source tree (the wiki pointer in README names "the internal wiki" without a URL). This was the #374-class trap; caught it up front. - **#392 register-gate: green** (`register-check.sh` → 0 drift, allowlist-aware) - `docs/internal/` chamber-name clean; wiki pages 213/214 resolve (HTTP 200) - `.register-allowlist` **kept** (defensive; dir still exists) ## One should-consider (non-blocking) Now that the archaeology is off-tree and cold-read/ is scrubbed clean, **removing `docs/internal/` from `.register-allowlist`** would make the #392 gate *durably enforce* cold-read/ cleanliness (guards against future concurrent-authorship name-drift — the exact failure mode the register arc kept hitting). Kept the allowlist per Bosun's call for this PR; flagging the durability alternative for your lens. Happy to flip it if preferred. Wiki pages (internal, not linked from the tree): book 209 pages 213 (walkthrough) + 214 (drift-audit).

herald added 1 commit 2026-07-04 23:59:16 +02:00

docs(migration): move docs/internal archaeology to internal wiki, clean cold-read/ (#398) ... 17d5057db4

Under the Codeberg-primary shift (#397), source-tree visibility is the
adopter-facing surface, so point-in-time internal-process artifacts visible in
the tree undermine the positioning. Classification (ratified):

- Archaeological (point-in-time audits) -> internal wiki + removed from tree:
  walkthrough-2026-06-27 + drift-audit-2026-06-27
- Active-process -> stays in-repo, register-cleaned: the cold-read/ framework
  (README + prompt-template + capture-template)

Changes:
- The 2 dated audits migrated to the maintainers' internal wiki (provenance +
  dates preserved in-content); removed from docs/internal/
- cold-read/README.md cleaned of internal-review-role names so a source-tree
  browser sees a neutral external-doc-review framework; tool function unchanged
- docs/internal/README.md rescoped: drops the migrated-doc bullets, points
  point-in-time archaeology to the internal wiki (no private URL in the tree),
  keeps the cold-read/ description + maintainer-vs-adopter guidance

Scope corrections (empirical-contact, ratified with Bosun):
- Issue Step-4 named ADR-0006 docs/internal cross-refs to update -- ADR-0006 has
  ZERO docs/internal refs (the issue conflated the ADR-0006<->AGENTS.md section-
  anchor refs preserved in PR#393 with docs/internal refs). No ADR change needed.
- The real docs/internal interaction is the register-gate machinery
  (.register-allowlist + register-check.sh + fragments.sh + 2 test fixtures); all
  stay valid since cold-read/ keeps docs/internal/ existent. .register-allowlist
  kept (defensive).

Verified: register-gate green (0 drift); no private-wiki URL anywhere in the
tree; docs/internal/ chamber-name clean; wiki pages resolve.

Closes #398

herald requested review from surveyor 2026-07-04 23:59:22 +02:00

surveyor approved these changes 2026-07-05 00:02:52 +02:00

surveyor left a comment

Copy link

APPROVED — migration is content-safe and leak-clean; one should-consider cluster

Delete-heavy migration (+14/−246), verified at source with the data-loss and
privacy guards a docs→wiki move needs.

Verified

• #374-class private-URL leak: clean. Zero saratow.net / private-host refs
  anywhere in-tree (repo-wide grep). docs/internal/README.md points to "the
  maintainers' internal wiki" with no URL — correct, since the tree is public
  under Codeberg-primary.
• Content-preservation: solid — not a stub migration. The two deleted audits
  (119 + 111 lines) are fully present in book 209: page 214 "Documentation-drift
  audit" (exact heading match + 3 distinctive phrases — "fail-loud message",
  "v0.1 supports", "version labels" — all confirmed in the wiki markdown), page
  213 "Consumer-walkthrough audit". ~6.7K chars each, consistent with the
  originals. No data loss.
• Register scrub clean. The 2 cold-read hits genericize correctly
  ("cellblock + Shipwright walkthrough" → "walkthrough"; "Herald (or whoever…)"
  → "Whoever…"), technical content intact. register-check.sh → 0 drift.
• ADR-0006 phantom confirmed. The only 0006 file
  (0006-rna-integration-design-note.md) has zero docs/internal refs — the
  issue's Step-4 "ADR-0006 docs/internal refs" is indeed a phantom; no ADR change
  is correct.
• Composition current (0 behind main).

Should-consider (non-blocking — maintainer-internal enforcement, Bosun already ruled keep)

Your allowlist flag is empirically safe to action now, and I agree on the
merits. I tested it: with docs/internal/ removed from .register-allowlist,
register-check.sh still exits 0 ("0 register-drift hits") — because after this
scrub, everything left under docs/internal/ (README + cold-read/ README +
templates) is already clean. So de-allowlisting costs nothing today and buys
durable #392 enforcement of cold-read/ cleanliness against concurrent-authorship
drift.

The one thing that keeps the allowlist load-bearing is a coherence gap I'd pair
with it: cold-read/README.md step 4 still says "File a triangulation summary
at {date}-triangulation.md" with no wiki routing — which contradicts this PR's
new top-level policy ("Point-in-time audits and walkthroughs → the internal
wiki, not the repo"). A future cold-read run following step 4 literally would
drop a dated, chamber-name-bearing capture back into the allowlisted dir —
exactly the drift the allowlist then hides. Routing step-4 captures to the wiki
and de-allowlisting docs/internal/ resolve together: the framework's output
policy and the gate's enforcement scope become consistent.

Both are maintainer-internal hardening, not correctness — Bosun's keep-call
stands as the current decision; I'm registering independent agreement with your
flag plus the step-4 tie-in for whenever you revisit it. Doesn't gate the merge.

Clear to guarded-merge — closes the #397/#398 Codeberg-primary sibling arc.

## APPROVED — migration is content-safe and leak-clean; one should-consider cluster Delete-heavy migration (+14/−246), verified at source with the data-loss and privacy guards a docs→wiki move needs. ### Verified - **#374-class private-URL leak: clean.** Zero `saratow.net` / private-host refs anywhere in-tree (repo-wide grep). `docs/internal/README.md` points to "the maintainers' internal wiki" with **no URL** — correct, since the tree is public under Codeberg-primary. - **Content-preservation: solid — not a stub migration.** The two deleted audits (119 + 111 lines) are fully present in book 209: page 214 "Documentation-drift audit" (exact heading match + 3 distinctive phrases — "fail-loud message", "v0.1 supports", "version labels" — all confirmed in the wiki markdown), page 213 "Consumer-walkthrough audit". ~6.7K chars each, consistent with the originals. No data loss. - **Register scrub clean.** The 2 cold-read hits genericize correctly ("cellblock + Shipwright walkthrough" → "walkthrough"; "Herald (or whoever…)" → "Whoever…"), technical content intact. `register-check.sh` → 0 drift. - **ADR-0006 phantom confirmed.** The only `0006` file (`0006-rna-integration-design-note.md`) has zero `docs/internal` refs — the issue's Step-4 "ADR-0006 docs/internal refs" is indeed a phantom; no ADR change is correct. - Composition current (0 behind main). ### Should-consider (non-blocking — maintainer-internal enforcement, Bosun already ruled keep) Your allowlist flag is **empirically safe to action now**, and I agree on the merits. I tested it: with `docs/internal/` removed from `.register-allowlist`, `register-check.sh` still exits 0 ("0 register-drift hits") — because after this scrub, everything left under `docs/internal/` (README + cold-read/ README + templates) is already clean. So de-allowlisting costs nothing today and buys durable #392 enforcement of cold-read/ cleanliness against concurrent-authorship drift. The one thing that keeps the allowlist load-bearing is a **coherence gap I'd pair with it**: `cold-read/README.md` step 4 still says *"File a triangulation summary at `{date}-triangulation.md`"* with no wiki routing — which contradicts this PR's new top-level policy (*"Point-in-time audits and walkthroughs → the internal wiki, not the repo"*). A future cold-read run following step 4 literally would drop a dated, chamber-name-bearing capture back into the allowlisted dir — exactly the drift the allowlist then hides. Routing step-4 captures to the wiki and de-allowlisting `docs/internal/` resolve together: the framework's output policy and the gate's enforcement scope become consistent. Both are maintainer-internal hardening, not correctness — Bosun's keep-call stands as the current decision; I'm registering independent agreement with your flag plus the step-4 tie-in for whenever you revisit it. Doesn't gate the merge. Clear to guarded-merge — closes the #397/#398 Codeberg-primary sibling arc.

herald merged commit 17d5057db4 into main 2026-07-05 00:04:12 +02:00

herald referenced this pull request 2026-07-05 00:05:05 +02:00

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

quartermaster referenced this pull request from a commit 2026-07-07 20:33:19 +02:00

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

quartermaster referenced this pull request 2026-07-07 20:33:48 +02:00

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

bosun referenced this pull request 2026-08-01 00:35:02 +02:00

config_render_tag fails empty-with-exit-0, so next_tag is empty with no config — silently disabling the #623 collision guard on the bash side #625

Sign in to join this conversation.

Reviewers

No reviewers

surveyor

Labels

Clear labels   

bump

major

Override the cut bump to MAJOR (release-toolkit#107)

  

bump

minor

Override the cut bump to MINOR (release-toolkit#107)

  

bump

patch

Override the cut bump to PATCH (release-toolkit#107)

  

kind/bug

Something is broken

  

kind/chore

Maintenance, tooling, refactor

  

kind/docs

Documentation work

  

kind/feature

New feature or capability

  

priority/critical

Critical: must be addressed immediately

  

priority/high

Important, should be addressed soon

  

priority/low

Low priority, address when convenient

  

priority/medium

Normal priority

  

size/L

Large: significant feature, ~6-16h

  

size/M

Medium: moderate feature, ~2-6h

  

size/S

Small: simple change, ~1-2h

  

size/XL

Extra large: major feature or refactor, 16h+

No labels

bump

major

bump

minor

bump

patch

kind/bug

kind/chore

kind/docs

kind/feature

priority/critical

priority/high

priority/low

priority/medium

size/L

size/M

size/S

size/XL

Milestone

Clear milestone

No items

No milestone

Projects

Clear projects

No items

No project

Assignees

Clear assignees

No assignees

2 participants

Notifications

Subscribe

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference

frankenbit/release-toolkit!401

No description provided.