Fix progressive disclosure violations and amend DoD/Self-Audit for document deliverables

canon/constraints/README.md

@@ -40,6 +40,10 @@ Constraints define the baseline assumptions and design defaults applied to most
 - [Boundary Transitions Require Deceleration](/canon/constraints/boundary-transitions-require-deceleration.md)
 - [ODD Is an Epistemic OS, Not a Value System](/canon/constraints/odd-is-epistemic-os-not-values.md)
 - [No Irreversible Action Without Epistemic Justification](/canon/constraints/no-irreversible-action-without-epistemic-justification.md)
+- **ODD-Level Constraints** (universal, in `/odd/constraint/`):
+  - [Anti-Metric Laundering](/odd/constraint/anti-metric-laundering.md) — A system that cannot surface its own blind spots will optimize to protect them
+  - [Anti-Cache Lying](/odd/constraint/anti-cache-lying.md) — A cache of derived content is a polite lie; only content-addressed storage is acceptable
+  - [Use Only What Hurts](/odd/constraint/use-only-what-hurts.md) — Prevents ODD from becoming heavy, coercive, or self-justifying
 
 ---
 

canon/constraints/definition-of-done.md

@@ -21,7 +21,7 @@ start_here_label: Definition of Done
 
 ## Description
 
-This policy is a specific application of the foundational axiom that every claim creates an evidence obligation. This policy defines completion requirements for all work: code, UI, architecture, automation, and AI-assisted outputs. Work is only done when it includes a change description, verification performed, observed behavior, evidence produced, and self-audit completed. Evidence must demonstrate actual behavior (screenshots, recordings, rendered output, test logs) and be produced after the change. Visual verification is required for UI work. The policy covers partial completion handling, explicit exceptions, and agent responsibilities.
+This policy is a specific application of the foundational axiom that every claim creates an evidence obligation. This policy defines completion requirements for all work: code, UI, architecture, automation, documents, and AI-assisted outputs. Work is only done when it includes a change description, verification performed, observed behavior, evidence produced, and self-audit completed. Evidence must demonstrate actual behavior (screenshots, recordings, rendered output, test logs) and be produced after the change. Visual verification is required for UI work. The policy covers partial completion handling, explicit exceptions, and agent responsibilities.
 
 ## Outline
 
@@ -46,6 +46,7 @@ This policy is a specific application of the foundational axiom that every claim
 - MUST provide visual proof for any work affecting UI, interaction, layout, or visible state
 - MUST NOT claim "done" without evidence; the correct response is "This is not complete yet"
 - MUST label partial completion explicitly with what was verified and what remains
+- MUST validate document deliverables against the Writing Canon checklist (`canon/meta/writing-canon.md`) before claiming completion
 
 ---
 
@@ -66,6 +67,7 @@ This policy is a specific application of the foundational axiom that every claim
 - **"This should work"**: Treating confidence as evidence
 - **"I reviewed the code"**: Treating inspection as observation of behavior
 - **"I didn't have time to test"**: Treating explanation as exemption from evidence
+- **"The document exists"**: Treating file creation as completion without validating progressive disclosure structure
 
 ---
 
@@ -137,6 +139,23 @@ Evidence must be:
 
 ---
 
+## 📄 Document Deliverables — Progressive Disclosure Is a Structural Requirement
+
+If the work produces a document targeting `canon/`, `odd/`, or `docs/`, the document must pass the Writing Canon checklist (`canon/meta/writing-canon.md`):
+
+1. **Title** names the concept and its stance
+2. **Blockquote** contains the complete compressed argument — an agent could act on title + blockquote alone
+3. **Metadata** includes epoch, derivation, governance with full file paths
+4. **Summary section** (`## Summary — [subtitle]`) is self-contained — could skip everything below and have the full picture
+5. **Headers** pass the scan test — reading them in sequence tells the document's story
+6. **No buried claims** — every key assertion is present in compressed form at a higher tier
+
+A document that exists but fails these tiers is not done. Existence is not quality.
+
+This was added after the Progressive Disclosure Failure incident (February 2026) — see `docs/incidents/progressive-disclosure-failure-2026-02.md`.
+
+---
+
 ## 👁️ Visual Verification (Preferred)
 
 If the work affects:

canon/meta/writing-canon.md

@@ -9,8 +9,9 @@ stability: stable
 tags: ["canon", "meta", "writing", "progressive-disclosure"]
 epoch: E0005
 date: 2026-02-09
-complements: "canon/meta/TEMPLATE.md, docs/TEMPLATE.md, canon/meta/agent-executable-outline.md"
+complements: "canon/meta/TEMPLATE.md, docs/TEMPLATE.md, canon/meta/agent-executable-outline.md, canon/constraints/definition-of-done.md, canon/methods/self-audit.md, docs/oddkit/IMPL-writing-canon-gate.md"
 derives_from: "canon/values/axioms.md (Axiom 2 — A Claim Is a Debt)"
+governs: "All documents in canon/, odd/, and docs/ directories"
 ---
 
 # Writing Canon — Progressive Disclosure and Topographic Navigation
@@ -141,3 +142,17 @@ The practical test: if your document were loaded alongside `canon/values/axioms.
 5. **Header scan test:** Do the headers tell the document's story when read in sequence? Do structural markers have descriptive subtitles?
 6. **No buried claims:** Is every key assertion present in compressed form at a higher tier? Does the body elaborate rather than introduce?
 7. **Axiom space test:** If loaded in a small context alongside the axioms and creed, does this document amplify the values or crowd them out?
+
+---
+
+## Enforcement — This Checklist Is Not Optional
+
+This checklist is not advice. It is a structural requirement integrated into the Definition of Done (`canon/constraints/definition-of-done.md`) and the Self-Audit Checklist (`canon/methods/self-audit.md`).
+
+If the deliverable is a document targeting `canon/`, `odd/`, or `docs/`, the progressive disclosure tiers are Definition of Done requirements. A document that exists but fails these tiers is not complete.
+
+OddKit's preflight and validate actions are being updated to surface this checklist automatically when the deliverable is a document — see `docs/oddkit/IMPL-writing-canon-gate.md`.
+
+This enforcement was proven necessary by the Progressive Disclosure Failure incident (February 2026), where an AI agent wrote and shipped three canon documents that violated every tier of this checklist. The documents were merged to main without validation. The agent had full access to this document but never checked its output against it. Access is not enforcement.
+
+See `docs/incidents/progressive-disclosure-failure-2026-02.md` for the full incident record.

canon/methods/self-audit.md

@@ -17,7 +17,7 @@ execution_posture: operational
 
 ## Description
 
-The self-audit checklist defines how work should be self-reviewed before claiming completion. It covers nine areas: intended outcome, constraints applied, decision rules followed, verification performed, evidence produced, UX and behavior check, tradeoffs and risks, maintainability check, and confidence level. Minimum acceptable completion requires a stated outcome, at least one verification step, at least one piece of evidence, and acknowledgment of tradeoffs or unknowns. This replaces repeated back-and-forth questions about whether work was actually run and verified.
+The self-audit checklist defines how work should be self-reviewed before claiming completion. It covers ten areas: intended outcome, constraints applied, decision rules followed, verification performed, evidence produced, document structure validation, UX and behavior check, tradeoffs and risks, maintainability check, and confidence level. Minimum acceptable completion requires a stated outcome, at least one verification step, at least one piece of evidence, and acknowledgment of tradeoffs or unknowns. This replaces repeated back-and-forth questions about whether work was actually run and verified.
 
 ## Outline
 
@@ -26,6 +26,7 @@ The self-audit checklist defines how work should be self-reviewed before claimin
 - Decision Rules Followed
 - Verification Performed
 - Evidence Produced
+- Document Structure Check
 - UX & Behavior Check
 - Tradeoffs & Risks
 - Maintainability Check
@@ -103,6 +104,18 @@ If an item cannot be answered, that is a signal—not a failure.
 
 ---
 
+### 5b. Document Structure Check (If Applicable)
+
+If the deliverable is a document targeting `canon/`, `odd/`, or `docs/`:
+
+   • Does it pass the Writing Canon checklist (`canon/meta/writing-canon.md`)?
+   • Does the blockquote contain the full compressed argument?
+   • Is the Summary section self-contained?
+   • Do headers tell the story when read in sequence?
+   • Could an agent act on title + blockquote alone?
+
+---
+
 ### 6. UX & Behavior Check (If Applicable)
 
 - Does the UI or interaction behave as expected?

docs/CONTENT-MAP.md

@@ -43,7 +43,7 @@ This map provides navigational links to ALL content in the repository, including
 
 **Subdirectories:**
 - `/odd/appendices/` — Patterns: progressive-elevation, quantum-development, visual-evolution
-- `/odd/constraint/` — Core constraints: use-only-what-hurts, anti-metric-laundering
+- `/odd/constraint/` — Core constraints: use-only-what-hurts, anti-metric-laundering, anti-cache-lying
 - `/odd/contract/` — Epistemic contracts
 - `/odd/decisions/` — ODD-level decision records
 
@@ -82,8 +82,10 @@ This map provides navigational links to ALL content in the repository, including
 | [/docs/oddkit/WHY.md](/docs/oddkit/WHY.md) | **Why oddkit exists** — Start here for oddkit |
 | [/docs/appendices/ATTEMPTS.md](/docs/appendices/ATTEMPTS.md) | Attempt lifecycle |
 | [/docs/TRUTH_MAP.md](/docs/TRUTH_MAP.md) | Authoritative sources per domain |
+| [/docs/incidents/README.md](/docs/incidents/README.md) | Incident records — failures that changed the canon |
 
 **Subdirectories:**
+- `/docs/incidents/` — Incident records documenting failures that led to canon changes
 - `/docs/oddkit/` — oddkit reference (ABOUT, SYSTEM-MAP, modes, WHY)
 - `/docs/agents/` — Agent role definitions and patterns (librarian, validation, discovery, ODD agents)
 - `/docs/orchestrator/` — Orchestrator guides (QUICKSTART)

docs/incidents/README.md

@@ -0,0 +1,21 @@
+---
+uri: klappy://docs/incidents
+title: "Incident Records"
+audience: docs
+exposure: nav
+tier: 2
+voice: neutral
+stability: evolving
+tags: ["incidents", "index", "dogfooding", "lessons"]
+---
+
+# Incident Records
+
+> Documented failures that led to canon or constraint changes. Each incident records what happened, which axioms were violated, what was learned, and what was created to prevent recurrence. Incidents are evidence — they explain why constraints exist.
+
+---
+
+| File | Title | Date | Led To |
+|------|-------|------|--------|
+| [oddkit-stale-cache-2026-02.md](oddkit-stale-cache-2026-02.md) | OddKit Stale Cache — Days of Silent Lies | 2026-02-12 | Anti-Cache Lying constraint, Decision Rule #15, Content-Addressed Storage impl |
+| [progressive-disclosure-failure-2026-02.md](progressive-disclosure-failure-2026-02.md) | Canon Documents Shipped Without Progressive Disclosure | 2026-02-12 | DoD amendment, Self-Audit amendment, Writing Canon enforcement, OddKit Writing Canon gate impl |

docs/incidents/oddkit-stale-cache-2026-02.md

@@ -1,6 +1,6 @@
 ---
 uri: klappy://docs/incidents/oddkit-stale-cache-2026-02
-title: "Incident: OddKit Stale Cache (February 2026)"
+title: "Incident: OddKit Stale Cache — Days of Silent Lies (February 2026)"
 audience: docs
 exposure: nav
 tier: 2
@@ -12,15 +12,19 @@ epoch: E0005
 date: 2026-02-12
 ---
 
-# Incident: OddKit Stale Cache (February 2026)
+# Incident: OddKit Stale Cache — Days of Silent Lies (February 2026)
 
-## Summary
+> OddKit — the epistemic guide built to enforce "Reality Is Sovereign" — served stale canon documents for days without detection. Its cache flush mechanism (`invalidate_cache`) only cleared `.zip` files, leaving other stale derived content in place. The tool built to prevent assertion without verification was itself asserting without verification. This incident proved that TTL-based caching of derived content is incompatible with ODD's Foundational Axioms and led to the creation of the Anti-Cache Lying constraint (`odd/constraint/anti-cache-lying.md`).
 
-OddKit — the epistemic guide for ODD — served stale canon documents for days without detection. Its cache flush mechanism (`invalidate_cache`) only cleared `.zip` files, leaving other stale derived content in place. The tool built to enforce "Reality Is Sovereign" was itself substituting a past observation for current truth.
+---
+
+## Summary — The Epistemic Integrity Tool Was Itself Lying About Reality
+
+OddKit caches baseline canon documents fetched from GitHub to reduce latency. This cache used a staleness window — content was fetched once and served until TTL expiry or manual `invalidate_cache`. During active canon development, documents in the baseline repo were updated. OddKit continued serving old versions for days. No error was raised. No signal indicated staleness. When the issue was discovered through human observation (not automated detection), `invalidate_cache` only cleared `.zip` files — other cached artifacts remained stale. The flush mechanism was itself incomplete: a lie about the lie-clearing mechanism. This violated Axioms 1, 3, and 4. The root cause was pre-optimization: caching was introduced to save latency without measuring Total Cost of Ownership. This incident directly led to the Anti-Cache Lying constraint, Decision Rule #15 (Measure Total Cost Before Optimizing), and the implementation instruction for content-addressed storage in OddKit.
 
 ---
 
-## What Happened
+## What Happened — Stale Canon Served Without Any Signal
 
 OddKit caches baseline canon documents fetched from GitHub to reduce latency on repeated calls (orient, search, get, etc.). This cache used a staleness window — content was fetched once and served from cache until either the TTL expired or `invalidate_cache` was manually invoked.
 
@@ -30,21 +34,19 @@ When the issue was eventually discovered and `invalidate_cache` was called, it o
 
 ---
 
-## Duration
+## Duration — Days, Exact Duration Unknown Because the Cache Produced No Signal
 
-Days. The exact duration is unknown because the cache produced no staleness signal.
+Days. The exact duration is unknown because the cache produced no staleness signal. This is consistent with the core failure mode of derived-content caching: the cache eliminates the very signal that would prompt investigation.
 
 ---
 
-## Detection
+## Detection — Human Observation, Not Automated
 
 The staleness was not detected by any automated system. It was discovered through human observation when canon content did not match expected updates.
 
-This is consistent with the core failure mode of derived-content caching: the cache eliminates the very signal that would prompt investigation.
-
 ---
 
-## Axiom Violations
+## Axiom Violations — Three of Four Axioms Breached
 
 **Axiom 1: Reality Is Sovereign**
 The cache served a model of reality (past state) instead of reality itself (current state). Every response from OddKit during the stale period was an assertion about canon that was not grounded in the current state of the canon.
@@ -57,15 +59,15 @@ The cache eliminated the observation path. Because cached content was served wit
 
 ---
 
-## Root Cause
+## Root Cause — Pre-Optimization Without Measuring Total Cost of Ownership
 
-Pre-optimization. The caching strategy was introduced to reduce GitHub API calls and improve response latency. No Total Cost of Ownership analysis was performed. The cost of the optimization — stale state, incomplete flush, debugging opacity, trust erosion — exceeded the benefit by orders of magnitude.
+The caching strategy was introduced to reduce GitHub API calls and improve response latency. No Total Cost of Ownership analysis was performed. The cost of the optimization — stale state, incomplete flush, debugging opacity, trust erosion — exceeded the benefit by orders of magnitude.
 
 This is the named anti-pattern **Local Maxima Optimization (The Cache Trap)**: optimizing for a single metric (latency) while ignoring the full cost of the decision.
 
 ---
 
-## Irony
+## The Irony — The Creed vs. The Cache
 
 The tool whose entire purpose is to enforce epistemic discipline — to ensure agents observe before asserting, verify before claiming, and prove before confirming — was itself asserting without observation, claiming without verification, and confirming without proof.
 
@@ -74,7 +76,7 @@ The cache said: *"What I saw yesterday is close enough."*
 
 ---
 
-## Resolution
+## Resolution — Three Canonical Artifacts Created
 
 This incident led to the creation of:
 
@@ -84,7 +86,7 @@ This incident led to the creation of:
 
 ---
 
-## Lessons
+## Lessons — What This Incident Teaches About Caching and Trust
 
 1. A cache that can lie will lie. The question is not *if* but *when* and *for how long*.
 2. A flush mechanism that exists for correctness is an admission that the cache is a liability.