canon(principle): Abstraction Matches Scope — falsifiability placement test [DRAFT]

[git-repo-auth]

DRAFT — operator review only. Do not merge. Assigned to @klappy; review not requested.

What this adds

One universal canon principle: canon/principles/abstraction-matches-scope.md (epoch E0010, tier 1, target_repo: outcomes-driven-development, neutral voice, status: proposed).

The principle: a governing document's level of abstraction must equal the breadth of what it actually governs.

• WHAT — match a document's abstraction to its blast radius. Abstraction level is a claim about scope, and can be wrong.
• WHY — a local rule stated universally is silently false everywhere it was over-applied once its one stack changes; a universal truth filed as implementation detail hides from the readers it should govern and decays too fast.
• HOW (the placement test) — falsifiability: if a change confined to one repository or one stack would falsify a document, it is repo/stack-scoped, not universal. A universal doc should be falsifiable only by something that reaches everything downstream. Corollary: a mis-filed doc is relocated, not caveated.

The doc passes its own test (only a change to the shared discipline of assigning authority could falsify it), which is why it is stated abstractly in universal canon.

Reconciliation — what already existed (the operator "thought it was already documented")

Searched canon first. Closest existing coverage, and how this reconciles rather than duplicates:

• D0001 — Three-Tier Conceptual Hierarchy (odd/decisions/D0001, tier 1, stable) already separates universal principles / program constraints / implementation detail and gives a placement litmus built on temporal reach + breadth ("true in 10 years?" / "should all products obey?"). This principle sharpens that litmus into a falsifiability test (decidable now, no forecasting) and makes explicit the relocation corollary D0001 implies but never states. This is very likely the doc that felt "already written" — it covers the tiers, not the placement test.
• canon/principles/scope-over-folders (tier 2) governs a different axis: storage location is not authoritative; scope is a declared attribute, never inferred from path. It forbids faking scope with folders. This principle forbids faking scope with generality. Complementary, not overlapping.
• docs/repo-bifurcation-and-target-repo-routing — its "domain-applicability test" is this falsifiability test wearing klappy.dev→ODD clothes: the stack-specific instance of the universal principle proposed here.

Net: no existing doc states the falsifiability placement test or the relocation corollary. New peer principle warranted; cross-referenced to all three above via derives_from/complements.

oddkit_challenge (mode: canon-tier-1) — findings folded

block_until_addressed: false, tensions: [], governance_source: knowledge_base. Folded into a new "Limits, prior art, and where the test needs care" section:

• Prior art acknowledged (separation-of-concerns, single-responsibility, DRY's single source of truth, rule of least power) with the distinction stated.
• Mixed-scope documents — split; confined-falsifiability half dominates placement.
• Pure values vs claims — the test governs falsifiable claims; pure values fall back to D0001's breadth litmus.
• Confidence + retraction condition made explicit: retracted if a class of docs proves to hold universal authority while being falsifiable by a single stack's change.

Residuals (for operator): the principle rests on a small sample of placement cases; it is offered as an operator-ruled working invariant, not a proven theorem.

⚠️ Motivating-case discrepancy — needs your reconciliation

The task described the sandbox-hygiene-per-flight-scratch constraint as "first filed in universal canon, being relocated to agent-role-service." Observed repo state differs: on branch policy/sandbox-hygiene-per-flight-scratch, the constraint sits whole in portable canon (canon/constraints/sandbox-hygiene-per-flight-scratch.md, tier 1, target_repo: outcomes-driven-development) and is not yet relocated. Its content is mixed-scope: a universal law (state residue is indistinguishable from signal) plus a substrate-specific mechanism (per-flight owned scratch dirs, no /tmp/pr_body.md).

So I did not encode "is being relocated" as accomplished fact. The doc instead presents the truthful, stronger version: the constraint is a mixed-scope case; the universal law stays up, the substrate mechanism goes down to agent-role-service per your ruling; and a parenthetical notes the relocation is a directed decision not yet reflected in the repo. Please confirm this framing matches your intent.

Before merge (not done here — draft)

• Per canon/constraints/governance-change-discipline: a behavior-affecting canon addition needs a version bump + changelog entry + release note (and epoch attribution E0010). Not authored in this draft.
• Relocating the sandbox-hygiene mechanism is a separate directed change, not included here.

Provenance

Authored via oddkit canon reads (klappy.dev @ f999655). Frontmatter passes scripts/validate-frontmatter.py (0 findings). Commit attributed to klappy 118073+klappy@users.noreply.github.com.

[github-actions]

Canon Quality — oddkit_audit ✅

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

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

[github-actions]

Canon Quality — Homepage Surfacing ✅

49 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 49 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: #373}

[github-actions]

Canon Quality — P0010 Retrieval-Readiness ⚠️

Soft report for klappy://canon/constraints/retrieval-disclosure-contract. 700 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': 51, 'canon': 241, 'apocrypha': 38, 'docs': 304, 'journals': 60, 'unknown': 6}
Kind source: {'path': 565, 'frontmatter': 129, 'none': 6} (frontmatter-primary, path-secondary)
Default-include visibility: 596 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: #373}