fix(canon): Audit 2026-04-30 — supersede 3 stale encode artifacts, graduate code-claims-require-code-observation principle, queue CLI deprecation, surface Open dedup bug

[klappy]

Summary

Audit 2026-04-30 cleanup. Three documents shipped in PR #157 (E0008.4 Phase 1, merged earlier today) described code state that PR #96 in klappy/oddkit had retired on 2026-04-16. The audit traced a six-link citation chain — TruthKit-KB brief → P1.3.4 H-01 → user memory → planning conversation → PR #157 — in which no reader verified against current code. This PR is the corrective.

The corrective has two layers:

1. Document layer — supersede the three stale artifacts in place (preserved for postmortem), publish accurate replacements, queue CLI deprecation per operator decision.
2. Structural layer — graduate a new tier-1 canon principle (code-claims-require-code-observation) that names the failure mode so it cannot recur silently.

The audit also surfaced a previously undetected production bug: discoverEncodingTypes in the worker dedupes by letter alone, silently dropping Open's quality criteria when both Observation and Open register letter O. Verified live: an [O-open P1] artifact returns quality.maxScore: 4 (Observation's max) instead of 5 (Open's max). Fix is queued in the revised Phase 2 handoff.

Files (8)

Modified — supersession in place (3)

These three artifacts shipped in PR #157 with stale framing. Pattern: status flipped to superseded, superseded_by and supersession_reason frontmatter added, addendum block prepended explaining what was wrong, what's still true, what to read instead. Original bodies preserved verbatim below the addendum.

• docs/architecture/encode-architecture-problem-and-gaps.md
• odd/handoffs/2026-04-30-encode-vodka-refactor-alternative-d.md
• odd/ledger/2026-04-30-e0008-4-phase-1-encode-governance-migration-landed.md

New — accurate replacements + structural fix (5)

• canon/principles/code-claims-require-code-observation.md — NEW tier-1 principle. Canon governs intent; canon does not govern code behavior. Any claim of the form "the X currently does Y" must be backed by direct code observation against current HEAD, not citation of another document.
• docs/architecture/encode-current-state-2026-04-30.md — accurate current-state architecture doc, sourced by direct code observation at klappy/oddkit@1a1f093. Includes describes_state_at frontmatter naming the exact commits read. Maps the predecessor brief's six gaps against current reality.
• odd/handoffs/2026-04-30-encode-vodka-refactor-alternative-d-revised.md — revised Phase 2 handoff scoping the actual five small worker items (envelope plural alignment, dedup-by-letter bug, fallback baseline gap, self-teaching surface, schema-driven check evaluator) plus the Open dedup bug surfaced by the audit. Target oddkit 0.28.0.
• odd/handoffs/2026-04-30-cli-encode-deprecation.md — CLI encode deprecation track per operator decision. Telemetry-gated removal target: 0.30.0+.
• odd/ledger/2026-04-30-audit-cleanup-encode-artifacts-landed.md — closeout ledger for this PR (Decisions, Observations, Learnings, Constraints, Handoffs, Encodes), per the C-03 constraint graduated in PR feat(canon): E0008.4 Phase 1 — Encode governance from truthkit-kb (field schemas, quality criteria, architecture brief, Phase 2 handoff) #157.

Validation

This is canon-only — no code changes, no Bugbot validator agent gate required. Standard canon-doc gauntlet applies: frontmatter conventions, voice, claim auditability, cross-link integrity. Cross-references between the eight files were verified before push.

The Phase 2 PR (separate, in klappy/oddkit) will require the full release-validation-gate per klappy://canon/constraints/release-validation-gate.

What this PR does not do

• Touch klappy/oddkit source. Phase 2 is the next PR; it will fix the Open dedup bug and the four envelope/self-teaching items per the revised handoff.
• Delete the stale artifacts. They're preserved as evidence of the failure mode.
• Backport governance-driven encode to the CLI. Operator decision is deprecation, not parity.
• Rewrite user memory entries. Entry Expose ODD definition in navigation, indexing, and metadata #14 was updated in the prior session; remaining entries are queued for parallel audit but not load-bearing for Phase 2.

Provenance

Authored by direct code observation at:

• klappy/oddkit@1a1f093:workers/src/orchestrate.ts (governance discovery, parsers, scorer, action handler)
• klappy/oddkit@1a1f093:src/tasks/encode.js (legacy CLI parser, confirmed unchanged from pre-feat: add ?consumer= query param to getting started URLs and telemetry governance #96)
• GitHub API: PR feat: add ?consumer= query param to getting started URLs and telemetry governance #96 merge timing
• Live oddkit_encode call against production worker (Open dedup bug verification)
• klappy/klappy.dev@125cf8d1:odd/encoding-types/open.md (criteria count comparison)

Every claim of code behavior in the new architecture doc corresponds to a specific function and line range observed at the cited commits.

---

Note

Low Risk
Documentation-only changes that update canon status/supersession metadata and add new guidance; no runtime code paths are modified, so risk is limited to confusion from broken links or misapplied process.

Overview
Canon cleanup after Audit 2026-04-30: flips three encode-related artifacts (architecture brief, Phase 2 handoff, Phase 1 ledger) to status: superseded with frontmatter pointers and addendum blocks explaining the staleness and where to look instead.

Adds a new tier-1 principle, canon/principles/code-claims-require-code-observation.md, requiring direct HEAD code reads (and describes_state_at provenance) before making claims about current code behavior.

Publishes replacement docs: docs/architecture/encode-current-state-2026-04-30.md (current encode state + remaining items), a revised Phase 2 handoff scoping the real remaining work and surfacing the Open dedup bug, a separate handoff queuing Node CLI encode deprecation, and an audit closeout ledger recording the supersession decisions.

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

[github-actions]

Canon Quality — oddkit_audit ✅

No dead klappy:// references or legacy link patterns found in writings/. 39 files scanned.

_{Spec: klappy://docs/oddkit/specs/oddkit-audit · Workflow: .github/workflows/canon-quality.yml · Run: #19}