@gonrocca/zero-pi 0.1.7 → 0.1.10

package/README.md

@@ -46,6 +46,12 @@ Run it with the `/forge <feature>` prompt. The orchestrator drives phase order
 and enforces a hard build/veredicto iteration cap. Each phase has its own prompt
 under `prompts/phases/` so it can be delegated to a dedicated sub-agent.
 
+Besides the explicit `/forge` command, an SDD run can also be started from
+natural language: describe the work and signal SDD intent — e.g. "hacelo con
+sdd" or "usá el pipeline" — and the `sdd-routing` skill routes the request into
+`/forge` for you. It triggers only on a clear signal phrase and stays out of the
+way for ordinary requests; `/forge` remains the primary, explicit entry point.
+
 **Review Workload Forecast** — the plan phase keeps tasks reviewable. Every
 planned task carries a `review: ~N changed lines` estimate, and `tasks.md` gains
 a `## Review Workload` section with the per-task estimates and a bold run total.
@@ -80,6 +86,47 @@ 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.
 
+### Canonical specs & `/zero-sync`
+
+zero keeps a **canonical, project-wide spec store** that accumulates accepted
+requirements across runs, so each `/forge` run builds on the last instead of
+starting from a blank spec.
+
+**The canonical store — `.sdd/specs/requirements.md`.** A single flat markdown
+file: a `# ` title followed by `### REQ: <stable-unique-name>` requirement
+blocks. It is the project's source of truth. The `plan` phase reads it as the
+baseline; a fresh project has no store yet, and that absence simply means an
+empty store.
+
+**The granular plan artifacts.** Every run's `plan` phase writes four files
+into `.sdd/<slug>/`:
+
+- `proposal.md` — the change intent: scope and rationale, in prose.
+- `spec.md` — the **delta** against the canonical store, never a full spec. Up
+  to three `H2` sections — `## ADDED`, `## MODIFIED`, `## REMOVED` — each
+  holding `### REQ:` blocks. `## MODIFIED` carries the complete updated text of
+  an existing block (not a diff); `## REMOVED` needs only the name line.
+- `design.md` — how it is built.
+- `tasks.md` — the ordered task list with its `## Review Workload` section.
+
+**`/zero-sync` — folding the delta into the store.** `/zero-sync <slug>` is a
+real pi command — a deterministic, unit-tested merge, not an LLM prompt — that
+reads the store and the run's delta `spec.md`, applies the ADDED/MODIFIED/REMOVED
+changes, and writes the store atomically. Guardrails reject a bad delta before
+anything is written: a duplicate name, an ADDED collision with an existing
+block, a MODIFIED or REMOVED of a missing block, or malformed input. On a
+guardrail failure it writes nothing and reports the offending requirement; the
+store is never left half-merged. After a `pasa` verdict the SDD orchestrator
+invokes `/zero-sync <slug>` automatically — a `corregir`, `replantear`, or
+cap-reached run never syncs.
+
+**The archive — `.sdd/archive/`.** Each successful sync appends a dated,
+slug-named entry `.sdd/archive/<YYYY-MM-DD>-<slug>/` containing a copy of the
+run's `proposal.md` and `spec.md` plus a `sync.md` report listing every added,
+modified, and removed requirement. The archive is append-only — a new entry
+never rewrites a prior one — so it is a full audit trail of how the canonical
+store evolved.
+
 ### Adaptive model profiles
 
 zero learns which model fits each SDD phase from your own run history and can
@@ -87,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/extensions/spec-merge-extension.ts

@@ -0,0 +1,286 @@
+// zero-pi — the /zero-sync command.
+//
+// A real pi command — a code handler, not an LLM prompt — that folds a
+// `/forge` run's delta `spec.md` into the project's canonical spec store and
+// archives the change. It is deterministic: every parsing, guardrail, and
+// merge decision lives in the pure-logic `spec-merge.ts`; this file only reads
+// and writes the filesystem and reports the result.
+//
+//   /zero-sync canonical-specs   sync the named run's delta into the store
+//   /zero-sync                   resolve the single candidate run, or ask
+//
+// The SDD orchestrator invokes `/zero-sync <slug>` after a `pasa` verdict. On a
+// guardrail failure the command writes NOTHING and reports the failing
+// requirement name(s); on success it writes the store atomically (`.tmp` +
+// `rename`) and appends an entry to `.sdd/archive/`.
+//
+// All decisions live in `spec-merge.ts`; the package stays dependency-free:
+// `node:fs`/`node:os`/`node:path` only, plus minimal local interfaces for the
+// pi API. The whole handler is wrapped in a swallowing `try/catch`, exactly
+// like `autotune-extension.ts` — a failure must never break a pi session.
+
+import {
+  copyFileSync,
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  renameSync,
+  writeFileSync,
+} from "node:fs";
+import { join } from "node:path";
+
+import { isEmptyDelta, mergeDelta, parseDelta, type MergeSummary } from "./spec-merge.ts";
+
+/** The canonical store path, relative to the project root. */
+const STORE_DIR = join(".sdd", "specs");
+const STORE_FILE = join(STORE_DIR, "requirements.md");
+
+/** The per-run artifacts directory root. */
+const SDD_DIR = ".sdd";
+
+/** The audit-trail archive root. */
+const ARCHIVE_DIR = join(".sdd", "archive");
+
+/** Read a UTF-8 file, returning `null` when it is absent or unreadable. */
+function readFileOrNull(path: string): string | null {
+  try {
+    return readFileSync(path, "utf8");
+  } catch {
+    return null;
+  }
+}
+
+/** Today's date as `YYYY-MM-DD`, for the archive directory name. */
+function todayStamp(): string {
+  return new Date().toISOString().slice(0, 10);
+}
+
+/**
+ * Resolve the run slug to sync.
+ *
+ * The orchestrator always passes an explicit slug, so this is a convenience
+ * path. With an explicit arg it is used verbatim. With no arg it lists the
+ * `.sdd/` subdirectories that carry a `spec.md` (sync candidates) and, when
+ * exactly one exists, returns it; otherwise it returns `null` so the caller
+ * can ask or report.
+ */
+function resolveSlug(arg: string): string | null {
+  const explicit = arg.trim();
+  if (explicit !== "") return explicit;
+
+  let entries: string[];
+  try {
+    entries = readdirSync(SDD_DIR, { withFileTypes: true })
+      .filter((e) => e.isDirectory() && e.name !== "specs" && e.name !== "archive")
+      .map((e) => e.name);
+  } catch {
+    return null;
+  }
+
+  const candidates = entries.filter((name) => existsSync(join(SDD_DIR, name, "spec.md")));
+  return candidates.length === 1 ? candidates[0] : null;
+}
+
+/**
+ * Pick a unique archive directory for `<date>-<slug>`.
+ *
+ * The archive is append-only: a new entry never rewrites a prior one. When a
+ * slug syncs twice on the same date the bare `<date>-<slug>` is already taken,
+ * so a numeric `-2`, `-3` … suffix is appended until the name is free.
+ */
+function uniqueArchiveDir(date: string, slug: string): string {
+  const base = `${date}-${slug}`;
+  let dir = join(ARCHIVE_DIR, base);
+  let n = 2;
+  while (existsSync(dir)) {
+    dir = join(ARCHIVE_DIR, `${base}-${n}`);
+    n += 1;
+  }
+  return dir;
+}
+
+/** Render a `MergeSummary` as the archive `sync.md` audit report. */
+function renderSyncReport(slug: string, date: string, summary: MergeSummary): string {
+  const section = (title: string, names: string[]): string =>
+    names.length === 0
+      ? `## ${title}\n\n(none)\n`
+      : `## ${title}\n\n${names.map((n) => `- ${n}`).join("\n")}\n`;
+
+  return [
+    `# Spec sync — ${slug}`,
+    "",
+    `Date: ${date}`,
+    "",
+    section("Added", summary.added),
+    section("Modified", summary.modified),
+    section("Removed", summary.removed),
+  ].join("\n");
+}
+
+/** Render the human-facing one-shot report of a `MergeSummary`. */
+function describeSummary(summary: MergeSummary): string {
+  const lines: string[] = [];
+  if (summary.added.length > 0) lines.push(`  added:    ${summary.added.join(", ")}`);
+  if (summary.modified.length > 0) {
+    lines.push(`  modified: ${summary.modified.join(", ")}  (replaces existing spec text)`);
+  }
+  if (summary.removed.length > 0) {
+    lines.push(`  removed:  ${summary.removed.join(", ")}  (deletes from the store)`);
+  }
+  return lines.join("\n");
+}
+
+/** The slice of pi's extension API this command uses. */
+interface PiUI {
+  notify(message: string, type?: "info" | "warning" | "error"): void;
+}
+interface PiCommandContext {
+  ui: PiUI;
+}
+interface PiExtensionAPI {
+  registerCommand(
+    name: string,
+    options: {
+      description?: string;
+      handler: (args: string, ctx: PiCommandContext) => Promise<void> | void;
+    },
+  ): void;
+}
+
+/**
+ * The `/zero-sync` handler — folds a run's delta into the canonical store.
+ *
+ * Wrapped in a swallowing `try/catch` so a failure can never break a pi
+ * session. On a guardrail error or any read failure it writes nothing and
+ * reports the problem; only a clean `mergeDelta` result reaches the atomic
+ * store write and the archive step.
+ */
+function runSync(args: string, ctx: PiCommandContext): 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.
+    }
+  };
+
+  const slug = resolveSlug(args);
+  if (slug === null) {
+    notify(
+      "zero-sync: no run slug given and no single sync candidate found — " +
+        "run /zero-sync <slug> (the slug of the run's .sdd/<slug>/ directory)",
+      "warning",
+    );
+    return;
+  }
+
+  const deltaPath = join(SDD_DIR, slug, "spec.md");
+  const deltaText = readFileOrNull(deltaPath);
+  if (deltaText === null) {
+    // A legacy run produced no delta `spec.md` — nothing to sync. This is not
+    // an error: legacy runs finish in legacy mode (additive design).
+    notify(
+      `zero-sync: ${deltaPath} not found — this run produced no delta spec.md, nothing to sync`,
+      "warning",
+    );
+    return;
+  }
+
+  // An empty delta (no blocks in any section) is valid — report and stop
+  // before touching the store.
+  if (isEmptyDelta(parseDelta(deltaText))) {
+    notify(`zero-sync: empty delta in ${deltaPath} — nothing to sync, store left untouched`, "info");
+    return;
+  }
+
+  // The store is absent on a fresh project — `mergeDelta` treats "" as the
+  // empty store, so an all-ADDED delta bootstraps it.
+  const storeText = readFileOrNull(STORE_FILE) ?? "";
+
+  const result = mergeDelta(storeText, deltaText);
+  if (!result.ok) {
+    // Guardrail failure — write NOTHING. The `pasa` verdict still stands, but
+    // the store is flagged out of sync for a manual fix.
+    const detail = result.errors.map((e) => `  - [${e.kind}] ${e.message}`).join("\n");
+    notify(
+      `zero-sync: store NOT updated — the delta has guardrail errors:\n${detail}`,
+      "error",
+    );
+    return;
+  }
+
+  // Success — write the store atomically: `.tmp` then `rename`. `mkdir -p`
+  // `.sdd/specs/` so a fresh project gets its first store file.
+  try {
+    mkdirSync(STORE_DIR, { recursive: true });
+    const tmp = `${STORE_FILE}.tmp`;
+    writeFileSync(tmp, result.store, "utf8");
+    renameSync(tmp, STORE_FILE);
+  } catch (err) {
+    notify(
+      `zero-sync: failed to write the store at ${STORE_FILE}: ${
+        err instanceof Error ? err.message : String(err)
+      }`,
+      "error",
+    );
+    return;
+  }
+
+  // Archive step. The store is already the source of truth; an archive failure
+  // here does NOT revert the merge — it is reported so the gap is visible.
+  const date = todayStamp();
+  let archiveNote = "";
+  try {
+    const archiveDir = uniqueArchiveDir(date, slug);
+    mkdirSync(archiveDir, { recursive: true });
+
+    for (const name of ["proposal.md", "spec.md"]) {
+      const src = join(SDD_DIR, slug, name);
+      if (existsSync(src)) copyFileSync(src, join(archiveDir, name));
+    }
+    writeFileSync(join(archiveDir, "sync.md"), renderSyncReport(slug, date, result.summary), "utf8");
+    archiveNote = `archived to ${archiveDir}`;
+  } catch (err) {
+    archiveNote = `WARNING: store updated but archive step failed: ${
+      err instanceof Error ? err.message : String(err)
+    }`;
+  }
+
+  const detail = describeSummary(result.summary);
+  notify(
+    `zero-sync: canonical store updated (${STORE_FILE})\n${detail}\n${archiveNote}`,
+    "info",
+  );
+}
+
+/**
+ * The pi extension entry point — registers the `/zero-sync` command.
+ *
+ * Called with no or an invalid `pi`, it no-ops cleanly. The handler body is
+ * wrapped again in a swallowing `try/catch` so neither registration nor a
+ * later failure can break a pi session.
+ */
+export default function register(pi?: PiExtensionAPI): void {
+  if (!pi || typeof pi.registerCommand !== "function") return;
+
+  pi.registerCommand("zero-sync", {
+    description:
+      "Fold a /forge run's delta spec.md into the canonical .sdd/specs/ store — /zero-sync <slug>",
+    handler: (args: string, ctx: PiCommandContext): void => {
+      try {
+        if (!ctx || !ctx.ui || typeof ctx.ui.notify !== "function") return;
+        runSync(args, ctx);
+      } catch (err) {
+        try {
+          ctx.ui.notify(
+            `zero-sync: ${err instanceof Error ? err.message : String(err)}`,
+            "error",
+          );
+        } catch {
+          // A notification failure must never break a pi session.
+        }
+      }
+    },
+  });
+}

package/extensions/spec-merge.ts

@@ -0,0 +1,373 @@
+// zero-pi — canonical spec store delta-merge engine, pure-logic module.
+//
+// zero keeps a project-wide canonical spec store under `.sdd/specs/`. Every
+// `/forge` run produces a *delta* (`.sdd/<slug>/spec.md`) and, once the run
+// reaches a `pasa` verdict, the delta is folded into the store. The merge
+// *must* be deterministic and reproducible (the same delta against the same
+// store always yields the same result) — so every parsing, guardrail, and
+// merge decision lives here in plain, dependency-free TypeScript, exactly like
+// `autotune.ts`. The pi wiring lives in `spec-merge-extension.ts`.
+//
+// This file has no pi imports, no filesystem access, and no side-effecting
+// top-level code: parsing and merging are pure string work. It never throws on
+// malformed input — a bad emission degrades to a surfaced `MergeError`, never
+// a corrupted store.
+
+/** One named requirement: stable name + raw body text (criteria included). */
+export interface RequirementBlock {
+  name: string;
+  /** Verbatim block body, trimmed; `""` allowed for a REMOVED entry. */
+  body: string;
+}
+
+/** A parsed delta — three buckets, any may be empty. */
+export interface SpecDelta {
+  added: RequirementBlock[];
+  modified: RequirementBlock[];
+  removed: RequirementBlock[];
+}
+
+/** A guardrail violation. `kind` drives the human message. */
+export interface MergeError {
+  kind:
+    | "duplicate-in-delta" // same name twice across/within delta sections
+    | "added-name-collision" // ADDED name already in the store
+    | "modified-missing" // MODIFIED names a block absent from the store
+    | "removed-missing" // REMOVED names a block absent from the store
+    | "parse-error"; // malformed store or delta input
+  /** Offending requirement name (`""` for a `parse-error`). */
+  name: string;
+  /** Ready-to-surface explanation. */
+  message: string;
+}
+
+/** What a successful merge changed — drives the sync report. */
+export interface MergeSummary {
+  added: string[]; // names appended
+  modified: string[]; // names replaced
+  removed: string[]; // names deleted
+}
+
+/** Result of a merge attempt: either the new store text, or the errors. */
+export type MergeResult =
+  | { ok: true; store: string; summary: MergeSummary }
+  | { ok: false; errors: MergeError[] };
+
+/** The pinned `# ` title line of `.sdd/specs/requirements.md`. A stable title
+ *  keeps `renderStore` ↔ `parseStore` a clean round-trip. */
+export const STORE_TITLE = "Canonical specs";
+
+/** Matches a requirement-block header: `### REQ: <name>`. The name is
+ *  everything after `REQ:`, captured for trimming by the caller. */
+const REQ_HEADER = /^###\s+REQ:\s*(.*)$/;
+
+/** Matches a delta section header: `## ADDED` / `## MODIFIED` / `## REMOVED`
+ *  (case-insensitive on the keyword). */
+const SECTION_HEADER = /^##\s+(ADDED|MODIFIED|REMOVED)\s*$/i;
+
+// ---------------------------------------------------------------------------
+// Parsing
+// ---------------------------------------------------------------------------
+
+/**
+ * Split a run of text lines into `### REQ:` blocks.
+ *
+ * Each block starts at a `### REQ:` header and runs up to (but not including)
+ * the next `### REQ:` header or the end of the input. The name is everything
+ * after `REQ:`, trimmed; the body is every following line up to the next
+ * header, joined and trimmed. Lines before the first header are ignored — they
+ * are a title or a section heading the caller already consumed. A header with
+ * an empty name still produces a block (with `name === ""`); the caller's
+ * guardrails decide whether that is acceptable.
+ */
+function parseBlocks(lines: readonly string[]): RequirementBlock[] {
+  const blocks: RequirementBlock[] = [];
+  let current: { name: string; body: string[] } | null = null;
+
+  const flush = (): void => {
+    if (current !== null) {
+      blocks.push({ name: current.name, body: current.body.join("\n").trim() });
+    }
+  };
+
+  for (const line of lines) {
+    const header = line.match(REQ_HEADER);
+    if (header !== null) {
+      flush();
+      current = { name: header[1].trim(), body: [] };
+    } else if (current !== null) {
+      current.body.push(line);
+    }
+  }
+  flush();
+
+  return blocks;
+}
+
+/**
+ * Parse a canonical store file into ordered blocks.
+ *
+ * The store is a `# ` title line followed by a sequence of `### REQ:` blocks —
+ * there are no `## ADDED` etc. headings in the *store*. Any line before the
+ * first `### REQ:` header (the title, blank lines) is ignored. Never throws:
+ * malformed input simply yields whatever blocks could be recognized — the
+ * caller's `parse-error` guardrail decides whether the result is usable.
+ * Empty or whitespace-only text yields `[]`.
+ */
+export function parseStore(text: string): RequirementBlock[] {
+  if (typeof text !== "string") return [];
+  return parseBlocks(text.split(/\r?\n/));
+}
+
+/**
+ * Parse a delta `spec.md` into a `SpecDelta`.
+ *
+ * Walks the file line by line, switching the active bucket on each
+ * `## ADDED` / `## MODIFIED` / `## REMOVED` header and collecting the
+ * `### REQ:` blocks that follow into that bucket. Lines outside any section
+ * (the `# ` title, blank lines) are ignored. An absent or empty section simply
+ * yields an empty bucket. Never throws — missing/non-string text yields an
+ * empty delta. A `### REQ:` block that appears before any section header is
+ * dropped (it belongs to no bucket); the caller treats a delta with zero
+ * blocks as "empty delta — nothing to sync", not an error.
+ */
+export function parseDelta(text: string): SpecDelta {
+  const delta: SpecDelta = { added: [], modified: [], removed: [] };
+  if (typeof text !== "string") return delta;
+
+  let section: keyof SpecDelta | null = null;
+  let buffer: string[] = [];
+
+  const flush = (): void => {
+    if (section !== null && buffer.length > 0) {
+      delta[section].push(...parseBlocks(buffer));
+    }
+    buffer = [];
+  };
+
+  for (const line of text.split(/\r?\n/)) {
+    const sectionHeader = line.match(SECTION_HEADER);
+    if (sectionHeader !== null) {
+      flush();
+      const keyword = sectionHeader[1].toUpperCase();
+      section =
+        keyword === "ADDED" ? "added" : keyword === "MODIFIED" ? "modified" : "removed";
+      continue;
+    }
+    if (section !== null) buffer.push(line);
+  }
+  flush();
+
+  return delta;
+}
+
+/** Total block count across the three delta buckets. */
+function deltaBlockCount(delta: SpecDelta): number {
+  return delta.added.length + delta.modified.length + delta.removed.length;
+}
+
+// ---------------------------------------------------------------------------
+// Guardrails
+// ---------------------------------------------------------------------------
+
+/**
+ * Run every guardrail check against a parsed store + delta.
+ *
+ * Returns a `MergeError[]` — empty when the merge is safe to apply. Each error
+ * carries the offending `name` and a ready-to-surface `message`. The checks,
+ * in order:
+ *
+ *   - `parse-error`     — a block (store or delta) carries an empty name; the
+ *                         input could not be structurally understood.
+ *   - `duplicate-in-delta` — the same name appears more than once across (or
+ *                         within) the ADDED/MODIFIED/REMOVED sections.
+ *   - `added-name-collision` — an ADDED name already exists in the store (to
+ *                         *change* a block the run must use MODIFIED).
+ *   - `modified-missing` — a MODIFIED block names a requirement absent from
+ *                         the store.
+ *   - `removed-missing` — a REMOVED block names a requirement absent from the
+ *                         store.
+ *
+ * Pure, never throws. `mergeDelta` runs this before applying *any* change, so
+ * a non-empty result means the whole delta is rejected and the store is left
+ * untouched.
+ */
+export function checkGuardrails(
+  store: readonly RequirementBlock[],
+  delta: SpecDelta,
+): MergeError[] {
+  const errors: MergeError[] = [];
+
+  // parse-error — any block (store or delta) with an empty name is malformed.
+  for (const block of store) {
+    if (block.name === "") {
+      errors.push({
+        kind: "parse-error",
+        name: "",
+        message:
+          "malformed store: a `### REQ:` block has an empty name — the store could not be parsed",
+      });
+      break;
+    }
+  }
+  for (const block of [...delta.added, ...delta.modified, ...delta.removed]) {
+    if (block.name === "") {
+      errors.push({
+        kind: "parse-error",
+        name: "",
+        message:
+          "malformed delta: a `### REQ:` block has an empty name — the delta could not be parsed",
+      });
+      break;
+    }
+  }
+
+  // duplicate-in-delta — the same name twice across all three delta sections.
+  const seen = new Set<string>();
+  const flagged = new Set<string>();
+  for (const block of [...delta.added, ...delta.modified, ...delta.removed]) {
+    if (block.name === "") continue; // already reported as a parse-error
+    if (seen.has(block.name)) {
+      if (!flagged.has(block.name)) {
+        flagged.add(block.name);
+        errors.push({
+          kind: "duplicate-in-delta",
+          name: block.name,
+          message: `duplicate requirement "${block.name}": it appears more than once in the delta — each requirement may appear at most once across ADDED/MODIFIED/REMOVED`,
+        });
+      }
+    } else {
+      seen.add(block.name);
+    }
+  }
+
+  const storeNames = new Set(store.map((b) => b.name));
+
+  // added-name-collision — an ADDED name already exists in the store.
+  for (const block of delta.added) {
+    if (block.name === "") continue;
+    if (storeNames.has(block.name)) {
+      errors.push({
+        kind: "added-name-collision",
+        name: block.name,
+        message: `ADDED requirement "${block.name}" already exists in the store — use MODIFIED to change an existing requirement`,
+      });
+    }
+  }
+
+  // modified-missing — a MODIFIED name is absent from the store.
+  for (const block of delta.modified) {
+    if (block.name === "") continue;
+    if (!storeNames.has(block.name)) {
+      errors.push({
+        kind: "modified-missing",
+        name: block.name,
+        message: `MODIFIED requirement "${block.name}" is not in the store — only an existing requirement can be modified`,
+      });
+    }
+  }
+
+  // removed-missing — a REMOVED name is absent from the store.
+  for (const block of delta.removed) {
+    if (block.name === "") continue;
+    if (!storeNames.has(block.name)) {
+      errors.push({
+        kind: "removed-missing",
+        name: block.name,
+        message: `REMOVED requirement "${block.name}" is not in the store — only an existing requirement can be removed`,
+      });
+    }
+  }
+
+  return errors;
+}
+
+// ---------------------------------------------------------------------------
+// Render
+// ---------------------------------------------------------------------------
+
+/**
+ * Render an ordered block list back to canonical store markdown.
+ *
+ * The output is a `# ` title line, a blank line, then every block as a
+ * `### REQ: <name>` header followed by its body. Blocks are separated by a
+ * blank line. Round-trips with `parseStore`: `parseStore(renderStore(blocks))`
+ * yields the same names and (trimmed) bodies. `title` defaults to the pinned
+ * `STORE_TITLE`. The result always ends with a single trailing newline.
+ */
+export function renderStore(blocks: readonly RequirementBlock[], title: string = STORE_TITLE): string {
+  const parts: string[] = [`# ${title}`];
+  for (const block of blocks) {
+    const body = block.body.trim();
+    parts.push(body === "" ? `### REQ: ${block.name}` : `### REQ: ${block.name}\n\n${body}`);
+  }
+  return `${parts.join("\n\n")}\n`;
+}
+
+// ---------------------------------------------------------------------------
+// Merge entry point
+// ---------------------------------------------------------------------------
+
+/**
+ * The whole pipeline: parse both inputs, run every guardrail, and — only when
+ * there are zero errors — apply the delta and render the new store.
+ *
+ * This is the single entry point the `/zero-sync` wiring calls. It is pure: no
+ * filesystem, no pi, never throws.
+ *
+ * On any guardrail error it returns `{ ok: false, errors }` and **no store
+ * text is produced** — a partially-applied store is structurally impossible,
+ * because the merge runs after *all* guardrails pass. On success it returns
+ * `{ ok: true, store, summary }` where the delta has been applied as:
+ *
+ *   - ADDED    → appended to the end of the store, in delta order;
+ *   - MODIFIED → the matching store block's body is replaced in place;
+ *   - REMOVED  → the matching store block is deleted.
+ *
+ * An empty delta (zero blocks in every section) is *not* an error: it returns
+ * `ok: true` with the store unchanged and an empty `summary`, so the caller
+ * can report "empty delta — nothing to sync".
+ */
+export function mergeDelta(storeText: string, deltaText: string): MergeResult {
+  const store = parseStore(storeText);
+  const delta = parseDelta(deltaText);
+
+  const errors = checkGuardrails(store, delta);
+  if (errors.length > 0) {
+    return { ok: false, errors };
+  }
+
+  // Apply the delta. Guardrails have proven every name resolves, so the
+  // mutations below cannot fail or leave the store half-applied.
+  const removedNames = new Set(delta.removed.map((b) => b.name));
+  const modifiedByName = new Map(delta.modified.map((b) => [b.name, b]));
+
+  const merged: RequirementBlock[] = [];
+  for (const block of store) {
+    if (removedNames.has(block.name)) continue; // REMOVED — drop it
+    const replacement = modifiedByName.get(block.name);
+    merged.push(replacement ?? block); // MODIFIED — replace; else keep
+  }
+  for (const block of delta.added) {
+    merged.push(block); // ADDED — append in delta order
+  }
+
+  const summary: MergeSummary = {
+    added: delta.added.map((b) => b.name),
+    modified: delta.modified.map((b) => b.name),
+    removed: delta.removed.map((b) => b.name),
+  };
+
+  return { ok: true, store: renderStore(merged), summary };
+}
+
+/**
+ * Whether a parsed delta carries no blocks at all.
+ *
+ * The `/zero-sync` command uses this to report "empty delta — nothing to sync"
+ * before touching the store: a zero-block delta is valid (not a `MergeError`),
+ * it simply has nothing to apply.
+ */
+export function isEmptyDelta(delta: SpecDelta): boolean {
+  return deltaBlockCount(delta) === 0;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gonrocca/zero-pi",
-  "version": "0.1.7",
+  "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": [
@@ -22,7 +22,8 @@
     "extensions": [
       "./extensions/startup-banner.ts",
       "./extensions/zero-models.ts",
-      "./extensions/autotune-extension.ts"
+      "./extensions/autotune-extension.ts",
+      "./extensions/spec-merge-extension.ts"
     ]
   },
   "files": [
@@ -32,6 +33,8 @@
     "extensions/zero-models.ts",
     "extensions/autotune.ts",
     "extensions/autotune-extension.ts",
+    "extensions/spec-merge.ts",
+    "extensions/spec-merge-extension.ts",
     "README.md",
     "LICENSE"
   ],

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:
@@ -199,3 +206,41 @@ Rules:
 - **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.
+
+## Spec sync & 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.
+
+**After a `pasa` verdict — and only then.** Alongside the Cortex save and the
+`zero-runs.jsonl` append, invoke the **`/zero-sync <slug>`** command, passing
+the run's feature slug explicitly. `/zero-sync` is a real pi command — a
+deterministic, unit-tested merge, not a prompt instruction — that reads
+`.sdd/specs/requirements.md` and `.sdd/<slug>/spec.md`, folds the delta into the
+store, writes the store atomically, and archives the change. 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`
+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.

package/prompts/phases/plan.md

@@ -6,12 +6,13 @@ You run the **plan** phase of a zero SDD pipeline.
 
 **Locating artifacts.** If you are invoked with a feature slug, operate on
 `.sdd/<slug>/`. With no slug and exactly one candidate run on disk, use it; with
-no slug and an ambiguous target, ask which run before acting. You write
-`requirements.md`, `design.md`, and `tasks.md` into that directory. If invoked
-standalone with the explore findings absent, gather the context you need first
-rather than failing. On a resumed run, sanity-check any `requirements.md` or
-`design.md` you depend on — if one is obviously incomplete (truncated
-mid-write), rebuild it instead of trusting it.
+no slug and an ambiguous target, ask which run before acting. You write four
+artifacts into that directory — `proposal.md`, `spec.md`, `design.md`, and
+`tasks.md` (see *Artifacts*). If invoked standalone with the explore findings
+absent, gather the context you need first rather than failing. On a resumed run,
+sanity-check any `proposal.md`, `spec.md`, or `design.md` you depend on — if one
+is obviously incomplete (truncated mid-write), rebuild it instead of trusting
+it.
 
 Using the explore findings, write the plan: the requirements (what must be
 true), the design (how it will be built), and an ordered list of small,
@@ -19,7 +20,43 @@ independently verifiable tasks.
 
 Do not write implementation code in this phase — only the plan. Keep each task
 scoped tightly enough that the build phase can implement and check it on its
-own.
+own. `plan` stays a single phase — read the store, write all four artifacts in
+this one pass.
+
+## Reading the canonical store
+
+The project keeps a **canonical spec store** at `.sdd/specs/requirements.md` —
+the accumulated, accepted requirements of every prior run. Read it as the
+baseline before writing this run's requirements.
+
+- **Absent** (`.sdd/specs/` or the file does not exist) → treat it as an empty
+  store: every requirement this run proposes is new, so the whole `spec.md`
+  delta is `## ADDED`.
+- **Present and well-formed** → it is a `# ` title followed by `### REQ: <name>`
+  blocks. Use the existing block names as the identities you may MODIFY or
+  REMOVE.
+- **Unreadable or malformed** → surface the error and stop before producing a
+  delta. Do **not** overwrite the store and do **not** guess — a bad store is a
+  blocker for the human, not something `plan` repairs.
+
+## Artifacts
+
+Write all four into `.sdd/<slug>/`:
+
+- **`proposal.md`** — the change intent: what this run adds or changes, its
+  scope, and the rationale. Prose, no requirement blocks.
+- **`spec.md`** — the **delta** against the canonical store, never a full spec.
+  Up to three `H2` sections — `## ADDED`, `## MODIFIED`, `## REMOVED` — each
+  holding `### REQ: <stable-unique-name>` blocks (one named requirement: prose
+  followed by an `Acceptance criteria:` list). `## ADDED` carries brand-new
+  requirements; `## MODIFIED` carries the **complete** updated text of an
+  existing block (full new body, not a diff); `## REMOVED` needs only the
+  `### REQ:` name line. Any section may be empty or absent; a block name must be
+  unique within and across the delta's sections and not collide with an existing
+  store name unless it is the target of MODIFIED/REMOVED.
+- **`design.md`** — how it is built (unchanged from before).
+- **`tasks.md`** — the ordered task list, keeping its `## Review Workload`
+  section (see below).
 
 Honour the prior-run lessons carried in the explore findings: when a past run
 was sent back with `replantear`, do not repeat the plan mistake it recorded.

package/skills/sdd-routing.md

@@ -0,0 +1,54 @@
+---
+description: Route a natural-language request into the zero SDD pipeline when the user signals SDD intent
+---
+
+# zero — Natural-language SDD routing
+
+zero's spec-driven development pipeline is normally started with the explicit
+`/forge <feature>` command. This skill adds one purely additive convenience:
+when the user **describes work** and **explicitly signals** that they want it
+run through the disciplined SDD pipeline, route the request into the `/forge`
+workflow instead of handling it ad-hoc.
+
+`/forge` stays the primary, deliberate entry point. This skill never replaces
+it — it only catches the case where the user expressed SDD intent in plain
+language rather than typing the command.
+
+## When to route
+
+Route to `/forge` only when **both** of these hold:
+
+1. The message describes **non-trivial work** — a feature, a refactor, a
+   multi-step change worth a spec.
+2. The message contains a **clear SDD intent signal** — an explicit phrase
+   asking for the pipeline. Recognised signals (Spanish or English), and close
+   equivalents:
+   - "hacelo con sdd" / "do it with sdd"
+   - "usá el pipeline" / "use the pipeline"
+   - "con sdd" / "with sdd"
+   - "andá con forge" / "run forge" / "go with forge"
+   - "spec-driven" / "spec driven development"
+
+When both hold, invoke the `/forge` workflow with the user's described work as
+the feature request. Pass that described work **verbatim** — do not rephrase,
+summarize, translate, or interpret it. The existing `/forge` workflow does the
+rest: an ordinary SDD run with all four phases (explore, plan, build,
+veredicto), the round cap, and the veredicto verdict, exactly as an explicit
+`/forge` invocation behaves.
+
+## When NOT to route — be conservative
+
+This skill must **not** hijack ordinary interaction. Do nothing (handle the
+request normally) when:
+
+- The message has **no clear SDD intent signal** — description of work alone is
+  never enough.
+- The user asks a **question**, requests a **small or one-off fix**, or makes
+  any routine request without an SDD signal.
+- The SDD intent is **ambiguous or uncertain** in any way.
+
+When in doubt, do nothing. Default to normal handling and leave the user to
+invoke `/forge` explicitly. A missed natural-language route is harmless — the
+user can still type `/forge`. A wrong route forces routine work through the
+heavy pipeline, which is not. Triggering only on a clear signal phrase is the
+rule; `/forge` remains the explicit primary entry point.