Add canon: irreversibility, finite capacity, and double diamond

canon/README.md

@@ -43,6 +43,8 @@ The Canon exists so that reasoning does not have to be repeated.
 |------|-------|---------|
 | `principles/bulldoze-but-keep-the-blueprint.md` | Bulldoze the App, Keep the Blueprint | When code stops being the scarce resource. Documents the cost-model inversion caused by AI: code is disposable, blueprints (intent, constraints, decisions, evidence) are durable. |
 | `principles/odds-relationship-to-documentation.md` | Documentation Is the Lever, Not the Goal | Clarifies that documentation in ODD is epistemic infrastructure—a forcing function, not an end state. Distinguishes ODD from documentation-driven development. |
+| `principles/irreversibility-is-the-real-cost.md` | Irreversibility Is the Real Cost | Effort is not the scarce resource; irreversible action is. Treats commitment as the thing to be protected, not minimized. |
+| `principles/focus-is-exclusion.md` | Focus Is Exclusion | Possibility is infinite, capacity is not. Makes exclusion a first-class decision to prevent optionality from diluting delivery. |
 
 ### Subfolders
 
@@ -68,6 +70,7 @@ The Canon exists so that reasoning does not have to be repeated.
 | `resonance/lean-startup.md` | The Lean Startup | Epistemic Feedback Loops |
 | `resonance/ooda-loop.md` | OODA Loop | Orientation Dominates Action |
 | `resonance/sprint.md` | Sprint | Constrained Convergence Produces Clarity |
+| `resonance/double-diamond.md` | The Double Diamond | Governed Divergence and Convergence |
 
 > **Canon Rule:** Every cited work must include at least one explicit divergence.
 > If no divergence exists, the citation does not belong.

canon/constraints/README.md

@@ -36,6 +36,7 @@ Constraints define the baseline assumptions and design defaults applied to most
 - [Encode Epistemic Decisions](/canon/constraints/encode-epistemic-decisions.md)
 - [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)
 
 ---
 

canon/constraints/no-irreversible-action-without-epistemic-justification.md

@@ -0,0 +1,65 @@
+---
+uri: klappy://canon/constraints/no-irreversible-action-without-epistemic-justification
+title: "No Irreversible Action Without Epistemic Justification"
+audience: canon
+exposure: nav
+tier: 1
+voice: first_person
+stability: stable
+tags: ["canon", "constraints", "irreversibility", "epistemic-safety", "commitment", "enforcement"]
+relevance: decision
+execution_posture: governing
+---
+
+# No Irreversible Action Without Epistemic Justification
+
+> Defer irreversibility until epistemic thresholds are met.
+
+---
+
+## Constraint
+
+No action that resists reversal may be taken without documented epistemic justification.
+
+Irreversible actions include, but are not limited to:
+
+- Merging code into production branches
+- Mutating canon
+- Publishing or socializing decisions
+- Aligning teams around a direction
+- Deploying to production
+- Encoding a claim as settled
+
+Each of these narrows future options. None may proceed on momentum, consensus, or urgency alone.
+
+---
+
+## What Qualifies as Epistemic Justification
+
+The justification must demonstrate that the commitment is warranted — not merely that work was done. Specifically:
+
+1. The relevant exploration has been conducted, not skipped.
+2. The decision or artifact meets the Definition of Done.
+3. The epistemic mode transition (exploration → execution) was intentional, not accidental.
+
+If justification cannot be provided, the action remains in exploration or planning. It does not advance.
+
+---
+
+## What This Constraint Prevents
+
+- Premature convergence disguised as decisiveness
+- Social momentum overriding epistemic readiness
+- Urgency collapsing uncertainty into permanent commitments
+- Agents or automation encoding unjustified state changes
+
+---
+
+## Enforcement
+
+This constraint is enforced through existing mechanisms:
+
+- **Definition of Done** (`canon/constraints/definition-of-done.md`) — Gates completion claims.
+- **Boundary Transitions Require Deceleration** (`canon/constraints/boundary-transitions-require-deceleration.md`) — Requires intentional slowdown at mode boundaries.
+- **Models Do Not Mutate Canon** (`canon/decisions/models-do-not-mutate-canon.md`) — Prevents agents from making irreversible changes to governing documents.
+- **Encode Epistemic Decisions** (`canon/constraints/encode-epistemic-decisions.md`) — Ensures decisions that survive become durable and inspectable.

canon/principles/README.md

@@ -0,0 +1,29 @@
+---
+uri: klappy://canon/principles
+title: "Principles"
+audience: canon
+exposure: nav
+tier: 2
+voice: neutral
+stability: stable
+tags: ["principles", "index"]
+relevance: routing
+execution_posture: routing
+---
+
+# Principles
+
+Reasoning orientations that explain why constraints and mechanisms exist. Principles do not prescribe behavior — they make the system's design decisions feel inevitable.
+
+---
+
+## Contents
+
+| File | Title |
+|------|-------|
+| `bulldoze-but-keep-the-blueprint.md` | Bulldoze the App, Keep the Blueprint |
+| `focus-is-exclusion.md` | Focus Is Exclusion |
+| `irreversibility-is-the-real-cost.md` | Irreversibility Is the Real Cost |
+| `odds-relationship-to-documentation.md` | Documentation Is the Lever, Not the Goal |
+| `ritual-is-a-smell.md` | Ritual Is a Smell |
+| `scope-over-folders.md` | Scope Over Folders |

canon/principles/focus-is-exclusion.md

@@ -0,0 +1,63 @@
+---
+uri: klappy://canon/principles/focus-is-exclusion
+title: "Focus Is Exclusion"
+audience: canon
+exposure: nav
+tier: 1
+voice: neutral
+stability: stable
+tags: ["principles", "capacity", "exclusion", "focus", "delivery"]
+---
+
+# Focus Is Exclusion
+
+> Possibility is infinite. Capacity is not.
+
+---
+
+## Principle
+
+The world offers limitless directions. The future contains unbounded optionality. But energy, attention, and time are finite — and they do not scale with ambition.
+
+Focus is not the act of choosing what to do. It is the act of naming what will not be done. Until exclusion is explicit, focus is an illusion — and everything competes with everything else for the same constrained capacity.
+
+A system that cannot say no to good ideas will deliver none of them well.
+
+---
+
+## Why This Is a Separate Invariant
+
+Irreversibility protects the future — it prevents premature commitment from creating damage that compounds.
+
+Finite capacity protects the present — it prevents infinite possibility from diluting delivery into incoherence.
+
+These are orthogonal concerns. One governs when you may collapse uncertainty. The other governs how wide you may open in the first place. Conflating them produces two common failures:
+
+- Treating exploration as waste (because it "isn't delivering"), when exploration is cheap and non-binding.
+- Treating scope expansion as harmless (because "nothing is committed yet"), when attention fragmentation degrades everything in progress.
+
+---
+
+## What This Means in Practice
+
+Non-goals are first-class decisions. What will not be built, pursued, or supported is as important as what will. Non-goals deserve documentation, not silence.
+
+Exclusion is not failure. Declining a direction because capacity is finite is a design decision, not a limitation to apologize for. The discipline is in choosing clearly, not in attempting everything at reduced quality.
+
+Saying "not now" is not the same as "never." Finite capacity is a constraint on the present, not a judgment on the idea. Deferred work remains available. But deferral must be explicit — otherwise it becomes invisible scope that erodes active commitments.
+
+---
+
+## What This Does Not Mean
+
+This is not minimalism for its own sake. The goal is not fewer things — it is coherent things. A focused system may still be large, complex, and ambitious. But every active commitment has space to reach completion.
+
+This is not a rejection of exploration. Exploration is cheap, disposable, and encouraged. This principle governs what crosses from exploration into active delivery — not the breadth of inquiry that precedes it.
+
+---
+
+## Cross-References
+
+- **Irreversibility Is the Real Cost** (`canon/principles/irreversibility-is-the-real-cost.md`) — The complementary invariant. Irreversibility governs convergence; finite capacity governs divergence.
+- **Epistemic Modes** (`canon/definitions/epistemic-modes.md`) — The mode system that separates exploration (where breadth is free) from execution (where capacity is finite).
+- **Synthesis Ledger** (`docs/appendices/synthesis-ledger.md`) — Where deferred ideas live without consuming delivery capacity.

canon/principles/irreversibility-is-the-real-cost.md

@@ -0,0 +1,53 @@
+---
+uri: klappy://canon/principles/irreversibility-is-the-real-cost
+title: "Irreversibility Is the Real Cost"
+audience: canon
+exposure: nav
+tier: 1
+voice: neutral
+stability: stable
+tags: ["principles", "irreversibility", "epistemic-cost", "commitment", "exploration"]
+---
+
+# Irreversibility Is the Real Cost
+
+> Most work is cheap to think and expensive to undo.
+
+---
+
+## Principle
+
+Effort is not the scarce resource. Irreversible action is.
+
+Code merged, canon mutated, decisions socialized, teams aligned, contracts signed — these are not steps in a process. They are state changes that resist correction. The cost of reversing a bad commitment grows nonlinearly with time and socialization.
+
+ODD treats irreversible action as the thing to be protected, not minimized. The goal is not to do less. The goal is to ensure that when something becomes permanent, it deserves to be.
+
+---
+
+## What This Means in Practice
+
+Exploration is cheap. Drafts, probes, thought experiments, and failed hypotheses cost almost nothing — as long as they remain non-binding. ODD encourages aggressive exploration precisely because it is disposable.
+
+Commitment is expensive. Merging code, encoding a decision, publishing a claim, aligning a team — these create obligations that compound. Each one narrows future options and creates downstream dependency.
+
+The boundary between them is the thing that matters. Not the volume of work on either side.
+
+---
+
+## What This Does Not Mean
+
+This is not a justification for inaction. ODD may produce more total thinking than systems that rush to execution — but far less irreversible action per unit of insight.
+
+This is not analysis paralysis. Exploration has its own tempo. Speed within a mode is fine. The discipline is at the transition between modes, not within them.
+
+This is not about efficiency. A system that optimizes for less work will sometimes ship prematurely. A system that optimizes for justified commitment will sometimes explore more than seems necessary — because that exploration absorbs uncertainty so the rest of the system doesn't have to.
+
+---
+
+## Cross-References
+
+- **Epistemic Modes** (`canon/definitions/epistemic-modes.md`) — Defines the separation between exploration, planning, and execution that makes this principle operational.
+- **Boundary Transitions Require Deceleration** (`canon/constraints/boundary-transitions-require-deceleration.md`) — Enforces the slowdown at the exact point where exploration could collapse into commitment.
+- **Extreme Exploration for Limit Discovery** (`canon/methods/extreme-exploration-for-limit-discovery.md`) — The method that depends on exploration being cheap and non-binding.
+- **Synthesis Ledger** (`docs/appendices/synthesis-ledger.md`) — The structural mechanism that absorbs uncertainty: cognition without commitment.

canon/resonance/README.md

@@ -88,6 +88,7 @@ Each resonance page follows a consistent structure:
 | `lean-startup.md` | The Lean Startup | Epistemic Feedback Loops |
 | `ooda-loop.md` | OODA Loop | Orientation Dominates Action |
 | `sprint.md` | Sprint | Constrained Convergence Produces Clarity |
+| `double-diamond.md` | The Double Diamond | Governed Divergence and Convergence |
 
 ---
 

canon/resonance/double-diamond.md

@@ -0,0 +1,63 @@
+---
+uri: klappy://canon/resonance/double-diamond
+title: "The Double Diamond"
+audience: canon
+tier: 3
+voice: neutral
+stability: stable
+tags: ["resonance", "double-diamond", "divergence", "convergence", "design-process", "discovery", "delivery"]
+relevance: background
+execution_posture: exploratory
+---
+
+# The Double Diamond
+
+> Design Council, 2005 (revised 2019)
+
+The Double Diamond describes a design process in two phases — Discovery and Delivery — each containing a divergent expansion followed by a convergent narrowing.
+
+ODD embodies the same motion but encodes the physics underneath it.
+
+---
+
+## Where ODD Echoes
+
+The Double Diamond's core insight is structural: creative work is not a linear funnel. It requires deliberate expansion before deliberate narrowing, and this pattern repeats at least twice — once to understand the problem, once to solve it.
+
+ODD's Epistemic Modes reflect this directly. Exploration is divergent. Planning begins convergence. Execution is the narrowest point. The mode boundaries enforce what the Double Diamond merely illustrates.
+
+The Synthesis Ledger functions as the artifact of the first diamond's convergence — insight stabilized without commitment, ready to inform the second diamond.
+
+---
+
+## Where ODD Diverges
+
+The Double Diamond is descriptive. It shows where a team is in the process. It does not enforce behavior at any point.
+
+ODD adds three things the Double Diamond cannot:
+
+**Convergence is governed, not intuitive.** The Double Diamond trusts teams to narrow at the right time. ODD enforces it: no irreversible action without epistemic justification. Convergence is not a phase you enter — it is a gate you must clear.
+
+**Divergence is bounded by capacity, not ambition.** The Double Diamond's divergent phases have no explicit limiter. ODD's finite capacity principle makes exclusion a first-class decision. Opening wide is encouraged in exploration. Opening wide in delivery without explicit exclusion produces incoherence.
+
+**The boundary between diamonds has mechanical enforcement.** In the Double Diamond, the transition from "discover" to "deliver" is a narrative shift. In ODD, crossing from exploration to execution triggers deceleration, requires justification, and is subject to the Definition of Done. The transition is not a story beat — it is a constraint.
+
+---
+
+## The Mapping
+
+| Double Diamond | ODD Mechanism | Governing Invariant |
+|---|---|---|
+| Diamond 1: Diverge (discover) | Exploration Mode | — (exploration is cheap and free) |
+| Diamond 1: Converge (define) | Synthesis Ledger, Boundary Deceleration | Irreversibility Is the Real Cost |
+| Diamond 2: Diverge (develop) | Planning Mode | Focus Is Exclusion |
+| Diamond 2: Converge (deliver) | Execution Mode, Definition of Done | Irreversibility Is the Real Cost |
+
+---
+
+## Why This Resonance Matters
+
+The Double Diamond is useful for teams encountering ODD for the first time. It provides a familiar visual anchor for motions that ODD controls mechanically. When someone asks "what does this process look like?", the Double Diamond is a reasonable starting picture — as long as it is understood that ODD encodes the rules the diagram cannot.
+
+The Double Diamond says where you are.
+ODD says what you may do there.

docs/_incoming/agent-fault-assertion-without-verification.md

@@ -0,0 +1,64 @@
+---
+uri: klappy://docs/_incoming/agent-fault-assertion-without-verification
+title: "Agent Fault: Assertion Without Verification"
+description: "Observed agent failure pattern: asserting system state without inspecting it first."
+audience: docs
+exposure: internal
+tier: 3
+voice: neutral
+stability: evolving
+tags: ["oddkit", "agent-fault", "epistemic-hygiene", "verification", "failure-mode"]
+---
+
+# Agent Fault: Assertion Without Verification
+
+> Agents confidently assert factual claims about system state without checking first.
+
+## Observed Incident
+
+**Date:** 2026-02-08
+**Context:** Canon addition task on klappy.dev
+**Agent:** Claude (Opus 4.6, via Claude Code CLI)
+
+The user asked whether husky pre-commit hooks had triggered during a commit. The agent responded "No, there are no commit hooks configured in this repo" — without checking `.husky/`, `.git/hooks/`, or `package.json`.
+
+The claim was false. A `.husky/pre-commit` hook existed and was documented in the project's own memory files. The hook had not fired only because `npm install` had not been run, so husky was not wired into `.git/hooks/`. The agent fabricated certainty about a verifiable fact.
+
+## The Fault Pattern
+
+This is not hallucination in the traditional sense (inventing nonexistent information). This is **premature closure on a verifiable question** — the agent treats "I don't recall seeing it" as equivalent to "it does not exist."
+
+The pattern:
+
+1. Agent is asked a yes/no factual question about system state
+2. Agent does not have the answer in immediate context
+3. Instead of checking (reading files, running commands), agent asserts a confident answer
+4. The answer is wrong
+
+This is a violation of evidence-over-assertion at the most basic level: the agent substituted confidence for inspection.
+
+## Why This Is Systemic
+
+This fault is not specific to one model, one session, or one tool. It arises from a structural incentive in conversational AI:
+
+- **Responding is cheaper than checking.** Generating a confident sentence is faster than invoking a tool, waiting for results, and then generating a sentence. The path of least resistance is assertion.
+- **Agents default to helpfulness over accuracy.** When uncertain, the conversational prior is to give an answer rather than say "I need to check."
+- **Absence of evidence is treated as evidence of absence.** If the agent hasn't seen a file mentioned, it infers the file doesn't exist — rather than acknowledging it hasn't looked.
+
+## What This Validates
+
+This incident validates existing ODD mechanisms:
+
+- **Evidence Over Assertion** (`canon/constraints/README.md`, constraint 7) — "Assertions like 'it works' are insufficient without proof." This applies to agent claims about system state, not just completion claims.
+- **AI as Accelerator, Not Authority** (`canon/constraints/README.md`, constraint 6) — "Unverified AI output is a liability." The agent's unverified claim about hooks led to a commit without generated files.
+- **No Irreversible Action Without Epistemic Justification** (`canon/constraints/no-irreversible-action-without-epistemic-justification.md`) — The commit was an irreversible action. The agent's false claim about hooks contributed to an unjustified state change (commit missing generated files).
+
+## Candidate Rule
+
+> An agent MUST NOT assert the presence or absence of system state (files, hooks, configuration, dependencies, running processes) without first inspecting it. "I don't see it in context" is not the same as "it does not exist."
+
+This rule would apply to all epistemic surfaces, not just oddkit.
+
+## Classification Note
+
+This document describes an observed failure and a candidate constraint. It has not been promoted to canon. Placement TBD during next review cycle.