docs: prune docs/ to guides, deployment, records, assets (#1357)

[radandevist]

Closes #1357

What this does

Prunes docs/ to exactly four directories and wires a repo-wide dead-link guard so the prune is provably safe:

docs/
├── guides/       standing rules AGENTS.md links (maintained)
├── deployment/   production operations (separate by owner decision 2026-08-25)
├── records/      dated, write-once evidence, YYYY-MM-DD-<type>-<topic>.md
└── assets/

Inventory method

The move/delete decision is mechanical and reproducible: a committed script (packages/scripts-ts/src/audit-docs-prune.ts, commit 1) scans every file outside the four target directories, resolves who references it among the survival surfaces (AGENTS.md, DESIGN.md, docs/guides, docs/deployment, apps/, packages/, .github, the justfile — deliberately NOT docs/README.md indexes or the retired archive-guard manifest), and emits the inventory committed as evidence at docs/records/2026-08-25-audit-docs-prune.md.

The inventory carries two independent freshness controls:

1. Byte equality: audit-docs-prune.ts --check regenerates the record from the merge-base tree and exits non-zero if the committed copy differs byte-for-byte. Enforced twice — in the required docs-archive-gate CI job and locally in recipe ci-doc-links (manifest reconciled through just ci-drift). Paired proof: editing one row of the record makes --check exit 1 naming the file; reverting restores exit 0.
2. Git fidelity (added in round 2): before the byte comparison, --check cross-validates every rendered row against git diff -M --name-status <merge-base>..HEAD. Git's rename detection is an INDEPENDENT source of truth for what actually moved, so a decision-table omission — a real rename left unmapped, hence rendered as a deletion — now fails loudly instead of regenerating identically-wrong evidence. This closes the structural blind spot of control 1 alone: regenerating from the same wrong table matches byte-for-byte and proves nothing.

Moved vs deleted

93 candidate files: 11 moved to docs/records/, 1 kept in place, 81 deleted (counts after merging origin/develop — see below).

• Moved (11): ten survivors each referenced by at least one survival surface, plus two deliberate exceptions documented below; every survivor got a canonical dated record name, e.g. docs/implementation-plans/identity-scoped-tenant-cookie.md → docs/records/2026-01-31-plan-identity-scoped-tenant-cookie.md, and every link to it was rewritten repo-wide (AGENTS.md, DESIGN.md, guides, app code comments).
• Kept in place (1): docs/README.md itself, rewritten as the one-page filing index.
• Deleted (81): everything unreferenced — all of docs/archive/ (history lives in git and the old-front-final tag), plus superpowers/, reviews/, front-migration/, implementation-plans/, spikes/, roadmaps/, misc/, audits/, and one orphan under analysis/. No content edits beyond link rewrites on survivors.

Correction to the first version of this description: it said 9 moved / 82 deleted. That under-counted by exactly one file — docs/superpowers/specs/2026-08-25-paid-modules-design.md. Git shows it as an R100 rename to docs/records/2026-08-25-spec-open-core-paid-modules.md, but the generator's hand-kept MOVES table omitted it, so the committed inventory rendered it as a deletion and byte-equality --check reproduced the same wrong answer. Round-2 review caught it; the fix is under "Round 2 fix" below.

Honest provenance for the exception: no survival surface references the paid-modules spec. It is preserved because #1355 merged it into develop while this lane was in flight, and the lane deliberately keeps work develop already merged rather than deleting it in the prune. Its record name carries -open-core- through an explicit topic: override in the decision table (deriveTopic() alone would yield paid-modules, which is not the name that landed). The committed inventory's Notes section states this plainly.

Mid-flight merges, handled explicitly: develop merged #1355 while this lane branched (adding the paid-modules spec back under a directory this lane deletes) and later #1385 (adding the bulk-actions spec, docs/superpowers/specs/2026-08-25-820-bulk-actions-design.md). This branch merged origin/develop (merge b068baa). The #820 spec follows the same precedent as paid-modules — no survival surface references it either, and it is preserved deliberately, landing at docs/records/2026-08-25-spec-820-bulk-actions.md. Develop also MODIFIED the already-pruned DLQ triage design (docs/analysis/2026-08-24-dlq-unclassified-triage-design.md); it stays deleted per the mechanical rule (unreferenced by any survival surface, history preserved in git). With develop as ancestor, the regenerated inventory lists both mid-flight specs as their own rows (93 candidates total); both --check controls pin the committed record to that regeneration AND to what git actually renamed.

Round 2 fix

Adversarial review round 2 returned two MAJOR findings; both fixed with RED→GREEN proof:

1. Miscounted inventory: a real rename classified as a delete (finding 1). The fidelity gate is new code (listGitDocRenames + assertGitFidelity wired into --check ahead of the byte comparison).

   • RED (against the old committed inventory and the unmapped table), captured as produced in .dump/red-transcript-r2.txt:

     $ node packages/scripts-ts/src/audit-docs-prune.ts --check
     (old inventory still committed: 92 candidates — 9 moved / 1 kept / 82 deleted; MOVES table omits paid-modules)
     Inventory disagrees with git diff -M (f2811483ae335c2a76dceccc61f7e5c6f64651aa..HEAD) on 1 row(s):
       - docs/superpowers/specs/2026-08-25-paid-modules-design.md: git records a rename to docs/records/2026-08-25-spec-open-core-paid-modules.md, but the inventory classifies it as "delete".
     exit=1
     

   • GREEN: the MOVES table gained the paid-modules row with its explicit topic, the inventory regenerated to the true counts (then 10 moved / 81 deleted / 1 kept), and --check exits 0 on the committed tip. Fix commit: 7bbf128.

   • Live proof on real data: when this lane later merged origin/develop, the SAME gate flagged a REAL destination mismatch on the newly arrived #820: restore bulk management actions in the staff-users selection mode #1385 spec before any wrong evidence could be committed — the mapping named …-spec-820-bulk-actions.md while the merge auto-planted …-820-bulk-actions-design.md. Renaming the planted file to the canonical name turned the gate green (c0a507c).

2. False provenance claim (finding 2). The previous description said paid-modules survives because surfaces reference it. Nothing does. Corrected here and in the inventory Notes: the preservation reason is the mid-flight docs(specs): open-core paid modules design #1355 merge, stated without embellishment.

A regression suite pins the gate end-to-end: packages/scripts-ts/src/audit-docs-prune.test.ts (commit 7b8ce98) runs the REAL generator inside throwaway git repositories across four fixtures — (1) RED replay: rename recorded as delete fails --check naming the row; (2) a correctly mapped move passes both controls; (3) inverse lie: an inventory claiming a move git does not show fails; (4) a destination mismatch between mapping and git's rename target fails. All four pass on the committed tip.

Local gates re-run before this update: full scripts-ts vitest suite (pre-merge run: 27 files, 689 passed | 2 skipped; re-run green after the develop merge), including these four fixtures and the doc-links guard fixtures — plus node packages/scripts-ts/src/audit-docs-prune.ts --check (exit 0 post-merge), the doc-links guard itself (59 files, 133 links), and just ci-drift (7/7). A formatting-only commit (2cef5aa) satisfies oxfmt --check on the new fixture file.

Round 1 fix

Review round 1 returned CHANGES_REQUIRED (stale evidence, unenforced reproducibility control). All findings fixed, one commit each:

1. Inventory regenerated at the tip — 92 candidates including the merged docs(specs): open-core paid modules design #1355 paid-modules row; --check exits 0 (ea66f0c).
2. --check wired into docs-archive-gate + ci-doc-links, classifier pattern wakes the gate on generator edits, manifest reconciled honestly (6e744c1).
3. Guard scans untracked non-ignored files; new fixture test RED vs old code; RED transcript rewritten from a real run (8412095 + 73fddcf).
4. Code-surface docs/… literal scanner added with fixture test and paired RED (eb2fc37).

Round 1 fix implemented by Ox Alpha via Nous Portal (max, jcode). Round 2 fix implemented by Ox Alpha (stealth/ox-alpha via Nous Portal, max, jcode).

docs-archive gate retarget

• Old gate: check-archive-records.ts enumerated files that were supposed to exist under docs/archive/ and failed when they went missing. With the archive deleted it would have asserted an empty set forever — vacuously green. Per the issue's rule ("never left passing vacuously") the script, its test, and their manifest entries are deleted, not loosened.
• New gate: the same workflow (.github/workflows/docs-archive.yml, required context unchanged) now runs three things: the check-doc-links.ts guard, its fixture suite, and the prune-inventory freshness checks above.
• Guard scope: every tracked *.md in the whole repo plus untracked non-ignored working-tree files (git ls-files --others --exclude-standard), so a broken link planted but never staged still fails a local run. On top of Markdown links, the guard scans the code surfaces (apps/, packages/, .github/, the justfile, AGENTS.md, DESIGN.md) for docs/… path literals whose target does not exist — a code comment naming a deleted doc is as broken as a dead link. docs/records/ bodies stay exempt (write-once evidence, same policy the old archive carried); fenced code, inline code spans, URLs, branch names and test/spec fixtures are out of scope so examples cannot trip it. Wired into the local gate identically: recipe ci-doc-links, manifest entries reconciled through just ci-drift.
• RED/GREEN proof: committed at docs/records/2026-08-25-analysis-doc-links-guard-proof.md. GREEN on the clean tree (58 files scanned, 132 relative links checked, exit 0). RED from a real run, captured as written:

$ echo 'broken [link](./no-such-target.md) here.' > docs/guides/_tmp-red-proof-untracked.md
$ node packages/scripts-ts/src/check-doc-links.ts
1 broken relative link(s) in tracked or untracked non-ignored Markdown:
  docs/guides/_tmp-red-proof-untracked.md:1: -> docs/guides/no-such-target.md
exit=1

with an exempt frozen-record link planted in the same run staying silent, and a paired literal-scan RED (broken docs/… literal in apps/api/Lib/AppEnvironment.cs → exit 1 naming file and line). Both plantings were removed immediately after capture; the clean tree went green again. The fixture suite pins these modes permanently (13 tests), including the untracked-file case (RED against the old tracked-only code) and the literal-scan cases.

Public/private rule

Business/licensing/strategy content never enters this public repo — it lives in the owner's private notes.

Ruleset note

The required check context keeps the name docs-archive-gate: only the job's steps changed, not its name: (conditional docs-archive-gate on pull_request/merge_group, docs-archive-push-check on push). No rename, so the branch ruleset keeps matching and no PR gets spuriously blocked.

Known unrelated CI failure

Build e2e images fails due to the org-move issue (#1396). Not caused by this PR.

---

Implementer: Ox Alpha (stealth/ox-alpha via Nous Portal, max, jcode)

Unverified

• Local e2e stack intentionally NOT run per captain policy (2026-08-23): CI runs front-e2e on this PR and that is the accepted evidence.
• Full API integration suite and full front unit suite not run locally for this docs-only lane; CI covers both on the PR.
• All local claims in this update ran against tip 2cef5aa (scripts-ts suites, prune --check, just ci-drift, doc-links guard); the remaining evidence is this PR's own checks at that tip.