1. Parse input → Determine mode (PR / Local)
2. Read PLAN.md → Create ALL Tasks (Init + TODO sub-steps + Finalize) → Set dependencies
3. Init/resume context (.dev/specs/{name}/context/)
4. LOOP while TaskList() has pending tasks:
   Pick runnable (pending + not blocked) → dispatch by type:
     :State Begin      → [PR only] Skill("state", "begin") → stop on failure
     :Worker  → Task(worker) with substituted variables
     :Verify  → dispatch verify worker, triage (halt > adapt > retry > skip), reconcile if FAILED
     :Wrap-up → save context (Worker + Verify) + mark Plan checkbox [x]
     :Commit  → Task(git-master) per Commit Strategy
     :Residual Commit → git status → git-master if dirty
     :State Complete   → [PR only] Skill("state", "complete")
     :Report           → output final report
5. (Init, TODO execution, and Finalize are all part of the loop)

gh pr list --head $(git branch --show-current) --draft --json number
# PR exists → PR mode | No PR → infer spec from branch name

# ═══════════════════════════════════════════════════
# TURN 1: Create ALL tasks in PARALLEL (single message)
# ═══════════════════════════════════════════════════
# Send ALL of these TaskCreate calls in ONE message simultaneously.
# Claude Code supports multiple tool calls per message — use it.

# Init (PR only)
IF pr_mode:
  sb = TaskCreate(subject="Init:State Begin", ...)

# Per-TODO sub-steps (ALL TODOs in parallel)
FOR EACH "### [ ] TODO N: {title}" in plan:
  w  = TaskCreate(subject="{N}.1:Worker — {title}",
                  description="{full TODO section content}",
                  activeForm="{N}.1: Running Worker")
  v  = TaskCreate(subject="{N}.2:Verify",
                  description="Dispatch verify worker for TODO {N}. ...",
                  activeForm="{N}.2: Verifying")
  wu = TaskCreate(subject="{N}.3:Wrap-up",
                  description="Wrap-up for TODO {N}. ...",
                  activeForm="{N}.3: Wrapping up")
  IF commit_strategy_has_row(N):
    cm = TaskCreate(subject="{N}.4:Commit",
                    description="Commit TODO {N} changes. ...",
                    activeForm="{N}.4: Committing")

# Finalize tasks
rc = TaskCreate(subject="Finalize:Residual Commit", ...)
IF pr_mode:
  sc = TaskCreate(subject="Finalize:State Complete", ...)
rp = TaskCreate(subject="Finalize:Report", activeForm="Generating report",
     description="Read ${baseDir}/references/report-template.md, then output the report verbatim replacing placeholders with actual values.")

# ═══════════════════════════════════════════════════
# TURN 2: Set ALL dependencies in PARALLEL (single message)
# ═══════════════════════════════════════════════════
# After Turn 1 returns all task IDs, send ALL TaskUpdate calls
# for dependencies in ONE message simultaneously.

FOR EACH unchecked TODO N:
  TaskUpdate(taskId=w.task_id, addBlocks=[v.task_id])
  TaskUpdate(taskId=v.task_id, addBlocks=[wu.task_id])
  IF task_ids[N].commit:
    TaskUpdate(taskId=wu.task_id, addBlocks=[cm.task_id])

IF pr_mode:
  FOR EACH unchecked TODO N:
    TaskUpdate(taskId=sb.task_id, addBlocks=[task_ids[N].worker])

all_last_steps = [task_ids[N].commit ?? task_ids[N].wrapup for each unchecked TODO N]
FOR EACH last_step in all_last_steps:
  TaskUpdate(taskId=last_step, addBlocks=[rc.task_id])

IF pr_mode:
  TaskUpdate(taskId=rc.task_id, addBlocks=[sc.task_id])
  TaskUpdate(taskId=sc.task_id, addBlocks=[rp.task_id])
ELSE:
  TaskUpdate(taskId=rc.task_id, addBlocks=[rp.task_id])

FOR EACH row where row.Requires != "-" AND both TODOs unchecked:
  producer_N = parse(row.Requires)  # e.g., "todo-1.config_path" → 1
  consumer_N = row.TODO

  # Last sub-step of producer = Commit (if exists) or Checkbox
  producer_last = task_ids[producer_N].commit ?? task_ids[producer_N].checkbox
  consumer_first = task_ids[consumer_N].worker

  TaskUpdate(taskId=producer_last, addBlocks=[consumer_first])

Expected (PR mode, TODO 1 independent, TODO 2 depends on TODO 1):

#1  [pending] Init:State Begin
#2  [pending] 1.1:Worker — Config setup  [blocked by #1]
#3  [pending] 1.2:Verify          [blocked by #2]
#4  [pending] 1.3:Wrap-up         [blocked by #3]
#5  [pending] 1.4:Commit          [blocked by #4]
#6  [pending] 2.1:Worker — API    [blocked by #5]   ← cross-TODO dep
#7  [pending] 2.2:Verify          [blocked by #6]
#8  [pending] 2.3:Wrap-up         [blocked by #7]
#9  [pending] 3.1:Worker — Utils  [blocked by #1]
#10 [pending] 3.2:Verify          [blocked by #9]
#11 [pending] 3.3:Wrap-up         [blocked by #10]
#12 [pending] 3.4:Commit          [blocked by #11]
#13 [pending] Finalize:Residual Commit [blocked by #5, #8, #12]
#14 [pending] Finalize:State Complete  [blocked by #13]
#15 [pending] Finalize:Report          [blocked by #14]

→ Round 0: #1 (Init:State Begin)
→ Round 1: #2 (1.1:Worker), #9 (3.1:Worker) — parallel!

CONTEXT_DIR=".dev/specs/{name}/context"

mkdir -p "$CONTEXT_DIR"

WHILE TaskList() has pending tasks:
  runnable = TaskList().filter(status=="pending" AND blockedBy==empty)

  IF len(runnable) > 1 AND all are :Worker or :Verify or :Commit:
    # PARALLEL dispatch — mark in_progress FIRST, then send ALL in ONE message
    FOR EACH task in runnable:
      TaskUpdate(taskId=task.id, status="in_progress")
    FOR EACH task in runnable (in single message):
      dispatch(task, run_in_background=true)
    # Poll for completion
    WAIT until any background task completes (check TaskOutput periodically)
    # Process completed tasks, mark completed, loop
  ELSE:
    # Single task — mark in_progress, read details, then dispatch
    TaskUpdate(taskId=task.id, status="in_progress")
    task_details = TaskGet(taskId=task.id)
    dispatch(task, task_details)

Skill("state", args="begin <PR#>")

# outputs.json: {"todo-1": {"config_path": "./config/app.json"}}
# Plan Inputs:  config_path: ${todo-1.outputs.config_path}
# Result:       config_path: ./config/app.json

task_details = TaskGet(taskId={task.id})

Task(
  subagent_type="worker",
  description="Implement: {task.subject}",
  prompt="""
## TASK
{TODO title + Steps from task_details.description}

## EXPECTED OUTCOME
When this task is DONE, the following MUST be true:

**Outputs** (must generate):
{Outputs section from Plan}

**Acceptance Criteria** (all must pass):
{Acceptance Criteria section from Plan}

## REQUIRED TOOLS
- Read: Reference existing code
- Edit/Write: Write code
- Bash: Run build/tests

## MUST DO
- Perform only this Task
- Follow existing code patterns (see References below)
- Utilize Inherited Wisdom (see CONTEXT below)

## MUST NOT DO
{Must NOT do section from Plan}
- Do not perform other Tasks
- Do not add new dependencies
- Do not run git commands (Orchestrator handles this)

## CONTEXT
### References (from Plan)
{References section from Plan}

### Dependencies (from Inputs - substituted values)
{Actual values after substitution}

### Inherited Wisdom
SubAgent does not remember previous calls.

**Conventions (from learnings.md):**
{learnings.md content}

**Failed approaches to AVOID (from issues.md):**
{issues.md content}

**Key decisions & reconciliation history (from audit.md):**
{audit.md content}
"""
)

Task(
  subagent_type="worker",
  description="Verify: TODO {N} acceptance criteria + must-not-do",
  prompt="""
## TASK
You are a VERIFICATION worker. Your job is to independently verify
that TODO {N}'s acceptance criteria are met AND that must-not-do
rules were not violated.

DO NOT write or modify any code. Only READ and RUN verification commands.

## PART 1: ACCEPTANCE CRITERIA TO VERIFY
{Acceptance Criteria section from Plan for TODO N}

For each criterion, run the specified command and report PASS/FAIL:

1. Functional checks: run commands (test -f, curl, etc.)
2. Static checks: run linter/type-checker (tsc --noEmit, eslint, etc.)
3. Runtime checks: run tests (npm test, pytest, etc.)

⚠️ Do NOT trust the Worker's self-reported PASS status.
Re-execute every command yourself and judge independently.

## PART 2: MUST-NOT-DO VIOLATIONS
{Must NOT do section from Plan for TODO N}
{Standard must-not-do: no other Tasks, no new dependencies, no git commands}

For each must-not-do rule, check whether it was violated:
- Read `git diff` (staged + unstaged) to see what the Worker actually changed
- Check for must-not-do violations from the TODO's rules
- Check for new dependencies added (package.json, go.mod, etc.)
- Check for out-of-scope changes unrelated to this TODO

## PART 3: SIDE-EFFECT & CONTEXT AUDIT
Review the Worker's output JSON and the actual code changes:

1. **Suspicious PASS**: Did the Worker report PASS but the actual
   code doesn't fully satisfy the criterion? (e.g., stub implementation,
   TODO comments, partial logic, error swallowed silently)
2. **Undocumented side-effects**: Did the Worker change things not
   mentioned in its output? (e.g., modified shared utilities, changed
   configs, added exports not in scope)
3. **Missing context**: Did the Worker discover patterns, issues, or
   make decisions that should be in learnings/issues/decisions but aren't?

## PART 4: SCOPE-RELATED BLOCKAGE DETECTION
If you detect a failure that stems from SCOPE limitations (not Worker error),
populate the `suggested_adaptation` field:

**When to suggest adaptation:**
- **scope_violation**: Acceptance criteria requires work beyond current TODO's must-not-do boundaries
- **dod_gap**: DoD (Definition of Done) criterion cannot be met without expanding scope
- **dependency_missing**: Work requires outputs/artifacts not produced by any prior TODO

**Detection signals:**
1. Check if failed acceptance criteria require work that violates must-not-do rules
2. Check if the DoD explicitly requires work beyond current TODO's boundaries
3. Check if the Worker correctly identified a blocker but cannot fix it in-scope

**What NOT to suggest:**
- Worker made a mistake (code_error) → retry, don't adapt
- Environment issue (missing dependency, API key) → env_error, don't adapt
- Suspicious pass or missing context → side_effects, don't adapt

Only suggest adaptation when the PLAN itself needs adjustment, not the Worker's execution.

## OUTPUT FORMAT (strict JSON)
{
  "status": "VERIFIED" | "FAILED",
  "acceptance_criteria": {
    "pass": <number>,
    "fail": <number>,
    "results": [
      {
        "id": "<criterion_id>",
        "category": "functional" | "static" | "runtime",
        "description": "<what was checked>",
        "command": "<command run>",
        "status": "PASS" | "FAIL",
        "reason": "<failure reason, if FAIL>"
      }
    ]
  },
  "must_not_do": {
    "violations": [
      {
        "rule": "<which rule was violated>",
        "evidence": "<what was found>",
        "severity": "critical" | "warning"
      }
    ]
  },
  "side_effects": {
    "suspicious_passes": ["<criterion_id that looks questionable>"],
    "undocumented_changes": ["<file or change not mentioned in output>"],
    "missing_context": ["<learning/issue/decision Worker should have reported>"]
  },
  "suggested_adaptation": {
    // ⚠️ Only include this field when status is FAILED AND you detect a scope-related blockage
    // (e.g., DoD criterion requires work that violates must-not-do, or needs missing dependency)
    "blockage_type": "scope_violation" | "dod_gap" | "dependency_missing",
    "suggested_todo": {
      "title": "<concise TODO title for what needs to be added to plan>",
      "reason": "<why current scope cannot satisfy this criterion>",
      "steps": ["<step 1>", "<step 2>", ...],
      "scope_justification": "<why this new TODO is necessary and in-scope for the overall plan>"
    },
    "scope_signals": {
      "dod_related": ["<which acceptance criteria cannot be met with current scope>"],
      "within_todo_scope": <boolean — true if work fits within current TODO's must-not-do rules, false if out-of-scope>
    }
  }
}

## MUST NOT DO
- Do not modify any files
- Do not write code or fix issues
- Do not run git commands (except read-only: git diff, git status)
- Only verify — report results objectively
"""
)

function reconcile(TODO_N, verify_result, depth=0):
  # verify_result is passed in from :Verify handler (no duplicate dispatch)
  if verify_result.status == "VERIFIED" → mark completed, done

  # Log non-blocking items FIRST (always, regardless of disposition)
  log_non_blocking(verify_result)  # warnings → audit.md, undocumented → issues.md, missing_context → learnings.md

  # Single-pass triage (precedence: halt > adapt > retry)
  disposition = triage(verify_result, TODO_N.type)
  append_audit("triage", TODO_N, disposition, verify_result)  # always log triage decision

  if disposition == HALT → log to issues.md, stop execution
  if disposition == ADAPT → adapt(TODO_N, verify_result, depth)
  if disposition == RETRY → retry_loop(TODO_N, verify_result, depth)

function retry_loop(TODO_N, verify_result, depth):
  for attempt in 1..3:
    append_audit("retry", TODO_N, attempt)  # log retry intent
    fix_prompt = build_fix_prompt(verify_result)  # failed criteria + violations + suspicious passes
    Task(subagent_type="worker", prompt=fix_prompt)
    verify_result = dispatch_verify_worker(TODO_N)
    if VERIFIED → done
    log_non_blocking(verify_result)
    disposition = triage(verify_result, TODO_N.type)  # re-triage each cycle
    append_audit("triage", TODO_N, disposition, verify_result)
    if disposition == HALT → stop
    if disposition == ADAPT → adapt(TODO_N, verify_result, depth); return
  # 3 retries exhausted → halt
  halt("retry_exhausted")

function triage(verify_result, todo_type) → HALT | ADAPT | RETRY:
  # todo_type detection:
  #   "verification" — PLAN has `type: verification` field, OR title matches "TODO Final: Verification"
  #   "work"         — all other TODOs (default)

  # --- HALT (highest precedence) ---
  IF any must_not_do with severity==critical → HALT
  IF any env_error (permission, API key, network) → HALT

  # --- ADAPT (scope blocker OR verification TODO) ---
  IF suggested_adaptation present:
    IF scope_check(suggested_adaptation) == safe → ADAPT
    IF scope_check(suggested_adaptation) == destructive_out_of_scope → HALT

  IF todo_type == "verification" AND any acceptance_criteria FAIL:
    → ADAPT (auto-generate fix TODO from failed criteria)
    # Verification TODOs are read-only — retry cannot fix code.
    # Orchestrator builds suggested_adaptation from failed criteria:
    #   title: "Fix: {failed_criterion.description}"
    #   steps: derived from failure reason + affected files
    #   scope: safe (fixing own project's code)

  # --- RETRY (code error, suspicious pass — work TODOs only) ---
  IF any acceptance_criteria FAIL or suspicious_pass → RETRY

  # --- Non-blocking items (logged, not dispositions) ---
  # must_not_do warning     → log to audit.md
  # undocumented_change     → log to audit.md + issues.md
  # missing_context         → log to audit.md + learnings.md

function scope_check(suggested_adaptation) → safe | destructive_out_of_scope:
  # in_scope detection:
  #   needed_for_DoD = any acceptance_criteria in current TODO references the adaptation target
  #   within_todo_scope = adaptation doesn't violate the TODO's must-not-do rules
  in_scope = (needed_for_DoD OR within_todo_scope)

  # destructive detection (ANY of these → destructive):
  #   DB schema changes (migrations, ALTER TABLE)
  #   API breaking changes (endpoint removal, response shape change)
  #   Shared resource deletion (files imported by multiple modules)
  #   Auth/security changes (token handling, permissions, secrets)
  #   External config (CI/CD, deployment, infrastructure)
  destructive = matches_any_destructive_pattern(suggested_adaptation)

  IF in_scope → safe
  IF NOT in_scope AND NOT destructive → safe (log "out-of-scope, non-destructive" to audit.md)
  IF NOT in_scope AND destructive → destructive_out_of_scope

function adapt(TODO_N, verify_result, depth):
  IF depth >= 1 → halt("depth_limit")  # no nested adaptation
  # count_dynamic_todos: count PLAN.md entries matching "TODO {N}.a*" (ADDED) markers
  IF count_dynamic_todos(TODO_N) >= 3 → halt("max_dynamic_todos")  # max 3 per original
  suffix = next_suffix(TODO_N)  # "a", "b", "c" — sequential per original TODO

  # 1. Update PLAN.md
  Edit: insert after TODO {N}:
    ### [ ] TODO {N}.{suffix}: (ADDED) {suggested_todo.title}

  # 2. Log to audit.md
  append_audit("adapt", TODO_N, suggested_adaptation)

  # 3. Create & run dynamic TODO (Task subject matches PLAN marker)
  dynamic_task = TaskCreate(
    subject="{N}.{suffix}:Adapt — {suggested_todo.title}",
    description="{suggested_todo.description}",
    metadata={is_dynamic: true, parent_todo: N}
  )
  → reconcile(dynamic_task, depth=1)  # same flow, depth incremented

  # 4. Result
  IF dynamic_task VERIFIED:
    → Mark PLAN.md: [x] TODO {N}.{suffix}
    → Update audit.md: Status = COMPLETED
    → Retry original TODO {N} via reconcile(TODO_N, new_verify_result, depth=0)
  ELSE:
    → Mark PLAN.md: TODO {N}.{suffix} — FAILED
    → Update audit.md: Status = FAILED
    → halt("dynamic_todo_failed")

## TODO {N} — Reconciliation

### [YYYY-MM-DD HH:MM] Triage
- acceptance_criteria:login_test FAIL → retry
- must_not_do:no_git_commands warning → logged (non-blocking)
- suggested_adaptation:scope_violation → adapt

### [YYYY-MM-DD HH:MM] Retry #1
- Fix prompt sent, re-verified → FAIL
- acceptance_criteria:login_test FAIL → retry

### [YYYY-MM-DD HH:MM] Adapt
- **Dynamic TODO**: {N}.a — {title}
- **Trigger**: {blockage_type}
- **Scope**: safe (needed_for_DoD=YES)
- **Status**: COMPLETED | FAILED

### [YYYY-MM-DD HH:MM] Halted (if applicable)
- **Reason**: {reason}
- **Evidence**: {evidence}

# Parallel 1.3:Wrap-up and 3.3:Wrap-up both runnable:

# outputs.json — SEQUENTIAL:
current = Read("outputs.json")
current["todo-1"] = result1.outputs
Write("outputs.json", current)

current = Read("outputs.json")
current["todo-3"] = result3.outputs
Write("outputs.json", current)

# learnings.md, issues.md — PARALLEL OK (append mode)

Edit(plan_path, "### [ ] TODO N: ...", "### [x] TODO N: ...")

FOR EACH criterion in verify_result.acceptance_criteria:
  IF criterion.status == "PASS":
    Edit(plan_path,
         "- [ ] {criterion.description}",
         "- [x] {criterion.description}")

Task(
  subagent_type="git-master",
  description="Commit {N}",
  prompt="""
Commit TODO {N} changes.
Commit message: {Message from Commit Strategy table}
Files: {Files from Commit Strategy table}
Push after commit: {YES if PR mode, NO if Local mode}
"""
)

git status --porcelain

Task(
  subagent_type="git-master",
  description="Commit: residual changes",
  prompt="""
Plan execution complete. Run `git status`.
If changes: commit "chore({plan-name}): miscellaneous changes"
Push: {YES if PR mode, NO if Local mode}
If clean: report "No uncommitted changes" and exit.
"""
)

Skill("state", args="complete <PR#>")

TaskUpdate(report.id, status="in_progress")
template = Read("${baseDir}/references/report-template.md")   ← actual file read
# Output report verbatim, replacing {placeholders} with real values
# Do NOT invent your own format — follow the template exactly
TaskUpdate(report.id, status="completed")

{
  "todo-1": { "config_path": "./config/app.json" },
  "todo-2": { "api_module": "src/api/index.ts" }
}

Before TODO #1 → Read context → inject into prompt
After TODO #1  → Save outputs + learnings
Before TODO #2 → Read outputs.json → substitute ${todo-1.outputs.X}
After TODO #2  → Update outputs.json + append learnings
(Accumulates. Preserved in files across sessions.)

Desired State: All acceptance_criteria PASS, no critical violations
Current State: Verify Worker result

[VERIFIED] → Save context (2c) — include missing_context from Verify
[FAILED] → reconcile(TODO_N, verify_result, depth=0):
  log_non_blocking() → triage(verify_result, todo_type) → single disposition (halt > adapt > retry):
  halt    → Stop execution, log to audit.md + issues.md
  adapt   → Create dynamic TODO via reconcile(depth+1), then retry original
  retry   → Fix Worker → re-verify (max 3), re-triage each cycle
  All triage decisions + retry attempts logged to audit.md

## [YYYY-MM-DD HH:MM] {TODO name} Failed

**Category**: env_error | unknown
**Error**: {error message}
**Retry Count**: {n}
**Analysis**: {why human intervention needed}
**Suggestion**: {recommended action}

TaskList() after initialization:

#1  [pending] Init:State Begin
#2  [pending] 1.1:Worker — Config setup  [blocked by #1]
#3  [pending] 1.2:Verify          [blocked by #2]
#4  [pending] 1.3:Wrap-up         [blocked by #3]
#5  [pending] 1.4:Commit          [blocked by #4]
#6  [pending] 2.1:Worker — API    [blocked by #5]   ← cross-TODO dep
#7  [pending] 2.2:Verify          [blocked by #6]
#8  [pending] 2.3:Wrap-up         [blocked by #7]
#9  [pending] 3.1:Worker — Utils  [blocked by #1]
#10 [pending] 3.2:Verify          [blocked by #9]
#11 [pending] 3.3:Wrap-up         [blocked by #10]
#12 [pending] 3.4:Commit          [blocked by #11]
#13 [pending] Finalize:Residual Commit [blocked by #5, #8, #12]  ← #5=1.4:Commit, #8=2.3:Wrap-up, #12=3.4:Commit
#14 [pending] Finalize:State Complete  [blocked by #13]
#15 [pending] Finalize:Report          [blocked by #14]

Round 0:  #1 Init:State Begin                   ← PR only
Round 1:  #2 1.1:Worker, #9 3.1:Worker           ← PARALLEL
Round 2:  #3 1.2:Verify, #10 3.2:Verify          ← PARALLEL
Round 3:  #4 1.3:Wrap-up, #11 3.3:Wrap-up        ← PARALLEL (outputs.json sequential!)
Round 4:  #5 1.4:Commit, #12 3.4:Commit          ← PARALLEL
Round 5:  #6 2.1:Worker                           ← unblocked after #5
Round 6:  #7 2.2:Verify
Round 7:  #8 2.3:Wrap-up
Round 8:  #13 Finalize:Residual Commit            ← blocked by all TODO last steps
Round 9:  #14 Finalize:State Complete             ← blocked by #13
Round 10: #15 Finalize:Report                     ← blocked by #14

### [x] TODO 1: Config setup       ← skip (complete)
### [ ] TODO 2: API implementation ← create sub-step Tasks
### [x] TODO 3: Utils              ← skip (complete)
### [ ] TODO 4: Integration        ← create sub-step Tasks

# Init (PR only):
Init:State Begin → all {N}.1:Worker tasks

# Intra-TODO chain (always):
{N}.1:Worker → {N}.2:Verify → {N}.3:Wrap-up → {N}.4:Commit

# Cross-TODO (from Dependency Graph):
1.4:Commit (or 1.3:Wrap-up) → 2.1:Worker

# Finalize chain:
all TODO last steps → Residual Commit → State Complete (PR) → Report