P0011: split Policies vs. Requirements into distinct categories (captain-ratified, below evidence floor — named exception)

[git-repo-auth]

Promotion from the first distillation sweep (C1, successor charter, 2026-07-20). Drafted by sweep flight run_fb133d81, transplanted by the dispatch seat (klappy.dev push refused to the flight — documented fallback). Patch was git apply --check verified against main. Merging is the maintainer's alone (M3) — defer and reject are legitimate outcomes and each promotion's Evidence section says so honestly.

Full report + kirigami foldout: docs/reports/2026-07-20-first-distillation-sweep.md on sweep/2026-07-20-first-distillation in outcomes-driven-development.

---

---

uri: klappy://docs/promotions/P0011-policies-vs-requirements-split
title: "P0011: Policies vs. Requirements — Split an Overloaded Category So Steering Failures Stop Reproducing"
audience: docs
exposure: nav
tier: 3
voice: neutral
stability: evolving
tags: ["promotions", "proposed", "policy", "requirements", "steering", "prd", "governance"]
promotion_status: proposed

P0011: Policies vs. Requirements — Split an Overloaded Category So Steering Failures Stop Reproducing

"Policy" has been used to name two different artifact types — durable, slow-changing principles (POLICIES) and fast-changing, build-specific functional needs (REQUIREMENTS). Collapsing them is a suspected root cause of steering failures: requirements dressed as policy resist necessary change; policy dressed as requirements churns when it shouldn't. This promotion canonizes the split as a named distinction, without yet resolving the boundary test or migration path for existing documents.

Observed Pattern

The program has overloaded "policy" to cover everything that shapes AI behavior, from durable abstract guidance down to the specific functional needs of a single build. Two failure modes follow from the collapse:

• A requirement written as if it were policy inherits policy's durability expectations and becomes artificially resistant to change, when it should be revisable per build.

• A policy written as if it were a requirement inherits requirements' fast-changing cadence and churns on every build cycle, when it should be stable.

• Affects: mode-output contracts, PRD gates, and any surface that currently asks for "policy" without naming which of the two artifact types it means

• Outcome without the split: steering failures of the two shapes above continue to reproduce, each misdiagnosed as a one-off rather than an instance of a named category error

Evidence

Validation Session	Date	Outcome	Notes
Captain's log capture (Bee), relayed via Otto seat sess_f7294064	2026-07-18 ~12:10 EDT	Ratified	Captain named the category collapse directly and credited the observation to Jesse; ratified in-session 2026-07-19

Total observations: 1 (direct captain ruling, not a repeated-validator-failure pattern)
Independent occurrences: 1 — this promotion does not meet docs/promotions/README.md's literal rule ("No promotion without ≥2 independent validations"). Flagged squarely, not softened: this is below the pipeline's stated floor, not merely a "different evidence class." It is drafted anyway because the evidentiary basis is a direct captain ruling already recorded (candidates/2026-07-18-policies-vs-requirements-split.md, status: ratified) rather than a validator-discovered failure pattern, and the sweep judges that a captain's own in-session ratification is a legitimate basis for the maintainer to consider — but the maintainer should treat the ≥2-validations rule as unmet here, and accepted on the strength of the ruling alone (rather than deferred pending independent corroboration) is a deliberate exception to the pipeline's own numeric bar, not a case where the bar was satisfied.
Affected workflows: any workflow that produces or consumes something currently labeled "policy" — mode-output contracts, PRD gates, canon authoring

Current Handling

No canon document currently names this split. canon/meta/writing-canon.md and the PRD gate discuss what canon documents look like, but neither distinguishes POLICIES (durable, canon-shaped) from REQUIREMENTS (fast-changing, PRD-shaped) as a named category question a document must answer before being filed.

Proposed Promotion

Target Document

canon/meta/policies-vs-requirements.md (new)

Section

Whole document; new file.

Proposed Language

---
uri: klappy://canon/meta/policies-vs-requirements
title: "Policies vs. Requirements — A Category the Program Has Been Collapsing"
audience: canon
exposure: nav
tier: 2
voice:

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> **Low Risk**
> Documentation-only governance clarification with no code, migration, or enforcement; main reviewer note is inconsistent promotion status metadata vs “landed” text.
> 
> **Overview**
> Adds **active canon** `canon/meta/policies-vs-requirements.md`, which formally separates **POLICIES** (durable, canon-shaped guidance) from **REQUIREMENTS** (build-specific, PRD-shaped needs) and ties the overloaded “policy” label to steering failures. The doc deliberately stops short of a classification test or migration plan; it asks mode-output contracts and the PRD gate to state which artifact type they mean.
> 
> Adds promotion packet **`docs/promotions/P0011-policies-vs-requirements-split.md`** with pattern, evidence, proposed language, and low-risk assessment. Evidence is flagged as **below** the promotions README’s ≥2 independent validations bar, framed as a maintainer exception on captain ratification. The promotion **Status** section records canon as already landed verbatim while front matter still shows `promotion_status: proposed`—worth reconciling on merge.
> 
> <sup>Reviewed by [Cursor Bugbot](https://cursor.com/bugbot) for commit 928084748893334a2a395f26c863b9f79ffbd597. Bugbot is set up for automated code reviews on this repo. Configure [here](https://www.cursor.com/dashboard/bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

[github-actions]

Canon Quality — P0010 Retrieval-Readiness ⚠️

Soft report for klappy://canon/constraints/retrieval-disclosure-contract. 704 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': 52, 'canon': 243, 'apocrypha': 38, 'docs': 305, 'journals': 60, 'unknown': 6}
Kind source: {'path': 569, 'frontmatter': 129, 'none': 6} (frontmatter-primary, path-secondary)
Default-include visibility: 600 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: #401}

[github-actions]

Canon Quality — Homepage Surfacing ✅

50 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 50 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: #401}

[github-actions]

Canon Quality — oddkit_audit ⚠️

8 finding(s) in writings/ (50 files scanned). Mode: soft.

writings/agentic-software-development.md — 1 finding(s)

Line	Rule	Occurrence	Message
242	dead-reference	klappy://writings/nothing-new-even-ai	URI does not resolve

writings/choosing-faith-not-fear.md — 1 finding(s)

Line	Rule	Occurrence	Message
203	dead-reference	klappy://writings/four-questions-that-change-everything	URI does not resolve

writings/getting-started-with-odd-and-oddkit.md — 4 finding(s)

Line	Rule	Occurrence	Message
69	legacy-link-pattern	/page/writings/the-journey-from-ai-tasks-to-ai-augmented-workflows	Use a klappy:// URI instead of /page/ path
202	legacy-link-pattern	/page/docs/oddkit/proactive/proactive-bootstrap	Use a klappy:// URI instead of /page/ path
204	legacy-link-pattern	/page/docs/examples/project-instructions-template	Use a klappy:// URI instead of /page/ path
260	legacy-link-pattern	/page/writings/the-journey-from-ai-tasks-to-ai-augmented-workflows	Use a klappy:// URI instead of /page/ path

writings/the-broken-wall-and-the-buried-talent.md — 1 finding(s)

Line	Rule	Occurrence	Message
332	dead-reference	klappy://draft-zeros/appendix-a-the-biblical-roots	URI does not resolve

writings/the-voice-came-first.md — 1 finding(s)

Line	Rule	Occurrence	Message
244	dead-reference	klappy://writings/four-questions-that-change-everything	URI does not resolve

Soft-block mode — this status is informational; the job will not fail. Hard-block ships in PR-3.2 after the observation cycle.

What to do for each finding:

• Fix the slug if the target now lives at a different klappy:// URI.
• Remove the link if it is no longer needed.
• Allowlist with a reason if the rot is intentional (e.g. forward-ref to an upcoming article): place <!-- audit-allow: dead-reference reason="..." --> on the line above the offending link. The directive is line-level and scopes to the next markdown link.

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