@deftai/directive-core 0.98.1 → 0.100.0

package/dist/doctor/main.js

@@ -1,22 +1,18 @@
 import { existsSync, readFileSync, statSync, writeFileSync } from "node:fs";
 import { join, resolve } from "node:path";
-import { VBRIEF_VERSION } from "@deftai/directive-types";
 import { evaluate as evaluateAgentsMdAdvisory } from "../agents-md-advisory/evaluate.js";
 import { evaluateConsumerGateIntegrity, formatConsumerGateIntegrityFailure, } from "../check/consumer-gate-integrity.js";
 import { contentRoot } from "../content-root.js";
-import { resolveProjectDefinitionPath } from "../layout/resolve.js";
 import { DEFT_DIRECTIVE_DISABLE_FLAG_NAME, DEFT_DIRECTIVE_DISABLE_STATUS, DEFT_DIRECTIVE_DISABLE_TRACKED_WARNING, detectDeftDirectiveDisable, formatDeftDirectiveDisableMessage, isDeftDirectiveDisableActive, } from "../policy/deft-directive-disable.js";
 import { detectNoDeftDirective, NO_DEFT_DIRECTIVE_DISABLED_MESSAGE, NO_DEFT_DIRECTIVE_FLAG_NAME, NO_DEFT_DIRECTIVE_INCONSISTENT_MESSAGE, NO_DEFT_DIRECTIVE_INCONSISTENT_POLICY, } from "../policy/no-deft-directive.js";
 import { describeShadowedPlanExtension, detectShadowedPlanExtensions, } from "../policy/plan-extensions.js";
 import { loadProjectDefinition } from "../policy/resolve.js";
 import { checkLocalEngineIntegrity, classify, detectPackageManager, evaluateSkew, reconcileVersions, plan as resolvePlan, } from "../resolution/index.js";
-import { classifyXbriefSchemaDistance } from "../staleness-tickler/probe-xbrief.js";
 import { resolveUserMdPath } from "../user-config/resolve-user-md.js";
 import { evaluateAgentHooks } from "../verify-env/agent-hooks.js";
 import { probeAgentHooksLive } from "../verify-env/agent-hooks-live-probe.js";
-import { readDeclaredArtifactVersion } from "../xbrief-migrate/transforms.js";
 import { agentsRefreshPlan, hasV3ManagedMarker } from "./agents-md.js";
-import { runChecks } from "./checks.js";
+import { checkXbriefEnvelopeMajorVersion, runChecks, XBRIEF_ENVELOPE_MAJOR_CHECK, XBRIEF_ENVELOPE_MIGRATE_COMMAND, } from "./checks.js";
 import { CONSUMER_FRAMEWORK_DIRS, EXPECTED_CONTENT_DIRS, EXPECTED_FRAMEWORK_DIRS, NETWORK_DISCLOSURE_LINE, PAYLOAD_STALENESS_OFFLINE_SKIP_MESSAGE, TASKFILE_INCLUDE_SNIPPET, UV_INSTALL_URL, } from "./constants.js";
 import { decideThrottle, formatIsoZ, readState, renderDoctorStatusLine, writeState, } from "./doctor-state.js";
 import { formatAllowedFlagsHint, formatUnknownFlagsError, parseDoctorFlags } from "./flags.js";
@@ -33,8 +29,6 @@ import { runLocalSignpostChecks } from "./signpost-checks.js";
 import { classifyTaskfileInclude, formatGatesSurfaceDualRemediation, formatMissingIncludeSnippet, GATES_SURFACE_DEFT_REMEDIATION, includesBlockHasDeftTaskfile, resolveConsumerTaskfile, } from "./taskfile.js";
 import { defaultWhich } from "./which.js";
 const DEFAULT_RESOLUTION_PLATFORMS = ["linux", "darwin", "win32"];
-/** Next-action command for project-envelope behind-major (#2971). */
-const XBRIEF_ENVELOPE_MIGRATE_COMMAND = "deft migrate:xbrief";
 /**
  * Read the `packageManager` field (Corepack) from a project package.json, or
  * null when absent/unreadable. Lets the doctor detect a pnpm project that has
@@ -653,6 +647,11 @@ function runInstallIntegrityChecks(projectRoot, sink, addFinding, seams) {
             const name = String(entry.name ?? "install-integrity");
             const status = String(entry.status ?? "");
             const detail = String(entry.detail ?? "");
+            // Authoritative envelope-major emission is runXbriefEnvelopeVersionCheck
+            // (runs for framework repo + consumers). Skip install-integrity duplicate.
+            if (name === XBRIEF_ENVELOPE_MAJOR_CHECK) {
+                continue;
+            }
             if (status === "pass") {
                 sink.success(`${name}: pass`);
                 continue;
@@ -954,105 +953,99 @@ function runTaskfileIncludeCheck(projectRoot, fixMode, jsonMode, sink, addFindin
     });
 }
 /**
- * Fail closed when PROJECT-DEFINITION under an xbrief/ layout still declares
- * envelope 0.6 while the framework schema is 0.8 (#2971). Greenfield (no
- * project definition yet) and current 0.8 envelopes pass. Unreadable paths
- * (test seams / permission) skip rather than false-positive fail. Behind-major
- * records `deft migrate:xbrief` as the next action — layout rename alone is not
- * enough. Distinct from deposited-schema (`stale-xbrief-schema-deposit`) which
- * must NOT route to migrate:xbrief when only framework schema files are stale.
+ * Fail closed when any scanned project xbrief lifecycle `*.xbrief.json` envelope
+ * declares a schema major behind the framework target (#2971 / #3243). Greenfield
+ * (no envelopes) skips. Behind-major records `deft migrate:xbrief` as the next
+ * action (hybrid in-place rewrite on already-xbrief trees — #3236). Distinct from
+ * deposited-schema (`stale-xbrief-schema-deposit`) which must NOT route to
+ * migrate:xbrief when only framework schema files are stale.
  */
 export function runXbriefEnvelopeVersionCheck(projectRoot, sink, addFinding, seams) {
-    const checkName = "xbrief-envelope-version";
-    const isFile = seams.isFile ?? ((p) => existsSync(p));
-    const readText = seams.readText ?? readTextSafe;
-    const targetVersion = VBRIEF_VERSION;
+    const checkName = XBRIEF_ENVELOPE_MAJOR_CHECK;
     if (seams.probeXbriefEnvelope) {
         const probe = seams.probeXbriefEnvelope(projectRoot);
         emitXbriefEnvelopeFinding(checkName, probe, sink, addFinding);
         return;
     }
-    let definitionPath;
-    try {
-        definitionPath = resolveProjectDefinitionPath(projectRoot);
-    }
-    catch {
-        // Pure vbrief/-only trees are already covered by layout migrate signposts.
-        const skipMessage = `${checkName}: skip -- legacy-only layout (use layout migrate first)`;
-        sink.info(skipMessage);
-        addFinding({
-            severity: "skip",
-            message: skipMessage,
-            check: checkName,
-            status: "skip",
-            reason: "legacy-only-layout",
-        });
-        return;
-    }
-    if (!isFile(definitionPath)) {
-        const skipMessage = `${checkName}: skip -- no PROJECT-DEFINITION yet (greenfield)`;
-        sink.info(skipMessage);
-        addFinding({
-            severity: "skip",
-            message: skipMessage,
-            check: checkName,
-            status: "skip",
-            reason: "no-project-definition",
-        });
-        return;
-    }
-    const text = readText(definitionPath);
-    if (text === null) {
-        // Unreadable path (permissions or injectable seams) is not proof of 0.6.
-        const skipMessage = `${checkName}: skip -- PROJECT-DEFINITION unreadable`;
+    const result = checkXbriefEnvelopeMajorVersion(projectRoot, {
+        ...(seams.readText ? { readText: seams.readText } : {}),
+        ...(seams.isFile ? { isFile: seams.isFile } : {}),
+        ...(seams.isDir ? { isDir: seams.isDir } : {}),
+    });
+    const data = (result.data ?? {});
+    const targetVersion = typeof data.target_version === "string"
+        ? data.target_version
+        : String(data.target_version ?? "");
+    const declaredFromData = data.declared_versions;
+    const declaredVersion = Array.isArray(declaredFromData)
+        ? (declaredFromData.find((v) => typeof v === "string") ?? null)
+        : null;
+    if (result.status === "skip") {
+        const skipMessage = `${checkName}: skip -- ${result.detail}`;
         sink.info(skipMessage);
         addFinding({
             severity: "skip",
             message: skipMessage,
             check: checkName,
             status: "skip",
-            reason: "unreadable",
+            reason: typeof data.reason === "string" ? data.reason : "skip",
+            target_version: targetVersion || undefined,
         });
         return;
     }
-    let declaredVersion = null;
-    try {
-        const parsed = JSON.parse(text);
-        if (typeof parsed === "object" && parsed !== null && !Array.isArray(parsed)) {
-            declaredVersion = readDeclaredArtifactVersion(parsed);
-        }
-        else {
-            const skipMessage = `${checkName}: skip -- PROJECT-DEFINITION is not a JSON object`;
-            sink.info(skipMessage);
+    if (result.status === "pass") {
+        const status = typeof data.status === "string" ? data.status : "current";
+        if (status === "behind-minor") {
+            // Major-only check (#3243) does not fail closed, but surface an advisory
+            // when the shared scan observed behind-minor distance.
+            const warnMessage = `${checkName}: behind-minor -- ${result.detail}. Prefer \`${XBRIEF_ENVELOPE_MIGRATE_COMMAND}\` when convenient.`;
+            sink.warn(warnMessage);
             addFinding({
-                severity: "skip",
-                message: skipMessage,
+                severity: "warning",
+                message: warnMessage,
                 check: checkName,
-                status: "skip",
-                reason: "invalid-json-shape",
+                status: "behind-minor",
+                suggestion: XBRIEF_ENVELOPE_MIGRATE_COMMAND,
+                target_version: targetVersion || undefined,
+                next_command: XBRIEF_ENVELOPE_MIGRATE_COMMAND,
             });
             return;
         }
-    }
-    catch {
-        const skipMessage = `${checkName}: skip -- PROJECT-DEFINITION JSON parse failed`;
-        sink.info(skipMessage);
+        const okMessage = `${checkName}: ${result.detail}`;
+        sink.success(okMessage);
         addFinding({
             severity: "skip",
-            message: skipMessage,
+            message: okMessage,
             check: checkName,
-            status: "skip",
-            reason: "parse-error",
+            status: "current",
+            target_version: targetVersion || undefined,
         });
         return;
     }
-    const distance = classifyXbriefSchemaDistance(declaredVersion, targetVersion);
-    emitXbriefEnvelopeFinding(checkName, {
-        declaredVersion,
-        targetVersion,
-        distance,
-        stale: distance !== "current",
-    }, sink, addFinding);
+    // fail / error → behind-major fail closed (migratable 0.6 or non-migratable)
+    const status = typeof data.status === "string" ? data.status : "behind-major";
+    const nextCommand = typeof data.next_command === "string"
+        ? data.next_command
+        : data.next_command === null
+            ? null
+            : XBRIEF_ENVELOPE_MIGRATE_COMMAND;
+    const suggestion = typeof data.suggestion === "string"
+        ? data.suggestion
+        : (nextCommand ?? `set xBRIEFInfo.version to framework target`);
+    const message = `${checkName}: ${result.detail}`;
+    sink.error(message);
+    addFinding({
+        severity: "error",
+        message,
+        check: checkName,
+        status,
+        suggestion,
+        declared_version: declaredVersion,
+        target_version: targetVersion || undefined,
+        next_command: nextCommand,
+        sample_paths: data.sample_paths,
+        behind_major_count: data.behind_major_count,
+    });
 }
 function emitXbriefEnvelopeFinding(checkName, probe, sink, addFinding) {
     if (probe.distance === "current") {

package/dist/doctor/which.d.ts

@@ -1,3 +1,22 @@
-/** Default PATH lookup mirroring Python `shutil.which`. */
+export interface WhichAllOptions {
+    readonly env?: NodeJS.ProcessEnv;
+    readonly platform?: NodeJS.Platform;
+    readonly exists?: (path: string) => boolean;
+    /** Optional executable predicate (defaults to file + X_OK on posix). */
+    readonly isExecutable?: (path: string) => boolean;
+}
+/**
+ * Enumerate every PATH match for `name` (PATH order, first = highest precedence).
+ * Pure PATH scan — no shell locator — so tests and win32/posix stay hermetic and
+ * gated ritual never executes a PATH-substituted `which`/`where` (#3233).
+ * Only files (posix: executable bit) are accepted — not bare directories.
+ */
+export declare function whichAllFromPath(name: string, options?: WhichAllOptions): string[];
+/**
+ * All PATH matches for `name` without shelling out (#3233 security).
+ * Alias of {@link whichAllFromPath} — never runs bare `which` / `where`.
+ */
+export declare function defaultWhichAll(name: string, options?: WhichAllOptions): string[];
+/** Default PATH lookup mirroring Python `shutil.which` (first match only). */
 export declare function defaultWhich(name: string): string | null;
 //# sourceMappingURL=which.d.ts.map

package/dist/doctor/which.js

@@ -1,5 +1,71 @@
 import { execFileSync } from "node:child_process";
-/** Default PATH lookup mirroring Python `shutil.which`. */
+import { accessSync, constants, existsSync, statSync } from "node:fs";
+import { posix, win32 } from "node:path";
+function defaultIsExecutable(path, platform) {
+    try {
+        const st = statSync(path);
+        // Directories named `deft` must not shadow later executables (#3233 Greptile).
+        if (st.isDirectory())
+            return false;
+        if (!st.isFile() && !st.isSymbolicLink())
+            return false;
+        if (platform === "win32") {
+            return true;
+        }
+        accessSync(path, constants.X_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Enumerate every PATH match for `name` (PATH order, first = highest precedence).
+ * Pure PATH scan — no shell locator — so tests and win32/posix stay hermetic and
+ * gated ritual never executes a PATH-substituted `which`/`where` (#3233).
+ * Only files (posix: executable bit) are accepted — not bare directories.
+ */
+export function whichAllFromPath(name, options = {}) {
+    const env = options.env ?? process.env;
+    const platform = options.platform ?? process.platform;
+    const exists = options.exists ?? existsSync;
+    const isExecutable = options.isExecutable ?? ((p) => defaultIsExecutable(p, platform));
+    const pathValue = env.PATH ?? env.Path ?? "";
+    if (pathValue === "") {
+        return [];
+    }
+    const isWindows = platform === "win32";
+    const exts = isWindows ? (env.PATHEXT ?? ".COM;.EXE;.BAT;.CMD").split(";") : [""];
+    const sep = isWindows ? ";" : ":";
+    const joinPath = isWindows ? win32.join : posix.join;
+    const seen = new Set();
+    const out = [];
+    for (const dir of pathValue.split(sep)) {
+        if (dir === "")
+            continue;
+        for (const ext of exts) {
+            const candidate = joinPath(dir, `${name}${ext}`);
+            const key = isWindows ? candidate.toLowerCase() : candidate;
+            if (seen.has(key))
+                continue;
+            if (exists(candidate) && isExecutable(candidate)) {
+                seen.add(key);
+                out.push(candidate);
+                // One match per PATH directory (first PATHEXT hit wins on win32).
+                break;
+            }
+        }
+    }
+    return out;
+}
+/**
+ * All PATH matches for `name` without shelling out (#3233 security).
+ * Alias of {@link whichAllFromPath} — never runs bare `which` / `where`.
+ */
+export function defaultWhichAll(name, options = {}) {
+    return whichAllFromPath(name, options);
+}
+/** Default PATH lookup mirroring Python `shutil.which` (first match only). */
 export function defaultWhich(name) {
     const locator = process.platform === "win32" ? "where" : "which";
     try {

package/dist/eval/report.d.ts

@@ -1,4 +1,5 @@
 import { type GoldenRunRecord } from "./run.js";
+import { type CellVersionPurity, type MixedVersionPolicy } from "./version-pin.js";
 export declare const REPORT_SCHEMA_VERSION: 1;
 /** Metric delta with a simple two-proportion significance test (#896). */
 export interface MetricDelta {
@@ -17,6 +18,15 @@ export interface HoldoutTripwire {
     readonly primaryDelta: number;
     readonly holdoutDelta: number;
 }
+/** Version purity evidence for report consumers (#3215). */
+export interface VersionPurityEvidence {
+    readonly pure: boolean;
+    readonly summary: string;
+    readonly cells: readonly CellVersionPurity[];
+    readonly championCellAllowed: boolean;
+    readonly challengerCellAllowed: boolean;
+    readonly policy: MixedVersionPolicy;
+}
 /** Version-diff report between champion and challenger golden runs. */
 export interface GoldenEvalReport {
     readonly schemaVersion: typeof REPORT_SCHEMA_VERSION;
@@ -27,12 +37,19 @@ export interface GoldenEvalReport {
     readonly challengerRunId: string;
     readonly deltas: readonly MetricDelta[];
     readonly holdoutTripwire: HoldoutTripwire;
+    /** Cell-level framework version purity for the reported model (#3215). */
+    readonly versionPurity: VersionPurityEvidence;
 }
 export interface ReportGoldenEvalOptions {
     readonly projectRoot?: string;
     readonly championVersion: string;
     readonly challengerVersion: string;
     readonly model: string;
+    /**
+     * Mixed-version cell policy (#3215). Default `refuse` fails the report when
+     * ledger runs for this model disagree on framework version within a treatment.
+     */
+    readonly mixedVersionPolicy?: MixedVersionPolicy;
 }
 export interface ReportGoldenEvalResult {
     readonly code: 0 | 1 | 2;
@@ -48,6 +65,18 @@ export declare function twoProportionZTest(passedA: number, totalA: number, pass
 };
 /** Detect holdout tripwire: primary improves while holdout regresses (#1703). */
 export declare function evaluateHoldoutTripwire(champion: GoldenRunRecord, challenger: GoldenRunRecord): HoldoutTripwire;
+/**
+ * Map a golden-run ledger row to the #3215 versioned-run identity.
+ * Treatment is model@harness@version so cross-version champion/challenger
+ * comparisons stay distinct cells; pin disagreements under one version refuse.
+ */
+export declare function goldenRunToVersionedRun(record: GoldenRunRecord): {
+    frameworkVersion: string;
+    treatment: string;
+    model: string;
+    harness: string;
+    runId: string;
+};
 /** Diff two directive versions with metric deltas and significance (#1703 Tier 2). */
 export declare function reportGoldenEval(options: ReportGoldenEvalOptions): ReportGoldenEvalResult;
 //# sourceMappingURL=report.d.ts.map

package/dist/eval/report.js

@@ -1,6 +1,7 @@
 import { existsSync, readFileSync } from "node:fs";
 import { resolveEvalPath } from "../layout/resolve.js";
 import { GOLDEN_RUNS_HISTORY_REL } from "./run.js";
+import { aggregateCellWithVersionPurity, evaluateLedgerVersionPurity, } from "./version-pin.js";
 export const REPORT_SCHEMA_VERSION = 1;
 function readGoldenRuns(projectRoot) {
     const path = resolveEvalPath(projectRoot, GOLDEN_RUNS_HISTORY_REL);
@@ -89,6 +90,21 @@ export function evaluateHoldoutTripwire(champion, challenger) {
 function formatPercent(value) {
     return `${(value * 100).toFixed(1)}%`;
 }
+/**
+ * Map a golden-run ledger row to the #3215 versioned-run identity.
+ * Treatment is model@harness@version so cross-version champion/challenger
+ * comparisons stay distinct cells; pin disagreements under one version refuse.
+ */
+export function goldenRunToVersionedRun(record) {
+    const pin = record.frameworkVersionPin?.frameworkVersion ?? record.directiveVersion;
+    return {
+        frameworkVersion: pin,
+        treatment: `${record.model}@${record.harness}@${record.directiveVersion}`,
+        model: record.model,
+        harness: record.harness,
+        runId: record.runId,
+    };
+}
 /** Diff two directive versions with metric deltas and significance (#1703 Tier 2). */
 export function reportGoldenEval(options) {
     if (!options.championVersion.trim() || !options.challengerVersion.trim()) {
@@ -102,7 +118,48 @@ export function reportGoldenEval(options) {
         return { code: 2, report: null, message: "eval:report: --model is required" };
     }
     const projectRoot = options.projectRoot ?? process.cwd();
+    const policy = options.mixedVersionPolicy ?? "refuse";
     const records = readGoldenRuns(projectRoot);
+    const modelRecords = records.filter((r) => r.model === options.model);
+    // Within each version×model×harness cell, refuse/flag if pins disagree (#3215).
+    // Cross-version champion vs challenger is intentional and uses distinct cells.
+    const championCellRuns = modelRecords
+        .filter((r) => r.directiveVersion === options.championVersion)
+        .map(goldenRunToVersionedRun);
+    const challengerCellRuns = modelRecords
+        .filter((r) => r.directiveVersion === options.challengerVersion)
+        .map(goldenRunToVersionedRun);
+    const championAgg = aggregateCellWithVersionPurity({
+        runs: championCellRuns,
+        treatment: `champion@${options.model}@${options.championVersion}`,
+        policy,
+    });
+    const challengerAgg = aggregateCellWithVersionPurity({
+        runs: challengerCellRuns,
+        treatment: `challenger@${options.model}@${options.challengerVersion}`,
+        policy,
+    });
+    const ledgerPurity = evaluateLedgerVersionPurity(modelRecords.map(goldenRunToVersionedRun));
+    if (!championAgg.allowed || !challengerAgg.allowed) {
+        const versionPurity = {
+            pure: false,
+            summary: [
+                !championAgg.allowed ? championAgg.purity.message : null,
+                !challengerAgg.allowed ? challengerAgg.purity.message : null,
+            ]
+                .filter((line) => line !== null)
+                .join(" "),
+            cells: [championAgg.purity, challengerAgg.purity],
+            championCellAllowed: championAgg.allowed,
+            challengerCellAllowed: challengerAgg.allowed,
+            policy,
+        };
+        return {
+            code: 1,
+            report: null,
+            message: `eval:report: mixed framework versions in treatment cell(s) — aggregation refused (#3215)\n  ${versionPurity.summary}`,
+        };
+    }
     const champion = findLatestGoldenRun(records, options.championVersion, options.model);
     const challenger = findLatestGoldenRun(records, options.challengerVersion, options.model);
     if (champion === null) {
@@ -133,6 +190,14 @@ export function reportGoldenEval(options) {
         metricDelta("overallPassRate", champion.summary.passRate, challenger.summary.passRate, countPasses(champion.results).passed, countPasses(champion.results).total, countPasses(challenger.results).passed, countPasses(challenger.results).total),
     ];
     const holdoutTripwire = evaluateHoldoutTripwire(champion, challenger);
+    const versionPurity = {
+        pure: championAgg.purity.pure && challengerAgg.purity.pure && ledgerPurity.pure,
+        summary: `${championAgg.purity.message} ${challengerAgg.purity.message}`,
+        cells: [championAgg.purity, challengerAgg.purity, ...ledgerPurity.cells],
+        championCellAllowed: championAgg.allowed,
+        challengerCellAllowed: challengerAgg.allowed,
+        policy,
+    };
     const report = {
         schemaVersion: REPORT_SCHEMA_VERSION,
         championVersion: options.championVersion,
@@ -142,6 +207,7 @@ export function reportGoldenEval(options) {
         challengerRunId: challenger.runId,
         deltas,
         holdoutTripwire,
+        versionPurity,
     };
     const lines = [
         `eval:report champion=v${options.championVersion} challenger=v${options.challengerVersion} model=${options.model}`,
@@ -154,6 +220,9 @@ export function reportGoldenEval(options) {
             return `  ${d.metric}: ${formatPercent(d.champion)} -> ${formatPercent(d.challenger)} (delta ${(d.delta * 100).toFixed(1)}pp, ${sig})`;
         }),
         `  ${holdoutTripwire.summary}`,
+        `  version purity: ${versionPurity.pure ? "ok" : "mixed"} — ${versionPurity.summary}`,
+        `  champion cell pin: v${champion.frameworkVersionPin?.frameworkVersion ?? champion.directiveVersion}`,
+        `  challenger cell pin: v${challenger.frameworkVersionPin?.frameworkVersion ?? challenger.directiveVersion}`,
     ];
     const code = holdoutTripwire.triggered ? 1 : 0;
     return { code, report, message: lines.join("\n") };

package/dist/eval/run.d.ts

@@ -1,3 +1,4 @@
+import { type FrameworkVersionPin } from "./version-pin.js";
 export declare const GOLDEN_RUNS_HISTORY_REL = "results/golden-runs.jsonl";
 export declare const GOLDEN_RUN_SCHEMA_VERSION: 1;
 export declare const GOLDEN_CORPUS_VERSION = "2026-07-05-tier2-fixture-v1";
@@ -32,7 +33,13 @@ export interface GoldenTaskResult {
 export interface GoldenRunRecord {
     readonly schemaVersion: typeof GOLDEN_RUN_SCHEMA_VERSION;
     readonly runId: string;
+    /** Framework version pin for this run (alias of frameworkVersionPin.frameworkVersion). */
     readonly directiveVersion: string;
+    /**
+     * Resolved framework version pin captured at run start (#3215).
+     * Optional for ledger rows written before the purity gate shipped.
+     */
+    readonly frameworkVersionPin?: FrameworkVersionPin;
     readonly model: string;
     readonly harness: string;
     readonly seeds: readonly number[];
@@ -63,6 +70,8 @@ export interface RunGoldenEvalResult {
     readonly code: 0 | 1 | 2;
     readonly record: GoldenRunRecord | null;
     readonly message: string;
+    /** #1584 shared-benchmark manifest after version pin wire, when present on disk. */
+    readonly sharedBenchmarkManifest?: Record<string, unknown> | null;
 }
 /** Fixed golden corpus with objective graders (#1703 Tier 2). */
 export declare const GOLDEN_CORPUS: readonly GoldenTaskDefinition[];

package/dist/eval/run.js

@@ -2,11 +2,11 @@ import { createHash } from "node:crypto";
 import { mkdirSync, mkdtempSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join, resolve } from "node:path";
-import { readCorePackageVersion } from "../engine-version.js";
 import { containedWrite } from "../fs/contained-write.js";
 import { resolveEvalPath } from "../layout/resolve.js";
 import { BYTE_DIFF_WHOLE_FILE_THRESHOLD, InstrumentedVbriefCrud } from "./crud-telemetry.js";
 import { evaluateHealth } from "./health.js";
+import { applyVersionPinToSharedBenchmark, resolveFrameworkVersionPin, } from "./version-pin.js";
 export const GOLDEN_RUNS_HISTORY_REL = "results/golden-runs.jsonl";
 export const GOLDEN_RUN_SCHEMA_VERSION = 1;
 export const GOLDEN_CORPUS_VERSION = "2026-07-05-tier2-fixture-v1";
@@ -250,10 +250,15 @@ export function runGoldenEval(options) {
         return { code: 2, record: null, message: "eval:run: --model is required" };
     }
     const projectRoot = options.projectRoot ?? process.cwd();
-    const directiveVersion = options.directiveVersion ?? readCorePackageVersion();
+    const now = options.now ?? (() => new Date());
+    // #3215: resolve framework version once at run start (package.json pin or override).
+    const frameworkVersionPin = resolveFrameworkVersionPin({
+        override: options.directiveVersion,
+        now,
+    });
+    const directiveVersion = frameworkVersionPin.frameworkVersion;
     const harness = options.harness ?? "deterministic-fixture";
     const seeds = options.seeds ?? [1, 2, 3];
-    const now = options.now ?? (() => new Date());
     const persist = options.persist ?? true;
     if (seeds.length === 0) {
         return { code: 2, record: null, message: "eval:run: at least one seed is required" };
@@ -293,6 +298,7 @@ export function runGoldenEval(options) {
         schemaVersion: GOLDEN_RUN_SCHEMA_VERSION,
         runId: runIdFor(directiveVersion, options.model, harness, seeds),
         directiveVersion,
+        frameworkVersionPin,
         model: options.model,
         harness,
         seeds,
@@ -303,6 +309,8 @@ export function runGoldenEval(options) {
         results,
         summary,
     };
+    // Persist ledger first so a failed golden-run write never leaves a dangling
+    // shared-benchmark pin without a matching run row (#3215 Greptile).
     if (persist) {
         try {
             persistGoldenRun(projectRoot, record);
@@ -312,16 +320,44 @@ export function runGoldenEval(options) {
                 code: 2,
                 record,
                 message: `eval:run: failed to persist golden run: ${String(err)}`,
+                sharedBenchmarkManifest: null,
             };
         }
     }
+    // #1584 / #3215: wire (+ persist when ledger was written) shared-benchmark pin.
+    let sharedBenchmark;
+    try {
+        sharedBenchmark = applyVersionPinToSharedBenchmark(projectRoot, frameworkVersionPin, {
+            persist,
+        });
+    }
+    catch (err) {
+        return {
+            code: 2,
+            record,
+            message: `eval:run: failed to wire shared-benchmark pin: ${String(err)}`,
+            sharedBenchmarkManifest: null,
+        };
+    }
     const lines = [
         `eval:run v${record.directiveVersion} model=${record.model} harness=${record.harness} seeds=[${record.seeds.join(",")}]`,
+        `  framework version pin: ${frameworkVersionPin.frameworkVersion} (source=${frameworkVersionPin.source})`,
         `  primary pass rate: ${(summary.primaryPassRate * 100).toFixed(1)}% (${summary.primaryTotal} trials)`,
         `  holdout pass rate: ${(summary.holdoutPassRate * 100).toFixed(1)}% (${summary.holdoutTotal} trials)`,
         `  rotating holdout task: ${rotatingHoldout?.id ?? "none"}`,
         `  runId=${record.runId}`,
     ];
-    return { code: 0, record, message: lines.join("\n") };
+    if (sharedBenchmark.persisted) {
+        lines.push("  shared-benchmark manifest: frameworkVersion pin persisted (#1584 / #3215)");
+    }
+    else if (sharedBenchmark.applied) {
+        lines.push("  shared-benchmark manifest: frameworkVersion wired in-memory (#1584 / #3215)");
+    }
+    return {
+        code: 0,
+        record,
+        message: lines.join("\n"),
+        sharedBenchmarkManifest: sharedBenchmark.manifest,
+    };
 }
 //# sourceMappingURL=run.js.map