@deftai/directive-core 0.55.0

package/dist/orchestration/verify-investigation.js

@@ -0,0 +1,314 @@
+/**
+ * Deterministic validator for forensic investigation ledgers (#1621).
+ * Port of scripts/verify_investigation.py.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { resolve } from "node:path";
+export const REQUIRED_WAVES = ["1", "2", "3", "4"];
+export class LedgerConfigError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "LedgerConfigError";
+    }
+}
+export function validationOk(result) {
+    return result.hard_failures.length === 0;
+}
+function iterClaims(items) {
+    const out = [];
+    function walk(node, branch) {
+        const children = node.items;
+        if (!Array.isArray(children)) {
+            return;
+        }
+        for (const child of children) {
+            if (typeof child !== "object" || child === null || Array.isArray(child)) {
+                continue;
+            }
+            out.push([child, branch]);
+            walk(child, branch);
+        }
+    }
+    for (const top of items) {
+        if (typeof top !== "object" || top === null || Array.isArray(top)) {
+            continue;
+        }
+        walk(top, top);
+    }
+    return out;
+}
+function claimMeta(claim) {
+    const meta = claim.metadata;
+    if (typeof meta !== "object" || meta === null || Array.isArray(meta)) {
+        return {};
+    }
+    const xclaim = meta["x-claim"];
+    if (typeof xclaim === "object" && xclaim !== null && !Array.isArray(xclaim)) {
+        return xclaim;
+    }
+    return {};
+}
+function evidenceRefs(xclaim) {
+    const refs = xclaim.evidenceRefs;
+    if (!Array.isArray(refs)) {
+        return [];
+    }
+    return refs.map((r) => String(r));
+}
+/** Load + structurally validate a ledger file. */
+export function loadLedger(path) {
+    if (!existsSync(path)) {
+        throw new LedgerConfigError(`ledger not found: ${path}`);
+    }
+    let raw;
+    try {
+        raw = readFileSync(path, "utf8");
+    }
+    catch (exc) {
+        throw new LedgerConfigError(`ledger unreadable: ${path}: ${String(exc.message ?? exc)}`);
+    }
+    let data;
+    try {
+        data = JSON.parse(raw);
+    }
+    catch (exc) {
+        throw new LedgerConfigError(`ledger is not valid JSON: ${path}: ${String(exc)}`);
+    }
+    if (typeof data !== "object" || data === null || Array.isArray(data)) {
+        throw new LedgerConfigError(`ledger root is not an object: ${path}`);
+    }
+    const obj = data;
+    const plan = obj.plan;
+    if (typeof plan !== "object" || plan === null || Array.isArray(plan)) {
+        throw new LedgerConfigError(`ledger missing 'plan' object: ${path}`);
+    }
+    const planObj = plan;
+    if (!Array.isArray(planObj.items)) {
+        throw new LedgerConfigError(`ledger missing 'plan.items' array: ${path}`);
+    }
+    const meta = planObj.metadata;
+    const xinv = typeof meta === "object" && meta !== null && !Array.isArray(meta)
+        ? meta["x-investigation"]
+        : null;
+    const profile = typeof xinv === "object" && xinv !== null && !Array.isArray(xinv)
+        ? xinv.profile
+        : null;
+    if (profile !== "forensic-research-v1") {
+        throw new LedgerConfigError(`ledger is not a forensic-research-v1 profile (got ${JSON.stringify(profile)}): ${path}`);
+    }
+    return obj;
+}
+/** Apply validator checklist to loaded ledger dict. */
+export function validateLedger(data) {
+    const result = { hard_failures: [], soft_warnings: [] };
+    const plan = data.plan;
+    const items = plan.items;
+    const meta = plan.metadata;
+    const xinv = typeof meta === "object" && meta !== null && !Array.isArray(meta)
+        ? meta["x-investigation"]
+        : {};
+    let waves = xinv.wavesCompleted;
+    if (typeof waves !== "object" || waves === null || Array.isArray(waves)) {
+        waves = {};
+    }
+    const wavesObj = waves;
+    const missing = REQUIRED_WAVES.filter((w) => wavesObj[w] !== true);
+    if (missing.length > 0) {
+        result.hard_failures.push({
+            code: "HF-WAVES",
+            message: `wavesCompleted is missing ${missing.join(", ")} -- falsifier (3) + red-team (4) MUST run before close`,
+        });
+    }
+    if (plan.status === "running") {
+        result.hard_failures.push({
+            code: "HF-STATUS",
+            message: "plan.status is still 'running' -- set it to completed/failed before close",
+        });
+    }
+    const refIds = new Set();
+    const references = plan.references;
+    if (Array.isArray(references)) {
+        for (const ref of references) {
+            if (typeof ref === "object" && ref !== null && !Array.isArray(ref)) {
+                const val = ref.id;
+                if (typeof val === "string") {
+                    refIds.add(val);
+                }
+            }
+        }
+    }
+    const claims = iterClaims(items);
+    for (const [claim] of claims) {
+        const cid = typeof claim.id === "string" ? claim.id : "<no-id>";
+        const cstatus = claim.status;
+        const isBranch = Array.isArray(claim.items) && claim.items.length > 0;
+        if (isBranch) {
+            continue;
+        }
+        const xclaim = claimMeta(claim);
+        const refs = evidenceRefs(xclaim);
+        if (cstatus === "failed") {
+            if (!xclaim.ruledOutReason || refs.length === 0) {
+                result.hard_failures.push({
+                    code: "HF-FAILED-CLAIM",
+                    message: `claim ${cid} is 'failed' but missing ruledOutReason and/or evidenceRefs (proof-required disproval)`,
+                });
+            }
+        }
+        else if (cstatus === "completed") {
+            if (refs.length === 0) {
+                result.hard_failures.push({
+                    code: "HF-COMPLETED-CLAIM",
+                    message: `claim ${cid} is 'completed' but cites no evidenceRefs (evidence before narrative)`,
+                });
+            }
+        }
+        else if (cstatus === "blocked") {
+            result.soft_warnings.push({
+                code: "SW-BLOCKED",
+                message: `claim ${cid} is 'blocked' (unknown) -- residual uncertainty on a live branch`,
+            });
+        }
+        for (const ref of refs) {
+            if (!refIds.has(ref)) {
+                result.hard_failures.push({
+                    code: "HF-DANGLING-EV",
+                    message: `claim ${cid} cites evidence ref ${JSON.stringify(ref)} not present in plan.references`,
+                });
+            }
+        }
+    }
+    const invalidatesTargets = new Set();
+    const edges = plan.edges;
+    if (Array.isArray(edges)) {
+        for (const edge of edges) {
+            if (typeof edge === "object" && edge !== null && !Array.isArray(edge)) {
+                const e = edge;
+                if (e.type === "invalidates" && typeof e.to === "string") {
+                    invalidatesTargets.add(e.to);
+                }
+            }
+        }
+    }
+    let completedBranches = 0;
+    for (const top of items) {
+        if (typeof top !== "object" || top === null || Array.isArray(top)) {
+            continue;
+        }
+        const branch = top;
+        const bid = typeof branch.id === "string" ? branch.id : "<no-id>";
+        const bstatus = branch.status;
+        if (bstatus === "failed" && !invalidatesTargets.has(bid)) {
+            result.hard_failures.push({
+                code: "HF-BRANCH-NO-EDGE",
+                message: `branch ${bid} is 'failed' but has no invalidates edge -- a branch is ruled out only by a falsified child claim`,
+            });
+        }
+        if (bstatus === "completed") {
+            completedBranches += 1;
+        }
+    }
+    if (completedBranches > 1) {
+        result.soft_warnings.push({
+            code: "SW-MULTI-SURVIVOR",
+            message: `${completedBranches} branches are 'completed' -- multiple surviving theories; note in Outcome`,
+        });
+    }
+    return result;
+}
+export function parseVerifyInvestigationArgs(argv) {
+    const parsed = {
+        ledger: null,
+        projectRoot: ".",
+        emitJson: false,
+    };
+    const positional = [];
+    for (let i = 0; i < argv.length; i += 1) {
+        const arg = argv[i];
+        if (arg === "--json") {
+            parsed.emitJson = true;
+        }
+        else if (arg === "--ledger") {
+            parsed.ledger = argv[i + 1] ?? null;
+            i += 1;
+        }
+        else if (arg?.startsWith("--ledger=")) {
+            parsed.ledger = arg.slice("--ledger=".length);
+        }
+        else if (arg === "--project-root") {
+            parsed.projectRoot = argv[i + 1] ?? ".";
+            i += 1;
+        }
+        else if (arg?.startsWith("--project-root=")) {
+            parsed.projectRoot = arg.slice("--project-root=".length);
+        }
+        else if (arg === "--help" || arg === "-h") {
+            return parsed;
+        }
+        else if (arg?.startsWith("-")) {
+            return { ...parsed, error: `unrecognized argument: ${arg}` };
+        }
+        else if (arg !== undefined) {
+            positional.push(arg);
+        }
+    }
+    if (parsed.ledger === null && positional.length > 0) {
+        parsed.ledger = positional[0] ?? null;
+    }
+    return parsed;
+}
+/** Run verify-investigation CLI; returns exit code. */
+export function cmdVerifyInvestigation(argv) {
+    const args = parseVerifyInvestigationArgs(argv);
+    if (args.error !== undefined) {
+        process.stderr.write(`config error: ${args.error}\n`);
+        return 2;
+    }
+    if (args.ledger === null || args.ledger.length === 0) {
+        process.stderr.write("config error: no ledger path given (--ledger <path>)\n");
+        return 2;
+    }
+    let path = args.ledger;
+    if (!path.startsWith("/")) {
+        path = resolve(args.projectRoot, path);
+    }
+    else {
+        path = resolve(path);
+    }
+    let data;
+    try {
+        data = loadLedger(path);
+    }
+    catch (exc) {
+        const msg = exc instanceof LedgerConfigError ? exc.message : String(exc);
+        if (args.emitJson) {
+            process.stdout.write(`${JSON.stringify({ exit: 2, error: msg })}\n`);
+        }
+        else {
+            process.stderr.write(`config error: ${msg}\n`);
+        }
+        return 2;
+    }
+    const result = validateLedger(data);
+    if (args.emitJson) {
+        process.stdout.write(`${JSON.stringify({
+            exit: validationOk(result) ? 0 : 1,
+            hard_failures: result.hard_failures.map((f) => ({ code: f.code, message: f.message })),
+            soft_warnings: result.soft_warnings.map((f) => ({ code: f.code, message: f.message })),
+        })}\n`);
+        return validationOk(result) ? 0 : 1;
+    }
+    for (const warn of result.soft_warnings) {
+        process.stdout.write(`warning [${warn.code}]: ${warn.message}\n`);
+    }
+    if (validationOk(result)) {
+        process.stdout.write(`OK investigation ledger passes the validator: ${path} (${result.soft_warnings.length} soft warning(s))\n`);
+        return 0;
+    }
+    process.stderr.write(`investigation ledger NOT close-ready: ${path}\n`);
+    for (const fail of result.hard_failures) {
+        process.stderr.write(`  hard failure [${fail.code}]: ${fail.message}\n`);
+    }
+    return 1;
+}
+//# sourceMappingURL=verify-investigation.js.map

package/dist/orchestration/verify-judgment-gates.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Risk-tiered judgment-gate engine (#1419 Slice 3). Port of scripts/verify_judgment_gates.py.
+ */
+import { type JudgmentGatesPolicy } from "./judgment-policy.js";
+export declare const AUDIT_DIR_REL = "vbrief/.audit";
+export declare const CLEARANCE_LOG_NAME = "judgment-gate-clearances.jsonl";
+export declare const UNIVERSAL_SOURCE = "universal";
+export declare const CONSUMER_SOURCE = "consumer";
+export declare const UNIVERSAL_GATES: readonly Record<string, unknown>[];
+export interface Candidate {
+    readonly paths: readonly string[];
+    readonly labels: readonly string[];
+    readonly body: string;
+    readonly state: string;
+    readonly updated_at: string | null;
+}
+export interface GateOutcome {
+    readonly gate_id: string;
+    readonly gate_class: string;
+    readonly tier: string;
+    readonly reason: string;
+    readonly required_human_reviewers: number;
+    readonly source: string;
+    readonly matched_paths: readonly string[];
+    readonly matched_labels: readonly string[];
+    readonly cleared_scope: string;
+    readonly clearance: Record<string, unknown> | null;
+    readonly stale_clearance: Record<string, unknown> | null;
+}
+export declare function outcomeCleared(o: GateOutcome): boolean;
+export declare function outcomeFired(o: GateOutcome): boolean;
+export declare function outcomeBlocking(o: GateOutcome): boolean;
+export interface JudgmentGateReport {
+    readonly posture: string;
+    readonly outcomes: readonly GateOutcome[];
+    readonly policy_error: string | null;
+}
+export declare function reportFired(report: JudgmentGateReport): GateOutcome[];
+export declare function reportBlocking(report: JudgmentGateReport): GateOutcome[];
+export declare function clearanceLogPath(projectRoot: string): string;
+export declare function readClearances(projectRoot: string, logPath?: string): Record<string, unknown>[];
+export declare function recordClearance(projectRoot: string, options: {
+    gate_id: string;
+    cleared_scope: string;
+    reviewers?: string[];
+    actor?: string;
+    reason?: string;
+    now?: Date;
+    log_path?: string;
+}): Record<string, unknown>;
+export declare function fingerprintScope(evidence: Record<string, unknown>): string;
+export declare function effectiveGates(projectRoot: string, policy?: JudgmentGatesPolicy): Record<string, unknown>[];
+export declare function matchEvidence(match: Record<string, unknown>, candidate: Candidate, matchedPaths: readonly string[]): Record<string, unknown>;
+export declare function buildReport(projectRoot: string, candidate: Candidate, options?: {
+    posture?: string;
+    clearances?: Record<string, unknown>[] | null;
+    now?: Date;
+}): JudgmentGateReport;
+export declare function renderReport(report: JudgmentGateReport): string;
+export declare function evaluate(projectRoot: string, candidate?: Candidate | null, options?: {
+    posture?: string;
+    clearances?: Record<string, unknown>[] | null;
+    now?: Date;
+}): [number, string];
+export declare function cmdVerifyJudgmentGates(argv: string[]): number;
+//# sourceMappingURL=verify-judgment-gates.d.ts.map