@deftai/directive-core 0.100.0 → 0.102.0

package/dist/run-summary/types.js

@@ -0,0 +1,28 @@
+/**
+ * Run-summary telemetry types (#3282).
+ *
+ * Event-driven JSONL lines for harness collection. Silent by default unless
+ * `DEFT_RUN_SUMMARY_PATH` is set (or the gitignored default path is writable).
+ */
+export const RUN_SUMMARY_SCHEMA_VERSION = 1;
+/** Env var that opts into / redirects run-summary JSONL (#3282). */
+export const ENV_RUN_SUMMARY_PATH = "DEFT_RUN_SUMMARY_PATH";
+/** Harness-supplied session tool/turn total stamped onto run-summary lines (#3320). */
+export const ENV_TOTAL_TOOL_TURNS = "DEFT_TOTAL_TOOL_TURNS";
+/** Repo-root default collectible path when gitignore coverage is present. */
+export const DEFAULT_RUN_SUMMARY_BASENAME = ".deft-run-summary.json";
+/** Prefix for stdout lines when `DEFT_RUN_SUMMARY_PATH=-`. */
+export const RUN_SUMMARY_STDOUT_PREFIX = "DEFT-TLM:";
+/** One warning when an explicitly requested write fails. */
+export const RUN_SUMMARY_WRITE_WARNING = "[deft run-summary] failed to write DEFT_RUN_SUMMARY_PATH telemetry (fail-open; exit codes unchanged)";
+export const RUN_SUMMARY_EVENT_KINDS = [
+    "session_start",
+    "dial_transition",
+    "dial_escalation_evaluation",
+    "check_invocation",
+    "tool_turn_denominator",
+    "verification",
+    "acceptance",
+    "acceptance_stamp",
+];
+//# sourceMappingURL=types.js.map

package/dist/scope/acceptance-activate-gate.d.ts

@@ -0,0 +1,23 @@
+/**
+ * scope:activate refuses acceptance-shaped narratives without plan.acceptance (#3334).
+ *
+ * Agents author Test / AcceptanceCriteria / Verification prose in narratives
+ * and then skip the executable plan.acceptance block. Activation fails closed
+ * with one remediation: stamp the acceptance block.
+ */
+export interface AcceptanceActivateHit {
+    readonly key: string;
+}
+export interface AcceptanceActivateGateResult {
+    readonly ok: boolean;
+    readonly message: string;
+    readonly hits: readonly AcceptanceActivateHit[];
+}
+/** Narrative keys that look like authored acceptance (non-empty string values). */
+export declare function collectAcceptanceShapedNarrativeKeys(narratives: Record<string, unknown>): AcceptanceActivateHit[];
+/**
+ * Fail closed when narratives carry acceptance-shaped keys and plan.acceptance
+ * is absent. A stamped (even empty/none_stated) block is enough.
+ */
+export declare function evaluateAcceptanceActivateGate(plan: Record<string, unknown>): AcceptanceActivateGateResult;
+//# sourceMappingURL=acceptance-activate-gate.d.ts.map

package/dist/scope/acceptance-activate-gate.js

@@ -0,0 +1,70 @@
+/**
+ * scope:activate refuses acceptance-shaped narratives without plan.acceptance (#3334).
+ *
+ * Agents author Test / AcceptanceCriteria / Verification prose in narratives
+ * and then skip the executable plan.acceptance block. Activation fails closed
+ * with one remediation: stamp the acceptance block.
+ */
+import { validatePlanAcceptance } from "../product-first-done-gate/acceptance.js";
+function asRecord(value) {
+    if (typeof value === "object" && value !== null && !Array.isArray(value)) {
+        return value;
+    }
+    return null;
+}
+const ACCEPTANCE_SHAPED_KEYS = new Set(["test", "acceptancecriteria", "verification"]);
+function normalizeNarrativeKey(key) {
+    return key.replace(/[\s_-]+/g, "").toLowerCase();
+}
+/** Narrative keys that look like authored acceptance (non-empty string values). */
+export function collectAcceptanceShapedNarrativeKeys(narratives) {
+    const hits = [];
+    for (const key of Object.keys(narratives)) {
+        if (!ACCEPTANCE_SHAPED_KEYS.has(normalizeNarrativeKey(key))) {
+            continue;
+        }
+        const value = narratives[key];
+        if (typeof value !== "string" || value.trim().length === 0) {
+            continue;
+        }
+        hits.push({ key });
+    }
+    return hits;
+}
+/**
+ * Fail closed when narratives carry acceptance-shaped keys and plan.acceptance
+ * is absent. A stamped (even empty/none_stated) block is enough.
+ */
+export function evaluateAcceptanceActivateGate(plan) {
+    const narratives = asRecord(plan.narratives);
+    if (narratives === null) {
+        return { ok: true, message: "", hits: [] };
+    }
+    const hits = collectAcceptanceShapedNarrativeKeys(narratives);
+    if (hits.length === 0) {
+        return { ok: true, message: "", hits: [] };
+    }
+    if (plan.acceptance !== undefined && plan.acceptance !== null) {
+        const schemaErrors = validatePlanAcceptance(plan.acceptance);
+        if (schemaErrors.length > 0) {
+            return {
+                ok: false,
+                message: `Refusing activate: plan.acceptance is present but invalid (#3334): ` +
+                    `${schemaErrors.join("; ")}. Stamp a valid plan.acceptance block ` +
+                    `(author commands or none_stated via intake capture / task issue:ingest).`,
+                hits,
+            };
+        }
+        return { ok: true, message: "", hits };
+    }
+    const keys = hits.map((h) => h.key).join(", ");
+    return {
+        ok: false,
+        message: `Refusing activate: narratives contain acceptance-shaped keys (${keys}) ` +
+            `but plan.acceptance is absent (#3334). Stamp plan.acceptance ` +
+            `(author commands or none_stated via intake capture / task issue:ingest) — ` +
+            `the criteria are in the wrong, non-executable field.`,
+        hits,
+    };
+}
+//# sourceMappingURL=acceptance-activate-gate.js.map

package/dist/scope/acceptance-evidence.d.ts

@@ -5,8 +5,18 @@
  * plan item needs either typed evidence or a human-origin disposition before complete
  * may advance it. Kind suitability: merge/review alone cannot satisfy smoke, UAT,
  * deploy, or observed_behavior requirements.
+ *
+ * Canonical item keys are namespaced under #1620 / #3305 (Option B):
+ * - plan.items[].x-directive/evidence
+ * - plan.items[].x-directive/disposition
+ * Bare `evidence` / `disposition` are not valid typed evidence (no dual-read).
+ * ITEM_CORE is not expanded with bare keys; verify:vbrief-conformance rejects them.
  */
 import type { GrantOrigin } from "../authz/types.js";
+/** Canonical namespaced key for typed acceptance evidence (#3305 / #1620). */
+export declare const ACCEPTANCE_EVIDENCE_KEY: "x-directive/evidence";
+/** Canonical namespaced key for human-origin disposition (#3305 / #1620). */
+export declare const ACCEPTANCE_DISPOSITION_KEY: "x-directive/disposition";
 /** Closed evidence kinds (locked Q3). */
 export declare const ACCEPTANCE_EVIDENCE_KINDS: readonly ["test", "review", "merge", "deploy", "smoke", "uat", "observed_behavior"];
 export type AcceptanceEvidenceKind = (typeof ACCEPTANCE_EVIDENCE_KINDS)[number];
@@ -64,6 +74,30 @@ export declare function inferRequiredStrictAxes(item: Record<string, unknown>):
  * or record a human-origin disposition (#3240 Greptile P1).
  */
 export declare function isEvidenceKindSuitable(kind: AcceptanceEvidenceKind, requiredAxes: readonly StrictAcceptanceAxis[]): boolean;
+/**
+ * Read only namespaced acceptance fields (#3305). Bare `evidence` / `disposition`
+ * are never treated as success (no permanent dual-read).
+ */
+export declare function readNamespacedAcceptanceFields(item: Record<string, unknown>): {
+    readonly evidence: unknown;
+    readonly disposition: unknown;
+    readonly hasEvidence: boolean;
+    readonly hasDisposition: boolean;
+    readonly hasBareEvidence: boolean;
+    readonly hasBareDisposition: boolean;
+};
+/**
+ * Stamp typed evidence under the canonical namespaced key only.
+ * Clears bare evidence/disposition and any prior namespaced disposition so the item
+ * cannot carry both acceptance fields after a replace (#3305 Greptile P2).
+ */
+export declare function stampNamespacedEvidence(item: Record<string, unknown>, record: AcceptanceEvidenceRecord): void;
+/**
+ * Stamp human-origin disposition under the canonical namespaced key only.
+ * Clears bare evidence/disposition and any prior namespaced evidence so the item
+ * cannot carry both acceptance fields after a replace (#3305 Greptile P2).
+ */
+export declare function stampNamespacedDisposition(item: Record<string, unknown>, record: AcceptanceDispositionRecord): void;
 /**
  * Fail closed when any non-terminal plan item lacks suitable evidence or a human-origin disposition.
  */

package/dist/scope/acceptance-evidence.js

@@ -5,8 +5,18 @@
  * plan item needs either typed evidence or a human-origin disposition before complete
  * may advance it. Kind suitability: merge/review alone cannot satisfy smoke, UAT,
  * deploy, or observed_behavior requirements.
+ *
+ * Canonical item keys are namespaced under #1620 / #3305 (Option B):
+ * - plan.items[].x-directive/evidence
+ * - plan.items[].x-directive/disposition
+ * Bare `evidence` / `disposition` are not valid typed evidence (no dual-read).
+ * ITEM_CORE is not expanded with bare keys; verify:vbrief-conformance rejects them.
  */
 import { isHumanOrigin } from "../authz/origin.js";
+/** Canonical namespaced key for typed acceptance evidence (#3305 / #1620). */
+export const ACCEPTANCE_EVIDENCE_KEY = "x-directive/evidence";
+/** Canonical namespaced key for human-origin disposition (#3305 / #1620). */
+export const ACCEPTANCE_DISPOSITION_KEY = "x-directive/disposition";
 /** Closed evidence kinds (locked Q3). */
 export const ACCEPTANCE_EVIDENCE_KINDS = [
     "test",
@@ -215,37 +225,100 @@ function itemLabel(item, path) {
     }
     return path;
 }
+/**
+ * Read only namespaced acceptance fields (#3305). Bare `evidence` / `disposition`
+ * are never treated as success (no permanent dual-read).
+ */
+export function readNamespacedAcceptanceFields(item) {
+    const evidence = item[ACCEPTANCE_EVIDENCE_KEY];
+    const disposition = item[ACCEPTANCE_DISPOSITION_KEY];
+    return {
+        evidence,
+        disposition,
+        hasEvidence: evidence !== undefined && evidence !== null,
+        hasDisposition: disposition !== undefined && disposition !== null,
+        hasBareEvidence: item.evidence !== undefined && item.evidence !== null,
+        hasBareDisposition: item.disposition !== undefined && item.disposition !== null,
+    };
+}
+/** Clear bare and namespaced acceptance fields so stamps never leave dual/conflicting keys. */
+function clearAcceptanceStampFields(item) {
+    delete item.evidence;
+    delete item.disposition;
+    delete item[ACCEPTANCE_EVIDENCE_KEY];
+    delete item[ACCEPTANCE_DISPOSITION_KEY];
+}
+/**
+ * Stamp typed evidence under the canonical namespaced key only.
+ * Clears bare evidence/disposition and any prior namespaced disposition so the item
+ * cannot carry both acceptance fields after a replace (#3305 Greptile P2).
+ */
+export function stampNamespacedEvidence(item, record) {
+    clearAcceptanceStampFields(item);
+    item[ACCEPTANCE_EVIDENCE_KEY] = {
+        kind: record.kind,
+        pointer: record.pointer,
+        recorded_at: record.recorded_at,
+        recorded_by: record.recorded_by,
+    };
+}
+/**
+ * Stamp human-origin disposition under the canonical namespaced key only.
+ * Clears bare evidence/disposition and any prior namespaced evidence so the item
+ * cannot carry both acceptance fields after a replace (#3305 Greptile P2).
+ */
+export function stampNamespacedDisposition(item, record) {
+    clearAcceptanceStampFields(item);
+    const body = {
+        disposition: record.disposition,
+        reason: record.reason,
+        provenance: { ...record.provenance },
+        recorded_at: record.recorded_at,
+    };
+    if (record.resume_when !== undefined) {
+        body.resume_when = record.resume_when;
+    }
+    item[ACCEPTANCE_DISPOSITION_KEY] = body;
+}
 function evaluateOneItem(item, path) {
     const title = itemLabel(item, path);
     const status = String(item.status ?? "");
     if (!NON_TERMINAL_ITEM_STATUSES.has(status)) {
+        // Already-terminal: complete does not re-validate typed evidence (#3240 / #3305).
+        // Suitability/provenance apply only when advancing non-terminal items. Pre-marking
+        // items completed with narrative-only fields still skips the typed gate — that is
+        // intentional for fail/cancel and historical terminals, not a silent dual success path.
         return {
             path,
             title,
             outcome: "already_terminal",
-            detail: `status=${status || "(empty)"} (not advanced)`,
+            detail: `status=${status || "(empty)"} (not advanced; typed evidence not re-checked)`,
         };
     }
-    const hasEvidence = item.evidence !== undefined && item.evidence !== null;
-    const hasDisposition = item.disposition !== undefined && item.disposition !== null;
+    const fields = readNamespacedAcceptanceFields(item);
+    const { hasEvidence, hasDisposition, hasBareEvidence, hasBareDisposition } = fields;
     if (hasEvidence && hasDisposition) {
         return {
             path,
             title,
             outcome: "invalid",
-            detail: "exactly one of evidence or disposition required; both present",
+            detail: `exactly one of ${ACCEPTANCE_EVIDENCE_KEY} or ${ACCEPTANCE_DISPOSITION_KEY} required; both present`,
         };
     }
     if (!hasEvidence && !hasDisposition) {
+        const bareHint = hasBareEvidence || hasBareDisposition
+            ? ` bare evidence/disposition ignored — use ${ACCEPTANCE_EVIDENCE_KEY} or ${ACCEPTANCE_DISPOSITION_KEY} (#3305);`
+            : "";
         return {
             path,
             title,
             outcome: "missing",
-            detail: "no evidence or disposition; scope:complete refuses to auto-complete (#3240)",
+            detail: `no ${ACCEPTANCE_EVIDENCE_KEY} or ${ACCEPTANCE_DISPOSITION_KEY};` +
+                `${bareHint} scope:complete refuses to auto-complete (#3240)`,
         };
     }
     if (hasDisposition) {
-        const parsed = parseDisposition(item.disposition);
+        const parsed = parseDisposition(fields.disposition);
         if (!parsed.ok) {
             return { path, title, outcome: "invalid", detail: parsed.message };
         }
@@ -257,7 +330,7 @@ function evaluateOneItem(item, path) {
             disposition: parsed.record,
         };
     }
-    const parsed = parseEvidence(item.evidence);
+    const parsed = parseEvidence(fields.evidence);
     if (!parsed.ok) {
         return { path, title, outcome: "invalid", detail: parsed.message };
     }
@@ -315,12 +388,13 @@ export function evaluateAcceptanceEvidenceGate(plan) {
     const lines = blockers.map((r) => `  - ${r.path} "${r.title}": ${r.detail}`);
     return {
         ok: false,
-        message: `Acceptance evidence required for scope:complete (#3240). ` +
+        message: `Acceptance evidence required for scope:complete (#3240 / #3305). ` +
             `${blockers.length} criterion/criteria missing suitable evidence or disposition:\n` +
             `${lines.join("\n")}\n` +
-            `Each non-terminal plan item needs evidence ` +
+            `Each non-terminal plan item needs ${ACCEPTANCE_EVIDENCE_KEY} ` +
             `{kind: test|review|merge|deploy|smoke|uat|observed_behavior, pointer, recorded_at, recorded_by} ` +
-            `or disposition {disposition: waived|deferred|not_applicable, reason, provenance (human-origin), recorded_at}. ` +
+            `or ${ACCEPTANCE_DISPOSITION_KEY} {disposition: waived|deferred|not_applicable, reason, provenance (human-origin), recorded_at}. ` +
+            `Bare evidence/disposition keys are not valid (#1620 / #3305). ` +
             `merge/review alone cannot satisfy smoke|uat|deploy|observed_behavior criteria.`,
         reports,
     };

package/dist/scope/decompose.d.ts

@@ -34,6 +34,11 @@ export interface ApplyDecompositionOptions {
     draftPath: string;
     checkOnly: boolean;
     date: string;
+    /**
+     * Optional GitHub-style repo (owner/name). When omitted, resolved via
+     * DEFT_TRIAGE_REPO / git remote origin so repo-bound structural grants match (#3291).
+     */
+    repo?: string | null;
 }
 export declare function applyDecomposition(opts: ApplyDecompositionOptions): string[];
 /** CLI entry for scope-decompose (mirrors scope_decompose.py main()). */

package/dist/scope/decompose.js

@@ -14,6 +14,7 @@ import { claimSingleUseGrantForApply } from "../authz/store.js";
 import { containedWrite } from "../fs/contained-write.js";
 import { ProjectionContainmentError } from "../fs/projection-containment.js";
 import { hasArtifactSuffix, LEGACY_ARTIFACT_DIR, MIGRATED_ARTIFACT_DIR, resolveLifecycleRoot, } from "../layout/resolve.js";
+import { resolveRepo } from "../triage/queue/repo.js";
 import { referenceWithDefaultTrust, slugify } from "../vbrief-build/build.js";
 import { EMITTED_VBRIEF_VERSION } from "../vbrief-build/constants.js";
 import { formatCoverageReportLine, validateCoverageMap } from "./coverage-map.js";
@@ -828,6 +829,9 @@ function buildChildVbrief(opts) {
 }
 export function applyDecomposition(opts) {
     const { projectRoot, parentPath, draftPath, checkOnly, date } = opts;
+    // Repo identity for structural apply grants that pin scope.repo (#3291).
+    const explicitRepo = (opts.repo ?? "").trim();
+    const repo = explicitRepo.length > 0 ? explicitRepo : resolveRepo(null, projectRoot);
     const vbriefDirPath = vbriefDir(projectRoot);
     const parent = loadJson(parentPath);
     // Single draft read: digest must bind the exact bytes used to build child docs (#3239 P1).
@@ -929,13 +933,15 @@ export function applyDecomposition(opts) {
     }
     if (checkOnly)
         return actions;
-    // #3239: structural apply requires human-origin grant bound to exact draft digest
-    // from the single load above. --check is ungated (returned earlier).
+    // #3239 / #3291: structural apply requires human-origin grant bound to exact draft digest
+    // from the single load above. Thread repo into both evaluator calls so repo-bound grants
+    // match. --check is ungated (returned earlier).
     const authz = evaluateDecomposeStructuralApply({
         projectRoot,
         parentPath,
         draftPath,
         draftDigest,
+        repo,
     });
     if (!authz.allowed) {
         throw new DecompositionError(authz.reason);
@@ -1015,12 +1021,15 @@ export function applyDecomposition(opts) {
     if (authz.humanApprovalRef !== null) {
         const claim = claimSingleUseGrantForApply(projectRoot, authz.humanApprovalRef, {
             revalidate: (grant) => {
+                // Same repo binding as the initial check (#3291) — under-lock revalidation must not
+                // silently drop project identity or a repo-bound grant would fail closed incorrectly.
                 const again = evaluateDecomposeStructuralApply({
                     projectRoot,
                     parentPath,
                     draftPath,
                     draftDigest,
                     grants: [grant],
+                    repo,
                 });
                 return again.allowed ? { ok: true } : { ok: false, reason: again.reason };
             },

package/dist/scope/index.d.ts

@@ -1,3 +1,4 @@
+export * from "./acceptance-activate-gate.js";
 export * from "./acceptance-evidence.js";
 export * from "./audit-log.js";
 export * from "./batch-promote.js";

package/dist/scope/index.js

@@ -1,3 +1,4 @@
+export * from "./acceptance-activate-gate.js";
 export * from "./acceptance-evidence.js";
 export * from "./audit-log.js";
 export * from "./batch-promote.js";

package/dist/scope/transition.js

@@ -5,6 +5,7 @@ import { assertProjectionContained, ProjectionContainmentError, } from "../fs/pr
 import { hasArtifactSuffix } from "../layout/resolve.js";
 import { evaluateCompletedPlanConsistency } from "../lifecycle/completed-consistency.js";
 import { evaluateLiteralAcceptanceFromPlan } from "../literal-acceptance/index.js";
+import { evaluateAcceptanceActivateGate } from "./acceptance-activate-gate.js";
 import { evaluateAcceptanceEvidenceGate, formatAcceptanceCompletionListing, } from "./acceptance-evidence.js";
 import { append, canonicalLogPath, newDecisionId } from "./audit-log.js";
 import { atomicWriteBrief, formatBriefJson, readBriefForMutation } from "./brief-io.js";
@@ -148,6 +149,10 @@ export function runTransition(action, filePath, now = new Date(), options = {})
         if (!effortGate.ok) {
             return { ok: false, message: effortGate.message };
         }
+        const acceptanceGate = evaluateAcceptanceActivateGate(planObj);
+        if (!acceptanceGate.ok) {
+            return { ok: false, message: acceptanceGate.message };
+        }
     }
     // #3041: fail closed before mutating a code-bearing complete without delivery evidence.
     if (act === "complete") {

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

@@ -0,0 +1,221 @@
+/**
+ * AC-pass banking checkpoint (#3285).
+ *
+ * When stated acceptance criteria first pass, FINALIZE: record a durable bank
+ * checkpoint, optionally append a bank-event to the run summary, and refuse
+ * self-imposed deepening unless remaining budget meets the surplus threshold
+ * (default 20% of max turns/cost). Post-bank out-of-scope findings are
+ * reported, not chased, when surplus is insufficient.
+ *
+ * Sharpens #3266 bank-the-pass. Composes product-first done-gate (#3284) and
+ * optional DEFT_RUN_SUMMARY_PATH telemetry (#3282 hook, fail-open).
+ */
+import { type AcPassBankingConfig } from "../policy/ac-pass-banking.js";
+import type { HardEffortBudget, VerificationDepthPolicy } from "./effort-budget.js";
+/** Durable bank ledger directory (gitignored under `.deft/`). */
+export declare const AC_PASS_BANK_DIR = ".deft/ac-pass-banks";
+export declare const AC_PASS_BANK_SCHEMA_VERSION: 1;
+/** Env path for optional JSONL run summary (#3282). Unset = silent. */
+export declare const ENV_RUN_SUMMARY_PATH = "DEFT_RUN_SUMMARY_PATH";
+export type PostBankFindingAction = "report" | "chase" | "fix-regression";
+export type AcPassNextAction = "still_open" | "finalize_and_ship" | "finalize_and_deepen";
+export interface SurplusEvaluation {
+    readonly hasSurplus: boolean;
+    /** Remaining / max when both known; null when unknown. */
+    readonly remainingFraction: number | null;
+    readonly surplusThreshold: number;
+    readonly axis: "turns" | "cost" | "both" | "unknown";
+    readonly reason: string;
+}
+export interface PostBankFinding {
+    readonly summary: string;
+    readonly action: PostBankFindingAction;
+    readonly recordedAt: string;
+    readonly regressesStatedAc: boolean;
+}
+export interface AcPassBankRecord {
+    readonly schemaVersion: typeof AC_PASS_BANK_SCHEMA_VERSION;
+    readonly scopeId: string;
+    readonly bankedAt: string;
+    readonly headSha: string | null;
+    readonly remainingTurns: number | null;
+    readonly remainingBudget: number | null;
+    readonly maxTurns: number | null;
+    readonly maxBudget: number | null;
+    readonly surplusThreshold: number;
+    readonly hadSurplus: boolean;
+    readonly nextAction: Exclude<AcPassNextAction, "still_open">;
+    readonly postBankFindings: readonly PostBankFinding[];
+}
+export interface EvaluateSurplusInput {
+    readonly budget: HardEffortBudget;
+    /** Fraction 0–1; default from policy / {@link DEFAULT_SURPLUS_THRESHOLD}. */
+    readonly surplusThreshold?: number;
+}
+export interface EvaluateAcPassBankingInput {
+    readonly budget: HardEffortBudget;
+    /** Whether stated AC (verify:ac / official checker) is met. */
+    readonly statedAcceptanceMet: boolean;
+    readonly config?: Partial<AcPassBankingConfig>;
+    /** Absolute turn reserve floor (still applied; #3266). Default 3. */
+    readonly deepenReserveTurns?: number;
+    readonly deepenReserveBudget?: number | null;
+}
+export interface AcPassBankingDecision {
+    readonly nextAction: AcPassNextAction;
+    readonly surplus: SurplusEvaluation;
+    readonly depthPolicy: VerificationDepthPolicy;
+    readonly deepeningAllowed: boolean;
+    readonly notes: readonly string[];
+}
+export interface BankAcPassInput {
+    readonly projectRoot: string;
+    readonly scopeId: string;
+    readonly budget: HardEffortBudget;
+    readonly surplus: SurplusEvaluation;
+    readonly nextAction: Exclude<AcPassNextAction, "still_open">;
+    readonly headSha?: string | null;
+    readonly now?: string;
+    readonly environ?: Readonly<Record<string, string | undefined>>;
+}
+export interface DecidePostBankFindingInput {
+    readonly findingSummary: string;
+    readonly regressesStatedAc: boolean;
+    readonly hasSurplus: boolean;
+    readonly now?: string;
+}
+/**
+ * Evaluate whether remaining budget meets the surplus threshold (#3285).
+ *
+ * When max is known: remaining/max >= threshold on every known axis.
+ * When only remaining is known (no max): surplus is false (fail-safe) —
+ * absolute #3266 reserve still applies separately via recommendVerificationDepth.
+ */
+export declare function evaluateSurplus(input: EvaluateSurplusInput): SurplusEvaluation;
+/**
+ * Full AC-pass banking decision: still open / finalize+ship / finalize+deepen.
+ */
+export declare function evaluateAcPassBanking(input: EvaluateAcPassBankingInput): AcPassBankingDecision;
+/**
+ * Post-bank finding disposition: report (default) vs chase (only with surplus)
+ * vs fix-regression (always when stated AC regressed).
+ */
+export declare function decidePostBankFinding(input: DecidePostBankFindingInput): PostBankFinding;
+export declare function acPassBanksDir(projectRoot: string): string;
+/**
+ * Sanitize scopeId for a ledger filename without unbounded quantifiers (CodeQL).
+ * Walks characters once — O(n), no ReDoS risk on pathological "-" runs.
+ */
+export declare function sanitizeScopeIdForFilename(scopeId: string): string;
+/** Stable filename for a scope bank record. */
+export declare function acPassBankFilename(scopeId: string): string;
+export declare function acPassBankPath(projectRoot: string, scopeId: string): string;
+/**
+ * Persist a bank checkpoint that survives session death (#3285).
+ * Also appends a bank-event to DEFT_RUN_SUMMARY_PATH when set (fail-open).
+ */
+/** Append-only findings journal (never truncated by re-bank). */
+export declare function acPassFindingsJournalPath(projectRoot: string, scopeId: string): string;
+export declare function bankAcPass(input: BankAcPassInput): AcPassBankRecord;
+/** Recover complete JSON objects from a (possibly truncated) array body. */
+export declare function recoverCompleteJsonObjects(arrayBody: string): readonly unknown[];
+export declare function recoverFindingsFromLedgerText(raw: string): readonly PostBankFinding[];
+/**
+ * Load bank record. When both primary and .tmp exist, prefer a fully-valid
+ * JSON primary over a partial tmp, and union recovered findings so partial
+ * recovery cannot erase durable history (#3285 Greptile residual).
+ */
+export declare function readAcPassBank(projectRoot: string, scopeId: string): AcPassBankRecord | null;
+/**
+ * Append a post-bank finding to an existing bank record (report/chase/fix).
+ */
+export declare function recordPostBankFinding(projectRoot: string, scopeId: string, finding: PostBankFinding): AcPassBankRecord | null;
+export interface BankEventPayload {
+    readonly type: "ac_pass_bank" | "ac_pass_post_bank_finding" | "ac_pass_deepening_skipped";
+    readonly schemaVersion: number;
+    readonly scopeId?: string;
+    readonly bankedAt?: string;
+    readonly nextAction?: string;
+    readonly hadSurplus?: boolean;
+    readonly surplusThreshold?: number;
+    readonly remainingFraction?: number | null;
+    readonly remainingTurns?: number | null;
+    readonly remainingBudget?: number | null;
+    readonly maxTurns?: number | null;
+    readonly maxBudget?: number | null;
+    readonly headSha?: string | null;
+    readonly path?: string;
+    readonly finding?: PostBankFinding;
+    readonly note?: string;
+    readonly [key: string]: unknown;
+}
+/**
+ * Format one JSONL bank-event line for run-summary telemetry (#3285 / #3282).
+ */
+export declare function formatBankEventLine(event: BankEventPayload): string;
+/**
+ * Append bank event to DEFT_RUN_SUMMARY_PATH when set.
+ * Unset = silent. `-` = stdout. Failures warn once to stderr (fail-open).
+ */
+export declare function appendBankEventToRunSummary(input: {
+    readonly environ?: Readonly<Record<string, string | undefined>>;
+    readonly event: BankEventPayload;
+    readonly writeLine?: (path: string, line: string) => void;
+    readonly warn?: (message: string) => void;
+}): {
+    written: boolean;
+    path: string | null;
+};
+/**
+ * Simulated run used by the surplus-insufficient acceptance test (#3285):
+ * AC passes → bank → extra checks would exceed budget → ship + report finding.
+ */
+export declare function simulateSurplusInsufficientRun(input: {
+    readonly projectRoot: string;
+    readonly scopeId: string;
+    readonly budget: HardEffortBudget;
+    readonly findingSummary: string;
+    readonly surplusThreshold?: number;
+    readonly headSha?: string | null;
+    readonly now?: string;
+    readonly environ?: Readonly<Record<string, string | undefined>>;
+}): {
+    readonly decision: AcPassBankingDecision;
+    readonly bank: AcPassBankRecord;
+    readonly finding: PostBankFinding;
+    readonly shipped: boolean;
+    readonly findingAction: PostBankFindingAction;
+};
+/**
+ * Resolve policy config for a project root (typed → env → default).
+ */
+export declare function resolveBankingConfigForRoot(projectRoot?: string | null, environ?: Readonly<Record<string, string | undefined>>): AcPassBankingConfig;
+export interface MaybeBankOnAcPassInput {
+    readonly projectRoot: string;
+    /** plan.id or path-derived scope key. */
+    readonly scopeId: string;
+    readonly budget?: HardEffortBudget;
+    readonly config?: Partial<AcPassBankingConfig>;
+    readonly headSha?: string | null;
+    readonly now?: string;
+    readonly environ?: Readonly<Record<string, string | undefined>>;
+    /**
+     * Only bank when real acceptance commands executed and passed.
+     * Soft/advisory passes with zero runs do not bank.
+     */
+    readonly executableRuns: number;
+    readonly quiet?: boolean;
+}
+export interface MaybeBankOnAcPassResult {
+    readonly banked: boolean;
+    readonly decision: AcPassBankingDecision | null;
+    readonly bank: AcPassBankRecord | null;
+    readonly notes: readonly string[];
+}
+/**
+ * Production bridge (#3285 Greptile P1): after verify:ac reports executable
+ * success, FINALIZE the bank checkpoint + surplus decision.
+ * Throws on I/O failure so verify:ac can fail closed (checkpoint mandatory).
+ */
+export declare function maybeBankOnAcPass(input: MaybeBankOnAcPassInput): MaybeBankOnAcPassResult;
+//# sourceMappingURL=ac-pass-banking.d.ts.map