@webpresso/agent-kit 3.1.28 → 3.2.0

package/dist/esm/blueprint/markdown/helpers.js

@@ -67,10 +67,14 @@ export function updateBlockedReason(content, taskId, reason) {
         const trimmedReason = reason.trim();
         const blockedPattern = /\n?\*\*Blocked:\*\*\s*.*(?:\n+)?/i;
         if (!trimmedReason) {
-            return section
+            // Preserve the section's trailing whitespace: trimEnd on the whole
+            // section would also delete the blank line separating this task from the
+            // next heading, changing bytes the writer does not own.
+            const trailingWhitespace = section.slice(section.trimEnd().length);
+            return (section
                 .replace(blockedPattern, "\n")
                 .replace(/\n{3,}/g, "\n\n")
-                .trimEnd();
+                .trimEnd() + trailingWhitespace);
         }
         const blockedLine = `**Blocked:** ${trimmedReason}`;
         if (/\*\*Blocked:\*\*/i.test(section)) {

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;

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

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

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

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