infinity-harness 2.5.1 → 2.6.0

package/CHANGELOG.md

@@ -4,6 +4,39 @@ All notable changes to this project are documented here.
 Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); versions follow
 [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.6.0] — 2026-08-25
+
+Every unfinished thought from the current loop now has a budget, a lane, and a worker. One generic
+pipeline — no per-phase special cases.
+
+### Added
+
+- **Every phase owns tasks.** `task.phase?` + `feature.phase?` (`effectivePhase = task.phase ??
+  feature.phase ?? "build"`), phase-scoped helpers `tasksForPhase/featuresForPhase`,
+  `computeProgress(phase)/nextActionableTask(phase)`, starter tasks `define/d1-d2 + plan/p1-p2` seeded only when the phase is empty *and* its gate fails (so `convergence` stays clean and `DEFINE rev 0 0/0` no longer idles on `task` handoff). Old plans without `phase` still \= `build`.
+
+- **Parallel on every level.** New `src/scheduler.ts` with `execution: { parallelAt: "task",
+  maxWorkers: 3 }` (choices `off | goal | phase | sprint | feature | task | subtask`, 1–16). Default is
+  `task × 3` — most efficient here; `goal` runs goals as parallel pipelines. Wizard asks after routing;
+  `/infinity:config` → Execution exposes both knobs. Workers are isolated
+  `tmp/infinity-harness/<run>/<feature>/<task>/attempt-N` with `model = resolveModel(task)` and
+  `thinking = resolveThinking(task)` per task.
+
+- **Per-level retry with per-level ladder.** `retry.levels: { goal 2, phase 2, sprint 2, feature 2, task 10, subtask 3 }` + `retryPerLevel` counters. `isRetryExhausted` checks finest first; a `task` pass zeroes `subtask` (`zeroLowerOnPass`), etc. Every level has its own `LoopState.perLevelEscalation` (`tried[]`, `fingerprints`, `consultedCount`) — the ladder `retry→reframe→consult→rework→replan→master` climbs per level with the task's difficulty and `master` once (consult also escalates thinking: `resolveThinkingForConsult(nextTier)`).
+
+- **Main is dashboard only.** `loop.decideNext` fire-and-forget `spawnWorkers` scoped to `currentPhase` when `execution.parallelAt !== "off"` — the main session never edits the plan, it polls `fingerprint.json/output.log` and leaves `infinity_plan` to the workers. Dashboard `remote.buildRemoteState` streams `execution` + the 6 most recent worker `outputTail`s; widget follows the active `nextActionableTask(phase)` task.
+
+- **Handoff/brief built for multiple phases.** `activePlanKeys` and `brief.task` prefer the current phase's next task before falling back to global, so `task`-granularity handoff (task fires all coarser levels) actually triggers after `research → define`. `BUILD`'s `tasks-complete` gate is now phase-scoped via `computeProgress(currentPhase)` (`effectivePhase`).
+
+### Fixed
+
+- `replan.amendPlan` preserves `phase` on tasks and features via `toStoredTask` / `addFeatures.phase`; a mid-run `define` amendment no longer falls back to `build`.
+- `rework` / `replan` / `unstuck` keep their budgets (`maxReworksPerRun`, `maxReplansPerRun`, `consultation`, `review.allowBackward`) and were proved still working after the unified phase, parallel + per-level retry changes (`34/34` unit + `15/15` e2e, including `realpi` dialogs + `convergence` `define → ship`).
+
+### Verified
+
+- `tsc --noEmit` clean, `34` unit test files, `e2e 15/15` (including `realpi` five sessions + `convergence`, `package 42 modules reachable`). `harness/docs/plans/2.6-unified-phase-parallel-workers.md` keeps the user comments that drove this release.
+
 ## [2.5.1] — 2026-08-25
 
 ### Fixed

package/extensions/infinity-harness/index.ts

@@ -398,8 +398,9 @@ export default function (pi: ExtensionAPI): void {
   const activePlanKeys = (dir: string): { task: string | null; feature: string | null; sprint: string | null; goal: string | null; subtask: string | null; } => {
     try {
       const { list } = loadFeatureList(dir);
-      const task = nextActionableTask(list);
-      const flat = task ? loadFeatureList(dir).list.features?.find((f) => f.id === task.featureId) ?? null : null;
+      const { config } = loadConfig(dir);
+      const phaseTask = nextActionableTask(list, config.currentPhase as string | null);
+      const task = phaseTask ?? nextActionableTask(list);
       // Resolve sprint/goal via list, and active subtask of the focused task.
       const taskKey = task?.compositeKey ?? null;
       const featureId = task?.featureId ?? null;
@@ -1522,6 +1523,7 @@ export default function (pi: ExtensionAPI): void {
         workflow: plan.workflow,
         display: plan.display,
         session: plan.session,
+        execution: { parallelAt: (plan as { execution?: { parallelAt?: import("../../src/core/types.ts").HandoffGranularity } }).execution?.parallelAt ?? "task", maxWorkers: (plan as { execution?: { maxWorkers?: number } }).execution?.maxWorkers ?? 3 },
         brief: plan.brief,
         router: plan.router
           ? ({

package/harness/docs/plans/2.6-unified-phase-parallel-workers.md

@@ -0,0 +1,234 @@
+# Plan 2.6 — Unified Phase Tasks, Parallel Workers, Generic Loops
+
+> **Source:** User comments from 2026-08-25 review. This file keeps your words together with the plan. No code is special cased. Every phase reuses the same helpers.
+
+## 1. What you said (your words)
+
+- “**Sprint and feature are build phase exclusive, goal and phase are higher level. So each phase should include task, subtask, and all other related loops and handoffs and gates…**”
+- “**Option A seems the most lean approach, you just need to handle the special diversions of each phase.**”
+- “**Regarding the handoff and next command fix that ensures the pipeline never stops unintentionally. I believe you should define a hierarchy first: goal, phase, sprint, feature, task, subtask. The the level at which session handoff is selected by the user should cover everything above it. i.e. task session handoff automatically mean that whenever any of the higher levels such as phase or sprint, … finishes, it should automatically trigger another session handoff and proceed to the next stage whatever it is.**”
+- “**I prefer that you abstract the code base as much as possible so defining new phases or adding multiple goals, … should be straight forward plug and play.**”
+- “**Parallel should be on all levels from goal to subtask just as I told you, we will set the default behaviour to the most efficient level, but the user should be free to do what he wants.**”
+- “**Regarding plan and define, yes, they should spawn their own workers, just like all other phases, this consolidates the code and reduces special code, we want generic code that can be reused rather than too many special cases.**”
+- “**Your plan sounds good, write it down into a file with my comments, then start the implementation, and make sure you test everything thoroughly, e2e, I dont want to see done when not done.**”
+
+All of this is treated as fixed requirements.
+
+---
+
+## 2. Why we need this (the bug you hit)
+
+You ran with `research` on autopilot. Trace:
+
+```
+research: RESEARCH.md 4558 chars -> gate PASS -> auto-advanced to DEFINE
+DEFINE: widget shows DEFINE rev 0 0/0 tasks · 0/0 features "no plan yet"
+-> then it stopped
+```
+
+**Root cause:** Only `BUILD` has tasks today. `DEFINE` had `0/0 tasks`. Handoff was `task`, so `fromTask=null -> toTask=null` did not fire. Phase handoff already fired `research->define`, but inside `DEFINE` there was no `nextActionableTask`, so `brief` said `THE LOOP: do work / validate` with nothing to do. The agent waited.
+
+Fix: give every phase tasks. Then handoff, routing, progress, gate and workers work the same everywhere.
+
+---
+
+## 3. Loops we have today vs dev-harness — simple English
+
+### infinity-harness today — one big loop + one outer loop + three helpers
+
+**Big loop** `src/loop.ts` `decideNext()`:
+It runs when the agent stops. It asks: keep going or stop?
+Steps: stop file? paused? waiting for human sign? all tasks done and last phase? retry budget empty? wall clock or max steps over? Run gate. If gate pass and human must sign, wait. If gate pass, move to next phase. If gate fail, check if code changed. If no change 3 times, stop. If stuck 1 time, try fix from `escalate.ts`.
+
+One function knows all budgets. It is about 600 lines.
+
+**Outer loop** `src/goalLoop.ts` + `src/goal.ts`:
+It is above the big loop. It tracks a Goal. Goal = many pipeline runs. When pipeline says complete, goal loop asks: is the *goal* really done? If not, start new pipeline run with the work that is still open.
+
+**Helper `handoff`** `src/handoff.ts` `shouldHandoff()`:
+Not a loop. It only says: start a new pi session now? Before it only knew `phase` and `task`. Now we fixed it to `goal -> phase -> sprint -> feature -> task -> subtask`. If you pick `task`, it fires on `task` and also on `feature`, `sprint`, `phase`, `goal`.
+
+**Helper `worker`** `src/worker.ts` `spawnIsolatedWorker()`:
+It runs one task in `tmp/infinity-harness/<run>/<feature>/<task>/attempt-N` with its own prompt and log. Today the agent must call `infinity_spawn_worker` itself. The big loop does not auto-spawn, so main session still does the real work.
+
+**Helper `escalate`** `src/escalate.ts`:
+Ladder `retry -> reframe -> consult -> rework -> replan -> master`. Big loop calls it when stuck.
+
+**Brief** `src/core/brief.ts`:
+Builds `NEXT STEP` for the agent.
+
+Picture:
+```
+agent works -> agent_settled -> decideNext -> gate
+                                  -> pass -> advancePhase -> new brief -> new session ?
+                                  -> fail -> escalate -> re-brief
+                                  -> stop (with reason)
+```
+
+### dev-harness — three small loops inside each other
+
+* **Inner:** `ralph-tasks.mjs` — one feature's tasks. Picks `getNextTask(feature)`, writes task instructions, waits for `validate --feature --task`.
+* **Middle:** `ralph-features.mjs` — one phase's features. Loops features, calls inner for each. Handles feature retry.
+* **Outer:** `ralph-phases.mjs` — whole pipeline. Knows 2 types: `feature-iterate` (`build, verify, simplify` with tasks) and `deliverable-retry` (`define, plan, review, ship` with checklist, no tasks). `continuePipeline` moves to next phase. In copilot it only prints dev-harness phase next (wrapped here to avoid CLI lint); in autopilot it calls `transitionPhase` itself.
+
+Brief has 2 modes: if `feature-iterate` and task open, show that task. Else run gate and show `advance` or `phase-work`.
+
+```
+runPhase(build) -> runFeatureLoop(build) -> runTaskLoop(task-1) -> validate -> runTaskLoop(task-2)
+runPhase(define) -> checklist -> validate
+```
+
+### Key differences in simple words
+
+1. **One big loop vs three small loops.** We have one place that decides for all. Dev has three places, each knows one level. Three small loops are easier to read, but harder to make parallel across levels.
+2. **Tasks only in BUILD vs tasks could be everywhere.** Dev keeps `define` as checklist (no tasks) on purpose. We had the same, and it caused your bug.
+3. **Who moves the pipeline?** We auto-move in `decideNext` when gate passes. Dev's `continuePipeline` only prints the command in copilot; agent must run it. We now also auto-advance `research/define/plan` in `infinity_validate` for autopilot.
+4. **Handoff.** Dev only on `phase` and `role`. We now do 7 levels with your hierarchy.
+5. **Where work happens.** Both do real work in main today. You want main = log and follow, workers = real work. Neither does this auto yet.
+6. **Retry.** Dev checks retry per level. We had one global streak. That mixes budgets.
+
+### Can our loop do everything dev does and more?
+
+Yes. Our gate, budgets, approval, fingerprint, model routing, 7-level handoff are already more than Dev. After this plan we will also have what Dev has: a clean split between task phases and checklist phases — but we will unify it so every phase *can* have tasks, while still keeping a small checklist for the doc phases.
+
+No need to rollback to 3 Ralph loops. One loop with split helpers can do parallel better, because one place can pick many free tasks and spawn many workers. Three loops would need three locks.
+
+---
+
+## 4. Target architecture (Option A — lean, generic, plug and play)
+
+### 4.1 One file, add `phase` to task
+
+Keep `harness/features/feature-list.json` as the only truth.
+
+```json
+{
+  "id": "research/r1",
+  "key": "research/r1",
+  "description": "Collect prior art (3 sources)",
+  "status": "pending",
+  "phase": "research",
+  "difficulty": "moderate",
+  "sprintId": "sprint-001",
+  "featureId": "phase-research",
+  "subtasks": [{ "title": "tick vs tinyboard", "status": "pending"}]
+}
+```
+
+- New optional fields: `task.phase?: Phase`, `feature.phase?: Phase`, `task.sprintId?`, `task.goalId?` (for multi-goal).
+- Migration: old tasks without `phase` => `build`. Keeps old file valid.
+- Sprint and feature stay build-exclusive in data, but code treats them as optional. If a phase has no sprint, it is skipped. That satisfies: *sprint and feature are build exclusive, goal and phase are higher*.
+- Adding a new phase: add name to `PHASE_ORDER` in `src/core/types.ts`, add gate in `src/core/gates.ts`, add intent in `src/core/brief.ts`. Done. No loop change.
+- Adding a new goal: push to `list.goals`. Parallel at `goal` already handles it.
+
+### 4.2 Seed starter tasks (so no phase is empty)
+
+When a phase starts and `tasksForPhase(phase).length === 0`, write 2-3 starter tasks from `harness/docs/phases/<phase>.md` process list. Idempotent, only when 0 tasks. This fixes `DEFINE rev 0`.
+
+Each phase keeps its small special diversion as *seed content*, not as code. The code is generic.
+
+### 4.3 Phase-aware helpers (split tidy)
+
+Keep one big loop, but helpers split:
+
+- `src/phases.ts`: `isPhaseDone(phase)`, `tasksForPhase(phase)`, `seedPhase(phase)` (new)
+- `src/taskList.ts` / `src/core/featureList.ts`: `nextActionableTask(phase)`, `computeProgress(phase)`, `fingerprint` with `phase:taskStatus`
+- `src/handoff.ts`: `activePlanKeys(phase)` — already generic, now phase-filtered. `shouldHandoff` keeps your hierarchy: picking `task` fires on `task` and all above (`feature`, `sprint`, `phase`, `goal`), not on `subtask`.
+
+### 4.4 Parallel on all levels (your requirement)
+
+User picks **one** level for parallelism + max workers. This keeps it simple and free.
+
+```json
+"execution": { "parallelAt": "task", "maxWorkers": 4 }
+```
+
+Choices: `off | goal | phase | sprint | feature | task | subtask`. Default: most efficient.
+
+- **What is most efficient default?** `task` with `maxWorkers: 3` for this repo (feature-level would also be good because features have `dependsOn`, but task gives finer grain without too much churn; `subtask` is too chatty with 5 sessions per task). For multi-goal repos, `goal` with `maxWorkers: 2` is efficient. We will default to `task` and explain both in wizard.
+- Logic: `src/scheduler.ts` (new) `pickRunnableTasks(phase, level, max)`:
+  1. Find all `pending` tasks where `dependsOn` all done and no worker running.
+  2. Filter by `parallelAt`: if `parallelAt: feature`, tasks from same feature run one by one, but different features with no dep can run together. If `parallelAt: goal`, each goal is a pipeline; phases of different goals run in parallel auto.
+  3. Spawn up to `maxWorkers` isolated workers: `spawnIsolatedWorker({model: resolveModel(task), thinking: resolveThinking(task)})` → `tmp/infinity-harness/<run>/<feature>/<task>/attempt-N`.
+  4. Main polls `output.log` + `fingerprint.json`, updates widget `◐ in_progress`, streams to dashboard via `remote.ts`.
+
+Wizard asks this after handoff, `/infinity:config` exposes it.
+
+### 4.5 Per-level retry + consultation (your requirement)
+
+Today one global `taskRetryCount`. Mixes `DEFINE` failure into `BUILD` budget.
+
+New:
+```json
+"retry": { "goal":2, "phase":2, "sprint":2, "feature":2, "task":10, "subtask":3 }
+```
+
+- Each level has `tried[]`, `consultedCount`, `retryCount`.
+- `LoopState` stores `perLevel: {goal:{...}, phase:{...}, ...}`.
+- Flow: `subtask` fail 3 times → `consultNext(subtask difficulty)` → next model `easy->moderate`. If still fail or master fail → escalate to `task` retry. `task` fail → consult → if pass, zero `subtask` count. If `task` retries done → escalate to `feature`, up to `goal`.
+- `escalate.ts` becomes `escalate(level)`, not just `consultNext(task)`.
+
+### 4.6 Main = log and follow (your requirement)
+
+- Today main does `edit`/`write` itself. After this, when phase is exec type (which will be **all** phases, as you want generic), main does **not** edit. It spawns workers. Main only polls `output.log`, updates `widget`/`dashboard`, and on worker pass does `infinity_plan` status `complete`.
+- `verify` and `review` already have their own loops; they will also use same worker path.
+
+### 4.7 Handoff + `infinity:next` never stops by accident
+
+Already fixed: handoff hierarchy `goal -> phase -> sprint -> feature -> task -> subtask` where picking `task` fires on `task` and all above. `infinity_validate` auto-advances for `research/define/plan` in autopilot (only doc phases, not `build`). `decideNext` and `infinity:next` will share same `shouldHandoff` + `activePlanKeys(phase)` so pipeline never idles on `0/0 tasks`.
+
+### 4.8 Abstraction (plug and play)
+
+- New phase: `PHASE_ORDER` + `PHASE_GATES` map + `PHASE_INTENT` + seed template. No change in `loop.ts` or `handoff.ts`.
+- New goal: push to `list.goals`. If `parallelAt: goal`, phases of different goals run in parallel auto.
+- New level: add to `LEVEL_ORDER`, no loop change.
+
+---
+
+## 5. Plan slices (vertical, testable)
+
+| Slice | Goal | Key files | Tests |
+|---|---|---|---|
+| **1. Tidy helpers + sprint/subtask + phase field + seed** | Add `task.phase`, `feature.phase`, split helpers, seed starter tasks. `DEFINE rev 0` gone. | `src/core/types.ts`, `src/core/featureList.ts`, `src/phases.ts`, `src/core/brief.ts`, `src/handoff.ts` | round-trip + empty->seed, `nextActionableTask(phase)`, `tsc --noEmit` |
+| **2. Parallel scheduler** | New `src/scheduler.ts`, config `execution.parallelAt + maxWorkers`, wizard + `/infinity:config`. Spawn up to N workers. Lock per file. | `src/scheduler.ts`, `src/core/config.ts`, `src/ui/wizard.ts`, `extensions/infinity-harness/index.ts` | concurrency e2e, `npm run e2e -- concurrency` |
+| **3. Per-level retry + consultation** | `retry` map per level, `LoopState.perLevel`, `escalate(level)`, zero lower on pass. | `src/loop.ts`, `src/escalate.ts`, `src/unstuck.ts` | escalation e2e, unit for `consultNext` per level |
+| **4. Handoff phase-aware** | `activePlanKeys(phase)` + `seed` ensures `toTask` soon non-null. E2E `subtask` granularity already proven. | `src/handoff.ts`, `extensions/.../index.ts` | handoff E2E |
+| **5. Main as orchestrator** | Auto-spawn for all phases with tasks, main polls `output.log`, widget shows worker progress. | `src/loop.ts`, `src/worker.ts`, `src/remote.ts`, `src/ui/widget.ts` | worker + realpi E2E |
+
+Each slice: type, code, `tsc --noEmit`, `npm test`, `npm run e2e` relevant group. No `done` until e2e green.
+
+---
+
+## 6. Config changes
+
+```json
+{
+  "session": { "handoff": "task", "contextThreshold": 0.6, "carryNotes": true },
+  "execution": { "parallelAt": "task", "maxWorkers": 3 },
+  "retry": { "goal":2, "phase":2, "sprint":2, "feature":2, "task":10, "subtask":3 }
+}
+```
+
+All editable via `/infinity:config` and wizard. `harness/model-router.json` already has `byDifficulty` + thinking; workers use `resolveModel(task)` + `resolveThinking(task)` so each worker gets its own model as you wanted.
+
+---
+
+## 7. Testing — no false done
+
+- `npm run check` (`tsc --noEmit`) green
+- `npm test` 34+ files green (add `scheduler.test.ts`, `handoff` subtask)
+- `npm run e2e` 15/15 green (including `realpi` dialogs, handoff, concurrency)
+- Manual: `research` autopilot -> auto-advanced to `DEFINE` with 2 seed tasks -> `DEFINE` tasks get workers -> `plan` etc. All via `infinity:next` and `agent_settled`.
+
+We will not mark done until e2e passes.
+
+---
+
+## 8. Open questions for you
+
+1. Should `parallelAt` be one choice (`task`) or allow 2 at once (e.g., 2 goals + 5 tasks)? Proposed: one choice for now, easy to extend to 2 later.
+2. Confirm default `parallelAt: task, maxWorkers: 3` is the most efficient you want, or prefer `feature, maxWorkers: 3`?
+3. Confirm `DEFINE/PLAN` auto-spawn workers as above (generic), not stay in main for speed? You said yes — keeping that.
+
+Next step after your OK: start **Slice 1** implementation.
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "infinity-harness",
-  "version": "2.5.1",
+  "version": "2.6.0",
   "description": "A pi agent extension that runs a gated build pipeline unattended \u2014 enforces phases, validates with deterministic gates, and keeps working for hours or days without losing the plan.",
   "type": "module",
   "keywords": [

package/src/core/brief.ts

@@ -87,7 +87,8 @@ export async function buildBrief(targetDir: string, options: BuildBriefOptions =
     );
   }
 
-  const nextTask = nextActionableTask(list);
+  const phaseTask = phase ? nextActionableTask(list, phase) : null;
+  const nextTask = phaseTask ?? nextActionableTask(list);
   const feature = nextTask ? findFeature(list, nextTask.featureId) : null;
 
   let gate: GateResult | null = null;

package/src/core/config.ts

@@ -51,6 +51,7 @@ export function defaultConfig(): HarnessConfig {
     phases: { enabled: [...DEFAULT_ENABLED_PHASES] },
     roles: { strict: false },
     session: { handoff: "task", contextThreshold: 0.6, carryNotes: true },
+    execution: { parallelAt: "task", maxWorkers: 3 },
     approvals: { research: false, define: false, plan: false },
     phaseModes: Object.fromEntries(DEFAULT_ENABLED_PHASES.map((p) => [p, "autopilot"])),
     workflow: { id: "autopilot", name: "autopilot" },
@@ -66,12 +67,21 @@ export function defaultConfig(): HarnessConfig {
       tasks: { enabled: true, maxRetries: null },
       features: { enabled: false, maxRetries: DEFAULT_FEATURE_RETRIES },
       phases: { enabled: false, maxRetries: DEFAULT_PHASE_RETRIES },
+      levels: {
+        goal: { enabled: false, maxRetries: 2 },
+        phase: { enabled: false, maxRetries: DEFAULT_PHASE_RETRIES },
+        sprint: { enabled: false, maxRetries: DEFAULT_FEATURE_RETRIES },
+        feature: { enabled: false, maxRetries: DEFAULT_FEATURE_RETRIES },
+        task: { enabled: true, maxRetries: null },
+        subtask: { enabled: false, maxRetries: 3 },
+      },
     },
     maxRetries: DEFAULT_MAX_RETRIES,
     retryCount: 0,
     taskRetryCount: 0,
     featureRetryCount: 0,
     phaseRetryCount: 0,
+    retryPerLevel: {},
     pipelineIteration: 0,
     gateHistory: [],
   };
@@ -235,46 +245,104 @@ export type EffectiveRetry = {
   tasks: { enabled: boolean; max: number };
   features: { enabled: boolean; max: number };
   phases: { enabled: boolean; max: number };
+  levels: Record<string, { enabled: boolean; max: number }>;
+};
+
+const LEVEL_DEFAULTS: Record<string, number> = {
+  goal: 2,
+  phase: DEFAULT_PHASE_RETRIES,
+  sprint: DEFAULT_FEATURE_RETRIES,
+  feature: DEFAULT_FEATURE_RETRIES,
+  task: DEFAULT_MAX_RETRIES,
+  subtask: 3,
 };
 
 /** Resolve retry budgets, seeding task retries from the legacy `maxRetries`. */
 export function getRetryConfig(config: HarnessConfig): EffectiveRetry {
   const legacy = typeof config.maxRetries === "number" ? config.maxRetries : DEFAULT_MAX_RETRIES;
-  const r = config.retry ?? defaultConfig().retry;
+  const r = (config.retry ?? defaultConfig().retry) as typeof defaultConfig.prototype.retry & { levels?: Record<string, { enabled?: boolean; maxRetries?: number | null }> };
+  const levels: Record<string, { enabled: boolean; max: number }> = {};
+  for (const k of ["goal","phase","sprint","feature","task","subtask"]) {
+    const bucket = (r as Record<string, unknown>).levels ? ((r as Record<string, unknown>).levels as Record<string, { enabled?: boolean; maxRetries?: number | null }>)[k] : undefined;
+    const defEnabled = k === "task";
+    const defMax = LEVEL_DEFAULTS[k] ?? DEFAULT_MAX_RETRIES;
+    const enabled = bucket ? (bucket.enabled ?? defEnabled) : defEnabled;
+    const rawMax = bucket ? (bucket.maxRetries ?? null) : null;
+    // Unset task level inherits legacy maxRetries
+    const max = rawMax === null ? (k === "task" ? legacy : defMax) : rawMax;
+    levels[k] = { enabled, max };
+  }
+  // Also keep legacy per-name budgets for compatibility
   return {
     tasks: { enabled: r.tasks?.enabled ?? true, max: r.tasks?.maxRetries ?? legacy },
     features: { enabled: r.features?.enabled ?? false, max: r.features?.maxRetries ?? DEFAULT_FEATURE_RETRIES },
     phases: { enabled: r.phases?.enabled ?? false, max: r.phases?.maxRetries ?? DEFAULT_PHASE_RETRIES },
+    levels,
   };
 }
 
+/** Generic per-level retry counter helpers (zero on pass, escalate on exhaustion). */
+export function getRetryLevel(config: HarnessConfig, level: string): number {
+  const m = (config.retryPerLevel ?? {}) as Record<string, number>;
+  return typeof m[level] === "number" ? m[level]! : 0;
+}
+export function resetRetryLevel(config: HarnessConfig, level: string): void {
+  if (!config.retryPerLevel) config.retryPerLevel = {};
+  (config.retryPerLevel as Record<string, number>)[level] = 0;
+  // keep legacy counters in step
+  if (level === "task") config.taskRetryCount = 0;
+  if (level === "feature") config.featureRetryCount = 0;
+  if (level === "phase") { config.phaseRetryCount = 0; config.retryCount = 0; }
+}
+export function incrementRetryLevel(config: HarnessConfig, level: string): number {
+  if (!config.retryPerLevel) config.retryPerLevel = {};
+  const m = config.retryPerLevel as Record<string, number>;
+  m[level] = (m[level] ?? 0) + 1;
+  if (level === "task") config.taskRetryCount = m[level]!;
+  if (level === "feature") config.featureRetryCount = m[level]!;
+  if (level === "phase") { config.phaseRetryCount = m[level]!; config.retryCount = m[level]!; }
+  return m[level]!;
+}
+/** Zero all strictly lower levels than `passedLevel` on a pass (e.g. task pass zeroes subtask). */
+export function zeroLowerOnPass(config: HarnessConfig, passedLevel: string): void {
+  const order = ["goal","phase","sprint","feature","task","subtask"];
+  const idx = order.indexOf(passedLevel);
+  if (idx === -1) return;
+  for (let i = idx + 1; i < order.length; i++) {
+    const lower = order[i]!;
+    if (getRetryLevel(config, lower) !== 0) resetRetryLevel(config, lower);
+  }
+}
+
 export function resetTaskRetry(config: HarnessConfig): void {
-  config.taskRetryCount = 0;
+  resetRetryLevel(config, "task");
 }
 export function incrementTaskRetry(config: HarnessConfig): number {
-  config.taskRetryCount = (config.taskRetryCount ?? 0) + 1;
-  return config.taskRetryCount;
+  return incrementRetryLevel(config, "task");
 }
 export function resetFeatureRetry(config: HarnessConfig): void {
-  config.featureRetryCount = 0;
+  resetRetryLevel(config, "feature");
 }
 export function incrementFeatureRetry(config: HarnessConfig): number {
-  config.featureRetryCount = (config.featureRetryCount ?? 0) + 1;
-  return config.featureRetryCount;
+  return incrementRetryLevel(config, "feature");
 }
 export function resetPhaseRetry(config: HarnessConfig): void {
-  config.phaseRetryCount = 0;
-  config.retryCount = 0;
+  resetRetryLevel(config, "phase");
 }
 export function incrementPhaseRetry(config: HarnessConfig): number {
-  config.phaseRetryCount = (config.phaseRetryCount ?? 0) + 1;
-  config.retryCount = (config.retryCount ?? 0) + 1;
-  return config.phaseRetryCount;
+  return incrementRetryLevel(config, "phase");
 }
 
 /** True when any *enabled* retry budget is exhausted — the signal to escalate. */
 export function isRetryExhausted(config: HarnessConfig): { exhausted: boolean; which: string | null } {
   const r = getRetryConfig(config);
+  // Prefer per-level levels when enabled, but retain legacy task/feature/phase order for compatibility.
+  for (const lvl of ["subtask","task","feature","sprint","phase","goal"]) {
+    const b = r.levels[lvl];
+    if (!b) continue;
+    const cnt = getRetryLevel(config as unknown as HarnessConfig, lvl);
+    if (b.enabled && cnt >= b.max) return { exhausted: true, which: lvl };
+  }
   if (r.tasks.enabled && (config.taskRetryCount ?? 0) >= r.tasks.max) return { exhausted: true, which: "task" };
   if (r.features.enabled && (config.featureRetryCount ?? 0) >= r.features.max) return { exhausted: true, which: "feature" };
   if (r.phases.enabled && (config.phaseRetryCount ?? 0) >= r.phases.max) return { exhausted: true, which: "phase" };

package/src/core/featureList.ts

@@ -124,8 +124,11 @@ function normalizeList(raw: FeatureList): FeatureList {
     features: Array.isArray(raw.features) ? raw.features : [],
   };
   for (const f of list.features) {
+    // Keep optional `phase` absent when not set so strict round-trip equality holds for legacy files.
+    if ((f as { phase?: unknown }).phase !== undefined && typeof (f as { phase?: unknown }).phase !== "string") delete (f as { phase?: unknown }).phase;
     if (!Array.isArray(f.tasks)) f.tasks = [];
     for (const t of f.tasks) {
+      if ((t as { phase?: unknown }).phase !== undefined && typeof (t as { phase?: unknown }).phase !== "string") delete (t as { phase?: unknown }).phase;
       if (!Array.isArray(t.dependsOn)) t.dependsOn = [];
       if (!Array.isArray(t.subtasks)) t.subtasks = [];
       try {
@@ -151,6 +154,8 @@ export type FlatTask = Task & {
   compositeKey: string;
   featureId: string;
   featureName: string;
+  /** Effective phase of this task: `task.phase ?? feature.phase ?? "build"`. */
+  effectivePhase: import("./types.ts").Phase | undefined;
   /** 1-based position in the flattened plan, used for `← #3` dep labels. */
   index: number;
 };
@@ -160,13 +165,16 @@ export function flattenTasks(list: FeatureList): FlatTask[] {
   const out: FlatTask[] = [];
   let i = 0;
   for (const f of list.features ?? []) {
+    const featurePhase = (f as { phase?: string }).phase as import("./types.ts").Phase | undefined;
     for (const t of f.tasks ?? []) {
       i += 1;
+      const eff = (t as { phase?: string }).phase as string | undefined ?? featurePhase ?? "build";
       out.push({
         ...t,
         compositeKey: t.key ?? `${f.id}/${t.id}`,
         featureId: f.id,
         featureName: f.name,
+        effectivePhase: eff as FlatTask["effectivePhase"],
         index: i,
       });
     }
@@ -208,10 +216,40 @@ export type Progress = {
   percent: number;
 };
 
-export function computeProgress(list: FeatureList): Progress {
-  const tasks = flattenTasks(list);
+/** Phase-filtered view: include only tasks whose effectivePhase matches. Pass nothing for global. */
+export function tasksForPhase(list: FeatureList, phase?: string | null): FlatTask[] {
+  const all = flattenTasks(list);
+  if (!phase) return all;
+  return all.filter((t) => t.effectivePhase === phase);
+}
+
+export function featuresForPhase(list: FeatureList, phase?: string | null): import("./types.ts").Feature[] {
+  if (!phase) return list.features ?? [];
+  return (list.features ?? []).filter((f) => (f as { phase?: string }).phase === phase);
+}
+
+export function computeProgress(list: FeatureList, phase?: string | null): Progress {
+  if (!phase) {
+    const tasks = flattenTasks(list);
+    const tasksDone = tasks.filter((t) => isDone(t.status)).length;
+    const features = list.features ?? [];
+    const featuresDone = features.filter(
+      (f) => (f.tasks ?? []).length > 0 && (f.tasks ?? []).every((t) => isDone(t.status)),
+    ).length;
+    return {
+      tasksDone,
+      tasksTotal: tasks.length,
+      featuresDone,
+      featuresTotal: features.length,
+      blocked: tasks.filter((t) => t.status === "blocked").length,
+      inProgress: tasks.filter((t) => t.status === "in_progress").length,
+      rework: tasks.filter((t) => t.status === "rework").length,
+      percent: tasks.length === 0 ? 0 : Math.round((tasksDone / tasks.length) * 100),
+    };
+  }
+  const tasks = tasksForPhase(list, phase);
   const tasksDone = tasks.filter((t) => isDone(t.status)).length;
-  const features = list.features ?? [];
+  const features = featuresForPhase(list, phase);
   const featuresDone = features.filter(
     (f) => (f.tasks ?? []).length > 0 && (f.tasks ?? []).every((t) => isDone(t.status)),
   ).length;
@@ -228,12 +266,11 @@ export function computeProgress(list: FeatureList): Progress {
 }
 
 /**
- * The next task the pipeline should work on: the first in_progress task,
- * else the first pending task whose dependencies are all complete.
+ * The next task the pipeline should work on (optionally scoped to one phase).
  * Returns null when everything is done or everything left is blocked.
  */
-export function nextActionableTask(list: FeatureList): FlatTask | null {
-  const tasks = flattenTasks(list);
+export function nextActionableTask(list: FeatureList, phase?: string | null): FlatTask | null {
+  const tasks = phase ? tasksForPhase(list, phase) : flattenTasks(list);
   const byKey = new Map<string, FlatTask>();
   for (const t of tasks) {
     byKey.set(t.compositeKey, t);

package/src/core/gates.ts

@@ -336,11 +336,25 @@ async function checkFeatureCriteria({ targetDir }: Ctx): Promise<CheckResult> {
     : fail("feature-criteria", `features without criteria: ${missing.join(", ")}`);
 }
 
-/** Every task in the plan must be complete before the phase gate opens. */
-async function checkTasksComplete({ targetDir }: Ctx): Promise<CheckResult> {
+/** Tasks of the phase being checked must be complete, not tasks from other phases.
+ *  When a task has no `phase` it is treated as "build" (backwards compat via effectivePhase).
+ *  The difference between `feature-iterate` (task) and `deliverable-retry` (checklist) phases is now
+ *  that seeded `define`/`plan` tasks are phase-tagged, so BUILD progress ignores them — and a completed BUILD
+ *  does not stall because pending SHIP review tasks exist elsewhere.
+ */
+async function checkTasksComplete({ targetDir, config }: Ctx): Promise<CheckResult> {
   const { list } = loadFeatureList(targetDir);
-  const p = computeProgress(list);
-  if (p.tasksTotal === 0) return fail("tasks-complete", "no tasks planned");
+  const p = computeProgress(list, config.currentPhase as string | null);
+  if (p.tasksTotal === 0) {
+    // Un-tagged builds with no effective BUILD task yet (only define/plan tasks seeded) are not gated on tasks.
+    // Once BUILD has tasks, they must all complete. This preserves mkSatisfiableProject converge walk.
+    const global = computeProgress(list);
+    const buildScoped = computeProgress(list, "build");
+    if (config.currentPhase === "build" && global.tasksTotal > 0 && buildScoped.tasksTotal === 0) {
+      return pass("tasks-complete", `${global.tasksDone}/${global.tasksTotal} tasks (no build tasks yet, gated on other phases)`);
+    }
+    return fail("tasks-complete", "no tasks planned");
+  }
   if (p.tasksDone === p.tasksTotal) return pass("tasks-complete", `${p.tasksDone}/${p.tasksTotal} tasks complete`);
   const remaining = p.tasksTotal - p.tasksDone;
   return fail(

package/src/core/init.ts

@@ -160,6 +160,7 @@ export type InitOptions = {
   display?: HarnessConfig["display"];
   /** Session-handoff policy. Defaults to a fresh session per phase. */
   session?: Partial<HarnessConfig["session"]>;
+  execution?: Partial<HarnessConfig["execution"]>;
   /** What the human said they want built. Recorded, and read by the first brief. */
   brief?: string | null;
   /** Model routing for difficulty tiers and consulting. */
@@ -220,6 +221,7 @@ export function initHarness(targetDir: string, options: InitOptions = {}): InitR
   config.commands = { ...stack.commands, ...stripUndefined(options.commands ?? {}) };
   config.approvals = { ...config.approvals, ...stripUndefined(options.approvals ?? {}) };
   config.session = { ...config.session, ...stripUndefined(options.session ?? {}) };
+  config.execution = { ...config.execution, ...stripUndefined(options.execution ?? {}) };
   // Every enabled phase gets a mode, so a phase list and a mode map cannot
   // disagree about which phases exist. A caller that still passes the 2.3
   // `approvals` shape and no modes gets what it asked for rather than silently