@webpresso/agent-kit 3.3.4 → 3.3.6

package/dist/esm/config/oxlint/oxlintrc.d.ts

@@ -1,6 +1,6 @@
 /**
  * Compiled plugin module basenames shipped next to the generated oxlintrc.json.
- * Must match agent-config policy plugins (guarded by vendor + parity tests).
+ * SSOT: `@webpresso/agent-config/oxlint` `OXLINT_POLICY_PLUGIN_BASENAMES`.
  */
 export declare const OXLINT_PLUGIN_BASENAMES: readonly ["code-safety", "foundation-purity", "graphql-conventions", "import-hygiene", "monorepo-paths", "query-patterns", "testing-quality", "tier-boundaries"];
 /** jsPlugins specifiers, sibling-relative to the shipped oxlintrc.json. */

package/dist/esm/config/oxlint/oxlintrc.js

@@ -15,21 +15,12 @@
  *   (`./<plugin>.js` siblings of the shipped JSON).
  * - `ignorePatterns` apply relative to the LINTED project (cwd).
  */
-import { rules as agentConfigRules } from "@webpresso/agent-config/oxlint";
+import { OXLINT_POLICY_PLUGIN_BASENAMES, rules as agentConfigRules, } from "@webpresso/agent-config/oxlint";
 /**
  * Compiled plugin module basenames shipped next to the generated oxlintrc.json.
- * Must match agent-config policy plugins (guarded by vendor + parity tests).
+ * SSOT: `@webpresso/agent-config/oxlint` `OXLINT_POLICY_PLUGIN_BASENAMES`.
  */
-export const OXLINT_PLUGIN_BASENAMES = [
-    "code-safety",
-    "foundation-purity",
-    "graphql-conventions",
-    "import-hygiene",
-    "monorepo-paths",
-    "query-patterns",
-    "testing-quality",
-    "tier-boundaries",
-];
+export const OXLINT_PLUGIN_BASENAMES = OXLINT_POLICY_PLUGIN_BASENAMES;
 /** jsPlugins specifiers, sibling-relative to the shipped oxlintrc.json. */
 export const OXLINT_JS_PLUGIN_FILES = OXLINT_PLUGIN_BASENAMES.map((name) => `./${name}.js`);
 /**

package/dist/esm/content/dispatch.js

@@ -12,6 +12,10 @@ import { loadContent } from "./loader.js";
 const CONSUMER_DIR_BY_KIND = {
     rule: "agent-rules",
     skill: "agent-skills",
+    // Not reachable today (no `wp agent` CRUD command dispatches here), kept
+    // only to satisfy Record<ContentKind, string> exhaustiveness now that
+    // "agent" is a ContentKind for the unified-sync projection pipeline.
+    agent: "agent-agents",
 };
 function todayIsoDate() {
     return new Date().toISOString().slice(0, 10);

package/dist/esm/content/loader.d.ts

@@ -14,7 +14,7 @@
  * gray-matter object in both `rawFrontmatter` and `parsedFrontmatter` so the
  * shape stays stable for downstream callers writing tests against it.
  */
-export type ContentKind = "rule" | "skill";
+export type ContentKind = "rule" | "skill" | "agent";
 export type ContentSource = "canonical" | "consumer";
 /**
  * Stub raw frontmatter type. Replaced with schema output in Task 2.x.

package/dist/esm/content/loader.js

@@ -21,10 +21,12 @@ const DEFAULT_KINDS = ["rule", "skill"];
 const CONSUMER_DIR_BY_KIND = {
     rule: "agent-rules",
     skill: "agent-skills",
+    agent: "agent-agents",
 };
 const CATALOG_DIR_BY_KIND = {
     rule: "rules",
     skill: "skills",
+    agent: "agents",
 };
 export function loadContent(options) {
     const { catalogDir, consumerRoot, kinds = DEFAULT_KINDS } = options;
@@ -83,9 +85,11 @@ function readKind(args) {
     const stat = statSync(root);
     if (!stat.isDirectory())
         return [];
-    return kind === "rule" ? readRules(root, source) : readSkills(root, source);
+    // agent kind shares the rule shape: flat `<slug>.md` files, README.md
+    // excluded. Only `skill` is directory-shaped (`<slug>/SKILL.md`).
+    return kind === "skill" ? readSkills(root, source) : readFlatMarkdown(kind, root, source);
 }
-function readRules(root, source) {
+function readFlatMarkdown(kind, root, source) {
     const out = [];
     for (const entry of readdirSync(root, { withFileTypes: true })) {
         if (!entry.isFile())
@@ -93,9 +97,9 @@ function readRules(root, source) {
         if (!entry.name.endsWith(".md"))
             continue;
         // Skip directory-documentation files. README.md exists in both the
-        // canonical catalog and the consumer-owned agent-rules/ scaffolder
-        // surface; treating it as a rule would produce a spurious slug
-        // collision and would also try to project it into per-IDE surfaces.
+        // canonical catalog and the consumer-owned agent-rules/ (or agent-agents/)
+        // scaffolder surface; treating it as content would produce a spurious
+        // slug collision and would also try to project it into per-IDE surfaces.
         if (entry.name === "README.md")
             continue;
         const filePath = realpathSync(join(root, entry.name));
@@ -103,7 +107,7 @@ function readRules(root, source) {
         const parsed = matter(readFileSync(filePath, "utf8"));
         const raw = { ...parsed.data };
         out.push({
-            kind: "rule",
+            kind,
             slug,
             source,
             filePath,

package/dist/esm/content/skill-policy.d.ts

@@ -1,6 +1,17 @@
 export declare const DEFAULT_PACKAGED_SKILL_SLUGS: readonly ["verify", "fix", "investigate", "ai-deslop", "plan-refine", "ralplan", "best-practice-research", "testing-philosophy", "tph", "claude", "codex", "grok", "opencode-go", "plan-eng-review", "plan-ceo-review", "plan-design-review", "plan-devex-review", "browse", "devex-review", "design-review", "hooks-doctor", "tech-debt", "lore-protocol", "deep-interview", "deep-research", "autoresearch", "ultragoal", "autopilot", "team"];
 export type DefaultPackagedSkillSlug = (typeof DEFAULT_PACKAGED_SKILL_SLUGS)[number];
 export declare const DEFAULT_PACKAGED_SKILL_SLUG_SET: ReadonlySet<string>;
+/**
+ * Catalog skills that are deliberately NOT in DEFAULT_PACKAGED_SKILL_SLUGS,
+ * with a one-line reason each. Every slug under `catalog/agent/skills/` must
+ * appear in either that list or this one (enforced by
+ * `checkCatalogSkillClassification` in `src/audit/agents.ts`) — an
+ * unclassified slug means a new catalog skill shipped without a deliberate
+ * packaging decision.
+ */
+export declare const UNPACKAGED_SKILL_SLUGS: Readonly<Record<string, string>>;
+export declare const UNPACKAGED_SKILL_SLUG_SET: ReadonlySet<string>;
+export declare function isUnpackagedSkillSlug(slug: string): boolean;
 export declare const MERGED_DELETED_SKILL_SLUGS: readonly ["autoplan", "health", "systematic-debugging", "test-driven-development"];
 export declare const MERGED_DELETED_SKILL_SLUG_SET: ReadonlySet<string>;
 /**

package/dist/esm/content/skill-policy.js

@@ -30,6 +30,39 @@ export const DEFAULT_PACKAGED_SKILL_SLUGS = [
     "team",
 ];
 export const DEFAULT_PACKAGED_SKILL_SLUG_SET = new Set(DEFAULT_PACKAGED_SKILL_SLUGS);
+/**
+ * Catalog skills that are deliberately NOT in DEFAULT_PACKAGED_SKILL_SLUGS,
+ * with a one-line reason each. Every slug under `catalog/agent/skills/` must
+ * appear in either that list or this one (enforced by
+ * `checkCatalogSkillClassification` in `src/audit/agents.ts`) — an
+ * unclassified slug means a new catalog skill shipped without a deliberate
+ * packaging decision.
+ */
+export const UNPACKAGED_SKILL_SLUGS = {
+    qa: "source-catalog QA skill, not package-visible in the default plugin skill set today (see workflow-skills-routing.md)",
+    "qa-only": "source-catalog QA skill, not package-visible in the default plugin skill set today (see workflow-skills-routing.md)",
+    review: "listed as a default workflow skill in workflow-skills-routing.md but not yet added to DEFAULT_PACKAGED_SKILL_SLUGS",
+    pll: "ultragoal's parallel-execute companion (ready-queue/worktrees driver); not independently default-packaged",
+    "frontend-design": "opt-in design-guidance skill, not part of the default packaged workflow set",
+    "monorepo-navigation": "tier-3 opt-in preset (wp setup --with monorepo-navigation), not default-packaged",
+    "tanstack-query": "tier-3 opt-in preset (wp setup --with tanstack-query), not default-packaged",
+    "react-doctor": "opt-in framework best-practice skill, not default-packaged",
+    "better-auth-best-practices": "opt-in best-practice reference skill, not default-packaged",
+    "logging-best-practices": "opt-in best-practice reference skill, not default-packaged",
+    "vercel-react-best-practices": "opt-in best-practice reference skill, not default-packaged",
+    "web-design-guidelines": "opt-in best-practice reference skill, not default-packaged",
+    deepseek: "individual OpenCode-Go model reviewer skill; only the aggregate opencode-go skill is default-packaged",
+    glm: "individual OpenCode-Go model reviewer skill; only the aggregate opencode-go skill is default-packaged",
+    hy3: "individual OpenCode-Go model reviewer skill; only the aggregate opencode-go skill is default-packaged",
+    kimi: "individual OpenCode-Go model reviewer skill; only the aggregate opencode-go skill is default-packaged",
+    mimo: "individual OpenCode-Go model reviewer skill; only the aggregate opencode-go skill is default-packaged",
+    minimax: "individual OpenCode-Go model reviewer skill; only the aggregate opencode-go skill is default-packaged",
+    qwen: "individual OpenCode-Go model reviewer skill; only the aggregate opencode-go skill is default-packaged",
+};
+export const UNPACKAGED_SKILL_SLUG_SET = new Set(Object.keys(UNPACKAGED_SKILL_SLUGS));
+export function isUnpackagedSkillSlug(slug) {
+    return UNPACKAGED_SKILL_SLUG_SET.has(slug);
+}
 export const MERGED_DELETED_SKILL_SLUGS = [
     "autoplan",
     "health",

package/dist/esm/hooks/doctor.js

@@ -28,7 +28,7 @@ import { findAgentKitPackageRoot, resolveAgentKitPackageRoot, } from "#cli/comma
 import { readInstalledHooksMap } from "#hooks/shared/installed-hooks.js";
 import { auditCodexConfigPaths, checkCodexConfigPathIntegrity } from "#hooks/codex-config-paths.js";
 import { findInstalledCodexPluginMcpManifests, pruneOwnedMcpServerBlock, } from "#cli/commands/init/scaffolders/codex-mcp/index.js";
-import { isAgentKitOwnedWpCommand, WEBPRESSO_MCP_SERVER_NAME, } from "#cli/commands/init/mcp-spec.js";
+import { resolveExecutableOnPath, WEBPRESSO_MCP_SPEC, isAgentKitOwnedWpCommand, WEBPRESSO_MCP_SERVER_NAME, } from "#cli/commands/init/mcp-spec.js";
 import { parseProjectMcpServers, scanCodexConfigDrift } from "#hooks/host-config-contract.js";
 import { defaultCodexConfigFilePath } from "#cli/commands/init/scaffolders/agent-hooks/codex-trust-sync.js";
 import { expectedRootWpBinRelativePath, formatRootLauncherContractFailure, rootContractMode, validateRootLauncherContract, } from "#launcher/root-contract.js";
@@ -1201,31 +1201,135 @@ function runCommand(command, args, cwd = process.cwd(), timeoutMs = DEFAULT_HOOK
         });
     });
 }
-async function checkCodexHost() {
+function asRecord(value) {
+    return value && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : null;
+}
+function unsupportedCodexJsonFlag(result) {
+    const text = `${result.stderr}\n${result.stdout}`;
+    return (/--json/u.test(text) && /(unexpected|unknown|unrecognized|invalid|found argument)/iu.test(text));
+}
+function classifyCodexMcpListJson(stdout) {
+    let parsed;
+    try {
+        parsed = JSON.parse(stdout);
+    }
+    catch (error) {
+        return {
+            kind: "malformed",
+            reason: error instanceof Error ? error.message : "invalid JSON",
+        };
+    }
+    if (!Array.isArray(parsed)) {
+        return { kind: "malformed", reason: "expected a top-level array" };
+    }
+    const webpressoEntry = parsed
+        .map((entry) => asRecord(entry))
+        .find((entry) => entry?.name === WEBPRESSO_MCP_SERVER_NAME);
+    if (!webpressoEntry)
+        return { kind: "missing" };
+    if (webpressoEntry.enabled !== true) {
+        const reason = typeof webpressoEntry.disabled_reason === "string" &&
+            webpressoEntry.disabled_reason.length > 0
+            ? webpressoEntry.disabled_reason
+            : "enabled=false";
+        return { kind: "disabled", reason };
+    }
+    const transport = asRecord(webpressoEntry.transport);
+    if (!transport || transport.type !== "stdio" || typeof transport.command !== "string") {
+        return { kind: "nonstdio" };
+    }
+    if (transport.command === "wp" && stringArrayEquals(transport.args, WEBPRESSO_MCP_SPEC.args)) {
+        return { kind: "canonical", command: "wp", args: ["mcp"] };
+    }
+    const args = Array.isArray(transport.args)
+        ? transport.args.map((arg) => String(arg)).join(" ")
+        : "";
+    return { kind: "noncanonical", command: `${transport.command}${args ? ` ${args}` : ""}` };
+}
+function classifyCodexMcpLaunchability(stdout, env) {
+    const classification = classifyCodexMcpListJson(stdout);
+    switch (classification.kind) {
+        case "canonical": {
+            const resolved = resolveExecutableOnPath(classification.command, env);
+            if (resolved) {
+                return null;
+            }
+            const pathValue = env.PATH && env.PATH.length > 0 ? env.PATH : "(empty)";
+            return {
+                kind: "failure",
+                detail: `@webpresso/codex-plugin/.mcp.json configures webpresso MCP as \`wp mcp\`, but \`wp\` is not resolvable on this doctor's PATH (${pathValue}); fix is not automatic: restore global \`wp\` in the Codex launch environment or run \`wp install codex\` after PATH is fixed`,
+            };
+        }
+        case "disabled":
+            return {
+                kind: "failure",
+                detail: `webpresso MCP entry is configured but disabled by \`codex mcp list --json\` (${classification.reason}); fix is not automatic: inspect Codex MCP configuration and run \`wp install codex\` if the bundled plugin is stale`,
+            };
+        case "malformed":
+            return {
+                kind: "failure",
+                detail: `codex mcp list --json returned malformed output (${classification.reason}); cannot verify webpresso MCP launchability; fix is not automatic: run \`wp install codex\` if the Codex CLI is stale`,
+            };
+        case "missing":
+            return {
+                kind: "failure",
+                detail: "missing MCP entry (webpresso=false); run `wp install codex` to install the bundled plugin",
+            };
+        case "nonstdio":
+            return {
+                kind: "advisory",
+                detail: "webpresso MCP configured with a non-stdio transport; launchability was not verified for user-owned transports",
+            };
+        case "noncanonical":
+            return {
+                kind: "advisory",
+                detail: `webpresso MCP configured with non-canonical command \`${classification.command}\`; launchability was not verified for user-owned commands`,
+            };
+    }
+}
+async function checkCodexHost(env = process.env) {
     const available = await runCommand("codex", ["--version"]);
     if (!available.ok) {
         return { name: "Codex host integration", ok: true, detail: "skipped (codex not on PATH)" };
     }
-    const result = await runCommand("codex", ["mcp", "list"]);
+    const result = await runCommand("codex", ["mcp", "list", "--json"]);
     if (!result.ok) {
+        if (unsupportedCodexJsonFlag(result)) {
+            return {
+                name: "Codex host integration",
+                ok: false,
+                detail: "codex mcp list --json is unsupported by the installed Codex CLI; fix is not automatic: run `wp install codex` to refresh the Codex integration",
+            };
+        }
         return {
             name: "Codex host integration",
             ok: false,
             detail: result.stderr.trim() || `exit ${result.code}`,
         };
     }
-    const hasAgentKit = result.stdout.includes("webpresso");
-    if (!hasAgentKit) {
+    const launchability = classifyCodexMcpLaunchability(result.stdout, env);
+    const findings = launchability?.kind === "failure" ? [launchability.detail] : [];
+    const advisories = launchability?.kind === "advisory" ? [launchability.detail] : [];
+    const legacy = classifyLegacyCodexWebpressoChannel();
+    if (legacy)
+        findings.push(legacy);
+    if (findings.length > 0) {
         return {
             name: "Codex host integration",
             ok: false,
-            detail: `missing MCP entry (webpresso=${hasAgentKit})`,
+            detail: [...findings, ...advisories].join("; "),
         };
     }
-    const legacy = classifyLegacyCodexWebpressoChannel();
-    if (legacy)
-        return { name: "Codex host integration", ok: false, detail: legacy };
-    return { name: "Codex host integration", ok: true, detail: "webpresso MCP visible" };
+    if (advisories.length > 0) {
+        return { name: "Codex host integration", ok: true, detail: advisories.join("; ") };
+    }
+    return {
+        name: "Codex host integration",
+        ok: true,
+        detail: "webpresso MCP visible (wp mcp launch command resolves on PATH)",
+    };
 }
 /**
  * Codex must receive `webpresso` over exactly one channel — the bundled Codex

package/dist/esm/hooks/pretool-guard/dev-routing.js

@@ -296,11 +296,11 @@ const SAFE_PASSTHROUGH_PREFIXES = [
 const SANDBOX_PREFIXES = [
     {
         prefix: "grep",
-        guidance: "Use wp_session_batch_execute for bounded shell gathering/search commands so output is capped, indexed, and recallable instead of flooding the transcript. If MCP is unavailable, use a bounded `rg -n ... | sed -n '1,120p'` excerpt instead of recursive raw grep output",
+        guidance: "Recursive/directory-wide grep is unbounded; narrow to explicit file target(s) (`grep -n pattern file`) to pass through directly. Otherwise use wp_session_batch_execute for bounded search so output is capped, indexed, and recallable instead of flooding the transcript — note wp_session_batch_execute runs argv directly (no shell) and cannot express `|`/`>`. If MCP is unavailable, use a bounded `rg -n ... | sed -n '1,120p'` excerpt instead of recursive raw grep output",
     },
     {
         prefix: "find",
-        guidance: "Use wp_session_batch_execute for bounded shell gathering/search commands so output is capped, indexed, and recallable instead of flooding the transcript. If MCP is unavailable, use `rg --files ... | sed -n '1,120p'` or another explicit bounded listing",
+        guidance: "Use wp_session_batch_execute for bounded shell gathering/search commands so output is capped, indexed, and recallable instead of flooding the transcript — note wp_session_batch_execute runs argv directly (no shell) and cannot express `|`/`>`. If MCP is unavailable, use `rg --files ... | sed -n '1,120p'` or another explicit bounded listing",
     },
     {
         prefix: "cat",
@@ -324,7 +324,7 @@ const SANDBOX_PREFIXES = [
     },
     {
         prefix: "git log",
-        guidance: "Use wp_session_batch_execute for bounded git log shell gathering so output is capped, indexed, and recallable. If MCP is unavailable, use explicit bounds such as `git log --oneline -n 50`",
+        guidance: "Add an explicit count bound (`-N`, `-n N`, or `--max-count=N`) to pass through directly — e.g. `git log --oneline -50`. Otherwise use wp_session_batch_execute for bounded git log shell gathering so output is capped, indexed, and recallable. If MCP is unavailable, use an explicit bound directly, e.g. `git log --oneline -n 50`",
     },
     {
         prefix: "git diff",
@@ -332,7 +332,7 @@ const SANDBOX_PREFIXES = [
     },
     {
         prefix: "git show",
-        guidance: "Use wp_session_batch_execute or wp_session_execute for bounded git show gathering instead of raw large output. If MCP is unavailable, use `git show --stat` or a targeted excerpt",
+        guidance: "Add `--stat`/`--name-only`/`--name-status`/`--shortstat` to pass through directly — e.g. `git show --stat HEAD` — or use wp_session_batch_execute or wp_session_execute for bounded gathering of the full patch",
     },
     {
         prefix: "vp run build",
@@ -782,6 +782,63 @@ const BOUNDED_GIT_DIFF = new RegExp(String.raw `^git\s+${SIMPLE_GIT_GLOBAL_OPTIO
 function isBoundedGitDiffRead(command) {
     return BOUNDED_GIT_DIFF.test(command);
 }
+// `git log`/`git show` reads are bounded (small, predictable output) exactly when
+// they carry an explicit count/summary bound the same way BOUNDED_GIT_DIFF already
+// recognizes `--stat`/`--name-only`/etc. as bounded. Unbounded forms (bare `git log`,
+// full-patch `git show <ref>`) still fall through to the SANDBOX_PREFIXES rules below.
+const SIMPLE_GIT_LOG_PREFIX = new RegExp(String.raw `^git\s+${SIMPLE_GIT_GLOBAL_OPTION}log\b`, "u");
+const GIT_LOG_COUNT_BOUND = /(?:^|\s)(?:-\d+|-n[=\s]?\d+|--max-count(?:=|\s+)\d+)(?:\s|$)/u;
+function isBoundedGitLogRead(command) {
+    return SIMPLE_GIT_LOG_PREFIX.test(command) && GIT_LOG_COUNT_BOUND.test(command);
+}
+const BOUNDED_GIT_SHOW = new RegExp(String.raw `^git\s+${SIMPLE_GIT_GLOBAL_OPTION}show\b(?=[\s\S]*(?:--stat\b|--shortstat\b|--name-only\b|--name-status\b))(?![\s\S]*(?:--patch\b|-p\b))`, "u");
+function isBoundedGitShowRead(command) {
+    return BOUNDED_GIT_SHOW.test(command);
+}
+// A grep read is bounded when it targets explicit file argument(s) (not a whole
+// directory tree via -r/-R/--recursive/--include/--exclude*) and supplies at least
+// one non-flag file target beyond the pattern itself. Recursive/directory-wide grep
+// stays sandboxed since its output size is unpredictable.
+const GREP_RECURSIVE_LONG_FLAGS = new Set([
+    "--recursive",
+    "--include",
+    "--exclude",
+    "--exclude-dir",
+    "--exclude-from",
+]);
+function isBoundedGrepRead(command) {
+    const tokens = tokenizeCommand(command);
+    if (tokens[0] !== "grep")
+        return false;
+    const positionals = [];
+    let optionsEnded = false;
+    for (let index = 1; index < tokens.length; index += 1) {
+        const token = tokens[index];
+        if (!token)
+            continue;
+        if (!optionsEnded && token === "--") {
+            optionsEnded = true;
+            continue;
+        }
+        if (!optionsEnded && token !== "-" && token.startsWith("-")) {
+            const longFlag = token.split("=")[0] ?? token;
+            if (GREP_RECURSIVE_LONG_FLAGS.has(longFlag))
+                return false;
+            // Strip a trailing bundled numeric argument (e.g. the `2` in `-rA2` for
+            // `-r -A 2`) before checking for a bundled `r`/`R` — otherwise a
+            // recursive short flag bundled with a value-taking flag like `-A`/`-B`/
+            // `-C`/`-m` slips past undetected.
+            const shortCluster = token.slice(1).replace(/\d+$/u, "");
+            if (/^[A-Za-z]+$/u.test(shortCluster) && /[rR]/u.test(shortCluster))
+                return false;
+            continue;
+        }
+        positionals.push(token);
+    }
+    // First positional is the search pattern; at least one more explicit file
+    // target is required to count as a bounded (non-stdin, non-directory) read.
+    return positionals.length >= 2;
+}
 function escapedRegexToken(value) {
     return value.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&");
 }
@@ -982,6 +1039,12 @@ export function routeCommand(command, _sessionId) {
     }
     if (isBoundedGitDiffRead(trimmed))
         return { action: { action: "passthrough" } };
+    if (isBoundedGitLogRead(trimmed))
+        return { action: { action: "passthrough" } };
+    if (isBoundedGitShowRead(trimmed))
+        return { action: { action: "passthrough" } };
+    if (isBoundedGrepRead(trimmed))
+        return { action: { action: "passthrough" } };
     // Explicit passthroughs (audits, safe git/nav commands)
     for (const prefix of PASSTHROUGH_PREFIXES) {
         if (matchesPrefix(trimmed, prefix))

package/dist/esm/hooks/pretool-guard/validators/worktree-discipline.js

@@ -850,7 +850,9 @@ const GIT_GLOBAL_RUN = `(?:-C\\s+${QUOTED_ARG}\\s+|-c\\s+${QUOTED_ARG}\\s+|--git
 // branch flags are allowed.
 const FORBIDDEN_SUBCOMMAND = "(commit\\b|switch\\b(?!\\s+(?:-h|--help)\\b)|checkout\\s+(?!--(?:\\s|$))(?:(?:\\S+\\s+)*)\\S|branch\\s+(?:(?!-|--)\\S|--track\\b|--no-track\\b|--create-reflog\\b|--force\\b|-f\\b|-c\\b|-C\\b|-m\\b|-M\\b))";
 const FORBIDDEN_OP = new RegExp(`\\bgit\\s+(${GIT_GLOBAL_RUN})${FORBIDDEN_SUBCOMMAND}`, "gu");
-const MAIN_OWNERSHIP_OP = new RegExp(`\\bgit\\s+(${GIT_GLOBAL_RUN})(switch\\b[^;&|(){}]*|checkout\\b[^;&|(){}]*|branch\\b[^;&|(){}]*|worktree\\s+add\\b[^;&|(){}]*)`, "gu");
+// Verb-only: deliberately does NOT slurp trailing arguments itself (see
+// mainOwnershipGitOps below for why a naive `[^;&|(){}]*` capture is unsafe).
+const MAIN_OWNERSHIP_VERB = new RegExp(`\\bgit\\s+(${GIT_GLOBAL_RUN})(switch\\b|checkout\\b|branch\\b|worktree\\s+add\\b)`, "gu");
 function labelFor(subcommand) {
     if (subcommand.startsWith("commit"))
         return "git commit";
@@ -958,12 +960,69 @@ function mainOwnershipLabel(words) {
         return "git worktree add main";
     return null;
 }
+/**
+ * Quote-aware segment bounds for `command`, split on the same unquoted
+ * `;&|(){}` control characters as {@link splitShellSegments} (kept in sync
+ * intentionally), but returning OFFSETS instead of trimmed substrings so a
+ * caller can slice the original command text for a match that falls inside a
+ * given segment.
+ */
+function segmentBounds(command) {
+    const bounds = [];
+    let start = 0;
+    let quote = null;
+    let escaped = false;
+    for (let i = 0; i < command.length; i += 1) {
+        const ch = command[i];
+        if (ch === undefined)
+            continue;
+        if (escaped) {
+            escaped = false;
+            continue;
+        }
+        if (quote !== "'" && ch === "\\") {
+            escaped = true;
+            continue;
+        }
+        if ((ch === '"' || ch === "'") && (quote === null || quote === ch)) {
+            quote = quote === ch ? null : ch;
+            continue;
+        }
+        if (!quote && /[;&|(){}]/u.test(ch)) {
+            bounds.push({ start, end: i });
+            start = i + 1;
+        }
+    }
+    bounds.push({ start, end: command.length });
+    return bounds;
+}
+/**
+ * Main-ownership candidate ops (`git switch|checkout|branch|worktree add`).
+ *
+ * MAIN_OWNERSHIP_VERB intentionally does NOT slurp trailing arguments itself
+ * (unlike the pre-fix implementation) — a naive `[^;&|(){}]*` character class
+ * is not quote-aware, so a read-only `git branch --format='%(refname:short)'`
+ * has its captured subcommand text truncated mid-quote at the `(` inside the
+ * quoted format string, producing an unterminated quote that shellWords()
+ * reports as "ambiguous" and gets fail-closed blocked — purely because of a
+ * paren inside its OWN quoted argument, not because it mutates anything.
+ * Bounding the subcommand text to the enclosing quote-aware shell segment
+ * (segmentBounds, sharing splitShellSegments' control-char set) fixes that
+ * without weakening real-mutation detection: genuinely ambiguous syntax
+ * (nested shells, unresolved substitutions, unterminated quotes) still
+ * produces "ambiguous" and fails closed exactly as before.
+ */
 function mainOwnershipGitOps(command) {
     if (!/\bgit\b/u.test(command))
         return [];
     const ops = [];
-    for (const m of command.matchAll(MAIN_OWNERSHIP_OP)) {
-        const subcommand = m[2] ?? "";
+    const segments = segmentBounds(command);
+    for (const m of command.matchAll(MAIN_OWNERSHIP_VERB)) {
+        const verb = m[2] ?? "";
+        const verbStart = (m.index ?? 0) + m[0].length - verb.length;
+        const segment = segments.find((s) => verbStart >= s.start && verbStart < s.end) ??
+            { start: verbStart, end: command.length };
+        const subcommand = command.slice(verbStart, segment.end);
         const words = shellWords(subcommand);
         if (words === "ambiguous") {
             ops.push({ label: "git main", globals: m[1] ?? "", index: m.index ?? 0 });

package/dist/esm/mcp/blueprint/_shared/lifecycle.d.ts

@@ -1,5 +1,18 @@
 export declare const ALL_BLUEPRINT_STATES: readonly ["draft", "planned", "in-progress", "parked", "archived", "completed"];
 export declare const NON_COMPLETED_BLUEPRINT_STATES: readonly ["draft", "planned", "in-progress", "parked", "archived"];
+/**
+ * Collect every reason "${slug}" cannot move to `completed`, without
+ * stopping at the first one: zero-task / unfinished-task blockers, missing
+ * task-local evidence per done task, `runValidate` document gaps, and the
+ * completed approval/digest gate. Callers that need to report every
+ * blocking condition in a single response (e.g. `wp_blueprint_finalize`)
+ * use this directly, before attempting any external side effect (platform
+ * sync) or local move — so a refusal never fires mid-move and a caller
+ * fixing issues one at a time never needs one failed round-trip per
+ * condition. {@link assertBlueprintCanComplete} throws the same combined
+ * message for callers that only need a single throw.
+ */
+export declare function collectBlueprintCompletionBlockers(overviewPath: string, slug: string): string[];
 export declare function assertBlueprintCanComplete(overviewPath: string, slug: string): void;
 export declare function applyLocalBlueprintTransition(input: {
     projectCwd: string;

package/dist/esm/mcp/blueprint/_shared/lifecycle.js

@@ -6,7 +6,7 @@ import { setBlueprintFrontmatterFields } from "#lifecycle/engine";
 import { assertCompletedApprovalGate, evaluateApprovalGate, formatApprovalGateRequirement, } from "#lifecycle/audit";
 import { resolveBlueprintRoot } from "#utils/blueprint-root.js";
 import { getBlueprintDocumentPaths } from "#utils/document-paths.js";
-import { assertAllTasksHaveCanonicalPassingEvidence } from "#verification.js";
+import { collectMissingCanonicalPassingEvidence } from "#verification.js";
 import { writeFileAtomic } from "#shared-utils/write-json-file.js";
 import { applyPromotionTrustGate } from "#trust/promotion.js";
 import { reIngest } from "#mcp/blueprint/_shared/db";
@@ -34,18 +34,50 @@ function formatBlueprintProgress(totalTasks, doneTasks, blockedTasks) {
     const percent = totalTasks === 0 ? 0 : Math.round((doneTasks / totalTasks) * 100);
     return `${percent}% (${doneTasks}/${totalTasks} tasks done, ${blockedTasks} blocked, updated ${todayIsoDate()})`;
 }
-export function assertBlueprintCanComplete(overviewPath, slug) {
+/**
+ * Collect every reason "${slug}" cannot move to `completed`, without
+ * stopping at the first one: zero-task / unfinished-task blockers, missing
+ * task-local evidence per done task, `runValidate` document gaps, and the
+ * completed approval/digest gate. Callers that need to report every
+ * blocking condition in a single response (e.g. `wp_blueprint_finalize`)
+ * use this directly, before attempting any external side effect (platform
+ * sync) or local move — so a refusal never fires mid-move and a caller
+ * fixing issues one at a time never needs one failed round-trip per
+ * condition. {@link assertBlueprintCanComplete} throws the same combined
+ * message for callers that only need a single throw.
+ */
+export function collectBlueprintCompletionBlockers(overviewPath, slug) {
+    const blockers = [];
     const markdown = readFileSync(overviewPath, "utf8");
     const blueprint = parseBlueprint(markdown, slug);
     if (blueprint.tasks.length === 0) {
-        throw new Error(`Cannot complete "${slug}": zero-task blueprints cannot move to completed through the public lifecycle surface`);
+        blockers.push(`Cannot complete "${slug}": zero-task blueprints cannot move to completed through the public lifecycle surface`);
+    }
+    else {
+        const unfinished = blueprint.tasks.filter((task) => task.status !== "done" && task.status !== "dropped");
+        if (unfinished.length > 0) {
+            const list = unfinished.map((task) => `${task.id} (${task.status})`).join(", ");
+            blockers.push(`Cannot complete "${slug}": the following tasks are not done: ${list}`);
+        }
+        blockers.push(...collectMissingCanonicalPassingEvidence(markdown, blueprint.tasks.filter((task) => task.status !== "dropped").map((task) => task.id)));
+    }
+    const validated = runValidate(overviewPath);
+    if (!validated.valid) {
+        blockers.push(...validated.gaps.map((gap) => `Cannot complete "${slug}": ${gap}`));
+    }
+    try {
+        assertCompletedApprovalGate(overviewPath, markdown);
+    }
+    catch (error) {
+        blockers.push(`Cannot complete "${slug}": ${error instanceof Error ? error.message : String(error)}`);
     }
-    const unfinished = blueprint.tasks.filter((task) => task.status !== "done" && task.status !== "dropped");
-    if (unfinished.length > 0) {
-        const list = unfinished.map((task) => `${task.id} (${task.status})`).join(", ");
-        throw new Error(`Cannot complete "${slug}": the following tasks are not done: ${list}`);
+    return blockers;
+}
+export function assertBlueprintCanComplete(overviewPath, slug) {
+    const blockers = collectBlueprintCompletionBlockers(overviewPath, slug);
+    if (blockers.length > 0) {
+        throw new Error(blockers.join("; "));
     }
-    assertAllTasksHaveCanonicalPassingEvidence(markdown, blueprint.tasks.filter((task) => task.status !== "dropped").map((task) => task.id));
 }
 export async function applyLocalBlueprintTransition(input) {
     const { projectCwd, slug, to_state, found, trustedMarkdown: preflightTrustedMarkdown } = input;