canon: add core-governance-baseline contract (draft)#101
Merged
Conversation
Adds canon/constraints/core-governance-baseline.md establishing the three-tier resolution stack (live canon → bundled baseline → fail-loud) that every oddkit canon-driven tool must conform to. Context: PR #100's voice-dump suppression bug was a canon/code drift (schema said 3 modes, canon defined 9) that shipped to prod for 1h 39m because no contract governed how tools reconcile canon vs shipped code. The governance anti-pattern sweep audit identified 5 of 11 tools with the same shape of bug. This contract is the architectural answer the sweep refactors conform to. Key provisions: - Three-tier resolution per governance file: canon (preferred) → bundled baseline (fallback) → fail-loud error envelope - Response envelope declares governance_source on every call - Six required-baseline files enumerated - Baseline regenerated from canon at build; build-time schema check fails deploy if baseline and canon diverge - Fail-loud envelope includes actionable resolution block with reference_content_url pointing at oddkit-hosted canon (reference, not mandatory) - New tool oddkit_baseline_check probes canon completeness pre-deploy Passes Writing Canon (5 tiers verified). Converged after 5 challenge rounds (no blocking objections). Ships tier:1 status:draft; graduates to status:active after the canary refactor (telemetry_policy) lands following this contract. Companion PR: klappy/oddkit audit/governance-anti-pattern-sweep
klappy
added a commit
to klappy/oddkit
that referenced
this pull request
Apr 18, 2026
Replaces the hardcoded self_report_headers dictionary with a runtime parse of canon/constraints/telemetry-governance.md #### Self-Report Fields table. Response envelope now declares governance_source: 'canon' when the fetch succeeds and the table parses, 'minimal' when it falls back to the shipped baseline. This is the canary refactor for the governance anti-pattern sweep (docs/oddkit/audit/governance-anti-pattern-sweep-2026-04-17). It conforms to the three-tier resolution contract drafted in klappy/klappy.dev#101 (canon/constraints/core-governance-baseline), exercising tiers 1 (live canon) and 3 (minimal baseline in code). Tier 2 (bundled baseline directory with manifest) and the build-time schema check arrive in follow-up work once the contract graduates from status:draft to status:active. Implementation: - New helper parseSelfReportHeadersTable in index.ts parses the '### Self-Report Fields' table section from the canon doc. - Parser is permissive (whitespace + backticks) and fails closed to null so the caller falls back to the minimal baseline rather than hiding the degradation. - Minimal baseline remains the 8 stable headers; canon controls the descriptions once live. Verified: - npm run typecheck: clean - Parser unit-tested against live canon content: 8/8 headers parsed - Parser degradation paths (no section, empty table) return null Refactor discipline this commit follows (from PR #100 post-mortem): - Single feature PR, single site touched - Public contract (MCP tool response) changes are additive (governance_source field added; self_report_headers keys unchanged) - Preview smoke against live prod will verify canon-tier response before promotion
klappy
added a commit
that referenced
this pull request
Apr 18, 2026
The canary refactor (klappy/oddkit#106) reads this table at runtime to populate telemetry_policy's self_report_headers response field. The prior 3-column schema (Field, Header, Source) gave callers only short labels ('Client name'); the hardcoded dictionary in the worker had richer per-field guidance ('Your client name (highest priority identifier)') that was lost when canon became the source of truth. Extending the table to 4 columns lets canon carry the authoritative per-header description. This is a DRY consolidation: the guidance lives in one place (here), the worker parses it at runtime, and updates flow through canon rather than code. Examples added per field (client names, surface identifiers, capability list format) so the table doubles as implementer docs for consumers wiring up their own telemetry headers. Related: klappy/oddkit#106 (canary refactor), #101 (core-governance-baseline contract draft).
klappy
added a commit
that referenced
this pull request
Apr 18, 2026
…102) The canary refactor (klappy/oddkit#106) reads this table at runtime to populate telemetry_policy's self_report_headers response field. The prior 3-column schema (Field, Header, Source) gave callers only short labels ('Client name'); the hardcoded dictionary in the worker had richer per-field guidance ('Your client name (highest priority identifier)') that was lost when canon became the source of truth. Extending the table to 4 columns lets canon carry the authoritative per-header description. This is a DRY consolidation: the guidance lives in one place (here), the worker parses it at runtime, and updates flow through canon rather than code. Examples added per field (client names, surface identifiers, capability list format) so the table doubles as implementer docs for consumers wiring up their own telemetry headers. Related: klappy/oddkit#106 (canary refactor), #101 (core-governance-baseline contract draft).
klappy
added a commit
to klappy/oddkit
that referenced
this pull request
Apr 18, 2026
…me (#106) * feat(telemetry_policy): canary refactor — headers from canon at runtime Replaces the hardcoded self_report_headers dictionary with a runtime parse of canon/constraints/telemetry-governance.md #### Self-Report Fields table. Response envelope now declares governance_source: 'canon' when the fetch succeeds and the table parses, 'minimal' when it falls back to the shipped baseline. This is the canary refactor for the governance anti-pattern sweep (docs/oddkit/audit/governance-anti-pattern-sweep-2026-04-17). It conforms to the three-tier resolution contract drafted in klappy/klappy.dev#101 (canon/constraints/core-governance-baseline), exercising tiers 1 (live canon) and 3 (minimal baseline in code). Tier 2 (bundled baseline directory with manifest) and the build-time schema check arrive in follow-up work once the contract graduates from status:draft to status:active. Implementation: - New helper parseSelfReportHeadersTable in index.ts parses the '### Self-Report Fields' table section from the canon doc. - Parser is permissive (whitespace + backticks) and fails closed to null so the caller falls back to the minimal baseline rather than hiding the degradation. - Minimal baseline remains the 8 stable headers; canon controls the descriptions once live. Verified: - npm run typecheck: clean - Parser unit-tested against live canon content: 8/8 headers parsed - Parser degradation paths (no section, empty table) return null Refactor discipline this commit follows (from PR #100 post-mortem): - Single feature PR, single site touched - Public contract (MCP tool response) changes are additive (governance_source field added; self_report_headers keys unchanged) - Preview smoke against live prod will verify canon-tier response before promotion * refactor(workers): extract parseTableRow to shared markdown-utils * fix(telemetry_policy canary): read Description column + add parser tests Addresses execution-mode challenge gaps on PR #106: 1. Information regression fixed: parser now reads canon's column 4 (Description) instead of column 0 (Field label). Canon was extended with richer per-header descriptions in klappy/klappy.dev#102; this commit updates the parser to consume that new column. 2. Tests committed: Test 8 added to workers/test/governance-parser.test.mjs covering 8/8 header extraction, non-trivial description lengths, and degradation paths (no section, empty table). All 105 tests pass against the unmerged klappy.dev branch via KLAPPYDEV_RAW override. Still outstanding (follow-up work, not blocking the canary): - parseTableRow duplicated across workers/src/index.ts and workers/src/orchestrate.ts. Accepted duplication for now, flagged in both sites; export-and-share refactor lands when the sweep surfaces more duplication candidates. - Preview smoke against Cloudflare preview with the extended canon loaded but no worker redeploy — run manually after this PR deploys. Companion PR: klappy/klappy.dev#102 (canon extension). This worker change is backward-compatible with the old 3-column table: the parser requires 4 cols, so against the old canon it falls through to the minimal baseline tier. Once klappy.dev#102 merges, canon tier takes over. --------- Co-authored-by: Cursor Agent <cursoragent@cursor.com>
Live validation of telemetry_policy canary (klappy/oddkit#106) against prod surfaced three gaps the original contract didn't name explicitly enough: 1. Response envelope shape is part of the contract. A tool that returns {action, result} but omits server_time/assistant_text/debug breaks the time-discipline system even if governance_source is present. Added as Runtime Invariant #3. 2. canon_url parameter must be in the Zod schema, not just documented as a concept. MCP silently strips unknown parameters. The canary shipped with schema={} and canon_url was unreachable. Added as Runtime Invariant #4. 3. Live-smoke against the MCP endpoint is a ship-blocker, not a nice-to-have. Internal parser tests passed while the tool shipped with broken envelope and silent param stripping. Added as Runtime Invariant #7, template referenced. Refactor Implications section expanded to a 7-point checklist and acknowledges the canary's partial completion + follow-up PR as the first documented test of the contract. Follow-up PR that closes the canary gaps: klappy/oddkit#108.
…canon→knowledge_base, baseline→bundled External-facing rename: terminology that users and future maintainers will actually read. Decision to rename made after canary validation revealed that 'canon' and 'baseline' are ODD-specific jargon that leaks into every caller's mental model. Zero reported external users today, so the migration cost is zero. Naming principles applied: - Name by function, not form. 'knowledge_base_url' names what the URL refers to (a knowledge base); 'canon_url' presumed a specific governance framework. - Use plain English that external users already know. 'Knowledge base' is universal vocabulary; 'canon' is a Klappy/ODD term. Tier renames in response envelope: - canon → knowledge_base (served from user's KB) - baseline → bundled (served from Worker's bundled snapshot) - minimal → minimal (unchanged; already plain English) 'Canon' as a content genre/concept stays throughout the prose — it's still what the docs ARE (stable, curated, human-governed truth). 'Knowledge base' is where they LIVE (a URL you point at). Different concepts, different words. Companion changes landing separately: - klappy/oddkit#108 (telemetry_policy canary completeness + same rename) - #105 (no changes needed — doesn't reference canon_url) - canon/principles/consistency-same-pattern-every-time.md — one stray reference to update in a follow-up sweep commit TruthKit alignment: this rename makes 'bring your own knowledge base' the supported story. A TruthKit consumer sets knowledge_base_url and the response envelope's governance_source tells them whether they're reading their canon, the bundled fallback, or the minimal last resort.
klappy
added a commit
that referenced
this pull request
Apr 19, 2026
Forward-facing documentation sweep aligning tool reference docs, consistency principle, and template with the rename landing in klappy.dev#101 and klappy/oddkit#108. Files updated: - canon/principles/consistency-same-pattern-every-time.md — one reference to `canon_url` values being server-invariant - docs/oddkit/tools/oddkit_{search,get,encode,orient,catalog,challenge, version,gate,cleanup_storage}.md — tool schema parameter references - docs/oddkit/tools/telemetry_public.md — telemetry schema field name and SQL query alias (blob6 was documented as canon_url; now documented as knowledge_base_url with the same underlying blob) - docs/examples/project-instructions-template.md — step 3 reference - docs/oddkit/IMPL-catalog-recent.md — temporal-discovery docs Intentionally NOT updated (historical records): - docs/planning/e0007-implementation-plan.md - docs/oddkit/proactive/handoff-to-new-conversation.md - docs/oddkit/proactive/e0007-validation.md These are archaeological records of epoch-7 planning and validation. Rewriting them to use current terminology would falsify the historical record. The terminology shift is documented in the PR landing this rename; readers of historical planning docs can infer the mapping. Companion PRs: - #101 (contract with new terminology) - klappy/oddkit#108 (tool implementation + smoke test)
klappy
added a commit
to klappy/oddkit
that referenced
this pull request
Apr 19, 2026
User-facing terminology rename. Companion to klappy/klappy.dev#101 (contract update) and klappy/klappy.dev#118 (forward-facing doc sweep). Public API changes: - Every tool's Zod schema parameter: canon_url → knowledge_base_url. Affects oddkit router tool (action-routed) and all per-action tools (orient, search, get, challenge, gate, preflight, validate, encode, catalog, version, cleanup_storage) via the unified args passthrough. - telemetry_policy schema also renamed, with updated description naming strict-mode semantics: 'When set, strict mode is automatic: missing files fall through to the bundled governance tier rather than silently substituting from the default knowledge base.' Response envelope tier strings: - governance_source: "canon" → "knowledge_base" - governance_source: "baseline" → "bundled" - governance_source: "minimal" → "minimal" (unchanged) Smoke test (workers/test/canon-tool-envelope.smoke.mjs): - All parameter references renamed - Tier-string assertions updated - Strict-override test now explicitly verifies the 'knowledge_base_url set → bundled fallback suppressed' contract - Error message assertions check debug.knowledge_base_url echo Intentionally NOT renamed in this commit (internal, deferred): - ZipBaselineFetcher class → would become KnowledgeBaseFetcher - Internal variable canonUrl in orchestrate.ts (111 refs) - Internal variable canonUrl in telemetry.ts - BASELINE_URL environment variable Deferring internal renames keeps this PR focused on the user-visible contract. A dedicated internal-rename PR will clean up the class, variable names, and env var in one coordinated pass so reviewers can see the full internal shift at once rather than spread across the user-facing change. The router passthrough (orchestrate.ts interface) still names its input field canon_url for now — the rename there happens in the internal PR. Users never see that field; they pass knowledge_base_url at the MCP level and it's mapped to the orchestrator's canon_url parameter internally. Typecheck clean. Smoke test will run against Cloudflare preview once this commit deploys.
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
A new tier-1 canon doc at
canon/constraints/core-governance-baseline.mdestablishing the three-tier resolution stack that every oddkit canon-driven tool must conform to: live canon → bundled baseline → fail-loud error envelope, withgovernance_sourcesignal on every response.Why
PR klappy/oddkit#100 shipped a voice-dump suppression feature that was unreachable from the public MCP API for 1h 39m of prod breakage — canon defined 9 modes, the worker schema accepted 3. That was one instance of a class of bug: no contract governed how tools reconcile canon-defined vocabulary against shipped code.
The governance anti-pattern sweep audit (companion PR on klappy/oddkit) identified 5 of 11 tools with the same shape of bug. This contract is the architectural answer the sweep refactors conform to.
Key provisions
governance_source—canon | baseline | minimal | error— on every call. Callers can detect degradation.resolutionblock withif_using_default_canonandif_using_custom_canon_urlguidance, spec URI, andreference_content_urlpointing at the oddkit-hosted version (reference, not mandatory canon — consumers stay sovereign over content, inherit only structural contract)oddkit_baseline_checklets operators probe canon completeness pre-deploy; returns COMPLETE/INCOMPLETE/UNREACHABLE plus per-file detailsGovernance trail
canon/meta/frontmatter-schema(booleans/integers/dates unquoted, strings with specials quoted)Status
Ships
tier: 1, status: draft. Graduates tostatus: activewhen all of these land:governance_sourcein their envelopesoddkit_baseline_checkprobe shipsresolutionblockCompanion PR
klappy/oddkit— audit doc atdocs/oddkit/audit/governance-anti-pattern-sweep-2026-04-17.mdcatalogs the 5 tools with the anti-pattern and ranks refactor priority. The two docs are meant to be read together: audit establishes why, canon establishes how.Note
Low Risk
Low risk: adds a new canon constraint document only (no runtime or build changes), so impact is limited to how future oddkit governance refactors are guided/reviewed.
Overview
Adds a new tier-1 canon constraint,
canon/constraints/core-governance-baseline.md, defining a standard governance resolution contract for oddkit tools: live canon first, then a bundled baseline fallback, then fail-loud with an actionable error envelope.The doc also specifies required baseline files, build-time invariants (manifest + schema matching + baseline SHA), runtime invariants (mandatory
governance_source, full response envelope, andknowledge_base_urlhandling), and introduces a proposedoddkit_baseline_checkprobe for validating canon completeness.Reviewed by Cursor Bugbot for commit 1c24e9d. Bugbot is set up for automated code reviews on this repo. Configure here.