@webpresso/agent-kit 3.1.30 → 3.2.0

package/dist/esm/cli/commands/init/mcp-spec.d.ts

@@ -0,0 +1,57 @@
+export declare const WEBPRESSO_MCP_SERVER_NAME = "webpresso";
+/**
+ * The single canonical launch spec for the webpresso MCP server. `name` is the
+ * server alias every host registers; `args` are appended after the resolved
+ * `wp` launcher; `env` is forwarded to the spawned process by every
+ * env-capable channel. `WP_SKIP_UPDATE_CHECK=1` keeps MCP startup from doing a
+ * network update probe on every host session.
+ */
+export declare const WEBPRESSO_MCP_SPEC: {
+    readonly name: "webpresso";
+    readonly args: readonly ["mcp"];
+    readonly env: {
+        readonly WP_SKIP_UPDATE_CHECK: "1";
+    };
+};
+export type WebpressoMcpSpec = typeof WEBPRESSO_MCP_SPEC;
+/**
+ * Resolve `binary` against PATH, returning the first executable candidate.
+ * Returns the candidate as an absolute path: relative PATH entries (`bin`,
+ * `.`) resolve against the current working directory — persisting them
+ * verbatim into host configs would resolve differently in later sessions.
+ * No realpath is taken, so generated configs stay anchored to a stable
+ * global-bin symlink rather than a version-pinned store path.
+ */
+export declare function resolveExecutableOnPath(binary: string, env: NodeJS.ProcessEnv): string | null;
+export interface WebpressoInstallProbe {
+    /** Test seam — override the candidate roots. Default: probe in fixed order. */
+    candidates?: readonly string[];
+    /** Test seam — resolve the stable global `wp` shim available on PATH. */
+    stableEntry?: () => string | null;
+    /** Test seam — verify that a PATH entry is the Webpresso command. */
+    stableEntryIsWebpresso?: (entryPath: string) => boolean;
+}
+/**
+ * Resolve the absolute path to webpresso's global `bin/wp` launcher on this
+ * machine. Probes the locations consumers use to install webpresso, in order
+ * of stability:
+ *
+ *   1. the stable global `wp` shim available on PATH
+ *   2. the currently executing `@webpresso/agent-kit` package
+ *   3. Claude plugin install — `~/.claude/plugins/cache/.../agent-kit/`
+ *   4. bun global — `~/.bun/install/global/node_modules/@webpresso/agent-kit/`
+ * Returns `null` when none of the candidates contain a usable `bin/wp`.
+ */
+export declare function findWebpressoMcpEntry(probe?: WebpressoInstallProbe): string | null;
+export declare function resolveWebpressoMcpEntry(probe?: WebpressoInstallProbe): {
+    entryPath: string | null;
+    checked: readonly string[];
+};
+export declare function isWebpressoWpEntry(entryPath: string): boolean;
+/** Run a discovery probe with bounded output and SIGKILL escalation. */
+export declare function runQuiet(cmd: string, args: readonly string[], timeoutMs?: number): string | null;
+/** Launch tuple for the webpresso MCP server given a resolved `wp` launcher. */
+export declare function agentKitMcpLaunchCommand(entryPath: string): {
+    command: string;
+    args: string[];
+};

package/dist/esm/cli/commands/init/mcp-spec.js

@@ -0,0 +1,273 @@
+/**
+ * Canonical Webpresso MCP server spec + shared `wp` binary resolver.
+ *
+ * One source of truth for how every supported host launches the webpresso MCP
+ * server. Each host channel (Claude plugin manifest, Codex plugin manifest,
+ * Codex `config.toml`, OpenCode `opencode.json`, Grok `.grok/config.toml`)
+ * projects this spec into its own config dialect. The two committed plugin
+ * manifests reference the launcher via `${CLAUDE_PLUGIN_ROOT}`/`${PLUGIN_ROOT}`;
+ * the setup-time writers resolve an absolute `bin/wp` path via
+ * {@link findWebpressoMcpEntry}. Compare channels *semantically* (command
+ * basename, args, env) — never byte-for-byte.
+ */
+import { accessSync, constants, existsSync, readFileSync, realpathSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, isAbsolute, join, relative, resolve } from "node:path";
+import { execFileSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { pathCandidates } from "#runtime/command-exists.js";
+export const WEBPRESSO_MCP_SERVER_NAME = "webpresso";
+/**
+ * The single canonical launch spec for the webpresso MCP server. `name` is the
+ * server alias every host registers; `args` are appended after the resolved
+ * `wp` launcher; `env` is forwarded to the spawned process by every
+ * env-capable channel. `WP_SKIP_UPDATE_CHECK=1` keeps MCP startup from doing a
+ * network update probe on every host session.
+ */
+export const WEBPRESSO_MCP_SPEC = {
+    name: WEBPRESSO_MCP_SERVER_NAME,
+    args: ["mcp"],
+    env: { WP_SKIP_UPDATE_CHECK: "1" },
+};
+/**
+ * Resolve `binary` against PATH, returning the first executable candidate.
+ * Returns the candidate as an absolute path: relative PATH entries (`bin`,
+ * `.`) resolve against the current working directory — persisting them
+ * verbatim into host configs would resolve differently in later sessions.
+ * No realpath is taken, so generated configs stay anchored to a stable
+ * global-bin symlink rather than a version-pinned store path.
+ */
+export function resolveExecutableOnPath(binary, env) {
+    for (const candidate of pathCandidates(binary, {
+        pathEnv: env.PATH,
+        pathExtEnv: env.PATHEXT,
+    })) {
+        try {
+            if (!statSync(candidate).isFile())
+                continue;
+            if (process.platform !== "win32")
+                accessSync(candidate, constants.X_OK);
+            return isAbsolute(candidate) ? candidate : resolve(candidate);
+        }
+        catch {
+            // Continue scanning PATH.
+        }
+    }
+    return null;
+}
+const WP_BIN_RELATIVE = join("bin", "wp");
+const WP_LAUNCHER_REQUIRED_RELATIVES = [
+    WP_BIN_RELATIVE,
+    join("bin", "_run.js"),
+    join("bin", "runtime-lanes.js"),
+    join("bin", "runtime-manifest.json"),
+];
+/**
+ * Resolve the absolute path to webpresso's global `bin/wp` launcher on this
+ * machine. Probes the locations consumers use to install webpresso, in order
+ * of stability:
+ *
+ *   1. the stable global `wp` shim available on PATH
+ *   2. the currently executing `@webpresso/agent-kit` package
+ *   3. Claude plugin install — `~/.claude/plugins/cache/.../agent-kit/`
+ *   4. bun global — `~/.bun/install/global/node_modules/@webpresso/agent-kit/`
+ * Returns `null` when none of the candidates contain a usable `bin/wp`.
+ */
+export function findWebpressoMcpEntry(probe = {}) {
+    return resolveWebpressoMcpEntry(probe).entryPath;
+}
+function isUsableWebpressoMcpRoot(root) {
+    return WP_LAUNCHER_REQUIRED_RELATIVES.every((relativePath) => existsSync(join(root, relativePath)));
+}
+export function resolveWebpressoMcpEntry(probe = {}) {
+    const checked = [];
+    if (probe.candidates === undefined) {
+        const stableEntry = probe.stableEntry !== undefined
+            ? probe.stableEntry()
+            : resolveExecutableOnPath("wp", process.env);
+        if (stableEntry) {
+            checked.push(stableEntry);
+            const packageWp = packageWpFromAdjacentNpmCmdShim(stableEntry);
+            if (packageWp !== null)
+                return { entryPath: packageWp, checked };
+            const verifierAllows = probe.stableEntryIsWebpresso?.(stableEntry) ?? true;
+            if (verifierAllows && isWebpressoWpEntry(stableEntry)) {
+                return { entryPath: stableEntry, checked };
+            }
+        }
+    }
+    const candidateGroups = probe.candidates !== undefined ? [probe.candidates] : [defaultFixedCandidates()];
+    for (const candidates of candidateGroups) {
+        for (const root of candidates) {
+            if (!root)
+                continue;
+            checked.push(root);
+            const wpBin = join(root, WP_BIN_RELATIVE);
+            if (isTrustedWebpressoPackageRoot(root))
+                return { entryPath: wpBin, checked };
+        }
+    }
+    return { entryPath: null, checked };
+}
+function defaultFixedCandidates() {
+    const home = process.env.HOME || homedir();
+    const packageRoot = currentAgentKitPackageRoot();
+    const claudePlugin = join(home, ".claude", "plugins", "cache", "webpresso", "agent-kit");
+    const bunGlobal = join(home, ".bun", "install", "global", "node_modules", "@webpresso", "agent-kit");
+    return [packageRoot ?? "", claudePlugin, bunGlobal];
+}
+function currentAgentKitPackageRoot() {
+    let current = dirname(fileURLToPath(import.meta.url));
+    for (let depth = 0; depth < 12; depth += 1) {
+        const packagePath = join(current, "package.json");
+        if (existsSync(packagePath)) {
+            try {
+                const pkg = JSON.parse(readFileSync(packagePath, "utf8"));
+                if (pkg.name === "@webpresso/agent-kit")
+                    return current;
+            }
+            catch {
+                return null;
+            }
+        }
+        const parent = dirname(current);
+        if (parent === current)
+            break;
+        current = parent;
+    }
+    return null;
+}
+function isUsableWebpressoPackageRoot(packageRoot) {
+    try {
+        const pkg = JSON.parse(readFileSync(join(packageRoot, "package.json"), "utf8"));
+        return pkg.name === "@webpresso/agent-kit" && isUsableWebpressoMcpRoot(packageRoot);
+    }
+    catch {
+        return false;
+    }
+}
+function isPathInsideOrEqual(parent, candidate) {
+    const parentRoot = realpathSync(parent);
+    const candidateRoot = realpathSync(candidate);
+    const rel = relative(resolve(parentRoot), resolve(candidateRoot));
+    return rel === "" || (!rel.startsWith("..") && !isAbsolute(rel));
+}
+function isTrustedWebpressoPackageRoot(packageRoot) {
+    try {
+        if (!isUsableWebpressoPackageRoot(packageRoot))
+            return false;
+        const realPackageRoot = realpathSync(packageRoot);
+        const sourceRoot = currentAgentKitPackageRoot();
+        if (sourceRoot !== null && realPackageRoot === realpathSync(sourceRoot))
+            return true;
+        return trustedHomeInstallPackageRoots().some((anchor) => existsSync(anchor) && isPathInsideOrEqual(anchor, realPackageRoot));
+    }
+    catch {
+        return false;
+    }
+}
+function trustedHomeInstallPackageRoots() {
+    const home = process.env.HOME || homedir();
+    return [
+        join(home, ".claude", "plugins", "cache", "webpresso", "agent-kit"),
+        join(home, ".bun", "install", "global", "node_modules", "@webpresso", "agent-kit"),
+    ];
+}
+function packageWpFromAdjacentNpmCmdShim(entryPath) {
+    if (!entryPath.toLowerCase().endsWith(".cmd"))
+        return null;
+    const packageRoot = join(dirname(entryPath), "node_modules", "@webpresso", "agent-kit");
+    return isTrustedWebpressoPackageRoot(packageRoot) ? join(packageRoot, "bin", "wp") : null;
+}
+export function isWebpressoWpEntry(entryPath) {
+    try {
+        if (entryPath.toLowerCase().endsWith(".cmd"))
+            return false;
+        // Validate package ownership from the symlink target. Executing a binary
+        // and trusting its self-reported version lets any same-named PATH entry
+        // impersonate Webpresso.
+        const resolvedEntry = realpathSync(entryPath);
+        const packageRoot = dirname(dirname(resolvedEntry));
+        if (resolvedEntry !== join(packageRoot, WP_BIN_RELATIVE))
+            return false;
+        return isTrustedWebpressoPackageRoot(packageRoot);
+    }
+    catch {
+        return false;
+    }
+}
+const PROBE_SUPERVISOR = String.raw `
+const { spawn } = require("node:child_process");
+const input = JSON.parse(process.argv[1]);
+const child = spawn(input.cmd, input.args, {
+  detached: process.platform !== "win32",
+  env: { ...process.env, WP_SKIP_UPDATE_CHECK: "1" },
+  stdio: ["ignore", "pipe", "ignore"],
+  windowsHide: true,
+});
+let output = "";
+let timedOut = false;
+let finished = false;
+const signal = (name) => {
+  try {
+    if (process.platform !== "win32" && child.pid) process.kill(-child.pid, name);
+    else child.kill(name);
+  } catch {}
+};
+const finish = (value) => {
+  if (finished) return;
+  finished = true;
+  clearTimeout(deadline);
+  clearTimeout(forceKill);
+  process.stdout.write(JSON.stringify(value));
+};
+let forceKill;
+const deadline = setTimeout(() => {
+  timedOut = true;
+  signal("SIGTERM");
+  forceKill = setTimeout(() => signal("SIGKILL"), input.killGraceMs);
+}, input.timeoutMs);
+child.stdout.setEncoding("utf8");
+child.stdout.on("data", (chunk) => {
+  output += chunk;
+  if (Buffer.byteLength(output) > input.maxBytes) {
+    timedOut = true;
+    output = "";
+    child.stdout.destroy();
+    signal("SIGKILL");
+  }
+});
+child.on("error", () => finish(null));
+child.on("exit", (code) => finish(!timedOut && code === 0 ? output.trim() || null : null));
+`;
+/** Run a discovery probe with bounded output and SIGKILL escalation. */
+export function runQuiet(cmd, args, timeoutMs = 1_500) {
+    try {
+        const output = execFileSync(process.execPath, [
+            "-e",
+            PROBE_SUPERVISOR,
+            JSON.stringify({
+                cmd,
+                args: [...args],
+                timeoutMs,
+                killGraceMs: 100,
+                maxBytes: 64 * 1024,
+            }),
+        ], {
+            encoding: "utf8",
+            env: { ...process.env, WP_SKIP_UPDATE_CHECK: "1" },
+            stdio: ["ignore", "pipe", "ignore"],
+            timeout: timeoutMs + 1_000,
+            // JSON escaping can expand the supervisor's already-bounded 64 KiB payload.
+            maxBuffer: 512 * 1024,
+        });
+        return JSON.parse(output);
+    }
+    catch {
+        return null;
+    }
+}
+/** Launch tuple for the webpresso MCP server given a resolved `wp` launcher. */
+export function agentKitMcpLaunchCommand(entryPath) {
+    return { command: entryPath, args: [...WEBPRESSO_MCP_SPEC.args] };
+}

package/dist/esm/cli/commands/init/merge.d.ts

@@ -4,6 +4,7 @@ export interface MergeOptions {
     overwrite?: boolean;
     dryRun?: boolean;
     ownership?: MergeOwnership;
+    repoRoot?: string;
 }
 export interface MergeResult {
     targetPath: string;

package/dist/esm/cli/commands/init/merge.js

@@ -7,7 +7,33 @@
  * only.
  */
 import { existsSync, mkdirSync, readFileSync, writeFileSync, statSync, readdirSync } from "node:fs";
-import { dirname, join } from "node:path";
+import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { convergeUnitFromTarget } from "./convergence.js";
+import { resolveUntrackedCollision } from "./untracked-collision.js";
+function guardUntrackedOverwrite(targetPath, incoming, opts) {
+    if (!opts.repoRoot)
+        return;
+    const repoRoot = resolve(opts.repoRoot);
+    const target = resolve(targetPath);
+    const repoRelative = relative(repoRoot, target);
+    if (repoRelative.length === 0 ||
+        repoRelative === ".." ||
+        repoRelative.startsWith(`..${sep}`) ||
+        isAbsolute(repoRelative)) {
+        return;
+    }
+    const result = resolveUntrackedCollision({
+        unit: convergeUnitFromTarget(repoRoot, target, {
+            action: "modify",
+            scope: "repo-committed",
+            reason: "setup merge target",
+        }),
+        desiredContent: incoming,
+        force: opts.overwrite,
+    });
+    if (!result.ok)
+        throw new Error(result.error);
+}
 export function writeFileMerged(targetPath, incoming, opts = {}) {
     const exists = existsSync(targetPath);
     const existingContent = exists ? readFileSync(targetPath, "utf8") : null;
@@ -25,6 +51,7 @@ export function writeFileMerged(targetPath, incoming, opts = {}) {
     if (shouldOverwrite) {
         if (opts.dryRun)
             return { targetPath, action: "skipped-dry" };
+        guardUntrackedOverwrite(targetPath, incoming, opts);
         writeFileSync(targetPath, incoming);
         return { targetPath, action: "overwritten" };
     }
@@ -92,6 +119,8 @@ export function patchJsonFile(targetPath, patcher, opts = {}) {
     if (opts.dryRun) {
         return { targetPath, action: "skipped-dry" };
     }
+    if (exists)
+        guardUntrackedOverwrite(targetPath, incoming, opts);
     mkdirSync(dirname(targetPath), { recursive: true });
     writeFileSync(targetPath, incoming);
     return { targetPath, action: exists ? "overwritten" : "created" };

package/dist/esm/cli/commands/init/plugin-cache-prune.d.ts

@@ -10,9 +10,6 @@ export declare const PLUGIN_CACHE_TARGETS: readonly [{
 }, {
     readonly host: "opencode";
     readonly rootParts: readonly [".config", "opencode", "plugins", "cache"];
-}, {
-    readonly host: "windsurf";
-    readonly rootParts: readonly [".windsurf", "plugins", "cache"];
 }, {
     readonly host: "agents";
     readonly rootParts: readonly [".agents", "plugins", "cache"];

package/dist/esm/cli/commands/init/plugin-cache-prune.js

@@ -6,7 +6,6 @@ export const PLUGIN_CACHE_TARGETS = [
     { host: "codex", rootParts: [".codex", "plugins", "cache"] },
     { host: "opencode", rootParts: [".opencode", "plugins", "cache"] },
     { host: "opencode", rootParts: [".config", "opencode", "plugins", "cache"] },
-    { host: "windsurf", rootParts: [".windsurf", "plugins", "cache"] },
     { host: "agents", rootParts: [".agents", "plugins", "cache"] },
     { host: "factory", rootParts: [".factory", "plugins", "cache"] },
 ];

package/dist/esm/cli/commands/init/scaffold-agents-md.d.ts

@@ -1,7 +1,7 @@
 import type { AgentkitConfig } from "./config.js";
 import type { ConsumerContext } from "./detect-consumer.js";
 import { type MergeOptions, type MergeResult } from "./merge.js";
-export declare const AGENTS_MD_MAX_BYTES = 8100;
+export declare const AGENTS_MD_MAX_BYTES = 8180;
 export declare function renderRepositoryMap(consumer: ConsumerContext): string;
 export declare function renderTechStack(consumer: ConsumerContext): string;
 export interface ScaffoldAgentsMdInput {

package/dist/esm/cli/commands/init/scaffold-agents-md.js

@@ -29,9 +29,15 @@ const TECH_STACK_RULES = [
     { dep: /^zod$/, label: "Zod" },
     { dep: /^typescript$/, label: "TypeScript" },
 ];
-// Kept under 8 KB (8192 bytes); headroom above 8_000 absorbs the longer
-// `wp_ultragoal_*` native tool names in the Codex routing surface.
-export const AGENTS_MD_MAX_BYTES = 8_100;
+// Kept under the 8 KB (8192-byte) hard ceiling. The rendered template embeds
+// the full `native_tool_names` registry list, so this soft target tracks the
+// tool count: adding an MCP tool grows the list by ~15-17 bytes. Bumped
+// 8_100 -> 8_180 for the four-tool batch (wp_ci_preflight, wp_session_id,
+// wp_session_info, wp_review_run), which renders ~8_160 — still 30+ bytes under
+// 8_192. The 8_192 ceiling is the real guardrail; the next addition that would
+// breach it should trigger a conscious restructure (or exclude the
+// auto-generated tool list from the prose budget), not another reflexive bump.
+export const AGENTS_MD_MAX_BYTES = 8_180;
 export function renderRepositoryMap(consumer) {
     const packages = consumer.workspacePackages;
     if (packages.length === 0) {

package/dist/esm/cli/commands/init/scaffold-base-kit.d.ts

@@ -14,6 +14,17 @@ interface PackageJsonLike {
     [key: string]: unknown;
 }
 export declare function readSetupWpActionRef(metaUrl: string): string;
+/**
+ * Idempotent, inject-by-content-absence repair for the managed `wp audit
+ * guardrails` CI step. On every `wp setup`, re-inserts the step into any
+ * wp-enabled quality workflow whose content lacks a guardrails invocation, so a
+ * consumer who deleted the step (with or without its comments) gets it back —
+ * and therefore keeps inheriting new guardrails (e.g. typescript-version) on
+ * their next agent-kit bump. Returns the content unchanged when the step is
+ * already present, the workflow is not a wp quality pipeline, or no test step
+ * anchor exists.
+ */
+export declare function ensureGuardrailsCiStep(content: string): string;
 export declare function readAgentConfigVersion(metaUrl: string): string;
 export declare function collectRuntimeContractGuidance(packageJson: PackageJsonLike | null | undefined): RuntimeContractGuidance;
 export declare const BASE_KIT_QUALITY_TARGETS: string[];

package/dist/esm/cli/commands/init/scaffold-base-kit.js

@@ -162,6 +162,61 @@ function migrateWorkflowContent(content, actionRef, version) {
     })
         .join("\n");
 }
+// Detects whether a workflow already invokes `wp audit guardrails`, keyed on the
+// command itself (not a `wp` prefix nor a marker comment) — mirrors how
+// `hasAuditBlock()` (audit-hooks scaffolder) self-heals the pre-commit hook by
+// scanning for the invocation string, so re-injection works even if a consumer
+// stripped every surrounding comment.
+const GUARDRAILS_CI_INVOCATION = /\baudit guardrails\b/u;
+// A workflow is a wp-enabled quality pipeline when it both installs the `wp`
+// runtime and runs the default test suite. Gating on a wp-runtime anchor keeps
+// injection off non-wp workflows (a reusable-workflow release.yml, or
+// agent-kit's own source-built CI) that must never get a consumer step. Two
+// install shapes count as the anchor: the `setup-wp` GitHub Action, and a
+// global npm/pnpm/vp install of `@webpresso/agent-kit` — the documented
+// third-party quick start for consumers that don't use the action (see
+// `package-conventions.md`; e.g. ozby/edge-matte's ci.yml).
+const SETUP_WP_MARKER = "setup-wp@";
+const GLOBAL_AGENT_KIT_INSTALL = /^(?=.*\b(?:npm|pnpm|vp)\s+(?:install|i|add)\b)(?=.*(?:-g\b|--global\b))(?=.*@webpresso\/agent-kit\b).*$/imu;
+const GUARDRAILS_CI_TEST_RUN = /(?:\bvp\s+run\s+test\b|\bpnpm\s+(?:run\s+)?test\b|\bnpm\s+(?:run\s+)?test\b|\bbun\s+(?:run\s+)?test\b|\bwp\s+test\b|\bvitest\s+run\b)/iu;
+function hasWpRuntimeAnchor(content) {
+    return content.includes(SETUP_WP_MARKER) || GLOBAL_AGENT_KIT_INSTALL.test(content);
+}
+/**
+ * Idempotent, inject-by-content-absence repair for the managed `wp audit
+ * guardrails` CI step. On every `wp setup`, re-inserts the step into any
+ * wp-enabled quality workflow whose content lacks a guardrails invocation, so a
+ * consumer who deleted the step (with or without its comments) gets it back —
+ * and therefore keeps inheriting new guardrails (e.g. typescript-version) on
+ * their next agent-kit bump. Returns the content unchanged when the step is
+ * already present, the workflow is not a wp quality pipeline, or no test step
+ * anchor exists.
+ */
+export function ensureGuardrailsCiStep(content) {
+    if (GUARDRAILS_CI_INVOCATION.test(content))
+        return content;
+    if (!hasWpRuntimeAnchor(content))
+        return content;
+    const lines = content.split("\n");
+    let anchorStepStart = -1;
+    let lastStepStart = -1;
+    for (let index = 0; index < lines.length; index += 1) {
+        const line = lines[index];
+        if (line.trim().startsWith("#"))
+            continue;
+        if (/^\s*-\s/u.test(line))
+            lastStepStart = index;
+        if (GUARDRAILS_CI_TEST_RUN.test(line)) {
+            anchorStepStart = lastStepStart;
+            break;
+        }
+    }
+    if (anchorStepStart === -1)
+        return content;
+    const indent = lines[anchorStepStart].match(/^(\s*)/u)?.[1] ?? "";
+    lines.splice(anchorStepStart, 0, `${indent}- name: Run wp audit guardrails`, `${indent}  run: wp audit guardrails`);
+    return lines.join("\n");
+}
 function migrateConsumerWorkflows(repoRoot, actionRef, version, options) {
     const workflowDir = join(repoRoot, ".github", "workflows");
     if (!existsSync(workflowDir))
@@ -171,7 +226,7 @@ function migrateConsumerWorkflows(repoRoot, actionRef, version, options) {
         .map((name) => {
         const targetPath = join(workflowDir, name);
         const existing = readFileSync(targetPath, "utf8");
-        const migrated = migrateWorkflowContent(existing, actionRef, version);
+        const migrated = ensureGuardrailsCiStep(migrateWorkflowContent(existing, actionRef, version));
         if (migrated === existing)
             return { targetPath, action: "identical" };
         if (options.dryRun)

package/dist/esm/cli/commands/init/scaffolders/agent-hooks/emitters/grok.d.ts

@@ -1,14 +1,20 @@
 /**
  * Grok Build native project hooks emitter.
  *
- * Writes a project-local `.grok/hooks.json` surface with managed commands
- * labeled `WP_HOOK_HOST=grok`. Claude freeload remains the fallback delivery
- * path; this is the first-class native project surface for doctor/setup.
+ * Grok reads project hook configs from `.grok/hooks/*.json` — a near-clone of
+ * the Claude Code hook contract (stdin event JSON incl. hookEventName/cwd,
+ * regex matchers, exit code 2 = deny, JSON stdout for decisions). We write one
+ * managed file, `.grok/hooks/webpresso.json`, with commands labeled
+ * `WP_HOOK_HOST=grok`. Hooks are trust-gated: the user must run `/hooks-trust`
+ * once in Grok before they fire (fail-open on timeout).
+ *
+ * Managed events are the intersection of WP_HOOK_SPECS with Grok's documented
+ * event set — notably Grok has no PermissionRequest event (it has
+ * PermissionDenied instead), so that spec is skipped.
  */
-export declare const GROK_HOOKS_RELATIVE_PATH = ".grok/hooks.json";
+export declare const GROK_HOOKS_DIR_RELATIVE_PATH = ".grok/hooks";
+export declare const GROK_HOOKS_RELATIVE_PATH = ".grok/hooks/webpresso.json";
 export type GrokHooksDocument = {
-    readonly version: 1;
-    readonly host: "grok";
     readonly hooks: Readonly<Record<string, readonly {
         readonly matcher?: string;
         readonly hooks: readonly {
@@ -19,8 +25,8 @@ export type GrokHooksDocument = {
     }[]>>;
 };
 /**
- * Build managed Grok hook groups. PreToolUse uses a broad Bash|Write|Edit matcher;
- * PermissionRequest and SessionStart are included without matchers.
+ * Build the managed Grok hook document (Claude-contract wrapped shape:
+ * `{ "hooks": { Event: [ { matcher?, hooks: [...] } ] } }`).
  */
 export declare function buildGrokHookDocument(input: {
     readonly resolveBin: (name: string) => string;

package/dist/esm/cli/commands/init/scaffolders/agent-hooks/emitters/grok.js

@@ -1,33 +1,55 @@
 /**
  * Grok Build native project hooks emitter.
  *
- * Writes a project-local `.grok/hooks.json` surface with managed commands
- * labeled `WP_HOOK_HOST=grok`. Claude freeload remains the fallback delivery
- * path; this is the first-class native project surface for doctor/setup.
+ * Grok reads project hook configs from `.grok/hooks/*.json` — a near-clone of
+ * the Claude Code hook contract (stdin event JSON incl. hookEventName/cwd,
+ * regex matchers, exit code 2 = deny, JSON stdout for decisions). We write one
+ * managed file, `.grok/hooks/webpresso.json`, with commands labeled
+ * `WP_HOOK_HOST=grok`. Hooks are trust-gated: the user must run `/hooks-trust`
+ * once in Grok before they fire (fail-open on timeout).
+ *
+ * Managed events are the intersection of WP_HOOK_SPECS with Grok's documented
+ * event set — notably Grok has no PermissionRequest event (it has
+ * PermissionDenied instead), so that spec is skipped.
  */
-import { mkdirSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { WP_HOOK_SPECS } from "#cli/commands/init/scaffolders/agent-hooks/ir.js";
-export const GROK_HOOKS_RELATIVE_PATH = ".grok/hooks.json";
+import { updateScaffolderTextFile } from "#cli/commands/init/scaffolders/file-transaction.js";
+export const GROK_HOOKS_DIR_RELATIVE_PATH = ".grok/hooks";
+export const GROK_HOOKS_RELATIVE_PATH = `${GROK_HOOKS_DIR_RELATIVE_PATH}/webpresso.json`;
+/** Grok's documented lifecycle events. */
+const GROK_HOOK_EVENTS = new Set([
+    "SessionStart",
+    "SessionEnd",
+    "UserPromptSubmit",
+    "PreToolUse",
+    "PostToolUse",
+    "PostToolUseFailure",
+    "PermissionDenied",
+    "Stop",
+    "StopFailure",
+    "Notification",
+    "SubagentStart",
+    "SubagentStop",
+    "PreCompact",
+    "PostCompact",
+]);
 /**
- * Build managed Grok hook groups. PreToolUse uses a broad Bash|Write|Edit matcher;
- * PermissionRequest and SessionStart are included without matchers.
+ * Build the managed Grok hook document (Claude-contract wrapped shape:
+ * `{ "hooks": { Event: [ { matcher?, hooks: [...] } ] } }`).
  */
 export function buildGrokHookDocument(input) {
     const { resolveBin } = input;
     const hooks = {};
     for (const spec of WP_HOOK_SPECS) {
-        // Grok managed subset: PreToolUse, PermissionRequest, SessionStart, PostToolUse.
-        if (spec.event !== "PreToolUse" &&
-            spec.event !== "PermissionRequest" &&
-            spec.event !== "SessionStart" &&
-            spec.event !== "PostToolUse") {
+        if (!GROK_HOOK_EVENTS.has(spec.event))
             continue;
-        }
-        // resolveBin (GROK_BIN) already labels WP_HOOK_HOST=grok on each branch of the
-        // launcher chain. Only prefix when the resolver returns a bare command.
+        // resolveBin (GROK_BIN) already labels WP_HOOK_HOST=grok on each branch of
+        // the launcher chain — with shell quoting (`WP_HOOK_HOST='grok'`), so match
+        // the variable name, not one quoting variant. Only prefix a bare command;
+        // prefixing a compound `if …` launcher would produce invalid `env … if`.
         const resolved = resolveBin(spec.bin);
-        const command = resolved.includes("WP_HOOK_HOST=grok")
+        const command = /WP_HOOK_HOST=(['"]?)grok\1/u.test(resolved)
             ? resolved
             : `env WP_HOOK_HOST=grok ${resolved}`;
         const group = {
@@ -41,11 +63,7 @@ export function buildGrokHookDocument(input) {
         const existing = hooks[spec.event] ?? [];
         hooks[spec.event] = [...existing, group];
     }
-    return {
-        version: 1,
-        host: "grok",
-        hooks,
-    };
+    return { hooks };
 }
 export function writeGrokProjectHooks(input) {
     const path = join(input.repoRoot, GROK_HOOKS_RELATIVE_PATH);
@@ -53,7 +71,6 @@ export function writeGrokProjectHooks(input) {
     if (input.dryRun) {
         return { path, written: false };
     }
-    mkdirSync(join(input.repoRoot, ".grok"), { recursive: true });
-    writeFileSync(path, `${JSON.stringify(doc, null, 2)}\n`, "utf8");
-    return { path, written: true };
+    const outcome = updateScaffolderTextFile(path, () => `${JSON.stringify(doc, null, 2)}\n`);
+    return { path, written: outcome === "written" };
 }