@deftai/directive-core 0.78.0 → 0.79.1

package/dist/session/cache-recovery.js

@@ -0,0 +1,26 @@
+import { formatFrameworkCommand } from "../render/framework-commands.js";
+const CACHE_FETCH_SOURCE = "github-issue";
+/**
+ * Format a consumer-runnable `deft cache fetch-all` recovery command (#2574).
+ *
+ * Uses the space-separated CLI surface (not the colon task alias) and always
+ * includes required `--source` / `--repo` flags so following the hint literally
+ * reaches the handler instead of `unknown verb 'cache:fetch-all'`.
+ */
+export function formatCacheFetchAllRecoveryCommand(repo, options = {}) {
+    const repoSlug = repo ?? "OWNER/NAME";
+    const args = ["cache", "fetch-all", "--source", CACHE_FETCH_SOURCE, "--repo", repoSlug];
+    if (options.force) {
+        args.push("--force");
+    }
+    return formatFrameworkCommand(args);
+}
+/**
+ * Branch-aware recovery hint (#1953 Option 3, #2574 argv fix).
+ * Age-stale (or age+drift mixed) → --force bypasses TTL; drift-only → plain refetch.
+ */
+export function recoveryHintForStaleFailure(causes, repo = null) {
+    const command = formatCacheFetchAllRecoveryCommand(repo, { force: causes.ageStale });
+    return `  Recovery: run \`${command}\` to refresh and reconcile upstream state.`;
+}
+//# sourceMappingURL=cache-recovery.js.map

package/dist/session/session-start.d.ts

@@ -1,3 +1,4 @@
+import { type EnvironmentContext } from "../platform/shell-context.js";
 import { type ResolveUserMdResult } from "../user-config/resolve-user-md.js";
 import type { GitRunner } from "./git.js";
 import { ritualStatePath } from "./ritual-sentinel.js";
@@ -40,6 +41,7 @@ export interface SessionStartOptions {
         exitCode: number;
     };
     readonly resolveUserMd?: (projectRoot: string) => ResolveUserMdResult;
+    readonly probeEnvironment?: () => EnvironmentContext;
 }
 export declare function parseDeferrals(rawValues: readonly string[]): {
     deferrals: Record<string, string>;

package/dist/session/session-start.js

@@ -2,6 +2,7 @@ import { randomUUID } from "node:crypto";
 import { runningInsideDeftRepo } from "../doctor/paths.js";
 import { emitSessionEvalReadback } from "../eval/readback.js";
 import { MIGRATE_COMPLETION_NUDGE, shouldEmitMigrateNudge } from "../init-deposit/migrate.js";
+import { detectEnvironmentContext, environmentContextToDict, formatEnvironmentContext, } from "../platform/shell-context.js";
 import { disclosureLine } from "../policy/disclosure.js";
 import { resolvePolicy } from "../policy/resolve.js";
 import { runDefaultMode } from "../triage/welcome/default-mode.js";
@@ -187,7 +188,7 @@ export function defaultBranchSync(projectRoot, runGit = defaultGitRunner) {
     }
     return { branch, upstream, ahead, behind, warning };
 }
-function runReadOnlySessionStart(projectRoot, options, instant) {
+function runReadOnlySessionStart(projectRoot, options, instant, environment) {
     const lines = [];
     const resolveUserMd = options.resolveUserMd ?? ((root) => resolveUserMdPath({ projectRoot: root }));
     const userMd = resolveUserMd(projectRoot);
@@ -198,6 +199,7 @@ function runReadOnlySessionStart(projectRoot, options, instant) {
         : safeDiagnostic;
     lines.push(READ_ONLY_ALIGNMENT_MESSAGE);
     lines.push(userMdLine);
+    lines.push(formatEnvironmentContext(environment));
     const resultPayload = {
         ready: true,
         exit_code: 0,
@@ -217,6 +219,7 @@ function runReadOnlySessionStart(projectRoot, options, instant) {
             found: userMd.found,
             diagnostic: userMd.diagnostic,
         },
+        environment: environmentContextToDict(environment),
         message: READ_ONLY_RESULT_MESSAGE,
     };
     return { code: 0, payload: resultPayload, lines };
@@ -226,16 +229,22 @@ export function runSessionStart(projectRoot, options = {}) {
     const instant = options.now ?? new Date();
     const deferrals = options.deferrals ?? {};
     const runGit = options.runGit ?? defaultGitRunner;
+    const environment = (options.probeEnvironment ?? detectEnvironmentContext)();
     if (posture === READ_ONLY_POSTURE) {
-        return runReadOnlySessionStart(projectRoot, options, instant);
+        return runReadOnlySessionStart(projectRoot, options, instant, environment);
     }
     const { head: gitHeadValue, error: gitError } = gitHead(projectRoot, runGit);
     if (gitHeadValue === null) {
         const payload = {
             ready: false,
+            environment: environmentContextToDict(environment),
             message: gitError ?? "could not resolve git HEAD",
         };
-        return { code: 2, payload, lines: [payload.message] };
+        return {
+            code: 2,
+            payload,
+            lines: [formatEnvironmentContext(environment), payload.message],
+        };
     }
     const quickSteps = recordDeferredSteps(QUICK_STEPS, deferrals, instant);
     const gatedSteps = recordDeferredSteps(GATED_STEPS, deferrals, instant);
@@ -265,6 +274,7 @@ export function runSessionStart(projectRoot, options = {}) {
         lines.push(message);
         lines.push(userMdLine);
     }
+    lines.push(formatEnvironmentContext(environment));
     if (!quickSteps.branch_policy) {
         const result = resolvePolicy(projectRoot);
         const message = disclosureLine(result);
@@ -377,6 +387,7 @@ export function runSessionStart(projectRoot, options = {}) {
             found: userMd.found,
             diagnostic: userMd.diagnostic,
         },
+        environment: environmentContextToDict(environment),
         message: code === 0 ? "session ritual recorded" : "session ritual failed",
     };
     return { code, payload: resultPayload, lines };

package/dist/session/verify-session-ritual.d.ts

@@ -1,5 +1,6 @@
 import { type GitRunner } from "./git.js";
 import { type DirectivePosture } from "./posture.js";
+export { formatCacheFetchAllRecoveryCommand, recoveryHintForStaleFailure, } from "./cache-recovery.js";
 export declare const ENV_SKIP = "DEFT_SESSION_RITUAL_SKIP";
 export { ENTRYPOINT_TIMEOUT_EXIT_CODE, ENTRYPOINT_TIMEOUT_SECONDS, } from "./ritual-entrypoint.js";
 export declare const GATED_ENTRYPOINT_COMMANDS: Readonly<Record<string, readonly string[]>>;

package/dist/session/verify-session-ritual.js

@@ -7,6 +7,7 @@ import { defaultRitualRunner } from "./ritual-entrypoint.js";
 import { readRitualState, ritualStatePath, ritualStep, writeRitualState, } from "./ritual-sentinel.js";
 import { GATED_STEPS, QUICK_STEPS } from "./session-start.js";
 import { resolveSessionRitualStalenessHours } from "./staleness.js";
+export { formatCacheFetchAllRecoveryCommand, recoveryHintForStaleFailure, } from "./cache-recovery.js";
 export const ENV_SKIP = "DEFT_SESSION_RITUAL_SKIP";
 export { ENTRYPOINT_TIMEOUT_EXIT_CODE, ENTRYPOINT_TIMEOUT_SECONDS, } from "./ritual-entrypoint.js";
 export const GATED_ENTRYPOINT_COMMANDS = {

package/dist/triage/welcome/default-mode.js

@@ -1,4 +1,5 @@
 import { resolve } from "node:path";
+import { ensureTriageCacheHydrated } from "../../cache/empty-populate.js";
 import { maybeSelfHealCache } from "../../cache/fetch.js";
 import { FIRST_TIME_NUDGE, INCOMPLETE_NUDGE_TEMPLATE } from "./constants.js";
 import { classifyOnboarding, detectPriorState } from "./prior-state.js";
@@ -32,6 +33,7 @@ export function runDefaultMode(projectRoot, options = {}) {
     };
     const heal = options.selfHealFn ??
         ((root) => {
+            ensureTriageCacheHydrated(resolve(root));
             maybeSelfHealCache(resolve(root));
         });
     heal(projectRoot);

package/dist/triage/welcome/onboard.js

@@ -1,5 +1,6 @@
 import { existsSync } from "node:fs";
 import { resolve } from "node:path";
+import { ensureTriageCacheHydrated } from "../../cache/empty-populate.js";
 import { maybeSelfHealCache } from "../../cache/fetch.js";
 import { resolveProjectDefinitionPath } from "../../layout/resolve.js";
 import { DEFAULT_WIP_CAP, SUBSCRIPTION_PRESETS, TRIAGE_SKILL_PATH } from "./constants.js";
@@ -57,6 +58,7 @@ export function runOnboardMode(projectRoot, options = {}) {
     }
     const heal = options.selfHealFn ??
         ((root) => {
+            ensureTriageCacheHydrated(resolve(root));
             maybeSelfHealCache(resolve(root));
         });
     heal(projectRoot);

package/dist/ts-check-lane/run-lane.d.ts

@@ -41,6 +41,11 @@ export interface RunTsLaneOptions {
     readonly runner?: LaneRunner;
     /** Injected sink for human-facing notices (defaults to stdout). */
     readonly out?: (message: string) => void;
+    /**
+     * Env used to resolve release coverage-debt before sanitizeTsLaneEnv strips
+     * DEFT_RELEASE_PREFLIGHT (#2618). Defaults to process.env.
+     */
+    readonly env?: NodeJS.ProcessEnv;
 }
 /** Windows command shims (.cmd/.bat) need a shell; native executables do not. */
 export declare function shouldUseShellForCommand(command: string, platform?: NodeJS.Platform): boolean;

package/dist/ts-check-lane/run-lane.js

@@ -20,6 +20,7 @@ import { spawnSync } from "node:child_process";
 import { existsSync } from "node:fs";
 import { posix, win32 } from "node:path";
 import { BRANCH_GATE_BYPASS_ENV, RELEASE_PREFLIGHT_ENV } from "../release/constants.js";
+import { resolveCoverageDebtIssue } from "../vitest-runner/coverage-debt.js";
 /** Release Step-5 vars that must not leak into vitest via inherited pnpm env (#2434). */
 const TS_LANE_POISON_ENV_KEYS = [BRANCH_GATE_BYPASS_ENV, RELEASE_PREFLIGHT_ENV];
 /**
@@ -96,12 +97,20 @@ export function runTsLane(projectRoot, options) {
     const { pnpm } = options;
     const runner = options.runner ?? defaultRunner;
     const out = options.out ?? ((message) => process.stdout.write(`${message}\n`));
+    // Resolve debt from the pre-sanitize env: sanitizeTsLaneEnv strips
+    // DEFT_RELEASE_PREFLIGHT (required for the env-based debt path), so forward
+    // --allow-coverage-debt=#N on the vitest argv instead (#2618 / #2573).
+    const debt = resolveCoverageDebtIssue([], options.env ?? process.env);
+    const debtIssue = debt.kind === "valid" ? debt.issue : null;
     if (!pnpm) {
         out(SKIP_NOTICE);
         return 0;
     }
     for (const command of LANE_COMMANDS) {
         const argv = [pnpm, ...command];
+        if (debtIssue !== null && command[1] === "test") {
+            argv.push("--", `--allow-coverage-debt=${debtIssue}`);
+        }
         const result = runner(argv, projectRoot);
         const code = result.status;
         // A null status means the child was terminated by a signal (SIGKILL / OOM /

package/dist/vbrief-reconcile/labels.d.ts

@@ -14,6 +14,9 @@ export interface ReconcileLabelsOptions {
     readonly repo?: string | null;
     readonly dryRun?: boolean;
     readonly client?: LabelClient;
+    /** Opt in to mutating issues outside the resolved project repo (#2601). */
+    readonly allowCrossRepo?: boolean;
+    readonly repoAllowlist?: readonly string[];
 }
 export declare function reconcileLabels(projectRoot: string, options?: ReconcileLabelsOptions): [number, ReconcileLabelsOutcome];
 export declare function renderLabelsReport(outcome: ReconcileLabelsOutcome): string;

package/dist/vbrief-reconcile/labels.js

@@ -4,6 +4,7 @@ import { hasArtifactSuffix, resolveLifecycleRoot, stripArtifactSuffix } from "..
 import { call } from "../scm/call.js";
 import { extractIssueRef } from "../triage/reconcile/parse-uri.js";
 import { depResolved, RESOLVED_FOLDERS } from "./graph.js";
+import { isRepoMutationAllowed } from "./repo-guard.js";
 import { allScopeIds, asStrList } from "./swarm-deps.js";
 export const SCAN_FOLDERS = ["proposed", "pending", "active"];
 export const MANAGED_LABELS = ["status:blocked", "epic", "status:tracker", "rfc"];
@@ -163,6 +164,19 @@ export function reconcileLabels(projectRoot, options = {}) {
                 ? metadata.swarm
                 : {};
             const desired = computeDesiredLabels(plan, hasUnresolvedDeps(swarm, knownIds));
+            // Guard before any SCM read so cross-repo refusal is explicit (#2601 / Greptile P1).
+            const mutateGate = isRepoMutationAllowed(effectiveRepo, root, {
+                allowCrossRepo: options.allowCrossRepo,
+                allowlist: options.repoAllowlist,
+                explicitRepo: options.repo ?? null,
+            });
+            if (!mutateGate.allowed) {
+                outcome.errors.push({
+                    story_id: storyId,
+                    message: mutateGate.reason ?? `refusing cross-repo mutation on ${effectiveRepo}`,
+                });
+                continue;
+            }
             let current;
             try {
                 current = client.fetchLabels(effectiveRepo, number);

package/dist/vbrief-reconcile/main.d.ts

@@ -7,6 +7,7 @@ export interface CliOptions {
     scenario?: string | null;
     all?: boolean;
     fixtureRoot?: string | null;
+    allowCrossRepo?: boolean;
 }
 export declare function usage(): void;
 export declare function runGraph(opts: CliOptions): number;

package/dist/vbrief-reconcile/main.js

@@ -28,6 +28,8 @@ function parseOptions(rest) {
         }
         else if (arg === "--force")
             opts.force = true;
+        else if (arg === "--allow-cross-repo")
+            opts.allowCrossRepo = true;
         else if (arg === "--dry-run")
             opts.dryRun = true;
         else if (arg === "--json")
@@ -46,7 +48,7 @@ function parseOptions(rest) {
     return opts;
 }
 export function usage() {
-    process.stderr.write("usage: vbrief-reconcile <graph|labels|umbrellas> [--project-root PATH] [--dry-run] [--json] [--force] [--repo OWNER/NAME]\n" +
+    process.stderr.write("usage: vbrief-reconcile <graph|labels|umbrellas> [--project-root PATH] [--dry-run] [--json] [--force] [--repo OWNER/NAME] [--allow-cross-repo]\n" +
         "       vbrief-reconcile parity --scenario NAME [--fixture-root PATH]\n" +
         "       vbrief-reconcile parity --all [--fixture-root PATH]\n");
 }
@@ -70,7 +72,11 @@ export function runGraph(opts) {
 }
 export function runLabels(opts) {
     const root = resolve(opts.projectRoot ?? ".");
-    const [code, outcome] = reconcileLabels(root, { repo: opts.repo, dryRun: opts.dryRun });
+    const [code, outcome] = reconcileLabels(root, {
+        repo: opts.repo,
+        dryRun: opts.dryRun,
+        allowCrossRepo: opts.allowCrossRepo,
+    });
     if (code === 2) {
         if (opts.json) {
             process.stdout.write(`${JSON.stringify({ error: "no vbrief/ directory found" })}\n`);
@@ -88,7 +94,11 @@ export function runLabels(opts) {
 }
 export function runUmbrellas(opts) {
     const root = resolve(opts.projectRoot ?? ".");
-    const [code, outcome] = reconcileUmbrellas(root, { repo: opts.repo, dryRun: opts.dryRun });
+    const [code, outcome] = reconcileUmbrellas(root, {
+        repo: opts.repo,
+        dryRun: opts.dryRun,
+        allowCrossRepo: opts.allowCrossRepo,
+    });
     if (code === 2) {
         if (opts.json) {
             process.stdout.write(`${JSON.stringify({ error: "no vbrief/ directory found" })}\n`);

package/dist/vbrief-reconcile/parity-scenarios.js

@@ -291,7 +291,11 @@ export function runParityScenario(name, options) {
                 ],
             });
             const client = options.labelClient ?? new MemoryLabelClient();
-            const [code, outcome] = reconcileLabels(root, { client, dryRun: true });
+            const [code, outcome] = reconcileLabels(root, {
+                client,
+                dryRun: true,
+                repo: "deftai/directive",
+            });
             return {
                 scenario: name,
                 ok: true,
@@ -314,7 +318,11 @@ export function runParityScenario(name, options) {
                 ],
             });
             const client = options.labelClient ?? new MemoryLabelClient();
-            const [code, outcome] = reconcileLabels(root, { client, dryRun: true });
+            const [code, outcome] = reconcileLabels(root, {
+                client,
+                dryRun: true,
+                repo: "deftai/directive",
+            });
             return {
                 scenario: name,
                 ok: true,
@@ -342,6 +350,7 @@ export function runParityScenario(name, options) {
                 client,
                 dryRun: true,
                 now: FIXED_NOW.toISOString().replace(/\.\d{3}Z$/, "Z"),
+                repo: "deftai/directive",
             });
             return {
                 scenario: name,
@@ -367,8 +376,13 @@ export function runParityScenario(name, options) {
             });
             const client = options.umbrellaClient ?? SHARED_UMBRELLA_CLIENT;
             const now = FIXED_NOW.toISOString().replace(/\.\d{3}Z$/, "Z");
-            reconcileUmbrellas(root, { client, dryRun: false, now });
-            const [code, outcome] = reconcileUmbrellas(root, { client, dryRun: true, now });
+            reconcileUmbrellas(root, { client, dryRun: false, now, repo: "deftai/directive" });
+            const [code, outcome] = reconcileUmbrellas(root, {
+                client,
+                dryRun: true,
+                now,
+                repo: "deftai/directive",
+            });
             return {
                 scenario: name,
                 ok: true,

package/dist/vbrief-reconcile/repo-guard.d.ts

@@ -0,0 +1,17 @@
+export interface RepoMutateGuardOptions {
+    readonly allowCrossRepo?: boolean;
+    readonly allowlist?: readonly string[];
+    readonly explicitRepo?: string | null;
+}
+/** Normalize owner/name slugs for case-insensitive comparison. */
+export declare function normalizeRepoSlug(repo: string): string;
+/**
+ * Fail-closed gate before SCM label/comment mutations (#2601).
+ * Cross-repo targets are refused unless explicitly opted in or allowlisted.
+ */
+export declare function isRepoMutationAllowed(targetRepo: string, projectRoot: string, options?: RepoMutateGuardOptions): {
+    readonly allowed: boolean;
+    readonly projectRepo: string | null;
+    readonly reason?: string;
+};
+//# sourceMappingURL=repo-guard.d.ts.map

package/dist/vbrief-reconcile/repo-guard.js

@@ -0,0 +1,33 @@
+import { resolveRepo } from "../triage/queue/repo.js";
+/** Normalize owner/name slugs for case-insensitive comparison. */
+export function normalizeRepoSlug(repo) {
+    return repo.trim().toLowerCase();
+}
+/**
+ * Fail-closed gate before SCM label/comment mutations (#2601).
+ * Cross-repo targets are refused unless explicitly opted in or allowlisted.
+ */
+export function isRepoMutationAllowed(targetRepo, projectRoot, options = {}) {
+    const projectRepo = resolveRepo(options.explicitRepo ?? null, projectRoot);
+    if (options.allowCrossRepo) {
+        return { allowed: true, projectRepo };
+    }
+    const normalizedTarget = normalizeRepoSlug(targetRepo);
+    for (const entry of options.allowlist ?? []) {
+        if (normalizeRepoSlug(entry) === normalizedTarget) {
+            return { allowed: true, projectRepo };
+        }
+    }
+    if (projectRepo !== null && normalizeRepoSlug(projectRepo) === normalizedTarget) {
+        return { allowed: true, projectRepo };
+    }
+    const hint = projectRepo !== null
+        ? `(project repo: ${projectRepo})`
+        : "(project repo unknown — set --repo or git remote origin)";
+    return {
+        allowed: false,
+        projectRepo,
+        reason: `refusing cross-repo mutation on ${targetRepo} ${hint}`,
+    };
+}
+//# sourceMappingURL=repo-guard.js.map

package/dist/vbrief-reconcile/umbrellas.d.ts

@@ -41,6 +41,9 @@ export interface ReconcileUmbrellasOptions {
     readonly dryRun?: boolean;
     readonly client?: UmbrellaClient;
     readonly now?: string;
+    /** Opt in to mutating comments on issues outside the resolved project repo (#2601). */
+    readonly allowCrossRepo?: boolean;
+    readonly repoAllowlist?: readonly string[];
 }
 export declare function reconcileUmbrellas(projectRoot: string, options?: ReconcileUmbrellasOptions): [number, ReconcileUmbrellasOutcome];
 export declare function renderUmbrellasReport(outcome: ReconcileUmbrellasOutcome): string;

package/dist/vbrief-reconcile/umbrellas.js

@@ -5,6 +5,7 @@ import { createIssueComment, editIssueCommentBody, GitHubBodyError, } from "../i
 import { hasArtifactSuffix, resolveLifecycleRoot, stripArtifactSuffix } from "../layout/resolve.js";
 import { call } from "../scm/call.js";
 import { extractIssueRef } from "../triage/reconcile/parse-uri.js";
+import { isRepoMutationAllowed } from "./repo-guard.js";
 export const OPEN_FOLDERS = ["proposed", "pending", "active"];
 export const CLOSED_FOLDERS = ["completed", "cancelled"];
 export const LIFECYCLE_FOLDERS = [...OPEN_FOLDERS, ...CLOSED_FOLDERS];
@@ -261,6 +262,14 @@ function planShape(epicData, index) {
     return [openChildren, closedChildren, waves];
 }
 function reconcileOneEpic(epicData, index, options) {
+    const mutateGate = isRepoMutationAllowed(options.repo, options.projectRoot, {
+        allowCrossRepo: options.allowCrossRepo,
+        allowlist: options.repoAllowlist,
+        explicitRepo: options.explicitRepo ?? null,
+    });
+    if (!mutateGate.allowed) {
+        throw new Error(mutateGate.reason ?? `refusing cross-repo mutation on ${options.repo}`);
+    }
     const [openChildren, closedChildren, waves] = planShape(epicData, index);
     const total = openChildren.length + closedChildren.length;
     const comments = options.client.fetchComments(options.repo, options.number);
@@ -412,6 +421,10 @@ export function reconcileUmbrellas(projectRoot, options = {}) {
                     client,
                     dryRun: options.dryRun ?? false,
                     now,
+                    projectRoot: root,
+                    allowCrossRepo: options.allowCrossRepo ?? false,
+                    repoAllowlist: options.repoAllowlist,
+                    explicitRepo: options.repo ?? null,
                 });
                 if (change.action === "unchanged")
                     outcome.unchanged.push(change);
@@ -419,7 +432,10 @@ export function reconcileUmbrellas(projectRoot, options = {}) {
                     outcome.changed.push(change);
             }
             catch (exc) {
-                outcome.errors.push({ story_id: storyId, message: String(exc) });
+                outcome.errors.push({
+                    story_id: storyId,
+                    message: exc instanceof Error ? exc.message : String(exc),
+                });
             }
         }
     }

package/dist/verify-env/agent-hooks.js

@@ -25,7 +25,7 @@ export function evaluateAgentHooks(projectRoot) {
     if (unhealthy.length > 0) {
         return {
             code: 1,
-            message: "❌ deft agent hooks NON-FUNCTIONAL:\n" +
+            message: "❌ deft agent hook registration INCOMPLETE:\n" +
                 unhealthy
                     .map((entry) => `  - ${entry.host}: ${entry.status} at ${entry.path} — ${entry.detail}`)
                     .join("\n") +
@@ -36,8 +36,9 @@ export function evaluateAgentHooks(projectRoot) {
     }
     return {
         code: 0,
-        message: "✓ deft agent hooks installed and functional for Claude, Grok, Cursor " +
-            "(SessionStart + PreToolUse direct-write tools only; shell/MCP policy is deferred).",
+        message: "✓ deft agent hooks registered and structurally valid for Claude, Grok, Cursor, Codex " +
+            "(SessionStart + PreToolUse direct-write tools only; Codex runtime trust is " +
+            "user-controlled and must be reviewed with `/hooks`; shell/MCP policy is deferred).",
         stream: "stdout",
         registrations,
     };

package/dist/verify-env/verify-hooks-installed.js

@@ -134,7 +134,7 @@ export function evaluate(projectRoot, options = {}) {
         return {
             code: 1,
             message: "❌ deft hooks not installed: core.hooksPath is unset.\n" +
-                "  Recovery: run `task setup` (or re-run the deft installer).",
+                "  Recovery: run `deft update` to deposit project-root `.githooks/`, then `task setup` to wire core.hooksPath.",
             stream: "stderr",
         };
     }
@@ -147,7 +147,7 @@ export function evaluate(projectRoot, options = {}) {
             code: 1,
             message: `❌ deft hooks wired but NON-FUNCTIONAL: core.hooksPath=${hooksPath} ` +
                 `but the directory ${hooksDir} does not exist (#1463 false-green).\n` +
-                "  Recovery: re-run the deft installer / `task setup` to deposit the hooks.",
+                "  Recovery: run `deft update` to deposit project-root `.githooks/`, then `task setup` to wire core.hooksPath.",
             stream: "stderr",
         };
     }
@@ -157,7 +157,7 @@ export function evaluate(projectRoot, options = {}) {
             code: 1,
             message: `❌ deft hooks wired but NON-FUNCTIONAL: ${hooksDir} is missing ` +
                 `${missingHooks.join(", ")} (#1463 false-green).\n` +
-                "  Recovery: re-run the deft installer / `task setup`.",
+                "  Recovery: run `deft update` to deposit project-root `.githooks/`, then `task setup` to wire core.hooksPath.",
             stream: "stderr",
         };
     }
@@ -169,7 +169,7 @@ export function evaluate(projectRoot, options = {}) {
                 message: `❌ deft hooks wired but NON-FUNCTIONAL: ${hooksDir} hook(s) ` +
                     `${nonExec.join(", ")} are not executable (git mode is not ` +
                     "100755); git silently skips non-executable hooks on Unix (#1477).\n" +
-                    "  Recovery: re-run the deft installer / `task setup`, or " +
+                    "  Recovery: run `deft update` to refresh `.githooks/`, or " +
                     "`chmod +x .githooks/pre-commit .githooks/pre-push`.",
                 stream: "stderr",
             };
@@ -198,7 +198,7 @@ export function evaluate(projectRoot, options = {}) {
             message: "❌ deft hooks wired but NON-FUNCTIONAL:\n" +
                 contentIssues.map((issue) => `  - ${issue.replace(/\r?\n/g, " ")}`).join("\n") +
                 "\n" +
-                "  Recovery: re-run the deft installer / `task setup` to refresh .githooks/.",
+                "  Recovery: run `deft update` to refresh project-root `.githooks/`.",
             stream: "stderr",
         };
     }

package/dist/vitest-runner/coverage-debt-teardown.d.ts

@@ -0,0 +1,3 @@
+/** Vitest globalTeardown: enforce coverage goal or debt soft-pass (#2573). */
+export default function coverageDebtTeardown(): Promise<void>;
+//# sourceMappingURL=coverage-debt-teardown.d.ts.map

package/dist/vitest-runner/coverage-debt-teardown.js

@@ -0,0 +1,33 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { COVERAGE_GOAL, countRecentCoverageDebtMentions, formatCoverageAttribution, formatOveruseWarning, metricsBelowGoal, readCoverageTotalsFromReport, resolveCoverageDebtIssue, } from "./coverage-debt.js";
+/** Vitest globalTeardown: enforce coverage goal or debt soft-pass (#2573). */
+export default async function coverageDebtTeardown() {
+    const resolution = resolveCoverageDebtIssue(process.argv, process.env);
+    if (resolution.kind === "none")
+        return;
+    if (resolution.kind === "invalid") {
+        throw new Error(`coverage-debt: ${resolution.reason}`);
+    }
+    const repoRoot = join(import.meta.dirname, "..", "..", "..", "..");
+    const totals = readCoverageTotalsFromReport(join(repoRoot, "coverage"));
+    if (totals === null) {
+        throw new Error("coverage-debt: could not read coverage/coverage-final.json");
+    }
+    const missed = metricsBelowGoal(totals);
+    if (missed.length === 0) {
+        process.stderr.write(`coverage-debt: note — --allow-coverage-debt=#${resolution.issue} set but all metrics meet the ${COVERAGE_GOAL.branches}% goal\n`);
+        return;
+    }
+    process.stderr.write(`${formatCoverageAttribution(resolution.issue, totals)}\n`);
+    try {
+        const changelog = readFileSync(join(repoRoot, "CHANGELOG.md"), "utf8");
+        const overuse = formatOveruseWarning(countRecentCoverageDebtMentions(changelog));
+        if (overuse)
+            process.stderr.write(`${overuse}\n`);
+    }
+    catch {
+        // CHANGELOG unreadable — debt attribution still stands.
+    }
+}
+//# sourceMappingURL=coverage-debt-teardown.js.map

package/dist/vitest-runner/coverage-debt.d.ts

@@ -0,0 +1,50 @@
+/** Shared coverage goal (vitest thresholds). */
+export declare const COVERAGE_GOAL: {
+    readonly lines: 85;
+    readonly functions: 85;
+    readonly branches: 85;
+    readonly statements: 85;
+};
+export type CoverageMetric = keyof typeof COVERAGE_GOAL;
+export interface CoverageTotals {
+    readonly lines: number;
+    readonly functions: number;
+    readonly branches: number;
+    readonly statements: number;
+}
+export type CoverageDebtResolution = {
+    readonly kind: "none";
+} | {
+    readonly kind: "valid";
+    readonly issue: number;
+} | {
+    readonly kind: "invalid";
+    readonly reason: string;
+};
+/** Parse `#2573`, `2573`, or bare numeric strings. */
+export declare function parseCoverageDebtIssueNumber(raw: string): number | null;
+/** Parse `--allow-coverage-debt=#N` tokens from argv. */
+export declare function parseCoverageDebtArgv(argv: readonly string[]): CoverageDebtResolution;
+/**
+ * Resolve coverage-debt issue from argv or release-scoped env (#2573 / #1553).
+ * Raw env bypass is accepted only during release Step-5 preflight.
+ */
+export declare function resolveCoverageDebtIssue(argv: readonly string[], env?: NodeJS.ProcessEnv): CoverageDebtResolution;
+interface IstanbulBranchHits {
+    readonly [branchId: string]: readonly number[];
+}
+interface IstanbulFileCoverage {
+    readonly s?: Readonly<Record<string, number>>;
+    readonly f?: Readonly<Record<string, number>>;
+    readonly b?: IstanbulBranchHits;
+}
+/** Aggregate global coverage percentages from istanbul coverage-final.json. */
+export declare function summarizeCoverageFinal(coverageFinal: Readonly<Record<string, IstanbulFileCoverage>>): CoverageTotals;
+export declare function readCoverageTotalsFromReport(coverageDir: string): CoverageTotals | null;
+export declare function metricsBelowGoal(totals: CoverageTotals): CoverageMetric[];
+export declare function formatCoverageAttribution(issue: number, totals: CoverageTotals): string;
+/** Count recent release sections citing coverage-debt (CHANGELOG scan). */
+export declare function countRecentCoverageDebtMentions(changelog: string, maxSections?: number): number;
+export declare function formatOveruseWarning(recentCount: number): string | null;
+export {};
+//# sourceMappingURL=coverage-debt.d.ts.map