@deftai/directive-core 0.104.0 → 0.106.0

package/dist/product-first-done-gate/acceptance-resolver.js

@@ -0,0 +1,144 @@
+/**
+ * One resolver for "does this artifact carry executable acceptance that passed?" (#3497).
+ *
+ * Before this module `verify:ac` and `scope:complete` read the same artifact through
+ * two different lenses and reported two different things:
+ *
+ * - verify:ac composed a message from the sub-gates (`verify:ac passed`, `Literal
+ *   acceptance-command gate passed`) and then flipped `ok` in a later stage
+ *   (clause walk / no-op ledger / oracle integrity) without relabelling the message.
+ * - scope:complete took that `ok=false` and asserted "empty or failing acceptance"
+ *   even when acceptance was neither empty nor failing.
+ *
+ * Both now read the verdict here. One predicate name, one observed value, printed
+ * identically by both consumers.
+ *
+ * This module is intentionally structural (no import of `VerifyAcResult`) so the
+ * done-gate evaluator and the scope gate can both depend on it without a cycle.
+ */
+import { NOOP_ACCEPTANCE_REMEDIATION } from "../literal-acceptance/index.js";
+const REMEDY = {
+    "executable-pass": "",
+    "empty-pass": "",
+    "config-error": "fix plan.acceptance so it matches the #3284 schema, then re-run task verify:ac",
+    "noop-refused": NOOP_ACCEPTANCE_REMEDIATION,
+    "safety-rejected": "promote a safe alternative into plan.metadata.swarm.verify_commands or remove the stated command from the task statement (#3267)",
+    "commands-failed": "fix the product until the stated acceptance command exits as expected — the command, not the gate, is the oracle (#3284)",
+    "empty-acceptance": "stamp executable commands on plan.acceptance.commands (or plan.metadata.swarm.verify_commands) with source_rung derived|project_floor (#3334)",
+    "clause-walk-failed": "ship the artifact each failed clause names, or bind the clause to the path it actually landed at (#3323)",
+    "integrity-discrepancy": "resolve by a product change under the same method, or independently re-derive both sides and record independent_rederivation=true (#3322)",
+    unclassified: "read the verify:ac message below; the deciding check did not name itself",
+};
+function countClauses(reading, outcome) {
+    return (reading.clauseOutcomes ?? []).filter((row) => row.outcome === outcome).length;
+}
+function firstLine(message) {
+    const line = message.split("\n").find((row) => row.trim().length > 0);
+    return line === undefined ? "(no detail)" : line.trim();
+}
+function verdict(ok, predicate, observed) {
+    return { ok, predicate, observed, remedy: REMEDY[predicate] };
+}
+/** Executable command count this reading resolved (stamped or ledger). */
+export function resolvedAcceptanceCommandCount(reading) {
+    return Math.max(reading.commands.length, reading.acceptance.commands.length);
+}
+/**
+ * Name the predicate that decided this verify:ac result, and the value it read.
+ *
+ * Order matters: the earliest fail-closed stage wins so the operator is pointed at
+ * the check that actually refused rather than a downstream symptom.
+ */
+export function resolveAcceptanceVerdict(reading) {
+    const commandCount = resolvedAcceptanceCommandCount(reading);
+    const greenRuns = reading.runs.filter((run) => run.ok).length;
+    const failedRuns = reading.runs.filter((run) => !run.ok);
+    if (reading.ok) {
+        if (reading.runs.length > 0) {
+            return verdict(true, "executable-pass", `${greenRuns}/${reading.runs.length} command(s) exited as expected [rung=${reading.sourceRung}]`);
+        }
+        return verdict(true, "empty-pass", `no executable command resolved; project floor allows it [rung=${reading.sourceRung}]`);
+    }
+    if (reading.resolution === "config" || reading.code === 2) {
+        return verdict(false, "config-error", firstLine(reading.message));
+    }
+    if (reading.resolution === "rejected-noop") {
+        const noop = (reading.rejected ?? []).map((row) => row.command);
+        return verdict(false, "noop-refused", noop.length > 0
+            ? `blocking ledger command(s) that cannot fail: ${noop.join(", ")}`
+            : firstLine(reading.message));
+    }
+    const rejected = reading.rejected ?? [];
+    if (rejected.length > 0) {
+        return verdict(false, "safety-rejected", `${rejected.length} blocking safety-rejected command(s): ${rejected
+            .map((row) => row.command)
+            .join(", ")}`);
+    }
+    if (failedRuns.length > 0) {
+        return verdict(false, "commands-failed", `${failedRuns.length}/${reading.runs.length} command(s) did not exit as expected: ${failedRuns
+            .map((row) => row.command)
+            .join(", ")}`);
+    }
+    if (reading.resolution === "soft_empty") {
+        return verdict(false, "empty-acceptance", `plan.acceptance.commands=${commandCount}, runs=0 [rung=${reading.sourceRung}]`);
+    }
+    if ((reading.clauseOutcomes?.length ?? 0) > 0) {
+        const failed = countClauses(reading, "failed");
+        const unverifiable = countClauses(reading, "unverifiable");
+        const verified = countClauses(reading, "verified");
+        return verdict(false, "clause-walk-failed", `clause walk read ${verified} verified, ${unverifiable} unverifiable, ${failed} failed ` +
+            `against ${commandCount} stamped command(s) and ${reading.runs.length} run(s)`);
+    }
+    if (/#3322/.test(reading.message)) {
+        return verdict(false, "integrity-discrepancy", firstLine(reading.message));
+    }
+    if (commandCount === 0) {
+        return verdict(false, "empty-acceptance", `plan.acceptance.commands=0, runs=0 [rung=${reading.sourceRung}]`);
+    }
+    return verdict(false, "unclassified", firstLine(reading.message));
+}
+/** One line naming the predicate and the value it read (#3497). */
+export function formatAcceptanceVerdict(verdictResult) {
+    const lead = `acceptance verdict (#3497): ${verdictResult.predicate} — ${verdictResult.observed}`;
+    if (verdictResult.ok || verdictResult.remedy.length === 0) {
+        return lead;
+    }
+    return `${lead}\n  remedy: ${verdictResult.remedy}`;
+}
+/**
+ * Clause-walk composition (#3323 / #3497).
+ *
+ * A clause the shipped artifact contradicts (`failed`) always blocks. A clause the
+ * static walk cannot decide (`unverifiable`) is evidence of nothing — it blocks only
+ * when nothing else verified the product. A green executable acceptance run IS that
+ * something: the product-first oracle already ran. Before #3497 an all-unverifiable
+ * clause set refused an artifact whose stated command had just exited 0.
+ */
+export function clauseWalkBlocks(input) {
+    if (input.failed > 0) {
+        return true;
+    }
+    if (input.walked === 0 || input.verified > 0) {
+        return false;
+    }
+    return !input.hasGreenExecutableRun;
+}
+/**
+ * The single option set each reader uses. Previously verify:ac and scope:complete
+ * hand-assembled divergent option objects at their call sites (#3497).
+ */
+export function resolveAcceptanceGateProfile(profile) {
+    switch (profile) {
+        case "check":
+            // Re-scanning issue prose during `task check` re-captures backtick lines
+            // as rejected and deadlocks the graph (#3323).
+            return { captureFromNarratives: false, checkIntegrated: true, reuseMode: "auto" };
+        case "complete":
+            // Completion re-scans narratives so a narrative-only stated command fails
+            // closed rather than being skipped, and never serves from a same-session cache.
+            return { captureFromNarratives: true, checkIntegrated: false, reuseMode: "bank" };
+        default:
+            return { captureFromNarratives: undefined, checkIntegrated: false, reuseMode: "auto" };
+    }
+}
+//# sourceMappingURL=acceptance-resolver.js.map

package/dist/product-first-done-gate/acceptance.d.ts

@@ -4,7 +4,7 @@
  * Captures stated acceptance.commands at intake; empty requires none_stated:true.
  * Interoperates with #3267 plan.metadata.literal_acceptance_commands.
  */
-import { type AcceptanceCommand, type PlanAcceptance } from "./types.js";
+import { type AcceptanceCommand, type AcSourceRung, type PlanAcceptance } from "./types.js";
 /** Validation errors for a plan.acceptance object (empty list = valid). */
 export declare function validatePlanAcceptance(value: unknown): string[];
 /**
@@ -15,11 +15,14 @@ export declare function readPlanAcceptance(plan: Record<string, unknown> | null
 /** Attach a validated PlanAcceptance onto plan.acceptance + mirror to #3267 metadata. */
 export declare function attachPlanAcceptance(plan: Record<string, unknown>, acceptance: PlanAcceptance): Record<string, unknown>;
 /**
- * Build plan.acceptance from intake capture (#3284).
- * Stated commands → none_stated:false, source_rung:stated.
+ * Build plan.acceptance from intake capture (#3284 / #3396).
+ * Stated only when capture recorded a verbatim statement span.
  * No stated commands → none_stated:true, source_rung:project_floor (until agent derives).
  */
-export declare function buildAcceptanceFromIntakeCapture(capturedCommands: readonly AcceptanceCommand[]): PlanAcceptance;
+export declare function buildAcceptanceFromIntakeCapture(capturedCommands: readonly AcceptanceCommand[], options?: {
+    readonly hasVerbatimStatementSpan?: boolean;
+    readonly previousRung?: AcSourceRung;
+}): PlanAcceptance;
 /** Stamp plan.acceptance from existing literal capture after issue ingest. */
 export declare function stampAcceptanceFromLiteralCapture(plan: Record<string, unknown>): Record<string, unknown>;
 //# sourceMappingURL=acceptance.d.ts.map

package/dist/product-first-done-gate/acceptance.js

@@ -4,7 +4,7 @@
  * Captures stated acceptance.commands at intake; empty requires none_stated:true.
  * Interoperates with #3267 plan.metadata.literal_acceptance_commands.
  */
-import { attachLiteralAcceptanceCommands, readStoredLiteralAcceptanceCommands, } from "../literal-acceptance/index.js";
+import { attachLiteralAcceptanceCommands, evaluateStampAcceptanceSafety, isNoopRefusalReason, isVerbatimStatementSpan, NOOP_ACCEPTANCE_REMEDIATION, readStoredLiteralAcceptanceCommands, } from "../literal-acceptance/index.js";
 import { readAcceptanceClauses, serializeAcceptanceClauses } from "../verify-ac/clauses.js";
 import { PLAN_ACCEPTANCE_KEY, } from "./types.js";
 function asRecord(value) {
@@ -100,6 +100,12 @@ export function validatePlanAcceptance(value) {
         errors.push("plan.acceptance: none_stated:true with source_rung:stated is contradictory " +
             "(use source_rung:derived when commands are agent-authored under none_stated)");
     }
+    for (const cmd of commands) {
+        const stamp = evaluateStampAcceptanceSafety({ commands: [{ command: cmd.command }] });
+        if (!stamp.ok && isNoopRefusalReason(stamp.reason)) {
+            errors.push(stamp.reason ?? NOOP_ACCEPTANCE_REMEDIATION);
+        }
+    }
     return errors;
 }
 /**
@@ -218,11 +224,11 @@ export function attachPlanAcceptance(plan, acceptance) {
     return next;
 }
 /**
- * Build plan.acceptance from intake capture (#3284).
- * Stated commands → none_stated:false, source_rung:stated.
+ * Build plan.acceptance from intake capture (#3284 / #3396).
+ * Stated only when capture recorded a verbatim statement span.
  * No stated commands → none_stated:true, source_rung:project_floor (until agent derives).
  */
-export function buildAcceptanceFromIntakeCapture(capturedCommands) {
+export function buildAcceptanceFromIntakeCapture(capturedCommands, options = {}) {
     if (capturedCommands.length === 0) {
         return {
             commands: [],
@@ -231,17 +237,82 @@ export function buildAcceptanceFromIntakeCapture(capturedCommands) {
             derived_reason: "no shell acceptance commands stated in task text; floor until agent derives AC (#3284 ladder)",
         };
     }
+    const stamp = evaluateStampAcceptanceSafety({
+        commands: capturedCommands.map((cmd) => ({ command: cmd.command })),
+        previousRung: options.previousRung,
+    });
+    if (!stamp.ok) {
+        throw new Error(stamp.reason ?? NOOP_ACCEPTANCE_REMEDIATION);
+    }
+    const sourceRung = options.hasVerbatimStatementSpan === true ? "stated" : "derived";
     return {
         commands: capturedCommands,
-        none_stated: false,
-        source_rung: "stated",
-        derived_reason: null,
+        none_stated: sourceRung !== "stated",
+        source_rung: sourceRung,
+        derived_reason: sourceRung === "stated"
+            ? null
+            : "no recorded verbatim statement span; derived not stated (#3396)",
     };
 }
+function rawStampCommandStrings(plan) {
+    const out = [];
+    const seen = new Set();
+    const push = (value) => {
+        if (typeof value === "string" && value.trim().length > 0) {
+            const command = value.trim();
+            if (seen.has(command))
+                return;
+            seen.add(command);
+            out.push(command);
+            return;
+        }
+        const rec = asRecord(value);
+        if (rec === null)
+            return;
+        const command = rec.command ?? rec.cmd ?? rec.shell;
+        if (isNonEmptyString(command)) {
+            const trimmed = command.trim();
+            if (seen.has(trimmed))
+                return;
+            seen.add(trimmed);
+            out.push(trimmed);
+        }
+    };
+    const acceptance = asRecord(plan[PLAN_ACCEPTANCE_KEY]);
+    if (acceptance !== null && Array.isArray(acceptance.commands)) {
+        for (const entry of acceptance.commands) {
+            push(entry);
+        }
+    }
+    const metadata = asRecord(plan.metadata);
+    if (metadata !== null) {
+        const explicit = metadata.literal_acceptance_commands ?? metadata.literalAcceptanceCommands;
+        if (Array.isArray(explicit)) {
+            for (const entry of explicit) {
+                push(entry);
+            }
+        }
+    }
+    return out;
+}
 /** Stamp plan.acceptance from existing literal capture after issue ingest. */
 export function stampAcceptanceFromLiteralCapture(plan) {
+    const previous = asRecord(plan[PLAN_ACCEPTANCE_KEY]);
+    const previousRung = isAcSourceRung(previous?.source_rung) ? previous.source_rung : undefined;
+    const attempted = rawStampCommandStrings(plan);
+    const refuse = evaluateStampAcceptanceSafety({
+        commands: attempted.map((command) => ({ command })),
+        previousRung,
+    });
+    if (!refuse.ok) {
+        throw new Error(refuse.reason ?? NOOP_ACCEPTANCE_REMEDIATION);
+    }
     const literal = readStoredLiteralAcceptanceCommands(plan);
-    const acceptance = buildAcceptanceFromIntakeCapture(literal.map(literalToAcceptance));
+    const hasVerbatimStatementSpan = literal.some((cmd) => cmd.source === "task_statement" && isVerbatimStatementSpan(cmd.sourceSpan ?? null));
+    const acceptance = buildAcceptanceFromIntakeCapture(literal.map(literalToAcceptance), {
+        hasVerbatimStatementSpan,
+        previousRung,
+    });
     // Avoid re-mirroring task_statement into verify_commands (ingest strips those).
     const serializable = {
         commands: acceptance.commands.map((c) => {

package/dist/product-first-done-gate/empty-resolution.d.ts

@@ -8,7 +8,9 @@ import type { PlanAcceptance } from "./types.js";
 export declare const EMPTY_AC_OUTCOME: "soft_empty";
 export declare const EMPTY_AC_CAUSE = "no acceptance stamped \u2014 floor is empty in this project";
 export declare const EMPTY_AC_REMEDY = "stamp plan.acceptance via clause derivation (scope:activate / scope:promote runs #3323, or task issue:ingest)";
-export type VerifyAcResolution = "verified-pass" | "empty-pass" | "soft_empty" | "fail" | "config" | "skipped";
+export declare const TRANSCRIPT_EMPTY_CAUSE = "transcript skip left zero captured commands";
+export declare const TRANSCRIPT_EMPTY_REMEDY = "stamp real acceptance commands; suite-floor empty-pass does not apply when a transcript fence dropped prompt lines (#3511)";
+export type VerifyAcResolution = "verified-pass" | "empty-pass" | "soft_empty" | "fail" | "config" | "skipped" | "rejected-noop";
 /** True when this project check composition includes a suite gate (#3188). */
 export declare function projectHasSuiteFloor(projectRoot: string): boolean;
 export declare function isSoftEmptyAcText(text: string): boolean;
@@ -23,4 +25,5 @@ export interface EmptyAcResolutionInput {
 /** Zero executable commands, no rejected/unpromoted ledger, not already classified. */
 export declare function isEmptyAcResolution(input: EmptyAcResolutionInput): boolean;
 export declare function formatSoftEmptyMessage(acceptance: PlanAcceptance, quiet?: boolean): string;
+export declare function formatTranscriptEmptyMessage(acceptance: PlanAcceptance, quiet?: boolean): string;
 //# sourceMappingURL=empty-resolution.d.ts.map

package/dist/product-first-done-gate/empty-resolution.js

@@ -8,6 +8,8 @@ import { isFrameworkRepoRoot } from "../check/context.js";
 export const EMPTY_AC_OUTCOME = "soft_empty";
 export const EMPTY_AC_CAUSE = "no acceptance stamped — floor is empty in this project";
 export const EMPTY_AC_REMEDY = "stamp plan.acceptance via clause derivation (scope:activate / scope:promote runs #3323, or task issue:ingest)";
+export const TRANSCRIPT_EMPTY_CAUSE = "transcript skip left zero captured commands";
+export const TRANSCRIPT_EMPTY_REMEDY = "stamp real acceptance commands; suite-floor empty-pass does not apply when a transcript fence dropped prompt lines (#3511)";
 /** True when this project check composition includes a suite gate (#3188). */
 export function projectHasSuiteFloor(projectRoot) {
     return isFrameworkRepoRoot(projectRoot);
@@ -17,7 +19,9 @@ export function isSoftEmptyAcText(text) {
 }
 /** Zero executable commands, no rejected/unpromoted ledger, not already classified. */
 export function isEmptyAcResolution(input) {
-    if (input.resolution === "config" || input.resolution === "skipped") {
+    if (input.resolution === "config" ||
+        input.resolution === "skipped" ||
+        input.resolution === "rejected-noop") {
         return false;
     }
     if (input.code === 2) {
@@ -35,4 +39,11 @@ export function formatSoftEmptyMessage(acceptance, quiet) {
     return (`verify:ac ${EMPTY_AC_OUTCOME} (#3334) [rung=${acceptance.source_rung}]: ` +
         `${EMPTY_AC_CAUSE}. ${EMPTY_AC_REMEDY}.`);
 }
+export function formatTranscriptEmptyMessage(acceptance, quiet) {
+    if (quiet) {
+        return "";
+    }
+    return (`verify:ac FAILED (#3511) [rung=${acceptance.source_rung}]: ` +
+        `${TRANSCRIPT_EMPTY_CAUSE}. ${TRANSCRIPT_EMPTY_REMEDY}.`);
+}
 //# sourceMappingURL=empty-resolution.js.map

package/dist/product-first-done-gate/evaluate.d.ts

@@ -9,6 +9,7 @@
  */
 import { type EvaluateLiteralAcceptanceOptions, type LiteralAcceptanceGateResult } from "../literal-acceptance/index.js";
 import { type AcceptanceRunSummaryOutcome } from "../run-summary/index.js";
+import { type AcServedFrom } from "../session/verify-ac-session-cache.js";
 import { type ClauseWalkResult } from "../verify-ac/clauses.js";
 import { type VerifyAcResolution } from "./empty-resolution.js";
 import type { AcSourceRung, PlanAcceptance } from "./types.js";
@@ -20,6 +21,12 @@ export interface VerifyAcResult extends LiteralAcceptanceGateResult {
     readonly resolvedCommandCount: number;
     readonly clauseOutcomes?: readonly ClauseWalkResult[];
     readonly clauseWalked?: boolean;
+    /** How the result was obtained (#3387). */
+    readonly servedFrom?: AcServedFrom;
+    /** Config-error cause when resolution is config (#3559). */
+    readonly cause?: string;
+    /** Reuse-gate miss cause when servedFrom is executed (#3558). */
+    readonly missReason?: string;
 }
 export interface EvaluateVerifyAcOptions extends EvaluateLiteralAcceptanceOptions {
     /**
@@ -74,6 +81,15 @@ export interface EvaluateVerifyAcOptions extends EvaluateLiteralAcceptanceOption
      * under one session must not share a single global `verify:ac` check id.
      */
     readonly oracleScopeKey?: string | null;
+    /**
+     * Reuse a matching #3285 bank / same-session cache (#3387).
+     * - auto (default): cache then bank
+     * - bank: complete walk — bank only
+     * - never: always execute
+     */
+    readonly reuseMode?: "auto" | "bank" | "never";
+    readonly sessionId?: string | null;
+    readonly productPaths?: readonly string[];
 }
 /**
  * Evaluate product AC from an in-memory plan.