Skip to content

per-task-loop.md

Latest commit

 

History

History
121 lines (95 loc) · 5.88 KB

per-task-loop.md

File metadata and controls

121 lines (95 loc) · 5.88 KB
Raw

The per-task loop

Whichever way your roadmap came into being, every task is worked the same way. This page is the single description of that loop — other docs link here instead of repeating it. New to the vocabulary? See the glossary.

The lifecycle

A task moves through states that code-pact derives from the append-only progress ledger. With no events yet, a task is planned.

stateDiagram-v2
    [*] --> planned
    planned --> started: task start
    started --> done: task complete
    started --> blocked: task block
    blocked --> resumed: task resume
    resumed --> done: task complete
    started --> failed: failure
    failed --> started: task start
    done --> [*]
Loading

task complete records done only after the phase's verification command passes. task finalize happens after done and is a separate surface — it flips the task's design status (intent) to match the operational fact; it does not add a progress event.

Full set of allowed transitions (the deterministic state machine):

From Can move to Via
planned started task start
started done / blocked / failed task complete / task block / failure
blocked resumed / failed task resume / failure
resumed done / blocked / failed task complete / task block / failure
failed started task start (retry)
done — terminal (then task finalize reconciles design status)

The verbs

Step Command What it does Records an event?
Prepare task prepare <id> --agent <a> --json The single entry point. Returns current state, the recommendation, context-pack metadata, a structured next_action, and a commands dictionary with the exact next commands. No — progress-read-only (writes the context pack unless --dry-run)
Start task start <id> --agent <a> Records started. Idempotent — a second call returns already_started. started
(implement) — Your agent's own work. code-pact is not running. —
Verify verify --phase <p> --task <id> Runs the phase's verification commands without recording anything. A pre-flight for complete. No
Complete task complete <id> --agent <a> Re-runs verification; appends done on pass. Idempotent — a second call returns already_done. done (on pass)
Finalize task finalize <id> --write --json Flips the task's design status to done, and audits declared vs. actual writes. Run without --write first to preview. No

If a task is waiting on something, record it explicitly:

Command What it does Records an event?
task block <id> --reason "…" Marks the task blocked with a reason. blocked
task resume <id> --agent <a> Clears the block; the task becomes resumed. resumed

Recording a done without task complete

task record-done records a done event without running the loop's verification commands — the proof is the --evidence you supply. It is the honest path for two cases:

  1. External completion — work already merged, or not verifiable from the current working tree.
  2. The record_only lightweight lane — when task prepare recommends lifecycleMode: record_only (a small, low-risk, strongly-verified docs/test task), you run the project's verification yourself, then record the result here. record_only is a lighter loop, not lighter verification.
Command What it does Records an event?
task record-done <id> --evidence "PR #123 · pnpm test green" Records done without running verification commands — the proof is --evidence (a PR, CI link, or the verification you ran). The event carries source: external. The decision gate still applies for requires_decision tasks. done (source: external)

When the work can be verified from the working tree and lifecycleMode is not record_only, prefer the normal complete path (it runs verification for you). source: external marks an event that did not go through task complete's loop verification — so later diagnostics can tell the two apart. Put real proof in --evidence: a PR number, a CI result, or the verification command you ran.

A worked example

# 1. Prepare — read state + recommendation + the exact next commands.
code-pact task prepare P1-T1 --agent claude-code --json

# 2. Start, then implement the task.
code-pact task start P1-T1 --agent claude-code

# 3. (Optional) pre-flight verification before completing.
code-pact verify --phase P1 --task P1-T1

# 4. Complete — re-runs verification, appends `done` on pass.
code-pact task complete P1-T1 --agent claude-code

# 5. Finalize — preview first, then flip the design status to done.
code-pact task finalize P1-T1 --json
code-pact task finalize P1-T1 --write --json

Warning

task finalize --write mutates the phase YAML in design/. Run it without --write first to preview the change (dry-run is the default).

Invariants worth knowing

  • task start and task complete are idempotent. Re-running on an already-started / already-done task returns already_started: true / already_done: true instead of erroring.
  • A blocked task cannot complete directly. task complete returns INVALID_TASK_TRANSITION until you task resume, so the unblock decision is captured as an event.
  • task complete records progress but does not touch design/. Design intent and operational fact are kept separate on purpose. task finalize (one task) or phase reconcile (a whole phase) is what reconciles them. If they drift, plan analyze reports a STATUS_DRIFT warning.

For the full flag, exit-code, and envelope reference of every verb, see cli-contract.md.