@deftai/directive-core 0.66.2 → 0.68.0

package/dist/doctor/flags.js

@@ -5,6 +5,7 @@ export function parseDoctorFlags(args) {
     let json = false;
     let quiet = false;
     let full = false;
+    let network = false;
     let help = false;
     let projectRoot = null;
     const unknown = [];
@@ -26,6 +27,9 @@ export function parseDoctorFlags(args) {
         else if (token === "--full") {
             full = true;
         }
+        else if (token === "--network") {
+            network = true;
+        }
         else if (token === "-h" || token === "--help") {
             help = true;
         }
@@ -52,7 +56,7 @@ export function parseDoctorFlags(args) {
         }
         i += 1;
     }
-    return { session, fix, json, quiet, full, help, projectRoot, unknown };
+    return { session, fix, json, quiet, full, network, help, projectRoot, unknown };
 }
 export function formatUnknownFlagsError(unknown) {
     return `Unknown flag(s): ${unknown.join(", ")}`;

package/dist/doctor/main.js

@@ -1,9 +1,10 @@
 import { existsSync, readFileSync, statSync, writeFileSync } from "node:fs";
 import { join, resolve } from "node:path";
+import { evaluate as evaluateAgentsMdAdvisory } from "../agents-md-advisory/evaluate.js";
 import { contentRoot } from "../content-root.js";
 import { agentsRefreshPlan, hasV3ManagedMarker } from "./agents-md.js";
 import { runChecks } from "./checks.js";
-import { CONSUMER_FRAMEWORK_DIRS, EXPECTED_CONTENT_DIRS, EXPECTED_FRAMEWORK_DIRS, TASKFILE_INCLUDE_SNIPPET, UV_INSTALL_URL, } from "./constants.js";
+import { CONSUMER_FRAMEWORK_DIRS, EXPECTED_CONTENT_DIRS, EXPECTED_FRAMEWORK_DIRS, NETWORK_DISCLOSURE_LINE, PAYLOAD_STALENESS_OFFLINE_SKIP_MESSAGE, TASKFILE_INCLUDE_SNIPPET, UV_INSTALL_URL, } from "./constants.js";
 import { decideThrottle, formatIsoZ, readState, renderDoctorStatusLine, writeState, } from "./doctor-state.js";
 import { formatAllowedFlagsHint, formatUnknownFlagsError, parseDoctorFlags } from "./flags.js";
 import { pythonJsonDump } from "./json.js";
@@ -130,13 +131,38 @@ export function cmdDoctor(args, seams = {}) {
     if (!jsonMode) {
         sink.blank();
     }
-    sink.info("Checking payload staleness from install manifest...");
-    runPayloadStalenessCheck(projectRoot, sink, addFinding, {
-        frameworkRoot,
-        readText: seams.readText,
-        isFile: seams.isFile,
-        runGitLsRemote: seams.runGitLsRemote,
-    });
+    sink.info("Checking AGENTS.md legibility (advisory)...");
+    runAgentsMdAdvisoryCheck(projectRoot, sink, addFinding, seams);
+    if (!jsonMode) {
+        sink.blank();
+    }
+    // #2182: payload-staleness is the only doctor check that can reach a
+    // registry (git remote, then npm as a fallback). It stays in the OFFLINE
+    // tier (skipped) unless the operator explicitly opts into the NETWORK tier
+    // via `--network`, and the tool + registry class is disclosed BEFORE the
+    // check runs -- never silently, never as a side effect of a read-only
+    // `deft doctor` invocation (e.g. from the gated session-ritual step).
+    if (flags.network) {
+        sink.info(NETWORK_DISCLOSURE_LINE);
+        sink.info("Checking payload staleness from install manifest...");
+        runPayloadStalenessCheck(projectRoot, sink, addFinding, {
+            frameworkRoot,
+            readText: seams.readText,
+            isFile: seams.isFile,
+            runGitLsRemote: seams.runGitLsRemote,
+            runNpmViewVersion: seams.runNpmViewVersion,
+        });
+    }
+    else {
+        sink.info(`payload-staleness: ${PAYLOAD_STALENESS_OFFLINE_SKIP_MESSAGE}`);
+        addFinding({
+            severity: "skip",
+            message: PAYLOAD_STALENESS_OFFLINE_SKIP_MESSAGE,
+            check: "payload-staleness",
+            status: "skip",
+            reason: "offline-tier",
+        });
+    }
     if (!jsonMode) {
         sink.blank();
     }
@@ -346,6 +372,71 @@ function runAgentsMdFreshnessCheck(projectRoot, sink, addFinding, seams) {
         addFinding({ severity: "warning", message, check: checkName });
     }
 }
+/**
+ * Advisory (never-failing) consumer AGENTS.md legibility signal (#2155).
+ *
+ * Reports the unmanaged (project-authored) region size against the soft budget
+ * (`plan.policy.agentsMdAdvisory.unmanagedSoftMaxLines`, generous by default).
+ * The managed section is EXCLUDED. This is the consumer companion to the
+ * maintainer-only #645 ratchet and follows the advise -> observe -> enforce
+ * posture (#1419): it emits at most a `warning` finding, NEVER an `error`, so
+ * `deft doctor` (and the `check:consumer` aggregate that depends on it) can
+ * never fail-close on a judgment call about the consumer's own file.
+ */
+function runAgentsMdAdvisoryCheck(projectRoot, sink, addFinding, seams) {
+    const checkName = "agents-md-advisory";
+    // Only meaningful for consumer installs (managed markers present). In the
+    // maintainer repo the #645 ratchet owns this file, so skip -- mirrors the
+    // freshness check's guard above.
+    if (runningInsideDeftRepo(projectRoot, seams) ||
+        !hasV3ManagedMarker(projectRoot, seams.readText)) {
+        const skipReason = "no managed-section markers (likely maintainer repo)";
+        sink.info(`${checkName}: skip -- ${skipReason}`);
+        addFinding({ severity: "skip", message: skipReason, check: checkName, status: "skip" });
+        return;
+    }
+    try {
+        const evalFn = seams.agentsMdAdvisoryEvaluate ?? ((root) => evaluateAgentsMdAdvisory(root));
+        const result = evalFn(projectRoot);
+        if (result.over && result.counts !== null) {
+            const message = `AGENTS.md unmanaged (project-authored) region is ${result.counts.unmanaged} lines, ` +
+                `over the soft budget of ${result.softMaxLines} (advisory only -- your build is NOT ` +
+                "affected). AGENTS.md is a map, not a manual (#1882): push detail into a reference doc " +
+                "and leave a pointer (see content/docs/good-agents-md.md). Raise " +
+                "plan.policy.agentsMdAdvisory.unmanagedSoftMaxLines to accept the growth and silence this.";
+            sink.warn(message);
+            addFinding({
+                severity: "warning",
+                message,
+                check: checkName,
+                status: "over-soft-budget",
+                suggestion: "content/docs/good-agents-md.md",
+            });
+            return;
+        }
+        if (result.counts !== null) {
+            sink.success(`${checkName}: unmanaged region ${result.counts.unmanaged}/${result.softMaxLines} lines (within soft budget)`);
+            return;
+        }
+        // No counts (missing / unreadable / malformed AGENTS.md): advisory stays
+        // silent-but-informational; never a doctor error.
+        sink.info(`${checkName}: skip -- AGENTS.md not measurable`);
+        addFinding({
+            severity: "skip",
+            message: "AGENTS.md not measurable",
+            check: checkName,
+            status: "skip",
+        });
+    }
+    catch (exc) {
+        // Sanitize newlines so an error string can't break out of the markdown
+        // bullet when findings are rendered (CWE-116).
+        const detail = `${exc instanceof Error ? exc.name : "Error"}: ${exc}`.replace(/\r?\n/g, " ");
+        const message = `${checkName}: probe failed -- ${detail}`;
+        sink.warn(message);
+        addFinding({ severity: "warning", message, check: checkName });
+    }
+}
 function runTaskfileIncludeCheck(projectRoot, fixMode, jsonMode, sink, addFinding, seams) {
     if (runningInsideDeftRepo(projectRoot, seams)) {
         sink.info("Skipping Taskfile include check -- running inside the deft framework repo (the repo's own Taskfile.yml is the surface).");

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/doctor/types.d.ts

@@ -1,3 +1,4 @@
+import type { AdvisoryEvaluateResult } from "../agents-md-advisory/evaluate.js";
 export declare const EXIT_CLEAN = 0;
 export declare const EXIT_DRIFT = 1;
 export declare const EXIT_CONFIG_ERROR = 2;
@@ -30,6 +31,7 @@ export interface DoctorFlags {
     readonly json: boolean;
     readonly quiet: boolean;
     readonly full: boolean;
+    readonly network: boolean;
     readonly help: boolean;
     readonly projectRoot: string | null;
     readonly unknown: readonly string[];
@@ -60,7 +62,12 @@ export interface DoctorSeams {
         ok: boolean;
         stdout: string;
     };
+    readonly runNpmViewVersion?: () => {
+        ok: boolean;
+        version: string;
+    };
     readonly agentsRefreshPlan?: (projectRoot: string) => Record<string, unknown>;
+    readonly agentsMdAdvisoryEvaluate?: (projectRoot: string) => AdvisoryEvaluateResult;
     readonly readState?: (projectRoot: string) => DoctorState | null;
     readonly writeState?: (projectRoot: string, payload: {
         exitCode: number;

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

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

@@ -0,0 +1,50 @@
+/**
+ * Scoped staging + installer-managed allowlist for TS-native init/update (#1453).
+ *
+ * Mirrors cmd/deft-install/hygiene.go + deposit.go installerManagedMatchers.
+ * Refs #1576, #1453, #1430.
+ */
+import { type InitDepositIo } from "./constants.js";
+export declare const CODEQL_CONFIG_REL = ".github/codeql/codeql-config.yml";
+export declare const CORE_GUARD_WORKFLOW_REL = ".github/workflows/deft-core-guard.yml";
+export interface InstallerManagedMatcher {
+    readonly exact?: string;
+    readonly prefix?: string;
+}
+/** Single source of truth for installer-managed paths (#1440 / #1576). */
+export declare function installerManagedMatchers(): InstallerManagedMatcher[];
+/** POSIX ERE alternation embedded in the deposited deft-core-guard workflow. */
+export declare function installerManagedGuardEre(): string;
+export declare function isInstallerManagedPath(path: string): boolean;
+export interface FrameworkStagePathsOptions {
+    /**
+     * Include the project-root ``Taskfile.yml`` in the stage set. Defaults to
+     * ``false``: unlike the other allowlisted paths, ``Taskfile.yml`` is a
+     * consumer-owned file that merely *contains* an installer-managed include
+     * block, so it must only be staged when the installer actually wired that
+     * block this run -- otherwise an unrelated user edit would be silently
+     * ``git add``ed (#1576 review).
+     */
+    readonly includeTaskfile?: boolean;
+}
+export declare function frameworkStagePaths(projectDir: string, deftDir: string, options?: FrameworkStagePathsOptions): string[];
+export interface StageFrameworkPathsSeams {
+    gitPorcelain?: (projectRoot: string) => string | null;
+    runGitAdd?: (projectDir: string, paths: readonly string[]) => void;
+}
+/** Best-effort scoped `git add` — never fails the install/update (#1453 Layer 2b). */
+export declare function stageFrameworkPaths(projectDir: string, paths: readonly string[], seams?: StageFrameworkPathsSeams): {
+    staged: boolean;
+    error: Error | null;
+};
+export declare const COMMIT_HYGIENE_BRANCH_NAME = "chore/deft-framework-upgrade";
+export declare function printCommitGuidance(io: InitDepositIo, paths: readonly string[], staged: boolean): void;
+export interface DepositStagePathsOptions extends StageFrameworkPathsSeams, FrameworkStagePathsOptions {
+    readCachedNames?: (projectDir: string) => string[];
+}
+export declare function depositStagePaths(projectDir: string, options?: DepositStagePathsOptions): {
+    stagePaths: string[];
+    staged: boolean;
+    stagedPaths: string[];
+};
+//# sourceMappingURL=hygiene.d.ts.map