@deftai/directive-core 0.100.0 → 0.101.0

package/dist/triage/classify/mirror-discovery-tip.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Operator discovery tip for SCM label mirror (#3124).
+ *
+ * Throttled existence + get-the-most-out-of-it disclosure for cold session /
+ * triage welcome / doctor. Hides after operator ack or first successful dry-run.
+ * Does not fire on session re-arm (welcome skipped).
+ *
+ * Never auto-apply; never auto-accept into proposed/.
+ */
+/** State file basename under xbrief/.triage-cache/. */
+export declare const MIRROR_DISCOVERY_STATE_FILE = "scm-label-mirror-discovery-state.json";
+/** Display/back-compat relative path. */
+export declare const MIRROR_DISCOVERY_STATE_RELATIVE_PATH: string;
+export interface MirrorDiscoveryState {
+    /** ISO timestamp when the tip was last emitted. */
+    readonly shownAt?: string;
+    /** ISO timestamp when the operator acked (tip stays hidden). */
+    readonly ackedAt?: string;
+    /** ISO timestamp of first successful --mirror dry-run (tip stays hidden). */
+    readonly successfulDryRunAt?: string;
+}
+export interface MirrorDiscoveryTipOptions {
+    readonly now?: Date;
+    readonly readState?: (path: string) => string | null;
+    readonly writeState?: (path: string, content: string) => void;
+    /** When false, evaluate eligibility without persisting shownAt. Default true. */
+    readonly recordShown?: boolean;
+}
+export declare function parseMirrorDiscoveryState(text: string | null): MirrorDiscoveryState;
+export declare function readMirrorDiscoveryState(projectRoot: string, options?: Pick<MirrorDiscoveryTipOptions, "readState">): MirrorDiscoveryState;
+/** True when tip should still surface (not acked and no successful dry-run yet). */
+export declare function isMirrorDiscoveryTipDue(projectRoot: string, options?: Pick<MirrorDiscoveryTipOptions, "readState">): boolean;
+/**
+ * Recommended full five-chip machine map for consumers (#3124 / #2611).
+ * Names only — do not invent vocabulary; labels must exist on GitHub.
+ */
+export declare const MIRROR_DISCOVERY_RECOMMENDED_ACTION_LABELS: {
+    readonly defer: readonly ["triage:deferred"];
+    readonly archive: readonly ["triage:archived"];
+    readonly accept: readonly ["triage:lifecycle-linked"];
+    readonly escalate: readonly ["triage:needs-human"];
+};
+/** Dry-run command shown in the tip (open-only default). */
+export declare const MIRROR_DISCOVERY_DRY_RUN_COMMAND = "deft triage:classify -- --mirror";
+/** Operator ack command that dismisses the tip without a dry-run (#3124 Greptile). */
+export declare const MIRROR_DISCOVERY_ACK_COMMAND = "deft triage:classify -- --ack-discovery";
+/** Policy inspect command. */
+export declare const MIRROR_DISCOVERY_POLICY_SHOW_COMMAND = "deft policy:show --field=plan.policy.triageLabelMirror";
+/**
+ * Agent-facing anti-swallow rule embedded in tip output (#3124).
+ * When this tip fires, agents MUST restate existence + get-the-most in the
+ * user-visible message (not only absorb ceremony output).
+ */
+export declare const MIRROR_DISCOVERY_ANTI_SWALLOW_RULE: string;
+/**
+ * Full operator-facing tip body (existence + get-the-most).
+ * Kept short enough for ceremony but complete enough for PROJECT-DEFINITION edits.
+ */
+export declare function formatMirrorDiscoveryTipBody(): string;
+export declare function formatMirrorDiscoveryTip(): string;
+/**
+ * Emit tip when due; record shownAt. Returns empty string when throttled.
+ * Fail-open on write errors (ceremony must not hard-block).
+ */
+export declare function maybeFormatMirrorDiscoveryTip(projectRoot: string, options?: MirrorDiscoveryTipOptions): string;
+/** Persist operator ack so the tip no longer surfaces. */
+export declare function recordMirrorDiscoveryAcked(projectRoot: string, options?: MirrorDiscoveryTipOptions): void;
+/**
+ * Persist first successful --mirror dry-run so the tip no longer surfaces.
+ * Idempotent: keeps the earliest successfulDryRunAt.
+ */
+export declare function recordMirrorDiscoverySuccessfulDryRun(projectRoot: string, options?: MirrorDiscoveryTipOptions): void;
+/** State path helper for tests / docs. */
+export declare function resolveMirrorDiscoveryStatePath(projectRoot: string): string;
+/** Whether a state file currently exists (tests / diagnostics). */
+export declare function mirrorDiscoveryStateExists(projectRoot: string): boolean;
+export interface MirrorDiscoveryDigestCueInput {
+    readonly planned: number;
+    readonly applied: number;
+    readonly skipped_no_match: number;
+    readonly skipped_already_triaged: number;
+    readonly skipped_closed: number;
+    readonly actionLabelsEmpty: boolean;
+    readonly dry_run: boolean;
+}
+/** Footer when planned rows exist but actionLabels is empty. */
+export declare const MIRROR_DISCOVERY_EMPTY_ACTION_LABELS_HINT: string;
+/** Footer when open no_match dominates under universal rules. */
+export declare const MIRROR_DISCOVERY_NO_MATCH_DOMINATION_HINT: string;
+/**
+ * Build optional digest footer lines for consumer upgrade cues.
+ * Empty when neither condition holds.
+ */
+export declare function formatMirrorDiscoveryDigestCues(input: MirrorDiscoveryDigestCueInput): readonly string[];
+//# sourceMappingURL=mirror-discovery-tip.d.ts.map

package/dist/triage/classify/mirror-discovery-tip.js

@@ -0,0 +1,234 @@
+/**
+ * Operator discovery tip for SCM label mirror (#3124).
+ *
+ * Throttled existence + get-the-most-out-of-it disclosure for cold session /
+ * triage welcome / doctor. Hides after operator ack or first successful dry-run.
+ * Does not fire on session re-arm (welcome skipped).
+ *
+ * Never auto-apply; never auto-accept into proposed/.
+ */
+import { existsSync, mkdirSync, readFileSync } from "node:fs";
+import { basename, dirname, join, resolve } from "node:path";
+import { containedWrite } from "../../fs/contained-write.js";
+import { resolveTriageCachePath } from "../cache-path.js";
+/** State file basename under xbrief/.triage-cache/. */
+export const MIRROR_DISCOVERY_STATE_FILE = "scm-label-mirror-discovery-state.json";
+/** Display/back-compat relative path. */
+export const MIRROR_DISCOVERY_STATE_RELATIVE_PATH = join("xbrief", ".triage-cache", MIRROR_DISCOVERY_STATE_FILE);
+function resolveStatePath(projectRoot) {
+    return resolveTriageCachePath(projectRoot, MIRROR_DISCOVERY_STATE_FILE);
+}
+function defaultReadState(path) {
+    try {
+        return readFileSync(path, "utf8");
+    }
+    catch {
+        return null;
+    }
+}
+function defaultWriteState(path, content) {
+    const dir = dirname(path);
+    mkdirSync(dir, { recursive: true });
+    // Direct contained write (no tmp/rename) — tip state is advisory and small.
+    const base = basename(path);
+    containedWrite({
+        root: resolve(dir),
+        target: base,
+        data: content,
+        mode: "replace",
+    });
+}
+export function parseMirrorDiscoveryState(text) {
+    if (text === null)
+        return {};
+    try {
+        const parsed = JSON.parse(text);
+        if (parsed !== null && typeof parsed === "object" && !Array.isArray(parsed)) {
+            const obj = parsed;
+            return {
+                ...(typeof obj.shownAt === "string" ? { shownAt: obj.shownAt } : {}),
+                ...(typeof obj.ackedAt === "string" ? { ackedAt: obj.ackedAt } : {}),
+                ...(typeof obj.successfulDryRunAt === "string"
+                    ? { successfulDryRunAt: obj.successfulDryRunAt }
+                    : {}),
+            };
+        }
+    }
+    catch {
+        // Corrupt advisory state never blocks ceremony.
+    }
+    return {};
+}
+export function readMirrorDiscoveryState(projectRoot, options = {}) {
+    const path = resolveStatePath(projectRoot);
+    const read = options.readState ?? defaultReadState;
+    return parseMirrorDiscoveryState(read(path));
+}
+function writeMirrorDiscoveryState(projectRoot, state, options = {}) {
+    const path = resolveStatePath(projectRoot);
+    const write = options.writeState ?? defaultWriteState;
+    write(path, `${JSON.stringify(state, null, 2)}\n`);
+}
+/** True when tip should still surface (not acked and no successful dry-run yet). */
+export function isMirrorDiscoveryTipDue(projectRoot, options = {}) {
+    const state = readMirrorDiscoveryState(projectRoot, options);
+    if (state.ackedAt !== undefined && state.ackedAt.length > 0)
+        return false;
+    if (state.successfulDryRunAt !== undefined && state.successfulDryRunAt.length > 0) {
+        return false;
+    }
+    return true;
+}
+/**
+ * Recommended full five-chip machine map for consumers (#3124 / #2611).
+ * Names only — do not invent vocabulary; labels must exist on GitHub.
+ */
+export const MIRROR_DISCOVERY_RECOMMENDED_ACTION_LABELS = {
+    defer: ["triage:deferred"],
+    archive: ["triage:archived"],
+    accept: ["triage:lifecycle-linked"],
+    escalate: ["triage:needs-human"],
+};
+/** Dry-run command shown in the tip (open-only default). */
+export const MIRROR_DISCOVERY_DRY_RUN_COMMAND = "deft triage:classify -- --mirror";
+/** Operator ack command that dismisses the tip without a dry-run (#3124 Greptile). */
+export const MIRROR_DISCOVERY_ACK_COMMAND = "deft triage:classify -- --ack-discovery";
+/** Policy inspect command. */
+export const MIRROR_DISCOVERY_POLICY_SHOW_COMMAND = "deft policy:show --field=plan.policy.triageLabelMirror";
+/**
+ * Agent-facing anti-swallow rule embedded in tip output (#3124).
+ * When this tip fires, agents MUST restate existence + get-the-most in the
+ * user-visible message (not only absorb ceremony output).
+ */
+export const MIRROR_DISCOVERY_ANTI_SWALLOW_RULE = "! Agent anti-swallow (#3124): when this tip fires, restate existence + get-the-most " +
+    "in the **user-visible** message (not ceremony dump alone): feature is default-on; " +
+    "dry-run first; defaults only stamp **triaged** on matches (control stamp, not disposition); " +
+    "board usability is greatly decreased without **actionLabels** (full five-chip map); " +
+    "more matches need **triageAutoClassify**; never auto-accept into proposed/; " +
+    "where policy lives + policy:show; labels must exist on GitHub; " +
+    "applying triaged before actionLabels skips re-enrichment on re-run; " +
+    "point at consumer kit #2611 — do not invent label vocabulary.";
+/**
+ * Full operator-facing tip body (existence + get-the-most).
+ * Kept short enough for ceremony but complete enough for PROJECT-DEFINITION edits.
+ */
+export function formatMirrorDiscoveryTipBody() {
+    const mapJson = JSON.stringify({
+        enabled: true,
+        idempotencyLabel: "triaged",
+        alwaysLabels: ["triaged"],
+        actionLabels: MIRROR_DISCOVERY_RECOMMENDED_ACTION_LABELS,
+    }, null, 2);
+    return [
+        "[deft triage] SCM label mirror discovery (#3124 / #1423):",
+        "  Feature exists and is **default-on** (plan.policy.triageLabelMirror resolves even when absent).",
+        `  Dry-run first (open-only default; --include-closed opt-in): \`${MIRROR_DISCOVERY_DRY_RUN_COMMAND}\``,
+        "  `--apply` writes labels in batches; **never** auto-accepts into proposed/ (triage:accept is separate).",
+        "  Defaults only stamp **`triaged`** on **matches** — a machine control stamp (idempotency), not a disposition board.",
+        "  **Board usability is greatly decreased without `actionLabels`** — every match looks like a single triaged chip.",
+        "  Recommend full five-chip map (create these labels on GitHub first, or apply fails closed):",
+        "    defer→triage:deferred, archive→triage:archived, accept→triage:lifecycle-linked,",
+        "    escalate→triage:needs-human (+ always triaged).",
+        "  Chip setup (all five) is separate from rule aggressiveness — start rules minimal; escalate carefully.",
+        "  More matches → configure `plan.policy.triageAutoClassify` in PROJECT-DEFINITION",
+        '    (xbrief/PROJECT-DEFINITION.xbrief.json → plan["x-directive/policy"] / docs: plan.policy.*).',
+        `  Inspect: \`${MIRROR_DISCOVERY_POLICY_SHOW_COMMAND}\` (and triageAutoClassify).`,
+        "  Labels must **exist on GitHub** (policy JSON alone is insufficient).",
+        "  Warn: applying triaged **before** actionLabels stamps issues that re-run then skips",
+        "    (use --mirror --re-enrich later for additive chips; #3197).",
+        "  Recommended consumer labels + PD sketch: consumer kit **#2611**",
+        "    (content/docs/consumer-issue-label-kit.md) — do not invent new triage:* vocabulary.",
+        "  Depth: commands.md § triage:classify --mirror; tip hides after first successful dry-run",
+        `    or operator ack: \`${MIRROR_DISCOVERY_ACK_COMMAND}\` (not every session re-arm).`,
+        "  Recommended PD sketch:",
+        ...mapJson.split("\n").map((line) => `    ${line}`),
+        MIRROR_DISCOVERY_ANTI_SWALLOW_RULE,
+    ].join("\n");
+}
+export function formatMirrorDiscoveryTip() {
+    return `${formatMirrorDiscoveryTipBody()}\n`;
+}
+/**
+ * Emit tip when due; record shownAt. Returns empty string when throttled.
+ * Fail-open on write errors (ceremony must not hard-block).
+ */
+export function maybeFormatMirrorDiscoveryTip(projectRoot, options = {}) {
+    if (!isMirrorDiscoveryTipDue(projectRoot, options)) {
+        return "";
+    }
+    if (options.recordShown !== false) {
+        try {
+            const now = options.now ?? new Date();
+            const prior = readMirrorDiscoveryState(projectRoot, options);
+            writeMirrorDiscoveryState(projectRoot, {
+                ...prior,
+                shownAt: now.toISOString(),
+            }, options);
+        }
+        catch {
+            // Advisory tip state must never block welcome / session start.
+        }
+    }
+    return formatMirrorDiscoveryTip();
+}
+/** Persist operator ack so the tip no longer surfaces. */
+export function recordMirrorDiscoveryAcked(projectRoot, options = {}) {
+    const now = options.now ?? new Date();
+    const prior = readMirrorDiscoveryState(projectRoot, options);
+    writeMirrorDiscoveryState(projectRoot, {
+        ...prior,
+        ackedAt: now.toISOString(),
+    }, options);
+}
+/**
+ * Persist first successful --mirror dry-run so the tip no longer surfaces.
+ * Idempotent: keeps the earliest successfulDryRunAt.
+ */
+export function recordMirrorDiscoverySuccessfulDryRun(projectRoot, options = {}) {
+    const prior = readMirrorDiscoveryState(projectRoot, options);
+    if (prior.successfulDryRunAt !== undefined && prior.successfulDryRunAt.length > 0) {
+        return;
+    }
+    const now = options.now ?? new Date();
+    writeMirrorDiscoveryState(projectRoot, {
+        ...prior,
+        successfulDryRunAt: now.toISOString(),
+    }, options);
+}
+/** State path helper for tests / docs. */
+export function resolveMirrorDiscoveryStatePath(projectRoot) {
+    return resolveStatePath(projectRoot);
+}
+/** Whether a state file currently exists (tests / diagnostics). */
+export function mirrorDiscoveryStateExists(projectRoot) {
+    return existsSync(resolveStatePath(projectRoot));
+}
+/** Footer when planned rows exist but actionLabels is empty. */
+export const MIRROR_DISCOVERY_EMPTY_ACTION_LABELS_HINT = "Hint (#3124): planned matches will only gain alwaysLabels (triaged) — " +
+    "set plan.policy.triageLabelMirror.actionLabels to map defer/archive/accept/escalate " +
+    "to extra SCM chips (full five recommended; see consumer kit #2611). " +
+    "Board usability is greatly decreased without actionLabels.";
+/** Footer when open no_match dominates under universal rules. */
+export const MIRROR_DISCOVERY_NO_MATCH_DOMINATION_HINT = "Hint (#3124): few open matches under current rules (no_match dominates) — " +
+    "add plan.policy.triageAutoClassify in PROJECT-DEFINITION to classify more of the backlog.";
+/**
+ * Build optional digest footer lines for consumer upgrade cues.
+ * Empty when neither condition holds.
+ */
+export function formatMirrorDiscoveryDigestCues(input) {
+    const lines = [];
+    const writeTotal = input.planned + input.applied;
+    if (writeTotal > 0 && input.actionLabelsEmpty) {
+        lines.push(MIRROR_DISCOVERY_EMPTY_ACTION_LABELS_HINT);
+    }
+    // Open-ish population: exclude closed_skipped from domination base.
+    const openish = writeTotal + input.skipped_no_match + Math.max(0, input.skipped_already_triaged);
+    if (input.skipped_no_match > 0 &&
+        openish > 0 &&
+        input.skipped_no_match >= writeTotal &&
+        input.skipped_no_match * 2 >= openish) {
+        lines.push(MIRROR_DISCOVERY_NO_MATCH_DOMINATION_HINT);
+    }
+    return lines;
+}
+//# sourceMappingURL=mirror-discovery-tip.js.map

package/dist/triage/reconcile/reconcile.js

@@ -1,7 +1,8 @@
 import { execFileSync } from "node:child_process";
 import { randomUUID } from "node:crypto";
-import { appendFileSync, mkdirSync } from "node:fs";
-import { dirname, resolve } from "node:path";
+import { mkdirSync } from "node:fs";
+import { dirname, isAbsolute, relative, resolve } from "node:path";
+import { containedWrite } from "../../fs/contained-write.js";
 import { resolveLifecycleFolder } from "../../layout/resolve.js";
 import { resolveCandidatesLogPath } from "../cache-path.js";
 import { auditKey, existingAuditRefs, scanLifecycleRefs } from "./audit.js";
@@ -127,9 +128,30 @@ function buildReconcileEntry(repo, issueNumber, sourceFolder) {
             "with a github-issue reference but no prior decision in the audit log",
     };
 }
-function appendAuditEntry(auditPath, entry) {
-    mkdirSync(dirname(auditPath), { recursive: true });
-    appendFileSync(auditPath, `${JSON.stringify(entry)}\n`, "utf8");
+/**
+ * Containment root for reconcile audit appends (#3288 / #3245).
+ * Prefer project root when the log is nested under it; otherwise parent dir.
+ */
+function containmentRootForAudit(projectRoot, auditPath) {
+    const rootAbs = resolve(projectRoot);
+    const logAbs = resolve(auditPath);
+    const parent = dirname(logAbs);
+    mkdirSync(parent, { recursive: true });
+    const rel = relative(rootAbs, logAbs);
+    if (rel.length > 0 && !rel.startsWith("..") && !isAbsolute(rel)) {
+        return rootAbs;
+    }
+    return resolve(parent);
+}
+/** #3288 / #3245 / #2980: product append refuses leaf symlink follow. */
+function appendAuditEntry(projectRoot, auditPath, entry) {
+    const root = containmentRootForAudit(projectRoot, auditPath);
+    containedWrite({
+        root,
+        target: auditPath,
+        data: `${JSON.stringify(entry)}\n`,
+        mode: "append",
+    });
 }
 export function reconcile(projectRoot, options = {}) {
     const root = resolve(projectRoot);
@@ -158,7 +180,7 @@ export function reconcile(projectRoot, options = {}) {
     for (const item of items) {
         const entry = buildReconcileEntry(item.repo, item.issueNumber, item.folder);
         try {
-            appendAuditEntry(auditPath, entry);
+            appendAuditEntry(root, auditPath, entry);
         }
         catch (err) {
             return {

package/dist/triage/summary/index.js

@@ -1,6 +1,7 @@
 import { createHash } from "node:crypto";
-import { appendFileSync, existsSync, mkdirSync, readdirSync, readFileSync } from "node:fs";
-import { join, resolve as pathResolve } from "node:path";
+import { existsSync, mkdirSync, readdirSync, readFileSync } from "node:fs";
+import { dirname, join, resolve as pathResolve } from "node:path";
+import { containedWrite } from "../../fs/contained-write.js";
 import { hasArtifactSuffix, resolveLifecycleFolder, resolveProjectDefinitionPath, } from "../../layout/resolve.js";
 import { readPlanPolicy } from "../../policy/plan-extensions.js";
 import { loadProjectDefinition, PROJECT_DEFINITION_REL_PATH } from "../../policy/resolve.js";
@@ -542,8 +543,15 @@ export function appendHistory(historyPath, result, line, options = {}) {
     });
     const payload = pythonStyleStringify(record);
     try {
-        mkdirSync(join(historyPath, ".."), { recursive: true });
-        appendFileSync(historyPath, `${payload}\n`, { encoding: "utf8" });
+        // #3288 / #3245 / #2980: refuse leaf symlink follow (in-tree diversion).
+        const parent = dirname(historyPath);
+        mkdirSync(parent, { recursive: true });
+        containedWrite({
+            root: pathResolve(parent),
+            target: historyPath,
+            data: `${payload}\n`,
+            mode: "append",
+        });
     }
     catch {
         // observability only — never crash the ritual

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

@@ -1,6 +1,7 @@
 import { resolve } from "node:path";
 import { ensureTriageCacheHydrated } from "../../cache/empty-populate.js";
 import { maybeSelfHealCache } from "../../cache/fetch.js";
+import { maybeFormatMirrorDiscoveryTip } from "../classify/mirror-discovery-tip.js";
 import { FIRST_TIME_NUDGE, INCOMPLETE_NUDGE_TEMPLATE } from "./constants.js";
 import { classifyOnboarding, detectPriorState } from "./prior-state.js";
 import { emitOneliner } from "./summary.js";
@@ -52,6 +53,21 @@ export function runDefaultMode(projectRoot, options = {}) {
     else if (label === "incomplete") {
         out(INCOMPLETE_NUDGE_TEMPLATE.replace("{missing}", missing.join(" + ")).replace(canonicalOnboard, onboardCommand));
     }
+    // #3124: throttled SCM label-mirror discovery tip (existence + get-the-most).
+    // Cold session:start runs this welcome path; re-arm skips welcome so tip is not spammed.
+    try {
+        const tip = maybeFormatMirrorDiscoveryTip(projectRoot, {
+            ...(options.now !== undefined ? { now: options.now } : {}),
+        });
+        if (tip.length > 0) {
+            for (const line of tip.trimEnd().split(/\r?\n/)) {
+                out(line);
+            }
+        }
+    }
+    catch {
+        // Discovery tip is advisory — never fail welcome.
+    }
     return outcome;
 }
 //# sourceMappingURL=default-mode.js.map

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

@@ -51,12 +51,12 @@ export function shouldUseShellForCommand(command, platform = process.platform) {
     return platform === "win32" && /\.(?:cmd|bat)$/i.test(command);
 }
 /** Default runner: an inherited-stdio pnpm invocation. */
-function defaultRunner(argv, cwd) {
+function defaultRunner(argv, cwd, envOverride) {
     const [command, ...rest] = argv;
     const commandPath = command ?? "";
     const result = spawnSync(commandPath, rest, {
         cwd,
-        env: sanitizeTsLaneEnv(process.env),
+        env: envOverride ?? sanitizeTsLaneEnv(process.env),
         stdio: "inherit",
         shell: shouldUseShellForCommand(commandPath),
     });
@@ -108,10 +108,27 @@ export function runTsLane(projectRoot, options) {
     }
     for (const command of LANE_COMMANDS) {
         const argv = [pnpm, ...command];
+        // Soft-pass via lane-private env (vitest 3 CAC rejects unknown CLI debt tokens).
+        // vitest.config reads DEFT_TS_LANE_COVERAGE_DEBT without DEFT_RELEASE_PREFLIGHT
+        // (sanitizeTsLaneEnv strips preflight). Refs #2573 / #2618.
+        const prevDebt = process.env.DEFT_TS_LANE_COVERAGE_DEBT;
         if (debtIssue !== null && command[1] === "test") {
-            argv.push("--", `--allow-coverage-debt=${debtIssue}`);
+            process.env.DEFT_TS_LANE_COVERAGE_DEBT = String(debtIssue);
+        }
+        let result;
+        try {
+            result = runner(argv, projectRoot);
+        }
+        finally {
+            if (debtIssue !== null && command[1] === "test") {
+                if (prevDebt === undefined) {
+                    delete process.env.DEFT_TS_LANE_COVERAGE_DEBT;
+                }
+                else {
+                    process.env.DEFT_TS_LANE_COVERAGE_DEBT = prevDebt;
+                }
+            }
         }
-        const result = runner(argv, projectRoot);
         const code = result.status;
         // A null status means the child was terminated by a signal (SIGKILL / OOM /
         // SIGTERM) before it could exit. Mapping that to 0 would silently pass a

package/dist/vbrief-validate/conformance.js

@@ -28,6 +28,8 @@ export const PLAN_CORE = new Set([
     "changeLog",
     "sequence",
     "fork",
+    // Product-first done-gate (#3284): plan.acceptance.commands / none_stated / source_rung.
+    "acceptance",
 ]);
 export const ITEM_CORE = new Set([
     "id",
@@ -62,6 +64,11 @@ export const ITEM_CORE = new Set([
     "lastModifiedBy",
     "lockedBy",
     "items",
+    // Optional PlanItem.effort enum S/M/L/XL (#1581) — schema-validated, core not extension.
+    "effort",
+    // #3305 Option B: acceptance evidence/disposition are NOT ITEM_CORE.
+    // Canonical keys: plan.items[].x-directive/evidence and x-directive/disposition
+    // (accepted via EXTENSION_PREFIXES). Bare evidence/disposition fail #1620.
 ]);
 export const EXTENSION_PREFIXES = ["x-directive/", "x-vbrief/", "x-xbrief/"];
 export function renderFinding(finding) {

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

@@ -1,14 +1,26 @@
 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() {
+function resolveDebtIssueForTeardown() {
     const resolution = resolveCoverageDebtIssue(process.argv, process.env);
-    if (resolution.kind === "none")
-        return;
+    if (resolution.kind === "valid")
+        return resolution;
     if (resolution.kind === "invalid") {
         throw new Error(`coverage-debt: ${resolution.reason}`);
     }
+    const laneRaw = process.env.DEFT_TS_LANE_COVERAGE_DEBT;
+    if (laneRaw !== undefined && /^\d+$/.test(laneRaw.trim())) {
+        const issue = Number.parseInt(laneRaw.trim(), 10);
+        if (issue > 0)
+            return { kind: "valid", issue };
+    }
+    return { kind: "none" };
+}
+/** Vitest globalTeardown: enforce coverage goal or debt soft-pass (#2573). */
+export default async function coverageDebtTeardown() {
+    const resolution = resolveDebtIssueForTeardown();
+    if (resolution.kind === "none")
+        return;
     const repoRoot = join(import.meta.dirname, "..", "..", "..", "..");
     const totals = readCoverageTotalsFromReport(join(repoRoot, "coverage"));
     if (totals === null) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deftai/directive-core",
-  "version": "0.100.0",
+  "version": "0.101.0",
   "description": "TypeScript engine core for the Directive framework.",
   "license": "MIT",
   "type": "module",
@@ -287,6 +287,10 @@
       "types": "./dist/literal-acceptance/index.d.ts",
       "default": "./dist/literal-acceptance/index.js"
     },
+    "./product-first-done-gate": {
+      "types": "./dist/product-first-done-gate/index.d.ts",
+      "default": "./dist/product-first-done-gate/index.js"
+    },
     "./packs": {
       "types": "./dist/packs/index.d.ts",
       "default": "./dist/packs/index.js"
@@ -315,6 +319,10 @@
       "types": "./dist/check/index.d.ts",
       "default": "./dist/check/index.js"
     },
+    "./run-summary": {
+      "types": "./dist/run-summary/index.d.ts",
+      "default": "./dist/run-summary/index.js"
+    },
     "./preflight-gh": {
       "types": "./dist/preflight-gh/index.d.ts",
       "default": "./dist/preflight-gh/index.js"
@@ -370,8 +378,8 @@
     "provenance": true
   },
   "dependencies": {
-    "@deftai/directive-content": "^0.100.0",
-    "@deftai/directive-types": "^0.100.0",
+    "@deftai/directive-content": "^0.101.0",
+    "@deftai/directive-types": "^0.101.0",
     "archiver": "^8.0.0"
   },
   "scripts": {