@webpresso/agent-kit 3.1.30 → 3.3.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;
@@ -371,10 +382,13 @@ function runtimeSourceRequiresSourceLaunch(sourceRootDir, builtRootDir) {
   return false;
 }
 
-function wpSourceRequiresSourceLaunch(repoRoot) {
+export function wpSourceRequiresSourceLaunch(repoRoot) {
   const sourceRoots = [
     ["src", "cli"],
     ["src", "tool-runtime"],
+    ["src", "mcp"],
+    ["src", "blueprint"],
+    ["src", "audit"],
   ];
 
   return sourceRoots.some((segments) =>
@@ -839,6 +853,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 +1008,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 +1092,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.
@@ -66,7 +66,7 @@ asynchronously.
 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`).
+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/parallel-orchestration-quota.md

@@ -0,0 +1,100 @@
+---
+type: rule
+slug: parallel-orchestration-quota
+title: Parallel orchestration and quota discipline
+status: active
+scope: repo
+applies_to: [agents]
+related:
+  - ci-cost-local-first
+  - cmd-execution
+  - pre-implementation
+  - engineering-principles
+  - supported-agent-clis
+created: "2026-07-24"
+last_reviewed: "2026-07-24"
+paths:
+  - "blueprints/**"
+  - "catalog/agent/**"
+---
+
+# Parallel orchestration and quota discipline
+
+How to execute multi-blueprint work: one orchestrator, many cheap executors,
+lowest defensible token/quota/CI cost. This is the **default** execution model
+for programs of more than ~3 blueprints — not an opt-in mode.
+
+Companion rules (do not restate them here): `ci-cost-local-first.md` for runner
+policy, `cmd-execution.md` for the scoped-command surface,
+`pre-implementation.md` for the blueprint gate, `engineering-principles.md` for
+scope filters, `supported-agent-clis.md` for host tiers.
+
+## Orchestrator / executor split
+
+The session that owns the program is an **orchestrator**: it plans, sequences,
+dispatches, reviews, and lands. It does not implement. Implementation is
+delegated to **executor subagents**, one per blueprint, each confined to that
+blueprint's owner worktree.
+
+- Spawn a **fresh executor per task** inside a multi-task blueprint. Long
+  single-session runs drift; a fresh executor per task keeps a consolidated
+  blueprint cheap to run correctly.
+- Executors never touch the primary checkout or another blueprint's worktree.
+- The orchestrator runs from its own controller worktree cut from
+  `origin/main`, never from the primary checkout.
+
+## Model tier by intrinsic difficulty
+
+Pick the **cheapest model that can do the job**, judged by the hardest task in
+the blueprint — never by aggregate diff size or file count.
+
+| Complexity                                          | Executor                                     |
+| --------------------------------------------------- | -------------------------------------------- |
+| L / XL, design-heavy, security- or protocol-bearing | premium reasoning tier                       |
+| M                                                   | mid tier, high effort                        |
+| S / XS, mechanical                                  | mid tier, medium effort — or small/fast tier |
+
+A blueprint bundling many mechanically-trivial edits stays a cheap-tier job. If
+a blueprint would need a premium tier only because of one hard task, that task
+is mis-homed: move it to a blueprint whose tier it matches.
+
+**Exception: design, UI, and frontend work always gets the premium tier**,
+whatever its sized complexity — components, panels, layout, styling, UX flows,
+design systems, and the frontend half of any feature. Mechanical work degrades
+gracefully at a cheaper tier: it is either correct or it fails a test. Interface
+work does not. A technically-correct but badly-judged UI passes every check and
+still has to be redone, so the cheaper tier is not actually cheaper. Backend and
+mechanical work keeps the cheapest-capable rule above.
+
+## Quota awareness across hosts
+
+Provider subscriptions are the budget. Treat weekly quota as a shared,
+exhaustible resource across every host (see `supported-agent-clis.md`).
+
+- Route each job — implementation and review alike — to the host whose
+  subscription can absorb it, not reflexively to the strongest one.
+- On a provider usage-limit error, **rotate provider and resume** rather than
+  waiting or retrying the same host. Review gates are resumable by gate id.
+- Never spend a premium tier on work a cheap tier finishes identically.
+
+## Review and CI cost
+
+Blueprint count is the dominant cost driver: one executable blueprint is one
+PR, one external review, and one full CI matrix run.
+
+- **Consolidate coherent work.** One blueprint = one reviewable contract in one
+  subsystem. Never straddle a dependency cut, mix intrinsic-difficulty tiers, or
+  merge unrelated subsystems just to reduce count.
+- **Route each review gate to the cheapest adequate provider.** Reserve premium
+  reviewers for premium-tier blueprints.
+- **Prefer work that needs no gate at all.** Markdown-only PRs are exempt from
+  blueprint PR coverage; pure git hygiene (branch/worktree pruning) needs no PR.
+- Verify locally before pushing, and rebase onto fresh `origin/main` before
+  landing so cached CI layers are reused.
+
+## Parallelism
+
+Run 3–4 blueprints concurrently. Widen only when the extra lanes touch disjoint
+files; serialize where they contend. When several features would edit one hot
+file, land a **behavior-preserving split first** so each feature owns its own
+file — that split pays for itself across the whole program.

package/catalog/agent/rules/pre-implementation.md

@@ -7,7 +7,7 @@ scope: repo
 applies_to: [agents, humans]
 related: []
 created: "2026-05-06"
-last_reviewed: "2026-05-06"
+last_reviewed: "2026-07-23"
 ---
 
 # Pre-Implementation Rules
@@ -157,6 +157,10 @@ as finished.
 A blueprint is a **folder** (`blueprints/<status>/<slug>/_overview.md`) and may
 not be promoted from `draft/` to `planned/` until it has **1 provenance-backed
 approval from Claude/Codex/Grok or an OpenCode-Go model** on the current content.
+Legacy flat blueprints (`blueprints/<status>/<slug>.md`) remain readable and
+lifecycle-valid, but they have no sibling review authority; run
+`wp blueprint canonicalize <slug>` before recording review ledgers, artifacts,
+Ultragoal events, or approval frontmatter.
 
 - **Gate input = committed in-folder review authority.** The preferred path is a
   content-addressed v2 `review-events.jsonl` event produced by `wp review gate`.
@@ -203,6 +207,19 @@ approval from Claude/Codex/Grok or an OpenCode-Go model** on the current content
   `approvals:` frontmatter with first-hand knowledge that reviewer actually
   produced that verdict — there is intentionally no MCP-reachable shortcut
   around that.
+- **`wp review override <slug> --reason "…" --confirm` is the gated CLI escape
+  hatch for a genuinely un-convergeable gate** — a strong reviewer legitimately
+  rejected the subject but its sole remaining blocker is physically
+  un-remediable (e.g. a platform residual the code cannot fix). It records a
+  `maintainer-override` approval that satisfies the promotion gate DISTINCTLY
+  (never counted as a strong or OpenCode-Go approval). It is not a way to skip
+  review: it REFUSES unless a formal Claude/Codex/Grok/OpenCode-Go gate has
+  already rejected the exact current subject, and it requires an explicit reason
+  plus `--confirm`. `maintainer-override` is not in the `wp review log` /
+  `wp_blueprint_review_log` reviewer enum, so this command is the only writer —
+  there is no MCP-reachable or frontmatter shortcut to mint it. Reserve it for
+  the residual that no code change can close; a normal blocker is fixed and
+  re-reviewed, not overridden.
 - **Retry interrupted or structurally failed gates with the same immutable
   target** by running `wp review gate ... --resume <gate-id>`. Aborted,
   timed-out, incomplete, and protocol/transport failures append a new attempt
@@ -210,6 +227,16 @@ approval from Claude/Codex/Grok or an OpenCode-Go model** on the current content
   killed writer is never overwritten. A complete content rejection is terminal
   for that unchanged target, while active provider limits/unavailability remain
   suppressed until their recorded retry window permits another attempt.
+- **Completed rejections have a two-subject circuit breaker.** Plan review
+  lineage uses the canonical `wp-blueprint-v1` subject, so lifecycle/trust
+  bookkeeping commits reuse the prior rejection and do not invoke another
+  reviewer. One semantically changed remediation subject may receive the final
+  formal review; its prompt includes the prior rejection artifact and requires
+  all remaining blockers together. After two distinct semantic subjects are
+  rejected, `wp review gate` returns `scope-exhausted` before provider
+  invocation. Stop automated retries and obtain an explicit human scope
+  decision before creating a successor blueprint. Plan and delivery purposes
+  have separate budgets; delivery retains its existing whole-tree subject.
 - **`provider-event-too-large` means one captured provider JSON event exceeded
   the bounded event limit; it is not a reviewer verdict.** Keep the bound in
   place, retry the same gate id, and switch provider/model when possible because

package/catalog/agent/rules/supported-agent-clis.md

@@ -56,6 +56,15 @@ This is a product control-plane surface, not a silent Tier-1 promotion:
 - Missing binary/auth degrades with an explicit UI reason (never silent omit).
 - Benchmarks/plugins that require Tier-1 guarantees MUST still treat Grok as
   outside Tier 1 until a separate tier promotion lands.
+- `wp setup` also delivers the native project surfaces for Grok: the
+  `.grok/config.toml` `[mcp_servers.webpresso]` entry and trust-gated
+  `.grok/hooks/webpresso.json` managed hooks (run `/hooks-trust` once in Grok).
+  Grok reads `AGENTS.md`/`CLAUDE.md` natively, so no instruction projection is
+  needed.
+- After trusting the project hooks, operators verify native discovery with
+  `grok inspect --json`, `grok mcp list --json`, and
+  `grok mcp doctor --json`. Grok remains a trial host until its protected
+  privacy/native-proof job passes for the release SHA.
 
 ## Tier 3 — not supported