@gonrocca/zero-pi 0.1.4 → 0.1.5

package/README.md

@@ -70,6 +70,45 @@ correction rounds, and the gotchas — under `topic_key: zero-run/<slug>`. The
 next run on related work starts from what the last one learned. With `--no-mcp`
 the loop degrades silently.
 
+### Adaptive model profiles
+
+zero learns which model fits each SDD phase from your own run history and can
+re-tune `~/.pi/zero.json` for you.
+
+**The metrics log — `~/.pi/zero-runs.jsonl`.** Every completed SDD run appends
+one JSON line to this file: the feature slug, the per-phase models the run used,
+the final verdict, and the build/veredicto round count. It is append-only and
+never rewritten. This local log is the only thing zero learns from — a run
+abandoned before it reaches a verdict adds no line.
+
+**Autotune modes.** At each pi session start zero aggregates the log and, once a
+phase has accumulated enough run data to cross a confidence threshold, decides
+whether that phase's model should change. The `autotune` mode in `~/.pi/zero.json`
+controls what happens next:
+
+| Mode | Behaviour |
+| ---- | --------- |
+| `auto` _(default)_ | zero applies the adjustment to `~/.pi/zero.json` and notifies you exactly what changed. |
+| `ask` | zero records the recommendation but changes nothing — you apply it from `/zero-models`. |
+| `off` | zero still records run metrics, but never changes or recommends anything. |
+
+A change always takes effect on the *next* `/forge` run, and every applied
+change is announced — autotune is never silent.
+
+**Setting the mode.** Set it directly, or pick it from the interactive
+`/zero-models` menu (which shows the current mode as its own entry):
+
+```
+/zero-models autotune=ask   # auto | ask | off
+```
+
+**Applying a pending suggestion.** In `ask` mode, when a recommendation is
+waiting, running `/zero-models` shows a leading `★ aplicar sugerencia` entry;
+selecting it applies the change and clears the pending suggestion. Note that a
+pending suggestion is *refreshed* — an unactioned suggestion is overwritten by
+the next `ask`-mode session with fresher data, so `/zero-models` always reflects
+the most recent recommendation.
+
 ### Skill auto-learning (`skills/`)
 
 `skill-loop.md` gives the agent a closed learning loop so solutions are reused

package/extensions/autotune-extension.ts

@@ -0,0 +1,250 @@
+// zero-pi — adaptive model profiles, pi wiring.
+//
+// A thin pi extension that wires the pure decision logic in `autotune.ts` to
+// the `session_start` hook. On every session start it reads the local outcome
+// log (`~/.pi/zero-runs.jsonl`), aggregates it, decides per-phase model
+// adjustments, and — depending on the `autotune` mode stored in
+// `~/.pi/zero.json` — either applies them (`auto`), records them as a pending
+// suggestion (`ask`), or does nothing (`off`).
+//
+// `session_start` is the chosen trigger: it runs deterministic code and
+// applies the freshly-learned profile *before* the next `/forge` run reads
+// `zero.json`. A run's own record only influences the *next* session — the
+// one-run lag the requirements explicitly model ("a change takes effect on the
+// next run").
+//
+// All decisions live in `autotune.ts`; this file only reads files, calls those
+// functions, and applies/notifies. The whole handler is wrapped in a swallowing
+// `try/catch` — exactly like `startup-banner.ts`, a failure must never break a
+// pi session. The package stays dependency-free: `node:fs`/`node:os`/`node:path`
+// only, plus minimal local interfaces for the pi API.
+
+import { readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+import {
+  aggregate,
+  decideAdjustments,
+  readAutotuneMode,
+  readRunRecords,
+  type Adjustment,
+} from "./autotune.ts";
+
+/** The SDD phases, in pipeline order. Mirrors `zero-models.ts`. */
+const PHASES = ["explore", "plan", "build", "veredicto"] as const;
+type Phase = (typeof PHASES)[number];
+
+/**
+ * One pending adjustment recorded under the `autotunePending` key of
+ * `~/.pi/zero.json` in `ask` mode. It mirrors `autotune.ts`'s `Adjustment`
+ * exactly — a flat `{ phase, from, to, reason }` record — so `/zero-models`
+ * (Task 6) can read the key, surface the suggestion, apply it, and clear it.
+ *
+ * `autotunePending` is the JSON shape `Adjustment[]`: an array of these
+ * records. It is never read by the orchestrator.
+ */
+export interface AutotunePending {
+  /** SDD phase the suggested change applies to. */
+  phase: Phase;
+  /** Model the phase currently runs on. */
+  from: string;
+  /** Model the phase is suggested to move to (always one tier above `from`). */
+  to: string;
+  /** Human-readable justification, used verbatim when surfacing the suggestion. */
+  reason: string;
+}
+
+/** Absolute path of pi's `zero.json` marker. Mirrors `zero-models.ts`. */
+function zeroJsonPath(): string {
+  return join(homedir(), ".pi", "zero.json");
+}
+
+/** Absolute path of the append-only run metrics log. */
+function zeroRunsPath(): string {
+  return join(homedir(), ".pi", "zero-runs.jsonl");
+}
+
+/** Whether a value is a non-null, non-array object. */
+function isObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/**
+ * Read `~/.pi/zero.json`.
+ *
+ * Returns `null` — distinct from an empty object — when the file is absent or
+ * unparseable. The autotune flow treats `null` as "no profile to safely tune":
+ * it must not synthesize a `models` map (AC 6.4). A present-but-`{}` file is a
+ * valid object and is returned as such.
+ */
+function readZeroJson(): Record<string, unknown> | null {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(readFileSync(zeroJsonPath(), "utf8"));
+  } catch {
+    return null;
+  }
+  return isObject(parsed) ? parsed : null;
+}
+
+/**
+ * Extract the per-phase models actually present in a `zero.json` object. Only
+ * string entries for known phases are kept; missing or non-string entries are
+ * omitted (no defaults are synthesized — `decideAdjustments` skips a phase with
+ * no current model).
+ */
+function readCurrentModels(data: Record<string, unknown>): Partial<Record<Phase, string>> {
+  const raw = isObject(data.models) ? data.models : {};
+  const models: Partial<Record<Phase, string>> = {};
+  for (const phase of PHASES) {
+    const value = raw[phase];
+    if (typeof value === "string" && value !== "") models[phase] = value;
+  }
+  return models;
+}
+
+/**
+ * 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
+ * run log plus the current per-phase models, so `stepUp` prefers a model the
+ * user already uses anywhere.
+ */
+function deriveKnownModels(
+  currentModels: Partial<Record<Phase, string>>,
+  loggedModels: Iterable<string>,
+): string[] {
+  const known = new Set<string>();
+  for (const phase of PHASES) {
+    const model = currentModels[phase];
+    if (typeof model === "string" && model !== "") known.add(model);
+  }
+  for (const model of loggedModels) {
+    if (typeof model === "string" && model !== "") known.add(model);
+  }
+  return [...known];
+}
+
+/** The slice of pi's UI surface the autotune extension uses. */
+interface PiUI {
+  notify(message: string, type?: "info" | "warning" | "error"): void;
+}
+interface PiSessionContext {
+  ui: PiUI;
+}
+/** The slice of pi's extension API the autotune extension uses. */
+interface PiExtensionAPI {
+  on(event: string, handler: (ctx: PiSessionContext) => void): void;
+}
+
+/**
+ * The `session_start` evaluate-and-tune handler.
+ *
+ * Runs entirely inside `register`'s swallowing `try/catch`, but is also written
+ * to never throw on the expected paths: a missing log, an absent `zero.json`,
+ * and an `off` mode all return cleanly.
+ */
+function evaluateAndTune(ctx: PiSessionContext): void {
+  const notify = (message: string, type?: "info" | "warning" | "error"): void => {
+    try {
+      ctx.ui.notify(message, type);
+    } catch {
+      // A notification failure must not break the session either.
+    }
+  };
+
+  const data = readZeroJson();
+  if (data === null) {
+    // Absent or unparseable `zero.json` — no profile to safely tune. Skip with
+    // a single non-blocking warning; never synthesize a `models` map (AC 6.4).
+    notify("zero autotune: ~/.pi/zero.json missing or unreadable — skipping", "warning");
+    return;
+  }
+
+  const mode = readAutotuneMode(data);
+  if (mode === "off") return; // metrics still captured by the orchestrator; nothing changes here.
+
+  const currentModels = readCurrentModels(data);
+
+  const records = readRunRecords(zeroRunsPath());
+  const loggedModels: string[] = [];
+  for (const record of records) {
+    for (const phase of PHASES) {
+      const model = record.phases[phase]?.model;
+      if (typeof model === "string" && model !== "") loggedModels.push(model);
+    }
+  }
+  const knownModels = deriveKnownModels(currentModels, loggedModels);
+
+  const stats = aggregate(records);
+  const adjustments: Adjustment[] = decideAdjustments(stats, currentModels, knownModels);
+  if (adjustments.length === 0) return; // nothing to do — return silently.
+
+  if (mode === "auto") {
+    // Apply every adjustment, write `zero.json` ONCE preserving all other keys,
+    // then emit one notification per change (AC 5.4, 6.1 — never silent).
+    const models: Record<string, unknown> = isObject(data.models) ? { ...data.models } : {};
+    for (const adj of adjustments) {
+      models[adj.phase] = adj.to;
+    }
+    writeFileSync(
+      zeroJsonPath(),
+      `${JSON.stringify({ ...data, models }, null, 2)}\n`,
+      "utf8",
+    );
+    for (const adj of adjustments) {
+      notify(`zero autotune: ${adj.phase} ${adj.from} → ${adj.to} (${adj.reason})`, "info");
+    }
+    return;
+  }
+
+  // mode === "ask" — record the recommendations under `autotunePending` without
+  // touching `models`, and tell the user to run /zero-models to apply.
+  const pending: AutotunePending[] = adjustments.map((adj) => ({
+    phase: adj.phase,
+    from: adj.from,
+    to: adj.to,
+    reason: adj.reason,
+  }));
+  writeFileSync(
+    zeroJsonPath(),
+    `${JSON.stringify({ ...data, autotunePending: pending }, null, 2)}\n`,
+    "utf8",
+  );
+  for (const adj of pending) {
+    notify(
+      `zero autotune suggests: ${adj.phase} → ${adj.to} — run /zero-models to apply`,
+      "info",
+    );
+  }
+}
+
+/**
+ * The pi extension entry point.
+ *
+ * pi calls this once when the extension loads. It wires the evaluate-and-tune
+ * handler to the `session_start` event. The whole body is wrapped in a
+ * swallowing `try/catch`, and the handler itself is wrapped again, so neither
+ * registration nor a later failure can ever break a pi session. Called with no
+ * or an invalid `pi`, it no-ops cleanly.
+ */
+export default function register(pi?: unknown): void {
+  try {
+    if (
+      !pi ||
+      typeof (pi as PiExtensionAPI).on !== "function"
+    ) {
+      return;
+    }
+    (pi as PiExtensionAPI).on("session_start", (ctx: PiSessionContext): void => {
+      try {
+        if (!ctx || !ctx.ui || typeof ctx.ui.notify !== "function") return;
+        evaluateAndTune(ctx);
+      } catch {
+        // An evaluate-and-tune failure must never break a pi session.
+      }
+    });
+  } catch {
+    // Registration itself must never break a pi session.
+  }
+}

package/extensions/autotune.ts

@@ -0,0 +1,385 @@
+// zero-pi — adaptive model profiles, pure-logic module.
+//
+// zero learns which Claude model fits each SDD phase by accumulating a local,
+// append-only outcome log (`~/.pi/zero-runs.jsonl`) and tuning `~/.pi/zero.json`
+// from aggregated statistics. Every *decision* — parsing, aggregation, tier
+// math, adjustment — lives here in plain, dependency-free TypeScript so it is
+// testable and reproducible. The pi wiring lives in `autotune-extension.ts`.
+//
+// This file has no pi imports and no side-effecting top-level code; it only
+// touches the filesystem through the explicit `readRunRecords` reader.
+
+import { readFileSync } from "node:fs";
+
+/** Schema version of one `~/.pi/zero-runs.jsonl` record. A record carrying any
+ *  other `v` is dropped by `parseRunLine` rather than mis-aggregated. */
+export const RUN_SCHEMA_VERSION = 1;
+
+/** The SDD phases a run record carries a model for, in pipeline order. */
+const RECORD_PHASES = ["explore", "plan", "build", "veredicto"] as const;
+
+/** Terminal states a run can be recorded with. `pasa` = success;
+ *  `cap-reached` = the round cap was hit without a `pasa`. */
+const VERDICTS = ["pasa", "cap-reached"] as const;
+
+/** A run's terminal verdict. */
+export type RunVerdict = (typeof VERDICTS)[number];
+
+/** The model a single phase ran on for a given run. An object (not a bare
+ *  string) so the schema can grow additive fields without a version bump. */
+export interface PhaseRun {
+  model: string;
+}
+
+/**
+ * One line of `~/.pi/zero-runs.jsonl` — a single completed SDD run. The
+ * orchestrator prompt emits exactly this shape at run end.
+ */
+export interface RunRecord {
+  /** Schema version — always `RUN_SCHEMA_VERSION`. */
+  v: number;
+  /** ISO 8601 run-end timestamp. */
+  ts: string;
+  /** SDD feature slug. */
+  feature: string;
+  /** The model each phase ran on for this run. */
+  phases: Record<(typeof RECORD_PHASES)[number], PhaseRun>;
+  /** The run's terminal verdict. */
+  verdict: RunVerdict;
+  /** Count of build/veredicto rounds — `1` for a clean first-pass run. */
+  rounds: number;
+}
+
+/** How aggressively zero applies a learned profile — stored in `zero.json`.
+ *  `auto` applies and notifies; `ask` records a pending suggestion; `off`
+ *  changes nothing. */
+export type AutotuneMode = "auto" | "ask" | "off";
+
+/** Whether a value is a non-null object (and not an array). */
+function isObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/**
+ * Parse one JSONL line into a `RunRecord`, validating the shape.
+ *
+ * Returns `null` — never throws — for anything off-shape: invalid JSON, a
+ * non-object, an unexpected `v`, a missing/non-string `feature` or `ts`, a
+ * non-integer `rounds`, a `verdict` outside the enum, or a `phases` map
+ * missing any of the four phases or carrying a non-string model. This is the
+ * deliberate defense against malformed LLM-emitted records: a bad emission
+ * degrades to "one missing sample", never a crash.
+ */
+export function parseRunLine(line: string): RunRecord | null {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(line);
+  } catch {
+    return null;
+  }
+
+  if (!isObject(parsed)) return null;
+
+  if (parsed.v !== RUN_SCHEMA_VERSION) return null;
+  if (typeof parsed.ts !== "string" || parsed.ts === "") return null;
+  if (typeof parsed.feature !== "string" || parsed.feature === "") return null;
+  if (typeof parsed.rounds !== "number" || !Number.isInteger(parsed.rounds)) return null;
+  if (typeof parsed.verdict !== "string") return null;
+  if (!(VERDICTS as readonly string[]).includes(parsed.verdict)) return null;
+
+  if (!isObject(parsed.phases)) return null;
+  const phases = {} as RunRecord["phases"];
+  for (const phase of RECORD_PHASES) {
+    const phaseRun = parsed.phases[phase];
+    if (!isObject(phaseRun)) return null;
+    if (typeof phaseRun.model !== "string" || phaseRun.model === "") return null;
+    phases[phase] = { model: phaseRun.model };
+  }
+
+  return {
+    v: RUN_SCHEMA_VERSION,
+    ts: parsed.ts,
+    feature: parsed.feature,
+    phases,
+    verdict: parsed.verdict as RunVerdict,
+    rounds: parsed.rounds,
+  };
+}
+
+/**
+ * Read `~/.pi/zero-runs.jsonl` (or any path) into a list of valid `RunRecord`s.
+ *
+ * A missing or unreadable file yields `[]`. The file is split on `\n`; empty
+ * lines are skipped, and any line `parseRunLine` rejects (a malformed or
+ * half-written record) is dropped. Never throws.
+ */
+export function readRunRecords(path: string): RunRecord[] {
+  let contents: string;
+  try {
+    contents = readFileSync(path, "utf8");
+  } catch {
+    return [];
+  }
+
+  const records: RunRecord[] = [];
+  for (const line of contents.split("\n")) {
+    if (line.trim() === "") continue;
+    const record = parseRunLine(line);
+    if (record !== null) records.push(record);
+  }
+  return records;
+}
+
+// ---------------------------------------------------------------------------
+// Aggregation
+// ---------------------------------------------------------------------------
+
+/**
+ * Aggregated outcome statistics for one `(phase, model)` pair.
+ */
+export interface PhaseModelStat {
+  /** SDD phase this stat is for. */
+  phase: (typeof RECORD_PHASES)[number];
+  /** Model id this stat is for. */
+  model: string;
+  /** Total runs recorded for the pair. */
+  samples: number;
+  /** Fraction of runs that reached `pasa` — `0` when `samples` is `0`. */
+  passRate: number;
+  /** Mean `rounds` averaged ONLY over runs that reached `pasa`; `null` when no
+   *  `pasa` run exists for the pair. */
+  avgRounds: number | null;
+}
+
+/** Map key for a `(phase, model)` bucket. */
+function statKey(phase: string, model: string): string {
+  return `${phase} ${model}`;
+}
+
+/**
+ * Aggregate run records into per-`(phase, model)` statistics.
+ *
+ * For every record, each of the four phases contributes one sample to the
+ * bucket of the model that phase ran on (a phase whose model is missing or
+ * non-string is skipped). `avgRounds` is averaged exclusively over runs that
+ * reached `pasa`; non-positive `rounds` values (which `parseRunLine` does not
+ * reject) are ignored when computing that average so a bad `0`/negative entry
+ * never skews or breaks the math. An empty input yields an empty map.
+ */
+export function aggregate(records: RunRecord[]): Map<string, PhaseModelStat> {
+  interface Acc {
+    samples: number;
+    passes: number;
+    passRounds: number;
+    passRoundCount: number;
+  }
+  const acc = new Map<string, { phase: (typeof RECORD_PHASES)[number]; model: string; data: Acc }>();
+
+  for (const record of records) {
+    const isPass = record.verdict === "pasa";
+    for (const phase of RECORD_PHASES) {
+      const phaseRun = record.phases[phase];
+      const model = phaseRun?.model;
+      if (typeof model !== "string" || model === "") continue;
+
+      const key = statKey(phase, model);
+      let bucket = acc.get(key);
+      if (bucket === undefined) {
+        bucket = { phase, model, data: { samples: 0, passes: 0, passRounds: 0, passRoundCount: 0 } };
+        acc.set(key, bucket);
+      }
+      bucket.data.samples += 1;
+      if (isPass) {
+        bucket.data.passes += 1;
+        // Guard against non-positive `rounds`: a clean run is `>= 1`, so a
+        // `0`/negative value is malformed and must not enter the average.
+        if (typeof record.rounds === "number" && record.rounds > 0) {
+          bucket.data.passRounds += record.rounds;
+          bucket.data.passRoundCount += 1;
+        }
+      }
+    }
+  }
+
+  const stats = new Map<string, PhaseModelStat>();
+  for (const [key, bucket] of acc) {
+    const { samples, passes, passRounds, passRoundCount } = bucket.data;
+    stats.set(key, {
+      phase: bucket.phase,
+      model: bucket.model,
+      samples,
+      passRate: samples > 0 ? passes / samples : 0,
+      avgRounds: passRoundCount > 0 ? passRounds / passRoundCount : null,
+    });
+  }
+  return stats;
+}
+
+// ---------------------------------------------------------------------------
+// Model tier ladder
+// ---------------------------------------------------------------------------
+
+/** Three Claude tiers, ordered `haiku < sonnet < opus`. */
+const TIER = { haiku: 0, sonnet: 1, opus: 2 } as const;
+
+/** A model's tier index, or `null` for an unrecognized (untierable) model. */
+export type Tier = (typeof TIER)[keyof typeof TIER];
+
+/** A single hardcoded representative model id per tier, used as the fallback
+ *  step-up target when the user has no known model at the next tier. */
+const TIER_REPRESENTATIVE: Record<Tier, string> = {
+  [TIER.haiku]: "claude-haiku-4-5",
+  [TIER.sonnet]: "claude-sonnet-4-6",
+  [TIER.opus]: "claude-opus-4-7",
+};
+
+/**
+ * Classify a model id into a tier by substring match — deliberate so future
+ * point releases (`claude-sonnet-4-7`, etc.) classify with no code change.
+ * Returns `null` for any id that is not recognizably haiku/sonnet/opus.
+ */
+export function tierOf(modelId: string): Tier | null {
+  if (typeof modelId !== "string") return null;
+  const id = modelId.toLowerCase();
+  if (id.includes("haiku")) return TIER.haiku;
+  if (id.includes("sonnet")) return TIER.sonnet;
+  if (id.includes("opus")) return TIER.opus;
+  return null;
+}
+
+/**
+ * Step a model up exactly one tier.
+ *
+ * Among `knownModels` (the models the user already uses anywhere in their
+ * `models` map) it picks one whose tier is exactly `tierOf(model) + 1`,
+ * preferring deterministically the smallest id when several qualify. If the
+ * user has no known model at the next tier, it falls back to the single
+ * hardcoded representative for that tier. Never returns an arbitrary id, and
+ * never steps more than one tier.
+ *
+ * Returns `null` when `model` is already at `opus` (no higher tier) or is
+ * untierable (an unrecognized model id).
+ */
+export function stepUp(model: string, knownModels: readonly string[]): string | null {
+  const tier = tierOf(model);
+  if (tier === null) return null;
+  if (tier === TIER.opus) return null;
+
+  const nextTier = (tier + 1) as Tier;
+
+  const candidates = knownModels
+    .filter((m) => typeof m === "string" && tierOf(m) === nextTier)
+    .sort();
+  if (candidates.length > 0) return candidates[0];
+
+  return TIER_REPRESENTATIVE[nextTier];
+}
+
+// ---------------------------------------------------------------------------
+// Adjustment rules
+// ---------------------------------------------------------------------------
+
+/** Below this many samples a `(phase, model)` pair is ignored — too little
+ *  evidence to act on (AC 5.1). */
+export const MIN_SAMPLES = 5;
+
+/** Pass-rate at or under this value marks a phase as under-performing. */
+export const LOW_PASS_RATE = 0.6;
+
+/** Average rounds-to-pass over this value marks a phase as struggling. */
+export const HIGH_AVG_ROUNDS = 2.5;
+
+/** Pass-rate at or over this value marks a phase as reliable — stay put. */
+export const RELIABLE_PASS_RATE = 0.85;
+
+/**
+ * A proposed change of model for one SDD phase. `reason` is a human-readable
+ * string used verbatim in notifications.
+ */
+export interface Adjustment {
+  /** SDD phase the change applies to. */
+  phase: (typeof RECORD_PHASES)[number];
+  /** Model the phase currently runs on. */
+  from: string;
+  /** Model the phase is proposed to move to (always one tier above `from`). */
+  to: string;
+  /** Human-readable justification, e.g. `"pass-rate 0.40 over 7 runs"`. */
+  reason: string;
+}
+
+/**
+ * Decide model adjustments from aggregated statistics.
+ *
+ * For each phase, looks up the `(phase, currentModel)` stat and applies the
+ * adjustment rules:
+ *   - absent stat or `samples < MIN_SAMPLES` → no decision (too little data);
+ *   - under-performing (`passRate <= LOW_PASS_RATE`, or a `pasa`-only
+ *     `avgRounds > HIGH_AVG_ROUNDS`) → propose one tier up via `stepUp`;
+ *   - reliable (`passRate >= RELIABLE_PASS_RATE` and `avgRounds` not high)
+ *     → keep the model;
+ *   - otherwise (middling) → no change.
+ *
+ * Safety caps are baked in: a proposal is emitted only when `stepUp` returns a
+ * model (so a phase already at `opus` or on an untierable model is left
+ * alone), `stepUp` never jumps more than one tier, and it never returns a
+ * model outside `knownModels`-or-the-fixed-representative set.
+ */
+export function decideAdjustments(
+  stats: Map<string, PhaseModelStat>,
+  currentModels: Partial<Record<(typeof RECORD_PHASES)[number], string>>,
+  knownModels: readonly string[],
+): Adjustment[] {
+  const adjustments: Adjustment[] = [];
+
+  for (const phase of RECORD_PHASES) {
+    const currentModel = currentModels[phase];
+    if (typeof currentModel !== "string" || currentModel === "") continue;
+
+    const stat = stats.get(statKey(phase, currentModel));
+    if (stat === undefined || stat.samples < MIN_SAMPLES) continue;
+
+    const highRounds = stat.avgRounds !== null && stat.avgRounds > HIGH_AVG_ROUNDS;
+    const underPerforming = stat.passRate <= LOW_PASS_RATE || highRounds;
+    const reliable =
+      stat.passRate >= RELIABLE_PASS_RATE &&
+      (stat.avgRounds === null || stat.avgRounds <= HIGH_AVG_ROUNDS);
+
+    if (reliable) continue;
+    if (!underPerforming) continue;
+
+    const to = stepUp(currentModel, knownModels);
+    if (to === null) continue; // already at top tier, or untierable
+
+    const reason =
+      stat.passRate <= LOW_PASS_RATE
+        ? `pass-rate ${stat.passRate.toFixed(2)} over ${stat.samples} runs`
+        : `avg ${(stat.avgRounds as number).toFixed(1)} rounds-to-pass over ${stat.samples} runs`;
+
+    adjustments.push({ phase, from: currentModel, to, reason });
+  }
+
+  return adjustments;
+}
+
+// ---------------------------------------------------------------------------
+// Autotune mode
+// ---------------------------------------------------------------------------
+
+/** The valid stored values of the `autotune` key, used for membership checks. */
+const AUTOTUNE_MODES = ["auto", "ask", "off"] as const;
+
+/**
+ * Read the `autotune` mode out of a parsed `~/.pi/zero.json` object.
+ *
+ * Returns the stored value only when it is exactly `"auto"`, `"ask"`, or
+ * `"off"`. A missing key, a non-string value, or any other string degrades to
+ * the safe default `"auto"` — never throws. This is the single point of truth
+ * for "absent ⇒ auto" (AC 3.2).
+ */
+export function readAutotuneMode(data: Record<string, unknown>): AutotuneMode {
+  const value = data.autotune;
+  if (typeof value === "string" && (AUTOTUNE_MODES as readonly string[]).includes(value)) {
+    return value as AutotuneMode;
+  }
+  return "auto";
+}

package/extensions/zero-models.ts

@@ -14,6 +14,9 @@ import { readFileSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
 
+import { readAutotuneMode, type AutotuneMode } from "./autotune.ts";
+import type { AutotunePending } from "./autotune-extension.ts";
+
 /** The SDD phases, in pipeline order. */
 export const PHASES = ["explore", "plan", "build", "veredicto"] as const;
 export type Phase = (typeof PHASES)[number];
@@ -86,11 +89,81 @@ export function formatModels(models: PhaseModels): string {
   return PHASES.map((phase) => `  ${phase.padEnd(10)} ${models[phase]}`).join("\n");
 }
 
+/** The valid `autotune` modes a user can set. */
+const AUTOTUNE_MODES = ["auto", "ask", "off"] as const;
+
+/**
+ * Parse the value of a `/zero-models autotune=<mode>` argument.
+ *
+ * Accepts only `auto`, `ask`, or `off` — case-insensitive and trimmed.
+ * Returns `null` for any other value so the caller can emit a usage warning
+ * and write nothing.
+ */
+export function parseAutotuneArg(arg: string): AutotuneMode | null {
+  const value = arg.trim().toLowerCase();
+  return (AUTOTUNE_MODES as readonly string[]).includes(value)
+    ? (value as AutotuneMode)
+    : null;
+}
+
+/** A short human label for an autotune mode, used in menus and notifications. */
+export function formatAutotune(mode: AutotuneMode): string {
+  switch (mode) {
+    case "auto":
+      return "auto — aplica cambios automáticamente";
+    case "ask":
+      return "ask — sugiere y espera confirmación";
+    case "off":
+      return "off — no ajusta nada";
+  }
+}
+
 /** Write the models back into `~/.pi/zero.json`, preserving every other key. */
 function writeModels(data: Record<string, unknown>, models: PhaseModels): void {
   writeFileSync(zeroJsonPath(), `${JSON.stringify({ ...data, models }, null, 2)}\n`, "utf8");
 }
 
+/**
+ * Write an updated `~/.pi/zero.json` object, preserving every other key via the
+ * same `{ ...data }` spread, 2-space indent and trailing newline `writeModels`
+ * uses. The caller passes the keys it wants to add/override.
+ */
+function writeZeroJson(data: Record<string, unknown>, patch: Record<string, unknown>): void {
+  writeFileSync(zeroJsonPath(), `${JSON.stringify({ ...data, ...patch }, null, 2)}\n`, "utf8");
+}
+
+/** Whether a value is a non-null, non-array object. */
+function isObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/**
+ * Extract the `autotunePending` adjustments from a zero.json object.
+ *
+ * Returns only well-formed records — an array entry with string `phase`/`from`/
+ * `to`/`reason` and a recognized phase — so a malformed key never crashes the
+ * picker. A missing or off-shape key yields `[]`.
+ */
+function readAutotunePending(data: Record<string, unknown>): AutotunePending[] {
+  const raw = data.autotunePending;
+  if (!Array.isArray(raw)) return [];
+  const pending: AutotunePending[] = [];
+  for (const entry of raw) {
+    if (!isObject(entry)) continue;
+    const { phase, from, to, reason } = entry;
+    if (
+      typeof phase === "string" &&
+      isPhase(phase) &&
+      typeof from === "string" &&
+      typeof to === "string" &&
+      typeof reason === "string"
+    ) {
+      pending.push({ phase, from, to, reason });
+    }
+  }
+  return pending;
+}
+
 /** The slice of pi's extension API this command uses. */
 interface PiUI {
   select(prompt: string, options: string[]): Promise<string | undefined>;
@@ -129,11 +202,28 @@ export default function register(pi?: PiExtensionAPI): void {
         // Direct form: /zero-models build=claude-opus-4-7
         const arg = args.trim();
         if (arg) {
+          // Direct form: /zero-models autotune=<mode>
+          const autotuneMatch = arg.match(/^autotune\s*[=\s]\s*(.+)$/i);
+          if (autotuneMatch) {
+            const mode = parseAutotuneArg(autotuneMatch[1]);
+            if (!mode) {
+              ctx.ui.notify(
+                "uso: /zero-models autotune=<modo>  (modo: auto | ask | off)",
+                "warning",
+              );
+              return;
+            }
+            writeZeroJson(data, { autotune: mode });
+            ctx.ui.notify(`zero autotune: ${formatAutotune(mode)}`, "info");
+            return;
+          }
+
           const assignment = parseAssignment(arg);
           if (!assignment) {
             ctx.ui.notify(
               "uso: /zero-models  —o—  /zero-models <fase>=<modelo> " +
-                "(fase: explore | plan | build | veredicto)",
+                "(fase: explore | plan | build | veredicto)  —o—  " +
+                "/zero-models autotune=<modo>",
               "warning",
             );
             return;
@@ -146,13 +236,51 @@ export default function register(pi?: PiExtensionAPI): void {
 
         // Interactive form: pick a phase, pick a model, repeat until saved.
         let changed = false;
+        let autotuneMode = readAutotuneMode(data);
+        let autotuneChanged = false;
+        let pending = readAutotunePending(data);
+        let pendingApplied = false;
         for (;;) {
-          const phasePick = await ctx.ui.select(
-            "zero · modelos SDD — elegí una fase",
-            [...PHASES.map((p) => `${p}   →   ${models[p]}`), SAVE_AND_EXIT],
-          );
+          const applyEntry =
+            pending.length > 0
+              ? `★ aplicar sugerencia: ${pending
+                  .map((p) => `${p.phase} → ${p.to}`)
+                  .join(", ")}`
+              : null;
+          const autotuneEntry = `autotune   →   ${autotuneMode}`;
+
+          const phasePick = await ctx.ui.select("zero · modelos SDD — elegí una fase", [
+            ...(applyEntry ? [applyEntry] : []),
+            ...PHASES.map((p) => `${p}   →   ${models[p]}`),
+            autotuneEntry,
+            SAVE_AND_EXIT,
+          ]);
           if (!phasePick || phasePick === SAVE_AND_EXIT) break;
 
+          // Apply the pending autotune suggestion.
+          if (applyEntry && phasePick === applyEntry) {
+            for (const adj of pending) models[adj.phase] = adj.to;
+            changed = true;
+            pendingApplied = true;
+            pending = [];
+            continue;
+          }
+
+          // Change the autotune mode.
+          if (phasePick === autotuneEntry) {
+            const modePick = await ctx.ui.select(
+              "Modo de autotune",
+              AUTOTUNE_MODES.map((m) => formatAutotune(m)),
+            );
+            if (!modePick) continue;
+            const picked = parseAutotuneArg(modePick.split(/\s/)[0]);
+            if (picked && picked !== autotuneMode) {
+              autotuneMode = picked;
+              autotuneChanged = true;
+            }
+            continue;
+          }
+
           const phase = phasePick.split(/\s/)[0];
           if (!isPhase(phase)) break;
 
@@ -172,11 +300,27 @@ export default function register(pi?: PiExtensionAPI): void {
           changed = true;
         }
 
-        if (changed) {
-          writeModels(data, models);
-          ctx.ui.notify(`zero · modelos SDD guardados:\n${formatModels(models)}`, "info");
+        if (changed || autotuneChanged) {
+          // Build the patch, preserving every other key via the spread. When
+          // the pending suggestion was applied, clear the `autotunePending` key.
+          const patch: Record<string, unknown> = { models };
+          if (autotuneChanged) patch.autotune = autotuneMode;
+          if (pendingApplied) patch.autotunePending = undefined;
+
+          const merged = { ...data, ...patch };
+          if (pendingApplied) delete merged.autotunePending;
+          writeFileSync(zeroJsonPath(), `${JSON.stringify(merged, null, 2)}\n`, "utf8");
+
+          const summary = [`zero · modelos SDD guardados:\n${formatModels(models)}`];
+          summary.push(`  autotune   ${autotuneMode}`);
+          if (pendingApplied) summary.push("sugerencia aplicada");
+          ctx.ui.notify(summary.join("\n"), "info");
         } else {
-          ctx.ui.notify(`zero · modelos SDD (sin cambios):\n${formatModels(models)}`, "info");
+          ctx.ui.notify(
+            `zero · modelos SDD (sin cambios):\n${formatModels(models)}\n` +
+              `  autotune   ${autotuneMode}`,
+            "info",
+          );
         }
       } catch (err) {
         ctx.ui.notify(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gonrocca/zero-pi",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "description": "zero-pi — an installable layer for pi (pi.dev): the zero spec-driven development workflow, skill auto-learning, and an animated ZERO startup banner. Adds capability to pi without modifying pi.",
   "type": "module",
   "keywords": [
@@ -21,7 +21,8 @@
     ],
     "extensions": [
       "./extensions/startup-banner.ts",
-      "./extensions/zero-models.ts"
+      "./extensions/zero-models.ts",
+      "./extensions/autotune-extension.ts"
     ]
   },
   "files": [
@@ -29,6 +30,8 @@
     "skills",
     "extensions/startup-banner.ts",
     "extensions/zero-models.ts",
+    "extensions/autotune.ts",
+    "extensions/autotune-extension.ts",
     "README.md",
     "LICENSE"
   ],

package/prompts/orchestrator.md

@@ -89,3 +89,40 @@ Use the project name Cortex derives from the working directory.
 
 If Cortex is unavailable — installed with `--no-mcp`, or the server is down —
 skip recall and persist silently. The memory loop must never block a run.
+
+## Run metrics
+
+zero tunes itself from a local outcome log. At the **end of every run** that
+reached a verdict, append exactly one line to `~/.pi/zero-runs.jsonl` recording
+how the run went. This is separate from — and additional to — the "## Run
+memory" Cortex save above; do both.
+
+The line is one `RunRecord` JSON object, serialized with no pretty-printing,
+followed by a single newline. Build it from facts you already hold:
+
+- `v`: the schema version — always the integer `1`.
+- `ts`: the run-end timestamp, ISO 8601 (e.g. `2026-05-17T14:03:22.000Z`).
+- `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.
+- `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
+  run).
+
+Exact one-line shape to emit:
+
+```json
+{"v":1,"ts":"2026-05-17T14:03:22.000Z","feature":"adaptive-model-profiles","phases":{"explore":{"model":"claude-haiku-4-5"},"plan":{"model":"claude-opus-4-7"},"build":{"model":"claude-sonnet-4-6"},"veredicto":{"model":"claude-opus-4-7"}},"verdict":"pasa","rounds":2}
+```
+
+Rules:
+
+- **Append only.** Add one line per run. Create `~/.pi/zero-runs.jsonl` if it
+  does not exist. Never rewrite, reorder, or delete existing lines.
+- **Never block the run.** If the write fails for any reason, emit a
+  non-blocking warning and continue — the run's result stands regardless.
+- **No record without a verdict.** If the run was aborted before `veredicto`
+  ever produced a verdict, write nothing — only a `pasa` or `cap-reached` run
+  is recorded.