docs(topic-docs): the contract-slice prune rule is normative, unenforced, and contradicted 17 times on main

[kyle-sexton]

The contradiction

docs/conventions/topic-docs/README.md states the contract-slice lifecycle as normative:

• Contract tier is "Committed on the task branch only; pruned before merge" (:33).
• Step 4: "A final commit prunes the contract slice <contract_dir>/<slug>/".
• Step 5: "Enforcement: a required check that the net PR diff (git diff --name-only base...head) contains no path under the resolved <contract_dir>/**".

Neither the pruning nor the enforcement is real:

• origin/main carries 17 topic slices under docs/topics/, and new ones keep landing — docs/topics/context-engineering-claude-5/PLAN.md arrived in the current batch.
• No such required check exists. The only occurrence of docs/topics in .github/workflows/ is a comment in ci.yml:39 about path filters.

Why it matters

The gap is not cosmetic. It surfaced as a review finding on #1400, where a reviewer correctly cited :33 and :290-309 to argue a PR should not merge — against a repository whose observable convention is the opposite. Any reviewer, human or automated, reading the doc will keep reaching the same conclusion, and any author following it will keep deleting work the repository in fact keeps.

An unenforced normative rule that practice contradicts 17 times is worse than no rule: it makes the doc unciteable without checking whether this particular clause is the live one.

Decide, do not split the difference

One of these, not a softening of both:

1. The doc is what's out of date — topic slices are durable and land with their PRs. Rewrite the lifecycle: drop steps 4–5, restate the contract tier as committed-and-kept, and describe the promotion-to-knowledge-vault path as an option for durable rationale rather than a prerequisite for merge.
2. The practice is what's wrong — build the required check step 5 already specifies, and prune the 17 existing slices through the knowledge-vault seam. This is the expensive branch, and it invalidates the accumulated cross-references to those paths.

Recommendation is (1): the doc's own rationale for pruning is diff noise and review-surface cleanliness, and the repository has been paying that cost deliberately for 17 slices without anyone reverting the practice. That is a decision already made in code; the doc simply never recorded it.

Filed rather than fixed inline because it changes a normative convention document, and because the correct branch is a judgment call about what the repository wants topic slices to be — not a drafting error.

Surfaced while driving #1400 to merge. #1400 merges under reading (1); if (2) is chosen instead, #1400's two files are pruned along with the other 17.

[kyle-sexton]

This was generated by AI during triage.

Classification: needs-decision, human-gated. The issue's own framing ("Decide, do not split the difference"; "the correct branch is a judgment call about what the repository wants topic slices to be") is a genuinely open decision — normative-convention-document territory, not a drafting error.

Likely-already-answered pointer, for whoever picks this up: this substantially overlaps with the currently active, operator-directed work on #1417/#1424 (contract-slice disposition — prune 8, graduate 3, register 6, plus a register file wired for future prunes). That decision reads as resolving this issue's option (2) — build the enforcement the doc already specifies, prune/graduate/register the existing slices through a real seam — rather than option (1), rewriting the doc to declare slices durable. Recommend closing this as answered-by-#1417 once that work lands, rather than re-litigating the same question independently; flagging the pointer here so a human reviewing this issue does not duplicate a decision already in flight.

[kyle-sexton]

Frontier disposition (drain session)

Ruling: Close as completed.

Contract-slice prune enforcement debt is tracked for execution in #1424; this advisory duplicate adds no separate deliverable.

Re-open trigger: None — track enforcement in #1424.