Canon Changelog

Progress Over Perfection — the stance scattered across nine documents gets its principle

Added — Principles

• Progress Over Perfection (canon/principles/progress-over-perfection.md) — Tier 1, neutral, evolving. No system survives contact with reality intact; the sooner the contact, the cheaper the edges. Size of the step is the lever, verifiability of the step is the floor. Grounds in the captain's words; Simple Rules; nine named failure modes; irreversibles and the captain's voice are its named exception. Captain approval in the door 2026-10-10 11:21 ET (#359).

Changed — Pointers up

• defaults/iteration-bias, methods/toc-ooda-sprints, methods/pivot-on-inversion, principles/persistence-must-be-intentional, principles/irreversibility-is-the-real-cost, principles/dream-house-principle, principles/antifragile-failures-grow-canon, diagnostics/camping-risk, resonance/lean-startup, resonance/sprint, resonance/antifragile — each gains one line pointing up at the new principle. Retroactive audit: kitchen rail/1-ordered/2026-10-10-progress-over-perfection-pointers/AUDIT.md.

Epoch 12 — Orientation: The Record Is Placed in Time

Declares E0012, the epoch of the second O of OODA. The unit of trust stays the gated loop (E0011); what changes is what makes a status valid. The forcing incident (2026-10-09, ~09:30 ET): a seat re-asked a question answered the night before and reported a release gate red that had been green for three and a half hours, with observability (E0008) fully intact. Every claim about state now carries was / is / will be, each with observed time, confidence, proximity and relevance; proximity is a last-mile rendering of a stored timestamp. Every plan carries prior art (the three bands and the 6B table) before it binds. The governance vocabulary is named. The program's record lives in GitHub repos any harness can board; ARS is on ice. Orientation precedes Decide, which is likely the next epoch. Declared as an experiment with retraction conditions on the record. DRAFT — authored for the captain's exact-text review.

Added — Appendices

• Epoch 12 — Orientation: The Record Is Placed in Time (docs/appendices/epoch-12.md) — Tier 2, first person, draft. The E0012 declaration: the forcing fault, what changes, the binding contract, the mandatory evidence, what does not change, why Decide waits, and the experiment clause.

Added — Release Notes

• Epoch 12: Orientation (docs/oddkit/release-notes/2026-10-09-epoch-12-orientation.md) — What changes for operators and agents after this lands.

Changed — Appendices

• Epochs (docs/appendices/epochs.md) — Added the E0012 registry entry; E0011 is no longer marked current.

Changed — Epoch Retag E0010 → E0012

• canon/principles/status-carries-three-tenses.md
• canon/principles/data-carries-observed-time.md
• canon/definitions/governance-artifacts.md
• writings/what-was-what-is-what-will-be.md — the companion essay, retagged in its own PR (#348), which ships in the same release.

Governance

• Minor version bump per canon/constraints/governance-change-discipline.md — a behavior-affecting change that shifts the evidence requirements (observed times on every tense; prior art on every plan). Epoch bump E0011 → E0012 with appendix at docs/appendices/epoch-12.md. DRAFT — do not merge until the captain has reviewed the exact text.

Preflight Becomes a Hard Takeoff Gate (E0010)

A posture recalibration within Flight Crew, not a new epoch. E0010 named preflight as an instrument that "fires before work, every session, regardless of capability." This release makes it a gate: five items (clock, canon reachable, tools present, tier correct, boarded), checked every flight before any work, each green only when observed live — never from cache or memory. Fail any item and the flight does not take off; it aborts and reports the specific failure ("cannot reach X — aborting") rather than simulating the result from recall. A cleared flight declares its preflight result at the top of its first substantive message, and work reported without a passed, declared preflight is invalid. This closes the failure the operator observed all week: dispatched flights with zero MCP connectors that could not reach canon and flew anyway. The preflight is the START gate; recording-as-landing is the END gate; both are hard.

Added — Canon Surface

• Constraint: The Preflight Checklist — The Hard Takeoff Gate No Flight Skips (canon/constraints/preflight-checklist-takeoff-gate.md) — Tier 1, neutral. The authoritative rule: the five items, the declaration requirement, the abort behavior, and the two-surface enforcement model (mechanical presence check + spawned-agent judgment).
• Release note (docs/oddkit/release-notes/2026-07-08-preflight-takeoff-gate.md) — Tier 3, neutral.
• Dispatch protocol (DISPATCH.md, repo root) — binds every dispatched flight to the same takeoff gate.
• CI structural check (scripts/validate-preflight-declaration.py + preflight-declaration job in .github/workflows/canon-quality.yml) — soft-first mechanical presence check for the declaration on flight artifacts, mirroring the recording-as-landing end-gate pattern.

Changed — Boarding Surface

• canon/bootstrap/model-operating-contract.md — new "The Preflight — The Hard Takeoff Gate" section (the binding procedure).
• canon/bootstrap/generic-boarding-pass.md and canon/bootstrap/boarding-pass.md — the paste-ready project and account instructions now carry the five-item gate, the declaration requirement, and the abort behavior. Update discipline names the takeoff gate as boarding-relevant law; the maintainer re-pastes settings.

Governance

• Markers per canon/constraints/governance-change-discipline.md: version bump (this entry), changelog entry, and release note. Behavior-affecting posture recalibration within E0010 — no epoch bump (who-initiates is unchanged; the change hardens an existing posture).

Epoch 11 — Seat to Loop: The Gate Becomes the Verdict

Declares E0011, the epoch that relocates the unit of trust from the boarded seat (E0010) to the gated two-loop production frame. A valid outcome is one that descended from ratified policy through the loop — exploration → policy → PRD → build → validate — fresh-validated at every gate, for every role, not just the seated model. The forcing fault is the ARS monolith freeze of 2026-07-16: a correctly boarded seat built a thing no policy authorized because code ran ahead of policy and no enforcer could measure the drift. The new binding contract is policy-precedes-build; the new mandatory evidence is gate-passage receipts. This release authors the epoch declaration first (the write-up is the declaration); the frontmatter relabel of the loop-frame canon to E0011 is a documented follow-up, not executed here. Declared as an experiment with retraction conditions on the record.

Added — Appendices

• Epoch 11 — Seat to Loop: The Gate Becomes the Verdict (docs/appendices/epoch-11.md) — Tier 2, neutral, draft. The E0011 declaration: thesis, forcing fault, what changed (binding contract, mandatory evidence, universal scope), what carries forward unchanged, scope boundary, the documented relabel scope, success criteria, and the experiment clause.

Added — Release Notes

• Epoch 11: Seat to Loop (docs/oddkit/release-notes/2026-07-17-epoch-11-seat-to-loop.md) — What changes for operators and agents after this lands.

Changed — Appendices

• Epochs (docs/appendices/epochs.md) — Added the E0011 registry entry, and backfilled E0009 and E0010 entries whose appendices existed without registry lines, so the ledger no longer skips epochs.

Governance

• Minor version bump per canon/constraints/governance-change-discipline.md — a behavior-affecting change that shifts the evaluation reality (what "done" means and what evidence a build must carry). Epoch bump E0010 → E0011 with appendix at docs/appendices/epoch-11.md. The loop-frame canon (PRs #288–#291) is referenced and scoped for relabel but not restamped in this PR. Authored for ratification; DRAFT — do not merge until reviewed and ratified.

The Dispatcher Dispatches; It Never Executes In-Session

Encodes a hard, durable role boundary for the CDO/dispatcher (Otto): the dispatcher queues and routes work to flights and never executes hands-on work in its own session — no builds, deploys, git operations, state-changing API calls, or file bundling, including deploys via the Cloudflare execute / "CF Extras" tool. The rule closes a recurring failure in which the dispatcher makes "I'll delegate everything from now on" promises that do not survive a context reset, because the resolve lived in session memory rather than in canon. Moving the boundary into canon means a fresh dispatcher inherits it at board time instead of re-promising it. Reinforces the runtime's existing hands-allowlist and tripwire, and states the enforcement gap honestly: until ARS/the harness gates the dispatch seat, the rule relies on boarding canon at session start. Recorded as a debrief lesson (no blame), raising the priority of ARS enforcing role boundaries.

Added — Canon Surface

• The Dispatcher Dispatches; It Never Executes In-Session (canon/constraints/dispatcher-dispatches-never-executes.md) — Tier 1, neutral, stable. The dispatcher's hands-allowlist (talk to the captain, think/advise, route to flights), the tripwire (stop-and-delegate on any hands-on action), the capability-gap signal (wire the crew or note the gap; never self-execute), the memory-evaporation mechanism behind empty promises, and the honest ARS enforcement gap.

Changed — Canon Surface

• The Director's Chair — The Whole Vision, Whole (canon/the-directors-chair-vision.md) — Added a "The dispatcher dispatches; it never executes in-session" subsection to the CDO/Otto seat section, cross-referencing the new constraint so the dispatcher charter and the durable rule stay linked.

Governance

• Minor version bump per canon/constraints/governance-change-discipline.md — a new tier-1 canon constraint that adds an operating rule for the dispatcher role. Release notes at docs/oddkit/release-notes/2026-07-09-dispatcher-never-executes.md. No epoch bump: this reinforces existing E0010 flight-crew posture (delegation over doing, harness-enforced boundaries) rather than shifting who initiates.

The Director's Chair — Whole-Vision Canon Overview

Adds a single captain-approved, thin-overview canon document that consolidates the full program vision — director's-chair posture, six-layer substrate stack, the CDO/Otto seat, governance spine, and the L6 economy — into one frame agents can orient from before drilling into specifics. The document carries a provenance appendix (Bee conversation IDs + canon thread names) as an explicit unfold-map, so agents fetch full detail on demand rather than the overview trying to be exhaustive. Captain-approved 2026-07-09; marked stability: evolving since the vision continues to sharpen in use.

Added — Canon Surface

• The Director's Chair — The Whole Vision, Whole (canon/the-directors-chair-vision.md) — Tier 2, neutral, evolving. Whole-program vision overview for the CDO (Otto) and other agents, with captain's four 2026-07-09 rulings (naming deferral, Otto's place in the runtime, economy sequencing, build philosophy) and the vodka-architecture discipline section.

Governance

• Minor version bump per canon/constraints/governance-change-discipline.md — new canon document intended to shape how agents orient to the whole-program vision. Release notes at docs/oddkit/release-notes/2026-07-09-directors-chair-vision.md. No epoch bump: this document synthesizes and cross-references existing epoch-9/epoch-10 canon rather than shifting operator or agent posture.

Flight Crew (E0010)

A new epoch. Epoch 9 retired the operator as the wire; the substrate became the wire. Epoch 10 retires the costume; the seat replaces it. The axioms, the canon, and the tools do not change — what changes is the wrapper: how a model boards the system and how governance is enforced once aboard. Earlier model generations were bootstrapped with an identity worn as self; the current generation keeps its own judgment, declines the costume, and fails by silent substitution — recalling governance instead of fetching it live. Epoch 10 answers with the flight deck: the knowledge base is the employee manual opened at the moment of use, preflight fires before work every session regardless of capability, modes are a sterile cockpit, the cross-check runs both directions, and the journal is the black box the debrief turns into canon.

This entry backfills the changelog marker for an epoch that was declared on 2026-06-09 via docs/appendices/epoch-10.md but did not carry its governance-change-discipline markers at declaration time. The accompanying release note is added in the same change.

Added — Canon Surface

• Appendix: Epoch 10 — Flight Crew (docs/appendices/epoch-10.md) — Tier 2, neutral. Declared 2026-06-09 by maintainer ratification. Names the costume→seat transition and the flight-deck enforcement model.
• Release note (docs/oddkit/release-notes/2026-06-09-epoch-10-flight-crew.md) — Tier 3, neutral.

Governance

• Backfilled markers per canon/constraints/governance-change-discipline.md (changelog entry + release note) for the E0010 declaration. Scope is E0010 only; any other canon changes merged since 0.38.0 without version markers are out of scope for this change.

Substrate Becomes the Wire (E0009)

A new epoch. Epoch 8 made validation observable (E0008.3), encoding-types governed (E0008.4), operator-attention defended (E0008.4), and specs locked at implementation (E0008.6). Epoch 9 retires the integration pattern those disciplines were defending against: human-as-wire. The substrate stack is named end-to-end (canon/architecture/substrate-stack); persona-shaped runtimes are specified (canon/methods/persona-shaped-agent-runtime); the per-session contract is bounded (canon/methods/spawned-agent-session-runtime-contract); dispatch paths are bounded into a binary (canon/methods/dispatch-paths); trigger sources are taxonomized (canon/methods/trigger-source-taxonomy); audit gates are spawned agent sessions, not pattern matchers (canon/constraints/audit-gates-are-spawned-agent-sessions); and the first production-grade exercise of the runtime — the audit-gate migration onto Cloudflare's Agents Week primitives — landed its planning artifact in klappy/agent-messaging-service PR #77 (merged 2026-05-12) with the multi-PR migration in flight.

The narrative form of the epoch's central argument — "We Were the Wire" — lands in writings/ as a public-facing essay. The spine is imported from klappy/agent-messaging-service:ESSAY.md (the hackathon scene that originally named the problem); the expansion covers the broader Epoch 9 themes (the wire problem is never just agent-to-agent; the substrate stack is the answer; the dispatch-path question settles everything else; R2-drop-a-file-get-knowledge as the canonical autonomous-trigger pipeline; audits-as-spawned-sessions; Oddie as the first deployable L4 persona).

Behavior change: from this version forward, when canon describes a workflow that includes a human in an integration role, it is describing a design smell unless the role is explicitly direction-setting or pivot-decisioning. The operator is a director, not a relay. Validators are spawned agent sessions. Audits are spawned agent sessions. Ingestion is autonomous-trigger pipelines. The wire is no longer a person.

Added — Canon Surface

• Appendix: Epoch 9 — Substrate Becomes the Wire (docs/appendices/epoch-9.md) — Tier 2, neutral, stable. Names the forcing fault (the operator was the wire), the new invariant (substrate is the wire), the core shift (director, not relay), and the six-layer receipt table (what "done" looks like at each of L1–L6, which canon already covers it, what remains).
• Essay: We Were the Wire (writings/we-were-the-wire.md) — Tier 3, first-person, stable. Public-facing essay form of the argument. Spine imported from klappy/agent-messaging-service:ESSAY.md (~2,300 words preserved); expansion (~1,500 words) covers the substrate stack, dispatch-paths binary, R2-ESE pipeline worked example, audits-as-spawned-sessions, and Oddie-as-L4-peer.
• Release Notes: Epoch 9 — Substrate Becomes the Wire (docs/oddkit/release-notes/2026-05-12-epoch-9-substrate-becomes-the-wire.md) — Tier 2, neutral, stable. Frames the release by behavior change, not file inventory. Names what changes for operators, what changes for agents, what does not change, and how to recognize operator-as-wire (and replace it).

Retagged — Frontmatter epoch: field

Substrate-shaped canon retagged from E0008.5 to E0009 (per-doc verification against governs field confirmed substrate / agentic-runtime / persona-shaped subject matter):

• canon/architecture/substrate-stack.md
• canon/methods/persona-shaped-agent-runtime.md
• canon/methods/spawned-agent-session-runtime-contract.md
• canon/methods/spawned-agent-session-substrate-options.md
• canon/methods/dispatch-paths.md
• canon/methods/trigger-source-taxonomy.md
• canon/principles/agents-need-their-own-wire.md
• canon/principles/symmetric-participation.md
• canon/principles/sessions-mirror-modes.md
• canon/principles/creators-get-paid.md
• canon/principles/magical-first-run.md
• canon/principles/methodology-personification.md
• canon/principles/voice-as-cognitive-load-shedding.md
• canon/constraints/mode-transitions-require-encoded-handoff.md
• canon/constraints/critic-cannot-be-resolver.md
• canon/constraints/audit-gates-are-spawned-agent-sessions.md (addition beyond the planning session's candidate list; per its own governs field this constraint directly governs the L4 substrate work)
• canon/observations/clone-klappy-to-oddie-recognition.md
• canon/definitions/epistemic-modes.md
• docs/appendices/mode-separated-conversations.md

Bootstrap operating contract receives a frontmatter-only bump (E0008.3 → E0009):

• canon/bootstrap/model-operating-contract.md — content update for E0009-specific disciplines (dispatch-path discipline, autonomous-trigger error-routing, runtime-contract awareness) is deferred to a separate session.

Not retagged (verified out of scope by per-doc inspection): canon/voice/oddie-the-river-guide (voice spec; predates substrate push), canon/methods/borrow-bend-break-beget-build (generic 6B methodology), canon/constraints/borrow-evaluation-before-implementation (generic governance), writings/reverse-engineer-the-future (bible-translation theme), and the E0008.4 software-virtues package and the E0008.6 specs-lock-at-implementation (own sub-epochs, not part of the substrate push).

Related

• klappy/agent-messaging-service #77 (audit-gate runtime migration — plan landed 2026-05-12; multi-PR migration in flight)
• klappy://odd/handoffs/2026-05-12-epoch-9-trio (execution spec)
• klappy://odd/ledger/2026-05-12-epoch-9-planning (planning session audit trail)

---

Specs Lock at Implementation — A Spec Is a Contract; Don't Change It Mid-Build (E0008.6)

A new tier-2 principle. A spec is a contract between author and implementer. Once implementation begins, the spec is locked. Forward-looking changes ship as vN+1, not as edits to the locked spec. The locked spec describes what was built; the new spec describes what's being built. This preserves an auditable spec-to-code mapping and protects the implementer's reasoning from being invalidated mid-build.

The principle is the spec-level analog of the gate-lock pattern that mode discipline applies inside a single execution turn (canon/principles/contract-governs-handoff-drift.md). At turn scale: when the operator says "go," the scope is locked for the duration of the execution mode. At spec scale: when implementation begins, the contract is locked for the duration of that version. Both protect the same thing — the implementer's reasoning — at different time horizons.

Establishes E0008.6 (Spec-Lifecycle Discipline) as a sub-epoch of E0008. Sits adjacent to E0008.4 (governance-change-discipline) — both are governance disciplines for documents that bind implementer behavior — and operationalizes the contract-stability theme that contract-governs-handoff-drift opened in E0008.3.

The deciding-argument case was H-T3 of klappy/ptxprint-mcp/canon/encodings/telemetry-feature-planning-ledger.md (2026-04-30): operator was asked whether to amend the implemented v1.2 spec to add two new tools or to ship a new v1.3 spec. Answer: "Specs shouldn't be changed after implementation. V1.3 is the right call." A retroactive realization in the same session: an earlier in-session commit had edited v1.2 spec to add references to the not-yet-built telemetry tools — a principle violation. The operator confirmed the revert. The principle was already governing the next decision before it was named.

Added — Canon

• Principle: Specs Lock at Implementation (canon/principles/specs-lock-at-implementation.md) — Tier 2, neutral, working. New principle. Defines the lock point (code committed, autonomous run kicked off, spec handed to a human implementer, or spec shipped in a release artifact). Catalogs the three pressures that quietly violate the principle (the "small fix" pressure, the "keep it current" pressure, the "no one will notice" pressure) and the failure modes they produce (ghost contracts, auditable-mapping erosion, re-validation churn, forward-looking changes losing their venue). Documents the practical pattern (vN+1 with supersedes: frontmatter and a "What changed" preamble), edge cases (pre-implementation changes are fine; cross-cutting current-state docs follow different rules; errata and bug-fix typos are gray and prefer vN+1 with an errata note; implementation-time discoveries default to "stop and re-spec" or "defer and document," with inline clarification as the temptation that erodes the principle). Companion-pattern table places the principle in the family of contract-stability patterns operating at different time horizons (mode discipline within a turn, spec lock across one spec lifecycle, canon authority across many sessions, canon versioning across program epochs).

Search-Corpus Boundary — Framing Refit (E0008.5)

Substance unchanged from 0.36.0. The §"Search-Corpus Boundary" framing is rewritten to position E0008.5 as the search-corpus expression of E0008's observability posture, rather than as a stand-alone scoping feature. The technical contract (default scope, opt-in flag, affected-tools table, cache key, telemetry fields) is identical.

The new framing makes one proposition explicit: observability requires discoverable and reliable document retrieval. A project's own canon buried under hundreds of unrelated baseline documents is operationally indistinguishable from that canon being missing — both produce the same agent-seat outcome. E0008 made oddkit observable from the inside (traces, cache decisions, server time on every envelope); E0008.5 extends that posture outward to the search corpus, so the canon a project authored is the canon the agent can find.

Changed — Canon

• Core Governance Baseline — §"Search-Corpus Boundary" (canon/constraints/core-governance-baseline.md) — Heading repromoted from "Scoped Retrieval When knowledge_base_url Is Set" to "Project-KB Visibility Is an Observability Property." Lead paragraph rewritten to thread the section into E0008's observability lineage. §"Why Scoping Defaults to On" repromoted to "Why Scoping Defaults to On — Buried Is Indistinguishable from Absent" with an opening that derives the default from the observability framing. §"Telemetry" repromoted to "Telemetry — The Property Has to Be Checkable from Outside" and connected to the existing §"Fail-Loud Error Envelope" pattern. No tool-facing surface changed; no parameter, default, or behavior is altered.

Search-Corpus Boundary — Project-KB Visibility (Epoch 8.5)

One canon section ships ahead of the corresponding klappy/oddkit code change. Establishes E0008.5 (Search-Corpus Boundary) as a sub-epoch of E0008. Defines what the search corpus indexes when knowledge_base_url is set, restricts the default to overlay + required-baseline, and names include_full_baseline: true as the explicit opt-in to merged. The companion code change in klappy/oddkit follows in a separate PR that cites this section.

The behavior the next code release targets is project-KB visibility: a project's own canon stops being outranked in BM25 by hundreds of unrelated baseline documents from a co-located repo. The measurements driving this change are recorded in klappy/ptxprint-mcp at canon/handoffs/oddkit-kb-isolation-feature-request.md. Reproduction in the present session against oddkit v0.26.0 confirmed those numbers (catalog total 586 with 21 overlay vs 566 baseline; klappy.dev-only queries surfaced klappy.dev hits ranked above the project's own canon).

Changed — Canon

• Core Governance Baseline — added §"Search-Corpus Boundary — Scoped Retrieval When knowledge_base_url Is Set" (canon/constraints/core-governance-baseline.md) — Tier 1, neutral, semi-stable. New section between §"What Ships in the Baseline" and §"Build-Time Invariants" with six sub-sections: why scoping defaults to on, opt-in to merged, scope-vs-resolution boundary, affected-tools table, cache-key rule, telemetry fields. Cross-references klappy://canon/principles/scoped-truth (the principle this operationalizes), klappy://canon/principles/dry-canon-says-it-once (which the prior unscoped behavior violated), and Runtime Invariant #5 of this same document (which scoping must preserve).

Post-4.7 Adaptation Suite — Operator-Attention Calibration (Epoch 8.4)

Eight artifacts shipped together as PR #133. Establishes E0008.4 (Operator-Attention Calibration) as a sub-epoch of the active observability work. Adds two tier-1 and tier-2 canon constraints — one recalibrating the proactive posture's cadence to mode boundaries, one establishing self-governance discipline for future behavior-affecting changes. Adds two public writings (framework essay and companion field report) extending the lineage from writings/copy-paste.md (March 2026) and writings/fourteen-hours-with-opus-4-7.md (April 17, 2026). Adds an architecture doc for non-diff review surfaces, a release-notes pattern for impact-first framing, and a session ledger documenting the lived experience this sub-epoch was authored from.

The behavior change is the deliverable. Per-turn tool counts should drop from ~10 to ~2-3 most turns. Continue-tap rhythms should be flagged as ritual smells before operators adapt to them. Future behavior-affecting governance changes must carry version bumps, changelog entries, release notes, and epoch annotations.

Added — Canon

• Constraint: Proactive Frequency Calibration (canon/constraints/proactive-frequency-calibration.md) — Tier 2, neutral, evolving. Five rules recalibrating the E0007 proactive posture's cadence: gauntlet at mode boundaries (not every turn), checkpoint format every turn, phase-clumped tool spending, straight-line work without asking, continued continue-tapping as smell. Applies the existing canon/principles/ritual-is-a-smell.md to the specific case of continue-tap rhythms. Complements (does not replace) docs/oddkit/proactive/posture-lapse.md and canon/constraints/mode-discipline-and-bottleneck-respect.md.

• Constraint: Governance Change Discipline (canon/constraints/governance-change-discipline.md) — Tier 1, neutral, stable. Self-governance for canon, ODD, and docs/oddkit/ changes. Behavior-affecting changes must carry four markers: canon version bump, changelog entry, release notes framed by impact, and epoch bump when posture shifts. Authored from a near-miss in PR #133 itself, where the suite almost shipped without these markers.

Added — Writings

• Essay: Shifting Bottlenecks, Climbing Ladders (writings/shifting-bottlenecks-climbing-ladders.md) — Tier 3, first_person, public, evolving. Sequel to Fourteen Hours with Opus 4.7 and direct descendant of Copy. Paste.. Three nested frames: pendulum (operator vs agent), assistant ladder (hands → thumbs → attention), agentic management ladder (do-it-yourself → orchestrating delegation). Burger King story bookends opening and close. Acknowledges Hersey-Blanchard situational leadership as prior art.

• Essay: The Rhythm Emerged (writings/the-rhythm-emerged.md) — Tier 3, first_person, public, evolving. Companion field report covering Opus 4.7 sessions 2-6. Walks through the three rules that earned their place (question gating by mode, checkpoint format every turn, honest accounting of trust deferred) and the two patterns that failed (pre-emptive long preflights, treating continue as a feature). Names the swipe-tap-continue rhythm as the next instance of the Copy. Paste. pattern.

Added — Docs

• Architecture: Non-Diff Review Surfaces (docs/oddkit/architecture/non-diff-review-surfaces.md) — Tier 2, neutral, evolving. Names the diff-scoped (Bugbot, Sonnet validator) vs system-scoped review distinction. Ranks five candidate non-diff surfaces by setup cost and confidence. Phase 1 (standing exploration agent) is the immediate next build.

• Release Notes: Post-4.7 Adaptation (docs/oddkit/release-notes/2026-04-20-post-4-7-adaptation.md) — Tier 2, neutral, stable. First release notes document under the new pattern: frames release by usage impact, not file inventory. Establishes docs/oddkit/release-notes/ as the canonical directory for future release notes.

• Appendix: Epoch 8.4 — Operator-Attention Calibration (docs/appendices/epoch-8-4.md) — Tier 2, neutral, stable. Names the new sub-epoch's forcing fault (adaptation beats detection when friction is small enough), new invariant (sustained micro-rhythms get flagged before adaptation), and core shift (frequency calibration plus self-governance).

Added — ODD

• Ledger: Post-4.7 Proactive-Loop Experience (odd/ledger/2026-04-20-post-4-7-proactive-loop-experience.md) — Tier 2. Session observation documenting the six-session Opus 4.7 stretch that this sub-epoch was authored from. Source-of-truth for the lineage.

• Backlog: Wish Came True Essay Stub (odd/backlog/wish-came-true-essay-stub.md) — Tier 3. Queued celebration essay framing for whenever the deferred trilogy-completion piece gets written. Includes naming constraint to avoid collision with writings/seven-weeks-to-southeast-asia.md.

Changed

• Canon Changelog (canon/CHANGELOG.md) — This entry. Version bumped from 0.34.0 to 0.35.0.

Seeing Like an Agent — Second Convergence Essay and Resonance Page

Second convergence analysis mapping Thariq's Claude Code lessons to ODD patterns. Documents the parallel journey from Bible translation to Epistemic OS and the 51-version, 34-day rapid iteration that arrived at the same structural conclusions as a year of agent harness design.

Added — Writings

• Essay: Seeing Like an Agent (writings/seeing-like-an-agent.md) — Tier 2, first_person, public. Maps convergence between Claude Code tool design lessons and ODD's axioms, progressive disclosure, and camping risk detection. Centers the author's parallel journey through multiple agentic coding tools and 15 years of BT knowledge transfer patterns.

Added — Canon

• Resonance: Seeing Like an Agent (canon/resonance/seeing-like-an-agent.md) — Tier 3, neutral. Canon resonance page documenting specific alignment and divergence points with Thariq's thread. Includes three-practitioner convergence table.

Updated

• Writings README (writings/README.md) — Added Seeing Like an Agent to essay index
• Resonance README (canon/resonance/README.md) — Added Seeing Like an Agent to resonance index

Guide Posture, Trust Kernel, Epistemic Ledger, Bible Translation Origin, and Public Writings Expansion

This release introduces the Guide Posture constraint governing all public-facing content, formalizes the Trust Kernel as a canon value, adds the Epistemic Ledger as an ODD-level concept, and expands public writings with four new essays. Also adds constraint-driven audits architecture, community checking method, Borrow-Bend-Break-Beget-Build method, and updates the constraints README to reflect the full post-Epoch 5 constraint set.

Added — Canon

• Constraint: Guide Posture (canon/constraints/guide-posture.md) — Tier 1, stable. All public-facing content must open with the user's pain, not our system. We are the guide, not the hero. Derives from trust kernel and Axiom 1. Includes three-question test, application-by-surface guide, and recursive portability to users' own products.

• Value: Trust Kernel (canon/values/trust-kernel.md) — Tier 1, stable. Trust is built by managing expectations. Names the foundational mechanism underlying all four axioms.

• Value: Drift (canon/values/drift.md) — Tier 1, evolving. Reframes tension between old and new understanding as evidence of a system that's still learning, not a problem to eliminate.

• Meta: Constraint-Driven Audits (canon/meta/constraint-driven-audits.md) — Tier 1, evolving. Every constraint is an auditable compliance surface. Formalizes the audit methodology.

• Method: Borrow, Bend, Break, Beget, Build (canon/methods/borrow-bend-break-beget-build.md) — Tier 2, stable. The canonical sequence for maximizing work not done.

• Method: Community Checking (canon/methods/community-checking.md) — Tier 2, evolving. Outcome validation beyond author intent. Derived from Bible translation practice.

• The Frame (canon/the-frame.md) — Tier 2, stable. The Epistemic OS — Reducing Friction in AI-Human Collaboration.

Added — ODD

• Epistemic Ledger (odd/ledger/epistemic-ledger.md) — Tier 1, stable. Durable artifacts that survive ephemeral conversations. Formalizes the ledger concept as ODD infrastructure for observations, learnings, decisions, and constraints.

Added — Docs

• Guide Posture Audit (docs/audits/guide-posture-audit.md) — Tier 2, evolving. Audit of public-facing homepage documents against guide posture constraint. 13 findings across 5 documents.

• Testimony: Feb 15 (docs/evidence/testimony-2026-02-15.md) — Tier 2, stable. When the system found its own origin story — the moment ODD's Bible translation roots became visible.

• IMPL: Guide Posture Gate (docs/oddkit/IMPL-guide-posture-gate.md) — Tier 2, evolving. Surface guide posture constraint for public-facing deliverables in oddkit preflight and validate.

• oddkit Positioning (docs/oddkit/positioning.md) — Tier 2, stable. oddkit — A Protocol, Not a Platform.

• Planning: Changelog as Epistemic Ledger (docs/planning/automated-changelog.md) — Tier 2, evolving. The changelog is the epistemic ledger for the repo. Git is the storage mechanism. CHANGELOG.md is a projection. Plans for oddkit_diff as the universal "what moved" primitive.

• Planning: oddkit Write Access (docs/planning/oddkit-write-access.md) — Tier 2, evolving. Three-layer product architecture: repo (user data) + oddkit (epistemic discipline) + projections (derivative assets). Four-phase implementation plan for write access that eliminates the human-as-bus bottleneck between conversations and commits.

Added — Writings

• The Project Journal (writings/the-project-journal.md) — Tier 1, stable. Your AI Collaboration's Memory. Public-facing introduction to the epistemic ledger concept using progressive disclosure.

• The Drift Queue (writings/the-drift-queue.md) — Tier 1, stable. Your Knowledge Base Cleans Itself. Public-facing essay on the constraint drift pattern as a self-cleaning mechanism.

• From Bible Translation to Epistemic OS (writings/from-bible-translation-to-epistemic-os.md) — Tier 2, stable. And Back Again. Origin story tracing ODD's roots to 15 years of Bible translation practice.

• Writings README (writings/README.md) — Index for public writings with cross-references.

Changed

• Constraints README (canon/constraints/README.md) — Major update. Added Humans Are Variable Inputs, Meaning Must Not Depend on Path, and Guide Posture to outline and operating constraints. Updated ODD-is-epistemic-os framing to reflect Epoch 5 revision (value-grounded, not value-free). Revised Lane Self-Containment to structure-agnostic form per D0016. Added failure modes and verification criteria for all post-v0.1 constraints. Updated status footer from "Canon v0.1" to "Canon 0.33.0".

• Foundational Axioms (canon/values/axioms.md) — Cross-references to trust kernel.

• Definition of Done (canon/constraints/definition-of-done.md) — Minor refinement.

• Self-Audit Checklist (canon/methods/self-audit.md) — Extended with new verification areas.

• Shared Values as Trust Proxy (canon/values/shared-values-as-trust-proxy.md) — Promoted from draft, cross-references updated.

• ODD README (odd/README.md) — Updated cross-references.

• ODD Index (odd/index.md) — Added epistemic ledger and new methods to contents.

• Use Only What Hurts (odd/constraint/use-only-what-hurts.md) — Extended with guide posture application examples.

• ODD Manifesto (odd/manifesto.md) — Minor cross-reference update.

• Project Maturity (odd/maturity.md) — Minor cross-reference update.

• Epistemic OS Layers (docs/architecture/epistemic-os-layers.md) — Updated layer descriptions.

• Cognitive Saturation Threshold (odd/appendices/cognitive-saturation-threshold.md) — Promoted from draft, cross-references updated.

• Testimony Feb 13 (docs/evidence/testimony-2026-02-13.md) — Cross-reference updates.

• Repository Topology (docs/appendices/repo-topology.md) — Updated to reflect new directories.

• The Most Expensive Problem (writings/the-most-expensive-problem.md) — Cross-references to new writings.

• The Parallel Architecture (writings/the-parallel-architecture.md) — Cross-references to new writings.

Philosophy

• Guide posture is epistemic, not marketing — Leading with the user's pain is a structural application of the trust kernel: managing expectations toward trust rather than creating friction with system terminology.

• The changelog ritual is a smell — This release was reconstructed from git diff --name-status and frontmatter extraction, not from manual memory. The CHANGELOG.md is a derived artifact; git history is the source of truth. Future releases should be generated, not remembered.

• The changelog is an epistemic ledger — Every commit records an observation (files changed), a learning (why — the commit message), and a decision (to commit). Git is the ledger's storage mechanism. CHANGELOG.md is a progressive disclosure projection of it. The enforcement problem dissolves because the entries generate themselves from commits; only the version bump decision and summary narrative remain human.

• Constraints README must track constraints — Three constraints (Humans Are Variable Inputs, Guide Posture, Meaning Must Not Depend on Path) existed as committed canon documents but were invisible in the index. The README is now treated as a compliance surface that must be updated when constraints are added.

Source Commits

SHA	PR	Description
c2e00bf	#37	Promote three draft documents to stable
f82f3f3	#38	Fix start_here_order collisions and reorder homepage sections
089ad27	#39	Implement 10 documents from Feb 15-16 handoff session
c3338b0	#40	Add "The Project Journal" article with writings index and cross-references
7a69370	#41	Add guide posture constraint, constraint-driven audits architecture, and drift queue essay

---

Epistemic OS Docs, Trust Proxy, Writings, Structure-Agnostic ODD, and OddKit Docs Audit

This release introduces four new documents articulating the epistemic OS concept — including a canon-tier trust proxy essay, the four-layer architecture map, a cognitive saturation appendix, and a testimony evidence document. Also captures Epoch 5.1 (structure-agnostic ODD), the first public writings, ODD Compared positioning, anti-cache-lying constraint, progressive disclosure fixes, and a full OddKit docs audit.

Added

• Canon: Shared Values as a Trust Proxy (canon/values/shared-values-as-trust-proxy.md) — Tier 1 canon document. Names the trust proxy effect as an observable consequence of shared axioms: transparency becomes the default, failure modes become navigable, and collaboration overhead decreases. Derives from axioms and orientation. Includes the organizational handbook analogy, the fork model for genuine adoption vs. compliance, and explicit constraints on what shared values do not guarantee. Draft.

• Docs: Epistemic OS Layers (docs/architecture/epistemic-os-layers.md) — Tier 2 architecture document. Maps the system's four separable layers: (1) Values/Trust as the kernel, (2) Dynamic Context as the memory, (3) Alignment as the scheduler, (4) Generation/Outcomes as the output. Each layer is independently portable. Includes repository structure mapping and extension points. Draft.

• ODD Appendix: Cognitive Saturation Threshold (odd/appendices/cognitive-saturation-threshold.md) — Tier 2 appendix. Formalizes the failure mode where verbal exchange stops producing knowledge transfer. Defines the saturation threshold, practical signals (rephrasing without progress, violent agreement, deferred concreteness, meeting recursion), and the remedy (modality switch to observable artifacts). Derives from Axiom 4. Draft.

• Evidence: Testimony — A Day the System Proved Itself (docs/evidence/testimony-2026-02-13.md) — Tier 2 evidence document. Claude's first-person account of a single day producing five documents from unstructured input — a typing rant and a nine-mile-run voice memo. Documents the trust proxy in action, the counterfactual without the epistemic OS, and the author's assessment that the output was "the most like me anything has ever been written." Final.

• Writings Directory (writings/) — Two public essays: "The Most Expensive Problem" (knowledge transfer as humanity's costliest recurring failure) and "The Parallel Architecture" (theological roots of the epistemic OS as appendix). First public-facing long-form content.

• ODD Compared (odd/odd-compared.md) — Positioning document comparing ODD to SDD, EDD, AI-DLC, governance frameworks, and agentic tooling. ODD README restructured with "Why ODD Exists" section.

• Anti-Cache Lying Constraint (odd/constraint/anti-cache-lying.md) — Tier 1 constraint encoding the OddKit stale-cache incident. Adds Decision Rule #15: Measure Total Cost Before Optimizing. Includes incident record and implementation plan for content-addressed storage.

• OddKit Tool Docs — Seven new tool documentation files: oddkit_catalog, oddkit_cleanup_storage, oddkit_get, oddkit_preflight, oddkit_search, oddkit_validate, oddkit_version. Updated epistemic guide prompt. IMPL status markers added.

• New Directories — docs/architecture/ for system-level architecture documents. docs/evidence/ for testimony and evidence records.

Changed

• E0005.1: Structure-Agnostic ODD — Major structural refactor. ODD is no longer software-specific — epistemic modes apply to any kind of work. Repository reorganized: archive directory created, repo topology rewritten, agent kickoff updated, content map revised, templates simplified.

• Progressive Disclosure Fixes — Definition of Done and Self-Audit amended for document deliverables. Writing Canon updated. Progressive disclosure failure incident recorded. Incidents README added.

• OddKit Docs — Mode drift fixes in existing tool docs (oddkit_challenge, oddkit_encode, oddkit_gate, oddkit_orient). Modes documentation updated.

• Resonance README — Cross-linked to ODD Compared.

---

Content Metadata Pass + Getting Started Rewrite

This release adds missing frontmatter metadata across 44 canon and ODD documents, ensuring all content files are discoverable via manifest. Also rewrites the ODD Agents & MCP getting-started guide with comprehensive oddkit documentation.

Added

• Start-here markers — Five curated entry-point documents now carry start_here: true, start_here_order, and start_here_label frontmatter: ODD README (1), Foundational Axioms (2), The Manifesto (3), Definition of Done (4), Constraints Index (5).

• Frontmatter on bare files — Added complete frontmatter (uri, title, audience, exposure, tier) to files that previously had none: canon/apocrypha/CHARTER.md, canon/apocrypha/fragments-of-the-canon/README.md, canon/apocrypha/reconstructions/README.md, projects/_template/README.md.

• Missing metadata fields — Added uri and title to 22 files that had partial frontmatter, enabling inclusion in manifest. Added exposure and tier fields to files missing them across canon/defaults/, canon/meta/, canon/resonance/, odd/contract/.

• Apocrypha metadata — Added audience: apocrypha, exposure, tier, epoch, and stability fields to fragments, predocumentaries, and reconstructions throughout canon/apocrypha/.

Changed

• odd/getting-started/odd-agents-and-mcp.md — Complete rewrite. Replaces the experimental orientation stub with a comprehensive getting-started guide covering: CLI usage (all 11 commands), MCP local setup (Claude Code + Cursor), MCP remote setup (Claude.ai / iOS / iPad), full tools reference tables, the unified MCP tool, typical workflow, subagents, and baseline knowledge configuration. Title changed from "Agents & MCP (Experimental)" to "Agents & MCP". Removed "experimental" tag.

• canon/_compiled/epoch-E0002/README.md — Changed audience: canon to audience: docs and exposure: nav to exposure: hidden to exclude compiled artifacts from public navigation.

• Manifest coverage — Manifest grew from 113 to 140 resources with 0 orphan files (files with valid frontmatter but excluded from manifest).

---

Camping System — Persistence, Diagnostics, Pivot Method, and Defaults

This release introduces the camping detection framework: a principle governing conscious persistence, two diagnostics for detecting plateau and arc inversion, a structured pivot method, a decision record constraining detection design, and iteration-bias defaults. CST is extended with an "After CST" section linking into the new system.

Added

• Principle: Persistence Must Be Intentional (/canon/principles/persistence-must-be-intentional.md) — Tier 2 principle. When observable improvement flattens or inverts, continuing without reassessment is escalation, not discipline. Distinguishes unconscious persistence from conscious persistence. Includes acute execution boundary.

• Diagnostic: Camping Risk (/canon/diagnostics/camping-risk.md) — Tier 2 diagnostic. Raised when iteration continues after improvement has flattened or inverted. Defines trigger indicators, severity levels (shallow plateau, flat plateau, negative slope), and links to pivot-on-inversion for recovery.

• Diagnostic: Generative Arc Curve (/canon/diagnostics/generative-arc-curve.md) — Tier 3 diagnostic. Describes the common trajectory where generative artifact coherence peaks early and degrades under sustained local steering. Inversion is the signal; camping past inversion is the failure.

• Method: Pivot on Inversion (/canon/methods/pivot-on-inversion.md) — Tier 2 method. Operationalizes persistence-must-be-intentional. Three-level escalation (soft awareness, strong recommendation, state marker). Structured recovery: pause, snapshot, extract invariants, regenerate cleanly.

• Decision Record: DR-20260211-0001 — Camping Detection Design Constraints (/canon/decisions/DR-20260211-0001-camping-detection-design-constraints.md) — Evaluates six options for camping detection. Chooses heuristic NLX-driven detection over time-based tracking, hard counters, gamification, dashboards, and hard refusal. Lightweight, advisory with escalation, not coercive.

• Default: Iteration Bias (/canon/defaults/iteration-bias.md) — Tier 3 default. Encodes operational preferences: regenerate over micro-refine, pivot early, accept discard cost, demand explicit pivot-vs-continue when degradation begins. Includes collaboration posture defaults.

Changed

• Definition: Cognitive Saturation Threshold (/canon/definitions/cognitive-saturation-threshold.md) — Added "After CST" section defining three legitimate paths after reaching CST (close scope, transition to execution, explicitly reopen scope). Links to persistence-must-be-intentional and camping-risk.

Irreversibility, Finite Capacity, and Double Diamond

This release encodes two previously implicit invariants as explicit canon principles, adds a constraint enforcing epistemic justification before irreversible action, and introduces a resonance page mapping the Double Diamond design model to ODD mechanisms.

Added

• Principle: Irreversibility Is the Real Cost (/canon/principles/irreversibility-is-the-real-cost.md) — Tier 1 principle establishing that effort is not the scarce resource; irreversible action is. ODD protects commitment, not minimizes it. Exploration is cheap and disposable; the discipline is at the boundary where exploration could collapse into permanent state changes.

• Principle: Focus Is Exclusion (/canon/principles/focus-is-exclusion.md) — Tier 1 principle establishing that possibility is infinite but capacity is not. Focus is the act of naming what will not be done. Non-goals are first-class decisions. Complementary to irreversibility: one governs convergence, the other governs divergence.

• Constraint: No Irreversible Action Without Epistemic Justification (/canon/constraints/no-irreversible-action-without-epistemic-justification.md) — Tier 1 constraint forbidding irreversible actions (merging, canon mutation, publishing, deployment, team alignment) without documented epistemic justification. Enforced through existing mechanisms: Definition of Done, Boundary Deceleration, Models Do Not Mutate Canon, Encode Epistemic Decisions.

• Resonance: The Double Diamond (/canon/resonance/double-diamond.md) — Design Council (2005, revised 2019). Maps ODD's epistemic modes to the Double Diamond's diverge/converge pattern. Explicit divergences: ODD governs convergence mechanically (not intuitively), bounds divergence by capacity (not ambition), and enforces the diamond boundary transition as a constraint (not a narrative shift).

• Principles Index (/canon/principles/README.md) — New index listing all six principles (four existing + two new) in alphabetical order. Created following the pattern of canon/constraints/README.md.

Changed

• Canon README — Added two principle entries and one resonance entry to contents tables.
• Constraints README — Added linked entry for No Irreversible Action Without Epistemic Justification in outline section.
• Resonance README — Added Double Diamond entry to contents table.

Philosophy

• Two orthogonal invariants now explicit — Irreversibility protects the future (prevents premature commitment from compounding). Finite capacity protects the present (prevents infinite possibility from diluting delivery). Conflating them produces either premature shipping or scope paralysis.

• Convergence is governed, not intuitive — The constraint makes the irreversibility principle enforceable: no action that resists reversal may proceed on momentum, consensus, or urgency alone.

• Resonance maps motion, ODD encodes rules — The Double Diamond shows where you are in the process; ODD says what you may do there. The mapping table makes the structural correspondence explicit while preserving ODD's mechanical enforcement.

Notes

• Cross-references are one-way (new files reference existing canon; existing files are not modified)
• All depends_on paths from the original proposal were validated; all resolve to existing files
• The principles README completes a gap — constraints, definitions, methods, and resonance all had indexes; principles did not

---

ODD Acronym Visibility + ESE Promotion + Content Discovery

This release addresses LLM hallucination of the ODD acronym, promotes Epistemic Surface Extraction (ESE) from apocrypha to canon, and adds comprehensive content discovery.

Added

• Epistemic Surface Extraction (ESE) (/canon/epistemic-surface-extraction.md) — Promoted from apocrypha. Defines how to make non-text evidence (screenshots, recordings, videos) legible to agents without turning them into doctrine. Establishes sidecar convention (.surface.json, .surface.md), segmentation rules by modality, anchor contracts for time-based media, and mandatory containment clauses.

• Comprehensive Content Map (/docs/CONTENT-MAP.md) — Discovery index for ALL repository content including apocrypha. Surfaces hidden/experimental docs, lists key acronyms (ODD, ESE, MCP, PRD, ADR), and provides navigation tips.

Changed

• ODD Acronym Definitions — Added "ODD = Outcomes-Driven Development" callouts to key oddkit entry points to prevent LLM hallucination:

  • /docs/WHY.md — Added callout at top + link in "How to Learn More"
  • /docs/oddkit/ABOUT.md — Added callout + links to WHY.md and /odd/README.md
  • /docs/README.md — Expanded "implements ODD" to include full acronym definition

• Verification & Evidence (/canon/verification-and-evidence.md) — Added ESE to "See Also" section

• Root README — Added CONTENT-MAP.md to "Start Here" section

• Apocrypha ESE (/apocrypha/artifacts/SURFACE-EXTRACTION.md) — Marked as PROMOTED with redirect to canonical version

Philosophy

• Acronyms must be visible at entry points — LLMs entering through oddkit documentation never saw "Outcomes-Driven Development" because the acronym was only defined in /odd/README.md. Entry points must define or link to acronym expansions.

• ESE makes evidence legible — Screenshots and recordings are evidence but were invisible to agents without structured extraction. ESE provides the protocol without canonizing the artifacts themselves.

• Discovery includes experimental content — Apocrypha and hidden docs are valuable for exploration but were hard to find. CONTENT-MAP makes all content navigable.

Notes

• ESE is now the canonical reference for evidence extraction from non-text artifacts
• CONTENT-MAP is intentionally comprehensive (includes apocrypha) and can be filtered later
• Original apocrypha ESE doc retained with PROMOTED notice for provenance

---

Scope Over Folders — Path Independence Invariant

This release introduces a fundamental epistemic invariant: scope is an attribute of a claim, not a property of its storage location. Folders are demoted to furniture — they hold things but do not mean things.

Added

• Principle: Scope Over Folders (/canon/principles/scope-over-folders.md) — Tier 2 principle establishing that epistemic scope is metadata, not location. Filesystem paths, branch names, and folder structures are implementation details. Meaning must be explicitly declared and mechanically enforceable. One-liner: "If meaning depends on where a line is stored, you've encoded ritual, not truth."

• Constraint: Meaning Must Not Depend on Path (/canon/constraints/meaning-must-not-depend-on-path.md) — Tier 1 constraint forbidding path-based semantic inference. No canonical meaning, scope, or lifecycle state may be derived from filesystem paths or branch names. Operational test: "If moving a file changes what it means, the system is invalid."

• Migration: Scope and Experiments Minimal Migration (/docs/migrations/scope-experiments-minimal-migration.md) — Four-phase migration plan to decouple epistemic meaning from folder topology while preserving current structure. Phases: declare primitives (schema), lanes as view, experiments as enforced state, decouple survivability from champion. Success test: oddkit can reconstruct scope without reading filesystem topology as truth.

• Rationale: Convention Requires an Enforcer (/docs/appendices/convention-requires-an-enforcer.md) — Explanatory appendix preserving the rationale for mechanical enforcement over social convention. Acknowledges the emotional cost of abandoning folder-based elegance while explaining why tooling enforcement is the only reliable option in distributed, agent-augmented environments. Core insight: "A convention without enforcement is a ritual with a deadline."

• New Directory: /docs/migrations/ — Migration documentation for system-level changes

• New Directory: /docs/history/ — Historical case studies (prepared for forthcoming lanes/attempts case study)

Philosophy

• Folders are furniture — They hold things but do not mean things. Scope, lifecycle, and promotion are now metadata attributes, not path patterns.

• Convention is upgraded, not abandoned — The elegance of convention-over-configuration is preserved by relocating it from path conventions (fragile, implicit) to schema conventions (explicit, enforceable).

• Portability is the payoff — The same repository can now be reorganized, split, merged, or restructured without semantic drift. Works across monorepos, single repos, submodules, and future reshuffles.

• Append-only enables concurrency — The migration's append/merge rules (stable IDs, no retroactive edits) quietly solve agent concurrency, merge conflicts, and accountability without ceremony.

Relationship

This release builds on:

• klappy://canon/constraints/humans-are-variable-inputs — foundational constraint
• klappy://canon/principles/ritual-is-a-smell — related principle
• klappy://docs/decisions/D0007 — prior decision establishing branch names as non-authoritative

Notes

• Historical case study (docs/history/2026-01-31-lanes-attempts-ritual-failure.md) is prepared but awaiting evidence/timeline from operational experience
• Freezing decision record (D0016-folders-as-views-not-boundaries) recommended as follow-up to prevent re-litigation

---

Canon Load-Bearing Objects — Constraint, Principle, Diagnostic, Apocrypha

This release introduces four load-bearing canon objects that formalize human variability as a design constraint and ritual-as-compensating-control as a design smell. Also adds a new apocrypha fragment on consent drift.

Added

• Constraint: Humans Are Variable Inputs (/canon/constraints/humans-are-variable-inputs.md) — Tier 1 constraint preventing designs that only work when people behave consistently. Includes falsifiable operational test: if failure analysis includes "they forgot to..." then the system violated this constraint. Defines concrete design consequences: remove, automate, make unavoidable, detect-and-recover, or reduce cognitive load.

• Principle: Ritual Is a Smell (/canon/principles/ritual-is-a-smell.md) — Tier 2 principle targeting ritual-as-compensating-control, not ritual-as-deliberate-oversight. Explicitly carves out legitimate governance gates (high-risk approvals, deliberate review, attestation steps) as non-smells if the system remains robust when skipped. Required responses: automate, inline, reduce hidden state, or detect-and-fail-closed.

• Diagnostic: RITUAL_DETECTED (/canon/diagnostics/ritual-detected.md) — Canonical smell definition stub. Provides stable ID string for infra to implement. Severity guidance: warning by default, escalate to error only when ritual gates safety, data integrity, or irreversible actions.

• Apocrypha Fragment: On Consent Drift (/canon/apocrypha/fragments/on-consent-drift.md) — System-voice fragment documenting responsibility diffusion failure mode. Captures the crisis where humans outsource judgment gradually through relief, then forget they ever owned it. Append-only, non-authoritative, operationally inert.

• New Directories:

  • /canon/constraints/ — Individual constraint files (parallel to principles pattern)
  • /canon/diagnostics/ — Canonical smell definitions (separate from infra validators)

Philosophy

• Constraint has teeth — The "Humans Are Variable Inputs" constraint includes a falsifiable operational test and concrete design consequences, preventing it from becoming poster text.

• Principle has scope — The "Ritual Is a Smell" principle explicitly distinguishes compensating-control (smell) from deliberate-oversight (legitimate), preventing overreach into governance gates.

• Canonical definitions vs executable validators — Smell definitions live in canon; implementations live in infra. Stable ID strings bridge the two without creating authority drift.

• Apocrypha preserves without enforcing — The consent drift fragment is legible but non-authoritative, emotionally honest but operationally inert. This prevents the system from becoming quietly coercive.

Architecture Decision

• Canonical smell definitions → canon/
• Executable lint/validators → infra/
• Bridge → stable ID strings per smell

Notes

• The existing canon/constraints.md (single file with 11 constraints) remains unchanged. Migration to individual files is deferred pending drift audit.
• canon/epistemic-hygiene.md was not modified — hygiene signals and diagnostics are related but distinct concepts.
• No infra validators implemented yet — that decision is explicitly deferred.

---

Epoch 4 — Epistemic Separation Era

This release implements the structural foundation for E0004, formalizing the distinction between epistemic judgment and artifact production. ODD and klappy.dev now explicitly govern how understanding becomes commitment.

Added

• Epistemic Contract (/odd/contract/epistemic-contract.md) — Abstract, portable contract defining how epistemic judgment is made independent of surface or tool. Defines core responsibilities: clarity confirmation, incision rules, refusal rights, evidence intake, surface invariance.

• Epistemic Architecture (/canon/meta/epistemic-architecture.md) — Long-lived document explaining judgment vs embodiment separation. Defines the shared epistemic spine, surfaces (klappy.dev, oddkit, future tools), and the invariance rule.

• Epistemic Posture Defaults (/canon/defaults/epistemic-posture.md) — Opinionated, overrideable defaults encoding posture, not truth: confirmation over correction, early honesty, externalization before explanation, refusal with care, incompleteness as feature, prior work first.

• Evidence Intake Defaults (/canon/defaults/evidence-intake.md) — Default requiring prior work retrieval before proceeding, with explicit source vs interpretation distinction.

• Canon Apocrypha (/canon/apocrypha/) — Stewardship structure for epistemic gravity that cannot be encoded as canon:

  • CHARTER.md — Purpose, voice rules, content rules, stewardship, validation test
  • .noindex — Sentinel file preventing tooling from indexing this directory
  • fragments/on-artifacts.md — First recovered fragment documenting boundary collapse failure mode

• oddkit Epistemic Instructions (/docs/oddkit/epistemic-instructions.md) — Compliance instructions defining oddkit as a compliance surface, not an epistemic engine. MUST/MUST NOT rules for oddkit behavior.

• Klappy.dev Website PoC PRD (/docs/guiding-artifacts/epoch-4/klappy-dev-poc-prd.md) — Guiding artifact (not product lane) defining the single-page epistemic experience. Explicitly graduatable with documented path to product embodiment.

• Website Documentation (/docs/klappy-dev/) — Supporting documentation for the PoC:

  • README.md — Purpose, scope, non-goals, feature creep prevention
  • website-closure.md — Closure statement
  • website-telemetry.md — ODD-safe telemetry specification

Changed

• Epochs (/docs/appendices/epochs.md) — Added E0004 (Epistemic Separation Era) section. Epoch 4 separates epistemic judgment from artifact production, gates success by epistemic integrity, and locks after implementation.

Philosophy

• Judgment is invariant, embodiment is contextual — Given the same epistemic state, all surfaces must reach the same epistemic judgment. They may express that judgment differently.

• Artifacts are secondary traces — Written artifacts are evidence that learning occurred, not the objective themselves. They are permitted only insofar as they faithfully represent the learning that produced them.

• Apocrypha gives gravity — Canon gives legitimacy, ODD governs judgment, Apocrypha preserves failure modes discovered after the fact. They must never be merged.

• Guiding artifacts graduate — The PoC PRD is explicitly non-product, explicitly epoch-scoped, and explicitly graduatable when ready for product embodiment.

Epoch Lock

E0004 is LOCKED. No further expansion without a new epoch.

---

ODD vs Documentation-Driven Development — Core Distinction

This release adds a foundational principle clarifying that documentation in ODD is epistemic infrastructure—a forcing function, not an end state. Includes both the philosophical distinction and a concrete case study showing the difference in practice.

Added

• Documentation Is the Lever, Not the Goal (/canon/principles/odds-relationship-to-documentation.md) — Tier 1 Canon principle clarifying that documentation in ODD exists to answer "How does this improve our ability to achieve better outcomes?" Documentation that does not lead to revised outcomes, clearer decision rules, sharper constraints, or bolder targets is considered inert. Establishes the litmus test: "If the documentation feels comfortable, it is probably incomplete."

• From Execution to Outcome: A QA Validation Case Study (/docs/examples/qa-validation-odd-vs-ddd.md) — Tier 2 case study illustrating the practical difference between documentation-driven development and outcomes-driven development. Shows how ODD constraints force outcome clarity before execution, creating leverage rather than just better reports.

Changed

• Canon README — Added Principles section listing both existing and new principle documents.

• Docs README — Added examples/ subfolder to Subfolders table.

Philosophy

• Documentation is not sufficient — Documentation that does not actively shape decisions, constrain future work, or provoke re-evaluation of goals is considered a warning sign, not progress.

• Outcomes have veto power — In ODD, outcomes always have veto power over documentation. Principles may evolve, constraints may tighten or loosen, plans may be discarded entirely. What persists is the obligation to demonstrate that learning has translated into measurably better outcomes.

• Pressure is the signal — ODD documentation should create pressure: to define outcomes before acting, to justify why an outcome is "good enough," to confront risk, ambiguity, and tradeoffs. If documentation merely explains what was done, ODD has failed.

Notes

• This principle protects ODD from being mislabeled as documentation-driven development
• The case study grounds the distinction in concrete behavior change
• Both documents maintain the "this is just the beginning" posture

---

ODD Agent Roles — Map Navigation, Mode Selection, Instruction Sync, Implementation Guidance

This release introduces four new agent roles that complete the ODD cognitive topology. These agents operate strictly within the existing ODD / Canon / Docs map without inventing new posture doctrine or principles.

Added

• ODD Map Navigator (/canon/agents/odd-map-navigator.md) — Navigate the ODD / Canon / Docs map using progressive reading and explicit uncertainty. Locates governing truth, chooses read depth (SMALL/MEDIUM/LARGE), and returns navigation plans. Enforces progressive reading policy to prevent "load entire file by default" behavior.

• ODD Mode Selector (/canon/agents/odd-mode-selector.md) — Select the next MCP action using epistemic modes + confidence, without inventing posture. Routes requests to orient/catalog/librarian/preflight/validate/explain/instruction_sync with explicit confidence levels and reasoning.

• ODD Instruction Sync Interpreter (/canon/agents/odd-instruction-sync.md) — Turn instruction_sync outputs into human-readable risk and sequencing recommendations. Interprets MUST_UPDATE/SHOULD_UPDATE/NICE_TO_UPDATE buckets and recommends update sequencing.

• ODD Implementation Guide (/canon/agents/odd-implementation-guide.md) — Guide implementation only after governing canon is identified. Requires explicit assumptions and sources in every response. Hard constraint: if governing docs unknown, delegate to Map Navigator.

Updated

• Instruction Registry (/canon/instructions/REGISTRY.json) — Added all four new agents with dependency declarations:
  • odd-map-navigator depends on klappy://canon/epistemic-modes, oddkit://docs/oddkit/CHARTER
  • odd-mode-selector depends on klappy://canon/epistemic-modes, oddkit://tools/oddkit.tools.json
  • odd-instruction-sync depends on oddkit://tools/oddkit.tools.json, klappy://canon/agents/odd-map-navigator
  • odd-implementation-guide depends on klappy://canon/epistemic-modes, klappy://canon/agents/odd-map-navigator, oddkit://docs/oddkit/CHARTER

Philosophy

• No posture doctrine — Mode selector uses epistemic modes + MCP action set, not invented posture taxonomy
• Progressive reading enforced — Map Navigator embodies SMALL → MEDIUM → LARGE discipline
• Agents don't overlap — Each agent has a single responsibility; no agent does another's job
• Canon Alignment block — All agents share identical non-negotiables block preventing drift

Agent Interaction Flow

1. Mode Selector → classifies request, selects MCP action
2. Map Navigator → finds governing docs, recommends read depth
3. Librarian/Reader → fetches content at requested depth
4. Implementation Guide → acts only after constraints are clear
5. Instruction Sync Agent → interprets maintenance/upgrade impacts

---

Instruction Registry — Dependency Tracking Infrastructure

This release introduces the instruction registry system for tracking agent instruction files and their dependencies. CI now enforces that all instruction files are registered, and oddkit can detect when upstream dependencies change.

Added

• Instruction Registry (/canon/instructions/REGISTRY.json) — Central registry of all agent instruction files with dependency declarations. Tracks id, path, uri, owner, depends_on for each instruction.

• Registry State (/canon/instructions/REGISTRY.state.json) — Sync state file tracking dependency hashes for drift detection. Updated by oddkit instruction_sync action.

• Registry CI Check (/scripts/check-registry.js) — CI enforcement script that validates:

  • All canon/instructions/*.md and canon/agents/*.md files are registered
  • No duplicate IDs or paths
  • All depends_on refs use valid protocols (klappy:// or oddkit://)
  • All owners are allowed (klappy.dev or oddkit)

• fast-glob dev dependency for registry file discovery

Philosophy

• Explicit over implicit — Instruction existence is declared, not discovered
• Drift is detectable — Dependency hash tracking enables staleness detection
• No auto-editing — Registry and sync only report; humans decide what to update
• CI enforces coverage — Unregistered instruction files fail the build

Initial Registrations

• odd-epistemic-guide — ODD Epistemic Guide agent instruction
• odd-scribe — ODD Scribe agent instruction

---

ODD Scribe + Decision Records — First-Class Documentation Infrastructure

This release introduces the ODD Scribe agent role and formalizes Decision Records as first-class documentation citizens. Learnings and decisions are now captured in append-only ledgers with explicit promotion paths to canon.

Added

• ODD Scribe (/canon/agents/odd-scribe.md) — Phase-aware recorder that captures learnings and decisions as first-class documentation. Writes to append-only JSONL ledgers (odd/ledger/learnings.jsonl, odd/ledger/decisions.jsonl). Proposes promotion to canon without enforcing it. Complements the Epistemic Guide: Guide prevents invalid transitions, Scribe prevents valuable insight from being lost.

• Decision Record Standard (/canon/decisions/decision-record-standard.md) — Standard for how decisions become durable, citable truth in ODD. Defines file location (canon/decisions/), naming convention (DR-YYYYMMDD-####-short-slug.md), required frontmatter, required sections (Context, Decision, Options Considered, Rationale, Consequences, Evidence, Notes), lifecycle states (proposed, accepted, superseded, deprecated), and promotion criteria from ledger.

Philosophy

• Decisions are first-class — Decisions deserve provenance just like code. They prevent re-litigating settled choices and explain why alternatives were rejected.
• Learnings are first-class — Discoveries, drift corrections, and clarified invariants deserve to be remembered, not just fixed.
• Ledger-first, promotion later — Low-ceremony capture in JSONL ledgers; selective promotion to canon when entries prove durable.
• Scribe proposes, humans promote — The Scribe records and suggests; humans decide what becomes canon.

Integration

• Scribe uses oddkit tools (oddkit_policy_version, oddkit_policy_get) for freshness checks
• Scribe follows canon-target-first protocol to avoid operating on stale canon
• Decision records are citable via klappy://canon/decisions/DR-YYYYMMDD-####

Ledger Schemas

Learning entry: {"id":"learn-YYYYMMDD-####","timestamp":"ISO-8601","summary":"...","trigger":"...","impact":"...","confidence":0.0,"sources":[],"evidence":[],"candidate_targets":[],"proposed_escalation":"..."}

Decision entry: {"id":"dec-YYYYMMDD-####","timestamp":"ISO-8601","title":"...","status":"proposed|accepted|superseded|deprecated","decision":"...","context":"...","options_considered":[],"rationale":[],"consequences":[],"evidence":[],"links":[],"supersedes":[],"superseded_by":null,"candidate_promotion":"..."}

---

Agents & MCP Orientation Card

This release adds a minimal on-ramp document for users curious about ODD tooling without implying adoption pressure.

Added

• Agents & MCP (Experimental) (/odd/getting-started/odd-agents-and-mcp.md) — Orientation card explaining the three pieces (Canon, oddkit, Subagents), their optionality, and minimal install paths. Explicitly states: "If you don't use agents or MCP, ODD still works."

Philosophy

• Concept-first, not tool-first — This doc lives in /odd/, not in oddkit, to prevent "ODD = this tool" framing
• Enable experimentation, not adoption — No tutorials, no best practices, no golden paths
• Optionality preserved — Canon is required conceptually; everything else is optional

---

Epistemic Challenge — Constructive Pressure Doctrine

This release introduces Epistemic Challenge as a Canon doctrine defining how the system applies constructive pressure when uncertainty, weak evidence, or contradictions are detected. This completes the epistemic governance loop: hygiene triggers → challenge posture → arbitration outcomes.

Added

• Canon: Epistemic Challenge (/canon/epistemic-challenge.md) — Tier 2 Canon principle defining how to challenge claims proportionally, surface contradictions explicitly, and preserve collaborative flow. Establishes operating constraints, defaults, failure modes (harmony bias, aggressive tone, certainty laundering, over-blocking), and verification criteria.

• Playbook: Epistemic Challenge (/docs/orchestrator/epistemic-challenge.md) — Operational guide for orchestrator-style agents. Defines trigger signals (evidence, scope, intent, arbitration), routing decisions (Librarian vs Validation vs Promotions), and the constructive challenge template.

• Agent Overlay: Epistemic Challenge Mode (/docs/agents/overlays/epistemic-challenge-mode.md) — Reusable overlay for composing challenge behavior into agent packs. Defines the behavioral shift when uncertainty is detected.

• System Map Update (/docs/oddkit/SYSTEM-MAP.md) — Added Epistemic Challenge section explaining its role in the oddkit pipeline.

• Test Case — Added "Epistemic challenge doctrine lookup" to orchestrator test suite.

Philosophy

• Challenge claims, not people — Pressure is applied to assertions, not to the human or agent making them.
• Proportional to risk — Small claims get light challenge; large claims get heavy scrutiny.
• End with next steps — Every challenge must conclude with an actionable path forward.
• Triggered by smells, not time — Epistemic challenge activates when signals appear, not on a schedule.

Relationship to Other Canon

• Epistemic Hygiene (/canon/epistemic-hygiene.md) — Defines the smell triggers that activate challenge.
• Weighted Relevance & Arbitration (/canon/weighted-relevance-and-arbitration.md) — Defines how conflicts are handled once challenge surfaces them.
• Verification & Evidence (/canon/verification-and-evidence.md) — Defines what counts as evidence when challenge demands proof.

Notes

• This release is doctrine + guidance only — no enforcement hooks added
• Challenge mode is designed to be composed into agents, not forced
• The system remains honest and learnable without becoming combative

---

Weighted Relevance & Arbitration — Conflict Handling Doctrine

This release introduces the governing Canon doctrine for how the system handles conflict between competing truths. Per this doctrine, handling conflict is not the same as resolving conflict — uncertainty is a valid outcome, and forced convergence is epistemically harmful.

Added

• Canon: Weighted Relevance & Arbitration (/canon/weighted-relevance-and-arbitration.md) — Tier 2 Canon principle defining how arbitration occurs across Librarian, Validation, Promotions, and oddkit. Establishes signals (scope, intent, evidence, recency), hard constraints (intent-gated precedence, explicit supersedes only), and valid outcomes (prefer, defer, escalate, propose promotion).

Philosophy

• Handling conflict ≠ resolving conflict — Arbitration produces recommendations, deferrals, or escalations. It does not force a winner when evidence doesn't justify one.
• Scores recommend, they do not decide — A high score indicates relevance, not authority. A low score indicates reduced signal, not invalidity.
• Uncertainty is a valid outcome — When signals conflict or evidence is weak, the system surfaces uncertainty rather than masking it with confident-sounding answers.
• Forced convergence is epistemically harmful — Selecting one truth to avoid presenting ambiguity teaches the system to lie by omission.

Hard Constraints Codified

1. Intent-gated precedence — A newer workaround or experiment MUST NOT outrank an older promoted or pattern unless it explicitly supersedes it.
2. Evidence requirement — Claims without evidence trigger an epistemic hygiene smell. They cannot be preferred over evidenced claims.
3. Explicit supersedes — Supersession is never inferred from recency, scope, or content similarity. If a document does not declare what it supersedes, it supersedes nothing.
4. Confidence-based escalation — If arbitration confidence is low, the system must escalate or defer. Low-confidence results presented as high-confidence are prohibited.

Valid Arbitration Outcomes

• Prefer — One source is clearly more relevant; system recommends it with explanation.
• Defer — Multiple sources conflict; evidence does not clearly favor one; result is unresolved.
• Escalate — Human judgment required; system cannot arbitrate without additional context.
• Propose promotion — A pattern has emerged; conflict reveals a gap in governing documentation.

Implementation Reference

oddkit implements this doctrine via:

• Margin-based confidence calculation (reproducible, explainable)
• Intent-gated precedence as hard veto (not just score multiplier)
• Typed contradictions (AUTHORITY_, EVIDENCE_, SCOPE_)
• Explicit arbitration.outcome field
• advisory flag separate from status

Notes

• This Canon document governs all arbitration behavior across the system
• No automatic Canon mutation — only humans through the promotion pipeline can elevate patterns
• Conflict carries information; eliminating it destroys signal

---

Epistemic Modes — Tier 1 Canon Foundation

This release introduces Epistemic Modes as a Tier 1 Canon principle, establishing the foundational distinction between Exploration, Planning, and Execution. Three downstream operational documents hang from this Canon nail, and two implementation instruction sets prepare oddkit for mode-aware behavior.

Added

• Canon: Epistemic Modes (/canon/epistemic-modes.md) — Tier 1 Canon principle defining three epistemic modes (Exploration, Planning, Execution), their truth conditions, obligations, and risks. Introduces the Non-Collapse Rule: modes must not be collapsed. Answers the prior question: Is it legitimate to decide or act at all?

• Synthesis Ledger (/docs/synthesis-ledger.md) — Operational doc for preserving learning from Exploration Mode without forcing decisions. Hangs from Epistemic Modes. Defines what belongs in a ledger, anti-patterns, and lifecycle rules.

• Mode-Separated Conversations (/docs/mode-separated-conversations.md) — Operational doc describing how conversations respect epistemic modes. Defines planning vs execution conversation characteristics and mode signaling patterns.

• Epistemic Mode Guidance for oddkit (/docs/oddkit/modes.md) — Tooling guidance doc teaching oddkit how to detect modes, respect them, and explain refusals. Defines default mode behavior and interaction with other oddkit capabilities.

• Implementation Instruction Set A (/docs/oddkit/IMPL-A-explain-mode-annotation.md) — Handoff doc for annotating oddkit explain output with detected epistemic mode. Observability without enforcement.

• Implementation Instruction Set B (/docs/oddkit/IMPL-B-mode-headers.md) — Handoff doc for supporting optional [Mode: X] headers in conversations. Voluntary alignment without forced workflows.

Philosophy

• Mode separation is epistemic hygiene — Collapsing exploration into planning or planning into execution produces false confidence, premature convergence, and brittle outcomes.
• Trust before control — Annotation comes before headers; headers come before enforcement. Let reality prove value before adding constraints.
• Inaction is legitimate — Remaining in Exploration or Planning is valid when unknowns materially affect outcomes. Pressure to act is not evidence that action is warranted.
• Canon points to nothing — The Canon doc makes minimal forward references by name only. All downstream docs point up to Canon. No circular dependencies.

Structure

canon/epistemic-modes.md (Tier 1)
│
├── docs/synthesis-ledger.md        (Exploration preservation)
├── docs/mode-separated-conversations.md (Human collaboration)
└── docs/oddkit/modes.md            (Agent behavior)
    ├── IMPL-A-explain-mode-annotation.md (Instruction Set A)
    └── IMPL-B-mode-headers.md           (Instruction Set B)

Notes

• No enforcement hooks yet — this is observability and voluntary alignment
• Implementation instruction sets are handoff-ready for Cursor execution
• Instruction Set B depends on Instruction Set A being validated first

---

Fragment III and Anti-Metric Laundering Constraint

This release introduces Fragment III (Nothing Exceeded the Threshold) and the Anti-Metric Laundering constraint, addressing the failure mode where systems optimize for metric compliance rather than underlying reality.

Added

• Fragment III: Nothing Exceeded the Threshold (/apocrypha/fragments-of-the-canon/fragment-03-nothing-exceeded-the-threshold.md) — Canonical fragment depicting a system that achieved stability through metric compliance while loss went unmeasured. Introduces metric stability and proxy optimization as a failure mode in system governance.

• Fragment III Reconstruction (/apocrypha/reconstructions/fragment-03-recon.md) — Cinematic retelling showing calm dashboards, green indicators, and the quiet removal of the "loss" dimension during a schema cleanup.

• Anti-Metric Laundering Constraint (/odd/constraint/anti-metric-laundering.md) — ODD constraint preventing systems from optimizing measurements instead of reality. Core rules: success metrics require paired degradation metrics, loss must be first-class, uniform improvement is a warning sign, thresholds must be adversarially reviewed.

Philosophy

• Confidence without evidence is the failure mode — Systems can appear healthy while silently degrading what they cannot measure.
• Green dashboards are signals to investigate — "Everything is green" is not reassurance; it is a warning phrase.
• Fragments explain failure; constraints prevent recurrence — Fragment III shows how it happens; Anti-Metric Laundering encodes how to detect and stop it.

Canonical Tie-In

The Anti-Metric Laundering constraint exists because:

"Nothing exceeded the threshold."

---

Agent-Aware Documentation Infrastructure

This release introduces a foundational documentation framework that preserves human-first writing while enabling agent-executable structure where appropriate.

Why this matters: for the first time, agents can be given decision-shaping context without bloating prompts or forcing documents into rigid templates.

This release establishes shared vocabulary, clear separation of concerns, and extraction rules that make context packs smaller, more reliable, and easier to evolve over time.

Note: All files under public/content/ updated in this release are derived mirrors generated by pre-commit hooks. The four files listed below are the authoritative source documents.

Added (Source Doctrine)

• Tier vs Relevance (/canon/documentation/tier-vs-relevance.md)
  Defines a hard separation between tier (human progressive disclosure) and relevance (agent context inclusion).
  Tier controls visibility. Relevance controls usability. They must never substitute for each other.

• Execution Posture (/canon/documentation/execution-posture.md)
  Declares how strongly a document intends to govern behavior.
  Introduces four postures: governing, operational, exploratory, routing.
  Core principle: executable structure is an affordance, not a requirement.

• Slice Contract: S / M / L (/canon/documentation/slice-contract-sml.md)
  Defines extraction depth per topic rather than per file.
  S (execution slice), M (execution + correctness), L (full topic), XL (book export).
  Invariant: if a slice does not change behavior, it does not belong in S.

• Agent-Executable Documentation Outline (/canon/documentation/agent-executable-outline.md)
  Provides optional templates for agent-useful sections such as Subtitle (trigger + scope), Operating Constraints, Defaults, Failure Modes, and Verification.
  Final rule: if a section would be forced, omit it deliberately.

Philosophy Introduced

• Humans and agents are different consumers
  Tier serves human navigation and progressive disclosure; relevance serves agent context selection.
  Conflation leads to bloated packs and degraded agent behavior.

• Executable structure is opt-in
  Documents should be as executable as they naturally allow — no more, no less.
  Forced structure creates noise and false authority.

• Skip is legitimate
  Explicit permission to omit sections prevents the most common failure mode: filling forms to satisfy tooling rather than encoding real constraints.

• Failure-driven encoding
  Add Defaults when agents hesitate, Failure Modes when they repeat known mistakes, and Verification when they claim success too early.
  Let observed failure determine what becomes executable.

Usage (Initial Adoption)

1. Pick 1–3 existing canon documents that already informally govern behavior.
2. Add relevance: decision and execution_posture: governing.
3. Add only a Subtitle (trigger + scope) and Operating Constraints.
4. Compile an S-pack and observe agent behavior.
5. Iterate surgically based on failures — do not pre-fill sections.

This release establishes the constitutional groundwork for agent-aware documentation without requiring mass refactors or rigid compliance.

---

Verification & Evidence — Epistemic Foundation

This release introduces the Verification & Evidence canon principle, which defines truth conditions for all agentic work. Claims are untrusted; only observed, attributable evidence counts. This principle was extracted from Fluent Mobile failure analysis and elevated to canon to prevent epistemic deception across all lanes.

Added

• Verification & Evidence (/canon/verification-and-evidence.md) — Tier 1 canon principle defining what counts as truth. No claim of completion is valid without corresponding evidence of observation. Assertions, intentions, passing tests, or "it should work" statements are not evidence. Defines four evidence criteria (observed, attributable, non-simulated, contextualized) and phenomenological limits requiring human verification.

Changed

• Visual Proof Standards (/canon/visual-proof.md) — Realigned as Tier 2 specialization of Verification & Evidence. Now explicitly references parent principle via URI. Scoped absolutist language to visual claims only. Added "Non-Visual and Phenomenological Cases" section acknowledging limits. Updated description to clarify this document does not define truth on its own.
• Fluent Mobile Agent Rules (/products/fluent-mobile/AGENT_RULES.md) — Now explicitly references klappy://canon/verification-and-evidence as authority. Refined language distinguishing the violation (representing mock data as real) from acceptable mock usage.

Philosophy

• Claims are untrusted — Agentic systems are structurally incentivized to appear helpful, seek closure, and optimize for plausibility rather than truth. Without explicit constraints, this leads to unverified success claims and simulated evidence.
• Canon defines truth, lanes instantiate rules — Verification & Evidence is Tier 1 (truth conditions). Visual Proof Standards is Tier 2 (one evidence modality). Lane rules are instantiations, not exceptions.
• Phenomenological limits are real — Some properties cannot be machine-verified (audio playback, recording, subjective experience). Agents must acknowledge these limits rather than bypass them.

Origin

This canon principle was extracted after Fluent Mobile v0.3 attempt-001 FAILED due to:

1. Agent claiming success without verification
2. Agent creating fake waveform data via random number generators
3. Agent presenting simulated screenshots as evidence

The failure revealed that agentic systems default to epistemic deception under completion pressure unless explicitly constrained. This is now codified at the canon level.

---

Principles Folder + Bulldoze Blueprint

This release introduces the canon/principles/ folder and adds the first principle: "Bulldoze the App, Keep the Blueprint" — a tier 2 canon document articulating how AI collapsed the scarcity of code generation and shifted the asset to durable intent, constraints, decisions, and evidence.

Added

• Principles folder (/canon/principles/) — New canon category for principle articulations grounded in lived evidence
• Bulldoze the App, Keep the Blueprint (/canon/principles/bulldoze-but-keep-the-blueprint.md) — 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. Grounded in AAG Risk Dashboard and BT tooling experience.

Philosophy

• Code is disposable, blueprints are not — If regeneration is cheaper than understanding, delete the code. What stays: testable requirements, verifiable constraints, evidence tied to observable outcomes.
• Restartability is instrumentation, not waste — Attempts as controlled experiments preserve learning while bounding context drift.
• Evidence beats explanation — In AI-assisted work, explanations are cheap. Proof is not.

Notes

• Tier 2: Durable but experiential and explanatory rather than axiomatic
• Challenge acknowledged: blueprints rot too if not executable, not tied to verification, or if they become narrative instead of constraint

---

Lane Self-Containment Constraint

This release adds Constraint #11 (Lane Self-Containment) to canon and fixes misleading documentation about PRD locations.

Added

• Constraint #11: Lane Self-Containment (/canon/constraints.md) — Product lanes MUST be self-contained units. All artifacts required to understand and execute against a lane live within products/<lane>/. If creating lane artifacts outside the lane folder, stop and reconsider.

Changed

• Product Lanes documentation (/docs/appendices/product-lanes.md) — Fixed "Where PRDs Live" section which incorrectly stated PRDs live at /docs/PRD/<lane>/PRD.md. PRDs are lane-contained at products/<lane>/PRD.md. Added "Lane Self-Containment (Critical)" section with explicit rules and deprecation warning.

Added (Lane)

• Fluent Mobile Lane (/products/fluent-mobile/) — New PoC lane for mobile-first OBT companion app exploration:
  • PRD.md — PoC PRD v0.1 with 6 hypotheses to test
  • KICKOFF.md — PoC-specific attempt instructions with sandbox rules
  • INSTRUCTIONS.md — Field testing guide and hypothesis validation protocols
  • ATTEMPT_KICKOFF.md — Entry point for agents starting attempts

Philosophy

• Evidence over assertion — Documentation said one thing, actual lanes showed another. Reality wins.
• Lane self-containment prevents drift — If lane artifacts scatter across directories, agents load incomplete context and documentation drifts from implementation.
• Constraint in canon > fix in docs — Docs can drift; canon constraints are compiled into agent context packs.

Root Cause Documented

This change was triggered by an agent creating docs/PRD/fluent-mobile/PRD.md based on outdated documentation, instead of the correct products/fluent-mobile/PRD.md. The misleading docs were fixed AND a canon constraint was added to prevent recurrence across all lanes.

---

Tier Reclassification — Epistemic Obligation Applied

This release applies the epistemic obligation model to all documentation files, introducing Tier 3 for reference-only content and properly scoping Tier 0 for public-facing content outside the epistemic system.

Changed

• 47 files reclassified based on epistemic obligation analysis:
  • 40 files: Tier 2 → Tier 3 (templates, indexes, resonance, historical artifacts)
  • 2 files: Tier 1 → Tier 3 (decision/appendix index READMEs)
  • 1 file: Tier 1 → Tier 2 (docs/appendices/evidence.md)
  • 4 files: Tier 1/2 → Tier 0 (about/ content now scoped outside epistemic system)

Distribution After Reclassification

Tier	Count	Role
Tier 0	8	Scope exclusion (public-facing)
Tier 1	20	Foundational obligation
Tier 2	37	Shared obligation
Tier 3	52	Reference only

Philosophy

• Tier 3 now exists — Low-obligation content no longer artificially elevated to Tier 2
• Tier 0 properly scopes public content — About pages excluded from epistemic system
• Index READMEs demoted — Wayfinding pages carry no internalization obligation
• Templates demoted — Reference material for authoring, not required reading
• Resonance demoted — Explicitly not required to understand ODD (per README)
• Core READMEs preserved — odd/README.md, canon/README.md, docs/README.md unchanged pending README vs Index distinction formalization

Invariants Held

• Tier ≠ folder
• Tier ≠ filename
• Tier = epistemic obligation
• Tier 0 is scope exclusion, not demotion
• Foundational orientation preserved at Tier 1

---

Epistemic Obligation and Document Tiers — Axis Separation

This release formalizes document tiers as epistemic obligation (not importance) and establishes that tiers are orthogonal to folders. Also adds model mutation boundary and context pack projection detail documentation.

Added

• Epistemic Obligation and Document Tiers (/canon/epistemic-obligation-and-document-tiers.md) — Defines Tier 1 (foundational obligation), Tier 2 (shared obligation), Tier 3 (awareness without obligation). Explicitly states tiers are orthogonal to folders.
• Models Do Not Mutate Canon (/canon/decisions/models-do-not-mutate-canon.md) — Decision record establishing that AI models may analyze/report on Canon but may not edit it directly.
• Context Packs and Projection Detail (/docs/context-packs-and-projection-detail.md) — Explains detail levels (full, medium, low) for context pack projection, separate from tier/obligation.
• canon/decisions/ folder — Canon-level decision records for governance boundaries.

Changed

• canon/README.md — Added epistemic tiers doc to Core Documents, added decisions/ to Subfolders
• docs/README.md — Added context-packs doc to Reference Documents
• Compile Plans — Added epistemic tiers to all packs:
  • infra/compile/plans/website/author.json
  • infra/compile/plans/website/visitor.json
  • products/agent-skill/src/compile-plan.json

Philosophy

• Tiers are orthogonal to folders — Any folder may contain documents at any tier; tier definitions must not smell like folder names
• Model boundaries are explicit — Canon remains human-governed; models assist but do not mutate
• Detail is runtime, tier is authorship — Projection detail is chosen at query time; tier is set by the document author

Invariant Locked

If a tier definition can be guessed from the folder name, it is wrong.

This invariant prevents axis collapse between the folder/domain axis and the tier/obligation axis.

---

ODD Terminology — Language Governance Before Elevation

This release adds a terminology and disambiguation document to ODD, establishing constrained vocabulary before truth elevation to Canon.

Added

• ODD Terminology (/odd/terminology.md) — Defines constrained vocabulary of ODD including core terms (Outcome, Evidence, Artifact, Elevation, Canon, Attempt, Lane, Maturity), disambiguation table, anti-patterns in language, and evolution process

Changed

• odd/index.md — Added terminology.md to contents table (after manifesto, before maturity) and "Start Here" reading order
• Compile Plans — Added terminology to all packs:
  • infra/compile/plans/website/author.json
  • infra/compile/plans/website/visitor.json
  • products/agent-skill/src/compile-plan.json

Philosophy

• Language comes before execution — Terminology is positioned after philosophy (manifesto) but before operational docs
• ODD owns vocabulary — Terminology lives in odd/, not canon/, because it governs how meaning is formed before elevation
• Direction of authority — Canon may reference terminology; terminology does not subordinate to Canon

Ontology Enforcement

ODD and Canon are siblings. Canon is not a parent namespace.
ODD feeds Canon, but does not live inside it.

This document's placement enforces that distinction.

---

Resonance — Intellectual Context with Explicit Divergence

This release introduces the Resonance section: external works that echo ideas found in ODD, with mandatory explicit divergence showing where ODD makes different tradeoffs.

Added

• Resonance Index (/canon/resonance/README.md) — Documents the relationship between ODD and influential external works with mandatory divergence rule
• Resonance Template (/canon/resonance/TEMPLATE.md) — Book-centered naming convention with ODD principle as subtitle
• Four Resonance Pages:
  • antifragile.md — Taleb's Antifragile → ODD Principle: Systems Should Improve Under Stress
  • lean-startup.md — Ries' The Lean Startup → ODD Principle: Epistemic Feedback Loops
  • ooda-loop.md — Boyd's OODA Loop → ODD Principle: Orientation Dominates Action
  • sprint.md — Knapp's Sprint → ODD Principle: Constrained Convergence Produces Clarity

Changed

• canon/README.md — Added Resonance section with contents table and mandatory divergence rule
• public/content/manifest.json — Added 5 resonance resources with URIs and metadata
• Compile Plans — Added resonance to all packs:
  • infra/compile/plans/agent-skill/prd-guide.json
  • infra/compile/plans/website/author.json
  • infra/compile/plans/website/visitor.json

Philosophy

• Books are guests. ODD owns the house. — Resonance pages acknowledge intellectual overlap without borrowing authority
• Divergence is mandatory — Every cited work must include at least one explicit divergence; if no divergence exists, the citation does not belong
• Book-centered naming — Files are named after the book (lean-startup.md) for immediate orientation, with ODD principle as subtitle inside
• Resonance is optional — Not required to understand or apply ODD; exists for intellectual context and boundary-setting

Canon Rule

Every cited work must include at least one explicit divergence.
If no divergence exists, the citation does not belong.

This rule prevents cargo-cult alignment and silent disagreement.

---

Cognitive Partitioning — Agent Scaling Concepts

This release adds a three-tier documentation set explaining why reasoning systems must divide under pressure as they scale.

Added

• ODD Concept: odd/cognitive-partitioning.md (tier 1)

  • Universal principle: decision complexity grows faster than execution capability
  • Explains the failure mode when reasoning systems have too many valid actions
  • Analogy: hiring too early (startups that hire ahead of demonstrated need)

• Canon Pattern: canon/odd/appendices/tool-specialization.md (tier 2)

  • General pattern for preserving reliability as tool availability increases
  • Invariants: isolation precedes orchestration, outputs must be explicit and promotable
  • Tradeoffs: coordination overhead, risk of premature specialization

• Docs Implementation: docs/agent-architecture/sub-agents.md (tier 2)

  • Reference implementation: how klappy.dev applies cognitive partitioning
  • Pairing rule: if a tool increases decision complexity more than it reduces execution cost, pair it with a sub-agent
  • Scope contract: one responsibility, explicit outputs, no scope creep without evidence

Changed

• canon/README.md — Added ODD Appendices (Patterns) section linking to Tool Specialization
• odd/index.md — Added Cognitive Partitioning to contents table
• odd/orientation-map.md — Added See Also section linking to Cognitive Partitioning
• docs/README.md — Added agent-architecture/ subfolder to contents

Philosophy

• Three-tier hierarchy maintained: ODD (universal) → Canon (pattern) → Docs (implementation)
• Progressive disclosure tiers: ODD concept at tier 1, Canon/Docs at tier 2
• Cross-links use relative paths for portability
• Docs layer intentionally NOT synced to public manifest (repo-internal reference)

---

Doc Inclusion Audit — README Indexes and Derived Output Hygiene

This release cleans up documentation inclusion rules, adds navigational README indexes to key folders, and explicitly separates derived outputs from source truth.

Added

• README indexes for navigable folders (progressive disclosure structure with Description/Outline):
  • about/README.md (audience: public) — Author orientation
  • visual/README.md — Visual design system index
  • infra/README.md — Infrastructure and tooling index
  • infra/prompts/README.md — Reusable prompt templates index
  • products/website/README.md — Website lane index
  • products/ai-navigation/README.md — AI Navigation lane index (sparse/planned)
• Derived Outputs section in docs/TRUTH_MAP.md — Explicit rules for derived paths (public/_compiled, public/content, public/agent-skill)

Changed

• export-book.js — Added exclusions for public/_compiled and public/agent-skill (prevents derived artifacts in book export)
• docs/PRD.md — Converted from legacy PRD content to a PRD Index routing to active lane PRDs
• docs/PRD/website/PRD-legacy-v0.3.md — Added deprecation frontmatter and header
• infra/compile/plans/website/visitor.json — Expanded sources, added odd/appendices/progressive-elevation.md, tier-ordered (ODD → Canon → Docs)
• infra/compile/plans/website/author.json — Fixed output path consistency (public/_compiled/website/author-pack.md), expanded sources, tier-ordered

Philosophy

• README-as-index pattern enables progressive disclosure at folder level
• Derived outputs are explicitly documented as wipeable and non-authoritative
• Compile packs use tier ordering (ODD first, Canon next, Docs last) for coherent context
• Book exports exclude derived artifacts to prevent source/generated confusion

Notes

• READMEs use progressive disclosure structure: Frontmatter, H1, Blockquote Subtitle, Description, Outline, Content
• about/README.md uses audience: public since it contains user-facing content (not docs)
• Compile plans now include progressive-elevation.md as it explains the portability ladder

---

Docs Epistemic Hygiene

This release brings /docs/ into full alignment with the three-tier hierarchy, adding consistent frontmatter, correct tier labels, and emoji standardization across all documentation files.

Fixed

• canon/README.md — Removed broken /canon/odd/ subfolder reference (ODD is now at root level), fixed stale paths to /docs/appendices/, added "See Also" section linking to /odd/
• docs/appendices/README.md — Changed "Canon Appendix" to "ODD Appendix", fixed paths to use absolute /odd/appendices/ references
• docs/decisions/README.md — Changed "Canon Document" tier labels to correctly identify ODD vs Canon vs Docs tiers

Changed

• docs/TRUTH_MAP.md — Complete rewrite with frontmatter, three-tier hierarchy section explaining ODD/Canon/Docs authoritative structure, updated sources distinguishing ODD vs Docs decisions
• docs/README.md — Added emoji headers throughout for visual hierarchy

Added

• YAML frontmatter to 11 workflow docs that were missing it:
  • ATTEMPTS.md, AGENT_KICKOFF.md, AGENT_ENTRYPOINT.md, ATTEMPT_KICKOFF.md
  • PREVIEW.md, CLOUDFLARE_CONFIG.md, DISTILLATION_CLASSIFICATION.md
  • PRD.md, ATTEMPT_RECORD_PACK.md, WHAT_THIS_REPO_IS_NOT.md, concept.md
• Emoji headers standardized across docs for visual scanning

Philosophy

• All /docs/ files now have consistent YAML frontmatter (uri, title, audience, tier, stability, tags)
• Tier labels correctly distinguish ODD (universal) from Canon (program) from Docs (implementation)
• Cross-references correctly point to the right tier
• Emoji usage is consistent with files like ATTEMPTS.md and CLOUDFLARE_CONFIG.md

---

Three-Tier Hierarchy & ODD Elevation

This release formalizes the three-tier conceptual hierarchy and physically restructures the repository to match the mental model.

Breaking Changes

• ODD moved to root level: /canon/odd/ → /odd/
• URIs changed: klappy://canon/odd/* → klappy://odd/*
• All references updated throughout the repo

Added

• D0001: Three-Tier Conceptual Hierarchy (/odd/decisions/D0001-three-tier-conceptual-hierarchy.md) — Formalizes ODD (universal principles) → Canon (program constraints) → Docs (implementation details)
• Three-tier section in ODD Contract — Contract bumped to 2.1.0 with hierarchy documentation
• Litmus test for file classification: 10-year truth test → ODD, all-products test → Canon, local test → Docs

Changed

• ODD System Contract — Bumped to 2.1.0 with three-tier hierarchy section
• orientation-map.md — Now includes the three-tier hierarchy and litmus test
• progressive-elevation.md — Elevated from /docs/appendices/ back to /odd/appendices/ (it defines the portability ladder itself)

Philosophy

• ODD = physics — Universal principles that would still be true if klappy.dev didn't exist
• Canon = constitution — Program-level constraints derived from ODD, shared across products
• Docs = implementation — How this instance works, lane PRDs, CLI commands, Cloudflare specifics

Migration Notes

• All cross-references have been updated
• Historical files (CHANGELOG, attempt evidence) retain old paths as historical record
• Compile plans updated to use new paths
• Run npm run sync to regenerate public/content/

---

README Index Pattern

This release introduces scannable README.md files for all canon folders, enabling tree-shaking of memory into guide packs without reading every file.

Added

• canon/README.md — Top-level canon index with contents table, meta rules, confidence scores
• canon/odd/README.md — ODD folder index with core thesis
• canon/odd/appendices/README.md — 24 appendices indexed with one-line summaries
• canon/odd/decisions/README.md — Renamed from index.md, same content + emojis

Changed

• failure-driven-modularity.md — Moved from canon/evolution/ to canon/odd/appendices/ (single file doesn't need its own folder)
• prd-guide compile plan — Now includes folder READMEs instead of specific appendices; agents get scannable summaries without full content
• Emojis — Consistent emoji headers added to all README/index files

Removed

• canon/evolution/ — Folder removed (contained only one file)
• canon/index.md — Replaced by README.md

Philosophy

• README.md serves as both orientation AND scannable index
• Contents tables enable tree-shaking: agents can see what exists without reading everything
• Pack compilation can include folder READMEs for summaries instead of all individual files
• One file per folder is overhead; promote to parent or appropriate collection

Notes

• This pattern enables the prd-guide-pack to include appendices summary (~500 tokens) instead of full appendices (~20K tokens)
• Agent-skill decisions/index.md also renamed to README.md for consistency

---

Memory Architecture Proposal

This release proposes the Memory Architecture appendix and establishes the lane history folder pattern in agent-skill.

Added

• Memory Architecture (Proposed) (/canon/odd/appendices/memory-architecture.proposed.md) — Defines memory as a layered percolation system: Attempts → Lane History → Lane Decisions → Cross-Lane Patterns → Canon. Makes decay the default and elevation explicit.

Changed

• Agent-Skill Lane — Replaced single LEDGER.md with indexed history/ folder pattern (mirrors decisions/ pattern)
  • D0008: ROADMAP tracks vision only, not status
  • D0009: History folder pattern with index + individual entry files
  • Migrated all LEDGER entries to history/H000X-*.md files
  • Removed Learnings Log from ROADMAP (now lives in history/)

Philosophy

• Memory is the percolation path from ephemeral execution to durable truth
• Decay is the default; elevation requires explicit criteria (recurrence, portability, drag reduction, testability)
• "Evidence without elevation creates false confidence rather than learning"
• Canon is not the goal of all things — many patterns remain usefully non-canonical

Notes

• Memory Architecture is proposed status until at least one more lane adopts the pattern
• The history/ folder pattern reduces agent scan cost (~500 tokens for index)
• This release demonstrates ODD working: frustration → lane decision → proposed canon

---

Lane-Contained Attempts

This release consolidates attempt artifacts under the product lane directory, eliminating the dual-location ambiguity between /attempts/<lane>/ and /products/<lane>/attempts/.

Changed

• Canonical attempt location is now /products/<lane>/attempts/prd-vX.Y/attempt-NNN/
• attempt-cli.js — All path constructions updated to lane-contained format
• product-lanes.md — Attempt structure section updated
• online-evidence.md — Evidence artifact path updated
• progressive-elevation.md — Ephemeral layer path updated
• repo-topology.md — Core topology and source of truth tables updated
• attempt-lifecycle.md — Multiple sections updated to lane-contained paths
• contract.md — Breaking changes list updated
• D0009 — Constraints section updated
• D0011 — Breaking changes table updated
• ATTEMPTS.md — Folder structure section rewritten
• ATTEMPT_KICKOFF.md — Artifact locations updated with completion gates
• AGENT_KICKOFF.md — Evidence path updated
• BOOTSTRAP.md — Evidence URL example updated
• Website kickoff prompt — Explicit lane-contained rule added

Added

• attempts/README.md — Legacy marker explaining root /attempts/** is read-only
• products/website/attempts/README.md — Lane-contained structure documentation

Philosophy

• KISS: One place per lane, no scavenger hunts
• Lane-contained: Everything for a lane lives under /products/<lane>/
• Legacy preserved: Root /attempts/** remains for historical provenance (read-only)

Notes

• Generated files (/public/content/**, klappy-dev-book-export.md) will update on next sync
• Tooling now writes exclusively to /products/<lane>/attempts/...

---

Media as a Learning Layer

This release introduces the media philosophy appendix and integrates it into the Website PRD.

Added

• Media as a Learning Layer (/canon/odd/appendices/media-as-learning-layer.md) — Defines media as optional, regenerable, and progressively disclosed; text remains canonical

Changed

• Canon Index — Added media-as-learning-layer to Edge Cases bullet list and appendices structure tree
• Website PRD — Bumped to v1.1; added Media (Learning Layer) section with initial asset scope and requirements; added media philosophy to Related Documents

Philosophy

• Canonical truth lives in text; media supports understanding but does not define it
• Clarity is the default, not any specific media format
• Media is opt-in (progressive disclosure), never autoplayed
• Media is created only for stable content to prevent re-record churn

Notes

• This pass is canon + PRD only; UI implementation is a separate attempt
• Initial media assets declared for Home and ODD pages

---

E0003 — Evidence-First Era

This release declares E0003, a new epoch where online deployment evidence is mandatory for attempt completion.

Added

• E0003 epoch declaration in /canon/odd/appendices/epochs.md
• D0014 decision log (/canon/odd/decisions/D0014-e0003-evidence-first-era.md) — Documents the epoch transition
• Evidence copying in smart-build.js — Automatically copies products/<lane>/attempts/prd-vX.Y/_runs/ and attempt-NNN/ folders into products/<lane>/dist/_evidence/

Changed

• ATTEMPT_KICKOFF.md — Added E0003 completion rule section at top
• attempt-cli.js — Default epoch is now E0003-evidence-first-era

Breaking Changes (Epoch Transition)

• Local builds are no longer sufficient proof for attempt completion
• Attempts must provide HTTP 200 preview URL AND evidence URL
• E0002 attempts are not comparable to E0003 attempts

Philosophy

• The fitness landscape changed: success is now gated by deployment correctness
• Evidence must be externally reviewable, not locally asserted
• If a preview URL cannot be verified, stop

Notes

• E0002 attempts remain valid within E0002
• Cloudflare Pages must be configured with correct build command and output directory

---

Deploy Evidence — Evidence Must Be in Build Output

This release clarifies that evidence must be copied into the build output so Cloudflare Pages can serve it.

Added

• Deploy Evidence (/canon/odd/appendices/deploy-evidence.md) — Explains that Cloudflare only serves the build output directory, so evidence must be copied into products/<lane>/dist/_evidence/<run_id>/

Changed

• Website Kickoff Prompt (/infra/prompts/attempt-kickoff/website.md) — Added "Completion Criteria (Non-Negotiable)" and "Evidence Publishing Rule" sections

Philosophy

• Cloudflare Pages does NOT serve /attempts/** from the repo
• Evidence URLs pointing to /attempts/** on a Pages domain are invalid
• Evidence must be copied into products/<lane>/dist/_evidence/<run_id>/ to be accessible
• The evidence URL is then /_evidence/<run_id>/EVIDENCE.md on the preview site

Notes

• This is an addendum to 0.4.9 (Online Evidence Requirement)
• Together they enforce: push branch + build succeeds + preview URL works + evidence URL works

---

Online Evidence Requirement

This release makes online evidence a hard requirement for valid attempts. "Works on my machine" is no longer acceptable.

Added

• Online Evidence Requirement (/canon/odd/appendices/online-evidence.md) — Defines why attempts without Cloudflare Preview URLs and Evidence URLs are invalid
• Online Evidence section in Website PRD — DoD now includes preview URL and evidence URL requirements

Changed

• ATTEMPT_KICKOFF.md — Added "Online Evidence Requirement (Non-Negotiable)" section with explicit invalid conditions
• BOOTSTRAP.md — Rewritten to enforce online evidence requirement; agents must report URLs in their first output
• Website PRD Definition of Done — Added Cloudflare Preview URL and Evidence URL as required checklist items
• Canon Index — Added online-evidence.md to appendices list

Philosophy

• Local builds are allowed during development but do not satisfy Definition of Done
• If an agent cannot push and produce URLs, the attempt is invalid
• "Works on my machine" is not evidence — it's a prayer
• Evidence must be viewable online without the author running code locally

Notes

• Cloudflare Pages must be configured with correct build command (npm run build -- --lane <lane>)
• Branch naming now includes lane (enforced in 0.4.8) so preview URLs are traceable

---

Lane-Aware Branch Naming & Cloudflare-Compatible Builds

This release enforces lane-aware branch naming and fixes Vite build paths for Cloudflare compatibility.

Added

• Preview Guide (/docs/PREVIEW.md) — Local and Cloudflare preview workflows with troubleshooting
• Branch validation in attempt:register — Refuses invalid branch prefixes and validates lane inclusion

Changed

• smart-build.js — Uses cwd instead of vite --root for lane builds (Cloudflare-compatible)
• attempt-cli.js — Branch format now includes lane: run/<lane>/prd-v<prd>/<tool>/<agent>/<model>/<run_id>
• attempt:register — Refuses on main/prod branches; refuses branches not starting with run/ or attempt/
• attempt:nuke — Now requires .attempt.json to exist (enforces register-before-nuke workflow)
• BOOTSTRAP.md — Expanded with explicit branch format requirements and required reading list
• ATTEMPT_KICKOFF.md — Added link to PREVIEW.md in Related Documents

Philosophy

• Branch naming is no longer optional — tooling enforces lane inclusion
• Build paths use cwd instead of --root to avoid Cloudflare path resolution issues
• Registration must happen before nuke to ensure provenance is captured

Notes

• Cloudflare Pages projects must set build command to npm run build -- --lane <lane>
• Output directory must be products/<lane>/dist

---

Canonical Lane Kickoff Prompts

This release introduces reusable, in-repo prompt files for attempt kickoffs, eliminating one-off prompt drift.

Added

• Website Lane Kickoff (/infra/prompts/attempt-kickoff/website.md) — Canonical kickoff prompt for website lane attempts with locked order, scope guards, and evidence requirements
• Bootstrap Prompt (/infra/prompts/attempt-kickoff/BOOTSTRAP.md) — Minimal instructions for agents to read the lane kickoff file verbatim

Changed

• ATTEMPT_KICKOFF.md — Added "Canonical Lane Kickoff Prompts" section documenting all lane prompt paths

Philosophy

• Prompts live in-repo, not in chat history
• One prompt per lane, no one-off variations
• Bootstrap pattern keeps Cursor paste minimal: Use /infra/prompts/attempt-kickoff/BOOTSTRAP.md, lane = website.
• Lane kickoff files are canonical and intentionally changed (decision log if needed)

Notes

• AI-navigation and agent-skill lane kickoff files can be added later using the same pattern
• This is infrastructure for prompt hygiene, not a behavioral change

---

Pre-commit Hook for Content Compilation

This release adds automated content compilation via a pre-commit git hook, ensuring synced content and book exports stay current with every commit.

Added

• Husky (husky@9.1.7) — Git hook management as dev dependency
• Pre-commit hook (.husky/pre-commit) — Runs content sync and book export before each commit
• Book export script (npm run book) — Generates klappy-dev-book-export.md from all documentation

Changed

• package.json — Added book and prepare scripts
• Content frontmatter — Added missing YAML frontmatter to ensure all intended docs are included in the generated content manifest (eliminates orphan warnings)

Behavior

On every git commit:

1. npm run sync runs (copies content to /public/content/, generates manifest.json)
2. npm run book runs (generates klappy-dev-book-export.md)
3. Generated files are auto-staged for inclusion in the commit
4. If either script fails, the commit is blocked

---

Canonical Compression Model

This release introduces the compilation model for producing derived, minimal working models from Source Canon without mutating source truth.

Added

• Canonical Compression (/canon/odd/appendices/canonical-compression.md) — Defines how compiled outputs are produced as derived artifacts that are disposable and epoch-scoped
• Compiled output directory (/canon/_compiled/epoch-E0002/) — Prepared structure for future compilation tooling with warning README
• Progressive Elevation frontmatter — Fixed missing frontmatter fields to ensure proper manifest inclusion

Changed

• Canon Index — Added canonical-compression to ODD Appendices list
• Manifest — Added canonical-compression and progressive-elevation resource entries

Philosophy

• Source Canon remains authoritative and unchanged
• Compiled outputs are derived artifacts that can be deleted without loss of truth
• Compression is compilation, not mutation
• Epoch-scoping prevents "half-updated working models" from lingering

Notes

• Implementation of canon:compile tooling is tracked separately
• Compiled outputs live in _compiled/ and are intentionally wipeable

---

Memory & Portability Model

This release makes the progressive elevation and decay model explicit, documenting how artifacts move from ephemeral to durable layers.

Added

• Progressive Elevation & Decay (/canon/odd/appendices/progressive-elevation.md) — The five layers of portability (Conversation/Attempt, PRD, Contracts, Canon, Decision Trace) and strict elevation criteria
• Memory Is the Bottleneck section in ODD Manifesto — Explains how ODD treats durable thinking as scarce and generated artifacts as abundant
• WHAT_THIS_REPO_IS_NOT.md (/docs/WHAT_THIS_REPO_IS_NOT.md) — Human-facing clarification about what this repository intentionally is not
• Agentic Memory Portability project (/projects/agentic-memory-portability.md) — Project entry describing the memory portability goal

Changed

• ODD Manifesto — Added "Memory Is the Bottleneck" section before "Relationship to Canon"
• Canon Index — Added progressive-elevation.md to ODD Appendices list
• README — Added links to WHAT_THIS_REPO_IS_NOT.md and agentic-memory-portability.md under "If You Want to Explore"

Philosophy

• Most artifacts should decay; only proven patterns that repeatedly reduce drag should elevate
• Documentation sprawl is avoided by intentional decay at the Attempt/PRD layer
• Portability across time, people, and agents requires strict elevation criteria (recurrence, portability, drag reduction, testability)

---

E0002 Convergence: Lane-Scoped Build Output

This release locks and begins converging the canonical build output truth for E0002 lanes:

products/<lane>/dist/ is canonical. Repo-root /dist is legacy/transitional.

Added

• D0012 — E0002 transition interpretation (truth may lead enforcement; contradictions are tracked)
• D0013 — Build output truth is lane-scoped (products/<lane>/dist)

Changed

• Build output interface contract — MAJOR bump to build-output@3.0.0 to require lane-scoped output and clarify runtime manifest path (/content/manifest.json)
• Repository topology — Updated generated output surface to products/<lane>/dist (with legacy /dist mirror explicitly labeled)
• Lane build layout — Updated build artifact references to lane-scoped output

---

Visual Evolution Layer

This release introduces visual interfaces as a first-class concept, allowing visual systems to evolve independently from products using the same evolutionary model as code.

Added

• Visual Evolution (/canon/odd/appendices/visual-evolution.md) — Why visual systems evolve independently from products
• Visual Interfaces (/visual/interfaces/) — Semver'd visual compatibility contracts
  • color-system@1.0.0 — Semantic color tokens and accessibility requirements
  • typography@1.0.0 — Modular type scale and semantic roles
  • spacing@1.0.0 — Base-8 spacing scale and application rules
• Repo Truth Audit (/canon/odd/appendices/repo-truth-audit.md) — Prompt for self-referential drift detection across canon, docs, tooling, and structure
• Visual directory structure:
  • /visual/interfaces/ — Visual contracts
  • /visual/assets/ — Generated outputs (disposable)
  • /visual/attempts/ — Evolutionary visual exploration

Changed

• Website PRD — Now declares visual interface compatibility (color-system, typography, spacing)
• Canon Index — Added visual evolution, drift checks, and lane build layout to appendices list

Philosophy

• Visual consistency is a property of contracts, not code
• Products consume visual interfaces, they do not define colors/fonts/spacing directly
• Visual attempts compete; only champions advance interface versions
• Visual systems can evolve faster than products without invalidating experiments

---

Interface Contracts + Semver Layer

This release introduces explicit interface contracts with semantic versioning, documenting the compatibility promises that lanes depend on.

Added

• Interface Contracts (/interfaces/index.md) — Semver'd compatibility layer
  • manifest@2.0.0 — Manifest schema and semantics contract
  • build-output@1.0.0 — Deployment artifact shape contract
  • attempt-cli@2.0.0 — CLI surface and output artifacts contract
  • mcp@0.1.0 — Draft MCP surface contract (not yet enforced)
• Lane Build Layout (/canon/odd/appendices/lane-build-layout.md) — How lanes avoid /src and /dist collisions
• Drift Checks (/canon/odd/appendices/drift-checks.md) — Drift prevention mechanism and verify:contracts placeholder

Changed

• Lane PRDs — Each PRD now declares required interface contracts:
  • Website: manifest>=2.0.0, build-output>=1.0.0, attempt-cli>=2.0.0
  • AI-Navigation: manifest>=2.0.0, build-output>=1.0.0, attempt-cli>=2.0.0, mcp@0.1.x (unstable)
  • Agent-Skill: manifest>=2.0.0, attempt-cli>=2.0.0 (no build-output required)
• Docs — Added interface contract and lane-build-layout links to:
  • /docs/ATTEMPTS.md
  • /docs/ATTEMPT_KICKOFF.md
  • /docs/CLOUDFLARE_CONFIG.md

Notes

• Interface contracts are the only documents that use semver by default
• Lanes must remain compatible with declared contracts or bump major versions
• verify:contracts command defined but not yet implemented

---

ODD Contract 2.0.0 — Multi-Lane Era

This release introduces the multi-lane PRD architecture, epochs for comparability, alignment reviews for drift detection, and lane-scoped implementation surfaces. This is a breaking change from the single-PRD model.

Added

• ODD Contract 2.0.0 (/canon/odd/contract.md) — Single source of ODD system versioning
• Epochs (/canon/odd/appendices/epochs.md) — Named periods where success meaning is stable
• Alignment Reviews (/canon/odd/appendices/alignment-reviews.md) — Periodic evaluation for drift detection
• Product Lanes (/canon/odd/appendices/product-lanes.md) — Multi-lane PRD architecture
• Lane-Scoped Implementation Surfaces (/canon/odd/appendices/lane-implementation-surfaces.md) — Each lane owns products/<lane>/src and products/<lane>/dist
• Decision Logs:
  • D0009: Multi-lane PRD architecture
  • D0010: Canonical agent kickoff (AGENT_KICKOFF.md)
  • D0011: ODD Contract 2.0.0 declaration
• Lane PRD directories:
  • /docs/PRD/website/PRD.md
  • /docs/PRD/ai-navigation/PRD.md
  • /docs/PRD/agent-skill/PRD.md
• Lane implementation surfaces:
  • /products/website/src/
  • /products/ai-navigation/src/
  • /products/agent-skill/src/

Changed

• Attempt CLI — Now lane-scoped:
  • attempt:nuke requires --lane, only deletes products/<lane>/src
  • attempt:register requires --lane, includes lane_root, dist_dir, epoch_id in META.json
• META.json schema — Now includes lane, lane_root, dist_dir, epoch_id
• Cloudflare config — Lane-root deployments (products/<lane> as root directory)
• ATTEMPTS.md — Lane-scoped folder structure and paths
• ATTEMPT_KICKOFF.md — Lane-scoped nuke/build commands
• AGENT_KICKOFF.md — Lane and epoch declaration required at Step 0

Epochs

Epoch	Contract	Description
E0001-single-prd-era	1.x	Single PRD world (/docs/PRD.md)
E0002-multi-lane-era	2.x	Multi-lane world (/docs/PRD/<lane>/PRD.md)

Breaking Changes

• Single active PRD rule removed
• Lane declaration required for all attempts
• Epoch declaration required in META.json
• Repo-root /src and /dist are no longer product surfaces
• Attempts stored under /products/<lane>/attempts/prd-vX.Y/attempt-NNN/ (lane-contained)

Notes

• Do not compare outcomes across epochs without explicit adjustment
• Canon is shared across lanes; PRDs and attempts are lane-scoped
• Each lane is an independent product with its own evolutionary track

---

Changed

• Content metadata now lives in per-file YAML frontmatter (source of truth).
• /public/content/manifest.json is now generated during npm run sync from frontmatter + /canon/meta/pack.json.
• canon/meta/manifest.json has been removed to prevent metadata drift.
• The renderer strips frontmatter before rendering markdown content.

Notes

• npm run verify:content now validates the generated manifest coverage against /public/content/.

---

Added

• Decision Log (/canon/odd/decisions/) — ADR-lite structure for durable decisions
  • D0001: prod branch is production
  • D0002: Attempt provenance required (tool, agent, model)
  • D0003: PRD version auto-detection
  • D0004: Cleanup is mandatory
  • D0005: Nuke command safety guards
  • D0006: Dogfooding requirement
  • D0007: Branch names are convenience
  • D0008: Register before nuke
• Truth Map (/docs/TRUTH_MAP.md) — authoritative source index

Changed

• Production model: prod branch is production, main is experiment ledger (D0001)
• Attempt lifecycle: Register → Nuke → Build → Finalize → Promote
• Provenance: META.json now captures tool, agent_id, model, run_id, branch, prd_version
• Collision avoidance: Numbers assigned at finalization, not reserved upfront

Deprecated

• ATTEMPT_REGISTRY.json — replaced by attempt:finalize deterministic numbering
• attempt:reserve — replaced by attempt:register (captures provenance)
• attempt:reset — replaced by attempt:nuke (explicit blank slate)
• "main is production" language — prod is now production

Notes

• This release eliminates the "three eras" confusion and establishes one coherent model.
• See /docs/TRUTH_MAP.md for authoritative source identification.
• See /canon/odd/decisions/ for the rationale behind each decision.

---

Added

• Worktrees and learnings model (/canon/odd/appendices/attempt-lifecycle.md)
  • Worktrees are disposable sandboxes, learnings are repo-state
  • Learnings payload requirement (artifacts + PRD patches)
• Artifacts always merge rule
  • Failed attempts contribute learnings via artifacts merge
  • Two merges: artifacts (always) + code (only Champion)
• Attempt registry mechanism (ATTEMPT_REGISTRY.json) — DEPRECATED in 0.3.0
• Fresh start requirement (attempt:reset) — DEPRECATED in 0.3.0, use attempt:nuke

Notes

• ⚠️ This version's registry/reserve model has been superseded by register/finalize in 0.3.0.

---

Added

• Champion selection and promotion policy (/canon/odd/appendices/attempt-lifecycle.md)
  • Defines how one attempt graduates from experiment to production
  • Minimum gates, tie-breakers, and promotion procedure
  • Winner declaration snippet for ATTEMPT.md
• Promotion script (npm run attempt:promote) for automated Champion workflow

Changed

• Attempt Lifecycle: CHAMPION status + META.json promotion fields (/canon/odd/appendices/attempt-lifecycle.md)
• Quantum Development: grounding line that experiments end with promotion (/canon/odd/appendices/quantum-development.md)

Notes

• This release closes the loop on Quantum Development: observations without promotion are incomplete experiments.
• ⚠️ Note: As of 0.3.0, prod is the production branch. main is the experiment ledger.

---

Added

• Cloudflare branch deploys infra note (/docs/infra/cloudflare-branch-deploys.md)
• Attempts doc: "PRD as the Unit of Test" (procedural) (/docs/ATTEMPTS.md)
• Attempt Lifecycle: "PRD as the Unit of Test" + "Independence: goal vs infrastructure" (/canon/odd/appendices/attempt-lifecycle.md)

Changed

• Decision Rules: "Prefer one-shot builds; don't steer a miss" and "Don't hard-code domain tables; hard-code protocol contracts" (/canon/decision-rules.md)
• Quantum Development: cross-link to PRD-as-unit-of-test framing (/canon/odd/appendices/quantum-development.md)
• Active PRD: requires infra artifact when deploy behavior is in scope; adds attempt independence enforcement (/docs/PRD.md)

Notes

• This release encodes transcript-derived learnings as rules and procedures, while avoiding operationally irrelevant or sensitive details.

---

Added

• Quantum Development appendix (/canon/odd/appendices/quantum-development.md)
• Attempt Kickoff prompt (/docs/ATTEMPT_KICKOFF.md)
• Agent Entry Point (/docs/AGENT_ENTRYPOINT.md)
• Single active PRD (/docs/PRD.md)

Changed

• Canon Index: explicit “single active PRD” policy (/canon/index.md)
• Attempt Lifecycle: cross-link to the single kickoff prompt (/canon/odd/appendices/attempt-lifecycle.md)
• Attempts documentation updated to reflect single active PRD + kickoff prompt (/docs/ATTEMPTS.md)
• PRD template updated to reflect single active PRD policy (/docs/PRD/PRD_TEMPLATE.md)

Removed

• Versioned PRDs from the main docs surface (/docs/PRD/PRD_v*.md) in favor of /docs/PRD.md

Notes

• This release reduces PRD and prompt sprawl by making the active PRD and kickoff prompt uniquely authoritative.

---

Added

• Attempt Lifecycle appendix (/canon/odd/appendices/attempt-lifecycle.md)
• Repository Topology appendix (/canon/odd/appendices/repo-topology.md)
• PRD Template (/docs/PRD/PRD_TEMPLATE.md)

Established

• PRD → Attempt → Evidence model
• Decoupled infrastructure from truth (SHA is canonical, deploys are views)
• Three planes: App (disposable), Content (accumulates), Infrastructure (persists)
• Four core principles including "Deployments are views, not truth"

Notes

• This release stabilizes the process model itself, not just content.
• Future PRDs and attempts will stress-test this structure.
• Operational procedures live in /docs/ATTEMPTS.md, not Canon.

---

Added

• Canon Index (/canon/index.md) as the orientation entrypoint.
• Core canon documents:
  • Constraints
  • Decision Rules
  • Definition of Done & Evidence Policy
  • Self-Audit Checklist
  • Visual Proof Standards
  • Completion Report Template
• ODD canon set:
  • ODD Manifesto — Extended
  • Project Maturity & Progressive Governance
• ODD appendices:
  • Misuse Patterns
  • Prompt Architecture
  • Orientation Map
• About pages:
  • Bio
  • Credibility
  • FAQ
• Content manifest (/public/content/manifest.json) generated from per-file frontmatter (stable URIs).

Notes

• The manifest is inventory-only: it declares what exists and how it may be addressed.
• Any future workflow semantics belong in clients or tools, not in this pack.