[calvin-archastro]

Why

Two gaps in how agents draft and maintain Task plans:

1. Plans read as complete to the drafter. The drafter has the whole conversation, so its tasks can lean on context a worker never sees. Workers then stall or get paused as underspecified.
2. Cleaning up paused work goes wrong in the same ways every time. An audit of ~175 unfinished Tasks across ~40 epics, many of them paused by the Factory overseer, showed:
   • flipping native status behind a running Factory, which just re-pauses the work;
   • guessing at pause reasons instead of reading the activity feed and comments;
   • silently deciding scope that belongs to the human;
   • leaving work hand-parked instead of recording dependency edges.

Summary

New ## 3. Check each task in isolation before review. Later sections are renumbered to 4–6.

• Before opening review, a fresh subagent reads each node alone and returns gaps as JSON. It gets only that node, not the conversation or the other nodes.
• The subagent runs on a smaller, cheaper model than the drafter. The harness picks its own cheaper tier: Claude Code's haiku/sonnet, or a mini/flash tier elsewhere. If it can't choose a model, it uses the default.
• The main context triages each gap once:
  • answer it in the node;
  • move it to major_decisions if only the human can decide;
  • or dismiss it with a reason.
• No second round. If the harness has no subagents, the step is skipped rather than replaced by self-review.
• Also documents the optional node fields scope, exclusions, depends_on and dependency_reasons.

New ## 7. Audit and unblock paused or failed work. Runs only when the user asks for an audit.

1. Inventory paused, failed, open and in-review Tasks by epic, paging through all results.
2. Find the reason first: activity feed, then comments, then description notes. Fall back to the web UI or ask; never read credential files. A pause without a comment means: ask the overseer.
3. Don't change status behind a running Factory. Fix the spec and dependencies, then ask the overseer to resume.
4. Classify and act, nine cases:
   • underspecified or contradictory spec;
   • needs a human decision;
   • blocked on another Task;
   • Factory or tooling bug;
   • acceptance a worker can't meet before merge;
   • needs access;
   • duplicate;
   • a "done" prerequisite that never shipped;
   • churn.
5. Batch per epic with tasks update, since tasks review needs the plan's receipt file.
6. CLI pitfalls: --tag replaces the whole tag set, zsh doesn't split a string of flags, pass long descriptions from a file, and create human-only Tasks paused with a human tag.
7. Comment every status change.

Test plan

• Sections 1–7 are numbered in order, with no stale cross-references.
• The model guidance is harness-neutral, and Claude Code names appear only as examples.
• The audit section is gated on an explicit user request.

🤖 Generated with Claude Code