ODD
The Stylebook
The method the house writes and builds by.
105 pages in 13 folders
Contents
The folders
Every folder of the method, in the order the bands run.
The method
NewestCognitive Partitioning
-
Cognitive Partitioning
Why reasoning systems must divide under pressure, just like execution systems do.
-
ODD + Canon + Evidence
A one-page mental model for the ODD system.
-
Odd Compared
ODD is about preserving intent without freezing execution. The measure of success is not how elegant the artifact is, but whether the outcome holds up in the real world.
-
ODD Manifesto
A governance framework for human-AI collaboration that optimizes learning, not execution. ODD operationalizes epistemic discipline: defining outcomes, enforcing constraints, and…
-
ODD Misuse Patterns
Predictable failure modes when ODD is applied incorrectly.
-
ODD System Contract
The single source of truth for ODD workflow compatibility. ODD is structure-agnostic portable epistemic infrastructure — it works in any repo where canon is addressable. Version…
-
ODD Terminology & Glossary
This document defines the constrained vocabulary of Outcomes-Driven Development. It governs how language is used before elevation to Canon — ensuring precision at the point of…
-
Outcomes-Driven Development (ODD)
The philosophical and operational foundation for this repository. ODD treats outcomes as primary, artifacts as ephemeral, and verification as mandatory.
-
Project Maturity & Progressive Governance
When to apply rigor, not just what rigor exists.
-
Prompt Architecture
How intent scales without collapsing into a monolithic prompt.
Contract
NewestEpistemic Contract
-
Epistemic Contract
This contract defines how epistemic judgment is made, independent of surface or tool.
Constraints
NewestConstraint: Anti-Cache Lying
-
Constraint: Anti-Cache Lying
Caching derived or mutable content violates the Foundational Axioms. A cache with a TTL serves a past observation as current truth — a polite lie that masks reality, blocks…
-
Constraint: Anti-Metric Laundering
Problem
-
Use Only What Hurts
This document is not an introduction.
Decisions
NewestThe Canon Storage Model: Files Write, the Index Reads, the URI Keys
-
The Canon Storage Model: Files Write, the Index Reads, the URI Keys
The system is a database that was always here. Git is the write path, the
-
Three-Tier Conceptual Hierarchy
ODD separates universal principles from program constraints from implementation details.
Encoding types
NewestEncoding Type: Tension (T, derived)
-
Encoding Type: Tension (T, derived)
A contradiction or unresolved conflict visible only across two or more captured artifacts — never in any single one. Unlike every other DOLCHEOT type, a Tension is synthesized by…
-
Encoding Type: Constraint (C)
What now governs future work. Rules, boundaries, and non-negotiables that emerged from the session. Constraints bind future behavior — they are the artifacts most likely to…
-
Encoding Type: Decision (D)
What was chosen. Explicit commitments with rationale. Decisions close options and create direction. They are the highest-stakes artifacts because they constrain all subsequent…
-
Encoding Type: Handoff (H)
What comes next and what context the next session needs. Explicit transfer of state across conversation boundaries. Handoffs are the artifacts most likely to be lost because they…
-
Encoding Type: Learning (L)
What was understood from the observations. Interpretation with evidence. Learnings connect observations to meaning — the bridge between "what did we see?" and "what does it mean?"…
-
Encoding Type: Observation (O)
What was seen or noticed. Raw facts without interpretation. Observations are the evidence layer — they describe reality as encountered, not reality as theorized. An observation…
-
Encoding Type: Open (O, forward-pointing)
An unresolved thread the current owner is still holding. Shares letter O with Observation; section placement and the -open subtype tag disambiguate. Open items carry priority…
-
Encoding Type: Encode (E)
The meta-level action of crystallizing a D, O, L, C, H, or Open into a structured, quality-scored artifact. Encode is a receipt that capture happened, not another category of…
-
Encoding Serialization Format
Encoding types define what fields exist. This document defines how those fields are serialized — the wire format between model and server, and the storage format for accumulated…
-
How to Write an Encoding Type Governance Article
Every encoding type in oddkit — default or custom — is defined by a governance article, not by server code. The server discovers these articles at encode time, extracts their…
Challenge types
NewestChallenge Type: Assumption
-
Challenge Type: Assumption
An implicit premise treated as established. Assumptions are dangerous precisely because they are not examined — the work built on top of them silently inherits their uncertainty.…
-
Challenge Type: Comparative Positioning
A claim that locates this work against other work — existing approaches, adjacent projects, viral repositories, published papers, competing frameworks. Comparative positioning…
-
Challenge Type: Observation
A report of something seen or noticed, offered without strong claim or directive. Observations are the lightest-pressure claim type. They deserve sample-representativeness and…
-
Challenge Type: Pattern Coinage
A move that names a novel pattern, concept, or architecture and asks the reader to adopt the name. Coinage is high-stakes because a successful coinage becomes vocabulary others…
-
Challenge Type: Principle Extraction
A move that lifts a heuristic out of specific experience and elevates it to a principle — a named rule, an aphorism, an invariant the writer intends others to adopt. The failure…
-
Challenge Type: Proposal
A future-oriented plan or recommendation. Proposals carry their weight in the options they close. Pressure here is about alternatives considered, reversibility, and what would…
-
Challenge Type: Strong Claim
A definitive statement offered without qualification. Strong claims foreclose doubt and deserve the most pressure, because their cost of being wrong is proportional to the…
-
How to Write a Challenge Type Governance Article
Every challenge type in oddkit — default or custom — is defined by a governance article, not by server code. The server discovers these articles at challenge time and extracts…
Challenge
NewestChallenge Normative Vocabulary
-
Challenge Normative Vocabulary
The vocabulary the challenge tool uses both to detect signal in canon and to detect noise in user input. Two surfaces, one article: when canon says MUST, SHOULD, NEVER, or names…
-
Challenge Base Prerequisites
Universal prerequisites applied to every claim, regardless of which challenge types matched. Base prerequisites are checks so fundamental that their absence is a gap in any claim…
-
Challenge Stakes Calibration
Proportional pressure is a canon commitment. A voice-dump deserves different treatment than a published essay. A one-line experiment deserves different treatment than an…
Gate
NewestGate Prerequisites
-
Gate Prerequisites
Every transition in odd/gate/transitions.md references its prerequisites by id. This file is where those ids are defined. Each row names one prerequisite, gives a human-readable…
-
Gate Transitions
oddkit_gate checks prerequisites before the operator crosses a mode boundary. Each transition is identified by a stable key, has a from and to endpoint, names the prerequisite ids…
Getting started
NewestAgents & MCP
-
Agents & MCP
oddkit is the CLI and MCP server for ODD. It lets tools — terminals, IDEs, and Claude — query the ODD canon and get back citations, constraints, and epistemic guidance. It…
Appendices
NewestCognitive Saturation Threshold
-
Cognitive Saturation Threshold
In collaborative work — particularly product meetings — there is a point where verbal exchange stops producing knowledge transfer. Participants use the same words with different…
-
Alignment Reviews
Periodic evaluation of the ODD system itself to detect drift.
-
Failure-Driven Modularity
Modular boundaries emerge from repeated failure, not upfront design.
-
Media as a Learning Layer
Media reduces cognitive load over stable written content.
-
Progressive Elevation & Decay
How artifacts move from ephemeral attempts to durable Canon through strict elevation criteria.
-
Quantum Development
Why multiple attempts against the same PRD are sometimes necessary.
-
Visual Evolution
Visual systems evolve independently through versioned interfaces.
Backlog
NewestBacklog
-
Backlog
Maintainer rulings recorded 2026-06-09: ODD repo is public for now; license deliberately undecided; no federation built today — clients make multiple calls per repo via…
-
Backlog
Queued essay celebrating that the Copy. Paste. essay aged poorly on the timeline it wished for. Captured here so it does not get lost. Not yet drafted.
Handoffs
NewestHandoff
-
Handoff
Open a single PR on branch scope-audit against klappy/klappy.dev that writes a target_repo frontmatter tag onto the ~232 markdown files that will leave klappy.dev, records…
-
Handoff
A single 30-line middleware shared across klappy.dev MCP servers (klappy/oddkit, klappy/aquifer, future klappy/truthkit) validates the Authorization: Bearer <token> header on…
-
Handoff
Close the 27% byte/token instrumentation gap so paid-tier pricing can be derived from data that doesn't lie. Move payload measurement from the HTTP wire edge (where a…
-
Handoff
Plant the E0009 flag with full governance discipline, retag the agentic-substrate canon that earned it, and give klappy.dev a public-facing essay surface for the…
-
Handoff
Lane is narrow. Wire the existing survey method to oddkit governance machinery using the runtime-contract pattern from PR #187. Do not add new product surfaces. Do not draft Oddie…
-
Handoff
The Cloudflare Workers MCP server (workers/src/orchestrate.ts:runEncodeAction) is governance-driven and current. The Node CLI MCP server (src/tasks/encode.js, wired via…
-
Handoff
STATUS — SUPERSEDED BY AUDIT 2026-04-30. This document was published in PR #157 (E0008.4 Phase 1, merged 2026-04-30T05:08:53Z) but described code state that PR #96 in…
-
Handoff (Revised)
The Worker encode handler has been governance-driven since PR #96 merged on 2026-04-16. The predecessor handoff scoped a refactor of work that was already done. This revised…
-
Handoff
RV-gate validator was dispatched on PR #146 per canon (overriding the prior handoff's defer). Validator found one MEDIUM bug (F-1: misleading oddkit_audit tool description).…
-
Handoff
P1.3.1 shipped clean to prod (PR #116 feat, #117 promotion, prod at 0.19.0). Challenge's envelope now declares governancesource and a four-peer governanceuris array; smoke 126/126…
-
Handoff
Superseded 2026-04-19 by klappy://odd/handoffs/2026-04-20-post-closeout. The P2.1 (0.17.0 release) and O-open P1 (frontmatter schema gap) items from this handoff have shipped. The…
-
Handoff
P1.1 shipped clean. DOLCHEO canon umbrella plus per-type governance docs merged to klappy.dev main via PR #112, and the three prior-session PRs (#109 ledger, #110 self-report…
-
Handoff
P1.2 shipped. oddkit 0.18.0 is in prod (oddkit.klappy.dev, health confirms). Encode's envelope now declares governancesource + governanceuri, DOLCHEO paragraph-prefix batch input…
-
Handoff
Phase 1 of P1.3.2 landed on klappy.dev. Two canon files merged at commit 86a7194 — odd/gate/transitions.md (four transition keys, detection terms, prereq id references) and…
-
Handoff
P1.3.2 shipped clean to prod. oddkit 0.20.0 is live at oddkit.klappy.dev. Challenge (0.19.0) and gate (0.20.0) both declare governancesource + governanceuris in their envelopes…
-
Handoff
P1.3.3 shipped oddkit 0.21.1 to prod. Challenge joined gate in the stemmed-matcher + no-microsecond-cache camp. Encode is the last holdout: its trigger vocabulary is already…
-
Handoff
Superseded 2026-04-19 by klappy://odd/handoffs/2026-04-20-p1-3-challenge-canary. P1.2 landed (oddkit 0.18.0 in prod — encode envelope now declares governance_source, DOLCHEO batch…
-
Handoff
A reader of this document should be able to resume productive work without reading the full prior session transcript. The companion ledger…
Ledger
NewestLedger
-
Ledger
The black box records; the debrief legislates; the crew flies again. This is raw capture, not verdict. Low-resolution on purpose — it sharpens into policy later through friction…
-
Debrief
The black box records; the debrief legislates; the crew flies again. No blame — the failure goes in the debrief and becomes canon.
-
Flight Record
<!-- flight-artifact -->
-
Session Ledger
Diagnosed catalog token bloat from telemetry (76.65M of 78.74M tokens from one consumer × 7 days, ~112K tokens per call), traced cause to non-progressive catalog response shape…
-
Session Ledger
Continuation of the 2026-05-14 telemetry-coverage-completeness handoff. Three things happened: (1) the handoff's "24-hour soak + per-tool 95% statistical threshold" verdict model…
-
Session Journal
Planning session that produced the Phase 1 handoff for closing the 27% telemetry coverage gap. Started from a token-usage query, converged through one challenge cycle and one…
-
Session Ledger
One planning session, Opus 4.7 instance, 67 minutes elapsed. Operator named the Epoch 9 trio (declaration + essay import + writing governance pass); model surveyed merged PRs and…
-
Session Ledger
Execution session closing journal. Trio (#202 bootstrap, #203 Epoch 9 declaration, #204 We Were the Wire essay) all merged to klappy.dev main. Run started at 2026-05-12T12:02:22Z…
-
Session Ledger
Post-merge operator feedback on the published essay flagged that the forty-minute hackathon framing, repeated across hook + blockquote + close + epilogue, made the essay sound…
-
Journal
Exploration session on the klappy/agent-runtime architecture. Started with cost-shape concerns around the AMS audit gate's Managed-Agents bill; pulled the thread into CF Agents…
-
Session Ledger
Per operator instruction: oddkit gauntlet at every step, encode frequently to prevent loss, draft periodically, present artifacts as they accumulate. This ledger is the durable…
-
Ledger
Session journal capturing the production of a four-artifact canon package and accompanying essay around Klappy's 2018 Medium article "Software Virtues — How to Prioritize".…
-
PR #177 Validation Review
Independent fresh-session review of PR #177, which adds klappy://canon/constraints/audit-gates-are-managed-agents as a Tier-1 binding constraint. The PR is a single-file canon…
-
Biblical Roots Appendix Slug Alignment
Canon-quality audit job #36 reported eight findings in writings/. Five were already resolved in current main and reflected the audit's lag, not present state. Of the three…
-
Audit 2026-04-30 Cleanup Closeout
Audit found that three artifacts shipped in PR #157 (Phase 1) described code state that PR #96 in klappy/oddkit had retired two weeks earlier. Cleanup PR supersedes the three…
-
E0008.4 Phase 1 Closeout
STATUS — SUPERSEDED BY AUDIT 2026-04-30. This document was published in PR #157 (E0008.4 Phase 1, merged 2026-04-30T05:08:53Z) but described code state that PR #96 in…
-
E0008.4 Phase 2 Closeout
Phase 2 was scoped against real code state by the audit-2026-04-30 sweep: five small worker items, not the original brief's six gaps (most of which PR #96 had already retired in…
-
Session Ledger
oddkit v0.26.0 promoted to prod at 2026-04-27T02:51:55 UTC. CF auto-deploy completed by 02:55:26 UTC. All four post-deploy verifications passed against the live…
-
Ledger
Four PRs shipped this session: the Penny Wise and Pound Foolish essay with four supporting canon docs (PR #134), the canon-integration-audit constraint codifying three…
-
Ledger Correction
The prior session ledger (odd/ledger/2026-04-26-telemetry-and-canon-integration-session) recorded [O-open]: getFile-tier vs index-tier wiring as an open follow-up. That claim was…
-
Ledger
A handoff arrived from a prior session on klappy/aquifer-mcp documenting four PRs that transformed a production 503 cascade on the entity tool into a principle-aligned…
-
Observation
Six sessions into the proactive loop on Opus 4.7, the workflow is consistent, rule-following, trustworthy, and expensive. Turn-level verbosity is unreadable on mobile; running the…
-
P1.3.3 Closeout
P1.3.3 was scoped as a small canon-parity ship: stemmed prereq matcher, cache removal, principle graduation. It accomplished all three. It also broke prod, twice — once on a…
-
P1.3.4 Closeout
P1.3.4 was scoped as a small canon-parity ship: migrate the last regex matcher in the suite to stemmed matching, remove the last in-process derivation cache, close the sweep. It…
-
Session Ledger
The release-validation-gate canon (tier 1, landed earlier the same day as P1.3.3's closeout) had its first real application in this session — and one of its rules was almost bent.…
-
Session Ledger
P1.3.1 shipped clean to prod. oddkitchallenge now declares governancesource ("knowledgebase" | "minimal") and governanceuris (plural array of four peer canon URIs, alphabetical by…
-
Session Ledger
P1.3.2 shipped clean to prod in a single 1h 58m session. oddkitgate now reads both odd/gate/transitions.md and odd/gate/prerequisites.md from canon at runtime, declares…
-
E0008.3 Session
Multi-day session spanning a canary completeness refactor, a user-facing rename (canonurl → knowledgebase_url), the promotion of validation into a first-class epistemic mode, the…
-
Session Ledger
Pilot of the four-mode rhythm plus team architecture: the orchestrator (this session, Opus 4.7) writes specs and observes; an independent execution agent (fresh Opus 4.7) produces…
-
Session Ledger
P1.2 shipped clean to prod. oddkitencode now declares governancesource + governanceuri in its envelope, accepts DOLCHEO paragraph-prefix batch input ([D] / [O] / [L] / [C] / [H] /…
-
Session Ledger
A prior session hung mid-investigation of a Sonnet 4.6 validator it had dispatched against three already-merged klappy.dev PRs. This fresh session reconstructed validator state…
-
Session Journal
Date: 2026-04-17
-
Project Journal Best Practices
Common failure modes, proven solutions, and the major tradeoff warning: don't separate entries by type — it erases narrative.
-
The Epistemic Ledger
The epistemic ledger is the collection of durable artifacts that survive past ephemeral conversations. It is where observations, learnings, decisions, constraints, handoffs, and…
-
2026 04 03 E0007 The Gauntlet Should Run Itself
Observations
-
2026 04 09 Managed Agents Session
Date: 2026-04-09
-
2026 04 13 Swarm Spike
TruthKit Swarm Architecture Review & Spike Planning
-
E0007 Handoff Bootstrap
What happened