canon(telemetry): add Description column to Self-Report Fields table#102
Merged
Conversation
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
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.
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>
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
Extends the
Self-Report Fieldstable incanon/constraints/telemetry-governance.mdfrom 3 columns (Field, Header, Source) to 4 (+ Description). Each header now carries authoritative per-field guidance with concrete examples.Why
Canary refactor PR
klappy/oddkit#106reads this table at runtime to populatetelemetry_policy'sself_report_headersresponse field. The prior 3-column schema gave callers only short labels like "Client name" — the hardcoded worker dictionary had richer guidance like "Your client name (highest priority identifier)" that was lost when canon became the source of truth.Execution-mode challenge on the canary PR flagged this as an information regression: the refactor moved to canon-as-source-of-truth but canon didn't carry the information that was being replaced. Two options were on the table: extend the canon table, or accept short labels and retire the richer descriptions as code fiction. Extending canon is the DRY answer — the guidance belongs somewhere authoritative, and code is the wrong place.
Effect
telemetry_policyresponse'sself_report_headersvalues now contain the full descriptions from canon instead of terse labelsx-oddkit-surface: claude.ai, vscode, cli, ci, production) so the table doubles as implementer docsCompanion PRs
klappy/oddkit#106— canary refactor that reads this table; needs a follow-up commit to pull the new Description columnklappy/klappy.dev#101—core-governance-baselinecontract draft (this column extension is a case-in-point of canon-is-authoritative)Merge order
This PR lands first. Then the canary PR (oddkit#106) gets a follow-up commit adjusting its parser to read column 4.
Note
Medium Risk
Although this is a documentation-only change, it modifies the canonical markdown table schema (adds a 4th column) that downstream tooling may parse at runtime; any consumers assuming a 3-column format could break until updated.
Overview
Updates
canon/constraints/telemetry-governance.mdby extending the Transparency Leaderboard “Self-Report Fields” table from 3 columns to 4 by adding a Description column.Each self-report header now includes concrete guidance and examples (e.g., expected values for
x-oddkit-surfaceand formatting for capability lists), making the canon table a richer source of truth for telemetry self-report metadata.Reviewed by Cursor Bugbot for commit bd3d94d. Bugbot is set up for automated code reviews on this repo. Configure here.