[AI-1914] Register kcap-workitems on every harness

[realtonyyoung]

What

kcap-workitems was registered only for Claude Code. Every other harness (Codex, Cursor, Copilot, Gemini, Kiro, OpenCode, Antigravity, Pi) received a 5-server subset that stripped it — so those agents could not declare_work_item, nor declare the breakdown / blocks/blocked_by dependency topology (AI-1683/AI-1718).

The "Claude-only" rationale was stale: McpWorkItemsServer.ResolveSessionId resolves an explicit session_id arg (wins), else KCAP_SESSION_ID, else CODEX_THREAD_ID, else throws a clear error; the breakdown/relation tools need no session id at all.

Changes

• KcapMcpServers.ForCodex / ForCursor now return the full All set (kept as named per-harness seams for future divergence).
• Add kcap-workitems to the bundled kcap/.codex-mcp.json.
• Add "workitems" to the Pi MCP-bridge extension's KCAP_MCP_SERVERS (Pi's analytics gap was already closed on main; workitems was the only remaining one).
• Refresh the stale "Claude-only" comments in HarnessMcpProjections and SetupCommand.

Invariants preserved (and tested)

• Never auto-trusted — kcap-workitems is not ReadOnly, so it keeps prompting everywhere. Asserted against Gemini's per-server trust (kcap-workitems trust is null).
• Unattended-reviewer safe — it stays out of KcapMcpRegistry.ReviewFlowAutoApprovableServers ({review, sessions}); a reviewer allowlist naming kcap-workitems fails the launch. New test in KcapMcpRegistryReviewFlowTests.
• No server/protocol change.

Tests

Inverted the subset-exclusion assertions in KcapMcpServersTests and McpCanonicalContractTests; added kcap-workitems to the Cursor/Gemini/Pi expectations; added the trust + unattended-reviewer-rejection assertions above. Touched test classes pass locally (52 green); the only local reds are the pre-existing macOS-only Codex-config-temp-symlink baseline, which passes on Linux CI.

Spec + codex spec-review (clean, 5 rounds) recorded on the Linear issue.

Ships in the same release as AI-1915 (the SessionStart work-items nudge).

Fixes AI-1914

[linear-code]

AI-1914

[qodo-code-review]

PR Summary by Qodo

Register kcap-workitems MCP server across all harnesses

🐞 Bug fix ✨ Enhancement 🧪 Tests ⚙️ Configuration changes 🕐 20-40 Minutes

AI Description

• Register kcap-workitems for Codex/Cursor and all JSON harness projections.
• Bundle kcap-workitems into Codex and Pi MCP configs.
• Add contract tests for trust and unattended review-flow rejection invariants.

Diagram

graph TD
  A["KcapMcpServers"] --> B["HarnessMcpProjections"] --> C["Json MCP configs"]
  A --> D["Codex MCP bundle"]
  A --> E["Pi MCP bridge"]
  F["SetupCommand"] --> B --> C
  F --> E
  C --> G["kcap mcp workitems"]
  D --> G
  E --> G

Loading

High-Level Assessment

The following are alternative approaches to this PR:

1. Keep explicit per-harness subsets (but include workitems)

• ➕ Maintains clear, reviewable per-harness deltas if divergence is expected soon
• ➕ Avoids risk of accidentally broadening server sets when adding new servers later
• ➖ Duplicates policy in multiple places and makes it easier to regress parity again
• ➖ Requires updating multiple subsets/tests for every new server

2. Policy-driven projection (derive subsets from server metadata)

• ➕ Centralizes inclusion/exclusion rules (e.g., read-only vs writer, needs CWD, trust behavior)
• ➕ Scales better as more harnesses/servers are added
• ➖ More abstraction than needed right now; policy rules can become opaque
• ➖ Still needs harness-specific exceptions for shape/marker differences

Recommendation: The PR’s approach (make ForCodex/ForCursor equal to All, while keeping named seams) is the best tradeoff: it restores cross-harness parity immediately, reduces duplication, and preserves a future extension point for harness-specific divergence. The added tests around trust and unattended review-flow allowlisting appropriately lock in the safety invariants as the server set broadens.

Files changed (11) +47 / -25

Enhancement (2) +10 / -9

KcapMcpServers.csInclude workitems in Codex/Cursor server sets +9/-8

Include workitems in Codex/Cursor server sets

• Changes 'ForCodex' and 'ForCursor' to return the full 'All' server list (including 'kcap-workitems') while keeping per-harness accessors as future seams.

src/Capacitor.Cli.Core/Mcp/KcapMcpServers.cs

PiMcpExtensionInstaller.csAdd workitems to Pi MCP bridge server list +1/-1

Add workitems to Pi MCP bridge server list

• Extends the embedded Pi MCP-bridge extension to spawn/register the 'workitems' server alongside the existing kcap server set.

src/Capacitor.Cli.Core/Pi/PiMcpExtensionInstaller.cs

Tests (6) +28 / -12

KcapMcpRegistryReviewFlowTests.csAssert review-flow allowlist rejects kcap-workitems +10/-0

Assert review-flow allowlist rejects kcap-workitems

• Adds a unit test ensuring an unattended review-flow reviewer cannot allowlist 'kcap-workitems', preserving the auto-approval safety boundary.

test/Capacitor.Cli.Tests.Unit/KcapMcpRegistryReviewFlowTests.cs

KcapMcpServersTests.csUpdate subset tests to expect workitems included +6/-4

Update subset tests to expect workitems included

• Reworks Codex and Cursor subset tests to assert both subsets now equal the full canonical server set including 'kcap-workitems'.

test/Capacitor.Cli.Tests.Unit/Mcp/KcapMcpServersTests.cs

McpCanonicalContractTests.csUpdate canonical contract to include workitems in subsets +6/-4

Update canonical contract to include workitems in subsets

• Updates contract assertions to verify both Codex and Cursor projections include 'kcap-workitems' while retaining other required servers.

test/Capacitor.Cli.Tests.Unit/Mcp/McpCanonicalContractTests.cs

PiMcpExtensionInstallerTests.csExpect Pi bridge content to include workitems +2/-2

Expect Pi bridge content to include workitems

• Updates the embedded bridge shape test to require 'workitems' in the 'KCAP_MCP_SERVERS' list.

test/Capacitor.Cli.Tests.Unit/PiMcpExtensionInstallerTests.cs

PluginCommandCursorTests.csCursor plugin install now expects kcap-workitems registered +2/-2

Cursor plugin install now expects kcap-workitems registered

• Adjusts Cursor plugin registration test to assert 'kcap-workitems' is present in the generated config.

test/Capacitor.Cli.Tests.Unit/PluginCommandCursorTests.cs

PluginCommandGeminiTests.csAssert Gemini registers workitems but does not auto-trust it +2/-0

Assert Gemini registers workitems but does not auto-trust it

• Adds an assertion that Gemini includes 'kcap-workitems' while leaving its per-server 'trust' unset (null), preserving the “never auto-trusted” invariant for writer servers.

test/Capacitor.Cli.Tests.Unit/PluginCommandGeminiTests.cs

Documentation (2) +5 / -4

HarnessMcpProjections.csUpdate harness projection comment to reflect workitems inclusion +2/-2

Update harness projection comment to reflect workitems inclusion

• Refreshes stale documentation describing the non-Claude JSON harness subset, clarifying that the subset is now the full set including 'kcap-workitems'.

src/Capacitor.Cli.Core/Mcp/HarnessMcpProjections.cs

SetupCommand.csRefresh setup comments about non-Claude harness MCP registration +3/-2

Refresh setup comments about non-Claude harness MCP registration

• Updates inline setup documentation to match the new reality that non-Claude JSON harnesses register the full server set including 'kcap-workitems', with session-id resolution notes.

src/Capacitor.Cli/Commands/SetupCommand.cs

Other (1) +4 / -0

.codex-mcp.jsonBundle kcap-workitems in Codex MCP config +4/-0

Bundle kcap-workitems in Codex MCP config

• Adds a 'kcap-workitems' entry to the bundled Codex MCP server JSON so Codex installs include the workitems server by default.

kcap/.codex-mcp.json

[qodo-code-review]

Code Review by Qodo

🐞 Bugs (0) 📘 Rule violations (0) 📎 Requirement gaps (0) 🎨 UX issues (0) 🔗 Cross-repo conflicts (0) 📜 Skill insights (0)

1. SetupCommand comment too verbose ✓ Resolved 📘 Rule violation ⚙ Maintainability

Description

The updated RegisterCursorMcp comment block repeats implementation details (specific env var
precedence and tool behavior) that are better captured in code/tests, reducing maintainability. This
conflicts with the guideline to keep comments concise and rely on self-explanatory structure/naming.

Code

src/Capacitor.Cli/Commands/SetupCommand.cs[R341-343]

+            // every non-Claude JSON harness registers the ForCursor subset — the full set,
+            // kcap-workitems included (session id resolves from an explicit arg /
+            // KCAP_SESSION_ID / CODEX_THREAD_ID; breakdown/relation tools need no session id).

Evidence

PR Compliance ID 7 asks that new/modified comments remain concise and that readability comes
primarily from code structure and naming. The changed block in SetupCommand adds detailed
behavioral notes (env var names and tool-level behavior), which is an example of the verbose-comment
pattern this rule aims to prevent.

CLAUDE.md: Prefer Self-Explanatory Code Over Verbose Comments
src/Capacitor.Cli/Commands/SetupCommand.cs[341-343]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
A newly-expanded comment block in `SetupCommand` is verbose and repeats low-level implementation details (env-var precedence, which tools need a session id) rather than expressing a concise intent.

## Issue Context
Compliance rule prefers self-explanatory code and concise comments; this comment is in a central installer path and is likely to drift from behavior over time.

## Fix Focus Areas
- src/Capacitor.Cli/Commands/SetupCommand.cs[341-343]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

Tip of the day

💡 Did you know, you can enable the Remediation agent and Qodo fixes findings in a dedicated fix PR

More tips ↗ | Customize Qodo ↗ | Qodo docs ↗