fix: feat: planner v2 — prerequisite tree + resource-aware executive (#502)

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

planner/AGENTS.md

@@ -1,19 +1,22 @@
 <!-- last-reviewed: 80a64cd3e4d2836bfab3c46230a780e3e233125d -->
 # Planner Agent
 
-**Role**: Strategic planning, executed directly from cron via tmux + Claude.
-Phase 0 (preflight): pull latest code, load persistent memory from
-`planner/MEMORY.md`. Phase 1 (prediction-triage): triage
-`prediction/unreviewed` issues filed by the Predictor — for each prediction:
-promote to action, promote to backlog, watch (relabel to prediction/backlog),
-or dismiss with reasoning. Promoted predictions compete with vision gaps for
-the per-cycle issue limit. Phase 2 (strategic-planning): resource+leverage gap
-analysis — reasons about VISION.md, RESOURCES.md, formula catalog, and project
-state to create up to 5 total issues (including promotions) prioritized by
-leverage. Phase 3 (journal-and-memory): write daily journal entry (committed to
-git) and update `planner/MEMORY.md` (committed to git). Phase 4 (commit-and-pr):
-one commit with all file changes, push, create PR. AGENTS.md maintenance is
-handled by the Gardener.
+**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`. Phase 1
+(prediction-triage): triage `prediction/unreviewed` issues filed by the
+Predictor — for each prediction: promote to action, promote to backlog, watch
+(relabel to prediction/backlog), or dismiss with reasoning. Phase 2
+(update-prerequisite-tree): scan repo state + open/closed issues, mark resolved
+prerequisites, discover new ones, update the tree. Phase 3
+(file-at-constraints): identify the top 3 unresolved prerequisites that block
+the most downstream objectives — file issues ONLY at these constraints. No
+issues filed past the bottleneck. 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.
 
 **Trigger**: `planner-run.sh` runs daily via cron (accepts an optional project
 TOML argument, defaults to `projects/disinto.toml`). It creates a tmux session
@@ -25,18 +28,22 @@ issues — the planner is a nervous system component, not work.
 - `planner/planner-run.sh` — Cron wrapper + orchestrator: lock, memory guard,
   sources disinto project config, creates tmux session, injects formula prompt,
   monitors phase file, handles crash recovery, cleans up
-- `formulas/run-planner.toml` — Execution spec: five steps (preflight,
-  prediction-triage, strategic-planning, journal-and-memory, commit-and-pr)
-  with `needs` dependencies. Claude executes all steps in a single interactive
-  session with tool access
+- `formulas/run-planner.toml` — Execution spec: six steps (preflight,
+  prediction-triage, update-prerequisite-tree, file-at-constraints,
+  journal-and-memory, commit-and-pr) with `needs` dependencies. Claude
+  executes all steps in a single interactive session with tool access
+- `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 runs
 - `planner/MEMORY.md` — Persistent memory across runs (committed to git)
 - `planner/journal/*.md` — Daily raw logs from each planner run (committed to git)
 
-**Future direction**: The Predictor files prediction issues daily for the planner
-to triage. The next step is evidence-gated deployment (see
-`docs/EVIDENCE-ARCHITECTURE.md`): replacing human "ship it" decisions with
-automated gates across dimensions (holdout, red-team, user-test, evolution
-fitness, protocol metrics, funnel). Not yet implemented.
+**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**:
 - `CODEBERG_TOKEN`, `CODEBERG_REPO`, `CODEBERG_API`, `PROJECT_NAME`, `PROJECT_REPO_ROOT`

planner/planner-run.sh

@@ -43,7 +43,7 @@ log "--- Planner run start ---"
 
 # ── Load formula + context ───────────────────────────────────────────────
 load_formula "$FACTORY_ROOT/formulas/run-planner.toml"
-build_context_block VISION.md AGENTS.md RESOURCES.md
+build_context_block VISION.md AGENTS.md RESOURCES.md planner/prerequisite-tree.md
 
 # ── Read planner memory ─────────────────────────────────────────────────
 MEMORY_BLOCK=""

planner/prerequisite-tree.md

@@ -0,0 +1,37 @@
+# Prerequisite Tree
+<!-- Last updated: 2026-03-21 — seeded from VISION.md -->
+
+## Objective: One-command bootstrap — `disinto init` (#393)
+- [x] Core agent loop stable (Foundation)
+- [x] Multi-project support (Foundation)
+- [x] Guard allows formula agents in worktrees (#487)
+- [ ] Bundled dust cleanup — set-euo-pipefail (#516)
+- [ ] Agent-session.sh pre-register worktree trust (#514)
+Status: BLOCKED — 2 prerequisites unresolved
+
+## Objective: Documentation site with quickstart (#394)
+- [ ] disinto init working (#393)
+Status: BLOCKED — prerequisite of prerequisite unresolved
+
+## Objective: Metrics dashboard (#395)
+- [ ] disinto init working (#393)
+- [ ] Supervisor formula stable
+Status: BLOCKED — prerequisite of prerequisite unresolved
+
+## Objective: Example project demonstrating full lifecycle (#466)
+- [ ] disinto init working (#393)
+Status: BLOCKED — prerequisite of prerequisite unresolved
+
+## Objective: Landing page communicating value proposition
+- [ ] disinto init working (#393)
+- [ ] Documentation site live (#394)
+Status: BLOCKED — prerequisite chain unresolved
+
+## Objective: Unified escalation path (#510)
+- [ ] Supervisor escalates prolonged needs_human (#465)
+Status: BLOCKED — 1 prerequisite unresolved
+
+## Objective: Vault as procurement gate + RESOURCES.md inventory (#504)
+- [x] RESOURCES.md exists
+- [ ] Vault poll operational
+Status: BLOCKED — 1 prerequisite unresolved