feat: add harness-agnostic AgentTask contract

[joryirving]

Addresses #393.

What

Adds a code-level, harness-agnostic AgentTask discriminated union that defines the shape of work Dispatch assigns to any agent harness (OpenClaw, Hermes, Claude Code, Codex, OpenCode, or manual scripts).

Task Types

• idle — no work available (shouldRun: false)
• implement — claim or work an issue, open/update one PR, then stop
• followup-pr — fix an existing PR with queued feedback, then stop
• groom — enrich issues with labels, lane classification, and status; close completed work

Helper Builders

• createIdleTask(reason)
• createImplementTask(input)
• createFollowupPrTask(input)
• createGroomTask(input)

Each builder applies strict default instructions and forbidden actions (no merging PRs, no claiming multiple issues, etc.) that can be overridden per-call.

Does Not

• Add API routes (foundation for future /next-task endpoint)
• Change queue behavior
• Touch OpenClaw or workflow repos
• Add database migrations

Validation

• npm run lint ✅
• npm run typecheck ✅
• npm run test — 42/42 ✅
• npm run build ✅

[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 402: feat: add harness-agnostic AgentTask contract

Summary

This PR adds a harness-agnostic AgentTask discriminated union to src/lib/agent-task.ts with comprehensive test coverage in src/lib/agent-task.test.ts. The implementation defines four task types (idle, implement, followup-pr, groom) as TypeScript interfaces and provides factory functions for each.

Change-by-Change Analysis

src/lib/agent-task.ts (new file, 173 lines)

• Interface definitions: Defines IssueRef, OptionalIssueRef, PullRequestRef reference types, plus IdleTask, ImplementTask, FollowupPrTask, GroomTask interfaces, and the AgentTask discriminated union.
• Factory functions: createIdleTask, createImplementTask, createFollowupPrTask, createGroomTask with configurable instructions, stopAfter conditions, and forbiddenActions.
• Mutation safety: Correctly spreads arrays ([...input.forbiddenActions], [...IMPLEMENT_FORBIDDEN]) to prevent mutation leakage between tasks — verified in test suite.
• Type safety: Uses discriminated union on type field; shouldRun is a literal false for idle tasks.

src/lib/agent-task.test.ts (new file, 354 lines)

• Comprehensive coverage: Tests all four factory functions, discriminated union type narrowing, and mutation isolation.
• Mutation isolation tests: Explicitly verify that mutating one task's forbiddenActions does not affect another task (both from default arrays and custom inputs).
• Edge cases covered: Optional fields (lane, issue) tested for presence/absence; custom overrides tested for instructions, stopAfter, and forbiddenActions.

Standards Compliance

Standard	Status
TypeScript conventions	✅ Pass
Error handling pattern	✅ N/A (pure data transformation)
No commit of secrets	✅ Pass
Input validation	✅ Defaults provided; optional overrides respected
API route patterns	✅ N/A (library only; PR explicitly does not add routes)

Linked Issue Fit

The PR body states it addresses misospace/dispatch#393. The git log confirms commit 2d848cb feat: add harness-agnostic AgentTask contract (#393) is present in the repository history. The implementation matches the PR description:

• ✅ Adds code-level AgentTask discriminated union
• ✅ Defines four task types (idle, implement, followup-pr, groom)
• ✅ Provides helper builders with strict defaults and override capability
• ✅ Does NOT add API routes (explicitly scoped as foundation only)
• ✅ Does NOT change queue behavior
• ✅ No database migrations

Evidence Provider Findings

No evidence providers configured for this PR.

Tool Harness Findings

The tool harness successfully read both files and confirmed their content matches the PR diff. GitHub API lookups returned 404 (expected for new files on a feature branch). No discrepancies found between tool output and diff.

CI Check Results

Check	Status
Validate	✅ success
Docker Build	✅ success

The PR body states npm run lint, npm run typecheck, npm run test (42/42), and npm run build all pass. CI confirms the build pipeline succeeded.

Unknowns / Needs Verification

None identified. All assertions verified against corpus.

Recommendation

Approve. The implementation is a clean, well-typed foundation for a future /next-task endpoint. Type safety is maintained, mutation isolation is properly handled, and test coverage is thorough. No blockers.