@deftai/directive-core 0.67.0 → 0.68.0

package/dist/check/index.d.ts

@@ -1,3 +1,3 @@
 export type { CheckOrchestratorSeams } from "./orchestrator.js";
-export { dispatchTaskCheck, isFrameworkSourceContext, resolveCheckTarget } from "./orchestrator.js";
+export { dispatchTaskCheck, isFrameworkRepoRoot, isFrameworkSourceContext, resolveCheckTarget, } from "./orchestrator.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/check/index.js

@@ -1,2 +1,2 @@
-export { dispatchTaskCheck, isFrameworkSourceContext, resolveCheckTarget } from "./orchestrator.js";
+export { dispatchTaskCheck, isFrameworkRepoRoot, isFrameworkSourceContext, resolveCheckTarget, } from "./orchestrator.js";
 //# sourceMappingURL=index.js.map

package/dist/check/orchestrator.d.ts

@@ -24,13 +24,23 @@ export interface CheckOrchestratorSeams {
         error?: Error;
     };
 }
+/**
+ * True when `path` is the directive framework source checkout root (not a
+ * vendored `.deft/core` content deposit). Used to distinguish a maintainer
+ * running `task check` from a subdirectory (#2220) from a consumer install.
+ */
+export declare function isFrameworkRepoRoot(path: string): boolean;
 /**
  * Return true when running in the framework's own source checkout (#1519).
  *
- * Mirrors `is_framework_source_context` from _project_context.py:
- * equality of lexical absolute roots is the stable distinction. We do NOT
- * resolve symlinks here -- a consumer project may symlink `.deft/core` to a
- * local framework checkout and should still run the consumer-safe gate.
+ * Mirrors `is_framework_source_context` from _project_context.py with one
+ * extension (#2220): when the Taskfile lives at the framework repo root,
+ * `task check` may be invoked from a subdirectory (`USER_WORKING_DIR` !=
+ * `TASKFILE_DIR`). Those invocations must still route to
+ * `check:framework-source` so the biome lane runs. We do NOT resolve
+ * symlinks on the framework root -- a consumer project may symlink
+ * `.deft/core` to a local framework checkout and should still run the
+ * consumer-safe gate (the deposit path lacks `packages/cli`).
  */
 export declare function isFrameworkSourceContext(frameworkRoot: string, projectRoot: string): boolean;
 /**

package/dist/check/orchestrator.js

@@ -12,17 +12,41 @@
  *   2 -- config error (missing args, task spawn error, etc.)
  */
 import { spawnSync } from "node:child_process";
-import { join, resolve } from "node:path";
+import { existsSync } from "node:fs";
+import { join, resolve, sep } from "node:path";
+/**
+ * True when `path` is the directive framework source checkout root (not a
+ * vendored `.deft/core` content deposit). Used to distinguish a maintainer
+ * running `task check` from a subdirectory (#2220) from a consumer install.
+ */
+export function isFrameworkRepoRoot(path) {
+    const root = resolve(path);
+    return (existsSync(join(root, "packages", "cli", "package.json")) &&
+        existsSync(join(root, "biome.json")) &&
+        existsSync(join(root, "Taskfile.yml")));
+}
 /**
  * Return true when running in the framework's own source checkout (#1519).
  *
- * Mirrors `is_framework_source_context` from _project_context.py:
- * equality of lexical absolute roots is the stable distinction. We do NOT
- * resolve symlinks here -- a consumer project may symlink `.deft/core` to a
- * local framework checkout and should still run the consumer-safe gate.
+ * Mirrors `is_framework_source_context` from _project_context.py with one
+ * extension (#2220): when the Taskfile lives at the framework repo root,
+ * `task check` may be invoked from a subdirectory (`USER_WORKING_DIR` !=
+ * `TASKFILE_DIR`). Those invocations must still route to
+ * `check:framework-source` so the biome lane runs. We do NOT resolve
+ * symlinks on the framework root -- a consumer project may symlink
+ * `.deft/core` to a local framework checkout and should still run the
+ * consumer-safe gate (the deposit path lacks `packages/cli`).
  */
 export function isFrameworkSourceContext(frameworkRoot, projectRoot) {
-    return resolve(frameworkRoot) === resolve(projectRoot);
+    const fw = resolve(frameworkRoot);
+    const pr = resolve(projectRoot);
+    if (fw === pr) {
+        return true;
+    }
+    if (!isFrameworkRepoRoot(fw)) {
+        return false;
+    }
+    return pr.startsWith(`${fw}${sep}`);
 }
 /**
  * Select the Taskfile target for the given context.

package/dist/doctor/checks.js

@@ -34,14 +34,14 @@ export function checkQuickStartResolves(projectRoot, installRoot, seams = {}) {
             `install root is '${installRoot}' but the file is missing. ` +
             "Run `.deft/core/run agents:refresh` (Unix) / " +
             "`.deft\\core\\run agents:refresh` (Windows) to align AGENTS.md " +
-            "with the on-disk install root, OR run `task upgrade` to " +
+            "with the on-disk install root, OR run `deft update` to " +
             "re-pull the framework if the on-disk install is missing. " +
             "See UPGRADING.md for the canonical drift-repair walkthrough.",
         data: {
             path: qsPath,
             install_root: installRoot,
             suggested_fix: ".deft/core/run agents:refresh",
-            suggested_fix_alt: "task upgrade",
+            suggested_fix_alt: "deft update",
         },
     };
 }
@@ -89,13 +89,13 @@ export function checkSkillPathsResolve(projectRoot, agentsMdText, seams = {}) {
         status: "fail",
         detail: `${missing.length} skill path(s) do not resolve; ${redirectStubs.length} stub redirect(s). ` +
             `${parts.join("; ")}. Run \`.deft/core/run agents:refresh\` (Unix) / ` +
-            "`.deft\\core\\run agents:refresh` (Windows) to rewrite the managed AGENTS.md block so skill paths match the on-disk framework, OR run `task upgrade` if the on-disk skills are missing entirely. See UPGRADING.md for the drift-repair walkthrough.",
+            "`.deft\\core\\run agents:refresh` (Windows) to rewrite the managed AGENTS.md block so skill paths match the on-disk framework, OR run `deft update` if the on-disk skills are missing entirely. See UPGRADING.md for the drift-repair walkthrough.",
         data: {
             referenced,
             missing,
             redirect_stubs: redirectStubs,
             suggested_fix: ".deft/core/run agents:refresh",
-            suggested_fix_alt: "task upgrade",
+            suggested_fix_alt: "deft update",
         },
     };
 }
@@ -111,7 +111,7 @@ export function checkManifestAgreement(projectRoot, installRoot, seams = {}) {
             return {
                 name: "manifest-agreement",
                 status: "fail",
-                detail: `Two install manifests disagree: .deft/core/VERSION (tag='${coreVer}') vs legacy .deft/VERSION (tag='${legacyVer}'). The canonical manifest is .deft/core/VERSION -- run \`task upgrade\` to migrate the stale .deft/VERSION (backed up as .deft/VERSION.premigrate). See UPGRADING.md for the canonical drift-repair walkthrough.`,
+                detail: `Two install manifests disagree: .deft/core/VERSION (tag='${coreVer}') vs legacy .deft/VERSION (tag='${legacyVer}'). The canonical manifest is .deft/core/VERSION -- run \`deft update\` to migrate the stale .deft/VERSION (backed up as .deft/VERSION.premigrate). See UPGRADING.md for the canonical drift-repair walkthrough.`,
                 data: {
                     dual_manifest_drift: true,
                     core_manifest_path: coreManifest,
@@ -119,7 +119,7 @@ export function checkManifestAgreement(projectRoot, installRoot, seams = {}) {
                     core_version: coreVer,
                     legacy_version: legacyVer,
                     authoritative: "manifest",
-                    suggested_fix: "task upgrade",
+                    suggested_fix: "deft update",
                 },
             };
         }
@@ -149,13 +149,13 @@ export function checkManifestAgreement(projectRoot, installRoot, seams = {}) {
         return {
             name: "manifest-agreement",
             status: "fail",
-            detail: `Bare .deft-version exists at ${barePath} but YAML manifest is missing at ${expectedManifestPath}. Run \`task upgrade\` to write the canonical manifest (#1046 PR-B AC-4). See UPGRADING.md for the v0.27.x -> v0.28 transition walkthrough.`,
+            detail: `Bare .deft-version exists at ${barePath} but YAML manifest is missing at ${expectedManifestPath}. Run \`deft update\` to write the canonical manifest (#1046 PR-B AC-4). See UPGRADING.md for the v0.27.x -> v0.28 transition walkthrough.`,
             data: {
                 manifest_path: manifestPath,
                 expected_manifest_path: expectedManifestPath,
                 bare_path: barePath,
                 bare_value: bareText?.trim() ?? null,
-                suggested_fix: "task upgrade",
+                suggested_fix: "deft update",
             },
         };
     }
@@ -165,7 +165,7 @@ export function checkManifestAgreement(projectRoot, installRoot, seams = {}) {
         return {
             name: "manifest-agreement",
             status: "pass",
-            detail: `YAML manifest at ${manifestPath} present; bare .deft-version absent (derived value: '${derived}' from manifest tag). Run \`task upgrade\` to regenerate the derivative.`,
+            detail: `YAML manifest at ${manifestPath} present; bare .deft-version absent (derived value: '${derived}' from manifest tag). Run \`deft update\` to regenerate the derivative.`,
             data: {
                 manifest_path: manifestPath,
                 manifest,
@@ -205,14 +205,14 @@ export function checkManifestAgreement(projectRoot, installRoot, seams = {}) {
     return {
         name: "manifest-agreement",
         status: "fail",
-        detail: `Drift detected: YAML manifest tag='${derived}' does NOT agree with bare .deft-version='${bareValue}'. Per #1046 PR-B AC-4 the YAML manifest is the canonical source -- run \`task upgrade\` to regenerate the bare derivative from the manifest, OR manually update ${manifestPath} if the bare value is correct. See UPGRADING.md for the canonical drift-repair walkthrough.`,
+        detail: `Drift detected: YAML manifest tag='${derived}' does NOT agree with bare .deft-version='${bareValue}'. Per #1046 PR-B AC-4 the YAML manifest is the canonical source -- run \`deft update\` to regenerate the bare derivative from the manifest, OR manually update ${manifestPath} if the bare value is correct. See UPGRADING.md for the canonical drift-repair walkthrough.`,
         data: {
             manifest_path: manifestPath,
             bare_path: barePath,
             derived_version: derived,
             bare_value: bareValue,
             authoritative: "manifest",
-            suggested_fix: "task upgrade",
+            suggested_fix: "deft update",
         },
     };
 }

package/dist/doctor/constants.d.ts

@@ -18,6 +18,8 @@ export declare const DEFT_REPO_POSITIVE_MARKERS: readonly ["content/templates/ag
 export declare const EXPECTED_CONTENT_DIRS: readonly ["languages", "strategies", "skills", "templates"];
 /** Post-freeze canonical upgrade path (#1997 / #2003 / #1912). */
 export declare const CANONICAL_UPGRADE_COMMAND = "npm i -g @deftai/directive@latest";
+/** Vendored npm-managed deposit: global bump plus in-place `.deft/core/` refresh (#2115). */
+export declare const VENDORED_NPM_DEPOSIT_UPGRADE_COMMAND = "npm i -g @deftai/directive@latest && deft update";
 export declare const CLEAN_WINDOW_HOURS = 24;
 export declare const DIRTY_WINDOW_HOURS = 4;
 export declare const ENV_STATE_PATH = "DEFT_DOCTOR_STATE_PATH";

package/dist/doctor/constants.js

@@ -60,6 +60,8 @@ export const DEFT_REPO_POSITIVE_MARKERS = [
 export const EXPECTED_CONTENT_DIRS = ["languages", "strategies", "skills", "templates"];
 /** Post-freeze canonical upgrade path (#1997 / #2003 / #1912). */
 export const CANONICAL_UPGRADE_COMMAND = "npm i -g @deftai/directive@latest";
+/** Vendored npm-managed deposit: global bump plus in-place `.deft/core/` refresh (#2115). */
+export const VENDORED_NPM_DEPOSIT_UPGRADE_COMMAND = `${CANONICAL_UPGRADE_COMMAND} && deft update`;
 export const CLEAN_WINDOW_HOURS = 24;
 export const DIRTY_WINDOW_HOURS = 4;
 export const ENV_STATE_PATH = "DEFT_DOCTOR_STATE_PATH";

package/dist/doctor/payload-staleness.js

@@ -1,6 +1,7 @@
 import { spawnSync } from "node:child_process";
 import { dirname, join } from "node:path";
-import { CANONICAL_UPGRADE_COMMAND, NPM_PACKAGE_NAME } from "./constants.js";
+import { detectCanonicalVendoredManifest, isNpmManaged } from "../init-deposit/migrate.js";
+import { CANONICAL_UPGRADE_COMMAND, NPM_PACKAGE_NAME, VENDORED_NPM_DEPOSIT_UPGRADE_COMMAND, } from "./constants.js";
 import { locateManifest, parseInstallManifest } from "./manifest.js";
 import { readTextSafe, resolveDefaultFrameworkRoot } from "./paths.js";
 function isDeftFrameworkRepo(projectRoot, readText = readTextSafe) {
@@ -91,9 +92,16 @@ function emitUnverified(checkName, reason, sink, addFinding) {
         status: "unverified",
     });
 }
-function emitStale(checkName, installedLabel, remoteLabel, ref, sink, addFinding, extras = {}, behindWord = "remote") {
+function resolveUpgradeCommand(projectRoot, manifest, isFile) {
+    const vendoredManifest = detectCanonicalVendoredManifest(projectRoot, isFile);
+    if (vendoredManifest !== null && isNpmManaged(manifest)) {
+        return VENDORED_NPM_DEPOSIT_UPGRADE_COMMAND;
+    }
+    return CANONICAL_UPGRADE_COMMAND;
+}
+function emitStale(checkName, installedLabel, remoteLabel, ref, upgradeCommand, sink, addFinding, extras = {}, behindWord = "remote") {
     const msg = `Framework payload is stale (installed ${installedLabel} behind ${behindWord} ${remoteLabel} for ref '${ref}'). ` +
-        `Recommendation: run \`${CANONICAL_UPGRADE_COMMAND}\` from any shell with Node ≥ 20.`;
+        `Recommendation: run \`${upgradeCommand}\` from any shell with Node ≥ 20.`;
     sink.warn(msg);
     addFinding({
         severity: "warning",
@@ -101,7 +109,7 @@ function emitStale(checkName, installedLabel, remoteLabel, ref, sink, addFinding
         check: checkName,
         status: "stale",
         ref,
-        suggestion: CANONICAL_UPGRADE_COMMAND,
+        suggestion: upgradeCommand,
         ...extras,
     });
 }
@@ -155,6 +163,7 @@ export function runPayloadStalenessCheck(projectRoot, sink, addFinding, seams =
         return;
     }
     const manifest = parseInstallManifest(text);
+    const upgradeCommand = resolveUpgradeCommand(projectRoot, manifest, isFile);
     const installedSha = (manifest.sha ?? "").trim();
     const ref = (manifest.ref ?? manifest.tag ?? "").trim();
     const tag = (manifest.tag ?? "").trim();
@@ -204,7 +213,7 @@ export function runPayloadStalenessCheck(projectRoot, sink, addFinding, seams =
                 sink.info(`${checkName}: current (sha matches remote)`);
                 return;
             }
-            emitStale(checkName, `sha ${installedSha.slice(0, 8)}...`, `sha ${remoteSha.slice(0, 8)}...`, ref, sink, addFinding, { installed_sha: installedSha, remote_sha: remoteSha, resolver: "git-ls-remote" });
+            emitStale(checkName, `sha ${installedSha.slice(0, 8)}...`, `sha ${remoteSha.slice(0, 8)}...`, ref, upgradeCommand, sink, addFinding, { installed_sha: installedSha, remote_sha: remoteSha, resolver: "git-ls-remote" });
             return;
         }
     }
@@ -212,7 +221,7 @@ export function runPayloadStalenessCheck(projectRoot, sink, addFinding, seams =
     const installedVersion = manifestVersion(ref, tag);
     if (npmResult.ok && installedVersion) {
         if (semverLessThan(installedVersion, npmResult.version)) {
-            emitStale(checkName, `v${installedVersion}`, `v${npmResult.version}`, ref, sink, addFinding, {
+            emitStale(checkName, `v${installedVersion}`, `v${npmResult.version}`, ref, upgradeCommand, sink, addFinding, {
                 installed_version: installedVersion,
                 remote_version: npmResult.version,
                 resolver: "npm-view",

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

@@ -0,0 +1,55 @@
+/**
+ * forward-coverage/evaluate.ts -- deterministic forward-coverage gate (#1310).
+ *
+ * Migrates the prose-tier "new source files MUST include corresponding test
+ * files in the same PR" rule (AGENTS.md) to deterministic enforcement,
+ * mirroring `verify:encoding` (#798) and `verify:branch` (#747).
+ *
+ * Behaviour (v1 = NEW-file granularity only, to keep false positives near
+ * zero): read the staged (`--staged`) or HEAD-relative diff; for each NEW
+ * source file (`*.py` / `*.go` / `*.ts` / `*.tsx`, excluding test files and
+ * `*.d.ts`), assert a corresponding test file was added in the SAME diff.
+ * Three-state exit: 0 clean / 1 missing forward coverage / 2 config error.
+ */
+/** Diff scope: `staged` = index vs HEAD; `head` = working tree + index vs HEAD. */
+export type ForwardCoverageMode = "head" | "staged";
+/** A new source file that has no corresponding test file in the same diff. */
+export interface MissingCoverage {
+    /** POSIX-form repo-relative path of the uncovered new source file. */
+    readonly path: string;
+    /** Candidate test-file basenames the gate searched the diff for. */
+    readonly expectedTests: string[];
+}
+/** Result of a forward-coverage evaluation; mirrors the encoding-gate tuple. */
+export interface ForwardCoverageResult {
+    readonly exitCode: 0 | 1 | 2;
+    readonly missing: MissingCoverage[];
+    readonly message: string;
+}
+export interface ForwardCoverageOptions {
+    readonly mode?: ForwardCoverageMode;
+    readonly allowListPath?: string | null;
+}
+/**
+ * True when `relPath` is a test file (excluded from the "needs coverage" set
+ * AND counted as available coverage). Covers the co-located TS/TSX
+ * `.test` / `.spec` convention, Go `*_test.go`, and Python `test_*.py` /
+ * `*_test.py`.
+ */
+export declare function isTestFile(relPath: string): boolean;
+/** True when `relPath` is an in-scope, non-test, non-`.d.ts` source file. */
+export declare function isSourceFile(relPath: string): boolean;
+/**
+ * Candidate test-file basenames that would satisfy forward coverage for a
+ * given source file, keyed on its extension + stem. Matched by basename
+ * (directory-agnostic) so co-located, `tests/`, and `__tests__/` layouts all
+ * count -- keeping the false-positive rate near zero for v1.
+ */
+export declare function expectedTestBasenames(sourcePath: string): string[];
+/**
+ * Pure evaluation returning `{ exitCode, missing, message }`. Three-state exit
+ * (0 clean / 1 missing forward coverage / 2 config error). Mirrors the shape of
+ * `encoding.evaluate` (#798) so both gates read the same way.
+ */
+export declare function evaluateForwardCoverage(projectRoot: string, options?: ForwardCoverageOptions): ForwardCoverageResult;
+//# sourceMappingURL=evaluate.d.ts.map

package/dist/forward-coverage/evaluate.js

@@ -0,0 +1,254 @@
+/**
+ * forward-coverage/evaluate.ts -- deterministic forward-coverage gate (#1310).
+ *
+ * Migrates the prose-tier "new source files MUST include corresponding test
+ * files in the same PR" rule (AGENTS.md) to deterministic enforcement,
+ * mirroring `verify:encoding` (#798) and `verify:branch` (#747).
+ *
+ * Behaviour (v1 = NEW-file granularity only, to keep false positives near
+ * zero): read the staged (`--staged`) or HEAD-relative diff; for each NEW
+ * source file (`*.py` / `*.go` / `*.ts` / `*.tsx`, excluding test files and
+ * `*.d.ts`), assert a corresponding test file was added in the SAME diff.
+ * Three-state exit: 0 clean / 1 missing forward coverage / 2 config error.
+ */
+import { spawnSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { basename } from "node:path";
+import { GitCommandError, GitNotFoundError } from "../encoding/git.js";
+import { fnmatchCase } from "../encoding/text.js";
+/** Source-file extensions in scope for v1. */
+const SOURCE_EXTENSIONS = new Set([".py", ".go", ".ts", ".tsx"]);
+/** Raised by `loadAllowList` when the path does not exist. */
+class AllowListNotFoundError extends Error {
+}
+/** Return the final `.ext` (lowercased) of a path, or "" when none. */
+function extOf(pathStr) {
+    const b = basename(pathStr);
+    const dot = b.lastIndexOf(".");
+    return dot > 0 ? b.slice(dot).toLowerCase() : "";
+}
+/**
+ * True when `relPath` is a test file (excluded from the "needs coverage" set
+ * AND counted as available coverage). Covers the co-located TS/TSX
+ * `.test` / `.spec` convention, Go `*_test.go`, and Python `test_*.py` /
+ * `*_test.py`.
+ */
+export function isTestFile(relPath) {
+    const b = basename(relPath).toLowerCase();
+    if (b.endsWith(".test.ts") ||
+        b.endsWith(".test.tsx") ||
+        b.endsWith(".spec.ts") ||
+        b.endsWith(".spec.tsx")) {
+        return true;
+    }
+    if (b.endsWith("_test.go")) {
+        return true;
+    }
+    if (b.endsWith(".py") && (b.startsWith("test_") || b.endsWith("_test.py"))) {
+        return true;
+    }
+    return false;
+}
+/** True when `relPath` is an in-scope, non-test, non-`.d.ts` source file. */
+export function isSourceFile(relPath) {
+    const b = basename(relPath).toLowerCase();
+    if (b.endsWith(".d.ts")) {
+        return false;
+    }
+    if (!SOURCE_EXTENSIONS.has(extOf(b))) {
+        return false;
+    }
+    return !isTestFile(relPath);
+}
+/**
+ * Candidate test-file basenames that would satisfy forward coverage for a
+ * given source file, keyed on its extension + stem. Matched by basename
+ * (directory-agnostic) so co-located, `tests/`, and `__tests__/` layouts all
+ * count -- keeping the false-positive rate near zero for v1.
+ */
+export function expectedTestBasenames(sourcePath) {
+    const b = basename(sourcePath);
+    const ext = extOf(b);
+    const stem = b.slice(0, b.length - ext.length);
+    switch (ext) {
+        case ".ts":
+            return [`${stem}.test.ts`, `${stem}.spec.ts`];
+        case ".tsx":
+            return [`${stem}.test.tsx`, `${stem}.spec.tsx`, `${stem}.test.ts`, `${stem}.spec.ts`];
+        case ".py":
+            return [`test_${stem}.py`, `${stem}_test.py`];
+        case ".go":
+            return [`${stem}_test.go`];
+        default:
+            return [];
+    }
+}
+function loadAllowList(path) {
+    if (path === null || path === undefined) {
+        return [];
+    }
+    let raw;
+    try {
+        raw = readFileSync(path, "utf8");
+    }
+    catch (err) {
+        const e = err;
+        if (e.code === "ENOENT") {
+            throw new AllowListNotFoundError(path);
+        }
+        throw err;
+    }
+    const out = [];
+    for (const line of raw.split(/\r\n|[\n\r]/)) {
+        const stripped = line.trim();
+        if (stripped.length === 0 || stripped.startsWith("#")) {
+            continue;
+        }
+        out.push(stripped);
+    }
+    return out;
+}
+function isAllowListed(relPath, patterns) {
+    return patterns.some((pat) => fnmatchCase(relPath, pat));
+}
+/** Run `git` and return its status + stdout, mapping ENOENT to GitNotFoundError. */
+function git(args, projectRoot) {
+    const result = spawnSync("git", args, {
+        cwd: projectRoot,
+        encoding: "utf8",
+        stdio: ["ignore", "pipe", "pipe"],
+    });
+    if (result.error !== undefined) {
+        const e = result.error;
+        if (e.code === "ENOENT") {
+            throw new GitNotFoundError("'git' executable not found on PATH");
+        }
+        throw new GitCommandError(`git ${args.join(" ")} failed: ${String(e.message)}`);
+    }
+    return { status: result.status ?? 1, stdout: result.stdout ?? "" };
+}
+/** Run `git`, throwing GitCommandError on any non-zero exit; returns stdout. */
+function gitOrThrow(args, projectRoot) {
+    const { status, stdout } = git(args, projectRoot);
+    if (status !== 0) {
+        throw new GitCommandError(`git ${args.join(" ")} exited ${status}`);
+    }
+    return stdout;
+}
+function toLines(stdout) {
+    return stdout
+        .split("\n")
+        .map((l) => l.replace(/\r$/, ""))
+        .filter((l) => l.trim().length > 0);
+}
+/**
+ * Enumerate files ADDED in the diff scope, as POSIX-form rel paths.
+ *
+ * - `staged`: `git diff --cached --diff-filter=A` (index vs HEAD).
+ * - `head`: files added vs HEAD (`git diff --diff-filter=A HEAD`) plus
+ *   untracked-but-not-ignored files (`git ls-files --others`). When the repo
+ *   has no commits yet, every tracked file counts as added.
+ */
+function addedFiles(projectRoot, mode) {
+    // Confirm we are inside a work tree; a non-repo path raises exit 2 upstream.
+    const inside = git(["rev-parse", "--is-inside-work-tree"], projectRoot);
+    if (inside.status !== 0) {
+        throw new GitCommandError("not a git working tree");
+    }
+    if (mode === "staged") {
+        return toLines(gitOrThrow(["diff", "--cached", "--name-only", "--diff-filter=A"], projectRoot));
+    }
+    const added = new Set();
+    const hasHead = git(["rev-parse", "--verify", "-q", "HEAD"], projectRoot).status === 0;
+    if (hasHead) {
+        for (const f of toLines(gitOrThrow(["diff", "--name-only", "--diff-filter=A", "HEAD"], projectRoot))) {
+            added.add(f);
+        }
+    }
+    else {
+        for (const f of toLines(gitOrThrow(["ls-files"], projectRoot))) {
+            added.add(f);
+        }
+    }
+    for (const f of toLines(gitOrThrow(["ls-files", "--others", "--exclude-standard"], projectRoot))) {
+        added.add(f);
+    }
+    return [...added];
+}
+function configError(message) {
+    return { exitCode: 2, missing: [], message };
+}
+/**
+ * Pure evaluation returning `{ exitCode, missing, message }`. Three-state exit
+ * (0 clean / 1 missing forward coverage / 2 config error). Mirrors the shape of
+ * `encoding.evaluate` (#798) so both gates read the same way.
+ */
+export function evaluateForwardCoverage(projectRoot, options = {}) {
+    const mode = options.mode ?? "head";
+    if (mode !== "head" && mode !== "staged") {
+        return configError(`verify_forward_coverage: unrecognised mode '${mode}' (expected 'head' or 'staged').`);
+    }
+    let allowGlobs;
+    try {
+        allowGlobs = loadAllowList(options.allowListPath);
+    }
+    catch (err) {
+        if (err instanceof AllowListNotFoundError) {
+            return configError(`verify_forward_coverage: --allow-list file not found: ${err.message}\n` +
+                "  Recovery: pass an existing path or omit the flag.");
+        }
+        return configError(`verify_forward_coverage: --allow-list unreadable: ${String(err.message)}\n` +
+            "  Recovery: check file permissions.");
+    }
+    let added;
+    try {
+        added = addedFiles(projectRoot, mode);
+    }
+    catch (err) {
+        if (err instanceof GitNotFoundError) {
+            return configError("verify_forward_coverage: 'git' executable not found on PATH.\n" +
+                "  Recovery: install git or run inside a git working tree.");
+        }
+        if (err instanceof GitCommandError) {
+            return configError(`verify_forward_coverage: git failed -- ${err.message}\n` +
+                "  Recovery: ensure --project-root points at a git working tree.");
+        }
+        throw err;
+    }
+    const posixAdded = added.map((p) => p.replace(/\\/g, "/"));
+    const testBasenames = new Set(posixAdded.filter((p) => isTestFile(p)).map((p) => basename(p)));
+    const missing = [];
+    let checked = 0;
+    for (const rel of posixAdded) {
+        if (!isSourceFile(rel)) {
+            continue;
+        }
+        if (isAllowListed(rel, allowGlobs)) {
+            continue;
+        }
+        checked += 1;
+        const expected = expectedTestBasenames(rel);
+        const covered = expected.some((name) => testBasenames.has(name));
+        if (!covered) {
+            missing.push({ path: rel, expectedTests: expected });
+        }
+    }
+    if (missing.length > 0) {
+        const header = `verify_forward_coverage: ${missing.length} new source file(s) added without a ` +
+            "corresponding test in the same diff (#1310).\n" +
+            "  Rule: a new source file MUST ship with a test in the SAME diff -- running existing\n" +
+            "  tests alone does not satisfy forward coverage. Add a co-located test (e.g. <name>.test.ts,\n" +
+            "  <name>_test.go, test_<name>.py) or allow-list a documented exception via --allow-list <path>.";
+        const body = missing
+            .map((m) => `  ${m.path}\n    expected one of: ${m.expectedTests.join(", ")}`)
+            .join("\n");
+        return { exitCode: 1, missing, message: `${header}\n${body}` };
+    }
+    return {
+        exitCode: 0,
+        missing,
+        message: `verify_forward_coverage: ${checked} new source file(s) checked -- ` +
+            "all have forward coverage in the diff (#1310).",
+    };
+}
+//# sourceMappingURL=evaluate.js.map

package/dist/index.d.ts

@@ -15,6 +15,7 @@ export * as capacity from "./capacity/index.js";
 export * as codebase from "./codebase/index.js";
 export * as doctor from "./doctor/index.js";
 export * from "./encoding/index.js";
+export * from "./forward-coverage/evaluate.js";
 export * as intake from "./intake/index.js";
 export * as layout from "./layout/index.js";
 export * as legacyBridge from "./legacy-bridge/index.js";

package/dist/index.js

@@ -15,6 +15,7 @@ export * as capacity from "./capacity/index.js";
 export * as codebase from "./codebase/index.js";
 export * as doctor from "./doctor/index.js";
 export * from "./encoding/index.js";
+export * from "./forward-coverage/evaluate.js";
 export * as intake from "./intake/index.js";
 export * as layout from "./layout/index.js";
 export * as legacyBridge from "./legacy-bridge/index.js";

package/dist/init-deposit/constants.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Neutral leaf constants for the init-deposit surface.
+ *
+ * Kept dependency-free so both `scaffold.ts` and `hygiene.ts` can import the
+ * canonical install root without completing a module dependency cycle
+ * (scaffold needs hygiene's allowlist ERE; hygiene needs the install root).
+ */
+/** Canonical vendored framework install root, relative to the project root. */
+export declare const CANONICAL_INSTALL_ROOT = ".deft/core";
+/** Minimal output sink shared by the init-deposit surface. */
+export interface InitDepositIo {
+    printf: (text: string) => void;
+}
+//# sourceMappingURL=constants.d.ts.map

package/dist/init-deposit/constants.js

@@ -0,0 +1,10 @@
+/**
+ * Neutral leaf constants for the init-deposit surface.
+ *
+ * Kept dependency-free so both `scaffold.ts` and `hygiene.ts` can import the
+ * canonical install root without completing a module dependency cycle
+ * (scaffold needs hygiene's allowlist ERE; hygiene needs the install root).
+ */
+/** Canonical vendored framework install root, relative to the project root. */
+export const CANONICAL_INSTALL_ROOT = ".deft/core";
+//# sourceMappingURL=constants.js.map