@gonrocca/zero-pi 0.1.61 → 0.1.63

package/README.md

@@ -37,7 +37,19 @@ pi install npm:@gonrocca/zero-pi
 pi install npm:pi-subagents      # required — the pipeline delegates to sub-agents
 ```
 
-Needs Node ≥ 20.6. Restart pi after an upgrade.
+Needs Node ≥ 20.6. Restart pi after an install or upgrade so pi regenerates
+the `zero-*` phase agents.
+
+### Quick start
+
+1. Run `/zero-doctor` to catch missing `pi-subagents`, stale generated agents,
+   invalid model config, or GitHub CLI auth before spending tokens.
+2. Run `/zero-models` (or set direct assignments) when you want a different
+   model/thinking profile per phase; otherwise the package defaults are used.
+3. Run `/forge <feature>` and let the automatic gates drive the flow.
+4. Read the final cost table: `/forge` invokes `/zero-cost <slug>` automatically
+   at the end. Re-run `/zero-cost [slug]` manually only when you want to inspect
+   an older run or debug missing metadata.
 
 ## 🛠 `/forge` — the SDD pipeline
 
@@ -55,6 +67,10 @@ to its own sub-agent:
 | **build** | Implement the plan. |
 | **veredicto** | Review it adversarially and record a verdict. |
 
+Each run keeps its paper trail under `.sdd/<slug>/`: `clarifications.md`,
+`findings.md`, `proposal.md`, `spec.md`, `design.md`, `tasks.md`,
+`checklist.md`, and (when Strict TDD engages) `tdd-evidence.md`.
+
 The **clarify** and **analyze** gates are automatic inside `/forge` — no extra
 slash command in the normal flow. `clarify` writes `.sdd/<slug>/clarifications.md`
 and asks only when proceeding would risk the wrong product; `analyze` writes
@@ -90,13 +106,13 @@ into `/forge` for you.
 | **Dependency-aware tasks** | `tasks.md` is validated as a task graph with mandatory `depends:` edges, topological ordering, and review workload totals. |
 | **Autotune** | Learns which model fits each phase from your run history and re-tunes itself; optional `autotuneBudget.maxPhaseCostUsd` suppresses costly step-ups. |
 | **`/zero-doctor`** | Preflight diagnostics for zero-pi: package install, Node version, pi-subagents, generated phase agents, model config, `.sdd/config`, run history, git, and `gh` auth. |
-| **`/zero-cost`** | Aggregates a run's sub-agent `meta.json` files into a per-phase token/cost/duration report — no schema change, reads what pi already writes. |
+| **`/zero-cost`** | Aggregates a run's sub-agent `meta.json` files into a per-phase token/cost/duration report — `/forge` invokes it automatically at the end; manual re-run stays available for older runs/debug. |
 | **`/zero-checkpoint`** | Writes patch-based worktree checkpoints under `.sdd/<slug>/checkpoints/` before risky build batches. |
 | **`/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. |
+| **Startup banner** | The sunset ANSI-Shadow `ZERO` wordmark, drawn once at pi startup — `ZERO_HEADER=off` to disable. |
 | **Working-phrase ticker** | Swaps pi's `Working...` for a context-aware Spanish phrase + spinner. |
 | **Conversation resume** | Writes `.pi/zero-resume.md` on exit — the restore command + a conversation tail. |
 | **Windows tree-kill** | Aborting a turn kills the whole process tree — no orphaned `claude`. |
@@ -115,7 +131,7 @@ into `/forge` for you.
 | `/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-cost [<slug>]` | Report tokens (in/out/cache), USD cost, duration, and tool-count per SDD phase for a run — `<slug>` for a specific run, no argument for the most recent. |
+| `/zero-cost [<slug>]` | Report tokens (in/out/cache), USD cost, duration, and tool-count per SDD phase for a run — reads native pi session metas and project-local `.pi-subagents/artifacts`; `<slug>` for a specific run, no argument for the most recent. |
 | `/zero-checkpoint [<slug>] [--json]` | Save `diff.patch`, `status.txt`, `head.txt`, `meta.json`, and a review-before-running `restore.sh` under `.sdd/<slug>/checkpoints/<id>/`. |
 | `/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. |
@@ -248,11 +264,12 @@ tool-call budget with a mid-budget stop check. The heavy lifting happens inside
 the sub-agents on their own models — leave the session that runs `/forge` on
 your cheap default model.
 
-## Continuous integration
+## Release checks
 
-The `.github/workflows/zero-pi-ci.yml` workflow runs on every push to `main` and
-on every pull request that touches `packages/zero-pi/**`. It enforces `npm test`
-and `npm run pack-check` for the package.
+Before publishing, run `npm test` and `npm run pack-check` from
+`packages/zero-pi`. `prepublishOnly` also runs the test suite, but `pack-check`
+confirms the npm tarball still contains the prompts, skills, themes, assets, and
+extension support modules pi needs.
 
 ## 🔗 Relationship to `zero`
 

package/extensions/zero-cost-extension.ts

@@ -1,6 +1,6 @@
 import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { homedir } from "node:os";
-import { join } from "node:path";
+import { dirname, join, resolve } from "node:path";
 
 import { parseMeta, selectRunMetas, aggregateRun, formatReport, type PhaseMeta } from "./zero-cost.ts";
 
@@ -8,40 +8,106 @@ 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 }
 
-/** Read every sub-agent `meta.json` across all pi session dirs and parse the
- *  zero-<phase> ones. Scanning every session keeps us decoupled from pi's
- *  cwd-encoding scheme; selection by slug/timestamp narrows to one run. */
-function readAllPhaseMetas(): PhaseMeta[] {
-  const root = join(homedir(), ".pi", "agent", "sessions");
-  if (!existsSync(root)) return [];
+export interface ReadAllPhaseMetasOptions {
+  /** Override for tests; defaults to ~/.pi/agent/sessions. */
+  sessionsRoot?: string;
+  /** Project cwd used to discover local .pi-subagents/artifacts; defaults to process.cwd(). */
+  cwd?: string;
+  /** Disable project-local .pi-subagents scanning when needed. */
+  includeProjectArtifacts?: boolean;
+}
+
+function addMeta(out: PhaseMeta[], seen: Set<string>, meta: PhaseMeta): void {
+  const key = `${meta.runId}\0${meta.phase}\0${meta.slug ?? ""}\0${meta.timestamp}\0${meta.model}`;
+  if (seen.has(key)) return;
+  seen.add(key);
+  out.push(meta);
+}
+
+function readArtifactDir(artifacts: string, out: PhaseMeta[], seen: Set<string>): void {
+  if (!existsSync(artifacts)) return;
+  let files: string[];
+  try { files = readdirSync(artifacts); }
+  catch { return; }
+  for (const f of files) {
+    if (!f.endsWith("_meta.json")) continue;
+    try {
+      const meta = parseMeta(JSON.parse(readFileSync(join(artifacts, f), "utf8")));
+      if (meta) addMeta(out, seen, meta);
+    } catch { /* skip unreadable / malformed meta */ }
+  }
+}
+
+function localArtifactDirs(startCwd: string): string[] {
+  const out: string[] = [];
+  const home = resolve(homedir());
+  let dir = resolve(startCwd);
+  let hops = 0;
+  for (;;) {
+    out.push(join(dir, ".pi-subagents", "artifacts"));
+    const parent = dirname(dir);
+    if (dir === parent || dir === home || hops >= 8) break;
+    dir = parent;
+    hops += 1;
+  }
+  return out;
+}
+
+/** Read every sub-agent `meta.json` that zero-cost knows about:
+ *  - pi-native `/forge` artifacts under `~/.pi/agent/sessions/<session>/subagent-artifacts/`.
+ *  - project-local pi-subagents artifacts under `.pi-subagents/artifacts/` from
+ *    the current cwd and its parents. This covers manually delegated zero phase
+ *    runs without making `/zero-cost` scan unrelated projects. */
+export function readAllPhaseMetas(options: ReadAllPhaseMetasOptions = {}): PhaseMeta[] {
+  const root = options.sessionsRoot ?? join(homedir(), ".pi", "agent", "sessions");
   const out: PhaseMeta[] = [];
-  for (const session of readdirSync(root, { withFileTypes: true })) {
-    if (!session.isDirectory()) continue;
-    const artifacts = join(root, session.name, "subagent-artifacts");
-    if (!existsSync(artifacts)) continue;
-    for (const f of readdirSync(artifacts)) {
-      if (!f.endsWith("_meta.json")) continue;
-      try {
-        const meta = parseMeta(JSON.parse(readFileSync(join(artifacts, f), "utf8")));
-        if (meta) out.push(meta);
-      } catch { /* skip unreadable / malformed meta */ }
+  const seen = new Set<string>();
+
+  if (existsSync(root)) {
+    try {
+      for (const session of readdirSync(root, { withFileTypes: true })) {
+        if (!session.isDirectory()) continue;
+        readArtifactDir(join(root, session.name, "subagent-artifacts"), out, seen);
+      }
+    } catch { /* ignore inaccessible session root */ }
+  }
+
+  if (options.includeProjectArtifacts !== false) {
+    for (const artifacts of localArtifactDirs(options.cwd ?? process.cwd())) {
+      readArtifactDir(artifacts, out, seen);
     }
   }
+
   return out;
 }
 
-function runCost(args: string, ctx: PiCommandContext): void {
+export function formatNoCostMessage(slug: string | null, metaCount: number): string {
+  const searched = "Busqué en ~/.pi/agent/sessions/*/subagent-artifacts/ y en .pi-subagents/artifacts/ del proyecto actual (y padres).";
+  if (slug) {
+    const hint = metaCount > 0
+      ? "Encontré metadata de otros runs, pero ningún meta matchea ese slug; probá /zero-cost sin argumento o revisá el slug exacto."
+      : "No encontré ningún *_meta.json de zero-* todavía.";
+    return [
+      `zero-cost: no encontré datos de costo para "${slug}".`,
+      searched,
+      hint,
+      "Si el run fue manual con subagent(...) en otro proyecto, corré /zero-cost desde ese cwd; si no hay *_meta.json, no hay costo recuperable.",
+    ].join("\n");
+  }
+  return [
+    "zero-cost: no encontré runs con datos de costo todavía.",
+    searched,
+    "/zero-cost solo suma metadata real (*_meta.json). Ejecutá /forge nativo y volvé a probar; si el run fue manual, corré el comando desde el proyecto donde quedó .pi-subagents/.",
+  ].join("\n");
+}
+
+export function runZeroCost(args: string, ctx: PiCommandContext, options: ReadAllPhaseMetasOptions = {}): void {
   const notify = (m: string, t?: NotifyType) => { try { ctx.ui.notify(m, t); } catch {} };
   const slug = args.trim() || null;
-  const metas = readAllPhaseMetas();
+  const metas = readAllPhaseMetas(options);
   const selected = selectRunMetas(metas, slug);
   if (selected.length === 0) {
-    notify(
-      slug
-        ? `zero-cost: no encontré datos de costo para "${slug}".`
-        : "zero-cost: no encontré runs con datos de costo todavía.",
-      "info",
-    );
+    notify(formatNoCostMessage(slug, metas.length), "info");
     return;
   }
   notify(formatReport(aggregateRun(selected, slug ?? selected[0]?.slug ?? null)), "info");
@@ -52,7 +118,7 @@ export default function register(pi?: PiExtensionAPI): void {
   pi.registerCommand("zero-cost", {
     description: "Reporta tokens, costo y duración por fase de un run SDD (slug opcional; sin slug = el más reciente)",
     handler: (args: string, ctx: PiCommandContext): void => {
-      try { if (ctx?.ui?.notify) runCost(args ?? "", ctx); }
+      try { if (ctx?.ui?.notify) runZeroCost(args ?? "", ctx); }
       catch (err) { try { ctx.ui.notify(`zero-cost: ${err instanceof Error ? err.message : String(err)}`, "error"); } catch {} }
     },
   });

package/extensions/zero-cost.ts

@@ -77,7 +77,9 @@ export function extractSlug(task: unknown): string | null {
     const slug = m[1];
     if (slug && slug !== "specs" && slug !== "archive") return slug;
   }
-  return null;
+  const label = /(?:^|\n)\s*Slug:\s*([A-Za-z0-9._-]+)/i.exec(task);
+  const slug = label?.[1];
+  return slug && slug !== "specs" && slug !== "archive" ? slug : null;
 }
 
 function num(v: unknown): number {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gonrocca/zero-pi",
-  "version": "0.1.61",
+  "version": "0.1.63",
   "description": "zero-pi — an installable layer for pi (pi.dev): the zero spec-driven development workflow (clarify → explore → plan → analyze → build → veredicto) with automatic clarify/analyze gates, per-phase model autotune, and token-efficient batched builds. Adds capability to pi without modifying pi.",
   "type": "module",
   "keywords": [

package/prompts/forge.md

@@ -15,8 +15,10 @@ returns `continue` (proceed to build) or `replan` (re-run plan with its
 defects). A `corregir` verdict re-runs `build`; a `replantear` verdict re-runs
 `plan`; after a few rounds with no `pasa`, stop and report the result as not
 verified. Ask the user for interactive or automatic mode up front; in
-interactive mode pause after each phase for approval. Never claim success unless
-veredicto returned `pasa`.
+interactive mode pause after each phase for approval. At terminal run end,
+invoke `/zero-cost <slug>` automatically and include the best-effort cost table
+in the final summary; the user should not have to run a second command. Never
+claim success unless veredicto returned `pasa`.
 
 **Parse the arguments first.** If the request begins with `--continue`, this is
 a **resume** run, not a fresh one:

package/prompts/orchestrator.md

@@ -476,6 +476,30 @@ 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.
 
+## Run cost report
+
+At the end of every run that reached a terminal verdict (`pasa` or
+`cap-reached`), invoke `/zero-cost <slug>` automatically and include its result
+in the final summary under `Costo:`. The user should not have to remember a
+second command after `/forge`; `/zero-cost` remains available only as a manual
+re-run/debug command.
+
+Rules:
+
+- Run it **after** the final veredicto/iteration-cap outcome is known and after
+  the `~/.pi/zero-runs.jsonl` metric append above. Do not run it for an aborted
+  invocation that never reached veredicto.
+- Pass the feature slug explicitly: `/zero-cost <slug>`. Never rely on the
+  command's "latest run" default from inside `/forge`.
+- Treat cost reporting as best-effort and non-blocking. If the command is
+  missing, errors, or reports no metadata, keep the verdict intact and summarize
+  the reason plainly: the run may not have been executed by native `/forge`, pi
+  may not have written `*_meta.json`, or project-local `.pi-subagents/` artifacts
+  may live under a different cwd.
+- If the command returns a cost table, relay the table compactly in the final
+  summary. Do not invent costs from `~/.pi/zero-runs.jsonl`; that file records
+  outcomes/models only, not usage.
+
 ## 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`.