@deftai/directive-core 0.96.0 → 0.98.0

package/dist/policy/coverage-check-resume-presets.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Bundled presets for coverageDebt + checkResume (#3189).
+ *
+ * One project decision (not five micro-toggles in v1).
+ * Later does not write decided; Strict / Hatch-aware / dismiss-with-reason do.
+ *
+ * Both fields are written in a single PROJECT-DEFINITION mutation lock so a
+ * partial decision (coverageDebt decided, checkResume still unset) cannot
+ * persist after a mid-write failure.
+ */
+export declare const COVERAGE_CHECK_RESUME_PRESETS: readonly ["strict", "hatch-aware"];
+export type CoverageCheckResumePreset = (typeof COVERAGE_CHECK_RESUME_PRESETS)[number];
+export interface ApplyCoverageCheckResumePresetOptions {
+    readonly actor?: string;
+    readonly note?: string;
+}
+export interface ApplyCoverageCheckResumePresetResult {
+    readonly exitCode: 0 | 1 | 2;
+    readonly stdout: string;
+    readonly changed: boolean;
+    readonly preset: CoverageCheckResumePreset | "dismiss" | "later";
+}
+/** True when either policy is still unset (coupled v1 nag). */
+export declare function isCoverageCheckResumeUndecided(projectRoot: string): boolean;
+/**
+ * Apply Strict: coverageDebt.mode=off, checkResume.localStamp=off, both decided.
+ * Recommended for most apps.
+ */
+export declare function applyStrictCoverageCheckResumePreset(projectRoot: string, options?: ApplyCoverageCheckResumePresetOptions): ApplyCoverageCheckResumePresetResult;
+/**
+ * Apply Hatch-aware: coverageDebt.mode=hatch autoFile=false; localStamp=on for DX.
+ * CI still never trusts local stamps.
+ */
+export declare function applyHatchAwareCoverageCheckResumePreset(projectRoot: string, options?: ApplyCoverageCheckResumePresetOptions): ApplyCoverageCheckResumePresetResult;
+/**
+ * Dismiss-with-reason: marks both decided as fail-closed (mode off / localStamp off)
+ * and records the reason for policy:show / doctor visibility. Stops the session nag.
+ */
+export declare function dismissCoverageCheckResume(projectRoot: string, reason: string, options?: ApplyCoverageCheckResumePresetOptions): ApplyCoverageCheckResumePresetResult;
+/**
+ * Later: does NOT write status=decided. Caller skips for this session;
+ * next session-start ritual nags again.
+ */
+export declare function applyLaterCoverageCheckResumeSkip(): ApplyCoverageCheckResumePresetResult;
+export declare function formatCoverageCheckResumeBundleStatus(projectRoot: string): string;
+//# sourceMappingURL=coverage-check-resume-presets.d.ts.map

package/dist/policy/coverage-check-resume-presets.js

@@ -0,0 +1,228 @@
+/**
+ * Bundled presets for coverageDebt + checkResume (#3189).
+ *
+ * One project decision (not five micro-toggles in v1).
+ * Later does not write decided; Strict / Hatch-aware / dismiss-with-reason do.
+ *
+ * Both fields are written in a single PROJECT-DEFINITION mutation lock so a
+ * partial decision (coverageDebt decided, checkResume still unset) cannot
+ * persist after a mid-write failure.
+ */
+import { readFileSync } from "node:fs";
+import { atomicWriteProjectDefinition, projectDefinitionMutationLock, } from "../vbrief-build/project-definition-io.js";
+import { CHECK_RESUME_CI_TRUSTS_LOCAL_STAMP_V1, formatCheckResumeStatusLine, resolveCheckResume, resolveCheckResumeFromTypedBlock, } from "./check-resume.js";
+import { DEFAULT_COVERAGE_DEBT_AUTO_FILE, formatCoverageDebtStatusLine, resolveCoverageDebt, resolveCoverageDebtFromTypedBlock, } from "./coverage-debt.js";
+import { migrateLegacyPolicyKey, PLAN_POLICY_KEY } from "./plan-extensions.js";
+import { policyColonInvocation } from "./policy-invocation.js";
+import { appendAuditLog, projectDefinitionPath } from "./resolve.js";
+export const COVERAGE_CHECK_RESUME_PRESETS = ["strict", "hatch-aware"];
+/** True when either policy is still unset (coupled v1 nag). */
+export function isCoverageCheckResumeUndecided(projectRoot) {
+    const debt = resolveCoverageDebt(projectRoot);
+    const resume = resolveCheckResume(projectRoot);
+    return debt.status === "unset" || resume.status === "unset";
+}
+/**
+ * Atomically write both coverageDebt and checkResume under one mutation lock.
+ */
+function writeCoverageCheckResumeBundle(projectRoot, input) {
+    const path = projectDefinitionPath(projectRoot);
+    try {
+        const writeResult = projectDefinitionMutationLock(projectRoot, () => {
+            const parsed = JSON.parse(readFileSync(path, { encoding: "utf8" }));
+            if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+                throw new Error(`PROJECT-DEFINITION at ${path} top-level value is not a JSON object`);
+            }
+            const data = parsed;
+            if (typeof data.plan !== "object" || data.plan === null || Array.isArray(data.plan)) {
+                if (data.plan === undefined) {
+                    data.plan = {};
+                }
+                else {
+                    throw new Error("PROJECT-DEFINITION 'plan' is not an object");
+                }
+            }
+            const plan = data.plan;
+            migrateLegacyPolicyKey(plan);
+            const existingPolicy = plan[PLAN_POLICY_KEY];
+            if (typeof existingPolicy !== "object" ||
+                existingPolicy === null ||
+                Array.isArray(existingPolicy)) {
+                if (existingPolicy === undefined) {
+                    plan[PLAN_POLICY_KEY] = {};
+                }
+                else {
+                    throw new Error("plan.policy is not an object");
+                }
+            }
+            const policyBlock = plan[PLAN_POLICY_KEY];
+            const previousDebt = policyBlock.coverageDebt;
+            const previousResume = policyBlock.checkResume;
+            const autoFile = input.mode === "hatch" ? (input.autoFile ?? DEFAULT_COVERAGE_DEBT_AUTO_FILE) : false;
+            const dismissReason = typeof input.dismissReason === "string" && input.dismissReason.trim().length > 0
+                ? input.dismissReason.trim()
+                : null;
+            const nextDebt = {
+                status: "decided",
+                mode: input.mode,
+                autoFile,
+                dismissReason,
+            };
+            const nextResume = {
+                status: "decided",
+                localStamp: input.localStamp,
+                ciTrustsLocalStamp: CHECK_RESUME_CI_TRUSTS_LOCAL_STAMP_V1,
+                dismissReason,
+            };
+            const prevDebt = resolveCoverageDebtFromTypedBlock(previousDebt);
+            const prevResume = resolveCheckResumeFromTypedBlock(previousResume);
+            const changedFlag = prevDebt.status !== nextDebt.status ||
+                prevDebt.mode !== nextDebt.mode ||
+                prevDebt.autoFile !== nextDebt.autoFile ||
+                prevDebt.dismissReason !== nextDebt.dismissReason ||
+                prevResume.status !== nextResume.status ||
+                prevResume.localStamp !== nextResume.localStamp ||
+                prevResume.dismissReason !== nextResume.dismissReason;
+            // Single write of both keys — no partial decide on mid-failure.
+            policyBlock.coverageDebt = nextDebt;
+            policyBlock.checkResume = nextResume;
+            if (changedFlag) {
+                atomicWriteProjectDefinition(path, data);
+            }
+            let auditOk = true;
+            // Audit after durable write: failure must not reverse the decision, but
+            // the operator report must not claim the audit trail was updated.
+            try {
+                const note = input.note.replace(/\n/g, " ").replace(/\r/g, " ");
+                appendAuditLog(projectRoot, [
+                    `actor=${input.actor}`,
+                    `preset=${input.preset}`,
+                    "coverageDebt.status=decided",
+                    `mode=${nextDebt.mode}`,
+                    `autoFile=${String(nextDebt.autoFile)}`,
+                    "checkResume.status=decided",
+                    `localStamp=${nextResume.localStamp}`,
+                    "ciTrustsLocalStamp=false",
+                    `dismissReason=${JSON.stringify(dismissReason)}`,
+                    `previousDebt=${JSON.stringify(previousDebt ?? null)}`,
+                    `previousResume=${JSON.stringify(previousResume ?? null)}`,
+                    note ? `note=${note}` : "",
+                ]
+                    .filter(Boolean)
+                    .join(" "));
+            }
+            catch {
+                auditOk = false;
+            }
+            return { changed: changedFlag, auditOk };
+        });
+        const summary = formatCoverageCheckResumeBundleStatus(projectRoot);
+        const auditLine = writeResult.auditOk
+            ? writeResult.changed
+                ? "  audit: meta/policy-changes.log updated."
+                : "  no-op: value already matched (audit entry still appended for trail)."
+            : "  warning: policy write succeeded but audit log append failed; decision is durable.";
+        const lines = [
+            `\u2713 coverageDebt+checkResume decided via preset=${input.preset} (atomic write).`,
+            auditLine,
+            summary,
+        ];
+        return {
+            exitCode: 0,
+            stdout: `${lines.join("\n")}\n`,
+            changed: writeResult.changed,
+            preset: input.preset,
+        };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        if (message.includes("PROJECT-DEFINITION not found") ||
+            message.includes("ENOENT") ||
+            message.includes("no such file")) {
+            return {
+                exitCode: 2,
+                stdout: `\u274c PROJECT-DEFINITION not found under ${projectRoot}\n`,
+                changed: false,
+                preset: input.preset,
+            };
+        }
+        return {
+            exitCode: 2,
+            stdout: `\u274c Config error: ${message}\n`,
+            changed: false,
+            preset: input.preset,
+        };
+    }
+}
+/**
+ * Apply Strict: coverageDebt.mode=off, checkResume.localStamp=off, both decided.
+ * Recommended for most apps.
+ */
+export function applyStrictCoverageCheckResumePreset(projectRoot, options = {}) {
+    return writeCoverageCheckResumeBundle(projectRoot, {
+        mode: "off",
+        autoFile: false,
+        localStamp: "off",
+        actor: options.actor ?? policyColonInvocation("coverage-check-resume-preset", " strict"),
+        note: options.note ?? "preset=strict",
+        preset: "strict",
+    });
+}
+/**
+ * Apply Hatch-aware: coverageDebt.mode=hatch autoFile=false; localStamp=on for DX.
+ * CI still never trusts local stamps.
+ */
+export function applyHatchAwareCoverageCheckResumePreset(projectRoot, options = {}) {
+    return writeCoverageCheckResumeBundle(projectRoot, {
+        mode: "hatch",
+        autoFile: false,
+        localStamp: "on",
+        actor: options.actor ?? policyColonInvocation("coverage-check-resume-preset", " hatch-aware"),
+        note: options.note ?? "preset=hatch-aware",
+        preset: "hatch-aware",
+    });
+}
+/**
+ * Dismiss-with-reason: marks both decided as fail-closed (mode off / localStamp off)
+ * and records the reason for policy:show / doctor visibility. Stops the session nag.
+ */
+export function dismissCoverageCheckResume(projectRoot, reason, options = {}) {
+    const trimmed = reason.trim();
+    if (trimmed.length === 0) {
+        return {
+            exitCode: 1,
+            stdout: "\u274c dismiss-with-reason requires a non-empty reason " +
+                "(Later without a reason does not decide; re-nag next ritual).\n",
+            changed: false,
+            preset: "dismiss",
+        };
+    }
+    return writeCoverageCheckResumeBundle(projectRoot, {
+        mode: "off",
+        autoFile: false,
+        localStamp: "off",
+        dismissReason: trimmed,
+        actor: options.actor ?? policyColonInvocation("coverage-check-resume-dismiss"),
+        note: options.note ?? `dismiss=${trimmed}`,
+        preset: "dismiss",
+    });
+}
+/**
+ * Later: does NOT write status=decided. Caller skips for this session;
+ * next session-start ritual nags again.
+ */
+export function applyLaterCoverageCheckResumeSkip() {
+    return {
+        exitCode: 0,
+        stdout: "[deft policy] coverageDebt/checkResume: Later -- not decided. " +
+            "Fail-closed defaults remain (mode off, localStamp off, CI never trusts local stamps). " +
+            "Next interactive session-start ritual will remind you.\n",
+        changed: false,
+        preset: "later",
+    };
+}
+export function formatCoverageCheckResumeBundleStatus(projectRoot) {
+    return (`${formatCoverageDebtStatusLine(resolveCoverageDebt(projectRoot))}\n` +
+        `${formatCheckResumeStatusLine(resolveCheckResume(projectRoot))}`);
+}
+//# sourceMappingURL=coverage-check-resume-presets.js.map

package/dist/policy/coverage-debt.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Coverage-debt hatch policy (#3189).
+ *
+ * Consent / SoT surface for consumer expansion of release-originated hatch
+ * behavior (#3187). Unset is fail-closed for behavior (mode off) but still
+ * nags on interactive session-start until decided or dismissed with reason.
+ *
+ * Non-goal: a consumer tree never auto-files coverage-debt issues on
+ * deftai/directive -- ledger is always THIS repo.
+ */
+/** Canonical registered policy field name. */
+export declare const FIELD_COVERAGE_DEBT = "plan.policy.coverageDebt";
+/** Short alias for `policy:show --field=coverageDebt`. */
+export declare const FIELD_COVERAGE_DEBT_CLI_ALIAS = "coverageDebt";
+export declare const COVERAGE_DEBT_STATUSES: readonly ["unset", "decided"];
+export type CoverageDebtStatus = (typeof COVERAGE_DEBT_STATUSES)[number];
+export declare const COVERAGE_DEBT_MODES: readonly ["off", "warn", "hatch"];
+export type CoverageDebtMode = (typeof COVERAGE_DEBT_MODES)[number];
+/** Fail-closed effective mode when unset / missing / invalid. */
+export declare const DEFAULT_COVERAGE_DEBT_MODE: CoverageDebtMode;
+/** Consumers default autoFile false even under hatch mode. */
+export declare const DEFAULT_COVERAGE_DEBT_AUTO_FILE = false;
+export interface CoverageDebtConfig {
+    readonly status: CoverageDebtStatus;
+    readonly mode: CoverageDebtMode;
+    readonly autoFile: boolean;
+    /** Present when decided via dismiss-with-reason (still visible to show/doctor). */
+    readonly dismissReason: string | null;
+}
+export type CoverageDebtSource = "typed" | "default" | "default-on-error";
+export interface CoverageDebtResolved extends CoverageDebtConfig {
+    readonly source: CoverageDebtSource;
+    readonly error: string | null;
+}
+/** Validate a `plan.policy.coverageDebt` payload. */
+export declare function validateCoverageDebt(value: unknown): string[];
+/**
+ * Resolve a typed block. Missing/invalid → fail-closed mode off, status unset.
+ * Unset is not the same as decided-off for nag purposes.
+ */
+export declare function resolveCoverageDebtFromTypedBlock(raw: unknown): CoverageDebtResolved;
+/** Resolve `plan.policy.coverageDebt` from PROJECT-DEFINITION (#3189). */
+export declare function resolveCoverageDebt(projectRoot: string): CoverageDebtResolved;
+/** Effective hatch soft-pass allowed only when decided mode=hatch. */
+export declare function isCoverageDebtHatchAllowed(policy: CoverageDebtResolved): boolean;
+/** Auto-file debt issues only when hatch is allowed AND autoFile true. */
+export declare function isCoverageDebtAutoFileAllowed(policy: CoverageDebtResolved): boolean;
+/**
+ * Non-goal guard (#3189): consumer trees never auto-file coverage-debt on
+ * deftai/directive. Ledger is always the project under check.
+ */
+export declare function coverageDebtLedgerRepoIsSelfOnly(): true;
+export declare function formatCoverageDebtStatusLine(policy: CoverageDebtResolved): string;
+export interface CoverageDebtPolicyField {
+    readonly name: typeof FIELD_COVERAGE_DEBT;
+    readonly current: CoverageDebtConfig;
+    readonly default: CoverageDebtConfig;
+    readonly source: string;
+}
+/** Inspector row for `policy:show --field=coverageDebt`. */
+export declare function inspectCoverageDebt(data: Record<string, unknown> | null, projectRoot?: string): CoverageDebtPolicyField;
+export interface WriteCoverageDebtOptions {
+    readonly mode: CoverageDebtMode;
+    readonly autoFile?: boolean;
+    readonly dismissReason?: string | null;
+    readonly actor?: string;
+    readonly note?: string;
+}
+export interface WriteCoverageDebtResult {
+    readonly exitCode: 0 | 2;
+    readonly stdout: string;
+    readonly changed: boolean;
+}
+/** Persist decided coverageDebt (preset or dismiss-with-reason). */
+export declare function writeCoverageDebt(projectRoot: string, options: WriteCoverageDebtOptions): WriteCoverageDebtResult;
+//# sourceMappingURL=coverage-debt.d.ts.map

package/dist/policy/coverage-debt.js

@@ -0,0 +1,262 @@
+/**
+ * Coverage-debt hatch policy (#3189).
+ *
+ * Consent / SoT surface for consumer expansion of release-originated hatch
+ * behavior (#3187). Unset is fail-closed for behavior (mode off) but still
+ * nags on interactive session-start until decided or dismissed with reason.
+ *
+ * Non-goal: a consumer tree never auto-files coverage-debt issues on
+ * deftai/directive -- ledger is always THIS repo.
+ */
+import { readFileSync } from "node:fs";
+import { atomicWriteProjectDefinition, projectDefinitionMutationLock, } from "../vbrief-build/project-definition-io.js";
+import { migrateLegacyPolicyKey, PLAN_POLICY_KEY, readPlanPolicy } from "./plan-extensions.js";
+import { policyColonInvocation } from "./policy-invocation.js";
+import { appendAuditLog, loadProjectDefinition, projectDefinitionPath } from "./resolve.js";
+/** Canonical registered policy field name. */
+export const FIELD_COVERAGE_DEBT = "plan.policy.coverageDebt";
+/** Short alias for `policy:show --field=coverageDebt`. */
+export const FIELD_COVERAGE_DEBT_CLI_ALIAS = "coverageDebt";
+export const COVERAGE_DEBT_STATUSES = ["unset", "decided"];
+export const COVERAGE_DEBT_MODES = ["off", "warn", "hatch"];
+/** Fail-closed effective mode when unset / missing / invalid. */
+export const DEFAULT_COVERAGE_DEBT_MODE = "off";
+/** Consumers default autoFile false even under hatch mode. */
+export const DEFAULT_COVERAGE_DEBT_AUTO_FILE = false;
+function defaultResolved(source, error = null) {
+    return {
+        status: "unset",
+        mode: DEFAULT_COVERAGE_DEBT_MODE,
+        autoFile: DEFAULT_COVERAGE_DEBT_AUTO_FILE,
+        dismissReason: null,
+        source,
+        error,
+    };
+}
+function isMode(value) {
+    return typeof value === "string" && COVERAGE_DEBT_MODES.includes(value);
+}
+function isStatus(value) {
+    return typeof value === "string" && COVERAGE_DEBT_STATUSES.includes(value);
+}
+/** Validate a `plan.policy.coverageDebt` payload. */
+export function validateCoverageDebt(value) {
+    if (value === null || value === undefined) {
+        return [];
+    }
+    if (typeof value !== "object" || Array.isArray(value)) {
+        return [`${FIELD_COVERAGE_DEBT} must be an object; got ${typeof value}`];
+    }
+    const rec = value;
+    const errors = [];
+    if ("status" in rec && !isStatus(rec.status)) {
+        errors.push(`${FIELD_COVERAGE_DEBT}.status must be one of ${COVERAGE_DEBT_STATUSES.join("|")}`);
+    }
+    if ("mode" in rec && !isMode(rec.mode)) {
+        errors.push(`${FIELD_COVERAGE_DEBT}.mode must be one of ${COVERAGE_DEBT_MODES.join("|")}`);
+    }
+    if ("autoFile" in rec && typeof rec.autoFile !== "boolean") {
+        errors.push(`${FIELD_COVERAGE_DEBT}.autoFile must be a boolean`);
+    }
+    if ("dismissReason" in rec &&
+        rec.dismissReason !== null &&
+        typeof rec.dismissReason !== "string") {
+        errors.push(`${FIELD_COVERAGE_DEBT}.dismissReason must be a string or null`);
+    }
+    return errors;
+}
+/**
+ * Resolve a typed block. Missing/invalid → fail-closed mode off, status unset.
+ * Unset is not the same as decided-off for nag purposes.
+ */
+export function resolveCoverageDebtFromTypedBlock(raw) {
+    const errors = validateCoverageDebt(raw);
+    if (errors.length > 0) {
+        return defaultResolved("default-on-error", errors[0] ?? "invalid coverageDebt block");
+    }
+    if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+        return defaultResolved("default");
+    }
+    const block = raw;
+    const status = isStatus(block.status) ? block.status : "unset";
+    const mode = isMode(block.mode) ? block.mode : DEFAULT_COVERAGE_DEBT_MODE;
+    // Fail-closed: hatch modes only apply when decided.
+    const effectiveMode = status === "decided" ? mode : DEFAULT_COVERAGE_DEBT_MODE;
+    const autoFileRaw = typeof block.autoFile === "boolean" ? block.autoFile : DEFAULT_COVERAGE_DEBT_AUTO_FILE;
+    // autoFile only meaningful under hatch; never on when not hatch.
+    const autoFile = effectiveMode === "hatch" ? autoFileRaw : false;
+    const dismissReason = typeof block.dismissReason === "string" && block.dismissReason.trim().length > 0
+        ? block.dismissReason.trim()
+        : null;
+    return {
+        status,
+        mode: status === "decided" ? mode : DEFAULT_COVERAGE_DEBT_MODE,
+        autoFile,
+        dismissReason: status === "decided" ? dismissReason : null,
+        source: "typed",
+        error: null,
+    };
+}
+/** Resolve `plan.policy.coverageDebt` from PROJECT-DEFINITION (#3189). */
+export function resolveCoverageDebt(projectRoot) {
+    const [data, err] = loadProjectDefinition(projectRoot);
+    if (data === null) {
+        return defaultResolved("default-on-error", err);
+    }
+    const policyBlock = readPlanPolicy(data.plan);
+    if (typeof policyBlock !== "object" ||
+        policyBlock === null ||
+        Array.isArray(policyBlock) ||
+        !("coverageDebt" in policyBlock)) {
+        return defaultResolved("default");
+    }
+    return resolveCoverageDebtFromTypedBlock(policyBlock.coverageDebt);
+}
+/** Effective hatch soft-pass allowed only when decided mode=hatch. */
+export function isCoverageDebtHatchAllowed(policy) {
+    return policy.status === "decided" && policy.mode === "hatch";
+}
+/** Auto-file debt issues only when hatch is allowed AND autoFile true. */
+export function isCoverageDebtAutoFileAllowed(policy) {
+    return isCoverageDebtHatchAllowed(policy) && policy.autoFile === true;
+}
+/**
+ * Non-goal guard (#3189): consumer trees never auto-file coverage-debt on
+ * deftai/directive. Ledger is always the project under check.
+ */
+export function coverageDebtLedgerRepoIsSelfOnly() {
+    return true;
+}
+export function formatCoverageDebtStatusLine(policy) {
+    const dismiss = policy.dismissReason !== null ? ` dismissReason=${JSON.stringify(policy.dismissReason)}` : "";
+    return (`[deft policy] coverageDebt status=${policy.status} mode=${policy.mode} ` +
+        `autoFile=${String(policy.autoFile)}${dismiss} (source=${policy.source}).`);
+}
+function fieldFromResolved(resolved) {
+    return {
+        name: FIELD_COVERAGE_DEBT,
+        current: {
+            status: resolved.status,
+            mode: resolved.mode,
+            autoFile: resolved.autoFile,
+            dismissReason: resolved.dismissReason,
+        },
+        default: {
+            status: "unset",
+            mode: DEFAULT_COVERAGE_DEBT_MODE,
+            autoFile: DEFAULT_COVERAGE_DEBT_AUTO_FILE,
+            dismissReason: null,
+        },
+        source: resolved.source,
+    };
+}
+/** Inspector row for `policy:show --field=coverageDebt`. */
+export function inspectCoverageDebt(data, projectRoot) {
+    if (data === null) {
+        return fieldFromResolved(defaultResolved("default"));
+    }
+    const policyBlock = readPlanPolicy(data.plan);
+    if (typeof policyBlock !== "object" ||
+        policyBlock === null ||
+        Array.isArray(policyBlock) ||
+        !("coverageDebt" in policyBlock)) {
+        if (projectRoot !== undefined) {
+            return fieldFromResolved(resolveCoverageDebt(projectRoot));
+        }
+        return fieldFromResolved(defaultResolved("default"));
+    }
+    return fieldFromResolved(resolveCoverageDebtFromTypedBlock(policyBlock.coverageDebt));
+}
+/** Persist decided coverageDebt (preset or dismiss-with-reason). */
+export function writeCoverageDebt(projectRoot, options) {
+    const path = projectDefinitionPath(projectRoot);
+    try {
+        const { changed } = projectDefinitionMutationLock(projectRoot, () => {
+            const parsed = JSON.parse(readFileSync(path, { encoding: "utf8" }));
+            if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+                throw new Error(`PROJECT-DEFINITION at ${path} top-level value is not a JSON object`);
+            }
+            const data = parsed;
+            if (typeof data.plan !== "object" || data.plan === null || Array.isArray(data.plan)) {
+                if (data.plan === undefined) {
+                    data.plan = {};
+                }
+                else {
+                    throw new Error("PROJECT-DEFINITION 'plan' is not an object");
+                }
+            }
+            const plan = data.plan;
+            migrateLegacyPolicyKey(plan);
+            const existingPolicy = plan[PLAN_POLICY_KEY];
+            if (typeof existingPolicy !== "object" ||
+                existingPolicy === null ||
+                Array.isArray(existingPolicy)) {
+                if (existingPolicy === undefined) {
+                    plan[PLAN_POLICY_KEY] = {};
+                }
+                else {
+                    throw new Error("plan.policy is not an object");
+                }
+            }
+            const policyBlock = plan[PLAN_POLICY_KEY];
+            const previous = policyBlock.coverageDebt;
+            const autoFile = options.mode === "hatch" ? (options.autoFile ?? DEFAULT_COVERAGE_DEBT_AUTO_FILE) : false;
+            const dismissReason = typeof options.dismissReason === "string" && options.dismissReason.trim().length > 0
+                ? options.dismissReason.trim()
+                : null;
+            const nextBlock = {
+                status: "decided",
+                mode: options.mode,
+                autoFile,
+                dismissReason,
+            };
+            const previousNormalized = resolveCoverageDebtFromTypedBlock(previous);
+            const changedFlag = previousNormalized.status !== nextBlock.status ||
+                previousNormalized.mode !== nextBlock.mode ||
+                previousNormalized.autoFile !== nextBlock.autoFile ||
+                previousNormalized.dismissReason !== nextBlock.dismissReason;
+            policyBlock.coverageDebt = nextBlock;
+            if (changedFlag) {
+                atomicWriteProjectDefinition(path, data);
+            }
+            const actor = options.actor ?? policyColonInvocation("set-coverage-debt");
+            const note = options.note ?? "";
+            const parts = [
+                `actor=${actor}`,
+                "coverageDebt.status=decided",
+                `mode=${nextBlock.mode}`,
+                `autoFile=${String(nextBlock.autoFile)}`,
+                `dismissReason=${JSON.stringify(nextBlock.dismissReason)}`,
+                `previous=${JSON.stringify(previous ?? null)}`,
+            ];
+            if (note) {
+                parts.push(`note=${note.replace(/\n/g, " ").replace(/\r/g, " ")}`);
+            }
+            appendAuditLog(projectRoot, parts.join(" "));
+            return { changed: changedFlag };
+        });
+        const resolved = resolveCoverageDebt(projectRoot);
+        const lines = [
+            `\u2713 ${FIELD_COVERAGE_DEBT} status=decided mode=${resolved.mode}.`,
+            changed
+                ? "  audit: meta/policy-changes.log updated."
+                : "  no-op: value already matched (audit entry still appended for trail).",
+            formatCoverageDebtStatusLine(resolved),
+        ];
+        return { exitCode: 0, stdout: `${lines.join("\n")}\n`, changed };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        if (message.includes("PROJECT-DEFINITION not found") ||
+            message.includes("ENOENT") ||
+            message.includes("no such file")) {
+            return {
+                exitCode: 2,
+                stdout: `\u274c PROJECT-DEFINITION not found under ${projectRoot}\n`,
+                changed: false,
+            };
+        }
+        return { exitCode: 2, stdout: `\u274c Config error: ${message}\n`, changed: false };
+    }
+}
+//# sourceMappingURL=coverage-debt.js.map

package/dist/policy/index.d.ts

@@ -1,6 +1,9 @@
 export * from "./agents-md-advisory.js";
 export * from "./autonomy.js";
 export * from "./capacity.js";
+export * from "./check-resume.js";
+export * from "./coverage-check-resume-presets.js";
+export * from "./coverage-debt.js";
 export * from "./decisions.js";
 export * from "./deft-directive-disable.js";
 export * from "./delivery-branch.js";