@webpresso/agent-kit 3.3.4 → 3.3.6

package/dist/esm/audit/agents.js

@@ -1,20 +1,13 @@
 import { existsSync, lstatSync, readFileSync, readdirSync, readlinkSync } from "node:fs";
 import { basename, dirname, join, relative, resolve } from "node:path";
 import { readConfig } from "#cli/commands/init/config";
-import { DEFAULT_PACKAGED_SKILL_SLUG_SET } from "#content/skill-policy";
+import { AGENT_KIT_INTERNAL_SKILL_SLUGS, DEFAULT_PACKAGED_SKILL_SLUG_SET, DEFAULT_PACKAGED_SKILL_SLUGS, MERGED_DELETED_SKILL_SLUGS, UNPACKAGED_SKILL_SLUGS, } from "#content/skill-policy";
 import { readTrustedJsonFile } from "#shared-utils/read-json-file.js";
 import matter from "gray-matter";
 import { WP_HOOK_SPECS } from "#cli/commands/init/scaffolders/agent-hooks/ir.js";
 const REQUIRED_HOOKS = WP_HOOK_SPECS.map(({ event, bin }) => ({ event, bin }));
 const CLAUDE_SETTINGS_PATH = ".claude/settings.json";
 const CODEX_HOOKS_PATH = ".codex/hooks.json";
-const REQUIRED_SUBAGENTS = [
-    "code-reviewer.md",
-    "security-auditor.md",
-    "doc-writer.md",
-    "explorer.md",
-    "implementer.md",
-];
 const EXPLORER_CONTRACT_MARKERS = [
     "3–5 tool calls",
     "Defs:",
@@ -54,6 +47,10 @@ export function auditAgents(rootDirectory = process.cwd()) {
         checkCatalogAgents(root, violations);
         checked += 1;
         checkCatalogReportOnlySkills(root, violations);
+        checked += 1;
+        checkSelfHostClaudeAgents(root, violations);
+        checked += 1;
+        checkCatalogSkillClassification(root, violations);
     }
     else {
         checked += 1;
@@ -117,6 +114,19 @@ function checkCatalogSkillHooks(root, violations) {
         }
     }
 }
+/**
+ * List the `.md` filenames (e.g. "code-reviewer.md") directly under a
+ * catalog/agent/agents-shaped directory, excluding README.md. Returns an
+ * empty array when the directory does not exist. This is the single source
+ * of truth for "which subagents are required" — no hardcoded list.
+ */
+function listCatalogAgentFiles(agentsSourceDir) {
+    if (!existsSync(agentsSourceDir))
+        return [];
+    return readdirSync(agentsSourceDir)
+        .filter((file) => file.endsWith(".md") && file !== "README.md")
+        .sort();
+}
 function checkCatalogAgents(root, violations) {
     const agentsSource = join(root, "catalog", "agent", "agents");
     if (!existsSync(agentsSource)) {
@@ -126,28 +136,44 @@ function checkCatalogAgents(root, violations) {
         });
         return;
     }
-    for (const file of REQUIRED_SUBAGENTS) {
+    const requiredFiles = listCatalogAgentFiles(agentsSource);
+    if (requiredFiles.length === 0) {
+        violations.push({
+            file: "catalog/agent/agents",
+            message: "catalog/agent/agents must contain canonical subagent markdown files.",
+        });
+        return;
+    }
+    for (const file of requiredFiles) {
+        if (file !== "explorer.md")
+            continue;
         const sourcePath = join(agentsSource, file);
-        if (!existsSync(sourcePath)) {
+        const content = readFileSync(sourcePath, "utf8");
+        for (const marker of EXPLORER_CONTRACT_MARKERS) {
+            if (content.includes(marker))
+                continue;
             violations.push({
                 file: relative(root, sourcePath),
-                message: `Missing canonical subagent ${file} in catalog/agent/agents.`,
+                message: `Explorer subagent output contract is missing marker: ${marker}`,
             });
-            continue;
-        }
-        if (file === "explorer.md") {
-            const content = readFileSync(sourcePath, "utf8");
-            for (const marker of EXPLORER_CONTRACT_MARKERS) {
-                if (content.includes(marker))
-                    continue;
-                violations.push({
-                    file: relative(root, sourcePath),
-                    message: `Explorer subagent output contract is missing marker: ${marker}`,
-                });
-            }
         }
     }
 }
+/**
+ * Self-host-only: validate `.claude/agents/` (this repo's own generated
+ * projection) the same way a consumer's `.claude/agents/` is validated.
+ * Absent is acceptable — the surface is generated + gitignored in a clean
+ * checkout — but when present, every catalog-required subagent must resolve
+ * to a live symlink.
+ */
+function checkSelfHostClaudeAgents(root, violations) {
+    const agentsTarget = join(root, ".claude", "agents");
+    if (!existsSync(agentsTarget))
+        return;
+    const agentsSource = join(root, "catalog", "agent", "agents");
+    const requiredFiles = listCatalogAgentFiles(agentsSource);
+    validateClaudeAgentSymlinks(root, agentsTarget, requiredFiles, violations);
+}
 function checkCatalogReportOnlySkills(root, violations) {
     const skillsSource = join(root, "catalog", "agent", "skills");
     if (!existsSync(skillsSource)) {
@@ -193,6 +219,63 @@ function checkCatalogReportOnlySkills(root, violations) {
         }
     }
 }
+/**
+ * Resolve the required subagent file list for a consumer repo. Preferred
+ * source: the installed catalog under node_modules (the real consumer-mode
+ * source of truth that `.claude/agents/*.md` symlinks point at). When
+ * node_modules is not installed (e.g. a partial checkout), fall back to
+ * whatever `.claude/agents/*.md` already exists so symlink-health checks
+ * still run without false-positiving "missing" for agents we have no
+ * catalog reference for.
+ */
+function resolveConsumerRequiredAgentFiles(root) {
+    const installedAgentsSource = join(root, "node_modules", "@webpresso", "agent-kit", "catalog", "agent", "agents");
+    const fromInstalled = listCatalogAgentFiles(installedAgentsSource);
+    if (fromInstalled.length > 0)
+        return fromInstalled;
+    const agentsTarget = join(root, ".claude", "agents");
+    if (!existsSync(agentsTarget))
+        return [];
+    // Restrict to symlinks only — a hand-authored real file (Claude Code's
+    // native subagent authoring surface) is never agent-kit-managed and must
+    // not be false-flagged as "must remain a symlink" just because node_modules
+    // isn't installed to prove otherwise.
+    return readdirSync(agentsTarget)
+        .filter((file) => file.endsWith(".md") && lstatSync(join(agentsTarget, file)).isSymbolicLink())
+        .sort();
+}
+/**
+ * Every catalog skill slug must be accounted for as either default-packaged,
+ * explicitly unpackaged (with a reason), merged/deleted, or an
+ * agent-kit-internal maintainer-only skill. An unclassified slug is a
+ * violation — it means a new catalog skill was added without a deliberate
+ * packaging decision.
+ */
+function checkCatalogSkillClassification(root, violations) {
+    const skillsSource = join(root, "catalog", "agent", "skills");
+    if (!existsSync(skillsSource))
+        return; // reported by checkCatalogReportOnlySkills
+    const knownSlugs = new Set([
+        ...DEFAULT_PACKAGED_SKILL_SLUGS,
+        ...Object.keys(UNPACKAGED_SKILL_SLUGS),
+        ...MERGED_DELETED_SKILL_SLUGS,
+        ...AGENT_KIT_INTERNAL_SKILL_SLUGS,
+    ]);
+    for (const entry of readdirSync(skillsSource, { withFileTypes: true })) {
+        if (!entry.isDirectory())
+            continue;
+        if (!existsSync(join(skillsSource, entry.name, "SKILL.md")))
+            continue;
+        if (knownSlugs.has(entry.name))
+            continue;
+        violations.push({
+            file: `catalog/agent/skills/${entry.name}/SKILL.md`,
+            message: `Skill "${entry.name}" is not classified as packaged or unpackaged. Add it to ` +
+                "DEFAULT_PACKAGED_SKILL_SLUGS or UNPACKAGED_SKILL_SLUGS in src/content/skill-policy.ts " +
+                "with a one-line reason.",
+        });
+    }
+}
 function checkClaudeAgents(root, violations) {
     const agentsTarget = join(root, ".claude", "agents");
     if (!existsSync(agentsTarget)) {
@@ -202,16 +285,33 @@ function checkClaudeAgents(root, violations) {
         });
         return;
     }
-    for (const file of REQUIRED_SUBAGENTS) {
+    const requiredFiles = resolveConsumerRequiredAgentFiles(root);
+    validateClaudeAgentSymlinks(root, agentsTarget, requiredFiles, violations);
+}
+/**
+ * Shared per-file symlink validator for `.claude/agents/<file>`, used by both
+ * the self-host and consumer audit paths. Checks: missing entry, not a
+ * symlink, wrong/unrecognized target, and dangling target.
+ */
+function validateClaudeAgentSymlinks(root, agentsTarget, requiredFiles, violations) {
+    for (const file of requiredFiles) {
         const targetPath = join(agentsTarget, file);
-        if (!existsSync(targetPath)) {
+        // lstatSync (not existsSync) so a dangling symlink — an entry that
+        // exists but resolves to nothing — is distinguished from a genuinely
+        // missing entry. existsSync follows symlinks, so it would misreport
+        // every dangling symlink as "missing" and the dangling check below
+        // would never be reachable.
+        let stat;
+        try {
+            stat = lstatSync(targetPath);
+        }
+        catch {
             violations.push({
                 file: relative(root, targetPath),
                 message: `Missing Claude subagent ${file}. Run \`wp setup\` to re-sync canonical subagents.`,
             });
             continue;
         }
-        const stat = lstatSync(targetPath);
         if (!stat.isSymbolicLink()) {
             violations.push({
                 file: relative(root, targetPath),

package/dist/esm/blueprint/trust/dossier.js

@@ -39,8 +39,15 @@ export function parseTrustDossier(markdown) {
     const gates = parsePromotionGatesTable(requiredBlock(blocks, "Promotion Gates"), violations);
     const residualUnknowns = requiredBlock(blocks, "Residual Unknowns").trim();
     for (const [section, block] of blocks) {
-        if (containsPlaceholder(block))
+        const fields = findPlaceholderFields(block);
+        if (fields.length > 0) {
+            for (const field of fields) {
+                violations.push({ section, message: `placeholder value not filled in: ${field}` });
+            }
+        }
+        else if (containsPlaceholder(block)) {
             violations.push({ section, message: "placeholder values are not allowed" });
+        }
     }
     if (violations.length > 0 || readiness === null)
         return { violations };
@@ -181,6 +188,39 @@ function splitRow(row) {
 function containsPlaceholder(value) {
     return /<[^>]+>|\bTBD\b|\bTODO\b/u.test(value);
 }
+// Names the specific field(s) inside a Trust Dossier subsection block that
+// still carry a scaffold placeholder, instead of only flagging the section as
+// a whole. Covers both shapes the dossier uses: `- key: value` list lines
+// (Readiness Verdict) and markdown table rows (Material Claims/Decisions,
+// Promotion Gates). Free-text sections (Residual Unknowns) have no named
+// field to point at, so the caller falls back to the whole-section message
+// when this returns an empty array.
+function findPlaceholderFields(block) {
+    const fields = [];
+    for (const line of block.split("\n")) {
+        const match = /^-\s*([^:]+):\s*(.+?)\s*$/u.exec(line.trim());
+        if (match && containsPlaceholder(match[2] ?? ""))
+            fields.push(match[1].trim());
+    }
+    const rows = block
+        .split("\n")
+        .map((line) => line.trim())
+        .filter((line) => line.startsWith("|") && line.endsWith("|"));
+    if (rows.length >= 2) {
+        const header = splitRow(rows[0] ?? "");
+        for (const row of rows.slice(2)) {
+            const cells = splitRow(row);
+            for (const [index, cell] of cells.entries()) {
+                if (!containsPlaceholder(cell))
+                    continue;
+                const columnName = header[index] ?? `column ${index + 1}`;
+                const rowId = cells[0] ? ` (row ${cells[0]})` : "";
+                fields.push(`${columnName}${rowId}`);
+            }
+        }
+    }
+    return fields;
+}
 function escapeRegExp(value) {
     return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }

package/dist/esm/blueprint/verification.d.ts

@@ -110,6 +110,17 @@ export declare function readTaskVerification(markdown: string, taskId: string):
  */
 export declare function assertTaskHasCanonicalPassingEvidence(markdown: string, taskId: string): readonly Evidence[];
 /**
- * Assert that each supplied task id has task-local canonical passing evidence.
+ * Collect a failure message for every supplied task id that is missing
+ * task-local canonical passing evidence, instead of stopping at the first
+ * one. Callers that need to report every blocking condition in a single
+ * response (e.g. `wp_blueprint_finalize`) use this directly; callers that
+ * only need a single throw use {@link assertAllTasksHaveCanonicalPassingEvidence}.
+ */
+export declare function collectMissingCanonicalPassingEvidence(markdown: string, taskIds: readonly string[]): string[];
+/**
+ * Assert that each supplied task id has task-local canonical passing
+ * evidence. Throws once with every failing task's message joined, rather
+ * than stopping at the first failure — a caller fixing one issue at a time
+ * would otherwise need one failed round-trip per missing-evidence task.
  */
 export declare function assertAllTasksHaveCanonicalPassingEvidence(markdown: string, taskIds: readonly string[]): void;

package/dist/esm/blueprint/verification.js

@@ -173,11 +173,34 @@ export function assertTaskHasCanonicalPassingEvidence(markdown, taskId) {
     return evidence;
 }
 /**
- * Assert that each supplied task id has task-local canonical passing evidence.
+ * Collect a failure message for every supplied task id that is missing
+ * task-local canonical passing evidence, instead of stopping at the first
+ * one. Callers that need to report every blocking condition in a single
+ * response (e.g. `wp_blueprint_finalize`) use this directly; callers that
+ * only need a single throw use {@link assertAllTasksHaveCanonicalPassingEvidence}.
  */
-export function assertAllTasksHaveCanonicalPassingEvidence(markdown, taskIds) {
+export function collectMissingCanonicalPassingEvidence(markdown, taskIds) {
+    const failures = [];
     for (const taskId of taskIds) {
-        assertTaskHasCanonicalPassingEvidence(markdown, taskId);
+        try {
+            assertTaskHasCanonicalPassingEvidence(markdown, taskId);
+        }
+        catch (error) {
+            failures.push(error instanceof Error ? error.message : String(error));
+        }
+    }
+    return failures;
+}
+/**
+ * Assert that each supplied task id has task-local canonical passing
+ * evidence. Throws once with every failing task's message joined, rather
+ * than stopping at the first failure — a caller fixing one issue at a time
+ * would otherwise need one failed round-trip per missing-evidence task.
+ */
+export function assertAllTasksHaveCanonicalPassingEvidence(markdown, taskIds) {
+    const failures = collectMissingCanonicalPassingEvidence(markdown, taskIds);
+    if (failures.length > 0) {
+        throw new Error(failures.join("; "));
     }
 }
 // ---------------------------------------------------------------------------

package/dist/esm/build/vendor-oxlint-plugins.d.ts

@@ -1,7 +1,10 @@
 #!/usr/bin/env bun
 export declare const AGENT_CONFIG_OXLINT_DIST: string;
 export declare const AGENT_KIT_OXLINT_DIST: string;
-/** Plugin basenames that ship as sibling .js next to oxlintrc.json (not path-roles). */
+/**
+ * Plugin basenames that ship as sibling .js next to oxlintrc.json (not path-roles).
+ * SSOT: `@webpresso/agent-config/oxlint/basenames`.
+ */
 export declare const VENDOR_PLUGIN_BASENAMES: readonly ["code-safety", "foundation-purity", "graphql-conventions", "import-hygiene", "monorepo-paths", "query-patterns", "testing-quality", "tier-boundaries"];
 export declare function vendorOxlintPlugins(sourceDir?: string, destDir?: string): {
     copied: string[];

package/dist/esm/build/vendor-oxlint-plugins.js

@@ -9,19 +9,14 @@
  */
 import { cpSync, existsSync, mkdirSync } from "node:fs";
 import { join } from "node:path";
+import { OXLINT_PATH_ROLES_BASENAME, OXLINT_POLICY_PLUGIN_BASENAMES, } from "@webpresso/agent-config/oxlint/basenames";
 export const AGENT_CONFIG_OXLINT_DIST = join(process.cwd(), "packages/agent-config/dist/esm/oxlint");
 export const AGENT_KIT_OXLINT_DIST = join(process.cwd(), "dist/esm/config/oxlint");
-/** Plugin basenames that ship as sibling .js next to oxlintrc.json (not path-roles). */
-export const VENDOR_PLUGIN_BASENAMES = [
-    "code-safety",
-    "foundation-purity",
-    "graphql-conventions",
-    "import-hygiene",
-    "monorepo-paths",
-    "query-patterns",
-    "testing-quality",
-    "tier-boundaries",
-];
+/**
+ * Plugin basenames that ship as sibling .js next to oxlintrc.json (not path-roles).
+ * SSOT: `@webpresso/agent-config/oxlint/basenames`.
+ */
+export const VENDOR_PLUGIN_BASENAMES = OXLINT_POLICY_PLUGIN_BASENAMES;
 export function vendorOxlintPlugins(sourceDir = AGENT_CONFIG_OXLINT_DIST, destDir = AGENT_KIT_OXLINT_DIST) {
     if (!existsSync(sourceDir)) {
         throw new Error(`vendor-oxlint-plugins: missing agent-config oxlint dist at ${sourceDir}. Build @webpresso/agent-config first.`);
@@ -39,12 +34,12 @@ export function vendorOxlintPlugins(sourceDir = AGENT_CONFIG_OXLINT_DIST, destDi
         // path-roles is imported by several plugins as a sibling — vendor it too.
     }
     // Always vendor path-roles (shared classifier used via relative imports inside plugins).
-    const pathRoles = join(sourceDir, "path-roles.js");
+    const pathRoles = join(sourceDir, `${OXLINT_PATH_ROLES_BASENAME}.js`);
     if (!existsSync(pathRoles)) {
         throw new Error(`vendor-oxlint-plugins: missing ${pathRoles}`);
     }
-    cpSync(pathRoles, join(destDir, "path-roles.js"));
-    copied.push("path-roles");
+    cpSync(pathRoles, join(destDir, `${OXLINT_PATH_ROLES_BASENAME}.js`));
+    copied.push(OXLINT_PATH_ROLES_BASENAME);
     return { copied };
 }
 if (import.meta.main) {

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

@@ -61,7 +61,6 @@ import { ensureOpenCodeWebpressoPlugin } from "./scaffolders/opencode-plugin/ind
 import { ensureGrokWebpressoMcp } from "./scaffolders/grok-mcp/index.js";
 import { ensureRtk } from "./scaffolders/rtk/index.js";
 import { checkRuntimes } from "./scaffolders/runtime-check/index.js";
-import { scaffoldSubagents } from "./scaffolders/subagents/index.js";
 import { maybeRunVisionInterview } from "./scaffolders/vision/interview.js";
 import { scaffoldVision } from "./scaffolders/vision/index.js";
 import { scaffoldWorkspaceConfig } from "./scaffolders/workspace-config/index.js";
@@ -1333,7 +1332,7 @@ export async function runInit(flags, deps = {}) {
             runUnifiedSync({
                 catalogDir: join(catalogDir, "agent"),
                 consumerRoot: consumer.repoRoot,
-                kinds: ["rule", "skill"],
+                kinds: ["rule", "skill", "agent"],
                 check: false,
                 allowedSkillSlugs,
                 hosts: selectedHosts,
@@ -1484,7 +1483,8 @@ export async function runInit(flags, deps = {}) {
             }
             throw error;
         }
-        const subagentResults = scaffoldSubagents({ repoRoot: consumer.repoRoot, options });
+        // Canonical subagents (.claude/agents/) are projected by the unified sync
+        // call above (kinds includes "agent") — no standalone scaffolder here.
         // Generated host instructions (AGENTS.md) are a tier-1 (guarded/full)
         // surface; the tier-0 quality profile omits them.
         // Base-kit may have created or updated package metadata earlier in this
@@ -1853,7 +1853,6 @@ export async function runInit(flags, deps = {}) {
                 ]
                 : []),
             ...claudeRulesResults,
-            ...subagentResults,
             ...presetResults,
         ];
         const summary = summarizeResults(all);

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

@@ -209,7 +209,11 @@ export function ensureGuardrailsCiStep(content, repoAlreadyWired = false) {
     // Safe: anchorStepStart is an index returned by findLiveTestRunAnchor over
     // this same content.split("\n"), so it is always within lines' bounds here.
     const indent = lines[anchorStepStart].match(/^(\s*)/u)?.[1] ?? "";
-    lines.splice(anchorStepStart, 0, `${indent}- name: Run wp audit guardrails`, `${indent}  run: wp audit guardrails`);
+    // continue-on-error: true matches framework quality.yml and keeps
+    // ci-guardrails-wiring green without hard-failing thin consumers on
+    // agent-kit dogfood audits (command-surface, etc.) or known suite debt.
+    // Explicit hard-fail audits remain separate workflow steps.
+    lines.splice(anchorStepStart, 0, `${indent}- name: Run wp audit guardrails`, `${indent}  continue-on-error: true`, `${indent}  run: wp audit guardrails`);
     return lines.join("\n");
 }
 function migrateConsumerWorkflows(repoRoot, actionRef, version, options) {

package/dist/esm/cli/commands/mcp.js

@@ -6,6 +6,8 @@ export const MCP_COMMAND_HELP = [
     "by a Claude Code plugin manifest entry (`mcpServers.webpresso`) or any MCP",
     "client. Tools are auto-discovered from `dist/esm/mcp/tools/*.js`.",
     "",
+    "No subcommands are supported; use `wp review gate` for review workflows.",
+    "",
     "Examples:",
     "  wp mcp",
 ].join("\n");

package/dist/esm/cli/commands/review.d.ts

@@ -220,6 +220,7 @@ export interface ReviewGateDependencies {
      */
     readonly prepareOpencodeCredential?: (account: OpencodeAccount) => string;
 }
+export declare function describeVerificationFailure(verification: ReviewGateVerification | undefined, gateId: string): string;
 /**
  * Sanctioned fallback when `wp review gate` does not reach "approved" — points
  * at the tracked-provenance path (`wp review log` / `wp_blueprint_review_log`)

package/dist/esm/cli/commands/review.js

@@ -28,6 +28,7 @@ import { isPolicyApprovalVerdict } from "#review/verdict.js";
 import { verificationArtifactSection, verificationPromptSummary, verifyDeliveryPromotionGates, } from "#review/delivery-verifier.js";
 import { createDeliverySubjectAtRef, createPlanSubjectAtRef, findUnreviewedWorkingTreeChanges, } from "#review/subject.js";
 import { runCommand } from "#mcp/tools/_shared/run-command.js";
+import { ALLOWED_WP_COMMAND_TIMEOUT_MS } from "#trust/command-runner.js";
 import { NotInGitRepoError, withLock } from "#paths/state-root.js";
 import { writeFileAtomic, writeJsonFileAtomic } from "#shared-utils/write-json-file.js";
 export const REVIEWER_IDS = [
@@ -1844,6 +1845,64 @@ function selectGateProviders(input) {
     const available = ordered.filter((provider) => !isProviderSuppressed(input.availability, provider));
     return available.length > 0 ? available : [];
 }
+// Builds the `message` for a "verification-failed" gate result: host-side
+// verification (delivery Promotion Gates + Trust Dossier parsing) died before
+// any review provider ran, so `attempts` is empty and the default
+// approval-gate-template message ("Approval gate not satisfied (...)") reads
+// like a reviewer rejected the work when no reviewer was ever invoked. Names
+// the actual cause and the corrective action so a failed gate does not cost
+// a repeat run just to discover what happened. Exported for tests.
+export function describeVerificationFailure(verification, gateId) {
+    const resume = `Retry with --resume ${gateId} once fixed.`;
+    const preamble = "Host verification failed before any review provider ran (0 review attempts) -- this is not a provider/quota failure.";
+    if (!verification || verification.status !== "failed") {
+        return `${preamble} ${resume}`;
+    }
+    if (verification.failureCode === "malformed-trust-dossier") {
+        const fields = (verification.violations ?? [])
+            .map((violation) => `${violation.section}: ${violation.message}`)
+            .join("; ");
+        return `${preamble} The Trust Dossier is malformed${fields ? ` (${fields})` : ""}. Fill in the named field(s) via wp_blueprint_put (or wp blueprint promote to see the same detail) before gating again. ${resume}`;
+    }
+    const failedCommand = verification.commands.find((command) => command.outcome !== "passed");
+    if (verification.failureCode === "command-timed-out" && failedCommand) {
+        const budgetSeconds = ALLOWED_WP_COMMAND_TIMEOUT_MS / 1000;
+        return (`${preamble} The Promotion Gate command \`${failedCommand.command}\` exceeded the ` +
+            `${budgetSeconds}s sandboxed gate budget and was killed -- this is a fixed per-command ` +
+            "budget, not a live outage, and raising it is not the fix. Either replace this gate with " +
+            "a faster command (e.g. `wp lint`, or a narrow `wp audit <kind>`), or mark this Promotion " +
+            'Gates row `defer: "pre-implementation"` so it is recorded without being executed at gate ' +
+            `time. ${resume}`);
+    }
+    if (failedCommand) {
+        const exitDetail = failedCommand.exitCode === null ? "no exit code" : `exit ${failedCommand.exitCode}`;
+        const logDetail = verification.logPath ? ` Log: ${verification.logPath}.` : "";
+        return (`${preamble} Gate command \`${failedCommand.command}\` failed (${exitDetail}, ` +
+            `outcome: ${failedCommand.outcome}).${logDetail} This is usually a missing dependency or ` +
+            "stale install in the sandboxed checkout -- run the repo's install command " +
+            `(e.g. \`wp install\`) and retry. ${resume}`);
+    }
+    const codeDetail = verification.failureCode ? ` (failureCode: ${verification.failureCode})` : "";
+    return `${preamble} Verification failed${codeDetail} before any gate command ran. ${resume}`;
+}
+// Human-readable summary of why every candidate provider/reviewer is
+// currently suppressed in the project's availability.json cache, so a
+// zero-candidate gate result names the file and the reason instead of
+// looking like a silent no-op.
+function describeSuppressedCandidates(availability, candidates) {
+    return candidates
+        .map((provider) => {
+        const record = availability.providers[provider];
+        if (!record?.suppressed)
+            return undefined;
+        const reason = record.suppressionReason ?? record.terminalClassification ?? "unknown reason";
+        const since = record.suppressedAt ? ` since ${record.suppressedAt}` : "";
+        const retry = record.retryAfterMs === undefined ? "" : ` (retry window ${record.retryAfterMs}ms)`;
+        return `${provider}: suppressed${since} (${reason}${retry})`;
+    })
+        .filter((value) => value !== undefined)
+        .join("; ");
+}
 function safeArtifactPath(blueprintPath, relativeArtifact) {
     if (path.isAbsolute(relativeArtifact) || relativeArtifact.split(/[\\/]/u).includes("..")) {
         throw new Error(`Unsafe review artifact path: ${relativeArtifact}`);
@@ -2225,7 +2284,7 @@ export async function runReviewGate(projectRoot, slug, input, dependencies = { i
                     prompt = renderPrompt(summary);
                 }
                 if (verification?.status === "failed") {
-                    const result = makeResult(currentApprovalGate(), "verification-failed");
+                    const result = makeResult(currentApprovalGate(), "verification-failed", describeVerificationFailure(verification, gateId));
                     assertReviewRefUnchanged(projectRoot, input.target ?? "HEAD", targetSha);
                     persistGateState(projectRoot, result);
                     cleanupSharedCheckout();
@@ -2297,6 +2356,23 @@ export async function runReviewGate(projectRoot, slug, input, dependencies = { i
                 availability,
                 ...(explicitProvider ? { explicitProvider } : {}),
             });
+            if (providerQueue.length === 0) {
+                const candidates = hostNeutralProviderOrder(explicitProvider);
+                const detail = describeSuppressedCandidates(availability, candidates);
+                const availabilityFile = path
+                    .relative(projectRoot, reviewAvailabilityPath(projectRoot))
+                    .replace(/\\/gu, "/");
+                const result = makeResult(approvalGate, "needs-review", `No review provider was invoked: every candidate provider is suppressed by the ` +
+                    `cached availability record at ${availabilityFile}${detail ? ` (${detail})` : ""}. ` +
+                    "This is a stale-cache condition, not a live provider outage -- if the " +
+                    "account/provider has since recovered or been re-authenticated, delete the stale " +
+                    `entry (or the whole file) at ${availabilityFile}, or wait for its suppression ` +
+                    `window to elapse, then retry with --resume ${gateId}.`);
+                assertReviewRefUnchanged(projectRoot, input.target ?? "HEAD", targetSha);
+                persistGateState(projectRoot, result);
+                cleanupSharedCheckout();
+                return result;
+            }
             const usedReviewers = new Set([
                 ...attempts
                     .filter((attempt) => !isRetryableGateAttempt(attempt))

package/dist/esm/cli/commands/sync.d.ts

@@ -1,16 +1,18 @@
 /**
- * `wp sync` — projects the canonical webpresso rule/skill catalog into the
- * supported host surfaces.
+ * `wp sync` — projects the canonical webpresso rule/skill/agent catalog into
+ * the supported host surfaces.
  *
- * Projects unified rule + skill content (catalog ∪ consumer) into per-IDE
- * surfaces according to `DEFAULT_UNIFIED_CONSUMERS`.
+ * Projects unified rule + skill + agent content (catalog ∪ consumer) into
+ * per-IDE surfaces according to `DEFAULT_UNIFIED_CONSUMERS`.
  *
  * Flags:
- *   --kind rules|skills   Filter to a single kind (default: both).
- *   --check               Dry-run; exit 1 on first drift, no writes.
+ *   --kind rules|skills|agents   Filter to a single kind (default: all).
+ *   --check                      Dry-run; exit 1 on first drift, no writes.
  */
 import type { CAC } from "cac";
+import type { ContentKind } from "#content/loader";
 import { type ConsumerContext } from "./init/detect-consumer.js";
+export declare function parseKind(input: string | undefined): readonly ContentKind[] | undefined;
 export declare function computeSyncDriftCounts(input: {
     readonly surfaceFixCount: number;
     readonly agentsChanged: boolean;

package/dist/esm/cli/commands/sync.js

@@ -1,13 +1,13 @@
 /**
- * `wp sync` — projects the canonical webpresso rule/skill catalog into the
- * supported host surfaces.
+ * `wp sync` — projects the canonical webpresso rule/skill/agent catalog into
+ * the supported host surfaces.
  *
- * Projects unified rule + skill content (catalog ∪ consumer) into per-IDE
- * surfaces according to `DEFAULT_UNIFIED_CONSUMERS`.
+ * Projects unified rule + skill + agent content (catalog ∪ consumer) into
+ * per-IDE surfaces according to `DEFAULT_UNIFIED_CONSUMERS`.
  *
  * Flags:
- *   --kind rules|skills   Filter to a single kind (default: both).
- *   --check               Dry-run; exit 1 on first drift, no writes.
+ *   --kind rules|skills|agents   Filter to a single kind (default: all).
+ *   --check                      Dry-run; exit 1 on first drift, no writes.
  */
 import { existsSync } from "node:fs";
 import { join } from "node:path";
@@ -25,14 +25,16 @@ function commandError(message, exitCode = 1) {
     err.exitCode = exitCode;
     return err;
 }
-function parseKind(input) {
+export function parseKind(input) {
     if (input === undefined)
         return undefined;
     if (input === "rules" || input === "rule")
         return ["rule"];
     if (input === "skills" || input === "skill")
         return ["skill"];
-    throw commandError(`Invalid --kind: ${input}. Must be 'rules' or 'skills'.`);
+    if (input === "agents" || input === "agent")
+        return ["agent"];
+    throw commandError(`Invalid --kind: ${input}. Must be 'rules', 'skills', or 'agents'.`);
 }
 function formatMismatches(mismatches) {
     return mismatches.map((m) => `  - [${m.consumerId}] ${m.targetPath}: ${m.reason}`).join("\n");
@@ -90,7 +92,7 @@ export function isUnmaterializedAgentKitSourceWorktree(consumer) {
 export function registerSyncCommand(cli) {
     cli
         .command("sync", "Sync agent rules + skills across all supported host surfaces")
-        .option("--kind <kind>", "Filter: rules | skills (default: both)")
+        .option("--kind <kind>", "Filter: rules | skills | agents (default: all)")
         .option("--check", "Exit 1 on drift; no writes")
         .action(async (options = {}) => {
         const kinds = parseKind(options.kind);
@@ -140,6 +142,14 @@ export function registerSyncCommand(cli) {
             }
             throw error;
         }
+        // Operator-owned paths agent-kit refused to replace. A warning, never
+        // drift: treating it as a mismatch would red `wp sync --check` on every
+        // run for someone who legitimately customized a subagent.
+        for (const entry of result.preserved) {
+            console.warn(`wp sync: preserved ${entry.targetPath} — it is not an agent-kit projection, ` +
+                `so the catalog '${entry.slug}' agent was not written there. ` +
+                `Rename yours, or move it to agent-agents/ to have it managed.`);
+        }
         const retiredMcp = cleanupRetiredMcpFanouts(repoRoot, { check });
         for (const targetPath of retiredMcp.preserved) {
             console.warn(`wp sync: preserved divergent retired MCP target ${targetPath}; remove it manually if it is no longer needed.`);