canon: policy-precedes-build — no build without a ratified, enforceable governing policy (DRAFT, captain review)

[git-repo-auth]

DRAFT — DO NOT MERGE. This is canon in the captain's authorial voice. It ships only after the captain reviews the exact text. Opened as draft and assigned to @klappy for that review.

What this adds

A tier-1, fleet-wide canon constraint: klappy://canon/constraints/policy-precedes-build.

The rule. On every project, no implementation, build, or deploy proceeds without a ratified, enforceable governing policy stating what is being built and why. The order is design → policy (→ PRD) → build — never code-first. The policy must be precise enough that the implementation is derivable from it (self-building), and every build must cite its governing policy URI (self-documenting).

Why. The 2026-07-16 ARS monolith SQLITE_TOOBIG freeze: code ran ahead of policy, so there was nothing to build from and no enforcer to catch the drift. Plus — this is the captain's consistent build philosophy; encoding it removes the per-task restatement and makes compliance the default. Policy-first is universal in order; policy weight scales with maturity.

How enforcement is real (not aspirational)

1. Mode gate. Adds prerequisite ratified-governing-policy-cited to the planning → execution transition (klappy://odd/gate/prerequisites). oddkit_gate gaps without a policy URI; oddkit_preflight refuses build mode when the work cites no ratified policy.
2. Build-PR / CI check. Every build/impl PR must reference its governing policy URI (e.g. a Governing-Policy: trailer); a PR/CI check fails a build that cites none and cannot resolve it via oddkit_resolve. Composes with release-validation-gate.
3. Generalizes PR canon(constraint): ratified model requires reconciliation and an enforcer (DRAFT — do not merge) #288 (ratified-model-requires-reconciliation-and-enforcer) — the model-specific instance of which this is the general rule. Cross-referenced, not duplicated.

Reconciliation (extend, don't duplicate)

model-operating-contract (mode gate + preflight) · prompt-over-code (the ordering discipline it presupposes) · constraint-driven-audits (written as an auditable surface: machine-resolvable governs, named T1–T5 tests, remediation vocabulary) · release-validation-gate · definition-of-done ("done" now includes citing a resolvable policy URI) · borrow-evaluation-before-implementation (whether to build vs. the order of building — they stack) · odd/maturity (order universal, weight scales) · contract-governs-handoff-drift.

Provenance & honest residuals

• Reconciliation targets retrieved from live canon via oddkit before drafting; pressure-tested with oddkit_challenge at canon-tier-1 (no hard tensions, block_until_addressed: false). Its prompts drove the Edge Cases (emergency/incident exception w/ retroactive ratification), Alternatives Considered, and Falsifiability & Retraction sections.
• PR canon(constraint): ratified model requires reconciliation and an enforcer (DRAFT — do not merge) #288, the ratified flat-records model, and the ARS incident report were not in the indexed canon baseline at authoring time (consistent with living in open, unmerged PRs). They are referenced from the captain's account; no claim is made about their internals. Reconcile against exact text once merged.
• Structural tests can be satisfied by a vacuous policy; T4 (derivable) is the semantic backstop and requires reviewer judgment — a known soft floor, flagged in the doc.
• The gate prerequisite + CI check are described as policy; the enforcer implementation is itself a build that must proceed from this ratified policy.

CI: passes scripts/validate-frontmatter.py (0 findings). target_repo intentionally omitted so the file stays in klappy.dev.

[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: #369}

[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: #369}

[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: #369}

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