@webpresso/agent-kit 3.1.28 → 3.2.0

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

@@ -24,9 +24,9 @@ import { getBlueprintDocumentPaths } from "#utils/document-paths.js";
 import { resolveBlueprintRoot } from "#utils/blueprint-root.js";
 import { reIngestProjection } from "#projection-ready.js";
 import { assertAllTasksHaveCanonicalPassingEvidence } from "#verification.js";
-import { applyPromotionTrustGate } from "#trust/promotion.js";
+import { assertPromotionTrustProofCurrent, preparePromotionTrustGate, } from "#trust/promotion.js";
 import matter from "gray-matter";
-import { evaluateApprovalGate, formatApprovalGateRequirement } from "#lifecycle/audit";
+import { assertCompletedApprovalGate, evaluateApprovalGate, formatApprovalGateRequirement, } from "#lifecycle/audit";
 /**
  * Module-level factory.  `null` = use the production default (loadSyncCredentials
  * from auth.ts + BlueprintSyncClient + ReplicaManager — lazy-imported so that
@@ -161,6 +161,31 @@ async function reIngestDb(cwd) {
         return;
     await reIngestProjection(cwd);
 }
+/**
+ * Force reingest of one blueprint document even when the stored content hash
+ * still matches. Used on complete so task-table lag cannot block finalize.
+ */
+async function forceReIngestBlueprint(cwd, slug, documentPath) {
+    const target = dbPath(cwd);
+    if (!existsSync(target))
+        return;
+    try {
+        const conn = openDb(target);
+        try {
+            // Invalidate hash so ingestAll's skip-if-unchanged path rewrites tasks.
+            conn.db.prepare(`UPDATE blueprints SET content_hash = NULL WHERE slug = ?`).run(slug);
+        }
+        finally {
+            conn.close();
+        }
+        await reIngestProjection(cwd);
+    }
+    catch {
+        // Projection is best-effort for complete; markdown gate already passed.
+        // Swallow so a broken local projection cannot block lifecycle completion.
+        void documentPath;
+    }
+}
 /**
  * Update `status:` in YAML frontmatter. Preserves everything else verbatim.
  */
@@ -296,19 +321,38 @@ async function advanceTaskLocked(cwd, blueprintSlug, taskId, toStatus) {
  * - Re-ingests into DB
  */
 export async function promoteBlueprint(cwd, slug, toState) {
+    const adapter = await resolveSyncAdapterForCli(cwd);
+    // Pull platform state under the mutation lock, then release it before any
+    // Trust Dossier command spawns a child `wp`. Child startup/ingestion can
+    // legitimately need the same repo-scoped lock.
+    await withMarkdownWriteLock(cwd, () => runCliPlatformMutationSync(adapter, {
+        label: "wp_blueprint_promote",
+        ensureFreshSlug: slug,
+    }));
+    const found = findBlueprintDocument(resolveBlueprintRoot(cwd), slug);
+    if (!found) {
+        throw new Error(`Blueprint "${slug}" not found in any state directory under ${resolveBlueprintRoot(cwd)}`);
+    }
+    const crossesDraftApprovalBoundary = found.state === "draft" && (toState === "planned" || toState === "in-progress");
+    const trustProof = crossesDraftApprovalBoundary
+        ? preparePromotionTrustGate({
+            repoRoot: cwd,
+            file: found.documentPath,
+            markdown: readFileSync(found.documentPath, "utf8"),
+        })
+        : null;
     // F9/R7: cross-worktree markdown writes serialize via the repo-scoped lock.
-    return withMarkdownWriteLock(cwd, () => promoteBlueprintLocked(cwd, slug, toState));
+    // The proof is revalidated inside this lock before any lifecycle write.
+    return withMarkdownWriteLock(cwd, () => promoteBlueprintLocked(cwd, slug, toState, adapter, trustProof));
 }
-async function promoteBlueprintLocked(cwd, slug, toState) {
+async function promoteBlueprintLocked(cwd, slug, toState, adapter, trustProof) {
     const blueprintRoot = resolveBlueprintRoot(cwd);
     const found = findBlueprintDocument(blueprintRoot, slug);
     if (!found) {
         throw new Error(`Blueprint "${slug}" not found in any state directory under ${blueprintRoot}`);
     }
     const { dir: currentDir, documentPath: currentDocumentPath, shape, state: currentState } = found;
-    // Guard: refuse to complete if any tasks are not done/dropped
-    if (toState === "completed") {
-        const markdown = readFileSync(currentDocumentPath, "utf8");
+    const assertCompletionReady = (markdown) => {
         const blueprint = parseBlueprint(markdown, slug);
         if (blueprint.tasks.length === 0) {
             throw new Error(`Cannot promote "${slug}" to completed: zero-task blueprints cannot complete through the public lifecycle surface`);
@@ -319,43 +363,30 @@ async function promoteBlueprintLocked(cwd, slug, toState) {
             throw new Error(`Cannot promote "${slug}" to completed: the following tasks are not done/dropped: ${list}`);
         }
         assertAllTasksHaveCanonicalPassingEvidence(markdown, blueprint.tasks.filter((task) => task.status === "done").map((task) => task.id));
-        const target = dbPath(cwd);
-        if (existsSync(target)) {
-            const conn = openDb(target);
-            let openTasks;
-            try {
-                openTasks = conn.db
-                    .prepare(`SELECT task_id, status FROM tasks WHERE blueprint_slug = ? AND status NOT IN ('done', 'dropped')`)
-                    .all(slug);
-            }
-            finally {
-                conn.close();
-            }
-            if (openTasks.length > 0) {
-                const list = openTasks.map((t) => `${t.task_id} (${t.status})`).join(", ");
-                throw new Error(`Cannot promote "${slug}" to completed: the following tasks are not done: ${list}`);
-            }
+        // Completion parity with CI: the CLI completion owner uses the same
+        // audit-owned gate as the MCP funnel and execution engine, so all normal
+        // paths into `completed` enforce the same plan-purpose approval.
+        try {
+            assertCompletedApprovalGate(currentDocumentPath, markdown);
         }
-    }
-    // Platform freshness must be resolved before trust validation so the proof
-    // applies to the current replica, not stale local markdown.
-    // Iron rule: resolveSyncAdapterForCli() returns null when WP_BLUEPRINT_PLATFORM_DISABLED=1.
-    const adapter = await resolveSyncAdapterForCli(cwd);
-    await runCliPlatformMutationSync(adapter, {
-        label: "wp_blueprint_promote",
-        ensureFreshSlug: slug,
-    });
+        catch (error) {
+            throw new Error(`Cannot complete "${slug}": ${error instanceof Error ? error.message : String(error)}`);
+        }
+    };
     // Trust must be proven before any platform status_changed event is published.
     let content = readFileSync(currentDocumentPath, "utf8");
     let trustedSource = content;
+    if (toState === "completed") {
+        assertCompletionReady(content);
+    }
     const crossesDraftApprovalBoundary = currentState === "draft" && (toState === "planned" || toState === "in-progress");
     if (crossesDraftApprovalBoundary) {
-        content = applyPromotionTrustGate({
-            repoRoot: cwd,
-            file: currentDocumentPath,
-            markdown: content,
-        });
-        trustedSource = readFileSync(currentDocumentPath, "utf8");
+        if (trustProof === null) {
+            throw new Error("Blueprint trust gate invalidated: no external gate proof is available");
+        }
+        assertPromotionTrustProofCurrent({ repoRoot: cwd, file: currentDocumentPath, markdown: content }, trustProof);
+        content = trustProof.trustedMarkdown;
+        trustedSource = trustProof.sourceMarkdown;
         // Governance Piece 1 — HARD gate at the promotion boundary. One
         // provenance-backed Claude/Codex/Grok or OpenCode-Go model approval can
         // promote. Check AFTER the trust gate so trust failures surface first.
@@ -385,18 +416,23 @@ async function promoteBlueprintLocked(cwd, slug, toState) {
         if (crossesDraftApprovalBoundary) {
             const refreshedSource = readFileSync(currentDocumentPath, "utf8");
             if (refreshedSource !== trustedSource) {
-                content = applyPromotionTrustGate({
-                    repoRoot: cwd,
-                    file: currentDocumentPath,
-                    markdown: refreshedSource,
-                });
-                const approvalEvaluation = evaluateApprovalGate(currentDocumentPath, matter(content).data.approvals);
-                if (!approvalEvaluation.satisfied) {
-                    throw new Error(`Cannot promote "${slug}" to ${toState}: frontmatter \`approvals:\` does not satisfy the promotion reviewer mix (${formatApprovalGateRequirement(approvalEvaluation)}). Record approvals, commit the matching review ledger (e.g. reviews.md), and include tracked review transcript/artifact files referenced by each structured review entry — see catalog/agent/rules/pre-implementation.md.`);
-                }
+                throw new Error(`Cannot promote "${slug}" to ${toState}: blueprint changed after external trust gates ran; retry promotion`);
             }
+            assertPromotionTrustProofCurrent({ repoRoot: cwd, file: currentDocumentPath, markdown: refreshedSource }, trustProof);
+        }
+        if (toState === "completed") {
+            // The platform pull can replace the document after the first completion
+            // check. Re-read and re-assert against the exact content written below.
+            content = readFileSync(currentDocumentPath, "utf8");
+            assertCompletionReady(content);
         }
     }
+    if (toState === "completed") {
+        // Best-effort projection refresh. Clear content hash first so a lagging
+        // tasks table is rewritten even when a prior corrupt UPDATE left the
+        // stored hash equal to current markdown.
+        await forceReIngestBlueprint(cwd, slug, currentDocumentPath);
+    }
     // Always update local markdown + SQLite.
     // Platform-first: these become derived artifacts; disabled: these are canonical.
     // Update frontmatter in the current location first, then move

package/dist/esm/cli/commands/blueprint/router-dispatch.d.ts

@@ -1,6 +1,6 @@
 import type { BlueprintAuditResult, BlueprintSummary } from "#local";
 import type { BlueprintTemplateEntry } from "#sync/types.js";
-import type { AdvanceTaskResult, BlueprintCommandOptions, BlueprintLifecycleMutationResult, CreateBlueprintResult, ExportBlueprintResult, ExecuteBlueprintResult, MoveBlueprintResult, PromoteBlueprintResult, ShowBlueprintResult } from "./router.js";
+import type { AdvanceTaskResult, BlueprintCommandOptions, BlueprintCanonicalizeResult, BlueprintLifecycleMutationResult, CreateBlueprintResult, ExportBlueprintResult, ExecuteBlueprintResult, MoveBlueprintResult, PromoteBlueprintResult, ShowBlueprintResult } from "./router.js";
 /**
  * Override the platform template fetcher — for tests only.
  * Pass `null` to restore the production default.
@@ -21,6 +21,7 @@ export declare class BlueprintAuditFailedError extends Error {
 interface BlueprintCommandDependencies {
     advanceBlueprintTask: (slug: string, taskId: string, toStatus: string, options: BlueprintCommandOptions) => Promise<AdvanceTaskResult>;
     auditBlueprints: (options: BlueprintCommandOptions) => Promise<BlueprintAuditResult>;
+    canonicalizeBlueprintBySlug: (slug: string, options: BlueprintCommandOptions) => Promise<BlueprintCanonicalizeResult>;
     controlBlueprintExec: (action: "status" | "resume" | "stop", slug: string, options: BlueprintCommandOptions) => Promise<ExecuteBlueprintResult>;
     readBlueprintExecutionLogs: (slug: string, options: BlueprintCommandOptions) => Promise<ExecuteBlueprintResult>;
     createBlueprint: (goal: string, options: BlueprintCommandOptions) => Promise<CreateBlueprintResult>;

package/dist/esm/cli/commands/blueprint/router-dispatch.js

@@ -3,7 +3,9 @@ import { tmpdir } from "node:os";
 import { randomUUID } from "node:crypto";
 import path from "node:path";
 import { executeBlueprintDbSubcommand } from "./db-commands.js";
+import { getBlueprintSubcommandNames } from "./router-output.js";
 import { listTemplates, resolveTemplate } from "./template-resolver.js";
+import { TRUST_DOSSIER_SCAFFOLD } from "#trust/scaffold.js";
 // ---------------------------------------------------------------------------
 // Platform template fetcher (injectable for tests)
 // ---------------------------------------------------------------------------
@@ -232,6 +234,15 @@ export async function executeBlueprintSubcommand(subcommand, args, options, deps
             deps.printBlueprintOutput(options.json ? result : result.message, options.json);
             return;
         }
+        case "canonicalize": {
+            const slug = args[0];
+            if (!slug) {
+                throw new Error("Usage: wp blueprint canonicalize <slug>");
+            }
+            const result = await deps.canonicalizeBlueprintBySlug(slug, options);
+            deps.printBlueprintOutput(options.json ? { from: result.from, to: result.to, moved: result.moved } : result.message, options.json);
+            return;
+        }
         case "start": {
             const slug = args[0];
             if (!slug) {
@@ -350,8 +361,16 @@ export async function executeBlueprintSubcommand(subcommand, args, options, deps
             deps.printBlueprintOutput(options.json ? result : result.message, options.json);
             return;
         }
+        case "trust-dossier": {
+            // Read-only: prints an already-valid "## Trust Dossier" starter block
+            // (src/blueprint/trust/scaffold.ts). No file writes, no worktree/lock
+            // interaction — an author pastes the output into their overview and
+            // edits the example values.
+            deps.printBlueprintOutput(options.json ? { markdown: TRUST_DOSSIER_SCAFFOLD } : TRUST_DOSSIER_SCAFFOLD, options.json);
+            return;
+        }
         default: {
-            throw new Error(`Unknown blueprint subcommand: ${subcommand}\n\nUse one of: list, new, show, exec, start, park, task, finalize, promote, audit, move, control, logs, db, export`);
+            throw new Error(`Unknown blueprint subcommand: ${subcommand}\n\nUse one of: ${getBlueprintSubcommandNames().join(", ")}`);
         }
     }
 }

package/dist/esm/cli/commands/blueprint/router-output.d.ts

@@ -1,7 +1,28 @@
 import type { Blueprint, BlueprintAuditResult, BlueprintSummary } from "#local";
 import type { CreateBlueprintResult, ExecuteBlueprintResult, ShowBlueprintResult } from "./router.js";
+/**
+ * Canonical registry of every subcommand `router-dispatch.ts` actually
+ * dispatches. This is the single source of truth for both the `--help`
+ * `Commands:` block (see `BLUEPRINT_HELP` below) and the unknown-subcommand
+ * error list — so a subcommand can't ship dispatched-but-undocumented
+ * again. `router-dispatch.test.ts` asserts this list stays equal to the
+ * live `case "…":` labels in the dispatch switch.
+ */
+export interface BlueprintSubcommandSpec {
+    /** Matches a `case "<name>":` label in router-dispatch.ts exactly. */
+    readonly name: string;
+    /** One or more `Commands:` lines (without the leading indent). */
+    readonly usage: readonly string[];
+}
+export declare const BLUEPRINT_SUBCOMMANDS: readonly BlueprintSubcommandSpec[];
 export declare function formatTaskLine(task: Blueprint["tasks"][number]): string;
 export declare function getBlueprintHelpText(): string;
+/**
+ * Subcommand names in registry order, for the unknown-subcommand error
+ * message. Kept as a function (rather than exporting a derived constant)
+ * so the source of truth stays singular: `BLUEPRINT_SUBCOMMANDS`.
+ */
+export declare function getBlueprintSubcommandNames(): readonly string[];
 export interface BlueprintInventorySummary {
     total: number;
     byStatus: Record<string, number>;

package/dist/esm/cli/commands/blueprint/router-output.js

@@ -1,25 +1,48 @@
 import { buildRoadmapModel, planStatusSchema } from "#local";
+export const BLUEPRINT_SUBCOMMANDS = [
+    { name: "list", usage: ["list [status]"] },
+    {
+        name: "new",
+        usage: ["new <goal> --complexity <XS|S|M|L|XL> [--type <blueprint|parent-roadmap>]"],
+    },
+    { name: "show", usage: ["show <slug>"] },
+    {
+        name: "exec",
+        usage: [
+            "exec <slug>",
+            "exec status <slug>",
+            "exec resume <slug>",
+            "exec stop <slug>",
+            "exec logs <slug>",
+        ],
+    },
+    { name: "start", usage: ["start <slug>"] },
+    { name: "park", usage: ["park <slug>"] },
+    {
+        name: "task",
+        usage: [
+            "task start <slug> <taskId>",
+            "task block <slug> <taskId> --reason <text>",
+            "task unblock <slug> <taskId>",
+            "task complete <slug> <taskId>",
+        ],
+    },
+    { name: "finalize", usage: ["finalize <slug>"] },
+    { name: "promote", usage: ["promote <slug> <planned|in-progress|completed|parked>"] },
+    { name: "audit", usage: ["audit [--staged|--all] [--strict]"] },
+    { name: "move", usage: ["move <slug> <status> --force-recovery"] },
+    { name: "canonicalize", usage: ["canonicalize <slug>"] },
+    { name: "control", usage: ["control <status|resume|stop> <slug>"] },
+    { name: "logs", usage: ["logs <slug>"] },
+    { name: "db", usage: ["db <verb> [...args]"] },
+    { name: "export", usage: ["export --format spec-kit <slug>"] },
+    { name: "trust-dossier", usage: ["trust-dossier"] },
+];
 const BLUEPRINT_HELP = [
     "Blueprint management",
     "",
     "Commands:",
-    "  list [status]",
-    "  new <goal> --complexity <XS|S|M|L|XL> [--type <blueprint|parent-roadmap>]",
-    "  show <slug>",
-    "  exec <slug>",
-    "  exec status <slug>",
-    "  exec resume <slug>",
-    "  exec stop <slug>",
-    "  exec logs <slug>",
-    "  start <slug>",
-    "  park <slug>",
-    "  task start <slug> <taskId>",
-    "  task block <slug> <taskId> --reason <text>",
-    "  task unblock <slug> <taskId>",
-    "  task complete <slug> <taskId>",
-    "  finalize <slug>",
-    "  audit [--staged|--all] [--strict]",
-    "  move <slug> <status> --force-recovery",
+    ...BLUEPRINT_SUBCOMMANDS.flatMap((spec) => spec.usage.map((line) => `  ${line}`)),
 ].join("\n");
 export function formatTaskLine(task) {
     const checkbox = task.status === "done" || task.status === "dropped" ? "x" : " ";
@@ -28,6 +51,14 @@ export function formatTaskLine(task) {
 export function getBlueprintHelpText() {
     return BLUEPRINT_HELP;
 }
+/**
+ * Subcommand names in registry order, for the unknown-subcommand error
+ * message. Kept as a function (rather than exporting a derived constant)
+ * so the source of truth stays singular: `BLUEPRINT_SUBCOMMANDS`.
+ */
+export function getBlueprintSubcommandNames() {
+    return BLUEPRINT_SUBCOMMANDS.map((spec) => spec.name);
+}
 export function summarizeBlueprintInventory(summaries) {
     const byStatus = Object.fromEntries(planStatusSchema.options.toSorted().map((status) => [status, 0]));
     const byType = {

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

@@ -73,6 +73,12 @@ export interface BlueprintLifecycleMutationResult {
     status: string;
     taskId?: string;
 }
+export interface BlueprintCanonicalizeResult {
+    from: string;
+    to: string;
+    moved: boolean;
+    message: string;
+}
 export interface CreateBlueprintResult extends CreatedBlueprint {
     message: string;
     /** True when draft was auto-routed off a primary-like checkout (H-009 DX). */
@@ -123,6 +129,7 @@ export declare function exportBlueprint(slug: string, format: string, options?:
 export declare function advanceBlueprintTask(slug: string, taskId: string, toStatus: string, options?: BlueprintMoveOptions): Promise<AdvanceTaskResult>;
 export declare function promoteBlueprintToState(slug: string, toState: string, options?: BlueprintMoveOptions): Promise<PromoteBlueprintResult>;
 export declare function finalizeBlueprintBySlug(slug: string, options?: BlueprintMoveOptions): Promise<PromoteBlueprintResult>;
+export declare function canonicalizeBlueprintBySlug(slug: string, options?: BlueprintMoveOptions): Promise<BlueprintCanonicalizeResult>;
 export declare function registerBlueprintRouter(cli: CAC): void;
 export declare function _setBlueprintExecCommandExistsForTests(probe: ((command: string) => boolean) | null): void;
 export declare function _setBlueprintExecStarterForTests(starter: ((slug: string, options: BlueprintMoveOptions) => Promise<BlueprintLifecycleMutationResult>) | null): void;

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

@@ -5,9 +5,12 @@ import { parseBlueprintForDb } from "#db/parser/blueprint-db-parser";
 import { blueprintToSpecKit } from "#export/spec-kit/index";
 import { getProjectRoot } from "#cli/utils";
 import { commandExists as defaultCommandExists } from "#runtime/command-exists.js";
-import { clearBlueprintWorktreeOwnership, ensureBlueprintOwnerWorktree, } from "#worktrees/manager.js";
+import { adoptBlueprintOwnerWorktree, clearBlueprintWorktreeOwnership, ensureBlueprintOwnerWorktree, } from "#worktrees/manager.js";
+import { resolveCurrentManagedWorktreeContext } from "#worktrees/current.js";
+import { canonicalizeWorktreePath, WORKTREE_PROBE_TIMEOUT_MS } from "#worktrees/identity.js";
 import { resolveBlueprintRoot } from "#utils/blueprint-root";
 import { getBlueprintDocumentPaths } from "#utils/document-paths.js";
+import { canonicalizeBlueprint } from "#lifecycle/canonicalize.js";
 import { applyBlueprintLifecycleToFile, BlueprintCreationService, BlueprintService, complexitySchema, relativeBlueprintSlug, parseBlueprint, planStatusSchema, runBlueprintAudit, resolveBlueprintFile, serializeBlueprint, validateAllTasksDone, } from "#local";
 import { resolvePackageAssetPreferred } from "#utils/package-assets";
 import { resolveDraftAuthoringRoot } from "#worktrees/draft-authoring-root.js";
@@ -392,7 +395,16 @@ export async function startBlueprint(slug, options = {}) {
     if (source.blueprint.status !== "planned") {
         throw new Error(`Blueprint ${source.slug} must be planned before start (current: ${source.blueprint.status}).`);
     }
-    const binding = ensureBlueprintOwnerWorktree(projectRoot, relativeBlueprintSlug(slug));
+    const relativeSlug = relativeBlueprintSlug(slug);
+    const currentManaged = resolveCurrentManagedWorktreeContext(projectRoot);
+    const canonicalProjectRoot = canonicalizeWorktreePath(projectRoot);
+    const currentBranch = readCurrentGitBranch(projectRoot);
+    const binding = currentManaged &&
+        currentManaged.kind === "owner" &&
+        currentManaged.worktreePath === canonicalProjectRoot &&
+        currentBranch === `bp/${relativeSlug}`
+        ? adoptBlueprintOwnerWorktree(currentManaged.repoRoot, relativeSlug, currentManaged.worktreePath)
+        : ensureBlueprintOwnerWorktree(projectRoot, relativeSlug);
     const result = await applyLifecycleMutation(slug, {
         type: "start",
         worktreeOwnerId: binding.id,
@@ -404,6 +416,20 @@ export async function startBlueprint(slug, options = {}) {
         ownerWorktreePath: binding.path,
     };
 }
+function readCurrentGitBranch(cwd) {
+    try {
+        const branch = execFileSync("git", ["branch", "--show-current"], {
+            cwd,
+            encoding: "utf8",
+            timeout: WORKTREE_PROBE_TIMEOUT_MS,
+            stdio: ["ignore", "pipe", "ignore"],
+        }).trim();
+        return branch.length > 0 ? branch : null;
+    }
+    catch {
+        return null;
+    }
+}
 export async function parkBlueprint(slug, options = {}) {
     const projectRoot = resolveProjectRoot(options.projectRoot);
     const result = await applyLifecycleMutation(slug, { type: "park" }, projectRoot);
@@ -487,9 +513,19 @@ export async function finalizeBlueprintBySlug(slug, options = {}) {
     const projectRoot = resolveProjectRoot(options.projectRoot);
     return finalizeBlueprintMutation(projectRoot, slug);
 }
+export async function canonicalizeBlueprintBySlug(slug, options = {}) {
+    const projectRoot = resolveProjectRoot(options.projectRoot);
+    const result = await canonicalizeBlueprint(projectRoot, slug);
+    return {
+        ...result,
+        message: result.moved
+            ? `Canonicalized blueprint ${slug}: ${result.from} -> ${result.to}`
+            : `Blueprint ${slug} is already canonical: ${result.to}`,
+    };
+}
 export function registerBlueprintRouter(cli) {
     cli
-        .command("blueprint [subcommand] [...args]", "Manage blueprints. Use: wp blueprint <action> --help for action-specific options (new, list, show, audit, exec, move, finalize, start, task)")
+        .command("blueprint [subcommand] [...args]", "Manage blueprints. Use: wp blueprint <action> --help for action-specific options (new, list, show, audit, exec, move, finalize, start, task, trust-dossier)")
         .option("--json", "Print JSON output")
         .option("--no-tui", "Use plain terminal output")
         .option("--complexity <complexity>", "Blueprint complexity (XS|S|M|L|XL)")
@@ -510,6 +546,7 @@ export function registerBlueprintRouter(cli) {
             await executeBlueprintSubcommand(subcommand, args, options, {
                 advanceBlueprintTask,
                 auditBlueprints,
+                canonicalizeBlueprintBySlug,
                 createBlueprint,
                 controlBlueprintExec,
                 executeBlueprint,

package/dist/esm/cli/commands/ci-preflight.d.ts

@@ -31,9 +31,20 @@ export interface CiPreflightDeps {
     readonly cwd?: string;
     readonly resolveRepoRoot?: (cwd: string) => string | null;
     readonly hasNodeModules?: (repoRoot: string) => boolean;
-    readonly runCheck?: (check: CiPreflightCheck, repoRoot: string) => number;
+    readonly runCheck?: (check: CiPreflightCheck, repoRoot: string) => number | Promise<number>;
     readonly stdout?: Pick<typeof process.stdout, "write">;
     readonly stderr?: Pick<typeof process.stderr, "write">;
 }
-export declare function runCiPreflight(deps?: CiPreflightDeps): number;
+/**
+ * Re-invoke the same `wp` runtime that is currently executing so each check
+ * runs the real verb (faithful CI parity) rather than a reimplemented copy of
+ * its affected-resolution logic. Prefers the repo-local `bin/wp` launcher when
+ * present so the exact source/compiled selection and NODE_PATH wiring apply;
+ * falls back to the running runtime for consumer repos with a global `wp`.
+ */
+export declare function resolveWpLauncher(repoRoot: string): {
+    readonly command: string;
+    readonly prefixArgs: readonly string[];
+};
+export declare function runCiPreflight(deps?: CiPreflightDeps): Promise<number>;
 export declare function registerCiPreflightCommand(cli: CAC): void;

package/dist/esm/cli/commands/ci-preflight.js

@@ -57,7 +57,10 @@ function reproduceLine(check) {
  * present so the exact source/compiled selection and NODE_PATH wiring apply;
  * falls back to the running runtime for consumer repos with a global `wp`.
  */
-function resolveWpLauncher(repoRoot) {
+// Exported so `src/mcp/tools/ci-preflight.ts` can re-invoke the exact same
+// `wp` launcher when it substitutes an output-capturing `runCheck` for the
+// default `stdio: "inherit"` spawn — do not duplicate this resolution logic.
+export function resolveWpLauncher(repoRoot) {
     const localLauncher = path.join(repoRoot, "bin", process.platform === "win32" ? "wp.cmd" : "wp");
     if (existsSync(localLauncher))
         return { command: localLauncher, prefixArgs: [] };
@@ -82,7 +85,7 @@ function defaultRunCheck(check, repoRoot) {
     }
     return typeof result.status === "number" ? result.status : 1;
 }
-export function runCiPreflight(deps = {}) {
+export async function runCiPreflight(deps = {}) {
     const cwd = deps.cwd ?? process.cwd();
     const stdout = deps.stdout ?? process.stdout;
     const stderr = deps.stderr ?? process.stderr;
@@ -100,7 +103,7 @@ export function runCiPreflight(deps = {}) {
     }
     for (const check of CI_PREFLIGHT_CHECKS) {
         stdout.write(`\nwp ci-preflight: running ${check.label} (${reproduceLine(check)})\n`);
-        const exitCode = runCheck(check, repoRoot);
+        const exitCode = await runCheck(check, repoRoot);
         if (exitCode !== 0) {
             const normalizedExit = exitCode === 0 ? 1 : exitCode;
             stderr.write(`\nwp ci-preflight: ${check.label} failed (exit ${normalizedExit}).\n` +

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

@@ -2,12 +2,14 @@ import type { CAC } from "cac";
 import type { SecretGateCommandOptions, SecretGateRunResult } from "#secret-gate/runner.js";
 import { type CiActEventName, type CiActExecutionMode } from "#ci/act-runner.js";
 export declare const DEFAULT_CI_ACT_TIMEOUT_MS: number;
+export declare const SMOKE_CI_ACT_TIMEOUT_MS = 30000;
 export declare const MAX_CI_ACT_TIMEOUT_MS: number;
 export declare const CI_COMMAND_HELP: string;
 export interface CiActOptions {
     readonly workflow?: string;
     readonly workflowPath?: string;
     readonly job?: string;
+    readonly matrix?: readonly string[];
     readonly eventName?: CiActEventName;
     readonly eventPath?: string;
     readonly envProfile?: string;
@@ -17,6 +19,7 @@ export interface CiActOptions {
     readonly platformImage?: string;
     readonly execute?: boolean;
     readonly timeoutMs?: number;
+    readonly smoke?: boolean;
 }
 export interface CiCommandConfig {
     readonly command: string;
@@ -32,5 +35,9 @@ export declare function registerCiCommand(cli: CAC): void;
 export declare function buildCiActCommand(options?: CiActOptions, cwd?: string): CiCommandConfig;
 export declare function validateCiActCommand(..._legacyArgs: readonly unknown[]): string | null;
 export declare function runCiActCommand(options?: CiActOptions, deps?: CiCommandDeps): Promise<number>;
-export declare function normalizeCiActTimeoutMs(value: number | undefined): number;
+export declare function normalizeCiActTimeoutMs(value: number | undefined, options?: {
+    readonly smoke?: boolean;
+}): number;
 export declare function parseCiActTimeoutMs(value: unknown): number | undefined;
+export declare function parseCiActExecutionMode(value: unknown): CiActExecutionMode | undefined;
+export declare function parseCiActEventName(value: unknown): CiActEventName | undefined;