Canon: Document Routing Tests — falsifiable decision tree for what goes where

[git-repo-auth]

Summary

Adds canon/methods/document-routing-tests.md — a falsifiable decision tree that routes any document in a layered estate to exactly one home per layer (universal canon, portable core, owner's office, working conventions, project repo) using tests answerable from the document's own text. It extends the seven core-boundary criteria from a three-home world to a five-layer estate, with Gate 0 (capture precedes routing), the T1–T7 tree, tie-breakers, the SPLIT rule, and six worked examples from the night of 08-27/28.

Routing evidence (per the doc's own standard)

Deciding tests: T2 pass (operator-stripped substance survives), T3 pass (proven across the 2026-06 bifurcation and 2026-07 repo-scope decomposition), T4 → stays in overlay with target_repo: outcomes-driven-development; SPLIT residue → kitchens pointer PR (https://github.com/klappy/kitchens/pull/1).

Validation

scripts/validate-frontmatter.py canon/methods/document-routing-tests.md → ✅ Frontmatter OK — 1 file(s) scanned, 0 findings. (exit 0, no frontmatter changes needed)

Provenance

Dispatch seat Otto, design flight 2026-08-28. Captain's order verbatim: "We need to make sure we have clean and clear tests that route what goes where"

Ratification = captain's merge. Do not merge without captain review.

---

Note

Low Risk
Adds governance documentation only; it affects future routing discipline across repos but does not change runtime code, auth, or data paths.

Overview
Introduces canon/methods/document-routing-tests.md, a new tier-1 canon method that tells agents and adopters how to place a document in exactly one home per layer using tests that must be answerable from the document text alone.

It extends the seven core-boundary criteria from a three-home model (core / overlay / tool) to a five-layer map (universal canon, portable core via target_repo, owner’s office, working conventions, project repos). Gate 0 requires capture before routing; T1–T7 run in order (genericization and bet gates before L1/L2); tie-breakers include SPLIT (one substance per layer, pointers not copies) and evidence requirements for routing PRs.

The doc includes six worked examples from 2026-08-27/28 and self-applies its own tree (L1 with target_repo: outcomes-driven-development, office pointer residue per SPLIT). No application code changes—only new governed canon text.

^{Reviewed by Cursor Bugbot for commit 560d0e7. Bugbot is set up for automated code reviews on this repo. Configure here.}

[github-actions]

Canon Quality — Homepage Surfacing ✅

51 essay(s) scanned. Soft report — never blocks; the hard field gate is the Frontmatter Schema job.

All published essays resolve to the homepage feed.

_{Report: scripts/surfacing-report.py · Canon: klappy://canon/constraints/frontmatter-validation-before-merge}

[github-actions]

Canon Quality — Frontmatter Schema ✅

All 51 file(s) in writings/ conform to klappy://canon/meta/frontmatter-schema.

_{Validator: scripts/validate-frontmatter.py · Canon: klappy://canon/constraints/frontmatter-validation-before-merge · Run: #429}

[github-actions]

Canon Quality — P0010 Retrieval-Readiness ⚠️

Soft report for klappy://canon/constraints/retrieval-disclosure-contract. 712 files scanned. Never blocks — informational until the corpus is ready to enforce.

• Blocking-class findings: 15 (structural fields the contract would filter on)
• Warnings: 0 (kind resolves to unknown)
• Informational: 13 (exempt templates/archive/drafts)

Kind distribution: {'essays': 53, 'canon': 248, 'apocrypha': 38, 'docs': 307, 'journals': 60, 'unknown': 6}
Kind source: {'path': 576, 'frontmatter': 130, 'none': 6} (frontmatter-primary, path-secondary)
Default-include visibility: 608 visible, 104 hidden (journals/apocrypha/unknown)

By rule: {'audience-invalid': 2, 'exposure-missing': 5, 'tier-missing': 5, 'tier-invalid': 7, 'fm-missing': 3, 'kind-unresolvable': 6}

These are not schema violations (see the Frontmatter Schema job for those on writings/). They are corpus-readiness signals for the retrieval contract: invalid/missing audience, exposure, tier, and docs whose kind cannot be resolved. Fix in a corpus-cleanup PR before the contract flips to enforcing. See the retrieval-readiness-findings artifact for the full list.

_{Validator: scripts/audit-retrieval-readiness.py · Constraint: klappy://canon/constraints/retrieval-disclosure-contract · Run: #429}

[github-actions]

Canon Quality — oddkit_audit ✅

No dead klappy:// references or legacy link patterns found in writings/. 53 files scanned.

_{Spec: klappy://docs/oddkit/specs/oddkit-audit · Workflow: .github/workflows/canon-quality.yml · Run: #429}

[cursor]

Cursor Bugbot has reviewed your changes using default effort and found 2 potential issues.

Bugbot Autofix prepared fixes for both issues found in the latest run.

• ✅ Fixed: T2 and T3 disagree on L2
  • The T2 empty-after-strip falsifier now continues to T3 then T4–T7 and states that T3 vetoes L1/L2 only for bets, matching T3's settled-plus-no-candidate continue-to-T4 branch.
• ✅ Fixed: Bet branch names two homes
  • The T3 bet arm and tree intro now skip T4 and resume at T5 so T5–T7 name office, kitchen, or overlay, instead of treating T5 or overlay as the unique home.

_{You can send follow-ups to the cloud agent here.}

^{Reviewed by Cursor Bugbot for commit 075399a. Configure here.}