@deftai/directive-core 0.101.0 → 0.103.0

package/dist/verify-ac/evaluate.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Apply product-oracle integrity to verify:ac (#3322).
+ *
+ * Missing run-summary is a no-op (no evidence). A flagged
+ * fail → method-change → pass without independent_rederivation fails closed.
+ * Stdout dest (`DEFT_RUN_SUMMARY_PATH=-`) evaluates the same-process
+ * attempts just emitted by this verify:ac — it does not treat non-file
+ * dest as no evidence.
+ */
+import type { LiteralAcceptanceRunResult } from "../literal-acceptance/types.js";
+import { type FlaggedMethodChangePass } from "./flag.js";
+export interface EvaluateProductOracleIntegrityOptions {
+    readonly projectRoot: string;
+    /** Injected JSONL (tests). Undefined → read dest; null → empty. */
+    readonly runSummaryText?: string | null;
+    readonly env?: NodeJS.ProcessEnv;
+}
+export interface ProductOracleIntegrityVerdict {
+    readonly ok: boolean;
+    readonly code: 0 | 1;
+    readonly flagged: readonly FlaggedMethodChangePass[];
+    readonly unresolved: readonly FlaggedMethodChangePass[];
+    readonly message: string;
+}
+export interface OracleIntegrityResultFields {
+    readonly ok: boolean;
+    readonly code: number;
+    readonly message: string;
+}
+/** Stable prefix for product-oracle check ids emitted by verify:ac (#3322 / #3337). */
+export declare const VERIFY_AC_CHECK_ID_PREFIX = "verify:ac";
+/**
+ * Namespace product-oracle check_id per active scope (#3337).
+ *
+ * Same-session multi-active verify:ac must not pair fail/pass across briefs.
+ * Prefer plan.id or xBRIEF path as scopeKey; empty → global fallback `verify:ac`
+ * (unknown-scope single-brief / tests without a plan).
+ */
+export declare function verifyAcCheckId(scopeKey?: string | null): string;
+/** Test seam: isolate stdout-dest buffer across cases. */
+export declare function resetInProcessVerificationBuffer(): void;
+/**
+ * Record each executed acceptance command as a verification event (#3322).
+ * Fail-open: missing dest / write errors never change the AC result.
+ * Stdout dest also appends to the same-process buffer so evaluate can
+ * inspect this invocation without re-reading a file.
+ * check_id is namespaced per active scope when scopeKey is provided (#3337).
+ */
+export declare function emitVerifyAcAttempts(options: {
+    readonly projectRoot: string;
+    readonly runs: readonly LiteralAcceptanceRunResult[];
+    readonly env?: NodeJS.ProcessEnv;
+    readonly sessionId?: string;
+    /**
+     * Active scope identity (plan.id or xBRIEF path stem). When set, check_id
+     * becomes `verify:ac/<scopeKey>` so multi-active sessions do not false-deny (#3337).
+     */
+    readonly scopeKey?: string | null;
+    /** Full check_id override (tests). Wins over scopeKey when non-empty. */
+    readonly checkId?: string | null;
+    /** stdout seam (tests). */
+    readonly writeStdout?: (line: string) => void;
+}): void;
+/**
+ * Evaluate run-summary verification events for pass-after-fail-with-method-change.
+ */
+export declare function evaluateProductOracleIntegrity(options: EvaluateProductOracleIntegrityOptions): ProductOracleIntegrityVerdict;
+/**
+ * Lead the verify:ac message with any unresolved discrepancy.
+ * Config errors (code 2) stay 2; unresolved oracle is exit 1.
+ */
+export declare function mergeOracleVerdict<T extends OracleIntegrityResultFields>(result: T, verdict: ProductOracleIntegrityVerdict): T;
+//# sourceMappingURL=evaluate.d.ts.map

package/dist/verify-ac/evaluate.js

@@ -0,0 +1,167 @@
+/**
+ * Apply product-oracle integrity to verify:ac (#3322).
+ *
+ * Missing run-summary is a no-op (no evidence). A flagged
+ * fail → method-change → pass without independent_rederivation fails closed.
+ * Stdout dest (`DEFT_RUN_SUMMARY_PATH=-`) evaluates the same-process
+ * attempts just emitted by this verify:ac — it does not treat non-file
+ * dest as no evidence.
+ */
+import { randomUUID } from "node:crypto";
+import { existsSync, readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { parseRunSummaryJsonl, RunSummaryEmitter, resolveRunSummaryDestination, } from "../run-summary/index.js";
+import { flagPassAfterFailWithMethodChange, readVerificationAttempts, unresolvedMethodChangePasses, } from "./flag.js";
+function formatUnresolved(flag) {
+    return (`check_id=${flag.check_id} fail method=${flag.failed_method} ` +
+        `then pass method=${flag.passed_method} without independent re-derivation`);
+}
+/** Stable prefix for product-oracle check ids emitted by verify:ac (#3322 / #3337). */
+export const VERIFY_AC_CHECK_ID_PREFIX = "verify:ac";
+/**
+ * Namespace product-oracle check_id per active scope (#3337).
+ *
+ * Same-session multi-active verify:ac must not pair fail/pass across briefs.
+ * Prefer plan.id or xBRIEF path as scopeKey; empty → global fallback `verify:ac`
+ * (unknown-scope single-brief / tests without a plan).
+ */
+export function verifyAcCheckId(scopeKey) {
+    const key = typeof scopeKey === "string" ? scopeKey.trim() : "";
+    if (key.length === 0) {
+        return VERIFY_AC_CHECK_ID_PREFIX;
+    }
+    // Keep pairing keys readable; strip control chars that would corrupt JSONL.
+    const safe = key.replace(/[\0\n\r]/g, "_");
+    return `${VERIFY_AC_CHECK_ID_PREFIX}/${safe}`;
+}
+/** Same-process verification JSONL when dest is stdout (`-`). */
+const inProcessVerificationLines = [];
+let inProcessStdoutSessionId;
+/** Test seam: isolate stdout-dest buffer across cases. */
+export function resetInProcessVerificationBuffer() {
+    inProcessVerificationLines.length = 0;
+    inProcessStdoutSessionId = undefined;
+}
+function inProcessVerificationText() {
+    if (inProcessVerificationLines.length === 0) {
+        return null;
+    }
+    return inProcessVerificationLines.join("\n");
+}
+/**
+ * Record each executed acceptance command as a verification event (#3322).
+ * Fail-open: missing dest / write errors never change the AC result.
+ * Stdout dest also appends to the same-process buffer so evaluate can
+ * inspect this invocation without re-reading a file.
+ * check_id is namespaced per active scope when scopeKey is provided (#3337).
+ */
+export function emitVerifyAcAttempts(options) {
+    if (options.runs.length === 0) {
+        return;
+    }
+    try {
+        const env = options.env ?? process.env;
+        const projectRoot = resolve(options.projectRoot);
+        const dest = resolveRunSummaryDestination(projectRoot, { env });
+        const explicitSession = options.sessionId?.trim() ||
+            (typeof env.DEFT_SESSION_ID === "string" ? env.DEFT_SESSION_ID.trim() : "");
+        let sessionId = explicitSession;
+        if (!sessionId) {
+            if (dest.kind === "stdout") {
+                inProcessStdoutSessionId ??= randomUUID();
+                sessionId = inProcessStdoutSessionId;
+            }
+            else {
+                sessionId = randomUUID();
+            }
+        }
+        const explicitCheck = typeof options.checkId === "string" && options.checkId.trim().length > 0
+            ? options.checkId.trim()
+            : null;
+        const checkId = explicitCheck ?? verifyAcCheckId(options.scopeKey);
+        const emitter = new RunSummaryEmitter({
+            projectRoot,
+            sessionId,
+            env,
+            writeStdout: options.writeStdout,
+        });
+        for (const run of options.runs) {
+            const emitted = emitter.emitVerification({
+                check_id: checkId,
+                method_fingerprint: `${run.command}\0${run.cwd}`,
+                outcome: run.ok ? "pass" : "fail",
+            });
+            if (dest.kind === "stdout" && emitted.line !== null) {
+                inProcessVerificationLines.push(JSON.stringify(emitted.line));
+            }
+        }
+    }
+    catch {
+        // fail-open
+    }
+}
+function loadRunSummaryText(projectRoot, env) {
+    const dest = resolveRunSummaryDestination(resolve(projectRoot), { env });
+    if (dest.kind === "stdout") {
+        return inProcessVerificationText();
+    }
+    if (dest.kind !== "file") {
+        return null;
+    }
+    if (!existsSync(dest.path)) {
+        return null;
+    }
+    try {
+        return readFileSync(dest.path, "utf8");
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Evaluate run-summary verification events for pass-after-fail-with-method-change.
+ */
+export function evaluateProductOracleIntegrity(options) {
+    const env = options.env;
+    const text = options.runSummaryText === undefined
+        ? env !== undefined
+            ? loadRunSummaryText(options.projectRoot, env)
+            : null
+        : options.runSummaryText;
+    if (text === null || text.trim().length === 0) {
+        return { ok: true, code: 0, flagged: [], unresolved: [], message: "" };
+    }
+    const flagged = flagPassAfterFailWithMethodChange(readVerificationAttempts(parseRunSummaryJsonl(text)));
+    const unresolved = unresolvedMethodChangePasses(flagged);
+    if (unresolved.length === 0) {
+        return { ok: true, code: 0, flagged, unresolved, message: "" };
+    }
+    const lead = `UNRESOLVED product-oracle discrepancy (#3322): ${unresolved.map(formatUnresolved).join("; ")}. ` +
+        "Resolve by a product change (same method) or independently re-derive both sides " +
+        "and record independent_rederivation=true.";
+    return {
+        ok: false,
+        code: 1,
+        flagged,
+        unresolved,
+        message: lead,
+    };
+}
+/**
+ * Lead the verify:ac message with any unresolved discrepancy.
+ * Config errors (code 2) stay 2; unresolved oracle is exit 1.
+ */
+export function mergeOracleVerdict(result, verdict) {
+    if (verdict.ok || verdict.message.length === 0) {
+        return result;
+    }
+    const message = result.message ? `${verdict.message}\n${result.message}` : verdict.message;
+    const code = result.code === 2 ? 2 : 1;
+    return {
+        ...result,
+        ok: false,
+        code,
+        message,
+    };
+}
+//# sourceMappingURL=evaluate.js.map

package/dist/verify-ac/flag.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Flag fail → method-change → pass on one product-oracle check id (#3322).
+ *
+ * A red verification may be resolved only by a product change (same method)
+ * or an independently re-derived oracle (both sides rebuilt, different method).
+ * In-place comparison repair then pass is unresolved.
+ */
+import { type RunSummaryLine } from "../run-summary/index.js";
+import type { VerificationOutcome } from "../run-summary/types.js";
+export interface VerificationAttempt {
+    readonly check_id: string;
+    readonly method_fingerprint: string;
+    readonly outcome: VerificationOutcome;
+    readonly independent_rederivation: boolean;
+    /** Session that emitted the attempt; used to avoid cross-session pairing. */
+    readonly session_id: string;
+}
+export interface FlaggedMethodChangePass {
+    readonly check_id: string;
+    readonly failed_method: string;
+    readonly passed_method: string;
+    readonly independent_rederivation: boolean;
+}
+/** Extract well-formed verification attempts in stream order. */
+export declare function readVerificationAttempts(lines: readonly RunSummaryLine[]): VerificationAttempt[];
+/**
+ * Flag each fail → different method → pass sequence on the same check id.
+ * Independent re-derivation is recorded on the pass event, not inferred.
+ */
+export declare function flagPassAfterFailWithMethodChange(attempts: readonly VerificationAttempt[]): FlaggedMethodChangePass[];
+/** Unresolved flags: method-change pass without recorded re-derivation. */
+export declare function unresolvedMethodChangePasses(flagged: readonly FlaggedMethodChangePass[]): FlaggedMethodChangePass[];
+/** Parse JSONL (or DEFT-TLM capture) and flag method-change passes. */
+export declare function flagPassAfterFailFromJsonl(text: string): FlaggedMethodChangePass[];
+//# sourceMappingURL=flag.d.ts.map

package/dist/verify-ac/flag.js

@@ -0,0 +1,104 @@
+/**
+ * Flag fail → method-change → pass on one product-oracle check id (#3322).
+ *
+ * A red verification may be resolved only by a product change (same method)
+ * or an independently re-derived oracle (both sides rebuilt, different method).
+ * In-place comparison repair then pass is unresolved.
+ */
+import { parseRunSummaryJsonl } from "../run-summary/index.js";
+function asRecord(value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+        return null;
+    }
+    return value;
+}
+function isVerificationOutcome(value) {
+    return value === "pass" || value === "fail";
+}
+function readAttempt(line) {
+    if (line.event !== "verification") {
+        return null;
+    }
+    const payload = asRecord(line.payload);
+    if (payload === null) {
+        return null;
+    }
+    const checkId = payload.check_id;
+    const fingerprint = payload.method_fingerprint;
+    if (typeof checkId !== "string" || checkId.trim().length === 0) {
+        return null;
+    }
+    if (typeof fingerprint !== "string" || fingerprint.trim().length === 0) {
+        return null;
+    }
+    if (!isVerificationOutcome(payload.outcome)) {
+        return null;
+    }
+    return {
+        check_id: checkId,
+        method_fingerprint: fingerprint,
+        outcome: payload.outcome,
+        independent_rederivation: payload.independent_rederivation === true,
+        session_id: line.session_id,
+    };
+}
+/** Extract well-formed verification attempts in stream order. */
+export function readVerificationAttempts(lines) {
+    const attempts = [];
+    for (const line of lines) {
+        const attempt = readAttempt(line);
+        if (attempt !== null) {
+            attempts.push(attempt);
+        }
+    }
+    return attempts;
+}
+/**
+ * Flag each fail → different method → pass sequence on the same check id.
+ * Independent re-derivation is recorded on the pass event, not inferred.
+ */
+export function flagPassAfterFailWithMethodChange(attempts) {
+    const failedMethods = new Map();
+    const flagged = [];
+    for (const attempt of attempts) {
+        const key = `${attempt.session_id}\0${attempt.check_id}`;
+        if (attempt.outcome === "fail") {
+            const set = failedMethods.get(key) ?? new Set();
+            set.add(attempt.method_fingerprint);
+            failedMethods.set(key, set);
+            continue;
+        }
+        const prior = failedMethods.get(key);
+        if (prior === undefined || prior.size === 0) {
+            continue;
+        }
+        const other = [...prior].find((method) => method !== attempt.method_fingerprint);
+        if (other !== undefined) {
+            flagged.push({
+                check_id: attempt.check_id,
+                failed_method: other,
+                passed_method: attempt.method_fingerprint,
+                independent_rederivation: attempt.independent_rederivation,
+            });
+        }
+        if (attempt.independent_rederivation || other === undefined) {
+            failedMethods.delete(key);
+        }
+        else {
+            prior.delete(attempt.method_fingerprint);
+            if (prior.size === 0) {
+                failedMethods.delete(key);
+            }
+        }
+    }
+    return flagged;
+}
+/** Unresolved flags: method-change pass without recorded re-derivation. */
+export function unresolvedMethodChangePasses(flagged) {
+    return flagged.filter((flag) => !flag.independent_rederivation);
+}
+/** Parse JSONL (or DEFT-TLM capture) and flag method-change passes. */
+export function flagPassAfterFailFromJsonl(text) {
+    return flagPassAfterFailWithMethodChange(readVerificationAttempts(parseRunSummaryJsonl(text)));
+}
+//# sourceMappingURL=flag.js.map

package/dist/verify-ac/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Product-oracle gate integrity for verify:ac (#3322).
+ *
+ * Extends #3156: a red product verification may not be self-adjudicated
+ * by editing the comparison. Deterministic surface is the flagged event.
+ */
+export { type AcceptanceClause, type AcceptanceClauseReading, type ClauseOutcome, type ClauseWalkReport, type ClauseWalkResult, deriveAcceptanceClauses, formatClauseWalkMessage, isScratchArtifactPath, readAcceptanceClauses, serializeAcceptanceClauses, stampDerivedClausesOnAcceptance, walkAcceptanceClauses, } from "./clauses.js";
+export { type EvaluateProductOracleIntegrityOptions, emitVerifyAcAttempts, evaluateProductOracleIntegrity, mergeOracleVerdict, type OracleIntegrityResultFields, type ProductOracleIntegrityVerdict, VERIFY_AC_CHECK_ID_PREFIX, verifyAcCheckId, } from "./evaluate.js";
+export { type FlaggedMethodChangePass, flagPassAfterFailFromJsonl, flagPassAfterFailWithMethodChange, readVerificationAttempts, unresolvedMethodChangePasses, type VerificationAttempt, } from "./flag.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/verify-ac/index.js

@@ -0,0 +1,10 @@
+/**
+ * Product-oracle gate integrity for verify:ac (#3322).
+ *
+ * Extends #3156: a red product verification may not be self-adjudicated
+ * by editing the comparison. Deterministic surface is the flagged event.
+ */
+export { deriveAcceptanceClauses, formatClauseWalkMessage, isScratchArtifactPath, readAcceptanceClauses, serializeAcceptanceClauses, stampDerivedClausesOnAcceptance, walkAcceptanceClauses, } from "./clauses.js";
+export { emitVerifyAcAttempts, evaluateProductOracleIntegrity, mergeOracleVerdict, VERIFY_AC_CHECK_ID_PREFIX, verifyAcCheckId, } from "./evaluate.js";
+export { flagPassAfterFailFromJsonl, flagPassAfterFailWithMethodChange, readVerificationAttempts, unresolvedMethodChangePasses, } from "./flag.js";
+//# sourceMappingURL=index.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deftai/directive-core",
-  "version": "0.101.0",
+  "version": "0.103.0",
   "description": "TypeScript engine core for the Directive framework.",
   "license": "MIT",
   "type": "module",
@@ -291,6 +291,10 @@
       "types": "./dist/product-first-done-gate/index.d.ts",
       "default": "./dist/product-first-done-gate/index.js"
     },
+    "./verify-ac": {
+      "types": "./dist/verify-ac/index.d.ts",
+      "default": "./dist/verify-ac/index.js"
+    },
     "./packs": {
       "types": "./dist/packs/index.d.ts",
       "default": "./dist/packs/index.js"
@@ -378,8 +382,8 @@
     "provenance": true
   },
   "dependencies": {
-    "@deftai/directive-content": "^0.101.0",
-    "@deftai/directive-types": "^0.101.0",
+    "@deftai/directive-content": "^0.103.0",
+    "@deftai/directive-types": "^0.103.0",
     "archiver": "^8.0.0"
   },
   "scripts": {

package/dist/policy/coverage-check-resume-presets.d.ts

@@ -1,46 +0,0 @@
-/**
- * Bundled presets for coverageDebt + checkResume (#3189).
- *
- * One project decision (not five micro-toggles in v1).
- * Later does not write decided; Strict / Hatch-aware / dismiss-with-reason do.
- *
- * Both fields are written in a single PROJECT-DEFINITION mutation lock so a
- * partial decision (coverageDebt decided, checkResume still unset) cannot
- * persist after a mid-write failure.
- */
-export declare const COVERAGE_CHECK_RESUME_PRESETS: readonly ["strict", "hatch-aware"];
-export type CoverageCheckResumePreset = (typeof COVERAGE_CHECK_RESUME_PRESETS)[number];
-export interface ApplyCoverageCheckResumePresetOptions {
-    readonly actor?: string;
-    readonly note?: string;
-}
-export interface ApplyCoverageCheckResumePresetResult {
-    readonly exitCode: 0 | 1 | 2;
-    readonly stdout: string;
-    readonly changed: boolean;
-    readonly preset: CoverageCheckResumePreset | "dismiss" | "later";
-}
-/** True when either policy is still unset (coupled v1 nag). */
-export declare function isCoverageCheckResumeUndecided(projectRoot: string): boolean;
-/**
- * Apply Strict: coverageDebt.mode=off, checkResume.localStamp=off, both decided.
- * Recommended for most apps.
- */
-export declare function applyStrictCoverageCheckResumePreset(projectRoot: string, options?: ApplyCoverageCheckResumePresetOptions): ApplyCoverageCheckResumePresetResult;
-/**
- * Apply Hatch-aware: coverageDebt.mode=hatch autoFile=false; localStamp=on for DX.
- * CI still never trusts local stamps.
- */
-export declare function applyHatchAwareCoverageCheckResumePreset(projectRoot: string, options?: ApplyCoverageCheckResumePresetOptions): ApplyCoverageCheckResumePresetResult;
-/**
- * Dismiss-with-reason: marks both decided as fail-closed (mode off / localStamp off)
- * and records the reason for policy:show / doctor visibility. Stops the session nag.
- */
-export declare function dismissCoverageCheckResume(projectRoot: string, reason: string, options?: ApplyCoverageCheckResumePresetOptions): ApplyCoverageCheckResumePresetResult;
-/**
- * Later: does NOT write status=decided. Caller skips for this session;
- * next session-start ritual nags again.
- */
-export declare function applyLaterCoverageCheckResumeSkip(): ApplyCoverageCheckResumePresetResult;
-export declare function formatCoverageCheckResumeBundleStatus(projectRoot: string): string;
-//# sourceMappingURL=coverage-check-resume-presets.d.ts.map