@deftai/directive-core 0.79.3 → 0.79.4

package/dist/coverage-hotspots/evaluate.d.ts

@@ -0,0 +1,49 @@
+import { type CoverageMetric, type CoverageTotals, summarizeCoverageFinal } from "../vitest-runner/coverage-debt.js";
+import { type CoverageThresholds } from "./thresholds.js";
+export declare const DEFAULT_MIN_HEADROOM_PP = 0.3;
+export declare const DEFAULT_LOWEST_MODULE_LIMIT = 10;
+export interface ModuleCoverage {
+    readonly path: string;
+    readonly lines: number;
+    readonly functions: number;
+    readonly branches: number;
+    readonly statements: number;
+}
+export interface UncoveredBranchSample {
+    readonly path: string;
+    readonly line: number;
+    readonly branchId: string;
+    readonly type: string;
+}
+export interface CoverageHotspotsReport {
+    readonly ok: boolean;
+    readonly global: CoverageTotals;
+    readonly thresholds: CoverageThresholds;
+    readonly headroomPp: Record<CoverageMetric, number>;
+    readonly minHeadroomPp: number;
+    readonly failReasons: readonly string[];
+    readonly lowestModules: readonly ModuleCoverage[];
+    readonly uncoveredBranches: readonly UncoveredBranchSample[];
+    readonly pathFilter: readonly string[];
+    readonly coverageReportPath: string;
+}
+export interface CoverageHotspotsResult {
+    readonly exitCode: 0 | 1 | 2;
+    readonly report: CoverageHotspotsReport | null;
+    readonly message: string;
+}
+export interface CoverageHotspotsOptions {
+    readonly projectRoot: string;
+    readonly coverageDir?: string;
+    readonly minHeadroomPp?: number;
+    readonly baseRef?: string | null;
+    readonly pathFilter?: readonly string[] | null;
+    readonly useDiffPaths?: boolean;
+    readonly lowestModuleLimit?: number;
+}
+export declare function evaluateCoverageHotspots(options: CoverageHotspotsOptions): CoverageHotspotsResult;
+export declare function formatJsonReport(report: CoverageHotspotsReport): string;
+export declare function formatTextReport(report: CoverageHotspotsReport, failed: boolean): string;
+/** Re-export for tests that build synthetic reports. */
+export { summarizeCoverageFinal };
+//# sourceMappingURL=evaluate.d.ts.map

package/dist/coverage-hotspots/evaluate.js

@@ -0,0 +1,262 @@
+import * as childProcess from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { join, relative } from "node:path";
+import { summarizeCoverageFinal, } from "../vitest-runner/coverage-debt.js";
+import { readProjectCoverageThresholds } from "./thresholds.js";
+export const DEFAULT_MIN_HEADROOM_PP = 0.3;
+export const DEFAULT_LOWEST_MODULE_LIMIT = 10;
+class GitCommandError extends Error {
+}
+function runGit(args, projectRoot) {
+    try {
+        return childProcess.execFileSync("git", args, {
+            cwd: projectRoot,
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+    }
+    catch (err) {
+        const e = err;
+        const stderr = String(e.stderr ?? e.message ?? err).trim();
+        throw new GitCommandError(`coverage-hotspots: git ${args.join(" ")} failed: ${stderr}`);
+    }
+}
+function splitLines(stdout) {
+    return stdout
+        .split("\n")
+        .map((line) => line.trim())
+        .filter((line) => line.length > 0);
+}
+function resolveBaseRef(projectRoot, override) {
+    if (override && override.trim().length > 0)
+        return override.trim();
+    for (const candidate of ["origin/master", "origin/main", "master", "main", "HEAD~1"]) {
+        try {
+            runGit(["rev-parse", "--verify", "-q", candidate], projectRoot);
+            return candidate;
+        }
+        catch {
+            // try next
+        }
+    }
+    return "HEAD~1";
+}
+function diffPaths(projectRoot, baseRef) {
+    return splitLines(runGit(["diff", "--name-only", baseRef, "HEAD"], projectRoot));
+}
+function pct(covered, total) {
+    return total === 0 ? 100 : (covered / total) * 100;
+}
+function summarizeFileCoverage(relPath, file) {
+    let stmtTotal = 0;
+    let stmtCovered = 0;
+    let fnTotal = 0;
+    let fnCovered = 0;
+    let branchTotal = 0;
+    let branchCovered = 0;
+    if (file.s) {
+        for (const hits of Object.values(file.s)) {
+            stmtTotal += 1;
+            if (hits > 0)
+                stmtCovered += 1;
+        }
+    }
+    if (file.f) {
+        for (const hits of Object.values(file.f)) {
+            fnTotal += 1;
+            if (hits > 0)
+                fnCovered += 1;
+        }
+    }
+    if (file.b) {
+        for (const paths of Object.values(file.b)) {
+            for (const hits of paths) {
+                branchTotal += 1;
+                if (hits > 0)
+                    branchCovered += 1;
+            }
+        }
+    }
+    const statements = pct(stmtCovered, stmtTotal);
+    const functions = pct(fnCovered, fnTotal);
+    const branches = pct(branchCovered, branchTotal);
+    return {
+        path: relPath,
+        statements,
+        functions,
+        branches,
+        lines: statements,
+    };
+}
+function normalizeReportPath(projectRoot, rawKey, file) {
+    if (file.path && file.path.length > 0) {
+        const abs = file.path;
+        if (abs.startsWith(projectRoot)) {
+            return relative(projectRoot, abs).replace(/\\/g, "/");
+        }
+        return abs.replace(/\\/g, "/");
+    }
+    return rawKey.replace(/\\/g, "/");
+}
+function pathMatchesFilter(relPath, filters) {
+    if (filters.length === 0)
+        return true;
+    // Substring only — do not feed CLI/argv filters into RegExp (CodeQL js/regex-injection).
+    return filters.some((pattern) => relPath.includes(pattern));
+}
+function collectUncoveredBranches(relPath, file) {
+    if (!file.b)
+        return [];
+    const samples = [];
+    for (const [branchId, hits] of Object.entries(file.b)) {
+        if (!hits.some((count) => count === 0))
+            continue;
+        const meta = file.branchMap?.[branchId];
+        const line = meta?.line ?? meta?.loc?.start?.line ?? 0;
+        samples.push({
+            path: relPath,
+            line,
+            branchId,
+            type: meta?.type ?? "branch",
+        });
+    }
+    return samples;
+}
+function computeHeadroom(totals, thresholds) {
+    return {
+        lines: totals.lines - thresholds.lines,
+        functions: totals.functions - thresholds.functions,
+        branches: totals.branches - thresholds.branches,
+        statements: totals.statements - thresholds.statements,
+    };
+}
+function evaluatePassFail(totals, thresholds, headroomPp, minHeadroomPp) {
+    const reasons = [];
+    if (totals.branches + 1e-9 < thresholds.branches) {
+        reasons.push(`branches ${totals.branches.toFixed(2)}% below project floor ${thresholds.branches}%`);
+    }
+    if (headroomPp.branches + 1e-9 < minHeadroomPp) {
+        reasons.push(`branch headroom ${headroomPp.branches.toFixed(2)}pp below minimum ${minHeadroomPp}pp`);
+    }
+    return reasons;
+}
+function configError(message) {
+    return { exitCode: 2, report: null, message };
+}
+export function evaluateCoverageHotspots(options) {
+    const projectRoot = options.projectRoot;
+    const coverageDir = options.coverageDir ?? join(projectRoot, "coverage");
+    const minHeadroomPp = options.minHeadroomPp ?? DEFAULT_MIN_HEADROOM_PP;
+    const lowestModuleLimit = options.lowestModuleLimit ?? DEFAULT_LOWEST_MODULE_LIMIT;
+    const useDiffPaths = options.useDiffPaths ?? true;
+    const reportPath = join(coverageDir, "coverage-final.json");
+    if (!existsSync(reportPath)) {
+        return configError(`coverage-hotspots: coverage report missing at ${reportPath}\n` +
+            "  Run tests with coverage first (e.g. vitest run --coverage or task test:coverage).");
+    }
+    let rawReport;
+    try {
+        rawReport = JSON.parse(readFileSync(reportPath, "utf8"));
+    }
+    catch (err) {
+        return configError(`coverage-hotspots: unreadable coverage report at ${reportPath}: ${String(err.message)}`);
+    }
+    const totals = summarizeCoverageFinal(rawReport);
+    const thresholds = readProjectCoverageThresholds(projectRoot);
+    const headroomPp = computeHeadroom(totals, thresholds);
+    let pathFilter = options.pathFilter ?? [];
+    if (pathFilter.length === 0 && useDiffPaths) {
+        try {
+            const baseRef = resolveBaseRef(projectRoot, options.baseRef);
+            pathFilter = diffPaths(projectRoot, baseRef);
+        }
+        catch (err) {
+            const message = err instanceof GitCommandError
+                ? `${err.message}\n  Recovery: pass explicit --path filters or run inside a git repo.`
+                : `coverage-hotspots: ${String(err.message)}`;
+            return configError(message);
+        }
+    }
+    const modules = [];
+    const uncoveredBranches = [];
+    for (const [rawKey, file] of Object.entries(rawReport)) {
+        const relPath = normalizeReportPath(projectRoot, rawKey, file);
+        modules.push(summarizeFileCoverage(relPath, file));
+        if (pathMatchesFilter(relPath, pathFilter)) {
+            uncoveredBranches.push(...collectUncoveredBranches(relPath, file));
+        }
+    }
+    modules.sort((a, b) => a.branches - b.branches || a.path.localeCompare(b.path));
+    const lowestModules = modules.slice(0, lowestModuleLimit);
+    uncoveredBranches.sort((a, b) => a.path.localeCompare(b.path) || a.line - b.line || a.branchId.localeCompare(b.branchId));
+    const failReasons = evaluatePassFail(totals, thresholds, headroomPp, minHeadroomPp);
+    const report = {
+        ok: failReasons.length === 0,
+        global: totals,
+        thresholds,
+        headroomPp,
+        minHeadroomPp,
+        failReasons,
+        lowestModules,
+        uncoveredBranches,
+        pathFilter,
+        coverageReportPath: reportPath,
+    };
+    if (failReasons.length > 0) {
+        return {
+            exitCode: 1,
+            report,
+            message: formatTextReport(report, true),
+        };
+    }
+    return {
+        exitCode: 0,
+        report,
+        message: formatTextReport(report, false),
+    };
+}
+export function formatJsonReport(report) {
+    return `${JSON.stringify(report, null, 2)}\n`;
+}
+function metricLine(label, value, threshold, headroom) {
+    return `  ${label.padEnd(12)} ${value.toFixed(2)}%  (floor ${threshold}% | headroom ${headroom.toFixed(2)}pp)`;
+}
+export function formatTextReport(report, failed) {
+    const lines = [];
+    lines.push(failed ? "coverage-hotspots: FAIL" : "coverage-hotspots: OK");
+    lines.push(`report: ${report.coverageReportPath}`);
+    lines.push("global:");
+    lines.push(metricLine("branches", report.global.branches, report.thresholds.branches, report.headroomPp.branches));
+    lines.push(metricLine("lines", report.global.lines, report.thresholds.lines, report.headroomPp.lines));
+    lines.push(metricLine("functions", report.global.functions, report.thresholds.functions, report.headroomPp.functions));
+    lines.push(metricLine("statements", report.global.statements, report.thresholds.statements, report.headroomPp.statements));
+    lines.push(`min branch headroom: ${report.minHeadroomPp}pp`);
+    if (report.pathFilter.length > 0) {
+        lines.push(`path filter (${report.pathFilter.length}): ${report.pathFilter.slice(0, 8).join(", ")}${report.pathFilter.length > 8 ? ", ..." : ""}`);
+    }
+    if (report.failReasons.length > 0) {
+        lines.push("fail reasons:");
+        for (const reason of report.failReasons) {
+            lines.push(`  - ${reason}`);
+        }
+    }
+    if (report.lowestModules.length > 0) {
+        lines.push("lowest modules (branches):");
+        for (const mod of report.lowestModules.slice(0, 5)) {
+            lines.push(`  - ${mod.path}: branches ${mod.branches.toFixed(2)}%`);
+        }
+    }
+    if (report.uncoveredBranches.length > 0) {
+        lines.push("uncovered branch samples:");
+        for (const sample of report.uncoveredBranches.slice(0, 12)) {
+            lines.push(`  - ${sample.path}:${sample.line} (${sample.type} #${sample.branchId})`);
+        }
+        if (report.uncoveredBranches.length > 12) {
+            lines.push(`  ... ${report.uncoveredBranches.length - 12} more`);
+        }
+    }
+    return `${lines.join("\n")}\n`;
+}
+/** Re-export for tests that build synthetic reports. */
+export { summarizeCoverageFinal };
+//# sourceMappingURL=evaluate.js.map

package/dist/coverage-hotspots/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./evaluate.js";
+export * from "./thresholds.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/coverage-hotspots/index.js

@@ -0,0 +1,3 @@
+export * from "./evaluate.js";
+export * from "./thresholds.js";
+//# sourceMappingURL=index.js.map

package/dist/coverage-hotspots/thresholds.d.ts

@@ -0,0 +1,5 @@
+import { type CoverageMetric } from "../vitest-runner/coverage-debt.js";
+export type CoverageThresholds = Record<CoverageMetric, number>;
+/** Best-effort read of vitest coverage thresholds; falls back to framework 85% defaults. */
+export declare function readProjectCoverageThresholds(projectRoot: string): CoverageThresholds;
+//# sourceMappingURL=thresholds.d.ts.map

package/dist/coverage-hotspots/thresholds.js

@@ -0,0 +1,48 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { COVERAGE_GOAL } from "../vitest-runner/coverage-debt.js";
+const VITEST_CONFIG_CANDIDATES = [
+    "vitest.config.ts",
+    "vitest.config.mts",
+    "vitest.config.js",
+    "vitest.config.cjs",
+    "vitest.config.mjs",
+];
+const METRIC_PATTERN = /(?:^|[\n\r{,])\s*(branches|lines|functions|statements)\s*:\s*(\d+(?:\.\d+)?)/g;
+function parseMetricBlock(text, anchor) {
+    const match = anchor.exec(text);
+    if (match?.index === undefined)
+        return {};
+    const slice = text.slice(match.index, match.index + 800);
+    const out = {};
+    for (const metricMatch of slice.matchAll(METRIC_PATTERN)) {
+        const metric = metricMatch[1];
+        const value = metricMatch[2];
+        if (metric === undefined || value === undefined)
+            continue;
+        out[metric] = Number.parseFloat(value);
+    }
+    return out;
+}
+/** Best-effort read of vitest coverage thresholds; falls back to framework 85% defaults. */
+export function readProjectCoverageThresholds(projectRoot) {
+    for (const name of VITEST_CONFIG_CANDIDATES) {
+        const path = join(projectRoot, name);
+        if (!existsSync(path))
+            continue;
+        const text = readFileSync(path, "utf8");
+        const fromCoverageThresholds = parseMetricBlock(text, /coverageThresholds\s*=\s*\{/);
+        const fromNested = parseMetricBlock(text, /thresholds\s*:\s*\{/);
+        const merged = { ...fromNested, ...fromCoverageThresholds };
+        if (Object.keys(merged).length > 0) {
+            return {
+                lines: merged.lines ?? COVERAGE_GOAL.lines,
+                functions: merged.functions ?? COVERAGE_GOAL.functions,
+                branches: merged.branches ?? COVERAGE_GOAL.branches,
+                statements: merged.statements ?? COVERAGE_GOAL.statements,
+            };
+        }
+    }
+    return { ...COVERAGE_GOAL };
+}
+//# sourceMappingURL=thresholds.js.map

package/dist/hooks/dispatcher.d.ts

@@ -17,11 +17,17 @@ export interface HookDecision {
     readonly message: string;
     readonly scopePath: string | null;
 }
+/** Stdin parse metadata from hook-dispatch; absent when callers supply payload directly. */
+export interface HookPayloadContext {
+    readonly stdinEmpty?: boolean;
+    readonly parseFailed?: boolean;
+}
 export interface HookDispatchInput {
     readonly host: HookHost;
     readonly event: HookEvent;
     readonly projectRoot: string;
     readonly payload: unknown;
+    readonly payloadContext?: HookPayloadContext;
 }
 export interface HookPolicySeams {
     readonly inspectRitual?: (projectRoot: string) => VerifyResult;
@@ -32,6 +38,7 @@ export interface HookPolicySeams {
         stderr: string;
     };
 }
+export declare function hookPayloadTopLevelKeys(payload: unknown): string[];
 export declare function hookToolName(payload: unknown, host?: HookHost): string | null;
 /**
  * Best-effort write-target path from host PreToolUse payloads (#2625).

package/dist/hooks/dispatcher.js

@@ -29,7 +29,12 @@ function fieldString(input, key) {
     return null;
 }
 function toolInputRecord(payload) {
-    return record(payload.tool_input) ?? record(payload.toolInput) ?? record(payload.input);
+    const toolCall = record(payload.tool_call) ?? record(payload.toolCall);
+    return (record(payload.tool_input) ??
+        record(payload.toolInput) ??
+        record(payload.input) ??
+        record(payload.arguments) ??
+        (toolCall !== null ? record(toolCall.arguments) : null));
 }
 /**
  * Cursor preToolUse payloads sometimes omit `tool_name` even when the hook matcher
@@ -65,19 +70,50 @@ function inferCursorDirectWriteToolName(payload) {
         return "Write";
     return null;
 }
+export function hookPayloadTopLevelKeys(payload) {
+    const input = record(payload);
+    if (input === null)
+        return [];
+    return Object.keys(input).sort();
+}
 export function hookToolName(payload, host) {
     const input = record(payload);
     if (input === null)
         return null;
-    const direct = fieldString(input, "tool_name") ?? fieldString(input, "toolName") ?? fieldString(input, "tool");
+    const toolObject = record(input.tool);
+    const toolCall = record(input.tool_call) ?? record(input.toolCall);
+    // OpenAI-style nestings are host-agnostic; checked before Cursor-only inference.
+    const direct = fieldString(input, "tool_name") ??
+        fieldString(input, "toolName") ??
+        fieldString(input, "tool") ??
+        (toolObject !== null ? fieldString(toolObject, "name") : null) ??
+        (toolCall !== null ? fieldString(toolCall, "name") : null);
     if (direct !== null)
         return direct;
     if (host === "cursor")
         return inferCursorDirectWriteToolName(input);
     return null;
 }
-function missingToolNameMessage(host) {
+function missingToolNameMessage(input) {
+    const { host, payload, context } = input;
     if (host === "cursor") {
+        if (context?.stdinEmpty) {
+            return ("Directive denied this Cursor preToolUse event because the host sent an empty payload " +
+                "(stdin was empty — not a session ritual or scope failure). " +
+                "If write tools should pass, update Directive or report the payload shape from Cursor.");
+        }
+        if (context?.parseFailed) {
+            return ("Directive denied this Cursor preToolUse event because the host payload was not valid JSON " +
+                "(host-integration mismatch — not a session ritual or scope failure). " +
+                "If write tools should pass, update Directive or report the payload shape from Cursor.");
+        }
+        const keys = hookPayloadTopLevelKeys(payload);
+        if (keys.length > 0) {
+            return ("Directive denied this Cursor preToolUse event because the host payload omitted a " +
+                "recognizable tool name (host-integration mismatch — not a session ritual or scope failure). " +
+                `Top-level payload keys: ${keys.join(", ")}. ` +
+                "If write tools should pass, update Directive or report the payload shape from Cursor.");
+        }
         return ("Directive denied this Cursor preToolUse event because the host payload omitted a " +
             "recognizable tool name (host-integration mismatch — not a session ritual or scope failure). " +
             "If write tools should pass, update Directive or report the payload shape from Cursor.");
@@ -189,7 +225,11 @@ export function decideHook(input, seams = {}) {
     }
     const toolName = hookToolName(input.payload, input.host);
     if (toolName === null) {
-        return deny(input, "invalid-input", null, missingToolNameMessage(input.host));
+        return deny(input, "invalid-input", null, missingToolNameMessage({
+            host: input.host,
+            payload: input.payload,
+            context: input.payloadContext,
+        }));
     }
     if (!isDirectWriteTool(toolName)) {
         return {

package/dist/index.d.ts

@@ -13,6 +13,7 @@ export * as branch from "./branch/index.js";
 export * as cache from "./cache/index.js";
 export * as capacity from "./capacity/index.js";
 export * as codebase from "./codebase/index.js";
+export * from "./coverage-hotspots/index.js";
 export * as doctor from "./doctor/index.js";
 export * from "./encoding/index.js";
 export * as evalCrud from "./eval/crud-telemetry.js";

package/dist/index.js

@@ -13,6 +13,7 @@ export * as branch from "./branch/index.js";
 export * as cache from "./cache/index.js";
 export * as capacity from "./capacity/index.js";
 export * as codebase from "./codebase/index.js";
+export * from "./coverage-hotspots/index.js";
 export * as doctor from "./doctor/index.js";
 export * from "./encoding/index.js";
 export * as evalCrud from "./eval/crud-telemetry.js";

package/dist/init-deposit/xbrief-projections.d.ts

@@ -5,6 +5,13 @@
  * freshness. A current `.deft/core/VERSION` therefore cannot short-circuit
  * these repairs.
  */
+/** Rewrite legacy vbrief/.eval description paths for xbrief/schemas projection (#2670). */
+export declare function rewriteProjectedSchemaContent(content: string): string;
+/**
+ * Fail closed when a projected xbrief/schemas file still cites vbrief/.eval/.
+ * Upstream vbrief/schemas/ may keep legacy paths; consumer copies must not (#2670).
+ */
+export declare function assertProjectedSchemaDescriptionsRooted(projectDir: string, destinationDir: string): void;
 /**
  * Synchronize framework-owned xBRIEF schemas while preserving unknown consumer
  * files. The obsolete v0.6 root schema is the only destination-only file this

package/dist/init-deposit/xbrief-projections.js

@@ -13,6 +13,10 @@ import { DEV_FALLBACK } from "../platform/constants.js";
 import { MIGRATED_ARTIFACT_DIR } from "../xbrief-migrate/constants.js";
 const OBSOLETE_CORE_SCHEMA = "vbrief-core.schema.json";
 const CURRENT_CORE_SCHEMA = "xbrief-core-0.8.schema.json";
+/** Legacy lifecycle eval prefix in framework vbrief/schemas source copies. */
+const LEGACY_EVAL_PATH_PREFIX = "vbrief/.eval/";
+/** Consumer xbrief/schemas projection must root description paths here (#2670). */
+const XBRIEF_EVAL_PATH_PREFIX = "xbrief/.eval/";
 function normalizeVersion(version) {
     return version.trim().replace(/^v/, "");
 }
@@ -39,6 +43,28 @@ function collectSchemaFiles(root, dir = root, files = []) {
     }
     return files;
 }
+/** Rewrite legacy vbrief/.eval description paths for xbrief/schemas projection (#2670). */
+export function rewriteProjectedSchemaContent(content) {
+    return content.includes(LEGACY_EVAL_PATH_PREFIX)
+        ? content.replaceAll(LEGACY_EVAL_PATH_PREFIX, XBRIEF_EVAL_PATH_PREFIX)
+        : content;
+}
+/**
+ * Fail closed when a projected xbrief/schemas file still cites vbrief/.eval/.
+ * Upstream vbrief/schemas/ may keep legacy paths; consumer copies must not (#2670).
+ */
+export function assertProjectedSchemaDescriptionsRooted(projectDir, destinationDir) {
+    assertProjectionContained(projectDir, destinationDir);
+    if (!isDirectory(destinationDir))
+        return;
+    for (const rel of collectSchemaFiles(destinationDir)) {
+        const full = join(destinationDir, rel);
+        const text = readFileSync(full, "utf8");
+        if (text.includes(LEGACY_EVAL_PATH_PREFIX)) {
+            throw new Error(`projected xbrief schema still cites ${LEGACY_EVAL_PATH_PREFIX}: ${join(MIGRATED_ARTIFACT_DIR, "schemas", rel)}`);
+        }
+    }
+}
 function writeFileIfChanged(projectDir, target, content) {
     assertProjectionContained(projectDir, target);
     const desired = Buffer.isBuffer(content) ? content : Buffer.from(content, "utf8");
@@ -73,7 +99,8 @@ export function syncConsumerXbriefSchemas(projectDir, deftDir) {
             continue;
         const source = join(sourceDir, rel);
         const destination = join(destinationDir, rel);
-        changed = writeFileIfChanged(projectDir, destination, readFileSync(source)) || changed;
+        const projected = rewriteProjectedSchemaContent(readFileSync(source, "utf8"));
+        changed = writeFileIfChanged(projectDir, destination, projected) || changed;
     }
     const obsoleteDestination = join(destinationDir, OBSOLETE_CORE_SCHEMA);
     assertProjectionContained(projectDir, obsoleteDestination);
@@ -81,6 +108,7 @@ export function syncConsumerXbriefSchemas(projectDir, deftDir) {
         rmSync(obsoleteDestination, { force: true });
         changed = true;
     }
+    assertProjectedSchemaDescriptionsRooted(projectDir, destinationDir);
     return changed;
 }
 function syncBareVersionMarkerWithPolicy(projectDir, version, allowRootFallback) {

package/dist/integration-e2e/bootstrap-cache-module.d.ts

@@ -1,5 +1,3 @@
-import type { FetchAllReportImpl } from "../cache/fetch.js";
-import type { CacheModule } from "../triage/bootstrap/types.js";
-/** Adapt TS cache reports to the bootstrap `FetchAllReport` shape. */
-export declare function bootstrapCacheModule(cacheFetchAll: (options: Parameters<typeof import("../cache/fetch.js").cacheFetchAll>[0]) => FetchAllReportImpl): CacheModule;
+/** Re-export bootstrap TS cache adapter (canonical home: triage/bootstrap). */
+export { bootstrapCacheModule } from "../triage/bootstrap/cache-module.js";
 //# sourceMappingURL=bootstrap-cache-module.d.ts.map

package/dist/integration-e2e/bootstrap-cache-module.js

@@ -1,21 +1,3 @@
-/** Adapt TS cache reports to the bootstrap `FetchAllReport` shape. */
-export function bootstrapCacheModule(cacheFetchAll) {
-    return {
-        cacheFetchAll(kwargs) {
-            const report = cacheFetchAll({
-                source: kwargs.source,
-                repo: kwargs.repo,
-                batchSize: kwargs.batchSize,
-                delayMs: kwargs.delayMs,
-                cacheRoot: kwargs.cacheRoot,
-            });
-            return Promise.resolve({
-                succeeded: report.issuesWritten,
-                failed: report.issuesFailed,
-                skipped: report.alreadyFresh,
-                summaryLine: (source, repo) => report.summaryLine(source, repo),
-            });
-        },
-    };
-}
+/** Re-export bootstrap TS cache adapter (canonical home: triage/bootstrap). */
+export { bootstrapCacheModule } from "../triage/bootstrap/cache-module.js";
 //# sourceMappingURL=bootstrap-cache-module.js.map

package/dist/pr-wait-mergeable/cascade.js

@@ -2,6 +2,13 @@ import { classifyMonitorOutcome, parseMonitorPayload } from "./classify.js";
 import { EXIT_CONFIG_ERROR, EXIT_MERGED, EXIT_TIMEOUT_OR_ESCALATION } from "./constants.js";
 import { makeResult } from "./result.js";
 import { runGhMerge, runMonitor, runProtectedCheck } from "./wrappers.js";
+/** Node module-not-found / missing script — not a protected-issue overlap (#2667). */
+function isProtectedCheckConfigFailure(stderr) {
+    const tail = stderr.trim();
+    return (tail.includes("MODULE_NOT_FOUND") ||
+        tail.includes("Cannot find module") ||
+        tail.includes("protected-check script not found:"));
+}
 /** Run protected-check -> wait -> merge cascade (#1369). */
 export function waitMergeableAndMerge(prNumber, repo, options) {
     const protectedFn = options.protectedFn ?? runProtectedCheck;
@@ -17,7 +24,7 @@ export function waitMergeableAndMerge(prNumber, repo, options) {
             stderr: prcStderr,
             protected: [...protectedIssues],
         };
-        if (prcRc === 1) {
+        if (prcRc === 1 && !isProtectedCheckConfigFailure(prcStderr)) {
             return makeResult({
                 prNumber,
                 repo,

package/dist/pr-wait-mergeable/classify.js

@@ -5,7 +5,11 @@ export function classifyMonitorOutcome(monitorReturncode, monitorPayload) {
         return ["clean", EXIT_MERGED];
     }
     if (monitorReturncode === 1) {
-        return ["cap-reached", EXIT_TIMEOUT_OR_ESCALATION];
+        // Bare exit 1 (MODULE_NOT_FOUND / missing script) is not budget exhaustion (#2673).
+        if (monitorPayload.monitor_result === "CAP-REACHED") {
+            return ["cap-reached", EXIT_TIMEOUT_OR_ESCALATION];
+        }
+        return ["config-error", EXIT_CONFIG_ERROR];
     }
     if (monitorReturncode === 2) {
         return ["config-error", EXIT_CONFIG_ERROR];

package/dist/pr-wait-mergeable/wrappers.js

@@ -56,14 +56,17 @@ export function cliScriptPath(name) {
     const candidates = [];
     try {
         const require = createRequire(import.meta.url);
-        const pkgJson = require.resolve("@deftai/directive/package.json");
-        candidates.push(resolve(dirname(pkgJson), "dist", script));
+        // package.json is not an exported subpath under @deftai/directive exports (#2667).
+        const mainEntry = require.resolve("@deftai/directive");
+        candidates.push(resolve(dirname(mainEntry), script));
     }
     catch {
         // Core does not declare a runtime dependency on the CLI package; ignore.
     }
     // Monorepo: packages/core/dist/pr-wait-mergeable -> packages/cli/dist
     candidates.push(resolve(here, "../../../cli/dist", script));
+    // npm hoisted: .../@deftai/directive-core/dist/... -> .../@deftai/directive/dist
+    candidates.push(resolve(here, "../../../directive/dist", script));
     // npm nested: .../directive/node_modules/@deftai/directive-core/dist/... -> .../directive/dist
     candidates.push(resolve(here, "../../../../dist", script));
     for (const candidate of candidates) {
@@ -75,9 +78,13 @@ export function cliScriptPath(name) {
 }
 /** Invoke pr-protected-issues CLI and return (returncode, stdout, stderr). */
 export function runProtectedCheck(prNumber, repo, protectedIssues, options = {}) {
+    const scriptPath = cliScriptPath("pr-protected-issues");
+    if (!existsSync(scriptPath)) {
+        return [2, "", `protected-check script not found: ${scriptPath}`];
+    }
     const node = options.nodeExecutable ?? process.execPath;
     const cmd = [
-        cliScriptPath("pr-protected-issues"),
+        scriptPath,
         String(prNumber),
         "--protected",
         protectedIssues.map(String).join(","),
@@ -92,10 +99,14 @@ export function runProtectedCheck(prNumber, repo, protectedIssues, options = {})
 }
 /** Invoke pr-monitor CLI with --json and return (returncode, stdout, stderr). */
 export function runMonitor(prNumber, repo, capMinutes, options = {}) {
+    const scriptPath = cliScriptPath("pr-monitor");
+    if (!existsSync(scriptPath)) {
+        return [2, "", `monitor script not found: ${scriptPath}`];
+    }
     const node = options.nodeExecutable ?? process.execPath;
     const timeoutSec = options.timeout ?? capMinutes * 60 + 60;
     const cmd = [
-        cliScriptPath("pr-monitor"),
+        scriptPath,
         String(prNumber),
         "--repo",
         repo,

package/dist/pr-watch/constants.d.ts

@@ -17,6 +17,11 @@ export declare const VERDICT_NEW_P0_P1 = "NEW_P0_P1";
 export declare const VERDICT_ERRORED = "ERRORED";
 export declare const VERDICT_STALL = "STALL";
 export declare const VERDICT_TIMEOUT = "TIMEOUT";
+/**
+ * Greptile side of the clean gate is satisfied on HEAD but required CI is red
+ * (#2688). Exit 2 — fail-loud toward a CI fix loop instead of idle-polling.
+ */
+export declare const VERDICT_CI_BLOCKED = "CI_BLOCKED";
 /** --one-shot only: a single probe with no terminal verdict yet. */
 export declare const VERDICT_PENDING = "PENDING";
 /** External/config fault mid-probe (unresolvable repo/HEAD, gh unavailable). */
@@ -35,4 +40,9 @@ export declare const WATCH_HELP: string;
  * whole 30-minute budget (#1039 STALL terminal).
  */
 export declare const DEFAULT_STALL_THRESHOLD = 3;
+/**
+ * Consecutive polls with clean_gate_holdout=ci_failures (Greptile otherwise
+ * satisfied) before CI_BLOCKED (#2688). Same default as SHA STALL.
+ */
+export declare const DEFAULT_CI_BLOCKED_THRESHOLD = 3;
 //# sourceMappingURL=constants.d.ts.map

package/dist/pr-watch/constants.js

@@ -17,6 +17,11 @@ export const VERDICT_NEW_P0_P1 = "NEW_P0_P1";
 export const VERDICT_ERRORED = "ERRORED";
 export const VERDICT_STALL = "STALL";
 export const VERDICT_TIMEOUT = "TIMEOUT";
+/**
+ * Greptile side of the clean gate is satisfied on HEAD but required CI is red
+ * (#2688). Exit 2 — fail-loud toward a CI fix loop instead of idle-polling.
+ */
+export const VERDICT_CI_BLOCKED = "CI_BLOCKED";
 /** --one-shot only: a single probe with no terminal verdict yet. */
 export const VERDICT_PENDING = "PENDING";
 /** External/config fault mid-probe (unresolvable repo/HEAD, gh unavailable). */
@@ -49,7 +54,7 @@ export const WATCH_HELP = "usage: task pr:watch -- <pr_number> [options]\n" +
     "exit codes:\n" +
     "  0  CLEAN       SHA-matched review, confidence > 3, no P0/P1, CI green\n" +
     "  1  NEW_P0_P1   Blocking findings on the current (SHA-matched) review\n" +
-    "  2  ERRORED | STALL | TIMEOUT | config / usage error\n";
+    "  2  ERRORED | STALL | TIMEOUT | CI_BLOCKED | config / usage error\n";
 /**
  * Consecutive polls with a review PRESENT but stuck on a stale (non-HEAD)
  * commit before the loop surfaces STALL instead of waiting the full cap. Keeps
@@ -57,4 +62,9 @@ export const WATCH_HELP = "usage: task pr:watch -- <pr_number> [options]\n" +
  * whole 30-minute budget (#1039 STALL terminal).
  */
 export const DEFAULT_STALL_THRESHOLD = 3;
+/**
+ * Consecutive polls with clean_gate_holdout=ci_failures (Greptile otherwise
+ * satisfied) before CI_BLOCKED (#2688). Same default as SHA STALL.
+ */
+export const DEFAULT_CI_BLOCKED_THRESHOLD = 3;
 //# sourceMappingURL=constants.js.map

package/dist/pr-watch/main.js

@@ -151,6 +151,7 @@ export function watchResultToJson(result) {
         p1_count: p.p1Count,
         errored: p.errored,
         ci_failures: p.ciFailures,
+        ci_failed_checks: [...p.ciFailedChecks],
         is_clean: p.isClean,
         clean_gate_holdout: p.cleanGateHoldout,
         elapsed_seconds: result.elapsedSeconds,
@@ -171,6 +172,9 @@ export function printWatchHuman(result) {
     lines.push(`  Findings:           P0=${p.p0Count}  P1=${p.p1Count}`);
     lines.push(`  Errored sentinel:   ${p.errored}`);
     lines.push(`  CI failures:        ${p.ciFailures}`);
+    if (p.ciFailedChecks.length > 0) {
+        lines.push(`  Failed checks:      ${p.ciFailedChecks.join("; ")}`);
+    }
     if (p.cleanGateHoldout !== null) {
         lines.push(`  Clean-gate holdout: ${p.cleanGateHoldout}`);
     }

package/dist/pr-watch/probe.js

@@ -14,6 +14,7 @@ function errorProbe(headSha, message) {
         hasBlocking: false,
         errored: false,
         ciFailures: 0,
+        ciFailedChecks: [],
         terminalCheckRun: false,
         isClean: false,
         cleanGateHoldout: null,
@@ -61,12 +62,14 @@ export function probeOnce(prNumber, repoArg, runGh = defaultRunGh) {
     // ci_failures=0 / terminal so the Greptile verdict drives; the merge button
     // still owns the hard CI gate via pr:merge-ready (#796).
     let ciFailures = 0;
+    let ciFailedChecks = [];
     let terminalCheckRun = true;
     if (repo !== null) {
         const check = fetchCheckRunsRest(headSha, repo, runGh);
         if (check.summary !== null) {
             const ci = evaluateCiGate(check.checkRuns, {});
-            ciFailures = ci.summary.failed_required.length;
+            ciFailedChecks = ci.summary.failed_required;
+            ciFailures = ciFailedChecks.length;
             terminalCheckRun = ci.summary.pending_required.length === 0;
         }
     }
@@ -91,6 +94,7 @@ export function probeOnce(prNumber, repoArg, runGh = defaultRunGh) {
         hasBlocking: findings.has_blocking,
         errored,
         ciFailures,
+        ciFailedChecks,
         terminalCheckRun,
         isClean,
         cleanGateHoldout,

package/dist/pr-watch/types.d.ts

@@ -13,6 +13,8 @@ export interface WatchProbe {
     readonly hasBlocking: boolean;
     readonly errored: boolean;
     readonly ciFailures: number;
+    /** Failed required check identities (name + conclusion), when CI was probed. */
+    readonly ciFailedChecks: readonly string[];
     /** All required CI check-runs have a terminal conclusion (none pending). */
     readonly terminalCheckRun: boolean;
     readonly isClean: boolean;

package/dist/pr-watch/watch.js

@@ -1,5 +1,5 @@
 import { defaultRunGh } from "../pr-merge-readiness/gh.js";
-import { DEFAULT_MAX_WAIT_MINUTES, DEFAULT_POLL_SECONDS, DEFAULT_STALL_THRESHOLD, EXIT_CLEAN, EXIT_NEW_P0_P1, EXIT_TERMINAL_ERROR, VERDICT_CLEAN, VERDICT_CONFIG, VERDICT_ERRORED, VERDICT_NEW_P0_P1, VERDICT_PENDING, VERDICT_STALL, VERDICT_TIMEOUT, } from "./constants.js";
+import { DEFAULT_CI_BLOCKED_THRESHOLD, DEFAULT_MAX_WAIT_MINUTES, DEFAULT_POLL_SECONDS, DEFAULT_STALL_THRESHOLD, EXIT_CLEAN, EXIT_NEW_P0_P1, EXIT_TERMINAL_ERROR, VERDICT_CI_BLOCKED, VERDICT_CLEAN, VERDICT_CONFIG, VERDICT_ERRORED, VERDICT_NEW_P0_P1, VERDICT_PENDING, VERDICT_STALL, VERDICT_TIMEOUT, } from "./constants.js";
 import { probeOnce } from "./probe.js";
 const systemMonotonicClock = {
     now() {
@@ -52,6 +52,7 @@ export function watch(prNumber, repo, options = {}) {
     const startedAt = clockFn.now();
     let lastProbe = null;
     let stallStreak = 0;
+    let ciBlockedStreak = 0;
     const build = (verdict, exitCode, probe, poll) => ({
         verdict,
         exitCode,
@@ -79,6 +80,20 @@ export function watch(prNumber, repo, options = {}) {
         if (probe.errored) {
             return build(VERDICT_ERRORED, EXIT_TERMINAL_ERROR, probe, poll);
         }
+        // #2688: Greptile side satisfied on HEAD but CI red — fail loud toward a
+        // fix loop instead of burning max-wait-minutes on idle Greptile polls.
+        if (probe.cleanGateHoldout === "ci_failures") {
+            ciBlockedStreak += 1;
+        }
+        else {
+            ciBlockedStreak = 0;
+        }
+        if (oneShot && probe.cleanGateHoldout === "ci_failures") {
+            return build(VERDICT_CI_BLOCKED, EXIT_TERMINAL_ERROR, probe, poll);
+        }
+        if (!oneShot && ciBlockedStreak >= DEFAULT_CI_BLOCKED_THRESHOLD) {
+            return build(VERDICT_CI_BLOCKED, EXIT_TERMINAL_ERROR, probe, poll);
+        }
         // Stall = a review IS present but stuck on a non-HEAD commit; surface it
         // rather than burning the whole cap waiting for a re-review that isn't coming.
         if (probe.found && !probe.shaMatch) {
@@ -112,6 +127,7 @@ export function watch(prNumber, repo, options = {}) {
         hasBlocking: false,
         errored: false,
         ciFailures: 0,
+        ciFailedChecks: [],
         terminalCheckRun: false,
         isClean: false,
         cleanGateHoldout: null,

package/dist/scope/undo.js

@@ -1,5 +1,6 @@
 import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
 import { basename, join, relative, resolve } from "node:path";
+import { assertWriteTargetSafe, ProjectionContainmentError } from "../fs/projection-containment.js";
 import { resolveLifecycleRoot } from "../layout/resolve.js";
 import { append, canonicalLogPath, newDecisionId, readAll } from "./audit-log.js";
 import { REVERSIBLE_ACTIONS, TERMINAL_ACTIONS } from "./constants.js";
@@ -157,7 +158,7 @@ function inversePlan(entry, logEntries) {
     }
     return null;
 }
-function moveAndFlip(srcFile, destFolder, newStatus, timestamp) {
+function moveAndFlip(srcFile, destFolder, newStatus, timestamp, projectRoot) {
     if (!existsSync(srcFile)) {
         return [false, `File not found: ${srcFile}`, null];
     }
@@ -172,6 +173,15 @@ function moveAndFlip(srcFile, destFolder, newStatus, timestamp) {
     if (typeof plan !== "object" || plan === null || Array.isArray(plan)) {
         return [false, `Missing or invalid 'plan' object in ${srcFile}`, null];
     }
+    try {
+        assertWriteTargetSafe(projectRoot, srcFile);
+    }
+    catch (err) {
+        if (err instanceof ProjectionContainmentError) {
+            return [false, err.message, null];
+        }
+        throw err;
+    }
     const planObj = plan;
     planObj.status = newStatus;
     planObj.updated = timestamp;
@@ -262,7 +272,7 @@ export function undoOne(entry, projectRoot, options = {}) {
         });
         return { ok: true, message: msg, auditEntry: preview };
     }
-    const [ok, fsMsg, destPath] = moveAndFlip(srcPath, destFolderPath, plan.newStatus, timestamp);
+    const [ok, fsMsg, destPath] = moveAndFlip(srcPath, destFolderPath, plan.newStatus, timestamp, projectRoot);
     if (!ok || destPath === null) {
         return { ok: false, message: fsMsg, auditEntry: null };
     }

package/dist/triage/bootstrap/cache-module.d.ts

@@ -0,0 +1,25 @@
+/**
+ * TypeScript default cache module for triage:bootstrap (#2684).
+ *
+ * npm / packaged consumers never ship scripts/cache.py; bootstrap must use the
+ * same cacheFetchAll path as empty-cache auto-populate (#2575).
+ */
+import { type FetchAllReportImpl } from "../../cache/fetch.js";
+import type { CacheModule } from "./types.js";
+export type CacheFetchAllFn = (options: {
+    source: string;
+    repo: string;
+    batchSize?: number;
+    delayMs?: number;
+    state?: string;
+    limit?: number;
+    labels?: readonly string[];
+    author?: string | null;
+    cacheRoot?: string;
+    force?: boolean;
+}) => FetchAllReportImpl;
+/** Adapt TS cache reports to the bootstrap `FetchAllReport` shape. */
+export declare function bootstrapCacheModule(fetchAll?: CacheFetchAllFn): CacheModule;
+/** Default module for packaged and source checkouts — never gates on Python. */
+export declare function loadDefaultCacheModule(): CacheModule;
+//# sourceMappingURL=cache-module.d.ts.map

package/dist/triage/bootstrap/cache-module.js

@@ -0,0 +1,39 @@
+/**
+ * TypeScript default cache module for triage:bootstrap (#2684).
+ *
+ * npm / packaged consumers never ship scripts/cache.py; bootstrap must use the
+ * same cacheFetchAll path as empty-cache auto-populate (#2575).
+ */
+import { cacheFetchAll } from "../../cache/fetch.js";
+/** Adapt TS cache reports to the bootstrap `FetchAllReport` shape. */
+export function bootstrapCacheModule(fetchAll = cacheFetchAll) {
+    return {
+        cacheFetchAll(kwargs) {
+            const report = fetchAll({
+                source: kwargs.source,
+                repo: kwargs.repo,
+                cacheRoot: kwargs.cacheRoot,
+                force: true,
+                ...(kwargs.batchSize !== undefined ? { batchSize: kwargs.batchSize } : {}),
+                ...(kwargs.delayMs !== undefined ? { delayMs: kwargs.delayMs } : {}),
+                ...(kwargs.state !== undefined ? { state: kwargs.state } : {}),
+                ...(kwargs.limit !== undefined ? { limit: kwargs.limit } : {}),
+                ...(kwargs.labels !== undefined && kwargs.labels.length > 0
+                    ? { labels: kwargs.labels }
+                    : {}),
+                ...(kwargs.author !== undefined ? { author: kwargs.author } : {}),
+            });
+            return Promise.resolve({
+                succeeded: report.issuesWritten,
+                failed: report.issuesFailed,
+                skipped: report.alreadyFresh,
+                summaryLine: (source, repo) => report.summaryLine(source, repo),
+            });
+        },
+    };
+}
+/** Default module for packaged and source checkouts — never gates on Python. */
+export function loadDefaultCacheModule() {
+    return bootstrapCacheModule();
+}
+//# sourceMappingURL=cache-module.js.map

package/dist/triage/bootstrap/index.d.ts

@@ -1,4 +1,5 @@
 import type { BootstrapResult, CacheModule, RunBootstrapOptions, StepOutcome } from "./types.js";
+export * from "./cache-module.js";
 export * from "./gitignore.js";
 export * from "./types.js";
 export declare const CACHE_DIR_NAME = ".deft-cache";

package/dist/triage/bootstrap/index.js

@@ -1,13 +1,13 @@
-import { execFile, execFileSync } from "node:child_process";
+import { execFileSync } from "node:child_process";
 import { randomUUID } from "node:crypto";
 import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
-import { promisify } from "node:util";
 import { hasArtifactSuffix, resolveLifecycleRoot } from "../../layout/resolve.js";
-import { SUBPROCESS_MAX_BUFFER } from "../../subprocess/max-buffer.js";
 import { resolveCandidatesLogPath } from "../cache-path.js";
+import { loadDefaultCacheModule } from "./cache-module.js";
 import { stepEnsureGitignoreEntry, stepEnsureGitignoreEvalEntries, stepSeedCandidatesLog, } from "./gitignore.js";
 import { PROGRESS_DEFAULT } from "./types.js";
+export * from "./cache-module.js";
 export * from "./gitignore.js";
 export * from "./types.js";
 export const CACHE_DIR_NAME = ".deft-cache";
@@ -21,7 +21,6 @@ const TOTAL_STEPS = 5;
 const GIT_ORIGIN_RE = /^(?:https?:\/\/(?:[^@/]+@)?github\.com\/|git@github\.com:|ssh:\/\/git@github\.com[:/])([A-Za-z0-9][A-Za-z0-9._-]*)\/([A-Za-z0-9][A-Za-z0-9._-]*?)(?:\.git)?\/?\s*$/;
 const REPO_RE = /^[A-Za-z0-9][A-Za-z0-9._-]*\/[A-Za-z0-9][A-Za-z0-9._-]*$/;
 const RUNNER_UNSET = Symbol("runner-unset");
-const execFileAsync = promisify(execFile);
 function defaultWhich(name) {
     const locator = process.platform === "win32" ? "where" : "which";
     try {
@@ -126,81 +125,6 @@ export async function runWithTimeout(func, timeoutS) {
         error: boxError,
     };
 }
-function resolveDeftRoot(explicit) {
-    if (explicit !== undefined && explicit.length > 0)
-        return resolve(explicit);
-    if (process.env.DEFT_ROOT !== undefined && process.env.DEFT_ROOT.length > 0) {
-        return resolve(process.env.DEFT_ROOT);
-    }
-    return resolve(process.cwd());
-}
-function cacheModulePresent(deftRoot) {
-    return existsSync(join(deftRoot, "scripts", "cache.py"));
-}
-async function invokePythonCacheFetchAll(deftRoot, kwargs) {
-    const payload = JSON.stringify({
-        source: kwargs.source,
-        repo: kwargs.repo,
-        cache_root: kwargs.cacheRoot,
-        batch_size: kwargs.batchSize ?? null,
-        delay_ms: kwargs.delayMs ?? null,
-        state: kwargs.state ?? null,
-        limit: kwargs.limit ?? null,
-        labels: kwargs.labels ?? null,
-        author: kwargs.author ?? null,
-    });
-    const script = `
-import json, sys
-sys.path.insert(0, ${JSON.stringify(join(deftRoot, "scripts"))})
-from cache import cache_fetch_all
-raw = json.loads(sys.argv[1])
-kwargs = {
-    "source": raw["source"],
-    "repo": raw["repo"],
-    "cache_root": raw["cache_root"],
-}
-for key in ("batch_size", "delay_ms", "state", "limit", "author"):
-    if raw[key] is not None:
-        kwargs[key] = raw[key]
-if raw["labels"]:
-    kwargs["labels"] = tuple(raw["labels"])
-report = cache_fetch_all(**kwargs)
-out = {
-    "succeeded": getattr(report, "succeeded", None),
-    "failed": getattr(report, "failed", None),
-    "skipped": getattr(report, "skipped", None),
-}
-summary_line = getattr(report, "summary_line", None)
-if callable(summary_line):
-    try:
-        out["summary_message"] = summary_line(source=raw["source"], repo=raw["repo"])
-    except TypeError:
-        pass
-print(json.dumps(out))
-`;
-    const { stdout } = await execFileAsync("uv", ["run", "python", "-c", script, payload], {
-        cwd: deftRoot,
-        encoding: "utf8",
-        maxBuffer: SUBPROCESS_MAX_BUFFER,
-    });
-    const parsed = JSON.parse(String(stdout).trim());
-    const summaryMessage = parsed.summary_message;
-    return {
-        succeeded: parsed.succeeded,
-        failed: parsed.failed,
-        skipped: parsed.skipped,
-        summaryLine: typeof summaryMessage === "string" ? () => summaryMessage : null,
-    };
-}
-function loadDefaultCacheModule(deftRoot) {
-    if (!cacheModulePresent(deftRoot))
-        return null;
-    return {
-        cacheFetchAll(kwargs) {
-            return invokePythonCacheFetchAll(deftRoot, kwargs);
-        },
-    };
-}
 function nowIsoDefault() {
     return new Date().toISOString().replace(/\.\d{3}Z$/, "Z");
 }
@@ -219,10 +143,11 @@ export async function stepPopulateCache(projectRoot, repo, options = {}) {
     if (!REPO_RE.test(effectiveRepo)) {
         return stepOutcome("populate_cache", false, `invalid --repo '${effectiveRepo}'`, {}, "repo must be 'owner/name' (alphanumerics, '.', '_', '-' only)");
     }
-    const deftRoot = resolveDeftRoot(options.deftRoot);
-    const cacheMod = options.cacheModule ?? loadDefaultCacheModule(deftRoot);
+    // #2684: default is TypeScript cacheFetchAll — never gate on scripts/cache.py.
+    // Explicit null still skips populate (tests / callers that inject empty cache).
+    const cacheMod = options.cacheModule !== undefined ? options.cacheModule : loadDefaultCacheModule();
     if (cacheMod === null) {
-        return stepOutcome("populate_cache", true, "deferred (scripts/cache.py not present on this branch; re-run after rebase to populate via task cache:fetch-all)", { deferred: "cache-module-missing", repo: effectiveRepo });
+        return stepOutcome("populate_cache", true, "deferred (cache module explicitly disabled; pass a cacheModule or omit the override to populate via cache:fetch-all)", { deferred: "cache-module-disabled", repo: effectiveRepo });
     }
     const kwargs = {
         source: CACHE_SOURCE,

package/dist/xbrief-migrate/agents-header.d.ts

@@ -1,14 +1,3 @@
-/**
- * Bounded, ordered set of legacy crossover tokens rewritten in the UNMANAGED
- * region of a consumer AGENTS.md after `migrate:xbrief` (#2154 / Option A).
- *
- * Each entry is a mechanical path / verb literal — NOT freeform prose. The
- * casing-only `vBRIEF format` product-description token from the issue table is
- * intentionally excluded so freeform prose survives untouched. The tokens are
- * disjoint substrings (`.vbrief.json` has no trailing slash, `vbrief:preflight`
- * uses a colon, `vbrief/` requires a slash), so replacement order does not
- * change the result and a second pass is a guaranteed no-op (idempotent).
- */
 export declare const LEGACY_HEADER_TOKENS: ReadonlyArray<{
     readonly legacy: string;
     readonly migrated: string;

package/dist/xbrief-migrate/agents-header.js

@@ -1,5 +1,6 @@
 import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
+import { assertProjectionContained } from "../fs/projection-containment.js";
 import { iterManagedSections } from "../platform/agents-md.js";
 import { MIGRATED_ARTIFACT_DIR } from "./constants.js";
 import { isDirectory } from "./fs-helpers.js";
@@ -14,6 +15,12 @@ import { isDirectory } from "./fs-helpers.js";
  * uses a colon, `vbrief/` requires a slash), so replacement order does not
  * change the result and a second pass is a guaranteed no-op (idempotent).
  */
+/** Refuse migrate header writes that escape via repo-controlled symlinks (#2668). */
+function projectionTarget(projectDir, ...relSegments) {
+    const target = join(projectDir, ...relSegments);
+    assertProjectionContained(projectDir, target);
+    return target;
+}
 export const LEGACY_HEADER_TOKENS = [
     { legacy: ".vbrief.json", migrated: ".xbrief.json" },
     { legacy: "vbrief:preflight", migrated: "xbrief:preflight" },
@@ -94,6 +101,7 @@ export function patchAgentsMdHeader(projectRoot, seams = {}) {
             }
         });
     const writeText = seams.writeText ?? ((path, text) => writeFileSync(path, text, "utf8"));
+    const usingWriteSeam = seams.writeText !== undefined;
     const existing = readText(agentsPath);
     if (existing === null) {
         return { kind: "absent", path: agentsPath, replacements: [] };
@@ -103,7 +111,8 @@ export function patchAgentsMdHeader(projectRoot, seams = {}) {
         return { kind: "clean", path: agentsPath, replacements: [] };
     }
     try {
-        writeText(agentsPath, result.content);
+        const writePath = usingWriteSeam ? agentsPath : projectionTarget(projectRoot, "AGENTS.md");
+        writeText(writePath, result.content);
     }
     catch (err) {
         return {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deftai/directive-core",
-  "version": "0.79.3",
+  "version": "0.79.4",
   "description": "TypeScript engine core for the Directive framework.",
   "type": "module",
   "main": "./dist/index.js",
@@ -309,8 +309,8 @@
     "provenance": true
   },
   "dependencies": {
-    "@deftai/directive-content": "^0.79.3",
-    "@deftai/directive-types": "^0.79.3",
+    "@deftai/directive-content": "^0.79.4",
+    "@deftai/directive-types": "^0.79.4",
     "archiver": "^8.0.0"
   },
   "scripts": {