@webpresso/agent-kit 3.1.28 → 3.2.0

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

@@ -43,6 +43,7 @@ export declare function countDistinctLogBackedApprovals(file: string, approvals:
 export interface ApprovalGateEvaluation {
     distinct: number;
     openCodeGoModelReviewers: string[];
+    overrideReviewers: string[];
     satisfied: boolean;
     strongReviewers: string[];
 }
@@ -59,5 +60,24 @@ export declare function validateApprovalGate(file: string, frontmatter: Lifecycl
     completedApprovalGate?: boolean;
     inProgressApprovalGate?: boolean;
 }): BlueprintAuditIssue[];
+/**
+ * Write-path mirror of {@link validateApprovalGate}'s `completed` branch.
+ *
+ * There is no single completion chokepoint: this helper is called from all
+ * three write-path owners that can set `status: completed` — the MCP transition
+ * funnel `applyLocalBlueprintTransition` (finalize/promote/transition), the CLI
+ * `promoteBlueprintLocked` (which does not traverse that funnel), and the
+ * execution engine's `finalize` intent via `applyBlueprintLifecycleToFile`
+ * (exec/resume/stop/move). Calling it before each write guarantees a blueprint
+ * can only reach `completed` when it carries the same plan-purpose approval CI's
+ * `wp audit blueprint-lifecycle` requires afterward. It delegates to
+ * {@link validateApprovalGate} verbatim — including the pre-rollout grandfather
+ * ({@link predatesCompletedApprovalGate}) and the v2 `review-events.jsonl`
+ * ledger — so the write-path and the audit-path can never diverge and a
+ * finalized blueprint can never fail its own lifecycle audit.
+ *
+ * @throws Error when no plan-purpose approval satisfies the promotion reviewer mix.
+ */
+export declare function assertCompletedApprovalGate(file: string, markdown: string): void;
 export declare function runBlueprintAudit(options: RunBlueprintAuditOptions): Promise<BlueprintAuditResult>;
 export {};

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

@@ -13,6 +13,7 @@ import { resolveBlueprintRoot } from "#utils/blueprint-root";
 import { parseBlueprintDocumentRelativePath } from "#utils/document-paths.js";
 import { relativeBlueprintSlug } from "#lifecycle/local.js";
 import { collectV2ReviewProvenance, collectTrackedReviewProvenance, normalizeTrackedReviewApprovals, } from "#lifecycle/review-provenance.js";
+import { MAINTAINER_OVERRIDE_REVIEWER } from "#review/events.js";
 import { isPolicyApprovalVerdict } from "#review/verdict.js";
 function isBlueprintOverview(file) {
     const normalized = file.replace(/\\/g, "/");
@@ -94,11 +95,13 @@ function approvalReviewerKey(reviewer) {
     return parts.at(-1) ?? normalized;
 }
 function provenanceBackedApprovalReviewers(file, approvals, options = {}) {
-    const purpose = options.purpose ?? "plan";
-    const legacy = purpose === "plan"
+    const purposes = options.purpose
+        ? [options.purpose]
+        : ["plan", "delivery"];
+    const legacy = purposes.includes("plan")
         ? collectTrackedReviewProvenance(file, approvals, options).map((record) => record.reviewer)
         : [];
-    const current = collectV2ReviewProvenance(file, purpose, "HEAD", options.issuesSink).map((record) => record.reviewer);
+    const current = purposes.flatMap((purpose) => collectV2ReviewProvenance(file, purpose, "HEAD", options.issuesSink).map((record) => record.reviewer));
     return new Set([...legacy, ...current]);
 }
 export function countDistinctProvenanceBackedApprovals(file, approvals) {
@@ -116,15 +119,24 @@ export function evaluateApprovalReviewers(reviewerIds) {
     const openCodeGoModelReviewers = reviewers
         .map(approvalReviewerKey)
         .filter((reviewer) => OPENCODE_GO_MODEL_APPROVAL_REVIEWERS.has(reviewer));
+    const overrideReviewers = reviewers
+        .map(approvalReviewerKey)
+        .filter((reviewer) => reviewer === MAINTAINER_OVERRIDE_REVIEWER);
     return {
         distinct: reviewers.length,
         openCodeGoModelReviewers: [...new Set(openCodeGoModelReviewers)].sort(),
-        satisfied: strongReviewers.length >= 1 || new Set(openCodeGoModelReviewers).size >= 1,
+        overrideReviewers: [...new Set(overrideReviewers)].sort(),
+        satisfied: strongReviewers.length >= 1 ||
+            new Set(openCodeGoModelReviewers).size >= 1 ||
+            new Set(overrideReviewers).size >= 1,
         strongReviewers: [...new Set(strongReviewers)].sort(),
     };
 }
 export function formatApprovalGateRequirement(evaluation) {
-    return `need 1 provenance-backed Claude/Codex/Grok or OpenCode-Go model approval; currently have ${evaluation.strongReviewers.length} Claude/Codex/Grok approval(s), ${evaluation.openCodeGoModelReviewers.length} OpenCode-Go model approval(s), ${evaluation.distinct} distinct provenance-backed approval(s) total`;
+    const override = evaluation.overrideReviewers.length >= 1
+        ? ` + ${evaluation.overrideReviewers.length} maintainer-override(s)`
+        : "";
+    return `need 1 provenance-backed Claude/Codex/Grok or OpenCode-Go model approval (or a recorded maintainer-override); currently have ${evaluation.strongReviewers.length} Claude/Codex/Grok approval(s), ${evaluation.openCodeGoModelReviewers.length} OpenCode-Go model approval(s)${override}, ${evaluation.distinct} distinct provenance-backed approval(s) total`;
 }
 export function validateApprovalGate(file, frontmatter, options = {}) {
     if (frontmatter.type !== "blueprint")
@@ -162,6 +174,31 @@ export function validateApprovalGate(file, frontmatter, options = {}) {
         message: `Review evidence integrity: ${issue}`,
     }));
 }
+/**
+ * Write-path mirror of {@link validateApprovalGate}'s `completed` branch.
+ *
+ * There is no single completion chokepoint: this helper is called from all
+ * three write-path owners that can set `status: completed` — the MCP transition
+ * funnel `applyLocalBlueprintTransition` (finalize/promote/transition), the CLI
+ * `promoteBlueprintLocked` (which does not traverse that funnel), and the
+ * execution engine's `finalize` intent via `applyBlueprintLifecycleToFile`
+ * (exec/resume/stop/move). Calling it before each write guarantees a blueprint
+ * can only reach `completed` when it carries the same plan-purpose approval CI's
+ * `wp audit blueprint-lifecycle` requires afterward. It delegates to
+ * {@link validateApprovalGate} verbatim — including the pre-rollout grandfather
+ * ({@link predatesCompletedApprovalGate}) and the v2 `review-events.jsonl`
+ * ledger — so the write-path and the audit-path can never diverge and a
+ * finalized blueprint can never fail its own lifecycle audit.
+ *
+ * @throws Error when no plan-purpose approval satisfies the promotion reviewer mix.
+ */
+export function assertCompletedApprovalGate(file, markdown) {
+    const frontmatter = readLifecycleAuditFrontmatter(markdown);
+    const errors = validateApprovalGate(file, { ...frontmatter, status: "completed" }, { completedApprovalGate: true }).filter((issue) => issue.level === "error");
+    if (errors.length > 0) {
+        throw new Error(errors.map((issue) => issue.message).join("; "));
+    }
+}
 function countTaskHeadings(raw) {
     return raw.match(/^####\s+(?:\[[^\]]+\]\s+)?Task\s+/gm)?.length ?? 0;
 }
@@ -226,7 +263,13 @@ function validateTaskState(blueprint) {
     }
     return issues;
 }
-function validateBlueprintSlugUniqueness(blueprints) {
+function validateBlueprintSlugUniqueness(blueprints, 
+// When auditing a changed-only subset, `stagedSet` restricts reporting to
+// duplicates a CHANGED blueprint participates in, and attributes the error to
+// that changed file so a scope-filtering caller still surfaces it. A
+// pre-existing duplicate among only-untouched blueprints is left for the
+// full-corpus (CI) pass, not the changed-only hook.
+scope) {
     const grouped = new Map();
     for (const blueprint of blueprints) {
         const normalizedSlug = relativeBlueprintSlug(blueprint.slug);
@@ -239,12 +282,18 @@ function validateBlueprintSlugUniqueness(blueprints) {
         }
     }
     const issues = [];
+    const stagedSet = scope?.stagedSet ?? null;
     for (const [normalizedSlug, entries] of grouped) {
         const uniqueLifecycleSlugs = new Set(entries.map((entry) => entry.slug));
         if (uniqueLifecycleSlugs.size <= 1)
             continue;
+        const changedEntry = stagedSet
+            ? entries.find((entry) => stagedSet.has(normalizePath(path.relative(scope.projectRoot, entry.file))))
+            : undefined;
+        if (stagedSet && !changedEntry)
+            continue;
         issues.push({
-            file: entries[0]?.file,
+            file: (changedEntry ?? entries[0])?.file,
             level: "error",
             message: `Blueprint slug "${normalizedSlug}" appears in multiple lifecycle locations: ${Array.from(uniqueLifecycleSlugs)
                 .toSorted()
@@ -620,10 +669,16 @@ export async function runBlueprintAudit(options) {
         baseDir: resolveBlueprintRoot(options.projectRoot),
         includeSpecialFolders: true,
     });
-    const blueprintFiles = options.all || !options.stagedFiles
+    const stagedSet = options.all || !options.stagedFiles ? null : new Set(options.stagedFiles.map(normalizePath));
+    const blueprintFiles = stagedSet === null
         ? scanned
-        : scanned.filter((entry) => new Set(options.stagedFiles?.map(normalizePath) ?? []).has(normalizePath(path.relative(options.projectRoot, entry.path))));
-    issues.push(...validateBlueprintSlugUniqueness(blueprintFiles));
+        : scanned.filter((entry) => stagedSet.has(normalizePath(path.relative(options.projectRoot, entry.path))));
+    // Slug uniqueness is a corpus-wide invariant, so validate it over ALL scanned
+    // blueprints even in changed-only mode — otherwise a changed blueprint that
+    // duplicates an *untouched* lifecycle slug would only be compared with itself
+    // and the error would vanish. Only the expensive per-file audit below is
+    // scoped to the changed subset.
+    issues.push(...validateBlueprintSlugUniqueness(scanned, { projectRoot: options.projectRoot, stagedSet }));
     for (const entry of blueprintFiles) {
         issues.push(...(await auditBlueprintFile(entry.path, entry.slug, options)));
     }

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/engine.d.ts

@@ -35,5 +35,14 @@ export interface BlueprintLifecycleResult {
     progress: string;
     targetStatus: LifecycleBlueprintStatus;
 }
+/**
+ * Update only the named frontmatter keys, byte-preserving every other line.
+ * Review authority binds plan approvals to normalized blueprint bytes
+ * (`normalizePlanSubjectContent`), so lifecycle writers must never re-serialize
+ * fields they do not own — a whole-document YAML round-trip (quote-style or
+ * folding changes to an untouched `title:`) would strand committed approvals
+ * mid-lifecycle. Falls back to a gray-matter round-trip only when the document
+ * has no frontmatter block at all.
+ */
 export declare function setBlueprintFrontmatterFields(markdown: string, updates: Record<string, string | string[] | undefined>): string;
 export declare function applyBlueprintLifecycle(markdown: string, slug: string, intent: BlueprintLifecycleIntent): BlueprintLifecycleResult;

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

@@ -1,4 +1,5 @@
 import matter from "gray-matter";
+import { stringify as stringifyYaml } from "yaml";
 import { parseBlueprint } from "#core/parser";
 import { lifecycleBlueprintStatusSchema } from "#core/schema";
 import { updateBlockedReason, updateTaskStatus } from "#markdown/helpers";
@@ -6,17 +7,63 @@ import { applyVerification, assertAllTasksHaveCanonicalPassingEvidence } from "#
 function todayIsoDate() {
     return new Date().toISOString().split("T")[0] ?? new Date().toISOString();
 }
+function serializeFrontmatterEntry(key, value) {
+    // lineWidth: 0 disables folding so long scalars stay on one line. gray-matter
+    // parses frontmatter with js-yaml, which resolves plain date-like scalars
+    // ("2026-07-21") into Date objects — quote a string whenever gray-matter
+    // would not round-trip its plain form back to the same string.
+    const plain = stringifyYaml({ [key]: value }, { lineWidth: 0 }).trimEnd();
+    if (typeof value === "string" && matter(`---\n${plain}\n---\n`).data[key] !== value) {
+        return stringifyYaml({ [key]: value }, { defaultKeyType: "PLAIN", defaultStringType: "QUOTE_DOUBLE", lineWidth: 0 })
+            .trimEnd()
+            .split("\n");
+    }
+    return plain.split("\n");
+}
+/**
+ * Update only the named frontmatter keys, byte-preserving every other line.
+ * Review authority binds plan approvals to normalized blueprint bytes
+ * (`normalizePlanSubjectContent`), so lifecycle writers must never re-serialize
+ * fields they do not own — a whole-document YAML round-trip (quote-style or
+ * folding changes to an untouched `title:`) would strand committed approvals
+ * mid-lifecycle. Falls back to a gray-matter round-trip only when the document
+ * has no frontmatter block at all.
+ */
 export function setBlueprintFrontmatterFields(markdown, updates) {
-    const parsed = matter(markdown);
+    const match = /^(---\r?\n)([\s\S]*?)(\r?\n---(?:\r?\n|$))/u.exec(markdown);
+    if (!match) {
+        const parsed = matter(markdown);
+        for (const [key, value] of Object.entries(updates)) {
+            if (value === undefined || value === "") {
+                delete parsed.data[key];
+            }
+            else {
+                parsed.data[key] = value;
+            }
+        }
+        return matter.stringify(parsed.content, parsed.data);
+    }
+    const lines = (match[2] ?? "").split("\n");
     for (const [key, value] of Object.entries(updates)) {
-        if (value === undefined || value === "") {
-            delete parsed.data[key];
+        const keyPattern = new RegExp(String.raw `^${key}:`, "u");
+        const start = lines.findIndex((line) => keyPattern.test(line));
+        let removeCount = 0;
+        if (start !== -1) {
+            removeCount = 1;
+            while (start + removeCount < lines.length &&
+                /^[ \t]/u.test(lines[start + removeCount] ?? "")) {
+                removeCount += 1;
+            }
+        }
+        const replacement = value === undefined || value === "" ? [] : serializeFrontmatterEntry(key, value);
+        if (start !== -1) {
+            lines.splice(start, removeCount, ...replacement);
         }
-        else {
-            parsed.data[key] = value;
+        else if (replacement.length > 0) {
+            lines.push(...replacement);
         }
     }
-    return matter.stringify(parsed.content, parsed.data);
+    return `${match[1]}${lines.join("\n")}${match[3]}${markdown.slice(match[0].length)}`;
 }
 function assertExecutableStatus(status) {
     const parsed = lifecycleBlueprintStatusSchema.safeParse(status);

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.d.ts

@@ -36,6 +36,12 @@ export interface TrackedReviewProvenanceOptions {
     readonly targetHash?: string;
 }
 export declare function normalizeTrackedReviewApprovals(approvals: unknown): TrackedReviewApproval[];
+/**
+ * Read `_overview.md` for a blueprint at `ref`. Prefer the working-tree path;
+ * if missing (lifecycle move draft→planned before the promote commit), resolve
+ * by stable slug under any lifecycle directory at that ref.
+ */
+export declare function readBlueprintOverviewAtRef(repoRoot: string, ref: string, file: string): Buffer | null;
 export declare function collectV2ReviewProvenance(file: string, purpose: ReviewEvent["purpose"], ref?: string, issues?: string[]): readonly ValidTrackedReview[];
 export declare function auditReviewEventAppendOnly(cwd: string, baseRef: string, targetRef?: string): readonly string[];
 export declare function parseTrackedReviewRecords(markdown: string): TrackedReviewRecord[];

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

@@ -1,9 +1,9 @@
 import { execFileSync } from "node:child_process";
 import { existsSync, readFileSync } from "node:fs";
 import path from "node:path";
-import { readReviewAuthorityAtRef } from "#review/authority.js";
-import { parseReviewEventLog } from "#review/events.js";
-import { normalizePlanSubjectContent } from "#review/subject.js";
+import { readReviewAuthorityAtRef, readWorkingReviewEvents } from "#review/authority.js";
+import { evaluateReviewEvents, parseReviewEventLog } from "#review/events.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,8 +50,59 @@ 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));
 }
+/**
+ * Read `_overview.md` for a blueprint at `ref`. Prefer the working-tree path;
+ * if missing (lifecycle move draft→planned before the promote commit), resolve
+ * by stable slug under any lifecycle directory at that ref.
+ */
+export function readBlueprintOverviewAtRef(repoRoot, ref, file) {
+    const relative = normalizePath(path.relative(repoRoot, file));
+    if (relative.startsWith("..") || path.isAbsolute(relative))
+        return null;
+    try {
+        return execFileSync("git", ["show", `${ref}:${relative}`], {
+            cwd: repoRoot,
+            encoding: "buffer",
+            stdio: ["ignore", "pipe", "pipe"],
+            timeout: 5_000,
+        });
+    }
+    catch {
+        // Path may have moved across lifecycle dirs (draft→planned) while the
+        // promote commit is still uncommitted. Stable slug is the authority key.
+        const slug = stableSlugForBlueprintFile(file);
+        if (!slug || slug.includes(".."))
+            return null;
+        try {
+            const names = execFileSync("git", ["ls-tree", "-r", "--name-only", ref], {
+                cwd: repoRoot,
+                encoding: "utf8",
+                stdio: ["ignore", "pipe", "pipe"],
+                timeout: 5_000,
+            });
+            const escaped = slug.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&");
+            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;
+            return execFileSync("git", ["show", `${ref}:${hits[0]}`], {
+                cwd: repoRoot,
+                encoding: "buffer",
+                stdio: ["ignore", "pipe", "pipe"],
+                timeout: 5_000,
+            });
+        }
+        catch {
+            return null;
+        }
+    }
+}
 function workingContentMatchesRef(repoRoot, file, purpose, ref) {
     const relative = path.relative(repoRoot, file);
     if (relative.startsWith("..") || path.isAbsolute(relative))
@@ -63,12 +114,11 @@ function workingContentMatchesRef(repoRoot, file, purpose, ref) {
             // in the working tree before the promotion commit exists, and that
             // window must not strip a legitimately promoted blueprint of its plan
             // authority. Substantive edits still differ after normalization.
-            const atRef = execFileSync("git", ["show", `${ref}:${normalizePath(relative)}`], {
-                cwd: repoRoot,
-                encoding: "buffer",
-                stdio: ["ignore", "pipe", "pipe"],
-                timeout: 5_000,
-            });
+            // Also resolve by stable slug when the lifecycle path changed (draft→planned)
+            // so pre-commit on a rename does not falsely drop plan authority.
+            const atRef = readBlueprintOverviewAtRef(repoRoot, ref, file);
+            if (!atRef)
+                return false;
             const working = readFileSync(file);
             return normalizePlanSubjectContent(working).equals(normalizePlanSubjectContent(atRef));
         }
@@ -84,27 +134,83 @@ function workingContentMatchesRef(repoRoot, file, purpose, ref) {
         return false;
     }
 }
+// Working-ledger acceptance: pre-commit validates a blueprint whose new review
+// events are staged alongside it and therefore not yet at any git ref. An
+// 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, 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 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: subject.scheme,
+            subjectDigest: subject.digest,
+        }, working.compromisedIds).approvals)
+            .filter((event) => event.artifactPath)
+            .map((event) => ({
+            reviewer: event.reviewer,
+            artifact: event.artifactPath,
+            targetHash: event.subjectDigest,
+        }));
+    }
+    catch (error) {
+        issues?.push(`Working review authority unavailable for ${file}: ${error instanceof Error ? error.message : String(error)}`);
+        return [];
+    }
+}
 export function collectV2ReviewProvenance(file, purpose, ref = "HEAD", issues) {
     const repoRoot = findGitRoot(file);
     if (!repoRoot)
         return [];
+    const workingApprovals = collectWorkingV2ReviewProvenance(file, purpose, issues);
     if (!workingContentMatchesRef(repoRoot, file, purpose, ref))
-        return [];
+        return workingApprovals;
     try {
         const authority = readReviewAuthorityAtRef(repoRoot, ref, stableSlugForBlueprintFile(file), purpose);
         issues?.push(...authority.issues);
-        return authority.approvals.map((event) => ({
+        const refApprovals = authority.approvals.map((event) => ({
             reviewer: event.reviewer,
             artifact: event.artifactPath,
             targetHash: event.subjectDigest,
         }));
+        const seen = new Set(refApprovals.map((approval) => approval.reviewer));
+        return [...refApprovals, ...workingApprovals.filter((entry) => !seen.has(entry.reviewer))];
     }
     catch (error) {
         // Container-level failure (unparseable ledger, duplicate ids, cross-slug
         // events, unresolved commit): fail closed for the whole file, but surface
         // the reason instead of silently reporting zero authority.
         issues?.push(`Review authority unavailable for ${file}: ${error instanceof Error ? error.message : String(error)}`);
-        return [];
+        return workingApprovals;
     }
 }
 function reviewEventLogsAtRef(cwd, ref) {