6.2 KiB
spec, created, status
| spec | created | status |
|---|---|---|
| docs/specs/tasks/requirements/workflow-explicit-completion-signal.md | 2026-07-22 | implemented |
Implementation Plan: Kanban Completion Tool Reliability
Overview
Harden the existing step_complete_kandev control signal for Kanban sessions without changing its workflow semantics or exposing it to Office. First lock the mode and metadata contract with regression tests, then clarify canonical versus client-qualified names and verify new/load/reconnect configuration paths. The unknown upstream disconnect trigger is not a license for speculative transport changes.
Backend
Task-only discoverable tool contract
Files:
apps/backend/internal/mcp/server/server.goapps/backend/internal/mcp/server/server_test.go
Changes:
- Keep
step_complete_kandevon the standard MCP definition withoutanthropic/alwaysLoador other vendor-specific eager-load metadata. - Keep registration exclusively inside the
ModeTaskbranch. - Test discovery through the task-mode catalog and absence from Office/config/external modes.
Client-neutral naming guidance
Files:
apps/backend/config/prompts/kandev-context.mdapps/backend/internal/sysprompt/sysprompt_test.goapps/backend/internal/mcp/server/sysprompt_sync_test.godocs/public/automation-and-mcp.mddocs/public/agent-communication.md
Changes:
- Describe listed names as canonical MCP protocol names and note that a client may display a server-qualified runtime alias.
- Keep the
step_complete_kandevinstruction conditional onauto_advance_requires_signal. - Do not instruct every client to call Claude's qualified alias directly; the registered tool schema remains authoritative.
- Document that the signal is task-mode only and may require the client's normal tool-search flow. If transport recovery fails, the task stays put for retry or a normal human workflow move.
Claude ACP session wiring
Files:
apps/backend/internal/agentctl/server/api/agent_test.goapps/backend/internal/agentctl/server/adapter/transport/acp/mcp_test.goapps/backend/internal/agentctl/server/adapter/transport/acp/adapter_session_test.go
Changes:
- Preserve the existing unversioned Claude ACP package selection and adapter initialization logging of bridge name/version.
- Assert the local Kandev MCP server is supplied on both
session/newandsession/load, with HTTP preferred and SSE retained as fallback. - Add a reconnect-shaped contract test: initialize task mode, list the completion tool, load the session with the same MCP config, then list/call it again.
- If the test cannot reproduce an actual catalog loss, do not add retry loops or server re-registration. Retain ACP/MCP logging instructions for the next field capture.
Frontend
No frontend change. ADR 0015's planned manual completion fallback is not currently implemented and remains outside this reliability fix.
Tests
- What: task-mode
tools/listincludes discoverablestep_complete_kandevwithout vendor-specific eager metadata; every restricted mode excludes it. File:apps/backend/internal/mcp/server/server_test.goHow: mode table plus JSON serialization of the registered tool. - What: workflow flag controls prompt advertisement but never tool registration.
File:
apps/backend/internal/sysprompt/sysprompt_test.go,apps/backend/internal/mcp/server/sysprompt_sync_test.goHow: format contexts with the flag both ways and compare against mode inventories. - What: both ACP new and load requests receive the local Kandev MCP server and preserve HTTP/SSE selection.
File:
apps/backend/internal/agentctl/server/adapter/transport/acp/adapter_session_test.go,apps/backend/internal/agentctl/server/api/agent_test.goHow: fake ACP connection request capture. - What: reconnect-shaped MCP reinitialization still lists and calls the task-only completion tool.
File:
apps/backend/internal/mcp/server/server_test.goor a focused sibling integration test. How: use the streamable HTTP test server; avoid a live model dependency. - What: a signal-gated Kanban step profile selects a runner without selecting Office mode.
File:
apps/backend/internal/orchestrator/task_operations_test.goHow: persist the workspace, workflow, step, task, and session in SQLite; assert the runner and Office projections independently, then launch the created session and verify task-mode discovery guidance.
E2E Tests
No browser behavior changes. A live-provider test is not required in CI. The QA packet records an optional acp-debug probe against the currently resolved bridge when credentials and network are available.
Implementation Waves
Wave 1:
Wave 2 (parallel after the Office prompt-context task has landed):
Wave 3:
Verification Commands
rtk make -C apps/backend fmt
cd apps/backend && rtk go test ./internal/mcp/server ./internal/sysprompt
cd apps/backend && rtk go test ./internal/agent/agents ./internal/agentctl/server/api ./internal/agentctl/server/adapter/transport/acp
rtk make -C apps/backend lint
rtk make -C apps/backend test
node --test scripts/validate-public-docs.test.mjs
node scripts/validate-public-docs.mjs
Risks
- Deferred tool discovery is client behavior. Agents must use the active client's search mechanism, and a disconnected MCP transport can still make the tool temporarily unavailable.
- The affected field run lacked ACP/MCP logs, so the precise disconnect trigger remains unproven. Production transport behavior must not be changed without a red reproduction or new trace evidence.
- The unversioned Claude ACP dependency can change independently of a Kandev release, so field reports must include the bridge-reported version.
Open Questions
None for this pass. The plan deliberately limits remediation to task-mode registration, truthful discovery guidance, and existing reconnect wiring; it does not add eager-load metadata or change Claude ACP package resolution.