@gonrocca/zero-pi 0.1.60 → 0.1.62

package/README.md

@@ -37,7 +37,17 @@ 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. Run `/zero-cost [slug]` after the run to see cost/tokens by phase.
 
 ## 🛠 `/forge` — the SDD pipeline
 
@@ -55,6 +65,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
@@ -96,7 +110,7 @@ into `/forge` for you.
 | **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`. |
@@ -207,8 +221,11 @@ strong analyze):
 ```
 
 The `thinking` map sets each phase's pi effort level — one of `off`, `minimal`,
-`low`, `medium`, `high`, `xhigh`. A phase with no entry gets no `thinking:` line
-in its generated sub-agent (no aggressive default). `autotuneBudget` is optional:
+`low`, `medium`, `high`, `xhigh`. An explicit entry always wins; a phase with no
+entry (or an invalid level) falls back to the package default — `clarify:
+medium`, `explore: high`, `plan: high`, `analyze: high`, `build: high`,
+`veredicto: xhigh` — so no phase inherits your session-wide
+`defaultThinkingLevel`. `autotuneBudget` is optional:
 when `maxPhaseCostUsd` is set, autotune will not step a blamed phase up to a more
 expensive tier if that phase/model is already at or above the average USD
 ceiling with enough cost samples (`minSamples`, default 3). Set thinking from
@@ -233,11 +250,24 @@ audits the TDD evidence) and accepts `"off"` to disable the discipline.
 `tdd.testCommand` overrides the auto-detected test runner the TDD cycle invokes;
 leave it empty to let the build/veredicto phases detect it from the project.
 
-## Continuous integration
+### Token efficiency
+
+The phase sub-agents run **without** your global project context
+(`inheritProjectContext: false`): a global `AGENTS.md` is heavy and may carry
+personal data or credentials no phase needs — project conventions still reach
+the phases, because explore/build skim the repo's own `AGENTS.md`/`CLAUDE.md`.
+Every phase runs at an explicit `thinking:` level (your `zero.json` entry wins;
+gaps take the package defaults above), and explore works under a numeric
+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.
+
+## 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/sdd-agents.ts

@@ -17,7 +17,7 @@ import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 
-import { isThinkingLevel } from "./zero-models.ts";
+import { DEFAULT_THINKING, isThinkingLevel } from "./zero-models.ts";
 import type { ThinkingLevel } from "./zero-models.ts";
 
 /** The six SDD phases, in pipeline order, each backed by a
@@ -115,9 +115,13 @@ export function buildAgentFile(
   if (thinking && isThinkingLevel(thinking)) front.push(`thinking: ${thinking}`);
   front.push(`tools: ${PHASE_TOOLS[phase].join(", ")}`);
   if (!PHASE_COMPLETION_GUARD[phase]) front.push("completionGuard: false");
+  // `inheritProjectContext: false` keeps the user's global AGENTS.md out of
+  // every phase sub-agent: it is heavy (re-sent to each phase) and may carry
+  // personal data or credentials no phase needs. Project conventions still
+  // reach the phases — explore/build skim the repo's own AGENTS.md/CLAUDE.md.
   front.push(
     "systemPromptMode: replace",
-    "inheritProjectContext: true",
+    "inheritProjectContext: false",
     "inheritSkills: false",
     "---",
   );
@@ -176,6 +180,17 @@ export function phaseThinking(data: unknown, phase: Phase): ThinkingLevel | unde
   return undefined;
 }
 
+/**
+ * Resolve the effective `thinking:` level for a phase: the user's valid
+ * `zero.json` entry (or recoverable legacy suffix) wins; a missing or invalid
+ * entry falls back to the package default, so no generated agent ever inherits
+ * the session-wide `defaultThinkingLevel` from the user's settings. Exported
+ * for tests.
+ */
+export function resolvePhaseThinking(data: unknown, phase: Phase): ThinkingLevel {
+  return phaseThinking(data, phase) ?? DEFAULT_THINKING[phase];
+}
+
 /** Read the per-phase model from `~/.pi/zero.json`; `undefined` when absent. */
 function readPhaseModel(phase: Phase): string | undefined {
   try {
@@ -224,7 +239,7 @@ export default function register(_pi?: unknown): void {
           body,
           description,
           readPhaseModel(phase),
-          readPhaseThinking(phase),
+          readPhaseThinking(phase) ?? DEFAULT_THINKING[phase],
         );
         writeFileSync(join(agentsDir, `zero-${phase}.md`), file, "utf8");
       } catch {

package/extensions/zero-models.ts

@@ -88,6 +88,21 @@ const DEFAULT_MODELS: PhaseModels = {
   veredicto: "claude-opus-4-8",
 };
 
+/** Package default thinking level per phase, used to fill any gap in the
+ *  user's `zero.json` when the agent files are generated — so no phase ever
+ *  inherits the session-wide `defaultThinkingLevel` from the user's settings.
+ *  An explicit valid `zero.json` entry always wins. The gates get a level
+ *  proportional to their job (clarify records assumptions, analyze reviews
+ *  artifacts); veredicto keeps `xhigh` as the pipeline's adversarial guard. */
+export const DEFAULT_THINKING: Record<Phase, ThinkingLevel> = {
+  clarify: "medium",
+  explore: "high",
+  plan: "high",
+  analyze: "high",
+  build: "high",
+  veredicto: "xhigh",
+};
+
 /** Model list used only when pi's model registry is unavailable. */
 const FALLBACK_MODELS = [
   "claude-opus-4-8",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gonrocca/zero-pi",
-  "version": "0.1.60",
+  "version": "0.1.62",
   "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/orchestrator.md

@@ -260,11 +260,14 @@ and lists only the original four phases stays valid, and `clarify`/`analyze`
 fall back to their defaults (`clarify` cheap/fast, `analyze` strong). Configure
 all six through `/zero-models`.
 
-The `thinking` map is optional and partial: a phase with no entry simply gets no
-`thinking:` line in its generated `zero-<phase>.md` frontmatter — no aggressive
-default is written. When a phase has a valid level, the generated agent file
-carries a `thinking: <level>` line in its frontmatter (placed after `model:` and
-before `systemPromptMode:`), so the sub-agent runs at that effort level.
+The `thinking` map is optional and partial: an explicit valid entry always
+wins, and a phase with no entry (or an invalid level) falls back to the package
+default — `clarify: medium`, `explore: high`, `plan: high`, `analyze: high`,
+`build: high`, `veredicto: xhigh` — so no phase silently inherits the
+session-wide `defaultThinkingLevel` from the user's settings. Every generated
+`zero-<phase>.md` therefore carries a `thinking: <level>` line in its
+frontmatter (placed after `model:` and before `systemPromptMode:`), so the
+sub-agent runs at that effort level.
 
 ## Language Boundary
 

package/prompts/phases/build.md

@@ -22,6 +22,8 @@ re-read a file you already read this run unless you have changed it since —
 re-reading the same large file repeatedly is the main avoidable token cost. If
 the code roots are missing or wrong, run a single targeted search to fix them,
 then proceed — never fall back to scanning the whole tree.
+If the project root carries an `AGENTS.md` or `CLAUDE.md`, skim it once for
+project conventions — you receive no global user context.
 
 Implement the planned tasks in dependency order, test-first where practical. `tasks.md` is a dependency-aware graph: every task has a `depends:` line. Before starting a task, verify each listed dependency is already `[x]`; if a dependency is unchecked, complete that dependency first (when it is in your assigned batch) or stop and report the blocked task (when it is outside the assigned batch). Never skip ahead just because a later task looks easier. Keep every change within the plan's scope — do not expand it on your own initiative.
 

package/prompts/phases/explore.md

@@ -13,6 +13,8 @@ is normal; do not treat the missing directory as an error.
 Investigate the codebase and the feature request read-only. Do not modify any
 files. Map the relevant modules, the existing patterns and conventions, the
 integration points, and the constraints. Identify the risks and the unknowns.
+If the project root carries an `AGENTS.md` or `CLAUDE.md`, skim it once for
+project conventions — you receive no global user context.
 
 **Size exploration to the request.** Match breadth to what the change actually
 needs. A localized change — copy/text, one component, a config value, a single
@@ -21,8 +23,15 @@ wiring; do not map the full permission/billing model or unrelated subsystems
 unless the request touches them. A cross-cutting or architectural change earns
 full breadth. Stop once you can name the exact files to change and their
 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.
+
+**Exploration budget.** Classify the request from `request.md` before the first
+tool call: a localized change gets a budget of **20 tool calls**; a
+cross-cutting or architectural change gets **40**. At half budget, checkpoint:
+if you can already name the exact files to change and their constraints, STOP
+and write the findings. Exceeding the budget requires a
+`Budget exceeded: <concrete reason>` line inside `findings.md`, and whatever you
+did not get to goes into a `## Unknowns` section of the findings instead of more
+reading.
 
 **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