docs(promotions): P0003-P0009 — seven promotions for MCP server patterns

[klappy]

Summary

Slate of seven promotion artifacts (P0003-P0009) distilled from patterns observed across two MCP server projects in this program — klappy/PTXprint-MCP (v1.0 → v1.2 arc, PR #30 fresh-validator review) and klappy/agent-messaging-service (hosted /mcp planning, 2026-05-03). Each promotion is a proposal, not canon, per docs/promotions/README.md. Reviewer triage expected.

Why this slate exists

canon/principles/ritual-is-a-smell: "if correctness depends on people repeatedly remembering a procedure, the system is compensating for missing design." These patterns have been re-derived independently across at least two server projects within ~6 weeks. The fix per ritual-is-a-smell is to encode the discipline as canon so the next server project reads it once at preflight rather than re-deriving it under time pressure.

The seven promotions

ID	Type	Target	Risk	One-line
P0003	NEW method	canon/methods/reframe-before-trimming.md	Medium	Bloated tool surface? Question the frame, not the count.
P0004	NEW pattern	canon/patterns/docs-proxy-canon-as-tool.md	Low	MCP servers SHOULD expose docs proxy so consumers wire one MCP, not two.
P0005	NEW principle	canon/principles/async-by-default-for-long-running-tools.md	Low	Any tool >5s returns id+poll+cancel, never blocks.
P0006	AMEND vodka-architecture	append section	Medium	Specs MUST enumerate "knows / does not know" + "what this is NOT".
P0007	AMEND definition-of-done	append section	Low	Spec DoD = 5–7 agent-observable behaviors, not implementation milestones.
P0008	AMEND release-validation-gate	append section	Medium	Fresh-validator deliverable is a DOLCHEO ledger committed to the repo.
P0009	AMEND dolcheo-vocabulary	append section	Low	Explicit anti-pattern callout: do not write "DOLCHEO+H".

Recommended sequencing

If shipping all seven: P0007 first (low-risk DoD sharpening, immediately useful for in-flight specs) → P0004 (most actionable, AMS could adopt this week) → P0003 + P0006 together (adjacent moves) → P0005 (independent, lands any time) → P0009 (small-blast-radius, kills a recurring hallucination at canon source) → P0008 last (highest operational ripple).

Each can also ship independently. Reviewer may accept any subset.

Pre-push gauntlet results

Audit 1 — link-rot (oddkit_audit-equivalent): 8/8 cited existing canon URIs resolve in this clone. 3 new canon URIs (the targets the promotions create) correctly unresolved — they exist only post-acceptance.

Audit 2 — adjacent-canon (canon-integration-audit Audit 2): every promotion cites the matching existing canon via derives_from chains. Notably:

• P0003 cites doing-less-enables-more (landed 2026-05-02, canon: add doing-less-enables-more — the empirical principle behind vodka architecture #162) as the structural empirical claim it operationalizes
• P0005 cites partial-data-with-transparency-and-background-warm as the read-side complement to its action-side principle
• P0008 cites dolcheo-vocabulary and release-validation-gate (the two docs it joins at the deliverable layer)
• P0009 cites both dolcheo-vocabulary and the superseded oldc-h-vocabulary (the propagation source)

Audit 3 — frontmatter validation (canon-integration-audit Audit 3): 9/9 files in docs/promotions/ pass type-discipline (uri, title, audience, exposure, tier, voice, stability, tags, promotion_status). All 7 new files have URI tails matching their filenames and titles starting with P####:.

oddkit_challenge against P0003 (highest stakes — Medium risk, recently-landed-canon adjacent): challenge surfaced the standard prereqs for pattern-coinage / principle-extraction (alternatives considered, retraction conditions, sample size). block_until_addressed: false. P0003 was already reframed mid-authoring from canon/principles/inversion-before-trimming.md to canon/methods/reframe-before-trimming.md after surveying recent canon — the principle space is occupied by doing-less-enables-more; P0003 positions itself as the operational method (post-drift diagnosis), not a competing principle.

Mid-session recovery — numbering collision

My initial clone showed only P0001 in docs/promotions/. While running the gauntlet, the oddkit_challenge response surfaced a citation to P0002-borrow-evaluation-before-implementation that did not exist locally. git pull revealed PR #163 had merged in the interim, taking P0002. I renumbered all seven from P0002-P0008 → P0003-P0009 (URIs, titles, body self-refs all updated; verified via grep). No content collision with the new P0002 (different topic — adding "Bide" to the 5B method).

Promotion #4 — DOLCHEO not DOLCHEO+H (P0009)

Worth special note: this promotion grew out of an operator-flagged hallucination during the slate-authoring session itself. The malformed string "DOLCHEO+H" propagated from a canon-resident artifact in klappy/PTXprint-MCP (canon/encodings/pr-30-fresh-validator-ledger.md line ~12) into freshly-authored slate documents, 8 instances across 2 files before the operator caught and corrected it. Operator framing: "It is minor but I am frustrated at it resurfacing every conversation."

P0009 proposes a two-paragraph anti-pattern callout in the DOLCHEO vocabulary doc that makes the malformed form findable through oddkit_search, killing the hallucination at canon source. The PTXprint-MCP repo also has the malformed string and would benefit from a sibling cleanup PR (noted in the promotion).

Per the docs/promotions/README.md rules

• ✅ Evidence: each promotion has ≥2 independent observations across distinct repositories
• ✅ Specific Canon target named
• ✅ Risk Assessment present
• ✅ Status proposed
• ✅ No automation of Canon changes — this PR adds promotion artifacts, not the canon docs themselves; canon edits are separate follow-up PRs after acceptance

Author

Claude (Sonnet) via klappy/agent-messaging-service planning session, 2026-05-03. Authoring transcript and prior-session artifacts available on request.

---

Note

Low Risk
Documentation-only change adding proposed promotion artifacts; no runtime or build impact, with only process/guidance implications if later accepted into canon.

Overview
Adds seven new proposed promotion artifacts (P0003–P0009) under docs/promotions/, each capturing an observed MCP-server governance pattern and proposing specific canon additions or amendments.

The slate covers: reframing bloated tool surfaces before trimming, adding a docs proxy tool to avoid wiring two MCPs, defaulting long-running tools to an async id + status + cancel shape, and tightening spec/review conventions (explicit vodka boundary enumeration, DoD as agent-observable behaviors, fresh-validator output as a committed DOLCHEO ledger, and an anti-pattern note to avoid the term DOLCHEO+H).

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

[github-actions]

Canon Quality — oddkit_audit ⚠️

1 finding(s) in writings/ (39 files scanned). Mode: soft.

writings/agentic-software-development.md — 1 finding(s)

Line	Rule	Occurrence	Message
242	dead-reference	klappy://writings/nothing-new-even-ai	URI does not resolve

3 finding(s) suppressed via <!-- audit-allow: ... --> directives.

Soft-block mode — this status is informational; the job will not fail. Hard-block ships in PR-3.2 after the observation cycle.

What to do for each finding:

• Fix the slug if the target now lives at a different klappy:// URI.
• Remove the link if it is no longer needed.
• Allowlist with a reason if the rot is intentional (e.g. forward-ref to an upcoming article): place <!-- audit-allow: dead-reference reason="..." --> on the line above the offending link. The directive is line-level and scopes to the next markdown link.

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