@deftai/directive-core 0.100.0 → 0.102.0

package/dist/doctor/session-coda.js

@@ -0,0 +1,151 @@
+/**
+ * Optional deterministic session coda for interactive doctor success (#2712).
+ *
+ * Human TTY affordance only: never JSON, never AGENTS/skills, never exit-code
+ * changes. Env three-state DEFT_SESSION_CODA (unset / 1 / 0). Copy lives in
+ * content/doctor/session-coda.json — not embedded as an engine literal.
+ */
+import { readFileSync, realpathSync } from "node:fs";
+import { join } from "node:path";
+import { contentRoot } from "../content-root.js";
+/** Env var name (env-only v1; no USER.md key). */
+export const SESSION_CODA_ENV = "DEFT_SESSION_CODA";
+/**
+ * Fixed discoverability line when env is unset and gates pass (D3).
+ * Snapshot-stable; not selected from the pack; no ✦ prefix.
+ */
+export const SESSION_CODA_OFF_HINT = "Session coda: off (set DEFT_SESSION_CODA=1 to enable)";
+/** U+2726 FOUR RAYED STAR + space — stable; do not localize. */
+export const SESSION_CODA_STAR_PREFIX = "\u2726 ";
+/** Max body length; longer pack entries are skipped (fail-open). */
+export const SESSION_CODA_MAX_CHARS = 100;
+/** Relative path under contentRoot (source: content/doctor/…; deposit: doctor/…). */
+export const SESSION_CODA_REL_PATH = join("doctor", "session-coda.json");
+/**
+ * Map DEFT_SESSION_CODA to the three-state mode (D3).
+ * - undefined / "" → unset (discoverability off-hint)
+ * - "1" → on (✦ coda)
+ * - "0" → off (silent)
+ * - any other non-empty value → unset (show correct enable form)
+ */
+export function sessionCodaMode(envValue) {
+    if (envValue === undefined || envValue === "")
+        return "unset";
+    if (envValue === "1")
+        return "on";
+    if (envValue === "0")
+        return "off";
+    return "unset";
+}
+/**
+ * Whether any extra line (off-hint or coda) is allowed (D1 + surface gates).
+ * TTY = stdout.isTTY; CI truthy blocks; json blocks; exitOk = errorCount === 0.
+ */
+export function shouldEmitSessionCodaLine(input) {
+    return input.exitOk === true && input.tty === true && input.ci !== true && input.json !== true;
+}
+/**
+ * FNV-1a 32-bit (#2712). Documented choice for hash_u32(date + "\\0" + root).
+ * No Math.random; same inputs ⇒ same u32 on every platform.
+ */
+export function hashU32(input) {
+    let hash = 0x811c9dc5;
+    for (let i = 0; i < input.length; i += 1) {
+        hash ^= input.charCodeAt(i);
+        hash = Math.imul(hash, 0x01000193);
+    }
+    return hash >>> 0;
+}
+/** UTC calendar date yyyy-mm-dd from a Date (stable for 24h across a team day). */
+export function utcDateYmd(date) {
+    return date.toISOString().slice(0, 10);
+}
+/** Best-effort realpath; falls back to the given path when realpath fails. */
+export function projectRootRealpath(projectRoot) {
+    try {
+        return realpathSync(projectRoot);
+    }
+    catch {
+        return projectRoot;
+    }
+}
+/**
+ * Select one coda body from the pack (enabled path only).
+ * index = hash_u32(utc_date + "\\0" + project_root_realpath) % len(codas)
+ * Empty list → null (omit ✦; doctor still 0).
+ */
+export function selectSessionCoda(input) {
+    const { date, projectRoot, codas } = input;
+    if (codas.length === 0)
+        return null;
+    const key = `${date}\0${projectRoot}`;
+    const index = hashU32(key) % codas.length;
+    return codas[index] ?? null;
+}
+/** Skip non-strings and bodies over SESSION_CODA_MAX_CHARS. */
+export function filterCodaEntries(raw) {
+    if (!Array.isArray(raw))
+        return [];
+    const out = [];
+    for (const entry of raw) {
+        if (typeof entry !== "string")
+            continue;
+        if (entry.length === 0 || entry.length > SESSION_CODA_MAX_CHARS)
+            continue;
+        out.push(entry);
+    }
+    return out;
+}
+/**
+ * Load + filter coda lines from content. Fail-open: missing/unreadable/invalid
+ * / empty after filter → [] (omit ✦; no error noise).
+ */
+export function loadSessionCodas(frameworkRoot, readText) {
+    const packPath = join(contentRoot(frameworkRoot), SESSION_CODA_REL_PATH);
+    try {
+        const text = readText !== undefined ? readText(packPath) : readFileSync(packPath, { encoding: "utf8" });
+        if (text === null || text === "")
+            return [];
+        return filterCodaEntries(JSON.parse(text));
+    }
+    catch {
+        return [];
+    }
+}
+/** Format enabled coda line: ✦ + space + body. */
+export function formatSessionCodaEnabledLine(body) {
+    return `${SESSION_CODA_STAR_PREFIX}${body}`;
+}
+/**
+ * Resolve the single extra line (or null) after final success footer.
+ * Does not print; caller places after blank line post footer (D2).
+ */
+export function resolveSessionCodaLine(input) {
+    if (!input.shouldEmit)
+        return null;
+    if (input.mode === "off")
+        return null;
+    if (input.mode === "unset")
+        return SESSION_CODA_OFF_HINT;
+    const body = selectSessionCoda({
+        date: input.date,
+        projectRoot: input.projectRoot,
+        codas: input.codas,
+    });
+    if (body === null)
+        return null;
+    return formatSessionCodaEnabledLine(body);
+}
+/** Help / env-docs fragment for DEFT_SESSION_CODA three-state (#2712). */
+export function sessionCodaHelpText() {
+    return [
+        "Environment:",
+        `  ${SESSION_CODA_ENV}  Session coda after interactive success (exit 0, TTY, not CI, not --json):`,
+        "    unset  Print discoverability line:",
+        `           ${SESSION_CODA_OFF_HINT}`,
+        "    =1     Print one curated line, e.g.:",
+        `           ${formatSessionCodaEnabledLine("Doctor first. Then continue.")}`,
+        "    =0     Silent (no hint, no coda)",
+    ].join("\n");
+}
+//# sourceMappingURL=session-coda.js.map

package/dist/doctor/types.d.ts

@@ -123,6 +123,22 @@ export interface DoctorSeams {
         now?: Date;
     }) => string | null;
     readonly isTty?: () => boolean;
+    /**
+     * stdout TTY probe for session coda (#2712). Defaults to
+     * `process.stdout.isTTY === true` (not stdin). Separate from `isTty` (stdin
+     * used by --fix prompts).
+     */
+    readonly stdoutIsTty?: () => boolean;
+    /**
+     * Override DEFT_SESSION_CODA for tests (#2712). `undefined` means read
+     * process.env; pass `""` or omit via explicit nullish env simulation with
+     * `undefined` from a seam that returns undefined.
+     */
+    readonly sessionCodaEnv?: string | undefined;
+    /** Override CI env string for session coda gates (#2712). */
+    readonly ciEnv?: string | undefined;
+    /** Override session-coda pack loader for fail-open tests (#2712). */
+    readonly loadSessionCodas?: (frameworkRoot: string) => string[];
     readonly readYn?: (prompt: string, defaultYes: boolean) => boolean;
     readonly writeText?: (path: string, content: string) => void;
     readonly now?: () => Date;

package/dist/eval/later-graduation.d.ts

@@ -0,0 +1,39 @@
+/**
+ * #3286 Later graduation trigger from a #3282 run summary (#3320).
+ *
+ * Named surface: eval:report prints graduate / do-not-graduate / unevaluable.
+ * A graduation or decline MUST cite an emitted share. Counts without a
+ * denominator are unevaluable — never invent a ratio.
+ */
+import { type RitualGateShare } from "../run-summary/share.js";
+/** #3286 Later trigger: graduate when ritual+gate share is at least this fraction. */
+export declare const LATER_GRADUATION_SHARE_THRESHOLD = 0.25;
+export type LaterGraduationVerdict = "graduate" | "do-not-graduate" | "unevaluable";
+export interface LaterGraduationTrigger {
+    readonly evaluable: boolean;
+    readonly verdict: LaterGraduationVerdict;
+    readonly summary: string;
+    readonly ritualGateCount: number;
+    readonly totalToolTurns: number | null;
+    readonly share: number | null;
+    readonly threshold: number;
+}
+export interface EvaluateLaterGraduationOptions {
+    readonly projectRoot: string;
+    readonly runSummaryPath?: string;
+    readonly env?: NodeJS.ProcessEnv;
+    readonly threshold?: number;
+}
+export declare function laterGraduationFromShare(share: RitualGateShare, threshold?: number): LaterGraduationTrigger;
+/**
+ * Resolve a readable run-summary path. Unset env + missing default file → null
+ * (fail-open / unevaluable). stdout dest (`-`) is not a file.
+ */
+export declare function resolveRunSummaryReadPath(projectRoot: string, options?: {
+    readonly runSummaryPath?: string;
+    readonly env?: NodeJS.ProcessEnv;
+}): string | null;
+/** Evaluate #3286 Later from the run-summary file (or unevaluable). */
+export declare function evaluateLaterGraduationTrigger(options: EvaluateLaterGraduationOptions): LaterGraduationTrigger;
+export declare function formatLaterGraduationLine(trigger: LaterGraduationTrigger): string;
+//# sourceMappingURL=later-graduation.d.ts.map

package/dist/eval/later-graduation.js

@@ -0,0 +1,91 @@
+/**
+ * #3286 Later graduation trigger from a #3282 run summary (#3320).
+ *
+ * Named surface: eval:report prints graduate / do-not-graduate / unevaluable.
+ * A graduation or decline MUST cite an emitted share. Counts without a
+ * denominator are unevaluable — never invent a ratio.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { isAbsolute, resolve } from "node:path";
+import { computeRitualGateShare, parseRunSummaryJsonl, } from "../run-summary/share.js";
+import { DEFAULT_RUN_SUMMARY_BASENAME, ENV_RUN_SUMMARY_PATH } from "../run-summary/types.js";
+/** #3286 Later trigger: graduate when ritual+gate share is at least this fraction. */
+export const LATER_GRADUATION_SHARE_THRESHOLD = 0.25;
+function formatPercent(value) {
+    return `${(value * 100).toFixed(1)}%`;
+}
+export function laterGraduationFromShare(share, threshold = LATER_GRADUATION_SHARE_THRESHOLD) {
+    if (!share.evaluable || share.share === null || share.totalToolTurns === null) {
+        return {
+            evaluable: false,
+            verdict: "unevaluable",
+            summary: "trigger unevaluable (no tool/turn denominator on run summary)",
+            ritualGateCount: share.ritualGateCount,
+            totalToolTurns: share.totalToolTurns,
+            share: null,
+            threshold,
+        };
+    }
+    const graduate = share.share >= threshold;
+    const verdict = graduate ? "graduate" : "do-not-graduate";
+    return {
+        evaluable: true,
+        verdict,
+        summary: `ritual+gate share ${formatPercent(share.share)} (${share.ritualGateCount}/${share.totalToolTurns}) — ${verdict} (threshold ${formatPercent(threshold)})`,
+        ritualGateCount: share.ritualGateCount,
+        totalToolTurns: share.totalToolTurns,
+        share: share.share,
+        threshold,
+    };
+}
+/**
+ * Resolve a readable run-summary path. Unset env + missing default file → null
+ * (fail-open / unevaluable). stdout dest (`-`) is not a file.
+ */
+export function resolveRunSummaryReadPath(projectRoot, options = {}) {
+    if (options.runSummaryPath !== undefined && options.runSummaryPath.trim().length > 0) {
+        return resolve(options.runSummaryPath.trim());
+    }
+    const env = options.env ?? process.env;
+    const raw = env[ENV_RUN_SUMMARY_PATH];
+    if (raw !== undefined && raw.trim() === "-") {
+        return null;
+    }
+    if (raw !== undefined && raw.trim().length > 0) {
+        const trimmed = raw.trim();
+        return isAbsolute(trimmed) ? resolve(trimmed) : resolve(projectRoot, trimmed);
+    }
+    const fallback = resolve(projectRoot, DEFAULT_RUN_SUMMARY_BASENAME);
+    return existsSync(fallback) ? fallback : null;
+}
+function readSummaryText(path) {
+    try {
+        if (!existsSync(path)) {
+            return null;
+        }
+        return readFileSync(path, "utf8");
+    }
+    catch {
+        return null;
+    }
+}
+/** Evaluate #3286 Later from the run-summary file (or unevaluable). */
+export function evaluateLaterGraduationTrigger(options) {
+    const threshold = options.threshold ?? LATER_GRADUATION_SHARE_THRESHOLD;
+    const path = resolveRunSummaryReadPath(options.projectRoot, {
+        runSummaryPath: options.runSummaryPath,
+        env: options.env,
+    });
+    if (path === null) {
+        return laterGraduationFromShare({ evaluable: false, ritualGateCount: 0, totalToolTurns: null, share: null }, threshold);
+    }
+    const text = readSummaryText(path);
+    if (text === null) {
+        return laterGraduationFromShare({ evaluable: false, ritualGateCount: 0, totalToolTurns: null, share: null }, threshold);
+    }
+    return laterGraduationFromShare(computeRitualGateShare(parseRunSummaryJsonl(text)), threshold);
+}
+export function formatLaterGraduationLine(trigger) {
+    return `#3286 Later: ${trigger.summary}`;
+}
+//# sourceMappingURL=later-graduation.js.map

package/dist/eval/report.d.ts

@@ -1,3 +1,4 @@
+import { type LaterGraduationTrigger } from "./later-graduation.js";
 import { type GoldenRunRecord } from "./run.js";
 import { type CellVersionPurity, type MixedVersionPolicy } from "./version-pin.js";
 export declare const REPORT_SCHEMA_VERSION: 1;
@@ -39,6 +40,8 @@ export interface GoldenEvalReport {
     readonly holdoutTripwire: HoldoutTripwire;
     /** Cell-level framework version purity for the reported model (#3215). */
     readonly versionPurity: VersionPurityEvidence;
+    /** #3286 Later graduation trigger from the run-summary denominator (#3320). */
+    readonly laterGraduation: LaterGraduationTrigger;
 }
 export interface ReportGoldenEvalOptions {
     readonly projectRoot?: string;
@@ -50,6 +53,9 @@ export interface ReportGoldenEvalOptions {
      * ledger runs for this model disagree on framework version within a treatment.
      */
     readonly mixedVersionPolicy?: MixedVersionPolicy;
+    /** Override run-summary JSONL path (#3320). Default: DEFT_RUN_SUMMARY_PATH or repo default. */
+    readonly runSummaryPath?: string;
+    readonly env?: NodeJS.ProcessEnv;
 }
 export interface ReportGoldenEvalResult {
     readonly code: 0 | 1 | 2;

package/dist/eval/report.js

@@ -1,5 +1,6 @@
 import { existsSync, readFileSync } from "node:fs";
 import { resolveEvalPath } from "../layout/resolve.js";
+import { evaluateLaterGraduationTrigger, formatLaterGraduationLine, } from "./later-graduation.js";
 import { GOLDEN_RUNS_HISTORY_REL } from "./run.js";
 import { aggregateCellWithVersionPurity, evaluateLedgerVersionPurity, } from "./version-pin.js";
 export const REPORT_SCHEMA_VERSION = 1;
@@ -107,17 +108,33 @@ export function goldenRunToVersionedRun(record) {
 }
 /** Diff two directive versions with metric deltas and significance (#1703 Tier 2). */
 export function reportGoldenEval(options) {
-    if (!options.championVersion.trim() || !options.challengerVersion.trim()) {
+    const projectRoot = options.projectRoot ?? process.cwd();
+    const laterGraduation = evaluateLaterGraduationTrigger({
+        projectRoot,
+        runSummaryPath: options.runSummaryPath,
+        env: options.env,
+    });
+    const laterLine = formatLaterGraduationLine(laterGraduation);
+    const championMissing = !options.championVersion.trim();
+    const challengerMissing = !options.challengerVersion.trim();
+    const modelMissing = !options.model.trim();
+    if (championMissing && challengerMissing && modelMissing) {
+        return {
+            code: 0,
+            report: null,
+            message: `eval:report ${laterLine}`,
+        };
+    }
+    if (championMissing || challengerMissing) {
         return {
             code: 2,
             report: null,
-            message: "eval:report: --champion and --challenger are required",
+            message: `eval:report: --champion and --challenger are required\n  ${laterLine}`,
         };
     }
-    if (!options.model.trim()) {
-        return { code: 2, report: null, message: "eval:report: --model is required" };
+    if (modelMissing) {
+        return { code: 2, report: null, message: `eval:report: --model is required\n  ${laterLine}` };
     }
-    const projectRoot = options.projectRoot ?? process.cwd();
     const policy = options.mixedVersionPolicy ?? "refuse";
     const records = readGoldenRuns(projectRoot);
     const modelRecords = records.filter((r) => r.model === options.model);
@@ -157,7 +174,7 @@ export function reportGoldenEval(options) {
         return {
             code: 1,
             report: null,
-            message: `eval:report: mixed framework versions in treatment cell(s) — aggregation refused (#3215)\n  ${versionPurity.summary}`,
+            message: `eval:report: mixed framework versions in treatment cell(s) — aggregation refused (#3215)\n  ${versionPurity.summary}\n  ${laterLine}`,
         };
     }
     const champion = findLatestGoldenRun(records, options.championVersion, options.model);
@@ -166,14 +183,14 @@ export function reportGoldenEval(options) {
         return {
             code: 1,
             report: null,
-            message: `eval:report: no golden run found for champion v${options.championVersion} model=${options.model}`,
+            message: `eval:report: no golden run found for champion v${options.championVersion} model=${options.model}\n  ${laterLine}`,
         };
     }
     if (challenger === null) {
         return {
             code: 1,
             report: null,
-            message: `eval:report: no golden run found for challenger v${options.challengerVersion} model=${options.model}`,
+            message: `eval:report: no golden run found for challenger v${options.challengerVersion} model=${options.model}\n  ${laterLine}`,
         };
     }
     const championPrimary = champion.results.filter((r) => !r.holdout);
@@ -208,6 +225,7 @@ export function reportGoldenEval(options) {
         deltas,
         holdoutTripwire,
         versionPurity,
+        laterGraduation,
     };
     const lines = [
         `eval:report champion=v${options.championVersion} challenger=v${options.challengerVersion} model=${options.model}`,
@@ -223,6 +241,7 @@ export function reportGoldenEval(options) {
         `  version purity: ${versionPurity.pure ? "ok" : "mixed"} — ${versionPurity.summary}`,
         `  champion cell pin: v${champion.frameworkVersionPin?.frameworkVersion ?? champion.directiveVersion}`,
         `  challenger cell pin: v${challenger.frameworkVersionPin?.frameworkVersion ?? challenger.directiveVersion}`,
+        `  ${laterLine}`,
     ];
     const code = holdoutTripwire.triggered ? 1 : 0;
     return { code, report, message: lines.join("\n") };

package/dist/index.d.ts

@@ -48,12 +48,14 @@ export * as prMonitor from "./pr-monitor/index.js";
 export * as prProtectedIssues from "./pr-protected-issues/index.js";
 export * as prWaitMergeable from "./pr-wait-mergeable/index.js";
 export * as preflight from "./preflight/index.js";
+export * as productFirstDoneGate from "./product-first-done-gate/index.js";
 export * as release from "./release/index.js";
 export * as releaseE2e from "./release-e2e/index.js";
 export * as releasePublish from "./release-publish/index.js";
 export * as releaseRollback from "./release-rollback/index.js";
 export * as render from "./render/index.js";
 export * as resolution from "./resolution/index.js";
+export * as runSummary from "./run-summary/index.js";
 export * as scm from "./scm/index.js";
 export * as scope from "./scope/index.js";
 export * as scopeProvenance from "./scope-provenance/index.js";
@@ -72,6 +74,7 @@ export * as vbriefBuild from "./vbrief-build/index.js";
 export * as vbriefReconcile from "./vbrief-reconcile/index.js";
 export * as vbriefValidate from "./vbrief-validate/index.js";
 export * as vbriefValidation from "./vbrief-validation/index.js";
+export * as verifyAc from "./verify-ac/index.js";
 export * as verifyEnv from "./verify-env/index.js";
 export * as verifySource from "./verify-source/index.js";
 export * as wipCap from "./wip-cap/index.js";

package/dist/index.js

@@ -49,12 +49,14 @@ export * as prMonitor from "./pr-monitor/index.js";
 export * as prProtectedIssues from "./pr-protected-issues/index.js";
 export * as prWaitMergeable from "./pr-wait-mergeable/index.js";
 export * as preflight from "./preflight/index.js";
+export * as productFirstDoneGate from "./product-first-done-gate/index.js";
 export * as release from "./release/index.js";
 export * as releaseE2e from "./release-e2e/index.js";
 export * as releasePublish from "./release-publish/index.js";
 export * as releaseRollback from "./release-rollback/index.js";
 export * as render from "./render/index.js";
 export * as resolution from "./resolution/index.js";
+export * as runSummary from "./run-summary/index.js";
 export * as scm from "./scm/index.js";
 export * as scope from "./scope/index.js";
 export * as scopeProvenance from "./scope-provenance/index.js";
@@ -73,6 +75,7 @@ export * as vbriefBuild from "./vbrief-build/index.js";
 export * as vbriefReconcile from "./vbrief-reconcile/index.js";
 export * as vbriefValidate from "./vbrief-validate/index.js";
 export * as vbriefValidation from "./vbrief-validation/index.js";
+export * as verifyAc from "./verify-ac/index.js";
 export * as verifyEnv from "./verify-env/index.js";
 export * as verifySource from "./verify-source/index.js";
 export * as wipCap from "./wip-cap/index.js";

package/dist/init-deposit/gitignore.js

@@ -30,6 +30,8 @@ export const CANONICAL_GITIGNORE_BASELINE = [
     ".deft/ritual-state.json",
     ".deft/last-session.json",
     ".deft/routing.local.json",
+    // #3282: opt-in default run-summary JSONL at repo root (collectible; must not dirty trees).
+    ".deft-run-summary.json",
     // Temporary test/local kill-switch — must stay untracked (#3039).
     DEFT_DIRECTIVE_DISABLE_GITIGNORE_LINE,
     "vbrief/.triage-cache/candidates.jsonl",

package/dist/intake/issue-ingest.js

@@ -5,12 +5,15 @@ import { scan } from "../cache/scanner.js";
 import { assertWriteTargetSafe, ProjectionContainmentError } from "../fs/projection-containment.js";
 import { hasArtifactSuffix, resolveLifecycleRoot } from "../layout/resolve.js";
 import { captureAndAttachLiteralAcceptance } from "../literal-acceptance/index.js";
+import { stampAcceptanceFromLiteralCapture } from "../product-first-done-gate/index.js";
+import { ENV_RUN_SUMMARY_PATH, RunSummaryEmitter } from "../run-summary/index.js";
 import { call } from "../scm/call.js";
 import { resolveProjectRoot } from "../scope/project-context.js";
 import { resolveProjectRepo } from "../slice/project-context.js";
 import { countMaintainerCurrentShapeComments, mapIssueCommentEntry, RAW_ISSUE_COMMENTS_KEY, selectCurrentShapeComment, } from "../umbrella-current-shape/index.js";
 import { slugify, TODAY } from "../vbrief-build/build.js";
 import { EMITTED_VBRIEF_VERSION } from "../vbrief-build/constants.js";
+import { stampDerivedClausesOnAcceptance } from "../verify-ac/clauses.js";
 import { LEGACY_ARTIFACT_SUFFIX, LEGACY_INFO_ROOT_KEY, MIGRATED_ARTIFACT_DIR, MIGRATED_ARTIFACT_SUFFIX, MIGRATED_INFO_ROOT_KEY, VBRIEF_VERSION, } from "../xbrief-migrate/constants.js";
 import { findAcHeading, parseCheckboxItems, parseListItems, sliceAcSection, stripCodeBlocks, stripFencedCodeBlocks, } from "./markdown-scanners.js";
 import { detectRepo, extractReferencesFromVbrief, fetchOpenIssues, GITHUB_ISSUE_REF_TYPES, LIFECYCLE_FOLDERS, parseIssueNumber, } from "./reconcile-issues.js";
@@ -472,6 +475,15 @@ export function buildIssueVbrief(issue, status, repoUrl, options = {}) {
             }
         }
         Object.assign(plan, attached.plan);
+        // #3284: stamp plan.acceptance from captured literals (stated or none_stated floor).
+        Object.assign(plan, stampAcceptanceFromLiteralCapture(plan));
+        // #3323: when no commands were stated, derive numbered clauses before product edit.
+        const derived = stampDerivedClausesOnAcceptance(plan, [title, overviewSource].filter((s) => s.length > 0).join("\n\n"));
+        Object.assign(plan, derived.plan);
+    }
+    else {
+        // No body: still record none_stated acceptance so absence is a decision.
+        Object.assign(plan, stampAcceptanceFromLiteralCapture(plan));
     }
     const infoRootKey = options.infoRootKey ?? LEGACY_INFO_ROOT_KEY;
     const infoVersion = options.infoVersion ?? EMITTED_VBRIEF_VERSION;
@@ -711,8 +723,45 @@ export function ingestOne(issue, options) {
     assertWriteTargetSafe(projectRoot, target);
     mkdirSync(folderPath, { recursive: true });
     writeFileSync(target, `${JSON.stringify(vbrief, null, 2)}\n`, "utf8");
+    emitIntakeAcceptanceStamp(projectRoot, vbrief.plan);
     return ["created", target, `CREATED ${folder}/${filename}`];
 }
+function emitIntakeAcceptanceStamp(projectRoot, plan) {
+    const rec = plan !== null && typeof plan === "object" && !Array.isArray(plan)
+        ? plan
+        : null;
+    if (rec === null) {
+        return;
+    }
+    const acceptance = rec.acceptance !== null && typeof rec.acceptance === "object" && !Array.isArray(rec.acceptance)
+        ? rec.acceptance
+        : null;
+    if (acceptance === null) {
+        return;
+    }
+    const env = process.env;
+    const dest = env[ENV_RUN_SUMMARY_PATH];
+    if (dest === undefined || dest.trim().length === 0) {
+        return;
+    }
+    try {
+        const sessionId = typeof env.DEFT_SESSION_ID === "string" && env.DEFT_SESSION_ID.trim().length > 0
+            ? env.DEFT_SESSION_ID.trim()
+            : "issue-ingest";
+        const emitter = new RunSummaryEmitter({ projectRoot, sessionId, env });
+        const commands = Array.isArray(acceptance.commands) ? acceptance.commands.length : 0;
+        const clauses = Array.isArray(acceptance.clauses) ? acceptance.clauses.length : 0;
+        emitter.emitAcceptanceStamp({
+            rung: typeof acceptance.source_rung === "string" ? acceptance.source_rung : "project_floor",
+            none_stated: acceptance.none_stated === true,
+            command_count: commands,
+            clause_count: clauses,
+        });
+    }
+    catch {
+        // fail-open
+    }
+}
 export function ingestBulk(issues, options) {
     let filtered = issues;
     if (options.label !== undefined && options.label !== null) {

package/dist/policy/ac-pass-banking.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Typed plan.policy.acPassBanking (#3285).
+ *
+ * Surplus-threshold policy for post-AC-pass deepening: after the first
+ * stated-AC bank, agents may deepen only when remaining budget is at least
+ * this fraction of the hard max (default 0.2 = 20%).
+ *
+ * Composes #3266 bank-the-pass and product-first done-gate (#3284).
+ */
+/** Canonical dotted path for policy:show / PROJECT-DEFINITION. */
+export declare const FIELD_AC_PASS_BANKING = "plan.policy.acPassBanking";
+/** CLI alias for `task policy:show --field=acPassBanking`. */
+export declare const FIELD_AC_PASS_BANKING_CLI_ALIAS = "acPassBanking";
+/**
+ * Default surplus fraction of max turns/cost that must remain after bank
+ * before self-imposed deepening is allowed (#3285).
+ */
+export declare const DEFAULT_SURPLUS_THRESHOLD = 0.2;
+/** Floor / ceiling for surplusThreshold (inclusive). */
+export declare const SURPLUS_THRESHOLD_MIN = 0;
+export declare const SURPLUS_THRESHOLD_MAX = 1;
+/** Optional env override (fraction 0–1 or percent 0–100). */
+export declare const ENV_SURPLUS_THRESHOLD = "DEFT_AC_PASS_SURPLUS_THRESHOLD";
+export interface AcPassBankingConfig {
+    /**
+     * When false, surplus gate is inactive (unbounded / optional discipline only).
+     * Default true — the gate still only binds under a hard effort budget.
+     */
+    readonly enabled: boolean;
+    /**
+     * Minimum remaining fraction of max turns/cost required to deepen after bank.
+     * Default {@link DEFAULT_SURPLUS_THRESHOLD} (0.2).
+     */
+    readonly surplusThreshold: number;
+}
+export type AcPassBankingSource = "typed" | "env" | "default" | "default-on-error";
+export interface AcPassBankingResolved extends AcPassBankingConfig {
+    readonly source: AcPassBankingSource;
+    readonly error: string | null;
+}
+/** Parse a 0–1 fraction or a 0–100 percent string/number into a fraction. */
+export declare function parseSurplusThreshold(raw: unknown): number | null;
+/** Validate a `plan.policy.acPassBanking` payload. */
+export declare function validateAcPassBanking(value: unknown): string[];
+/**
+ * Resolve surplus policy from typed plan.policy.acPassBanking, then env,
+ * then defaults (#3285).
+ */
+export declare function resolveAcPassBanking(projectRoot?: string | null, environ?: Readonly<Record<string, string | undefined>>): AcPassBankingResolved;
+export interface AcPassBankingPolicyField {
+    readonly name: typeof FIELD_AC_PASS_BANKING;
+    readonly current: AcPassBankingConfig;
+    readonly default: AcPassBankingConfig;
+    readonly source: string;
+}
+/** Inspector row for `task policy:show --field=acPassBanking` (#3285). */
+export declare function inspectAcPassBanking(_data: Record<string, unknown> | null, projectRoot?: string): AcPassBankingPolicyField;
+//# sourceMappingURL=ac-pass-banking.d.ts.map