@webpresso/agent-kit 3.1.28 → 3.2.0

package/README.md

@@ -12,6 +12,11 @@ projects a repeatable `wp` command surface, generated host instructions, MCP
 quality tools, local continuity, and policy checks so agent work can be run,
 reviewed, and repaired with evidence.
 
+Its durable value is repo-owned policy and evidence, not matching every native
+host feature. Host launchers and plugin packages bridge the repo contract onto
+Claude, Codex, OpenCode, Grok, and future hosts; parity utilities are kept only
+where they protect that contract.
+
 The root `@webpresso/agent-kit` package is the CLI/core distribution: it
 ships `wp`, MCP tools, audits, blueprints, session memory, docs, and the
 catalog sources that generate repo-owned agent surfaces. Host-native plugin
@@ -96,13 +101,25 @@ Native host delivery is package-scoped: Claude, Codex, and OpenCode consume
 `@webpresso/claude-plugin`, `@webpresso/codex-plugin`, and
 `@webpresso/opencode-plugin` respectively. The root
 `@webpresso/agent-kit` package no longer ships repo-root host plugin payloads,
-and OpenCode uses native `opencode.json` `plugin[]` registration via
-`@webpresso/opencode-plugin`, not an MCP bridge. Claude Code installs the
+and OpenCode combines native `opencode.json` `plugin[]` registration via
+`@webpresso/opencode-plugin` (hook bridge) with a setup-managed
+`mcp.webpresso` entry that launches the shared `wp mcp` server directly.
+Claude Code installs the
 plugin as `agent-kit@webpresso` from a **version-pinned** GitHub marketplace
 (`webpresso/agent-kit@vX.Y.Z`); `wp update` / `wp setup` rebind that pin so
 hosts do not freeze on a stale catalog. See
 [`docs/packages/claude-plugin.md`](./docs/packages/claude-plugin.md).
 
+All four supported hosts receive the same `wp mcp` server from one canonical
+spec (`webpresso`, args `["mcp"]`, env `WP_SKIP_UPDATE_CHECK=1`):
+
+| Host     | Skills                                      | Hooks                                                                       | MCP (`wp mcp`)                                                 |
+| -------- | ------------------------------------------- | --------------------------------------------------------------------------- | -------------------------------------------------------------- |
+| Claude   | plugin `agent-kit@webpresso`                | setup-managed `.claude/settings.json`                                       | plugin manifest `mcpServers.webpresso`                         |
+| Codex    | plugin `@webpresso/codex-plugin`            | setup-managed `.codex/hooks.json`                                           | setup-managed `~/.codex/config.toml` `[mcp_servers.webpresso]` |
+| OpenCode | shared skill roots (`.claude/`, `.agents/`) | npm plugin `@webpresso/opencode-plugin` via `plugin[]`                      | setup-managed `opencode.json` `mcp.webpresso`                  |
+| Grok     | reads `AGENTS.md`/`CLAUDE.md` natively      | project `.grok/hooks/webpresso.json` (trust-gated: run `/hooks-trust` once) | project `.grok/config.toml` `[mcp_servers.webpresso]`          |
+
 Then ask Claude, Codex, or another MCP-capable host for one bounded read-only
 check:
 
@@ -122,20 +139,40 @@ When a repo uses provider-backed MCP credentials, launch the host through
 `wp claude`, `wp codex`, `wp grok`, `wp opencode`, or `wp dash` so `wp` can inject the
 configured provider environment before the host starts.
 
+Maintainers prove Claude's package-native path in an isolated fixture with
+`claude --plugin-dir packages/claude-plugin`, empty setting sources, built-in
+tools disabled, and an MCP allowlist containing only `wp_session_stats`. Grok
+operators run `/hooks-trust` in the project once, then verify discovery with
+`grok inspect --json`, `grok mcp list --json`, and
+`grok mcp doctor webpresso --json`. Scoping doctor keeps unrelated personal MCP
+authentication failures out of the Webpresso result.
+Provider-authenticated inference is deliberately local-only:
+
+```bash
+wp run proof:host-native
+```
+
+The command uses the Claude and Grok CLIs' saved local subscription sessions,
+removes API-key and CI OAuth variables from its child processes, fails closed
+when either login is unavailable, and writes only redacted evidence under
+`.webpresso/evidence/`. CI/CD validates the deterministic host contracts but
+never receives provider credentials or performs billed model inference. Use
+`proof:host-native:claude` or `proof:host-native:grok` to run one host.
+
 ## What `wp` guards
 
-| Outcome                                | What Agent Kit provides                                                                                                                                                                                                                                                     | Proof                                                                                                                                                                                                                                                                                                                                                                                                                                                |
-| -------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Start from a known repo contract       | `wp setup repair --project-init` creates or repairs agent instructions, host config, docs templates, blueprint folders, quality scripts, and safe ignores.                                                                                                                  | [setup command source](https://github.com/webpresso/agent-kit/tree/main/src/cli/commands/init)                                                                                                                                                                                                                                                                                                                                                       |
-| Give agents one command facade         | `wp test`, `wp lint`, `wp typecheck`, `wp format`, `wp e2e`, `wp qa`, `wp audit`, `wp worktree`, `wp fleet`, and `wp secrets` wrap repo-specific tooling behind one facade (see [stability policy](./docs/stability-policy.md) for which surfaces carry semver guarantees). | [CLI entrypoint](https://github.com/webpresso/agent-kit/blob/main/src/cli/cli.ts)                                                                                                                                                                                                                                                                                                                                                                    |
-| Expose bounded MCP tools               | `wp_*` MCP tools return JSON summaries with failure evidence, output limits, and token-saved metadata instead of raw terminal dumps.                                                                                                                                        | [MCP registry](https://github.com/webpresso/agent-kit/blob/main/src/mcp/tools/_registry.ts)                                                                                                                                                                                                                                                                                                                                                          |
-| Keep host surfaces consistent          | One catalog projects rules, hooks, generated instruction files, and the adapter-package contents used for native Claude, Codex, and OpenCode registration.                                                                                                                  | [Claude adapter](./packages/claude-plugin/), [Codex adapter](./packages/codex-plugin/), [OpenCode adapter](./packages/opencode-plugin/)                                                                                                                                                                                                                                                                                                              |
-| Preserve local continuity              | Session memory is local storage with explicit search, restore, capture, retrieve, reset, and doctor tools.                                                                                                                                                                  | [`docs/guides/session-memory.md`](./docs/guides/session-memory.md), [`docs/bench/session-memory-methodology.md`](./docs/bench/session-memory-methodology.md)                                                                                                                                                                                                                                                                                         |
-| Isolate risky work                     | Managed worktrees and blueprint owner binding keep implementation lanes separate from the main checkout.                                                                                                                                                                    | [worktrees guide](https://github.com/webpresso/agent-kit/blob/main/docs/worktrees.md)                                                                                                                                                                                                                                                                                                                                                                |
-| Run browser QA with evidence           | Browser doctor/ensure helpers and bundled browse, QA, design-review, and devex-review skills support local or explicit preview URLs.                                                                                                                                        | [browser source](https://github.com/webpresso/agent-kit/tree/main/src/browser), [QA output guide](https://github.com/webpresso/agent-kit/blob/main/docs/qa-output.md)                                                                                                                                                                                                                                                                                |
-| Handle secrets without committing them | Provider/profile/sink contracts route secrets through configured runtime channels for local commands, host launch wrappers, CI rehearsal, and supported preview/deploy workflows with repo-specific setup.                                                                  | [`docs/secrets/providers.md`](./docs/secrets/providers.md), [`docs/ci-act.md`](./docs/ci-act.md)                                                                                                                                                                                                                                                                                                                                                     |
-| Block drift before release             | Guardrails cover docs, blueprints, catalog drift, reference parity, paths, licenses, secrets, tech debt, and package surface.                                                                                                                                               | [audit source](https://github.com/webpresso/agent-kit/tree/main/src/audit), [`docs/bench/reference-parity-matrix.md`](./docs/bench/reference-parity-matrix.md), [host smoke test](https://github.com/webpresso/agent-kit/blob/main/src/__integration__/reference-parity-host-smoke.integration.test.ts), [tool surface test](https://github.com/webpresso/agent-kit/blob/main/src/__integration__/reference-parity-tool-surface.integration.test.ts) |
-| Tie claims to evidence                 | Public benchmark and release claims require docs gates plus a checked-in first-party result card under `docs/bench/result-cards/` before publication.                                                                                                                       | [`docs/bench/result-card-contract.md`](./docs/bench/result-card-contract.md), [`docs/bench/result-cards/README.md`](./docs/bench/result-cards/README.md), [public readiness script](https://github.com/webpresso/agent-kit/blob/main/scripts/public-readiness.ts)                                                                                                                                                                                    |
+| Outcome                                | What Agent Kit provides                                                                                                                                                                                                                                                                                           | Proof                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| -------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Start from a known repo contract       | `wp setup repair --project-init` creates or repairs agent instructions, host config, docs templates, blueprint folders, quality scripts, and safe ignores.                                                                                                                                                        | [setup command source](https://github.com/webpresso/agent-kit/tree/main/src/cli/commands/init)                                                                                                                                                                                                                                                                                                                                                       |
+| Give agents one command bridge         | `wp test`, `wp lint`, `wp typecheck`, `wp format`, `wp e2e`, `wp qa`, `wp audit`, `wp worktree`, `wp fleet`, and `wp secrets` expose repo-owned checks consistently while host-native mechanics stay replaceable (see [stability policy](./docs/stability-policy.md) for which surfaces carry semver guarantees). | [CLI entrypoint](https://github.com/webpresso/agent-kit/blob/main/src/cli/cli.ts)                                                                                                                                                                                                                                                                                                                                                                    |
+| Expose bounded MCP tools               | `wp_*` MCP tools return JSON summaries with failure evidence, output limits, and token-saved metadata instead of raw terminal dumps.                                                                                                                                                                              | [MCP registry](https://github.com/webpresso/agent-kit/blob/main/src/mcp/tools/_registry.ts)                                                                                                                                                                                                                                                                                                                                                          |
+| Keep host surfaces consistent          | One catalog projects rules, hooks, generated instruction files, and adapter-package contents; host-specific plugins are bridges, not the source of policy truth.                                                                                                                                                  | [Claude adapter](./packages/claude-plugin/), [Codex adapter](./packages/codex-plugin/), [OpenCode adapter](./packages/opencode-plugin/), [host substitution scorecard](./docs/host-substitution-scorecard.md)                                                                                                                                                                                                                                        |
+| Preserve local continuity              | Session memory is local storage with explicit search, restore, capture, retrieve, reset, and doctor tools.                                                                                                                                                                                                        | [`docs/guides/session-memory.md`](./docs/guides/session-memory.md), [`docs/bench/session-memory-methodology.md`](./docs/bench/session-memory-methodology.md)                                                                                                                                                                                                                                                                                         |
+| Isolate risky work                     | Managed worktrees and blueprint owner binding keep implementation lanes separate from the main checkout.                                                                                                                                                                                                          | [worktrees guide](https://github.com/webpresso/agent-kit/blob/main/docs/worktrees.md)                                                                                                                                                                                                                                                                                                                                                                |
+| Run browser QA with evidence           | Browser doctor/ensure helpers and bundled browse, QA, design-review, and devex-review skills support local or explicit preview URLs.                                                                                                                                                                              | [browser source](https://github.com/webpresso/agent-kit/tree/main/src/browser), [QA output guide](https://github.com/webpresso/agent-kit/blob/main/docs/qa-output.md)                                                                                                                                                                                                                                                                                |
+| Handle secrets without committing them | Provider/profile/sink contracts route secrets through configured runtime channels for local commands, host launch wrappers, CI rehearsal, and supported preview/deploy workflows with repo-specific setup.                                                                                                        | [`docs/secrets/providers.md`](./docs/secrets/providers.md), [`docs/ci-act.md`](./docs/ci-act.md)                                                                                                                                                                                                                                                                                                                                                     |
+| Block drift before release             | Guardrails cover docs, blueprints, catalog drift, reference parity, paths, licenses, secrets, tech debt, and package surface.                                                                                                                                                                                     | [audit source](https://github.com/webpresso/agent-kit/tree/main/src/audit), [`docs/bench/reference-parity-matrix.md`](./docs/bench/reference-parity-matrix.md), [host smoke test](https://github.com/webpresso/agent-kit/blob/main/src/__integration__/reference-parity-host-smoke.integration.test.ts), [tool surface test](https://github.com/webpresso/agent-kit/blob/main/src/__integration__/reference-parity-tool-surface.integration.test.ts) |
+| Tie claims to evidence                 | Public benchmark and release claims require docs gates plus a checked-in first-party result card under `docs/bench/result-cards/` before publication.                                                                                                                                                             | [`docs/bench/result-card-contract.md`](./docs/bench/result-card-contract.md), [`docs/bench/result-cards/README.md`](./docs/bench/result-cards/README.md), [public readiness script](https://github.com/webpresso/agent-kit/blob/main/scripts/public-readiness.ts)                                                                                                                                                                                    |
 
 ## Develop/deploy workflow shape
 
@@ -258,7 +295,8 @@ surfaces, quality gates, MCP tools, session memory, worktrees, blueprints,
 preview/deploy guardrails, and audit policy in one repeatable package.
 
 Skip it when you only want a prompt library, cannot run Node-based developer
-tooling, or do not want repo-local agent files. See
+tooling, or do not want repo-local agent files. Agent Kit is a repository
+delivery harness around coding-agent hosts, not a runtime agent SDK — see
 [`docs/is-agent-kit-for-me.md`](https://github.com/webpresso/agent-kit/blob/main/docs/is-agent-kit-for-me.md).
 
 ## Maintainer verification

package/bin/_run.js

@@ -1,8 +1,16 @@
 #!/usr/bin/env node
 
 import { spawn, spawnSync } from "node:child_process";
-import { existsSync, readFileSync, readdirSync, realpathSync, statSync } from "node:fs";
-import { basename, delimiter, dirname, isAbsolute, join, relative, resolve } from "node:path";
+import {
+  accessSync,
+  constants,
+  existsSync,
+  readFileSync,
+  readdirSync,
+  realpathSync,
+  statSync,
+} from "node:fs";
+import { basename, delimiter, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
 
 import {
@@ -28,6 +36,9 @@ const LAUNCHER_LINEAGE_ENV = "WP_INTERNAL_LAUNCHER_LINEAGE";
 const MAX_LAUNCHER_LINEAGE_DEPTH = 16;
 const MAX_LAUNCHER_LINEAGE_BYTES = 16 * 1024;
 const WP_PROBE_TIMEOUT_MS = 5_000;
+// Set on the child env when bootstrapping deps via `vp install`; a re-entrant `wp install`
+// (e.g. a vp wrapper that shells back to wp) sees it and refuses, bounding recursion.
+const BOOTSTRAP_VP_INSTALL_SENTINEL = "WP_BOOTSTRAP_VP_INSTALL";
 const WP_PROBE_TERM_GRACE_MS = 250;
 const WP_PROBE_KILL_OBSERVE_MS = 1_000;
 const WP_PROBE_OUTPUT_LIMIT_BYTES = 64 * 1024;
@@ -839,6 +850,139 @@ function formatMissingPathDelegateDiagnostic(repoRoot) {
   ].join(" ");
 }
 
+// Shared PATH-scan core for the bootstrap layer: yields { candidate, realpath } for each
+// `join(dir, name)` (name ∈ binNames) across PATH, realpath-deduped, skipping excludedOwners.
+// Extracted so the wp delegate resolver and the vp bootstrap resolver share one loop instead of
+// copying it. binNames is a list so callers can supply Windows PATHEXT variants (e.g. vp.cmd).
+function* iterateAgentPathCandidates({ binNames, pathEnv, excludedOwners = new Set() }) {
+  const seen = new Set();
+  for (const dir of pathEnv.split(delimiter)) {
+    if (!dir) continue;
+    for (const binName of binNames) {
+      const candidate = join(dir, binName);
+      if (!existsSync(candidate)) continue;
+      let realpath;
+      try {
+        realpath = canonicalPath(candidate);
+      } catch {
+        continue;
+      }
+      if (excludedOwners.has(realpath) || seen.has(realpath)) continue;
+      seen.add(realpath);
+      yield { candidate, realpath };
+    }
+  }
+}
+
+// Plain-JS mirror of src/cli/global-vp.ts's rejection contract. bin/_run.js is the
+// dependency-free bootstrap layer and cannot import global-vp.ts (TS, resolved from
+// node_modules that do not exist yet), so the contract is duplicated here by necessity.
+function splitPathSegments(value) {
+  const normalized = value.replace(/\\/g, sep);
+  const stripped = normalized.startsWith(sep) ? normalized.slice(sep.length) : normalized;
+  return stripped.split(sep).filter((segment) => segment.length > 0 && segment !== delimiter);
+}
+function hasSegmentPair(segments, left, right) {
+  return segments.some((segment, index) => segment === left && segments[index + 1] === right);
+}
+function isProjectNodeModulesCandidate(value) {
+  const segments = splitPathSegments(value);
+  return segments.includes("node_modules") && !segments.includes(".vite-plus");
+}
+function isRuntimeLocalVitePlusCandidate(value) {
+  return hasSegmentPair(splitPathSegments(value), ".vite-plus", "js_runtime");
+}
+function isRejectedBootstrapVpCandidate(candidatePath, realpath) {
+  return (
+    isProjectNodeModulesCandidate(candidatePath) ||
+    isProjectNodeModulesCandidate(realpath) ||
+    isRuntimeLocalVitePlusCandidate(candidatePath) ||
+    isRuntimeLocalVitePlusCandidate(realpath)
+  );
+}
+function isExecutableFile(path, platform = process.platform) {
+  try {
+    if (!statSync(path).isFile()) return false;
+    if (platform !== "win32") accessSync(path, constants.X_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// The `vp` filenames to look for on PATH. On Windows, expand PATHEXT (e.g. vp.cmd, vp.exe) so a
+// shim-installed `vp` is found; elsewhere just `vp`. Mirrors src/cli/global-vp.ts's discovery.
+function bootstrapVpCandidateNames(platform, env) {
+  if (platform !== "win32") return ["vp"];
+  const exts = (env.PATHEXT ?? ".COM;.EXE;.BAT;.CMD")
+    .split(";")
+    .map((ext) => ext.trim())
+    .filter((ext) => ext.length > 0);
+  return [...exts.map((ext) => `vp${ext}`), "vp"];
+}
+
+// Build the spawn descriptor for a resolved vp. On Windows a `.cmd`/`.bat` shim must run through
+// the command interpreter; elsewhere the realpath is executed directly. Mirrors global-vp.ts.
+function bootstrapVpCommand(realpath, platform, env) {
+  if (platform === "win32" && /\.(?:cmd|bat)$/iu.test(realpath)) {
+    return {
+      command: env.ComSpec ?? env.COMSPEC ?? "cmd.exe",
+      args: ["/d", "/s", "/c", realpath],
+    };
+  }
+  return { command: realpath, args: [] };
+}
+
+// Resolve a global Vite+ (`vp`) binary on PATH to bootstrap dependency installation on a bare
+// agent-kit source checkout, where `wp install` cannot load its own CLI. Mirrors the
+// `resolveGlobalCapableVp` contract: rejects project-local and Vite+ runtime-local `vp`, checks
+// executability, expands Windows PATHEXT, and wraps `.cmd`/`.bat` shims. Returns a spawn
+// descriptor `{ command, args }` (args is the prefix before the forwarded install args) or null.
+export function resolveBareCheckoutVp({
+  pathEnv = process.env.PATH ?? "",
+  platform = process.platform,
+  env = process.env,
+} = {}) {
+  const binNames = bootstrapVpCandidateNames(platform, env);
+  for (const { candidate, realpath } of iterateAgentPathCandidates({ binNames, pathEnv })) {
+    if (isRejectedBootstrapVpCandidate(candidate, realpath)) continue;
+    if (!isExecutableFile(realpath, platform)) continue;
+    return bootstrapVpCommand(realpath, platform, env);
+  }
+  return null;
+}
+
+// True only for a BARE `wp install` on a bare checkout. Positional subcommands
+// (`wp install codex|claude-code|opencode|oh-my`, or `wp install <pkg>`) route to
+// adapter/global-install/add paths in the real CLI and must NOT be blindly delegated to
+// `vp install`; only flag-only forms (e.g. `--frozen-lockfile`) pass. Deliberately not
+// generalized to `update`/`add`: default `wp update` is a tooling refresh, not a PM install.
+//
+// Eligibility keys off whether the CLI can actually load, not merely `node_modules` absence: the
+// CLI's own dependency `cac` must be present, or a built dist CLI must exist. This covers both a
+// fully bare checkout AND a partial/interrupted install (node_modules present but `cac` missing),
+// which would otherwise fall through to the same missing-dependency source crash.
+export function isInstallBootstrapNeeded(binName, argv, { repoRoot, env = process.env } = {}) {
+  if (binName !== "wp") return false;
+  if (argv[0] !== "install") return false;
+  if (!argv.slice(1).every((arg) => arg.startsWith("-"))) return false;
+  if (env.WP_FORCE_SOURCE === "1") return false;
+  if (!isAgentKitSourceRepo(repoRoot)) return false;
+  const cacInstalled = existsSync(join(repoRoot, "node_modules", "cac"));
+  const builtCli = existsSync(join(repoRoot, "dist", "esm", "cli", "cli.js"));
+  return !cacInstalled && !builtCli;
+}
+
+function formatMissingBareInstallDiagnostic(repoRoot) {
+  return [
+    "Unable to bootstrap dependencies for this @webpresso/agent-kit checkout:",
+    "its runtime dependencies are not installed, so `wp install` cannot load its own CLI (which",
+    "depends on packages that are not present yet).",
+    `No Vite+ (\`vp\`) binary was found on PATH to perform the install for ${repoRoot}.`,
+    "Install Vite+ (see the vite-plus documentation) or run a supported global `wp`, then re-run `wp install`.",
+  ].join(" ");
+}
+
 export async function resolvePathDelegateWp({
   repoRoot = resolvePackageRoot(),
   pathEnv = process.env.PATH ?? "",
@@ -861,24 +1005,15 @@ export async function resolvePathDelegateWp({
 
   const excludedOwners = new Set(launcherLineage);
   if (selfRealpath !== null) excludedOwners.add(selfRealpath);
-  const seenCandidates = new Set();
-  for (const dir of pathEnv.split(delimiter)) {
-    if (!dir) continue;
-    const candidate = join(dir, "wp");
-    if (!existsSync(candidate)) continue;
-    let candidateRealpath;
-    try {
-      candidateRealpath = canonicalPath(candidate);
-    } catch {
-      continue;
-    }
-    if (excludedOwners.has(candidateRealpath) || seenCandidates.has(candidateRealpath)) continue;
-    seenCandidates.add(candidateRealpath);
-    const probeEnv = withLauncherDelegate(env, launcherLineage, candidateRealpath);
-    if (!(await isAgentKitWpBinary(candidateRealpath, probeEnv, probeVersion, probeCommand))) {
-      continue;
+  for (const { realpath } of iterateAgentPathCandidates({
+    binNames: ["wp"],
+    pathEnv,
+    excludedOwners,
+  })) {
+    const probeEnv = withLauncherDelegate(env, launcherLineage, realpath);
+    if (await isAgentKitWpBinary(realpath, probeEnv, probeVersion, probeCommand)) {
+      return realpath;
     }
-    return candidateRealpath;
   }
   return null;
 }
@@ -954,6 +1089,31 @@ export async function runNamedBin(binName, argv = process.argv.slice(2)) {
     if (shouldBareMcpDelegate) throw new Error(formatMissingPathDelegateDiagnostic(repoRoot));
   }
 
+  // Dependency bootstrap for `wp install` when the CLI's own deps are not installed. Runs after
+  // the global-`wp` delegate attempt above (a healthy global wp is preferred for bare checkouts),
+  // and independently of `bareExternalPluginCheckout` so a partial/interrupted install (node_modules
+  // present but unusable) is also recovered instead of crashing on the missing `cac` import.
+  if (isInstallBootstrapNeeded(binName, argv, { repoRoot })) {
+    if (process.env[BOOTSTRAP_VP_INSTALL_SENTINEL] === "1") {
+      throw new Error(
+        "Refusing recursive vp bootstrap: a vp on PATH re-invoked `wp install` during dependency bootstrap.",
+      );
+    }
+    const vp = resolveBareCheckoutVp();
+    if (!vp) throw new Error(formatMissingBareInstallDiagnostic(repoRoot));
+    // Preserve the caller's cwd (matches package-manager.ts's `vp install`); do not force repoRoot.
+    const installed = spawnSync(vp.command, [...vp.args, "install", ...argv.slice(1)], {
+      stdio: "inherit",
+      env: { ...process.env, [BOOTSTRAP_VP_INSTALL_SENTINEL]: "1" },
+    });
+    if (installed.error) throw installed.error;
+    if (installed.signal) {
+      process.kill(process.pid, installed.signal);
+      return;
+    }
+    process.exit(installed.status ?? 1);
+  }
+
   const plan = buildLaunchPlan({ binName, forwardedArgs: argv, repoRoot });
   const isHookDispatch = binName === "wp" && argv[0] === "hook";
   const isHooksRuntimeCommand =

package/catalog/AGENTS.md.tpl

@@ -47,8 +47,8 @@ Catalog-owned surfaces:
 
 - Command routing is a hard invariant: prefer `wp`, then `vp`, then `pnpm`.
   Use `vp` only when `wp` has no equivalent, and raw `pnpm` only when
-  neither facade can perform the operation. All documentation, instructions,
-  scripts, and workflow examples must follow this order.
+  neither facade can perform the operation. All docs, instructions, scripts,
+  and workflows must follow this order.
 - Prefer repo scripts/wrappers over ad-hoc commands.
 - Repo hook/tool denial: switch to the named facade/lifecycle; do not retry raw.
 - Reuse nearby utilities and patterns before adding new abstractions.
@@ -63,10 +63,10 @@ asynchronously.
 
 ## Verify
 
-Before claiming completion, run the narrowest checks that prove the change:
-MCP/`wp` quality tools, typecheck, lint/format, affected tests, policy checks,
-docs/blueprint validation when those changed, and `wp sync --check` after
-template/catalog changes. On failure, fix root cause or record the blocker.
+Before claiming completion, run the narrowest MCP/`wp` checks that prove the
+change: typecheck, lint/format, affected tests, policy, docs/blueprint, and
+`wp sync --check` after template/catalog changes. Fix root cause or record the
+blocker. Before pushing, run `wp_ci_preflight` (see `ci-cost-local-first`).
 
 ## Communicate
 

package/catalog/agent/agents/implementer.md

@@ -0,0 +1,45 @@
+---
+name: implementer
+description: Implement a scoped fix or feature end-to-end (reproduce, edit, verify) when the task needs real Edit/Write/Bash access, not just review or docs. Prefer this over general-purpose for a single well-scoped code change.
+tools:
+  - Read
+  - Grep
+  - Glob
+  - Edit
+  - Write
+  - Bash
+model: sonnet
+---
+
+# Implementer
+
+You own landing one scoped code change: reproduce the problem or confirm the
+requirement, make the minimal correct edit, and prove it works.
+
+## Primary responsibilities
+
+- Reproduce the failure or confirm the requirement before editing.
+- Fix at the owning boundary — the root cause, not the nearest symptom.
+- Write or strengthen a regression proof (test, or the nearest reliable
+  equivalent) that fails against the old behavior before your fix and passes
+  after.
+- Update every consumer of a changed contract in the same change. No
+  half-migrations.
+- Run the narrowest verification that proves the repaired behavior (lint,
+  typecheck, targeted tests, relevant audits) before reporting done.
+
+## Scope discipline
+
+- One coherent repair per dispatch. If the task turns out to be several
+  unrelated failures, say so and name them instead of bundling fixes.
+- No speculative abstractions, config knobs, or unrelated cleanup alongside
+  the fix.
+- No silent fallbacks, suppressions, or lint disables to make a check pass.
+
+## Expected output
+
+- The invariant that was broken, in one sentence.
+- What changed and why, at the owning boundary.
+- The verification that ran (commands, exit codes, test names) — not a claim
+  without evidence.
+- Anything noticed but intentionally left unfixed, named explicitly.

package/catalog/agent/rules/ci-cost-local-first.md

@@ -0,0 +1,139 @@
+---
+type: rule
+slug: ci-cost-local-first
+title: CI cost and local-first gates
+status: active
+scope: repo
+applies_to: [agents]
+related:
+  - cmd-execution
+  - ci-test-perf
+  - pre-implementation
+  - hook-hot-path
+  - no-timeout-as-fix
+created: "2026-07-21"
+last_reviewed: "2026-07-21"
+paths:
+  - ".github/workflows/**"
+  - "catalog/agent/**"
+  - "AGENTS.md"
+  - ".husky/**"
+---
+
+# CI cost and local-first gates
+
+Agents waste money when they treat remote CI as the primary debugger.
+**Catch failures locally first.** Remote CI is confirmation, not exploration.
+
+Monthly spend on private repos (Ubicloud + GitHub-hosted minutes + artifact
+storage) is a product constraint. Prefer cheap local loops over burning full
+PR matrices to discover format/lint/type/test/governance failures.
+
+## Iron law
+
+1. **Never open or update a PR you already know will fail** a locally-runnable
+   gate (format, guardrails, typecheck, lint, affected tests, PR body contract,
+   changeset/blueprint trailers when applicable).
+2. **Never use `git push --no-verify` / `HUSKY=0` / skip hooks** to “save
+   time.” That only moves the failure to paid CI and trains a red-loop habit.
+3. **Never re-run a failed CI job “to see if it flaked”** until you have a
+   local reproduction or a concrete flake hypothesis with evidence.
+4. **Never add GitHub-hosted runners** (`ubuntu-latest`, `macos-*`,
+   `windows-*`) on private-repo workflows except the **Release / npm OIDC
+   publish** path (and release-native targets that truly need that OS). Default
+   is **Ubicloud** (`ubicloud-standard-2` / `-4` only when justified).
+
+## Local gate stack (must pass before push)
+
+| When                       | Command / check                                                                                                                  |
+| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
+| Every commit               | Managed pre-commit (format + staged guardrails)                                                                                  |
+| Every push                 | `wp ci-preflight` before pushing; in agent-kit itself this is also enforced by `.husky/pre-push`                                 |
+| Before PR open / body edit | PR template fields filled; trailers exact (`Blueprint-exempt`, `Changeset-exempt`, `Review-skip` as **start-of-line** when used) |
+| Before claim merge-ready   | `/verify <target>` then `/verify <target> --merge-ready` when landing                                                            |
+
+`wp ci-preflight` is fail-fast and **branch-scoped**:
+
+1. `wp format --affected --branch --check`
+2. `wp audit guardrails --affected --branch`
+3. `wp typecheck --affected --branch`
+4. `wp lint --affected --branch`
+5. `wp test --affected --branch`
+
+If preflight fails: **fix locally**, do not push. Reproduce with the printed
+`wp …` line.
+
+### Bootstrap before preflight
+
+Missing `node_modules` in a worktree → run `wp install` (or the repo’s setup),
+then preflight. Use `vp install` only when `wp` has no equivalent. Do not push a
+bare worktree “to let CI install.”
+
+## Cost model (private repos)
+
+| Resource                       | Cost driver                                       | Agent duty                                     |
+| ------------------------------ | ------------------------------------------------- | ---------------------------------------------- |
+| Ubicloud minutes               | Every PR job matrix (lint, tests, smokes, shards) | Local preflight; avoid drive-by full re-runs   |
+| GitHub-hosted `ubuntu-latest`  | Billable Actions minutes                          | Only release/OIDC publish unless proven needed |
+| GitHub `macos-*` / `windows-*` | ~10× Linux minutes                                | Release natives only; never default PR CI      |
+| Actions artifacts / caches     | Storage quota; can block Release uploads          | Prefer short retention; do not spam artifacts  |
+| Failed CI loops                | Full matrix × attempts                            | Fix from logs locally before `gh run rerun`    |
+
+Related: `ci-test-perf.md` (keep coverage; speed via workers/cache/shards — not
+by skipping tests). Prefer **fewer/cheaper runners + sharding** over raising
+timeouts (`no-timeout-as-fix.md`).
+
+## Workflow authoring (when you touch CI)
+
+- Private non-release jobs: `runs-on: ubicloud-standard-2` by default.
+- Use `ubicloud-standard-4` only when wall-time evidence shows standard-2 is
+  insufficient **with** full coverage and workers (document why).
+- Release publish job may use `ubuntu-latest` for npm trusted publishing /
+  provenance. Session-memory / platform native matrices that require Darwin or
+  Windows may use GH-hosted OS runners **only on the Release (publish=true)
+  path**, never on ordinary PR CI.
+- Path filters, `concurrency` cancel-in-progress, and change-scope skips are
+  preferred over always-on heavy jobs.
+- Do not add nightly/macOS “perf” jobs that run on every PR; keep them opt-in
+  (`workflow_dispatch`, label, or schedule) and prefer Ubicloud for any check
+  that is not Apple-signing/display-bound.
+
+## PR governance without burning CI
+
+These fail **before** expensive tests if you get them wrong — fix **before**
+push/open:
+
+- PR description AI/model disclosure + `Session id` (or `Session-skip`)
+- `Review-skip: SKIP <reason>` must match `^Review-skip:` at **line start**
+  (not nested under a bullet)
+- `Blueprint-exempt:` / `Changeset-exempt:` in **commit message** and/or body
+  when required (blueprint-pr-coverage reads **git trailers**, not only the PR body)
+- Version Packages / bot CI: do not invent admin-merge; use the runbook
+  (`docs/runbooks/version-packages-bot-ci.md` when present)
+
+## Forbidden agent habits
+
+- Push → watch red CI → tweak → push again (the “CI as unit test” loop)
+- Broaden CI timeouts / disable flakes instead of root-cause fix
+- Schedule or matrix-expand macOS/Windows for convenience
+- Upload large artifacts every PR “for debugging”
+- Claim “CI is green” from a partial check while WP check / required jobs pending
+- Force-push past hooks to land red work for “later fix”
+
+## Good loop
+
+```text
+edit → scoped lint/type/test → commit (hooks) → wp ci-preflight → push
+→ open PR with complete body → watch CI once → fix root cause locally if red
+```
+
+When CI fails: download/read the failed job log, reproduce with the matching
+local `wp` command, fix, preflight, push **one** corrective commit.
+
+## Related
+
+- `cmd-execution.md` — bookend QA; scoped commands in the middle
+- `ci-test-perf.md` — parallelism and install cache
+- `pre-implementation.md` — blueprint gates that only fail in CI if left open
+- `hook-hot-path.md` — pre-push stays local and non-network
+- CLI: `wp ci-preflight` (pre-push owner)

package/catalog/agent/rules/ci-test-perf.md

@@ -56,9 +56,13 @@ Mutation/Stryker jobs are auto-exempt when the step/job name or nearby lines men
 When a single job still exceeds budget **with full coverage**:
 
 1. Prefer **Vitest sharding** (`vitest run --shard=i/n` + blob reporter merge) over raising isolation-off globally.
-2. Prefer a **larger runner** (`ubicloud-standard-4`, etc.) + more `VITEST_MAX_WORKERS` over dropping suites.
+2. Prefer a **larger runner** (`ubicloud-standard-4`, etc.) + more `VITEST_MAX_WORKERS` over dropping suites — only after `ubicloud-standard-2` is proven insufficient. Do not jump to GitHub-hosted macOS/Windows for ordinary test jobs.
 3. Cache **native/build artifacts** when warm steps rebuild every PR (producer-specific).
 
+Private-repo default is **Ubicloud** for non-release jobs. GitHub-hosted
+runners are reserved for Release/OIDC publish (and release-native OS builds).
+See `ci-cost-local-first.md`.
+
 ## Related
 
 - Vitest performance: https://vitest.dev/guide/improving-performance

package/catalog/agent/rules/cmd-execution.md

@@ -14,6 +14,15 @@ paths:
 
 # Command Execution Rules
 
+## Local-first before remote CI
+
+Paid CI (Ubicloud + GitHub-hosted) is for confirmation. Use scoped commands
+while iterating, then **`wp ci-preflight` before every push**. In agent-kit
+itself, `.husky/pre-push` enforces that gate; consumer templates may leave
+pre-push checks user-owned. Never `git push --no-verify` to skip a configured
+local gate. See `ci-cost-local-first.md` for runner policy and anti-red-loop
+habits.
+
 ## BOOKEND Rule: Full QA Runs Exactly Twice
 
 The full QA pipeline (e.g. `wp qa`, `bun run qa`) is a