@webpresso/agent-kit 3.1.30 → 3.2.0

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

@@ -2,6 +2,7 @@ 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";
 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 +19,10 @@ 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>;
 }
 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 +34,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,11 @@ 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";
 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 +88,67 @@ 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 and materialize its key into the
+ * global opencode `auth.json` before the TUI launches.
+ *
+ * Honest limitation: interactive opencode is a long-lived TUI — the account is
+ * chosen once at launch and a mid-session dollar-cap is NOT auto-swapped. A
+ * plain relaunch does NOT rotate either: nothing on this path records a
+ * cooldown, so an exhausted account stays "first non-suppressed" and gets
+ * re-picked every time. Run `wp opencode --wp-rotate` to cool the current
+ * account and launch on the next one. Only the review gate does automatic
+ * in-flight failover, because only it can observe the usage-limit response.
+ *
+ * Never throws: a Doppler outage or materialize failure must not block the
+ * TUI from launching, so every failure is logged and swallowed.
+ */
+function selectAndMaterializeOpencodeAccount(cwd, deps, secretProfile) {
+    try {
+        const resolution = (deps.resolveOpencodeAccounts ?? resolveOpencodeAccountsGracefully)({
+            cwd,
+            secretProfile,
+        });
+        if (!resolution.ok)
+            return;
+        const pruned = pruneExpiredOpencodeAccountSuppressions(loadOpencodeAccountAvailability());
+        const selection = selectActiveOpencodeAccount(resolution.accounts, pruned.state);
+        if (!selection)
+            return;
+        (deps.materializeGlobalOpencodeAuth ?? ((key) => materializeOpencodeGoAuth(key)))(selection.account.key);
+        if (selection.cooled) {
+            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) {
+    if (!args.includes(OPENCODE_ROTATE_FLAG)) {
+        if (secretsConfig !== null)
+            selectAndMaterializeOpencodeAccount(cwd, deps, secretProfile);
+        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) {
+        selectAndMaterializeOpencodeAccount(cwd, deps, secretProfile);
+    }
+    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 +158,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)
+        : args;
     const runtimeOptions = buildAgentRuntimeCommandOptions({
         command,
-        args,
+        args: launchArgs,
         cwd,
         env: options.env ?? process.env,
         secretsConfig,
@@ -108,8 +183,11 @@ export function runAgentLaunchCommand(command, args = [], options = {}, deps = {
     return result.status ?? 1;
 }
 export function registerAgentLaunchCommand(cli, command) {
+    const rotateHint = command === "opencode"
+        ? ` (pass \`${OPENCODE_ROTATE_FLAG}\` to cool the current OpenCode Go account and launch on the next one)`
+        : "";
     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,6 +142,7 @@ 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"),
@@ -467,22 +470,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>;

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;