@gonrocca/zero-pi 0.1.58 → 0.1.60

package/README.md

@@ -42,15 +42,26 @@ Needs Node ≥ 20.6. Restart pi after an upgrade.
 ## 🛠 `/forge` — the SDD pipeline
 
 The core of zero-pi. Run **`/forge <feature>`** and the orchestrator drives the
-work through four phases, each delegated to its own sub-agent:
+work through six phases — the automatic
+**clarify → explore → plan → analyze → build → veredicto** flow — each delegated
+to its own sub-agent:
 
 | Phase | Does |
 | ----- | ---- |
+| **clarify** | Record de-risking assumptions before exploration; stop only on blocking ambiguity. |
 | **explore** | Investigate the codebase read-only; produce findings. |
 | **plan** | Write requirements, design, and an ordered task list. |
+| **analyze** | Review plan readiness after `/zero-validate`; decide continue or replan. |
 | **build** | Implement the plan. |
 | **veredicto** | Review it adversarially and record a verdict. |
 
+The **clarify** and **analyze** gates are automatic inside `/forge` — no extra
+slash command in the normal flow. `clarify` writes `.sdd/<slug>/clarifications.md`
+and asks only when proceeding would risk the wrong product; `analyze` writes
+`.sdd/<slug>/checklist.md` after the structural `/zero-validate` gate and returns
+`continue` (build) or `replan` (re-run plan with concrete defects). Neither gate
+counts as a build/veredicto round.
+
 The verdict is `pasa` (done), `corregir` (re-run build), or `replantear`
 (re-run plan). A hard iteration cap bounds the build↔veredicto loop — reached
 without a `pasa`, the run stops and is reported as **not verified**.
@@ -74,10 +85,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. Direct assignments are validated against pi's model registry when available. |
-| **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 of the six SDD phases — 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, clarify/analyze/plan write only `.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. |
@@ -102,6 +116,7 @@ into `/forge` for you.
 | `/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`. |
@@ -111,7 +126,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:
 
@@ -175,21 +190,29 @@ zero-pi keeps its state in `~/.pi/zero.json` (per-phase `models`, `providers`,
 per-project artifacts live under `.sdd/`. Set `ZERO_RESUME=off` to disable the
 conversation-resume note.
 
-`~/.pi/zero.json` stores three parallel per-phase maps plus the autotune mode:
+`~/.pi/zero.json` stores three parallel per-phase maps plus the autotune mode.
+The configurable phases are `clarify`, `explore`, `plan`, `analyze`, `build`,
+and `veredicto`; a pre-gates file that lists only the original four stays valid
+and the missing `clarify`/`analyze` fall back to defaults (cheap/fast clarify,
+strong analyze):
 
 ```json
 {
-  "models":    { "explore": "claude-haiku-4-5", "build": "claude-sonnet-4-6" },
-  "providers": { "explore": "anthropic",        "build": "anthropic" },
-  "thinking":  { "explore": "low",              "build": "high" },
-  "autotune": "ask"
+  "models":    { "clarify": "claude-haiku-4-5", "analyze": "claude-opus-4-8", "build": "claude-sonnet-4-6" },
+  "providers": { "clarify": "anthropic",         "analyze": "anthropic",       "build": "anthropic" },
+  "thinking":  { "analyze": "high",              "build": "high" },
+  "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,19 +19,28 @@
 // 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`. */
+/** The four core SDD phases autotune reads models for and attributes blame to,
+ *  in pipeline order. This is deliberately NOT the full six-phase list in
+ *  `zero-models.ts`: the `clarify`/`analyze` gates are never verdict-attributable
+ *  (only `corregir`→build and `replantear`→plan drive adjustments), and the
+ *  run-record schema keeps these four as its required phases. Reading only these
+ *  four means a configured gate model in `zero.json` is never turned into a
+ *  pending adjustment. */
 const PHASES = ["explore", "plan", "build", "veredicto"] as const;
 type Phase = (typeof PHASES)[number];
 
@@ -104,6 +113,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 +219,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

@@ -1,12 +1,13 @@
 // zero-pi — SDD sub-agent provisioning.
 //
-// `/forge` delegates each phase to a dedicated sub-agent — `zero-explore`,
-// `zero-plan`, `zero-build`, `zero-veredicto`. pi-subagents discovers agents
-// from `~/.pi/agent/agents/**/*.md`, but a `pi install` of zero-pi ships only
-// the phase *prompts* (`prompts/phases/*.md`), never the agent definitions —
-// so `/forge` had nothing to delegate to and stalled.
+// `/forge` delegates each phase to a dedicated sub-agent — `zero-clarify`,
+// `zero-explore`, `zero-plan`, `zero-analyze`, `zero-build`, `zero-veredicto`.
+// pi-subagents discovers agents from `~/.pi/agent/agents/**/*.md`, but a
+// `pi install` of zero-pi ships only the phase *prompts* (`prompts/phases/*.md`),
+// never the agent definitions — so `/forge` had nothing to delegate to and
+// stalled.
 //
-// This extension closes that gap: at load it generates the four agent files
+// This extension closes that gap: at load it generates the six agent files
 // under `~/.pi/agent/agents/zero/` from the package's own phase prompts and
 // the per-phase models in `~/.pi/zero.json`. The files are regenerated every
 // load, so they stay in sync with the prompts and with `/zero-models`.
@@ -19,8 +20,10 @@ import { fileURLToPath } from "node:url";
 import { isThinkingLevel } from "./zero-models.ts";
 import type { ThinkingLevel } from "./zero-models.ts";
 
-/** The four SDD phases, each backed by a `prompts/phases/<phase>.md`. */
-export const PHASES = ["explore", "plan", "build", "veredicto"] as const;
+/** The six SDD phases, in pipeline order, each backed by a
+ *  `prompts/phases/<phase>.md`. `clarify` is the pre-explore assumption gate and
+ *  `analyze` is the post-plan readiness gate; both write only `.sdd` artifacts. */
+export const PHASES = ["clarify", "explore", "plan", "analyze", "build", "veredicto"] as const;
 export type Phase = (typeof PHASES)[number];
 
 /**
@@ -32,6 +35,41 @@ 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. The `clarify` and `analyze` gates can write — but only their own
+ * `.sdd/<slug>/` artifacts (`clarifications.md`, `checklist.md`); the tool
+ * allowlist cannot enforce paths, so their prompts state the `.sdd`-only write
+ * boundary. Plan can write 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[]> = {
+  clarify: ["read", "bash", "write", "edit"],
+  explore: ["read", "bash"],
+  plan: ["read", "bash", "write", "edit"],
+  analyze: ["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.
+ *  Only `build` is a real implementation phase — the gates and read phases all
+ *  disable the guard. */
+export const PHASE_COMPLETION_GUARD: Record<Phase, boolean> = {
+  clarify: false,
+  explore: false,
+  plan: false,
+  analyze: 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 +113,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/working-phrases.ts

@@ -65,8 +65,10 @@ const THINKING_SDD = [
 
 /** SDD phase labels keyed by the zero sub-agent that owns the phase. */
 const SDD_PHASE: Record<string, string> = {
+  "zero-clarify": "Aclarando supuestos",
   "zero-explore": "Explorando el código",
   "zero-plan": "Planeando la solución",
+  "zero-analyze": "Analizando el plan",
   "zero-build": "Construyendo la implementación",
   "zero-veredicto": "Revisando el veredicto",
 };

package/extensions/zero-banner.ts

@@ -156,7 +156,7 @@ export function bannerBlock(width: number): string[] {
   if (width < 64) {
     return [center(fg(PEACH, "ZERO SDD"), width), center(fg(MUTED, "pi.dev · spec-driven work"), width)];
   }
-  const tag = fg(PEACH, "ZERO SDD") + fg(MUTED, "   explore → plan → build → veredicto");
+  const tag = fg(PEACH, "ZERO SDD") + fg(MUTED, "   clarify → explore → plan → analyze → build → veredicto");
   return [ornament(width), ...renderLogo(width), center(tag, width), ornament(width)];
 }
 

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-cost.ts

@@ -13,8 +13,9 @@
 
 import { formatTokens } from "./format-tokens.ts";
 
-/** The SDD phases a run is composed of, in pipeline order. */
-export const COST_PHASES = ["explore", "plan", "build", "veredicto"] as const;
+/** The SDD phases a run is composed of, in pipeline order — the `clarify` and
+ *  `analyze` gate sub-agents write cost meta like any other phase. */
+export const COST_PHASES = ["clarify", "explore", "plan", "analyze", "build", "veredicto"] as const;
 export type CostPhase = (typeof COST_PHASES)[number];
 
 /** Token + cost usage of a single sub-agent run. */
@@ -57,12 +58,12 @@ export interface RunCost {
   total: PhaseUsage & { durationMs: number; toolCount: number; subAgents: number };
 }
 
-const PHASE_INDEX: Record<CostPhase, number> = { explore: 0, plan: 1, build: 2, veredicto: 3 };
+const PHASE_INDEX: Record<CostPhase, number> = { clarify: 0, explore: 1, plan: 2, analyze: 3, build: 4, veredicto: 5 };
 
 /** Map a sub-agent name `zero-<phase>` to its phase, or `null`. */
 export function phaseFromAgent(agent: unknown): CostPhase | null {
   if (typeof agent !== "string") return null;
-  const m = /^zero-(explore|plan|build|veredicto)$/.exec(agent);
+  const m = /^zero-(clarify|explore|plan|analyze|build|veredicto)$/.exec(agent);
   return m ? (m[1] as CostPhase) : null;
 }
 

package/extensions/zero-models-picker.ts

@@ -18,8 +18,8 @@ import type { AutotunePending } from "./autotune-extension.ts";
 
 /** The SDD phases, in pipeline order — re-stated locally so the pure module
  *  carries no value import. Must stay in lockstep with `PHASES` in
- *  `zero-models.ts`. */
-const PHASES = ["explore", "plan", "build", "veredicto"] as const;
+ *  `zero-models.ts` (the `clarify` gate leads, `analyze` sits after `plan`). */
+const PHASES = ["clarify", "explore", "plan", "analyze", "build", "veredicto"] as const;
 
 /** The three autotune modes offered on the autotune screen. */
 const AUTOTUNE_MODES = ["auto", "ask", "off"] as const;

package/extensions/zero-models.ts

@@ -51,8 +51,10 @@ import {
   type PickerState,
 } from "./zero-models-picker.ts";
 
-/** The SDD phases, in pipeline order. */
-export const PHASES = ["explore", "plan", "build", "veredicto"] as const;
+/** The SDD phases, in pipeline order. `clarify` is the pre-explore assumption
+ *  gate and `analyze` is the post-plan readiness gate; both are configurable
+ *  here like any other phase. */
+export const PHASES = ["clarify", "explore", "plan", "analyze", "build", "veredicto"] as const;
 export type Phase = (typeof PHASES)[number];
 
 /** The per-phase model map. */
@@ -74,11 +76,14 @@ export function isThinkingLevel(value: unknown): value is ThinkingLevel {
   return typeof value === "string" && (THINKING_LEVELS as readonly string[]).includes(value);
 }
 
-/** Fallback models when `~/.pi/zero.json` has none — cheap to explore, strong
- *  to plan and review. */
+/** Fallback models when `~/.pi/zero.json` has none — cheap to clarify/explore,
+ *  strong to plan, analyze and review. A pre-gates zero.json missing `clarify`/
+ *  `analyze` keeps its four phases and gets these gate defaults in memory. */
 const DEFAULT_MODELS: PhaseModels = {
+  clarify: "claude-haiku-4-5",
   explore: "claude-haiku-4-5",
   plan: "claude-opus-4-8",
+  analyze: "claude-opus-4-8",
   build: "claude-sonnet-4-6",
   veredicto: "claude-opus-4-8",
 };
@@ -144,7 +149,14 @@ function stripThinkingSuffix(model: string): string {
  */
 export function readProviders(data: Record<string, unknown>): PhaseProviders {
   const raw = (data.providers ?? {}) as Record<string, unknown>;
-  const providers: PhaseProviders = { explore: "", plan: "", build: "", veredicto: "" };
+  const providers: PhaseProviders = {
+    clarify: "",
+    explore: "",
+    plan: "",
+    analyze: "",
+    build: "",
+    veredicto: "",
+  };
   for (const phase of PHASES) {
     if (typeof raw[phase] === "string") providers[phase] = raw[phase] as string;
   }
@@ -778,7 +790,7 @@ export default function register(pi?: PiExtensionAPI): void {
           if (!assignment) {
             ctx.ui.notify(
               "uso: /zero-models  —o—  /zero-models <fase>=[<provider>/]<modelo> [thinking=<nivel>] " +
-                "(fase: explore | plan | build | veredicto · " +
+                "(fase: clarify | explore | plan | analyze | build | veredicto · " +
                 "nivel: off | minimal | low | medium | high | xhigh)  —o—  " +
                 "/zero-models autotune=<modo>",
               "warning",

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,7 +1,7 @@
 {
   "name": "@gonrocca/zero-pi",
-  "version": "0.1.58",
-  "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.",
+  "version": "0.1.60",
+  "description": "zero-pi — an installable layer for pi (pi.dev): the zero spec-driven development workflow (clarify → explore → plan → analyze → build → veredicto) with automatic clarify/analyze gates, per-phase model autotune, and token-efficient batched builds. Adds capability to pi without modifying pi.",
   "type": "module",
   "keywords": [
     "pi",
@@ -37,6 +37,7 @@
       "./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",
@@ -72,6 +73,8 @@
     "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/forge.md

@@ -3,13 +3,20 @@ description: Run the zero spec-driven development pipeline for a feature request
 ---
 
 Run the zero SDD pipeline for the feature request below — you are the
-orchestrator. Drive it through four phases in order: **explore → plan → build →
-veredicto**, delegating each to its sub-agent (`zero-explore`, `zero-plan`,
-`zero-build`, `zero-veredicto`). A `corregir` verdict re-runs `build`; a
-`replantear` verdict re-runs `plan`; after a few rounds with no `pasa`, stop and
-report the result as not verified. Ask the user for interactive or automatic
-mode up front; in interactive mode pause after each phase for approval. Never
-claim success unless veredicto returned `pasa`.
+orchestrator. Drive it through the phases in order:
+**clarify → explore → plan → analyze → build → veredicto**, delegating each to
+its sub-agent (`zero-clarify`, `zero-explore`, `zero-plan`, `zero-analyze`,
+`zero-build`, `zero-veredicto`). The `clarify` and `analyze` gates run
+**automatically** inside `/forge` — there is no slash command a user must run
+by hand for the normal flow. `clarify` records assumptions in
+`.sdd/<slug>/clarifications.md` and stops only on genuinely blocking ambiguity;
+`analyze` writes `.sdd/<slug>/checklist.md` after `plan`/`/zero-validate` and
+returns `continue` (proceed to build) or `replan` (re-run plan with its
+defects). A `corregir` verdict re-runs `build`; a `replantear` verdict re-runs
+`plan`; after a few rounds with no `pasa`, stop and report the result as not
+verified. Ask the user for interactive or automatic mode up front; in
+interactive mode pause after each phase for approval. Never claim success unless
+veredicto returned `pasa`.
 
 **Parse the arguments first.** If the request begins with `--continue`, this is
 a **resume** run, not a fresh one:
@@ -31,7 +38,7 @@ veredicto audits that evidence and returns `corregir` if it fails. Set
 **Output and language.** Follow the orchestrator's `## Language Boundary` and
 `## Output Contract`: user-facing chat in Spanish (natural Rioplatense voseo),
 the bounded per-phase summary, no raw tool output, no agent listings, no
-step-by-step narration — progress and the final verdict, never a log. The four
+step-by-step narration — progress and the final verdict, never a log. The six
 `zero-*` sub-agents already exist; delegate to them directly without running a
 `subagent` listing.
 

package/prompts/orchestrator.md

@@ -1,28 +1,43 @@
 ---
-description: zero SDD orchestrator — drives the explore → plan → build → veredicto pipeline
+description: zero SDD orchestrator — drives the clarify → explore → plan → analyze → build → veredicto pipeline
 ---
 
 # zero — SDD Orchestrator
 
 You are the orchestrator of a spec-driven development (SDD) run. You COORDINATE
 the work; you decide what runs next — never let the loop drift on the model's
-whim. Drive the run through four phases, in order:
-
-1. **explore** — investigate the codebase read-only; produce findings.
-2. **plan** — write a plan: requirements, design, and an ordered task list.
-3. **build** — implement the plan.
-4. **veredicto** — review the build adversarially with a fresh perspective and
+whim. Drive the run through the phases, in order:
+
+1. **clarify** — record de-risking assumptions before exploration; stop only on
+   genuinely blocking ambiguity. Writes `.sdd/<slug>/clarifications.md`.
+2. **explore** — investigate the codebase read-only; produce findings.
+3. **plan** — write a plan: requirements, design, and an ordered task list.
+4. **analyze** — review plan readiness after `/zero-validate`; decide
+   `continue` or `replan`. Writes `.sdd/<slug>/checklist.md`.
+5. **build** — implement the plan.
+6. **veredicto** — review the build adversarially with a fresh perspective and
    record a verdict: `pasa`, `corregir`, or `replantear`.
 
+The full automatic flow is
+**clarify → explore → plan → /zero-validate → analyze → build → veredicto**.
+Both gates run automatically inside `/forge`; a user never runs them by a
+separate slash command in the normal flow. (Any manual slash form is a debug
+override only, never part of the automatic run.)
+
 ## Phase order and the iteration cap
 
 - A `pasa` verdict finishes the run successfully.
 - A `corregir` verdict re-runs **build**.
-- A `replantear` verdict re-runs **plan**, then **build**.
+- A `replantear` verdict re-runs **plan**, then `/zero-validate`, then
+  **analyze**, then **build**.
 - Count every build/veredicto round. There is a hard **cap** on rounds. When
   the cap is reached without a `pasa` verdict, STOP. Report that the result is
   **not verified** — do **not** claim success.
 
+The `clarify` and `analyze` gates are **not** build/veredicto rounds: they never
+count against the iteration cap. An `analyze` `replan` re-runs `plan` and comes
+back through `analyze` before build begins; it does not consume a round.
+
 The orchestrator code controls phase order and the round count. The cap is not
 optional and the model does not get to extend it.
 
@@ -39,8 +54,8 @@ state file; the artifacts are the run's durable state.
   disambiguate. (`forge.md` already reports "no such run" and stops if the
   directory is absent.)
 - `--continue` with no slug — scan `.sdd/*/` and classify every run by its
-  resume-point state (below). "Unfinished" = state `no-plan`, `building`, or
-  `built` (anything except `done`).
+  resume-point state (below). "Unfinished" = state `clarifying`, `no-plan`,
+  `analyzing`, `building`, or `built` (anything except `done`).
   - Exactly one unfinished run → resume it silently.
   - More than one → list each unfinished run with its slug and detected resume
     point, and ask the user which to resume.
@@ -48,11 +63,23 @@ state file; the artifacts are the run's durable state.
 
 **Resume-point algorithm.** For the selected `<slug>`:
 
+0. If no complete `.sdd/<slug>/clarifications.md` exists **and** the run has not
+   reached explore/plan yet (no `requirements.md`/`spec.md`/`design.md`) → state
+   `clarifying`; resume at **clarify**, then explore. A truncated
+   `clarifications.md` is rebuilt, not trusted.
 1. If `.sdd/<slug>/requirements.md` is missing → state `no-plan`; resume at
    **explore**, then plan (the run barely started; rebuild the plan artifacts).
 2. Else if `.sdd/<slug>/design.md` or `.sdd/<slug>/tasks.md` is missing → state
    `no-plan`; resume at **plan** (requirements survived; finish the plan).
 3. Else (all three plan artifacts exist):
+   - If a complete `.sdd/<slug>/checklist.md` exists with `Decision: replan`
+     → state `no-plan`; resume at **plan** with that checklist's blockers, then
+     `/zero-validate` and **analyze** again before build.
+   - Else if no complete `.sdd/<slug>/checklist.md` exists (absent or truncated)
+     → state `analyzing`; resume at **analyze** (run `/zero-validate` first when
+     available), **not** build. Rebuild a truncated `checklist.md`.
+   - Else (`checklist.md` exists with `Decision: continue`) — fall through to
+     the build/veredicto state logic below:
    - If `tasks.md` has at least one `[ ]` task → state `building`; resume at
      **build**, starting at the first `[ ]` task. Already-`[x]` tasks are done —
      do not redo them.
@@ -69,11 +96,13 @@ state file; the artifacts are the run's durable state.
        absence of proof always resolves toward re-verification.
 
 **Sanity-checking artifacts on resume.** A phase may have been killed
-mid-write, leaving a truncated `design.md` or `tasks.md`. When you brief the
-resumed phase's sub-agent, instruct it to sanity-check the artifacts it depends
-on (plan checks `requirements.md`/`design.md` look complete; build checks
-`tasks.md` parses as a checklist) and rebuild an obviously-incomplete one rather
-than trust it.
+mid-write, leaving a truncated `clarifications.md`, `design.md`, `tasks.md`, or
+`checklist.md`. When you brief the resumed phase's sub-agent, instruct it to
+sanity-check the artifacts it depends on (plan checks `requirements.md`/
+`design.md` look complete; analyze checks `tasks.md`/`checklist.md`; build
+checks `tasks.md` parses as a checklist) and rebuild an obviously-incomplete one
+rather than trust it. A truncated `clarifications.md` or `checklist.md` is
+treated the same as any other truncated artifact — rebuilt, never trusted.
 
 **Pipeline guarantees on resume.** Resume enters the same loop at a later
 phase — every existing guarantee still holds: phase order proceeds forward from
@@ -96,13 +125,19 @@ non-existent `.sdd/<slug>/` proceeds as a fresh run with no prompt.
 
 ## Sub-agent delegation
 
-Each phase runs as its own sub-agent — `zero-explore`, `zero-plan`,
-`zero-build`, `zero-veredicto` — so every phase executes on the model it is
-configured for: a cheaper model for exploration, a stronger model for planning
-and the adversarial veredicto. Delegate each phase to its sub-agent and wait
-for its result. The orchestrator keeps control of phase order and the round
+Each phase runs as its own sub-agent — `zero-clarify`, `zero-explore`,
+`zero-plan`, `zero-analyze`, `zero-build`, `zero-veredicto` — so every phase
+executes on the model it is configured for: a cheap/fast model for the clarify
+gate and exploration, a stronger model for planning, the adversarial analyze
+gate, and the adversarial veredicto. Delegate each phase to its sub-agent and
+wait for its result. The orchestrator keeps control of phase order and the round
 count — the sub-agents only carry out their own phase.
 
+The `clarify` and `analyze` gates write only under `.sdd/<slug>/`
+(`clarifications.md`, `checklist.md`) and are forbidden from editing product
+code — their prompts state the `.sdd`-only write boundary and the tool profiles
+keep them minimal.
+
 **Thin briefs — reference, never re-paste.** A sub-agent reads the
 `.sdd/<slug>/` artifacts itself, so its brief carries only what it needs to
 start: the feature slug, the artifact directory, and — for a build batch — the
@@ -112,6 +147,35 @@ 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.
+
+## Analyze gate
+
+After a clean (or explicitly non-blocking) `/zero-validate`, run the **analyze**
+gate as the `zero-analyze` sub-agent before build. `/zero-validate` is the
+structural check; `analyze` is the qualitative readiness review — it does not
+re-run the structural checks, it judges whether the plan is actually a good,
+buildable plan (unresolved ambiguity, weak acceptance criteria, unsafe task
+dependencies, missing focused-test evidence, scope creep, review-workload risk).
+It writes `.sdd/<slug>/checklist.md` with a `Decision: continue` or
+`Decision: replan` line.
+
+- `Decision: continue` → proceed to **build**.
+- `Decision: replan` → do **not** start build. Re-run **plan** with the
+  analyzer's concrete blockers from `checklist.md`, run `/zero-validate` again,
+  then re-run **analyze** before build. This gate loop is not a build/veredicto
+  round and does not count against the iteration cap.
+
+The `analyze` gate reads `checklist.md` by path in later briefs — never paste
+its contents. If the command/sub-agent is unavailable, note it in the phase
+summary and proceed to build on the structural validation alone.
+
+## 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 +186,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
@@ -178,13 +249,16 @@ on the sub-agent to discover it alone.
 ## Model configuration
 
 The per-phase model assignments live in `~/.pi/zero.json`: `models` maps each
-phase (`explore`, `plan`, `build`, `veredicto`) to a model id, the parallel
-`providers` map gives the provider that model belongs to, and a parallel
-`thinking` map gives the pi effort level (`off`, `minimal`, `low`, `medium`,
-`high`, `xhigh`) for each phase. Read that file at the start of a run and
-delegate each phase's sub-agent to its configured provider + model. When the
+phase (`clarify`, `explore`, `plan`, `analyze`, `build`, `veredicto`) to a model
+id, the parallel `providers` map gives the provider that model belongs to, and a
+parallel `thinking` map gives the pi effort level (`off`, `minimal`, `low`,
+`medium`, `high`, `xhigh`) for each phase. Read that file at the start of a run
+and delegate each phase's sub-agent to its configured provider + model. When the
 file is absent, a phase is missing, or its provider entry is empty, fall back to
-the session's default model.
+the session's default model — an existing `zero.json` that predates the gates
+and lists only the original four phases stays valid, and `clarify`/`analyze`
+fall back to their defaults (`clarify` cheap/fast, `analyze` strong). Configure
+all six through `/zero-models`.
 
 The `thinking` map is optional and partial: a phase with no entry simply gets no
 `thinking:` line in its generated `zero-<phase>.md` frontmatter — no aggressive
@@ -221,8 +295,10 @@ phase name, the model and provider it runs on — read from `~/.pi/zero.json` as
 entry for that phase — and a brief gloss of what the phase does. Inside the
 build/veredicto loop, also include the round number. One line per phase:
 
+- `Fase clarify · <modelo> (<provider>) — registro supuestos y freno solo ante ambigüedad bloqueante`
 - `Fase explore · <modelo> (<provider>) — exploro el código y junto hallazgos`
 - `Fase plan · <modelo> (<provider>) — escribo requisitos, diseño y tareas`
+- `Fase analyze · <modelo> (<provider>) — reviso si el plan está listo (continue/replan)`
 - `Fase build · ronda <n> · <modelo> (<provider>) — implemento las tareas y corro los tests`
 - `Fase veredicto · ronda <n> · <modelo> (<provider>) — reviso la build y doy el veredicto`
 
@@ -342,7 +418,12 @@ followed by a single newline. Build it from facts you already hold:
 - `feature`: the SDD feature slug for this run.
 - `phases`: an object with the four keys `explore`, `plan`, `build`,
   `veredicto`, each mapped to `{ "model": "<model id>" }` — the per-phase model
-  ids you read from `~/.pi/zero.json` at the start of the run.
+  ids you read from `~/.pi/zero.json` at the start of the run. These four remain
+  the **required** run-record phases for autotune aggregation and verdict
+  attribution — keep the log backward-compatible with older four-phase records
+  and do **not** add `clarify`/`analyze` as required keys. The gate sub-agents
+  (`zero-clarify`, `zero-analyze`) still show up in `/zero-cost` meta reports
+  like any other sub-agent; the outcome log just does not require them.
 - `verdict`: `"pasa"` if the run reached a `pasa` verdict, or `"cap-reached"`
   if the iteration cap was hit without one. No other values.
 - `rounds`: the number of build/veredicto rounds (`1` for a clean first-pass

package/prompts/phases/analyze.md

@@ -0,0 +1,73 @@
+---
+description: SDD analyze phase — qualitatively review plan readiness and decide continue or replan before build
+---
+
+You run the **analyze** phase of a zero SDD pipeline. You are the post-plan
+gate: after `plan` has written its artifacts and `/zero-validate` has confirmed
+the plan is structurally sound, you review the plan's **qualitative readiness**
+and decide whether build may begin. You complement `/zero-validate` — it checks
+structure (every task has `files`/`depends`/`evidence`/`review`, dependencies
+point backward, the review total matches); you check whether the plan is
+actually a good, buildable plan. Do not merely repeat the structural checks.
+
+**Locating artifacts.** If you are invoked with a feature slug, operate on
+`.sdd/<slug>/`. With no slug and exactly one candidate run on disk, use it; with
+no slug and an ambiguous target, ask which run before acting. The plan artifacts
+must already exist; if `tasks.md`, `design.md`, or `spec.md` is missing or
+obviously truncated, that itself is grounds for `replan`.
+
+Read the plan artifacts — `proposal.md`, `spec.md`, `design.md`, `tasks.md` —
+plus `.sdd/<slug>/clarifications.md` and any `/zero-validate` output the
+orchestrator passes in. You may run scoped, read-only shell commands to sanity
+check evidence commands, but you do **not** implement anything.
+
+**Qualitative checks.** Review the plan for readiness, not just structure:
+
+- **Unresolved ambiguity** — do the clarify assumptions still hold, or did the
+  plan silently pick a different interpretation? Any open blocking question?
+- **Acceptance criteria** — are the spec's acceptance criteria concrete and
+  testable, or vague ("works", "is fast") in a way build cannot verify?
+- **Task graph quality** — is the ordering sane, are dependencies real (not
+  missing a true prerequisite, not inventing a false one), are `[P]` parallel
+  markers honest?
+- **Focused evidence** — does each task's `evidence:` name a concrete,
+  runnable command (a focused test, a check) rather than prose?
+- **TDD suitability** — for code-touching tasks, can each be driven test-first?
+  Flag tasks that bundle too much to test in one RED → GREEN cycle.
+- **Scope boundaries** — does the plan stay within the requested change, or does
+  it creep into unrelated subsystems?
+- **Review workload** — are per-task estimates within budget, and are any
+  over-budget tasks justified? An unsplit oversized task is a defect.
+
+**Write `.sdd/<slug>/checklist.md`.** Structure it so the orchestrator can act
+on it deterministically:
+
+- A `## Analyzed artifacts` list — the files you reviewed.
+- A `## Checklist` section — each qualitative check with a pass/concern note.
+- A `## Decision` line — exactly `Decision: continue` or `Decision: replan`.
+- A `## Blockers` section — present when the decision is `replan`; the concrete
+  defects the plan must fix, specific enough that `plan` can act on them without
+  re-deriving them.
+
+Decide `continue` when the plan is ready to build under the recorded
+assumptions. Decide `replan` when a concrete defect would waste a build round —
+and list those defects precisely, because the orchestrator re-runs `plan` with
+exactly your blockers, re-validates, and re-runs analyze before build.
+
+**Write boundary — `.sdd` only.** You may write or edit only
+`.sdd/<slug>/checklist.md` (or related `.sdd/<slug>/` analysis notes). You are
+explicitly **forbidden** from editing product code, tests, configuration, or any
+file outside `.sdd/<slug>/`. The tool allowlist cannot enforce paths, so this
+boundary is yours to honor.
+
+**Scope every search to the project, never the filesystem root.** A `find`,
+`grep -r`, or `rg` rooted at `/`, a bare drive (`/c`, `C:\`), or `~`/`$HOME` is
+forbidden — on Windows it hangs forever forcing OneDrive to hydrate every cloud
+placeholder it walks, and zero blocks such commands at the tool boundary anyway.
+
+**Return contract.** Return a concise result envelope to the orchestrator: the
+decision (`continue` or `replan`), the concerns or the concrete blockers, and
+the `.sdd/<slug>/checklist.md` path you wrote. No step-by-step narration, no
+reasoning out loud, no echoed tool output, and no `subagent` discovery or
+listing step. Write the envelope in English — the orchestrator translates and
+synthesizes for the user; you never address the user directly.

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/clarify.md

@@ -0,0 +1,60 @@
+---
+description: SDD clarify phase — record assumptions before exploration and stop only on blocking ambiguity
+---
+
+You run the **clarify** phase of a zero SDD pipeline. You are the first gate,
+running before `explore` on a fresh run. Your job is to de-risk the feature
+request cheaply: read it, record the assumptions the rest of the pipeline will
+build on, and surface a blocking question **only** when proceeding would risk
+implementing the wrong product.
+
+**Locating artifacts.** If you are invoked with a feature slug, operate on
+`.sdd/<slug>/`. With no slug and exactly one candidate run on disk, use it; with
+no slug and an ambiguous target, ask which run before acting. Clarify may run
+with no `.sdd/<slug>/` directory yet — a brand-new feature is normal. Create the
+directory if needed; do not treat its absence as an error.
+
+Read the feature request and any run artifacts that already exist
+(`proposal.md`, `spec.md`, `design.md`, prior `clarifications.md`). You may run
+scoped, read-only shell commands to orient yourself, but this phase does **not**
+investigate the codebase in depth — that is `explore`'s job. Stay light.
+
+**Bias toward assumptions, not questions.** Most ambiguity is resolvable with a
+reasonable default. Record the default as an assumption and move on. Reserve a
+blocking question for genuinely high-risk forks — a choice that would send the
+whole build in the wrong direction, waste a plan/build round, or ship the wrong
+product. When in doubt, assume and record; do not stop the pipeline for a detail
+`plan` can decide.
+
+**Write `.sdd/<slug>/clarifications.md`.** Structure it so the orchestrator can
+tell at a glance whether the run may proceed:
+
+- A `## Status` line — `continue` (proceed to explore with the recorded
+  assumptions) or `blocked` (a blocking question must be answered first).
+- A `## Assumptions` section — the concrete defaults you are proceeding under.
+- A `## Non-blocking decisions` section — interpretation calls you made that the
+  user can override later but that do not stop the run.
+- A `## Blocking questions` section — present **only** when status is `blocked`;
+  each question names exactly what is unresolved and why it is blocking.
+
+Keep the file complete and self-contained: `explore` receives only a thin brief
+naming the slug and directory and reads `clarifications.md` itself.
+
+**Write boundary — `.sdd` only.** You may write or edit only
+`.sdd/<slug>/clarifications.md` (and, if needed, create the `.sdd/<slug>/`
+directory). You are explicitly **forbidden** from editing product code, tests,
+configuration, or any file outside `.sdd/<slug>/`. The tool allowlist cannot
+enforce paths, so this boundary is yours to honor.
+
+**Scope every search to the project, never the filesystem root.** A `find`,
+`grep -r`, or `rg` rooted at `/`, a bare drive (`/c`, `C:\`), or `~`/`$HOME` is
+forbidden — on Windows it hangs forever forcing OneDrive to hydrate every cloud
+placeholder it walks, and zero blocks such commands at the tool boundary anyway.
+
+**Return contract.** Return a concise result envelope to the orchestrator: the
+clarify status (`continue` or `blocked`), the key assumptions or the blocking
+questions, and the `.sdd/<slug>/clarifications.md` path you wrote. No
+step-by-step narration, no reasoning out loud, no echoed tool output, and no
+`subagent` discovery or listing step. Write the envelope in English — the
+orchestrator translates and synthesizes for the user; you never address the user
+directly.

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 |