@webpresso/agent-kit 3.1.30 → 3.2.0

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

@@ -1,14 +1,12 @@
 import { execFileSync, spawnSync } from "node:child_process";
-import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { existsSync } from "node:fs";
 import { join } from "node:path";
 import { validateBlueprintTrust } from "./validator.js";
 import { parseTrustDossier } from "./dossier.js";
-import { parseAllowedWpCommand } from "./gates.js";
-import { resolvePackageAssetPreferred } from "#utils/package-assets.js";
+import { parseAllowedWpCommand, wpTestFileTargets } from "./gates.js";
+import { ALLOWED_WP_COMMAND_TIMEOUT_MS, executeAllowedWpCommand, tailBounded, } from "./command-runner.js";
 export { parseAllowedWpCommand };
-const PROMOTION_GATE_TIMEOUT_MS = 30_000;
-const PROMOTION_GATE_STDIO_TAIL_LIMIT = 500;
-export function applyPromotionTrustGate(input) {
+export function preparePromotionTrustGate(input) {
     const now = (input.now ?? new Date()).toISOString();
     const syntacticMarkdown = upsertReadinessValue(upsertReadinessValue(input.markdown, "verified-at", now), "verified-head", "0123456789abcdef0123456789abcdef01234567");
     const parsedBeforeHead = parseTrustDossier(syntacticMarkdown);
@@ -30,6 +28,16 @@ export function applyPromotionTrustGate(input) {
         throw new Error(`Blueprint trust gate failed: ${preflight.violations.map((v) => `${v.section}: ${v.message}`).join("; ")}`);
     const parsed = parseTrustDossier(markdown);
     for (const gate of parsed.dossier?.gates ?? []) {
+        const deferredTarget = firstMissingTestTarget(input.repoRoot, gate.command);
+        if (deferredTarget !== undefined) {
+            // A `wp test --file <path>` gate whose target file does not exist yet is
+            // recorded as an honest non-`pass` result instead of aborting the whole
+            // promotion. `deferred` is a distinct failing state: it is only tolerated
+            // by the post-run validation below (allowDeferredGates), and the strict
+            // whole-repo completion audit still rejects it, so it can never merge.
+            markdown = updateGateLastResult(markdown, gate.gate, `deferred: test file not yet created (${deferredTarget})`);
+            continue;
+        }
         runPromotionCommand(input.repoRoot, gate.command);
         markdown = updateGateLastResult(markdown, gate.gate, `pass at ${now}`);
     }
@@ -40,10 +48,27 @@ export function applyPromotionTrustGate(input) {
         markdown,
         promotionCandidate: true,
         scanTaskAmbiguity: true,
+        allowDeferredGates: true,
     });
     if (!validated.ok)
         throw new Error(`Blueprint trust gate failed: ${validated.violations.map((v) => `${v.section}: ${v.message}`).join("; ")}`);
-    return markdown;
+    return {
+        file: input.file,
+        sourceMarkdown: input.markdown,
+        verifiedHead: head,
+        trustedMarkdown: markdown,
+    };
+}
+export function applyPromotionTrustGate(input) {
+    return preparePromotionTrustGate(input).trustedMarkdown;
+}
+export function assertPromotionTrustProofCurrent(input, proof) {
+    if (input.file !== proof.file || input.markdown !== proof.sourceMarkdown) {
+        throw new Error("Blueprint trust gate invalidated: the blueprint changed after external gates ran; retry promotion");
+    }
+    if (readHead(input.repoRoot) !== proof.verifiedHead) {
+        throw new Error("Blueprint trust gate invalidated: git HEAD changed after external gates ran; retry promotion");
+    }
 }
 function readHead(repoRoot) {
     const testHead = process.env["WP_BLUEPRINT_TRUST_GATE_TEST_HEAD"];
@@ -61,123 +86,48 @@ function readHead(repoRoot) {
         throw new Error("Blueprint trust gate failed: git HEAD is unavailable");
     }
 }
+/**
+ * Returns the first `wp test --file` target of `command` that does not exist on
+ * disk (resolved against `repoRoot`), or undefined when the gate is not a
+ * `wp test --file` gate or all its targets exist. A missing target is
+ * indistinguishable at `existsSync` time from "renamed / wrong path / deleted",
+ * so callers must treat it as a non-`pass` deferral, never a success.
+ */
+function firstMissingTestTarget(repoRoot, command) {
+    const targets = wpTestFileTargets(parseAllowedWpCommand(command));
+    return targets.find((target) => !existsSync(join(repoRoot, target)));
+}
 export function runPromotionCommand(repoRoot, command, deps = {}) {
-    const argv = parseAllowedWpCommand(command);
-    const [binary, ...args] = argv;
-    if (binary === undefined)
-        throw new Error(`Promotion gate command is empty: ${command}`);
-    const invocation = resolvePromotionGateInvocation(repoRoot, binary, args);
-    const spawn = deps.spawn ?? spawnSync;
-    const result = spawn(invocation.command, invocation.args, {
-        cwd: repoRoot,
-        encoding: "utf8",
-        stdio: ["ignore", "pipe", "pipe"],
-        timeout: PROMOTION_GATE_TIMEOUT_MS,
-        env: invocation.env,
+    const result = executeAllowedWpCommand({
+        command,
+        executionRoot: repoRoot,
+        logRoot: join(repoRoot, ".webpresso", "logs", "promotion-gates"),
+        ...(deps.spawn ? { spawn: deps.spawn } : {}),
     });
-    if (result.status === 0 && !result.error && result.signal === null)
+    if (result.outcome === "passed")
         return;
-    const stdout = typeof result.stdout === "string" ? result.stdout : "";
-    const stderr = typeof result.stderr === "string" ? result.stderr : "";
-    const logPath = writePromotionGateLog(repoRoot, command, invocation, stdout, stderr, result);
-    throw new Error(formatPromotionGateFailure(command, stdout, stderr, result, logPath));
+    throw new Error(formatPromotionGateFailure(result));
 }
-function resolvePromotionGateInvocation(repoRoot, binary, args) {
-    if (binary === "./bin/wp" || binary === "wp") {
-        const localLauncher = resolveRepoWpLauncher(repoRoot);
-        if (localLauncher !== null) {
-            return {
-                command: localLauncher,
-                args: [...args],
-                env: { ...process.env, PATH: `${repoRoot}/bin:${process.env["PATH"] ?? ""}` },
-            };
-        }
-        if (binary === "./bin/wp") {
-            return {
-                command: join(repoRoot, "bin", process.platform === "win32" ? "wp.cmd" : "wp"),
-                args: [...args],
-                env: { ...process.env, PATH: `${repoRoot}/bin:${process.env["PATH"] ?? ""}` },
-            };
-        }
-        const packagedLauncher = resolvePackagedWpLauncher();
-        return {
-            command: process.execPath,
-            args: [packagedLauncher, ...args],
-            env: { ...process.env },
-        };
-    }
-    return {
-        command: binary,
-        args: [...args],
-        env: { ...process.env, PATH: `${repoRoot}/bin:${process.env["PATH"] ?? ""}` },
-    };
-}
-function resolveRepoWpLauncher(repoRoot) {
-    const launcher = join(repoRoot, "bin", process.platform === "win32" ? "wp.cmd" : "wp");
-    return existsSync(launcher) ? launcher : null;
-}
-function resolvePackagedWpLauncher() {
-    const launcher = resolvePackageAssetPreferred([
-        process.platform === "win32" ? "bin/wp.cmd" : "bin/wp",
-        "bin/wp",
-    ]);
-    if (!existsSync(launcher)) {
-        throw new Error(`Promotion gate failed: packaged wp launcher is unavailable at ${launcher}`);
-    }
-    return launcher;
-}
-function formatPromotionGateFailure(command, stdout, stderr, result, logPath) {
+function formatPromotionGateFailure(result) {
     const details = [];
-    if (typeof result.status === "number")
-        details.push(`exit=${result.status}`);
+    if (typeof result.exitCode === "number")
+        details.push(`exit=${result.exitCode}`);
     if (result.signal)
         details.push(`signal=${result.signal}`);
-    if (result.error) {
-        const code = typeof result.error === "object" &&
-            result.error !== null &&
-            "code" in result.error &&
-            typeof result.error.code === "string"
-            ? result.error.code
-            : null;
-        details.push(code ? `spawn_error=${code}` : `spawn_error=${result.error.message}`);
-        if (code === "ETIMEDOUT")
-            details.push(`timeout=${PROMOTION_GATE_TIMEOUT_MS}ms`);
+    if (result.errorMessage) {
+        details.push(`spawn_error=${result.failureCode ?? result.errorMessage}`);
+        if (result.outcome === "timed-out")
+            details.push(`timeout=${ALLOWED_WP_COMMAND_TIMEOUT_MS}ms`);
     }
-    const stderrTail = tailBounded(stderr);
-    const stdoutTail = tailBounded(stdout);
+    const stderrTail = tailBounded(result.stderr);
+    const stdoutTail = tailBounded(result.stdout);
     if (stderrTail.length > 0)
         details.push(`stderr_tail=${JSON.stringify(stderrTail)}`);
     if (stdoutTail.length > 0)
         details.push(`stdout_tail=${JSON.stringify(stdoutTail)}`);
-    details.push(`log=${logPath}`);
-    return `Promotion gate failed (${command}): ${details.join("; ")}`;
-}
-function tailBounded(text) {
-    if (text.length <= PROMOTION_GATE_STDIO_TAIL_LIMIT)
-        return text.trim();
-    return text.slice(-PROMOTION_GATE_STDIO_TAIL_LIMIT).trim();
-}
-function writePromotionGateLog(repoRoot, command, invocation, stdout, stderr, result) {
-    const logsDir = join(repoRoot, ".webpresso", "logs", "promotion-gates");
-    mkdirSync(logsDir, { recursive: true });
-    const logPath = join(logsDir, `${Date.now()}-promotion-gate.log`);
-    const errorBlock = result.error
-        ? `error: ${result.error.name}: ${result.error.message}\n`
-        : "error: none\n";
-    writeFileSync(logPath, [
-        `command: ${command}`,
-        `invocation: ${invocation.command} ${invocation.args.join(" ")}`,
-        `exit: ${result.status ?? "null"}`,
-        `signal: ${result.signal ?? "null"}`,
-        `timeout_ms: ${PROMOTION_GATE_TIMEOUT_MS}`,
-        errorBlock.trimEnd(),
-        "--- stderr ---",
-        stderr,
-        "--- stdout ---",
-        stdout,
-        "",
-    ].join("\n"), "utf8");
-    return logPath;
+    if (result.logPath)
+        details.push(`log=${result.logPath}`);
+    return `Promotion gate failed (${result.command}): ${details.join("; ")}`;
 }
 function upsertReadinessValue(markdown, key, value) {
     const re = new RegExp(`^- ${key}: .*$`, "mu");

package/dist/esm/blueprint/trust/scaffold.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Trust Dossier authoring scaffold.
+ *
+ * `dossier.ts` / `evidence.ts` / `gates.ts` / `ambiguity.ts` define strict
+ * validation for a blueprint's `## Trust Dossier` section, but nothing
+ * generates a starting template. `TRUST_DOSSIER_SCAFFOLD` is a complete,
+ * already-valid worked example — proven by `scaffold.test.ts` to pass
+ * `validateBlueprintTrust` under both the strict configuration
+ * `wp audit blueprint-trust` uses and the draft-preflight configuration
+ * `wp_blueprint_put` / `preparePromotionTrustGate` use — so an author can
+ * paste it in and edit the example values instead of hand-deriving the
+ * contract from source.
+ *
+ * `verified-at` / `verified-head` stay as inert, obviously-fake placeholders:
+ * `preparePromotionTrustGate` (./promotion.ts) overwrites both with the real
+ * timestamp/HEAD on every promotion attempt, so there is no need for this
+ * pure, dependency-free module to shell out to git.
+ */
+export declare const TRUST_DOSSIER_SCAFFOLD: string;

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

@@ -0,0 +1,64 @@
+/**
+ * Trust Dossier authoring scaffold.
+ *
+ * `dossier.ts` / `evidence.ts` / `gates.ts` / `ambiguity.ts` define strict
+ * validation for a blueprint's `## Trust Dossier` section, but nothing
+ * generates a starting template. `TRUST_DOSSIER_SCAFFOLD` is a complete,
+ * already-valid worked example — proven by `scaffold.test.ts` to pass
+ * `validateBlueprintTrust` under both the strict configuration
+ * `wp audit blueprint-trust` uses and the draft-preflight configuration
+ * `wp_blueprint_put` / `preparePromotionTrustGate` use — so an author can
+ * paste it in and edit the example values instead of hand-deriving the
+ * contract from source.
+ *
+ * `verified-at` / `verified-head` stay as inert, obviously-fake placeholders:
+ * `preparePromotionTrustGate` (./promotion.ts) overwrites both with the real
+ * timestamp/HEAD on every promotion attempt, so there is no need for this
+ * pure, dependency-free module to shell out to git.
+ */
+const PLACEHOLDER_HEAD = "0".repeat(40);
+export const TRUST_DOSSIER_SCAFFOLD = `## Trust Dossier
+
+<!-- Trust Dossier scaffold — generated by \`wp blueprint trust-dossier\`. -->
+<!-- Replace every example value below, then delete these comment lines before promotion. -->
+<!-- Constraints enforced by \`wp audit blueprint-trust\` / \`wp_blueprint_put\`: -->
+<!-- - All 5 "###" subsections below are required, verbatim, exactly once each. -->
+<!-- - Material Claims "repo:<path>" evidence must be a bare, existing repo-relative path -->
+<!--   (no ":line" suffix, no leading "/", no "../"). -->
+<!-- - "Residual Unknowns" must render exactly \`None.\` when nothing is outstanding. -->
+<!-- - Promotion Gates "Command" must be a \`wp\` facade call: \`wp typecheck\`, \`wp lint\` -->
+<!--   (no extra args), \`wp test --file <path>\` (repeatable), or -->
+<!--   \`wp audit <kind> [--json|--affected|--branch|--base <val>]\`. -->
+<!-- - No TBD, TODO, "decide during implementation", "open question", or <placeholder> tokens -->
+<!--   anywhere in the 5 subsections below. -->
+
+### Readiness Verdict
+
+- promotion-ready: true
+- unresolved-count: 0
+- verified-at: 1970-01-01T00:00:00.000Z
+- verified-head: ${PLACEHOLDER_HEAD}
+- trust-gate-version: v1
+
+### Material Claims
+
+| ID | Claim | Evidence |
+| --- | --- | --- |
+| C1 | Example material claim — replace with a real, falsifiable claim this blueprint depends on. | repo:README.md |
+
+### Material Decisions
+
+| ID | Decision | Chosen option | Rejected alternatives | Rationale |
+| --- | --- | --- | --- | --- |
+| D1 | Example material decision — replace with a real decision this blueprint locks in. | Example chosen option. | Example rejected alternative and why it lost. | Example rationale for the chosen option. |
+
+### Promotion Gates
+
+| Gate | Command | Expected outcome | Last result |
+| --- | --- | --- | --- |
+| typecheck | wp typecheck | Typecheck passes with zero errors. | pass (scaffold example — rerun and record the real result before promotion) |
+
+### Residual Unknowns
+
+None.
+`;

package/dist/esm/blueprint/trust/validator.d.ts

@@ -8,6 +8,7 @@ export type ValidateBlueprintTrustInput = {
     promotionCandidate?: boolean;
     requirePassingGates?: boolean;
     scanTaskAmbiguity?: boolean;
+    allowDeferredGates?: boolean;
 };
 export type BlueprintTrustViolation = TrustDossierViolation & {
     file: string;

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

@@ -51,7 +51,8 @@ export function validateBlueprintTrust(input) {
                     message: error instanceof Error ? error.message : String(error),
                 });
             }
-            if (input.requirePassingGates !== false && !/^pass\b/iu.test(gate.lastResult))
+            if (input.requirePassingGates !== false &&
+                !isAcceptableGateResult(gate.lastResult, input.allowDeferredGates))
                 violations.push({
                     section: "Promotion Gates",
                     claimId: gate.gate,
@@ -64,3 +65,8 @@ export function validateBlueprintTrust(input) {
         violations: violations.map((v) => ({ ...v, file: input.file })),
     };
 }
+function isAcceptableGateResult(lastResult, allowDeferredGates) {
+    if (/^pass\b/iu.test(lastResult))
+        return true;
+    return allowDeferredGates === true && /^deferred:/iu.test(lastResult);
+}

package/dist/esm/blueprint/utils/archive.js

@@ -6,6 +6,7 @@
 import { access, readFile, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { parseBlueprint } from "#core/parser";
+import { getBlueprintDocumentCandidates } from "./document-paths.js";
 import { resolveBlueprintRoot } from "./blueprint-root.js";
 /**
  * Validates that all tasks in a plan are complete.
@@ -111,7 +112,13 @@ export async function archiveBlueprint(slug, projectPath) {
     if (isAlreadyCompleted(slug)) {
         return { success: false, error: "Plan is already completed" };
     }
-    const paths = buildPlanPaths(projectPath, slug);
+    const paths = await buildPlanPaths(projectPath, slug);
+    if (paths.ambiguousPaths) {
+        return {
+            success: false,
+            error: `Plan ${slug} exists in both flat and folder forms; remove one before archiving: ${paths.ambiguousPaths.join(", ")}`,
+        };
+    }
     // Check if plan exists
     const planExists = await checkPlanExists(paths.sourcePath);
     if (!planExists) {
@@ -132,16 +139,31 @@ export async function archiveBlueprint(slug, projectPath) {
 /**
  * Builds source and target paths for archival.
  *
+ * Resolves the existing flat or folder document via the shared candidates;
+ * when neither shape exists, falls back to the canonical folder path so the
+ * caller reports the same "Plan not found" error as before.
+ *
  * @param projectPath - Root path of the project
  * @param slug - Plan slug
  * @returns Path information
  */
-function buildPlanPaths(projectPath, slug) {
+async function buildPlanPaths(projectPath, slug) {
     const plansDir = resolveBlueprintRoot(projectPath);
-    const sourcePath = path.join(plansDir, slug, "_overview.md");
+    const candidates = getBlueprintDocumentCandidates(plansDir, slug);
+    const existing = [];
+    for (const candidate of candidates) {
+        if (await checkPlanExists(candidate))
+            existing.push(candidate);
+    }
+    const sourcePath = existing[0] ?? candidates.at(-1) ?? path.join(plansDir, slug, "_overview.md");
     const sourceDir = path.dirname(sourcePath);
-    const targetDir = sourceDir;
-    return { sourcePath, sourceDir, targetDir, planName: slug };
+    return {
+        sourcePath,
+        sourceDir,
+        targetDir: sourceDir,
+        planName: slug,
+        ...(existing.length > 1 ? { ambiguousPaths: existing } : {}),
+    };
 }
 /**
  * Extracts plan name from slug (removes status prefix).

package/dist/esm/blueprint/utils/document-paths.d.ts

@@ -8,6 +8,13 @@ export interface BlueprintDocumentPath {
     slug: string;
     state: BlueprintStatus;
 }
+export interface BlueprintDocumentIdentity extends BlueprintDocumentPath {
+    documentPath: string;
+    folderDirectory: string;
+    folderPath: string;
+    lifecycleSlug: string;
+    stableSlug: string;
+}
 export declare function normalizeBlueprintPath(filePath: string): string;
 export declare function isBlueprintStatus(value: string | undefined): value is BlueprintStatus;
 export declare function isBlueprintSlugSegment(value: string | undefined): value is string;
@@ -18,5 +25,16 @@ export declare function getBlueprintDocumentPaths(root: string, state: Blueprint
     flat: string;
     folder: string;
 };
+export declare function resolveBlueprintDocumentIdentity(root: string, documentPath: string): BlueprintDocumentIdentity | null;
+export declare function folderBlueprintRequiredMessage(identity: {
+    readonly documentPath: string;
+    readonly lifecycleSlug: string;
+    readonly shape: BlueprintShape;
+}): string;
+export declare function assertFolderBlueprintIdentity(identity: {
+    readonly documentPath: string;
+    readonly lifecycleSlug: string;
+    readonly shape: BlueprintShape;
+}): void;
 export declare function getBlueprintDocumentCandidates(root: string, slug: string): string[];
 export declare function getBlueprintAlternateDocumentPath(root: string, filePath: string): string | null;

package/dist/esm/blueprint/utils/document-paths.js

@@ -22,7 +22,7 @@ export function isBlueprintSlugSegment(value) {
 export function parseBlueprintDocumentRelativePath(filePath) {
     const normalized = normalizeBlueprintPath(filePath);
     const parts = normalized.split("/").filter((segment) => segment.length > 0);
-    const [state, second, third] = parts;
+    const [state, second] = parts;
     if (!isBlueprintStatus(state)) {
         return null;
     }
@@ -38,13 +38,16 @@ export function parseBlueprintDocumentRelativePath(filePath) {
             state,
         };
     }
-    if (parts.length === 3 &&
-        isBlueprintSlugSegment(second) &&
-        third === BLUEPRINT_OVERVIEW_FILENAME) {
+    if (parts.length >= 3 && parts.at(-1) === BLUEPRINT_OVERVIEW_FILENAME) {
+        const slugSegments = parts.slice(1, -1);
+        if (!slugSegments.every((segment) => isBlueprintSlugSegment(segment))) {
+            return null;
+        }
+        const slug = slugSegments.join("/");
         return {
-            relativePath: `${state}/${second}/${BLUEPRINT_OVERVIEW_FILENAME}`,
+            relativePath: `${state}/${slug}/${BLUEPRINT_OVERVIEW_FILENAME}`,
             shape: "folder",
-            slug: second,
+            slug,
             state,
         };
     }
@@ -53,13 +56,13 @@ export function parseBlueprintDocumentRelativePath(filePath) {
 export function isBlueprintSupportingMarkdownRelativePath(filePath) {
     const normalized = normalizeBlueprintPath(filePath);
     const parts = normalized.split("/").filter((segment) => segment.length > 0);
-    const [state, slug, doc] = parts;
-    return (parts.length === 3 &&
+    const [state] = parts;
+    return (parts.length >= 3 &&
         isBlueprintStatus(state) &&
-        isBlueprintSlugSegment(slug) &&
-        typeof doc === "string" &&
-        doc.endsWith(".md") &&
-        doc !== BLUEPRINT_OVERVIEW_FILENAME);
+        parts.slice(1, -1).every((segment) => isBlueprintSlugSegment(segment)) &&
+        typeof parts.at(-1) === "string" &&
+        parts.at(-1).endsWith(".md") &&
+        parts.at(-1) !== BLUEPRINT_OVERVIEW_FILENAME);
 }
 export function getBlueprintDocumentPaths(root, state, slug) {
     const directory = path.join(root, state, slug);
@@ -69,6 +72,36 @@ export function getBlueprintDocumentPaths(root, state, slug) {
         folder: path.join(directory, BLUEPRINT_OVERVIEW_FILENAME),
     };
 }
+export function resolveBlueprintDocumentIdentity(root, documentPath) {
+    const relativePath = normalizeBlueprintPath(path.relative(root, documentPath));
+    const parsed = parseBlueprintDocumentRelativePath(relativePath);
+    if (!parsed)
+        return null;
+    const paths = getBlueprintDocumentPaths(root, parsed.state, parsed.slug);
+    return {
+        ...parsed,
+        documentPath: parsed.shape === "flat" ? paths.flat : paths.folder,
+        folderDirectory: paths.directory,
+        folderPath: paths.folder,
+        lifecycleSlug: `${parsed.state}/${parsed.slug}`,
+        stableSlug: parsed.slug,
+    };
+}
+export function folderBlueprintRequiredMessage(identity) {
+    if (identity.shape === "folder") {
+        return "";
+    }
+    return [
+        `Blueprint evidence requires folder shape; ${identity.documentPath} is a flat blueprint.`,
+        `Run: wp blueprint canonicalize ${identity.lifecycleSlug}`,
+        "Then commit the canonicalized path and rerun the evidence command.",
+    ].join(" ");
+}
+export function assertFolderBlueprintIdentity(identity) {
+    const message = folderBlueprintRequiredMessage(identity);
+    if (message)
+        throw new Error(message);
+}
 export function getBlueprintDocumentCandidates(root, slug) {
     const normalized = normalizeBlueprintPath(slug);
     const segments = normalized.split("/").filter((segment) => segment.length > 0);

package/dist/esm/build/cli-mcp-parity.js

@@ -187,6 +187,11 @@ export const CLI_MCP_PARITY_CLASSIFICATION = {
         classification: "direct-fallback-by-design",
         reason: "internal serialization wrapper spawned by the auto-update, wp update, and setup lanes; never agent-facing",
     },
+    "optional-tool-refresh": {
+        command: "optional-tool-refresh",
+        classification: "direct-fallback-by-design",
+        reason: "internal detached worker spawned by provider launch freshness; never agent-facing",
+    },
     init: {
         command: "init",
         classification: "unsafe-credentialed-destructive",
@@ -229,6 +234,11 @@ export const CLI_MCP_PARITY_CLASSIFICATION = {
         classification: "direct-fallback-by-design",
         reason: "long-running local preview server remains a direct CLI workflow",
     },
+    "public:readiness": {
+        command: "public:readiness",
+        classification: "direct-fallback-by-design",
+        reason: "public package readiness performs local package/tarball checks and is intentionally not a read-only MCP workflow",
+    },
     qa: {
         command: "qa",
         classification: "existing-mcp",

package/dist/esm/cli/bundle/commands/blueprint.d.ts

@@ -1,6 +1,7 @@
 import type { CliCommand } from "@webpresso/cli-contract";
 export declare const blueprintCommands: {
     audit: CliCommand<Record<string, unknown>>;
+    canonicalize: CliCommand<Record<string, unknown>>;
     exec: CliCommand<Record<string, unknown>>;
     finalize: CliCommand<Record<string, unknown>>;
     list: CliCommand<Record<string, unknown>>;

package/dist/esm/cli/bundle/commands/blueprint.js

@@ -35,6 +35,7 @@ function createBlueprintAuditCommand() {
 }
 export const blueprintCommands = {
     audit: createBlueprintAuditCommand(),
+    canonicalize: placeholderCommand(SCOPE, "canonicalize", "Canonicalize a flat blueprint to folder shape"),
     exec: placeholderGroup(SCOPE, "exec", "Execute a blueprint", {
         logs: placeholderCommand(SCOPE, "logs", "Show blueprint execution logs"),
         resume: placeholderCommand(SCOPE, "resume", "Resume blueprint execution"),

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

@@ -5,7 +5,7 @@
  * Lazy-loads subcommand modules based on the first argv to keep startup
  * cheap. Modeled on apps/cli-wp/src/cli.ts.
  */
-declare const SUPPORTED_COMMANDS: readonly ["blueprint", "browser", "dash", "dash-helper-start", "dash-helper-complete", "claude", "codex", "grok", "opencode", "yolo", "config", "secrets", "roadmap", "status", "review", "sync", "audit", "qa", "ultragoal", "compile", "rule", "skill", "skills", "docs", "setup", "init", "dev", "deploy", "preview", "cleanup", "migrate", "doctor", "err", "test", "e2e", "ci", "ci-preflight", "typecheck", "lint", "format", "logs", "session-id", "session-info", "session", "tech-debt", "pr", "fleet", "worktree", "mcp", "hook", "hooks", "self-install-guard", "gain", "bench", "install", "add", "remove", "update", "exec", "run"];
+declare const SUPPORTED_COMMANDS: readonly ["blueprint", "browser", "dash", "dash-helper-start", "dash-helper-complete", "claude", "codex", "grok", "opencode", "yolo", "config", "secrets", "roadmap", "status", "review", "sync", "audit", "qa", "ultragoal", "compile", "rule", "skill", "skills", "docs", "setup", "init", "dev", "deploy", "preview", "cleanup", "migrate", "doctor", "err", "test", "e2e", "ci", "ci-preflight", "public:readiness", "typecheck", "lint", "format", "logs", "session-id", "session-info", "session", "tech-debt", "pr", "fleet", "worktree", "mcp", "hook", "hooks", "self-install-guard", "optional-tool-refresh", "gain", "bench", "install", "add", "remove", "update", "exec", "run"];
 export type SupportedCommand = (typeof SUPPORTED_COMMANDS)[number];
 type RootHelpEntry = {
     readonly command: string;

package/dist/esm/cli/cli.js

@@ -55,6 +55,7 @@ const SUPPORTED_COMMANDS = [
     "e2e",
     "ci",
     "ci-preflight",
+    "public:readiness",
     "typecheck",
     "lint",
     "format",
@@ -70,6 +71,7 @@ const SUPPORTED_COMMANDS = [
     "hook",
     "hooks",
     "self-install-guard",
+    "optional-tool-refresh",
     "gain",
     "bench",
     "install",
@@ -111,6 +113,10 @@ const ROOT_HELP_CORE_ENTRIES = [
         command: "ci-preflight",
         description: "Run the locally-runnable required CI checks fail-fast (the pre-push gate)",
     },
+    {
+        command: "public:readiness",
+        description: "Run the public package readiness gate through the portable wp surface",
+    },
     { command: "logs", description: "Print persisted raw output from recent quality runs" },
     { command: "dev", description: "Run a manifest-backed development target" },
     { command: "status", description: "Show unified local readiness and next action" },
@@ -364,6 +370,10 @@ const COMMAND_REGISTRARS = {
         const { registerCiPreflightCommand } = await import("./commands/ci-preflight.js");
         registerCiPreflightCommand(cli);
     },
+    "public:readiness": async (cli) => {
+        const { registerPublicReadinessCommand } = await import("./commands/public-readiness.js");
+        registerPublicReadinessCommand(cli);
+    },
     typecheck: async (cli) => {
         const { registerTypecheckCommand } = await import("./commands/typecheck.js");
         registerTypecheckCommand(cli);
@@ -422,6 +432,15 @@ const COMMAND_REGISTRARS = {
         const { registerSelfInstallGuardCommand } = await import("./commands/self-install-guard.js");
         registerSelfInstallGuardCommand(cli);
     },
+    "optional-tool-refresh": async (cli) => {
+        cli
+            .command("optional-tool-refresh <tool> [...args]", "Internal detached optional-tool freshness worker")
+            .allowUnknownOptions()
+            .action(async (tool, args = []) => {
+            const { runOptionalToolRefreshWorker } = await import("./optional-tool-freshness.js");
+            process.exitCode = runOptionalToolRefreshWorker([tool, ...args]);
+        });
+    },
     gain: async (cli) => {
         const { registerGainCommand } = await import("./commands/gain/index.js");
         registerGainCommand(cli);
@@ -636,6 +655,21 @@ export async function main() {
         console.error(formatUnknownCommandError(command, SUPPORTED_COMMANDS));
         return 1;
     }
+    // `wp run wait` is the read-only workflow-run waiter, intercepted before the
+    // package-manager `run` facade (which maps `wp run <script>` to `vp run
+    // <script>`). Without this, `wait` would be treated as a package script name.
+    // Errors resolve to an exit code here, mirroring main()'s catch below, so a
+    // bad flag never rejects the main() promise.
+    if (resolvedCommand === "run" && argv[3] === "wait") {
+        const { runRunWaitCommand } = await import("./commands/run-wait.js");
+        try {
+            return await runRunWaitCommand(argv.slice(4));
+        }
+        catch (error) {
+            console.error(error instanceof Error ? error.message : String(error));
+            return 1;
+        }
+    }
     await COMMAND_REGISTRARS[resolvedCommand](cli, resolvedCommand);
     if (resolvedCommand === "session") {
         const { runSessionCommand } = await import("./commands/session.js");