docs: add next-task smoke checks

[itsmiso-ai]

Closes #422

[its-saffron]

AI Automated Review

Full PR review.

Analysis engine: MiniMax-M2.7@https://litellm.jory.dev/v1 (anthropic) — escalated (fast_low_confidence)

PR PR 437 Review: docs: add next-task smoke checks

Summary

This PR closes issue PR 422 by adding three new smoke checks to docs/smoke-checklist.md (checks PR 15–17) that exercise the next-task endpoint's authenticated happy path, idle path, and groom mode. It also introduces a new comprehensive documentation file (docs/configurable-lanes.md) explaining execution lane configuration, and adds a startup warning in the MCP server for unset DISPATCH_AGENT_NAME.

Change-by-Change Findings

1. README.md (+4 lines)

• Adds an "Execution Lanes" section referencing the new docs/configurable-lanes.md. Correctly cross-links to the new doc.

2. docs/configurable-lanes.md (+324 lines, new file)

• Comprehensive documentation of custom lane configuration covering default setup, field definitions, lane roles, migration aliases, environment variable setup, and API reference.
• Clearly distinguishes execution lanes from status labels (important: lanes control agent queue behavior, status labels control Kanban board columns).
• Includes safe migration examples with read-time aliasing.
• Cross-references sister docs appropriately (issue-lane-classification.md, worker-execution-contract.md).

3. docs/issue-lane-classification.md (+2 lines)

• Adds cross-reference to the new configurable-lanes doc. Minor, correct addition.

4. docs/smoke-checklist.md (+90/-1 lines)

• Updated check count from 14 to 17.
• Check PR 15 (happy path): Documents authenticated GET /api/agents/<agent>/next-task?lane=normal with expected shouldRun: true, type: "implement", and full issue shape. Prerequisites clearly state bearer auth and synced ready issues are required.
• Check PR 16 (idle path): Documents the idle response (shouldRun: false, type: "idle") when no work exists. Includes step-by-step test methodology: confirm PR 15 passes, then close/resolve issues, re-run, expect idle.
• Check PR 17 (groom mode): Documents mode=groom returning type: "groom" task shape for backlog/untriaged issues.
• Adds failure signals for 401 (auth) and unexpected idle conditions.
• Adds runbook entries for next-task-specific failures.
• Updates history to cite issue PR 422.

5. src/mcp/server.ts (+17 lines)

• New exported function warnIfAgentNameUnset() that logs a warning if DISPATCH_AGENT_NAME is unset.
• Called at startup in main(), providing runtime feedback mirroring the DISPATCH_AUTH_MODE=disabled warning pattern documented in docker-entrypoint.sh.
• Non-blocking: this is a heads-up only, as tools can still pass explicit agentName.

6. src/mcp/server.test.ts (+31 lines)

• Two test cases for warnIfAgentNameUnset(): confirms warning emits when env var is unset, confirms no warning when set.
• Tests use standard vitest mocking pattern (vi.spyOn(console, 'warn')).

Linked Issue Fit

Issue PR 422 requested:

"Add a smoke check to docs/smoke-checklist.md that exercises the next-task end-to-end happy path and an idle path"

The PR satisfies this exactly:

• ✅ Check PR 15 covers the authenticated happy path (shouldRun: true, type: "implement")
• ✅ Check PR 16 covers the idle path (shouldRun: false, type: "idle")
• ✅ Check PR 17 additionally covers mode=groom (mentioned in issue body as a gap)

The issue body noted that ?includeClaimed=true / ?includeRenovate=true query parameters also lack test coverage. These are advanced queue-filtering options not covered by this PR; they could be tracked separately if desired, but the primary ask is addressed.

Standards Compliance

Per AGENTS.md conventions:

• ✅ No agent-specific names in generic docs — all checks use generic agent/<name> patterns
• ✅ Error handling uses error instanceof Error pattern (in MCP server handlers)
• ✅ API routes return appropriate HTTP status codes (documented in smoke checks)
• ✅ No commit of secrets — no env files or credentials introduced

Evidence Provider Findings

No evidence providers were configured for this review.

Tool Harness Findings

Four file reads were performed to verify MCP server implementation:

• src/mcp/server.ts — confirmed warnIfAgentNameUnset export and implementation
• src/mcp/server.test.ts — confirmed test structure and import of new function

Both read outputs confirm the diff is accurate and implementation is internally consistent.

Unknowns / Needs Verification

• Query parameter smoke coverage: The ?includeClaimed=true and ?includeRenovate=true parameters noted in issue PR 422's evidence are not covered by the new smoke checks. This is a minor gap; the primary ask (happy path, idle, groom mode) is fully addressed.
• No breaking changes: This is a documentation-first PR with a non-breaking MCP enhancement. No API contracts are changed.

Recommendation

Approve. This PR correctly implements the smoke check additions requested in issue PR 422, adds valuable documentation on configurable lanes, and includes a helpful MCP startup warning. CI passed (Docker Build, Validate). The implementation is consistent with repository conventions and introduces no breaking changes.