@gonrocca/zero-pi 0.1.49 → 0.1.50

package/README.md

@@ -67,8 +67,8 @@ into `/forge` for you.
 | ------- | ------------ |
 | **`/zero-models`** | Pick the model + provider for each SDD phase — a boxed-window picker, or set one directly. |
 | **Autotune** | Learns which model fits each phase from your run history and re-tunes itself. |
-| **`/zero-sync`** | Folds each run's spec delta into a canonical, project-wide spec store. |
-| **PR / Issues** | `/zero-pr <slug>` and `/zero-issue <slug>` create GitHub tracking links from SDD artifacts. |
+| **`/zero-sync` / `/zero-archive`** | Folds each run's spec delta into a canonical, project-wide spec store and archives approved runs. |
+| **Git / PR / Issues** | `/zero-branch`, `/zero-git-validate`, `/zero-pr`, and `/zero-issue` keep branches and GitHub links audit-ready. |
 | **Run memory** | Every run recalls and saves traces to Cortex, so runs learn from each other. |
 | **Provider guard** | Warns when the `anthropic` provider runs on a metered API key instead of your subscription. |
 | **Startup banner** | The violet ANSI-Shadow `ZERO` wordmark, drawn once at pi startup — `ZERO_HEADER=off` to disable. |
@@ -85,14 +85,40 @@ into `/forge` for you.
 | `/forge <feature>` | Run the SDD pipeline — `--continue [slug]` resumes. |
 | `/zero-models [<phase>=[<provider>/]<model>]` | Show or set per-phase models — `autotune=auto\|ask\|off`. |
 | `/zero-sync <slug>` | Fold a run's spec delta into the canonical spec store; a first all-`## ADDED` delta creates the store lazily. |
-| `/zero-validate <slug>` | Validate a run's proposal/spec/design/tasks artifacts before sync. |
+| `/zero-archive <slug>` | Merge an approved run into `.sdd/specs/`, move it to `.sdd/archive/YYYY-MM-DD-<slug>/`, and persist `archivePath`. |
+| `/zero-validate <slug>` | Validate proposal/spec/design/tasks artifacts, including task schema and per-domain specs. |
 | `/zero-status` | Show each `.sdd/` run's artifact, sync, latest-verdict, and GitHub-link status. |
-| `/zero-pr <slug>` | Create a GitHub PR from a run that already has verdict `pasa`. |
+| `/zero-branch <slug>` | Create/reuse the configured SDD Git branch and persist `branch`/`baseBranch`. |
+| `/zero-git-validate <slug>` | Check worktree, branch, remote, `gh auth`, and verdict gating before PR/archive. |
+| `/zero-pr <slug>` | Create an audit-ready GitHub PR from a run that already has verdict `pasa`. |
 | `/zero-issue <slug>` | Create or reuse a GitHub issue for a run and persist the link. |
 | `/zero-diff <slug>` | Preview the logical spec-store merge without writing files. |
 | `/zero-resume` | Write the session handoff note now. |
 
-### PR / Issues
+### Git / PR / Issues
+
+Recommended flow: `/zero-branch <slug>` → `/zero-issue <slug>` → `/forge <slug>` → `/zero-git-validate <slug> --for=pr` → `/zero-pr <slug>` → `/zero-archive <slug>`.
+
+`links.json` is forward-compatible and may contain:
+
+```json
+{
+  "issueNumber": 12,
+  "issueUrl": "https://github.com/org/repo/issues/12",
+  "branch": "sdd/my-feature",
+  "baseBranch": "main",
+  "prNumber": 34,
+  "prUrl": "https://github.com/org/repo/pull/34",
+  "archivePath": ".sdd/archive/2026-05-24-my-feature"
+}
+```
+
+`/zero-branch <slug>` uses `.sdd/config.json` when present:
+
+```json
+{ "git": { "branchPrefix": "sdd/", "numbering": false, "autoCommit": false, "commitStyle": "conventional", "baseBranch": "main" } }
+```
+
 
 `/zero-pr <slug>` builds a PR title/body from `.sdd/<slug>/proposal.md`,
 `spec.md`, `design.md`, and `tasks.md`, then saves the returned `prNumber` and

package/extensions/gh-runner.ts

@@ -42,7 +42,7 @@ function parseVersion(stdout: string | undefined): string | undefined {
 function parseCreatedUrl(stdout: string | undefined, kind: "pull" | "issues"): { number?: number; url?: string } {
   const lines = (stdout ?? "").split(/\r?\n/).map((l) => l.trim()).filter(Boolean);
   const url = [...lines].reverse().find((l) => /^https:\/\/github\.com\/.+/.test(l));
-  const number = url ? Number(new RegExp(`/${kind}/(\\d+)(?:$|[?#])`).exec(url)?.[1]) : undefined;
+  const number = url ? Number((new RegExp(`/${kind}/(\\d+)(?:$|[?#])`).exec(url) ?? /\/(?:pull|pulls|issues)\/(\d+)(?:$|[?#])/.exec(url))?.[1]) : undefined;
   return { url, number: Number.isFinite(number) ? number : undefined };
 }
 
@@ -58,8 +58,10 @@ export function createGhRunner({ spawn }: { spawn: SpawnLike }) {
       if (!parsed.ok) return parsed as GhResult<string[]>;
       return { ok: true, data: (parsed.data ?? []).map((l) => l.name).filter((n): n is string => typeof n === "string") };
     },
-    async createPr(input: { title: string; bodyFile: string; labels?: string[]; label?: string }): Promise<GhResult<{ number?: number; url?: string }>> {
+    async createPr(input: { title: string; bodyFile: string; labels?: string[]; label?: string; base?: string; head?: string }): Promise<GhResult<{ number?: number; url?: string }>> {
       const args = ["pr", "create", "--title", input.title, "--body-file", input.bodyFile];
+      if (input.base) args.push("--base", input.base);
+      if (input.head) args.push("--head", input.head);
       for (const label of input.labels ?? (input.label ? [input.label] : [])) args.push("--label", label);
       const r = await run(spawn, args);
       return r.ok ? { ok: true, data: parseCreatedUrl(r.data, "pull"), stderr: r.stderr, exitCode: r.exitCode } : { ok: false, stderr: r.stderr, exitCode: r.exitCode };

package/extensions/git-runner.ts

@@ -0,0 +1,44 @@
+import { spawn } from "node:child_process";
+
+export interface GitResult { ok: boolean; stdout: string; stderr: string; code: number }
+export type SpawnLike = typeof spawn;
+
+export interface GitRunner {
+  run(args: string[]): Promise<GitResult>;
+  currentBranch(): Promise<string>;
+  isDirty(): Promise<boolean>;
+  branchExists(branch: string, remote?: boolean): Promise<boolean>;
+  createBranch(branch: string, base?: string): Promise<GitResult>;
+  switchBranch(branch: string): Promise<GitResult>;
+  revParse(ref: string): Promise<GitResult>;
+  hasRemote(name?: string): Promise<boolean>;
+}
+
+export function createGitRunner(spawnImpl: SpawnLike = spawn): GitRunner {
+  const run = (args: string[]): Promise<GitResult> => new Promise((resolve) => {
+    let stdout = "";
+    let stderr = "";
+    let child: ReturnType<SpawnLike>;
+    try {
+      child = spawnImpl("git", args, { shell: false }) as ReturnType<SpawnLike>;
+    } catch (err) {
+      resolve({ ok: false, stdout: "", stderr: err instanceof Error ? err.message : String(err), code: -1 });
+      return;
+    }
+    child.stdout?.on("data", (d: Buffer | string) => { stdout += String(d); });
+    child.stderr?.on("data", (d: Buffer | string) => { stderr += String(d); });
+    child.on("error", (err: Error) => resolve({ ok: false, stdout, stderr: err.message, code: -1 }));
+    child.on("close", (code: number | null) => resolve({ ok: code === 0, stdout: stdout.trim(), stderr: stderr.trim(), code: code ?? -1 }));
+  });
+
+  return {
+    run,
+    async currentBranch() { return (await run(["branch", "--show-current"])).stdout; },
+    async isDirty() { return (await run(["status", "--porcelain"])).stdout.trim() !== ""; },
+    async branchExists(branch: string, remote = false) { return (await run(remote ? ["ls-remote", "--exit-code", "--heads", "origin", branch] : ["rev-parse", "--verify", branch])).ok; },
+    createBranch(branch: string, base?: string) { return run(base ? ["switch", "-c", branch, base] : ["switch", "-c", branch]); },
+    switchBranch(branch: string) { return run(["switch", branch]); },
+    revParse(ref: string) { return run(["rev-parse", "--verify", ref]); },
+    async hasRemote(name = "origin") { return (await run(["remote", "get-url", name])).ok; },
+  };
+}

package/extensions/pr-body.ts

@@ -1,6 +1,7 @@
 export interface ArtifactTexts {
   proposal?: string;
   spec?: string;
+  specs?: Record<string, string>;
   design?: string;
   tasks?: string;
   proposalMd?: string;
@@ -10,6 +11,8 @@ export interface ArtifactTexts {
   linkedIssueNumber?: number;
 }
 
+export interface PrBodyInput { slug?: string; links?: { issueNumber?: number; branch?: string; baseBranch?: string; prUrl?: string }; artifacts: ArtifactTexts }
+
 export interface BuiltBody { title: string; body: string }
 
 function normalize(text: string | undefined): string {
@@ -54,18 +57,19 @@ export function extractSectionByHeading(markdown: string | undefined, heading: s
 export function extractTasksTable(tasks: string | undefined): string {
   const text = normalize(tasks);
   if (text === "") return "";
-  const taskMatches = [...text.matchAll(/^##\s+\[[ xX]\]\s+(T\d+\s+[^\n]*)/gm)];
+  const taskMatches = [...text.matchAll(/^(?:##\s+\[[ xX]\]\s+|###\s+)(T\d+[^\n]*)/gm)];
   if (taskMatches.length === 0) return "";
-  const rows = ["| Task | Files |", "| --- | --- |"];
+  const rows = ["| Task | Files | Evidence |", "| --- | --- | --- |"];
   for (const match of taskMatches) {
     const title = match[1].trim();
     const start = match.index ?? 0;
-    const next = text.slice(start + match[0].length).search(/^##\s+/m);
+    const next = text.slice(start + match[0].length).search(/^#{2,3}\s+/m);
     const block = next === -1 ? text.slice(start) : text.slice(start, start + match[0].length + next);
     if (!/^\s*-\s+files:\s*$/m.test(block)) continue;
     const files = [...block.matchAll(/^\s+-\s+`([^`]+)`/gm)].map((m) => m[1]);
+    const evidence = (/^\s*-\s+evidence:\s*(.+)$/m.exec(block)?.[1] ?? "").trim();
     if (files.length === 0) continue;
-    rows.push(`| ${title} | ${files.join("<br>")} |`);
+    rows.push(`| ${title} | ${files.join("<br>")} | ${evidence || "—"} |`);
   }
   return rows.length > 2 ? rows.join("\n") : "";
 }
@@ -99,22 +103,41 @@ function issueSections(input: ArtifactTexts): string[] {
   return sections;
 }
 
-export function buildPrBody(input: ArtifactTexts, links: { issueNumber?: number } = {}): BuiltBody {
+export function buildPrBody(inputOrWrapped: ArtifactTexts | PrBodyInput, linksArg: { issueNumber?: number; branch?: string; baseBranch?: string } = {}): BuiltBody {
+  const wrapped = "artifacts" in inputOrWrapped ? inputOrWrapped as PrBodyInput : null;
+  const input = wrapped?.artifacts ?? inputOrWrapped as ArtifactTexts;
+  const links = { ...linksArg, ...(wrapped?.links ?? {}) };
   const issueNumber = input.linkedIssueNumber ?? links.issueNumber;
   const linkedIssue = issueNumber ? `Closes #${issueNumber}` : "Closes #\n<!-- Reemplazá # por el número de issue si existe. -->";
+  const specText = input.specs ? Object.entries(input.specs).map(([domain, spec]) => `### ${domain}\n\n${spec}`).join("\n\n") : specOf(input);
   const body = [
     "## 🔗 Linked Issue",
     linkedIssue,
     "",
+    "## SDD artifacts",
+    `- Slug: ${wrapped?.slug ?? "n/a"}`,
+    `- Branch: ${links.branch ?? "n/a"}`,
+    `- Base branch: ${links.baseBranch ?? "n/a"}`,
+    "- Artifacts: proposal.md, spec.md/specs/*/spec.md, design.md, tasks.md, veredicto.md",
+    "",
+    "## Requirements",
+    placeholder(extractAcceptanceCriteria(specText)),
+    "",
     "## 📝 Summary",
     placeholder(extractFirstParagraph(proposalOf(input))),
     "",
     "## 📂 Changes",
     placeholder(extractTasksTable(tasksOf(input))),
     "",
-    "## 🧪 Test Plan",
+    "## 🧪 Test evidence",
     placeholder(input.verdictReasoning ?? ""),
     "",
+    "## Risks",
+    placeholder(extractSectionByHeading(proposalOf(input), "Riesgos") || extractSectionByHeading(input.design, "Riesgos")),
+    "",
+    "## Verdict",
+    placeholder(input.verdictReasoning ?? "Sin veredicto registrado."),
+    "",
     "## ✅ Checklist",
     "- [ ] Revisé el diff local",
     "- [ ] Corrí los tests relevantes",

package/extensions/sdd-config.ts

@@ -0,0 +1,38 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+export interface SddConfig {
+  git: {
+    branchPrefix: string;
+    numbering: boolean;
+    autoCommit: boolean;
+    commitStyle: "conventional" | "plain";
+    baseBranch: string;
+  };
+}
+
+export const DEFAULT_SDD_CONFIG: SddConfig = {
+  git: { branchPrefix: "sdd/", numbering: false, autoCommit: false, commitStyle: "conventional", baseBranch: "main" },
+};
+
+function asObject(value: unknown): Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value) ? value as Record<string, unknown> : {};
+}
+
+export function loadSddConfig(root = process.cwd()): SddConfig {
+  const path = join(root, ".sdd", "config.json");
+  if (!existsSync(path)) return structuredClone(DEFAULT_SDD_CONFIG);
+  let parsed: Record<string, unknown>;
+  try { parsed = asObject(JSON.parse(readFileSync(path, "utf8"))); }
+  catch (err) { throw new Error(`invalid .sdd/config.json: ${err instanceof Error ? err.message : String(err)}`); }
+  const git = asObject(parsed.git);
+  return {
+    git: {
+      branchPrefix: typeof git.branchPrefix === "string" ? git.branchPrefix : DEFAULT_SDD_CONFIG.git.branchPrefix,
+      numbering: typeof git.numbering === "boolean" ? git.numbering : DEFAULT_SDD_CONFIG.git.numbering,
+      autoCommit: typeof git.autoCommit === "boolean" ? git.autoCommit : DEFAULT_SDD_CONFIG.git.autoCommit,
+      commitStyle: git.commitStyle === "plain" ? "plain" : DEFAULT_SDD_CONFIG.git.commitStyle,
+      baseBranch: typeof git.baseBranch === "string" ? git.baseBranch : DEFAULT_SDD_CONFIG.git.baseBranch,
+    },
+  };
+}

package/extensions/sdd-links.ts

@@ -1,23 +1,29 @@
 import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 
-export interface LinksRecord {
+export interface SddLinks {
   prNumber?: number;
   prUrl?: string;
   issueNumber?: number;
   issueUrl?: string;
+  branch?: string;
+  baseBranch?: string;
+  archivePath?: string;
+  createdAt?: string;
   [key: string]: unknown;
 }
 
+export type LinksRecord = SddLinks;
+
 function linksPath(sddDir: string, slug: string): string {
   return join(sddDir, slug, "links.json");
 }
 
-function validRecord(value: unknown): LinksRecord {
-  return typeof value === "object" && value !== null && !Array.isArray(value) ? value as LinksRecord : {};
+function validRecord(value: unknown): SddLinks {
+  return typeof value === "object" && value !== null && !Array.isArray(value) ? value as SddLinks : {};
 }
 
-export function readLinks(sddDir: string, slug: string): LinksRecord {
+export function readLinks(sddDir: string, slug: string): SddLinks {
   const path = linksPath(sddDir, slug);
   if (!existsSync(path)) return {};
   try {
@@ -27,9 +33,13 @@ export function readLinks(sddDir: string, slug: string): LinksRecord {
   }
 }
 
-export function writeLinks(sddDir: string, slug: string, partial: LinksRecord): LinksRecord {
+export function mergeLinks(current: SddLinks, partial: SddLinks): SddLinks {
+  return { ...validRecord(current), ...validRecord(partial) };
+}
+
+export function writeLinks(sddDir: string, slug: string, partial: SddLinks): SddLinks {
   const path = linksPath(sddDir, slug);
-  const next = { ...readLinks(sddDir, slug), ...partial };
+  const next = mergeLinks(readLinks(sddDir, slug), partial);
   mkdirSync(dirname(path), { recursive: true });
   const tmp = `${path}.${process.pid}.${Date.now()}.tmp`;
   writeFileSync(tmp, `${JSON.stringify(next, null, 2)}\n`, "utf8");

package/extensions/spec-merge.ts

@@ -97,6 +97,15 @@ export function parseStore(text: string): RequirementBlock[] {
   return parseBlocks(text.split(/\r?\n/));
 }
 
+export function loadCanonical(text: string | undefined | null): { blocks: RequirementBlock[]; errors: MergeError[] } {
+  const source = text ?? "";
+  const blocks = parseStore(source);
+  const errors = blocks.some((b) => b.name === "")
+    ? [{ kind: "parse-error" as const, name: "", message: "malformed canonical store: empty REQ name" }]
+    : [];
+  return { blocks, errors };
+}
+
 export function parseDelta(text: string): SpecDelta {
   const delta: SpecDelta = { added: [], modified: [], removed: [], renamed: [] };
   if (typeof text !== "string") return delta;
@@ -220,6 +229,10 @@ export function checkGuardrails(
   return errors;
 }
 
+export function serializeCanonical(blocks: readonly RequirementBlock[], title: string = STORE_TITLE): string {
+  return renderStore([...blocks].sort((a, b) => a.name.localeCompare(b.name)), title);
+}
+
 export function renderStore(blocks: readonly RequirementBlock[], title: string = STORE_TITLE): string {
   const parts: string[] = [`# ${title}`];
   for (const block of blocks) {
@@ -229,9 +242,9 @@ export function renderStore(blocks: readonly RequirementBlock[], title: string =
   return `${parts.join("\n\n")}\n`;
 }
 
-export function mergeDelta(storeText: string, deltaText: string): MergeResult {
-  const store = parseStore(storeText);
-  const delta = parseDelta(deltaText);
+export function mergeDelta(storeTextOrBlocks: string | readonly RequirementBlock[], deltaTextOrDelta: string | SpecDelta): MergeResult {
+  const store = typeof storeTextOrBlocks === "string" ? parseStore(storeTextOrBlocks) : [...storeTextOrBlocks];
+  const delta = typeof deltaTextOrDelta === "string" ? parseDelta(deltaTextOrDelta) : deltaTextOrDelta;
   const errors = checkGuardrails(store, delta);
   if (errors.length > 0) return { ok: false, errors };
 

package/extensions/zero-archive-extension.ts

@@ -0,0 +1,44 @@
+import { spawn } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+
+import { readRunRecords } from "./autotune.ts";
+import { createGitRunner, type GitRunner, type SpawnLike } from "./git-runner.ts";
+import { mergeDelta } from "./spec-merge.ts";
+import { writeLinks } from "./sdd-links.ts";
+import { validateSpecInputs, validateTasksFile } from "./zero-validate.ts";
+
+const SDD_DIR = ".sdd";
+type NotifyType = "info" | "warning" | "error";
+interface PiCommandContext { ui: { notify(message: string, type?: NotifyType): void } }
+interface PiExtensionAPI { registerCommand(name: string, options: { description?: string; handler: (args: string, ctx: PiCommandContext) => void | Promise<void> }): void }
+
+function parse(args: string): { slug: string; dryRun: boolean; json: boolean; allowDirty: boolean } { const out = { slug: "", dryRun: false, json: false, allowDirty: false }; for (const p of args.trim().split(/\s+/).filter(Boolean)) { if (p === "--dry-run") out.dryRun = true; else if (p === "--json") out.json = true; else if (p === "--allow-dirty") out.allowDirty = true; else if (!out.slug) out.slug = p; } return out; }
+function notify(ctx: PiCommandContext, message: string, type?: NotifyType) { try { ctx.ui.notify(message, type); } catch {} }
+function latestVerdict(slug: string): string | null { const path = process.env.ZERO_RUNS_PATH || join(homedir(), ".pi", "zero-runs.jsonl"); let latest: { ts: string; verdict: string } | null = null; for (const r of readRunRecords(path)) if (r.feature === slug && (!latest || r.ts > latest.ts)) latest = { ts: r.ts, verdict: r.verdict }; return latest?.verdict ?? null; }
+function today(): string { return new Date().toISOString().slice(0, 10); }
+function read(path: string): string { try { return readFileSync(path, "utf8"); } catch { return ""; } }
+function atomicWrite(path: string, content: string): void { mkdirSync(dirname(path), { recursive: true }); const tmp = `${path}.${process.pid}.${Date.now()}.tmp`; writeFileSync(tmp, content, "utf8"); renameSync(tmp, path); }
+function specPairs(runDir: string): Array<{ domain: string; deltaPath: string; canonicalPath: string }> { const out: Array<{ domain: string; deltaPath: string; canonicalPath: string }> = []; if (existsSync(join(runDir, "spec.md"))) out.push({ domain: "default", deltaPath: join(runDir, "spec.md"), canonicalPath: join(SDD_DIR, "specs", "requirements.md") }); try { const base = join(runDir, "specs"); for (const e of readdirSync(base, { withFileTypes: true })) if (e.isDirectory() && existsSync(join(base, e.name, "spec.md"))) out.push({ domain: e.name, deltaPath: join(base, e.name, "spec.md"), canonicalPath: join(SDD_DIR, "specs", e.name, "requirements.md") }); } catch {} return out; }
+
+export async function runZeroArchive(args: string, ctx: PiCommandContext, git: GitRunner = createGitRunner(spawn as unknown as SpawnLike)): Promise<void> {
+  const opts = parse(args);
+  if (!opts.slug) { notify(ctx, "zero-archive: usage /zero-archive <slug> [--dry-run] [--json] [--allow-dirty]", "warning"); return; }
+  const runDir = join(SDD_DIR, opts.slug);
+  const emit = (payload: unknown, text: string, type: NotifyType = "info") => notify(ctx, opts.json ? JSON.stringify(payload) : text, type);
+  if (!existsSync(runDir)) { emit({ ok: false, reason: "missing-run" }, `zero-archive: no existe ${runDir}`, "error"); return; }
+  const verdict = latestVerdict(opts.slug); if (verdict !== "pasa") { emit({ ok: false, reason: "verdict", verdict }, `zero-archive: ${opts.slug} no tiene veredicto pasa (último: ${verdict ?? "—"})`, "error"); return; }
+  if (!opts.allowDirty && await git.isDirty()) { emit({ ok: false, reason: "dirty-worktree" }, "zero-archive: worktree sucio; usá --allow-dirty si corresponde", "error"); return; }
+  const defects = [...validateSpecInputs(runDir), ...validateTasksFile(read(join(runDir, "tasks.md")))]; if (defects.length) { emit({ ok: false, reason: "validate", defects }, `zero-archive: validación falló\n${defects.map((d) => `  - [${d.kind}] ${d.message}`).join("\n")}`, "error"); return; }
+  const pairs = specPairs(runDir); if (!pairs.length) { emit({ ok: false, reason: "missing-spec" }, "zero-archive: no hay spec.md para archivar", "error"); return; }
+  const writes: Array<{ path: string; next: string; before: string | null }> = [];
+  for (const pair of pairs) { const before = existsSync(pair.canonicalPath) ? read(pair.canonicalPath) : ""; const merged = mergeDelta(before, read(pair.deltaPath)); if (!merged.ok) { emit({ ok: false, reason: "merge", errors: merged.errors }, `zero-archive: merge falló en ${pair.domain}: ${merged.errors.map((e) => e.message).join("; ")}`, "error"); return; } writes.push({ path: pair.canonicalPath, next: merged.store, before: existsSync(pair.canonicalPath) ? before : null }); }
+  const archivePath = join(SDD_DIR, "archive", `${today()}-${opts.slug}`);
+  if (opts.dryRun) { emit({ ok: true, dryRun: true, archivePath, writes: writes.map((w) => w.path) }, `zero-archive: dry-run archivaría ${opts.slug} en ${archivePath}`); return; }
+  const written: typeof writes = [];
+  try { for (const w of writes) { atomicWrite(w.path, w.next); written.push(w); } writeLinks(SDD_DIR, opts.slug, { archivePath }); mkdirSync(dirname(archivePath), { recursive: true }); renameSync(runDir, archivePath); emit({ ok: true, archivePath, writes: writes.map((w) => w.path) }, `zero-archive: archivado en ${archivePath}`); }
+  catch (err) { for (const w of written.reverse()) { if (w.before === null) rmSync(w.path, { force: true }); else atomicWrite(w.path, w.before); } emit({ ok: false, reason: "rollback", error: err instanceof Error ? err.message : String(err) }, `zero-archive: falló y revertí cambios canónicos: ${err instanceof Error ? err.message : String(err)}`, "error"); }
+}
+
+export default function register(pi?: PiExtensionAPI): void { if (!pi || typeof pi.registerCommand !== "function") return; pi.registerCommand("zero-archive", { description: "Mergea el delta aprobado a .sdd/specs y mueve el run a .sdd/archive", handler: (args, ctx) => runZeroArchive(args, ctx).catch((err) => notify(ctx, `zero-archive: ${err instanceof Error ? err.message : String(err)}`, "error")) }); }

package/extensions/zero-branch-extension.ts

@@ -0,0 +1,64 @@
+import { spawn } from "node:child_process";
+
+import { createGitRunner, type GitRunner, type SpawnLike } from "./git-runner.ts";
+import { loadSddConfig } from "./sdd-config.ts";
+import { writeLinks } from "./sdd-links.ts";
+
+const SDD_DIR = ".sdd";
+type NotifyType = "info" | "warning" | "error";
+interface PiCommandContext { ui: { notify(message: string, type?: NotifyType): void } }
+interface PiExtensionAPI { registerCommand(name: string, options: { description?: string; handler: (args: string, ctx: PiCommandContext) => void | Promise<void> }): void }
+
+export interface BranchOptions { slug: string; dryRun: boolean; json: boolean; allowDirty: boolean; base?: string }
+
+export function sanitizeSlug(slug: string): string {
+  return slug.trim().toLowerCase().replace(/[^a-z0-9._-]+/g, "-").replace(/^-+|-+$/g, "").replace(/-{2,}/g, "-") || "feature";
+}
+
+export function parseBranchArgs(args: string): BranchOptions {
+  const parts = args.trim().split(/\s+/).filter(Boolean);
+  const out: BranchOptions = { slug: "", dryRun: false, json: false, allowDirty: false };
+  for (const p of parts) {
+    if (p === "--dry-run") out.dryRun = true;
+    else if (p === "--json") out.json = true;
+    else if (p === "--allow-dirty") out.allowDirty = true;
+    else if (p.startsWith("--base=")) out.base = p.slice(7);
+    else if (!out.slug) out.slug = p;
+  }
+  return out;
+}
+
+function notify(ctx: PiCommandContext, message: string, type?: NotifyType) { try { ctx.ui.notify(message, type); } catch {} }
+function emit(ctx: PiCommandContext, opts: BranchOptions, payload: unknown, text: string, type: NotifyType = "info") { notify(ctx, opts.json ? JSON.stringify(payload) : text, type); }
+
+export async function runZeroBranch(args: string, ctx: PiCommandContext, runner?: GitRunner): Promise<void> {
+  const opts = parseBranchArgs(args);
+  if (!opts.slug) { notify(ctx, "zero-branch: usage /zero-branch <slug> [--dry-run] [--json] [--allow-dirty] [--base=<branch>]", "warning"); return; }
+  const config = loadSddConfig(process.cwd());
+  const branch = `${config.git.branchPrefix}${sanitizeSlug(opts.slug)}`;
+  const base = opts.base ?? config.git.baseBranch;
+  const git = runner ?? createGitRunner(spawn as unknown as SpawnLike);
+  if (!opts.allowDirty && await git.isDirty()) { emit(ctx, opts, { ok: false, branch, reason: "dirty-worktree" }, `zero-branch: worktree sucio; usá --allow-dirty si querés continuar`, "error"); return; }
+  if (opts.dryRun) { emit(ctx, opts, { ok: true, dryRun: true, branch, baseBranch: base }, `zero-branch: dry-run crearía/cambiaría a ${branch} desde ${base}`); return; }
+
+  let action = "create";
+  if (await git.branchExists(branch)) {
+    action = "reuse-local";
+    const switched = await git.switchBranch(branch);
+    if (!switched.ok) { emit(ctx, opts, { ok: false, branch, action, stderr: switched.stderr }, `zero-branch: no pude cambiar a ${branch}: ${switched.stderr}`, "error"); return; }
+  } else if (await git.branchExists(branch, true)) {
+    action = "track-remote";
+    const switched = await git.run(["switch", "--track", `origin/${branch}`]);
+    if (!switched.ok) { emit(ctx, opts, { ok: false, branch, action, stderr: switched.stderr }, `zero-branch: no pude trackear origin/${branch}: ${switched.stderr}`, "error"); return; }
+  } else {
+    const created = await git.createBranch(branch, base);
+    if (!created.ok) { emit(ctx, opts, { ok: false, branch, action, stderr: created.stderr }, `zero-branch: no pude crear ${branch}: ${created.stderr}`, "error"); return; }
+  }
+  writeLinks(SDD_DIR, opts.slug, { branch, baseBranch: base });
+  emit(ctx, opts, { ok: true, branch, baseBranch: base, action }, `zero-branch: ${action} ${branch} (base ${base})`);
+}
+
+export default function register(pi?: PiExtensionAPI): void {
+  if (!pi || typeof pi.registerCommand !== "function") return;
+  pi.registerCommand("zero-branch", { description: "Crea o cambia a la rama Git sdd/<slug> y la registra en links.json", handler: (args, ctx) => runZeroBranch(args, ctx).catch((err) => notify(ctx, `zero-branch: ${err instanceof Error ? err.message : String(err)}`, "error")) });
+}

package/extensions/zero-git-validate-extension.ts

@@ -0,0 +1,56 @@
+import { spawn } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+import { readRunRecords } from "./autotune.ts";
+import { createGhRunner, type SpawnLike as GhSpawnLike } from "./gh-runner.ts";
+import { createGitRunner, type GitRunner, type SpawnLike } from "./git-runner.ts";
+import { readLinks } from "./sdd-links.ts";
+
+const SDD_DIR = ".sdd";
+type NotifyType = "info" | "warning" | "error";
+interface PiCommandContext { ui: { notify(message: string, type?: NotifyType): void } }
+interface PiExtensionAPI { registerCommand(name: string, options: { description?: string; handler: (args: string, ctx: PiCommandContext) => void | Promise<void> }): void }
+export interface GitCheck { name: string; ok: boolean; message: string }
+
+function parse(args: string): { slug: string; forMode: "pr" | "archive" | "any"; json: boolean } {
+  const out = { slug: "", forMode: "any" as "pr" | "archive" | "any", json: false };
+  for (const p of args.trim().split(/\s+/).filter(Boolean)) {
+    if (p === "--json") out.json = true;
+    else if (p.startsWith("--for=")) out.forMode = ["pr", "archive", "any"].includes(p.slice(6)) ? p.slice(6) as any : "any";
+    else if (!out.slug) out.slug = p;
+  }
+  return out;
+}
+function latestVerdict(slug: string): string | null {
+  const path = process.env.ZERO_RUNS_PATH || join(homedir(), ".pi", "zero-runs.jsonl");
+  let latest: { ts: string; verdict: string } | null = null;
+  for (const r of readRunRecords(path)) if (r.feature === slug && (!latest || r.ts > latest.ts)) latest = { ts: r.ts, verdict: r.verdict };
+  return latest?.verdict ?? null;
+}
+async function ghAvailable(spawnImpl: GhSpawnLike): Promise<boolean> { return Boolean((await createGhRunner({ spawn: spawnImpl }).detect()).data?.available); }
+export async function validateGitState(slug: string, forMode: "pr" | "archive" | "any", git: GitRunner, ghSpawn: GhSpawnLike = spawn as unknown as GhSpawnLike): Promise<{ ok: boolean; checks: GitCheck[] }> {
+  const links = readLinks(SDD_DIR, slug);
+  const expectedBranch = typeof links.branch === "string" ? links.branch : null;
+  const checks: GitCheck[] = [];
+  const dirty = await git.isDirty(); checks.push({ name: "worktree", ok: !dirty, message: dirty ? "worktree has uncommitted changes" : "worktree clean" });
+  const current = await git.currentBranch(); checks.push({ name: "branch", ok: !expectedBranch || current === expectedBranch, message: expectedBranch ? `current ${current || "(detached)"}, expected ${expectedBranch}` : `current ${current || "(detached)"}` });
+  checks.push({ name: "remote", ok: await git.hasRemote("origin"), message: "origin remote configured" });
+  if (forMode === "pr") checks.push({ name: "gh-auth", ok: await ghAvailable(ghSpawn), message: "gh CLI available/authenticated" });
+  if (forMode === "pr" || forMode === "archive") { const verdict = latestVerdict(slug); checks.push({ name: "verdict", ok: verdict === "pasa", message: `latest verdict ${verdict ?? "—"}` }); }
+  return { ok: checks.every((c) => c.ok), checks };
+}
+export async function runZeroGitValidate(args: string, ctx: PiCommandContext, git: GitRunner = createGitRunner(spawn as unknown as SpawnLike), ghSpawn: GhSpawnLike = spawn as unknown as GhSpawnLike): Promise<void> {
+  const opts = parse(args);
+  const notify = (m: string, t?: NotifyType) => { try { ctx.ui.notify(m, t); } catch {} };
+  if (!opts.slug) { notify("zero-git-validate: usage /zero-git-validate <slug> [--for=pr|archive|any] [--json]", "warning"); return; }
+  if (!existsSync(join(SDD_DIR, opts.slug))) { notify(`zero-git-validate: no existe .sdd/${opts.slug}`, "error"); return; }
+  const result = await validateGitState(opts.slug, opts.forMode, git, ghSpawn);
+  const text = result.checks.map((c) => `${c.ok ? "✅" : "❌"} ${c.name}: ${c.message}`).join("\n");
+  notify(opts.json ? JSON.stringify(result) : `zero-git-validate: ${result.ok ? "ok" : "falló"}\n${text}`, result.ok ? "info" : "error");
+}
+export default function register(pi?: PiExtensionAPI): void {
+  if (!pi || typeof pi.registerCommand !== "function") return;
+  pi.registerCommand("zero-git-validate", { description: "Valida worktree, rama, remote, gh auth y veredicto antes de PR/archive", handler: (args, ctx) => runZeroGitValidate(args, ctx).catch((err) => { try { ctx.ui.notify(`zero-git-validate: ${err instanceof Error ? err.message : String(err)}`, "error"); } catch {} }) });
+}

package/extensions/zero-pr-extension.ts

@@ -7,6 +7,7 @@ import { readRunRecords } from "./autotune.ts";
 import { buildPrBody } from "./pr-body.ts";
 import { createGhRunner, type SpawnLike } from "./gh-runner.ts";
 import { readLinks, writeLinks } from "./sdd-links.ts";
+import { validateArtifactSet, validateSpecInputs, validateTasksFile } from "./zero-validate.ts";
 
 const SDD_DIR = ".sdd";
 type NotifyType = "info" | "warning" | "error";
@@ -45,6 +46,18 @@ function writeTempBody(body: string): string {
   return file;
 }
 function skippedNote(skipped: string[]): string { return skipped.length ? `; skipié labels que no existen en este repo: ${skipped.join(", ")}` : ""; }
+function readSpecArtifacts(dir: string): { specMd: string; specs?: Record<string, string> } {
+  const flat = readFileOrEmpty(join(dir, "spec.md"));
+  const specsDir = join(dir, "specs");
+  const specs: Record<string, string> = {};
+  try {
+    for (const e of readdirSync(specsDir, { withFileTypes: true })) if (e.isDirectory()) {
+      const text = readFileOrEmpty(join(specsDir, e.name, "spec.md"));
+      if (text) specs[e.name] = text;
+    }
+  } catch {}
+  return Object.keys(specs).length ? { specMd: flat, specs } : { specMd: flat };
+}
 
 export async function runZeroPr(args: string, ctx: PiCommandContext, spawnImpl: SpawnLike = spawn as unknown as SpawnLike): Promise<void> {
   const notify = (m: string, t?: NotifyType) => { try { ctx.ui.notify(m, t); } catch {} };
@@ -54,18 +67,25 @@ export async function runZeroPr(args: string, ctx: PiCommandContext, spawnImpl:
   const verdict = latestVerdict(slug);
   if (verdict?.verdict !== "pasa") { notify(`zero-pr: ${slug} no tiene veredicto pasa (último: ${verdict?.verdict ?? "—"})`, "warning"); return; }
   const dir = join(SDD_DIR, slug);
-  const artifacts = { proposalMd: readFileOrEmpty(join(dir, "proposal.md")), specMd: readFileOrEmpty(join(dir, "spec.md")), tasksMd: readFileOrEmpty(join(dir, "tasks.md")), verdictReasoning: verdict.reasoning };
+  const artifacts = { proposalMd: readFileOrEmpty(join(dir, "proposal.md")), ...readSpecArtifacts(dir), tasksMd: readFileOrEmpty(join(dir, "tasks.md")), verdictReasoning: verdict.reasoning };
+  const defects = [
+    ...validateArtifactSet({ proposal: artifacts.proposalMd !== "", spec: artifacts.specMd !== "" || Boolean(artifacts.specs), design: existsSync(join(dir, "design.md")), tasks: artifacts.tasksMd !== "" }),
+    ...validateSpecInputs(dir),
+    ...validateTasksFile(artifacts.tasksMd),
+  ].filter((d) => !d.kind.startsWith("missing-proposal"));
+  if (defects.length > 0) { notify(`zero-pr: validateForPr falló:\n${defects.map((d) => `  - [${d.kind}] ${d.message}`).join("\n")}`, "error"); return; }
   const links = readLinks(SDD_DIR, slug);
   const gh = createGhRunner({ spawn: spawnImpl });
   const detected = await gh.detect();
   if (!detected.data?.available) { notify(`zero-pr: ${detected.data?.hint ?? "gh CLI no disponible"}`, "error"); return; }
   const { applied, skipped } = await labelIfExists(gh, labels);
-  const built = buildPrBody({ ...artifacts, linkedIssueNumber: typeof links.issueNumber === "number" ? links.issueNumber : undefined });
+  const built = buildPrBody({ slug, links, artifacts: { ...artifacts, linkedIssueNumber: typeof links.issueNumber === "number" ? links.issueNumber : undefined } });
   const tmp = writeTempBody(built.body);
   try {
-    const result = await gh.createPr({ title: built.title, bodyFile: tmp, labels: applied });
+    const result = await gh.createPr({ title: built.title, bodyFile: tmp, labels: applied, base: typeof links.baseBranch === "string" ? links.baseBranch : undefined, head: typeof links.branch === "string" ? links.branch : undefined } as any);
     if (!result.ok) { notify(`zero-pr: gh pr create falló${result.stderr ? ` — ${result.stderr}` : ""}`, "error"); return; }
-    writeLinks(SDD_DIR, slug, { prNumber: result.data?.number, prUrl: result.data?.url, createdAt: new Date().toISOString() });
+    const parsedNumber = result.data?.number ?? (result.data?.url ? Number(/\/(?:pull|pulls)\/(\d+)(?:$|[?#])/.exec(result.data.url)?.[1]) : undefined);
+    writeLinks(SDD_DIR, slug, { prNumber: Number.isFinite(parsedNumber) ? parsedNumber : undefined, prUrl: result.data?.url, createdAt: new Date().toISOString() });
     notify(`zero-pr: PR creado${result.data?.number ? ` #${result.data.number}` : ""}${result.data?.url ? ` ${result.data.url}` : ""}${skippedNote(skipped)}`, "info");
   } finally {
     if (existsSync(tmp)) rmSync(tmp, { force: true });

package/extensions/zero-validate-extension.ts

@@ -1,7 +1,7 @@
 import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 
-import { validateArtifactSet, validateSpecDelta, validateTasksFile, type ValidationDefect } from "./zero-validate.ts";
+import { validateArtifactSet, validateSpecInputs, validateTasksFile, type ValidationDefect } from "./zero-validate.ts";
 
 const SDD_DIR = ".sdd";
 const ARTIFACTS = ["proposal", "spec", "design", "tasks"] as const;
@@ -38,12 +38,14 @@ function runValidate(args: string, ctx: PiCommandContext): void {
   }
   const dir = join(SDD_DIR, slug);
   const texts = Object.fromEntries(ARTIFACTS.map((a) => [a, readFileOrNull(join(dir, `${a}.md`))])) as Record<(typeof ARTIFACTS)[number], string | null>;
-  const presence = Object.fromEntries(ARTIFACTS.map((a) => [a, texts[a] !== null])) as Record<(typeof ARTIFACTS)[number], boolean>;
+  const hasDomainSpec = existsSync(join(dir, "specs"));
+  const presence = Object.fromEntries(ARTIFACTS.map((a) => [a, a === "spec" ? texts.spec !== null || hasDomainSpec : texts[a] !== null])) as Record<(typeof ARTIFACTS)[number], boolean>;
   const defects = validateArtifactSet(presence);
-  if (texts.spec !== null) defects.push(...validateSpecDelta(texts.spec));
+  defects.push(...validateSpecInputs(dir));
   if (texts.tasks !== null) defects.push(...validateTasksFile(texts.tasks));
+  for (const legacy of ["requirements.md"]) if (existsSync(join(dir, legacy))) defects.push({ kind: "legacy-artifact", path: legacy, message: `${legacy} is a legacy Kiro artifact; keep it only as historical context` });
 
-  const structural = defects.filter((d) => !d.kind.startsWith("missing-proposal"));
+  const structural = defects.filter((d) => !d.kind.startsWith("missing-proposal") && d.kind !== "legacy-artifact");
   if (structural.length > 0) {
     notify(`zero-validate: encontré defectos estructurales en ${slug}; revisalos antes de sync:\n${formatDefects(defects)}`, "error");
   } else if (defects.length > 0) {

package/extensions/zero-validate.ts

@@ -1,3 +1,6 @@
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
 import { checkGuardrails, parseDelta, type MergeError, type RenameBlock, type RequirementBlock } from "./spec-merge.ts";
 
 export interface ValidationDefect {
@@ -14,6 +17,7 @@ export interface TaskRecord {
   id: string;
   title: string;
   files: { path: string; isNew: boolean }[];
+  evidence: string | null;
   review: number | null;
   reviewRaw: string | null;
 }
@@ -37,9 +41,9 @@ export function parseTasks(text: string): { tasks: TaskRecord[]; workload: Workl
   };
 
   for (const line of lines) {
-    const task = line.match(/^\s*- \[[ xX]\]\s+\*\*(T\d+)\.\s+([^*]+)\*\*/);
+    const task = line.match(/^\s*- \[[ xX]\]\s+\*\*(T\d+)\.\s+([^*]+)\*\*/) ?? line.match(/^###\s+(T\d+)\s+[—-]\s+(.+)$/) ?? line.match(/^##\s+\[[ xX]\]\s+(T\d+)\s*(?:[—-]\s*(.+))?$/);
     if (task) {
-      current = { id: task[1], title: task[2].trim(), files: [], review: null, reviewRaw: null };
+      current = { id: task[1], title: (task[2] ?? "").trim(), files: [], evidence: null, review: null, reviewRaw: null };
       tasks.push(current);
       collectingFiles = false;
       continue;
@@ -50,6 +54,11 @@ export function parseTasks(text: string): { tasks: TaskRecord[]; workload: Workl
       pushFile(line);
       continue;
     }
+    if (/^\s*-\s+evidence:/.test(line)) {
+      collectingFiles = false;
+      current.evidence = line.replace(/^\s*-\s+evidence:\s*/, "").trim();
+      continue;
+    }
     if (/^\s*-\s+review:/.test(line)) {
       collectingFiles = false;
       const raw = line.replace(/^\s*-\s+review:\s*/, "").trim();
@@ -59,13 +68,14 @@ export function parseTasks(text: string): { tasks: TaskRecord[]; workload: Workl
       continue;
     }
     if (collectingFiles) {
-      if (/^\s*`[^`]+`/.test(line) || /^\s+`[^`]+`/.test(line)) pushFile(line);
+      if (/^\s*`[^`]+`/.test(line) || /^\s+`[^`]+`/.test(line) || /^\s*-\s+`[^`]+`/.test(line)) pushFile(line);
       else if (/^\s*-\s+/.test(line)) collectingFiles = false;
     }
   }
 
   for (const task of tasks) {
     if (task.files.length === 0) defects.push({ kind: "missing-files", task: task.id, message: `${task.id} is missing files list` });
+    if (task.evidence === null || task.evidence === "") defects.push({ kind: "missing-evidence", task: task.id, message: `${task.id} is missing evidence` });
     if (task.reviewRaw === null) defects.push({ kind: "missing-review", task: task.id, message: `${task.id} is missing review estimate` });
     else if (task.review === null) defects.push({ kind: "non-integer-review", task: task.id, message: `${task.id} review estimate is not an integer` });
   }
@@ -124,6 +134,25 @@ export function validateSpecDelta(text: string): ValidationDefect[] {
   return defects;
 }
 
+export function discoverSpecFiles(runDir: string): string[] {
+  const files: string[] = [];
+  if (existsSync(join(runDir, "spec.md"))) files.push(join(runDir, "spec.md"));
+  const specsDir = join(runDir, "specs");
+  try {
+    for (const e of readdirSync(specsDir, { withFileTypes: true })) if (e.isDirectory()) {
+      const file = join(specsDir, e.name, "spec.md");
+      if (existsSync(file)) files.push(file);
+    }
+  } catch {}
+  return files;
+}
+
+export function validateSpecInputs(runDir: string): ValidationDefect[] {
+  const files = discoverSpecFiles(runDir);
+  if (files.length === 0) return [{ kind: "missing-spec", path: "spec.md", message: "spec.md or specs/<domain>/spec.md is missing" }];
+  return files.flatMap((file) => validateSpecDelta(readFileSync(file, "utf8")).map((d) => ({ ...d, path: file })));
+}
+
 export function validateArtifactSet(present: { proposal: boolean; spec: boolean; design: boolean; tasks: boolean }): ValidationDefect[] {
   const defects: ValidationDefect[] = [];
   for (const key of ["proposal", "spec", "design", "tasks"] as const) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gonrocca/zero-pi",
-  "version": "0.1.49",
+  "version": "0.1.50",
   "description": "zero-pi — an installable layer for pi (pi.dev): the zero spec-driven development workflow (explore → plan → build → veredicto) with per-phase model autotune and token-efficient batched builds. Adds capability to pi without modifying pi.",
   "type": "module",
   "keywords": [
@@ -36,6 +36,9 @@
       "./extensions/zero-validate-extension.ts",
       "./extensions/zero-status-extension.ts",
       "./extensions/zero-pr-extension.ts",
+      "./extensions/zero-branch-extension.ts",
+      "./extensions/zero-git-validate-extension.ts",
+      "./extensions/zero-archive-extension.ts",
       "./extensions/zero-issue-extension.ts",
       "./extensions/zero-diff-extension.ts",
       "./extensions/provider-guard-extension.ts",
@@ -65,8 +68,13 @@
     "extensions/zero-status-extension.ts",
     "extensions/pr-body.ts",
     "extensions/sdd-links.ts",
+    "extensions/sdd-config.ts",
+    "extensions/git-runner.ts",
     "extensions/gh-runner.ts",
     "extensions/zero-pr-extension.ts",
+    "extensions/zero-branch-extension.ts",
+    "extensions/zero-git-validate-extension.ts",
+    "extensions/zero-archive-extension.ts",
     "extensions/zero-issue-extension.ts",
     "extensions/zero-diff-extension.ts",
     "extensions/provider-guard.ts",

package/prompts/orchestrator.md

@@ -177,7 +177,7 @@ A zero SDD run has two language surfaces — keep them apart.
 - **Fixed identifiers — verbatim.** Never translate identifiers. Keep verdict
   values (`pasa`, `corregir`, `replantear`, `cap-reached`), feature slugs,
   file and directory paths, model ids, and command names (`/forge`,
-  `/zero-sync`) exactly as they are, even inside Spanish text.
+  `/zero-sync`, `/zero-branch`, `/zero-git-validate`, `/zero-pr`, `/zero-archive`) exactly as they are, even inside Spanish text.
 
 ## Output Contract
 
@@ -361,6 +361,14 @@ verdict" above). If the push fails for any reason, or zero runs with `--no-mcp`
 or Cortex is down — emit a non-blocking warning and continue, never block the
 run. The local line already stands.
 
+## Git/PR/archive commands
+
+Recommended command order for an audit-ready SDD change is: `/zero-branch <slug>` → `/zero-issue <slug>` → `/forge <slug>` (plan/build/veredicto) → `/zero-git-validate <slug> --for=pr` → `/zero-pr <slug>` → `/zero-archive <slug>` after `pasa`.
+
+- `/zero-branch <slug>` creates/reuses `sdd/<slug>` (configurable) and records `branch`/`baseBranch` in `links.json`.
+- `/zero-git-validate <slug>` checks worktree, branch, remote, `gh auth`, and verdict gating without mutating.
+- `/zero-archive <slug>` merges approved deltas into `.sdd/specs/` and moves the run to `.sdd/archive/YYYY-MM-DD-<slug>/`.
+
 ## Spec sync & archive
 
 The project keeps a **canonical spec store** at `.sdd/specs/requirements.md` —
@@ -369,12 +377,13 @@ 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
+`zero-runs.jsonl` append, invoke the **`/zero-archive <slug>`** command, passing
+the run's feature slug explicitly. `/zero-archive` is a real pi command — a
 deterministic, unit-tested merge, not a prompt instruction — that reads
-`.sdd/specs/requirements.md` 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.
+`.sdd/specs/requirements.md` or per-domain `.sdd/specs/<domain>/requirements.md`
+and `.sdd/<slug>/spec.md` or `.sdd/<slug>/specs/<domain>/spec.md`, folds the
+delta into the store, writes atomically, moves the run to `.sdd/archive/`, and
+records `archivePath` in `links.json`. You only call it; you never edit the store yourself.
 
 **Never sync on a non-`pasa` outcome.** Do **not** invoke `/zero-sync` for a
 `corregir` or `replantear` verdict, or when the iteration cap was reached

package/prompts/phases/plan.md

@@ -62,6 +62,38 @@ Write all four into `.sdd/<slug>/`:
   absolute (or code-root-relative) paths it creates or edits, marking new files
   `(new)`, so the build phase edits them directly instead of rediscovering them.
 
+## Task schema
+
+Use this exact checklist shape so build/validate/review can parse it without rediscovery:
+
+```markdown
+### T001 — Implement focused capability
+
+- files:
+  - `<root>/src/example.ts`
+  - `<root>/src/example.test.ts` (new)
+- detail: concrete implementation notes and boundaries.
+- evidence: `npm test -- example` passes, or the exact manual check expected.
+- review: ~120 changed lines
+```
+
+Rules:
+- Task ids are monotonic `T###`; keep existing completed ids stable on resume.
+- Add `[P]` only for tasks that are truly parallel-safe, and `[Story:S1]`/`[Story:S2]` when the plan has independently testable stories.
+- `files:` is mandatory and uses exact paths; append `(new)` for created files.
+- `evidence:` is mandatory and names a concrete verification command or artifact.
+- Keep `## Review Workload` present and synchronized with the task list.
+
+## Constitution / Steering check
+
+Before finalizing tasks, check project steering/constitution files when present (`.sdd/constitution.md`, `.sdd/steering.md`, `.kiro/steering/*`, or project equivalents). If absent, mark `n/a`; absence is not a blocker. Include this table in `design.md` or `tasks.md`:
+
+| rule | status | waiver |
+| --- | --- | --- |
+| Steering/constitution present | n/a | No local steering file found |
+| Scope matches product/tech constraints | pass | — |
+| No forbidden dependency or workflow change | pass | — |
+
 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/prompts/phases/veredicto.md

@@ -39,6 +39,21 @@ Review the build adversarially, with a fresh perspective. Check it against the
 plan's requirements, run the tests yourself, and look for gaps, regressions,
 and unmet acceptance criteria.
 
+## Constitution / Steering gate
+
+Re-check the plan's Constitution/Steering table before choosing a verdict. If a
+present steering or constitution rule is violated and the plan did not record an
+explicit waiver, return `corregir` even if the code compiles. If steering files
+are absent, treat the row as `n/a`, not as a failure.
+
+Example gate table to cite in reasoning when relevant:
+
+| rule | status | waiver |
+| --- | --- | --- |
+| Steering/constitution present | n/a | No local steering file found |
+| Scope matches product/tech constraints | pass | — |
+| No forbidden dependency or workflow change | fail | corregir: added undeclared dependency |
+
 Record exactly one verdict:
 
 - `pasa` — the build meets the plan; the run finishes successfully.

package/skills/sdd-routing/SKILL.md

@@ -54,3 +54,12 @@ 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.
+
+## Related zero commands
+
+- `/zero-branch <slug>` — create/reuse the configured Git branch for the SDD run and persist it in `.sdd/<slug>/links.json`.
+- `/zero-git-validate <slug>` — validate worktree, branch, remote, GitHub CLI auth, and verdict gating before PR/archive.
+- `/zero-pr <slug>` — create an audit-ready GitHub PR from SDD artifacts after `veredicto` returns `pasa`.
+- `/zero-archive <slug>` — merge approved deltas into `.sdd/specs/` and move the run to `.sdd/archive/YYYY-MM-DD-<slug>/`.
+
+Recommended flow: `/zero-branch` → `/zero-issue` → `/forge` → `/zero-git-validate --for=pr` → `/zero-pr` → `/zero-archive`.