@deftai/directive-core 0.78.0 → 0.79.0

package/dist/preflight-cache/evaluate.js

@@ -13,8 +13,11 @@
 import { execFileSync } from "node:child_process";
 import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
 import { join, relative } from "node:path";
+import { isTriageCacheEmpty, maybeAutoPopulateEmptyCache } from "../cache/empty-populate.js";
 import { probeCacheDrift } from "../cache/fetch.js";
 import { resolveProjectDefinitionPath } from "../layout/resolve.js";
+import { recoveryHintForStaleFailure } from "../session/cache-recovery.js";
+export { recoveryHintForStaleFailure } from "../session/cache-recovery.js";
 import { readPlanPolicy } from "../policy/plan-extensions.js";
 import { latestDecisionForIssue as auditLatestDecisionForIssue } from "../triage/actions/candidates-log.js";
 import { resolveCandidatesLogPath } from "../triage/cache-path.js";
@@ -280,22 +283,6 @@ function candidatesLogState(candidatesPath) {
 // Main evaluate function
 // ---------------------------------------------------------------------------
 const REMEDIATION_NO_CACHE = ["  Recovery: run `deft triage:bootstrap` to seed the cache."].join("\n");
-const REMEDIATION_STALE_FORCE = [
-    "  Recovery: run `deft cache:fetch-all --force` to refresh and reconcile upstream state.",
-].join("\n");
-const REMEDIATION_STALE_PLAIN = [
-    "  Recovery: run `deft cache:fetch-all` to refresh and reconcile upstream state.",
-].join("\n");
-/**
- * Branch-aware recovery hint (#1953 Option 3).
- * Age-stale (or age+drift mixed) → --force bypasses TTL; drift-only → plain refetch.
- */
-export function recoveryHintForStaleFailure(causes) {
-    if (causes.ageStale) {
-        return REMEDIATION_STALE_FORCE;
-    }
-    return REMEDIATION_STALE_PLAIN;
-}
 function formatDriftFailure(repo, drift) {
     const parts = [];
     if (drift.stateDriftNumbers.length > 0) {
@@ -308,7 +295,7 @@ function formatDriftFailure(repo, drift) {
         code: 1,
         message: [
             `❌ deft cache-fresh: stale-by-drift -- ${parts.join("; ")} (${repo}).`,
-            recoveryHintForStaleFailure({ ageStale: false, driftDetected: true }),
+            recoveryHintForStaleFailure({ ageStale: false, driftDetected: true }, repo),
         ].join("\n"),
     };
 }
@@ -332,10 +319,23 @@ const REMEDIATION_NO_CANDIDATES = [
  * Faithful port of scripts/preflight_cache.py::evaluate().
  */
 export function evaluate(projectRoot, options = {}) {
+    return evaluateWithContext(projectRoot, options, { afterEmptyPopulate: false });
+}
+function evaluateWithContext(projectRoot, options, ctx) {
+    const allowMissingBootstrap = options.allowMissingBootstrap ?? false;
+    const autoPopulateEmpty = options.autoPopulateEmpty !== false;
+    if (!allowMissingBootstrap &&
+        autoPopulateEmpty &&
+        !ctx.afterEmptyPopulate &&
+        isTriageCacheEmpty(projectRoot)) {
+        const populated = maybeAutoPopulateEmptyCache(projectRoot, { repo: options.repo ?? null });
+        if (populated.populated) {
+            return evaluateWithContext(projectRoot, options, { afterEmptyPopulate: true });
+        }
+    }
     const source = options.source ?? DEFAULT_SOURCE;
     const allowStale = options.allowStale ?? false;
     const releasePreflightStaleBypass = releasePreflightBypassActive();
-    const allowMissingBootstrap = options.allowMissingBootstrap ?? false;
     const nowFn = options.nowFn ?? (() => new Date());
     const envMaxAge = process.env[ENV_MAX_AGE_HOURS];
     const envMaxAgeParsed = envMaxAge !== undefined ? Number.parseInt(envMaxAge, 10) : null;
@@ -453,7 +453,7 @@ export function evaluate(projectRoot, options = {}) {
             code: 1,
             message: [
                 `❌ deft cache-fresh: cache is ${ageH.toFixed(1)}h old (max-age=${maxAgeHours}h); oldest in-scope entry ${display}.`,
-                recoveryHintForStaleFailure({ ageStale: true, driftDetected: false }),
+                recoveryHintForStaleFailure({ ageStale: true, driftDetected: false }, resolvedRepo),
             ].join("\n"),
         };
     }

package/dist/release/constants.d.ts

@@ -18,6 +18,8 @@ export declare const BRANCH_GATE_BYPASS_ENV = "DEFT_ALLOW_DEFAULT_BRANCH_COMMIT"
 export declare const DESTRUCTIVE_GH_GATE_BYPASS_ENV = "DEFT_ALLOW_DESTRUCTIVE_GH_VERBS";
 /** Set by releaseSubprocessEnv() so Step-5 pre-flight skips triage-cache staleness (#2386). */
 export declare const RELEASE_PREFLIGHT_ENV = "DEFT_RELEASE_PREFLIGHT";
+/** Set only by release Step-5 preflight when --allow-coverage-debt=#N is supplied (#2573). */
+export declare const COVERAGE_DEBT_ENV = "DEFT_ALLOW_COVERAGE_DEBT";
 export declare const PYPROJECT_VERSION_LINE_RE: RegExp;
 /** Byte-identical argparse --help from scripts/release.py (Python 3.12). */
 export declare const RELEASE_HELP: string;

package/dist/release/constants.js

@@ -26,10 +26,13 @@ export const BRANCH_GATE_BYPASS_ENV = "DEFT_ALLOW_DEFAULT_BRANCH_COMMIT";
 export const DESTRUCTIVE_GH_GATE_BYPASS_ENV = "DEFT_ALLOW_DESTRUCTIVE_GH_VERBS";
 /** Set by releaseSubprocessEnv() so Step-5 pre-flight skips triage-cache staleness (#2386). */
 export const RELEASE_PREFLIGHT_ENV = "DEFT_RELEASE_PREFLIGHT";
+/** Set only by release Step-5 preflight when --allow-coverage-debt=#N is supplied (#2573). */
+export const COVERAGE_DEBT_ENV = "DEFT_ALLOW_COVERAGE_DEBT";
 export const PYPROJECT_VERSION_LINE_RE = /version\s*=\s*"[^"]*"/;
 /** Byte-identical argparse --help from scripts/release.py (Python 3.12). */
 export const RELEASE_HELP = "usage: release [-h] [--dry-run] [--skip-tag] [--skip-release] [--allow-dirty]\n" +
-    "               [--allow-vbrief-drift] [--skip-ci] [--skip-build] [--no-draft]\n" +
+    "               [--allow-vbrief-drift] [--allow-coverage-debt #N]\n" +
+    "               [--skip-ci] [--skip-build] [--no-draft]\n" +
     "               [--repo OWNER/REPO] [--base-branch BRANCH]\n" +
     "               [--project-root PATH] [--summary TEXT]\n" +
     "               version\n" +
@@ -57,6 +60,10 @@ export const RELEASE_HELP = "usage: release [-h] [--dry-run] [--skip-tag] [--ski
     "                        may still live in non-terminal folders. The clean path\n" +
     "                        is to run `task reconcile:issues -- --apply-lifecycle-\n" +
     "                        fixes` first.\n" +
+    "  --allow-coverage-debt #N\n" +
+    "                        Acknowledge a hairline coverage miss: Step 5 passes\n" +
+    "                        only when metrics sit below the 85% goal and this\n" +
+    "                        flag cites an operator-owned issue number (#2573).\n" +
     "  --skip-ci             Skip Step 3 (task ci:local / task check fallback).\n" +
     "                        Used by `task release:e2e` to keep wall-clock\n" +
     "                        manageable inside the auto-created temp repo (CI\n" +

package/dist/release/flags.js

@@ -1,3 +1,4 @@
+import { parseCoverageDebtIssueNumber } from "../vitest-runner/coverage-debt.js";
 import { DEFAULT_BASE_BRANCH, RELEASE_HELP } from "./constants.js";
 export function parseReleaseFlags(args) {
     let help = false;
@@ -6,6 +7,7 @@ export function parseReleaseFlags(args) {
     let skipRelease = false;
     let allowDirty = false;
     let allowVbriefDrift = false;
+    let allowCoverageDebtIssue = null;
     let skipCi = false;
     let skipBuild = false;
     let draft = true;
@@ -43,6 +45,29 @@ export function parseReleaseFlags(args) {
         else if (token === "--allow-vbrief-drift") {
             allowVbriefDrift = true;
         }
+        else if (token === "--allow-coverage-debt") {
+            const value = takeValue(token, i);
+            if (value !== null) {
+                const issue = parseCoverageDebtIssueNumber(value);
+                if (issue === null) {
+                    unknown.push(`${token} (malformed issue number)`);
+                }
+                else {
+                    allowCoverageDebtIssue = issue;
+                }
+                i += 1;
+            }
+        }
+        else if (token.startsWith("--allow-coverage-debt=")) {
+            const value = token.slice("--allow-coverage-debt=".length);
+            const issue = parseCoverageDebtIssueNumber(value);
+            if (issue === null) {
+                unknown.push("--allow-coverage-debt= (malformed issue number)");
+            }
+            else {
+                allowCoverageDebtIssue = issue;
+            }
+        }
         else if (token === "--skip-ci") {
             skipCi = true;
         }
@@ -118,6 +143,7 @@ export function parseReleaseFlags(args) {
         skipRelease,
         allowDirty,
         allowVbriefDrift,
+        allowCoverageDebtIssue,
         skipCi,
         skipBuild,
         draft,

package/dist/release/issue-state-fetch.d.ts

@@ -0,0 +1,27 @@
+import { type FetchIssueStatesOptions } from "../intake/reconcile-issues.js";
+import { type CallOptions, type CompletedProcess } from "../scm/call.js";
+export type ScmCallFn = (source: string, verb: string, args: readonly string[] | null, options?: CallOptions) => CompletedProcess;
+/** Max seconds to sleep before the single rate-limit retry (operator-locked cap). */
+export declare const MAX_RATE_LIMIT_RETRY_SLEEP_S = 120;
+export type SleepFn = (seconds: number) => void;
+export interface RateLimitProbe {
+    readonly coreRemaining: number | null;
+    readonly coreResetUnix: number | null;
+    readonly graphqlRemaining: number | null;
+}
+export interface FetchIssueStatesForReleaseOptions extends FetchIssueStatesOptions {
+    readonly sleep?: SleepFn;
+    readonly now?: () => number;
+}
+export type FetchIssueStatesForReleaseResult = {
+    readonly ok: true;
+    readonly states: Map<number, import("../intake/reconcile-issues.js").IssueState>;
+} | {
+    readonly ok: false;
+    readonly reason: string;
+};
+export declare function probeGithubRateLimit(scmCall: ScmCallFn, cwd?: string): RateLimitProbe | null;
+export declare function computeRateLimitSleepSeconds(stderr: string, probe: RateLimitProbe | null, nowSec: number): number;
+export declare function formatRateLimitFailureDetails(probe: RateLimitProbe | null, rateLimitRelated: boolean): string;
+export declare function fetchIssueStatesForRelease(repo: string, issueNumbers: ReadonlySet<number>, options?: FetchIssueStatesForReleaseOptions): FetchIssueStatesForReleaseResult;
+//# sourceMappingURL=issue-state-fetch.d.ts.map

package/dist/release/issue-state-fetch.js

@@ -0,0 +1,146 @@
+/**
+ * Release Step 3 issue-state fetch with capped rate-limit retry (#2577).
+ */
+import { detectRateLimit } from "../cache/fetch.js";
+import { fetchIssueStates } from "../intake/reconcile-issues.js";
+import { call } from "../scm/call.js";
+/** Max seconds to sleep before the single rate-limit retry (operator-locked cap). */
+export const MAX_RATE_LIMIT_RETRY_SLEEP_S = 120;
+const X_RATE_LIMIT_RESET_RE = /X-RateLimit-Reset:\s*(\d+)/i;
+function defaultSleep(seconds) {
+    const ms = Math.max(0, Math.trunc(seconds * 1000));
+    if (ms === 0) {
+        return;
+    }
+    const shared = new Int32Array(new SharedArrayBuffer(4));
+    Atomics.wait(shared, 0, 0, ms);
+}
+function parseRateLimitProbe(stdout) {
+    try {
+        const body = JSON.parse(stdout);
+        if (typeof body !== "object" || body === null) {
+            return null;
+        }
+        const resources = body.resources;
+        if (typeof resources !== "object" || resources === null) {
+            return null;
+        }
+        const core = resources.core;
+        const graphql = resources.graphql;
+        if (typeof core !== "object" ||
+            core === null ||
+            Array.isArray(core) ||
+            typeof graphql !== "object" ||
+            graphql === null ||
+            Array.isArray(graphql)) {
+            return null;
+        }
+        const coreRemainingRaw = core.remaining;
+        const coreResetRaw = core.reset;
+        const graphqlRemainingRaw = graphql.remaining;
+        const coreRemaining = coreRemainingRaw === undefined ? null : Number.parseInt(String(coreRemainingRaw), 10);
+        const coreResetUnix = coreResetRaw === undefined ? null : Number.parseInt(String(coreResetRaw), 10);
+        const graphqlRemaining = graphqlRemainingRaw === undefined ? null : Number.parseInt(String(graphqlRemainingRaw), 10);
+        if ((coreRemaining !== null && Number.isNaN(coreRemaining)) ||
+            (coreResetUnix !== null && Number.isNaN(coreResetUnix)) ||
+            (graphqlRemaining !== null && Number.isNaN(graphqlRemaining))) {
+            return null;
+        }
+        return { coreRemaining, coreResetUnix, graphqlRemaining };
+    }
+    catch {
+        return null;
+    }
+}
+export function probeGithubRateLimit(scmCall, cwd) {
+    let result;
+    try {
+        result = scmCall("github-issue", "api", ["rate_limit"], { timeout: 30, cwd });
+    }
+    catch {
+        return null;
+    }
+    if (result.returncode !== 0 || result.stdout.trim().length === 0) {
+        return null;
+    }
+    return parseRateLimitProbe(result.stdout);
+}
+export function computeRateLimitSleepSeconds(stderr, probe, nowSec) {
+    const [isRateLimit, retryAfter] = detectRateLimit(stderr);
+    if (!isRateLimit) {
+        return 0;
+    }
+    let candidate = retryAfter;
+    const resetMatch = X_RATE_LIMIT_RESET_RE.exec(stderr);
+    if (resetMatch?.[1]) {
+        const resetAt = Number.parseInt(resetMatch[1], 10);
+        if (!Number.isNaN(resetAt)) {
+            candidate = Math.max(0, resetAt - nowSec + 1);
+        }
+    }
+    else if (probe !== null && probe.coreResetUnix !== null) {
+        candidate = Math.max(0, probe.coreResetUnix - nowSec + 1);
+    }
+    return Math.min(Math.max(1, candidate), MAX_RATE_LIMIT_RETRY_SLEEP_S);
+}
+export function formatRateLimitFailureDetails(probe, rateLimitRelated) {
+    const lines = [];
+    if (probe !== null) {
+        const resetHint = probe.coreResetUnix !== null
+            ? `core resets at ${new Date(probe.coreResetUnix * 1000).toISOString()}`
+            : "run `gh api rate_limit` for reset time";
+        lines.push(`GitHub rate limit probe: core.remaining=${probe.coreRemaining ?? "?"} graphql.remaining=${probe.graphqlRemaining ?? "?"} (${resetHint})`);
+    }
+    else {
+        lines.push("Probe `gh api rate_limit` for core.remaining and reset time.");
+    }
+    if (rateLimitRelated) {
+        lines.push("Recovery: wait for the REST core bucket to reset, then re-run `task release`.");
+        lines.push("If local lifecycle validation is clean (`task vbrief:validate` exits 0), you may pass `--allow-vbrief-drift` to skip Step 3 for this cut.");
+    }
+    return lines.join("\n");
+}
+export function fetchIssueStatesForRelease(repo, issueNumbers, options = {}) {
+    const sleepFn = options.sleep ?? defaultSleep;
+    const nowFn = options.now ?? (() => Math.floor(Date.now() / 1000));
+    const baseScmCall = options.scmCall ?? call;
+    const cwd = options.cwd ?? undefined;
+    let sawRateLimit = false;
+    let lastRateLimitStderr = "";
+    const trackingScmCall = (source, verb, args, callOptions) => {
+        const result = baseScmCall(source, verb, args, callOptions);
+        if (result.returncode !== 0 && detectRateLimit(result.stderr)[0]) {
+            sawRateLimit = true;
+            lastRateLimitStderr = result.stderr;
+        }
+        return result;
+    };
+    let states = fetchIssueStates(repo, issueNumbers, { ...options, scmCall: trackingScmCall });
+    if (states !== null) {
+        return { ok: true, states };
+    }
+    if (sawRateLimit) {
+        const probe = probeGithubRateLimit(baseScmCall, cwd);
+        const sleepS = computeRateLimitSleepSeconds(lastRateLimitStderr, probe, nowFn());
+        process.stderr.write(`[release Step 3] GitHub REST rate limit hit; sleeping ${sleepS}s before one retry\n`);
+        sleepFn(sleepS);
+        sawRateLimit = false;
+        lastRateLimitStderr = "";
+        states = fetchIssueStates(repo, issueNumbers, { ...options, scmCall: trackingScmCall });
+        if (states !== null) {
+            return { ok: true, states };
+        }
+    }
+    const rateLimitRelated = sawRateLimit || lastRateLimitStderr.length > 0;
+    if (rateLimitRelated) {
+        const probe = probeGithubRateLimit(baseScmCall, cwd);
+        const details = formatRateLimitFailureDetails(probe, true);
+        process.stderr.write(`${details}\n`);
+        return {
+            ok: false,
+            reason: "GitHub REST rate limit exhausted (see stderr for recovery steps)",
+        };
+    }
+    return { ok: false, reason: "failed to fetch issue states from gh" };
+}
+//# sourceMappingURL=issue-state-fetch.js.map

package/dist/release/main.js

@@ -41,6 +41,7 @@ export function cmdRelease(args, seams = {}) {
         skipBuild: flags.skipBuild,
         summary: flags.summary,
         allowVbriefDrift: flags.allowVbriefDrift,
+        allowCoverageDebtIssue: flags.allowCoverageDebtIssue,
     };
     return runPipeline(config, seams);
 }

package/dist/release/native-steps.js

@@ -6,9 +6,10 @@ import { spawnSync } from "node:child_process";
 import { existsSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
-import { fetchIssueStates, isTerminalLifecyclePath, reconcile, scanVbriefDir, } from "../intake/reconcile-issues.js";
+import { isTerminalLifecyclePath, reconcile, scanVbriefDir } from "../intake/reconcile-issues.js";
 import { LEGACY_ARTIFACT_DIR, MIGRATED_ARTIFACT_DIR, resolveLifecycleFolder, resolveLifecycleRoot, } from "../layout/resolve.js";
 import { renderRoadmap } from "../render/roadmap-render.js";
+import { fetchIssueStatesForRelease } from "./issue-state-fetch.js";
 const BUILD_DIST_RUNNER = join(dirname(fileURLToPath(import.meta.url)), "build-dist-runner.js");
 export function refreshRoadmapNative(projectRoot) {
     const pending = resolveLifecycleFolder(projectRoot, "pending");
@@ -35,12 +36,13 @@ export function checkVbriefLifecycleSyncNative(projectRoot, repo) {
     }
     try {
         const issueToVbriefs = scanVbriefDir(vbriefDir);
-        const issueStateMap = fetchIssueStates(repo, new Set(issueToVbriefs.keys()), {
+        const fetchResult = fetchIssueStatesForRelease(repo, new Set(issueToVbriefs.keys()), {
             cwd: projectRoot,
         });
-        if (issueStateMap === null) {
-            return [false, -1, "failed to fetch issue states from gh"];
+        if (!fetchResult.ok) {
+            return [false, -1, fetchResult.reason];
         }
+        const issueStateMap = fetchResult.states;
         const report = reconcile(issueToVbriefs, issueStateMap);
         const mismatches = [];
         for (const entry of report.no_open_issue) {

package/dist/release/pipeline.js

@@ -21,7 +21,8 @@ export function runPipeline(config, seams = {}) {
     const readFile = seams.readFile ?? ((p) => readFileSync(p, "utf8"));
     const writeFile = seams.writeFile ?? ((p, c) => writeFileSync(p, c, "utf8"));
     const fileExists = seams.fileExists ?? ((p) => existsSync(p));
-    const runCiFn = seams.runCi ?? ((root) => runReleaseCheck(root));
+    const runCiFn = seams.runCi ??
+        ((root, debtIssue) => runReleaseCheck(root, {}, debtIssue));
     const refreshRoadmapFn = seams.refreshRoadmap ?? ((root) => refreshRoadmapNative(root));
     const checkVbriefFn = seams.checkVbriefLifecycleSync ??
         ((root, repo) => checkVbriefLifecycleSyncNative(root, repo));
@@ -110,15 +111,24 @@ export function runPipeline(config, seams = {}) {
         emit(5, label, "SKIP (--skip-ci)");
     }
     else if (config.dryRun) {
-        emit(5, label, "DRYRUN (would run task ci:local with task check fallback)");
+        const debtNote = config.allowCoverageDebtIssue !== null
+            ? `; would pass --allow-coverage-debt=#${config.allowCoverageDebtIssue} to task check`
+            : "";
+        emit(5, label, `DRYRUN (would run task ci:local with task check fallback${debtNote})`);
     }
     else {
-        const [ok, reason] = runCiFn(projectRoot);
+        const [ok, reason] = runCiFn(projectRoot, config.allowCoverageDebtIssue);
         if (ok) {
-            emit(5, label, `OK (${reason})`);
+            const debtNote = config.allowCoverageDebtIssue !== null
+                ? ` (coverage-debt acknowledged #${config.allowCoverageDebtIssue})`
+                : "";
+            emit(5, label, `OK (${reason}${debtNote})`);
         }
         else {
-            emit(5, label, `FAIL (${reason})`);
+            const debtHint = config.allowCoverageDebtIssue === null
+                ? "; pass --allow-coverage-debt=#N only after operator review"
+                : "";
+            emit(5, label, `FAIL (${reason}${debtHint})`);
             return EXIT_VIOLATION;
         }
     }

package/dist/release/preflight.d.ts

@@ -8,8 +8,12 @@
  * dispatches `check:framework-source`.
  */
 import { type CheckOrchestratorSeams } from "../check/orchestrator.js";
+export interface ReleaseCheckEnvOptions {
+    readonly base?: NodeJS.ProcessEnv;
+    readonly allowCoverageDebtIssue?: number | null;
+}
 /** Step-5-only env: branch bypass plus release pre-flight cache staleness tolerance (#2386). */
-export declare function releaseCheckEnv(base?: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
+export declare function releaseCheckEnv(options?: ReleaseCheckEnvOptions): NodeJS.ProcessEnv;
 /** Seams for test isolation of the native release pre-flight. */
 export interface ReleasePreflightSeams {
     /** Override the check dispatcher (default: dispatchTaskCheck from check/orchestrator). */
@@ -25,5 +29,5 @@ export interface ReleasePreflightSeams {
  * and the project root -- the orchestrator then resolves the framework-source
  * context and runs `check:framework-source`.
  */
-export declare function runReleaseCheck(projectRoot: string, seams?: ReleasePreflightSeams): [boolean, string];
+export declare function runReleaseCheck(projectRoot: string, seams?: ReleasePreflightSeams, allowCoverageDebtIssue?: number | null): [boolean, string];
 //# sourceMappingURL=preflight.d.ts.map

package/dist/release/preflight.js

@@ -8,14 +8,25 @@
  * dispatches `check:framework-source`.
  */
 import { dispatchTaskCheck } from "../check/orchestrator.js";
-import { RELEASE_PREFLIGHT_ENV } from "./constants.js";
+import { COVERAGE_DEBT_ENV, RELEASE_PREFLIGHT_ENV } from "./constants.js";
 import { releaseSubprocessEnv } from "./git.js";
 /** Step-5-only env: branch bypass plus release pre-flight cache staleness tolerance (#2386). */
-export function releaseCheckEnv(base = process.env) {
-    return {
+export function releaseCheckEnv(options = {}) {
+    const base = options.base ?? process.env;
+    const allowCoverageDebtIssue = options.allowCoverageDebtIssue ?? null;
+    const env = {
         ...releaseSubprocessEnv(base),
         [RELEASE_PREFLIGHT_ENV]: "1",
     };
+    if (allowCoverageDebtIssue !== null) {
+        env[COVERAGE_DEBT_ENV] = String(allowCoverageDebtIssue);
+    }
+    else {
+        // Scrub ambient parent-shell debt so nested unit tests and unpaid checks
+        // do not inherit a prior --allow-coverage-debt from the release process (#2618).
+        delete env[COVERAGE_DEBT_ENV];
+    }
+    return env;
 }
 /**
  * Run the native TypeScript `task check` as the release pre-flight.
@@ -25,11 +36,14 @@ export function releaseCheckEnv(base = process.env) {
  * and the project root -- the orchestrator then resolves the framework-source
  * context and runs `check:framework-source`.
  */
-export function runReleaseCheck(projectRoot, seams = {}) {
+export function runReleaseCheck(projectRoot, seams = {}, allowCoverageDebtIssue = null) {
     const dispatch = seams.dispatchCheck ?? dispatchTaskCheck;
     const checkSeams = {
         ...seams.checkSeams,
-        env: releaseCheckEnv(seams.checkSeams?.env ?? process.env),
+        env: releaseCheckEnv({
+            base: seams.checkSeams?.env ?? process.env,
+            allowCoverageDebtIssue,
+        }),
     };
     const code = dispatch(projectRoot, projectRoot, checkSeams);
     if (code === 0) {

package/dist/release/types.d.ts

@@ -12,6 +12,7 @@ export interface ReleaseConfig {
     readonly skipBuild: boolean;
     readonly summary: string | null;
     readonly allowVbriefDrift: boolean;
+    readonly allowCoverageDebtIssue: number | null;
 }
 export interface ReleaseFlags {
     readonly help: boolean;
@@ -28,6 +29,7 @@ export interface ReleaseFlags {
     readonly skipBuild: boolean;
     readonly draft: boolean;
     readonly summary: string | null;
+    readonly allowCoverageDebtIssue: number | null;
     readonly unknown: readonly string[];
 }
 export interface SpawnResult {
@@ -48,7 +50,7 @@ export interface ReleaseSeams {
     readonly writeFile?: (path: string, content: string) => void;
     readonly readFile?: (path: string) => string;
     readonly fileExists?: (path: string) => boolean;
-    readonly runCi?: (projectRoot: string) => [boolean, string];
+    readonly runCi?: (projectRoot: string, allowCoverageDebtIssue: number | null) => [boolean, string];
     readonly refreshRoadmap?: (projectRoot: string) => [boolean, string];
     readonly checkVbriefLifecycleSync?: (projectRoot: string, repo: string) => [boolean, number, string];
     readonly runBuild?: (projectRoot: string, version: string | null) => [boolean, string];

package/dist/release-e2e/constants.js

@@ -28,20 +28,20 @@ export const RELEASE_ENTRYPOINT_TIMEOUT_SECONDS = 600.0;
 export const ROLLBACK_ENTRYPOINT_TIMEOUT_SECONDS = 300.0;
 export const ENTRYPOINT_TIMEOUT_EXIT_CODE = 124;
 /** Byte-identical --help from scripts/release_e2e.py (Python 3.12 argparse). */
-export const RELEASE_E2E_HELP = "usage: release_e2e [-h] [--owner OWNER] [--dry-run] [--keep-repo]\n" +
+export const RELEASE_E2E_HELP = "usage: release_e2e [-h] [--owner OWNER] [--dry-run] [--destroy-repo]\n" +
     "                   [--project-root PATH] [--skip-npm]\n" +
     "\n" +
-    "End-to-end release rehearsal against an auto-created+destroyed temp GitHub\n" +
-    "repo (#716 safety hardening Q1).\n" +
+    "End-to-end release rehearsal against an auto-created temp GitHub repo\n" +
+    "(#716 safety hardening Q1; #2572 defaults to keep+report cleanup).\n" +
     "\n" +
     "options:\n" +
     "  -h, --help           show this help message and exit\n" +
     "  --owner OWNER        GitHub owner under which to create the temp repo\n" +
     "                       (default: deftai).\n" +
     "  --dry-run            Print the pipeline plan without invoking gh.\n" +
-    "  --keep-repo          Skip destroying the temp repo at the end (use only when\n" +
-    "                       manually debugging a failed rehearsal; remember to\n" +
-    "                       clean up by hand).\n" +
+    "  --destroy-repo       Attempt gh repo delete after rehearsal (privileged\n" +
+    "                       environments with delete_repo permission only; default\n" +
+    "                       keeps the temp repo and reports manual cleanup).\n" +
     "  --project-root PATH  Repository root (default: $DEFT_PROJECT_ROOT or\n" +
     "                       scripts/.. ).\n" +
     "  --skip-npm           Skip the npm publish dry-run rehearsal step (#1910).\n" +

package/dist/release-e2e/flags.d.ts

@@ -1,5 +1,7 @@
 import type { E2ESeams } from "./types.js";
 export declare function emit(label: string, status: string): void;
+/** Copy-paste cleanup hint for leftover release-e2e temp repos (#2572). */
+export declare function formatTempRepoCleanupHint(owner: string, slug: string): string;
 export declare function generateRepoSlug(seams?: E2ESeams): string;
 export declare function parseE2EFlags(argv: readonly string[]): import("./types.js").ParsedE2EFlags;
 //# sourceMappingURL=flags.d.ts.map

package/dist/release-e2e/flags.js

@@ -3,6 +3,10 @@ import { REPO_SLUG_PREFIX } from "./constants.js";
 export function emit(label, status) {
     process.stderr.write(`[e2e] ${label}... ${status}\n`);
 }
+/** Copy-paste cleanup hint for leftover release-e2e temp repos (#2572). */
+export function formatTempRepoCleanupHint(owner, slug) {
+    return `gh repo delete ${owner}/${slug} --yes`;
+}
 export function generateRepoSlug(seams = {}) {
     if (seams.generateRepoSlug) {
         return seams.generateRepoSlug();
@@ -22,7 +26,7 @@ export function parseE2EFlags(argv) {
     let help = false;
     let owner = "deftai";
     let dryRun = false;
-    let keepRepo = false;
+    let destroyRepo = false;
     let projectRoot = null;
     let skipNpm = false;
     let legacyBridge = false;
@@ -37,8 +41,8 @@ export function parseE2EFlags(argv) {
         else if (arg === "--dry-run") {
             dryRun = true;
         }
-        else if (arg === "--keep-repo") {
-            keepRepo = true;
+        else if (arg === "--destroy-repo") {
+            destroyRepo = true;
         }
         else if (arg === "--skip-npm") {
             skipNpm = true;
@@ -79,6 +83,6 @@ export function parseE2EFlags(argv) {
             unknown.push(arg);
         }
     }
-    return { help, owner, dryRun, keepRepo, projectRoot, skipNpm, legacyBridge, unknown };
+    return { help, owner, dryRun, destroyRepo, projectRoot, skipNpm, legacyBridge, unknown };
 }
 //# sourceMappingURL=flags.js.map

package/dist/release-e2e/main.js

@@ -1,6 +1,6 @@
 import { resolveProjectRoot } from "../release/paths.js";
 import { EXIT_CONFIG_ERROR, EXIT_OK, EXIT_VIOLATION, RELEASE_E2E_HELP } from "./constants.js";
-import { emit, generateRepoSlug, parseE2EFlags } from "./flags.js";
+import { emit, formatTempRepoCleanupHint, generateRepoSlug, parseE2EFlags } from "./flags.js";
 import { destroyTempRepo, provisionTempRepo } from "./gh-ops.js";
 import { runLegacyBridgeLeg } from "./legacy-bridge-leg.js";
 import { runRehearsal } from "./rehearsal.js";
@@ -18,7 +18,13 @@ export function runE2e(config, seams = {}) {
             emit("Legacy-bridge leg", "DRYRUN (would run the pinned legacy -> bridge -> npm-hybrid migration leg; reads the " +
                 "Tier-0 SoT lastGoInstaller(), pending-pin while null)");
         }
-        emit("Destroy temp repo", `DRYRUN (would run \`gh repo delete ${owner}/${slug} --yes\`)`);
+        const cleanupHint = formatTempRepoCleanupHint(owner, slug);
+        if (config.destroyRepo) {
+            emit("Destroy temp repo", `DRYRUN (would run \`${cleanupHint}\`)`);
+        }
+        else {
+            emit("Temp repo cleanup", `DRYRUN (would keep ${owner}/${slug}; manual cleanup: ${cleanupHint})`);
+        }
         return EXIT_OK;
     }
     // Opt-in #1912 leg: local + self-contained (no temp GitHub repo), so run it
@@ -49,19 +55,19 @@ export function runE2e(config, seams = {}) {
         }
     }
     finally {
-        if (config.keepRepo) {
-            emit(`Destroy ${owner}/${slug}`, "SKIP (--keep-repo set; manual cleanup required: " +
-                `gh repo delete ${owner}/${slug} --yes)`);
-        }
-        else {
+        const cleanupHint = formatTempRepoCleanupHint(owner, slug);
+        if (config.destroyRepo) {
             const [destroyOk, destroyReason] = destroyTempRepo(owner, slug, seams);
             if (destroyOk) {
                 emit(`Destroy ${owner}/${slug}`, `OK (${destroyReason})`);
             }
             else {
-                emit(`Destroy ${owner}/${slug}`, `WARN (${destroyReason}); manual cleanup hint: gh repo delete ${owner}/${slug} --yes`);
+                emit(`Destroy ${owner}/${slug}`, `WARN (${destroyReason}); manual cleanup: ${cleanupHint}`);
             }
         }
+        else {
+            emit(`Temp repo ${owner}/${slug}`, `KEEP (manual cleanup: ${cleanupHint})`);
+        }
     }
     return rehearsalRc !== EXIT_OK ? rehearsalRc : legacyBridgeRc;
 }
@@ -84,7 +90,7 @@ export function cmdReleaseE2e(args, seams = {}) {
         owner: flags.owner,
         projectRoot,
         dryRun: flags.dryRun,
-        keepRepo: flags.keepRepo,
+        destroyRepo: flags.destroyRepo,
         skipNpm: flags.skipNpm,
         legacyBridge: flags.legacyBridge,
         repoSlug: null,