canon(constraints): bug-class lessons from resolver PR (Phase 2 PR-2.3b)

[klappy]

Summary

Phase 2 PR-2.3b of the link-rot-elimination campaign. Encodes three bug-class lessons from PR-2.1 (the resolver implementation) as tier-2 canon constraints. Sibling to klappy/oddkit#143 (the audit implementation).

Per operator decision in PR-2.2: bundle the three bug-class lessons from the resolver PR's review and validation into PR-2.3 as supporting canon. Making them canon (not just commit messages) makes them searchable and audit-checkable.

Three new tier-2 constraints (additive)

1. canon/constraints/oddkit-action-registration-completeness.md

New oddkit MCP actions must register in both the dispatch switch and the VALID_ACTIONS array. Caught by Cursor Bugbot on PR-2.1's initial commit; without the catch, the resolver would have shipped Unknown action: resolve errors to every caller because the validator rejects names not in the allowlist before dispatch is reached. Process control until a typecheck-time invariant exists (a possible future fix is captured in the constraint's "Future Work" section).

2. canon/constraints/superseded-by-shape-normalization.md

Tools that read superseded_by must normalize across three shapes:

• Full canonical URI: klappy://canon/x/y
• Path with .md: canon/x/y.md
• Path without: canon/x/y

Cycle detection keys on canonical URI, not raw superseded_by string. Caught by the independent Sonnet 4.6 validator dispatched per release-validation-gate on PR-2.1 — klappy://docs/oddkit/proactive/dolche-vocabulary had superseded_by: "canon/definitions/dolcheo-vocabulary.md" and the resolver's strict-URI lookup couldn't follow it. The Vodka rule applies: the resolver normalizes; consumers and authors don't.

3. canon/constraints/bash-test-rig-assignment-chain-discipline.md

Bash silently concatenates two assignments when the newline between them is dropped:

RAW=$(curl -X POST -d '...')RESULT=$(extract_json "$RAW")  # the bug

Parses, runs, produces wrong values. After any closing ) of a command substitution, the next character must be a newline. bash -n does NOT catch this. Caught by post-merge CI on PR-2.1's third commit; one-character fix, non-trivial diagnostic time. Authoring discipline + visual blank lines as preventive; CI lint as durable fix when ritual breaks down.

Why land these as canon and not just commit messages

Commit messages don't show up in oddkit_search. Canon constraints do. The next time someone (or some agent) is about to add an oddkit action, mishandle a superseded_by chain, or paste a bash test block, they can find the constraint by searching for the symptom — not just by remembering "didn't this come up in some PR a few months ago?"

What this PR does NOT do

• Does not modify the audit implementation (feat(audit): add oddkit_audit MCP action — Phase 2 PR-2.3a oddkit#143)
• Does not implement CI workflow (Phase 3)
• Does not change any existing canon
• Does not break any existing references — three additive constraint docs

Refs

• feat(resolve): add oddkit_resolve MCP action with transparent supersession oddkit#140 (PR-2.1 — where all three bugs surfaced)
• feat(audit): add oddkit_audit MCP action — Phase 2 PR-2.3a oddkit#143 (PR-2.3a — sibling, audit implementation)
• klappy://docs/planning/link-rot-elimination-campaign
• klappy://canon/constraints/release-validation-gate (the gate that caught two of three bugs)
• klappy://canon/principles/vodka-architecture (the principle the superseded_by-normalization constraint operationalizes)

---

Note

Low Risk
Documentation-only changes: adds new canon constraint pages and a small spec clarification, with no runtime code impact.

Overview
Adds three new tier-2 canon constraints capturing recurring failure modes from the resolver work: (1) bash test rigs must not accidentally join $(...) assignments across missing newlines, (2) new oddkit actions must be registered in both the dispatch switch and VALID_ACTIONS, and (3) superseded_by consumers must normalize three allowed value shapes and key cycle detection on canonical URIs.

Updates the oddkit_audit spec to clarify/narrow the default scope.paths to [writings/] (with rationale tied to CI timeout/cold-cache behavior).

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