@gonrocca/zero-pi 0.1.59 → 0.1.61

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,8 +85,8 @@ 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. |
-| **Phase tool gating** | Generated `zero-*` sub-agents get phase-specific tool allowlists: explore/veredicto are read-only, plan writes SDD artifacts, build edits code. |
+| **`/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. |
@@ -179,21 +190,28 @@ 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" },
+  "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). `autotuneBudget` is optional:
+`low`, `medium`, `high`, `xhigh`. An explicit entry always wins; a phase with no
+entry (or an invalid level) falls back to the package default — `clarify:
+medium`, `explore: high`, `plan: high`, `analyze: high`, `build: high`,
+`veredicto: xhigh` — so no phase inherits your session-wide
+`defaultThinkingLevel`. `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
@@ -218,6 +236,18 @@ audits the TDD evidence) and accepts `"off"` to disable the discipline.
 `tdd.testCommand` overrides the auto-detected test runner the TDD cycle invokes;
 leave it empty to let the build/veredicto phases detect it from the project.
 
+### Token efficiency
+
+The phase sub-agents run **without** your global project context
+(`inheritProjectContext: false`): a global `AGENTS.md` is heavy and may carry
+personal data or credentials no phase needs — project conventions still reach
+the phases, because explore/build skim the repo's own `AGENTS.md`/`CLAUDE.md`.
+Every phase runs at an explicit `thinking:` level (your `zero.json` entry wins;
+gaps take the package defaults above), and explore works under a numeric
+tool-call budget with a mid-budget stop check. The heavy lifting happens inside
+the sub-agents on their own models — leave the session that runs `/forge` on
+your cheap default model.
+
 ## Continuous integration
 
 The `.github/workflows/zero-pi-ci.yml` workflow runs on every push to `main` and

package/extensions/autotune-extension.ts

@@ -34,7 +34,13 @@ import {
 } 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];
 

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`.
@@ -16,11 +17,13 @@ import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 
-import { isThinkingLevel } from "./zero-models.ts";
+import { DEFAULT_THINKING, 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];
 
 /**
@@ -37,23 +40,32 @@ export const SUPPORT_MODULES = ["strict-tdd.md", "strict-tdd-verify.md"] as cons
  *
  * 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:`
+ * 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. */
+ *  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,
 };
@@ -103,9 +115,13 @@ export function buildAgentFile(
   if (thinking && isThinkingLevel(thinking)) front.push(`thinking: ${thinking}`);
   front.push(`tools: ${PHASE_TOOLS[phase].join(", ")}`);
   if (!PHASE_COMPLETION_GUARD[phase]) front.push("completionGuard: false");
+  // `inheritProjectContext: false` keeps the user's global AGENTS.md out of
+  // every phase sub-agent: it is heavy (re-sent to each phase) and may carry
+  // personal data or credentials no phase needs. Project conventions still
+  // reach the phases — explore/build skim the repo's own AGENTS.md/CLAUDE.md.
   front.push(
     "systemPromptMode: replace",
-    "inheritProjectContext: true",
+    "inheritProjectContext: false",
     "inheritSkills: false",
     "---",
   );
@@ -164,6 +180,17 @@ export function phaseThinking(data: unknown, phase: Phase): ThinkingLevel | unde
   return undefined;
 }
 
+/**
+ * Resolve the effective `thinking:` level for a phase: the user's valid
+ * `zero.json` entry (or recoverable legacy suffix) wins; a missing or invalid
+ * entry falls back to the package default, so no generated agent ever inherits
+ * the session-wide `defaultThinkingLevel` from the user's settings. Exported
+ * for tests.
+ */
+export function resolvePhaseThinking(data: unknown, phase: Phase): ThinkingLevel {
+  return phaseThinking(data, phase) ?? DEFAULT_THINKING[phase];
+}
+
 /** Read the per-phase model from `~/.pi/zero.json`; `undefined` when absent. */
 function readPhaseModel(phase: Phase): string | undefined {
   try {
@@ -212,7 +239,7 @@ export default function register(_pi?: unknown): void {
           body,
           description,
           readPhaseModel(phase),
-          readPhaseThinking(phase),
+          readPhaseThinking(phase) ?? DEFAULT_THINKING[phase],
         );
         writeFileSync(join(agentsDir, `zero-${phase}.md`), file, "utf8");
       } catch {

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-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,15 +76,33 @@ 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",
 };
 
+/** Package default thinking level per phase, used to fill any gap in the
+ *  user's `zero.json` when the agent files are generated — so no phase ever
+ *  inherits the session-wide `defaultThinkingLevel` from the user's settings.
+ *  An explicit valid `zero.json` entry always wins. The gates get a level
+ *  proportional to their job (clarify records assumptions, analyze reviews
+ *  artifacts); veredicto keeps `xhigh` as the pipeline's adversarial guard. */
+export const DEFAULT_THINKING: Record<Phase, ThinkingLevel> = {
+  clarify: "medium",
+  explore: "high",
+  plan: "high",
+  analyze: "high",
+  build: "high",
+  veredicto: "xhigh",
+};
+
 /** Model list used only when pi's model registry is unavailable. */
 const FALLBACK_MODELS = [
   "claude-opus-4-8",
@@ -144,7 +164,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 +805,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/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@gonrocca/zero-pi",
-  "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.",
+  "version": "0.1.61",
+  "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",

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
@@ -116,6 +151,27 @@ batched build issues many briefs.
 
 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`.
@@ -193,19 +249,25 @@ 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 `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
-default is written. When a phase has a valid level, the generated agent file
-carries a `thinking: <level>` line in its frontmatter (placed after `model:` and
-before `systemPromptMode:`), so the sub-agent runs at that effort level.
+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: an explicit valid entry always
+wins, and a phase with no entry (or an invalid level) falls back to the package
+default — `clarify: medium`, `explore: high`, `plan: high`, `analyze: high`,
+`build: high`, `veredicto: xhigh` — so no phase silently inherits the
+session-wide `defaultThinkingLevel` from the user's settings. Every generated
+`zero-<phase>.md` therefore carries a `thinking: <level>` line in its
+frontmatter (placed after `model:` and before `systemPromptMode:`), so the
+sub-agent runs at that effort level.
 
 ## Language Boundary
 
@@ -236,8 +298,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`
 
@@ -357,7 +421,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

@@ -22,6 +22,8 @@ re-read a file you already read this run unless you have changed it since —
 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.
+If the project root carries an `AGENTS.md` or `CLAUDE.md`, skim it once for
+project conventions — you receive no global user context.
 
 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.
 

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

@@ -13,6 +13,8 @@ is normal; do not treat the missing directory as an error.
 Investigate the codebase and the feature request read-only. Do not modify any
 files. Map the relevant modules, the existing patterns and conventions, the
 integration points, and the constraints. Identify the risks and the unknowns.
+If the project root carries an `AGENTS.md` or `CLAUDE.md`, skim it once for
+project conventions — you receive no global user context.
 
 **Size exploration to the request.** Match breadth to what the change actually
 needs. A localized change — copy/text, one component, a config value, a single
@@ -21,8 +23,15 @@ wiring; do not map the full permission/billing model or unrelated subsystems
 unless the request touches them. A cross-cutting or architectural change earns
 full breadth. Stop once you can name the exact files to change and their
 constraints — reading past that point burns tokens without improving the plan.
-As a rough gauge, a localized change rarely needs more than ~20 tool calls; if
-you blow past that on a small request, you are over-exploring.
+
+**Exploration budget.** Classify the request from `request.md` before the first
+tool call: a localized change gets a budget of **20 tool calls**; a
+cross-cutting or architectural change gets **40**. At half budget, checkpoint:
+if you can already name the exact files to change and their constraints, STOP
+and write the findings. Exceeding the budget requires a
+`Budget exceeded: <concrete reason>` line inside `findings.md`, and whatever you
+did not get to goes into a `## Unknowns` section of the findings instead of more
+reading.
 
 **Scope every search to the project, never the filesystem root.** Search inside
 the repo/code directory you are working in. A `find`, `grep -r`, or `rg` rooted