Skip to main content

Receipts

A receipt is a durable artifact written when a task transitions. The canonical writers are scripts/goal-runner/receipt_writer.py and the adapter invoke methods.

Where receipts live​

<worktree>/.goal-runner/receipts/
├── <task_id>-<session_id>.yaml          # task receipt
├── <task_id>-<session_id>.stdout.log    # captured stdout
├── <task_id>-<session_id>.stderr.log    # captured stderr
└── …

Per-goal evidence lives under evidence/<GOAL_ID>/ and is Git-tracked.

Receipt schema​

A task receipt contains:

adapter: <adapter-name>
role: <role>
task_id: <task-id>
session_id: <session-uuid>
outcome: PASS | FAIL | TIMEOUT | BLOCKED | REPAIR_REQUIRED
notes: <text>
created_at: <UTC ISO-8601>

An adapter result is the in-process object; the receipt is the persisted form. The orchestrator only treats a task as terminal when the adapter outcome is PASS and the corresponding task receipt has been verified.

Evidence​

Evidence is any Git-tracked file in evidence/<GOAL_ID>/ that proves an assertion. Common evidence files:

  • canonical_sources_read.yaml — proves the role read the canonical sources.
  • module_inventory.yaml — proves a planning inventory.
  • gap_classification_report.md — proves a planning gap analysis.
  • pr_<N>_review_evidence.json — proves a PR review was ingested.
  • governed_commit_log.txt — proves the governed commit landed.
  • ci_status_log.txt — proves CI passed.
  • merge_approval_gate.yaml — proves the merge gate was materialized at the exact head.
  • deployment_health.txt — proves the deployment succeeded.

Failure mode​

A receipt with outcome: FAIL does not by itself block a goal — the orchestrator re-dispatches according to next_action_policy.on_fail. The REPAIR_REQUIRED outcome is special: it triggers the bounded repair path, which requires a separate REPAIR_GOAL and a separate gate.