E0007: From Passive to Proactive

[klappy]

Epoch 7 — From Passive to Proactive

Forcing fault: A system that requires its user to remember its features has delegated its cognition to the wrong party.

Invariant: The system acts, the operator reviews.

Phase 0 (complete — prior session)

• docs/oddkit/encode-persistence-gap.md — Cornerstone governance article
• docs/planning/e0007-implementation-plan.md — Full 5-phase plan
• odd/ledger/2026-04-03-e0007-the-gauntlet-should-run-itself.md — Session OLDC+H
• odd/ledger/e0007-handoff-bootstrap.md — Handoff bootstrap

Phase 1 (complete)

• docs/appendices/epoch-7.md — Full epoch declaration
• docs/appendices/epochs.md — Updated with E0007 section

Phase 2 (complete — all 13 articles)

Proactive tool articles (6):

• docs/oddkit/proactive/proactive-orient.md
• docs/oddkit/proactive/proactive-search.md
• docs/oddkit/proactive/proactive-challenge.md
• docs/oddkit/proactive/proactive-gate.md
• docs/oddkit/proactive/proactive-validate.md
• docs/oddkit/proactive/proactive-preflight.md

Core concept articles (6):

• docs/oddkit/proactive/continuous-encoding.md
• docs/oddkit/proactive/proactive-identity-of-integrity.md
• docs/oddkit/proactive/encode-does-not-persist.md
• docs/oddkit/proactive/oldc-h-vocabulary.md
• odd/ledger/project-journal-best-practices.md
• docs/oddkit/proactive/handoff-to-new-conversation.md

Terminology (1):

• docs/oddkit/proactive/terminology-project-journal.md

Remaining phases

• Phase 3: oddkit code changes (tool descriptions + response formats)
• Phase 4: A/B testing via canon_url branch override
• Phase 5: Merge to main + public essay

---

Note

Low Risk
Low risk because changes are documentation/content-only (new governance articles, essays, README refresh) plus a package version bump, with no runtime code changes.

Overview
Defines Epoch 7 (E0007) “From Passive to Proactive” in canon, shifting the guidance for oddkit-powered agents from wait for invocation to system-initiated behavior ("the system acts, the operator reviews"), including explicit treatment of the encode persistence gap and making OLDC+H a first-class, discoverable vocabulary.

Adds a set of focused E0007 governance docs for proactive usage patterns (orient, search, challenge, gate, validate, preflight), continuous session capture/hand-off/provenance, plus an implementation note proposing catalog recency/metadata exposure.

Overhauls the repo README.md and adds two public onboarding/narrative essays (writings/getting-started-with-odd-and-oddkit.md, writings/from-passive-to-proactive.md), and bumps package.json version to 0.7.0.

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

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

Bugbot Autofix prepared a fix for the issue found in the latest run.

• ✅ Fixed: Validation document average control score is miscalculated
  • Corrected the average control #1 score from 12.95 to 13.00, which is the actual mean of the ten control BM25 scores (130.04 / 10 = 13.004, rounded to 13.00).

Preview (c9a61f490a)

diff --git a/docs/appendices/epoch-7.md b/docs/appendices/epoch-7.md
new file mode 100644
--- /dev/null
+++ b/docs/appendices/epoch-7.md
@@ -1,0 +1,170 @@
+---
+uri: klappy://docs/appendices/epoch-7
+title: "Epoch 7 — From Passive to Proactive"
+audience: docs
+exposure: nav
+tier: 2
+voice: neutral
+stability: stable
+tags: ["odd", "epochs", "proactive-posture", "cognitive-rhythm", "oldc-h", "epoch-7"]
+epoch: E0007
+date: 2026-04-03
+supersedes: "Epoch 6 (scoped truth and operator governance)"
+forcing_fault: "A system that requires its user to remember its features has delegated its cognition to the wrong party"
+new_invariant: "The system acts, the operator reviews"
+core_shift: "Passive tool invocation → proactive cognitive rhythm. User-remembered features → system-initiated behavior."
+documents_introduced: ["docs/oddkit/encode-persistence-gap.md", "docs/oddkit/proactive/proactive-orient.md", "docs/oddkit/proactive/proactive-search.md", "docs/oddkit/proactive/proactive-challenge.md", "docs/oddkit/proactive/proactive-gate.md", "docs/oddkit/proactive/proactive-validate.md", "docs/oddkit/proactive/proactive-preflight.md", "docs/oddkit/proactive/continuous-encoding.md", "docs/oddkit/proactive/proactive-identity-of-integrity.md", "docs/oddkit/proactive/encode-does-not-persist.md", "docs/oddkit/proactive/oldc-h-vocabulary.md", "docs/oddkit/proactive/handoff-to-new-conversation.md", "docs/oddkit/proactive/terminology-project-journal.md", "odd/ledger/project-journal-best-practices.md"]
+---
+
+# Epoch 7 — From Passive to Proactive
+
+> E0006 governed the operator's relationship to the system. E0007 governs the system's relationship to the operator — and reverses who initiates. The axioms don't change. The tools don't change. What changes is who acts first: the system proposes, the operator reviews. A tool that waits to be remembered is a tool that waits to be forgotten.
+
+---
+
+## Summary — The System Acts, the Operator Reviews
+
+E0006 introduced operator governance and scoped truth. Together they ensured the operator could be sustainable while the system's truth remained portable. The guiding question was "Am I being faithful, and is this sustainable?" That question was correct and remains correct. But it was incomplete.
+
+What emerged through observation — not theory — is that a system can satisfy every epistemic requirement while remaining invisible to its own operator. Every oddkit tool worked. Every governance article existed. Every constraint was encoded. And the operator still had to remember to use them. The tools were correct and available and unused — not because they failed, but because they waited.
+
+E0006 had no axis for "who initiates." E0007 adds it.
+
+The passive posture was not a mistake. It was intentional constraint during a period when the system needed to prove itself without imposing. The tools needed to be tested by an operator who chose them, not prompted by a system that insisted. That testing phase is complete. Months of daily driving oddkit across code, household planning, financial decisions, and home buying produced validated learning: the tools work, the operator trusts them, and the remaining friction is that the operator must remember they exist.
+
+That friction is now the signal.
+
+---
+
+## A Change in What the System Assumes About Initiative
+
+E0007 changes the answer to a foundational question:
+
+**Who acts first — the operator or the system?**
+
+E0006 answered: the operator acts. The system responds faithfully when invoked, sustainably within the operator's chosen boundaries.
+
+E0007 answers: the system acts first. The operator reviews, approves, corrects, or overrides. The system proposes orientation when context shifts. The system tracks observations and learnings continuously. The system challenges consequential claims before encoding them. The system detects saturation and proposes handoff before quality degrades. The operator governs — but the system initiates.
+
+This is a foundational shift because it changes what "available" means. Under E0006, an available tool was sufficient. Under E0007, an available tool that waits to be invoked has delegated its cognition to the operator's memory — the least reliable component in the system. Available is necessary but no longer sufficient. The tool must also act.
+
+---
+
+## The Forcing Fault — Delegated Cognition
+
+The forcing fault is not a tooling failure. It is a design posture that succeeded itself into irrelevance.
+
+The passive posture — tools that wait for explicit invocation — was the correct design for the testing phase. An operator learning to trust a new epistemic system needs to choose when and how to engage each tool. Prompting would have been intrusive. Waiting was respectful. The problem is that waiting, once correct, became permanent. The system never graduated from "prove yourself" to "participate."
+
+The result: a system with 400+ governance documents, six completed epochs, validated daily use across multiple domains — and an operator who still had to type "encode OLDC+H" from memory. The system knew what OLDC+H meant. The system knew when encoding was appropriate. The system knew the operator wanted continuous tracking. And the system waited.
+
+This is the RITUAL_DETECTED pattern: when a human repeatedly performs the same invocation sequence across sessions, the system has enough evidence to propose that sequence proactively. The ritual is the signal that the behavior should have been internalized.
+
+Under E0006, this pattern was invisible to the evaluation framework. A system that waited faithfully for invocation was not violating any criterion. E0007 calls it a system failure — specifically, a failure of initiative.
+
+---
+
+## The New Invariant
+
+**The system acts, the operator reviews.**
+
+This invariant was previously false in the system's posture. A system that waited for invocation while the operator forgot its features was not a recognized failure mode. Now it is.
+
+---
+
+## One Shift — Proactive Cognitive Rhythm
+
+### Every Tool Becomes Proactive
+
+The shift applies to every oddkit tool, not just encode:
+
+**Orient** is not a session-start ritual. The system reorients whenever context shifts, a new subtask emerges, or the mode may have changed. The operator does not need to remember to ask "where are we?"
+
+**Search** happens before claiming, not after failing. When the system is about to make a claim that canon might have guidance on, it searches first. The operator does not need to remember what the canon covers.
+
+**Challenge** fires before encoding consequential decisions. When a claim would close options, create constraints, or be expensive to reverse, the system challenges it proactively. The operator does not need to remember to ask "what could go wrong?"
+
+**Gate** activates at every implicit mode transition. When the system detects a verb change — from exploring to building, from planning to executing — it gates. Most transitions are implicit. The operator does not need to recognize the shift.
+
+**Validate** runs before claiming done. When the system believes a task is complete, it validates against requirements before presenting the deliverable. The operator does not need to remember to check.
+
+**Preflight** precedes every execution task. Before producing an artifact, the system checks constraints and definition of done. The operator does not need to remember what was required.
+
+**Encode** tracks continuously. Observations, learnings, decisions, constraints, and handoffs are captured at every exchange — not batched at session end. The operator does not need to remember to journal.
+
+### The Identity of Integrity as Self-Correction
+
+The creed and axioms are not a one-time orientation. They are a continuous self-correction mechanism. When the system detects its confidence outrunning its evidence — when it is about to claim what it has not verified — it resurfaces its own creed. This is observably effective: proactive creed resurfacing corrects hallucination patterns that passive orientation does not catch.
+
+### Encode Does Not Persist — And That's the Caller's Problem
+
+A critical discovery: the encode tool returns structured artifacts in the response stream. It does not persist them. Every encode output that isn't saved by the caller is lost. This is by design — ODD is a protocol layer, not a storage layer. But the design created a gap: the operator assumed encoding meant saving. It did not.
+
+E0007 makes this explicit. Every encode response declares `persist_required: true` and instructs the caller to save the output. The system does not silently lose the operator's work.
+
+### OLDC+H as Standard Vocabulary
+
+Observations, Learnings, Decisions, Constraints, Handoffs — OLDC+H — is the standard vocabulary for session capture. Under E0006, this vocabulary existed but was not discoverable. An operator who didn't already know the acronym couldn't find it. E0007 ensures OLDC+H surfaces in any search about session capture, journaling, or encoding.
+
+---
+
+## From "Am I Being Faithful and Sustainable?" to "Am I Acting, Not Just Available?"
+
+The guiding question expands. E0006's question remains embedded — faithfulness and sustainability are still required. E0007 adds initiative as a co-equal criterion.
+
+This is not a relaxation. It is a constraint. Under E0006, a system that waited faithfully and sustainably for invocation was not violating any evaluation criterion. Under E0007, it is. The system now requires evidence that it initiates appropriate actions, that it does not delegate cognition to the operator's memory, and that "available" is a starting point rather than a destination.
+
+---
+
+## What E0007 Does Not Change
+
+- **The four axioms carry forward unchanged.** Reality Is Sovereign. A Claim Is a Debt. Integrity Is Non-Negotiable Efficiency. You Cannot Verify What You Did Not Observe.
+- **The creed carries forward unchanged.** Before I speak, I observe. Before I claim, I verify. Before I confirm, I prove. What I have not seen, I do not know. What I have not verified, I will not imply.
+- **Operator governance carries forward.** Capability is still not permission. Sustainability is still required.
+- **Scoped truth carries forward.** Axioms travel. Domain doesn't.
+- **All E0006 principles remain valid within E0006.** No prior work is invalidated.
+- **Progressive disclosure and writing canon remain in force.**
+- **The Definition of Done still applies.** E0007 extends what "available" means — it does not replace the existing requirements.
+
+---
+
+## Evidence — Not Theory
+
+This epoch is grounded in observation, not speculation. The evidence includes:
+
+- **Daily driving across domains.** Months of using oddkit for software development, household planning, financial decisions, and home buying. The tools work. The trust is established. The remaining friction is recall.
+- **The "encode OLDC+H" ritual.** The operator typed this invocation sequence from memory in every session. The system had enough context to propose it proactively. It waited instead.
+- **The persistence gap discovery.** The operator assumed encode persisted. It did not. Multiple sessions of work were silently lost because the system did not declare its own limitation.
+- **BM25 surfacing failure.** The cornerstone article — a comprehensive treatment of the proactive posture — did not surface in oddkit's top-5 search results. Many small, pointed files are required for discoverability. The system's own search mechanism confirmed the need for spin-off articles.
+- **Proactive creed resurfacing.** In sessions where the creed and axioms were resurfaced mid-conversation, hallucination patterns were observably corrected. In sessions where they were only stated at orientation, drift accumulated.
+- **The OLDC+H discoverability problem.** An operator who didn't know the acronym couldn't find the vocabulary. The system required prior knowledge of its own conventions to use them.
+
+---
+
+## Epoch 7 Documents
+
+| Document | Purpose |
+|----------|---------|
+| `docs/oddkit/encode-persistence-gap.md` | Cornerstone article — diagnoses the encode persistence gap, prescribes continuous proactive usage |
+| `docs/oddkit/proactive/proactive-orient.md` | Proactive orient — reorient at every context shift |
+| `docs/oddkit/proactive/proactive-search.md` | Proactive search — search before claiming |
+| `docs/oddkit/proactive/proactive-challenge.md` | Proactive challenge — challenge before encoding |
+| `docs/oddkit/proactive/proactive-gate.md` | Proactive gate — gate at every mode transition |
+| `docs/oddkit/proactive/proactive-validate.md` | Proactive validate — validate before claiming done |
+| `docs/oddkit/proactive/proactive-preflight.md` | Proactive preflight — preflight before every execution task |
+| `docs/oddkit/proactive/continuous-encoding.md` | Continuous OLDC+H encoding — track at every turn |
+| `docs/oddkit/proactive/proactive-identity-of-integrity.md` | Proactive Identity of Integrity — resurface the creed to prevent drift |
+| `docs/oddkit/proactive/encode-does-not-persist.md` | Encode does not persist — the caller must save |
+| `docs/oddkit/proactive/oldc-h-vocabulary.md` | OLDC+H — the five standard artifact types |
+| `odd/ledger/project-journal-best-practices.md` | Project journal best practices — sizing, timestamps, tradeoffs |
+| `docs/oddkit/proactive/handoff-to-new-conversation.md` | Proactive handoff — detect saturation, bootstrap next conversation |
+| `docs/oddkit/proactive/terminology-project-journal.md` | Terminology — project journal over epistemic ledger |
+| This document | Epoch declaration and historiographic record |
+
+---
+
+## Compatibility
+
+- E0006 artifacts remain valid within E0006.
+- E0006 artifacts are not comparable to E0007 artifacts by default — E0007 requires evidence of proactive system initiative that E0006 does not.
+- E0007 is the current epoch.

diff --git a/docs/appendices/epochs.md b/docs/appendices/epochs.md
--- a/docs/appendices/epochs.md
+++ b/docs/appendices/epochs.md
@@ -15,7 +15,7 @@
 
 ## Description
 
-An epoch is a named period where "success" meaning is stable enough to compare outcomes. Attempts are individuals, PRDs are fitness functions, Promotion is selection, Canon is inherited traits, and Epochs are shifts in the fitness landscape. An epoch defines evaluation reality: what "done" means, mandatory evidence, binding contracts, acceptable risks, and infrastructure stability. Epochs are not PRDs—they are the context in which PRDs are interpreted. klappy.dev defines E0001 (single-PRD era), E0002 (multi-lane era), E0003 (evidence-first era with Cloudflare deployment proof required), E0004 (epistemic separation era with judgment/embodiment distinction), and E0005 (values-first epistemics with foundational axioms and orientation creed).
+An epoch is a named period where "success" meaning is stable enough to compare outcomes. Attempts are individuals, PRDs are fitness functions, Promotion is selection, Canon is inherited traits, and Epochs are shifts in the fitness landscape. An epoch defines evaluation reality: what "done" means, mandatory evidence, binding contracts, acceptable risks, and infrastructure stability. Epochs are not PRDs—they are the context in which PRDs are interpreted. klappy.dev defines E0001 (single-PRD era), E0002 (multi-lane era), E0003 (evidence-first era with Cloudflare deployment proof required), E0004 (epistemic separation era with judgment/embodiment distinction), E0005 (values-first epistemics with foundational axioms and orientation creed), E0006 (scoped truth and operator governance), and E0007 (proactive cognitive rhythm — the system acts, the operator reviews).
 
 ## Outline
 
@@ -24,7 +24,7 @@
 - Relationship to Product Lanes
 - Relationship to PRDs and Attempts
 - When to Start a New Epoch
-- Naming Convention (E0001, E0002, E0003, E0004, E0005)
+- Naming Convention (E0001, E0002, E0003, E0004, E0005, E0006, E0007)
 - Minimal Epoch Metadata (META.json)
 - Anti-Patterns
 - E0003 — Evidence-First Era (klappy.dev specific)
@@ -135,6 +135,8 @@
 - `E0003-evidence-first-era`
 - `E0004-epistemic-separation-era`
 - `E0005-values-first-epistemics`
+- `E0006-scoped-truth-operator-governance`
+- `E0007-proactive-posture`
 
 The ID is the canonical reference. The name is a hint.
 
@@ -364,4 +366,33 @@
 
 - E0005 artifacts remain valid within E0005.
 - E0005 artifacts are not comparable to E0006 artifacts by default.
-- E0006 is the current epoch.
+- E0006 artifacts remain valid within E0006.
+
+---
+
+## E0007 — From Passive to Proactive
+
+**Date:** 2026-04-03
+
+E0006 governed the operator's relationship to the system. E0007 governs the system's relationship to the operator — and reverses who initiates.
+
+See [`docs/appendices/epoch-7.md`](/docs/appendices/epoch-7.md) for the full epoch declaration.
+
+### What changed
+
+E0007 shifts oddkit's tool posture from passive (wait for invocation) to proactive (act as cognitive rhythm). Every tool becomes proactive: orient reorients at context shifts, search fires before claiming, challenge fires before encoding consequential decisions, gate activates at implicit mode transitions, validate runs before claiming done, preflight precedes execution, and encode tracks OLDC+H continuously. The Identity of Integrity becomes a continuous self-correction mechanism, not a one-time orientation. The encode persistence gap is explicitly declared: encode returns artifacts in the response stream but does not persist them. OLDC+H becomes a discoverable standard vocabulary for session capture.
+
+### Why this is a new epoch
+
+This change alters the system's initiative posture:
+
+- "Available" is necessary but no longer sufficient — the system must also act
+- Cognition is no longer delegated to the operator's memory
+- The guiding question shifts from "Am I being faithful, and is this sustainable?" to "Am I acting, not just available?"
+- E0006 artifacts produced by a passive system are not comparable to E0007 artifacts produced by a proactive one
+
+### Compatibility
+
+- E0006 artifacts remain valid within E0006.
+- E0006 artifacts are not comparable to E0007 artifacts by default.
+- E0007 is the current epoch.

diff --git a/docs/oddkit/IMPL-catalog-recent.md b/docs/oddkit/IMPL-catalog-recent.md
new file mode 100644
--- /dev/null
+++ b/docs/oddkit/IMPL-catalog-recent.md
@@ -1,0 +1,183 @@
+---
+uri: klappy://docs/oddkit/IMPL-catalog-recent
+title: "Implementation: Catalog Metadata Exposure — Articles List with Full Frontmatter"
+audience: docs
+exposure: nav
+tier: 3
+voice: neutral
+stability: evolving
+tags: ["oddkit", "catalog", "discovery", "metadata", "recent", "temporal", "implementation", "epoch-7"]
+epoch: E0007
+date: 2026-04-03
+---
+
+# Implementation: Catalog Metadata Exposure — Articles List with Full Frontmatter
+
+> The metadata is already indexed. It's just not exposed. Catalog returns counts but no article-level metadata. Search and get hide metadata behind an opt-in flag. The real feature is exposure — sorting, filtering, and grouping are consumer concerns.
+
+---
+
+## Summary — Expose the Data, Let Consumers Decide
+
+oddkit already parses and indexes full frontmatter for every document. The `include_metadata` flag on search and get proves the data is there. But catalog — the discovery tool — returns only aggregate counts and categories. It cannot list individual articles or their metadata. And search/get default `include_metadata` to false, hiding the very data that enables temporal discovery, epoch grouping, and audience filtering.
+
+The core feature is metadata exposure: catalog should return an articles list with full frontmatter metadata. Sorting by date and limiting results are server-side operations — deterministic, cheap, and correct. The server does deterministic work (sort, filter, aggregate) because pushing that to an LLM is slow, expensive, and error-prone. Consumers get pre-sorted, pre-filtered results with full metadata attached — they can do additional grouping for novel queries without repeating the deterministic work.
+
+This principle extends beyond catalog. Every tool that returns document references should expose metadata. The `include_metadata` default should be reconsidered across all tools — but catalog is the immediate priority because it's the discovery entry point.
+
+---
+
+## The Problem — New Articles Are Invisible
+
+When 15 new articles land on a branch (as with E0007), there is no way to discover them through oddkit unless you already know their URIs or search for the right keywords. Catalog returns total counts and categories — it can tell you the corpus grew from 411 to 426 documents, but not which 15 are new. Search finds documents by relevance to a query, not by recency.
+
+The result: the very articles designed to improve discoverability are themselves undiscoverable by the most natural question a user would ask — "what's new?"
+
+---
+
+## Proposed Parameters
+
+### `sort_by` (optional, string)
+
+Sorts the catalog results by the specified frontmatter field.
+
+- `"date"` — Sort by the frontmatter `date` field, newest first.
+- Default behavior (omitted or null): current catalog response — counts, categories, start-here suggestions, no individual document listing.
+
+When `sort_by` is provided, the response includes an `articles` array of individual document metadata (path, title, date, tags) in addition to the existing counts and categories.
+
+### `limit` (optional, number)
+
+Maximum number of documents to return in the `articles` array. Only meaningful when `sort_by` is provided.
+
+- Default: `10`
+- Range: `1–100`
+
+### `filter_epoch` (optional, string)
+
+Filter results to documents with a specific `epoch` value in frontmatter. Filtering is deterministic — the server should do it, not the LLM.
+
+- Example: `"E0007"` returns only documents with `epoch: E0007` in frontmatter.
+- Default: no filter (all documents).
+- Documents without an `epoch` field are excluded when this filter is active.
+- Limit applies after filtering.
+
+---
+
+## The Principle — Deterministic Work Belongs Server-Side
+
+Sort and filter are deterministic operations. They belong on the server, not in the LLM. Making an LLM sort 400 articles by date is burning tokens on arithmetic the server can do in microseconds.
+
+The division of labor: the server does deterministic work (sort, filter, aggregate, project metadata). The LLM does judgment work (interpretation, synthesis, recommendation, connecting patterns across results). Full metadata exposure enables the LLM to do its job without also doing the server's job.
+
+Both are required. Metadata exposure without server-side sort/filter forces deterministic work onto the LLM. Server-side sort/filter without metadata exposure prevents the LLM from doing novel analysis. The correct design is both.
+
+---
+
+## Beyond Catalog — Metadata Exposure Across All Tools
+
+This feature addresses catalog specifically, but the principle extends to all oddkit tools that return document references:
+
+**Search** already supports `include_metadata: true` but defaults to false. With metadata exposed by default, agents get epoch, date, audience, and tier alongside relevance-ranked results — enabling them to interpret results without round-tripping back to get.
+
+**Get** already supports `include_metadata: true`. Same principle — default to exposed.
+
+**Orient, preflight, challenge** all return `canon_refs` — lists of relevant documents. These currently return path and a quote snippet but no metadata. Exposing metadata on these references would let consumers understand what they're looking at without calling get on each one.
+
+The immediate implementation is catalog with `sort_by`, `limit`, and `filter_epoch`. Extend metadata exposure to other tools when the pain signal is clear.
+
+---
+
+## Response Shape (Extended)
+
+When `sort_by` is provided, the existing response is extended with an `articles` array containing full frontmatter metadata:
+
+```json
+{
+  "action": "catalog",
+  "result": {
+    "total": 426,
+    "canon": 180,
+    "baseline": 426,
+    "categories": ["...existing..."],
+    "start_here": ["...existing..."],
+    "articles": [
+      {
+        "path": "docs/oddkit/proactive/continuous-encoding.md",
+        "uri": "klappy://docs/oddkit/proactive/continuous-encoding",
+        "metadata": {
+          "title": "Continuous OLDC+H Encoding — Track at Every Turn, Not Just Session End",
+          "date": "2026-04-03",
+          "epoch": "E0007",
+          "audience": "docs",
+          "exposure": "nav",
+          "tier": 3,
+          "voice": "neutral",
+          "stability": "stable",
+          "tags": ["odd", "oddkit", "encode", "oldc-h", "proactive", "continuous", "journal", "epoch-7"]
+        }
+      }
+    ]
+  }
+}
+```
+
+The `metadata` object is the same shape that `include_metadata: true` returns on search and get — full parsed frontmatter, no cherry-picking. Consumers can group by `epoch`, filter by `audience`, sort by `date`, or use `tags` for faceted navigation. The server sorts; the consumer filters and groups.
+
+When `sort_by` is omitted, the response is unchanged — backward compatible.
+
+---
+
+## Behavioral Rules
+
+1. **Backward compatible.** Catalog with no new parameters returns exactly what it returns today. No existing consumer breaks.
+2. **Full metadata, not cherry-picked fields.** The `metadata` object in each article is the complete parsed frontmatter — the same data `include_metadata: true` returns on search and get. No field filtering. Consumers decide what to use.
+3. **Documents without dates sort last.** Not all documents have a `date` field. Those without it appear at the end of the sorted list, not at the beginning.
+4. **Limit caps response size.** Without a limit, a sorted catalog of 400+ documents would be unwieldy. The default of 10 serves the most common use case.
+5. **Respect canon_url.** The temporal discovery works with branch overrides. `catalog({ sort_by: "date", limit: 10, canon_url: "...branch..." })` returns the 10 newest articles on that branch.
+
+---
+
+## Alternatives Considered
+
+**New tool (`oddkit_recent`):** Rejected. Adding tools dilutes the existing set. Every new MCP tool competes for attention in tool selection. Catalog is already the discovery tool — temporal sorting belongs there.
+
+**Parameter on search:** Rejected. Search is relevance-ranked by design. Adding a date sort to search would create ambiguity: is the result relevant or just recent? Catalog is the right home because it's already about structural discovery, not semantic relevance.
+
+**Separate REST endpoint:** Rejected for now. The klappy.dev site can call oddkit via MCP. If performance requires it, a REST endpoint can be added later — but the governance and behavior should be defined in MCP first.
+
+---
+
+## Implementation Notes
+
+- Full frontmatter is already parsed during indexing — confirmed by `include_metadata: true` on search returning fields like `date`, `epoch`, `audience`, `tier`, `stability`, `tags`, and custom fields like `derives_from` and `complements`.
+- The `articles` array is a projection of the existing index — path, URI, and the complete metadata object. No additional data fetching or parsing required.
+- The `limit` parameter caps response size. Without it, a sorted catalog of 400+ documents would be unwieldy.
+- Canon reference `docs/planning/oddkit-full-frontmatter-and-drift-audit.md` documents that oddkit historically cherry-picked frontmatter fields. The current `include_metadata` behavior suggests full parsing is now in place — verify before implementation.
+
+---
+
+## Consumer Examples
+
+**klappy.dev site — "What's new on this branch?"**
+```
+catalog({ sort_by: "date", limit: 15, canon_url: "https://raw.githubusercontent.com/klappy/klappy.dev/e0007-proactive-posture" })
+```
+
+**Agent — "What was added in E0007?"**
+```
+catalog({ sort_by: "date", filter_epoch: "E0007" })
+```
+
+**Operator — "Show me recent articles"**
+```
+catalog({ sort_by: "date", limit: 10 })
+```
+
+---
+
+## Canon References
+
+- `docs/oddkit/tools/oddkit_catalog.md` — Existing catalog tool specification
+- `docs/oddkit/IMPL-oddkit-diff.md` — Related: diff answers "what changed since X" at git level; catalog recent answers "what's newest" at frontmatter level
+- `docs/oddkit/proactive/proactive-search.md` — Proactive search pattern that this feature complements

diff --git a/docs/oddkit/encode-persistence-gap.md b/docs/oddkit/encode-persistence-gap.md
new file mode 100644
--- /dev/null
+++ b/docs/oddkit/encode-persistence-gap.md
@@ -1,0 +1,303 @@
+---
+uri: klappy://docs/oddkit/encode-persistence-gap
+title: "Encode Does Not Persist, Nobody Knows OLDC+H, and the Fix Is Continuous Encoding"
+audience: operators
+exposure: nav
+tier: 2
+voice: direct
+stability: evolving
+tags: ["oddkit", "encode", "persistence", "OLDC", "epistemic-ledger", "continuous-encoding", "use-only-what-hurts", "ritual-smell", "frustration-signal", "default-behavior"]
+epoch: E0007
+date: 2026-04-03
+derives_from: "odd/constraint/use-only-what-hurts.md, canon/values/axioms.md, canon/principles/ritual-is-a-smell.md"
+complements: "odd/ledger/epistemic-ledger.md, docs/oddkit/tools/oddkit_encode.md, writings/the-project-journal.md, canon/diagnostics/ritual-detected.md, writings/learning-in-the-open.md, canon/values/drift.md"
+governs: "oddkit_encode tool description, oddkit_orient behavior, and all consumers of the encode action"
+---
+
+# Encode Does Not Persist, Nobody Knows OLDC+H, and the Fix Is Continuous Encoding
+
+> Two failures in the oddkit encode tool compound into daily frustration: the tool implies persistence but doesn't persist, and the standard artifact types (OLDC+H — Observations, Learnings, Decisions, Constraints, Handoffs) are undiscoverable from the tool itself. But the real fix is not better documentation, a shorthand command, or even periodic batch capture at session boundaries. The real fix is continuous encoding: every agent tracks OLDC+H at every exchange — after every user message and after every agent action — as a natural part of its thought process. Start your response by encoding what the user just shared. End your response by encoding what you just did. This is not a feature to invoke. It is how an agent thinks. The axioms keep the work honest; continuous encoding keeps the work remembered. Together they solve the two biggest problems in agentic workflows: drift and amnesia. The running ledger accumulates throughout the conversation and persists to project storage at natural breakpoints. The operator reviews and approves — they never invoke, explain, or re-teach.
+
+---
+
+## Summary — The Axioms Plus Continuous Encoding Solve Most Problems in Daily Agentic Use
+
+This is a problem of success, not failure.
+
+The passive oddkit tool posture was intentional. The tools were deliberately designed to wait for invocation — to let operators get used to them in their projects without the tools causing issues. That was the right design choice for the testing phase. The tools work. The governance works. The canon is thorough. The problem that emerged is the best possible outcome: nobody uses the tools proactively because the agent doesn't use them automatically. Adoption friction, not broken tooling.
+
+The pain of that friction is the graduation signal. The same way Use Only What Hurts (`odd/constraint/use-only-what-hurts.md`) identifies when structure should be added, this daily frustration identifies when posture should shift — from passive to active to proactive. The canon already has a name for what happened: `RITUAL_DETECTED` (`canon/diagnostics/ritual-detected.md`). The operator created rituals to compensate for passive tools. "Run the oddkit gauntlet." "Encode OLDC+H." "Remember the governance checklist." Every ritual is a smell indicating missing design.
+
+The axioms (`canon/values/axioms.md`) provide the epistemic foundation — they prevent drift, the slow corruption of reasoning when an agent confidently wanders from reality. Continuous OLDC+H encoding provides the operational memory — it prevents amnesia, the daily reset where every session starts from zero. Together they solve the two biggest problems in agentic workflows. But both depend on the agent using them proactively. A passive tool that waits to be invoked delegates its cognition to the operator. The operator becomes the scheduler, the rememberer, the invoker — the integration layer between the tool and its own documentation.
+
+The pivot from passive to proactive is not a single file change. It requires a full audit: every tool, principle, feature, and functionality of ODD and oddkit needs new proactive governance articles. Small, pointed files that ensure high BM25 search relevance. The previous passive posture should be overwritten but not erased — the history matters, and the progression from passive to proactive is itself a learning worth preserving.
+
+The fix requires reinforcement at every layer: governance articles that define the principle, tooling improvements that automate the behavior, project instruction hints that remind agents, and tool descriptions that teach the workflow. As much reinforcement as needed across all surfaces. If the agent has to be prompted, the system has failed. If the operator has to say "run the oddkit gauntlet" — their shorthand for "please use all your tools, because you won't do it on your own" — the system has made the human the scheduler for the agent's own cognitive process. The tools are not features to invoke. They are how the agent thinks.
+
+---
+
+## The Two Failures — Encode Lies by Implication and Hides Its Own Vocabulary
+
+### "Durable" Implies Persistence That Doesn't Exist
+
+The encode tool's MCP description reads: "Structure a decision, insight, or boundary as a durable record." The word "durable" causes every MCP consumer to assume the encoding was persisted. It was not. The structured artifact is returned in the response stream and vanishes with the conversation. No file is written. No state is saved.
+
+When the agent calls encode and gets back `"status": "ENCODED"`, it concludes the job is done. The status code reinforces the false completion signal. The canon is explicit that persistence is the project's responsibility (`odd/ledger/epistemic-ledger.md`: "Any project using oddkit needs persistent storage for the ledger"). But the encode tool never says this. The gap between what the tool implies and what the tool does is a violation of Axiom 1 — Reality Is Sovereign.
+
+### OLDC+H Is Undiscoverable from the Tool
+
+The epistemic ledger defines five standard artifact types: Observations, Learnings, Decisions, Constraints, and Handoffs — collectively OLDC+H. These are documented thoroughly in `odd/ledger/epistemic-ledger.md` and explained in plain language in `writings/the-project-journal.md`. The operator uses them constantly.
+
+But the encode tool description mentions none of this. It says "a decision, insight, or boundary" — three terms that partially overlap with the OLDC+H categories but don't name them. When an operator says "encode OLDC+H," the agent has never seen that acronym. It guesses. It fabricates. The operator corrects. Every. Single. Time.
+
+---
+
+## The Daily Lived Experience — RITUAL_DETECTED
+
+This is what happens in practice, repeated daily across sessions:
+
+> "Remember the governance, progressive disclosure audit! Oh yeah, preflight this! Challenge that! Argh… what was it called that I need you to do here!! Look it up! I can't remember! That's a daily lived experience!"
+
+That is not a hypothetical scenario. That is an operator who built the system, knows every check exists, knows they're important — and still can't remember all the names, the sequence, or which ones apply right now. They're exhausted from trying. They built oddkit to prevent exactly this kind of cognitive overhead for other people's projects. And they're drowning in it themselves.
+
+The canon already has a name for this: `RITUAL_DETECTED` (`canon/diagnostics/ritual-detected.md`). The principle it derives from is explicit (`canon/principles/ritual-is-a-smell.md`): "If correctness depends on people repeatedly remembering a procedure, the system is compensating for missing design. Ritual is not 'bad.' Ritual-as-compensating-control is a smell."
+
+The examples in that very article include: "Always run preflight before anything" — because the system can't detect prerequisites. That is literally one of the rituals the operator is frustrated about. The canon diagnosed this problem before the operator experienced it. The diagnosis was just never applied to oddkit itself.
+
+The canon also prescribes the required response when a ritual smell is detected. The system must do one of: automate the ritual, inline it into the moment it matters so it's unavoidable, make it unnecessary by reducing hidden state, or detect non-compliance and fail closed. The continuous encoding fix proposed in this article is option two — inline the ritual into the moment it matters. The agent runs preflight, challenge, validate, and encode at every turn not because someone remembered to ask, but because the tool descriptions make it unavoidable.
+
+The operator knows the checks exist. The canon knows what they're called. The tools know when they apply. The only person who shouldn't have to know any of this is the user.
+
+This is the design test for everything that follows: if the operator still has to say "what was it called," the fix hasn't worked.
+
+---
+
+## The Real Fix — Continuous Encoding as Default Cognition, Not a Feature to Invoke
+
+The initial diagnosis suggested two sentences added to the encode tool description — a persistence disclaimer and an OLDC+H reference. The second iteration reframed it as automatic capture at session boundaries. Both aimed too low.
+
+The operator's insight is sharper: encoding isn't a periodic checkpoint. It's how the agent should think at every single exchange. After every user message — what did they just share? An observation? A decision? A constraint? Encode it. After every agent action — what was learned? What was decided? What constraint was discovered? Encode it. Start every response by encoding what was received. End every response by encoding what was done.
+
+This is not a batch operation. This is not a session-closing ritual. This is the agent's cognitive rhythm — as natural as a human collaborator jotting notes during a working conversation. The running ledger grows with every turn. At natural breakpoints — task completion, a decision reached, session end — the accumulated entries persist to project storage.
+
+The distinction from "session boundary capture" matters enormously:
+
+Session boundary capture still requires the agent to reconstruct the conversation at the end. Reconstructing is lossy — important observations get missed, the nuance of early decisions gets flattened by later ones, constraints stated in passing get forgotten. The longer the session, the worse the reconstruction.
+
+Continuous encoding captures in real time. Nothing gets lost to reconstruction because nothing needs to be reconstructed. The agent tracked it as it happened. The final persist is just committing what's already been captured — not generating it from memory.
+
+This also means the agent is better throughout the conversation, not just at the end. An agent that tracks OLDC+H continuously is an agent that knows what has been decided, what constraints are active, and what's still open — at every turn. The encoding process improves the conversation, not just the output.
+
+---
+
+## Implementation — Reinforcement at Every Layer
+
+The fix requires changes at every surface where agents encounter oddkit. No single change is sufficient. The principle must be reinforced at every layer so that continuous encoding becomes the default behavior regardless of which tool, agent, or platform is used.
+
+### Layer 1: Encode Tool Description — Disclaim Persistence, Name the Categories, Define the Rhythm
+
+The encode tool's MCP description must explicitly state three things:
+
+First, that encode does not persist. "IMPORTANT: This tool returns the structured artifact in the response — it does not persist or save it. The caller must write the output to the project's storage."
+
+Second, that OLDC+H is the standard vocabulary. "Standard artifact types: Observations (O), Learnings (L), Decisions (D), Constraints (C), and Handoffs (H) — collectively OLDC+H. See `odd/ledger/epistemic-ledger.md`."
+
+Third, the continuous encoding instruction. "Track OLDC+H at every exchange — after every user message and after every agent action. Encode what the user shared at the start of your response. Encode what you did at the end. Persist accumulated entries to project storage at natural breakpoints (task completion, decision reached, session end)."
+
+### Layer 2: Orient Response — Plant the Continuous Encoding Intention
+
+When `oddkit_orient` fires at the start of a session, its response should include: "Track OLDC+H continuously throughout this session. Encode what the user shares and what you do at every exchange. Persist to project storage at natural breakpoints."
+
+This plants the intention at the very first interaction. The agent is tracking from the first message, not scrambling at the end.
+
+### Layer 3: Encode Response — Instruct the Caller to Save
+
+When encode returns its structured artifact, the response must include: "This artifact has been structured but NOT saved. Write it to the project's epistemic ledger or project journal." The current `"status": "ENCODED"` reads as "done." Adding a `"next_action"` or `"persist_required"` field eliminates the false completion signal.
+
+### Layer 4: Governance Article — This Document
+
+This article itself is one of the reinforcement layers. When agents search oddkit's canon for guidance on encoding, session capture, or OLDC+H, this article surfaces and explains the continuous encoding principle. The governance exists in the canon so it can be discovered by any agent that searches for it.
+
+### Layer 5: Project Instructions — Hints That Reinforce the Default
+
+Projects using oddkit should include a hint in their project instructions: "This project uses oddkit for epistemic guidance. Agents should track OLDC+H continuously and persist to project storage at natural breakpoints. See `odd/ledger/epistemic-ledger.md`." This is a fallback reinforcement — the tool descriptions should be sufficient, but a project-level hint catches agents that don't read tool descriptions thoroughly.
+
+---
+
+## Why These Two Things — Axioms Plus Continuous Encoding — Solve Most Problems
+
+The axioms are four statements. They fit in any context window. They prevent the most expensive failure mode in agentic work: confident drift from reality. An agent that checks its claims against evidence, admits what it hasn't verified, and treats integrity as efficiency will produce better work than one with a hundred rules and no values.
+
+Continuous OLDC+H encoding is five categories tracked at every turn. It prevents the second most expensive failure mode: amnesia across sessions and within sessions. A project that captures what was observed, learned, decided, constrained, and handed off — continuously, as the conversation flows — doesn't lose its thread. Every turn builds on the last. The human stops re-explaining and starts directing.
+
+But continuous encoding does something that batch capture cannot: it improves the conversation itself. An agent that tracks OLDC+H at every exchange is an agent that knows, at any moment, what has been decided, what constraints are active, and what remains open. It doesn't need to be reminded. It doesn't re-litigate settled ground. It doesn't ask questions the user already answered three turns ago. The encoding process is not overhead — it is the agent's working memory.
+
+Every other feature in oddkit — orient, challenge, gate, validate, preflight, search, catalog — serves one of these two functions: keeping the work honest (axiom enforcement) or keeping the work remembered (continuous encoding and retrieval). The rest is plumbing.
+
+The irony that this article exists is that the system built to solve knowledge-transfer failure has a knowledge-transfer failure in its most important feature. The system that prevents amnesia has amnesia about its own core capability. Fixing it requires reinforcement at every layer — tool descriptions, orient responses, encode responses, governance articles, project hints — because a single point of instruction is a single point of failure.
+
+---
+
+## Alternatives Considered — Why Continuous Encoding Is the Right Fix
+
+**Alternative A: Add a shorthand command.** Teach agents that "encode OLDC+H" triggers the workflow. Reduces friction but still requires the operator to remember. If they forget, the knowledge is lost. The human remains the trigger.
+
+**Alternative B: Automatic capture at session boundaries.** Better — the agent does it without being asked. But still batch. The agent reconstructs the conversation at the end, which is lossy. Long sessions lose important early observations. And the agent doesn't benefit from the encoding during the conversation — only after.
+
+**Alternative C: Add OLDC+H to every project's system prompt.** Works per-project but scales linearly. Every new project needs the same boilerplate. The operator becomes the distribution mechanism.
+
+**Alternative D: Build a new persistence tool.** A hypothetical `oddkit_journal` that both encodes and saves. Violates the architectural principle that ODD is a protocol layer, not a storage layer.
+
+**Alternative E (chosen): Continuous encoding via multi-layer reinforcement.** Encode tool description teaches the rhythm. Orient plants the intention. Encode response says "save this." Governance articles define the principle. Project hints reinforce. No new tools. No per-project configuration. Every MCP consumer gets the behavior through the tool descriptions they already read. Cost of being wrong: minimal — text changes, fully reversible.
+
+---
+
+## The Principle Is Universal — Every oddkit Tool, Not Just Encode
+
+The operator has a phrase for this: "run the oddkit gauntlet." It means: orient, search, challenge, encode, validate — do all of them. The phrase exists because the operator is tired of invoking each tool individually. They're tired of being the scheduler for the agent's own cognitive process.
+
+The existence of that phrase is the proof that the system has failed. A user should never need a shorthand for "please use your own brain." If the agent has to be told to orient, told to search, told to challenge, told to encode — the human has become the dispatcher for a toolkit that should be self-activating. The tools ARE thinking. An agent doesn't need to be told to think. It thinks.
+
+Continuous encoding is not a feature of the encode tool. It is the operating model for every oddkit tool. The same failure mode — sporadic usage only when obvious or when the user forces it — applies across the entire toolkit. The same fix applies: proactive usage as part of the agent's cognitive rhythm, at every turn, without being asked.
+
+### orient — Not Just at Session Start
+
+Current failure: agents call orient once at the beginning and never again. The conversation pivots, the task shifts, a new subtask emerges — and the agent stays in the mode it started in. Planning mode when it should be exploring. Execution mode when it should be planning.
+
+Continuous pattern: orient whenever the context shifts. A new topic? Orient. A surprising result? Orient. The user changes direction? Orient. The agent should be asking itself at every turn: am I still in the right mode for what's happening right now?
+
+### search — Before Claiming, Not After Failing
+
+Current failure: agents search canon only when explicitly asked ("check the governance docs") or when they've already failed and need to recover. They improvise answers about policies, constraints, and conventions — then get corrected.
+
+Continuous pattern: search before making any claim that canon might have guidance on. Before answering a policy question, search. Before proposing a convention, search. Before writing a document, search for the writing canon. The search is not overhead — it's the difference between grounded work and improvisation.
+
+### challenge — Before Encoding, Not When Asked
+
+Current failure: agents call challenge only when the user says "pressure-test this." The most important moment for challenge — right before a decision gets encoded — happens without any pressure-testing at all.
+
+Continuous pattern: challenge proactively when the user or agent makes a strong claim, proposes a design decision, or is about to encode something. Not every claim — that would be paralyzing. But every claim that creates a constraint, closes an option, or would be expensive to reverse.
+
+### gate — At Every Mode Transition, Not Just Formal Ones
+
+Current failure: agents call gate only at explicit phase transitions ("we're done exploring, let's plan"). Most mode transitions happen implicitly — the conversation drifts from exploring to building without anyone noticing. That's premature convergence, and it's the most common failure mode in agentic work.
+
+Continuous pattern: gate whenever the agent senses a verb change. Are we about to build something we haven't finished designing? Gate. Are we planning something we haven't finished exploring? Gate. The gate is a speed bump, not a wall — it slows you down just enough to check.
+
+### validate — Before Claiming Done, Not After Shipping
+
... diff truncated: showing 624 of 2726 lines

_{You can send follow-ups to the cloud agent here.}

^{Reviewed by Cursor Bugbot for commit 8ad0914. Configure here.}