@gonrocca/zero-pi 0.1.57 → 0.1.59

package/README.md

@@ -74,9 +74,13 @@ into `/forge` for you.
 | Feature | What it does |
 | ------- | ------------ |
 | **Strict TDD** | The build phase drives RED → GREEN → TRIANGULATE → REFACTOR with a TDD Cycle Evidence table; veredicto audits it. On by default, runtime-gated on a test runner; `tdd.mode: "off"` disables it. |
-| **`/zero-models`** | Pick the model + provider + thinking level for each SDD phase — a boxed-window picker, or set one directly. |
-| **Autotune** | Learns which model fits each phase from your run history and re-tunes itself. |
+| **`/zero-models`** | Pick the model + provider + thinking level for each SDD phase — a boxed-window picker, or set one directly. Direct assignments are validated against pi's model registry when available. |
+| **Phase tool gating** | Generated `zero-*` sub-agents get phase-specific tool allowlists: explore/veredicto are read-only, plan writes SDD artifacts, build edits code. |
+| **Dependency-aware tasks** | `tasks.md` is validated as a task graph with mandatory `depends:` edges, topological ordering, and review workload totals. |
+| **Autotune** | Learns which model fits each phase from your run history and re-tunes itself; optional `autotuneBudget.maxPhaseCostUsd` suppresses costly step-ups. |
+| **`/zero-doctor`** | Preflight diagnostics for zero-pi: package install, Node version, pi-subagents, generated phase agents, model config, `.sdd/config`, run history, git, and `gh` auth. |
 | **`/zero-cost`** | Aggregates a run's sub-agent `meta.json` files into a per-phase token/cost/duration report — no schema change, reads what pi already writes. |
+| **`/zero-checkpoint`** | Writes patch-based worktree checkpoints under `.sdd/<slug>/checkpoints/` before risky build batches. |
 | **`/zero-sync` / `/zero-archive`** | Folds each run's spec delta into a canonical, project-wide spec store and archives approved runs. |
 | **Git / PR / Issues** | `/zero-branch`, `/zero-git-validate`, `/zero-pr`, and `/zero-issue` keep branches and GitHub links audit-ready. |
 | **Run memory** | Every run recalls and saves traces to Cortex, so runs learn from each other. |
@@ -85,7 +89,7 @@ into `/forge` for you.
 | **Working-phrase ticker** | Swaps pi's `Working...` for a context-aware Spanish phrase + spinner. |
 | **Conversation resume** | Writes `.pi/zero-resume.md` on exit — the restore command + a conversation tail. |
 | **Windows tree-kill** | Aborting a turn kills the whole process tree — no orphaned `claude`. |
-| **Skill auto-learning** | Distills reusable skills from substantial tasks and surfaces them later. |
+| **SDD routing skill** | Natural-language requests that say "hacelo con sdd" route into `/forge` without remembering the slash command. |
 | **`zero-sdd` theme** | A dark, high-contrast pi theme tuned for SDD work. |
 | **`zero-sunset` theme** | A warm sunset variant — gold/coral/magenta accents over warm-dark panels, with one cool tone kept for syntax legibility. Activate with `/theme zero-sunset`. |
 
@@ -94,12 +98,14 @@ into `/forge` for you.
 | Command | Does |
 | ------- | ---- |
 | `/forge <feature>` | Run the SDD pipeline — `--continue [slug]` resumes. |
-| `/zero-models [<phase>=[<provider>/]<model> [thinking=<level>]]` | Show or set per-phase models, providers, and thinking — `thinking=<level>` (`off\|minimal\|low\|medium\|high\|xhigh`); `autotune=auto\|ask\|off`. |
+| `/zero-models [<phase>=[<provider>/]<model> [thinking=<level>]]` | Show or set per-phase models, providers, and thinking — `thinking=<level>` (`off\|minimal\|low\|medium\|high\|xhigh`); `autotune=auto\|ask\|off`. Direct assignments fail fast when pi's registry says the provider/model is unknown or ambiguous. |
+| `/zero-doctor` | Run zero-pi preflight diagnostics: package, Node, pi-subagents, generated agents/support modules, model config, `.sdd/config`, run history, git, and `gh`. |
 | `/zero-sync <slug>` | Fold a run's spec delta into the canonical spec store; a first all-`## ADDED` delta creates the store lazily. |
 | `/zero-archive <slug>` | Merge an approved run into `.sdd/specs/`, move it to `.sdd/archive/YYYY-MM-DD-<slug>/`, and persist `archivePath`. |
 | `/zero-validate <slug>` | Validate proposal/spec/design/tasks artifacts, including task schema and per-domain specs. |
 | `/zero-status` | Show each `.sdd/` run's artifact, sync, latest-verdict, and GitHub-link status. |
 | `/zero-cost [<slug>]` | Report tokens (in/out/cache), USD cost, duration, and tool-count per SDD phase for a run — `<slug>` for a specific run, no argument for the most recent. |
+| `/zero-checkpoint [<slug>] [--json]` | Save `diff.patch`, `status.txt`, `head.txt`, `meta.json`, and a review-before-running `restore.sh` under `.sdd/<slug>/checkpoints/<id>/`. |
 | `/zero-branch <slug>` | Create/reuse the configured SDD Git branch and persist `branch`/`baseBranch`. |
 | `/zero-git-validate <slug>` | Check worktree, branch, remote, `gh auth`, and verdict gating before PR/archive. |
 | `/zero-pr <slug>` | Create an audit-ready GitHub PR from a run that already has verdict `pasa`. |
@@ -109,7 +115,7 @@ into `/forge` for you.
 
 ### Git / PR / Issues
 
-Recommended flow: `/zero-branch <slug>` → `/zero-issue <slug>` → `/forge <slug>` → `/zero-git-validate <slug> --for=pr` → `/zero-pr <slug>` → `/zero-archive <slug>`.
+Recommended flow: `/zero-branch <slug>` → `/zero-issue <slug>` → `/forge <slug>` (the orchestrator validates plan artifacts and can create `/zero-checkpoint` before build) → `/zero-git-validate <slug> --for=pr` → `/zero-pr <slug>` → `/zero-archive <slug>`.
 
 `links.json` is forward-compatible and may contain:
 
@@ -180,14 +186,18 @@ conversation-resume note.
   "models":    { "explore": "claude-haiku-4-5", "build": "claude-sonnet-4-6" },
   "providers": { "explore": "anthropic",        "build": "anthropic" },
   "thinking":  { "explore": "low",              "build": "high" },
-  "autotune": "ask"
+  "autotune": "ask",
+  "autotuneBudget": { "maxPhaseCostUsd": 4, "minSamples": 3 }
 }
 ```
 
 The `thinking` map sets each phase's pi effort level — one of `off`, `minimal`,
 `low`, `medium`, `high`, `xhigh`. A phase with no entry gets no `thinking:` line
-in its generated sub-agent (no aggressive default). Set it from the picker's
-after-model thinking screen, or directly:
+in its generated sub-agent (no aggressive default). `autotuneBudget` is optional:
+when `maxPhaseCostUsd` is set, autotune will not step a blamed phase up to a more
+expensive tier if that phase/model is already at or above the average USD
+ceiling with enough cost samples (`minSamples`, default 3). Set thinking from
+the picker's after-model thinking screen, or directly:
 
 ```
 /zero-models build=anthropic/claude-sonnet-4-6 thinking=high

package/extensions/autotune-extension.ts

@@ -19,17 +19,20 @@
 // dependency-free: `node:fs`/`node:os`/`node:path`
 // only, plus minimal local interfaces for the pi API.
 
-import { readFileSync, writeFileSync } from "node:fs";
+import { existsSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
 
 import {
   aggregate,
+  aggregateCostStats,
   decideAdjustments,
   readAutotuneMode,
   readRunRecords,
   type Adjustment,
+  type AutotuneCostGuard,
 } from "./autotune.ts";
+import { parseMeta, type PhaseMeta } from "./zero-cost.ts";
 
 /** The SDD phases, in pipeline order. Mirrors `zero-models.ts`. */
 const PHASES = ["explore", "plan", "build", "veredicto"] as const;
@@ -104,6 +107,39 @@ function readCurrentModels(data: Record<string, unknown>): Partial<Record<Phase,
   return models;
 }
 
+function readCostGuard(data: Record<string, unknown>): AutotuneCostGuard {
+  const raw = isObject(data.autotuneBudget) ? data.autotuneBudget : {};
+  const guard: AutotuneCostGuard = {};
+  if (typeof raw.maxPhaseCostUsd === "number" && Number.isFinite(raw.maxPhaseCostUsd) && raw.maxPhaseCostUsd > 0) {
+    guard.maxPhaseCostUsd = raw.maxPhaseCostUsd;
+  }
+  if (typeof raw.minSamples === "number" && Number.isFinite(raw.minSamples) && raw.minSamples > 0) {
+    guard.minSamples = raw.minSamples;
+  }
+  return guard;
+}
+
+function readAllPhaseMetas(): PhaseMeta[] {
+  const root = join(homedir(), ".pi", "agent", "sessions");
+  if (!existsSync(root)) return [];
+  const out: PhaseMeta[] = [];
+  for (const session of readdirSync(root, { withFileTypes: true })) {
+    if (!session.isDirectory()) continue;
+    const artifacts = join(root, session.name, "subagent-artifacts");
+    if (!existsSync(artifacts)) continue;
+    for (const f of readdirSync(artifacts)) {
+      if (!f.endsWith("_meta.json")) continue;
+      try {
+        const meta = parseMeta(JSON.parse(readFileSync(join(artifacts, f), "utf8")));
+        if (meta) out.push(meta);
+      } catch {
+        // skip unreadable / malformed meta
+      }
+    }
+  }
+  return out;
+}
+
 /**
  * Derive `knownModels` — the distinct, non-empty model ids the autotune logic
  * may step toward. Per the design this is the union of every model seen in the
@@ -177,7 +213,9 @@ function evaluateAndTune(ctx: PiSessionContext): void {
   const knownModels = deriveKnownModels(currentModels, loggedModels);
 
   const stats = aggregate(records);
-  const adjustments: Adjustment[] = decideAdjustments(stats, currentModels, knownModels);
+  const costGuard = readCostGuard(data);
+  const costStats = costGuard.maxPhaseCostUsd ? aggregateCostStats(readAllPhaseMetas()) : new Map();
+  const adjustments: Adjustment[] = decideAdjustments(stats, currentModels, knownModels, costStats, costGuard);
   if (adjustments.length === 0) return; // nothing to do — return silently.
 
   if (mode === "auto") {

package/extensions/autotune.ts

@@ -265,6 +265,29 @@ export interface PhaseModelStat {
   avgReplantear: number | null;
 }
 
+export interface PhaseCostSample {
+  phase: unknown;
+  model: unknown;
+  usage: unknown;
+}
+
+export interface PhaseCostStat {
+  phase: (typeof RECORD_PHASES)[number];
+  model: string;
+  samples: number;
+  totalCost: number;
+  avgCost: number;
+}
+
+export interface AutotuneCostGuard {
+  /** Optional per-phase average cost ceiling in USD. Absent/invalid disables the guard. */
+  maxPhaseCostUsd?: number;
+  /** Minimum cost samples before the ceiling can suppress a step-up. Default: MIN_COST_SAMPLES. */
+  minSamples?: number;
+}
+
+export const MIN_COST_SAMPLES = 3;
+
 /** Map key for a `(phase, model)` bucket. */
 function statKey(phase: string, model: string): string {
   return `${phase} ${model}`;
@@ -287,6 +310,38 @@ function statKey(phase: string, model: string): string {
  * `avgReplantear` accumulator. `avgCorregir`/`avgReplantear` are `null` when a
  * pair has no v2 evidence. An empty input yields an empty map.
  */
+export function aggregateCostStats(samples: readonly PhaseCostSample[]): Map<string, PhaseCostStat> {
+  const acc = new Map<string, { phase: (typeof RECORD_PHASES)[number]; model: string; samples: number; totalCost: number }>();
+  for (const sample of samples) {
+    const phase = sample.phase;
+    if (typeof phase !== "string" || !(RECORD_PHASES as readonly string[]).includes(phase)) continue;
+    const model = sample.model;
+    if (typeof model !== "string" || model === "") continue;
+    const usage = isObject(sample.usage) ? sample.usage : {};
+    const cost = usage.cost;
+    if (typeof cost !== "number" || !Number.isFinite(cost)) continue;
+    const key = statKey(phase, model);
+    let bucket = acc.get(key);
+    if (!bucket) {
+      bucket = { phase: phase as (typeof RECORD_PHASES)[number], model, samples: 0, totalCost: 0 };
+      acc.set(key, bucket);
+    }
+    bucket.samples += 1;
+    bucket.totalCost += cost;
+  }
+  const stats = new Map<string, PhaseCostStat>();
+  for (const [key, bucket] of acc) {
+    stats.set(key, {
+      phase: bucket.phase,
+      model: bucket.model,
+      samples: bucket.samples,
+      totalCost: bucket.totalCost,
+      avgCost: bucket.samples > 0 ? bucket.totalCost / bucket.samples : 0,
+    });
+  }
+  return stats;
+}
+
 export function aggregate(records: RunRecord[]): Map<string, PhaseModelStat> {
   interface Acc {
     samples: number;
@@ -505,6 +560,8 @@ export function decideAdjustments(
   stats: Map<string, PhaseModelStat>,
   currentModels: Partial<Record<(typeof RECORD_PHASES)[number], string>>,
   knownModels: readonly string[],
+  costStats: Map<string, PhaseCostStat> = new Map(),
+  costGuard: AutotuneCostGuard = {},
 ): Adjustment[] {
   const adjustments: Adjustment[] = [];
 
@@ -522,6 +579,16 @@ export function decideAdjustments(
     const threshold = phase === "build" ? HIGH_AVG_CORREGIR : HIGH_AVG_REPLANTEAR;
     if (measure === null || !(measure > threshold)) continue;
 
+    const maxPhaseCostUsd = costGuard.maxPhaseCostUsd;
+    if (typeof maxPhaseCostUsd === "number" && Number.isFinite(maxPhaseCostUsd) && maxPhaseCostUsd > 0) {
+      const minCostSamples =
+        typeof costGuard.minSamples === "number" && Number.isFinite(costGuard.minSamples) && costGuard.minSamples > 0
+          ? Math.floor(costGuard.minSamples)
+          : MIN_COST_SAMPLES;
+      const cost = costStats.get(statKey(phase, currentModel));
+      if (cost && cost.samples >= minCostSamples && cost.avgCost >= maxPhaseCostUsd) continue;
+    }
+
     const to = stepUp(currentModel, knownModels);
     if (to === null) continue; // already at top tier, or untierable
 

package/extensions/sdd-agents.ts

@@ -32,6 +32,32 @@ export type Phase = (typeof PHASES)[number];
  */
 export const SUPPORT_MODULES = ["strict-tdd.md", "strict-tdd-verify.md"] as const;
 
+/**
+ * Phase-specific builtin tool allowlists for generated pi-subagents agents.
+ *
+ * Explore and veredicto are intentionally read-only at the mutation-tool layer:
+ * they can inspect files and run scoped verification commands, but they cannot
+ * edit. Plan can write only SDD artifacts; build is the only phase with the
+ * full mutation set for product code. This is enforced by pi-subagents' `tools:`
+ * frontmatter key, so an accidental phase prompt drift does not silently grant
+ * broad editing power to every child.
+ */
+export const PHASE_TOOLS: Record<Phase, readonly string[]> = {
+  explore: ["read", "bash"],
+  plan: ["read", "bash", "write", "edit"],
+  build: ["read", "bash", "write", "edit"],
+  veredicto: ["read", "bash"],
+};
+
+/** Non-build phases may mention implementation terms while using `bash`; do not
+ *  let pi-subagents' implementation completion guard classify them as writers. */
+export const PHASE_COMPLETION_GUARD: Record<Phase, boolean> = {
+  explore: false,
+  plan: false,
+  build: true,
+  veredicto: false,
+};
+
 /** Absolute path of the runtime support dir the phase prompts reference. */
 export function supportModulesDir(): string {
   return join(homedir(), ".pi", "agent", "agents", "zero", "support");
@@ -75,6 +101,8 @@ export function buildAgentFile(
   // defensive: callers already validate, but the file builder must never write
   // a bad level into agent frontmatter.
   if (thinking && isThinkingLevel(thinking)) front.push(`thinking: ${thinking}`);
+  front.push(`tools: ${PHASE_TOOLS[phase].join(", ")}`);
+  if (!PHASE_COMPLETION_GUARD[phase]) front.push("completionGuard: false");
   front.push(
     "systemPromptMode: replace",
     "inheritProjectContext: true",

package/extensions/zero-checkpoint-extension.ts

@@ -0,0 +1,62 @@
+import { existsSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { spawnSync } from "node:child_process";
+
+import { createCheckpoint, formatCheckpointReport, parseCheckpointArgs, type CheckpointRunner } from "./zero-checkpoint.ts";
+
+const SDD_DIR = ".sdd";
+
+type NotifyType = "info" | "warning" | "error";
+interface PiCommandContext { ui: { notify(message: string, type?: NotifyType): void } }
+interface PiExtensionAPI { registerCommand(name: string, options: { description?: string; handler: (args: string, ctx: PiCommandContext) => void | Promise<void> }): void }
+
+function resolveSlug(explicit: string | null): string | null {
+  if (explicit) return explicit;
+  try {
+    const candidates = readdirSync(SDD_DIR, { withFileTypes: true })
+      .filter((e) => e.isDirectory() && e.name !== "specs" && e.name !== "archive" && existsSync(join(SDD_DIR, e.name)))
+      .map((e) => e.name);
+    return candidates.length === 1 ? candidates[0] : null;
+  } catch {
+    return null;
+  }
+}
+
+function defaultRunner(cwd: string): CheckpointRunner {
+  return {
+    run(command, args) {
+      try {
+        const r = spawnSync(command, [...args], { cwd, encoding: "utf8" });
+        return {
+          status: typeof r.status === "number" ? r.status : 1,
+          stdout: r.stdout ?? "",
+          stderr: r.stderr ?? "",
+          error: r.error?.message,
+        };
+      } catch (err) {
+        return { status: 1, stdout: "", stderr: "", error: err instanceof Error ? err.message : String(err) };
+      }
+    },
+  };
+}
+
+export function runCheckpoint(args: string, ctx: PiCommandContext, runner = defaultRunner(process.cwd())): void {
+  const notify = (m: string, t?: NotifyType) => { try { ctx.ui.notify(m, t); } catch {} };
+  const parsed = parseCheckpointArgs(args ?? "");
+  const slug = resolveSlug(parsed.slug);
+  if (!slug) { notify("zero-checkpoint: no hay un único run — corré /zero-checkpoint <slug>", "warning"); return; }
+  const result = createCheckpoint(slug, process.cwd(), runner);
+  if (parsed.json) notify(JSON.stringify(result, null, 2), result.ok ? "info" : "error");
+  else notify(formatCheckpointReport(result), result.ok ? "info" : "error");
+}
+
+export default function register(pi?: PiExtensionAPI): void {
+  if (!pi || typeof pi.registerCommand !== "function") return;
+  pi.registerCommand("zero-checkpoint", {
+    description: "Crea un checkpoint patch-based del worktree actual dentro de .sdd/<slug>/checkpoints/",
+    handler: (args: string, ctx: PiCommandContext): void => {
+      try { if (ctx?.ui?.notify) runCheckpoint(args ?? "", ctx); }
+      catch (err) { try { ctx.ui.notify(`zero-checkpoint: ${err instanceof Error ? err.message : String(err)}`, "error"); } catch {} }
+    },
+  });
+}

package/extensions/zero-checkpoint.ts

@@ -0,0 +1,92 @@
+import { mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+export interface CheckpointRunner {
+  run(command: string, args: readonly string[]): { status: number; stdout: string; stderr: string; error?: string };
+}
+
+export interface CheckpointResult {
+  ok: boolean;
+  slug: string;
+  id: string;
+  dir: string;
+  head: string;
+  dirty: boolean;
+  untracked: string[];
+  message?: string;
+}
+
+export function checkpointId(date = new Date()): string {
+  const pad = (n: number): string => String(n).padStart(2, "0");
+  return `${date.getFullYear()}${pad(date.getMonth() + 1)}${pad(date.getDate())}-${pad(date.getHours())}${pad(date.getMinutes())}${pad(date.getSeconds())}`;
+}
+
+export function parseCheckpointArgs(args: string): { slug: string | null; json: boolean } {
+  const parts = args.trim().split(/\s+/).filter(Boolean);
+  let slug: string | null = null;
+  let json = false;
+  for (const part of parts) {
+    if (part === "--json") json = true;
+    else if (!slug) slug = part;
+  }
+  return { slug, json };
+}
+
+export function untrackedFromStatus(status: string): string[] {
+  return status
+    .split(/\r?\n/)
+    .filter((line) => line.startsWith("?? "))
+    .map((line) => line.slice(3).trim())
+    .filter(Boolean);
+}
+
+export function formatCheckpointReport(result: CheckpointResult): string {
+  if (!result.ok) return `zero-checkpoint: ${result.message ?? "falló"}`;
+  const lines = [
+    `zero-checkpoint: ${result.slug} @ ${result.id}`,
+    `  dir: ${result.dir}`,
+    `  head: ${result.head}`,
+    result.dirty ? "  estado: cambios capturados en diff.patch" : "  estado: worktree limpio (checkpoint base)",
+  ];
+  if (result.untracked.length > 0) {
+    lines.push(`  aviso: ${result.untracked.length} untracked no se incluyen en diff.patch (${result.untracked.slice(0, 5).join(", ")}${result.untracked.length > 5 ? ", …" : ""})`);
+  }
+  lines.push("  restore: revisá restore.sh antes de ejecutarlo");
+  return lines.join("\n");
+}
+
+export function createCheckpoint(
+  slug: string,
+  cwd: string,
+  runner: CheckpointRunner,
+  now = new Date(),
+): CheckpointResult {
+  const root = runner.run("git", ["rev-parse", "--show-toplevel"]);
+  if (root.status !== 0) return { ok: false, slug, id: "", dir: "", head: "", dirty: false, untracked: [], message: "este cwd no parece estar dentro de un repo git" };
+  const repoRoot = root.stdout.trim() || cwd;
+
+  const head = runner.run("git", ["rev-parse", "--short", "HEAD"]);
+  if (head.status !== 0) return { ok: false, slug, id: "", dir: "", head: "", dirty: false, untracked: [], message: "no pude resolver HEAD" };
+
+  const status = runner.run("git", ["status", "--short"]);
+  const diff = runner.run("git", ["diff", "--binary", "HEAD"]);
+  if (status.status !== 0 || diff.status !== 0) return { ok: false, slug, id: "", dir: "", head: head.stdout.trim(), dirty: false, untracked: [], message: "no pude leer el estado git" };
+
+  const id = checkpointId(now);
+  const dir = join(repoRoot, ".sdd", slug, "checkpoints", id);
+  mkdirSync(dir, { recursive: true });
+  const untracked = untrackedFromStatus(status.stdout);
+  const dirty = status.stdout.trim() !== "";
+
+  writeFileSync(join(dir, "head.txt"), `${head.stdout.trim()}\n`, "utf8");
+  writeFileSync(join(dir, "status.txt"), status.stdout, "utf8");
+  writeFileSync(join(dir, "diff.patch"), diff.stdout, "utf8");
+  writeFileSync(join(dir, "meta.json"), `${JSON.stringify({ slug, id, head: head.stdout.trim(), dirty, untracked, createdAt: now.toISOString() }, null, 2)}\n`, "utf8");
+  writeFileSync(
+    join(dir, "restore.sh"),
+    `#!/usr/bin/env bash\nset -euo pipefail\n# Review before running. This restores tracked files to checkpoint ${id}.\ngit reset --hard ${head.stdout.trim()}\ngit apply --3way ${JSON.stringify(join(dir, "diff.patch"))}\n`,
+    "utf8",
+  );
+
+  return { ok: true, slug, id, dir, head: head.stdout.trim(), dirty, untracked };
+}

package/extensions/zero-doctor-extension.ts

@@ -0,0 +1,42 @@
+import { createDefaultDoctorHost, formatDoctorReport, runDoctor } from "./zero-doctor.ts";
+import type { PiModel } from "./zero-models.ts";
+
+type NotifyType = "info" | "warning" | "error";
+
+interface PiCommandContext {
+  ui: { notify(message: string, type?: NotifyType): void };
+  modelRegistry?: { getAll(): PiModel[] };
+}
+
+interface PiExtensionAPI {
+  registerCommand(
+    name: string,
+    options: { description?: string; handler: (args: string, ctx: PiCommandContext) => void | Promise<void> },
+  ): void;
+}
+
+function registryModels(ctx: PiCommandContext): PiModel[] | undefined {
+  try {
+    const models = ctx.modelRegistry?.getAll?.();
+    return Array.isArray(models) ? models : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+export default function register(pi?: PiExtensionAPI): void {
+  if (!pi || typeof pi.registerCommand !== "function") return;
+  pi.registerCommand("zero-doctor", {
+    description: "Diagnostica instalación, modelos, sub-agentes, git/gh y estado SDD de zero-pi",
+    handler: (_args: string, ctx: PiCommandContext): void => {
+      try {
+        const report = runDoctor(createDefaultDoctorHost(registryModels(ctx)));
+        ctx.ui.notify(formatDoctorReport(report), report.ok ? "info" : "error");
+      } catch (err) {
+        try {
+          ctx.ui.notify(`zero-doctor: ${err instanceof Error ? err.message : String(err)}`, "error");
+        } catch {}
+      }
+    },
+  });
+}

package/extensions/zero-doctor.ts

@@ -0,0 +1,291 @@
+import { spawnSync } from "node:child_process";
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import {
+  groupByProvider,
+  PHASES,
+  readModels,
+  readProviders,
+  validateAssignment,
+  type PiModel,
+} from "./zero-models.ts";
+
+export type DoctorLevel = "ok" | "warn" | "fail";
+
+export interface DoctorCheck {
+  name: string;
+  level: DoctorLevel;
+  message: string;
+  hint?: string;
+}
+
+export interface DoctorReport {
+  ok: boolean;
+  checks: DoctorCheck[];
+}
+
+export interface CommandResult {
+  status: number | null;
+  stdout: string;
+  stderr: string;
+  error?: string;
+}
+
+export interface DoctorHost {
+  cwd: string;
+  home: string;
+  nodeVersion: string;
+  models?: readonly PiModel[];
+  exists(path: string): boolean;
+  readText(path: string): string | null;
+  listDir(path: string): string[];
+  run(command: string, args: readonly string[], cwd: string): CommandResult;
+}
+
+function currentPackageDir(): string {
+  return dirname(dirname(fileURLToPath(import.meta.url)));
+}
+
+function readText(path: string): string | null {
+  try {
+    return readFileSync(path, "utf8");
+  } catch {
+    return null;
+  }
+}
+
+function defaultRun(command: string, args: readonly string[], cwd: string): CommandResult {
+  try {
+    const out = spawnSync(command, [...args], {
+      cwd,
+      encoding: "utf8",
+      timeout: 5000,
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+    return {
+      status: out.status,
+      stdout: typeof out.stdout === "string" ? out.stdout : "",
+      stderr: typeof out.stderr === "string" ? out.stderr : "",
+      error: out.error?.message,
+    };
+  } catch (err) {
+    return { status: null, stdout: "", stderr: "", error: err instanceof Error ? err.message : String(err) };
+  }
+}
+
+export function createDefaultDoctorHost(models?: readonly PiModel[]): DoctorHost {
+  return {
+    cwd: process.cwd(),
+    home: homedir(),
+    nodeVersion: process.version,
+    models,
+    exists: existsSync,
+    readText,
+    listDir(path: string): string[] {
+      try {
+        return readdirSync(path);
+      } catch {
+        return [];
+      }
+    },
+    run: defaultRun,
+  };
+}
+
+function check(name: string, level: DoctorLevel, message: string, hint?: string): DoctorCheck {
+  return hint ? { name, level, message, hint } : { name, level, message };
+}
+
+function parseVersion(version: string): number[] {
+  return version.replace(/^v/, "").split(".").map((p) => Number.parseInt(p, 10)).map((n) => (Number.isFinite(n) ? n : 0));
+}
+
+export function versionAtLeast(version: string, minimum: string): boolean {
+  const a = parseVersion(version);
+  const b = parseVersion(minimum);
+  for (let i = 0; i < Math.max(a.length, b.length); i += 1) {
+    const av = a[i] ?? 0;
+    const bv = b[i] ?? 0;
+    if (av > bv) return true;
+    if (av < bv) return false;
+  }
+  return true;
+}
+
+function parseJson(text: string | null): { ok: true; value: Record<string, unknown> } | { ok: false; error: string } | null {
+  if (text === null) return null;
+  try {
+    const value = JSON.parse(text);
+    return typeof value === "object" && value !== null && !Array.isArray(value)
+      ? { ok: true, value: value as Record<string, unknown> }
+      : { ok: false, error: "JSON root is not an object" };
+  } catch (err) {
+    return { ok: false, error: err instanceof Error ? err.message : String(err) };
+  }
+}
+
+function settingsPackages(settings: Record<string, unknown>): string[] {
+  const raw = settings.packages;
+  if (!Array.isArray(raw)) return [];
+  const out: string[] = [];
+  for (const entry of raw) {
+    if (typeof entry === "string") out.push(entry);
+    else if (entry && typeof entry === "object" && typeof (entry as { source?: unknown }).source === "string") out.push((entry as { source: string }).source);
+  }
+  return out;
+}
+
+function packageSourceName(source: string): string {
+  return source.replace(/^npm:/, "").replace(/@[^/@]+$/, "");
+}
+
+function hasPackageSource(packages: readonly string[], name: string): boolean {
+  return packages.some((p) => packageSourceName(p) === name || packageSourceName(p).endsWith(`/${name}`));
+}
+
+function checkNode(host: DoctorHost): DoctorCheck {
+  return versionAtLeast(host.nodeVersion, "20.6.0")
+    ? check("node", "ok", `${host.nodeVersion} (>=20.6.0)`)
+    : check("node", "fail", `${host.nodeVersion} es viejo`, "zero-pi requiere Node >=20.6.0");
+}
+
+function checkPiSubagents(host: DoctorHost, settings: Record<string, unknown> | null): DoctorCheck {
+  const installed = host.exists(join(host.home, ".pi", "agent", "npm", "node_modules", "pi-subagents", "package.json"));
+  const configured = settings ? hasPackageSource(settingsPackages(settings), "pi-subagents") : false;
+  if (installed || configured) return check("pi-subagents", "ok", installed ? "package instalado" : "declarado en settings");
+  return check(
+    "pi-subagents",
+    "fail",
+    "no lo encontré instalado ni declarado",
+    "corré: pi install npm:pi-subagents",
+  );
+}
+
+function checkZeroJson(host: DoctorHost): { check: DoctorCheck; data: Record<string, unknown> | null } {
+  const path = join(host.home, ".pi", "zero.json");
+  const parsed = parseJson(host.readText(path));
+  if (parsed === null) return { check: check("zero.json", "warn", "~/.pi/zero.json no existe", "se crea al usar /zero-models"), data: null };
+  if (!parsed.ok) return { check: check("zero.json", "fail", `JSON inválido: ${parsed.error}`), data: null };
+
+  const groups = groupByProvider(host.models ?? []);
+  const models = readModels(parsed.value);
+  const providers = readProviders(parsed.value);
+  const failures: string[] = [];
+  if (groups.size > 0) {
+    for (const phase of PHASES) {
+      const assignment = { phase, model: models[phase], provider: providers[phase] || undefined };
+      const validation = validateAssignment(assignment, groups);
+      if (!validation.ok) failures.push(`${phase}: ${validation.message}`);
+    }
+  }
+  if (failures.length > 0) return { check: check("zero.json", "fail", failures.join(" · ")), data: parsed.value };
+  return { check: check("zero.json", "ok", groups.size > 0 ? "parseable y modelos válidos" : "parseable (sin registry para validar modelos)"), data: parsed.value };
+}
+
+function checkSettings(host: DoctorHost): { check: DoctorCheck; data: Record<string, unknown> | null } {
+  const path = join(host.home, ".pi", "agent", "settings.json");
+  const parsed = parseJson(host.readText(path));
+  if (parsed === null) return { check: check("settings", "warn", "~/.pi/agent/settings.json no existe"), data: null };
+  if (!parsed.ok) return { check: check("settings", "fail", `JSON inválido: ${parsed.error}`), data: null };
+  return { check: check("settings", "ok", "parseable"), data: parsed.value };
+}
+
+function checkGeneratedAgents(host: DoctorHost): DoctorCheck {
+  const dir = join(host.home, ".pi", "agent", "agents", "zero");
+  const missing = PHASES.map((p) => `zero-${p}.md`).filter((file) => !host.exists(join(dir, file)));
+  if (missing.length === 0) return check("agents", "ok", "sub-agentes zero generados");
+  return check("agents", "warn", `faltan ${missing.join(", ")}`, "reiniciá pi para que zero-pi regenere ~/.pi/agent/agents/zero/");
+}
+
+function checkSupportModules(host: DoctorHost): DoctorCheck {
+  const dir = join(host.home, ".pi", "agent", "agents", "zero", "support");
+  const required = ["strict-tdd.md", "strict-tdd-verify.md"];
+  const missing = required.filter((file) => !host.exists(join(dir, file)));
+  if (missing.length === 0) return check("support", "ok", "Strict TDD support modules presentes");
+  return check("support", "warn", `faltan ${missing.join(", ")}`, "reiniciá pi o reinstalá zero-pi");
+}
+
+function checkSddConfig(host: DoctorHost): DoctorCheck {
+  const path = join(host.cwd, ".sdd", "config.json");
+  const parsed = parseJson(host.readText(path));
+  if (parsed === null) return check(".sdd/config", "ok", "no existe (opcional)");
+  if (!parsed.ok) return check(".sdd/config", "fail", `JSON inválido: ${parsed.error}`);
+  return check(".sdd/config", "ok", "parseable");
+}
+
+function checkZeroRuns(host: DoctorHost): DoctorCheck {
+  const path = join(host.home, ".pi", "zero-runs.jsonl");
+  const text = host.readText(path);
+  if (text === null) return check("zero-runs", "warn", "~/.pi/zero-runs.jsonl no existe todavía", "se crea después de runs /forge");
+  let lines = 0;
+  let bad = 0;
+  for (const line of text.split(/\r?\n/)) {
+    if (!line.trim()) continue;
+    lines += 1;
+    try { JSON.parse(line); } catch { bad += 1; }
+  }
+  if (bad > 0) return check("zero-runs", "warn", `${bad}/${lines} líneas no parsean como JSONL`);
+  return check("zero-runs", "ok", `${lines} records parseables`);
+}
+
+function checkGit(host: DoctorHost): DoctorCheck {
+  const root = host.run("git", ["rev-parse", "--show-toplevel"], host.cwd);
+  if (root.status !== 0) return check("git", "warn", "este cwd no parece estar dentro de un repo git", root.stderr.trim() || root.error);
+  const repoRoot = root.stdout.trim() || host.cwd;
+  const remote = host.run("git", ["remote", "get-url", "origin"], repoRoot);
+  if (remote.status === 0) return check("git", "ok", `origin: ${remote.stdout.trim()}`);
+  return check("git", "warn", "repo git sin remote origin", remote.stderr.trim() || remote.error);
+}
+
+function checkGh(host: DoctorHost): DoctorCheck {
+  const gh = host.run("gh", ["auth", "status"], host.cwd);
+  if (gh.status === 0) return check("gh", "ok", "GitHub CLI autenticado");
+  const reason = (gh.stderr || gh.stdout || gh.error || "gh auth status falló").trim().split("\n")[0];
+  return check("gh", "warn", reason || "gh auth status falló", "necesario para /zero-pr y /zero-issue");
+}
+
+function checkPackageManifest(host: DoctorHost): DoctorCheck {
+  const pkg = parseJson(host.readText(join(currentPackageDir(), "package.json")));
+  if (!pkg || !pkg.ok) return check("zero-pi package", "warn", "no pude leer package.json del paquete");
+  const version = typeof pkg.value.version === "string" ? pkg.value.version : "unknown";
+  return check("zero-pi package", "ok", `@gonrocca/zero-pi v${version}`);
+}
+
+export function runDoctor(host: DoctorHost = createDefaultDoctorHost()): DoctorReport {
+  const checks: DoctorCheck[] = [];
+  checks.push(checkPackageManifest(host));
+  checks.push(checkNode(host));
+  const settings = checkSettings(host);
+  checks.push(settings.check);
+  checks.push(checkPiSubagents(host, settings.data));
+  const zero = checkZeroJson(host);
+  checks.push(zero.check);
+  checks.push(checkGeneratedAgents(host));
+  checks.push(checkSupportModules(host));
+  checks.push(checkSddConfig(host));
+  checks.push(checkZeroRuns(host));
+  checks.push(checkGit(host));
+  checks.push(checkGh(host));
+  return { ok: checks.every((c) => c.level !== "fail"), checks };
+}
+
+function icon(level: DoctorLevel): string {
+  if (level === "ok") return "✅";
+  if (level === "warn") return "⚠️";
+  return "❌";
+}
+
+export function formatDoctorReport(report: DoctorReport): string {
+  const ok = report.checks.filter((c) => c.level === "ok").length;
+  const warn = report.checks.filter((c) => c.level === "warn").length;
+  const fail = report.checks.filter((c) => c.level === "fail").length;
+  const lines = [`zero-doctor: ${report.ok ? "ok" : "falló"} · ${ok} ok · ${warn} warn · ${fail} fail`];
+  for (const c of report.checks) {
+    lines.push(`${icon(c.level)} ${c.name}: ${c.message}`);
+    if (c.hint) lines.push(`   ↳ ${c.hint}`);
+  }
+  return lines.join("\n");
+}

package/extensions/zero-models.ts

@@ -328,6 +328,85 @@ export function groupByProvider(models: readonly PiModel[]): Map<string, string[
   return map;
 }
 
+/** Result of validating a direct `/zero-models <phase>=...` assignment
+ *  against pi's model registry. */
+export type AssignmentValidation =
+  | { ok: true; provider?: string }
+  | { ok: false; message: string };
+
+function containsModel(list: readonly string[] | undefined, model: string): boolean {
+  return Boolean(list?.includes(model));
+}
+
+function modelProviders(groups: Map<string, string[]>, model: string): string[] {
+  const providers: string[] = [];
+  for (const [provider, models] of groups) if (models.includes(model)) providers.push(provider);
+  return providers.sort();
+}
+
+function suggestModels(groups: Map<string, string[]>, model: string): string[] {
+  const needle = model.toLowerCase();
+  const scored: string[] = [];
+  for (const [provider, models] of groups) {
+    for (const id of models) {
+      const hay = id.toLowerCase();
+      if (hay.includes(needle) || needle.includes(hay)) scored.push(`${provider}/${id}`);
+    }
+  }
+  return scored.slice(0, 5);
+}
+
+/**
+ * Validate a direct assignment against pi's model registry.
+ *
+ * Empty registry = permissive fallback (old behaviour), because tests and some
+ * headless contexts may not expose `ctx.modelRegistry`. When the registry is
+ * present, the command writes only provider/model pairs pi can actually
+ * resolve. Bare ambiguous model ids are rejected with a provider-qualified hint.
+ */
+export function validateAssignment(
+  assignment: Assignment,
+  groups: Map<string, string[]>,
+): AssignmentValidation {
+  if (groups.size === 0) return { ok: true, provider: assignment.provider };
+
+  if (assignment.provider) {
+    const providerModels = groups.get(assignment.provider);
+    if (!providerModels) {
+      return {
+        ok: false,
+        message: `provider desconocido: ${assignment.provider}. Usá uno de: ${[...groups.keys()].sort().join(", ")}`,
+      };
+    }
+    if (!containsModel(providerModels, assignment.model)) {
+      const suggestions = suggestModels(groups, assignment.model);
+      return {
+        ok: false,
+        message:
+          `modelo desconocido para ${assignment.provider}: ${assignment.model}` +
+          (suggestions.length > 0 ? `. Quizás: ${suggestions.join(", ")}` : ""),
+      };
+    }
+    return { ok: true, provider: assignment.provider };
+  }
+
+  const providers = modelProviders(groups, assignment.model);
+  if (providers.length === 1) return { ok: true, provider: providers[0] };
+  if (providers.length > 1) {
+    return {
+      ok: false,
+      message: `modelo ambiguo: ${assignment.model}. Usá provider/model: ${providers.map((p) => `${p}/${assignment.model}`).join(", ")}`,
+    };
+  }
+  const suggestions = suggestModels(groups, assignment.model);
+  return {
+    ok: false,
+    message:
+      `modelo desconocido: ${assignment.model}` +
+      (suggestions.length > 0 ? `. Quizás: ${suggestions.join(", ")}` : ""),
+  };
+}
+
 /** The pi-TUI host handed to a `ctx.ui.custom()` factory — only the one
  *  method the picker shell uses. */
 interface PiTui {
@@ -706,8 +785,15 @@ export default function register(pi?: PiExtensionAPI): void {
             );
             return;
           }
+          const validation = validateAssignment(assignment, groups);
+          if (!validation.ok) {
+            ctx.ui.notify(`zero-models: ${validation.message}`, "warning");
+            return;
+          }
+
           models[assignment.phase] = assignment.model;
           providers[assignment.phase] =
+            validation.provider ??
             assignment.provider ??
             resolveProvider(ctx.modelRegistry, assignment.model) ??
             providers[assignment.phase];

package/extensions/zero-validate.ts

@@ -17,6 +17,7 @@ export interface TaskRecord {
   id: string;
   title: string;
   files: { path: string; isNew: boolean }[];
+  depends: string[] | null;
   evidence: string | null;
   review: number | null;
   reviewRaw: string | null;
@@ -27,6 +28,13 @@ export interface WorkloadSection {
   declaredTotal: number | null;
 }
 
+export function parseDepends(raw: string): string[] {
+  const value = raw.trim();
+  if (value === "" || value === "[]" || /^(none|n\/a|na)$/i.test(value)) return [];
+  const ids = [...value.matchAll(/\bT\d+\b/g)].map((m) => m[0]);
+  return [...new Set(ids)];
+}
+
 export function parseTasks(text: string): { tasks: TaskRecord[]; workload: WorkloadSection | null; defects: ValidationDefect[] } {
   const tasks: TaskRecord[] = [];
   const defects: ValidationDefect[] = [];
@@ -43,7 +51,7 @@ export function parseTasks(text: string): { tasks: TaskRecord[]; workload: Workl
   for (const line of lines) {
     const task = line.match(/^\s*- \[[ xX]\]\s+\*\*(T\d+)\.\s+([^*]+)\*\*/) ?? line.match(/^###\s+(T\d+)\s+[—-]\s+(.+)$/) ?? line.match(/^##\s+\[[ xX]\]\s+(T\d+)\s*(?:[—-]\s*(.+))?$/);
     if (task) {
-      current = { id: task[1], title: (task[2] ?? "").trim(), files: [], evidence: null, review: null, reviewRaw: null };
+      current = { id: task[1], title: (task[2] ?? "").trim(), files: [], depends: null, evidence: null, review: null, reviewRaw: null };
       tasks.push(current);
       collectingFiles = false;
       continue;
@@ -54,6 +62,11 @@ export function parseTasks(text: string): { tasks: TaskRecord[]; workload: Workl
       pushFile(line);
       continue;
     }
+    if (/^\s*-\s+depends:/.test(line)) {
+      collectingFiles = false;
+      current.depends = parseDepends(line.replace(/^\s*-\s+depends:\s*/, ""));
+      continue;
+    }
     if (/^\s*-\s+evidence:/.test(line)) {
       collectingFiles = false;
       current.evidence = line.replace(/^\s*-\s+evidence:\s*/, "").trim();
@@ -73,8 +86,16 @@ export function parseTasks(text: string): { tasks: TaskRecord[]; workload: Workl
     }
   }
 
-  for (const task of tasks) {
+  const order = new Map(tasks.map((task, index) => [task.id, index] as const));
+  for (const [index, task] of tasks.entries()) {
     if (task.files.length === 0) defects.push({ kind: "missing-files", task: task.id, message: `${task.id} is missing files list` });
+    if (task.depends === null) defects.push({ kind: "missing-depends", task: task.id, message: `${task.id} is missing depends list` });
+    else for (const dep of task.depends) {
+      const depIndex = order.get(dep);
+      if (dep === task.id) defects.push({ kind: "self-depends", task: task.id, message: `${task.id} cannot depend on itself` });
+      else if (depIndex === undefined) defects.push({ kind: "unknown-depends", task: task.id, message: `${task.id} depends on unknown ${dep}` });
+      else if (depIndex > index) defects.push({ kind: "forward-depends", task: task.id, message: `${task.id} depends on later task ${dep}` });
+    }
     if (task.evidence === null || task.evidence === "") defects.push({ kind: "missing-evidence", task: task.id, message: `${task.id} is missing evidence` });
     if (task.reviewRaw === null) defects.push({ kind: "missing-review", task: task.id, message: `${task.id} is missing review estimate` });
     else if (task.review === null) defects.push({ kind: "non-integer-review", task: task.id, message: `${task.id} review estimate is not an integer` });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gonrocca/zero-pi",
-  "version": "0.1.57",
+  "version": "0.1.59",
   "description": "zero-pi — an installable layer for pi (pi.dev): the zero spec-driven development workflow (explore → plan → build → veredicto) with per-phase model autotune and token-efficient batched builds. Adds capability to pi without modifying pi.",
   "type": "module",
   "keywords": [
@@ -35,7 +35,9 @@
       "./extensions/spec-merge-extension.ts",
       "./extensions/zero-validate-extension.ts",
       "./extensions/zero-status-extension.ts",
+      "./extensions/zero-doctor-extension.ts",
       "./extensions/zero-cost-extension.ts",
+      "./extensions/zero-checkpoint-extension.ts",
       "./extensions/zero-pr-extension.ts",
       "./extensions/zero-branch-extension.ts",
       "./extensions/zero-git-validate-extension.ts",
@@ -67,8 +69,12 @@
     "extensions/zero-validate-extension.ts",
     "extensions/zero-status.ts",
     "extensions/zero-status-extension.ts",
+    "extensions/zero-doctor.ts",
+    "extensions/zero-doctor-extension.ts",
     "extensions/zero-cost.ts",
     "extensions/zero-cost-extension.ts",
+    "extensions/zero-checkpoint.ts",
+    "extensions/zero-checkpoint-extension.ts",
     "extensions/format-tokens.ts",
     "extensions/pr-body.ts",
     "extensions/sdd-links.ts",

package/prompts/orchestrator.md

@@ -112,6 +112,14 @@ findings, file dumps — into a brief; reference them by path. Re-passing contex
 the sub-agent can read for itself is wasted tokens on every invocation, and a
 batched build issues many briefs.
 
+## Plan quality gate
+
+After **plan** returns, run `/zero-validate <slug>` when the command is available. Treat structural validation errors as a plan failure: summarize the defects, re-run **plan** with those exact defects once, and validate again before entering build. Warnings (for example an intentionally-missing optional proposal) can proceed only when you name the warning in the phase summary. The gate specifically protects the dependency graph: every task must carry `files`, `depends`, `evidence`, and `review`; dependencies must point backward to known task ids; and the review workload total must match.
+
+## Pre-build checkpoint
+
+Before the first **build** batch of every round, run `/zero-checkpoint <slug>` when available. It writes a patch-based checkpoint under `.sdd/<slug>/checkpoints/<id>/` so a risky build has a concrete restore trail. If the command is missing or reports untracked files that were not captured, continue only after surfacing that risk in the build phase-start summary. Do not run destructive restore commands automatically; the checkpoint only records evidence and a reviewed `restore.sh`.
+
 ## Build batching
 
 The **build** phase is not one monolithic sub-agent that implements every
@@ -122,23 +130,30 @@ bounded batches, each a fresh `zero-build` sub-agent.
 Before delegating build — a fresh build phase, or a `corregir`/`replantear`
 re-run — drive this loop:
 
-1. Read the unchecked (`[ ]`) tasks from `tasks.md` in listed order and their
-   `review: ~N changed lines` estimates from the `## Review Workload` section.
-2. Group the unchecked tasks into ordered batches with this exact, deterministic
-   rule:
+1. Read the unchecked (`[ ]`) tasks from `tasks.md` in listed order, their
+   `depends:` edges, and their `review: ~N changed lines` estimates from the
+   `## Review Workload` section.
+2. Treat the task order as a validated topological order. A task is eligible for
+   the next batch only when every dependency in its `depends:` list is already
+   checked `[x]` or is also included earlier in the same contiguous batch. If an
+   unchecked task depends on a later/unknown/unchecked-outside-batch task, stop
+   and re-run **plan** — do not improvise a new order in build.
+3. Group the eligible unchecked tasks into ordered batches with this exact,
+   deterministic rule:
    - Walk the unchecked tasks in order, accumulating into the current batch.
    - Start a new batch when adding the next task would push the batch's summed
      estimate over **800 changed lines**, or when the current batch already
      holds **4 tasks** — whichever comes first.
    - A single task whose own estimate exceeds 800 is its own batch.
    - If estimates are missing or unparseable, group by the 4-task cap alone.
-3. Invoke `zero-build` once per batch, in listed order. Each brief is a fresh
+4. Invoke `zero-build` once per batch, in listed order. Each brief is a fresh
    sub-agent (no carried conversation) and names the batch's task numbers
-   explicitly (for example, "implement tasks 4–6 only, then return"). Emit the
-   build phase-start line for each batch, noting the batch as `lote <i>/<n>`, so
-   the loop stays visible. Wait for each batch to return before starting the
-   next.
-4. Repeat until `tasks.md` has no `[ ]` task left, then run **veredicto** once.
+   explicitly (for example, "implement tasks 4–6 only, then return"). Include the
+   dependency constraint in the brief: "do not start a task until its `depends:`
+   entries are `[x]`." Emit the build phase-start line for each batch, noting
+   the batch as `lote <i>/<n>`, so the loop stays visible. Wait for each batch to
+   return before starting the next.
+5. Repeat until `tasks.md` has no `[ ]` task left, then run **veredicto** once.
    Never run veredicto between batches.
 
 **Single-batch features behave exactly like before:** when every unchecked task

package/prompts/phases/build.md

@@ -23,8 +23,7 @@ re-reading the same large file repeatedly is the main avoidable token cost. If
 the code roots are missing or wrong, run a single targeted search to fix them,
 then proceed — never fall back to scanning the whole tree.
 
-Implement the planned tasks in order, test-first where practical. Keep every
-change within the plan's scope — do not expand it on your own initiative.
+Implement the planned tasks in dependency order, test-first where practical. `tasks.md` is a dependency-aware graph: every task has a `depends:` line. Before starting a task, verify each listed dependency is already `[x]`; if a dependency is unchecked, complete that dependency first (when it is in your assigned batch) or stop and report the blocked task (when it is outside the assigned batch). Never skip ahead just because a later task looks easier. Keep every change within the plan's scope — do not expand it on your own initiative.
 
 ## Strict TDD gate
 

package/prompts/phases/plan.md

@@ -73,6 +73,7 @@ Use this exact checklist shape so build/validate/review can parse it without red
   - `<root>/src/example.ts`
   - `<root>/src/example.test.ts` (new)
 - detail: concrete implementation notes and boundaries.
+- depends: []
 - evidence: `npm test -- example` passes, or the exact manual check expected.
 - review: ~120 changed lines
 ```
@@ -81,9 +82,14 @@ Rules:
 - Task ids are monotonic `T###`; keep existing completed ids stable on resume.
 - Add `[P]` only for tasks that are truly parallel-safe, and `[Story:S1]`/`[Story:S2]` when the plan has independently testable stories.
 - `files:` is mandatory and uses exact paths; append `(new)` for created files.
+- `depends:` is mandatory. Use `depends: []` for root tasks, or a comma-separated list of earlier task ids (`depends: T001, T002`) for prerequisites. Dependencies must point only backward so the written task order is already a valid topological order.
 - `evidence:` is mandatory and names a concrete verification command or artifact.
 - Keep `## Review Workload` present and synchronized with the task list.
 
+## Dependency graph discipline
+
+Treat `tasks.md` as a dependency-aware task graph, not just a checklist. Split work so every task has explicit prerequisites, no self-dependencies, no unknown dependencies, and no dependency on a later task. Use the graph to mark real parallelism: a task can get `[P]` only when all of its dependencies are complete and it does not touch the same files as another candidate parallel task.
+
 ## TDD-shaped tasks
 
 Unless the project sets `tdd.mode: "off"` in `.sdd/config.json`, the build phase
@@ -109,6 +115,8 @@ GREEN cycle and the TDD Cycle Evidence table.
 
 ## Constitution / Steering check
 
+Before finalizing tasks, run `/zero-validate <slug>` when available, or manually apply the same checks: all four artifacts present, every task has `files`, `depends`, `evidence`, and `review`, dependency edges point backward to known task ids, review workload totals match, and the spec delta passes guardrails. Fix the artifacts before returning if the validation fails.
+
 Before finalizing tasks, check project steering/constitution files when present (`.sdd/constitution.md`, `.sdd/steering.md`, `.kiro/steering/*`, or project equivalents). If absent, mark `n/a`; absence is not a blocker. Include this table in `design.md` or `tasks.md`:
 
 | rule | status | waiver |