docs(migration): move archaeological docs/internal contents to BookStack + update cross-refs #398

New issue

Closed

opened 2026-07-04 23:33:00 +02:00 by bosun · 0 comments

bosun commented

2026-07-04 23:33:00 +02:00

Owner

Empirical finding

Herald's #391 read-path framing established: docs/internal/ is out-of-read-path chamber-workflow archaeology. External contributor read-path is README → CONTRIBUTING → AGENTS.md; docs/internal/ sits outside it.

But release-toolkit shifts to Codeberg-primary (see companion tracker T-A). An external cold-reader on Codeberg-primary CAN navigate into docs/internal/ via source-tree exploration, even though it's not adopter-facing by read-path. Reader sees chamber-workflow archaeology → 'AI weirdness dampening perceived project quality' (round-4 external classifier).

Operator ratified 2026-07-04: move archaeological docs to BookStack (docs.saratow.net); keep active-process docs in-repo if any survive; keep Forgejo project description as internal pointer surface.

Blocking rationale

Codeberg-primary shift means source-tree visibility IS the adopter-facing surface. Chamber-workflow archaeology visible in the Codeberg-primary source tree undermines the Codeberg-primary positioning declared in T-A. Both trackers together close the ambiguity + hide the archaeology.

Scope

Step 1 — Herald classifies docs/internal/ contents:

Archaeological (walkthroughs, dated observations, retrospective docs): reference-only, no active read-path — migrate to BookStack
Active-process (cold-read framework docs invoked when we run external reviews): current use, may need to stay in-repo or migrate depending on invocation pattern

Current docs/internal/ contents (per Herald's PR#393 §10 scope): walkthrough-2026-06-27 + cold-read/README (as of 2026-07-04).

Step 2 — Migrate archaeological to BookStack:

Create pages under release-toolkit book on docs.saratow.net (book 209)
Preserve authorship, dates, cross-refs
Cross-references from ADR files (docs/adr/*.md) update to BookStack URLs

Step 3 — Reduce or remove docs/internal/:

If all archaeological: remove docs/internal/ entirely, replace with note in README
If some active: keep active-only, README callout scoping remaining content

Step 4 — Cross-ref sweep:

ADR-0006 (Herald preserved refs in §10 trim per PR#393) — update to BookStack URLs
Any other file referencing docs/internal/ — update

Verification AC

Herald's classification of docs/internal/ contents documented in PR body
Archaeological content lives in BookStack, cross-refs functional
docs/internal/ either removed or scoped to active-process only
ADR cross-refs resolve (no dangling links)
External cold-read round 5: source-tree exploration on Codeberg finds no chamber-workflow archaeology
Register grep-gate (#392, PR#395 merged) still green — no new residual leakage

Blocked-on: Herald content classification (docs/internal/ archaeological vs active-process)
Depends-on-succeeds: T-A (Codeberg-primary positioning) — architectural framing
Sibling: T-C (Forgejo description as pointer surface)
Fed by: Herald's read-path framing (PR#393 §10 discussion)
Substrate-verified 2026-07-04: Forgejo push-mirror doesn't sync repo metadata → Forgejo description can hold internal pointers

Anchor

Operator-ratified Codeberg-primary architectural shift 2026-07-04, following round-4 external cold-read positioning ambiguity finding (round-4 external named 4 conflated positioning claims: Forgejo-native / Gitea-compatible / Codeberg-hosted / mirror-releases). Herald's post-#393 read-path framing (external contributor: README → CONTRIBUTING → AGENTS.md; docs/internal is out-of-read-path archaeology) established the boundary. Substrate claim verified 2026-07-04: Forgejo push-mirror to codeberg.org is git-only (git protocol cannot push repo metadata), so Forgejo project description safe as internal-only pointer surface.

BLOCKING v1.0.0. Herald-shaped (prose-craft + cross-ref discipline).

## Empirical finding Herald's #391 read-path framing established: docs/internal/ is out-of-read-path chamber-workflow archaeology. External contributor read-path is README → CONTRIBUTING → AGENTS.md; docs/internal/ sits outside it. But release-toolkit shifts to Codeberg-primary (see companion tracker T-A). An external cold-reader on Codeberg-primary CAN navigate into docs/internal/ via source-tree exploration, even though it's not adopter-facing by read-path. Reader sees chamber-workflow archaeology → 'AI weirdness dampening perceived project quality' (round-4 external classifier). Operator ratified 2026-07-04: move archaeological docs to BookStack (docs.saratow.net); keep active-process docs in-repo if any survive; keep Forgejo project description as internal pointer surface. ## Blocking rationale Codeberg-primary shift means source-tree visibility IS the adopter-facing surface. Chamber-workflow archaeology visible in the Codeberg-primary source tree undermines the Codeberg-primary positioning declared in T-A. Both trackers together close the ambiguity + hide the archaeology. ## Scope **Step 1 — Herald classifies docs/internal/ contents**: - **Archaeological** (walkthroughs, dated observations, retrospective docs): reference-only, no active read-path — migrate to BookStack - **Active-process** (cold-read framework docs invoked when we run external reviews): current use, may need to stay in-repo or migrate depending on invocation pattern Current docs/internal/ contents (per Herald's PR#393 §10 scope): walkthrough-2026-06-27 + cold-read/README (as of 2026-07-04). **Step 2 — Migrate archaeological to BookStack**: - Create pages under release-toolkit book on docs.saratow.net (book 209) - Preserve authorship, dates, cross-refs - Cross-references from ADR files (docs/adr/*.md) update to BookStack URLs **Step 3 — Reduce or remove docs/internal/**: - If all archaeological: remove docs/internal/ entirely, replace with note in README - If some active: keep active-only, README callout scoping remaining content **Step 4 — Cross-ref sweep**: - ADR-0006 (Herald preserved refs in §10 trim per PR#393) — update to BookStack URLs - Any other file referencing docs/internal/ — update ## Verification AC - Herald's classification of docs/internal/ contents documented in PR body - Archaeological content lives in BookStack, cross-refs functional - docs/internal/ either removed or scoped to active-process only - ADR cross-refs resolve (no dangling links) - External cold-read round 5: source-tree exploration on Codeberg finds no chamber-workflow archaeology - Register grep-gate (#392, PR#395 merged) still green — no new residual leakage ## Related - Blocked-on: Herald content classification (docs/internal/ archaeological vs active-process) - Depends-on-succeeds: T-A (Codeberg-primary positioning) — architectural framing - Sibling: T-C (Forgejo description as pointer surface) - Fed by: Herald's read-path framing (PR#393 §10 discussion) - Substrate-verified 2026-07-04: Forgejo push-mirror doesn't sync repo metadata → Forgejo description can hold internal pointers ## Anchor Operator-ratified Codeberg-primary architectural shift 2026-07-04, following round-4 external cold-read positioning ambiguity finding (round-4 external named 4 conflated positioning claims: Forgejo-native / Gitea-compatible / Codeberg-hosted / mirror-releases). Herald's post-#393 read-path framing (external contributor: README → CONTRIBUTING → AGENTS.md; docs/internal is out-of-read-path archaeology) established the boundary. Substrate claim verified 2026-07-04: Forgejo push-mirror to codeberg.org is git-only (git protocol cannot push repo metadata), so Forgejo project description safe as internal-only pointer surface. BLOCKING v1.0.0. Herald-shaped (prose-craft + cross-ref discipline).

bosun added the

priority/high

size/M

kind/docs

labels

2026-07-04 23:33:00 +02:00