From 97f5111fb834320b7bd6ea2985a0e01d63d4625f Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 8 Feb 2026 16:49:43 +0000 Subject: [PATCH 1/4] Add canon: irreversibility, finite capacity, and double diamond Two new principles encoding previously implicit invariants: - Irreversibility Is the Real Cost (commitment as the scarce resource) - Focus Is Exclusion (finite capacity requires explicit exclusion) One new constraint: - No Irreversible Action Without Epistemic Justification One new resonance page: - The Double Diamond (Design Council, governed divergence/convergence) Also creates canon/principles/README.md index and registers all new entries in canon/README.md, constraints/README.md, and resonance/README.md. https://claude.ai/code/session_01Ka6iBFkSizb7NDqXaBYk4F --- canon/README.md | 3 + canon/constraints/README.md | 1 + ...-action-without-epistemic-justification.md | 65 +++++++++++++++++++ canon/principles/README.md | 29 +++++++++ canon/principles/focus-is-exclusion.md | 63 ++++++++++++++++++ .../irreversibility-is-the-real-cost.md | 53 +++++++++++++++ canon/resonance/README.md | 1 + canon/resonance/double-diamond.md | 63 ++++++++++++++++++ 8 files changed, 278 insertions(+) create mode 100644 canon/constraints/no-irreversible-action-without-epistemic-justification.md create mode 100644 canon/principles/README.md create mode 100644 canon/principles/focus-is-exclusion.md create mode 100644 canon/principles/irreversibility-is-the-real-cost.md create mode 100644 canon/resonance/double-diamond.md diff --git a/canon/README.md b/canon/README.md index cde5b905..76c7aca9 100644 --- a/canon/README.md +++ b/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. diff --git a/canon/constraints/README.md b/canon/constraints/README.md index 660e29b3..98a35199 100644 --- a/canon/constraints/README.md +++ b/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) --- diff --git a/canon/constraints/no-irreversible-action-without-epistemic-justification.md b/canon/constraints/no-irreversible-action-without-epistemic-justification.md new file mode 100644 index 00000000..7ee3cc68 --- /dev/null +++ b/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. diff --git a/canon/principles/README.md b/canon/principles/README.md new file mode 100644 index 00000000..96eb2def --- /dev/null +++ b/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 | diff --git a/canon/principles/focus-is-exclusion.md b/canon/principles/focus-is-exclusion.md new file mode 100644 index 00000000..d667e026 --- /dev/null +++ b/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. diff --git a/canon/principles/irreversibility-is-the-real-cost.md b/canon/principles/irreversibility-is-the-real-cost.md new file mode 100644 index 00000000..253062e8 --- /dev/null +++ b/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. diff --git a/canon/resonance/README.md b/canon/resonance/README.md index ae4932c9..da4d8032 100644 --- a/canon/resonance/README.md +++ b/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 | --- diff --git a/canon/resonance/double-diamond.md b/canon/resonance/double-diamond.md new file mode 100644 index 00000000..85c45de4 --- /dev/null +++ b/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. From be38ba449d0130448679eb9db3b4b134bcdb4b1b Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 8 Feb 2026 16:54:07 +0000 Subject: [PATCH 2/4] Add generated files from pre-commit hooks (sync, book, docs:index) https://claude.ai/code/session_01Ka6iBFkSizb7NDqXaBYk4F --- klappy-dev-book-export.md | 319 +++++++++++++++- public/_compiled/index/docs.json | 340 ++++++++++++++++-- public/content/canon/README.md | 3 + public/content/canon/constraints/README.md | 1 + ...-action-without-epistemic-justification.md | 65 ++++ public/content/canon/principles/README.md | 29 ++ .../canon/principles/focus-is-exclusion.md | 63 ++++ .../irreversibility-is-the-real-cost.md | 53 +++ public/content/canon/resonance/README.md | 1 + .../content/canon/resonance/double-diamond.md | 63 ++++ public/content/manifest.json | 90 +++++ 11 files changed, 985 insertions(+), 42 deletions(-) create mode 100644 public/content/canon/constraints/no-irreversible-action-without-epistemic-justification.md create mode 100644 public/content/canon/principles/README.md create mode 100644 public/content/canon/principles/focus-is-exclusion.md create mode 100644 public/content/canon/principles/irreversibility-is-the-real-cost.md create mode 100644 public/content/canon/resonance/double-diamond.md diff --git a/klappy-dev-book-export.md b/klappy-dev-book-export.md index f9cb49fe..48d59fac 100644 --- a/klappy-dev-book-export.md +++ b/klappy-dev-book-export.md @@ -5,8 +5,8 @@ ================================================================================ -Generated: 2026-02-07T04:19:06.874Z -Total Files: 284 +Generated: 2026-02-08T16:54:08.948Z +Total Files: 289 This is a documentation export of all markdown files from the klappy.dev repository. It includes lane guidance docs but excludes implementation @@ -20,7 +20,7 @@ details (attempts, version folders, source code). - **Root** (1 files) - **.cursor** (1 files) - **About** (6 files) -- **Canon** (72 files) +- **Canon** (77 files) - **Documentation** (102 files) - **Infrastructure** (10 files) - **Interfaces & Contracts** (6 files) @@ -16207,6 +16207,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 @@ -16232,6 +16234,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. @@ -18249,6 +18252,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) --- @@ -19553,6 +19557,78 @@ and rests on: +-------------------------------------------------------------------------------- +📄 File: canon/constraints/no-irreversible-action-without-epistemic-justification.md +-------------------------------------------------------------------------------- + +--- +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. + + + -------------------------------------------------------------------------------- 📄 File: canon/constraints/odd-is-epistemic-os-not-values.md -------------------------------------------------------------------------------- @@ -23519,6 +23595,42 @@ They stop where explanation would begin. +-------------------------------------------------------------------------------- +📄 File: canon/principles/README.md +-------------------------------------------------------------------------------- + +--- +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 | + + + -------------------------------------------------------------------------------- 📄 File: canon/principles/bulldoze-but-keep-the-blueprint.md -------------------------------------------------------------------------------- @@ -23780,6 +23892,136 @@ The question that remains: +-------------------------------------------------------------------------------- +📄 File: canon/principles/focus-is-exclusion.md +-------------------------------------------------------------------------------- + +--- +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. + + + +-------------------------------------------------------------------------------- +📄 File: canon/principles/irreversibility-is-the-real-cost.md +-------------------------------------------------------------------------------- + +--- +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. + + + -------------------------------------------------------------------------------- 📄 File: canon/principles/odds-relationship-to-documentation.md -------------------------------------------------------------------------------- @@ -24119,6 +24361,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 | --- @@ -24395,6 +24638,76 @@ ODD treats antifragility as insufficient on its own. Stress must be captured, in +-------------------------------------------------------------------------------- +📄 File: canon/resonance/double-diamond.md +-------------------------------------------------------------------------------- + +--- +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. + + + -------------------------------------------------------------------------------- 📄 File: canon/resonance/lean-startup.md -------------------------------------------------------------------------------- diff --git a/public/_compiled/index/docs.json b/public/_compiled/index/docs.json index 8175fc14..6179c248 100644 --- a/public/_compiled/index/docs.json +++ b/public/_compiled/index/docs.json @@ -1,6 +1,6 @@ { "version": "1.1", - "generated_at": "2026-02-07T04:19:07.514Z", + "generated_at": "2026-02-08T16:54:09.679Z", "description": "Fast-lookup index for Librarian retrieval. Per docs/agents/librarian/contract.md", "schema_notes": { "authority_band": "Resolved authority (frontmatter override > inferred from root)", @@ -30,17 +30,17 @@ } }, "stats": { - "total_documents": 205, - "with_frontmatter": 197, - "with_headings": 201, + "total_documents": 210, + "with_frontmatter": 202, + "with_headings": 206, "by_root": { - "canon": 71, + "canon": 76, "docs": 102, "interfaces": 6, "odd": 26 }, "by_authority": { - "governing": 97, + "governing": 102, "operational": 108 }, "with_authority_override": 0, @@ -2874,6 +2874,62 @@ "heading_count": 6, "has_frontmatter": true }, + { + "path": "canon/constraints/no-irreversible-action-without-epistemic-justification.md", + "root": "canon", + "authority_band": "governing", + "authority_inferred": "governing", + "uri": "klappy://canon/constraints/no-irreversible-action-without-epistemic-justification", + "title": "No Irreversible Action Without Epistemic Justification", + "subtitle": "Defer irreversibility until epistemic thresholds are met.", + "tags": [ + "canon", + "constraints", + "irreversibility", + "epistemic-safety", + "commitment", + "enforcement" + ], + "acronyms": [ + "niawej" + ], + "stability": "stable", + "tier": "1", + "audience": "canon", + "exposure": "nav", + "voice": "first_person", + "relevance": "decision", + "execution_posture": "governing", + "headings": [ + { + "level": 1, + "text": "No Irreversible Action Without Epistemic Justification", + "line": 2 + }, + { + "level": 2, + "text": "Constraint", + "line": 8 + }, + { + "level": 2, + "text": "What Qualifies as Epistemic Justification", + "line": 25 + }, + { + "level": 2, + "text": "What This Constraint Prevents", + "line": 37 + }, + { + "level": 2, + "text": "Enforcement", + "line": 46 + } + ], + "heading_count": 5, + "has_frontmatter": true + }, { "path": "canon/constraints/odd-is-epistemic-os-not-values.md", "root": "canon", @@ -2987,92 +3043,92 @@ { "level": 2, "text": "Operating Constraints", - "line": 30 + "line": 31 }, { "level": 2, "text": "Defaults", - "line": 45 + "line": 46 }, { "level": 2, "text": "Failure Modes", - "line": 56 + "line": 57 }, { "level": 2, "text": "Verification", - "line": 67 + "line": 68 }, { "level": 2, "text": "Content", - "line": 77 + "line": 78 }, { "level": 2, "text": "1. Offline-First (Default)", - "line": 98 + "line": 99 }, { "level": 2, "text": "2. Long Timelines & Changing Ownership", - "line": 124 + "line": 125 }, { "level": 2, "text": "3. Maintainability Over Cleverness", - "line": 149 + "line": 150 }, { "level": 2, "text": "4. Interoperability Over Feature Completeness", - "line": 168 + "line": 169 }, { "level": 2, "text": "5. Stateless or Low-State by Default", - "line": 192 + "line": 193 }, { "level": 2, "text": "6. AI as Accelerator, Not Authority", - "line": 216 + "line": 217 }, { "level": 2, "text": "7. Evidence Over Assertion", - "line": 239 + "line": 240 }, { "level": 2, "text": "8. UX Is Contextual, Not Universal", - "line": 257 + "line": 258 }, { "level": 2, "text": "9. Ephemeral Artifacts Are Acceptable", - "line": 281 + "line": 282 }, { "level": 2, "text": "10. Explicit Tradeoffs", - "line": 301 + "line": 302 }, { "level": 2, "text": "11. Lane Self-Containment", - "line": 319 + "line": 320 }, { "level": 2, "text": "💡 Closing Note", - "line": 344 + "line": 345 }, { "level": 2, "text": "✅ Status", - "line": 355 + "line": 356 } ], "heading_count": 21, @@ -5812,6 +5868,121 @@ "heading_count": 10, "has_frontmatter": true }, + { + "path": "canon/principles/focus-is-exclusion.md", + "root": "canon", + "authority_band": "governing", + "authority_inferred": "governing", + "uri": "klappy://canon/principles/focus-is-exclusion", + "title": "Focus Is Exclusion", + "subtitle": "Possibility is infinite. Capacity is not.", + "tags": [ + "principles", + "capacity", + "exclusion", + "focus", + "delivery" + ], + "acronyms": [ + "fe" + ], + "stability": "stable", + "tier": "1", + "audience": "canon", + "exposure": "nav", + "voice": "neutral", + "relevance": null, + "execution_posture": null, + "headings": [ + { + "level": 1, + "text": "Focus Is Exclusion", + "line": 2 + }, + { + "level": 2, + "text": "Principle", + "line": 8 + }, + { + "level": 2, + "text": "Why This Is a Separate Invariant", + "line": 18 + }, + { + "level": 2, + "text": "What This Means in Practice", + "line": 31 + }, + { + "level": 2, + "text": "What This Does Not Mean", + "line": 41 + }, + { + "level": 2, + "text": "Cross-References", + "line": 49 + } + ], + "heading_count": 6, + "has_frontmatter": true + }, + { + "path": "canon/principles/irreversibility-is-the-real-cost.md", + "root": "canon", + "authority_band": "governing", + "authority_inferred": "governing", + "uri": "klappy://canon/principles/irreversibility-is-the-real-cost", + "title": "Irreversibility Is the Real Cost", + "subtitle": "Most work is cheap to think and expensive to undo.", + "tags": [ + "principles", + "irreversibility", + "epistemic-cost", + "commitment", + "exploration" + ], + "acronyms": [ + "irc" + ], + "stability": "stable", + "tier": "1", + "audience": "canon", + "exposure": "nav", + "voice": "neutral", + "relevance": null, + "execution_posture": null, + "headings": [ + { + "level": 1, + "text": "Irreversibility Is the Real Cost", + "line": 2 + }, + { + "level": 2, + "text": "Principle", + "line": 8 + }, + { + "level": 2, + "text": "What This Means in Practice", + "line": 18 + }, + { + "level": 2, + "text": "What This Does Not Mean", + "line": 28 + }, + { + "level": 2, + "text": "Cross-References", + "line": 38 + } + ], + "heading_count": 5, + "has_frontmatter": true + }, { "path": "canon/principles/odds-relationship-to-documentation.md", "root": "canon", @@ -5861,6 +6032,40 @@ "heading_count": 5, "has_frontmatter": true }, + { + "path": "canon/principles/README.md", + "root": "canon", + "authority_band": "governing", + "authority_inferred": "governing", + "uri": "klappy://canon/principles", + "title": "Principles", + "subtitle": null, + "tags": [ + "principles", + "index" + ], + "stability": "stable", + "tier": "2", + "audience": "canon", + "exposure": "nav", + "voice": "neutral", + "relevance": "routing", + "execution_posture": "routing", + "headings": [ + { + "level": 1, + "text": "Principles", + "line": 2 + }, + { + "level": 2, + "text": "Contents", + "line": 8 + } + ], + "heading_count": 2, + "has_frontmatter": true + }, { "path": "canon/principles/ritual-is-a-smell.md", "root": "canon", @@ -6035,67 +6240,67 @@ { "level": 3, "text": "Subfolders", - "line": 35 + "line": 37 }, { "level": 3, "text": "Resonance (External Alignment & Divergence)", - "line": 51 + "line": 53 }, { "level": 2, "text": "🚀 Start Here", - "line": 65 + "line": 68 }, { "level": 2, "text": "📖 Precedence & Interpretation", - "line": 75 + "line": 78 }, { "level": 2, "text": "🧠 What the Canon Is (and Is Not)", - "line": 89 + "line": 92 }, { "level": 2, "text": "🔒 Public vs Internal Boundary", - "line": 106 + "line": 109 }, { "level": 2, "text": "📋 Meta Rules", - "line": 115 + "line": 118 }, { "level": 2, "text": "🔄 Stability & Change Philosophy", - "line": 136 + "line": 139 }, { "level": 2, "text": "⚠️ Confidence & Drift Risk", - "line": 149 + "line": 152 }, { "level": 2, "text": "🚫 What Is Intentionally Undefined", - "line": 175 + "line": 178 }, { "level": 2, "text": "📦 For Pack Compilation", - "line": 187 + "line": 190 }, { "level": 2, "text": "🔗 See Also", - "line": 198 + "line": 201 }, { "level": 2, "text": "✅ Status", - "line": 206 + "line": 209 } ], "heading_count": 17, @@ -6168,6 +6373,63 @@ "heading_count": 8, "has_frontmatter": true }, + { + "path": "canon/resonance/double-diamond.md", + "root": "canon", + "authority_band": "governing", + "authority_inferred": "governing", + "uri": "klappy://canon/resonance/double-diamond", + "title": "The Double Diamond", + "subtitle": "Design Council, 2005 (revised 2019)", + "tags": [ + "resonance", + "double-diamond", + "divergence", + "convergence", + "design-process", + "discovery", + "delivery" + ], + "acronyms": [ + "dd" + ], + "stability": "stable", + "tier": "3", + "audience": "canon", + "exposure": null, + "voice": "neutral", + "relevance": "background", + "execution_posture": "exploratory", + "headings": [ + { + "level": 1, + "text": "The Double Diamond", + "line": 2 + }, + { + "level": 2, + "text": "Where ODD Echoes", + "line": 12 + }, + { + "level": 2, + "text": "Where ODD Diverges", + "line": 22 + }, + { + "level": 2, + "text": "The Mapping", + "line": 36 + }, + { + "level": 2, + "text": "Why This Resonance Matters", + "line": 47 + } + ], + "heading_count": 5, + "has_frontmatter": true + }, { "path": "canon/resonance/lean-startup.md", "root": "canon", @@ -6371,12 +6633,12 @@ { "level": 2, "text": "What Resonance Is Not", - "line": 82 + "line": 83 }, { "level": 2, "text": "See Also", - "line": 97 + "line": 98 } ], "heading_count": 9, diff --git a/public/content/canon/README.md b/public/content/canon/README.md index cde5b905..76c7aca9 100644 --- a/public/content/canon/README.md +++ b/public/content/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. diff --git a/public/content/canon/constraints/README.md b/public/content/canon/constraints/README.md index 660e29b3..98a35199 100644 --- a/public/content/canon/constraints/README.md +++ b/public/content/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) --- diff --git a/public/content/canon/constraints/no-irreversible-action-without-epistemic-justification.md b/public/content/canon/constraints/no-irreversible-action-without-epistemic-justification.md new file mode 100644 index 00000000..7ee3cc68 --- /dev/null +++ b/public/content/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. diff --git a/public/content/canon/principles/README.md b/public/content/canon/principles/README.md new file mode 100644 index 00000000..96eb2def --- /dev/null +++ b/public/content/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 | diff --git a/public/content/canon/principles/focus-is-exclusion.md b/public/content/canon/principles/focus-is-exclusion.md new file mode 100644 index 00000000..d667e026 --- /dev/null +++ b/public/content/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. diff --git a/public/content/canon/principles/irreversibility-is-the-real-cost.md b/public/content/canon/principles/irreversibility-is-the-real-cost.md new file mode 100644 index 00000000..253062e8 --- /dev/null +++ b/public/content/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. diff --git a/public/content/canon/resonance/README.md b/public/content/canon/resonance/README.md index ae4932c9..da4d8032 100644 --- a/public/content/canon/resonance/README.md +++ b/public/content/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 | --- diff --git a/public/content/canon/resonance/double-diamond.md b/public/content/canon/resonance/double-diamond.md new file mode 100644 index 00000000..85c45de4 --- /dev/null +++ b/public/content/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. diff --git a/public/content/manifest.json b/public/content/manifest.json index a119e268..966800b5 100644 --- a/public/content/manifest.json +++ b/public/content/manifest.json @@ -705,6 +705,24 @@ "faq" ] }, + { + "uri": "klappy://canon/principles/focus-is-exclusion", + "path": "/canon/principles/focus-is-exclusion.md", + "title": "Focus Is Exclusion", + "type": "text/markdown", + "audience": "canon", + "exposure": "nav", + "tier": 1, + "voice": "neutral", + "stability": "stable", + "tags": [ + "principles", + "capacity", + "exclusion", + "focus", + "delivery" + ] + }, { "uri": "klappy://canon/apocrypha/fragments-of-the-canon/fragment-03", "path": "/canon/apocrypha/fragments-of-the-canon/fragment-03-nothing-exceeded-the-threshold.md", @@ -762,6 +780,24 @@ "epistemic-discipline" ] }, + { + "uri": "klappy://canon/principles/irreversibility-is-the-real-cost", + "path": "/canon/principles/irreversibility-is-the-real-cost.md", + "title": "Irreversibility Is the Real Cost", + "type": "text/markdown", + "audience": "canon", + "exposure": "nav", + "tier": 1, + "voice": "neutral", + "stability": "stable", + "tags": [ + "principles", + "irreversibility", + "epistemic-cost", + "commitment", + "exploration" + ] + }, { "uri": "klappy://canon/constraints/meaning-must-not-depend-on-path", "path": "/canon/constraints/meaning-must-not-depend-on-path.md", @@ -947,6 +983,25 @@ "governance" ] }, + { + "uri": "klappy://canon/constraints/no-irreversible-action-without-epistemic-justification", + "path": "/canon/constraints/no-irreversible-action-without-epistemic-justification.md", + "title": "No Irreversible Action Without Epistemic Justification", + "type": "text/markdown", + "audience": "canon", + "exposure": "nav", + "tier": 1, + "voice": "first_person", + "stability": "stable", + "tags": [ + "canon", + "constraints", + "irreversibility", + "epistemic-safety", + "commitment", + "enforcement" + ] + }, { "uri": "klappy://canon/apocrypha/reconstructions/fragment-03", "path": "/canon/apocrypha/reconstructions/fragment-03-recon.md", @@ -1155,6 +1210,21 @@ "methodology" ] }, + { + "uri": "klappy://canon/principles", + "path": "/canon/principles/README.md", + "title": "Principles", + "type": "text/markdown", + "audience": "canon", + "exposure": "nav", + "tier": 2, + "voice": "neutral", + "stability": "stable", + "tags": [ + "principles", + "index" + ] + }, { "uri": "klappy://odd/appendices/progressive-elevation", "path": "/odd/appendices/progressive-elevation.md", @@ -1417,6 +1487,26 @@ "cinematic" ] }, + { + "uri": "klappy://canon/resonance/double-diamond", + "path": "/canon/resonance/double-diamond.md", + "title": "The Double Diamond", + "type": "text/markdown", + "audience": "canon", + "exposure": "nav", + "tier": 3, + "voice": "neutral", + "stability": "stable", + "tags": [ + "resonance", + "double-diamond", + "divergence", + "convergence", + "design-process", + "discovery", + "delivery" + ] + }, { "uri": "klappy://canon/apocrypha/reconstructions/fragments-of-the-canon/fragment-02-recon", "path": "/canon/apocrypha/reconstructions/fragment-02-recon.md", From 2ef50ecdc9763887c380525b7eb3e0f849d6e033 Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 8 Feb 2026 16:58:06 +0000 Subject: [PATCH 3/4] Document agent fault: assertion without verification Observed failure where agent asserted system state (no hooks exist) without inspecting files first. Documents the pattern, incident, and candidate constraint for future review. https://claude.ai/code/session_01Ka6iBFkSizb7NDqXaBYk4F --- ...nt-fault-assertion-without-verification.md | 57 ++++++++++++++ klappy-dev-book-export.md | 70 ++++++++++++++++- public/_compiled/index/docs.json | 77 +++++++++++++++++-- 3 files changed, 195 insertions(+), 9 deletions(-) create mode 100644 docs/_incoming/agent-fault-assertion-without-verification.md diff --git a/docs/_incoming/agent-fault-assertion-without-verification.md b/docs/_incoming/agent-fault-assertion-without-verification.md new file mode 100644 index 00000000..dc0510f0 --- /dev/null +++ b/docs/_incoming/agent-fault-assertion-without-verification.md @@ -0,0 +1,57 @@ +--- +title: "Agent Fault: Assertion Without Verification" +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. diff --git a/klappy-dev-book-export.md b/klappy-dev-book-export.md index 48d59fac..ca6d3901 100644 --- a/klappy-dev-book-export.md +++ b/klappy-dev-book-export.md @@ -5,8 +5,8 @@ ================================================================================ -Generated: 2026-02-08T16:54:08.948Z -Total Files: 289 +Generated: 2026-02-08T16:58:07.307Z +Total Files: 290 This is a documentation export of all markdown files from the klappy.dev repository. It includes lane guidance docs but excludes implementation @@ -21,7 +21,7 @@ details (attempts, version folders, source code). - **.cursor** (1 files) - **About** (6 files) - **Canon** (77 files) -- **Documentation** (102 files) +- **Documentation** (103 files) - **Infrastructure** (10 files) - **Interfaces & Contracts** (6 files) - **ODD (Outcomes-Driven Development)** (26 files) @@ -1763,6 +1763,70 @@ This folder is removed (or archived) when: +-------------------------------------------------------------------------------- +📄 File: docs/_incoming/agent-fault-assertion-without-verification.md +-------------------------------------------------------------------------------- + +--- +title: "Agent Fault: Assertion Without Verification" +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. + + + -------------------------------------------------------------------------------- 📄 File: docs/agent-architecture/sub-agents.md -------------------------------------------------------------------------------- diff --git a/public/_compiled/index/docs.json b/public/_compiled/index/docs.json index 6179c248..13e4080c 100644 --- a/public/_compiled/index/docs.json +++ b/public/_compiled/index/docs.json @@ -1,6 +1,6 @@ { "version": "1.1", - "generated_at": "2026-02-08T16:54:09.679Z", + "generated_at": "2026-02-08T16:58:07.951Z", "description": "Fast-lookup index for Librarian retrieval. Per docs/agents/librarian/contract.md", "schema_notes": { "authority_band": "Resolved authority (frontmatter override > inferred from root)", @@ -30,18 +30,18 @@ } }, "stats": { - "total_documents": 210, - "with_frontmatter": 202, - "with_headings": 206, + "total_documents": 211, + "with_frontmatter": 203, + "with_headings": 207, "by_root": { "canon": 76, - "docs": 102, + "docs": 103, "interfaces": 6, "odd": 26 }, "by_authority": { "governing": 102, - "operational": 108 + "operational": 109 }, "with_authority_override": 0, "with_authority_warning": 0 @@ -6818,6 +6818,71 @@ "heading_count": 16, "has_frontmatter": true }, + { + "path": "docs/_incoming/agent-fault-assertion-without-verification.md", + "root": "docs", + "authority_band": "operational", + "authority_inferred": "operational", + "uri": null, + "title": "Agent Fault: Assertion Without Verification", + "subtitle": "Agents confidently assert factual claims about system state without checking first.", + "tags": [ + "oddkit", + "agent-fault", + "epistemic-hygiene", + "verification", + "failure-mode" + ], + "acronyms": [ + "afawv" + ], + "stability": null, + "tier": null, + "audience": null, + "exposure": null, + "voice": null, + "relevance": null, + "execution_posture": null, + "headings": [ + { + "level": 1, + "text": "Agent Fault: Assertion Without Verification", + "line": 2 + }, + { + "level": 2, + "text": "Observed Incident", + "line": 6 + }, + { + "level": 2, + "text": "The Fault Pattern", + "line": 16 + }, + { + "level": 2, + "text": "Why This Is Systemic", + "line": 29 + }, + { + "level": 2, + "text": "What This Validates", + "line": 37 + }, + { + "level": 2, + "text": "Candidate Rule", + "line": 45 + }, + { + "level": 2, + "text": "Classification Note", + "line": 51 + } + ], + "heading_count": 7, + "has_frontmatter": true + }, { "path": "docs/_incoming/README.md", "root": "docs", From 3e1f0bef875bceca8de69f3d5107868355a4dbde Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 8 Feb 2026 16:59:58 +0000 Subject: [PATCH 4/4] Add standard frontmatter to agent fault document Adds uri, description, audience, exposure, tier, voice, stability fields to match repo conventions. https://claude.ai/code/session_01Ka6iBFkSizb7NDqXaBYk4F --- .../agent-fault-assertion-without-verification.md | 7 +++++++ klappy-dev-book-export.md | 9 ++++++++- public/_compiled/index/docs.json | 14 +++++++------- 3 files changed, 22 insertions(+), 8 deletions(-) diff --git a/docs/_incoming/agent-fault-assertion-without-verification.md b/docs/_incoming/agent-fault-assertion-without-verification.md index dc0510f0..613b2770 100644 --- a/docs/_incoming/agent-fault-assertion-without-verification.md +++ b/docs/_incoming/agent-fault-assertion-without-verification.md @@ -1,5 +1,12 @@ --- +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"] --- diff --git a/klappy-dev-book-export.md b/klappy-dev-book-export.md index ca6d3901..c53e72b7 100644 --- a/klappy-dev-book-export.md +++ b/klappy-dev-book-export.md @@ -5,7 +5,7 @@ ================================================================================ -Generated: 2026-02-08T16:58:07.307Z +Generated: 2026-02-08T16:59:59.511Z Total Files: 290 This is a documentation export of all markdown files from the klappy.dev @@ -1768,7 +1768,14 @@ This folder is removed (or archived) when: -------------------------------------------------------------------------------- --- +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"] --- diff --git a/public/_compiled/index/docs.json b/public/_compiled/index/docs.json index 13e4080c..396fe56b 100644 --- a/public/_compiled/index/docs.json +++ b/public/_compiled/index/docs.json @@ -1,6 +1,6 @@ { "version": "1.1", - "generated_at": "2026-02-08T16:58:07.951Z", + "generated_at": "2026-02-08T17:00:00.191Z", "description": "Fast-lookup index for Librarian retrieval. Per docs/agents/librarian/contract.md", "schema_notes": { "authority_band": "Resolved authority (frontmatter override > inferred from root)", @@ -6823,7 +6823,7 @@ "root": "docs", "authority_band": "operational", "authority_inferred": "operational", - "uri": null, + "uri": "klappy://docs/_incoming/agent-fault-assertion-without-verification", "title": "Agent Fault: Assertion Without Verification", "subtitle": "Agents confidently assert factual claims about system state without checking first.", "tags": [ @@ -6836,11 +6836,11 @@ "acronyms": [ "afawv" ], - "stability": null, - "tier": null, - "audience": null, - "exposure": null, - "voice": null, + "stability": "evolving", + "tier": "3", + "audience": "docs", + "exposure": "internal", + "voice": "neutral", "relevance": null, "execution_posture": null, "headings": [