Handoff

Current epoch: E0008.3 (validation as fourth epistemic mode with context-break requirement). Canon merged. Covered in detail in klappy://docs/appendices/epoch-8-3 and klappy://canon/validation-as-epistemic-mode.

Next epoch (anticipated): E0009 — self-correction. Requires teams-over-swarms principle landing first. See O11 in the ledger.

What just shipped (this session):

1. klappy/klappy.dev#101 — knowledge_base_url contract rename + tier strings (canon → knowledge_base, baseline → bundled)
2. klappy/klappy.dev#106 — forward-facing doc sweep for the rename
3. klappy/klappy.dev#105 — validation as fourth epistemic mode (E0008.3) + context-break requirement + session ledger
4. klappy/oddkit#105 — governance anti-pattern audit doc (11-tool sweep)
5. klappy/oddkit#108 — telemetry_policy canary completion + rename + live smoke test template
6. klappy/oddkit#109 — main → prod promotion of the canary arc
7. klappy/klappy.dev#107 — DOLCHEO ledger framing + 19 open items + 5 open questions (contains this handoff; merge after reading)

Verified production state: https://oddkit.klappy.dev/mcp responding with full envelope (action, result, server_time, assistant_text, debug); telemetry_policy returns governance_source: "knowledge_base" by default; strict-override via knowledge_base_url correctly falls through to minimal tier when file missing. 24/24 smoke assertions green in prod.

---

Prompt-over-code refactor of all oddkit tools. This is where the session started and where the big remaining work still sits. E0008.3 was a detour that the canary incident forced us into — a good detour, but the canary was one tool out of eleven. The audit in docs/oddkit/audit/governance-anti-pattern-sweep-2026-04-17.md documents the full scope:

Every oddkit tool exhibits some form of the vodka anti-pattern: canon defines vocabulary (modes, challenge types, encoding types, DOLCHEO artifact types, stakes calibration, etc.), but tool code hardcodes interpretation. telemetry_policy was the first tool canary-refactored to fetch governance from the knowledge base at runtime with a bundled fallback and minimal last-resort. The same refactor is still needed for the other 10 tools.

The canary proved the pattern works. Now we scale it. The anti-pattern, the canary template, and the ship-blocker contract (live-smoke against deployed preview) are all documented in canon/constraints/core-governance-baseline.md.

---

P1.1 — Internal oddkit rename (scope expanded per 2026-04-19 decision)

Original scope: rename internal canonUrl variables, ZipBaselineFetcher class, BASELINE_URL env. Expanded scope based on operator decision that there are zero external users, so backward compatibility is not a constraint:

• Strip the a.canon_url legacy fallback from parseToolCall in workers/src/telemetry.ts
• Rename canonUrl → knowledgeBaseUrl across telemetry.ts (9 refs), orchestrate.ts (111 refs), zip-baseline-fetcher.ts (24 refs)
• Rename ZipBaselineFetcher class → KnowledgeBaseFetcher
• Rename BASELINE_URL env var → DEFAULT_KNOWLEDGE_BASE_URL (update wrangler.toml and every env.BASELINE_URL reference)
• Rename blob6 schema references from canon_url → knowledge_base_url in telemetry.ts comment block and docs/oddkit/tools/telemetry_public.md
• No aliasing, no dual-accept, no migration note — just rename and move on
• Run typecheck, deploy to preview, run workers/test/canon-tool-envelope.smoke.mjs against preview, merge if 24/24 green, promote to prod

Expected size: ~150 refs across 4 files. Mechanical but real. Do this with fresh eyes — decision to defer to fresh session was explicit E0008.3 practice.

P1.2 — DOLCHE → DOLCHEO vocabulary canon

Write tier-2 canon doc (candidate path: canon/definitions/dolcheo-vocabulary.md) establishing DOLCHEO as canonical, replacing DOLCHE.

Operator's lean (from session, needs final decision): DOLCHEO replaces DOLCHE — DOLCHE was always incomplete because Open items had no home. Both Os remain O; rely on section context to distinguish.

Doc should cover:

• Why the extension (retrospective-only tracking loses forward-pointing threads)
• Each letter defined: Decision, Observation (closed), Learning, Constraint, Handoff, Encode, Open (forward-pointing)
• Guidance on when to use Open vs Handoff (Handoff = work transfer; Open = unresolved thread or question)
• Example ledger structure with Open Items sectioned by priority band (P1–P6)

Then update the oddkit_encode tool description to reference DOLCHEO and unblock that long-deferred tool description improvement. See O3 in the ledger.

P1.3 — Verify oddkit#56 and #57 are stale

Two old open PRs on oddkit from months ago, both titled "Add oddkit_write tool definition (stub)". Duplicates of each other. Check if either is still relevant given the current direction. If superseded, close with a note linking to canon. If still planned work, leave open and update the ledger with the reference.

---

Per the audit doc (docs/oddkit/audit/governance-anti-pattern-sweep-2026-04-17.md), the canary pattern needs to be applied to each of these tools. Each one follows the same canary template: canon doc defines vocabulary → tool fetches canon at runtime → falls back to bundled tier → falls back to minimal hardcoded behavior → response envelope declares governance_source → Zod schema accepts knowledge_base_url optional override → ship-blocker live-smoke test added to the smoke suite.

Rough priority order (highest-impact anti-pattern first):

1. oddkit_encode — hardcoded four types (O/L/D/C/H), canon actually specifies DOLCHEO (seven letters). Biggest vocabulary mismatch in the system. Blocks tool description update until resolved. Pairs naturally with P1.2 (DOLCHEO canon doc) — do them together.
2. oddkit_challenge — execution mode has hardcoded claim type detection via regex. Canon defines challenge types in canon/. Tool should read types from canon at runtime.
3. oddkit_gate — problem_defined prerequisite uses hardcoded regex for transition detection. Cannot recognize writing-canon transitions without runtime canon read.
4. oddkit_preflight — Definition of Done lookups are partially hardcoded. Should read full DoD spec from canon.
5. oddkit_validate — Completion criteria matching is hardcoded. Canon has validation vocabulary (now including E0008.3 context-break requirement); tool should fetch.
6. oddkit_orient — Mode classification uses hardcoded mode list. Now that validation is a fourth mode (E0008.3), tool must read modes from canon to keep pace with canon changes without code redeploys.
7. oddkit_search — Ranking weights and tag boosts are hardcoded. Lower priority because search behavior is less load-bearing for epistemic correctness.
8. oddkit_catalog — start_here suggestions hardcoded. Should be canon-driven.
9. oddkit_cleanup_storage — Probably fine as-is; mostly mechanical storage work with no canon-vocabulary dependency. Verify and mark complete.
10. oddkit_version — Trivial tool, probably no vodka violation. Verify and mark complete.

Each refactor PR should:

• Include a canon doc update defining the vocabulary if not already canon-clean
• Pass oddkit_preflight and oddkit_challenge in canon-tier-1 or -2 mode
• Extend workers/test/canon-tool-envelope.smoke.mjs with assertions for the new tool's envelope and governance_source
• Live-smoke against preview deploy before merge — ship-blocker per canon/constraints/core-governance-baseline.md

Total scope: likely 8–10 separate PRs over several sessions. Do them in priority order; do them one at a time with full gauntlet each time.

---

P3.1 — canon/principles/teams-over-swarms.md (tier 2)

Governing architectural preference. Cite three anchors:

• African proverb: "If you want to go fast, go alone. If you want to go far, go together." (tradeoff)
• 1 Corinthians 12: body of Christ, many members with differentiated roles (anatomy)
• Operator testimony: oddkit and klappy.dev built alone (fast), TruthKit needs a team (far) (witness)

Sections:

• Opening blockquote
• Summary (engineering argument)
• Derivation from the body metaphor (Paul's four moves: no self-disqualification, no role-elimination, no one-part-does-everything, shared fate)
• When swarms are fine (keep principle honest — batch processing, parallel independent work)
• Architectural implications pointing forward to E0009 and TruthKit harness design

See O4 in the ledger.

P3.2 — Solo-to-team transition canon record

Durable decision doc recording the operator's explicit shift. Candidate location: odd/decisions/solo-to-team-transition.md or docs/appendices/solo-to-team-transition.md.

Covers:

• oddkit + klappy.dev as complete solo arc (public field notebook / resume / book source)
• TruthKit as team-driven commercial successor
• Open-core positioning (oddkit MIT cornerstone → TruthKit proprietary harness)
• Book Nothing New, Even AI as the polished handoff document from solo to team arc
• Course (O19) as the separate teaching product derived from the same journey

Should follow P3.1 so it can reference the teams-over-swarms principle.

P3.3 — canon/patterns/bugbot-as-validator.md (tier 2, lower priority)

Codify the bugbot collaboration pattern as canonical team architecture. See O6 in the ledger. Could live inside teams-over-swarms instead; decide when P3.1 is drafted.

P3.4 — canon/principles/mechanical-work-belongs-in-code.md (tier 2, lower priority)

Principle: if a transformation is mechanical (string splitting, formatting, classification with deterministic rules), the server owns it — not the LLM. Surfaced tonight via the encode blob-vs-artifact issue. First concrete application is oddkit_encode batch-mode. See O7 in the ledger.

---

P4.1 — oddkit_encode batch-mode feature (O2 in ledger)

Encode currently collapses multi-artifact input into a single typed blob. Fix: server-side paragraph splitting, optional typed prefixes ([D]/[L]/[O]/[C]/[H]/[E]), returns per-artifact array with individual quality scores.

This is P2.1 (encode canon refactor) and P4.1 combined — one PR, canon doc first, then tool change. Probably the single highest-leverage remaining work after the internal rename.

---

See O14, O15, O16, O19 in the ledger. Summary:

• Book Nothing New, Even AI — seven parts, polish/selection of public journal
• Essay: creator-cannot-be-own-critic — anchor tonight's bugbot story
• Essay: teams-over-swarms — general-audience version of P3.1 canon
• Course: chronological journey with forward-references — distinct product from the book (Q5 flags positioning decision)

---

See O17, O18 in the ledger.

• Social Projector at post.klappy.dev
• klappy.dev doc-listing cache staleness under GitHub rate limits

---

See Q1–Q5 in the ledger. The ones most likely to need a decision in the near term:

• Q1 — DOLCHEO replaces DOLCHE or coexists? (Decide when writing P1.2 canon doc; lean: replace)
• Q2 — Does the second O in DOLCHEO need a distinguishing letter? (Decide with Q1; lean: keep both as O)
• Q5 — Course (O19) a companion to the book (O14) or a separate product? (Decide before significant investment in either product's structure; lean: separate)

---

• Read the bootstrap first. Project instructions point at klappy://canon/bootstrap/model-operating-contract. Fetch it at session start. Mode discipline, context-break requirement, and DOLCHEO-style continuous tracking all live there.
• Declare mode out loud. "Exploring." "Moving to planning." "Executing." The operator should never guess.
• Search canon before asking. oddkit_search is essentially free. Most questions are already answered in canon.
• During execution, produce artifacts. Not questions. Not check-ins. Questions belong in planning.
• Validate with fresh context. You (the fresh session) ARE the fresh context for everything listed above. That is the structural advantage. Use it.
• Run the gauntlet before declaring canon done. oddkit_preflight → edits → oddkit_challenge in canon-tier-{1,2} mode → frontmatter audit → commit.
• Live smoke before merging any MCP tool change. Ship-blocker per canon. Template lives at workers/test/canon-tool-envelope.smoke.mjs in the oddkit repo.
• Track DOLCHEO continuously. Don't wait to be asked. Add Open items to the session ledger as they surface.

---

• GitHub PAT: see project instructions
• ANTHROPIC_API_KEY: see project instructions
• Working dirs used this session: /home/claude/work/oddkit, /home/claude/work/klappy.dev-pr/klappy.dev
• oddkit prod: https://oddkit.klappy.dev/mcp
• oddkit main preview: https://main-oddkit.klappy.workers.dev
• klappy.dev canon live on main branch

---

Orient. Search canon for prompt-over-code refactor oddkit tools and for vodka anti-pattern audit. Read the audit doc. Pick either P1.1 (internal rename, ~60–90 min, purely mechanical) or P1.2 + P4.1 bundled (DOLCHEO canon + encode batch-mode, ~2–3 hours, higher impact but more design work).

Either is a clean win. If operator is present, ask which they want to prioritize. If operating async from operator explicit instruction, default to P1.1 — lower-risk mechanical work is safer for an async session than design work.

Then open a new session ledger for that session's work and pick up the DOLCHEO tracking discipline from there.