@deftai/directive-core 0.78.0 → 0.79.0

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

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

@@ -0,0 +1,155 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+/** Shared coverage goal (vitest thresholds). */
+export const COVERAGE_GOAL = {
+    lines: 85,
+    functions: 85,
+    branches: 85,
+    statements: 85,
+};
+const DEBT_FLAG = "--allow-coverage-debt";
+const DEBT_ENV = "DEFT_ALLOW_COVERAGE_DEBT";
+const RELEASE_PREFLIGHT_ENV = "DEFT_RELEASE_PREFLIGHT";
+/** Parse `#2573`, `2573`, or bare numeric strings. */
+export function parseCoverageDebtIssueNumber(raw) {
+    const trimmed = raw.trim();
+    if (!trimmed)
+        return null;
+    const normalized = trimmed.startsWith("#") ? trimmed.slice(1) : trimmed;
+    if (!/^\d+$/.test(normalized))
+        return null;
+    const issue = Number.parseInt(normalized, 10);
+    return Number.isFinite(issue) && issue > 0 ? issue : null;
+}
+/** Parse `--allow-coverage-debt=#N` tokens from argv. */
+export function parseCoverageDebtArgv(argv) {
+    for (let i = 0; i < argv.length; i += 1) {
+        const token = argv[i] ?? "";
+        if (token === DEBT_FLAG) {
+            const next = argv[i + 1];
+            if (next === undefined || next.startsWith("-")) {
+                return { kind: "invalid", reason: `${DEBT_FLAG} requires an issue number (#N)` };
+            }
+            const issue = parseCoverageDebtIssueNumber(next);
+            return issue === null
+                ? { kind: "invalid", reason: `${DEBT_FLAG} value must be #N or N` }
+                : { kind: "valid", issue };
+        }
+        if (token.startsWith(`${DEBT_FLAG}=`)) {
+            const value = token.slice(DEBT_FLAG.length + 1);
+            const issue = parseCoverageDebtIssueNumber(value);
+            return issue === null
+                ? { kind: "invalid", reason: `${DEBT_FLAG}= value must be #N or N` }
+                : { kind: "valid", issue };
+        }
+    }
+    return { kind: "none" };
+}
+/**
+ * Resolve coverage-debt issue from argv or release-scoped env (#2573 / #1553).
+ * Raw env bypass is accepted only during release Step-5 preflight.
+ */
+export function resolveCoverageDebtIssue(argv, env = process.env) {
+    const fromArgv = parseCoverageDebtArgv(argv);
+    if (fromArgv.kind !== "none")
+        return fromArgv;
+    const rawEnv = env[DEBT_ENV];
+    if (rawEnv && env[RELEASE_PREFLIGHT_ENV] === "1") {
+        const issue = parseCoverageDebtIssueNumber(rawEnv);
+        return issue === null
+            ? { kind: "invalid", reason: `${DEBT_ENV} must be a positive integer` }
+            : { kind: "valid", issue };
+    }
+    return { kind: "none" };
+}
+/** Aggregate global coverage percentages from istanbul coverage-final.json. */
+export function summarizeCoverageFinal(coverageFinal) {
+    let stmtTotal = 0;
+    let stmtCovered = 0;
+    let fnTotal = 0;
+    let fnCovered = 0;
+    let branchTotal = 0;
+    let branchCovered = 0;
+    for (const file of Object.values(coverageFinal)) {
+        if (file.s) {
+            for (const hits of Object.values(file.s)) {
+                stmtTotal += 1;
+                if (hits > 0)
+                    stmtCovered += 1;
+            }
+        }
+        if (file.f) {
+            for (const hits of Object.values(file.f)) {
+                fnTotal += 1;
+                if (hits > 0)
+                    fnCovered += 1;
+            }
+        }
+        if (file.b) {
+            for (const paths of Object.values(file.b)) {
+                for (const hits of paths) {
+                    branchTotal += 1;
+                    if (hits > 0)
+                        branchCovered += 1;
+                }
+            }
+        }
+    }
+    const pct = (covered, total) => total === 0 ? 100 : (covered / total) * 100;
+    const statements = pct(stmtCovered, stmtTotal);
+    const functions = pct(fnCovered, fnTotal);
+    const branches = pct(branchCovered, branchTotal);
+    // Istanbul coverage-final.json does not carry pre-aggregated line hit counts —
+    // `l` (line map) is optional and its format differs from `s`/`f`/`b`. Using
+    // statements as a proxy may overstate line coverage when multiple statements
+    // share a single uncovered line.
+    return {
+        statements,
+        functions,
+        branches,
+        lines: statements, // approximation: actual line coverage may differ
+    };
+}
+export function readCoverageTotalsFromReport(coverageDir) {
+    const finalPath = join(coverageDir, "coverage-final.json");
+    try {
+        const raw = readFileSync(finalPath, "utf8");
+        const parsed = JSON.parse(raw);
+        return summarizeCoverageFinal(parsed);
+    }
+    catch {
+        return null;
+    }
+}
+export function metricsBelowGoal(totals) {
+    const missed = [];
+    for (const metric of Object.keys(COVERAGE_GOAL)) {
+        if (totals[metric] + 1e-9 < COVERAGE_GOAL[metric]) {
+            missed.push(metric);
+        }
+    }
+    return missed;
+}
+const sanitizeMetric = (value) => String(value).replace(/\r?\n/g, " ");
+export function formatCoverageAttribution(issue, totals) {
+    const lines = [
+        `coverage-debt: soft-pass acknowledged for issue #${issue}`,
+        `  measured: branches ${sanitizeMetric(totals.branches.toFixed(2))}% | lines ${sanitizeMetric(totals.lines.toFixed(2))}% | functions ${sanitizeMetric(totals.functions.toFixed(2))}% | statements ${sanitizeMetric(totals.statements.toFixed(2))}%`,
+        `  goal:     branches ${sanitizeMetric(COVERAGE_GOAL.branches)}% | lines ${sanitizeMetric(COVERAGE_GOAL.lines)}% | functions ${sanitizeMetric(COVERAGE_GOAL.functions)}% | statements ${sanitizeMetric(COVERAGE_GOAL.statements)}%`,
+    ];
+    return lines.join("\n");
+}
+/** Count recent release sections citing coverage-debt (CHANGELOG scan). */
+export function countRecentCoverageDebtMentions(changelog, maxSections = 5) {
+    const versionHeader = /^## \[(?!Unreleased)/m;
+    const sections = changelog.split(versionHeader).slice(1, maxSections + 1);
+    const pattern = /coverage[- ]debt soft[- ]pass|allow-coverage-debt=#?\d/i;
+    return sections.filter((section) => pattern.test(section)).length;
+}
+export function formatOveruseWarning(recentCount) {
+    if (recentCount < 2)
+        return null;
+    return (`coverage-debt WARN: ${recentCount} of the last release sections already cite coverage debt — ` +
+        "consider restoring real coverage instead of reusing the escape hatch.");
+}
+//# sourceMappingURL=coverage-debt.js.map