@webpresso/agent-kit 3.1.30 → 3.2.0

package/dist/esm/blueprint/lifecycle/canonicalize.d.ts

@@ -0,0 +1,6 @@
+export interface CanonicalizeBlueprintResult {
+    readonly from: string;
+    readonly to: string;
+    readonly moved: boolean;
+}
+export declare function canonicalizeBlueprint(projectRoot: string, slug: string): Promise<CanonicalizeBlueprintResult>;

package/dist/esm/blueprint/lifecycle/canonicalize.js

@@ -0,0 +1,135 @@
+import { constants } from "node:fs";
+import { access, lstat, mkdir, readdir, rename, rmdir } from "node:fs/promises";
+import { refreshBlueprintReadmeIndex } from "#audit/blueprint-readme-drift";
+import { resolveBlueprintFile } from "#lifecycle/local.js";
+import { BLUEPRINT_STATUSES, getBlueprintDocumentPaths, isBlueprintSlugSegment, isBlueprintStatus, } from "#utils/document-paths.js";
+import { resolveBlueprintRoot } from "#utils/blueprint-root.js";
+async function exists(filePath) {
+    try {
+        await access(filePath, constants.F_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function assertRegularFile(filePath) {
+    const stats = await lstat(filePath);
+    if (!stats.isFile() || stats.isSymbolicLink()) {
+        throw new Error(`Blueprint canonicalization requires a regular file: ${filePath}`);
+    }
+}
+async function directCanonicalizeLocation(projectRoot, slug) {
+    const root = resolveBlueprintRoot(projectRoot);
+    const segments = slug.split("/").filter((segment) => segment.length > 0);
+    const scopedState = isBlueprintStatus(segments[0]) ? segments[0] : null;
+    const slugSegments = scopedState === null ? segments : segments.slice(1);
+    const stableSlug = slugSegments.join("/");
+    // Validate before any filesystem probe: an unvalidated slug such as
+    // "../outside" would otherwise resolve paths outside the blueprint root.
+    if (!stableSlug || !slugSegments.every((segment) => isBlueprintSlugSegment(segment))) {
+        return null;
+    }
+    const states = scopedState === null ? BLUEPRINT_STATUSES : [scopedState];
+    for (const state of states) {
+        const paths = getBlueprintDocumentPaths(root, state, stableSlug);
+        const [flatExists, folderExists] = await Promise.all([
+            exists(paths.flat),
+            exists(paths.folder),
+        ]);
+        if (flatExists && folderExists) {
+            await assertRegularFile(paths.flat);
+            await assertRegularFile(paths.folder);
+            throw new Error(`Blueprint canonicalization refused to overwrite existing overview: ${paths.folder}`);
+        }
+        if (flatExists) {
+            return {
+                folderDirectory: paths.directory,
+                folderPath: paths.folder,
+                path: paths.flat,
+                shape: "flat",
+            };
+        }
+        if (folderExists) {
+            return {
+                folderDirectory: paths.directory,
+                folderPath: paths.folder,
+                path: paths.folder,
+                shape: "folder",
+            };
+        }
+    }
+    return null;
+}
+const GOVERNANCE_ENTRY_NAMES = new Set(["review-events.jsonl", "reviews.md", "review-artifacts"]);
+async function assertUsableTargetDirectory(directory) {
+    try {
+        const stats = await lstat(directory);
+        if (stats.isSymbolicLink() || !stats.isDirectory()) {
+            throw new Error(`Blueprint canonicalization target is not a real directory: ${directory}`);
+        }
+    }
+    catch (error) {
+        const code = error.code;
+        if (code !== "ENOENT")
+            throw error;
+        await mkdir(directory, { recursive: true });
+        return "created";
+    }
+    // Adopting a directory that already holds governance files would turn
+    // previously unattributed evidence into authoritative folder evidence the
+    // moment the overview lands next to it. Refuse; the operator must review
+    // and remove (or intentionally commit) that evidence first. Compare
+    // case-folded: on case-insensitive filesystems "Reviews.md" aliases the
+    // authoritative lowercase path.
+    const adopted = (await readdir(directory)).filter((entry) => GOVERNANCE_ENTRY_NAMES.has(entry.toLowerCase()));
+    if (adopted.length > 0) {
+        throw new Error(`Blueprint canonicalization refused to adopt a directory containing review evidence: ${directory} (${adopted.join(", ")})`);
+    }
+    return "existing";
+}
+async function removeCreatedDirectoryIfEmpty(directory, created) {
+    if (!created)
+        return;
+    try {
+        const entries = await readdir(directory);
+        if (entries.length === 0)
+            await rmdir(directory);
+    }
+    catch {
+        // Best-effort cleanup only. A concurrent caller may have completed the move.
+    }
+}
+export async function canonicalizeBlueprint(projectRoot, slug) {
+    const location = (await directCanonicalizeLocation(projectRoot, slug)) ??
+        (await resolveBlueprintFile(projectRoot, slug));
+    const from = location.path;
+    const to = location.folderPath;
+    if (location.shape === "folder") {
+        await assertRegularFile(to);
+        return { from, to, moved: false };
+    }
+    await assertRegularFile(from);
+    const directoryState = await assertUsableTargetDirectory(location.folderDirectory);
+    const createdDirectory = directoryState === "created";
+    try {
+        if (await exists(to)) {
+            await assertRegularFile(to);
+            if (await exists(from)) {
+                throw new Error(`Blueprint canonicalization refused to overwrite existing overview: ${to}`);
+            }
+            return { from, to, moved: false };
+        }
+        await rename(from, to);
+    }
+    catch (error) {
+        if (error.code === "ENOENT" && (await exists(to))) {
+            await assertRegularFile(to);
+            return { from, to, moved: false };
+        }
+        await removeCreatedDirectoryIfEmpty(location.folderDirectory, createdDirectory);
+        throw error;
+    }
+    refreshBlueprintReadmeIndex(projectRoot);
+    return { from, to, moved: true };
+}

package/dist/esm/blueprint/lifecycle/local.d.ts

@@ -1,5 +1,6 @@
 import type { BlueprintLifecycleIntent, BlueprintLifecycleResult } from "./engine.js";
-export interface ResolvedBlueprintFile {
+import { type BlueprintDocumentIdentity } from "#utils/document-paths.js";
+export interface ResolvedBlueprintFile extends BlueprintDocumentIdentity {
     path: string;
     slug: string;
 }

package/dist/esm/blueprint/lifecycle/local.js

@@ -1,10 +1,11 @@
 import { mkdir, readFile, readdir, rename, rmdir, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { refreshBlueprintReadmeIndex } from "#audit/blueprint-readme-drift";
+import { assertCompletedApprovalGate } from "#lifecycle/audit";
 import { applyBlueprintLifecycle } from "#lifecycle/engine";
 import { scanBlueprintDirectory } from "#service/scanner";
 import { resolveBlueprintRoot } from "#utils/blueprint-root";
-import { getBlueprintDocumentPaths } from "#utils/document-paths.js";
+import { getBlueprintDocumentPaths, resolveBlueprintDocumentIdentity, } from "#utils/document-paths.js";
 const BLUEPRINT_SLUG_SEGMENT_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
 function isStatusSegment(segment) {
     return (segment === "draft" ||
@@ -57,7 +58,15 @@ export async function resolveBlueprintFile(projectRoot, slug) {
             .map((entry) => entry.slug)
             .join(", ")}`);
     }
-    return { path: match.path, slug: match.slug };
+    const identity = resolveBlueprintDocumentIdentity(baseDir, match.path);
+    if (!identity) {
+        throw new Error(`Blueprint ${match.slug} resolved to an invalid document path: ${match.path}`);
+    }
+    return {
+        ...identity,
+        path: identity.documentPath,
+        slug: match.slug,
+    };
 }
 async function tryRemoveEmptyParent(dir) {
     try {
@@ -75,8 +84,15 @@ export async function applyBlueprintLifecycleToFile(projectRoot, slug, intent) {
     const location = await resolveBlueprintFile(projectRoot, slug);
     const raw = await readFile(location.path, "utf-8");
     const mutation = applyBlueprintLifecycle(raw, location.slug, intent);
+    // Completion parity: the execution engine's `finalize` intent (exec/resume/
+    // stop/move flows) also writes `status: completed`. Gate it with the same
+    // plan-approval check CI enforces so this path cannot diverge from the audit
+    // either — matching the MCP funnel and CLI completion owners.
+    if (mutation.targetStatus === "completed") {
+        assertCompletedApprovalGate(location.path, raw);
+    }
     const relativeSlug = relativeBlueprintSlug(location.slug);
-    const isFlatFile = path.basename(location.path) !== "_overview.md";
+    const isFlatFile = location.shape === "flat";
     const sourceDir = path.dirname(location.path);
     const targetDocumentPaths = getBlueprintDocumentPaths(baseDir, mutation.targetStatus, relativeSlug);
     const targetDir = targetDocumentPaths.directory;

package/dist/esm/blueprint/lifecycle/review-provenance.js

@@ -3,7 +3,7 @@ import { existsSync, readFileSync } from "node:fs";
 import path from "node:path";
 import { readReviewAuthorityAtRef, readWorkingReviewEvents } from "#review/authority.js";
 import { evaluateReviewEvents, parseReviewEventLog } from "#review/events.js";
-import { createPlanSubjectDigestForContent, normalizePlanSubjectContent } from "#review/subject.js";
+import { createDeliverySubjectAtRef, createPlanSubjectDigestForContent, normalizePlanSubjectContent, } from "#review/subject.js";
 import { isPolicyApprovalVerdict } from "#review/verdict.js";
 const REVIEW_ENTRY_MARKER = "<!-- wp:review-entry ";
 function normalizePath(file) {
@@ -50,6 +50,10 @@ function stableSlugForBlueprintFile(file) {
     if (lifecycleIndex >= 0 && segments.at(-1) === "_overview.md") {
         return segments.slice(lifecycleIndex + 1, -1).join("/");
     }
+    const basename = segments.at(-1) ?? "";
+    if (lifecycleIndex >= 0 && basename.endsWith(".md")) {
+        return basename.slice(0, -3);
+    }
     return path.basename(path.dirname(file));
 }
 /**
@@ -83,7 +87,7 @@ export function readBlueprintOverviewAtRef(repoRoot, ref, file) {
                 timeout: 5_000,
             });
             const escaped = slug.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&");
-            const pattern = new RegExp(`(?:^|/)(?:draft|planned|parked|in-progress|completed|archived)/${escaped}/_overview\\.md$`, "u");
+            const pattern = new RegExp(`(?:^|/)(?:draft|planned|parked|in-progress|completed|archived)/${escaped}(?:/_overview\\.md|\\.md)$`, "u");
             const hits = names.split("\n").filter((name) => pattern.test(normalizePath(name)));
             if (hits.length !== 1)
                 return null;
@@ -135,21 +139,42 @@ function workingContentMatchesRef(repoRoot, file, purpose, ref) {
 // event still counts only when its subjectDigest matches the digest of the
 // exact working bytes being committed and its artifact hash-verifies on disk —
 // content-addressing keeps this sound before the commit exists.
-function collectWorkingV2ReviewProvenance(file, issues) {
+function collectWorkingV2ReviewProvenance(file, purpose, issues) {
     try {
+        const repoRoot = findGitRoot(file);
+        if (!repoRoot)
+            return [];
         const slug = stableSlugForBlueprintFile(file);
         const working = readWorkingReviewEvents(file, slug);
         if (working.events.length === 0)
             return [];
         issues?.push(...working.issues);
-        const digest = createPlanSubjectDigestForContent(slug, readFileSync(file));
-        const evaluation = evaluateReviewEvents(working.events, {
-            purpose: "plan",
+        const subjects = purpose === "plan"
+            ? [
+                {
+                    scheme: "wp-blueprint-v1",
+                    digest: createPlanSubjectDigestForContent(slug, readFileSync(file)),
+                },
+            ]
+            : [
+                ...new Map(working.events
+                    .filter((event) => event.purpose === "delivery")
+                    .flatMap((event) => {
+                    const subject = createDeliverySubjectAtRef(repoRoot, event.reviewedCommit, slug, normalizePath(path.relative(repoRoot, file)));
+                    if (subject.digest !== event.subjectDigest) {
+                        issues?.push(`Working delivery review subject mismatch for ${event.id}: expected ${subject.digest}, found ${event.subjectDigest}.`);
+                        return [];
+                    }
+                    return [[subject.digest, subject]];
+                })).values(),
+            ];
+        return subjects
+            .flatMap((subject) => evaluateReviewEvents(working.events, {
+            purpose,
             blueprintSlug: slug,
-            subjectScheme: "wp-blueprint-v1",
-            subjectDigest: digest,
-        }, working.compromisedIds);
-        return evaluation.approvals
+            subjectScheme: subject.scheme,
+            subjectDigest: subject.digest,
+        }, working.compromisedIds).approvals)
             .filter((event) => event.artifactPath)
             .map((event) => ({
             reviewer: event.reviewer,
@@ -166,7 +191,7 @@ export function collectV2ReviewProvenance(file, purpose, ref = "HEAD", issues) {
     const repoRoot = findGitRoot(file);
     if (!repoRoot)
         return [];
-    const workingApprovals = purpose === "plan" ? collectWorkingV2ReviewProvenance(file, issues) : [];
+    const workingApprovals = collectWorkingV2ReviewProvenance(file, purpose, issues);
     if (!workingContentMatchesRef(repoRoot, file, purpose, ref))
         return workingApprovals;
     try {

package/dist/esm/blueprint/service/BlueprintCreationService.d.ts

@@ -48,6 +48,7 @@ export declare class BlueprintCreationService {
     resolveDraftSlug(input: CreateBlueprintDraftInput): string;
     compileDraft(input: CreateBlueprintDraftInput): Promise<CompiledBlueprintDraft>;
     create(input: CreateBlueprintDraftInput): Promise<CreatedBlueprintDraft>;
+    private reserveDraftSlugFolder;
     private resolveCollisionSafeSlug;
 }
 export {};

package/dist/esm/blueprint/service/BlueprintCreationService.js

@@ -42,12 +42,38 @@ function sentenceCase(value) {
     }
     return value.slice(0, 1).toUpperCase() + value.slice(1);
 }
+// A slug becomes a branch name, worktree directory, and repeated CLI argument,
+// so an unbounded goal string must not produce an unbounded slug. Cap it at a
+// word AND a character ceiling (whichever binds first), truncating on a word
+// boundary. The full goal survives as the human-readable title; only the slug
+// is bounded. Collision suffixing runs AFTER this cap, so `-2` is never counted
+// against the ceiling.
+const MAX_SLUG_WORDS = 6;
+const MAX_SLUG_CHARS = 50;
+// Bound on atomic slug-folder reservation retries under concurrent creation.
+const MAX_SLUG_RESERVATION_ATTEMPTS = 50;
+function capSlug(slug) {
+    const [firstWord, ...rest] = slug.split("-").filter(Boolean).slice(0, MAX_SLUG_WORDS);
+    if (firstWord === undefined)
+        return slug;
+    let capped = firstWord;
+    for (const word of rest) {
+        const candidate = `${capped}-${word}`;
+        if (candidate.length > MAX_SLUG_CHARS)
+            break;
+        capped = candidate;
+    }
+    // A single first word longer than the ceiling is hard-trimmed; drop any
+    // trailing hyphen the trim could expose.
+    return capped.slice(0, MAX_SLUG_CHARS).replace(/-+$/u, "");
+}
 function deriveSlug(goal) {
-    return goal
+    const slug = goal
         .toLowerCase()
         .replace(/[^a-z0-9]+/g, "-")
         .replace(/^-+|-+$/g, "")
         .replace(/-{2,}/g, "-");
+    return capSlug(slug);
 }
 function assertGoalProducesUsableSlug(goal, slug) {
     if (slug.length === 0) {
@@ -223,11 +249,16 @@ export class BlueprintCreationService {
     async create(input) {
         // H-009: refuse primary-like roots so drafts never leak onto main checkouts.
         assertDraftAuthoringAllowed(this.projectRoot);
-        const draft = await this.compileDraft(input);
         const draftRoot = path.join(this.blueprintsRoot, "draft");
-        const finalPath = draft.outputPath;
         await mkdir(draftRoot, { recursive: true });
-        await mkdir(path.dirname(finalPath), { recursive: true });
+        // Atomically RESERVE the slug folder. Two concurrent creations (CLI *and*
+        // MCP) can each resolve the same collision-safe slug before either writes;
+        // a plain recursive mkdir + rename would then let the later writer silently
+        // overwrite the earlier draft. `mkdir(..., { recursive: false })` is atomic:
+        // exactly one racer creates the folder, the loser gets EEXIST and re-resolves
+        // to the next `-N` suffix (compileDraft re-scans and sees the reservation).
+        const draft = await this.reserveDraftSlugFolder(input);
+        const finalPath = draft.outputPath;
         const tempDir = await mkdtemp(path.join(draftRoot, `${draft.slug}.tmp-`));
         const tempPath = path.join(tempDir, `${draft.slug}.md`);
         try {
@@ -252,6 +283,24 @@ export class BlueprintCreationService {
             throw error;
         }
     }
+    // Compile a draft and atomically claim its slug folder, retrying with the next
+    // collision-safe slug when a concurrent creator wins the folder first.
+    async reserveDraftSlugFolder(input) {
+        for (let attempt = 0; attempt < MAX_SLUG_RESERVATION_ATTEMPTS; attempt += 1) {
+            const candidate = await this.compileDraft(input);
+            try {
+                await mkdir(path.dirname(candidate.outputPath), { recursive: false });
+                return candidate;
+            }
+            catch (error) {
+                // Folder already reserved by a concurrent creator — re-resolve the slug.
+                if (error instanceof Error && error.code === "EEXIST")
+                    continue;
+                throw error;
+            }
+        }
+        throw new Error(`Could not reserve a unique blueprint slug after ${MAX_SLUG_RESERVATION_ATTEMPTS} attempts.`);
+    }
     resolveCollisionSafeSlug(baseSlug) {
         const blueprintsRoot = this.blueprintsRoot;
         const existing = new Set(scanBlueprintDirectory({

package/dist/esm/blueprint/service/blueprint-tech-debt-links.js

@@ -1,15 +1,29 @@
 import matter from "gray-matter";
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
+import { getBlueprintDocumentCandidates } from "#utils/document-paths.js";
 import { resolveTechDebtRoot } from "#utils/tech-debt-root";
+async function resolveBlueprintDocumentPath(baseDir, bpSlug) {
+    const candidates = getBlueprintDocumentCandidates(baseDir, bpSlug);
+    for (const candidate of candidates) {
+        try {
+            await fs.access(candidate);
+            return candidate;
+        }
+        catch {
+            // Keep trying the other canonical shape.
+        }
+    }
+    return candidates.at(-1) ?? path.join(baseDir, bpSlug, "_overview.md");
+}
 export async function linkBlueprintToTechDebt(baseDir, projectPath, bpSlug, tdSlug) {
-    const blueprintPath = path.join(baseDir, bpSlug, "_overview.md");
+    const blueprintPath = await resolveBlueprintDocumentPath(baseDir, bpSlug);
     await updateLinkedSlugs(blueprintPath, "linked_tech_debt_slugs", (linked) => [...linked, tdSlug]);
     const tdPath = path.join(resolveTechDebtRoot(projectPath), tdSlug, "README.md");
     await updateLinkedSlugs(tdPath, "linked_blueprints", (linked) => [...linked, bpSlug]);
 }
 export async function unlinkBlueprintFromTechDebt(baseDir, projectPath, bpSlug, tdSlug) {
-    const blueprintPath = path.join(baseDir, bpSlug, "_overview.md");
+    const blueprintPath = await resolveBlueprintDocumentPath(baseDir, bpSlug);
     await updateLinkedSlugs(blueprintPath, "linked_tech_debt_slugs", (linked) => linked.filter((slug) => slug !== tdSlug));
     const tdPath = path.join(resolveTechDebtRoot(projectPath), tdSlug, "README.md");
     try {

package/dist/esm/blueprint/trust/command-runner.d.ts

@@ -0,0 +1,26 @@
+import { spawnSync } from "node:child_process";
+export declare const ALLOWED_WP_COMMAND_TIMEOUT_MS = 30000;
+export declare const ALLOWED_WP_COMMAND_STDIO_TAIL_LIMIT = 500;
+export type AllowedWpCommandOutcome = "passed" | "failed" | "timed-out";
+export interface AllowedWpCommandResult {
+    readonly command: string;
+    readonly outcome: AllowedWpCommandOutcome;
+    readonly durationMs: number;
+    readonly exitCode: number | null;
+    readonly signal?: string;
+    readonly stdout: string;
+    readonly stderr: string;
+    readonly logPath?: string;
+    readonly failureCode?: string;
+    readonly errorMessage?: string;
+}
+export interface ExecuteAllowedWpCommandInput {
+    readonly command: string;
+    readonly executionRoot: string;
+    readonly logRoot: string;
+    readonly env?: NodeJS.ProcessEnv;
+    readonly spawn?: typeof spawnSync;
+}
+export declare function executeAllowedWpCommand(input: ExecuteAllowedWpCommandInput): AllowedWpCommandResult;
+export declare function tailBounded(text: string): string;
+export declare function relativeCommandLogPath(root: string, logPath: string | undefined): string | undefined;

package/dist/esm/blueprint/trust/command-runner.js

@@ -0,0 +1,148 @@
+import { spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { join, relative } from "node:path";
+import { parseAllowedWpCommand } from "./gates.js";
+import { resolvePackageAssetPreferred } from "#utils/package-assets.js";
+export const ALLOWED_WP_COMMAND_TIMEOUT_MS = 30_000;
+export const ALLOWED_WP_COMMAND_STDIO_TAIL_LIMIT = 500;
+export function executeAllowedWpCommand(input) {
+    const started = Date.now();
+    let invocation;
+    try {
+        const argv = parseAllowedWpCommand(input.command);
+        const [binary, ...args] = argv;
+        if (binary === undefined)
+            throw new Error(`Promotion gate command is empty: ${input.command}`);
+        invocation = resolveAllowedWpInvocation(input.executionRoot, binary, args, input.env);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        const result = {
+            command: input.command,
+            outcome: "failed",
+            durationMs: Date.now() - started,
+            exitCode: null,
+            stdout: "",
+            stderr: message,
+            failureCode: "command-policy-rejected",
+            errorMessage: message,
+        };
+        return {
+            ...result,
+            logPath: writeAllowedWpCommandLog(input.logRoot, input.command, null, result),
+        };
+    }
+    const spawn = input.spawn ?? spawnSync;
+    const result = spawn(invocation.command, invocation.args, {
+        cwd: input.executionRoot,
+        encoding: "utf8",
+        stdio: ["ignore", "pipe", "pipe"],
+        timeout: ALLOWED_WP_COMMAND_TIMEOUT_MS,
+        env: invocation.env,
+    });
+    const durationMs = Date.now() - started;
+    const stdout = typeof result.stdout === "string" ? result.stdout : "";
+    const stderr = typeof result.stderr === "string" ? result.stderr : "";
+    const timedOut = result.error ? errorCode(result.error) === "ETIMEDOUT" : false;
+    const output = {
+        command: input.command,
+        outcome: result.status === 0 && !result.error && result.signal === null
+            ? "passed"
+            : timedOut
+                ? "timed-out"
+                : "failed",
+        durationMs,
+        exitCode: typeof result.status === "number" ? result.status : null,
+        ...(result.signal ? { signal: result.signal } : {}),
+        stdout,
+        stderr,
+        ...(timedOut ? { failureCode: "command-timed-out" } : {}),
+        ...(result.error ? { errorMessage: result.error.message } : {}),
+    };
+    if (output.outcome === "passed")
+        return output;
+    return {
+        ...output,
+        logPath: writeAllowedWpCommandLog(input.logRoot, input.command, invocation, output),
+    };
+}
+export function tailBounded(text) {
+    if (text.length <= ALLOWED_WP_COMMAND_STDIO_TAIL_LIMIT)
+        return text.trim();
+    return text.slice(-ALLOWED_WP_COMMAND_STDIO_TAIL_LIMIT).trim();
+}
+export function relativeCommandLogPath(root, logPath) {
+    if (!logPath)
+        return undefined;
+    const rel = relative(root, logPath).replace(/\\/gu, "/");
+    return rel === "" || rel.startsWith("../") ? logPath : rel;
+}
+function resolveAllowedWpInvocation(executionRoot, binary, args, extraEnv) {
+    const baseEnv = { ...process.env, ...extraEnv };
+    if (binary === "./bin/wp" || binary === "wp") {
+        const localLauncher = resolveRepoWpLauncher(executionRoot);
+        if (localLauncher !== null) {
+            return {
+                command: localLauncher,
+                args: [...args],
+                env: { ...baseEnv, PATH: `${executionRoot}/bin:${baseEnv["PATH"] ?? ""}` },
+            };
+        }
+        if (binary === "./bin/wp") {
+            return {
+                command: join(executionRoot, "bin", process.platform === "win32" ? "wp.cmd" : "wp"),
+                args: [...args],
+                env: { ...baseEnv, PATH: `${executionRoot}/bin:${baseEnv["PATH"] ?? ""}` },
+            };
+        }
+        const packagedLauncher = resolvePackagedWpLauncher();
+        return {
+            command: process.execPath,
+            args: [packagedLauncher, ...args],
+            env: baseEnv,
+        };
+    }
+    return {
+        command: binary,
+        args: [...args],
+        env: { ...baseEnv, PATH: `${executionRoot}/bin:${baseEnv["PATH"] ?? ""}` },
+    };
+}
+function resolveRepoWpLauncher(repoRoot) {
+    const launcher = join(repoRoot, "bin", process.platform === "win32" ? "wp.cmd" : "wp");
+    return existsSync(launcher) ? launcher : null;
+}
+function resolvePackagedWpLauncher() {
+    const launcher = resolvePackageAssetPreferred([
+        process.platform === "win32" ? "bin/wp.cmd" : "bin/wp",
+        "bin/wp",
+    ]);
+    if (!existsSync(launcher)) {
+        throw new Error(`Promotion gate failed: packaged wp launcher is unavailable at ${launcher}`);
+    }
+    return launcher;
+}
+function writeAllowedWpCommandLog(logRoot, command, invocation, result) {
+    mkdirSync(logRoot, { recursive: true });
+    const logPath = join(logRoot, `${Date.now()}-wp-command.log`);
+    writeFileSync(logPath, [
+        `command: ${command}`,
+        `invocation: ${invocation ? `${invocation.command} ${invocation.args.join(" ")}` : "not-run"}`,
+        `outcome: ${result.outcome}`,
+        `exit: ${result.exitCode ?? "null"}`,
+        `signal: ${result.signal ?? "null"}`,
+        `timeout_ms: ${ALLOWED_WP_COMMAND_TIMEOUT_MS}`,
+        `error: ${result.errorMessage ?? "none"}`,
+        "--- stderr ---",
+        result.stderr,
+        "--- stdout ---",
+        result.stdout,
+        "",
+    ].join("\n"), "utf8");
+    return logPath;
+}
+function errorCode(error) {
+    return "code" in error && typeof error.code === "string"
+        ? error.code
+        : null;
+}

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

@@ -1 +1,8 @@
 export declare function parseAllowedWpCommand(command: string): string[];
+/**
+ * Extracts the `--file` targets from an argv already parsed by
+ * `parseAllowedWpCommand`. Returns an empty array for any non-`wp test` argv.
+ * `parseAllowedWpCommand` guarantees `wp test` args are only `--file <target>`
+ * pairs, so no shell/flag validation is needed here.
+ */
+export declare function wpTestFileTargets(argv: readonly string[]): string[];

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

@@ -54,3 +54,23 @@ export function parseAllowedWpCommand(command) {
     }
     throw new Error(`Unsupported promotion gate wp subcommand: ${sub ?? ""}`);
 }
+/**
+ * Extracts the `--file` targets from an argv already parsed by
+ * `parseAllowedWpCommand`. Returns an empty array for any non-`wp test` argv.
+ * `parseAllowedWpCommand` guarantees `wp test` args are only `--file <target>`
+ * pairs, so no shell/flag validation is needed here.
+ */
+export function wpTestFileTargets(argv) {
+    if (argv[1] !== "test")
+        return [];
+    const targets = [];
+    const rest = argv.slice(2);
+    for (let i = 0; i < rest.length; i++) {
+        const target = rest[i + 1];
+        if (rest[i] === "--file" && target !== undefined) {
+            targets.push(target);
+            i += 1;
+        }
+    }
+    return targets;
+}

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

@@ -7,7 +7,15 @@ export type PromotionTrustInput = {
     markdown: string;
     now?: Date;
 };
+export type PromotionTrustProof = {
+    readonly file: string;
+    readonly sourceMarkdown: string;
+    readonly verifiedHead: string;
+    readonly trustedMarkdown: string;
+};
+export declare function preparePromotionTrustGate(input: PromotionTrustInput): PromotionTrustProof;
 export declare function applyPromotionTrustGate(input: PromotionTrustInput): string;
+export declare function assertPromotionTrustProofCurrent(input: Pick<PromotionTrustInput, "repoRoot" | "file" | "markdown">, proof: PromotionTrustProof): void;
 export declare function runPromotionCommand(repoRoot: string, command: string, deps?: {
     spawn?: typeof spawnSync;
 }): void;