@deftai/directive-core 0.70.0 → 0.71.1

package/dist/branch/evaluate.js

@@ -1,3 +1,4 @@
+import { recordBypassSignal, recordGateCatch } from "../events/attribution-ledger.js";
 import { disclosureLine } from "../policy/disclosure.js";
 import { ENV_BYPASS, resolvePolicy } from "../policy/resolve.js";
 import { currentBranch, GitNotFoundError } from "./git.js";
@@ -42,6 +43,7 @@ export function evaluate(projectRoot, options = {}) {
     const defaultBranches = options.defaultBranches ?? DEFAULT_BRANCHES;
     const allowMissingProjectDefinition = options.allowMissingProjectDefinition ?? false;
     if (setupExemptionActive()) {
+        recordBypassSignal(projectRoot, "verify:branch", `${ENV_SETUP_EXEMPTION}=1 setup-interview exemption`);
         return {
             exitCode: 0,
             message: "✓ deft branch-protection: setup-interview exemption active " +
@@ -97,6 +99,9 @@ export function evaluate(projectRoot, options = {}) {
     }
     const result = resolvePolicy(projectRoot);
     if (result.allowDirectCommits) {
+        if (result.source === "env-bypass") {
+            recordBypassSignal(projectRoot, "verify:branch", `${ENV_BYPASS}=1 on default branch '${branch}'`);
+        }
         return {
             exitCode: 0,
             message: `⚠ deft branch-protection: on default branch '${branch}', but ` +
@@ -105,6 +110,7 @@ export function evaluate(projectRoot, options = {}) {
     }
     if (result.source === "default-fail-closed" && result.error !== null) {
         if (allowMissingProjectDefinition && result.error.includes("not found")) {
+            recordBypassSignal(projectRoot, "verify:branch", "--allow-missing-project-definition bootstrap on default branch");
             return {
                 exitCode: 0,
                 message: "✓ deft branch-protection: PROJECT-DEFINITION missing AND " +
@@ -128,6 +134,7 @@ export function evaluate(projectRoot, options = {}) {
                 recovery,
         };
     }
+    recordGateCatch(projectRoot, "verify:branch", `blocked commit on default branch '${branch}'`);
     return {
         exitCode: 1,
         message: buildBlockMessage(branch, result),

package/dist/doctor/doctor-state.js

@@ -1,6 +1,6 @@
 import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
-import { resolveEvalPath } from "../layout/resolve.js";
+import { resolveTriageCachePath } from "../triage/cache-path.js";
 import { CLEAN_WINDOW_HOURS, DIRTY_WINDOW_HOURS, ENV_STATE_PATH } from "./constants.js";
 const STATE_FILENAME = "doctor-state.json";
 export function statePath(projectRoot) {
@@ -10,7 +10,7 @@ export function statePath(projectRoot) {
             ? join(process.env.HOME ?? projectRoot, override.slice(1))
             : override;
     }
-    return resolveEvalPath(projectRoot, STATE_FILENAME);
+    return resolveTriageCachePath(projectRoot, STATE_FILENAME);
 }
 function parseIso(ts) {
     if (typeof ts !== "string" || !ts) {

package/dist/eval/crud-telemetry.d.ts

@@ -0,0 +1,59 @@
+export declare const CRUD_METRICS_HISTORY_REL = "results/crud-metrics.jsonl";
+export type CrudOperation = "create" | "read" | "update" | "delete";
+export type ByteDiffMinimality = "surgical" | "whole-file-rewrite";
+export interface CrudOperationMetric {
+    readonly directiveVersion: string;
+    readonly operation: CrudOperation;
+    readonly path: string;
+    readonly schemaValid: boolean;
+    readonly schemaErrors: readonly string[];
+    readonly fieldInventionCount: number;
+    readonly inventedKeys: readonly string[];
+    readonly byteDiffMinimality: ByteDiffMinimality | null;
+    readonly byteDiffChangedRatio: number | null;
+    readonly recordedAt: string;
+}
+export interface CrudResult {
+    readonly ok: boolean;
+    readonly content?: string;
+    readonly error?: string;
+}
+export interface InstrumentedVbriefCrudOptions {
+    readonly directiveVersion?: string;
+    readonly now?: () => Date;
+}
+/** Whole-file rewrites change at least half of the bytes or re-serialize with high drift. */
+export declare const BYTE_DIFF_WHOLE_FILE_THRESHOLD = 0.5;
+/** Ratio of edit distance to the longer string length. */
+export declare function computeChangedByteRatio(before: string, after: string): number;
+/** Classify whether an update preserved bytes (surgical) or rewrote the file. */
+export declare function classifyByteDiffMinimality(before: string, after: string): {
+    readonly kind: ByteDiffMinimality;
+    readonly changedRatio: number;
+};
+/** Absolute path to the versioned CRUD metrics ledger (#1703 Tier 1). */
+export declare function crudMetricsHistoryPath(projectRoot: string): string;
+/** Append CRUD operation metrics to the versioned ledger (#1703 Tier 1). */
+export declare function persistCrudMetrics(projectRoot: string, metrics: readonly CrudOperationMetric[]): void;
+/**
+ * Instrumented vBRIEF/xBRIEF CRUD chokepoint (#1703 Tier 1).
+ * Every operation emits a version-tagged metric covering schema validity,
+ * field invention, and (for updates) byte-diff minimality.
+ * Delete intentionally succeeds on schema-invalid files so corrupt artifacts can be removed.
+ */
+export declare class InstrumentedVbriefCrud {
+    private readonly directiveVersion;
+    private readonly now;
+    private readonly metrics;
+    constructor(options?: InstrumentedVbriefCrudOptions);
+    getMetrics(): readonly CrudOperationMetric[];
+    clearMetrics(): void;
+    create(path: string, content: string): CrudResult;
+    read(path: string): CrudResult;
+    update(path: string, content: string, options?: {
+        trustedWrite?: boolean;
+    }): CrudResult;
+    delete(path: string): CrudResult;
+    private recordMetric;
+}
+//# sourceMappingURL=crud-telemetry.d.ts.map

package/dist/eval/crud-telemetry.js

@@ -0,0 +1,307 @@
+import { appendFileSync, existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync, } from "node:fs";
+import { dirname } from "node:path";
+import { readCorePackageVersion } from "../engine-version.js";
+import { resolveEvalPath } from "../layout/resolve.js";
+import { scanVbrief } from "../vbrief-validate/conformance.js";
+import { validateVbriefSchema } from "../vbrief-validate/schema.js";
+export const CRUD_METRICS_HISTORY_REL = "results/crud-metrics.jsonl";
+/** Whole-file rewrites change at least half of the bytes or re-serialize with high drift. */
+export const BYTE_DIFF_WHOLE_FILE_THRESHOLD = 0.5;
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** Edit distance between two UTF-8 strings (Levenshtein, two-row). */
+function levenshteinDistance(before, after) {
+    if (before === after) {
+        return 0;
+    }
+    if (before.length === 0) {
+        return after.length;
+    }
+    if (after.length === 0) {
+        return before.length;
+    }
+    let prev = Array.from({ length: after.length + 1 }, (_, index) => index);
+    let curr = new Array(after.length + 1).fill(0);
+    for (let row = 1; row <= before.length; row += 1) {
+        curr[0] = row;
+        for (let col = 1; col <= after.length; col += 1) {
+            const cost = before[row - 1] === after[col - 1] ? 0 : 1;
+            const up = prev[col] ?? 0;
+            const left = curr[col - 1] ?? 0;
+            const diag = prev[col - 1] ?? 0;
+            curr[col] = Math.min(up + 1, left + 1, diag + cost);
+        }
+        [prev, curr] = [curr, prev];
+    }
+    return prev[after.length] ?? 0;
+}
+/** Ratio of edit distance to the longer string length. */
+export function computeChangedByteRatio(before, after) {
+    const maxLen = Math.max(before.length, after.length);
+    if (maxLen === 0) {
+        return 0;
+    }
+    return levenshteinDistance(before, after) / maxLen;
+}
+/** Classify whether an update preserved bytes (surgical) or rewrote the file. */
+export function classifyByteDiffMinimality(before, after) {
+    const changedRatio = computeChangedByteRatio(before, after);
+    try {
+        const oldParsed = JSON.parse(before);
+        const newParsed = JSON.parse(after);
+        if (JSON.stringify(oldParsed) === JSON.stringify(newParsed) && changedRatio > 0) {
+            return { kind: "whole-file-rewrite", changedRatio };
+        }
+    }
+    catch {
+        // Fall through to byte-ratio classification.
+    }
+    if (changedRatio >= BYTE_DIFF_WHOLE_FILE_THRESHOLD) {
+        return { kind: "whole-file-rewrite", changedRatio };
+    }
+    return { kind: "surgical", changedRatio };
+}
+function assessDocument(path, parsed) {
+    if (!isRecord(parsed)) {
+        return {
+            schemaValid: false,
+            schemaErrors: [`${path}: document must be a JSON object`],
+            inventedKeys: [],
+        };
+    }
+    const schemaErrors = validateVbriefSchema(parsed, path);
+    const findings = scanVbrief(path, parsed);
+    const inventedKeys = findings.map((finding) => finding.key);
+    return {
+        schemaValid: schemaErrors.length === 0,
+        schemaErrors,
+        inventedKeys,
+    };
+}
+function sanitizeInlineMessage(message) {
+    return message.replace(/\r?\n/g, " ");
+}
+function ensureParentDir(path) {
+    mkdirSync(dirname(path), { recursive: true });
+}
+/** Absolute path to the versioned CRUD metrics ledger (#1703 Tier 1). */
+export function crudMetricsHistoryPath(projectRoot) {
+    return resolveEvalPath(projectRoot, CRUD_METRICS_HISTORY_REL);
+}
+/** Append CRUD operation metrics to the versioned ledger (#1703 Tier 1). */
+export function persistCrudMetrics(projectRoot, metrics) {
+    if (metrics.length === 0) {
+        return;
+    }
+    const path = crudMetricsHistoryPath(projectRoot);
+    mkdirSync(dirname(path), { recursive: true });
+    for (const metric of metrics) {
+        appendFileSync(path, `${JSON.stringify(metric)}\n`, "utf8");
+    }
+}
+/**
+ * Instrumented vBRIEF/xBRIEF CRUD chokepoint (#1703 Tier 1).
+ * Every operation emits a version-tagged metric covering schema validity,
+ * field invention, and (for updates) byte-diff minimality.
+ * Delete intentionally succeeds on schema-invalid files so corrupt artifacts can be removed.
+ */
+export class InstrumentedVbriefCrud {
+    directiveVersion;
+    now;
+    metrics = [];
+    constructor(options = {}) {
+        this.directiveVersion = options.directiveVersion ?? readCorePackageVersion();
+        this.now = options.now ?? (() => new Date());
+    }
+    getMetrics() {
+        return this.metrics;
+    }
+    clearMetrics() {
+        this.metrics.length = 0;
+    }
+    create(path, content) {
+        let parsed;
+        try {
+            parsed = JSON.parse(content);
+        }
+        catch (err) {
+            const message = sanitizeInlineMessage(err instanceof Error ? err.message : String(err));
+            this.recordMetric({
+                operation: "create",
+                path,
+                schemaValid: false,
+                schemaErrors: [`${path}: invalid JSON -- ${message}`],
+                inventedKeys: [],
+                byteDiffMinimality: null,
+                byteDiffChangedRatio: null,
+            });
+            return { ok: false, error: message };
+        }
+        const assessment = assessDocument(path, parsed);
+        this.recordMetric({
+            operation: "create",
+            path,
+            schemaValid: assessment.schemaValid,
+            schemaErrors: assessment.schemaErrors,
+            inventedKeys: assessment.inventedKeys,
+            byteDiffMinimality: null,
+            byteDiffChangedRatio: null,
+        });
+        if (!assessment.schemaValid) {
+            return { ok: false, error: assessment.schemaErrors.join("; ") };
+        }
+        ensureParentDir(path);
+        writeFileSync(path, content, "utf8");
+        return { ok: true };
+    }
+    read(path) {
+        if (!existsSync(path)) {
+            this.recordMetric({
+                operation: "read",
+                path,
+                schemaValid: false,
+                schemaErrors: [`${path}: file not found`],
+                inventedKeys: [],
+                byteDiffMinimality: null,
+                byteDiffChangedRatio: null,
+            });
+            return { ok: false, error: "ENOENT" };
+        }
+        const content = readFileSync(path, "utf8");
+        let parsed;
+        try {
+            parsed = JSON.parse(content);
+        }
+        catch (err) {
+            const message = sanitizeInlineMessage(err instanceof Error ? err.message : String(err));
+            this.recordMetric({
+                operation: "read",
+                path,
+                schemaValid: false,
+                schemaErrors: [`${path}: invalid JSON -- ${message}`],
+                inventedKeys: [],
+                byteDiffMinimality: null,
+                byteDiffChangedRatio: null,
+            });
+            return { ok: false, error: message };
+        }
+        const assessment = assessDocument(path, parsed);
+        this.recordMetric({
+            operation: "read",
+            path,
+            schemaValid: assessment.schemaValid,
+            schemaErrors: assessment.schemaErrors,
+            inventedKeys: assessment.inventedKeys,
+            byteDiffMinimality: null,
+            byteDiffChangedRatio: null,
+        });
+        if (!assessment.schemaValid) {
+            return { ok: false, error: assessment.schemaErrors.join("; ") };
+        }
+        return { ok: true, content };
+    }
+    update(path, content, options = {}) {
+        const previousBytes = options.trustedWrite || !existsSync(path) ? null : readFileSync(path, "utf8");
+        let parsed;
+        try {
+            parsed = JSON.parse(content);
+        }
+        catch (err) {
+            const message = sanitizeInlineMessage(err instanceof Error ? err.message : String(err));
+            this.recordMetric({
+                operation: "update",
+                path,
+                schemaValid: false,
+                schemaErrors: [`${path}: invalid JSON -- ${message}`],
+                inventedKeys: [],
+                byteDiffMinimality: null,
+                byteDiffChangedRatio: null,
+            });
+            return { ok: false, error: message };
+        }
+        const assessment = assessDocument(path, parsed);
+        let byteDiffMinimality = null;
+        let byteDiffChangedRatio = null;
+        if (previousBytes !== null) {
+            const diff = classifyByteDiffMinimality(previousBytes, content);
+            byteDiffMinimality = diff.kind;
+            byteDiffChangedRatio = diff.changedRatio;
+        }
+        this.recordMetric({
+            operation: "update",
+            path,
+            schemaValid: assessment.schemaValid,
+            schemaErrors: assessment.schemaErrors,
+            inventedKeys: assessment.inventedKeys,
+            byteDiffMinimality,
+            byteDiffChangedRatio,
+        });
+        if (!assessment.schemaValid && !options.trustedWrite) {
+            return { ok: false, error: assessment.schemaErrors.join("; ") };
+        }
+        ensureParentDir(path);
+        writeFileSync(path, content, "utf8");
+        return { ok: true };
+    }
+    delete(path) {
+        if (!existsSync(path)) {
+            this.recordMetric({
+                operation: "delete",
+                path,
+                schemaValid: false,
+                schemaErrors: [`${path}: file not found`],
+                inventedKeys: [],
+                byteDiffMinimality: null,
+                byteDiffChangedRatio: null,
+            });
+            return { ok: false, error: "ENOENT" };
+        }
+        const content = readFileSync(path, "utf8");
+        let parsed;
+        try {
+            parsed = JSON.parse(content);
+        }
+        catch (err) {
+            const message = sanitizeInlineMessage(err instanceof Error ? err.message : String(err));
+            this.recordMetric({
+                operation: "delete",
+                path,
+                schemaValid: false,
+                schemaErrors: [`${path}: invalid JSON -- ${message}`],
+                inventedKeys: [],
+                byteDiffMinimality: null,
+                byteDiffChangedRatio: null,
+            });
+            unlinkSync(path);
+            return { ok: true };
+        }
+        const assessment = assessDocument(path, parsed);
+        this.recordMetric({
+            operation: "delete",
+            path,
+            schemaValid: assessment.schemaValid,
+            schemaErrors: assessment.schemaErrors,
+            inventedKeys: assessment.inventedKeys,
+            byteDiffMinimality: null,
+            byteDiffChangedRatio: null,
+        });
+        unlinkSync(path);
+        return { ok: true };
+    }
+    recordMetric(input) {
+        this.metrics.push({
+            directiveVersion: this.directiveVersion,
+            operation: input.operation,
+            path: input.path,
+            schemaValid: input.schemaValid,
+            schemaErrors: input.schemaErrors,
+            fieldInventionCount: input.inventedKeys.length,
+            inventedKeys: input.inventedKeys,
+            byteDiffMinimality: input.byteDiffMinimality,
+            byteDiffChangedRatio: input.byteDiffChangedRatio,
+            recordedAt: this.now().toISOString(),
+        });
+    }
+}
+//# sourceMappingURL=crud-telemetry.js.map

package/dist/eval/health.d.ts

@@ -0,0 +1,52 @@
+export declare const HEALTH_SCHEMA_VERSION: 1;
+export declare const HEALTH_HISTORY_REL = "results/health-history.jsonl";
+/** One static Tier-0 gate probe aggregated into the health score. */
+export interface GateProbeResult {
+    readonly id: string;
+    readonly title: string;
+    readonly pass: boolean;
+    readonly exitCode: number;
+    readonly detail?: string;
+    readonly skipped?: boolean;
+    readonly skipReason?: string;
+}
+/** Evidence for a contradictory / unsatisfiable gate pair (#1694 class). */
+export interface ContradictionEvidence {
+    readonly id: string;
+    readonly kind: "unsatisfiable-nudge";
+    readonly summary: string;
+    readonly signals: readonly string[];
+}
+/** Versioned Tier-0 health run persisted for trending (#1703). */
+export interface HealthReport {
+    readonly schemaVersion: typeof HEALTH_SCHEMA_VERSION;
+    readonly version: string;
+    readonly recordedAt: string;
+    readonly score: number;
+    readonly gates: readonly GateProbeResult[];
+    readonly contradictions: readonly ContradictionEvidence[];
+}
+export interface EvaluateHealthOptions {
+    readonly projectRoot?: string;
+    readonly persist?: boolean;
+    readonly now?: () => Date;
+    readonly frameworkSource?: boolean;
+}
+export interface EvaluateHealthResult {
+    readonly code: 0 | 1 | 2;
+    readonly report: HealthReport | null;
+    readonly message: string;
+}
+/** Absolute path to the versioned health history ledger. */
+export declare function healthHistoryPath(projectRoot: string): string;
+/** Detect the canonical wipCap unsatisfiable-nudge contradiction (#1694). */
+export declare function detectWipCapUnsatisfiableNudge(projectRoot: string): ContradictionEvidence | null;
+/** Run all registered contradictory-gate detectors. */
+export declare function detectContradictoryGates(projectRoot: string): ContradictionEvidence[];
+/** Compute a 0-100 score from gate pass rate minus contradiction penalty. */
+export declare function computeHealthScore(gates: readonly GateProbeResult[], contradictions: readonly ContradictionEvidence[]): number;
+/** Append one health run to the versioned ledger (#1703 Tier 0). */
+export declare function persistHealthRun(projectRoot: string, report: HealthReport): void;
+/** Aggregate Tier-0 static gates into a versioned framework health score (#1703). */
+export declare function evaluateHealth(options?: EvaluateHealthOptions): EvaluateHealthResult;
+//# sourceMappingURL=health.d.ts.map