Tasks

A task graph is plain YAML -- the concrete steps a confirmed contract breaks down into:

schema_version: 1
tasks:
  - id: T001
    name: Implement greeter
    objective: Implement the greet() function.
    status: planned
    depends_on: []
    acceptance_criteria:
      - greet() returns a friendly string
    context_files:
      - greeter.js
    write_scope:
      - greeter.js
    verification:
      strategy: command
      detail: npm test
    result: null
    usage: null

write_scope is mechanically enforced

write_scope is a list of exact file paths -- no directory prefixes, no globs. A task's completion commit refuses if it touches anything outside its declared paths. This is what keeps an agent from quietly drifting outside its intended boundary.

States

planned → waiting → ready → in_progress → review → completed, plus in_progress → blocked → ready, in_progress → failed → ready, review → in_progress on evidence-blocked recovery, and planned|waiting|ready → cancelled.

Working a task

pitway task-update T001 in_progress
# ... write greeter.js ...
pitway task-verify T001          # runs the approved command, records evidence
pitway task-update T001 review
pitway task-update T001 completed --result result.yaml --message message.txt

result.yaml is {summary: ..., evidence: ...}; message.txt is the commit message body PitWay appends PitWay-Milestone/PitWay-Task trailers to. Completion is one atomic commit containing the code changes and the matching .pitway/ state update -- the working tree must be clean except for the task's own declared write_scope at every transition.

Mid-flight correction

Once a milestone is confirmed or in progress, its task graph isn't frozen: pitway task-add inserts a new task discovered mid-flight, and pitway task-amend amends an existing task's objective, scope, or verification -- both require a change-log reason. See Evidence for how a task's verification is checked and recorded, and Worktrees for how independent tasks can run concurrently.