@webpresso/agent-kit 3.3.2 → 3.3.4

package/dist/esm/hooks/doctor.js

@@ -27,6 +27,8 @@ import { isAgentKitSourceRepo } from "#cli/commands/init/source-repo-hook-policy
 import { findAgentKitPackageRoot, resolveAgentKitPackageRoot, } from "#cli/commands/init/package-root";
 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 { 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";
@@ -55,7 +57,10 @@ function createOwnedProbeSettler(child, timeoutMs, timeoutResult, resolve) {
     return settle;
 }
 const RTK_REQUESTED_MARKER = join(".agent", ".rtk-requested");
-const RTK_INSTALL_HINT = "rtk requested via --with rtk but not on PATH; brew install rtk";
+const RTK_INSTALL_HINT = "rtk requested but managed binary missing; re-run wp setup (or set WP_RTK_BIN)";
+const RTK_FREESTANDING_HOOK_REL = join(".claude", "hooks", "rtk-rewrite.sh");
+const RTK_FREESTANDING_SETTINGS_REL = join(".claude", "settings.json");
+const RTK_FREESTANDING_REPAIR = "stale freestanding rtk-rewrite surface; run wp setup (ensureRtk strips rtk-rewrite.sh — pretool-guard owns rewrite)";
 const HOST_SMOKE_ENV = "WP_RUN_HOST_SMOKE";
 const HOOK_PROBE_TIMEOUT_ENV = "WP_DOCTOR_HOOK_TIMEOUT_MS";
 const WRAPPER_PROBE_ENV = "WP_DOCTOR_WRAPPER_PROBE";
@@ -347,6 +352,62 @@ function checkConsumerCodexHookPaths(cwd = process.cwd()) {
 function wasRtkRequested(cwd = process.cwd()) {
     return tryAccess(join(cwd, RTK_REQUESTED_MARKER));
 }
+export function checkFreestandingRtkSurface(cwd = process.cwd()) {
+    const hookPath = join(cwd, RTK_FREESTANDING_HOOK_REL);
+    const settingsPath = join(cwd, RTK_FREESTANDING_SETTINGS_REL);
+    const hookPresent = tryAccess(hookPath);
+    const markers = [];
+    if (hookPresent)
+        markers.push(RTK_FREESTANDING_HOOK_REL);
+    if (tryAccess(settingsPath)) {
+        try {
+            const settings = readFileSync(settingsPath, "utf8");
+            if (settings.includes("rtk-rewrite.sh")) {
+                markers.push(`${RTK_FREESTANDING_SETTINGS_REL} rtk-rewrite.sh`);
+            }
+            if (settings.includes("rtk hook claude")) {
+                markers.push(`${RTK_FREESTANDING_SETTINGS_REL} rtk hook claude`);
+            }
+        }
+        catch {
+            // ignore unreadable settings
+        }
+    }
+    if (markers.length === 0)
+        return null;
+    return {
+        name: "freestanding rtk PreToolUse retired",
+        ok: false,
+        detail: `${RTK_FREESTANDING_REPAIR} (found: ${markers.join(", ")})`,
+    };
+}
+/** Non-mutating warn for user-global freestanding RTK rewriters (rtk init -g). */
+export function checkGlobalFreestandingRtkSurface() {
+    const globalSettings = join(homedir(), ".claude", "settings.json");
+    const globalHook = join(homedir(), ".claude", "hooks", "rtk-rewrite.sh");
+    const markers = [];
+    if (tryAccess(globalHook))
+        markers.push("~/.claude/hooks/rtk-rewrite.sh");
+    if (tryAccess(globalSettings)) {
+        try {
+            const settings = readFileSync(globalSettings, "utf8");
+            if (settings.includes("rtk-rewrite.sh"))
+                markers.push("~/.claude/settings.json rtk-rewrite.sh");
+            if (settings.includes("rtk hook claude"))
+                markers.push("~/.claude/settings.json rtk hook claude");
+        }
+        catch {
+            // ignore
+        }
+    }
+    if (markers.length === 0)
+        return null;
+    return {
+        name: "global freestanding rtk (warn)",
+        ok: true,
+        detail: `WARNING: global freestanding RTK PreToolUse still present (${markers.join(", ")}); remove manually or re-run rtk uninstall — project setup does not mutate ~/.claude. Dual rewriters may race updatedInput with wp-pretool-guard.`,
+    };
+}
 function shouldRunHostChecks(mode) {
     if (mode === "skip")
         return false;
@@ -393,36 +454,13 @@ function resolveRequestedHosts(mode, hostNames) {
 export function checkRtkOnPath(cwd) {
     if (!wasRtkRequested(cwd))
         return Promise.resolve(null);
-    return new Promise((resolve) => {
-        const timeoutMs = hookProbeTimeoutMs();
-        const child = spawn("rtk", ["--version"], {
-            stdio: ["ignore", "pipe", "pipe"],
-            detached: process.platform !== "win32",
-        });
-        let stdout = "";
-        let stderr = "";
-        const settle = createOwnedProbeSettler(child, timeoutMs, () => ({
-            name: "rtk on PATH",
-            ok: false,
-            detail: `rtk probe timed out after ${timeoutMs}ms`,
-        }), resolve);
-        child.stdout.on("data", (chunk) => {
-            stdout += String(chunk);
-        });
-        child.stderr?.on("data", (chunk) => {
-            stderr += String(chunk);
-        });
-        child.on("error", () => {
-            settle({ name: "rtk on PATH", ok: false, detail: RTK_INSTALL_HINT });
-        });
-        child.on("close", (code) => {
-            if (code === 0) {
-                settle({ name: "rtk on PATH", ok: true, detail: stdout.trim() || "rtk present" });
-                return;
-            }
-            const suffix = stderr.trim().length > 0 ? ` (${stderr.trim()})` : "";
-            settle({ name: "rtk on PATH", ok: false, detail: `${RTK_INSTALL_HINT}${suffix}` });
-        });
+    // Managed binary (Webpresso cache / WP_RTK_BIN), not bare PATH brew install.
+    return import("#tool-runtime/managed-rtk.js").then(({ isManagedRtkAvailable, resolveManagedRtkExecutable }) => {
+        const path = resolveManagedRtkExecutable();
+        if (path && isManagedRtkAvailable()) {
+            return { name: "rtk managed", ok: true, detail: path };
+        }
+        return { name: "rtk managed", ok: false, detail: RTK_INSTALL_HINT };
     });
 }
 async function probeHookBin(wpCli, hookName, checkStdin) {
@@ -1184,19 +1222,44 @@ async function checkCodexHost() {
             detail: `missing MCP entry (webpresso=${hasAgentKit})`,
         };
     }
-    const mcpPathFindings = auditCodexConfigPaths().filter((finding) => finding.location.startsWith("mcp_servers.webpresso."));
-    if (mcpPathFindings.length > 0) {
-        const detail = mcpPathFindings
-            .map((finding) => `${finding.location}: ${finding.path} (${finding.reason === "missing" ? "path does not exist" : "volatile versioned path"})`)
-            .join("; ");
-        return {
-            name: "Codex host integration",
-            ok: false,
-            detail: `webpresso MCP listed but launch paths are broken or rot-prone — ${detail}`,
-        };
-    }
+    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" };
 }
+/**
+ * Codex must receive `webpresso` over exactly one channel — the bundled Codex
+ * plugin. Report the retired user-global `[mcp_servers.webpresso]` block that
+ * `wp setup` removes, and call out a double registration distinctly. A
+ * user-authored block (a live `wp` outside every agent-kit root) is never
+ * removed by setup, so it gets its own manual-action finding.
+ */
+export function classifyLegacyCodexWebpressoChannel(configPath = defaultCodexConfigFilePath(), homeDir = process.env.HOME || homedir()) {
+    const outcome = classifyCodexConfigWebpressoBlock(configPath);
+    if (outcome === null || outcome.kind === "absent")
+        return null;
+    if (outcome.kind === "ambiguous") {
+        return `${configPath} declares webpresso in a TOML spelling wp setup cannot rewrite; remove the [mcp_servers.webpresso] definition by hand — the bundled Codex plugin is the single delivery channel`;
+    }
+    if (outcome.kind === "preserved") {
+        return `${configPath} declares a user-authored webpresso MCP server (${outcome.command ?? "no command"}); wp setup preserves it. Remove it by hand to use the bundled Codex plugin as the single delivery channel`;
+    }
+    const dualChannel = findInstalledCodexPluginMcpManifests(homeDir).length > 0;
+    const prefix = dualChannel
+        ? "webpresso is registered over BOTH delivery channels — the bundled Codex plugin AND a legacy"
+        : "webpresso is still registered over the retired legacy";
+    return `${prefix} [mcp_servers.webpresso] block in ${configPath} (command = ${outcome.command}); run \`wp setup\` — it removes the legacy block`;
+}
+function classifyCodexConfigWebpressoBlock(configPath) {
+    try {
+        if (!existsSync(configPath))
+            return null;
+        return pruneOwnedMcpServerBlock(readFileSync(configPath, "utf8"), WEBPRESSO_MCP_SERVER_NAME, isAgentKitOwnedWpCommand);
+    }
+    catch {
+        return null;
+    }
+}
 async function checkOpenCodeHost(cwd = process.cwd()) {
     const available = await runCommand("opencode", ["--version"]);
     if (!available.ok) {
@@ -1430,9 +1493,8 @@ export function checkPackagedHostArtifacts(cwd = process.cwd()) {
             const serverRecord = server && typeof server === "object" && !Array.isArray(server)
                 ? server
                 : null;
-            if (serverRecord?.command !== "${PLUGIN_ROOT}/bin/wp" ||
-                !stringArrayEquals(serverRecord.args, ["mcp"])) {
-                failures.push("Codex adapter MCP surface must expose direct webpresso server map launching ${PLUGIN_ROOT}/bin/wp mcp");
+            if (serverRecord?.command !== "wp" || !stringArrayEquals(serverRecord.args, ["mcp"])) {
+                failures.push("Codex adapter MCP surface must expose direct webpresso server map launching wp mcp");
             }
         }
         if (codexHooks) {
@@ -2138,6 +2200,13 @@ export async function runHooksDoctor(opts = {}) {
     const rtkCheck = await checkRtkOnPath(opts.cwd);
     if (rtkCheck)
         checks.push(rtkCheck);
+    const freestandingRtk = checkFreestandingRtkSurface(opts.cwd);
+    if (freestandingRtk)
+        checks.push(freestandingRtk);
+    // Non-mutating WARN only — never mutates ~/.claude; surfaces dual-rewriter risk.
+    const globalFreestandingRtk = checkGlobalFreestandingRtkSurface();
+    if (globalFreestandingRtk)
+        checks.push(globalFreestandingRtk);
     if (shouldRunHostChecks(hostMode)) {
         for (const host of requestedHosts) {
             if (host === "codex") {

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

@@ -23,7 +23,7 @@ function routeRawMutatingGitWorktree(command) {
     return {
         action: "deny",
         tool: "wp_worktree",
-        guidance: "Use the `wp_worktree` MCP tool (or `wp worktree` CLI when MCP is unavailable) instead — managed repositories may mutate linked worktrees only through agent-kit so owner bindings and the global registry stay consistent.",
+        guidance: "Use the `wp_worktree` MCP tool (or `wp worktree prune --all` / `wp worktree remove <target>` when MCP is unavailable) instead — managed repositories may mutate linked worktrees only through agent-kit so owner bindings and the global registry stay consistent. Both prune paths also run `git worktree prune`, so a hand-deleted worktree directory still releases the branch it claimed.",
         code: "GUARD_RAW_GIT_MUTATION",
     };
 }

package/dist/esm/hooks/pretool-guard/rtk-rewrite.d.ts

@@ -0,0 +1,24 @@
+/**
+ * RTK rewrite inside path-stable pretool-guard (no freestanding consumer hook).
+ *
+ * v1: exact `git status` → `<managed-rtk> git status` when managed rtk is available.
+ */
+export type RtkRewriteDecision = {
+    readonly action: "rewrite";
+    readonly command: string;
+} | {
+    readonly action: "noop";
+    readonly reason: string;
+};
+export type RtkPresenceProbe = () => boolean;
+export type RtkExecutableResolver = () => string | null;
+/**
+ * Decide whether to rewrite a Bash command through managed rtk.
+ */
+export declare function decideRtkRewrite(command: string, isRtkPresent?: RtkPresenceProbe, resolveExecutable?: RtkExecutableResolver): RtkRewriteDecision;
+/**
+ * POSIX single-quote wrap for absolute managed paths.
+ * Refuse NUL/newline/single-quote — those cannot be safely embedded in `'…'`.
+ * Double-quote wrapping is intentionally avoided ($ / ` / " injection).
+ */
+export declare function shellQuoteExecutable(path: string): string | null;

package/dist/esm/hooks/pretool-guard/rtk-rewrite.js

@@ -0,0 +1,50 @@
+/**
+ * RTK rewrite inside path-stable pretool-guard (no freestanding consumer hook).
+ *
+ * v1: exact `git status` → `<managed-rtk> git status` when managed rtk is available.
+ */
+import { isManagedRtkAvailable, resolveManagedRtkExecutable } from "#tool-runtime/managed-rtk.js";
+const UNCERTAIN_SHELL_RE = /[\n\r|;&<>`$(){}[\]\\'"#*?]/u;
+/**
+ * Decide whether to rewrite a Bash command through managed rtk.
+ */
+export function decideRtkRewrite(command, isRtkPresent = isManagedRtkAvailable, resolveExecutable = resolveManagedRtkExecutable) {
+    if (command !== command.trim() || command.length === 0) {
+        return { action: "noop", reason: "uncertain-parse" };
+    }
+    if (UNCERTAIN_SHELL_RE.test(command)) {
+        return { action: "noop", reason: "uncertain-parse" };
+    }
+    // already managed absolute path or bare rtk prefix
+    if (command.startsWith("rtk ") || command.includes("/rtk ")) {
+        return { action: "noop", reason: "already-rtk" };
+    }
+    if (command !== "git status") {
+        return { action: "noop", reason: "not-eligible" };
+    }
+    if (!isRtkPresent()) {
+        return { action: "noop", reason: "rtk-missing" };
+    }
+    const executable = resolveExecutable();
+    if (!executable) {
+        return { action: "noop", reason: "rtk-missing" };
+    }
+    const bin = shellQuoteExecutable(executable);
+    if (!bin) {
+        return { action: "noop", reason: "rtk-missing" };
+    }
+    return { action: "rewrite", command: `${bin} git status` };
+}
+/**
+ * POSIX single-quote wrap for absolute managed paths.
+ * Refuse NUL/newline/single-quote — those cannot be safely embedded in `'…'`.
+ * Double-quote wrapping is intentionally avoided ($ / ` / " injection).
+ */
+export function shellQuoteExecutable(path) {
+    if (path.length === 0 || /[\0\n\r']/.test(path))
+        return null;
+    // Unquoted only for the common managed-cache shape (no shell metacharacters).
+    if (/^[A-Za-z0-9_./:@+=,-]+$/.test(path))
+        return path;
+    return `'${path}'`;
+}

package/dist/esm/hooks/pretool-guard/runner.js

@@ -11,6 +11,7 @@ import { VALIDATORS } from "./validators/index.js";
 import { isDirectEntrypoint } from "#hooks/shared/direct-entrypoint";
 import { optimizeToolInput, } from "./optimization.js";
 import { recordOptimizationEvent } from "./optimization-events.js";
+import { decideRtkRewrite } from "./rtk-rewrite.js";
 const RED = "\x1b[31m";
 const YELLOW = "\x1b[33m";
 const DIM = "\x1b[2m";
@@ -256,6 +257,11 @@ export function processValidation(inputJson, options = {}) {
         process.exit(2);
     }
     if (command) {
+        const rtkRewrite = decideRtkRewrite(command);
+        if (rtkRewrite.action === "rewrite") {
+            writeUpdatedInput(input, rtkRewrite.command);
+            process.exit(0);
+        }
         const originalAction = routeCommand(command)?.action ?? { action: "passthrough" };
         const optimization = optimizeToolInput(input, originalAction, options.optimizationRules);
         if (optimization.action === "rewrite") {

package/dist/esm/hooks/status/index.js

@@ -109,7 +109,7 @@ function hasValidCodexPluginArtifacts(repoRoot) {
     const hookMap = hooks?.hooks;
     return (plugin?.mcpServers === "./.mcp.json" &&
         plugin.hooks === "./hooks/hooks.json" &&
-        serverRecord?.command === "${PLUGIN_ROOT}/bin/wp" &&
+        serverRecord?.command === "wp" &&
         stringArrayEquals(serverRecord.args, ["mcp"]) &&
         hookMap !== null &&
         typeof hookMap === "object" &&

package/dist/esm/hooks/stop/qa-changed-files.js

@@ -45,12 +45,17 @@ export function filterQaFiles(files) {
 export function getTypecheckFiles(files) {
     return files.filter((f) => TYPECHECKABLE_EXTENSIONS.has(extname(f)));
 }
+const TEST_SOURCE_EXTENSIONS = new Set([".ts", ".tsx", ".mts", ".cts", ".js", ".jsx"]);
 export function findTestFiles(sourceFile, projectDir) {
     const ext = extname(sourceFile);
     const base = basename(sourceFile, ext);
     const dir = dirname(sourceFile);
-    if (base.endsWith(".test") || base.endsWith(".integration.test"))
+    // Only treat real test modules as tests. Names like `tsconfig.test.json` end
+    // with `.test` after stripping the extension and must not become vitest filters.
+    if (TEST_SOURCE_EXTENSIONS.has(ext) &&
+        (base.endsWith(".test") || base.endsWith(".integration.test"))) {
         return [sourceFile];
+    }
     const pattern = join(dir, `${base}.{test,integration.test}{.ts,.tsx}`);
     return globSync(pattern, { cwd: projectDir, withFileTypes: false });
 }

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

@@ -94,21 +94,49 @@ export async function applyLocalBlueprintTransition(input) {
     mkdirSync(path.dirname(found.shape === "flat" ? destination.flat : destination.directory), {
         recursive: true,
     });
+    const sourcePath = found.shape === "flat" ? overviewPath : found.dir;
+    const destinationPath = found.shape === "flat" ? destination.flat : destination.directory;
     let finalOverviewPath = overviewPath;
+    let renamed = false;
     if (found.state !== to_state) {
         const { renameSync } = await import("node:fs");
-        renameSync(found.shape === "flat" ? overviewPath : found.dir, found.shape === "flat" ? destination.flat : destination.directory);
+        renameSync(sourcePath, destinationPath);
+        renamed = true;
         finalOverviewPath = found.shape === "flat" ? destination.flat : destination.folder;
     }
-    writeFileAtomic(finalOverviewPath, updated, "utf8");
-    await reIngest(projectCwd);
-    const refreshed = getCurrentProjectBlueprint(projectCwd, slug);
-    if (!refreshed.blueprint) {
-        throw new Error(`Blueprint "${slug}" did not appear in the projection after transition`);
+    // Atomicity: everything from here on can still fail (re-ingest, projection
+    // lookup). The rename above may already have happened, and the frontmatter
+    // write below always happens before those checks run. Roll BOTH back
+    // before rethrowing so a failed transition never leaves the blueprint
+    // stranded in the destination lifecycle directory, nor leaves stale
+    // frontmatter (bumped last_updated/progress/status) on an otherwise
+    // unmoved file — either the transition fully lands (moved + content
+    // updated + re-ingested + visible in the projection) or the working tree
+    // is restored to exactly what it was before this call.
+    try {
+        writeFileAtomic(finalOverviewPath, updated, "utf8");
+        await reIngest(projectCwd);
+        const refreshed = getCurrentProjectBlueprint(projectCwd, slug);
+        if (!refreshed.blueprint) {
+            throw new Error(`Blueprint "${slug}" did not appear in the projection after transition`);
+        }
+        return {
+            blueprint: refreshed.blueprint,
+            overviewPath: finalOverviewPath,
+            fromState: found.state,
+        };
+    }
+    catch (error) {
+        try {
+            if (renamed) {
+                const { renameSync } = await import("node:fs");
+                renameSync(destinationPath, sourcePath);
+            }
+            writeFileAtomic(overviewPath, markdown, "utf8");
+        }
+        catch (rollbackError) {
+            throw new Error(`Transition to "${to_state}" failed and automatic rollback also failed; the blueprint may be left ${renamed ? `moved at ${destinationPath}` : "with partially-updated frontmatter"}. Original error: ${error instanceof Error ? error.message : String(error)}. Rollback error: ${rollbackError instanceof Error ? rollbackError.message : String(rollbackError)}`);
+        }
+        throw error;
     }
-    return {
-        blueprint: refreshed.blueprint,
-        overviewPath: finalOverviewPath,
-        fromState: found.state,
-    };
 }

package/dist/esm/mcp/blueprint/handlers/review-log.d.ts

@@ -2,13 +2,20 @@ import type { ProjectResolver } from "#project-resolver.js";
 import type { ToolHandlerResult } from "#mcp/auto-discover.js";
 /**
  * MCP wrapper around the SAME reviews.md-ledger writer `logReviewEntry` that
- * (an unwired) `wp review log` uses, plus the matching frontmatter `approvals:`
- * entry that `collectTrackedReviewProvenance` (the promotion approval gate)
- * actually reads. This is the tracked/frontmatter provenance path — the same
- * trust model a hand-authored `approvals:` block already had (the reviewer id
- * is caller-asserted, verified only by the referenced artifact/reviews.md
- * entry being tracked in git) — this tool just makes that existing path
- * reachable from MCP instead of a raw Write/Edit or a Bash/python workaround.
+ * (an unwired) `wp review log` uses. For NON-approval verdicts it also appends
+ * the matching frontmatter `approvals:` entry, so rejection attribution stays
+ * visible where readers already look. This is the tracked/frontmatter provenance
+ * path — the same trust model a hand-authored `approvals:` block already had (the
+ * reviewer id is caller-asserted, verified only by the referenced
+ * artifact/reviews.md entry being tracked in git) — this tool just makes that
+ * existing path reachable from MCP instead of a raw Write/Edit or a Bash/python
+ * workaround.
+ *
+ * It never writes a POLICY-APPROVAL entry (approve / approve-with-nits) into
+ * frontmatter. `collectTrackedReviewProvenance` — the legacy promotion leg — only
+ * counts policy approvals and never reads or hashes the blueprint body, so such
+ * an entry would be gate authority that survives an arbitrary rewrite of the
+ * plan. See `LEGACY_APPROVAL_LEG_ANCHOR_COMMIT` in `#lifecycle/rollout-anchor.js`.
  *
  * A policy-approval verdict (approve / approve-with-nits) REQUIRES
  * reviewer==="human" — matching `logReviewEvent`'s existing v2-ledger

package/dist/esm/mcp/blueprint/handlers/review-log.js

@@ -30,13 +30,20 @@ const reviewLogSchema = z.object({
 });
 /**
  * MCP wrapper around the SAME reviews.md-ledger writer `logReviewEntry` that
- * (an unwired) `wp review log` uses, plus the matching frontmatter `approvals:`
- * entry that `collectTrackedReviewProvenance` (the promotion approval gate)
- * actually reads. This is the tracked/frontmatter provenance path — the same
- * trust model a hand-authored `approvals:` block already had (the reviewer id
- * is caller-asserted, verified only by the referenced artifact/reviews.md
- * entry being tracked in git) — this tool just makes that existing path
- * reachable from MCP instead of a raw Write/Edit or a Bash/python workaround.
+ * (an unwired) `wp review log` uses. For NON-approval verdicts it also appends
+ * the matching frontmatter `approvals:` entry, so rejection attribution stays
+ * visible where readers already look. This is the tracked/frontmatter provenance
+ * path — the same trust model a hand-authored `approvals:` block already had (the
+ * reviewer id is caller-asserted, verified only by the referenced
+ * artifact/reviews.md entry being tracked in git) — this tool just makes that
+ * existing path reachable from MCP instead of a raw Write/Edit or a Bash/python
+ * workaround.
+ *
+ * It never writes a POLICY-APPROVAL entry (approve / approve-with-nits) into
+ * frontmatter. `collectTrackedReviewProvenance` — the legacy promotion leg — only
+ * counts policy approvals and never reads or hashes the blueprint body, so such
+ * an entry would be gate authority that survives an arbitrary rewrite of the
+ * plan. See `LEGACY_APPROVAL_LEG_ANCHOR_COMMIT` in `#lifecycle/rollout-anchor.js`.
  *
  * A policy-approval verdict (approve / approve-with-nits) REQUIRES
  * reviewer==="human" — matching `logReviewEvent`'s existing v2-ledger
@@ -143,22 +150,39 @@ export async function handleReviewLog(projectResolver, cwd, raw) {
             ...(rev ? { rev } : {}),
             ...(note ? { note } : {}),
         });
-        const overviewRaw = readFileSync(found.path, "utf8");
-        const parsed = matter(overviewRaw);
-        const existingApprovals = Array.isArray(parsed.data.approvals) ? parsed.data.approvals : [];
-        const approvalEntry = {
-            reviewer: entry.reviewer,
-            verdict: entry.verdict,
-            evidence: entry.evidence ?? "reviews.md",
-            artifact: entry.artifact ?? normalizedArtifactPath,
-            ...(entry.commit ? { commit: entry.commit } : {}),
-            ...(entry.rev ? { rev: entry.rev } : {}),
-        };
-        const updatedData = { ...parsed.data, approvals: [...existingApprovals, approvalEntry] };
-        const rendered = matter.stringify(parsed.content, updatedData);
-        writeFileAtomic(found.path, rendered, { encoding: "utf8" });
+        // Policy-approval verdicts are NOT projected into frontmatter `approvals:`.
+        // That field feeds `collectTrackedReviewProvenance`, the legacy promotion leg
+        // that carries no content binding at all: it matches a reviews.md record and
+        // a tracked artifact but never reads or hashes the blueprint body, and the
+        // gate supplies no `targetHash`. Writing an approval there would mint
+        // authority that survives an arbitrary rewrite of the plan. Non-approval
+        // verdicts (reject / no-verdict) are still recorded, because the legacy leg
+        // only ever counts policy approvals -- they are attribution, never authority.
+        //
+        // Nothing is lost: the approval is fully recorded in reviews.md and in the
+        // tracked artifact. Satisfying the promotion gate still requires a converged
+        // `wp review gate` run (content-addressed v2 ledger) or `wp review override`.
+        const mintsGateAuthority = isPolicyApprovalVerdict(entry.verdict);
+        if (!mintsGateAuthority) {
+            const overviewRaw = readFileSync(found.path, "utf8");
+            const parsed = matter(overviewRaw);
+            const existingApprovals = Array.isArray(parsed.data.approvals) ? parsed.data.approvals : [];
+            const approvalEntry = {
+                reviewer: entry.reviewer,
+                verdict: entry.verdict,
+                evidence: entry.evidence ?? "reviews.md",
+                artifact: entry.artifact ?? normalizedArtifactPath,
+                ...(entry.commit ? { commit: entry.commit } : {}),
+                ...(entry.rev ? { rev: entry.rev } : {}),
+            };
+            const updatedData = { ...parsed.data, approvals: [...existingApprovals, approvalEntry] };
+            const rendered = matter.stringify(parsed.content, updatedData);
+            writeFileAtomic(found.path, rendered, { encoding: "utf8" });
+        }
         return finishPayload({
-            summary: `Logged review ${entry.id} -> ${entry.blueprintSlug} and recorded approvals frontmatter`,
+            summary: mintsGateAuthority
+                ? `Logged review ${entry.id} -> ${entry.blueprintSlug} in reviews.md (no frontmatter approval recorded: an approval verdict must bind to reviewed content via wp review gate)`
+                : `Logged review ${entry.id} -> ${entry.blueprintSlug} and recorded approvals frontmatter`,
             event_id: entry.id,
             blueprint_slug: entry.blueprintSlug,
             reviewer: entry.reviewer,

package/dist/esm/mcp/blueprint/handlers/validate.js

@@ -41,6 +41,12 @@ export function runValidate(filePath) {
         gaps.push(`Invalid frontmatter field: last_updated (${lastUpdated})`);
     }
     const body = fm.content;
+    // Deliberately LOOSER than the canonical grammar in `#markdown/task-heading`
+    // (`Task\s+\S` accepts any id, not just `\d+(?:\.\d+)+`, and needs no title).
+    // This is a gap REPORTER: it has to see a malformed heading in order to tell
+    // the author about it. Converging it onto the strict matcher would make
+    // exactly the malformed tasks it exists to catch invisible again — the
+    // reported gaps would silently drop to zero. Do not "de-duplicate" this.
     const taskHeaderRegex = /^####\s+(?:\[[^\]]+\]\s+)?Task\s+\S/m;
     if (!taskHeaderRegex.test(body))
         gaps.push('No "#### Task" sections found');

package/dist/esm/mcp/blueprint/registration.js

@@ -289,7 +289,7 @@ export async function registerBlueprintTools(registrar, cwd, projectResolver = c
             next_action: nextActionOutputSchema,
         },
     }, (r) => handleTaskVerify(projectResolver, cwd, r), { title: "Blueprint Task Verify", destructiveHint: false, openWorldHint: false });
-    registrar.registerTool("wp_blueprint_review_log", 'Record a tracked review-ledger entry for a blueprint: writes the given artifact content under blueprints/<state>/<slug>/review-artifacts/, appends the matching structured entry to reviews.md (via the same logReviewEntry writer, distinct from the CLI\'s own `wp review log` subcommand), and appends the corresponding `approvals:` frontmatter entry to _overview.md that the legacy promotion approval path (`collectTrackedReviewProvenance`) reads. A `verdict` of approve or approve-with-nits REQUIRES reviewer="human" — this tool cannot mint a claude/codex/grok/OpenCode-Go frontmatter approval; satisfying the strong-reviewer promotion gate still requires either a converged `wp review gate` run or a maintainer directly authoring that frontmatter. Use this tool for reject/no-verdict entries from any reviewer, or a human-adjudicated approve/approve-with-nits — including the audit-trail note when `wp review gate` fails to converge. Returns { event_id, blueprint_slug, reviewer, verdict, status, artifact_path }.', {
+    registrar.registerTool("wp_blueprint_review_log", 'Record a tracked review-ledger entry for a blueprint: writes the given artifact content under blueprints/<state>/<slug>/review-artifacts/ and appends the matching structured entry to reviews.md (via the same logReviewEntry writer, distinct from the CLI\'s own `wp review log` subcommand). For reject/no-verdict it ALSO appends the corresponding `approvals:` frontmatter entry to _overview.md, so rejection attribution stays visible. It NEVER writes an approve/approve-with-nits entry into `approvals:`: that field feeds the legacy promotion path (`collectTrackedReviewProvenance`), which never reads or hashes the blueprint body, so an approval recorded there would keep satisfying the gate after the plan was rewritten. A `verdict` of approve or approve-with-nits additionally REQUIRES reviewer="human". Satisfying the promotion gate requires a converged `wp review gate` run (content-addressed v2 ledger) or `wp review override`. Use this tool for reject/no-verdict entries from any reviewer, or to record a human-adjudicated approve/approve-with-nits in reviews.md — including the audit-trail note when `wp review gate` fails to converge. Returns { event_id, blueprint_slug, reviewer, verdict, status, artifact_path }.', {
         type: "object",
         properties: {
             project_id: { type: "string" },

package/dist/esm/mcp/tools/_names.d.ts

@@ -8,4 +8,4 @@
  * is enforced by `_names.test.ts` against `COMPILED_TOOL_REGISTRY`, so this list
  * cannot silently drift.
  */
-export declare const WP_TOOL_NAMES: readonly ["wp_audit", "wp_audits", "wp_bench", "wp_ci_act", "wp_ci_preflight", "wp_e2e", "wp_fleet_status", "wp_format", "wp_gain", "wp_lint", "wp_pr_status", "wp_pr_upsert", "wp_pr_wait", "wp_qa", "wp_release_readiness", "wp_review_run", "wp_run_wait", "wp_session_batch_execute", "wp_session_capture", "wp_session_context", "wp_session_doctor", "wp_session_execute", "wp_session_execute_file", "wp_session_fetch_and_index", "wp_session_id", "wp_session_index", "wp_session_info", "wp_session_purge", "wp_session_retrieve", "wp_session_restore", "wp_session_search", "wp_session_snapshot", "wp_session_stats", "wp_test", "wp_typecheck", "wp_ultragoal_cancel", "wp_ultragoal_handoff", "wp_ultragoal_new", "wp_ultragoal_run", "wp_ultragoal_status", "wp_worker_tail", "wp_worktree"];
+export declare const WP_TOOL_NAMES: readonly ["wp_audit", "wp_audits", "wp_bench", "wp_ci_act", "wp_ci_preflight", "wp_e2e", "wp_fleet_status", "wp_format", "wp_gain", "wp_lint", "wp_pr_status", "wp_pr_upsert", "wp_pr_wait", "wp_qa", "wp_release_progress", "wp_release_readiness", "wp_review_run", "wp_run_wait", "wp_session_batch_execute", "wp_session_capture", "wp_session_context", "wp_session_doctor", "wp_session_execute", "wp_session_execute_file", "wp_session_fetch_and_index", "wp_session_id", "wp_session_index", "wp_session_info", "wp_session_purge", "wp_session_retrieve", "wp_session_restore", "wp_session_search", "wp_session_snapshot", "wp_session_stats", "wp_test", "wp_typecheck", "wp_ui_blocks_list", "wp_ui_compose", "wp_ui_preview", "wp_ultragoal_cancel", "wp_ultragoal_handoff", "wp_ultragoal_new", "wp_ultragoal_run", "wp_ultragoal_status", "wp_worker_tail", "wp_worktree"];

package/dist/esm/mcp/tools/_names.js

@@ -23,6 +23,7 @@ export const WP_TOOL_NAMES = [
     "wp_pr_upsert",
     "wp_pr_wait",
     "wp_qa",
+    "wp_release_progress",
     "wp_release_readiness",
     "wp_review_run",
     "wp_run_wait",
@@ -44,6 +45,9 @@ export const WP_TOOL_NAMES = [
     "wp_session_stats",
     "wp_test",
     "wp_typecheck",
+    "wp_ui_blocks_list",
+    "wp_ui_compose",
+    "wp_ui_preview",
     "wp_ultragoal_cancel",
     "wp_ultragoal_handoff",
     "wp_ultragoal_new",

package/dist/esm/mcp/tools/_registry.js

@@ -12,6 +12,7 @@ import prStatus from "./pr-status.js";
 import prUpsert from "./pr-upsert.js";
 import prWait from "./pr-wait.js";
 import qa from "./qa.js";
+import releaseProgress from "./release-progress.js";
 import releaseReadiness from "./release-readiness.js";
 import reviewRun from "./review-run.js";
 import runWait from "./run-wait.js";
@@ -33,6 +34,9 @@ import sessionSnapshot from "./session-snapshot.js";
 import sessionStats from "./session-stats.js";
 import test from "./test.js";
 import typecheck from "./typecheck.js";
+import uiBlocksList from "./wp-ui-blocks-list.js";
+import uiCompose from "./wp-ui-compose.js";
+import uiPreview from "./wp-ui-preview.js";
 import ultragoalCancel from "./ultragoal-cancel.js";
 import ultragoalHandoff from "./ultragoal-handoff.js";
 import ultragoalNew from "./ultragoal-new.js";
@@ -55,6 +59,7 @@ export const COMPILED_TOOL_REGISTRY = [
     prUpsert,
     prWait,
     qa,
+    releaseProgress,
     releaseReadiness,
     reviewRun,
     runWait,
@@ -76,6 +81,9 @@ export const COMPILED_TOOL_REGISTRY = [
     sessionStats,
     test,
     typecheck,
+    uiBlocksList,
+    uiCompose,
+    uiPreview,
     ultragoalCancel,
     ultragoalHandoff,
     ultragoalNew,