9thlevelsoftware/legion/execution-tracker

After receiving each agent's completion (per adapter.collect_results):
 
Step 1: Determine plan result
  - Success: agent completed all tasks, verification passed
  - Partial: agent completed some tasks, or verification had warnings
  - Failed: agent encountered errors or verification failed
 
Step 1.5: Verify or initialize STATE.md structure (precondition for Step 2)
 
  Before writing to STATE.md, verify the required section structure exists.
  Missing sections are the canonical failure mode for the first plan of a new phase.
 
  a) Read `.planning/STATE.md` explicitly via the Read tool. Do NOT assume contents.
     If STATE.md is absent: **FAIL FAST** — emit:
     ```
     <escalation>
     severity: blocker
     type: scope
     decision: Cannot record plan result — STATE.md missing
     context: .planning/STATE.md not found. Run /legion:start or /legion:validate to initialize.
     </escalation>
     ```
     and STOP. Do NOT create STATE.md from scratch here — that is `/legion:start`'s responsibility.
     If STATE.md exists but is empty or cannot be read (permission error): emit the same escalation with context describing the read failure and STOP.
 
  b) Verify required top-level sections exist (in this canonical order):
     1. `## Status`
     2. `## Last Activity`
     3. `## Phase {N} Results` — one per phase seen in ROADMAP.md (load-bearing for progress parse)
     4. `## Progress`
 
  c) For any missing section, **append it at the canonical position** with an empty placeholder:
     - `## Phase {N} Results` — placeholder body: `_No plans completed yet._`
     - `## Progress` — placeholder body: `[........] 0% — 0/{total} plans complete`
     - `## Status` / `## Last Activity` — placeholder body: `_Not set._`
 
  d) Write the updated STATE.md back before proceeding to Step 2.
 
  **Load-bearing headings for parsing:** `## Phase {N} Results` (exact pattern, integer N).
  Step 2 progress recalculation relies on this heading to count completed plans. Do not rename
  or change case.
 
Step 2: Update STATE.md
  Read current .planning/STATE.md, then update:
  - Status: "Phase {N} executing — Plan {NN}-{PP} {complete|failed}"
  - Last Activity: "Plan {NN}-{PP} execution ({date})"
  - Add to Phase {N} Results section:
    - Plan {NN}-{PP} (Wave {W}): {plan_name} — {brief result description}
  - Recalculate Progress:
    - Count all completed plans across all phases (from Phase Results sections)
    - Total plans = sum of Plans column from ROADMAP.md progress table
    - Percentage = (completed / total) * 100, rounded to nearest integer
    - Update the progress bar: [####...] {pct}% — {completed}/{total} plans complete
  Write updated STATE.md
 
Schema reference: docs/schemas/summary.schema.json defines the structured format.
  When generating summaries, agents SHOULD produce data conforming to this schema
  before rendering to markdown. This enables downstream tooling to parse summaries
  programmatically. The markdown rendering is the canonical format; the schema
  documents the expected structure.
 
Step 2.5: Record outcome in memory (optional)
  Follow memory-manager Section 6 (Graceful Degradation) caller pattern:
  - Check if .planning/memory/OUTCOMES.md exists OR if .planning/memory/ directory exists
  - If memory is available or can be created:
    Follow memory-manager Section 3 (Store Outcome):
    - Agent: the agent that executed the plan (from the plan's agent assignment, or "autonomous")
    - Task Type: inferred from the plan's primary task types (match against agent-registry tags)
    - Outcome: "success" if plan passed, "failed" if plan failed, "partial" if plan had warnings
    - Importance: calculated per memory-manager Section 2 importance scoring
    - Tags: phase slug, agent division, primary file types modified
    - Summary: one-line from the agent's completion report (per adapter.collect_results)
  - If memory is not available: skip silently, proceed to Step 3
  - If memory write fails: output the intended record as text, continue to Step 3
  NOTE: The git add -A in Step 3 will include any memory file changes automatically.
 
Step 3: Create atomic git commit (success only)
  Only commit if the plan succeeded:
  git add -A
  git commit -m "feat(legion): execute plan {NN}-{PP} — {plan_name}
 
  Phase {N}: {phase_name}
  Wave: {W}
  Requirements: {comma-separated requirement IDs}
 
  {adapter.commit_signature}"
 
  If the plan failed: do NOT commit — leave changes unstaged for diagnosis
 
Step 4: Verify commit
  - Run `git log --oneline -1` to confirm the commit was created
  - If commit failed (e.g., nothing to commit): log a warning, continue

After all plans in a wave have been processed:
 
Step 1: Summarize wave results
  - Count: plans succeeded, plans failed, plans total in wave
  - List files modified across all plans in the wave
 
Step 2: Update ROADMAP.md progress table
  Read current .planning/ROADMAP.md, find the progress table:
  | Phase | Plans | Completed | Status |
  Update the row for the current phase:
  - Completed: {total completed plans so far in this phase}
  - Status: "In Progress" if more waves remain, "Complete" if this was the last wave
  Write updated ROADMAP.md
 
Step 3: Report wave status
  Output for the orchestrator:
  ## Wave {W} Complete
  - Plans: {succeeded}/{total} succeeded
  - Files modified: {list}
  - {If any failures: "BLOCKED — {count} plan(s) failed. See summaries for details."}
  - {If all passed: "Ready for Wave {W+1}" or "All waves complete"}

After all waves have been executed:
 
Step 1: Calculate final phase status
  - All plans succeeded: phase is complete
  - Some plans failed: phase is partial (needs review)
 
Step 2: Update STATE.md
  - Phase: {N} of {total} (executed, pending review) | (partial — {count} plan(s) failed)
  - Status: "Phase {N} complete — all plans executed successfully"
    OR: "Phase {N} partial — {count} plan(s) failed, review needed"
  - Last Activity: "Phase {N} execution ({date})"
  - Next Action:
    - If all passed: "Run `/legion:review` to verify Phase {N}: {phase_name}"
    - If some failed: "Run `/legion:review` to diagnose failures in Phase {N}"
  Write updated STATE.md
 
Step 3: Update ROADMAP.md progress table
  - Status: "Complete" if all plans passed, "Partial" if some failed
 
Step 3.5: Suggest semantic compaction (optional)
  If all plans passed (phase is complete, not partial):
  - Check if any previous completed phases have uncompacted summaries:
    For each completed phase in ROADMAP.md:
      Check if .planning/phases/{NN-name}/{NN}-COMPACTED.md exists
      If not: count it as uncompacted
  - If uncompacted phases exist:
    Include in the output: "💡 {count} completed phase(s) have uncompacted summaries. Run compaction to free context for future planning."
  - This is informational only — never auto-compact, never block on compaction
 
Step 4: Final progress display
  Output for the user:
  ## Phase {N}: {phase_name} — Execution Complete
  [##########          ] {pct}% — {completed}/{total} plans complete
 
  | Plan | Wave | Status | Summary |
  |------|------|--------|---------|
  | {NN}-{PP} | {W} | Pass/Fail | {one-line summary} |
  ...
 
  Next: Run `/legion:review` to verify Phase {N}

To calculate overall project progress:
 
1. Read .planning/ROADMAP.md progress table
2. For each phase row:
   - Get "Plans" count (total plans in phase)
   - Get "Completed" count
3. Sum all "Plans" values = total_plans
4. Sum all "Completed" values = completed_plans
5. Percentage = floor((completed_plans / total_plans) * 100)
6. Progress bar:
   - 20 characters wide
   - filled = floor(percentage / 5)
   - empty = 20 - filled
   - Format: [{"#" * filled}{"." * empty}] {percentage}% — {completed}/{total} plans complete
 
Example:
  Phase 1: 2/2, Phase 2: 2/2, Phase 3: 2/2, Phase 4: 1/3
  Total: 7/13 = 53%
  [##########..........] 53% — 7/13 plans complete

Plan completion commit (one per successful plan):
  feat(legion): execute plan {NN}-{PP} — {brief plan name}
 
  Phase {N}: {phase_name}
  Wave: {W}
  Requirements: {REQ-XX, REQ-YY}
 
  {adapter.commit_signature}
 
Wave completion state update (one per wave):
  chore(legion): update state after wave {W} of phase {N}
 
  {succeeded}/{total} plans completed
  Progress: {completed}/{total_plans} ({pct}%)
 
  {adapter.commit_signature}
 
Phase completion state update (one per phase):
  chore(legion): complete phase {N} execution — {phase_name}
 
  All plans executed. {succeeded}/{total} passed.
  Overall progress: {completed}/{total_plans} ({pct}%)
 
  {adapter.commit_signature}
 
Milestone completion commit (one per completed milestone):
  chore(legion): complete milestone {N} — {milestone_name}
 
  Phases {start}-{end}: {phase_count} phases, {plans_completed} plans
  Requirements: {requirement_count} satisfied
  Summary: .planning/milestones/MILESTONE-{N}.md
 
  {adapter.commit_signature}
 
Milestone archive commit (one per archived milestone):
  chore(legion): archive milestone {N} — {milestone_name}
 
  Phases moved to .planning/archive/milestone-{N}/
  STATE.md and ROADMAP.md updated
 
  {adapter.commit_signature}
 
PR creation state update (one per phase PR):
  chore(legion): create PR for phase {N} — {phase_name}
 
  PR #{pr_number}: {pr_url}
  Branch: {branch_name}
  Issues: #{issue_number}
 
  {adapter.commit_signature}