@gonrocca/zero-pi 0.1.9 → 0.1.10

package/README.md

@@ -134,14 +134,24 @@ 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.
+the final verdict, the build/veredicto round count, and the ordered per-round
+verdict sequence. 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.
+
+**Phase attribution (v2).** The per-round verdict sequence makes blame precise:
+a `corregir` round re-runs — and so blames — the `build` phase, and a
+`replantear` round blames the `plan` phase. Autotune aggregates that sequence
+per phase and upgrades **only the phase at fault**, one tier at a time — a
+`build` problem no longer drags `plan` up with it. The `explore` and `veredicto`
+phases are never tuned.
 
 **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:
+whether that phase's model should change. Until a phase has accumulated enough
+v2 runs of its own, autotune deliberately stays quiet — a one-time, silent
+cold-start after upgrading, not a regression. The `autotune` mode in
+`~/.pi/zero.json` controls what happens next:
 
 | Mode | Behaviour |
 | ---- | --------- |

package/extensions/autotune.ts

@@ -12,8 +12,9 @@
 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;
+ *  other `v` is dropped by `parseRunLine` rather than mis-aggregated. v2 adds
+ *  the per-round `verdicts` sequence; `parseRunLine` still accepts v1 records. */
+export const RUN_SCHEMA_VERSION = 2;
 
 /** The SDD phases a run record carries a model for, in pipeline order. */
 const RECORD_PHASES = ["explore", "plan", "build", "veredicto"] as const;
@@ -25,6 +26,14 @@ const VERDICTS = ["pasa", "cap-reached"] as const;
 /** A run's terminal verdict. */
 export type RunVerdict = (typeof VERDICTS)[number];
 
+/** Per-round verdicts the `veredicto` phase can return. `corregir` re-runs
+ *  build, `replantear` re-runs plan, `pasa` ends the run. `cap-reached` is a
+ *  run-level terminal state and is deliberately *not* a round verdict. */
+const ROUND_VERDICTS = ["corregir", "replantear", "pasa"] as const;
+
+/** A single round's verdict from the `veredicto` phase. */
+export type RunRoundVerdict = (typeof ROUND_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 {
@@ -48,6 +57,11 @@ export interface RunRecord {
   verdict: RunVerdict;
   /** Count of build/veredicto rounds — `1` for a clean first-pass run. */
   rounds: number;
+  /** The chronological per-round verdict sequence. Present on `v:2` records
+   *  (`verdicts.length === rounds`); `undefined` on `v:1` records, which carry
+   *  only the run-level verdict and so cannot be phase-attributed. Its
+   *  presence is the single discriminator `aggregate` uses for v2 attribution. */
+  verdicts?: RunRoundVerdict[];
 }
 
 /** How aggressively zero applies a learned profile — stored in `zero.json`.
@@ -60,15 +74,56 @@ function isObject(value: unknown): value is Record<string, unknown> {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 
+/**
+ * Validate a parsed `verdicts` value against the v2 invariants.
+ *
+ * Returns the typed array when the value is a non-empty `RunRoundVerdict[]`
+ * with `length === rounds` and a sequence consistent with the run-level
+ * `verdict`: a `pasa` run ends with exactly one `pasa` (last entry), a
+ * `cap-reached` run contains no `pasa`. Returns `null` for any violation —
+ * the caller drops the whole record rather than mis-attribute.
+ */
+function validateVerdicts(
+  value: unknown,
+  verdict: RunVerdict,
+  rounds: number,
+): RunRoundVerdict[] | null {
+  if (!Array.isArray(value)) return null;
+  if (value.length < 1) return null;
+  if (value.length !== rounds) return null;
+
+  const verdicts: RunRoundVerdict[] = [];
+  for (const entry of value) {
+    if (typeof entry !== "string") return null;
+    if (!(ROUND_VERDICTS as readonly string[]).includes(entry)) return null;
+    verdicts.push(entry as RunRoundVerdict);
+  }
+
+  const passCount = verdicts.filter((e) => e === "pasa").length;
+  if (verdict === "pasa") {
+    // Exactly one `pasa`, and it is the final entry.
+    if (passCount !== 1) return null;
+    if (verdicts[verdicts.length - 1] !== "pasa") return null;
+  } else {
+    // `cap-reached`: the run never passed.
+    if (passCount !== 0) return null;
+  }
+
+  return verdicts;
+}
+
 /**
  * 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.
+ * Accepts both `v:1` records (no `verdicts`) and `v:2` records (a fully
+ * validated per-round `verdicts` sequence). Returns `null` — never throws —
+ * for anything off-shape: invalid JSON, a non-object, a `v` outside
+ * `{1, 2}`, a missing/non-string `feature` or `ts`, a non-integer `rounds`, a
+ * `verdict` outside the enum, a `phases` map missing any of the four phases
+ * or carrying a non-string model, or — for `v:2` — a missing/non-array/
+ * inconsistent `verdicts`. 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;
@@ -80,12 +135,13 @@ export function parseRunLine(line: string): RunRecord | null {
 
   if (!isObject(parsed)) return null;
 
-  if (parsed.v !== RUN_SCHEMA_VERSION) return null;
+  if (parsed.v !== 1 && parsed.v !== 2) 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;
+  const verdict = parsed.verdict as RunVerdict;
 
   if (!isObject(parsed.phases)) return null;
   const phases = {} as RunRecord["phases"];
@@ -96,13 +152,23 @@ export function parseRunLine(line: string): RunRecord | null {
     phases[phase] = { model: phaseRun.model };
   }
 
+  // v2 records must carry a fully consistent `verdicts` sequence; v1 records
+  // legitimately lack the field (the discriminator is `v`, not its presence).
+  let verdicts: RunRoundVerdict[] | undefined;
+  if (parsed.v === 2) {
+    const validated = validateVerdicts(parsed.verdicts, verdict, parsed.rounds);
+    if (validated === null) return null;
+    verdicts = validated;
+  }
+
   return {
-    v: RUN_SCHEMA_VERSION,
+    v: parsed.v,
     ts: parsed.ts,
     feature: parsed.feature,
     phases,
-    verdict: parsed.verdict as RunVerdict,
+    verdict,
     rounds: parsed.rounds,
+    ...(verdicts !== undefined ? { verdicts } : {}),
   };
 }
 
@@ -149,6 +215,16 @@ export interface PhaseModelStat {
   /** Mean `rounds` averaged ONLY over runs that reached `pasa`; `null` when no
    *  `pasa` run exists for the pair. */
   avgRounds: number | null;
+  // --- v2 phase attribution ---
+  /** Count of `v:2` records contributing to this pair — the dormancy-gate
+   *  denominator. v1 records do not increment this. */
+  v2Samples: number;
+  /** Mean count of `corregir` verdicts per v2 run for this pair — only
+   *  meaningful for `phase === "build"`. `null` when `v2Samples === 0`. */
+  avgCorregir: number | null;
+  /** Mean count of `replantear` verdicts per v2 run for this pair — only
+   *  meaningful for `phase === "plan"`. `null` when `v2Samples === 0`. */
+  avgReplantear: number | null;
 }
 
 /** Map key for a `(phase, model)` bucket. */
@@ -159,12 +235,19 @@ function statKey(phase: string, model: string): string {
 /**
  * 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.
+ * For every record (v1 and v2 alike), 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.
+ *
+ * Only records carrying a `verdicts` sequence (v2) contribute phase
+ * attribution: each such record increments `v2Samples` for every phase, and
+ * folds its per-run `corregir` count into the `build` model's `avgCorregir`
+ * accumulator and its per-run `replantear` count into the `plan` model's
+ * `avgReplantear` accumulator. `avgCorregir`/`avgReplantear` are `null` when a
+ * pair has no v2 evidence. An empty input yields an empty map.
  */
 export function aggregate(records: RunRecord[]): Map<string, PhaseModelStat> {
   interface Acc {
@@ -172,11 +255,22 @@ export function aggregate(records: RunRecord[]): Map<string, PhaseModelStat> {
     passes: number;
     passRounds: number;
     passRoundCount: number;
+    v2Samples: number;
+    corregirTotal: number;
+    replantearTotal: 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";
+    const isV2 = record.verdicts !== undefined;
+    const corregirCount = isV2
+      ? (record.verdicts as RunRoundVerdict[]).filter((v) => v === "corregir").length
+      : 0;
+    const replantearCount = isV2
+      ? (record.verdicts as RunRoundVerdict[]).filter((v) => v === "replantear").length
+      : 0;
+
     for (const phase of RECORD_PHASES) {
       const phaseRun = record.phases[phase];
       const model = phaseRun?.model;
@@ -185,7 +279,19 @@ export function aggregate(records: RunRecord[]): Map<string, PhaseModelStat> {
       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 } };
+        bucket = {
+          phase,
+          model,
+          data: {
+            samples: 0,
+            passes: 0,
+            passRounds: 0,
+            passRoundCount: 0,
+            v2Samples: 0,
+            corregirTotal: 0,
+            replantearTotal: 0,
+          },
+        };
         acc.set(key, bucket);
       }
       bucket.data.samples += 1;
@@ -198,18 +304,29 @@ export function aggregate(records: RunRecord[]): Map<string, PhaseModelStat> {
           bucket.data.passRoundCount += 1;
         }
       }
+      if (isV2) {
+        bucket.data.v2Samples += 1;
+        // `corregir` blames the build phase's model, `replantear` the plan
+        // phase's. The mapping is the pipeline contract, fixed and known.
+        if (phase === "build") bucket.data.corregirTotal += corregirCount;
+        if (phase === "plan") bucket.data.replantearTotal += replantearCount;
+      }
     }
   }
 
   const stats = new Map<string, PhaseModelStat>();
   for (const [key, bucket] of acc) {
-    const { samples, passes, passRounds, passRoundCount } = bucket.data;
+    const { samples, passes, passRounds, passRoundCount, v2Samples, corregirTotal, replantearTotal } =
+      bucket.data;
     stats.set(key, {
       phase: bucket.phase,
       model: bucket.model,
       samples,
       passRate: samples > 0 ? passes / samples : 0,
       avgRounds: passRoundCount > 0 ? passRounds / passRoundCount : null,
+      v2Samples,
+      avgCorregir: v2Samples > 0 ? corregirTotal / v2Samples : null,
+      avgReplantear: v2Samples > 0 ? replantearTotal / v2Samples : null,
     });
   }
   return stats;
@@ -292,6 +409,17 @@ 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;
 
+/** Below this many `v:2` records a phase is left dormant — too little
+ *  attributed evidence to act on (Story 7). Reuses v1's `MIN_SAMPLES` value. */
+export const MIN_V2_SAMPLES = 5;
+
+/** Mean `corregir`/run strictly above this value blames the `build` model. */
+export const HIGH_AVG_CORREGIR = 1.0;
+
+/** Mean `replantear`/run strictly above this value blames the `plan` model.
+ *  Lower than `HIGH_AVG_CORREGIR` because a `replantear` is rarer and costlier. */
+export const HIGH_AVG_REPLANTEAR = 0.5;
+
 /**
  * A proposed change of model for one SDD phase. `reason` is a human-readable
  * string used verbatim in notifications.
@@ -307,22 +435,33 @@ export interface Adjustment {
   reason: string;
 }
 
+/** The phases v2 autotune can attribute blame to and adjust. `explore` and
+ *  `veredicto` are structurally excluded — no round verdict ever blames them. */
+const ATTRIBUTABLE_PHASES = ["build", "plan"] as const;
+
 /**
- * Decide model adjustments from aggregated statistics.
+ * Decide model adjustments from aggregated statistics — v2 phase-attributed.
  *
- * 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.
+ * Only the `build` and `plan` phases are considered: a `corregir` verdict
+ * re-runs build and a `replantear` verdict re-runs plan, so those are the only
+ * phases the verdict sequence can blame. `explore` and `veredicto` are
+ * structurally never iterated and so never adjusted (Story 6).
+ *
+ * For each attributable phase, looks up the `(phase, currentModel)` stat and:
+ *   - skips an absent stat;
+ *   - skips a phase with `v2Samples < MIN_V2_SAMPLES` — too little attributed
+ *     evidence (the dormancy gate, Story 7);
+ *   - reads the phase's blame measure (`build` → `avgCorregir` vs
+ *     `HIGH_AVG_CORREGIR`, `plan` → `avgReplantear` vs `HIGH_AVG_REPLANTEAR`)
+ *     and skips when it is `null` or not strictly above its threshold;
+ *   - otherwise proposes one tier up via `stepUp`.
  *
  * 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.
+ * model outside `knownModels`-or-the-fixed-representative set. v1's
+ * `LOW_PASS_RATE`/`HIGH_AVG_ROUNDS`/`RELIABLE_PASS_RATE` constants remain
+ * exported but no longer drive this function.
  */
 export function decideAdjustments(
   stats: Map<string, PhaseModelStat>,
@@ -331,29 +470,25 @@ export function decideAdjustments(
 ): Adjustment[] {
   const adjustments: Adjustment[] = [];
 
-  for (const phase of RECORD_PHASES) {
+  for (const phase of ATTRIBUTABLE_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;
+    if (stat === undefined) 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);
+    // Dormancy gate: too few v2 records to attribute blame.
+    if (stat.v2Samples < MIN_V2_SAMPLES) continue;
 
-    if (reliable) continue;
-    if (!underPerforming) continue;
+    const measure = phase === "build" ? stat.avgCorregir : stat.avgReplantear;
+    const threshold = phase === "build" ? HIGH_AVG_CORREGIR : HIGH_AVG_REPLANTEAR;
+    if (measure === null || !(measure > threshold)) 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`;
+    const blame = phase === "build" ? "corregir" : "replantear";
+    const reason = `avg ${measure.toFixed(1)} ${blame}/run over ${stat.v2Samples} v2 runs`;
 
     adjustments.push({ phase, from: currentModel, to, reason });
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gonrocca/zero-pi",
-  "version": "0.1.9",
+  "version": "0.1.10",
   "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": [

package/prompts/orchestrator.md

@@ -173,7 +173,7 @@ 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`.
+- `v`: the schema version — always the integer `2`.
 - `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`,
@@ -183,11 +183,18 @@ followed by a single newline. Build it from facts you already hold:
   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).
+- `verdicts`: the ordered per-round verdict sequence — one entry per round, in
+  chronological order, accumulated as `veredicto` returns each round's verdict.
+  Every entry is one of `"corregir"`, `"replantear"`, or `"pasa"`;
+  `"cap-reached"` is a run-level terminal state and never appears inside this
+  array. `verdicts.length` must equal `rounds` (one verdict per round,
+  including the final cap-reaching round). A `pasa` run ends with exactly one
+  `"pasa"`, as the last entry; a `cap-reached` run contains no `"pasa"` at all.
 
 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}
+{"v":2,"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,"verdicts":["corregir","pasa"]}
 ```
 
 Rules: