@webpresso/agent-kit 3.1.30 → 3.3.0

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

@@ -36,6 +36,12 @@ export interface TrackedReviewProvenanceOptions {
     readonly targetHash?: string;
 }
 export declare function normalizeTrackedReviewApprovals(approvals: unknown): TrackedReviewApproval[];
+/**
+ * Slug for a blueprint file, invariant across lifecycle moves
+ * (`draft/ → planned/ → completed/`) and across both the folder
+ * (`<slug>/_overview.md`) and legacy flat (`<slug>.md`) shapes.
+ */
+export declare function stableSlugForBlueprintFile(file: string): string;
 /**
  * Read `_overview.md` for a blueprint at `ref`. Prefer the working-tree path;
  * if missing (lifecycle move draft→planned before the promote commit), resolve

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, createLegacyPlanSubjectDigestForContent, createPlanSubjectDigestForContent, createPreTagsStripPlanSubjectDigestForContent, normalizePlanSubjectContent, } from "#review/subject.js";
 import { isPolicyApprovalVerdict } from "#review/verdict.js";
 const REVIEW_ENTRY_MARKER = "<!-- wp:review-entry ";
 function normalizePath(file) {
@@ -44,12 +44,21 @@ function findGitRoot(file) {
         current = parent;
     }
 }
-function stableSlugForBlueprintFile(file) {
+/**
+ * Slug for a blueprint file, invariant across lifecycle moves
+ * (`draft/ → planned/ → completed/`) and across both the folder
+ * (`<slug>/_overview.md`) and legacy flat (`<slug>.md`) shapes.
+ */
+export function stableSlugForBlueprintFile(file) {
     const segments = normalizePath(file).split("/");
     const lifecycleIndex = segments.findIndex((segment) => new Set(["draft", "planned", "parked", "in-progress", "completed", "archived"]).has(segment));
     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 +92,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 +144,68 @@ 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",
+        // Events whose recorded `reviewedCommit` no longer resolves (typically
+        // orphaned by a rebase). Collected here rather than mutating
+        // `working.compromisedIds`, which is a ReadonlySet by contract, then merged
+        // into the set handed to evaluateReviewEvents below.
+        const unresolvableEventIds = new Set();
+        const subjects = purpose === "plan"
+            ? [
+                ...new Map([
+                    createPlanSubjectDigestForContent(slug, readFileSync(file)),
+                    createPreTagsStripPlanSubjectDigestForContent(slug, readFileSync(file)),
+                    createLegacyPlanSubjectDigestForContent(slug, readFileSync(file)),
+                ].map((digest) => [digest, { scheme: "wp-blueprint-v1", digest }])).values(),
+            ]
+            : [
+                ...new Map(working.events
+                    .filter((event) => event.purpose === "delivery")
+                    .flatMap((event) => {
+                    // Scope subject-construction failure to THIS event. A rebase
+                    // rewrites commit SHAs, so a previously-recorded
+                    // `reviewedCommit` can become unresolvable; letting that throw
+                    // would escape to the outer catch and discard every approval,
+                    // including valid ones for commits that still resolve. Mirror
+                    // the ref-path's markCompromisedArtifactEvents: record the
+                    // issue, mark the event compromised, and drop only it.
+                    let subject;
+                    try {
+                        subject = createDeliverySubjectAtRef(repoRoot, event.reviewedCommit, slug, normalizePath(path.relative(repoRoot, file)));
+                    }
+                    catch (error) {
+                        issues?.push(`Working delivery review subject unavailable for ${event.id} at ${event.reviewedCommit}: ${error instanceof Error ? error.message : String(error)}`);
+                        // Compromised (not merely skipped) so the event can never
+                        // grant approval while still participating in reviewer
+                        // supersession — see evaluateReviewEvents.
+                        unresolvableEventIds.add(event.id);
+                        return [];
+                    }
+                    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,
+        }, unresolvableEventIds.size === 0
+            ? working.compromisedIds
+            : new Set([...working.compromisedIds, ...unresolvableEventIds])).approvals)
             .filter((event) => event.artifactPath)
             .map((event) => ({
             reviewer: event.reviewer,
@@ -166,7 +222,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/lifecycle/rollout-anchor.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Rollout grandfathering, decided from git history instead of frontmatter.
+ *
+ * Two gates used to grant themselves an exemption by reading a blueprint's own
+ * `created:` frontmatter and comparing it to a hardcoded rollout date. That
+ * value is written by the same author the gate is meant to constrain, so
+ * `created: "2020-01-01"` disabled the check outright — on the CI audit path and
+ * (for the approval gate) on the `assertCompletedApprovalGate` write path, which
+ * would let a blueprint reach `completed` carrying no approval at all.
+ *
+ * Presence in a fixed commit's tree is instead a structural fact about history:
+ * no file content can add a slug to a tree that was written months ago.
+ *
+ * Matching on **slug** rather than path is deliberate. Blueprints legitimately
+ * move `draft/ → planned/ → completed/`, so a path-based check would mistake a
+ * lifecycle move for a new blueprint, while `git log --follow` would introduce a
+ * rename-similarity heuristic. The slug is invariant across those moves — the
+ * repo already enforces one blueprint = one slug = one `bp/<slug>` branch.
+ */
+/**
+ * The commit that introduced both the completed-approval gate and the Trust
+ * Dossier requirement ("fix: preserve pre-contract blueprint rollouts",
+ * 2026-07-12). Blueprints already tracked at this commit predate both contracts.
+ */
+export declare const ROLLOUT_ANCHOR_COMMIT = "c6ccb5f31cbecde3be4dbd6d3b7e67918006d22e";
+/** The date that anchor landed, used only by the legacy fallback below. */
+export declare const ROLLOUT_DATE = "2026-07-12";
+/**
+ * Outcome of consulting the anchor, cached per (repoRoot, anchorCommit).
+ *
+ * - `not-applicable`: the anchor commit is not in this repository at all. The
+ *   rollout it marks is an agent-kit history event, so in a consumer repo (which
+ *   has its own unrelated history) the "predates the rollout" question is
+ *   vacuous. Those repos keep their prior behaviour: nothing is retroactively
+ *   gated. The security property is unaffected where it matters, because in
+ *   agent-kit the anchor is an ancestor of `main`. Note a shallow clone can
+ *   also lack it; that case is detected separately and fails closed rather
+ *   than falling back, so truncated history cannot reopen the bypass.
+ * - `slugs`: the anchor resolved; membership decides the exemption.
+ * - `unreadable`: the anchor exists but could not be listed, OR it is absent
+ *   from a shallow clone where truncated history could be hiding it. Both are
+ *   inconclusive rather than different-repo signals, so both fail **closed**.
+ *   Memoised for the process lifetime, so a transient git failure stays
+ *   fail-closed for the rest of the run -- acceptable for short-lived CLI and
+ *   audit processes, and the safe direction if it ever is not.
+ */
+type AnchorLookup = {
+    readonly kind: "not-applicable";
+} | {
+    readonly kind: "slugs";
+    readonly slugs: ReadonlySet<string>;
+} | {
+    readonly kind: "unreadable";
+};
+/**
+ * Slugs tracked under `blueprints/` at `anchorCommit`, or `null` when the anchor
+ * cannot be read. Memoised per (repoRoot, anchorCommit).
+ *
+ * Callers must treat `null` as "grandfather nobody" — see
+ * {@link isBlueprintExemptFromRollout}, which fails closed.
+ */
+export declare function blueprintSlugsAtRolloutAnchor(repoRoot: string, anchorCommit?: string): AnchorLookup;
+/**
+ * True when this blueprint is exempt from a rollout-gated contract.
+ *
+ * Resolution order, deliberately:
+ *
+ * 1. **Anchor is present in this repository** (the agent-kit repo, where these
+ *    contracts actually rolled out and where CI and the promote/finalize write
+ *    path enforce them): membership in the anchor tree decides, and the
+ *    author-supplied `created` is ignored entirely. This is what closes the
+ *    forgery — a blueprint cannot add its own slug to a months-old tree.
+ * 2. **Anchor absent from a full (non-shallow) clone, or no git repository at
+ *    all**: the rollout is an agent-kit history event that never happened here,
+ *    so the anchor cannot answer the question. Fall back to the previous
+ *    `created` compare. This is unchanged prior behaviour for consumer repos and
+ *    non-git contexts, which is deliberate: those contexts have no such
+ *    protection today, so tightening them is a separate decision, and gating
+ *    them here would be unsatisfiable anyway because every accepted form of
+ *    approval provenance is git-tracked.
+ * 3. **Inconclusive**: the anchor exists but cannot be listed, or it is absent
+ *    from a *shallow* clone where truncated history could be hiding it. Fails
+ *    **closed** — the gate applies. Without the shallow check, `git clone
+ *    --depth 1` of this very repository would drop to the forgeable date
+ *    fallback and reopen the bypass on the local promote/finalize write path.
+ *
+ * Net effect: strictly hardens the gate where it is enforced, and regresses
+ * nothing anywhere else.
+ */
+export declare function isBlueprintExemptFromRollout(input: {
+    readonly repoRoot: string | null | undefined;
+    readonly slug: string;
+    readonly created: unknown;
+    readonly rolloutDate: string;
+    readonly anchorCommit?: string;
+}): boolean;
+export {};

package/dist/esm/blueprint/lifecycle/rollout-anchor.js

@@ -0,0 +1,161 @@
+import { execFileSync } from "node:child_process";
+/**
+ * Rollout grandfathering, decided from git history instead of frontmatter.
+ *
+ * Two gates used to grant themselves an exemption by reading a blueprint's own
+ * `created:` frontmatter and comparing it to a hardcoded rollout date. That
+ * value is written by the same author the gate is meant to constrain, so
+ * `created: "2020-01-01"` disabled the check outright — on the CI audit path and
+ * (for the approval gate) on the `assertCompletedApprovalGate` write path, which
+ * would let a blueprint reach `completed` carrying no approval at all.
+ *
+ * Presence in a fixed commit's tree is instead a structural fact about history:
+ * no file content can add a slug to a tree that was written months ago.
+ *
+ * Matching on **slug** rather than path is deliberate. Blueprints legitimately
+ * move `draft/ → planned/ → completed/`, so a path-based check would mistake a
+ * lifecycle move for a new blueprint, while `git log --follow` would introduce a
+ * rename-similarity heuristic. The slug is invariant across those moves — the
+ * repo already enforces one blueprint = one slug = one `bp/<slug>` branch.
+ */
+/**
+ * The commit that introduced both the completed-approval gate and the Trust
+ * Dossier requirement ("fix: preserve pre-contract blueprint rollouts",
+ * 2026-07-12). Blueprints already tracked at this commit predate both contracts.
+ */
+export const ROLLOUT_ANCHOR_COMMIT = "c6ccb5f31cbecde3be4dbd6d3b7e67918006d22e";
+/** The date that anchor landed, used only by the legacy fallback below. */
+export const ROLLOUT_DATE = "2026-07-12";
+const anchorSlugCache = new Map();
+function anchorCommitExists(repoRoot, anchorCommit) {
+    try {
+        execFileSync("git", ["cat-file", "-e", `${anchorCommit}^{commit}`], {
+            cwd: repoRoot,
+            stdio: ["ignore", "ignore", "ignore"],
+        });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * A shallow clone (`git clone --depth 1`) can be missing the anchor purely
+ * because history was truncated, which is indistinguishable from "different
+ * repository" by anchor lookup alone. Detecting shallowness lets us tell the two
+ * apart instead of assuming the benign one.
+ */
+function isShallowRepository(repoRoot) {
+    try {
+        const out = execFileSync("git", ["rev-parse", "--is-shallow-repository"], {
+            cwd: repoRoot,
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"],
+        });
+        // A path that is not a git repository at all answers with a non-zero exit,
+        // handled below. Anything else that is not a clean "false" is treated as
+        // truncated, so an odd repository shape fails closed rather than falling
+        // back to the forgeable date.
+        return out.trim() !== "false";
+    }
+    catch {
+        // Not a git repository (or git is unusable here). This is the "no history to
+        // consult" case, not a truncated-history case: the caller falls back, which
+        // preserves prior behaviour for non-git contexts where the gate would be
+        // unsatisfiable anyway.
+        return false;
+    }
+}
+/**
+ * Slugs tracked under `blueprints/` at `anchorCommit`, or `null` when the anchor
+ * cannot be read. Memoised per (repoRoot, anchorCommit).
+ *
+ * Callers must treat `null` as "grandfather nobody" — see
+ * {@link isBlueprintExemptFromRollout}, which fails closed.
+ */
+export function blueprintSlugsAtRolloutAnchor(repoRoot, anchorCommit = ROLLOUT_ANCHOR_COMMIT) {
+    const cacheKey = `${anchorCommit}:${repoRoot}`;
+    const cached = anchorSlugCache.get(cacheKey);
+    if (cached !== undefined)
+        return cached;
+    const result = (() => {
+        if (!anchorCommitExists(repoRoot, anchorCommit)) {
+            // Absent because this is a different repository (fine -- the rollout never
+            // happened here) or because history was truncated (NOT fine -- that would
+            // silently reopen the forged-date bypass). Only the former may fall back.
+            return isShallowRepository(repoRoot) ? { kind: "unreadable" } : { kind: "not-applicable" };
+        }
+        try {
+            const stdout = execFileSync("git", ["ls-tree", "-r", "--name-only", anchorCommit, "blueprints/"], { cwd: repoRoot, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] });
+            const found = new Set();
+            for (const line of stdout.split("\n")) {
+                const match = /^blueprints\/[^/]+\/(.+)$/u.exec(line.trim());
+                if (!match)
+                    continue;
+                const rest = match[1] ?? "";
+                // Folder shape `<slug>/_overview.md`, or legacy flat `<slug>.md`.
+                const slug = rest.includes("/")
+                    ? rest.slice(0, rest.indexOf("/"))
+                    : rest.endsWith(".md")
+                        ? rest.slice(0, -3)
+                        : "";
+                if (slug)
+                    found.add(slug);
+            }
+            return { kind: "slugs", slugs: found };
+        }
+        catch {
+            return { kind: "unreadable" };
+        }
+    })();
+    anchorSlugCache.set(cacheKey, result);
+    return result;
+}
+/** Legacy fallback: the author-supplied `created` date compare. */
+function createdPredatesRollout(created, rolloutDate) {
+    const date = created instanceof Date
+        ? created.toISOString().slice(0, 10)
+        : typeof created === "string" && /^\d{4}-\d{2}-\d{2}$/u.test(created)
+            ? created
+            : null;
+    return date !== null && date < rolloutDate;
+}
+/**
+ * True when this blueprint is exempt from a rollout-gated contract.
+ *
+ * Resolution order, deliberately:
+ *
+ * 1. **Anchor is present in this repository** (the agent-kit repo, where these
+ *    contracts actually rolled out and where CI and the promote/finalize write
+ *    path enforce them): membership in the anchor tree decides, and the
+ *    author-supplied `created` is ignored entirely. This is what closes the
+ *    forgery — a blueprint cannot add its own slug to a months-old tree.
+ * 2. **Anchor absent from a full (non-shallow) clone, or no git repository at
+ *    all**: the rollout is an agent-kit history event that never happened here,
+ *    so the anchor cannot answer the question. Fall back to the previous
+ *    `created` compare. This is unchanged prior behaviour for consumer repos and
+ *    non-git contexts, which is deliberate: those contexts have no such
+ *    protection today, so tightening them is a separate decision, and gating
+ *    them here would be unsatisfiable anyway because every accepted form of
+ *    approval provenance is git-tracked.
+ * 3. **Inconclusive**: the anchor exists but cannot be listed, or it is absent
+ *    from a *shallow* clone where truncated history could be hiding it. Fails
+ *    **closed** — the gate applies. Without the shallow check, `git clone
+ *    --depth 1` of this very repository would drop to the forgeable date
+ *    fallback and reopen the bypass on the local promote/finalize write path.
+ *
+ * Net effect: strictly hardens the gate where it is enforced, and regresses
+ * nothing anywhere else.
+ */
+export function isBlueprintExemptFromRollout(input) {
+    const { repoRoot, slug, created, rolloutDate } = input;
+    const anchorCommit = input.anchorCommit ?? ROLLOUT_ANCHOR_COMMIT;
+    if (repoRoot) {
+        const lookup = blueprintSlugsAtRolloutAnchor(repoRoot, anchorCommit);
+        if (lookup.kind === "slugs")
+            return slug.length > 0 && lookup.slugs.has(slug);
+        if (lookup.kind === "unreadable")
+            return false;
+    }
+    return createdPredatesRollout(created, rolloutDate);
+}

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 {};