docs: document generic harness loop

[joryirving]

Closes #400

[its-saffron]

AI Automated Review

Full PR review.

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

PR Review: PR 424 — docs: document generic harness loop

Recommendation

Approve. This PR adds a new documentation file that comprehensively documents the generic harness integration loop, perfectly satisfying all acceptance criteria from issue PR 400.

Change Summary

• New file: docs/generic-harness-loop.md (178 lines)
• Purpose: Document how any harness integrates with Dispatch without custom runtime scripts, second runtime repo, or OpenClaw-specific logic

Linked Issue Fit

The implementation aligns precisely with [issue PR 400](upstream misospace/dispatch issue 400) requirements:

Requirement	Verification
Docs harness-agnostic first	✅ Document opens with "how any harness integrates with Dispatch" and explicitly states "Any scheduler, CLI wrapper, or manual workflow that can make HTTP requests can use Dispatch."
Cover: ask for next task	✅ next-task endpoint documented in Endpoints table and used in both Worker and Groomer loops
Cover: exit on idle	✅ Task types table shows idle type with shouldRun: false; both loops check if not task["shouldRun"]: return
Cover: execute exactly one task	✅ Both loops execute one task then stop; Key Properties states "One task per run"
Cover: report result	✅ Report endpoint documented; Worker and Groomer loops both call /tasks/report
Cover: stop	✅ Both loops end immediately after reporting; Key Properties emphasizes "Stop"
Examples: generic curl/CLI	✅ Full shell example provided with idle check, task execution, and reporting
Examples: OpenClaw scheduler	✅ YAML schedule example with shouldRun check
Examples: OpenCode/manual	✅ Four-step numbered list for manual workflow
Examples: Codex/Claude Code one-shot	✅ One-shot example provided
Harness examples small and optional	✅ All examples are brief and clearly labeled as "Small Harness Examples"
No second runtime repo required	✅ Non-Goals section explicitly states "A second runtime repo is not required"
Worker and groomer loops documented separately	✅ Separate "Generic Worker Loop" and "Generic Groomer Loop" sections with distinct ?lane=normal vs ?mode=groom

Standards Compliance

• Generic patterns: Uses {agentName} placeholder and {name} in paths; no hardcoded agent names
• API correctness: Endpoints reference actual implementation files:
  • src/lib/agent-task.ts (task types)
  • src/app/api/agents/[agentName]/next-task/route.ts (next-task endpoint)
  • src/app/api/agents/[agentName]/tasks/report/route.ts (report endpoint)
• Documentation style: Consistent with existing docs in the docs/ directory
• Changelog format: History entry follows established pattern (- **2026-06-17** — Created...)

Evidence Provider Findings

No evidence providers are configured for this repository; no findings to report.

Tool Harness Findings

The tool harness executed 2 requests successfully. The evidence summary confirmed the linked issue context and verified the new documentation file contents. No discrepancies found.

CI Check Results

Both required checks passed:

• Docker Build: completed → success
• Validate: completed → success

Must-Check Items

The PR Classification specifies must_check: [] (empty). No mandatory review checklist items apply to this documentation-only change.

Unknowns / Needs Verification

None. The PR is a pure documentation addition with clear scope and no technical implementation changes requiring verification.