@gonrocca/zero-pi 0.1.53 → 0.1.55

package/README.md

@@ -74,7 +74,7 @@ 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 for each SDD phase — a boxed-window picker, or set one directly. |
+| **`/zero-models`** | Pick the model + provider + thinking level for each SDD phase — a boxed-window picker, or set one directly. |
 | **Autotune** | Learns which model fits each phase from your run history and re-tunes itself. |
 | **`/zero-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. |
@@ -92,7 +92,7 @@ into `/forge` for you.
 | Command | Does |
 | ------- | ---- |
 | `/forge <feature>` | Run the SDD pipeline — `--continue [slug]` resumes. |
-| `/zero-models [<phase>=[<provider>/]<model>]` | Show or set per-phase models — `autotune=auto\|ask\|off`. |
+| `/zero-models [<phase>=[<provider>/]<model> [thinking=<level>]]` | Show or set per-phase models, providers, and thinking — `thinking=<level>` (`off\|minimal\|low\|medium\|high\|xhigh`); `autotune=auto\|ask\|off`. |
 | `/zero-sync <slug>` | Fold a run's spec delta into the canonical spec store; a first all-`## ADDED` delta creates the store lazily. |
 | `/zero-archive <slug>` | Merge an approved run into `.sdd/specs/`, move it to `.sdd/archive/YYYY-MM-DD-<slug>/`, and persist `archivePath`. |
 | `/zero-validate <slug>` | Validate proposal/spec/design/tasks artifacts, including task schema and per-domain specs. |
@@ -165,9 +165,31 @@ Acceptance criteria:
 
 ## 🔧 Configuration
 
-zero-pi keeps its state in `~/.pi/zero.json` (per-phase models + autotune mode)
-and `~/.pi/zero-runs.jsonl` (the run-metrics log); per-project artifacts live
-under `.sdd/`. Set `ZERO_RESUME=off` to disable the conversation-resume note.
+zero-pi keeps its state in `~/.pi/zero.json` (per-phase `models`, `providers`,
+`thinking`, and autotune mode) and `~/.pi/zero-runs.jsonl` (the run-metrics log);
+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:
+
+```json
+{
+  "models":    { "explore": "claude-haiku-4-5", "build": "claude-sonnet-4-6" },
+  "providers": { "explore": "anthropic",        "build": "anthropic" },
+  "thinking":  { "explore": "low",              "build": "high" },
+  "autotune": "ask"
+}
+```
+
+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:
+
+```
+/zero-models build=anthropic/claude-sonnet-4-6 thinking=high
+/zero-models build=anthropic/claude-sonnet-4-6 high      # trailing shorthand
+```
 
 `.sdd/config.json` carries the per-project git and TDD settings:
 

package/extensions/sdd-agents.ts

@@ -16,6 +16,9 @@ import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 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;
 export type Phase = (typeof PHASES)[number];
@@ -59,6 +62,7 @@ export function buildAgentFile(
   body: string,
   description: string,
   model: string | undefined,
+  thinking?: ThinkingLevel,
 ): string {
   const front = [
     "---",
@@ -66,6 +70,11 @@ export function buildAgentFile(
     `description: ${description || `zero SDD ${phase} phase`}`,
   ];
   if (model) front.push(`model: ${model}`);
+  // The `thinking:` line sits after the optional `model:` and before
+  // `systemPromptMode:`. It is emitted only when a level is present AND valid —
+  // 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(
     "systemPromptMode: replace",
     "inheritProjectContext: true",
@@ -101,6 +110,32 @@ export function phaseModel(data: unknown, phase: Phase): string | undefined {
   return model;
 }
 
+/**
+ * Resolve the agent `thinking:` level for a phase from a parsed `zero.json`.
+ *
+ * The explicit `thinking[phase]` value wins when it is one of the six real pi
+ * effort levels. Otherwise a legacy model string of the form `"<model> <level>"`
+ * is mined: its trailing whitespace-separated token supplies the level, but
+ * only when that token is a valid level. `max`/`ultracode` and any other token
+ * resolve to `undefined`, so no `thinking:` line is emitted. Exported for tests.
+ */
+export function phaseThinking(data: unknown, phase: Phase): ThinkingLevel | undefined {
+  if (!data || typeof data !== "object") return undefined;
+  const d = data as {
+    thinking?: Record<string, unknown>;
+    models?: Record<string, unknown>;
+  };
+  const direct = d.thinking?.[phase];
+  if (isThinkingLevel(direct)) return direct;
+  // Legacy recovery: a valid trailing level on "<model> <level>".
+  const model = d.models?.[phase];
+  if (typeof model === "string" && model.trim().includes(" ")) {
+    const tail = model.trim().split(/\s+/).slice(-1)[0];
+    if (isThinkingLevel(tail)) return tail;
+  }
+  return undefined;
+}
+
 /** Read the per-phase model from `~/.pi/zero.json`; `undefined` when absent. */
 function readPhaseModel(phase: Phase): string | undefined {
   try {
@@ -113,6 +148,19 @@ function readPhaseModel(phase: Phase): string | undefined {
   }
 }
 
+/** Read the per-phase thinking level from `~/.pi/zero.json`; `undefined` when
+ *  absent, invalid, or unrecoverable. Mirrors {@link readPhaseModel}. */
+function readPhaseThinking(phase: Phase): ThinkingLevel | undefined {
+  try {
+    return phaseThinking(
+      JSON.parse(readFileSync(join(homedir(), ".pi", "zero.json"), "utf8")),
+      phase,
+    );
+  } catch {
+    return undefined;
+  }
+}
+
 /**
  * The pi extension entry point. Generates the four `zero-<phase>` agent files
  * so `/forge` has real sub-agents to delegate to. Every failure is swallowed —
@@ -131,7 +179,13 @@ export default function register(_pi?: unknown): void {
       try {
         const raw = readFileSync(join(phasesDir, `${phase}.md`), "utf8");
         const { description, body } = splitPhasePrompt(raw);
-        const file = buildAgentFile(phase, body, description, readPhaseModel(phase));
+        const file = buildAgentFile(
+          phase,
+          body,
+          description,
+          readPhaseModel(phase),
+          readPhaseThinking(phase),
+        );
         writeFileSync(join(agentsDir, `zero-${phase}.md`), file, "utf8");
       } catch {
         // A single phase failing must not block the other three.

package/extensions/zero-models-picker.ts

@@ -12,7 +12,7 @@
 // new state. Type-only imports are `import type` so `--experimental-strip-types`
 // erases them with no runtime resolution. Mirrors the `autotune.ts` precedent.
 
-import type { Phase, PhaseModels, PhaseProviders } from "./zero-models.ts";
+import type { Phase, PhaseModels, PhaseProviders, PhaseThinking, ThinkingLevel } from "./zero-models.ts";
 import type { AutotuneMode } from "./autotune.ts";
 import type { AutotunePending } from "./autotune-extension.ts";
 
@@ -24,12 +24,17 @@ const PHASES = ["explore", "plan", "build", "veredicto"] as const;
 /** The three autotune modes offered on the autotune screen. */
 const AUTOTUNE_MODES = ["auto", "ask", "off"] as const;
 
+/** The six real pi effort levels, in ascending order — re-stated locally so
+ *  the pure module carries no value import. Must stay in lockstep with
+ *  `THINKING_LEVELS` in `zero-models.ts`. No `max`/`ultracode` aliases. */
+const THINKING_LEVELS = ["off", "minimal", "low", "medium", "high", "xhigh"] as const;
+
 // ---------------------------------------------------------------------------
 // Screen model
 // ---------------------------------------------------------------------------
 
 /** Which sub-screen the picker is currently showing. */
-export type Screen = "main" | "provider" | "model" | "autotune";
+export type Screen = "main" | "provider" | "model" | "thinking" | "autotune";
 
 /** One selectable row in the current screen. */
 export interface MenuEntry {
@@ -43,6 +48,7 @@ export interface MenuEntry {
     | "custom-provider" // — otro provider (escribir) —
     | "model" // a concrete model id        (model screen)
     | "custom-model" // — otro modelo (escribir) —
+    | "thinking-level" // off | minimal | … | xhigh   (thinking screen)
     | "autotune-mode"; // auto | ask | off           (autotune screen)
   /** The text shown for the row (Spanish, voseo). */
   label: string;
@@ -60,6 +66,9 @@ export interface StagedEdits {
   models: PhaseModels;
   /** From `readProviders` — a mutated copy, parallel to {@link models}. */
   providers: PhaseProviders;
+  /** From `readThinking` — a mutated copy, parallel to {@link models}. A
+   *  partial map: an absent phase means no thinking level configured. */
+  thinking: PhaseThinking;
   /** The autotune mode, possibly changed from disk. */
   autotuneMode: AutotuneMode;
   /** Any phase model/provider changed. */
@@ -95,6 +104,9 @@ export interface PickerState {
   drillPhase: Phase | null;
   /** Drill-down context: provider chosen so far (model screen). */
   drillProvider: string | null;
+  /** Drill-down context: the model chosen, awaiting a thinking level
+   *  (thinking screen). Held out of `edits` until a level commits it. */
+  drillModel: string | null;
   /** When non-null, the component shows an inline text input for this. */
   textPrompt: { for: "provider" | "model"; label: string } | null;
 }
@@ -120,15 +132,19 @@ const CUSTOM_MODEL_LABEL = "— otro modelo (escribir) —";
 /** The save-and-exit row label. */
 const SAVE_LABEL = "— guardar y salir —";
 
-/** Render a phase's current `provider/model` (provider omitted when empty). */
+/** Render a phase's current `provider/model` (provider omitted when empty),
+ *  with ` · thinking <level>` appended when a level is staged — mirroring
+ *  `formatPhases` in `zero-models.ts`. No artifact when no level is set. */
 function phaseLabel(
   phase: Phase,
   models: PhaseModels,
   providers: PhaseProviders,
+  thinking: PhaseThinking,
 ): string {
   const provider = providers[phase];
   const model = provider ? `${provider}/${models[phase]}` : models[phase];
-  return `${phase}   →   ${model}`;
+  const level = thinking[phase];
+  return `${phase}   →   ${model}${level ? ` · thinking ${level}` : ""}`;
 }
 
 /** Render the `★ aplicar sugerencia` label from the pending adjustments. */
@@ -149,6 +165,7 @@ function applyLabel(pending: readonly AutotunePending[]): string {
 export function createPickerState(input: {
   models: PhaseModels;
   providers: PhaseProviders;
+  thinking: PhaseThinking;
   autotuneMode: AutotuneMode;
   pending: AutotunePending[];
   groups: Map<string, string[]>;
@@ -161,6 +178,7 @@ export function createPickerState(input: {
     edits: {
       models: { ...input.models },
       providers: { ...input.providers },
+      thinking: { ...input.thinking },
       autotuneMode: input.autotuneMode,
       changed: false,
       autotuneChanged: false,
@@ -171,6 +189,7 @@ export function createPickerState(input: {
     fallbackModels: input.fallbackModels,
     drillPhase: null,
     drillProvider: null,
+    drillModel: null,
     textPrompt: null,
   };
   return rebuildEntries(state);
@@ -197,7 +216,12 @@ function mainEntries(state: PickerState): MenuEntry[] {
   for (const phase of PHASES) {
     entries.push({
       kind: "phase",
-      label: phaseLabel(phase, state.edits.models, state.edits.providers),
+      label: phaseLabel(
+        phase,
+        state.edits.models,
+        state.edits.providers,
+        state.edits.thinking,
+      ),
       value: phase,
     });
   }
@@ -242,6 +266,15 @@ function modelEntries(state: PickerState): MenuEntry[] {
   return entries;
 }
 
+/** Build the rows for the `thinking` screen — the six real pi effort levels. */
+function thinkingEntries(): MenuEntry[] {
+  return THINKING_LEVELS.map((level) => ({
+    kind: "thinking-level" as const,
+    label: level,
+    value: level,
+  }));
+}
+
 /** Build the rows for the `autotune` screen — the three modes. */
 function autotuneEntries(): MenuEntry[] {
   return AUTOTUNE_MODES.map((mode) => ({
@@ -270,6 +303,9 @@ export function rebuildEntries(state: PickerState): PickerState {
     case "model":
       state.entries = modelEntries(state);
       break;
+    case "thinking":
+      state.entries = thinkingEntries();
+      break;
     case "autotune":
       state.entries = autotuneEntries();
       break;
@@ -365,20 +401,34 @@ export function enter(state: PickerState): EnterResult {
     }
 
     case "model": {
-      if (state.drillPhase !== null) {
+      // Selecting a model no longer commits — it stages the model in
+      // `drillModel` and advances to the thinking screen, so model + provider
+      // + thinking are written together (atomically) only when a level is
+      // chosen. An Esc before that leaves `edits` untouched.
+      state.drillModel = entry.value;
+      state.screen = "thinking";
+      state.cursor = 0;
+      return { type: "state", state: rebuildEntries(state) };
+    }
+
+    case "thinking-level": {
+      // The single commit point: write model + provider + thinking together
+      // for the drilled phase, then clear all drill context and return to main.
+      const level = entry.value as ThinkingLevel;
+      if (state.drillPhase !== null && state.drillModel !== null) {
         const phase = state.drillPhase;
-        state.edits.models[phase] = entry.value;
+        state.edits.models[phase] = state.drillModel;
         // `drillProvider` is the provider picked/typed on the provider screen,
-        // or `null` when the empty-registry skip jumped straight here — in
-        // which case there is no provider, so `""`. (The design's middle
-        // `resolveProvider` term is unreachable in the pure module: a null
-        // `drillProvider` only ever co-occurs with an empty `groups`.)
+        // or `null` when the empty-registry skip jumped straight to the model
+        // screen — in which case there is no provider, so `""`.
         state.edits.providers[phase] = state.drillProvider ?? "";
+        state.edits.thinking[phase] = level;
         state.edits.changed = true;
       }
       state.screen = "main";
       state.drillPhase = null;
       state.drillProvider = null;
+      state.drillModel = null;
       state.cursor = 0;
       return { type: "state", state: rebuildEntries(state) };
     }
@@ -428,6 +478,10 @@ export function back(state: PickerState): EnterResult {
   state.screen = "main";
   state.drillPhase = null;
   state.drillProvider = null;
+  // Clearing `drillModel` here is what makes the model+provider+thinking write
+  // atomic: Esc from the thinking screen drops the staged model so no partial
+  // edit is ever committed.
+  state.drillModel = null;
   state.textPrompt = null;
   state.cursor = 0;
   return { type: "state", state: rebuildEntries(state) };
@@ -470,16 +524,11 @@ export function submitText(state: PickerState, typed: string): PickerState {
     state.screen = "model";
     state.cursor = 0;
   } else {
-    // prompt.for === "model": commit the typed model into the drilled phase.
-    if (state.drillPhase !== null) {
-      const phase = state.drillPhase;
-      state.edits.models[phase] = value;
-      state.edits.providers[phase] = state.drillProvider ?? "";
-      state.edits.changed = true;
-    }
-    state.screen = "main";
-    state.drillPhase = null;
-    state.drillProvider = null;
+    // prompt.for === "model": stage the typed model in `drillModel` and advance
+    // to the thinking screen — the commit happens atomically when a level is
+    // chosen, never here. Mirrors the `model`-row `enter` path.
+    state.drillModel = value;
+    state.screen = "thinking";
     state.cursor = 0;
   }
 

package/extensions/zero-models.ts

@@ -60,6 +60,20 @@ export type PhaseModels = Record<Phase, string>;
 /** The per-phase provider map — parallel to {@link PhaseModels}. */
 export type PhaseProviders = Record<Phase, string>;
 
+/** The six real pi effort levels, in ascending order. The single source of
+ *  truth for thinking-level validity — no `max`/`ultracode` aliases exist. */
+export const THINKING_LEVELS = ["off", "minimal", "low", "medium", "high", "xhigh"] as const;
+/** One of the six real pi effort levels. */
+export type ThinkingLevel = (typeof THINKING_LEVELS)[number];
+/** The per-phase thinking map — partial on purpose: an absent phase means
+ *  "no thinking configured", which renders to no `thinking:` frontmatter. */
+export type PhaseThinking = Partial<Record<Phase, ThinkingLevel>>;
+
+/** Whether a value is one of the six real pi effort levels. */
+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. */
 const DEFAULT_MODELS: PhaseModels = {
@@ -105,11 +119,25 @@ export function readModels(data: Record<string, unknown>): PhaseModels {
   const raw = (data.models ?? {}) as Record<string, unknown>;
   const models: PhaseModels = { ...DEFAULT_MODELS };
   for (const phase of PHASES) {
-    if (typeof raw[phase] === "string") models[phase] = raw[phase] as string;
+    if (typeof raw[phase] === "string") models[phase] = stripThinkingSuffix(raw[phase] as string);
   }
   return models;
 }
 
+/**
+ * Strip a single whitespace-separated trailing token from a stored model string
+ * only when that token is a valid thinking level (legacy `"<model> <level>"`
+ * form). A non-level trailing token is left intact — dropping it would silently
+ * lose data — and a plain model id is returned unchanged.
+ */
+function stripThinkingSuffix(model: string): string {
+  const trimmed = model.trim();
+  const idx = trimmed.lastIndexOf(" ");
+  if (idx < 0) return model;
+  const tail = trimmed.slice(idx + 1);
+  return isThinkingLevel(tail) ? trimmed.slice(0, idx).trim() : model;
+}
+
 /**
  * Extract the per-phase providers from a zero.json object. A missing provider
  * is an empty string — the consumer resolves or ignores it.
@@ -123,16 +151,83 @@ export function readProviders(data: Record<string, unknown>): PhaseProviders {
   return providers;
 }
 
+/**
+ * Extract the per-phase thinking levels from a zero.json object.
+ *
+ * For each phase the explicit `thinking[phase]` value wins when it is a valid
+ * level. Otherwise a legacy model string of the form `"<model> <level>"` is
+ * mined: its trailing whitespace-separated token supplies the level, but only
+ * when that token is one of the six real levels. The result is a partial map —
+ * a phase with no valid or recoverable level is simply absent, never defaulted.
+ */
+export function readThinking(data: Record<string, unknown>): PhaseThinking {
+  const out: PhaseThinking = {};
+  const raw = (data.thinking ?? {}) as Record<string, unknown>;
+  const models = data.models as Record<string, unknown> | undefined;
+  for (const phase of PHASES) {
+    if (isThinkingLevel(raw[phase])) {
+      out[phase] = raw[phase];
+      continue;
+    }
+    // Legacy recovery: "<model> <level>" with a valid trailing level.
+    const model = models?.[phase];
+    if (typeof model === "string") {
+      const trimmed = model.trim();
+      const tail = trimmed.split(/\s+/).slice(-1)[0];
+      if (trimmed.includes(" ") && isThinkingLevel(tail)) out[phase] = tail;
+    }
+  }
+  return out;
+}
+
 /** A provider-qualified model assignment from the direct command form. */
 export interface Assignment {
   phase: Phase;
   model: string;
   provider?: string;
+  thinking?: ThinkingLevel;
+}
+
+/** The result of mining a thinking token out of an assignment value:
+ *  the cleaned value plus the level, or the `"invalid"` sentinel when an
+ *  explicit `thinking=` token names an unknown level. */
+export type ThinkingTokenResult = { value: string; thinking?: ThinkingLevel } | "invalid";
+
+/**
+ * Mine a thinking level out of an assignment value.
+ *
+ * Precedence:
+ *   1. An explicit `thinking=<level>` token anywhere in the value. When the
+ *      level is valid it is removed from the value and returned; when it is
+ *      unknown the whole parse is `"invalid"` so the handler shows usage help.
+ *   2. Otherwise a trailing bare `<level>` token — recognized only when it is
+ *      one of the six real levels; a non-level trailing token stays in the value.
+ *   3. Otherwise the value is returned unchanged with no thinking.
+ */
+export function parseThinkingToken(value: string): ThinkingTokenResult {
+  const tokens = value.trim().split(/\s+/);
+  // 1. explicit thinking=<level> anywhere in the value.
+  const idx = tokens.findIndex((t) => /^thinking=/i.test(t));
+  if (idx >= 0) {
+    const level = tokens[idx].slice("thinking=".length);
+    if (!isThinkingLevel(level)) return "invalid";
+    const rest = tokens.slice(0, idx).concat(tokens.slice(idx + 1));
+    return { value: rest.join(" "), thinking: level };
+  }
+  // 2. trailing bare <level> shorthand.
+  if (tokens.length > 1 && isThinkingLevel(tokens[tokens.length - 1])) {
+    return { value: tokens.slice(0, -1).join(" "), thinking: tokens[tokens.length - 1] };
+  }
+  // 3. no thinking token.
+  return { value: value.trim() };
 }
 
 /**
  * Parse a direct `<phase>=<model>` assignment. The value may carry an explicit
- * provider as `<provider>/<model>` — the first `/` splits them.
+ * provider as `<provider>/<model>` — the first `/` splits them — and an optional
+ * thinking level via `thinking=<level>` or a trailing bare `<level>` shorthand.
+ * An invalid explicit thinking level makes the whole parse `null` so the handler
+ * writes nothing and shows usage help.
  */
 export function parseAssignment(arg: string): Assignment | null {
   const match = arg.trim().match(/^(\w+)\s*[=\s]\s*(.+)$/);
@@ -142,18 +237,40 @@ export function parseAssignment(arg: string): Assignment | null {
   let value = match[2].trim();
   if (value === "") return null;
 
+  const parsed = parseThinkingToken(value);
+  if (parsed === "invalid") return null;
+  value = parsed.value.trim();
+  if (value === "") return null;
+  const thinking = parsed.thinking;
+
   const slash = value.indexOf("/");
   if (slash > 0 && slash < value.length - 1) {
-    return { phase, provider: value.slice(0, slash).trim(), model: value.slice(slash + 1).trim() };
+    const out: Assignment = {
+      phase,
+      provider: value.slice(0, slash).trim(),
+      model: value.slice(slash + 1).trim(),
+    };
+    if (thinking) out.thinking = thinking;
+    return out;
   }
-  return { phase, model: value };
+  const out: Assignment = { phase, model: value };
+  if (thinking) out.thinking = thinking;
+  return out;
 }
 
-/** Render the per-phase model map as an aligned `provider/model` block. */
-export function formatPhases(models: PhaseModels, providers: PhaseProviders): string {
+/**
+ * Render the per-phase model map as an aligned `provider/model` block, with the
+ * thinking level appended as ` · thinking <level>` for any phase that has one.
+ */
+export function formatPhases(
+  models: PhaseModels,
+  providers: PhaseProviders,
+  thinking: PhaseThinking,
+): string {
   return PHASES.map((phase) => {
     const provider = providers[phase];
-    const label = provider ? `${provider}/${models[phase]}` : models[phase];
+    let label = provider ? `${provider}/${models[phase]}` : models[phase];
+    if (thinking[phase]) label += ` · thinking ${thinking[phase]}`;
     return `  ${phase.padEnd(10)} ${label}`;
   }).join("\n");
 }
@@ -541,6 +658,7 @@ export default function register(pi?: PiExtensionAPI): void {
         const data = readZeroJson();
         const models = readModels(data);
         const providers = readProviders(data);
+        const thinking = readThinking(data);
         const groups = providerGroups(ctx.modelRegistry);
 
         // Direct form: /zero-models build=claude-opus-4-7
@@ -566,11 +684,23 @@ export default function register(pi?: PiExtensionAPI): void {
             return;
           }
 
+          // A malformed explicit `thinking=<level>` gets a targeted usage help
+          // and writes nothing — distinct from the generic assignment help.
+          const thinkingToken = arg.match(/(?:^|\s)thinking=(\S+)/i);
+          if (thinkingToken && !isThinkingLevel(thinkingToken[1])) {
+            ctx.ui.notify(
+              "uso: thinking=<nivel>  (nivel: off | minimal | low | medium | high | xhigh)",
+              "warning",
+            );
+            return;
+          }
+
           const assignment = parseAssignment(arg);
           if (!assignment) {
             ctx.ui.notify(
-              "uso: /zero-models  —o—  /zero-models <fase>=[<provider>/]<modelo> " +
-                "(fase: explore | plan | build | veredicto)  —o—  " +
+              "uso: /zero-models  —o—  /zero-models <fase>=[<provider>/]<modelo> [thinking=<nivel>] " +
+                "(fase: explore | plan | build | veredicto · " +
+                "nivel: off | minimal | low | medium | high | xhigh)  —o—  " +
                 "/zero-models autotune=<modo>",
               "warning",
             );
@@ -581,15 +711,25 @@ export default function register(pi?: PiExtensionAPI): void {
             assignment.provider ??
             resolveProvider(ctx.modelRegistry, assignment.model) ??
             providers[assignment.phase];
-          writeFileSync(
-            zeroJsonPath(),
-            `${JSON.stringify({ ...data, models, providers }, null, 2)}\n`,
-            "utf8",
-          );
+          // Resolve the thinking map: start from the recovered/persisted levels
+          // (legacy suffixes already mined by `readThinking`), apply the new
+          // level when given, preserve the prior level when absent. `models` was
+          // read via `readModels`, which already stripped any valid legacy
+          // suffix — so the written store is normalized (model token only).
+          const nextThinking = { ...thinking };
+          if (assignment.thinking) nextThinking[assignment.phase] = assignment.thinking;
+          const merged: Record<string, unknown> = { ...data, models, providers };
+          if (Object.keys(nextThinking).length > 0) merged.thinking = nextThinking;
+          else delete merged.thinking;
+          writeFileSync(zeroJsonPath(), `${JSON.stringify(merged, null, 2)}\n`, "utf8");
           const shown = providers[assignment.phase]
             ? `${providers[assignment.phase]}/${assignment.model}`
             : assignment.model;
-          ctx.ui.notify(`zero models: ${assignment.phase} → ${shown}`, "info");
+          const level = nextThinking[assignment.phase];
+          ctx.ui.notify(
+            `zero models: ${assignment.phase} → ${shown}${level ? ` · thinking ${level}` : ""}`,
+            "info",
+          );
           return;
         }
 
@@ -600,6 +740,7 @@ export default function register(pi?: PiExtensionAPI): void {
         const initialState = createPickerState({
           models,
           providers,
+          thinking,
           autotuneMode,
           pending,
           groups,
@@ -618,7 +759,7 @@ export default function register(pi?: PiExtensionAPI): void {
           // `zero.json` byte-for-byte unchanged, and report the leave-as-is
           // state — the existing "sin cambios" notification text.
           ctx.ui.notify(
-            `zero · modelos SDD (sin cambios):\n${formatPhases(models, providers)}\n` +
+            `zero · modelos SDD (sin cambios):\n${formatPhases(models, providers, thinking)}\n` +
               `  autotune   ${autotuneMode}`,
             "info",
           );
@@ -634,21 +775,26 @@ export default function register(pi?: PiExtensionAPI): void {
             models: edits.models,
             providers: edits.providers,
           };
+          // Persist the staged per-phase thinking map alongside models/
+          // providers; omit the key entirely when no phase has a level so the
+          // store stays byte-minimal and backward-compatible.
+          if (Object.keys(edits.thinking).length > 0) patch.thinking = edits.thinking;
           if (edits.autotuneChanged) patch.autotune = edits.autotuneMode;
 
           const merged = { ...data, ...patch };
+          if (Object.keys(edits.thinking).length === 0) delete merged.thinking;
           if (edits.pendingApplied) delete merged.autotunePending;
           writeFileSync(zeroJsonPath(), `${JSON.stringify(merged, null, 2)}\n`, "utf8");
 
           const summary = [
-            `zero · modelos SDD guardados:\n${formatPhases(edits.models, edits.providers)}`,
+            `zero · modelos SDD guardados:\n${formatPhases(edits.models, edits.providers, edits.thinking)}`,
           ];
           summary.push(`  autotune   ${edits.autotuneMode}`);
           if (edits.pendingApplied) summary.push("sugerencia aplicada");
           ctx.ui.notify(summary.join("\n"), "info");
         } else {
           ctx.ui.notify(
-            `zero · modelos SDD (sin cambios):\n${formatPhases(edits.models, edits.providers)}\n` +
+            `zero · modelos SDD (sin cambios):\n${formatPhases(edits.models, edits.providers, edits.thinking)}\n` +
               `  autotune   ${edits.autotuneMode}`,
             "info",
           );

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gonrocca/zero-pi",
-  "version": "0.1.53",
+  "version": "0.1.55",
   "description": "zero-pi — an installable layer for pi (pi.dev): the zero spec-driven development workflow (explore → plan → build → veredicto) with per-phase model autotune and token-efficient batched builds. Adds capability to pi without modifying pi.",
   "type": "module",
   "keywords": [

package/prompts/orchestrator.md

@@ -178,11 +178,19 @@ 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, and the parallel
-`providers` map gives the provider that model belongs to. 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.
+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
+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.
 
 ## Language Boundary
 
@@ -392,41 +400,45 @@ Recommended command order for an audit-ready SDD change is: `/zero-branch <slug>
 - `/zero-git-validate <slug>` checks worktree, branch, remote, `gh auth`, and verdict gating without mutating.
 - `/zero-archive <slug>` merges approved deltas into `.sdd/specs/` and moves the run to `.sdd/archive/YYYY-MM-DD-<slug>/`.
 
-## Spec sync & archive
+## Spec archive
 
 The project keeps a **canonical spec store** at `.sdd/specs/requirements.md` —
 the accepted requirements of every prior run. A `/forge` run's `plan` phase
 emits a delta `spec.md` against that store; once the run reaches a `pasa`
-verdict the delta is folded back into the store.
+verdict the delta is folded back into the store and the run is archived. One
+command does both: **`/zero-archive`**. (The older `/zero-sync` still exists as a
+manual fold-only command, but the pipeline drives `/zero-archive`, which already
+folds the delta itself — never run both for the same run.)
 
 **After a `pasa` verdict — and only then.** Alongside the Cortex save and the
 `zero-runs.jsonl` append, invoke the **`/zero-archive <slug>`** command, passing
 the run's feature slug explicitly. `/zero-archive` is a real pi command — a
-deterministic, unit-tested merge, not a prompt instruction — that reads
-`.sdd/specs/requirements.md` or per-domain `.sdd/specs/<domain>/requirements.md`
-and `.sdd/<slug>/spec.md` or `.sdd/<slug>/specs/<domain>/spec.md`, folds the
-delta into the store, writes atomically, moves the run to `.sdd/archive/`, and
-records `archivePath` in `links.json`. You only call it; you never edit the store yourself.
-
-**Never sync on a non-`pasa` outcome.** Do **not** invoke `/zero-sync` for a
-`corregir` or `replantear` verdict, or when the iteration cap was reached
-without a `pasa` — the store is changed by a `pasa` run only, and no archive
-entry is created otherwise. Likewise skip it for a **legacy resumed run** whose
-`.sdd/<slug>/` has no `spec.md` (the older artifact shape) — that run has no
-delta to fold, and `/zero-sync` will report it has nothing to sync.
-
-**On a guardrail error, surface — do not claim a sync.** If `/zero-sync`
+deterministic, unit-tested operation, not a prompt instruction. In one step it
+folds the delta into the store (`.sdd/specs/requirements.md`, or per-domain
+`.sdd/specs/<domain>/requirements.md`), writes the store atomically, moves the
+run to `.sdd/archive/<YYYY-MM-DD>-<slug>/`, and records `archivePath` in
+`links.json`. It guards itself: it refuses to run unless the run's last verdict
+is `pasa`, the worktree is clean (override with `--allow-dirty` when justified),
+and the spec/tasks artifacts validate. Use `--dry-run` to preview the writes
+without touching disk. You only call it; you never edit the store yourself.
+
+**Never archive on a non-`pasa` outcome.** Do **not** invoke `/zero-archive`
+for a `corregir` or `replantear` verdict, or when the iteration cap was reached
+without a `pasa` — the command refuses it anyway, and no store change or archive
+entry is created. Likewise skip it for a **legacy resumed run** whose
+`.sdd/<slug>/` has no `spec.md` (the older artifact shape): there is no delta to
+fold, so the command reports nothing to archive.
+
+**On a guardrail error, surface — do not claim success.** If `/zero-archive`
 reports a guardrail failure (a duplicate name, an ADDED collision, a MODIFIED or
-REMOVED of a missing block, or a malformed store/delta) it writes **nothing**.
-Relay the failing requirement name(s) and reason to the user and state plainly
-that the canonical store was **not** updated and is out of sync for a manual
-fix. The `pasa` verdict still stands — the build shipped; only the store fold
-was rejected. Never report the store as updated when `/zero-sync` did not
-update it.
-
-**On success, relay the report.** When `/zero-sync` succeeds it writes the new
-store and creates an archive entry at `.sdd/archive/<YYYY-MM-DD>-<slug>/` — a
-copy of the run's `proposal.md` and `spec.md` plus a `sync.md` report listing
-every added, modified, and removed requirement. Include `/zero-sync`'s report in
-the run's final summary, calling out the destructive effects (replacements,
-deletions) explicitly.
+REMOVED of a missing block, a malformed store/delta, a failed validation, or a
+dirty worktree) it changes **nothing**, and on a mid-write failure it rolls the
+store back. Relay the failing reason to the user and state plainly that the
+canonical store was **not** updated. The `pasa` verdict still stands — the build
+shipped; only the archive step was rejected. Never report the store as updated
+when `/zero-archive` did not update it.
+
+**On success, relay the report.** When `/zero-archive` succeeds it writes the
+new store, moves the run to `.sdd/archive/<YYYY-MM-DD>-<slug>/`, and records the
+archive path in `links.json`. Include its report in the run's final summary,
+calling out the destructive effects (replacements, deletions) explicitly.