@deftai/directive-core 0.99.0 → 0.101.0

package/dist/preflight-cache/evaluate.js

@@ -317,6 +317,9 @@ const REMEDIATION_NO_CANDIDATES = [
  * Evaluate cache freshness for the given project root.
  *
  * Faithful port of scripts/preflight_cache.py::evaluate().
+ * #3286 note: deposit-sha orientation no-ops live in session orientation
+ * composition (age-gated), not here — triage cache freshness is age/drift based
+ * and must not short-circuit solely on payload/templates/engine fingerprints.
  */
 export function evaluate(projectRoot, options = {}) {
     return evaluateWithContext(projectRoot, options, { afterEmptyPopulate: false });

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

@@ -0,0 +1,25 @@
+/**
+ * plan.acceptance schema helpers (#3284).
+ *
+ * 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";
+/** Validation errors for a plan.acceptance object (empty list = valid). */
+export declare function validatePlanAcceptance(value: unknown): string[];
+/**
+ * Read plan.acceptance when present; otherwise synthesize from #3267
+ * literal_acceptance_commands / empty+none_stated.
+ */
+export declare function readPlanAcceptance(plan: Record<string, unknown> | null | undefined): PlanAcceptance;
+/** 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.
+ * No stated commands → none_stated:true, source_rung:project_floor (until agent derives).
+ */
+export declare function buildAcceptanceFromIntakeCapture(capturedCommands: readonly AcceptanceCommand[]): 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

@@ -0,0 +1,247 @@
+/**
+ * plan.acceptance schema helpers (#3284).
+ *
+ * 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 { PLAN_ACCEPTANCE_KEY, } from "./types.js";
+function asRecord(value) {
+    if (typeof value === "object" && value !== null && !Array.isArray(value)) {
+        return value;
+    }
+    return null;
+}
+function isNonEmptyString(value) {
+    return typeof value === "string" && value.trim().length > 0;
+}
+function coerceCommands(raw) {
+    if (!Array.isArray(raw))
+        return [];
+    const out = [];
+    for (const entry of raw) {
+        if (typeof entry === "string") {
+            const command = entry.trim();
+            if (command.length > 0)
+                out.push({ command });
+            continue;
+        }
+        const rec = asRecord(entry);
+        if (rec === null)
+            continue;
+        const command = rec.command ?? rec.cmd ?? rec.shell;
+        if (!isNonEmptyString(command))
+            continue;
+        out.push({
+            command: command.trim(),
+            cwd: isNonEmptyString(rec.cwd) ? rec.cwd.trim() : null,
+            expectedStdout: isNonEmptyString(rec.expectedStdout)
+                ? rec.expectedStdout
+                : isNonEmptyString(rec.expected_stdout)
+                    ? rec.expected_stdout
+                    : null,
+            expectedExitCode: typeof rec.expectedExitCode === "number"
+                ? rec.expectedExitCode
+                : typeof rec.expected_exit_code === "number"
+                    ? rec.expected_exit_code
+                    : 0,
+        });
+    }
+    return out;
+}
+function isAcSourceRung(value) {
+    return value === "stated" || value === "derived" || value === "project_floor";
+}
+/** Validation errors for a plan.acceptance object (empty list = valid). */
+export function validatePlanAcceptance(value) {
+    if (value === null || value === undefined) {
+        return [];
+    }
+    const rec = asRecord(value);
+    if (rec === null) {
+        return ["plan.acceptance must be an object"];
+    }
+    const errors = [];
+    if ("commands" in rec && rec.commands !== undefined && !Array.isArray(rec.commands)) {
+        errors.push("plan.acceptance.commands must be an array");
+    }
+    if ("none_stated" in rec &&
+        rec.none_stated !== undefined &&
+        typeof rec.none_stated !== "boolean") {
+        errors.push("plan.acceptance.none_stated must be a boolean");
+    }
+    if ("source_rung" in rec && rec.source_rung !== undefined && !isAcSourceRung(rec.source_rung)) {
+        errors.push('plan.acceptance.source_rung must be "stated" | "derived" | "project_floor"');
+    }
+    const commands = coerceCommands(rec.commands);
+    const noneStated = rec.none_stated === true;
+    if (commands.length === 0 && !noneStated) {
+        errors.push("plan.acceptance.commands is empty but none_stated is not true — " +
+            "empty acceptance is only allowed with an explicit none_stated: true marker (#3284)");
+    }
+    if (commands.length > 0 && noneStated && rec.source_rung === "stated") {
+        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)");
+    }
+    return errors;
+}
+/**
+ * Read plan.acceptance when present; otherwise synthesize from #3267
+ * literal_acceptance_commands / empty+none_stated.
+ */
+export function readPlanAcceptance(plan) {
+    if (plan === null || plan === undefined) {
+        return { commands: [], none_stated: true, source_rung: "project_floor" };
+    }
+    const raw = plan[PLAN_ACCEPTANCE_KEY];
+    if (raw !== null && raw !== undefined) {
+        const rec = asRecord(raw);
+        if (rec !== null) {
+            const commands = coerceCommands(rec.commands);
+            const noneStated = rec.none_stated === true || (commands.length === 0 && rec.none_stated !== false);
+            let sourceRung = isAcSourceRung(rec.source_rung)
+                ? rec.source_rung
+                : commands.length > 0
+                    ? "stated"
+                    : "project_floor";
+            if (noneStated && commands.length > 0 && sourceRung === "stated") {
+                sourceRung = "derived";
+            }
+            if (noneStated && commands.length === 0) {
+                sourceRung = isAcSourceRung(rec.source_rung) ? rec.source_rung : "project_floor";
+            }
+            return {
+                commands,
+                none_stated: noneStated,
+                source_rung: sourceRung,
+                derived_reason: isNonEmptyString(rec.derived_reason)
+                    ? rec.derived_reason
+                    : isNonEmptyString(rec.derivedReason)
+                        ? rec.derivedReason
+                        : null,
+            };
+        }
+    }
+    // Fallback: #3267 metadata ledger.
+    const literal = readStoredLiteralAcceptanceCommands(plan);
+    if (literal.length > 0) {
+        return {
+            commands: literal.map(literalToAcceptance),
+            none_stated: false,
+            source_rung: "stated",
+            derived_reason: null,
+        };
+    }
+    return {
+        commands: [],
+        none_stated: true,
+        source_rung: "project_floor",
+        derived_reason: "no plan.acceptance and no literal_acceptance_commands (#3284 floor)",
+    };
+}
+function literalToAcceptance(cmd) {
+    return {
+        command: cmd.command,
+        cwd: cmd.cwd ?? null,
+        expectedStdout: cmd.expectedStdout ?? null,
+        expectedExitCode: cmd.expectedExitCode ?? 0,
+    };
+}
+function acceptanceToLiteral(cmd, source) {
+    return {
+        command: cmd.command,
+        cwd: cmd.cwd ?? null,
+        expectedStdout: cmd.expectedStdout ?? null,
+        expectedExitCode: cmd.expectedExitCode ?? 0,
+        source,
+        sourceSpan: "plan.acceptance.commands",
+    };
+}
+/** Attach a validated PlanAcceptance onto plan.acceptance + mirror to #3267 metadata. */
+export function attachPlanAcceptance(plan, acceptance) {
+    const errors = validatePlanAcceptance(acceptance);
+    if (errors.length > 0) {
+        throw new Error(`attachPlanAcceptance: ${errors.join("; ")}`);
+    }
+    const serializable = {
+        commands: acceptance.commands.map((c) => {
+            const row = { command: c.command };
+            if (c.cwd)
+                row.cwd = c.cwd;
+            if (c.expectedStdout)
+                row.expectedStdout = c.expectedStdout;
+            if (typeof c.expectedExitCode === "number" && c.expectedExitCode !== 0) {
+                row.expectedExitCode = c.expectedExitCode;
+            }
+            return row;
+        }),
+        none_stated: acceptance.none_stated,
+        source_rung: acceptance.source_rung,
+    };
+    if (acceptance.derived_reason) {
+        serializable.derived_reason = acceptance.derived_reason;
+    }
+    let next = {
+        ...plan,
+        [PLAN_ACCEPTANCE_KEY]: serializable,
+    };
+    // Mirror executable commands into #3267 ledger for verify:literal-ac interoperability.
+    if (acceptance.commands.length > 0) {
+        const source = acceptance.source_rung === "stated" ? "task_statement" : "explicit";
+        // derived / floor commands are agent-authored → executable source=explicit
+        const literalSource = acceptance.source_rung === "stated" ? "task_statement" : "explicit";
+        void source;
+        next = attachLiteralAcceptanceCommands(next, acceptance.commands.map((c) => acceptanceToLiteral(c, literalSource)));
+    }
+    return next;
+}
+/**
+ * Build plan.acceptance from intake capture (#3284).
+ * Stated commands → none_stated:false, source_rung:stated.
+ * No stated commands → none_stated:true, source_rung:project_floor (until agent derives).
+ */
+export function buildAcceptanceFromIntakeCapture(capturedCommands) {
+    if (capturedCommands.length === 0) {
+        return {
+            commands: [],
+            none_stated: true,
+            source_rung: "project_floor",
+            derived_reason: "no shell acceptance commands stated in task text; floor until agent derives AC (#3284 ladder)",
+        };
+    }
+    return {
+        commands: capturedCommands,
+        none_stated: false,
+        source_rung: "stated",
+        derived_reason: null,
+    };
+}
+/** Stamp plan.acceptance from existing literal capture after issue ingest. */
+export function stampAcceptanceFromLiteralCapture(plan) {
+    const literal = readStoredLiteralAcceptanceCommands(plan);
+    const acceptance = buildAcceptanceFromIntakeCapture(literal.map(literalToAcceptance));
+    // Avoid re-mirroring task_statement into verify_commands (ingest strips those).
+    const serializable = {
+        commands: acceptance.commands.map((c) => {
+            const row = { command: c.command };
+            if (c.cwd)
+                row.cwd = c.cwd;
+            if (c.expectedStdout)
+                row.expectedStdout = c.expectedStdout;
+            if (typeof c.expectedExitCode === "number" && c.expectedExitCode !== 0) {
+                row.expectedExitCode = c.expectedExitCode;
+            }
+            return row;
+        }),
+        none_stated: acceptance.none_stated,
+        source_rung: acceptance.source_rung,
+    };
+    if (acceptance.derived_reason) {
+        serializable.derived_reason = acceptance.derived_reason;
+    }
+    return {
+        ...plan,
+        [PLAN_ACCEPTANCE_KEY]: serializable,
+    };
+}
+//# sourceMappingURL=acceptance.js.map

package/dist/product-first-done-gate/check-mode.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Resolve product-first check composition mode (#3284).
+ *
+ * Priority (highest wins):
+ *  1. DEFT_CHECK_AC_ONLY / DEFT_CHECK_MODE=rapid → rapid (AC-only)
+ *  2. DEFT_CHECK_MODE=pressure|degraded or DEFT_HYGIENE_ADVISORY → pressure
+ *  3. ceremony dial depth rapid|minimal → rapid
+ *  4. hard effort budget (#3266) → pressure
+ *  5. default full
+ */
+import { type CeremonyDepth } from "../policy/ceremony-dial.js";
+import { type ProductFirstCheckMode } from "./types.js";
+export interface ResolveProductFirstCheckModeInput {
+    readonly environ?: Readonly<Record<string, string | undefined>>;
+    readonly projectRoot?: string;
+    /** Inject ceremony depth (tests); when unset, reads ritual-state audit. */
+    readonly ceremonyDepth?: CeremonyDepth | null;
+    /** Inject hard-budget detected flag (tests). */
+    readonly hardBudgetDetected?: boolean;
+}
+export interface ProductFirstCheckModeResolution {
+    readonly mode: ProductFirstCheckMode;
+    readonly sources: readonly string[];
+    readonly hygieneAdvisory: boolean;
+    readonly acOnly: boolean;
+    /** AC remains mandatory whenever mode is not a pure no-op. */
+    readonly acMandatory: true;
+}
+/**
+ * Resolve the active product-first check mode from env + ceremony + budget.
+ */
+export declare function resolveProductFirstCheckMode(input?: ResolveProductFirstCheckModeInput): ProductFirstCheckModeResolution;
+/** True when this gate id is the product AC gate. */
+export declare function isProductAcGate(gateId: string): boolean;
+/** True when this gate is classified as hygiene (may be advisory under pressure). */
+export declare function isHygieneGate(gateId: string): boolean;
+/**
+ * Filter / annotate gate list for the resolved mode.
+ * - rapid: only product AC gates
+ * - pressure/full: full list (pressure marks hygiene advisory at run time)
+ */
+export declare function applyProductFirstGateMode<T extends string | {
+    readonly task: string;
+}>(gates: readonly T[], mode: ProductFirstCheckMode, gateIdOf?: (g: T) => string): readonly T[];
+//# sourceMappingURL=check-mode.d.ts.map

package/dist/product-first-done-gate/check-mode.js

@@ -0,0 +1,148 @@
+/**
+ * Resolve product-first check composition mode (#3284).
+ *
+ * Priority (highest wins):
+ *  1. DEFT_CHECK_AC_ONLY / DEFT_CHECK_MODE=rapid → rapid (AC-only)
+ *  2. DEFT_CHECK_MODE=pressure|degraded or DEFT_HYGIENE_ADVISORY → pressure
+ *  3. ceremony dial depth rapid|minimal → rapid
+ *  4. hard effort budget (#3266) → pressure
+ *  5. default full
+ */
+import { CEREMONY_DEPTHS, readCeremonyDialAudit, } from "../policy/ceremony-dial.js";
+import { detectHardEffortBudget } from "../session/effort-budget.js";
+import { ENV_CHECK_AC_ONLY, ENV_CHECK_MODE, ENV_HYGIENE_ADVISORY, HYGIENE_GATE_ID_PREFIXES, PRODUCT_AC_GATE_ID, } from "./types.js";
+function asCeremonyDepth(value) {
+    return typeof value === "string" && CEREMONY_DEPTHS.includes(value)
+        ? value
+        : null;
+}
+const TRUTHY = new Set(["1", "true", "yes", "on"]);
+function isTruthy(raw) {
+    if (raw === undefined)
+        return false;
+    return TRUTHY.has(raw.trim().toLowerCase());
+}
+function normalizeModeToken(raw) {
+    const t = raw.trim().toLowerCase();
+    if (t === "full" || t === "standard")
+        return "full";
+    if (t === "pressure" || t === "degraded" || t === "advisory")
+        return "pressure";
+    if (t === "rapid" || t === "minimal" || t === "ac-only" || t === "ac_only")
+        return "rapid";
+    return null;
+}
+/**
+ * Resolve the active product-first check mode from env + ceremony + budget.
+ */
+export function resolveProductFirstCheckMode(input = {}) {
+    const env = input.environ ?? process.env;
+    const sources = [];
+    if (isTruthy(env[ENV_CHECK_AC_ONLY])) {
+        sources.push(`${ENV_CHECK_AC_ONLY}=truthy`);
+        return {
+            mode: "rapid",
+            sources,
+            hygieneAdvisory: true,
+            acOnly: true,
+            acMandatory: true,
+        };
+    }
+    const modeEnv = env[ENV_CHECK_MODE];
+    if (typeof modeEnv === "string" && modeEnv.trim().length > 0) {
+        const parsed = normalizeModeToken(modeEnv);
+        if (parsed !== null) {
+            sources.push(`${ENV_CHECK_MODE}=${modeEnv.trim()}`);
+            return {
+                mode: parsed,
+                sources,
+                hygieneAdvisory: parsed !== "full",
+                acOnly: parsed === "rapid",
+                acMandatory: true,
+            };
+        }
+    }
+    if (isTruthy(env[ENV_HYGIENE_ADVISORY])) {
+        sources.push(`${ENV_HYGIENE_ADVISORY}=truthy`);
+        return {
+            mode: "pressure",
+            sources,
+            hygieneAdvisory: true,
+            acOnly: false,
+            acMandatory: true,
+        };
+    }
+    let depth = input.ceremonyDepth;
+    if (depth === undefined && input.projectRoot !== undefined) {
+        try {
+            const audit = readCeremonyDialAudit(input.projectRoot);
+            depth = asCeremonyDepth(audit.depth);
+            if (depth !== null)
+                sources.push(`ceremony_dial.depth=${depth}`);
+        }
+        catch {
+            depth = null;
+        }
+    }
+    if (depth === "rapid" || depth === "minimal") {
+        if (!sources.some((s) => s.startsWith("ceremony_dial"))) {
+            sources.push(`ceremonyDepth=${depth}`);
+        }
+        return {
+            mode: "rapid",
+            sources,
+            hygieneAdvisory: true,
+            acOnly: true,
+            acMandatory: true,
+        };
+    }
+    let hardBudget = input.hardBudgetDetected;
+    if (hardBudget === undefined) {
+        hardBudget = detectHardEffortBudget({ environ: env }).detected;
+        if (hardBudget)
+            sources.push("hard_effort_budget");
+    }
+    else if (hardBudget) {
+        sources.push("hard_effort_budget(injected)");
+    }
+    if (hardBudget === true) {
+        return {
+            mode: "pressure",
+            sources,
+            hygieneAdvisory: true,
+            acOnly: false,
+            acMandatory: true,
+        };
+    }
+    sources.push("default:full");
+    return {
+        mode: "full",
+        sources,
+        hygieneAdvisory: false,
+        acOnly: false,
+        acMandatory: true,
+    };
+}
+/** True when this gate id is the product AC gate. */
+export function isProductAcGate(gateId) {
+    return gateId === PRODUCT_AC_GATE_ID || gateId === "verify:literal-ac";
+}
+/** True when this gate is classified as hygiene (may be advisory under pressure). */
+export function isHygieneGate(gateId) {
+    if (isProductAcGate(gateId))
+        return false;
+    return HYGIENE_GATE_ID_PREFIXES.includes(gateId);
+}
+/**
+ * Filter / annotate gate list for the resolved mode.
+ * - rapid: only product AC gates
+ * - pressure/full: full list (pressure marks hygiene advisory at run time)
+ */
+export function applyProductFirstGateMode(gates, mode, gateIdOf = (g) => (typeof g === "string" ? g : g.task)) {
+    if (mode === "rapid") {
+        const ac = gates.filter((g) => isProductAcGate(gateIdOf(g)));
+        return ac.length > 0 ? ac : gates.filter((g) => gateIdOf(g) === PRODUCT_AC_GATE_ID);
+    }
+    return gates;
+}
+//# sourceMappingURL=check-mode.js.map

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

@@ -0,0 +1,50 @@
+/**
+ * evaluate verify:ac — product-first acceptance gate (#3284).
+ *
+ * Runs plan.acceptance.commands (or #3267 literal ledger) via the shared
+ * literal-acceptance runner. Records source_rung in the result message.
+ * Project floor with empty commands is a soft pass (suite gates own the floor
+ * inside full `task check`); standalone done paths still surface the rung.
+ */
+import { type EvaluateLiteralAcceptanceOptions, type LiteralAcceptanceGateResult } from "../literal-acceptance/index.js";
+import type { AcSourceRung, PlanAcceptance } from "./types.js";
+export interface VerifyAcResult extends LiteralAcceptanceGateResult {
+    readonly sourceRung: AcSourceRung;
+    readonly noneStated: boolean;
+    readonly acceptance: PlanAcceptance;
+}
+export interface EvaluateVerifyAcOptions extends EvaluateLiteralAcceptanceOptions {
+    /**
+     * When true, missing xBRIEF / no active scope is exit 0 (check composition).
+     * Default false for standalone done-gate use.
+     */
+    readonly softMissingXbrief?: boolean;
+    /**
+     * Check-graph mode (#3284): used by `task check` via `--soft-missing-xbrief`.
+     * - Unpromoted capture-only (task_statement) commands do not fail the graph
+     *   (promotion remains a done-gate / scope:complete concern via verify:ac standalone).
+     * - Executable command failures still fail closed (product-first).
+     * - Safety-rejected ledger still fails closed.
+     */
+    readonly checkIntegrated?: boolean;
+    /** Allow task_statement sources to execute (tests / explicit promote). */
+    readonly allowTaskStatement?: boolean;
+    /**
+     * When false, skip AC-pass banking after executable pass (#3285).
+     * Default true — first green executable AC banks a finalize checkpoint.
+     */
+    readonly bankOnPass?: boolean;
+    /** Optional scope id override for the bank ledger (default plan.id / path). */
+    readonly bankScopeId?: string | null;
+}
+/**
+ * Evaluate product AC from an in-memory plan.
+ */
+export declare function evaluateVerifyAcFromPlan(plan: Record<string, unknown>, options?: EvaluateVerifyAcOptions): VerifyAcResult;
+/**
+ * Evaluate from xBRIEF path.
+ */
+export declare function evaluateVerifyAcFromPath(xbriefPath: string, options?: EvaluateVerifyAcOptions): VerifyAcResult;
+/** Pure: product AC is required at every ceremony depth (#3284 / #3267 / #3156). */
+export declare function isVerifyAcRequiredAtCeremonyDepth(_depth: string | null | undefined): boolean;
+//# sourceMappingURL=evaluate.d.ts.map