@deftai/directive-core 0.83.0 → 0.84.0

package/dist/cache/main.js

@@ -6,6 +6,10 @@ import { cacheFetchAll, cacheRefreshClosed } from "./fetch.js";
 import { pythonBool, pythonJsonPretty } from "./json.js";
 import { cacheGet, cacheInvalidate, cachePrune, cachePruneToCap, cachePut } from "./operations.js";
 import { resolveCaps } from "./quota.js";
+import { clearTaskCache } from "./task-cache/store.js";
+function usage() {
+    process.stderr.write("usage: cache [-h] {put,get,invalidate,fetch-all,prune,clear} ...\n");
+}
 function normaliseLabelFilter(raw) {
     if (!raw || raw.length === 0)
         return [];
@@ -14,8 +18,36 @@ function normaliseLabelFilter(raw) {
         .map((item) => item.trim())
         .filter((item) => item.length > 0));
 }
-function usage() {
-    process.stderr.write("usage: cache [-h] {put,get,invalidate,fetch-all,prune} ...\n");
+function cmdClear(args) {
+    let projectRoot = process.cwd();
+    for (let i = 0; i < args.length; i += 1) {
+        const arg = args[i];
+        if (arg === "--project-root") {
+            const next = args[i + 1];
+            if (next !== undefined) {
+                projectRoot = next;
+            }
+            i += 1;
+        }
+        else if (arg?.startsWith("--project-root=")) {
+            projectRoot = arg.slice("--project-root=".length);
+        }
+        else {
+            throw new CacheError(`unexpected argument: ${arg}`);
+        }
+    }
+    const result = clearTaskCache(projectRoot);
+    if (result.code !== 0) {
+        process.stderr.write("cache clear: failed to remove task cache directory\n");
+        return 1;
+    }
+    if (result.removed) {
+        process.stdout.write(`cache clear: removed task cache under ${projectRoot}\n`);
+    }
+    else {
+        process.stdout.write(`cache clear: no task cache present under ${projectRoot}\n`);
+    }
+    return 0;
 }
 function cmdPut(args) {
     let source = "";
@@ -298,6 +330,8 @@ export function main(argv) {
                 return cmdFetchAll(rest);
             case "prune":
                 return cmdPrune(rest);
+            case "clear":
+                return cmdClear(rest);
             default:
                 usage();
                 process.stderr.write(`cache: error: argument cmd: invalid choice: '${cmd}'\n`);

package/dist/cache/task-cache/constants.d.ts

@@ -0,0 +1,4 @@
+/** On-disk root for content-hash task cache entries (#1713). */
+export declare const DEFAULT_TASK_CACHE_ROOT = ".deft/cache/task";
+export declare const TASK_CACHE_MANIFEST = "entry.json";
+//# sourceMappingURL=constants.d.ts.map

package/dist/cache/task-cache/constants.js

@@ -0,0 +1,4 @@
+/** On-disk root for content-hash task cache entries (#1713). */
+export const DEFAULT_TASK_CACHE_ROOT = ".deft/cache/task";
+export const TASK_CACHE_MANIFEST = "entry.json";
+//# sourceMappingURL=constants.js.map

package/dist/cache/task-cache/executor.d.ts

@@ -0,0 +1,9 @@
+import type { RunWithCacheOptions, TaskRunResult } from "./types.js";
+/**
+ * Run a task with content-hash caching (#1713).
+ * - Only exit-0 results are stored.
+ * - Failures always re-run.
+ * - Non-cacheable / incomplete inputs fail open to running.
+ */
+export declare function runWithCache(options: RunWithCacheOptions): TaskRunResult;
+//# sourceMappingURL=executor.d.ts.map

package/dist/cache/task-cache/executor.js

@@ -0,0 +1,51 @@
+import { composeCacheKey, hashTaskInputs } from "./hash.js";
+import { readCachedTaskRecord, writeCachedTaskRecord } from "./store.js";
+/**
+ * Run a task with content-hash caching (#1713).
+ * - Only exit-0 results are stored.
+ * - Failures always re-run.
+ * - Non-cacheable / incomplete inputs fail open to running.
+ */
+export function runWithCache(options) {
+    const { projectRoot, contract, codeVersion, noCache = false, cacheRoot, runner } = options;
+    if (noCache || !contract.cacheable) {
+        const live = runner();
+        return { ...live, fromCache: false };
+    }
+    const effectiveVersion = contract.codeVersion ?? codeVersion;
+    const enumeration = hashTaskInputs(projectRoot, contract, process.env);
+    if (!enumeration.complete) {
+        const live = runner();
+        return { ...live, fromCache: false };
+    }
+    const cacheKey = composeCacheKey(contract.id, enumeration.digest, effectiveVersion);
+    const cached = readCachedTaskRecord(projectRoot, cacheKey, cacheRoot);
+    if (cached !== null && cached.codeVersion === effectiveVersion) {
+        if (cached.stdout.length > 0) {
+            process.stdout.write(cached.stdout);
+        }
+        if (cached.stderr.length > 0) {
+            process.stderr.write(cached.stderr);
+        }
+        return {
+            exitCode: cached.exitCode,
+            stdout: cached.stdout,
+            stderr: cached.stderr,
+            fromCache: true,
+        };
+    }
+    const live = runner();
+    if (live.exitCode === 0) {
+        writeCachedTaskRecord(projectRoot, cacheKey, {
+            taskId: contract.id,
+            inputsHash: enumeration.digest,
+            codeVersion: effectiveVersion,
+            exitCode: live.exitCode,
+            stdout: live.stdout,
+            stderr: live.stderr,
+            storedAt: new Date().toISOString(),
+        }, cacheRoot);
+    }
+    return { ...live, fromCache: false };
+}
+//# sourceMappingURL=executor.js.map

package/dist/cache/task-cache/hash.d.ts

@@ -0,0 +1,17 @@
+import type { TaskContract, TaskInputSpec } from "./types.js";
+export interface InputEnumeration {
+    readonly complete: boolean;
+    readonly digest: string;
+}
+/** Expand declared globs under projectRoot; returns sorted relative paths. */
+export declare function expandInputGlobs(projectRoot: string, spec: TaskInputSpec): string[];
+/** Collect env values for declared keys (missing vars map to empty string). */
+export declare function collectEnvValues(spec: TaskInputSpec, env: NodeJS.ProcessEnv): Record<string, string>;
+/**
+ * Hash declared inputs. Returns `complete: false` when no inputs are declared
+ * (fail open to running — never cache without explicit enumeration).
+ */
+export declare function hashTaskInputs(projectRoot: string, contract: TaskContract, env: NodeJS.ProcessEnv): InputEnumeration;
+/** Compose the final cache key digest including codeVersion. */
+export declare function composeCacheKey(taskId: string, inputsHash: string, codeVersion: string): string;
+//# sourceMappingURL=hash.d.ts.map

package/dist/cache/task-cache/hash.js

@@ -0,0 +1,92 @@
+import { createHash } from "node:crypto";
+import { globSync, readFileSync, statSync } from "node:fs";
+import { relative, resolve } from "node:path";
+function stableJson(value) {
+    if (value === null || typeof value !== "object") {
+        return JSON.stringify(value);
+    }
+    if (Array.isArray(value)) {
+        return `[${value.map((item) => stableJson(item)).join(",")}]`;
+    }
+    const obj = value;
+    const keys = Object.keys(obj).sort();
+    return `{${keys.map((key) => `${JSON.stringify(key)}:${stableJson(obj[key])}`).join(",")}}`;
+}
+function hashFile(path) {
+    const hash = createHash("sha256");
+    hash.update(readFileSync(path));
+    return hash.digest("hex");
+}
+/** Expand declared globs under projectRoot; returns sorted relative paths. */
+export function expandInputGlobs(projectRoot, spec) {
+    const root = resolve(projectRoot);
+    const globs = spec.globs ?? [];
+    const paths = new Set();
+    for (const pattern of globs) {
+        let matches;
+        try {
+            matches = globSync(pattern, { cwd: root }).filter((match) => {
+                try {
+                    return !statSync(resolve(root, match)).isDirectory();
+                }
+                catch {
+                    return true;
+                }
+            });
+        }
+        catch {
+            return [];
+        }
+        for (const match of matches) {
+            paths.add(relative(root, resolve(root, match)).replace(/\\/g, "/"));
+        }
+    }
+    return [...paths].sort();
+}
+/** Collect env values for declared keys (missing vars map to empty string). */
+export function collectEnvValues(spec, env) {
+    const out = {};
+    for (const key of spec.env ?? []) {
+        out[key] = env[key] ?? "";
+    }
+    return out;
+}
+/**
+ * Hash declared inputs. Returns `complete: false` when no inputs are declared
+ * (fail open to running — never cache without explicit enumeration).
+ */
+export function hashTaskInputs(projectRoot, contract, env) {
+    const spec = contract.inputs;
+    const hasGlobs = (spec.globs?.length ?? 0) > 0;
+    const hasEnv = (spec.env?.length ?? 0) > 0;
+    if (!hasGlobs && !hasEnv) {
+        return { complete: false, digest: "" };
+    }
+    const files = expandInputGlobs(projectRoot, spec);
+    if (hasGlobs && files.length === 0) {
+        return { complete: false, digest: "" };
+    }
+    const fileHashes = {};
+    for (const rel of files) {
+        const abs = resolve(projectRoot, rel);
+        try {
+            fileHashes[rel] = hashFile(abs);
+        }
+        catch {
+            // Fail open: a file removed/unreadable between glob and read must not crash check.
+            return { complete: false, digest: "" };
+        }
+    }
+    const payload = {
+        taskId: contract.id,
+        files: fileHashes,
+        env: collectEnvValues(spec, env),
+    };
+    const digest = createHash("sha256").update(stableJson(payload)).digest("hex");
+    return { complete: true, digest };
+}
+/** Compose the final cache key digest including codeVersion. */
+export function composeCacheKey(taskId, inputsHash, codeVersion) {
+    return createHash("sha256").update(stableJson({ taskId, inputsHash, codeVersion })).digest("hex");
+}
+//# sourceMappingURL=hash.js.map

package/dist/cache/task-cache/index.d.ts

@@ -0,0 +1,14 @@
+import { lintTaskRegistry } from "./lint.js";
+export { DEFAULT_TASK_CACHE_ROOT, TASK_CACHE_MANIFEST } from "./constants.js";
+export { runWithCache } from "./executor.js";
+export { composeCacheKey, expandInputGlobs, hashTaskInputs } from "./hash.js";
+export { lintTaskContract, lintTaskRegistry } from "./lint.js";
+export { defaultNonCacheableContract, lookupTaskContract, resolveTaskContract, TASK_REGISTRY, } from "./registry.js";
+export { clearTaskCache, readCachedTaskRecord, taskCacheRoot, writeCachedTaskRecord, } from "./store.js";
+export type { CachedTaskRecord, RegistryLintFinding, RunWithCacheOptions, TaskContract, TaskInputSpec, TaskRunResult, } from "./types.js";
+/** Lint the shipped registry; under-declared cacheable tasks fail closed. */
+export declare function lintShippedRegistry(): {
+    ok: boolean;
+    findings: ReturnType<typeof lintTaskRegistry>;
+};
+//# sourceMappingURL=index.d.ts.map

package/dist/cache/task-cache/index.js

@@ -0,0 +1,15 @@
+import { lintTaskRegistry } from "./lint.js";
+import { TASK_REGISTRY } from "./registry.js";
+export { DEFAULT_TASK_CACHE_ROOT, TASK_CACHE_MANIFEST } from "./constants.js";
+export { runWithCache } from "./executor.js";
+export { composeCacheKey, expandInputGlobs, hashTaskInputs } from "./hash.js";
+export { lintTaskContract, lintTaskRegistry } from "./lint.js";
+export { defaultNonCacheableContract, lookupTaskContract, resolveTaskContract, TASK_REGISTRY, } from "./registry.js";
+export { clearTaskCache, readCachedTaskRecord, taskCacheRoot, writeCachedTaskRecord, } from "./store.js";
+/** Lint the shipped registry; under-declared cacheable tasks fail closed. */
+export function lintShippedRegistry() {
+    const findings = lintTaskRegistry(TASK_REGISTRY);
+    const blocking = findings.filter((f) => f.kind === "under-declared-input");
+    return { ok: blocking.length === 0, findings };
+}
+//# sourceMappingURL=index.js.map

package/dist/cache/task-cache/lint.d.ts

@@ -0,0 +1,4 @@
+import type { RegistryLintFinding, TaskContract } from "./types.js";
+export declare function lintTaskContract(contract: TaskContract): RegistryLintFinding[];
+export declare function lintTaskRegistry(contracts: readonly TaskContract[]): RegistryLintFinding[];
+//# sourceMappingURL=lint.d.ts.map

package/dist/cache/task-cache/lint.js

@@ -0,0 +1,55 @@
+/** Strip trailing `*` glob wildcards without regex (CodeQL ReDoS-safe). */
+function stripTrailingGlobStars(pattern) {
+    let end = pattern.length;
+    while (end > 0 && pattern[end - 1] === "*") {
+        end--;
+    }
+    return pattern.slice(0, end);
+}
+function diffSpec(superset, declared) {
+    const findings = [];
+    for (const glob of superset.globs ?? []) {
+        const covered = (declared.globs ?? []).some((decl) => decl === glob || glob.startsWith(stripTrailingGlobStars(decl)));
+        if (!covered) {
+            findings.push(`glob '${glob}' missing from declared inputs`);
+        }
+    }
+    for (const envKey of superset.env ?? []) {
+        if (!(declared.env ?? []).includes(envKey)) {
+            findings.push(`env '${envKey}' missing from declared inputs`);
+        }
+    }
+    return findings;
+}
+export function lintTaskContract(contract) {
+    const findings = [];
+    if (!contract.knownReadSet) {
+        return findings;
+    }
+    const missing = diffSpec(contract.knownReadSet, contract.inputs);
+    for (const detail of missing) {
+        if (contract.cacheable) {
+            findings.push({
+                taskId: contract.id,
+                kind: "under-declared-input",
+                detail,
+            });
+        }
+        else {
+            findings.push({
+                taskId: contract.id,
+                kind: "non-cacheable",
+                detail: `${detail} (task marked non-cacheable)`,
+            });
+        }
+    }
+    return findings;
+}
+export function lintTaskRegistry(contracts) {
+    const all = [];
+    for (const contract of contracts) {
+        all.push(...lintTaskContract(contract));
+    }
+    return all;
+}
+//# sourceMappingURL=lint.js.map

package/dist/cache/task-cache/registry.d.ts

@@ -0,0 +1,7 @@
+import type { TaskContract } from "./types.js";
+/** Internal gate/task registry for directive dogfood (#1713). */
+export declare const TASK_REGISTRY: readonly TaskContract[];
+export declare function lookupTaskContract(taskId: string): TaskContract | undefined;
+export declare function defaultNonCacheableContract(taskId: string): TaskContract;
+export declare function resolveTaskContract(taskId: string): TaskContract;
+//# sourceMappingURL=registry.d.ts.map

package/dist/cache/task-cache/registry.js

@@ -0,0 +1,67 @@
+/** Internal gate/task registry for directive dogfood (#1713). */
+export const TASK_REGISTRY = [
+    {
+        id: "verify:biome-config",
+        cacheable: true,
+        inputs: { globs: ["biome.json", "biome.jsonc"] },
+        knownReadSet: { globs: ["biome.json", "biome.jsonc"] },
+    },
+    {
+        id: "verify:encoding",
+        cacheable: true,
+        inputs: {
+            globs: ["biome.json", "packages/**/*.ts", "packages/**/*.tsx", "content/**/*"],
+        },
+        knownReadSet: {
+            globs: ["biome.json", "packages/**/*.ts", "packages/**/*.tsx", "content/**/*"],
+        },
+    },
+    {
+        id: "toolchain:check",
+        cacheable: true,
+        inputs: {
+            globs: ["package.json", "pnpm-lock.yaml", ".nvmrc", ".node-version"],
+            env: ["PATH"],
+        },
+        knownReadSet: {
+            globs: ["package.json", "pnpm-lock.yaml", ".nvmrc", ".node-version"],
+            env: ["PATH"],
+        },
+    },
+    {
+        id: "verify:branch",
+        cacheable: false,
+        inputs: { env: ["GIT_BRANCH", "DEFT_ALLOW_DEFAULT_BRANCH_COMMIT"] },
+        knownReadSet: {
+            globs: [".git/HEAD"],
+            env: ["GIT_BRANCH", "DEFT_ALLOW_DEFAULT_BRANCH_COMMIT"],
+        },
+    },
+    {
+        id: "verify:cache-fresh",
+        cacheable: false,
+        inputs: {},
+        knownReadSet: { globs: [".deft-cache/**/*", "xbrief/.triage-cache/**/*"] },
+    },
+    {
+        id: "doctor",
+        cacheable: false,
+        inputs: {},
+        knownReadSet: { globs: ["**/*"] },
+    },
+];
+const REGISTRY_MAP = new Map(TASK_REGISTRY.map((entry) => [entry.id, entry]));
+export function lookupTaskContract(taskId) {
+    return REGISTRY_MAP.get(taskId);
+}
+export function defaultNonCacheableContract(taskId) {
+    return {
+        id: taskId,
+        cacheable: false,
+        inputs: {},
+    };
+}
+export function resolveTaskContract(taskId) {
+    return lookupTaskContract(taskId) ?? defaultNonCacheableContract(taskId);
+}
+//# sourceMappingURL=registry.js.map

package/dist/cache/task-cache/store.d.ts

@@ -0,0 +1,10 @@
+import type { CachedTaskRecord } from "./types.js";
+export declare function readCachedTaskRecord(projectRoot: string, cacheKey: string, cacheRoot?: string): CachedTaskRecord | null;
+export declare function writeCachedTaskRecord(projectRoot: string, cacheKey: string, record: CachedTaskRecord, cacheRoot?: string): void;
+export interface ClearTaskCacheResult {
+    readonly code: number;
+    readonly removed: boolean;
+}
+export declare function clearTaskCache(projectRoot: string, cacheRoot?: string): ClearTaskCacheResult;
+export declare function taskCacheRoot(projectRoot: string, cacheRoot?: string): string;
+//# sourceMappingURL=store.d.ts.map

package/dist/cache/task-cache/store.js

@@ -0,0 +1,48 @@
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { assertWriteTargetSafe } from "../../fs/projection-containment.js";
+import { DEFAULT_TASK_CACHE_ROOT, TASK_CACHE_MANIFEST } from "./constants.js";
+function entryDir(projectRoot, cacheKey, cacheRoot = DEFAULT_TASK_CACHE_ROOT) {
+    return join(resolve(projectRoot), cacheRoot, cacheKey.slice(0, 2), cacheKey);
+}
+export function readCachedTaskRecord(projectRoot, cacheKey, cacheRoot = DEFAULT_TASK_CACHE_ROOT) {
+    const manifest = join(entryDir(projectRoot, cacheKey, cacheRoot), TASK_CACHE_MANIFEST);
+    try {
+        const raw = JSON.parse(readFileSync(manifest, "utf8"));
+        if (raw.exitCode !== 0) {
+            return null;
+        }
+        return raw;
+    }
+    catch {
+        return null;
+    }
+}
+export function writeCachedTaskRecord(projectRoot, cacheKey, record, cacheRoot = DEFAULT_TASK_CACHE_ROOT) {
+    if (record.exitCode !== 0) {
+        return;
+    }
+    const dir = entryDir(projectRoot, cacheKey, cacheRoot);
+    const manifest = join(dir, TASK_CACHE_MANIFEST);
+    assertWriteTargetSafe(resolve(projectRoot), dir);
+    mkdirSync(dirname(manifest), { recursive: true });
+    assertWriteTargetSafe(resolve(projectRoot), manifest);
+    writeFileSync(manifest, `${JSON.stringify(record, null, 2)}\n`, "utf8");
+}
+export function clearTaskCache(projectRoot, cacheRoot = DEFAULT_TASK_CACHE_ROOT) {
+    const root = join(resolve(projectRoot), cacheRoot);
+    if (!existsSync(root)) {
+        return { code: 0, removed: false };
+    }
+    try {
+        rmSync(root, { recursive: true, force: true });
+        return { code: 0, removed: true };
+    }
+    catch {
+        return { code: 1, removed: false };
+    }
+}
+export function taskCacheRoot(projectRoot, cacheRoot = DEFAULT_TASK_CACHE_ROOT) {
+    return join(resolve(projectRoot), cacheRoot);
+}
+//# sourceMappingURL=store.js.map

package/dist/cache/task-cache/types.d.ts

@@ -0,0 +1,48 @@
+/** Internal gate/task contract (#1713). Public promotion deferred to #2784. */
+export interface TaskInputSpec {
+    /** Glob patterns relative to the project root. */
+    readonly globs?: readonly string[];
+    /** Environment variable names whose values affect the task outcome. */
+    readonly env?: readonly string[];
+}
+export interface TaskContract {
+    readonly id: string;
+    /** When false the task always runs and never stores a cache entry. */
+    readonly cacheable: boolean;
+    /** Override engine version in the cache key; defaults to installed directive version. */
+    readonly codeVersion?: string;
+    readonly inputs: TaskInputSpec;
+    /** Output globs for under-declaration lint (optional). */
+    readonly outputs?: readonly string[];
+    /** Superset of reads used by under-declaration lint. */
+    readonly knownReadSet?: TaskInputSpec;
+}
+export interface TaskRunResult {
+    readonly exitCode: number;
+    readonly stdout: string;
+    readonly stderr: string;
+    readonly fromCache: boolean;
+}
+export interface CachedTaskRecord {
+    readonly taskId: string;
+    readonly inputsHash: string;
+    readonly codeVersion: string;
+    readonly exitCode: number;
+    readonly stdout: string;
+    readonly stderr: string;
+    readonly storedAt: string;
+}
+export interface RunWithCacheOptions {
+    readonly projectRoot: string;
+    readonly contract: TaskContract;
+    readonly codeVersion: string;
+    readonly noCache?: boolean;
+    readonly cacheRoot?: string;
+    readonly runner: () => Pick<TaskRunResult, "exitCode" | "stdout" | "stderr">;
+}
+export interface RegistryLintFinding {
+    readonly taskId: string;
+    readonly kind: "under-declared-input" | "non-cacheable";
+    readonly detail: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/cache/task-cache/types.js

@@ -0,0 +1,3 @@
+/** Internal gate/task contract (#1713). Public promotion deferred to #2784. */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/check/cached-orchestrator.d.ts

@@ -0,0 +1,16 @@
+import type { TaskRunResult } from "../cache/task-cache/types.js";
+import { type CheckOrchestratorSeams } from "./context.js";
+export interface CachedCheckOptions extends CheckOrchestratorSeams {
+    readonly onGateStart?: (gateId: string) => void;
+    readonly onGateComplete?: (gateId: string, exitCode: number, fromCache: boolean) => void;
+    readonly gateSpawnFn?: (gateId: string, taskBin: string, taskArgs: string[], opts: {
+        cwd: string;
+        env?: NodeJS.ProcessEnv;
+    }) => Pick<TaskRunResult, "exitCode" | "stdout" | "stderr">;
+}
+/**
+ * Run check gates sequentially with content-hash caching (#1713).
+ * Falls back to fail-open execution for undeclared / non-cacheable gates.
+ */
+export declare function dispatchCachedTaskCheck(frameworkRoot: string, projectRoot: string, options?: CachedCheckOptions): number;
+//# sourceMappingURL=cached-orchestrator.d.ts.map

package/dist/check/cached-orchestrator.js

@@ -0,0 +1,76 @@
+import { spawnSync } from "node:child_process";
+import { join, resolve } from "node:path";
+import { lintShippedRegistry, resolveTaskContract, runWithCache, } from "../cache/task-cache/index.js";
+import { readCorePackageVersion } from "../engine-version.js";
+import { resolveCheckTarget } from "./context.js";
+import { checkGateId, checkGateSpawnArgs, gatesForCheckTarget } from "./gate-lists.js";
+function captureSpawn(taskBin, args, opts) {
+    const result = spawnSync(taskBin, args, {
+        cwd: opts.cwd,
+        encoding: "utf8",
+        env: opts.env ?? process.env,
+    });
+    return {
+        exitCode: result.status ?? 1,
+        stdout: result.stdout ?? "",
+        stderr: result.stderr ?? "",
+    };
+}
+/**
+ * Run check gates sequentially with content-hash caching (#1713).
+ * Falls back to fail-open execution for undeclared / non-cacheable gates.
+ */
+export function dispatchCachedTaskCheck(frameworkRoot, projectRoot, options = {}) {
+    const resolvedFramework = resolve(frameworkRoot);
+    const resolvedProject = resolve(projectRoot);
+    const taskfilePath = join(resolvedFramework, "Taskfile.yml");
+    const taskBin = options.taskBin ?? "task";
+    const target = resolveCheckTarget(resolvedFramework, resolvedProject);
+    const cwd = target === "check:framework-source" ? resolvedFramework : resolvedProject;
+    const gates = gatesForCheckTarget(target);
+    const codeVersion = readCorePackageVersion();
+    const registryLint = lintShippedRegistry();
+    if (!registryLint.ok) {
+        for (const finding of registryLint.findings.filter((f) => f.kind === "under-declared-input")) {
+            process.stderr.write(`check: task registry lint failed for ${finding.taskId}: ${finding.detail}\n`);
+        }
+        return 2;
+    }
+    if (gates.length === 0) {
+        process.stderr.write(`check: no gate list for target ${target}\n`);
+        return 2;
+    }
+    for (const gateSpec of gates) {
+        const gateId = checkGateId(gateSpec);
+        options.onGateStart?.(gateId);
+        const contract = resolveTaskContract(gateId);
+        const taskArgs = checkGateSpawnArgs(gateSpec, taskfilePath);
+        const result = runWithCache({
+            projectRoot: cwd,
+            contract,
+            codeVersion,
+            noCache: options.noCache,
+            runner: () => {
+                const spawned = options.gateSpawnFn
+                    ? options.gateSpawnFn(gateId, taskBin, taskArgs, {
+                        cwd,
+                        env: options.env,
+                    })
+                    : captureSpawn(taskBin, taskArgs, { cwd, env: options.env });
+                if (spawned.stdout.length > 0) {
+                    process.stdout.write(spawned.stdout);
+                }
+                if (spawned.stderr.length > 0) {
+                    process.stderr.write(spawned.stderr);
+                }
+                return spawned;
+            },
+        });
+        options.onGateComplete?.(gateId, result.exitCode, result.fromCache);
+        if (result.exitCode !== 0) {
+            return result.exitCode;
+        }
+    }
+    return 0;
+}
+//# sourceMappingURL=cached-orchestrator.js.map

package/dist/check/context.d.ts

@@ -0,0 +1,30 @@
+export interface CheckOrchestratorOptions {
+    readonly noCache?: boolean;
+    readonly useTaskCache?: boolean;
+}
+export interface CheckOrchestratorSeams extends CheckOrchestratorOptions {
+    /** Override the `task` binary path (default: "task"). */
+    readonly taskBin?: string;
+    /** Override the spawnSync implementation for unit testing. */
+    readonly spawnFn?: (cmd: string, args: string[], opts: {
+        cwd: string;
+        stdio: string;
+        env?: NodeJS.ProcessEnv;
+        timeoutMs?: number;
+    }) => {
+        status: number | null;
+        signal?: NodeJS.Signals | null;
+        error?: Error;
+    };
+    /** Child-process environment (default: process.env). */
+    readonly env?: NodeJS.ProcessEnv;
+    /** Wall-clock spawn timeout in milliseconds (default: none). */
+    readonly timeoutMs?: number;
+}
+/** True when `path` is the directive framework source checkout root. */
+export declare function isFrameworkRepoRoot(path: string): boolean;
+/** Return true when running in the framework's own source checkout (#1519). */
+export declare function isFrameworkSourceContext(frameworkRoot: string, projectRoot: string): boolean;
+/** Select the Taskfile target for the given context. */
+export declare function resolveCheckTarget(frameworkRoot: string, projectRoot: string): string;
+//# sourceMappingURL=context.d.ts.map