docs(audit): governance anti-pattern sweep across all oddkit tools#105
Merged
Conversation
Catalogs the Vodka anti-pattern — canon defines vocabulary, code hardcodes interpretation — across all 11 oddkit tools. PR #100's voice-dump schema bug (1h 39m prod breakage) was one instance of this class. Audit identifies 5 tools carrying the same shape. Findings: SEVERE: orient, gate, validate PARTIAL: encode, preflight CROSS-CUTTING: mode enum declared in 4 places CLEAN: challenge (post-refactor), search, get, catalog, version, time, cleanup_storage, telemetry_public Refactor priority ranked by impact × tractability. validate named as the most surprising: it gates 'done' but never reads canon/constraints/definition-of-done.md — which in fact does not exist in the repo despite three user-facing docs claiming it does. Companion PR on klappy/klappy.dev establishes canon/constraints/core-governance-baseline.md as the contract every sweep refactor will conform to.
Deploying with
|
| Status | Name | Latest Commit | Preview URL | Updated (UTC) |
|---|---|---|---|---|
| ✅ Deployment successful! View logs |
oddkit | 53dd1eb | Commit Preview URL Branch Preview URL |
Apr 19 2026, 12:07 AM |
5 tasks
…vise priority Canary (telemetry_policy self_report_headers reading from canon) shipped to prod via oddkit#106 + #107 and klappy.dev#102 (canon extension). Live smoke confirms governance_source: 'canon' with 8/8 canon-sourced descriptions. Corrections to the audit: - telemetry_policy was originally classified CLEAN but carried a hardcoded header dictionary next to the canon-fetched policy prose — the same anti-pattern class. Reclassified to LOW severity (drift, not correctness) and selected as the canary. Now ✅ shipped. - Refactor priority revised during planning after the canary was selected. New order: canary (✅ done) → validate+preflight bundled → mode-enum collapse → orient → gate → encode. Lessons-first-smallest sequencing rather than raw severity. Validate+preflight moves up because it's a correctness bug, not drift: validate gates 'done' but never reads canon/constraints/definition-of-done.md (which doesn't exist yet). First step is writing that canon doc.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What this adds
docs/oddkit/audit/governance-anti-pattern-sweep-2026-04-17.md— a complete audit of all 11 oddkit tools against the Vodka anti-pattern (canon defines vocabulary, code hardcodes interpretation).Why
PR #100 shipped a voice-dump suppression feature that was unreachable from the public MCP API for 1h 39m of prod breakage — schema rejected 6 of 9 modes the calibration canon defined. That bug was not unique to challenge. This audit sweeps all 11 tools for instances of the same shape.
Findings
SEVERE — same anti-pattern class as PR #100:
orchestrate.ts:1528canon/constraints/definition-of-done.md. That file is referenced byAGENTS.md,docs/MCP.md,docs/QUICKSTART.md, and the preflight fallback text — but does not exist in the repo.PARTIAL — discovery is canon-driven, interpreter is hardcoded:
discoverEncodingTypesreads canon correctly, butscoreArtifactQualityhardcodes English keyword matching to interpret canon-defined criteria. Same bug shape as PR feat(challenge): governance-driven runChallengeAction (E0008) #100.definition-of-done.md.CROSS-CUTTING:
workers/src/index.ts×2,src/core/tool-registry.js, andMODE_SIGNALSinorchestrate.ts. PR fix(mcp): expand challenge mode enum to all 9 modes — unblocks voice-dump suppression #102 commit message already flagged this as a follow-up.CLEAN (verified): challenge (post-refactor, gold standard), search, get, catalog, version, time, cleanup_storage, telemetry_public. (telemetry_policy was re-classified LOW after a closer pass — it has hardcoded header dictionary but the severity is drift, not correctness.)
Refactor priority (ranked)
canon/constraints/definition-of-done.mdfirst)Companion PR
klappy/klappy.dev#101—canon/constraints/core-governance-baseline.mdestablishes the three-tier resolution contract every sweep refactor will conform to (live canon → bundled baseline → fail-loud).Constraints applied to the sweep
git revertwithin 15 min. No forward-fix in prod.Note
Low Risk
Low risk: this PR only adds a documentation/audit markdown file and does not change runtime code paths.
Overview
Adds a new maintainer-facing audit doc,
docs/oddkit/audit/governance-anti-pattern-sweep-2026-04-17.md, cataloging where oddkit tools hardcode behavior that should be canon-driven (highlighting severe issues inorient,gate, andvalidate, plus partial issues inencodeandpreflight).The document also flags cross-cutting mode-enum duplication and proposes a refactor priority order and constraints (notably aligning
validate/preflighton a canondefinition-of-done.md).Reviewed by Cursor Bugbot for commit 53dd1eb. Bugbot is set up for automated code reviews on this repo. Configure here.