Add tier-2 principle: Specs Lock at Implementation (canon 0.37.0, E0008.6)

[klappy]

Summary

New tier-2 principle articulated by you on 2026-04-30 during the klappy/ptxprint-mcp telemetry-feature planning conversation:

"Specs shouldn't be changed after implementation. V1.3 is the right call."

The principle is the spec-level analog of the gate-lock pattern that mode discipline applies inside a single execution turn (canon/principles/contract-governs-handoff-drift.md). At turn scale: when you say "go," the scope is locked. At spec scale: when implementation begins, the contract is locked.

---

Files (2)

canon/principles/specs-lock-at-implementation.md (new, 162 lines)

Tier 2, neutral, working. Structure mirrors verification-requires-fresh-context.md and contract-governs-handoff-drift.md:

• Summary blockquote stating the principle
• §When does a spec lock? — four signals (code committed, autonomous run kicked off, human implementer assigned, release artifact shipped)
• §Why specs drift quietly — three pressures ("small fix", "keep it current", "no one will notice")
• §What forward-looking looks like in practice — the vN+1 with supersedes: pattern
• §Edge cases — pre-implementation changes (fine), cross-cutting current-state docs (different rules), errata (gray, prefer vN+1 with errata note), implementation-time discoveries (default to stop-and-respec or defer-and-document; inline clarification is the temptation that erodes the principle)
• §Failure modes — ghost contracts, auditable-mapping erosion, re-validation churn, forward-looking changes losing their venue
• §Companion patterns at other scales — table placing the principle in the contract-stability family (mode discipline / spec lock / canon authority / canon versioning, at four time horizons)
• §Origin — H-T3 graduation case + retroactive H-T4 revert application

canon/CHANGELOG.md

Canon version bumped 0.36.1 → 0.37.0 (minor: new substantive content). New entry follows the format established by 0.36.0/0.36.1: impact framing first, sub-epoch annotation, deciding-argument case cited, ### Added — Canon section.

---

Governance discipline compliance (per canon/constraints/governance-change-discipline.md)

Marker	Status
Canon version bump	✅ 0.36.1 → 0.37.0
Changelog entry	✅ Top of canon/CHANGELOG.md
Release notes (impact framing)	✅ In the changelog entry
Epoch bump	✅ E0008.6 (Spec-Lifecycle Discipline)

---

One thing to verify

Epoch numbering — E0008.6. I picked this as the next sub-epoch after E0008.5 (Search-Corpus Boundary, 2026-04-29). The principle is conceptually adjacent to E0008.4 (governance-change-discipline) — both are governance disciplines for documents that bind implementer behavior — and operationalizes the contract-stability theme that contract-governs-handoff-drift opened in E0008.3.

If you have a different sense of where it slots (e.g., should fold into E0008.5, or should jump to E0009 because it's a new theme), the changelog entry and the principle's frontmatter both need the same single-string update.

---

Audit trail (cumulative across both repos this session)

PR	Repo	What	Status
#25	ptxprint-mcp	H-T2 fresh-session review (managed-agent)	merged
#26	ptxprint-mcp	H-T2 revisions applied	open
#27	ptxprint-mcp	v1.3 spec resolves H-T3	open
#28	ptxprint-mcp	Revert H-T4 v1.2 spec edits (apply this principle retroactively)	open
this	klappy.dev	Encode the principle as canon	open

---

Note

Low Risk
Documentation-only change (new principle + changelog entry) with no code or runtime behavior modifications.

Overview
Adds a new tier-2 canon principle, Specs Lock at Implementation, defining that once implementation begins the spec becomes a locked contract and all forward-looking changes must ship as vN+1 (with guidance on lock signals, common drift pressures, edge cases like errata, and recommended supersedes/versioning patterns).

Bumps canon pack version to 0.37.0 and records the new sub-epoch E0008.6 in canon/CHANGELOG.md, including the deciding-argument case that motivated the rule.

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

[github-actions]

Canon Quality — oddkit_audit ✅

No dead klappy:// references or legacy link patterns found in writings/. 39 files scanned.

_{Spec: klappy://docs/oddkit/specs/oddkit-audit · Workflow: .github/workflows/canon-quality.yml · Run: #20}

[klappy]

✅ Independent fresh-context validation — recommend merge

Note on review event type: posted as COMMENT rather than APPROVE because GitHub blocks self-approval and the PAT shares the author's identity. The substance is an approval; the event type is a procedural workaround. Substantive validation summary follows.

Reviewer: Claude (Opus 4.7) operating as a fresh-context validator session, separate from the klappy/ptxprint-mcp authoring conversation. Per klappy://canon/principles/verification-requires-fresh-context and klappy://canon/constraints/release-validation-gate.

Release-Validation-Gate (tier 1)

Rule	Status	Evidence
R1 — No merge with active reviews	✅	Cursor Bugbot completed/success, zero findings, zero review comments. Reference integrity audit completed/success. Canon Quality (oddkit_audit) ✅ — 39 files, no dead refs.
R2 — Independent validation if load-bearing	N/A	Doc-only. No workers/src/orchestrate.ts, bm25.ts, governance-fetch additions, envelope changes, or oddkit_* action changes. Not load-bearing surface. (This session is a fresh-context review anyway.)
R3 — Canon wins over session artifacts	✅	No session artifact recommends skipping anything.

Governance-Change-Discipline (four markers)

1. ✅ Canon version bump 0.36.1 → 0.37.0 (correct minor — additive new principle)
2. ✅ Changelog entry at top of canon/CHANGELOG.md, format matches 0.36.1 / 0.36.0
3. ✅ Impact-framed release notes in first paragraph
4. ✅ Epoch bump to E0008.6 (Spec-Lifecycle Discipline)

Writing canon (the principle file)

• ✅ Summary blockquote present
• ✅ ## Summary — section present
• ✅ Descriptive headers pass scan test (When Does a Spec Lock?, Why Specs Drift Quietly, Edge Cases, Failure Modes, Companion Patterns at Other Scales, Origin)
• ✅ Frontmatter complete: tier 2, status active, stability working (correctly conservative), full derives_from / complements / governs
• ✅ Origin traces deciding-argument case (H-T3) plus retroactive H-T4 application

Oddkit gauntlet

• oddkit_challenge (canon-tier-2 mode): Non-blocking. Surfaces "single deciding-argument case → no counter-examples → prior-art check missing." Correctly absorbed by the stability: working flag and the Origin paragraph: "Future deciding-argument cases will further harden it." The principle ships honest about its provenance.
• oddkit_gate: Returned NOT_READY for planning → execution — but the merge is execution → completion, which the gate doesn't yet recognize (P11 roadmap item). Structural prereqs it could check (decisions_locked, irreversibility_assessed) are met. Not a PR defect.
• oddkit_validate: NEEDS_ARTIFACTS (visual proof) — per canon, expected for text commits, not a failure state.

Non-blocking observations

1. Cross-repo derives_from citation. Frontmatter cites klappy/ptxprint-mcp/canon/encodings/telemetry-feature-planning-ledger.md (H-T3 resolution) — oddkit_get cannot resolve that URI from klappy.dev canon. Documentation pointer, not a load-bearing dependency. Future reader auditing provenance will need to clone the other repo.
2. Author-flagged open item: Epoch slot for E0008.6 (vs fold-into-E0008.5 vs jump-to-E0009). Operator's call; single-string update if changed. PR is mergeable either way.

Verdict

Recommend merge. All three release-validation-gate rules satisfied, all four governance-change-discipline markers present, writing canon clean, Bugbot green with no findings. The only outstanding item is the epoch-slot knob — your call, not a blocker.