@gonrocca/zero-pi 0.1.7 → 0.1.9

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

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.9",
   "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

@@ -199,3 +199,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.