feat(challenge): governance_source envelope + peer governance_uris (0.19.0)

[klappy]

Summary

P1.3.1 canary retrofit for oddkit_challenge — mirrors the encode pattern from PR #114, first post-encode tool in the governance anti-pattern sweep.

What changed

• Four governance helpers retrofitted to return {<domainNoun>, source} tuples:
  • discoverChallengeTypes → {types, source}
  • fetchBasePrerequisites → {prerequisites, source}
  • fetchNormativeVocabulary → {vocabulary, source}
  • fetchStakesCalibration → {calibration, source}
• runChallengeAction aggregates sources strictly: any helper falling through to hardcoded defaults → aggregate = "minimal". All four from canon → "knowledge_base".
• Response envelope (both SUPPRESSED and CHALLENGED paths):
  • result.governance_source: "knowledge_base" | "minimal"
  • result.governance_uris: array of 4 peer canon URIs (alphabetical by path-tail)
  • debug.knowledge_base_url echoes override
• Smoke test extended with challenge envelope assertions + 9-mode parse integrity guard (PR feat(challenge): governance-driven runChallengeAction (E0008) #100 regression defense)
• Tool description updated to reference the four governance surfaces and two-tier signal

Design decision: governance_uris (plural) vs encode's governance_uri (singular)

Intentional shape divergence. Encode's encoding-type docs sit under one canonical umbrella (canon/definitions/dolcheo-vocabulary). Challenge reads four peer governance files with no hierarchy among them — a single anchor on any one of them (e.g. stakes-calibration because of its PR #100 weight) would misrepresent where base-prerequisites and normative-vocabulary live. Accurate representation outranks envelope-shape parity with encode. Consumers that prefer a singular anchor can read governance_uris[0]; alphabetical ordering keeps this stable. Called out explicitly in CHANGELOG so consumers reading both tools aren't surprised.

Two-tier cascade note (for validator)

Enum is "knowledge_base" | "minimal" today, not the three-tier shape in canon/constraints/core-governance-baseline. workers/baseline/ is not yet shipped — the bundled tier is a contract aspiration, not in-repo code. Same reality under which telemetry_policy (#106/#108) and encode (#114) shipped; parity with those precedents, not a contract deviation. Union expands additively to include "bundled" when the baseline build pipeline ships.

Verification

• npm run typecheck: clean
• node workers/test/governance-parser.test.mjs: 105/105 pass (no regression)
• Live smoke vs preview URL: 126/126 pass × 3 consecutive runs (isolate-warmup clean per P1.2 pattern)
• Preview: https://challenge-governance-source-envelope-oddkit.klappy.workers.dev/mcp

PRD

Planning artifact at /home/claude/work/prd-p1-3-1-challenge-canary.md (local to orchestrator session, not committed). PRD § numbers referenced in commit message and inline comments.

Closes

P1.3.1 per klappy://odd/handoffs/2026-04-20-p1-3-challenge-canary.

Next in sweep: one of {gate, preflight, validate, orient, search, catalog, cleanup, version}, to be decided in next session's handoff.

---

Note

Medium Risk
Changes the oddkit_challenge response contract by adding new envelope fields and refactoring governance-loading helpers, which could impact downstream consumers and caching behavior if assumptions about result shape exist.

Overview
oddkit_challenge responses now include result.governance_source (strictly aggregated across the four challenge governance fetches) and result.governance_uris (an ordered array of the four peer governance documents), and the knowledge_base_url override is echoed as debug.knowledge_base_url in both SUPPRESSED and CHALLENGED paths.

Internally, the four challenge governance helpers were refactored to return {<domainNoun>, source} tuples and their source classification is cached/reset alongside existing caches. The worker tool description and live envelope smoke test were updated to assert the new fields (including 9-mode coverage), and the release bumps to 0.19.0 with corresponding changelog notes.

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

[cloudflare-workers-and-pages]

Deploying with    Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Preview URL	Updated (UTC)
✅ Deployment successful! View logs	oddkit	3978232	Commit Preview URL Branch Preview URL	Apr 20 2026, 12:27 AM

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

Bugbot Autofix prepared a fix for the issue found in the latest run.

• ✅ Fixed: Vocab source misclassifies when hardcoded fallback runs
  • Derived parsedFromCanon from whether any vocabulary words were actually parsed (parse-success criterion) so that when the canon article exists but yields no rows and the hardcoded RFC 2119 fallback runs, source is classified as 'minimal', matching the other three helpers.

_{You can send follow-ups to the cloud agent here.}

^{Reviewed by Cursor Bugbot for commit 3978232. Configure here.}

[cursor]

Vocab source misclassifies when hardcoded fallback runs

Low Severity

parsedFromCanon is set to true when content is truthy (line 669), before any vocabulary tables are actually parsed. If the canon file exists but contains no parseable vocabulary tables, the hardcoded RFC 2119 fallback at lines 711–717 still runs, yet source becomes "knowledge_base". This contradicts the stated aggregation rule in the PR description ("any helper falling through to hardcoded defaults → aggregate = 'minimal'") and the comment at line 662–663 ("Left-falling to the hardcoded RFC 2119 fallback below is the 'minimal' tier"). The other three helpers (discoverChallengeTypes, fetchBasePrerequisites, fetchStakesCalibration) all classify source based on whether parsing produced non-empty results, making fetchNormativeVocabulary the inconsistent outlier.

Additional Locations (2)

• workers/src/orchestrate.ts#L661-L664
• workers/src/orchestrate.ts#L746-L751

 

^{Reviewed by Cursor Bugbot for commit 3978232. Configure here.}