Add declare_loose_end to kcap mcp workitems

[realtonyyoung]

AI-2220

What & why

Agents already attach sessions to work items and declare their structure, but they have no way to say what they left unfinished, so the next-work ledger only learns about loose ends by mining what's-done prose and checklists after the fact. This adds declare_loose_end to kcap mcp workitems: one plain-text item per call, posted to the server's /api/loose-ends/declare against the session the server runs in (or an explicit session_id), plus the skill, README, help and preamble text that make an agent reach for it at the end of a session or plan step.

Where to look

The client checks shape only (text present, a string, not blank); the 12–500 character bound and the refusal of none-class text stay server-side so a coded 400 names the real reason. The server route ships in kcap-server separately and must land first: against a server without it the tool surfaces Error: HTTP 404 and nothing else changes. The skill's frontmatter previously told agents to stay away from single indivisible tasks, which is exactly what a loose end is, so its trigger now names unfinished work and the exclusion applies to declaring structure only.

Verification

dotnet run --project test/Capacitor.Cli.Tests.Unit -- --treenode-filter "/*/*/McpWorkItemsServerTests/*"
total: 49  failed: 0  (42 before this change)
dotnet build src/Capacitor.Cli/Capacitor.Cli.csproj   0 warnings, 0 errors
bash scripts/check-linear-ids.sh                      exit 0

🤖 Generated with Claude Code

[linear-code]

AI-2220

[qodo-code-review]

PR Summary by Qodo

Add loose-end declarations to the work-items MCP server

✨ Enhancement 🧪 Tests 📝 Documentation 🕐 20-40 Minutes

AI Description

• Adds declare_loose_end to record unfinished session work in the next-work ledger.
• Reuses ambient session resolution while leaving content-policy validation to the server.
• Updates agent guidance, help, documentation, and unit coverage for the new tool.

Diagram

sequenceDiagram
    actor Agent
    participant MCP as Workitems MCP
    participant Session as Session Context
    participant API as Loose Ends API
    participant Ledger as Next-work Ledger
    Agent->>MCP: declare_loose_end
    MCP->>Session: Resolve session
    Session-->>MCP: Session ID
    MCP->>API: POST text and session
    API->>API: Validate content
    API->>Ledger: Record loose end
    Ledger-->>API: Creation result
    API-->>MCP: HTTP response
    MCP-->>Agent: Tool result

Loading

High-Level Assessment

The thin MCP adapter is the appropriate approach: it reuses established session resolution and HTTP error handling while keeping mutable semantic rules on the server, preventing client/server validation drift. Client-side policy validation or conditional tool registration for older servers would duplicate ownership or require new capability negotiation; surfacing HTTP 404 until the server route lands is simpler and leaves existing tools unaffected.

Files changed (7) +128 / -15

Enhancement (1) +16 / -1

McpWorkItemsServer.csImplement declare_loose_end MCP dispatch +16/-1

Implement declare_loose_end MCP dispatch

• Registers the new MCP tool and posts its resolved 'session_id' and required nonblank 'text' to '/api/loose-ends/declare'. Updates server instructions to prompt agents to declare each concrete unfinished item while leaving length and none-class validation to the server.

src/Capacitor.Cli/Commands/McpWorkItemsServer.cs

Tests (1) +59 / -1

McpWorkItemsServerTests.csCover loose-end schema, validation, guidance, and dispatch +59/-1

Cover loose-end schema, validation, guidance, and dispatch

• Adds tests for tool discovery, required arguments, body construction, blank or malformed input handling, session resolution, instructional text, and the exact POST route and payload.

test/Capacitor.Cli.Tests.Unit/Commands/McpWorkItemsServerTests.cs

Documentation (5) +53 / -13

README.mdDocument loose-end declarations in the work-items MCP server +4/-3

Document loose-end declarations in the work-items MCP server

• Expands the work-items overview and tool reference to describe 'declare_loose_end', its idempotency, server-side refusal rules, and ambient session behavior. Updates the advertised tool count from nine to ten.

README.md

CHANGES.mdRecord the loose-end client and server validation boundary +15/-0

Record the loose-end client and server validation boundary

• Adds a change note explaining request shape validation, server-owned content rules, session resolution, deployment ordering, and expected HTTP 404 behavior when the server route is unavailable.

docs/CHANGES.md

README.mdInclude loose ends in the work-items skill summary +1/-1

Include loose ends in the work-items skill summary

• Updates the bundled skills overview to state that the work-items skill can record unfinished session work.

kcap/README.md

SKILL.mdTeach agents when and how to declare loose ends +21/-5

Teach agents when and how to declare loose ends

• Broadens the skill trigger to include unfinished work at session or plan-step boundaries. Adds usage guidance, server constraints, idempotency behavior, and the new tool to the reference table while preserving structure-specific exclusions.

kcap/skills/work-items/SKILL.md

help-mcp.txtExpose declare_loose_end in CLI help +12/-4

Expose declare_loose_end in CLI help

• Updates work-items MCP help to advertise ten tools, describe loose-end recording, and include previously omitted merge and detach tool entries.

src/Capacitor.Cli.Core/Resources/help-mcp.txt

[qodo-code-review]

Code Review by Qodo

🐞 Bugs (0) 📘 Rule violations (0) 🔗 Cross-repo conflicts (0) 📜 Skill insights (0)

1. A test comment misstates discovery ⊘ Outdated 📘 Rule violation ⚙ Maintainability

Description

Server_instructions_steer_unfinished_work_to_declare_loose_end says the preamble is the only way
an agent that skips the skill learns about the tool, but BuildToolsList also exposes and describes
it. A later change guided by this rationale can preserve redundant preamble text while overlooking
the tool-list discovery path.

Code

test/Capacitor.Cli.Tests.Unit/Commands/McpWorkItemsServerTests.cs[R210-211]

+        // The preamble is the only place an agent that never opens the work-items skill learns the
+        // tool exists, so a loose end left undeclared is the failure it has to prevent.

Relevance

●●● Strong

Accepted history favors correcting inaccurate or over-specific test comments documenting behavior
and discovery paths.

PR-#539
PR-#667

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

Compliance rule 2762993 requires comments to remain true and document a non-obvious current
constraint. The added test comment claims exclusive discovery through the preamble, while the added
BuildToolsList entry independently exposes the tool name and its usage description.

Rule 2762993: Restrict comments to documenting non-obvious, behavior‑critical constraints
test/Capacitor.Cli.Tests.Unit/Commands/McpWorkItemsServerTests.cs[210-211]
src/Capacitor.Cli/Commands/McpWorkItemsServer.cs[403-406]

Agent prompt

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

## Issue description
The test comment incorrectly claims that the server preamble is the only discovery path for agents that do not open the work-items skill, even though the MCP tool list also exposes and describes `declare_loose_end`.

## Fix Focus Areas
- test/Capacitor.Cli.Tests.Unit/Commands/McpWorkItemsServerTests.cs[210-211]

## Recommended Fix
Rewrite the comment to explain that the preamble proactively directs agents to use `declare_loose_end`, rather than claiming it is the only way they can discover the tool.

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

---

Context sources

✅ Compliance rules (platform): 64 rules

✅ Cross-repo context — repo relationships

  Explored: repo: kurrent-io/kcap-server (sha: 63ae1b7b)

Review mode: ⚖️ Balanced: This adds a new runtime MCP tool and HTTP route integration with session resolution, validation, user-facing contracts, and tests; it has meaningful behavioral risk but is localized enough for a careful single-pass review.

Tip of the day

💡 Did you know, you can group findings by type and pick your Finding display, from Minimal to Full

More tips ↗ | Customize Qodo ↗ | Qodo docs ↗