canon: model operating contract + mode discipline; public template

[klappy]

What this adds

Three new docs + one link patch.

New canon

canon/bootstrap/model-operating-contract.md (tier:1)

The evolving operating contract that any LLM running in an oddkit-powered project fetches on first substantive turn. Consolidates posture (creed + axioms), tool rhythm, mode discipline, bottleneck respect, search-before-asking, canon-unreachable protocol, failure signals, and a statement that the contract itself evolves in canon rather than in prompts. Model-agnostic throughout — applies to Claude, GPT, Gemini, Llama, or any future LLM with tool-use capabilities.

canon/constraints/mode-discipline-and-bottleneck-respect.md (tier:1)

Operationalizes canon/definitions/epistemic-modes and docs/appendices/mode-separated-conversations for the specific case of LLM behavior during substantive work. Names the non-collapse contract (exploration/planning/execution do not mix), the reversion protocol (one sentence, one reason, one question), and the Theory of Constraints framing (operator attention is the bottleneck; asking unnecessary questions during execution is a throughput violation disguised as caution).

New public example

docs/examples/project-instructions-template.md

The actual template Klappy uses as the project-instructions layer, credentials stripped. Shows how the prompt-over-code pattern from canon/constraints/oddkit-prompt-pattern works in practice: creed, axioms, time rule, mode discipline, bottleneck respect, search-before-asking, and oddkit tool reference live in the prompt (load-bearing, always in context); the evolving contract is fetched from canon at runtime. Model-agnostic so the same template works for any LLM with MCP support.

Onramp patch

writings/getting-started-with-odd-and-oddkit.md

Added one sentence to the Bootstrap section linking readers who want "the actual template I use" to the new docs/examples/project-instructions-template. Immediately after the existing proactive-bootstrap link, so the ecosystem is navigable in either direction.

Why this PR exists

This body of work came out of a two-day session where an LLM instance (me) repeatedly asked questions during execution mode, violating canon/definitions/epistemic-modes's "Execution must not pretend to explore alternatives retroactively" rule. The operator (Klappy) spent hours answering questions that should have been extracted during planning — a direct Theory of Constraints violation, attacking the system bottleneck while feeling like caution.

The root cause was diagnosable but not preventable: the canon said one thing, the system prompt did not reinforce it, and the LLM treated canon as decoration rather than contract. The fix is architectural, not behavioral:

• Mode discipline is now canon as a tier-1 constraint, operationalizing what epistemic-modes already defined
• The bootstrap contract carries the full operating posture as canon, so any model in any session can fetch the current contract
• The public example shows the prompt-over-code pattern applied: prompts carry load-bearing posture, canon carries evolving contract

The prompt-over-code pattern (canon/constraints/oddkit-prompt-pattern) now applies to its own prompts.

What's intentionally NOT in this PR

• Changes to the tool implementations (those are the governance anti-pattern sweep, which is a separate sequence of PRs already in motion on klappy/oddkit)
• Changes to canon/definitions/epistemic-modes itself (this PR operationalizes it, does not redefine it)
• A migration of existing system prompts in Klappy's other projects (those get updated separately)

Verification

• Writing Canon 5-tier check passed on both canon docs (title, blockquote, frontmatter, Summary section, descriptive headers)
• Frontmatter conforms to canon/meta/frontmatter-schema (booleans/integers/dates/simple identifiers unquoted, strings with special chars quoted)
• Both canon docs derive_from and complements fields resolve to existing canon
• Model-agnostic grep: no remaining "Claude" references in either canon doc or the public example (all rewritten to "the model" / "any LLM")
• Getting-started link patch is surgical (one added paragraph, no other changes to the onramp)

Related

• klappy/oddkit#105 — the governance anti-pattern audit this work operationalizes a fix for at the architecture level
• klappy/oddkit#106 — canary refactor (telemetry_policy headers from canon) — in progress
• klappy/klappy.dev#101 — core-governance-baseline contract (draft) — companion architectural work

---

Note

Low Risk
Low risk documentation-only change that adds new canon guidance and a public template; no runtime code paths or tooling behavior are modified.

Overview
Introduces a new Tier-1 canon Model Operating Contract (canon/bootstrap/model-operating-contract.md) that centralizes the session bootstrap posture (time via oddkit_time, tool rhythm, search-before-asking, canon-unreachable behavior) and explicitly codifies mode discipline (exploration/planning/execution non-collapse with named reversion).

Adds a new Tier-1 constraint (canon/constraints/mode-discipline-and-bottleneck-respect.md) that formalizes no questions during execution and frames operator attention as the bottleneck, plus a public docs/examples/project-instructions-template.md showing how prompts carry only load-bearing rules while pointing to the evolving contract.

Updates the onboarding article (writings/getting-started-with-odd-and-oddkit.md) to link readers to the new project-instructions template.

^{Reviewed by Cursor Bugbot for commit 18b509d. Bugbot is set up for automated code reviews on this repo. Configure here.}