@gonrocca/zero-pi 0.1.48 → 0.1.50

package/extensions/zero-validate.ts

@@ -0,0 +1,162 @@
+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 {
+  kind: string;
+  message: string;
+  task?: string;
+  path?: string;
+  name?: string;
+  declaredTotal?: number;
+  computedTotal?: number;
+}
+
+export interface TaskRecord {
+  id: string;
+  title: string;
+  files: { path: string; isNew: boolean }[];
+  evidence: string | null;
+  review: number | null;
+  reviewRaw: string | null;
+}
+
+export interface WorkloadSection {
+  estimates: Map<string, number>;
+  declaredTotal: number | null;
+}
+
+export function parseTasks(text: string): { tasks: TaskRecord[]; workload: WorkloadSection | null; defects: ValidationDefect[] } {
+  const tasks: TaskRecord[] = [];
+  const defects: ValidationDefect[] = [];
+  const lines = typeof text === "string" ? text.split(/\r?\n/) : [];
+  let current: TaskRecord | null = null;
+  let collectingFiles = false;
+
+  const pushFile = (line: string): void => {
+    if (!current) return;
+    const matches = [...line.matchAll(/`([^`]+)`\s*(\(new\))?/g)];
+    for (const m of matches) current.files.push({ path: m[1], isNew: Boolean(m[2]) });
+  };
+
+  for (const line of lines) {
+    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: [], evidence: null, review: null, reviewRaw: null };
+      tasks.push(current);
+      collectingFiles = false;
+      continue;
+    }
+    if (!current) continue;
+    if (/^\s*-\s+files:/.test(line)) {
+      collectingFiles = true;
+      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();
+      current.reviewRaw = raw;
+      const m = raw.match(/~?(\d+)\s+changed lines/i);
+      current.review = m ? Number(m[1]) : null;
+      continue;
+    }
+    if (collectingFiles) {
+      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` });
+  }
+
+  const workload = parseWorkload(lines);
+  return { tasks, workload, defects };
+}
+
+function parseWorkload(lines: string[]): WorkloadSection | null {
+  const start = lines.findIndex((l) => /^##\s+Review Workload\s*$/.test(l));
+  if (start < 0) return null;
+  const estimates = new Map<string, number>();
+  let declaredTotal: number | null = null;
+  for (let i = start + 1; i < lines.length; i++) {
+    const line = lines[i];
+    if (/^##\s+/.test(line)) break;
+    let m = line.match(/^\|\s*(T\d+)\s*\|\s*~?(\d+)\s*\|/);
+    if (m) estimates.set(m[1], Number(m[2]));
+    m = line.match(/^\s*-\s*(T\d+)\s*[:|-]\s*~?(\d+)/);
+    if (m) estimates.set(m[1], Number(m[2]));
+    m = line.match(/\*\*Total:\s*~?(\d+)\s+changed lines\*\*/i);
+    if (m) declaredTotal = Number(m[1]);
+  }
+  return { estimates, declaredTotal };
+}
+
+export function validateTasksFile(text: string): ValidationDefect[] {
+  const parsed = parseTasks(text);
+  const defects = [...parsed.defects];
+  if (parsed.workload === null) {
+    defects.push({ kind: "missing-review-workload", message: "tasks.md is missing ## Review Workload" });
+  } else {
+    const computedTotal = parsed.tasks.reduce((sum, task) => sum + (task.review ?? 0), 0);
+    if (parsed.workload.declaredTotal === null) defects.push({ kind: "missing-workload-total", message: "Review Workload is missing total" });
+    else if (parsed.workload.declaredTotal !== computedTotal) defects.push({ kind: "total-mismatch", declaredTotal: parsed.workload.declaredTotal, computedTotal, message: `Review Workload total ${parsed.workload.declaredTotal} does not match computed ${computedTotal}` });
+    for (const task of parsed.tasks) {
+      const est = parsed.workload.estimates.get(task.id);
+      if (est !== undefined && task.review !== null && est !== task.review) defects.push({ kind: "workload-task-mismatch", task: task.id, declaredTotal: est, computedTotal: task.review, message: `${task.id} workload estimate does not match task review` });
+    }
+  }
+  return defects;
+}
+
+function allBlocks(delta: ReturnType<typeof parseDelta>): Array<RequirementBlock | RenameBlock> {
+  return [...delta.added, ...delta.modified, ...delta.removed, ...delta.renamed];
+}
+
+export function validateSpecDelta(text: string): ValidationDefect[] {
+  const delta = parseDelta(text);
+  const defects: ValidationDefect[] = checkGuardrails([], delta).map((e: MergeError) => ({ kind: e.kind, name: e.name, message: e.message }));
+  for (const block of allBlocks(delta)) {
+    const name = "name" in block ? block.name : block.to;
+    if (block.body.trim() === "") defects.push({ kind: "empty-body", name, message: `Requirement ${name} has an empty body` });
+    if (!block.body.includes("Acceptance criteria")) defects.push({ kind: "missing-acceptance-criteria", name, message: `Requirement ${name} is missing Acceptance criteria` });
+  }
+  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) {
+    if (!present[key]) defects.push({ kind: `missing-${key}`, path: `${key}.md`, message: `${key}.md is missing` });
+  }
+  return defects;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gonrocca/zero-pi",
-  "version": "0.1.48",
+  "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": [
@@ -33,7 +33,16 @@
       "./extensions/zero-models.ts",
       "./extensions/autotune-extension.ts",
       "./extensions/spec-merge-extension.ts",
-      "./extensions/provider-guard-extension.ts"
+      "./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",
+      "./extensions/scan-guard-extension.ts"
     ]
   },
   "files": [
@@ -53,8 +62,25 @@
     "extensions/autotune-extension.ts",
     "extensions/spec-merge.ts",
     "extensions/spec-merge-extension.ts",
+    "extensions/zero-validate.ts",
+    "extensions/zero-validate-extension.ts",
+    "extensions/zero-status.ts",
+    "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",
     "extensions/provider-guard-extension.ts",
+    "extensions/scan-guard.ts",
+    "extensions/scan-guard-extension.ts",
     "README.md",
     "LICENSE"
   ],

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/explore.md

@@ -24,6 +24,12 @@ constraints — reading past that point burns tokens without improving the plan.
 As a rough gauge, a localized change rarely needs more than ~20 tool calls; if
 you blow past that on a small request, you are over-exploring.
 
+**Scope every search to the project, never the filesystem root.** Search inside
+the repo/code directory you are working in. A `find`, `grep -r`, or `rg` rooted
+at `/`, a bare drive (`/c`, `C:\`), or `~`/`$HOME` is forbidden — on Windows it
+hangs forever forcing OneDrive to hydrate every cloud placeholder it walks, and
+zero blocks such commands at the tool boundary anyway.
+
 Produce a concise findings report the **plan** phase can build on: what exists,
 what is relevant to the request, and what to watch out for.
 

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.
 
@@ -85,6 +117,11 @@ means the same number on every run.
   per-task estimates, and the over-budget exceptions list — state "none" when
   there are no exceptions.
 
+When a run is likely to land as a chained PR series, make that explicit in the
+forecast: group tasks into reviewable PR-sized batches, name any ordering
+constraints between batches, and keep each batch small enough that `/zero-pr`
+can produce a focused pull request after `veredicto` returns `pasa`.
+
 **Return contract.** Return a concise result envelope to the orchestrator: your
 phase's outcome (findings, plan, build result, or verdict with its concrete
 reasoning) and the `.sdd/<slug>/` artifact path(s) you touched. No step-by-step

package/prompts/phases/veredicto.md

@@ -13,28 +13,56 @@ orchestrator's existing run-trace machinery — the Cortex `zero-run/<slug>` sav
 and the `~/.pi/zero-runs.jsonl` append. Do not write a separate verdict file;
 `.sdd/` artifacts stay plan state only.
 
-**Locating the code — read, do not search.** To check the build against the
-plan, read the `## Code roots` section in `design.md` (or the explore findings)
-for the absolute paths this feature touches, and read the build result for the
-files it changed — go straight to those paths to inspect the changes and run the
-tests. Do **not** run a filesystem-wide `find`/`grep` to rediscover where the
-code lives, and do **not** re-read a file you have already read this review
-unless it changed since; repeated re-reading is the main avoidable token cost on
-the review's model, which is often the most expensive in the pipeline. A single
-targeted search to fill a genuine gap is fine; a full-tree scan is not. This
-bounds cost only — it never lowers the bar for the verdict.
+**Locating the code — read, do not search.** Get the code root from the plan:
+the `## Code roots` section in `design.md`, or — for delta/forge runs that have
+no `design.md` — the `Code root:` line in `tasks.md` or the absolute path in
+your task input. Read the build result for the files it changed and go straight
+to those paths to inspect the changes and run the tests.
+
+**NEVER run a filesystem-wide scan to rediscover where the code lives.** A
+`find`, `grep -r`, or `rg` rooted at `/`, a bare drive (`/c`, `C:\`), or `~`/
+`$HOME` is forbidden — on Windows it does not merely run slow, it **hangs
+forever** forcing OneDrive to hydrate every cloud placeholder it walks (a real
+run wedged on `find / -maxdepth 12 …` for 6+ hours). zero blocks such commands
+at the tool boundary, so the call will fail anyway. Always scope a search to the
+code-root absolute path (`find <code-root> -name …`). If you cannot find the
+code root in the plan, say so in the verdict — do not go hunting for it.
+
+Also do **not** re-read a file you have already read this review unless it
+changed since; repeated re-reading is the main avoidable token cost on the
+review's model, which is often the most expensive in the pipeline. A single
+targeted search *inside the code root* to fill a genuine gap is fine; a
+full-tree scan is not. This bounds cost only — it never lowers the bar for the
+verdict.
 
 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.
 - `corregir` — fixable defects remain; the build phase must re-run.
 - `replantear` — the plan itself is wrong; the plan phase must re-run.
 
-Never return `pasa` unless the evidence supports it.
+Never return `pasa` unless the evidence supports it. `/zero-pr` is only allowed
+for runs whose latest recorded `veredicto` is `pasa`; if the verdict is
+`corregir` or `replantear`, the PR must wait for the next successful review.
 
 State the verdict's reasoning concretely — the specific defects for `corregir`,
 the specific plan flaw for `replantear`. The orchestrator persists that

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`.