@webpresso/agent-kit 3.1.30 → 3.3.0

package/dist/esm/cli/cli.js

@@ -55,9 +55,11 @@ const SUPPORTED_COMMANDS = [
     "e2e",
     "ci",
     "ci-preflight",
+    "public:readiness",
     "typecheck",
     "lint",
     "format",
+    "rust-check",
     "logs",
     "session-id",
     "session-info",
@@ -70,6 +72,7 @@ const SUPPORTED_COMMANDS = [
     "hook",
     "hooks",
     "self-install-guard",
+    "optional-tool-refresh",
     "gain",
     "bench",
     "install",
@@ -101,6 +104,10 @@ const ROOT_HELP_CORE_ENTRIES = [
         command: "format",
         description: "Format through the portable wp surface (--check for CI/husky)",
     },
+    {
+        command: "rust-check",
+        description: "Prove affected tracked Rust crates compile and pass tests (cargo check + test)",
+    },
     {
         command: "e2e",
         description: "Build and run E2E commands through the portable webpresso surface",
@@ -111,6 +118,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 +375,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);
@@ -376,6 +391,10 @@ const COMMAND_REGISTRARS = {
         const { registerFormatCommand } = await import("./commands/format.js");
         registerFormatCommand(cli);
     },
+    "rust-check": async (cli) => {
+        const { registerRustCheckCommand } = await import("./commands/rust-check.js");
+        registerRustCheckCommand(cli);
+    },
     logs: async (cli) => {
         const { registerLogsCommand } = await import("./commands/logs.js");
         registerLogsCommand(cli);
@@ -422,6 +441,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 +664,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");

package/dist/esm/cli/commands/agent-launch.d.ts

@@ -2,6 +2,8 @@ import type { CAC } from "cac";
 import { type DashPermissionMode, type DashProvider } from "#cli/commands/dash/provider-capabilities.js";
 import { type RuntimeCommandOptions } from "#runtime/executor.js";
 import { type SecretsConfig } from "#runtime/secrets-config.js";
+import { resolveOpencodeAccountsGracefully } from "#runtime/opencode-account-materializer.js";
+import { resolveHealthyOpencodeAccount } from "#cli/commands/opencode-probe.js";
 export declare const AGENT_LAUNCH_COMMANDS: readonly ["claude", "codex", "grok", "opencode"];
 export type AgentLaunchCommand = DashProvider;
 export declare const DEFAULT_AGENT_SECRET_PROFILE = "preview";
@@ -18,6 +20,11 @@ export interface AgentLaunchDeps {
         error?: Error;
     };
     readonly ensureCodexSkillSurface?: (cwd: string, env?: NodeJS.ProcessEnv) => string | null;
+    readonly resolveOpencodeAccounts?: typeof resolveOpencodeAccountsGracefully;
+    readonly materializeGlobalOpencodeAuth?: (key: string) => void;
+    readonly readActiveKey?: () => string | undefined;
+    readonly recordCooldown?: (canonicalId: string) => Promise<unknown>;
+    readonly resolveHealthyOpencodeAccount?: typeof resolveHealthyOpencodeAccount;
 }
 export declare function buildDefaultAgentArgs(command: AgentLaunchCommand, args?: readonly string[], permissionMode?: DashPermissionMode): readonly string[];
 export declare function isAgentLaunchCommand(command: string | undefined): command is AgentLaunchCommand;
@@ -29,5 +36,5 @@ export declare function buildAgentRuntimeCommandOptions(input: {
     readonly env?: NodeJS.ProcessEnv;
     readonly secretsConfig: SecretsConfig | null;
 }): RuntimeCommandOptions;
-export declare function runAgentLaunchCommand(command: AgentLaunchCommand, args?: readonly string[], options?: AgentLaunchOptions, deps?: AgentLaunchDeps): number;
+export declare function runAgentLaunchCommand(command: AgentLaunchCommand, args?: readonly string[], options?: AgentLaunchOptions, deps?: AgentLaunchDeps): Promise<number>;
 export declare function registerAgentLaunchCommand(cli: CAC, command: AgentLaunchCommand): void;

package/dist/esm/cli/commands/agent-launch.js

@@ -7,6 +7,12 @@ import { WP_AGENT_LAUNCHED_VIA_WP_ENV, WP_AGENT_LAUNCHED_VIA_WP_VALUE, } from "#
 import { readSecretsConfig } from "#runtime/secrets-config.js";
 import { resolveFreshAgentKitPackageRoot } from "#cli/commands/init/package-root";
 import { ensureCodexUserPlugin } from "#cli/commands/init/scaffolders/codex-plugin/index.js";
+import { resolveOpencodeAccountsGracefully } from "#runtime/opencode-account-materializer.js";
+import { loadOpencodeAccountAvailability, pruneExpiredOpencodeAccountSuppressions, } from "#review/availability.js";
+import { selectActiveOpencodeAccount } from "#review/opencode-account.js";
+import { materializeOpencodeGoAuth } from "#review/opencode-auth.js";
+import { describeOpencodeRotate, OPENCODE_ROTATE_FLAG, rotateActiveOpencodeAccount, } from "#cli/commands/opencode-rotate.js";
+import { OPENCODE_SKIP_PROBE_ENV, resolveHealthyOpencodeAccount, } from "#cli/commands/opencode-probe.js";
 export const AGENT_LAUNCH_COMMANDS = DASH_PROVIDERS;
 export const DEFAULT_AGENT_SECRET_PROFILE = "preview";
 export const AGENT_SECRET_PROFILE_ENV = "WP_AGENT_SECRET_PROFILE";
@@ -83,7 +89,77 @@ function ensureCodexSkillSurface(cwd, env = process.env) {
             return `Codex plugin refresh failed (${result.kind}). Run \`wp install codex\` and retry.`;
     }
 }
-export function runAgentLaunchCommand(command, args = [], options = {}, deps = {}) {
+/**
+ * Choose the active opencode-go account, verify it against the real provider,
+ * and materialize its key into the global opencode `auth.json` before the TUI
+ * launches.
+ *
+ * A launch-time health probe (`resolveHealthyOpencodeAccount`) spawns a bounded
+ * `opencode run` against the candidate's isolated credential store; a detected
+ * usage limit cools that account with the provider's real reset window and the
+ * next account is probed instead. So a plain relaunch now *does* rotate past an
+ * exhausted account, and `wp opencode --wp-rotate` is only needed to force a
+ * swap off an account that is still answering.
+ *
+ * Honest limitation: interactive opencode is a long-lived TUI — the account is
+ * chosen once at launch, so a cap hit *mid-session* is still NOT auto-swapped.
+ * Only the review gate does in-flight failover, because only it observes every
+ * provider response for the life of the run.
+ *
+ * Never throws: a Doppler outage, a failed probe, or a materialize failure must
+ * not block the TUI from launching, so every failure is logged and swallowed.
+ */
+async function selectAndMaterializeOpencodeAccount(cwd, deps, secretProfile, env) {
+    try {
+        const resolution = (deps.resolveOpencodeAccounts ?? resolveOpencodeAccountsGracefully)({
+            cwd,
+            secretProfile,
+        });
+        if (!resolution.ok)
+            return;
+        const pruned = pruneExpiredOpencodeAccountSuppressions(loadOpencodeAccountAvailability());
+        const initial = selectActiveOpencodeAccount(resolution.accounts, pruned.state);
+        if (!initial)
+            return;
+        const probed = await (deps.resolveHealthyOpencodeAccount ?? resolveHealthyOpencodeAccount)(resolution.accounts, initial, { env });
+        for (const line of probed.lines)
+            console.error(line);
+        const selection = probed.selection;
+        (deps.materializeGlobalOpencodeAuth ?? ((key) => materializeOpencodeGoAuth(key)))(selection.account.key);
+        if (selection.cooled && probed.lines.length === 0) {
+            console.error(`wp opencode: all OpenCode Go accounts are within their usage cooldown; launching on the soonest-expiring account (${selection.account.id}).`);
+        }
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        console.error(`wp opencode: account selection failed, launching without it (${message}).`);
+    }
+}
+/**
+ * Run the opencode-only pre-launch credential step and return the args to
+ * forward to the binary. `--wp-rotate` is consumed here and must never reach
+ * opencode, which would treat it as a prompt.
+ */
+async function prepareOpencodeLaunch(cwd, args, secretsConfig, deps, secretProfile, env) {
+    if (!args.includes(OPENCODE_ROTATE_FLAG)) {
+        if (secretsConfig !== null) {
+            await selectAndMaterializeOpencodeAccount(cwd, deps, secretProfile, env);
+        }
+        return args;
+    }
+    const outcome = await rotateActiveOpencodeAccount(cwd, secretProfile, deps);
+    for (const line of describeOpencodeRotate(outcome))
+        console.error(line);
+    // A successful rotation already materialized the next account, so the normal
+    // launch-time selection is skipped to avoid a second, redundant write. When
+    // rotation could not run, fall through to that selection so the launch still
+    // gets the best account it can rather than whatever the store happens to hold.
+    if (outcome.kind === "unavailable" && secretsConfig !== null) {
+        await selectAndMaterializeOpencodeAccount(cwd, deps, secretProfile, env);
+    }
+    return args.filter((arg) => arg !== OPENCODE_ROTATE_FLAG);
+}
+export async function runAgentLaunchCommand(command, args = [], options = {}, deps = {}) {
     const cwd = options.cwd ?? process.cwd();
     if (command === "codex") {
         const skillSurfaceError = (deps.ensureCodexSkillSurface ?? ensureCodexSkillSurface)(cwd, options.env ?? process.env);
@@ -93,9 +169,19 @@ export function runAgentLaunchCommand(command, args = [], options = {}, deps = {
         }
     }
     const secretsConfig = (deps.readSecretsConfig ?? readSecretsConfig)(cwd);
+    // Account discovery must resolve secrets through the same profile the launch
+    // itself uses (below, via buildAgentRuntimeCommandOptions). Without it no
+    // environment selector reaches the secret manager, which then falls back to
+    // its own ambient, path-scoped config — that resolves only in a checkout that
+    // happens to sit under the scoped directory and fails in every managed
+    // worktree, CI clone, and fresh checkout.
+    const secretProfile = resolveAgentSecretProfile(options.env ?? process.env);
+    const launchArgs = command === "opencode"
+        ? await prepareOpencodeLaunch(cwd, args, secretsConfig, deps, secretProfile, options.env ?? process.env)
+        : args;
     const runtimeOptions = buildAgentRuntimeCommandOptions({
         command,
-        args,
+        args: launchArgs,
         cwd,
         env: options.env ?? process.env,
         secretsConfig,
@@ -108,8 +194,11 @@ export function runAgentLaunchCommand(command, args = [], options = {}, deps = {
     return result.status ?? 1;
 }
 export function registerAgentLaunchCommand(cli, command) {
+    const rotateHint = command === "opencode"
+        ? ` (the selected OpenCode Go account is health-probed first and a capped one is rotated past automatically; pass \`${OPENCODE_ROTATE_FLAG}\` to force a rotation, or set \`${OPENCODE_SKIP_PROBE_ENV}=1\` to skip the probe)`
+        : "";
     cli
-        .command(`${command} [...args]`, `Launch ${command} with provider-backed agent secrets and safe-by-default permissions (run \`wp yolo on\` for persistent full-auto)`)
+        .command(`${command} [...args]`, `Launch ${command} with provider-backed agent secrets and safe-by-default permissions (run \`wp yolo on\` for persistent full-auto)${rotateHint}`)
         .allowUnknownOptions()
-        .action((args = []) => runAgentLaunchCommand(command, args, { cwd: process.cwd() }));
+        .action(async (args = []) => await runAgentLaunchCommand(command, args, { cwd: process.cwd() }));
 }

package/dist/esm/cli/commands/audit-core.d.ts

@@ -1,4 +1,4 @@
-import type { AuditKindId } from "#audit/registry";
+import { type AuditKindId } from "#audit/registry";
 import type { RepoAuditResult } from "#audit/repo-guardrails";
 export type AuditKind = AuditKindId;
 export type AuditOutcome = {

package/dist/esm/cli/commands/audit-core.js

@@ -1,3 +1,4 @@
+import { getAuditKindDescriptor } from "#audit/registry";
 function optionsForCompositeRepoAudit(name, options) {
     if (name !== "reference-parity-matrix" || options.strict !== true)
         return options;
@@ -94,7 +95,13 @@ export async function runAuditDispatch(auditKind, targets, options, deps) {
             let allOk = true;
             for (const name of deps.knownRepoKinds) {
                 const result = await deps.runRepoAudit(name, root, optionsForCompositeRepoAudit(name, options));
-                if (!result.ok)
+                // Signal-class kinds (registry.ts gateClass) still run and still
+                // report their findings via `results` below, but a failing signal
+                // kind must not flip the umbrella — only blocking-class failures do.
+                // Unclassified kinds default to blocking, matching the registry's
+                // own descriptor() default.
+                const gateClass = getAuditKindDescriptor(name)?.gateClass ?? "blocking";
+                if (!result.ok && gateClass !== "signal")
                     allOk = false;
                 results.push({ name, result });
             }

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

@@ -15,6 +15,7 @@ import { createCliLogSink } from "#cli/commands/quality-log-store.js";
 import { emitCliCommandOutput, runLoggedChildCommand } from "#cli/commands/quality-runner.js";
 export const REPO_AUDIT_REGISTRY = {
     "catalog-drift": async (root) => (await import("#audit/repo-guardrails")).auditCatalogDrift(root),
+    "typescript-version": async (root) => (await import("#audit/typescript-version")).auditTypescriptVersion(root),
     "package-surface": async (root) => (await import("#audit/package-surface")).auditPackageSurface(root),
     "command-surface": async (root) => (await import("#audit/command-surface")).auditCommandSurface(root),
     "reference-parity-matrix": async (root, options) => (await import("#audit/reference-parity-matrix")).auditReferenceParityMatrix(root, undefined, {
@@ -123,6 +124,7 @@ export const REPO_AUDIT_REGISTRY = {
     "secrets-config": async (root) => (await import("#audit/secrets-config")).auditSecretsConfig(root),
     "consumer-agent-kit-dependency": async (root) => (await import("#audit/consumer-agent-kit-dependency")).auditConsumerAgentKitDependency(root),
     "ci-test-perf": async (root) => (await import("#audit/ci-test-perf")).auditCiTestPerf(root),
+    "ci-guardrails-wiring": async (root) => (await import("#audit/ci-guardrails-wiring")).auditCiGuardrailsWiring(root),
     "test-scan-perf": async (root, options) => (await import("#audit/test-scan-perf")).auditTestScanPerf(root, {
         affectedFiles: options.affectedFiles,
     }),
@@ -140,9 +142,14 @@ export const REPO_AUDIT_REGISTRY = {
         draftTechDebt: options.draftTechDebt,
     }),
     "harness-overlay-evidence": async (root) => (await import("#audit/harness-overlay-evidence")).auditHarnessOverlayEvidence(root),
+    "host-substitution-risk": async (root) => (await import("#audit/host-substitution-risk")).auditHostSubstitutionRisk(root),
     "legacy-workflow-identity": async (root) => (await import("#audit/legacy-workflow-identity")).auditLegacyWorkflowIdentity(root),
     rules: async (root) => runContentAudit(root, "rule"),
     skills: async (root) => runContentAudit(root, "skill"),
+    "changeset-required": async (root, options) => (await import("#audit/changeset-required")).auditChangesetRequired(root, {
+        baseRef: options.baseRef ?? options.base,
+        changedFiles: options.affectedFiles,
+    }),
 };
 async function runContentAudit(root, kind) {
     const { auditContent } = await import("../../content/audit.js");
@@ -467,22 +474,31 @@ export function registerAuditCommand(cli) {
             }
             case "aggregate-result": {
                 const { formatRepoAuditReport } = await import("#audit/repo-guardrails");
+                const isSignal = (name) => getAuditKindDescriptor(name)?.gateClass === "signal";
                 for (const { name, result } of outcome.results) {
                     if (result.ok)
                         continue;
-                    sink.write(`\n[${name}]\n${formatRepoAuditReport(result)}\n`);
+                    const label = isSignal(name) ? `${name} (signal, non-blocking)` : name;
+                    sink.write(`\n[${label}]\n${formatRepoAuditReport(result)}\n`);
                 }
                 const failed = outcome.results.filter(({ result }) => !result.ok);
+                const blockingFailed = failed.filter(({ name }) => !isSignal(name));
+                const signalFailed = failed.filter(({ name }) => isSignal(name));
                 if (failed.length > 0) {
-                    sink.write(`\nguardrails: ${failed.length}/${outcome.results.length} audits failed: ${failed
-                        .map(({ name }) => name)
-                        .join(", ")}\n`);
+                    const parts = [];
+                    if (blockingFailed.length > 0) {
+                        parts.push(`${blockingFailed.length} blocking: ${blockingFailed.map(({ name }) => name).join(", ")}`);
+                    }
+                    if (signalFailed.length > 0) {
+                        parts.push(`${signalFailed.length} signal/non-blocking: ${signalFailed.map(({ name }) => name).join(", ")}`);
+                    }
+                    sink.write(`\nguardrails: ${failed.length}/${outcome.results.length} audits reported findings (${parts.join("; ")})\n`);
                 }
                 exitCode = outcome.code;
                 summary =
                     outcome.code === 0
                         ? "audit guardrails passed"
-                        : `audit guardrails failed (${failed.length}/${outcome.results.length})`;
+                        : `audit guardrails failed (${blockingFailed.length}/${outcome.results.length})`;
                 break;
             }
             case "quality-exit": {

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

@@ -9,6 +9,7 @@ import { setTimeout as delay } from "node:timers/promises";
 import { applyRuntimeProgressSnapshot, buildBlueprintProgressBridgeState, normalizeRuntimeTaskSnapshot, projectBlueprintLifecycleFromRuntime, readBlueprintExecutionArtifacts, runtimeStateSnapshotSchema, writeBlueprintExecutionArtifacts, writeBlueprintExecutionMetadata, } from "#index";
 import { applyBlueprintLifecycleToFile, parseBlueprint } from "#local";
 import { resolveBlueprintRoot } from "#utils/blueprint-root";
+import { resolveBlueprintDocumentIdentity } from "#utils/document-paths.js";
 import { clearBlueprintExecutionState, persistBlueprintExecutionArtifacts, persistBlueprintExecutionMetadata, persistBlueprintProgressBridgeState, readBlueprintExecutionArtifactsState, readBlueprintExecutionState, readBlueprintProgressBridgeState, readBlueprintRuntimeSnapshot, writeBlueprintRuntimeSnapshot, } from "./execution-io.js";
 import { assertCompletionEvidence, mergeExecutionArtifacts, } from "./execution-state.js";
 import { buildBlueprintExecutionControlCommand, buildBlueprintExecutionLaunchCommand, buildBlueprintExecutionRuntimePaths, buildBlueprintLaunchSpec, buildListTasksVerificationCommand, isMissingFileError, nowIsoTimestamp, parseRuntimeApiResponse, parseTeamExecutionId, resolveControlStatus, toProjectRelativePath, uniqueStrings, } from "./execution-spec.js";
@@ -114,22 +115,33 @@ export async function reconcileBlueprintRuntimeSnapshot(projectRoot, blueprintPa
     const currentStatus = currentDir.split(blueprintsRoot + path.sep)[1]?.split(path.sep)[0];
     const relativeSlug = slug.replace(/^[^/]+\//u, "");
     const targetDir = path.join(blueprintsRoot, nextStatus, relativeSlug);
-    const targetPath = path.join(targetDir, "_overview.md");
+    // A flat document owns only its own file; renaming its parent directory
+    // would move the entire lifecycle state directory. Lifecycle moves are
+    // shape-preserving: flat stays flat, folder moves as a folder.
+    const isFlatDocument = resolveBlueprintDocumentIdentity(blueprintsRoot, blueprintPath)?.shape === "flat";
+    const targetPath = isFlatDocument ? `${targetDir}.md` : path.join(targetDir, "_overview.md");
+    const documentMoved = blueprintPath !== targetPath;
     const nextMarkdown = completionEvidence
         ? writeBlueprintExecutionArtifacts(result.markdown, completionEvidence)
         : result.markdown;
-    if (currentDir !== targetDir && currentStatus && currentStatus !== nextStatus) {
+    if (documentMoved && currentStatus && currentStatus !== nextStatus) {
         const { mkdir, rename } = await import("node:fs/promises");
-        await mkdir(path.dirname(targetDir), { recursive: true });
-        await rename(currentDir, targetDir);
+        if (isFlatDocument) {
+            await mkdir(path.dirname(targetPath), { recursive: true });
+            await rename(blueprintPath, targetPath);
+        }
+        else {
+            await mkdir(path.dirname(targetDir), { recursive: true });
+            await rename(currentDir, targetDir);
+        }
         await writeFile(targetPath, nextMarkdown, "utf-8");
     }
     else {
         await writeFile(blueprintPath, nextMarkdown, "utf-8");
     }
     return {
-        moved: currentDir !== targetDir,
-        path: currentDir !== targetDir ? targetPath : blueprintPath,
+        moved: documentMoved,
+        path: documentMoved ? targetPath : blueprintPath,
         status: result.execution.status,
     };
 }

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
@@ -321,24 +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.
-    // Markdown `_overview.md` is SSOT for task status + verification evidence.
-    // The projection DB is derived and can lag when agents edit task Status
-    // blocks without going through `task complete` (hash-skipping reingest then
-    // leaves stale todo rows). Do not fail completion on projection lag —
-    // reingest after the markdown gate so consumers see fresh rows.
-    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`);
@@ -349,30 +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));
-        // 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);
-    }
-    // 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,
-    });
+        // 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);
+        }
+        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.
@@ -402,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>;