@deftai/directive-core 0.97.0 → 0.98.1

package/dist/release/coverage-debt-ledger.js

@@ -0,0 +1,157 @@
+/**
+ * Open-issue coverage-debt ledger probes for release Step 5 (#2866 / #3187).
+ *
+ * Production path uses `gh`; all I/O is seamed for unit tests (no live network).
+ */
+import { existsSync, readFileSync, unlinkSync } from "node:fs";
+import { join } from "node:path";
+import { containedWrite } from "../fs/contained-write.js";
+import { extractCoverageDebtCitationsFromChangelog, filterOpenCoverageDebtIssues, mergeOpenDebtLedger, } from "./auto-hatch.js";
+import { resolveGh } from "./gh.js";
+import { defaultWhich, spawnText } from "./spawn.js";
+function spawn(seams, cmd, args, cwd) {
+    const run = seams.spawnText ?? spawnText;
+    return run(cmd, args, { cwd, timeoutMs: 60_000, env: { ...process.env } });
+}
+class LedgerProbeError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "LedgerProbeError";
+    }
+}
+function listIssuesBySearch(ghPath, repo, projectRoot, search, seams) {
+    const result = spawn(seams, ghPath, [
+        "issue",
+        "list",
+        "--repo",
+        repo,
+        "--state",
+        "open",
+        "--search",
+        search,
+        "--limit",
+        "20",
+        "--json",
+        "number,title,body,state",
+    ], projectRoot);
+    if (result.status !== 0) {
+        throw new LedgerProbeError(`coverage-debt ledger search failed (${search}): ${(result.stderr || result.stdout).trim() || `exit ${result.status}`}`);
+    }
+    try {
+        const rows = JSON.parse(result.stdout || "[]");
+        if (!Array.isArray(rows)) {
+            throw new LedgerProbeError(`coverage-debt ledger search returned non-array for ${search}`);
+        }
+        return rows;
+    }
+    catch (err) {
+        if (err instanceof LedgerProbeError)
+            throw err;
+        throw new LedgerProbeError(`coverage-debt ledger search unparseable JSON for ${search}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
+function viewIssueState(ghPath, repo, projectRoot, issue, seams) {
+    // Prefer REST via `gh api` (avoids GraphQL issue-view --json).
+    const result = spawn(seams, ghPath, ["api", `repos/${repo}/issues/${issue}`, "--jq", ".state"], projectRoot);
+    if (result.status !== 0)
+        return "UNKNOWN";
+    const state = result.stdout.trim().toUpperCase();
+    if (state === "OPEN")
+        return "OPEN";
+    if (state === "CLOSED")
+        return "CLOSED";
+    return "UNKNOWN";
+}
+/**
+ * Probe open coverage-debt ledger: marker searches + CHANGELOG citation scan.
+ * Citation numbers whose state is OPEN or UNKNOWN count as unpaid (fail closed).
+ *
+ * Fail closed: gh marker-search failures throw (do not treat as empty ledger).
+ * Missing gh falls through to CHANGELOG citations only (still fail-closed on UNKNOWN).
+ */
+export function probeOpenCoverageDebtLedger(repo, projectRoot, seams = {}) {
+    if (seams.listOpenDebtIssues) {
+        return seams.listOpenDebtIssues(repo, projectRoot);
+    }
+    const which = seams.whichGh ?? defaultWhich;
+    const ghPath = resolveGh({ whichGh: which, spawnText: seams.spawnText });
+    const markerHits = ghPath === null
+        ? []
+        : [
+            ...listIssuesBySearch(ghPath, repo, projectRoot, "coverage-debt in:title,body", seams),
+            ...listIssuesBySearch(ghPath, repo, projectRoot, "allow-coverage-debt in:body", seams),
+        ];
+    const fromMarkers = filterOpenCoverageDebtIssues(markerHits);
+    const changelogPath = join(projectRoot, "CHANGELOG.md");
+    const exists = seams.fileExists ?? ((p) => existsSync(p));
+    const read = seams.readFile ?? ((p) => readFileSync(p, "utf8"));
+    let citedOpen = [];
+    if (exists(changelogPath)) {
+        try {
+            const cited = extractCoverageDebtCitationsFromChangelog(read(changelogPath));
+            if (ghPath === null) {
+                // Fail closed: cannot confirm closed state without gh.
+                citedOpen = cited;
+            }
+            else {
+                const openRows = [];
+                for (const n of cited) {
+                    const state = viewIssueState(ghPath, repo, projectRoot, n, seams);
+                    if (state === "OPEN" || state === "UNKNOWN") {
+                        openRows.push({ number: n });
+                    }
+                }
+                citedOpen = filterOpenCoverageDebtIssues(openRows);
+            }
+        }
+        catch {
+            // ignore unreadable changelog
+        }
+    }
+    return mergeOpenDebtLedger(fromMarkers, citedOpen);
+}
+/** Create a coverage-debt issue; returns issue number or throws. */
+export function createCoverageDebtIssue(repo, projectRoot, title, body, seams = {}) {
+    if (seams.createDebtIssue) {
+        return seams.createDebtIssue(repo, projectRoot, title, body);
+    }
+    const which = seams.whichGh ?? defaultWhich;
+    const ghPath = resolveGh({ whichGh: which, spawnText: seams.spawnText });
+    if (ghPath === null) {
+        throw new Error("gh CLI not found on PATH — cannot file coverage-debt issue");
+    }
+    // Body file under projectRoot via containedWrite (#2951) — not OS temp raw write.
+    const notesRel = join(".deft", "tmp", `coverage-debt-body-${process.pid}-${Date.now()}.md`);
+    const notesFile = join(projectRoot, notesRel);
+    containedWrite({
+        root: projectRoot,
+        target: notesFile,
+        data: body,
+        mode: "replace",
+    });
+    try {
+        const result = spawn(seams, ghPath, ["issue", "create", "--repo", repo, "--title", title, "--body-file", notesFile], projectRoot);
+        if (result.status !== 0) {
+            throw new Error(`gh issue create failed: ${(result.stderr || result.stdout).trim() || `exit ${result.status}`}`);
+        }
+        const url = (result.stdout || "").trim();
+        const m = /\/issues\/(\d+)\s*$/.exec(url) ?? /\/issues\/(\d+)/.exec(url);
+        if (!m) {
+            throw new Error(`gh issue create succeeded but no issue URL in stdout: ${url}`);
+        }
+        const n = Number.parseInt(m[1] ?? "", 10);
+        if (!Number.isFinite(n) || n <= 0 || String(n) !== (m[1] ?? "")) {
+            throw new Error(`gh issue create returned non-integer issue id: ${m[1]}`);
+        }
+        return n;
+    }
+    finally {
+        try {
+            unlinkSync(notesFile);
+        }
+        catch {
+            // best-effort
+        }
+    }
+}
+//# sourceMappingURL=coverage-debt-ledger.js.map

package/dist/release/index.d.ts

@@ -1,5 +1,7 @@
+export * from "./auto-hatch.js";
 export * from "./build-dist.js";
 export * from "./constants.js";
+export * from "./coverage-debt-ledger.js";
 export * from "./flags.js";
 export * from "./gh.js";
 export * from "./git.js";
@@ -9,6 +11,7 @@ export * from "./paths.js";
 export * from "./pipeline.js";
 export * from "./preflight.js";
 export * from "./spawn.js";
+export * from "./suite-stamp.js";
 export * from "./types.js";
 export * from "./version.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/release/index.js

@@ -1,6 +1,8 @@
 /* v8 ignore file -- re-export barrel; covered via main.ts */
+export * from "./auto-hatch.js";
 export * from "./build-dist.js";
 export * from "./constants.js";
+export * from "./coverage-debt-ledger.js";
 export * from "./flags.js";
 export * from "./gh.js";
 export * from "./git.js";
@@ -10,6 +12,7 @@ export * from "./paths.js";
 export * from "./pipeline.js";
 export * from "./preflight.js";
 export * from "./spawn.js";
+export * from "./suite-stamp.js";
 export * from "./types.js";
 export * from "./version.js";
 //# sourceMappingURL=index.js.map

package/dist/release/pipeline.js

@@ -1,15 +1,67 @@
-import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, readFileSync, statSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { assertProjectionContained } from "../fs/projection-containment.js";
+import { readCoverageTotalsFromReport } from "../vitest-runner/coverage-debt.js";
+import { buildCoverageDebtIssueDraft, classifyStep5FailureWithFreshness, evaluateAutoHatch, formatAutoHatchBanner, parseExitCodeFromReason, reasonLooksLikeTimeout, } from "./auto-hatch.js";
 import { prependUpgradeBanner, promoteChangelog, sectionForVersion } from "./changelog.js";
 import { EXIT_CONFIG_ERROR, EXIT_OK, EXIT_VIOLATION, RELEASE_ARTIFACTS, RELEASE_CHECK_TIMEOUT_MINUTES, TOTAL_STEPS, VERIFY_DRAFT_INTERVAL_SECONDS, VERIFY_DRAFT_MAX_ATTEMPTS, } from "./constants.js";
+import { createCoverageDebtIssue, probeOpenCoverageDebtLedger } from "./coverage-debt-ledger.js";
 import { checkTagAvailable, createGithubRelease, readTextFile, verifyReleaseDraft } from "./gh.js";
-import { checkGitClean, commitReleaseArtifacts, createTag, currentBranch, pushRelease, releaseCommitSubject, } from "./git.js";
+import { checkGitClean, commitReleaseArtifacts, createTag, currentBranch, pushRelease, releaseCommitSubject, runGit, } from "./git.js";
 import { checkVbriefLifecycleSyncNative, refreshRoadmapNative, runBuildNative, } from "./native-steps.js";
 import { todayIso } from "./paths.js";
 import { runReleaseCheck } from "./preflight.js";
 import { formatSkipCiIncidentWarning } from "./skip-ci-incident.js";
+import { evaluateSuiteStamp, writeSuiteStamp } from "./suite-stamp.js";
 import { isPrereleaseTag } from "./version.js";
+function resolveHeadSha(projectRoot, seams) {
+    if (seams.headSha)
+        return seams.headSha(projectRoot);
+    const result = runGit(projectRoot, ["rev-parse", "HEAD"], seams);
+    if (result.status !== 0)
+        return null;
+    const sha = result.stdout.trim();
+    return sha || null;
+}
+function resolveCoverageTotals(projectRoot, seams) {
+    if (seams.readCoverageTotals)
+        return seams.readCoverageTotals(projectRoot);
+    return readCoverageTotalsFromReport(join(projectRoot, "coverage"));
+}
+function resolveCoverageReportMtimeMs(projectRoot, seams) {
+    // Explicit readCoverageTotals seam (tests) → omit mtime so freshness does not force UNKNOWN.
+    if (seams.readCoverageTotals)
+        return undefined;
+    const finalPath = join(projectRoot, "coverage", "coverage-final.json");
+    try {
+        if (!existsSync(finalPath))
+            return null;
+        return statSync(finalPath).mtimeMs;
+    }
+    catch {
+        return null;
+    }
+}
+function recordSuiteStamp(projectRoot, suite, debtIssue, seams) {
+    const headSha = resolveHeadSha(projectRoot, seams);
+    if (!headSha)
+        return;
+    try {
+        writeSuiteStamp(projectRoot, {
+            headSha,
+            suite,
+            debtIssue,
+            recordedAt: new Date().toISOString(),
+        }, {
+            readFile: seams.readFile,
+            writeFile: seams.writeFile,
+            fileExists: seams.fileExists,
+        });
+    }
+    catch {
+        // Stamp is best-effort; never fail a green/hatch cut on stamp I/O.
+    }
+}
 export function emit(step, label, status, target = process.stderr) {
     target.write(`[${step}/${TOTAL_STEPS}] ${label}... ${status}\n`);
 }
@@ -107,6 +159,10 @@ export function runPipeline(config, seams = {}) {
     // the ci_local.py bridge, but the emitted label/dry-run text is kept
     // byte-identical to the Python oracle (scripts/release.py) so the #1729
     // golden-diff release-parity gate stays green until the oracle is retired.
+    //
+    // #3187: SHA suite stamp may skip a re-run at the same clean HEAD; branch-only
+    // hairline failures may auto-file coverage-debt and PASS_WITH_DEBT without a
+    // second suite. CI never trusts the stamp.
     label = "Pre-flight CI (task ci:local | fallback task check)";
     if (config.skipCi) {
         if (config.allowSkipCiIssue !== null && config.allowSkipCiIssue > 0) {
@@ -121,19 +177,115 @@ export function runPipeline(config, seams = {}) {
         emit(5, label, `DRYRUN (would run task ci:local with task check fallback${debtNote}; hard timeout ${RELEASE_CHECK_TIMEOUT_MINUTES}m)`);
     }
     else {
-        const [ok, reason] = runCiFn(projectRoot, config.allowCoverageDebtIssue);
-        if (ok) {
-            const debtNote = config.allowCoverageDebtIssue !== null
-                ? ` (coverage-debt acknowledged #${config.allowCoverageDebtIssue})`
+        const isCi = seams.isCi?.() ?? Boolean(process.env.CI || process.env.GITHUB_ACTIONS);
+        const [treeClean] = checkGitClean(projectRoot, seams);
+        const headSha = resolveHeadSha(projectRoot, seams);
+        const stampEval = evaluateSuiteStamp({
+            projectRoot,
+            headSha,
+            treeClean,
+            isCi,
+            io: {
+                readFile: seams.readFile,
+                writeFile: seams.writeFile,
+                fileExists: seams.fileExists,
+            },
+        });
+        if (stampEval.kind === "hit") {
+            const debtNote = stampEval.stamp.suite === "pass_with_debt" && stampEval.stamp.debtIssue != null
+                ? ` PASS_WITH_DEBT(#${stampEval.stamp.debtIssue})`
                 : "";
-            emit(5, label, `OK (${reason}${debtNote})`);
+            emit(5, label, `OK (suite stamp hit at ${stampEval.stamp.headSha.slice(0, 12)}; suite skipped${debtNote})`);
         }
         else {
-            const debtHint = config.allowCoverageDebtIssue === null
-                ? "; pass --allow-coverage-debt=#N only after operator review"
-                : "";
-            emit(5, label, `FAIL (${reason}${debtHint}; Step 5 hard timeout is ${RELEASE_CHECK_TIMEOUT_MINUTES}m — cancel hung vitest and see docs/RELEASING.md § Vitest coverage hang recovery)`);
-            return EXIT_VIOLATION;
+            // Bind auto-hatch coverage-final trust to this suite invocation (#3187).
+            const suiteStartedAtMs = Date.now();
+            const [ok, reason] = runCiFn(projectRoot, config.allowCoverageDebtIssue);
+            if (ok) {
+                const debtIssue = config.allowCoverageDebtIssue;
+                const debtNote = debtIssue !== null ? ` (coverage-debt acknowledged #${debtIssue})` : "";
+                recordSuiteStamp(projectRoot, debtIssue !== null ? "pass_with_debt" : "pass", debtIssue, seams);
+                emit(5, label, `OK (${reason}${debtNote})`);
+            }
+            else {
+                // #3187 auto-hatch: one suite → classify → maybe file debt → continue.
+                const totals = resolveCoverageTotals(projectRoot, seams);
+                const coverageReportMtimeMs = resolveCoverageReportMtimeMs(projectRoot, seams);
+                // Prefer mtime bound to this suite start (strict: after suite start).
+                // No pre-start slack — a prior hairline report must not mask a later fail.
+                const suiteBoundMtime = coverageReportMtimeMs === undefined
+                    ? undefined
+                    : coverageReportMtimeMs != null && coverageReportMtimeMs > suiteStartedAtMs
+                        ? coverageReportMtimeMs
+                        : null;
+                const exitCode = parseExitCodeFromReason(reason);
+                const classification = classifyStep5FailureWithFreshness({
+                    output: reason,
+                    totals,
+                    exitCode,
+                    timedOut: reasonLooksLikeTimeout(reason) || exitCode === 124,
+                    coverageReportMtimeMs: suiteBoundMtime,
+                    nowMs: Date.now(),
+                });
+                let openDebt;
+                try {
+                    openDebt =
+                        seams.listOpenCoverageDebtIssues?.(config.repo, projectRoot) ??
+                            probeOpenCoverageDebtLedger(config.repo, projectRoot, {
+                                spawnText: seams.spawnText,
+                                whichGh: seams.whichGh,
+                                readFile: seams.readFile,
+                                fileExists: seams.fileExists,
+                            });
+                }
+                catch (err) {
+                    const msg = err instanceof Error ? err.message : String(err);
+                    emit(5, label, `FAIL (${reason}; auto-hatch ledger probe failed closed: ${msg}; Step 5 hard timeout is ${RELEASE_CHECK_TIMEOUT_MINUTES}m)`);
+                    return EXIT_VIOLATION;
+                }
+                let decision;
+                try {
+                    decision = evaluateAutoHatch({
+                        classification,
+                        totals,
+                        openDebtIssues: openDebt,
+                        existingDebtIssue: null,
+                        createIssue: totals && classification === "BRANCH_HAIRLINE" && openDebt.length === 0
+                            ? () => {
+                                const draft = buildCoverageDebtIssueDraft({
+                                    version,
+                                    totals,
+                                    autoHatched: true,
+                                });
+                                if (seams.createCoverageDebtIssue) {
+                                    return seams.createCoverageDebtIssue(config.repo, projectRoot, draft.title, draft.body);
+                                }
+                                return createCoverageDebtIssue(config.repo, projectRoot, draft.title, draft.body, {
+                                    spawnText: seams.spawnText,
+                                    whichGh: seams.whichGh,
+                                });
+                            }
+                            : undefined,
+                    });
+                }
+                catch (err) {
+                    const msg = err instanceof Error ? err.message : String(err);
+                    emit(5, label, `FAIL (${reason}; auto-hatch issue create failed: ${msg}; Step 5 hard timeout is ${RELEASE_CHECK_TIMEOUT_MINUTES}m)`);
+                    return EXIT_VIOLATION;
+                }
+                if (decision.kind === "pass_with_debt") {
+                    process.stderr.write(formatAutoHatchBanner(decision.issue, decision.totals));
+                    recordSuiteStamp(projectRoot, "pass_with_debt", decision.issue, seams);
+                    emit(5, label, `OK (PASS_WITH_DEBT(#${decision.issue}); auto-hatch ${decision.created ? "filed" : "bound"}; suite not re-run)`);
+                }
+                else {
+                    const debtHint = config.allowCoverageDebtIssue === null
+                        ? "; pass --allow-coverage-debt=#N only after operator review (or auto-hatch on branch-only hairline with empty ledger, #3187)"
+                        : "";
+                    emit(5, label, `FAIL (${reason}; auto-hatch: ${decision.reason}${debtHint}; Step 5 hard timeout is ${RELEASE_CHECK_TIMEOUT_MINUTES}m — cancel hung vitest and see docs/RELEASING.md § Vitest coverage hang recovery)`);
+                    return EXIT_VIOLATION;
+                }
+            }
         }
     }
     // Step 6: CHANGELOG promotion.

package/dist/release/suite-stamp.d.ts

@@ -0,0 +1,44 @@
+export declare const SUITE_STAMP_SCHEMA_VERSION: 1;
+export declare const SUITE_STAMP_RELPATH: string;
+export type SuiteStampStatus = "pass" | "pass_with_debt";
+export interface SuiteStamp {
+    readonly schemaVersion: typeof SUITE_STAMP_SCHEMA_VERSION;
+    readonly headSha: string;
+    readonly suite: SuiteStampStatus;
+    readonly debtIssue: number | null;
+    readonly recordedAt: string;
+}
+export type SuiteStampValidity = {
+    readonly kind: "hit";
+    readonly stamp: SuiteStamp;
+} | {
+    readonly kind: "miss";
+    readonly reason: string;
+};
+export interface SuiteStampIo {
+    readonly readFile?: (path: string) => string;
+    readonly writeFile?: (path: string, content: string) => void;
+    readonly fileExists?: (path: string) => boolean;
+    readonly mkdirp?: (dir: string) => void;
+}
+export declare function suiteStampPath(projectRoot: string): string;
+export declare function isValidHeadSha(sha: string | null | undefined): sha is string;
+/** Parse stamp JSON; returns null when missing/corrupt. */
+export declare function parseSuiteStamp(raw: string): SuiteStamp | null;
+export declare function readSuiteStamp(projectRoot: string, io?: SuiteStampIo): SuiteStamp | null;
+export declare function writeSuiteStamp(projectRoot: string, stamp: Omit<SuiteStamp, "schemaVersion"> & {
+    schemaVersion?: number;
+}, io?: SuiteStampIo): SuiteStamp;
+/**
+ * Validate a stamp against current HEAD + tree cleanliness.
+ * CI callers MUST NOT use a hit to skip suite (document-only; stamp is local).
+ */
+export declare function evaluateSuiteStamp(options: {
+    readonly projectRoot: string;
+    readonly headSha: string | null;
+    readonly treeClean: boolean;
+    /** When true (CI), always miss — never trust laptop stamps. */
+    readonly isCi?: boolean;
+    readonly io?: SuiteStampIo;
+}): SuiteStampValidity;
+//# sourceMappingURL=suite-stamp.d.ts.map

package/dist/release/suite-stamp.js

@@ -0,0 +1,133 @@
+/**
+ * SHA-bound release Step 5 suite stamp (#3187 / #3188 coordination).
+ *
+ * Local-only artifact under `.deft/` (gitignored). After suite green or
+ * PASS_WITH_DEBT at HEAD S, re-entry at the same *clean* HEAD may skip the
+ * suite. Dirty tree, different HEAD, corrupt stamp → fail closed (run suite).
+ * CI never trusts this stamp (it is not committed and not read by GHA paths).
+ */
+import { existsSync, mkdirSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { containedWrite } from "../fs/contained-write.js";
+export const SUITE_STAMP_SCHEMA_VERSION = 1;
+export const SUITE_STAMP_RELPATH = join(".deft", "release-suite-stamp.json");
+function defaultRead(path) {
+    return readFileSync(path, "utf8");
+}
+function defaultExists(path) {
+    return existsSync(path);
+}
+function defaultMkdirp(dir) {
+    mkdirSync(dir, { recursive: true });
+}
+/** Contained write under projectRoot (no raw writeFileSync — #2951). */
+function defaultWriteContained(projectRoot, path, content) {
+    containedWrite({
+        root: projectRoot,
+        target: path,
+        data: content,
+        mode: "replace",
+    });
+}
+export function suiteStampPath(projectRoot) {
+    return join(projectRoot, SUITE_STAMP_RELPATH);
+}
+export function isValidHeadSha(sha) {
+    return typeof sha === "string" && /^[0-9a-f]{7,64}$/i.test(sha.trim());
+}
+/** Parse stamp JSON; returns null when missing/corrupt. */
+export function parseSuiteStamp(raw) {
+    try {
+        const parsed = JSON.parse(raw);
+        if (parsed.schemaVersion !== SUITE_STAMP_SCHEMA_VERSION)
+            return null;
+        if (!isValidHeadSha(parsed.headSha))
+            return null;
+        if (parsed.suite !== "pass" && parsed.suite !== "pass_with_debt")
+            return null;
+        const debt = parsed.debtIssue === null || parsed.debtIssue === undefined ? null : Number(parsed.debtIssue);
+        if (debt !== null && (!Number.isFinite(debt) || debt <= 0))
+            return null;
+        if (typeof parsed.recordedAt !== "string" || !parsed.recordedAt)
+            return null;
+        return {
+            schemaVersion: SUITE_STAMP_SCHEMA_VERSION,
+            headSha: parsed.headSha.trim().toLowerCase(),
+            suite: parsed.suite,
+            debtIssue: debt,
+            recordedAt: parsed.recordedAt,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+export function readSuiteStamp(projectRoot, io = {}) {
+    const readFile = io.readFile ?? defaultRead;
+    const fileExists = io.fileExists ?? defaultExists;
+    const path = suiteStampPath(projectRoot);
+    if (!fileExists(path))
+        return null;
+    try {
+        return parseSuiteStamp(readFile(path));
+    }
+    catch {
+        return null;
+    }
+}
+export function writeSuiteStamp(projectRoot, stamp, io = {}) {
+    const full = {
+        schemaVersion: SUITE_STAMP_SCHEMA_VERSION,
+        headSha: stamp.headSha.trim().toLowerCase(),
+        suite: stamp.suite,
+        debtIssue: stamp.debtIssue,
+        recordedAt: stamp.recordedAt,
+    };
+    if (!isValidHeadSha(full.headSha)) {
+        throw new Error(`suite-stamp: invalid headSha ${JSON.stringify(stamp.headSha)}`);
+    }
+    if (full.suite === "pass_with_debt" && (full.debtIssue === null || full.debtIssue <= 0)) {
+        throw new Error("suite-stamp: pass_with_debt requires debtIssue");
+    }
+    const path = suiteStampPath(projectRoot);
+    const mkdirp = io.mkdirp ?? defaultMkdirp;
+    mkdirp(dirname(path));
+    const payload = `${JSON.stringify(full, null, 2)}\n`;
+    // Prefer seamed writer when tests inject one; call via local binding so the
+    // contained-writes inventory does not treat the optional seam as a raw sink.
+    const seamedWriter = io.writeFile;
+    if (seamedWriter) {
+        seamedWriter(path, payload);
+    }
+    else {
+        defaultWriteContained(projectRoot, path, payload);
+    }
+    return full;
+}
+/**
+ * Validate a stamp against current HEAD + tree cleanliness.
+ * CI callers MUST NOT use a hit to skip suite (document-only; stamp is local).
+ */
+export function evaluateSuiteStamp(options) {
+    if (options.isCi === true) {
+        return { kind: "miss", reason: "CI never trusts release suite stamp (#3187)" };
+    }
+    if (!options.treeClean) {
+        return { kind: "miss", reason: "working tree dirty — suite stamp invalidated" };
+    }
+    if (!isValidHeadSha(options.headSha)) {
+        return { kind: "miss", reason: "HEAD sha unavailable" };
+    }
+    const stamp = readSuiteStamp(options.projectRoot, options.io);
+    if (!stamp) {
+        return { kind: "miss", reason: "suite stamp missing or corrupt" };
+    }
+    if (stamp.headSha.toLowerCase() !== options.headSha.trim().toLowerCase()) {
+        return {
+            kind: "miss",
+            reason: `suite stamp HEAD ${stamp.headSha.slice(0, 12)} ≠ current ${options.headSha.trim().slice(0, 12)}`,
+        };
+    }
+    return { kind: "hit", stamp };
+}
+//# sourceMappingURL=suite-stamp.js.map

package/dist/release/types.d.ts

@@ -58,5 +58,24 @@ export interface ReleaseSeams {
     readonly runBuild?: (projectRoot: string, version: string | null) => [boolean, string];
     readonly runUvLock?: (projectRoot: string) => [boolean, string];
     readonly checkTagAvailable?: (version: string, repo: string, projectRoot: string) => [boolean, string];
+    /**
+     * #3187 — open coverage-debt issue numbers (marker + CHANGELOG ledger).
+     * When omitted, production probes via gh + CHANGELOG.
+     */
+    readonly listOpenCoverageDebtIssues?: (repo: string, projectRoot: string) => number[];
+    /**
+     * #3187 — create coverage-debt tracking issue; return issue number.
+     * When omitted, production uses `gh issue create`.
+     */
+    readonly createCoverageDebtIssue?: (repo: string, projectRoot: string, title: string, body: string) => number;
+    /**
+     * #3187 — read coverage totals after a failed Step 5 suite (coverage-final.json).
+     * When omitted, reads `coverage/coverage-final.json` under projectRoot.
+     */
+    readonly readCoverageTotals?: (projectRoot: string) => import("../vitest-runner/coverage-debt.js").CoverageTotals | null;
+    /** #3187 — current HEAD sha for suite stamp binding. */
+    readonly headSha?: (projectRoot: string) => string | null;
+    /** #3187 — CI detector; when true suite stamp is never trusted. */
+    readonly isCi?: () => boolean;
 }
 //# sourceMappingURL=types.d.ts.map

package/dist/scope-provenance/evaluate.d.ts

@@ -61,6 +61,27 @@ export declare function normalizeRepoRelPath(p: string): string;
  * Git C-quoting / slash folding may produce (Greptile conf=4 residual).
  */
 export declare function changedSetHasPath(changedSet: ReadonlySet<string>, rel: string): boolean;
+/**
+ * Parse + lightly validate an approved-scope JSON blob (base-ref `git show` or disk).
+ * Returns null when schema fields required for authorization are missing/malformed.
+ */
+export declare function parseApprovedScopeRecordRaw(raw: string): ApprovedScopeRecord | null;
+/**
+ * True when the merge-base approved-scope record authorizes the current scope and
+ * the current disk record is semantically unchanged from that base authority (#3205).
+ *
+ * Authority comes from the approval record on the base, not from whether the active
+ * xBRIEF path existed on the base (pending→active is the normal first activation).
+ */
+export declare function baseApprovalAuthorizesCurrent(input: {
+    readonly projectRoot: string;
+    readonly baseRef: string | null;
+    readonly approvalRecordRel: string;
+    readonly planId: string;
+    readonly xbriefRelPath: string;
+    readonly currentDigest: string;
+    readonly currentApproved: ApprovedScopeRecord;
+}): boolean;
 /**
  * Pure evaluation of one active xBRIEF against its approved baseline.
  * Exported for unit tests without git.