f2064ba67c
Remove ESCALATED signal and escalation handling from planner, supervisor, and gardener. When blocked on external resources or human decisions, these agents now file vault procurement items (vault/pending/*.md) instead of escalating directly to the human. Changes: - Planner formula: ESCALATED signal replaced with HUMAN_BLOCKED; files vault items and marks prerequisites as blocked-on-vault - Supervisor formula/prompt: escalation sections replaced with vault item filing; preflight now reports pending vault items instead of escalation replies - Gardener formula: ESCALATE action replaced with VAULT action; files vault/pending/*.md for human decisions - Groom-backlog formula: same ESCALATE→VAULT replacement - Gardener shell: PHASE:escalate replaced with PHASE:failed for merge blocks and CI exhaustion; escalation reply consumption removed - Supervisor shell: escalation reply consumption removed from both supervisor-run.sh and legacy supervisor-poll.sh - Prerequisite tree: #466 updated from "escalated" to "blocked-on-vault" The vault is the factory's only interface to the human for resources and approvals. Dev/action agents retain PHASE:escalate for operational session issues (CI timeouts, merge blocks) which are a different mechanism. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
4.9 KiB
Planner Agent
Role: Strategic planning using a Prerequisite Tree (Theory of Constraints),
executed directly from cron via tmux + Claude.
Phase 0 (preflight): pull latest code, load persistent memory and prerequisite
tree from planner/MEMORY.md and planner/prerequisite-tree.md. Also reads
all available formulas: factory formulas ($FACTORY_ROOT/formulas/*.toml) and
project-specific formulas ($PROJECT_REPO_ROOT/formulas/*.toml). Phase 1
(prediction-triage): triage prediction/unreviewed issues filed by the
Predictor — for each prediction, the planner must act or dismiss with a
stated reason (no fence-sitting, no prediction/backlog label). Actions:
promote to a real issue (relabel to prediction/actioned, close) or
dismiss (comment reason, relabel to prediction/dismissed, close).
The planner has a per-run action budget — it cannot defer indefinitely.
Dismissed predictions get re-filed by the predictor with stronger evidence
if still valid. Phase 2
(update-prerequisite-tree): scan repo state + open/closed issues, mark resolved
prerequisites, discover new ones, update the tree. Also scans comments on
referenced issues for bounce/stuck signals (BOUNCED, LABEL_CHURN)
to detect issues ping-ponging between backlog and underspecified. Issues that
need human decisions or external resources are filed as vault procurement items
(vault/pending/*.md) instead of being escalated. Phase 3
(file-at-constraints): identify the top 3 unresolved prerequisites that block
the most downstream objectives — file issues as either backlog (code changes,
dev-agent) or action (run existing formula, action-agent). Stuck issues
(detected BOUNCED/LABEL_CHURN) are dispatched to the groom-backlog formula
in breakdown mode instead of being re-promoted — this breaks the ping-pong
loop by splitting them into dev-agent-sized sub-issues. Human-blocked issues
are routed through the vault — the planner files a procurement item and marks
the prerequisite as blocked-on-vault in the tree.
Phase 4 (journal-and-memory): write updated prerequisite tree + daily journal
entry (committed to git) and update planner/MEMORY.md (committed to git).
Phase 5 (commit-and-pr): one commit with all file changes, push, create PR.
AGENTS.md maintenance is handled by the Gardener.
Artifacts use $PROJECT_REPO_ROOT: All planner artifacts (journal,
prerequisite tree, memory, vault state) live under $PROJECT_REPO_ROOT/planner/
and $PROJECT_REPO_ROOT/vault/, not $FACTORY_ROOT. Each project manages its
own planner state independently.
Trigger: planner-run.sh runs daily via cron (accepts an optional project
TOML argument, defaults to projects/disinto.toml). Sources lib/guard.sh and
calls check_active planner first — skips if $FACTORY_ROOT/state/.planner-active
is absent. Then creates a tmux session with claude --model opus, injects
formulas/run-planner.toml as context, monitors the phase file, and cleans up
on completion or timeout. No action issues — the planner is a nervous system
component, not work.
Key files:
planner/planner-run.sh— Cron wrapper + orchestrator: lock, memory guard, sources disinto project config, builds structural analysis vialib/formula-session.sh:build_graph_section(), creates tmux session, injects formula prompt, monitors phase file, handles crash recovery, cleans upformulas/run-planner.toml— Execution spec: six steps (preflight, prediction-triage, update-prerequisite-tree, file-at-constraints, journal-and-memory, commit-and-pr) withneedsdependencies. Claude executes all steps in a single interactive session with tool accessformulas/groom-backlog.toml— Dual-mode formula: grooming (default) or breakdown (dispatched by planner for bounced/stuck issues — splits the issue into dev-agent-sized sub-issues, removesunderspecifiedlabel)planner/prerequisite-tree.md— Prerequisite tree: versioned constraint map linking VISION.md objectives to their prerequisites. Planner owns the tree, humans steer by editing VISION.md. Tree grows organically as the planner discovers new prerequisites during runsplanner/MEMORY.md— Persistent memory across runs (committed to git)planner/journal/*.md— Daily raw logs from each planner run (committed to git)
Constraint focus: The planner uses Theory of Constraints to avoid premature issue filing. Only the top 3 unresolved prerequisites that block the most downstream objectives get filed as issues. Everything else exists in the prerequisite tree but NOT as issues. This prevents the "spray issues across all milestones" pattern that produced premature work in planner v1/v2.
Environment variables consumed:
FORGE_TOKEN,FORGE_REPO,FORGE_API,PROJECT_NAME,PROJECT_REPO_ROOTPRIMARY_BRANCH,CLAUDE_MODEL(set to opus by planner-run.sh)MATRIX_TOKEN,MATRIX_ROOM_ID,MATRIX_HOMESERVER