@deftai/directive-core 0.99.0 → 0.101.0

package/dist/scope/transition.js

@@ -3,6 +3,9 @@ import { dirname, join, resolve } from "node:path";
 import { InstrumentedVbriefCrud, persistCrudMetrics } from "../eval/crud-telemetry.js";
 import { assertProjectionContained, ProjectionContainmentError, } from "../fs/projection-containment.js";
 import { hasArtifactSuffix } from "../layout/resolve.js";
+import { evaluateCompletedPlanConsistency } from "../lifecycle/completed-consistency.js";
+import { evaluateLiteralAcceptanceFromPlan } from "../literal-acceptance/index.js";
+import { evaluateAcceptanceEvidenceGate, formatAcceptanceCompletionListing, } from "./acceptance-evidence.js";
 import { append, canonicalLogPath, newDecisionId } from "./audit-log.js";
 import { atomicWriteBrief, formatBriefJson, readBriefForMutation } from "./brief-io.js";
 import { stampCompletionMetadata } from "./capacity-stamp.js";
@@ -165,16 +168,65 @@ export function runTransition(action, filePath, now = new Date(), options = {})
             stampDeliveryProvenance(planObj, gate.provenance);
         }
     }
+    // #3240: per-criterion typed evidence or human-origin disposition before auto-advance.
+    let acceptanceReports;
+    let acceptanceListing = "";
+    if (act === "complete" && options.skipAcceptanceEvidenceGate !== true) {
+        const acceptanceGate = evaluateAcceptanceEvidenceGate(planObj);
+        acceptanceReports = acceptanceGate.reports;
+        if (!acceptanceGate.ok) {
+            return {
+                ok: false,
+                message: acceptanceGate.message,
+                acceptanceReports: acceptanceGate.reports,
+            };
+        }
+        acceptanceListing = formatAcceptanceCompletionListing(acceptanceGate.reports);
+        // #3267: run agent-authored literal AC before complete; re-scan narratives so
+        // narrative-only stated commands fail closed (promote required) rather than skip.
+        const literalGate = evaluateLiteralAcceptanceFromPlan(planObj, {
+            projectRoot,
+            captureFromNarratives: true,
+        });
+        if (!literalGate.ok) {
+            return {
+                ok: false,
+                message: `Literal acceptance-command gate failed before scope:complete (#3267).\n` +
+                    literalGate.message,
+                acceptanceReports: acceptanceGate.reports,
+            };
+        }
+        if (literalGate.commands.length > 0 || literalGate.message.length > 0) {
+            acceptanceListing =
+                acceptanceListing.length > 0
+                    ? `${acceptanceListing}\n${literalGate.message}`
+                    : literalGate.message;
+        }
+    }
     planObj.status = targetStatus;
     planObj.updated = nowIso;
     // Keep the envelope clock aligned with plan.updated on every mutating transition (#2862).
     stampEnvelopeUpdated(data, nowIso);
     // Reconcile the completing brief's own plan.items (mirrors #1527 / #2566 registry sync) (#2862).
+    // On complete, items only reach here when #3240 evidence/disposition gate passed.
     if (OWN_ITEMS_RECONCILE_ACTIONS.has(act)) {
         advanceNonTerminalOwnItems(planObj.items, targetStatus);
     }
     if (act === "complete") {
         stampCompletionMetadata(planObj, projectRoot, nowIso);
+        // #3242 / epic #3237 Q4: after reconcile, completed lifecycle must match
+        // plan.status=completed and terminal plan.items (compose with #3240).
+        const consistency = evaluateCompletedPlanConsistency(planObj, {
+            relPath: basename,
+            requireStatus: "completed",
+        });
+        if (!consistency.ok) {
+            return {
+                ok: false,
+                message: consistency.message,
+                acceptanceReports,
+            };
+        }
     }
     const formatted = formatBriefJson(data);
     const crud = new InstrumentedVbriefCrud({ now: () => now });
@@ -219,12 +271,16 @@ export function runTransition(action, filePath, now = new Date(), options = {})
                 ok: false,
                 message: `${actionLabel} ${basename}: brief moved to ${targetFolder}/ but ` +
                     `PROJECT-DEFINITION sync failed: ${pdSyncError}`,
+                acceptanceReports,
             };
         }
         syncSpecificationAfterScopeMove(data, resolvedPath, destPath, vbriefRoot, targetStatus);
+        const moveMsg = `${actionLabel} ${basename}: ${currentFolder}/ -> ${targetFolder}/ (status: ${targetStatus})` +
+            (acceptanceListing.length > 0 ? `\n${acceptanceListing}` : "");
         return {
             ok: true,
-            message: `${actionLabel} ${basename}: ${currentFolder}/ -> ${targetFolder}/ (status: ${targetStatus})`,
+            message: moveMsg,
+            acceptanceReports,
         };
     }
     const writeResult = atomicWriteBrief(resolvedPath, data, vbriefRoot, { projectRoot });
@@ -239,9 +295,12 @@ export function runTransition(action, filePath, now = new Date(), options = {})
         /* best-effort telemetry persistence */
     }
     const actionLabel = STAY_LABELS[act] ?? act.charAt(0).toUpperCase() + act.slice(1);
+    const stayMsg = `${actionLabel} ${basename}: stays in ${currentFolder}/ (status: ${targetStatus})` +
+        (acceptanceListing.length > 0 ? `\n${acceptanceListing}` : "");
     return {
         ok: true,
-        message: `${actionLabel} ${basename}: stays in ${currentFolder}/ (status: ${targetStatus})`,
+        message: stayMsg,
+        acceptanceReports,
     };
 }
 export function recordWipCapOverride(filePath, projectRoot, check, now = new Date()) {

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