@webpresso/agent-kit 3.1.26 → 3.1.30

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

@@ -369,6 +369,27 @@ function changedBlueprintScope(candidates) {
     }
     return { slugs };
 }
+/**
+ * When `--affected` supplies an explicit file set (pre-commit staged files or
+ * branch ACMR list), only keep blueprint transition candidates that touch
+ * those paths. Untracked WIP drafts outside the set must not fail the commit.
+ *
+ * `affectedFiles === undefined` keeps the full porcelain candidate map (CLI
+ * `wp audit blueprint-lifecycle --changed-only` without a staged filter).
+ */
+function filterTransitionCandidatesByAffectedFiles(candidates, affectedFiles) {
+    if (affectedFiles === undefined)
+        return candidates;
+    const allowed = new Set(affectedFiles.map((file) => normalizeGitPath(file)));
+    const filtered = new Map();
+    for (const [currentPath, candidate] of candidates) {
+        const paths = [currentPath, ...candidate.previousPaths].map(normalizeGitPath);
+        if (paths.some((p) => allowed.has(p))) {
+            filtered.set(currentPath, candidate);
+        }
+    }
+    return filtered;
+}
 function violationTouchesBlueprintScope(violation, scope) {
     if (!violation.file)
         return false;
@@ -422,7 +443,10 @@ export async function auditBlueprintLifecycleSql(cwd = process.cwd(), options =
     const changedCandidateMap = gitHistoryAvailable
         ? listChangedBlueprintCandidates(cwd, { baseRef: options.baseRef })
         : null;
-    const changedScope = changedCandidateMap === null ? null : changedBlueprintScope(changedCandidateMap);
+    const scopedCandidateMap = changedCandidateMap === null
+        ? null
+        : filterTransitionCandidatesByAffectedFiles(changedCandidateMap, options.affectedFiles);
+    const changedScope = scopedCandidateMap === null ? null : changedBlueprintScope(scopedCandidateMap);
     // Review-evidence append-only enforcement (base-vs-head ledger prefix check).
     // Runs BEFORE the changed-only early returns: a PR that only rewrites a
     // review-events.jsonl touches zero blueprint documents, so changedScope is

package/dist/esm/audit/blueprint-pr-coverage.js

@@ -1,5 +1,6 @@
 import { spawnSync } from "node:child_process";
-import { relative } from "node:path";
+import { existsSync, readFileSync } from "node:fs";
+import { join, relative } from "node:path";
 import { resolveBlueprintRoot } from "#utils/blueprint-root.js";
 const TITLE = "Blueprint PR coverage";
 const BLUEPRINT_EXEMPT_PATTERN = /^Blueprint-exempt:\s*(\S.*)$/im;
@@ -39,14 +40,33 @@ export function auditBlueprintPrCoverage(rootDirectory = process.cwd(), options
     const configuredRoot = normalizeRoot(normalizePath(relative(rootDirectory, resolveBlueprintRoot(rootDirectory))));
     const blueprintRoots = [...new Set(["blueprints", configuredRoot].filter(Boolean))];
     const finalEntries = entries.filter((entry) => entry.status !== "D");
-    const activePaths = finalEntries.filter((entry) => {
+    const activeEntries = finalEntries.flatMap((entry) => {
         const location = parseBlueprintLocation(entry.path, blueprintRoots);
-        return location !== null && ACTIVE_LIFECYCLE_DIRECTORIES.has(location.lifecycle);
+        if (!location || !ACTIVE_LIFECYCLE_DIRECTORIES.has(location.lifecycle))
+            return [];
+        return [{ entry, location }];
     });
-    if (activePaths.length > 0) {
-        return fail(`non-doc landing PR leaves changed active blueprint content at ${activePaths
-            .map((entry) => entry.path)
-            .join(", ")}; move the owner blueprint to completed before merge`, changedFiles.length);
+    const ownerActive = activeEntries.filter(({ location }) => location.slug === ownerSlug);
+    if (ownerActive.length > 0) {
+        return fail(`non-doc landing PR leaves owner blueprint "${ownerSlug}" in active lifecycle at ${ownerActive
+            .map(({ entry }) => entry.path)
+            .join(", ")}; move completed/${ownerSlug}/_overview.md (or .md) into the PR and drop active-lifecycle owner paths`, changedFiles.length);
+    }
+    // Parent-roadmap program trackers may co-edit on a child land PR while still
+    // active (draft/planned). Executable blueprints (type: blueprint) may not.
+    const nonOwnerActive = activeEntries.filter(({ location }) => location.slug !== ownerSlug);
+    const programTrackers = [];
+    const blockingNonOwner = [];
+    for (const { entry, location } of nonOwnerActive) {
+        if (isParentRoadmapDocument(rootDirectory, entry.path, location)) {
+            programTrackers.push(entry.path);
+        }
+        else {
+            blockingNonOwner.push(entry.path);
+        }
+    }
+    if (blockingNonOwner.length > 0) {
+        return fail(`non-doc landing PR changes active non-owner blueprint content at ${blockingNonOwner.join(", ")}; remove those paths from the PR or complete those blueprints first (owner ${ownerSlug} is separate)`, changedFiles.length);
     }
     const matchingCompletedOwner = finalEntries.some((entry) => {
         const location = parseBlueprintLocation(entry.path, blueprintRoots);
@@ -55,6 +75,9 @@ export function auditBlueprintPrCoverage(rootDirectory = process.cwd(), options
     if (!matchingCompletedOwner) {
         return fail(`non-doc PR on ${headRef} must change its completed owner blueprint at completed/${ownerSlug}/_overview.md (or completed/${ownerSlug}.md)`, changedFiles.length);
     }
+    if (programTrackers.length > 0) {
+        return passWithWarning(`[warn] co-edited parent-roadmap program tracker(s) on non-doc land: ${programTrackers.join(", ")}`, changedFiles.length);
+    }
     return pass(changedFiles.length);
 }
 function pass(checked) {
@@ -134,6 +157,44 @@ function parseBlueprintLocation(filePath, roots) {
     }
     return null;
 }
+/**
+ * True when the changed path belongs to a `type: parent-roadmap` document.
+ * Nested non-overview files under a parent-roadmap folder inherit the overview
+ * type so review artifacts co-travel. Missing paths (unit-test fakes) return
+ * false → fail closed as executable blueprints.
+ */
+function isParentRoadmapDocument(rootDirectory, filePath, location) {
+    const normalized = normalizePath(filePath);
+    const overviewCandidates = [
+        // Prefer the changed overview when it is the document itself.
+        ...(location.ownerDocument ? [normalized] : []),
+        // folder overview: …/<lifecycle>/<slug>/_overview.md
+        normalized.replace(new RegExp(`/(draft|planned|in-progress|parked|completed|archived)/${escapeRegex(location.slug)}(?:/.*)?$`, "u"), `/$1/${location.slug}/_overview.md`),
+        // flat overview: …/<lifecycle>/<slug>.md
+        normalized.replace(new RegExp(`/(draft|planned|in-progress|parked|completed|archived)/${escapeRegex(location.slug)}(?:/.*|\\.md)?$`, "u"), `/$1/${location.slug}.md`),
+    ];
+    const seen = new Set();
+    for (const candidate of overviewCandidates) {
+        if (seen.has(candidate))
+            continue;
+        seen.add(candidate);
+        const abs = join(rootDirectory, candidate);
+        if (!existsSync(abs))
+            continue;
+        try {
+            const head = readFileSync(abs, "utf8").slice(0, 4_096);
+            if (/^type:\s*['"]?parent-roadmap['"]?\s*$/mu.test(head))
+                return true;
+        }
+        catch {
+            // unreadable → fail closed
+        }
+    }
+    return false;
+}
+function escapeRegex(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&");
+}
 function isDependabotDependencyOnlyUpdate(cwd, options, changedFiles) {
     if (!changedFiles.every(isDependabotDependencyFile))
         return false;

package/dist/esm/audit/registry.d.ts

@@ -14,11 +14,11 @@ export interface AuditKindDescriptor {
 }
 export declare const SCRIPT_AUDIT_KIND_IDS: readonly ["test-smells", "tph-e2e"];
 export declare const SPECIAL_AUDIT_KIND_IDS: readonly ["bundle-budget", "commit-message", "blueprint-pr-coverage", "mutation", "guardrails", "quality"];
-export declare const REPO_AUDIT_KIND_IDS: readonly ["catalog-drift", "package-surface", "command-surface", "reference-parity-matrix", "blueprint-readme-drift", "blueprint-lifecycle", "blueprint-trust", "roadmap-links", "docs-frontmatter", "agents", "vision", "tech-debt", "supported-agent-clis", "no-relative-parent-imports", "no-link-protocol", "no-relative-package-scripts", "test-isolation", "bucket-boundary", "skill-sizes", "broken-refs", "memory-rotation", "gitignore-agent-surfaces", "memory-unified", "compile-drift", "no-legacy-cli-bin", "architecture-drift", "cloudflare-deploy-contract", "toolchain-isolation", "absolute-path-policy", "no-first-party-mjs", "outside-review-runtime-ownership", "no-math-random", "agent-cost", "blueprint-db-consistency", "tech-debt-cadence", "cross-repo-correlation", "ai-contracts", "atomic-state-writes", "hook-surface", "hook-vendor-drift", "session-memory-hardcut", "open-source-licenses", "secrets-policy", "no-dev-vars", "secret-provider-quarantine", "github-actions-secrets", "security-quality-regressions", "secrets-config", "consumer-agent-kit-dependency", "ci-test-perf", "worktree-main-ownership", "sast", "harness-surfaces", "weakness-mining", "harness-overlay-evidence", "legacy-workflow-identity", "rules", "skills"];
+export declare const REPO_AUDIT_KIND_IDS: readonly ["catalog-drift", "package-surface", "command-surface", "reference-parity-matrix", "blueprint-readme-drift", "blueprint-lifecycle", "blueprint-trust", "roadmap-links", "docs-frontmatter", "agents", "vision", "tech-debt", "supported-agent-clis", "no-relative-parent-imports", "no-link-protocol", "no-relative-package-scripts", "test-isolation", "bucket-boundary", "skill-sizes", "broken-refs", "memory-rotation", "gitignore-agent-surfaces", "memory-unified", "compile-drift", "no-legacy-cli-bin", "architecture-drift", "cloudflare-deploy-contract", "toolchain-isolation", "absolute-path-policy", "no-first-party-mjs", "outside-review-runtime-ownership", "no-math-random", "agent-cost", "blueprint-db-consistency", "tech-debt-cadence", "cross-repo-correlation", "ai-contracts", "atomic-state-writes", "hook-surface", "hook-vendor-drift", "session-memory-hardcut", "open-source-licenses", "secrets-policy", "no-dev-vars", "secret-provider-quarantine", "github-actions-secrets", "security-quality-regressions", "secrets-config", "consumer-agent-kit-dependency", "ci-test-perf", "test-scan-perf", "worktree-main-ownership", "sast", "harness-surfaces", "weakness-mining", "harness-overlay-evidence", "legacy-workflow-identity", "rules", "skills"];
 export declare const AUDIT_KIND_DESCRIPTORS: readonly AuditKindDescriptor[];
-export declare const AUDIT_KIND_IDS: readonly ["test-smells", "tph-e2e", ...("absolute-path-policy" | "agent-cost" | "agents" | "ai-contracts" | "architecture-drift" | "atomic-state-writes" | "blueprint-db-consistency" | "blueprint-lifecycle" | "blueprint-pr-coverage" | "blueprint-readme-drift" | "blueprint-trust" | "broken-refs" | "bucket-boundary" | "bundle-budget" | "catalog-drift" | "ci-test-perf" | "cloudflare-deploy-contract" | "command-surface" | "commit-message" | "compile-drift" | "consumer-agent-kit-dependency" | "cross-repo-correlation" | "docs-frontmatter" | "github-actions-secrets" | "gitignore-agent-surfaces" | "guardrails" | "harness-overlay-evidence" | "harness-surfaces" | "hook-surface" | "hook-vendor-drift" | "legacy-workflow-identity" | "memory-rotation" | "memory-unified" | "mutation" | "no-dev-vars" | "no-first-party-mjs" | "no-legacy-cli-bin" | "no-link-protocol" | "no-math-random" | "no-relative-package-scripts" | "no-relative-parent-imports" | "open-source-licenses" | "outside-review-runtime-ownership" | "package-surface" | "quality" | "reference-parity-matrix" | "roadmap-links" | "rules" | "sast" | "secret-provider-quarantine" | "secrets-config" | "secrets-policy" | "security-quality-regressions" | "session-memory-hardcut" | "skill-sizes" | "skills" | "supported-agent-clis" | "tech-debt" | "tech-debt-cadence" | "test-isolation" | "toolchain-isolation" | "vision" | "weakness-mining" | "worktree-main-ownership")[]];
-export declare const MCP_AUDIT_KIND_IDS: readonly ["test-smells", "tph-e2e", "agents", "catalog-drift", "package-surface", "reference-parity-matrix", "docs-frontmatter", "blueprint-readme-drift", "blueprint-pr-coverage", "blueprint-lifecycle", "blueprint-trust", "architecture-drift", "cloudflare-deploy-contract", "absolute-path-policy", "no-first-party-mjs", "no-math-random", "roadmap-links", "bundle-budget", "commit-message", "tech-debt", "supported-agent-clis", "hook-surface", "harness-surfaces", "weakness-mining", "harness-overlay-evidence", "ai-contracts", "atomic-state-writes", "no-relative-package-scripts", "toolchain-isolation", "open-source-licenses", "secrets-policy", "no-dev-vars", "github-actions-secrets", "secret-provider-quarantine", "security-quality-regressions", "secrets-config", "consumer-agent-kit-dependency", "ci-test-perf", "session-memory-hardcut", "worktree-main-ownership", "sast"];
-export declare const AFFECTED_SAFE_AUDIT_KIND_IDS: readonly ["blueprint-readme-drift", "blueprint-lifecycle", "bucket-boundary", "skill-sizes", "broken-refs", "no-dev-vars", "absolute-path-policy", "secret-provider-quarantine", "secrets-config", "docs-frontmatter", "no-relative-parent-imports", "no-link-protocol", "no-first-party-mjs", "no-math-random"];
+export declare const AUDIT_KIND_IDS: readonly ["test-smells", "tph-e2e", ...("absolute-path-policy" | "agent-cost" | "agents" | "ai-contracts" | "architecture-drift" | "atomic-state-writes" | "blueprint-db-consistency" | "blueprint-lifecycle" | "blueprint-pr-coverage" | "blueprint-readme-drift" | "blueprint-trust" | "broken-refs" | "bucket-boundary" | "bundle-budget" | "catalog-drift" | "ci-test-perf" | "cloudflare-deploy-contract" | "command-surface" | "commit-message" | "compile-drift" | "consumer-agent-kit-dependency" | "cross-repo-correlation" | "docs-frontmatter" | "github-actions-secrets" | "gitignore-agent-surfaces" | "guardrails" | "harness-overlay-evidence" | "harness-surfaces" | "hook-surface" | "hook-vendor-drift" | "legacy-workflow-identity" | "memory-rotation" | "memory-unified" | "mutation" | "no-dev-vars" | "no-first-party-mjs" | "no-legacy-cli-bin" | "no-link-protocol" | "no-math-random" | "no-relative-package-scripts" | "no-relative-parent-imports" | "open-source-licenses" | "outside-review-runtime-ownership" | "package-surface" | "quality" | "reference-parity-matrix" | "roadmap-links" | "rules" | "sast" | "secret-provider-quarantine" | "secrets-config" | "secrets-policy" | "security-quality-regressions" | "session-memory-hardcut" | "skill-sizes" | "skills" | "supported-agent-clis" | "tech-debt" | "tech-debt-cadence" | "test-isolation" | "test-scan-perf" | "toolchain-isolation" | "vision" | "weakness-mining" | "worktree-main-ownership")[]];
+export declare const MCP_AUDIT_KIND_IDS: readonly ["test-smells", "tph-e2e", "agents", "catalog-drift", "package-surface", "reference-parity-matrix", "docs-frontmatter", "blueprint-readme-drift", "blueprint-pr-coverage", "blueprint-lifecycle", "blueprint-trust", "architecture-drift", "cloudflare-deploy-contract", "absolute-path-policy", "no-first-party-mjs", "no-math-random", "roadmap-links", "bundle-budget", "commit-message", "tech-debt", "supported-agent-clis", "hook-surface", "harness-surfaces", "weakness-mining", "harness-overlay-evidence", "ai-contracts", "atomic-state-writes", "no-relative-package-scripts", "toolchain-isolation", "open-source-licenses", "secrets-policy", "no-dev-vars", "github-actions-secrets", "secret-provider-quarantine", "security-quality-regressions", "secrets-config", "consumer-agent-kit-dependency", "ci-test-perf", "test-scan-perf", "session-memory-hardcut", "worktree-main-ownership", "sast"];
+export declare const AFFECTED_SAFE_AUDIT_KIND_IDS: readonly ["blueprint-readme-drift", "blueprint-lifecycle", "bucket-boundary", "skill-sizes", "broken-refs", "no-dev-vars", "absolute-path-policy", "secret-provider-quarantine", "secrets-config", "docs-frontmatter", "no-relative-parent-imports", "no-link-protocol", "no-first-party-mjs", "no-math-random", "test-scan-perf"];
 export type AuditKindId = (typeof AUDIT_KIND_IDS)[number];
 export type RepoAuditKindId = (typeof REPO_AUDIT_KIND_IDS)[number];
 export type MCPAuditKindId = (typeof MCP_AUDIT_KIND_IDS)[number];

package/dist/esm/audit/registry.js

@@ -16,6 +16,7 @@ const affectedSafeKinds = [
     "no-link-protocol",
     "no-first-party-mjs",
     "no-math-random",
+    "test-scan-perf",
 ];
 const mcpKindIds = [
     "test-smells",
@@ -56,6 +57,7 @@ const mcpKindIds = [
     "secrets-config",
     "consumer-agent-kit-dependency",
     "ci-test-perf",
+    "test-scan-perf",
     "session-memory-hardcut",
     "worktree-main-ownership",
     "sast",
@@ -130,6 +132,7 @@ const repoKinds = [
     "secrets-config",
     "consumer-agent-kit-dependency",
     "ci-test-perf",
+    "test-scan-perf",
     "worktree-main-ownership",
     "sast",
     "harness-surfaces",

package/dist/esm/audit/roadmap-links.js

@@ -58,7 +58,13 @@ export function auditRoadmapLinks(rootDirectory = process.cwd(), options = {}) {
                 message: "Parent-roadmap execution-wave maps may list local child blueprints only; move cross-repo references to Cross-Plan References and use GitHub links there",
             });
         }
+        // Archived parent-roadmaps are non-executable program records. They may
+        // document completed children without a live execution-wave map or local
+        // children still declaring parent_roadmap. Do not fail CI on that residue.
         if (waveMapChildren.size === 0 && localChildren.length === 0) {
+            if (roadmap.status === "archived") {
+                continue;
+            }
             violations.push({
                 file: roadmap.file,
                 message: "Roadmap declares no children in its wave map",

package/dist/esm/audit/test-scan-perf.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Guardrail: keep tests from silently growing multi-second / multi-ten-second
+ * full-repo filesystem scans, and from "fixing" that cost with elevated
+ * per-test timeouts.
+ *
+ * The private-UI cutover anti-regression suite originally walked the monorepo
+ * with readdirSync/statSync/readFileSync and needed a 30s timeout. Prefer
+ * `git grep` (tracked files) or a bounded fixture tree instead.
+ *
+ * Opt-out: `// test-scan-perf-allow` on the same line or previous line as the
+ * walk/timeout site, or `// test-scan-perf-allow-file` anywhere in the file.
+ */
+import type { RepoAuditResult, RepoAuditViolation } from "./repo-guardrails.js";
+export declare function isTestScanPerfTargetPath(relativePath: string): boolean;
+export declare function findTestScanPerfViolationsInText(relativePath: string, text: string): RepoAuditViolation[];
+export declare function auditTestScanPerf(rootDirectory?: string, options?: {
+    affectedFiles?: readonly string[];
+}): RepoAuditResult;

package/dist/esm/audit/test-scan-perf.js

@@ -0,0 +1,275 @@
+/**
+ * Guardrail: keep tests from silently growing multi-second / multi-ten-second
+ * full-repo filesystem scans, and from "fixing" that cost with elevated
+ * per-test timeouts.
+ *
+ * The private-UI cutover anti-regression suite originally walked the monorepo
+ * with readdirSync/statSync/readFileSync and needed a 30s timeout. Prefer
+ * `git grep` (tracked files) or a bounded fixture tree instead.
+ *
+ * Opt-out: `// test-scan-perf-allow` on the same line or previous line as the
+ * walk/timeout site, or `// test-scan-perf-allow-file` anywhere in the file.
+ */
+import { execFileSync } from "node:child_process";
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { join, relative } from "node:path";
+const TITLE = "test-scan-perf";
+const TEST_FILE_PATTERN = /\.(?:test|spec)\.[cm]?[jt]sx?$/u;
+const E2E_FILE_PATTERN = /\.e2e\./u;
+const SKIP_DIRS = new Set([
+    ".git",
+    "node_modules",
+    "dist",
+    "coverage",
+    ".turbo",
+    ".webpresso",
+    ".agent",
+    ".agents",
+    ".claude",
+    ".codex",
+    ".cursor",
+    ".opencode",
+    ".omx",
+    "playwright-report",
+    "test-results",
+    "logs",
+    "_worktrees",
+]);
+const ALLOW_LINE_PATTERN = /test-scan-perf-allow(?:-timeout|-walk)?\b/iu;
+const ALLOW_FILE_PATTERN = /test-scan-perf-allow-file\b/iu;
+/** Recursive walk helper that also reads file contents (content scan). */
+const RECURSIVE_WALK_HINT = /(?:function\s+walk\b|const\s+walk\s*=|let\s+walk\s*=|var\s+walk\s*=)/u;
+const RECURSIVE_CALL_HINT = /\bwalk\s*\(\s*(?:full|dir|current|directory|entryPath|sub|next)\b/u;
+const READDIR_HINT = /\breaddirSync\b/u;
+const READ_FILE_HINT = /\breadFileSync\b/u;
+/**
+ * True when the file acquires the *workspace* root (not a mkdtemp fixture)
+ * and feeds that root into a recursive walk / file-finder helper.
+ */
+function hasWorkspaceRootScanStart(code) {
+    const assignsWorkspaceRoot = /\bfindRepoRoot\s*\(/u.test(code) ||
+        /(?:const|let|var)\s+(?:repoRoot|REPO_ROOT)\s*=\s*process\.cwd\s*\(/u.test(code) ||
+        /(?:const|let|var)\s+root\s*=\s*(?:findRepoRoot\s*\(|process\.cwd\s*\()/u.test(code);
+    if (!assignsWorkspaceRoot)
+        return false;
+    // Direct walk(repoRoot|REPO_ROOT) or helper(repoRoot|REPO_ROOT) that owns the walk.
+    if (/\b(?:walk|findFiles|list\w*|scan\w*|collect\w*)\s*\(\s*(?:repoRoot|REPO_ROOT)\b/u.test(code)) {
+        return true;
+    }
+    // walk(root) only when `root` itself is the workspace root assignment.
+    if (/(?:const|let|var)\s+root\s*=\s*(?:findRepoRoot\s*\(|process\.cwd\s*\()/u.test(code) &&
+        /\b(?:walk|findFiles|list\w*|scan\w*|collect\w*)\s*\(\s*root\b/u.test(code)) {
+        return true;
+    }
+    return false;
+}
+const MIN_ELEVATED_TIMEOUT_MS = 30_000;
+export function isTestScanPerfTargetPath(relativePath) {
+    const normalized = relativePath.replaceAll("\\", "/");
+    if (!TEST_FILE_PATTERN.test(normalized))
+        return false;
+    if (E2E_FILE_PATTERN.test(normalized))
+        return false;
+    // Audit self-tests and fixtures intentionally include positive examples.
+    if (normalized.includes("/__fixtures__/"))
+        return false;
+    if (normalized.endsWith("/test-scan-perf.test.ts"))
+        return false;
+    return true;
+}
+function stripComments(source) {
+    return source.replace(/\/\*[\s\S]*?\*\//gu, "").replace(/(^|[^:])\/\/[^\n]*/gu, "$1");
+}
+function stripAllowedLines(source) {
+    const lines = source.split(/\r?\n/u);
+    return lines.map((line, index) => (lineAllowed(lines, index) ? "" : line)).join("\n");
+}
+function lineAllowed(lines, index) {
+    const current = lines[index] ?? "";
+    if (ALLOW_LINE_PATTERN.test(current))
+        return true;
+    if (index > 0 && ALLOW_LINE_PATTERN.test(lines[index - 1] ?? ""))
+        return true;
+    return false;
+}
+function hasRepoRootContentWalk(code) {
+    if (!READDIR_HINT.test(code) || !READ_FILE_HINT.test(code))
+        return false;
+    if (!RECURSIVE_WALK_HINT.test(code))
+        return false;
+    const recursiveCall = RECURSIVE_CALL_HINT.test(code) || /\bwalk\s*\(\s*join\s*\(/u.test(code);
+    if (!recursiveCall)
+        return false;
+    return hasWorkspaceRootScanStart(code);
+}
+function parseTimeoutMs(raw) {
+    const digits = raw.replaceAll("_", "");
+    if (!/^\d+$/u.test(digits))
+        return null;
+    const value = Number(digits);
+    return Number.isFinite(value) ? value : null;
+}
+function findElevatedTimeoutLines(text) {
+    const hits = [];
+    const lines = text.split(/\r?\n/u);
+    // Line-oriented: `{ timeout: 30000 }`, trailing `, 30000)`, or a multi-line
+    // `it(\n  "…",\n  () => {…},\n  30_000,\n)` form.
+    for (let index = 0; index < lines.length; index += 1) {
+        const line = lines[index] ?? "";
+        if (lineAllowed(lines, index))
+            continue;
+        const optionMatch = line.match(/timeout\s*:\s*([0-9_]+)/u);
+        if (optionMatch?.[1]) {
+            const ms = parseTimeoutMs(optionMatch[1]);
+            if (ms !== null && ms >= MIN_ELEVATED_TIMEOUT_MS) {
+                hits.push({ line: index + 1, ms });
+                continue;
+            }
+        }
+        // Same-line trailing timeout: `}, 30_000)` / `, 30000)`
+        const trailingMatch = line.match(/,\s*([0-9_]+)\s*\)\s*;?\s*$/u);
+        // Own-line timeout before closing paren: `    30_000,` / `    30000`
+        const ownLineMatch = line.match(/^\s*([0-9_]+)\s*,?\s*$/u);
+        const raw = trailingMatch?.[1] ?? ownLineMatch?.[1];
+        if (!raw)
+            continue;
+        const ms = parseTimeoutMs(raw);
+        const windowStart = Math.max(0, index - 16);
+        const windowEnd = Math.min(lines.length, index + 3);
+        const window = lines.slice(windowStart, windowEnd).join("\n");
+        if (ms !== null &&
+            ms >= MIN_ELEVATED_TIMEOUT_MS &&
+            /\b(?:it|test)(?:\.only|\.each)?\s*\(/u.test(window)) {
+            hits.push({ line: index + 1, ms });
+        }
+    }
+    // Deduplicate by line.
+    const seen = new Set();
+    return hits.filter((hit) => {
+        if (seen.has(hit.line))
+            return false;
+        seen.add(hit.line);
+        return true;
+    });
+}
+export function findTestScanPerfViolationsInText(relativePath, text) {
+    if (!isTestScanPerfTargetPath(relativePath))
+        return [];
+    if (ALLOW_FILE_PATTERN.test(text))
+        return [];
+    const violations = [];
+    const code = stripComments(stripAllowedLines(text));
+    const hasSlowWalk = hasRepoRootContentWalk(code);
+    if (hasSlowWalk) {
+        violations.push({
+            file: relativePath,
+            ruleId: "repo-root-recursive-content-scan",
+            severity: "error",
+            message: `${relativePath}: recursive readdir/readFile content scan from the repo root. ` +
+                `Use \`git grep -l\` (tracked files) or a bounded fixture tree instead of walking ` +
+                `the whole workspace. Opt out with \`// test-scan-perf-allow\` on the walk site ` +
+                `or \`// test-scan-perf-allow-file\` once with justification.`,
+        });
+    }
+    // Elevated timeouts are only flagged when co-located with a repo-root FS walk —
+    // that is the "band-aid for a slow scan" pattern. Legitimate long e2e/subprocess
+    // timeouts without a root walk are out of scope.
+    if (hasSlowWalk) {
+        for (const hit of findElevatedTimeoutLines(text)) {
+            violations.push({
+                file: relativePath,
+                line: hit.line,
+                ruleId: "timeout-band-aid-for-scan",
+                severity: "error",
+                message: `${relativePath}:${hit.line}: per-test timeout ${hit.ms}ms co-located with a ` +
+                    `repo-root recursive FS scan. Fix the scan (git-grep / bounded tree) instead of ` +
+                    `raising the timeout. Opt out with \`// test-scan-perf-allow\` on that line.`,
+            });
+        }
+    }
+    return violations;
+}
+function listTestFilesViaGit(root) {
+    try {
+        const stdout = execFileSync("git", ["-C", root, "ls-files", "-z"], {
+            encoding: "utf8",
+            maxBuffer: 16 * 1024 * 1024,
+        });
+        return stdout
+            .split("\0")
+            .map((entry) => entry.trim())
+            .filter(Boolean)
+            .filter((entry) => isTestScanPerfTargetPath(entry));
+    }
+    catch {
+        return null;
+    }
+}
+function walkTestFiles(dir, root, out) {
+    let entries;
+    try {
+        entries = readdirSync(dir);
+    }
+    catch {
+        return;
+    }
+    for (const entry of entries) {
+        if (SKIP_DIRS.has(entry))
+            continue;
+        const full = join(dir, entry);
+        let st;
+        try {
+            st = statSync(full);
+        }
+        catch {
+            continue;
+        }
+        if (st.isDirectory()) {
+            walkTestFiles(full, root, out);
+            continue;
+        }
+        if (!st.isFile())
+            continue;
+        const rel = relative(root, full).replaceAll("\\", "/");
+        if (isTestScanPerfTargetPath(rel))
+            out.push(rel);
+    }
+}
+function listTestFiles(root, affectedFiles) {
+    if (affectedFiles !== undefined) {
+        return affectedFiles
+            .map((file) => file.replaceAll("\\", "/"))
+            .filter((file) => isTestScanPerfTargetPath(file));
+    }
+    const fromGit = listTestFilesViaGit(root);
+    if (fromGit)
+        return fromGit;
+    const out = [];
+    walkTestFiles(root, root, out);
+    return out;
+}
+export function auditTestScanPerf(rootDirectory = process.cwd(), options = {}) {
+    const root = rootDirectory;
+    if (!existsSync(root)) {
+        return { ok: true, title: TITLE, checked: 0, violations: [] };
+    }
+    const files = listTestFiles(root, options.affectedFiles);
+    const violations = [];
+    for (const rel of files) {
+        const full = join(root, rel);
+        let text;
+        try {
+            text = readFileSync(full, "utf8");
+        }
+        catch {
+            continue;
+        }
+        violations.push(...findTestScanPerfViolationsInText(rel, text));
+    }
+    return {
+        ok: violations.length === 0,
+        title: TITLE,
+        checked: files.length,
+        violations,
+    };
+}

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/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[];