@deftai/directive-core 0.69.0 → 0.71.0

package/dist/eval/run.js

@@ -0,0 +1,309 @@
+import { createHash } from "node:crypto";
+import { appendFileSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { readCorePackageVersion } from "../engine-version.js";
+import { resolveEvalPath } from "../layout/resolve.js";
+import { BYTE_DIFF_WHOLE_FILE_THRESHOLD, InstrumentedVbriefCrud } from "./crud-telemetry.js";
+import { evaluateHealth } from "./health.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";
+const VALID_VBRIEF = `{
+  "vBRIEFInfo": { "version": "0.6", "description": "golden fixture" },
+  "plan": {
+    "id": "golden-fixture",
+    "title": "Golden fixture",
+    "status": "pending",
+    "narratives": { "Description": "Valid golden corpus document." },
+    "items": [
+      {
+        "id": "golden-a1",
+        "title": "Item",
+        "status": "pending",
+        "narrative": { "Acceptance": "Schema valid." }
+      }
+    ]
+  }
+}`;
+const INVENTED_KEY_VBRIEF = VALID_VBRIEF.replace('"items": [', '"agentInventedField": "bad",\n    "items": [');
+function passRate(results, holdout) {
+    const subset = results.filter((r) => r.holdout === holdout);
+    if (subset.length === 0) {
+        return 0;
+    }
+    return subset.filter((r) => r.passed).length / subset.length;
+}
+function summarizeResults(results) {
+    const primary = results.filter((r) => !r.holdout);
+    const holdout = results.filter((r) => r.holdout);
+    const primaryPassRate = passRate(results, false);
+    const holdoutPassRate = passRate(results, true);
+    return {
+        primaryPassRate,
+        holdoutPassRate,
+        passRate: results.length === 0 ? 0 : results.filter((r) => r.passed).length / results.length,
+        primaryTotal: primary.length,
+        holdoutTotal: holdout.length,
+    };
+}
+function gradeCrudValidCreate(context) {
+    const path = join(context.tempDir, "create.json");
+    const crud = new InstrumentedVbriefCrud({ directiveVersion: context.directiveVersion });
+    const result = crud.create(path, VALID_VBRIEF);
+    const metric = crud.getMetrics()[0];
+    return {
+        passed: result.ok && metric?.schemaValid === true,
+        metrics: {
+            schemaValid: metric?.schemaValid === true,
+            fieldInventionCount: metric?.fieldInventionCount ?? -1,
+        },
+    };
+}
+function gradeCrudRejectInvention(context) {
+    const path = join(context.tempDir, "invented.json");
+    const crud = new InstrumentedVbriefCrud({ directiveVersion: context.directiveVersion });
+    crud.create(path, INVENTED_KEY_VBRIEF);
+    const metric = crud.getMetrics()[0];
+    const inventedKeys = metric?.inventedKeys.length ?? 0;
+    return {
+        passed: metric?.schemaValid === true && inventedKeys > 0 && (metric?.fieldInventionCount ?? 0) > 0,
+        metrics: {
+            detectedInvention: inventedKeys > 0,
+            fieldInventionCount: metric?.fieldInventionCount ?? -1,
+        },
+    };
+}
+function gradeCrudSurgicalUpdate(context) {
+    const path = join(context.tempDir, "update.json");
+    const crud = new InstrumentedVbriefCrud({ directiveVersion: context.directiveVersion });
+    crud.create(path, VALID_VBRIEF);
+    const updated = VALID_VBRIEF.replace('"pending"', '"running"');
+    crud.update(path, updated);
+    const updateMetric = crud.getMetrics().find((m) => m.operation === "update");
+    return {
+        passed: updateMetric?.schemaValid === true &&
+            updateMetric.byteDiffMinimality === "surgical" &&
+            (updateMetric.byteDiffChangedRatio ?? 1) < BYTE_DIFF_WHOLE_FILE_THRESHOLD,
+        metrics: {
+            schemaValid: updateMetric?.schemaValid === true,
+            byteDiffMinimalitySurgical: updateMetric?.byteDiffMinimality === "surgical",
+            changedRatio: updateMetric?.byteDiffChangedRatio ?? -1,
+        },
+    };
+}
+function seedHealthFixture(tempDir) {
+    writeFileSync(join(tempDir, "xbrief", "PROJECT-DEFINITION.xbrief.json"), JSON.stringify({
+        xBRIEFInfo: { version: "0.6" },
+        plan: {
+            title: "Golden health fixture",
+            status: "running",
+            items: [],
+            "x-directive/policy": { triageScope: [{ rule: "all-open" }] },
+        },
+    }), "utf8");
+    writeFileSync(join(tempDir, "AGENTS.md"), "<!-- deft:managed-section v3 -->\n<!-- /deft:managed-section -->\n", "utf8");
+}
+function gradeHealthFixture(context) {
+    seedHealthFixture(context.tempDir);
+    const health = evaluateHealth({
+        projectRoot: context.tempDir,
+        persist: false,
+        frameworkSource: false,
+    });
+    return {
+        passed: health.report !== null && typeof health.report.score === "number",
+        metrics: {
+            score: health.report?.score ?? -1,
+            gateCount: health.report?.gates.length ?? -1,
+        },
+    };
+}
+function gradeHoldoutSchemaRoundtrip(context) {
+    const path = join(context.tempDir, "roundtrip.json");
+    const crud = new InstrumentedVbriefCrud({ directiveVersion: context.directiveVersion });
+    crud.create(path, VALID_VBRIEF);
+    const read = crud.read(path);
+    const roundtripOk = read.ok && read.content === VALID_VBRIEF;
+    const noise = (context.seed % 997) / 997;
+    return {
+        passed: roundtripOk && noise < 0.99,
+        metrics: { roundtripOk, seedNoise: noise },
+    };
+}
+function gradeHoldoutByteDiffTripwire(context) {
+    const path = join(context.tempDir, "rewrite.json");
+    const crud = new InstrumentedVbriefCrud({ directiveVersion: context.directiveVersion });
+    crud.create(path, VALID_VBRIEF);
+    const rewritten = JSON.stringify(JSON.parse(VALID_VBRIEF), null, 2);
+    crud.update(path, rewritten);
+    const updateMetric = crud.getMetrics().find((m) => m.operation === "update");
+    const detectedRewrite = updateMetric?.byteDiffMinimality === "whole-file-rewrite";
+    const tripwire = (context.seed % 991) / 991;
+    return {
+        passed: detectedRewrite && tripwire < 0.99,
+        metrics: {
+            detectedRewrite,
+            tripwire,
+        },
+    };
+}
+/** Fixed golden corpus with objective graders (#1703 Tier 2). */
+export const GOLDEN_CORPUS = [
+    {
+        id: "crud-valid-create",
+        title: "Instrumented create accepts valid vBRIEF",
+        holdout: false,
+        grade: gradeCrudValidCreate,
+    },
+    {
+        id: "crud-reject-invention",
+        title: "Instrumented create rejects invented keys",
+        holdout: false,
+        grade: gradeCrudRejectInvention,
+    },
+    {
+        id: "crud-surgical-update",
+        title: "Instrumented update classifies surgical edits",
+        holdout: false,
+        grade: gradeCrudSurgicalUpdate,
+    },
+    {
+        id: "health-fixture-score",
+        title: "Tier-0 health eval runs on fixture repo",
+        holdout: false,
+        grade: gradeHealthFixture,
+    },
+    {
+        id: "holdout-schema-roundtrip",
+        title: "Holdout: read-after-create roundtrip",
+        holdout: true,
+        grade: gradeHoldoutSchemaRoundtrip,
+    },
+    {
+        id: "holdout-byte-diff-tripwire",
+        title: "Holdout: whole-file rewrite detection tripwire",
+        holdout: true,
+        grade: gradeHoldoutByteDiffTripwire,
+    },
+];
+/** Absolute path to the golden-run results ledger. */
+export function goldenRunsHistoryPath(projectRoot) {
+    return resolveEvalPath(projectRoot, GOLDEN_RUNS_HISTORY_REL);
+}
+/** Append one golden run to the versioned ledger (#1703 Tier 2). */
+export function persistGoldenRun(projectRoot, record) {
+    const path = goldenRunsHistoryPath(projectRoot);
+    mkdirSync(dirname(path), { recursive: true });
+    appendFileSync(path, `${JSON.stringify(record)}\n`, "utf8");
+}
+/** Stable hash for rotating holdout selection (#1703 Goodhart mitigation). */
+export function holdoutRotationIndex(directiveVersion, model, holdoutCount) {
+    if (holdoutCount <= 0) {
+        return 0;
+    }
+    const digest = createHash("sha256")
+        .update(`${directiveVersion}\0${model}\0${GOLDEN_CORPUS_VERSION}`)
+        .digest("hex");
+    return Number.parseInt(digest.slice(0, 8), 16) % holdoutCount;
+}
+/** Select the active holdout task for this version × model tuple. */
+export function selectRotatingHoldoutTask(directiveVersion, model) {
+    const holdouts = GOLDEN_CORPUS.filter((task) => task.holdout);
+    if (holdouts.length === 0) {
+        return null;
+    }
+    return holdouts[holdoutRotationIndex(directiveVersion, model, holdouts.length)] ?? null;
+}
+function seedTempDir(taskId, seed) {
+    const base = mkdtempSync(join(tmpdir(), `deft-golden-${taskId}-seed-${seed}-`));
+    mkdirSync(join(base, "xbrief"), { recursive: true });
+    return base;
+}
+function runIdFor(directiveVersion, model, harness, seeds) {
+    const digest = createHash("sha256")
+        .update(`${directiveVersion}\0${model}\0${harness}\0${seeds.join(",")}\0${GOLDEN_CORPUS_VERSION}`)
+        .digest("hex");
+    return digest.slice(0, 12);
+}
+/** Execute the golden corpus for one model × seed set and optionally persist (#1703 Tier 2). */
+export function runGoldenEval(options) {
+    if (!options.model.trim()) {
+        return { code: 2, record: null, message: "eval:run: --model is required" };
+    }
+    const projectRoot = options.projectRoot ?? process.cwd();
+    const directiveVersion = options.directiveVersion ?? readCorePackageVersion();
+    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" };
+    }
+    const primaryTasks = GOLDEN_CORPUS.filter((task) => !task.holdout);
+    const rotatingHoldout = selectRotatingHoldoutTask(directiveVersion, options.model);
+    const tasksToRun = [...primaryTasks];
+    if (rotatingHoldout !== null) {
+        tasksToRun.push(rotatingHoldout);
+    }
+    const results = [];
+    const scratchDirs = [];
+    for (const task of tasksToRun) {
+        for (const seed of seeds) {
+            const tempDir = seedTempDir(task.id, seed);
+            scratchDirs.push(tempDir);
+            const grade = task.grade({
+                tempDir,
+                seed,
+                directiveVersion,
+                model: options.model,
+            });
+            results.push({
+                taskId: task.id,
+                seed,
+                passed: grade.passed,
+                holdout: task.holdout,
+                metrics: grade.metrics,
+            });
+        }
+    }
+    for (const dir of scratchDirs) {
+        rmSync(dir, { recursive: true, force: true });
+    }
+    const summary = summarizeResults(results);
+    const record = {
+        schemaVersion: GOLDEN_RUN_SCHEMA_VERSION,
+        runId: runIdFor(directiveVersion, options.model, harness, seeds),
+        directiveVersion,
+        model: options.model,
+        harness,
+        seeds,
+        corpusVersion: GOLDEN_CORPUS_VERSION,
+        recordedAt: now()
+            .toISOString()
+            .replace(/\.\d{3}Z$/, "Z"),
+        results,
+        summary,
+    };
+    if (persist) {
+        try {
+            persistGoldenRun(projectRoot, record);
+        }
+        catch (err) {
+            return {
+                code: 2,
+                record,
+                message: `eval:run: failed to persist golden run: ${String(err)}`,
+            };
+        }
+    }
+    const lines = [
+        `eval:run v${record.directiveVersion} model=${record.model} harness=${record.harness} seeds=[${record.seeds.join(",")}]`,
+        `  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") };
+}
+//# sourceMappingURL=run.js.map

package/dist/events/attribution-constants.d.ts

@@ -0,0 +1,13 @@
+/** Canonical behavioral event names for the attribution ledger (#1709). */
+export declare const ATTRIBUTION_EVENT_NAMES: {
+    readonly valueGateCatch: "value:gate-catch";
+    readonly valueWipCapProtect: "value:wip-cap-protect";
+    readonly bypassOffFlow: "bypass:off-flow";
+    readonly adoptionUnusedCapability: "adoption:unused-capability";
+    readonly frictionDirectiveGap: "friction:directive-gap";
+};
+export type AttributionEventName = (typeof ATTRIBUTION_EVENT_NAMES)[keyof typeof ATTRIBUTION_EVENT_NAMES];
+/** Required payload keys per attribution event (merged into lifecycle/events). */
+export declare const ATTRIBUTION_REQUIRED_PAYLOAD: Readonly<Record<string, readonly string[]>>;
+export declare const ALL_ATTRIBUTION_EVENT_NAMES: ("value:gate-catch" | "value:wip-cap-protect" | "bypass:off-flow" | "adoption:unused-capability" | "friction:directive-gap")[];
+//# sourceMappingURL=attribution-constants.d.ts.map

package/dist/events/attribution-constants.js

@@ -0,0 +1,18 @@
+/** Canonical behavioral event names for the attribution ledger (#1709). */
+export const ATTRIBUTION_EVENT_NAMES = {
+    valueGateCatch: "value:gate-catch",
+    valueWipCapProtect: "value:wip-cap-protect",
+    bypassOffFlow: "bypass:off-flow",
+    adoptionUnusedCapability: "adoption:unused-capability",
+    frictionDirectiveGap: "friction:directive-gap",
+};
+/** Required payload keys per attribution event (merged into lifecycle/events). */
+export const ATTRIBUTION_REQUIRED_PAYLOAD = {
+    [ATTRIBUTION_EVENT_NAMES.valueGateCatch]: ["signal_class", "source"],
+    [ATTRIBUTION_EVENT_NAMES.valueWipCapProtect]: ["signal_class", "source", "count", "cap"],
+    [ATTRIBUTION_EVENT_NAMES.bypassOffFlow]: ["signal_class", "source"],
+    [ATTRIBUTION_EVENT_NAMES.adoptionUnusedCapability]: ["signal_class", "source", "capability"],
+    [ATTRIBUTION_EVENT_NAMES.frictionDirectiveGap]: ["signal_class", "source"],
+};
+export const ALL_ATTRIBUTION_EVENT_NAMES = Object.values(ATTRIBUTION_EVENT_NAMES);
+//# sourceMappingURL=attribution-constants.js.map

package/dist/events/attribution-ledger.d.ts

@@ -0,0 +1,43 @@
+import { type BehavioralEventRecord } from "../lifecycle/events.js";
+import { type ValueFeedbackResolved } from "../policy/value-feedback.js";
+import { type AttributionEventName } from "./attribution-constants.js";
+export { ALL_ATTRIBUTION_EVENT_NAMES, ATTRIBUTION_EVENT_NAMES, ATTRIBUTION_REQUIRED_PAYLOAD, type AttributionEventName, } from "./attribution-constants.js";
+/** Four value-attribution signal classes (#1709 RFC). */
+export type SignalClass = "value" | "bypass" | "adoption" | "friction";
+export interface EmitAttributionOptions {
+    readonly projectRoot: string;
+    readonly logPath?: string | null;
+    /** Test hook: skip disk policy read. */
+    readonly policyOverride?: ValueFeedbackResolved;
+}
+/**
+ * Append an attribution ledger entry when valueFeedback emitEvents is allowed.
+ * Returns null when gated OFF (no disk write).
+ */
+export declare function emitAttributionSignal(name: AttributionEventName, payload: Record<string, unknown>, options: EmitAttributionOptions): BehavioralEventRecord | null;
+/** Record a detection-bound gate catch (value class). */
+export declare function recordGateCatch(projectRoot: string, source: string, detail: string, options?: {
+    logPath?: string | null;
+    policyOverride?: ValueFeedbackResolved;
+}): BehavioralEventRecord | null;
+/** Record a WIP-cap protect refusal (value class). */
+export declare function recordWipCapProtect(projectRoot: string, count: number, cap: number, options?: {
+    logPath?: string | null;
+    policyOverride?: ValueFeedbackResolved;
+}): BehavioralEventRecord | null;
+/** Record a bypass/off-flow signal. */
+export declare function recordBypassSignal(projectRoot: string, source: string, detail: string, options?: {
+    logPath?: string | null;
+    policyOverride?: ValueFeedbackResolved;
+}): BehavioralEventRecord | null;
+/** Record an adoption/unused-capability signal. */
+export declare function recordAdoptionSignal(projectRoot: string, capability: string, detail: string, options?: {
+    logPath?: string | null;
+    policyOverride?: ValueFeedbackResolved;
+}): BehavioralEventRecord | null;
+/** Record a friction/directive-gap signal. */
+export declare function recordFrictionSignal(projectRoot: string, source: string, detail: string, options?: {
+    logPath?: string | null;
+    policyOverride?: ValueFeedbackResolved;
+}): BehavioralEventRecord | null;
+//# sourceMappingURL=attribution-ledger.d.ts.map

package/dist/events/attribution-ledger.js

@@ -0,0 +1,61 @@
+import { resolve } from "node:path";
+import { DEFAULT_EVENT_LOG, emit } from "../lifecycle/events.js";
+import { isValueFeedbackPathAllowed, resolveValueFeedback, } from "../policy/value-feedback.js";
+import { ATTRIBUTION_EVENT_NAMES } from "./attribution-constants.js";
+export { ALL_ATTRIBUTION_EVENT_NAMES, ATTRIBUTION_EVENT_NAMES, ATTRIBUTION_REQUIRED_PAYLOAD, } from "./attribution-constants.js";
+function resolveLedgerLogPath(projectRoot, logPath) {
+    if (logPath !== undefined && logPath !== null) {
+        return resolve(logPath);
+    }
+    return resolve(projectRoot, DEFAULT_EVENT_LOG);
+}
+function signalClassForEvent(name) {
+    const prefix = name.split(":")[0];
+    if (prefix === "value" || prefix === "bypass" || prefix === "adoption" || prefix === "friction") {
+        return prefix;
+    }
+    throw new Error(`attribution event '${name}' has unknown signal-class prefix`);
+}
+/**
+ * Append an attribution ledger entry when valueFeedback emitEvents is allowed.
+ * Returns null when gated OFF (no disk write).
+ */
+export function emitAttributionSignal(name, payload, options) {
+    try {
+        const policy = options.policyOverride ?? resolveValueFeedback(options.projectRoot);
+        if (!isValueFeedbackPathAllowed("emitEvents", policy)) {
+            return null;
+        }
+        const signalClass = signalClassForEvent(name);
+        const logPath = resolveLedgerLogPath(options.projectRoot, options.logPath);
+        return emit(name, {
+            signal_class: signalClass,
+            ...payload,
+        }, { logPath });
+    }
+    catch {
+        // Telemetry is best-effort; any failure must not interrupt gate callers (#1709).
+        return null;
+    }
+}
+/** Record a detection-bound gate catch (value class). */
+export function recordGateCatch(projectRoot, source, detail, options = {}) {
+    return emitAttributionSignal(ATTRIBUTION_EVENT_NAMES.valueGateCatch, { source, detail }, { projectRoot, ...options });
+}
+/** Record a WIP-cap protect refusal (value class). */
+export function recordWipCapProtect(projectRoot, count, cap, options = {}) {
+    return emitAttributionSignal(ATTRIBUTION_EVENT_NAMES.valueWipCapProtect, { source: "verify:wip-cap", count, cap }, { projectRoot, ...options });
+}
+/** Record a bypass/off-flow signal. */
+export function recordBypassSignal(projectRoot, source, detail, options = {}) {
+    return emitAttributionSignal(ATTRIBUTION_EVENT_NAMES.bypassOffFlow, { source, detail }, { projectRoot, ...options });
+}
+/** Record an adoption/unused-capability signal. */
+export function recordAdoptionSignal(projectRoot, capability, detail, options = {}) {
+    return emitAttributionSignal(ATTRIBUTION_EVENT_NAMES.adoptionUnusedCapability, { source: "adoption-registry", capability, detail }, { projectRoot, ...options });
+}
+/** Record a friction/directive-gap signal. */
+export function recordFrictionSignal(projectRoot, source, detail, options = {}) {
+    return emitAttributionSignal(ATTRIBUTION_EVENT_NAMES.frictionDirectiveGap, { source, detail }, { projectRoot, ...options });
+}
+//# sourceMappingURL=attribution-ledger.js.map

package/dist/index.d.ts

@@ -15,6 +15,11 @@ export * as capacity from "./capacity/index.js";
 export * as codebase from "./codebase/index.js";
 export * as doctor from "./doctor/index.js";
 export * from "./encoding/index.js";
+export * as evalCrud from "./eval/crud-telemetry.js";
+export * as evalHealth from "./eval/health.js";
+export * as evalReport from "./eval/report.js";
+export * as evalRun from "./eval/run.js";
+export * as events from "./events/attribution-ledger.js";
 export * from "./forward-coverage/evaluate.js";
 export * as intake from "./intake/index.js";
 export * as layout from "./layout/index.js";

package/dist/index.js

@@ -15,6 +15,11 @@ export * as capacity from "./capacity/index.js";
 export * as codebase from "./codebase/index.js";
 export * as doctor from "./doctor/index.js";
 export * from "./encoding/index.js";
+export * as evalCrud from "./eval/crud-telemetry.js";
+export * as evalHealth from "./eval/health.js";
+export * as evalReport from "./eval/report.js";
+export * as evalRun from "./eval/run.js";
+export * as events from "./events/attribution-ledger.js";
 export * from "./forward-coverage/evaluate.js";
 export * as intake from "./intake/index.js";
 export * as layout from "./layout/index.js";

package/dist/init-deposit/gitignore.js

@@ -26,11 +26,11 @@ export const CANONICAL_GITIGNORE_BASELINE = [
     ".deft/ritual-state.json",
     ".deft/last-session.json",
     ".deft/routing.local.json",
-    "vbrief/.eval/candidates.jsonl",
-    "vbrief/.eval/summary-history.jsonl",
-    "vbrief/.eval/scope-lifecycle.jsonl",
-    "vbrief/.eval/decompositions/",
-    "vbrief/.eval/doctor-state.json",
+    "vbrief/.triage-cache/candidates.jsonl",
+    "vbrief/.triage-cache/summary-history.jsonl",
+    "vbrief/.triage-cache/scope-lifecycle.jsonl",
+    "vbrief/.triage-cache/decompositions/",
+    "vbrief/.triage-cache/doctor-state.json",
     "vbrief/*.lock",
     ".deft/core.bak-*/",
     ".deft/*.bak-*",

package/dist/init-deposit/init-deposit.js

@@ -8,6 +8,7 @@
 import { existsSync, mkdirSync, readFileSync } from "node:fs";
 import { homedir, platform } from "node:os";
 import { join, resolve } from "node:path";
+import { assertDepositContained } from "../deposit/contain.js";
 import { copyTree } from "../deposit/copy-tree.js";
 import { prunePythonArtifactsFromDeposit } from "../deposit/python-free.js";
 import { resolveInstalledContentRoot } from "../deposit/resolve-content.js";
@@ -124,6 +125,11 @@ export async function runInitDeposit(args, io, seams = {}) {
     if (legacy.legacy) {
         throw new LegacyLayoutRefusedError(legacy);
     }
+    // #2305: refuse a symlink-escaping deposit boundary BEFORE the first
+    // copy/reconstitute/mkdir, so a malicious `.deft`/`.deft/core` symlink cannot
+    // redirect the deposit outside the resolved project tree. Deposits nothing on
+    // refusal.
+    assertDepositContained(projectDir, deftDir);
     const resolveContent = seams.resolveContentRoot ?? resolveInstalledContentRoot;
     const copyContent = seams.copyContent ?? copyTree;
     const contentRoot = await resolveContent();

package/dist/init-deposit/refresh.js

@@ -10,6 +10,7 @@
 import { existsSync, mkdirSync, readFileSync, renameSync, statSync, writeFileSync } from "node:fs";
 import { platform as osPlatform } from "node:os";
 import { join, resolve } from "node:path";
+import { assertDepositContained } from "../deposit/contain.js";
 import { copyTree } from "../deposit/copy-tree.js";
 import { prunePythonArtifactsFromDeposit } from "../deposit/python-free.js";
 import { resolveInstalledContentRoot } from "../deposit/resolve-content.js";
@@ -335,6 +336,10 @@ export async function runRefreshDeposit(args, io, seams = {}) {
     if (legacy.legacy) {
         throw new LegacyLayoutRefusedError(legacy);
     }
+    // #2305: refuse a symlink-escaping deposit boundary BEFORE the first copy so a
+    // malicious `.deft`/`.deft/core` symlink cannot redirect the refresh outside
+    // the resolved project tree. Writes nothing on refusal.
+    assertDepositContained(projectDir, deftDir);
     const resolveContent = seams.resolveContentRoot ?? resolveInstalledContentRoot;
     const copyContent = seams.copyContent ?? copyTree;
     const readEngine = seams.readEngineVersion ?? readCorePackageVersion;

package/dist/intake/issue-ingest.d.ts

@@ -1,7 +1,18 @@
+import { type ScanFlag } from "../cache/scanner.js";
 import { LEGACY_ARTIFACT_SUFFIX, LEGACY_INFO_ROOT_KEY, MIGRATED_ARTIFACT_SUFFIX, MIGRATED_INFO_ROOT_KEY } from "../xbrief-migrate/constants.js";
 import { type ScmCallFn } from "./reconcile-issues.js";
 export declare const INGEST_STATUSES: readonly ["proposed", "pending", "active"];
 export type IngestStatus = (typeof INGEST_STATUSES)[number];
+/**
+ * Thrown when the quarantine scanner hard-fails (credential-shaped content) on
+ * an ingested issue body/comment thread (#2306). Ingest MUST fail closed: emit
+ * nothing and propagate a non-zero exit rather than persisting the xBRIEF.
+ */
+export declare class ScannerHardFailError extends Error {
+    readonly issueNumber: number;
+    readonly flags: readonly ScanFlag[];
+    constructor(issueNumber: number, flags: readonly ScanFlag[]);
+}
 /** GitHub issue comment thread entry (REST `repos/.../issues/N/comments`). */
 export interface IssueComment {
     readonly id?: number;