docs: enrich task/runtime contracts (DISPATCH_SPEC, DISPUTE, tasks/*) — part of #3

DISPATCH_SPEC.md

@@ -1,12 +1,14 @@
-# DISPATCH Specification
+# DISPATCH Specification v4
 
-The runtime uses a compact typed envelope:
+The system intentionally preserves the compatible typed envelope `DISPATCH v2`, using an explicit end marker `END_DISPATCH` inside task files.
+
+## Format
 
 ```text
 DISPATCH v2
 TASK: TASK-NNN
 GOAL: one-line goal
-CONSTRAINTS: no_credentials,requires_review
+CONSTRAINTS: comma-separated flags
 BUDGET_TOKENS: 4000
 ARTIFACTS:
   - path: /absolute/or/workspace/path
@@ -17,7 +19,7 @@ DEADLINE: YYYY-MM-DD
 END_DISPATCH
 ```
 
-Required fields:
+## Required Fields
 
 - `TASK`
 - `GOAL`
@@ -26,7 +28,7 @@ Required fields:
 - `REQUIRED_OUTPUT`
 - `DEADLINE`
 
-Useful constraints:
+## Useful Constraints
 
 - `no_network`
 - `readonly`
@@ -36,4 +38,63 @@ Useful constraints:
 - `max_files=N`
 - `timeout=Ns`
 
-Agents should reference artifact paths instead of embedding large file contents.
+## Output Contract
+
+### executor
+
+Success with audit request:
+
+```text
+SESSION_START agent=executor
+ATTEMPT_START task=TASK-001 agent=executor
+ARTIFACT_READY task=TASK-001 path=... sha256=...
+TASK-001 NEEDS_REVIEW: one-line summary
+ATTEMPT_END task=TASK-001 agent=executor status=needs_review
+```
+
+Direct completion without audit:
+
+```text
+SESSION_START agent=executor
+ATTEMPT_START task=TASK-001 agent=executor
+TASK-001 DONE: one-line summary
+ATTEMPT_END task=TASK-001 agent=executor status=done
+```
+
+Blocker:
+
+```text
+SESSION_START agent=executor
+ATTEMPT_START task=TASK-001 agent=executor
+TASK-001 BLOCKED: specific reason
+ATTEMPT_END task=TASK-001 agent=executor status=blocked
+```
+
+### auditor
+
+```text
+SESSION_START agent=auditor
+ATTEMPT_START task=TASK-001 agent=auditor
+TASK-001 AUDIT PASS
+ATTEMPT_END task=TASK-001 agent=auditor status=pass
+```
+
+or
+
+```text
+SESSION_START agent=auditor
+ATTEMPT_START task=TASK-001 agent=auditor
+TASK-001 AUDIT FAIL: specific criterion that failed
+ATTEMPT_END task=TASK-001 agent=auditor status=fail
+```
+
+## Envelope Size
+
+- recommended maximum: `4KB`
+- if larger: decompose the task or move context into artifacts
+
+## Artifact Rule
+
+File contents must not be embedded in the envelope if this can be avoided.
+
+Agents reference artifacts by path.

DISPUTE.md

@@ -1,11 +1,14 @@
-# DISPUTE Process
+# DISPUTE Process v4
+
+## When to Open a DISPUTE
 
 Open a formal dispute when there is a conceptual conflict:
 
-- docs contradict runtime behavior;
-- executor and auditor disagree on criteria;
-- target contract conflicts with observed target repo state;
-- two plausible process paths need a human/orchestrator decision.
+- between system documents;
+- between rules and actual runtime behavior;
+- between the executor's decision and the auditor's;
+- between the system and the target-project contract;
+- between two equally plausible paths where an arbiter is needed.
 
 Technical failure without conceptual conflict is `BLOCKED`, not a dispute.
 
@@ -25,14 +28,25 @@ INITIATOR: executor | auditor | orchestrator
 TOPIC: one-line summary
 
 ## Conflict
+...
 
 ## Position A
+...
 
 ## Position B
+...
 
 ## Evidence
+- file/path
+- file/path
 
 ## Resolution
+...
 ```
 
-Closed disputes must produce a follow-up artifact: docs update, task, issue, PR or roadmap entry.
+## Rules
+
+- a dispute without a file does not count as a dispute;
+- reopening a dispute on the same topic requires a new fact;
+- a closed DISPUTE must produce a follow-up artifact: a docs update, task, issue, PR, or roadmap entry;
+- the final arbiter is the orchestrator/human.

tasks/README.md

@@ -1,26 +1,67 @@
-# Tasks
+# Tasks v4
 
-Local task files live as `tasks/TASK-*.md` and are ignored by git by default.
+## Purpose
 
-Each task must include:
+A task file must be:
 
-- `STATUS`
-- `CREATED`
-- `AUTHOR`
-- `TARGET`
-- `Goal`
-- `Criteria`
-- `Context`
-- `Dispatch Envelope`
-- `Attempt Log`
-- `Audit Notes`
+- human-readable;
+- recoverable after failure;
+- convenient for coordinator parsing;
+- sufficient for the next agent without any hidden chat context.
 
-Statuses:
+## Naming
+
+- `TASK-001.md`
+- `TASK-002.md`
+- ...
+
+Template: `tasks/TASK_TEMPLATE.md`
+
+Local task files are ignored by git by default.
+
+## Required Metadata Lines
+
+The following lines must appear at the top of each task file:
+
+```text
+STATUS QUEUED
+CREATED 2026-04-23T10:00:00Z
+AUTHOR orchestrator
+TARGET none
+```
+
+The coordinator relies on the `STATUS ...` line.
+
+`TARGET` holds the name of the active target-pack, or `none`.
+
+## Statuses
 
 - `QUEUED`
 - `IN_PROGRESS`
 - `REVIEW`
 - `DONE`
 - `BLOCKED`
 
+## Dispatch Envelope
+
+Every task must contain an envelope between:
+
+- `DISPATCH v2`
+- `END_DISPATCH`
+
+This allows the runtime to extract a machine-readable dispatch without breaking the human-readable sections.
+
+## Recommended Sections
+
+- `## Goal`
+- `## Criteria`
+- `## Context`
+- `## Dispatch Envelope`
+- `## Attempt Log`
+- `## Audit Notes`
+
+## Continuity Rule
+
+If an audit fail, retry, or manual decision changes the context, that change must be recorded in the task file so that the next attempt does not depend on hidden chat history.
+
 If a task becomes important framework history, promote it to a GitHub issue or an explicit docs artifact.

tasks/TASK_TEMPLATE.md

@@ -7,7 +7,7 @@ TARGET none
 
 ## Goal
 
-<one paragraph>
+<one paragraph describing what must be accomplished>
 
 ## Criteria
 
@@ -16,10 +16,10 @@ TARGET none
 
 ## Context
 
-- Active repo:
-- Baseline repo:
-- Related docs:
-- Constraints:
+- Active repo:         <!-- target project being modified -->
+- Baseline repo:       <!-- reference repo, if any -->
+- Related docs:        <!-- relevant framework or project docs -->
+- Constraints:         <!-- e.g. no_network, readonly -->
 
 ## Dispatch Envelope