feat(mcp): wave 7b — editing-convention config-CRUD tools

[thewrz]

Why

Wave 7 (config-CRUD parity, ADR-044), sub-wave 7b. Exposes the /conventions REST endpoints as MCP tools so an agent can manage a library's editing-convention profiles (the editor-clue rule sets — colors, choice tokens, banners; ADR-022), not just consume them.

What

Four tools, moved MCP_UNEXPOSED → OP_TO_TOOL with tiers:

Tool	Tier	REST op
list_conventions	read	GET /conventions
get_library_conventions	read	GET /libraries/{id}/conventions
set_library_conventions	write	PUT /libraries/{id}/conventions
clone_conventions	write	POST /libraries/{id}/conventions/clone

• get_library_conventions surfaces inherited: true when a library has no profile of its own and resolves to the built-in industry default.
• set_library_conventions upserts one profile per library and rejects an unsafe/catastrophic regex in the rules (ConventionValidationError → tool error, mirroring REST 422).
• clone_conventions seeds a library's profile from a built-in default or another library's profile by sourceId.
• Handlers reuse the REST body schemas verbatim (PutConventionBodySchema, CloneConventionBodySchema); no openapi.yaml change (wraps existing ops).

No destructive tool in this sub-wave. No trim needed on the convention name (the table has no length(trim(name))>0 CHECK, unlike templates).

Review

• Codex (GPT-5.5 xhigh) adversarial review: no actionable findings — tools registered, tiered, contract-mapped, with validation/error handling consistent with the neighboring tools.

Testing

• Unit tests pass (1345)
• Integration tests pass (835) — incl. new convention.integration.test.ts (built-in listing, inheritance, set→get, clone, error branches)
• Contract test green (INV-1/2/3 — 4 ops mapped + tiered)
• Lint (eslint + tsc + prettier) clean
• CI green

🤖 Co-authored by Claude Opus 4.8. Part of the Wave 7 config-CRUD parity series (ADR-044/045).

Summary by CodeRabbit

• New Features

  • Added MCP convention management tools for listing conventions, viewing/editing library conventions, and cloning conventions.
  • Library conventions now support inheriting built-in defaults, customizing per library, and cloning from built-in or existing profiles.

• Bug Fixes

  • Improved error responses for missing libraries, unknown clone sources, and invalid convention inputs.

• Tests

  • Added integration tests covering tool behavior, inheritance/copy semantics, and validation error handling.

[thewrz]

Codex (GPT-5.5, xhigh) adversarial review — ran against main. No actionable correctness issues. The convention tools are registered, tiered, and contract-mapped, with handler validation + error handling consistent with the neighboring tools (library existence guard → not-found, ConventionValidationError → tool error).

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: ac040e63-5ac7-4f36-b22f-34aef2b85b80

📥 Commits

Reviewing files that changed from the base of the PR and between 7f2375d and 3cafc4b.

📒 Files selected for processing (1)

• src/mcp/convention.integration.test.ts

---

📝 Walkthrough

Walkthrough

Adds Wave 7b editing-convention CRUD MCP tools: capability-tier and contract-map entries, handler implementations, registration wiring, and integration tests for listing, reading, updating, cloning, and validation.

Changes

Convention Config MCP Tools

Layer / File(s)	Summary
Capability tiers and contract mapping src/mcp/capabilities.ts, src/mcp/contract-map.ts	Registers list_conventions/get_library_conventions as read and set_library_conventions/clone_conventions as write in TOOL_TIERS; maps the corresponding REST routes in OP_TO_TOOL and removes them from MCP_UNEXPOSED.
Convention handlers src/mcp/convention-handlers.ts	Adds input shapes and handlers for listing, getting, setting, and cloning library conventions, with validation, inheritance detection, clone-source resolution, and tool-error mapping.
Tool registration wiring src/mcp/convention-tools.ts, src/mcp/tools.ts	Adds registerConventionTools to register read/write convention tool groups and wires it into registerTools.
Integration tests src/mcp/convention.integration.test.ts	Adds integration tests covering listing, inheritance, setting, cloning, missing-library errors, unknown clone sources, and unsafe-regex rejection.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Possibly related PRs

• wrzonance/SpecR#194: Adds the same conventions CRUD REST endpoints that this PR exposes through MCP mapping and handlers.
• wrzonance/SpecR#334: Extends the same TOOL_TIERS and OP_TO_TOOL/MCP_UNEXPOSED infrastructure that this PR updates.
• wrzonance/SpecR#337: Also updates the shared MCP tool-registration path in src/mcp/tools.ts with another tool group.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title is concise and accurately summarizes the main change: new MCP editing-convention config CRUD tools for wave 7b.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/mcp-contract-wave7b

---

_{Comment @coderabbitai help to get the list of available commands.}

[thewrz]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (1)

src/mcp/convention.integration.test.ts (1)

42-89: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Missing test coverage for unsafe/catastrophic-regex rejection.

The PR objectives call out that set_library_conventions rejects unsafe/catastrophic regex as a tool error (mirroring REST 422), via ConventionValidationError handling in convention-handlers.ts. This suite covers not-found errors but doesn't exercise that validation-rejection path — worth adding given it's a safety-relevant behavior explicitly promised by the PR.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/mcp/convention.integration.test.ts` around lines 42 - 89, Add test
coverage for the unsafe/catastrophic-regex rejection path in convention MCP
tools. Extend the convention integration suite around
handleSetLibraryConventions to attempt setting a convention with a regex pattern
that should be rejected, and assert the result is a tool error. Use the existing
helpers in convention.integration.test.ts and the set/get flow to verify the
ConventionValidationError path exposed by convention-handlers.ts is exercised.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@src/mcp/convention-handlers.ts`:
- Around line 61-65: `handleGetLibraryConventions` is returning a fixed
validation message instead of the actual Zod validation details, unlike
`handleSetLibraryConventions` and `handleCloneConventions`. Update the
`ConventionLibraryIdArgs.safeParse` failure path in
`handleGetLibraryConventions` to return `issues(parsed.error)` so the error text
reflects the specific input problem, and keep the success path unchanged.

---

Nitpick comments:
In `@src/mcp/convention.integration.test.ts`:
- Around line 42-89: Add test coverage for the unsafe/catastrophic-regex
rejection path in convention MCP tools. Extend the convention integration suite
around handleSetLibraryConventions to attempt setting a convention with a regex
pattern that should be rejected, and assert the result is a tool error. Use the
existing helpers in convention.integration.test.ts and the set/get flow to
verify the ConventionValidationError path exposed by convention-handlers.ts is
exercised.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 68eb48cc-94f4-4be7-a098-b9852f6d1258

📥 Commits

Reviewing files that changed from the base of the PR and between 1b1cf1d and 7f2375d.

📒 Files selected for processing (6)

• src/mcp/capabilities.ts
• src/mcp/contract-map.ts
• src/mcp/convention-handlers.ts
• src/mcp/convention-tools.ts
• src/mcp/convention.integration.test.ts
• src/mcp/tools.ts

[thewrz]

CodeRabbit nitpick addressed: added the missing unsafe/catastrophic-regex coverage. convention.integration.test.ts now asserts set_library_conventions with rules: { noteBanners: ['(a+)+$'] } returns a tool error whose message mentions regex (the ConventionValidationError → toolError path). Fixed in 3cafc4b.