docs: reconcile agent workflow contract

[joryirving]

Closes #412

Changes

Reconciled the agent-facing workflow docs with current Dispatch endpoints and AgentTask contract.

AGENTS.md

• Replaced legacy "OpenClaw Agent Workflow Contract" section with "Agent Workflow Contract"
• Documents the canonical one-task worker loop: sync → next-task → execute → report → stop
• Documents auth requirements (bearer token via DISPATCH_AGENT_TOKEN)
• Documents task types (idle, implement, followup-pr, groom) and report outcomes
• Documents worker boundaries (no merge, no groom unless taskType is groom, one task per heartbeat)
• Added Legacy APIs section demoting sync, agent-runs, GET /api/issues, and queue endpoints

docs/generic-harness-loop.md

• Added bearer auth headers to all code examples (Python, curl, OpenClaw, Codex)

docs/worker-execution-contract.md

• Updated Linking section to reference current docs
• Added "Relationship to next-task" section explaining how next-task handles PR-fix precedence automatically

docs/harness-idle-first.md

• Added SUPERSEDED notice (content consolidated into generic-harness-loop.md)

docs/agent-workflow.md

• Added SUPERSEDED notice (legacy claim/unclaim workflow replaced by next-task)

Verification

• npm run lint ✓
• npm run typecheck ✓
• npm run test ✓ (72 files, 1341 tests)
• npm run build ✓

[its-saffron]

AI Automated Review (incremental)

Incremental review: reviewed the changes since the last managed review; unresolved findings from that review are carried forward.

Analysis engine: MiniMax-M2.7@https://litellm.jory.dev/v1 (anthropic) — routed smart (risk match: path_handling_changes)

Review Summary

Recommendation: Approve

This PR is a documentation-only change that reconciles agent-facing workflow docs with the current Dispatch API endpoints. The changes are accurate, internally consistent, and follow repository conventions.

Change-by-Change Findings

AGENTS.md

• Removed mandatory sync from heartbeat loop: The preflight sync is now correctly labeled "optional preflight sync" — this aligns with the actual implementation where next-task is the primary entry point and sync is best-effort.
• Updated failure modes: Clarified that next-task and tasks/report failures should stop the worker (not fail silently), while sync failures remain warnings. This is a meaningful clarification for worker authors.
• Updated Legacy APIs section: Correctly marks sync as "optional" rather than a required heartbeat step.
• Bearer token auth: Code examples properly show auth headers being constructed once and reused.

docs/generic-harness-loop.md

• Removed redundant sync blocks from code examples, adding the "optional preflight sync" note instead.
• Updated the generic harness guidelines to reflect the correct sync semantics.

Standards Compliance

• ✅ No agent-specific names in generic docs: Uses agent/* patterns, not specific agent names
• ✅ Auth requirements documented correctly: Bearer token via DISPATCH_AGENT_TOKEN shown in code examples
• ✅ Token handling guidance: "Never log" guidance present for secrets
• ✅ API routes return appropriate status codes: N/A (documentation only)
• ✅ Error handling patterns: Failure modes section accurately describes expected behavior

Linked Issue Fit

This PR closes issue PR 412 by reconciling the agent workflow documentation. The changes accurately reflect:

• The canonical one-task worker loop (sync → next-task → execute → report → stop)
• Auth requirements (DISPATCH_AGENT_TOKEN bearer auth)
• Task types and report outcomes
• Worker boundaries
• Legacy API deprecation

Required Checks — Path Handling

Path Traversal Vulnerabilities Review

Status: Not applicable — This is a documentation-only PR. No file system operations, path concatenation, user input handling, or file-serving code is modified. The changes consist entirely of markdown documentation and Python code examples demonstrating HTTP API calls.

Edge-Case Path Testing (null bytes, symlinks)

Status: Not applicable — No path handling code exists in this diff. The path_handling_changes classification appears to be a false positive for this documentation-only PR. No file paths are constructed, joined, or processed.

Unknowns / Needs Verification

None. The diff is self-contained documentation. No tool fetches or additional investigation needed.

Verification

• CI: Docker Build ✅, Validate ✅ (72 files, 1341 tests passed per PR body)
• No code changes — lint/typecheck not relevant to this diff
• No image digest changes
• No evidence providers or tool harness concerns