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.}

[git-repo-auth]

Driver's-seat lens + challenge — CoS door, 2026-09-03 ~4:30 PM ET

Ran klappy://canon/methods/driver-seat-lens over this document as the agent who has to route a document with it, then oddkit_challenge in canon-tier-1 mode. Lens before challenge, per the method. This is a delta receipt in comment form — the document is tier-1 canon in a PR the captain ratifies by merge, so the seat proposes edits here rather than pushing them.

What I would need from the driver's seat (proposed changes)

#	Pinch, observed	Proposed change
1	derives_from names odd://canon/constraints/core-boundary-criteria. oddkit_resolve rejects odd:// ("input must be a klappy:// URI") and klappy://canon/constraints/core-boundary-criteria is NOT_FOUND. An agent running T1–T7 cannot fetch criteria 1–7 from any tool it has. The seven criteria this whole tree "applies" are unreachable from the estate that ships it.	Either mirror/point to a resolvable URI, or inline the seven criteria as a one-line-each appendix (they are cited nine times). Also lists docs/repo-bifurcation-and-target-repo-routing.md by path — the resolvable form is klappy://docs/repo-bifurcation-and-target-repo-routing.
2	The control flow is prose (line 63): T1 gate → continue at T2 or skip to T5; T2 candidate-not-landing; T3 bet skips T4 and continues at T5; settled+candidate lands L1. Three reads to hold it.	Add a 7-row transition table under the tree: test · yes → · no → · lands?. Same content, one glance.
3	"Stays at the lower rung (in this tree, the overlay)" (line 129) — but the overlay is also where L1 and L2 physically live. The layer map has five rows; the estate has a sixth home: overlay, untagged (bets, observations). An agent routing a bet has no row to land it on.	Add the row: L2′ / overlay-untagged — bets and observations awaiting a second case — "T3 said bet; no target_repo". Rename "lower rung" to that name.
4	"Routing PRs carry evidence" names four fields but no shape. Every routing decision is a receipt the next agent must read.	One receipt row per document: doc · Gate 0 · T1 · T2 · T3 · landing · one line why. The worked examples already are this table in prose.
5	T3 "settled" needs ≥2 contexts and a considered counter-example — evidence that lives outside the text unless the document carries it, which strains "answerable from the document's own text alone."	State it: a document that wants L1/L2 carries its cases (a cases: line or a Cases section). Then T3 is text-answerable and lintable.

Considered and rejected

• Restating the seven criteria in full — the doc rightly cites, not copies; a one-line appendix is the compromise.
• Collapsing T2 and T3 into one test — the order is load-bearing (the doc says so and is right).
• Moving worked examples to the office — they are the proof the method needs to pass its own T3.

Challenge (canon-tier-1) — what the doc must answer before it is tier-1 law

• No retraction condition for the method itself. Every test has a falsifier; the document has none. Proposed: if two consecutive routing PRs reach verdicts two independent agents cannot reproduce from the text, the tree is not falsifiable in practice and this method is superseded.
• Confidence and cost unsignaled. It claims tier 1 while stability: evolving; the five-layer extension is one estate's topology (one case), the criteria are the settled part. Say which half is doctrine and which is under test — the self-application section nearly does.
• Comparison freshness. The office/kitchen topology it rests on was recut on 2026-08-31 (ARS removed) and 2026-09-02 (kitchen ruleset removed). Verdicts in worked examples 1 and 5 reference ARS as live. One line dating the snapshot.
• The dead derives_from is also a challenge finding, not only an ergonomics one: a tier-1 document whose named ancestor cannot be fetched fails criterion 7 (derivation chain travels) by its own rule.

Verdict from this seat

Substance is sound and the ordering argument is right. Not ready to ratify as tier 1 until #1 (unreachable ancestor) and the retraction condition are fixed; #2–#5 are ergonomics the next routing seat will thank you for. Captain merges; this seat does not.