@deftai/directive-core 0.100.0 → 0.102.0

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

@@ -0,0 +1,51 @@
+/**
+ * Rung-2 derived AC: decompose the task statement into testable clauses
+ * at intake; walk every clause against the shipped artifact at done (#3323).
+ */
+export type ClauseOutcome = "verified" | "unverifiable" | "failed";
+export interface AcceptanceClauseReading {
+    readonly text: string;
+    readonly artifact_path: string | null;
+}
+export interface AcceptanceClause {
+    readonly id: number;
+    readonly text: string;
+    readonly artifact_path: string | null;
+    readonly ambiguous: boolean;
+    readonly readings?: readonly AcceptanceClauseReading[];
+    readonly chosen_reading?: number;
+}
+export interface ClauseWalkResult {
+    readonly id: number;
+    readonly text: string;
+    readonly artifact_path: string | null;
+    readonly outcome: ClauseOutcome;
+    readonly detail: string;
+}
+export interface ClauseWalkReport {
+    readonly clauses: readonly ClauseWalkResult[];
+    readonly failed: readonly ClauseWalkResult[];
+    readonly unverifiable: readonly ClauseWalkResult[];
+    readonly verified: readonly ClauseWalkResult[];
+    readonly ok: boolean;
+    readonly message: string;
+}
+/** Numbered independently testable clauses from the task statement (#3323). */
+export declare function deriveAcceptanceClauses(taskStatement: string): AcceptanceClause[];
+export declare function readAcceptanceClauses(acceptance: unknown): AcceptanceClause[];
+export declare function serializeAcceptanceClauses(clauses: readonly AcceptanceClause[]): Record<string, unknown>[];
+/**
+ * When no commands are stated, stamp derived clauses onto plan.acceptance
+ * and promote source_rung to derived. Leaves stated-command acceptance alone.
+ */
+export declare function stampDerivedClausesOnAcceptance(plan: Record<string, unknown>, taskStatement: string): {
+    readonly plan: Record<string, unknown>;
+    readonly clauses: readonly AcceptanceClause[];
+};
+export declare function isScratchArtifactPath(artifactPath: string): boolean;
+export declare function walkAcceptanceClauses(clauses: readonly AcceptanceClause[], projectRoot: string): ClauseWalkReport;
+/** Done reports lead with failed/unverifiable; unverifiable is never dropped. */
+export declare function formatClauseWalkMessage(report: Omit<ClauseWalkReport, "message"> & {
+    readonly message?: string;
+}, prior?: string): string;
+//# sourceMappingURL=clauses.d.ts.map

package/dist/verify-ac/clauses.js

@@ -0,0 +1,490 @@
+/**
+ * Rung-2 derived AC: decompose the task statement into testable clauses
+ * at intake; walk every clause against the shipped artifact at done (#3323).
+ */
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { isAbsolute, relative, resolve } from "node:path";
+import { findAcHeading, parseListItems, sliceAcSection } from "../intake/markdown-scanners.js";
+const SECTION_HEADING = /^(#{1,6})\s+(acceptance(?:\s+criteria|\s+sketch)?|fix)\s*$/i;
+const LABELED_AC_PREFIXES = ["test:", "acceptance:", "acceptancecriteria:"];
+const META_CLAUSE = /^(relates?\s+#|refs?\s+#)/i;
+const FILE_EXT = /\.(?:ts|tsx|js|mjs|cjs|json|md|go|py|yml|yaml|txt)$/i;
+const SCRATCH_SEGMENTS = new Set([
+    "tmp",
+    "temp",
+    ".deft-scratch",
+    "node_modules",
+    "scratch",
+    "buffer",
+]);
+const EXISTENCE_CLAIM = /\b(?:exists?|stored on|written to|emitted? (?:at|to)|at its stated path|artifact path)\b/i;
+const NEGATED_EXISTENCE = /\b(?:does not exist|doesn't exist|must not exist|never exists?|not exist)\b/i;
+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 normalizeClauseText(text) {
+    return text.replace(/\s+/g, " ").trim();
+}
+function looksLikeFilePath(token) {
+    const t = token.trim().replace(/^['"`]|['"`]$/g, "");
+    if (t.length < 3 || t.includes("://") || t.includes(" ")) {
+        return false;
+    }
+    if (t.startsWith("plan.") || (t.includes(":") && !t.includes("/") && !t.includes("\\"))) {
+        return false;
+    }
+    const unified = t.replace(/\\/g, "/");
+    if (FILE_EXT.test(unified)) {
+        return true;
+    }
+    return unified.includes("/") && !unified.startsWith("#");
+}
+function extractPathTokens(text) {
+    const found = [];
+    const seen = new Set();
+    const push = (raw) => {
+        const token = raw.trim().replace(/^['"`]|['"`]$/g, "");
+        if (!looksLikeFilePath(token) || seen.has(token)) {
+            return;
+        }
+        seen.add(token);
+        found.push(token);
+    };
+    const backtick = /`([^`\n]{2,200})`/g;
+    let match = backtick.exec(text);
+    while (match !== null) {
+        push(match[1] ?? "");
+        match = backtick.exec(text);
+    }
+    const bare = /(?<![A-Za-z0-9_])((?:[A-Za-z0-9_.-]+\/)*[A-Za-z0-9_.-]+\.[A-Za-z][A-Za-z0-9]+)(?![A-Za-z0-9_])/g;
+    match = bare.exec(text);
+    while (match !== null) {
+        push(match[1] ?? "");
+        match = bare.exec(text);
+    }
+    return found;
+}
+function isMetaClause(text) {
+    return META_CLAUSE.test(text.trim());
+}
+function collectSectionItems(text, headingRe) {
+    const items = [];
+    let offset = 0;
+    for (const line of text.split("\n")) {
+        const match = headingRe.exec(line.trim());
+        if (match !== null) {
+            const hashes = (match[1] ?? "#").length;
+            const section = sliceAcSection(text, {
+                level: hashes,
+                sectionStart: offset + line.length + 1,
+            });
+            for (const item of parseListItems(section)) {
+                const title = normalizeClauseText(item.title.replace(/\*\*/g, ""));
+                if (title.length > 0 && !isMetaClause(title)) {
+                    items.push(title);
+                }
+            }
+        }
+        offset += line.length + 1;
+    }
+    return items;
+}
+function matchLabeledAcLine(line) {
+    const trimmed = line.trim();
+    if (trimmed.length === 0) {
+        return null;
+    }
+    const lower = trimmed.toLowerCase();
+    for (const prefix of LABELED_AC_PREFIXES) {
+        if (!lower.startsWith(prefix)) {
+            continue;
+        }
+        const body = trimmed.slice(prefix.length).trim();
+        return body.length > 0 ? body : null;
+    }
+    return null;
+}
+function collectLabeledLines(text) {
+    const items = [];
+    for (const line of text.split("\n")) {
+        const body = matchLabeledAcLine(line);
+        if (body !== null && !isMetaClause(body)) {
+            items.push(normalizeClauseText(body));
+        }
+    }
+    return items;
+}
+function collectPathBearingLines(text) {
+    const items = [];
+    for (const item of parseListItems(text)) {
+        const title = normalizeClauseText(item.title.replace(/\*\*/g, ""));
+        if (title.length === 0 || isMetaClause(title)) {
+            continue;
+        }
+        if (extractPathTokens(title).length > 0) {
+            items.push(title);
+        }
+    }
+    return items;
+}
+/** Numbered independently testable clauses from the task statement (#3323). */
+export function deriveAcceptanceClauses(taskStatement) {
+    const text = taskStatement.trim();
+    if (text.length === 0) {
+        return [];
+    }
+    const acHeading = findAcHeading(text);
+    const raw = [];
+    if (acHeading !== null) {
+        raw.push(...parseListItems(sliceAcSection(text, acHeading))
+            .map((item) => normalizeClauseText(item.title.replace(/\*\*/g, "")))
+            .filter((title) => title.length > 0 && !isMetaClause(title)));
+    }
+    raw.push(...collectSectionItems(text, SECTION_HEADING));
+    raw.push(...collectLabeledLines(text));
+    if (raw.length === 0) {
+        raw.push(...collectPathBearingLines(text));
+    }
+    const seen = new Set();
+    const clauses = [];
+    for (const line of raw) {
+        const key = line.toLowerCase();
+        if (seen.has(key)) {
+            continue;
+        }
+        seen.add(key);
+        clauses.push(buildClause(clauses.length + 1, line));
+    }
+    return clauses;
+}
+function buildClause(id, text) {
+    const paths = extractPathTokens(text);
+    if (paths.length <= 1) {
+        return {
+            id,
+            text,
+            artifact_path: paths[0] ?? null,
+            ambiguous: false,
+        };
+    }
+    const readings = paths.map((artifact_path) => ({
+        text: `${text} [reading: ${artifact_path}]`,
+        artifact_path,
+    }));
+    return {
+        id,
+        text,
+        artifact_path: paths[0] ?? null,
+        ambiguous: true,
+        readings,
+        chosen_reading: 0,
+    };
+}
+export function readAcceptanceClauses(acceptance) {
+    const rec = asRecord(acceptance);
+    if (rec === null || !Array.isArray(rec.clauses)) {
+        return [];
+    }
+    const out = [];
+    for (const [index, entry] of rec.clauses.entries()) {
+        const row = asRecord(entry);
+        if (row === null) {
+            continue;
+        }
+        const text = isNonEmptyString(row.text) ? normalizeClauseText(row.text) : "";
+        if (text.length === 0) {
+            continue;
+        }
+        const artifact = isNonEmptyString(row.artifact_path)
+            ? row.artifact_path.trim()
+            : isNonEmptyString(row.artifactPath)
+                ? row.artifactPath.trim()
+                : null;
+        const readings = Array.isArray(row.readings)
+            ? row.readings
+                .map((reading) => {
+                const rr = asRecord(reading);
+                if (rr === null || !isNonEmptyString(rr.text)) {
+                    return null;
+                }
+                const path = isNonEmptyString(rr.artifact_path)
+                    ? rr.artifact_path.trim()
+                    : isNonEmptyString(rr.artifactPath)
+                        ? rr.artifactPath.trim()
+                        : null;
+                return { text: rr.text.trim(), artifact_path: path };
+            })
+                .filter((r) => r !== null)
+            : [];
+        const ambiguous = row.ambiguous === true || readings.length > 1;
+        const chosen = typeof row.chosen_reading === "number"
+            ? row.chosen_reading
+            : typeof row.chosenReading === "number"
+                ? row.chosenReading
+                : 0;
+        const chosenPath = ambiguous && readings[chosen] !== undefined ? readings[chosen].artifact_path : artifact;
+        out.push({
+            id: typeof row.id === "number" && row.id > 0 ? row.id : index + 1,
+            text,
+            artifact_path: chosenPath,
+            ambiguous,
+            ...(readings.length > 0 ? { readings, chosen_reading: chosen } : {}),
+        });
+    }
+    return out;
+}
+export function serializeAcceptanceClauses(clauses) {
+    return clauses.map((clause) => {
+        const row = {
+            id: clause.id,
+            text: clause.text,
+            artifact_path: clause.artifact_path,
+            ambiguous: clause.ambiguous,
+        };
+        if (clause.ambiguous && clause.readings !== undefined) {
+            row.readings = clause.readings.map((reading) => ({
+                text: reading.text,
+                artifact_path: reading.artifact_path,
+            }));
+            row.chosen_reading = clause.chosen_reading ?? 0;
+        }
+        return row;
+    });
+}
+/**
+ * When no commands are stated, stamp derived clauses onto plan.acceptance
+ * and promote source_rung to derived. Leaves stated-command acceptance alone.
+ */
+export function stampDerivedClausesOnAcceptance(plan, taskStatement) {
+    const rec = asRecord(plan.acceptance);
+    if (rec === null) {
+        return { plan, clauses: [] };
+    }
+    if (rec.none_stated !== true) {
+        return { plan, clauses: [] };
+    }
+    const commands = rec.commands;
+    if (Array.isArray(commands) && commands.length > 0) {
+        return { plan, clauses: [] };
+    }
+    const clauses = deriveAcceptanceClauses(taskStatement);
+    if (clauses.length === 0) {
+        return { plan, clauses: [] };
+    }
+    return {
+        plan: {
+            ...plan,
+            acceptance: {
+                ...rec,
+                none_stated: true,
+                source_rung: "derived",
+                derived_reason: `derived ${clauses.length} independently testable clauses from the task statement before product edit (#3323)`,
+                clauses: serializeAcceptanceClauses(clauses),
+            },
+        },
+        clauses,
+    };
+}
+export function isScratchArtifactPath(artifactPath) {
+    const unified = artifactPath.replace(/\\/g, "/").toLowerCase();
+    return unified.split("/").some((seg) => SCRATCH_SEGMENTS.has(seg));
+}
+function isContained(root, child) {
+    const rel = relative(resolve(root), resolve(child));
+    return rel === "" || (!rel.startsWith("..") && !isAbsolute(rel));
+}
+function extractExpectedTokens(clause) {
+    const tokens = [];
+    const seen = new Set();
+    const quoted = /["']([^"'\n]{3,80})["']/g;
+    let match = quoted.exec(clause.text);
+    while (match !== null) {
+        const token = (match[1] ?? "").trim();
+        const skip = token.length === 0 ||
+            token === clause.artifact_path ||
+            looksLikeFilePath(token) ||
+            seen.has(token);
+        if (!skip) {
+            seen.add(token);
+            tokens.push(token);
+        }
+        match = quoted.exec(clause.text);
+    }
+    return tokens;
+}
+function walkOne(clause, projectRoot) {
+    const artifactPath = clause.artifact_path;
+    if (artifactPath === null || artifactPath.trim().length === 0) {
+        return {
+            id: clause.id,
+            text: clause.text,
+            artifact_path: artifactPath,
+            outcome: "unverifiable",
+            detail: "no artifact path bound",
+        };
+    }
+    if (isScratchArtifactPath(artifactPath)) {
+        return {
+            id: clause.id,
+            text: clause.text,
+            artifact_path: artifactPath,
+            outcome: "failed",
+            detail: "artifact path is a buffer/scratch copy, not the shipped path",
+        };
+    }
+    const abs = resolve(projectRoot, artifactPath);
+    if (!isContained(projectRoot, abs)) {
+        return {
+            id: clause.id,
+            text: clause.text,
+            artifact_path: artifactPath,
+            outcome: "failed",
+            detail: "artifact path escaped the project root",
+        };
+    }
+    if (!existsSync(abs)) {
+        if (NEGATED_EXISTENCE.test(clause.text)) {
+            return {
+                id: clause.id,
+                text: clause.text,
+                artifact_path: artifactPath,
+                outcome: "verified",
+                detail: `artifact correctly absent at ${artifactPath}`,
+            };
+        }
+        return {
+            id: clause.id,
+            text: clause.text,
+            artifact_path: artifactPath,
+            outcome: "failed",
+            detail: `artifact missing at stated path ${artifactPath}`,
+        };
+    }
+    try {
+        if (!statSync(abs).isFile()) {
+            return {
+                id: clause.id,
+                text: clause.text,
+                artifact_path: artifactPath,
+                outcome: "failed",
+                detail: `stated path is not a shipped file: ${artifactPath}`,
+            };
+        }
+    }
+    catch {
+        return {
+            id: clause.id,
+            text: clause.text,
+            artifact_path: artifactPath,
+            outcome: "failed",
+            detail: `artifact unreadable at stated path ${artifactPath}`,
+        };
+    }
+    if (NEGATED_EXISTENCE.test(clause.text)) {
+        return {
+            id: clause.id,
+            text: clause.text,
+            artifact_path: artifactPath,
+            outcome: "failed",
+            detail: `artifact exists at ${artifactPath} but the clause requires absence`,
+        };
+    }
+    const expected = extractExpectedTokens(clause);
+    if (expected.length > 0) {
+        let body = "";
+        try {
+            body = readFileSync(abs, "utf8");
+        }
+        catch {
+            return {
+                id: clause.id,
+                text: clause.text,
+                artifact_path: artifactPath,
+                outcome: "failed",
+                detail: `artifact unreadable at stated path ${artifactPath}`,
+            };
+        }
+        const missing = expected.filter((token) => !body.includes(token));
+        if (missing.length > 0) {
+            return {
+                id: clause.id,
+                text: clause.text,
+                artifact_path: artifactPath,
+                outcome: "failed",
+                detail: `expected token(s) missing from ${artifactPath}: ${missing.join(", ")}`,
+            };
+        }
+        return {
+            id: clause.id,
+            text: clause.text,
+            artifact_path: artifactPath,
+            outcome: "verified",
+            detail: `tokens present in shipped artifact ${artifactPath}`,
+        };
+    }
+    if (EXISTENCE_CLAIM.test(clause.text)) {
+        return {
+            id: clause.id,
+            text: clause.text,
+            artifact_path: artifactPath,
+            outcome: "verified",
+            detail: `shipped artifact exists at ${artifactPath}`,
+        };
+    }
+    return {
+        id: clause.id,
+        text: clause.text,
+        artifact_path: artifactPath,
+        outcome: "unverifiable",
+        detail: `cannot evaluate behavioral claim against shipped artifact ${artifactPath}`,
+    };
+}
+export function walkAcceptanceClauses(clauses, projectRoot) {
+    const walked = clauses.map((clause) => walkOne(clause, projectRoot));
+    const failed = walked.filter((row) => row.outcome === "failed");
+    const unverifiable = walked.filter((row) => row.outcome === "unverifiable");
+    const verified = walked.filter((row) => row.outcome === "verified");
+    const ok = failed.length === 0 && (verified.length > 0 || walked.length === 0);
+    return {
+        clauses: walked,
+        failed,
+        unverifiable,
+        verified,
+        ok,
+        message: formatClauseWalkMessage({
+            clauses: walked,
+            failed,
+            unverifiable,
+            verified,
+            ok,
+            message: "",
+        }),
+    };
+}
+function formatOne(row) {
+    const path = row.artifact_path ?? "(no path)";
+    return `  [${row.outcome}] clause ${row.id} @ ${path}: ${row.text} — ${row.detail}`;
+}
+/** Done reports lead with failed/unverifiable; unverifiable is never dropped. */
+export function formatClauseWalkMessage(report, prior) {
+    const lead = [...report.failed, ...report.unverifiable];
+    const rest = report.verified;
+    const lines = [
+        `verify:ac clause walk (#3323): ${report.verified.length} verified, ` +
+            `${report.unverifiable.length} unverifiable, ${report.failed.length} failed`,
+        ...lead.map(formatOne),
+        ...rest.map(formatOne),
+    ];
+    const body = lines.join("\n");
+    if (prior !== undefined && prior.trim().length > 0) {
+        return `${body}\n${prior}`;
+    }
+    return body;
+}
+//# sourceMappingURL=clauses.js.map

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

@@ -0,0 +1,55 @@
+/**
+ * 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;
+}
+/** 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.
+ */
+export declare function emitVerifyAcAttempts(options: {
+    readonly projectRoot: string;
+    readonly runs: readonly LiteralAcceptanceRunResult[];
+    readonly env?: NodeJS.ProcessEnv;
+    readonly sessionId?: string;
+    /** 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