@deftai/directive-core 0.88.0 → 0.89.0

package/dist/branch/evaluate.js

@@ -1,6 +1,7 @@
 import { recordBypassSignal, recordGateCatch } from "../events/attribution-ledger.js";
 import { disclosureLine } from "../policy/disclosure.js";
 import { policyColonInvocation } from "../policy/policy-invocation.js";
+import { humanMergeBranchNote, resolveHumanMergePolicy } from "../policy/require-human-merge.js";
 import { ENV_BYPASS, resolvePolicy } from "../policy/resolve.js";
 import { currentBranch, GitNotFoundError } from "./git.js";
 export const DEFAULT_BRANCHES = new Set(["master", "main"]);
@@ -93,9 +94,13 @@ export function evaluate(projectRoot, options = {}) {
         };
     }
     if (!isDefaultBranch(branch, defaultBranches)) {
+        // Surface (2) human-merge gate: advisory note on feature branches (#1193).
+        const hm = resolveHumanMergePolicy(projectRoot);
+        const hmNote = humanMergeBranchNote(hm);
+        const base = `✓ deft branch-protection: feature branch '${branch}' -- proceeding.`;
         return {
             exitCode: 0,
-            message: `✓ deft branch-protection: feature branch '${branch}' -- proceeding.`,
+            message: hmNote !== null ? `${base}\n${hmNote}` : base,
         };
     }
     const result = resolvePolicy(projectRoot);

package/dist/cache/fetch.js

@@ -1,6 +1,6 @@
-import { existsSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { join, resolve } from "node:path";
-import { assertWriteTargetSafe, ProjectionContainmentError } from "../fs/projection-containment.js";
+import { ContainedWriteError, containedWrite } from "../fs/contained-write.js";
 import { GhRestError, InvalidRepoError, restIssueView, runGhApi, } from "../scm/gh-rest.js";
 import { DEFAULT_BATCH_SIZE, DEFAULT_DELAY_MS } from "./constants.js";
 import { CacheError, CacheFetchError } from "./errors.js";
@@ -622,8 +622,13 @@ function readSelfHealState(cacheRoot) {
 }
 function writeSelfHealState(projectRoot, cacheRoot, when) {
     const path = join(resolve(cacheRoot), SELF_HEAL_STATE_FILENAME);
-    assertWriteTargetSafe(projectRoot, path);
-    writeFileSync(path, `${JSON.stringify({ last_reconcile_at: when.toISOString() })}\n`, "utf8");
+    // #2980 wave C: product write sink routes through containedWrite.
+    containedWrite({
+        root: resolve(projectRoot),
+        target: path,
+        data: `${JSON.stringify({ last_reconcile_at: when.toISOString() })}\n`,
+        mode: "replace",
+    });
 }
 /** TTL-bounded closed-reconcile for session ritual / triage:welcome self-healing (#1886). */
 export function maybeSelfHealCache(projectRoot, options = {}) {
@@ -679,7 +684,7 @@ export function maybeSelfHealCache(projectRoot, options = {}) {
                 writeSelfHealState(projectRoot, cacheRoot, now);
             }
             catch (err) {
-                if (err instanceof ProjectionContainmentError) {
+                if (err instanceof ContainedWriteError) {
                     return { skipped: true, skipReason: "containment-refused", drift, refresh: null };
                 }
                 throw err;

package/dist/cache/io.d.ts

@@ -1,7 +1,14 @@
 import { tmpdir } from "node:os";
-/** Write text via tempfile + rename (mirrors Python `_atomic_write_text`). */
+/**
+ * Write text via tempfile + rename (mirrors Python `_atomic_write_text`).
+ * #2951 Phase 2: temp payload write uses containedWrite under the parent dir.
+ */
 export declare function atomicWriteText(path: string, text: string): void;
-/** Append one JSON audit record (mirrors `_append_audit`). */
+/**
+ * Append one JSON audit record (mirrors `_append_audit`).
+ * #2951 Phase 2: product write sink routes through containedWrite.
+ * Create cacheRoot first — containedWrite requires the containment root to exist.
+ */
 export declare function appendAudit(record: Record<string, unknown>, cacheRoot: string): void;
 /** Touch mtime for LRU signal; failures swallowed. */
 export declare function touchMtime(path: string): void;

package/dist/cache/io.js

@@ -1,14 +1,25 @@
 import { randomBytes } from "node:crypto";
-import { appendFileSync, mkdirSync, renameSync, rmSync, statSync, utimesSync, writeFileSync, } from "node:fs";
+import { mkdirSync, renameSync, rmSync, statSync, utimesSync } from "node:fs";
 import { tmpdir } from "node:os";
-import { dirname, join } from "node:path";
+import { basename, dirname, join, resolve } from "node:path";
+import { containedWrite } from "../fs/contained-write.js";
 import { pythonJsonLine } from "./json.js";
-/** Write text via tempfile + rename (mirrors Python `_atomic_write_text`). */
+/**
+ * Write text via tempfile + rename (mirrors Python `_atomic_write_text`).
+ * #2951 Phase 2: temp payload write uses containedWrite under the parent dir.
+ */
 export function atomicWriteText(path, text) {
-    mkdirSync(dirname(path), { recursive: true });
-    const tmp = join(dirname(path), `${path.split(/[/\\]/).pop() ?? "file"}.${randomBytes(4).toString("hex")}.tmp`);
+    const dir = dirname(path);
+    mkdirSync(dir, { recursive: true });
+    const tmpName = `${basename(path)}.${randomBytes(4).toString("hex")}.tmp`;
+    const tmp = join(dir, tmpName);
     try {
-        writeFileSync(tmp, text, { encoding: "utf8" });
+        containedWrite({
+            root: resolve(dir),
+            target: tmpName,
+            data: text,
+            mode: "create",
+        });
         renameSync(tmp, path);
     }
     catch (err) {
@@ -21,11 +32,20 @@ export function atomicWriteText(path, text) {
         throw err;
     }
 }
-/** Append one JSON audit record (mirrors `_append_audit`). */
+/**
+ * Append one JSON audit record (mirrors `_append_audit`).
+ * #2951 Phase 2: product write sink routes through containedWrite.
+ * Create cacheRoot first — containedWrite requires the containment root to exist.
+ */
 export function appendAudit(record, cacheRoot) {
-    const path = join(cacheRoot, "quarantine-audit.jsonl");
-    mkdirSync(dirname(path), { recursive: true });
-    appendFileSync(path, `${pythonJsonLine(record)}\n`, { encoding: "utf8" });
+    const root = resolve(cacheRoot);
+    mkdirSync(root, { recursive: true });
+    containedWrite({
+        root,
+        target: "quarantine-audit.jsonl",
+        data: `${pythonJsonLine(record)}\n`,
+        mode: "append",
+    });
 }
 /** Touch mtime for LRU signal; failures swallowed. */
 export function touchMtime(path) {

package/dist/cache/task-cache/store.js

@@ -1,6 +1,6 @@
-import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
-import { dirname, join, resolve } from "node:path";
-import { assertWriteTargetSafe } from "../../fs/projection-containment.js";
+import { existsSync, readFileSync, rmSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { containedWrite } from "../../fs/contained-write.js";
 import { DEFAULT_TASK_CACHE_ROOT, TASK_CACHE_MANIFEST } from "./constants.js";
 function entryDir(projectRoot, cacheKey, cacheRoot = DEFAULT_TASK_CACHE_ROOT) {
     return join(resolve(projectRoot), cacheRoot, cacheKey.slice(0, 2), cacheKey);
@@ -22,12 +22,16 @@ export function writeCachedTaskRecord(projectRoot, cacheKey, record, cacheRoot =
     if (record.exitCode !== 0) {
         return;
     }
+    const root = resolve(projectRoot);
     const dir = entryDir(projectRoot, cacheKey, cacheRoot);
     const manifest = join(dir, TASK_CACHE_MANIFEST);
-    assertWriteTargetSafe(resolve(projectRoot), dir);
-    mkdirSync(dirname(manifest), { recursive: true });
-    assertWriteTargetSafe(resolve(projectRoot), manifest);
-    writeFileSync(manifest, `${JSON.stringify(record, null, 2)}\n`, "utf8");
+    // #2951 Phase 2: product write sink routes through containedWrite (mkdir + replace).
+    containedWrite({
+        root,
+        target: manifest,
+        data: `${JSON.stringify(record, null, 2)}\n`,
+        mode: "replace",
+    });
 }
 export function clearTaskCache(projectRoot, cacheRoot = DEFAULT_TASK_CACHE_ROOT) {
     const root = join(resolve(projectRoot), cacheRoot);

package/dist/capacity/backfill.js

@@ -1,9 +1,9 @@
 import { execFileSync } from "node:child_process";
-import { existsSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { join, resolve } from "node:path";
 import { referenceTypeMatches } from "@deftai/directive-types";
 import { sortedStringifyCompact } from "../codebase/json.js";
-import { assertWriteTargetSafe } from "../fs/projection-containment.js";
+import { containedWrite } from "../fs/contained-write.js";
 import { hasArtifactSuffix, resolveLifecycleFolder } from "../layout/resolve.js";
 import { classifyBucket, loadBucketMatchers, resolveCapacityAllocation, SOURCE_MATCH, } from "../policy/capacity.js";
 export const COMPLETED_FOLDER = "completed";
@@ -139,7 +139,7 @@ function inWindow(completedAt, windowDays, now) {
     return ageDays >= 0 && ageDays <= windowDays;
 }
 function writeMetadata(projectRoot, path, data, plan, metadata, options) {
-    assertWriteTargetSafe(projectRoot, path);
+    // #2980 wave D: product write sink routes through containedWrite.
     if (typeof plan.metadata !== "object" || plan.metadata === null || Array.isArray(plan.metadata)) {
         plan.metadata = metadata;
     }
@@ -152,7 +152,13 @@ function writeMetadata(projectRoot, path, data, plan, metadata, options) {
             metadata.capacityBucketSource = options.source;
         }
     }
-    writeFileSync(path, `${JSON.stringify(data, null, 2)}\n`, { encoding: "utf8" });
+    const root = resolve(projectRoot);
+    containedWrite({
+        root,
+        target: path,
+        data: `${JSON.stringify(data, null, 2)}\n`,
+        mode: "replace",
+    });
 }
 /** Backfill capacityBucket / completedAt on completed vBRIEFs. */
 export async function backfill(projectRoot, options = {}) {

package/dist/category-b-namespace/index.js

@@ -9,9 +9,10 @@
  * order-preserving (the namespaced key takes the legacy key's slot, keeping
  * artifact diffs minimal).
  */
-import { existsSync, lstatSync, readdirSync, readFileSync, writeFileSync, } from "node:fs";
+import { existsSync, lstatSync, readdirSync, readFileSync } from "node:fs";
 import { join, relative, resolve } from "node:path";
-import { assertDirectoryNotSymlink, assertWriteTargetSafe } from "../fs/projection-containment.js";
+import { containedWrite } from "../fs/contained-write.js";
+import { assertDirectoryNotSymlink } from "../fs/projection-containment.js";
 import { hasArtifactSuffix, resolveLifecycleRoot } from "../layout/resolve.js";
 import { LEGACY_PLAN_COMPLETED_NOTE_KEY, LEGACY_PLAN_POLICY_KEY, PLAN_COMPLETED_NOTE_KEY, PLAN_POLICY_KEY, } from "../policy/plan-extensions.js";
 /** The locked Category B renames (#1650): directive's own config, not xbrief data. */
@@ -141,7 +142,13 @@ export function migrateCategoryBCorpus(projectRoot) {
         }
         if (result.changed) {
             try {
-                assertWriteTargetSafe(root, file);
+                // #2980 wave D: product write sink routes through containedWrite.
+                containedWrite({
+                    root,
+                    target: file,
+                    data: `${JSON.stringify(result.doc, null, 2)}\n`,
+                    mode: "replace",
+                });
             }
             catch (err) {
                 conflicts.push({
@@ -150,7 +157,6 @@ export function migrateCategoryBCorpus(projectRoot) {
                 });
                 continue;
             }
-            writeFileSync(file, `${JSON.stringify(result.doc, null, 2)}\n`, "utf8");
             changed.push(relPath);
         }
     }

package/dist/codebase/default-extractor.js

@@ -20,6 +20,9 @@ export const SKIP_DIRS = new Set([
     "build",
     "dist",
     "node_modules",
+    // Swarm / agent worktrees are not source modules (#2953, #1656).
+    ".deft-scratch",
+    // Legacy swarm worktree root name (pre-.deft-scratch layout).
     "swarm-worktrees",
 ]);
 export const LANGUAGE_BY_SUFFIX = {

package/dist/codebase/map.js

@@ -1,5 +1,6 @@
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import { dirname, isAbsolute, join, relative, resolve } from "node:path";
+import { existsSync, readFileSync } from "node:fs";
+import { isAbsolute, join, relative, resolve } from "node:path";
+import { containedWrite } from "../fs/contained-write.js";
 import { assertProjectionContained } from "../fs/projection-containment.js";
 import { resolveProjectDefinitionPath } from "../layout/resolve.js";
 import { extractCodeStructure, loadJsonFile } from "../verify-source/code-structure-validate.js";
@@ -249,8 +250,14 @@ export function writeCodebaseMap(projectRoot, options) {
         artifactPath: options.artifactPath,
     });
     const document = renderCodebaseMap(selection.artifact);
-    mkdirSync(dirname(resolvedOutput), { recursive: true });
-    writeFileSync(resolvedOutput, document, { encoding: "utf8" });
+    // #2980 wave D: product write sink routes through containedWrite.
+    const root = resolve(projectRoot);
+    containedWrite({
+        root,
+        target: resolvedOutput,
+        data: document,
+        mode: "replace",
+    });
     return resolvedOutput;
 }
 export function runCodebaseMapCli(argv) {

package/dist/doctor/doctor-state.js

@@ -1,6 +1,7 @@
-import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { mkdirSync, readFileSync } from "node:fs";
 import { homedir } from "node:os";
-import { dirname, join } from "node:path";
+import { basename, dirname, isAbsolute, join, relative, resolve } from "node:path";
+import { containedWrite } from "../fs/contained-write.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";
@@ -57,8 +58,31 @@ export function writeState(projectRoot, payload) {
     };
     const path = statePath(projectRoot);
     try {
-        mkdirSync(dirname(path), { recursive: true });
-        writeFileSync(path, `${JSON.stringify(body, null, 2)}\n`, "utf8");
+        // #2980 wave C: product write sink routes through containedWrite.
+        // Default path is under the project triage cache; ENV_STATE_PATH may point outside.
+        const projectAbs = resolve(projectRoot);
+        const pathAbs = resolve(path);
+        const rel = relative(projectAbs, pathAbs);
+        const nested = rel.length > 0 && !rel.startsWith("..") && !isAbsolute(rel);
+        const payload = `${JSON.stringify(body, null, 2)}\n`;
+        if (nested) {
+            containedWrite({
+                root: projectAbs,
+                target: pathAbs,
+                data: payload,
+                mode: "replace",
+            });
+        }
+        else {
+            const parent = dirname(pathAbs);
+            mkdirSync(parent, { recursive: true });
+            containedWrite({
+                root: resolve(parent),
+                target: basename(pathAbs),
+                data: payload,
+                mode: "replace",
+            });
+        }
         return path;
     }
     catch {

package/dist/doctor/main.d.ts

@@ -4,6 +4,16 @@ import type { DoctorSeams, Finding, ResolutionSummary } from "./types.js";
 export declare function cmdDoctor(args: readonly string[], seams?: DoctorSeams): number;
 export declare function runAgentHooksHealthCheck(projectRoot: string, consumerContext: boolean, sink: ReturnType<typeof createPlainSink>, addFinding: (finding: Finding) => void, seams: DoctorSeams): boolean;
 export declare function runAgentHooksLiveProbeCheck(projectRoot: string, sink: ReturnType<typeof createPlainSink>, addFinding: (finding: Finding) => void, seams: DoctorSeams): void;
+/**
+ * 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.
+ */
+export declare function runXbriefEnvelopeVersionCheck(projectRoot: string, sink: ReturnType<typeof createPlainSink>, addFinding: (f: Finding) => void, seams: DoctorSeams): void;
 /**
  * Never emit a bare `task ...` remediation in a project without Taskfile wiring
  * (#2267 / #2893). The `directive`/`deft` surface always works; `task deft:X` is

package/dist/doctor/main.js

@@ -1,14 +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 { contentRoot } from "../content-root.js";
+import { resolveProjectDefinitionPath } from "../layout/resolve.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 { 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";
@@ -24,6 +28,8 @@ 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
@@ -341,6 +347,11 @@ export function cmdDoctor(args, seams = {}) {
     }
     sink.info("Checking gates-surface readiness (Taskfile include for deep-think agent gates)...");
     runTaskfileIncludeCheck(projectRoot, fixMode, jsonMode, sink, addFinding, seams);
+    if (!jsonMode) {
+        sink.blank();
+    }
+    sink.info("Checking xBRIEF project envelope version...");
+    runXbriefEnvelopeVersionCheck(projectRoot, sink, addFinding, seams);
     let resolution = null;
     if (!runningInsideDeftRepo(projectRoot, seams)) {
         if (!jsonMode) {
@@ -770,6 +781,155 @@ function runTaskfileIncludeCheck(projectRoot, fixMode, jsonMode, sink, addFindin
         suggestion: GATES_SURFACE_DEFT_REMEDIATION,
     });
 }
+/**
+ * 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.
+ */
+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;
+    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`;
+        sink.info(skipMessage);
+        addFinding({
+            severity: "skip",
+            message: skipMessage,
+            check: checkName,
+            status: "skip",
+            reason: "unreadable",
+        });
+        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);
+            addFinding({
+                severity: "skip",
+                message: skipMessage,
+                check: checkName,
+                status: "skip",
+                reason: "invalid-json-shape",
+            });
+            return;
+        }
+    }
+    catch {
+        const skipMessage = `${checkName}: skip -- PROJECT-DEFINITION JSON parse failed`;
+        sink.info(skipMessage);
+        addFinding({
+            severity: "skip",
+            message: skipMessage,
+            check: checkName,
+            status: "skip",
+            reason: "parse-error",
+        });
+        return;
+    }
+    const distance = classifyXbriefSchemaDistance(declaredVersion, targetVersion);
+    emitXbriefEnvelopeFinding(checkName, {
+        declaredVersion,
+        targetVersion,
+        distance,
+        stale: distance !== "current",
+    }, sink, addFinding);
+}
+function emitXbriefEnvelopeFinding(checkName, probe, sink, addFinding) {
+    if (probe.distance === "current") {
+        const okMessage = `${checkName}: current -- xBRIEFInfo@${probe.declaredVersion ?? probe.targetVersion} ` +
+            `(framework ${probe.targetVersion})`;
+        sink.success(okMessage);
+        addFinding({
+            severity: "skip",
+            message: okMessage,
+            check: checkName,
+            status: "current",
+            declared_version: probe.declaredVersion,
+            target_version: probe.targetVersion,
+        });
+        return;
+    }
+    if (probe.distance === "behind-minor") {
+        const warnMessage = `${checkName}: behind-minor -- declared ${probe.declaredVersion ?? "unknown"}, ` +
+            `framework ${probe.targetVersion}. Prefer \`deft migrate:xbrief\` when convenient.`;
+        sink.warn(warnMessage);
+        addFinding({
+            severity: "warning",
+            message: warnMessage,
+            check: checkName,
+            status: "behind-minor",
+            suggestion: XBRIEF_ENVELOPE_MIGRATE_COMMAND,
+            declared_version: probe.declaredVersion,
+            target_version: probe.targetVersion,
+            next_command: XBRIEF_ENVELOPE_MIGRATE_COMMAND,
+        });
+        return;
+    }
+    // behind-major (declared 0.6 vs framework 0.8, dual half-state, missing version)
+    const nextCommand = XBRIEF_ENVELOPE_MIGRATE_COMMAND;
+    const message = `${checkName}: behind-major -- declared ${probe.declaredVersion ?? "unknown"}, ` +
+        `framework ${probe.targetVersion}. Next action: run \`${nextCommand}\` to bump project ` +
+        `JSON envelopes to xBRIEFInfo@${probe.targetVersion} (layout rename alone is not enough).`;
+    sink.error(message);
+    addFinding({
+        severity: "error",
+        message,
+        check: checkName,
+        status: "behind-major",
+        suggestion: nextCommand,
+        declared_version: probe.declaredVersion,
+        target_version: probe.targetVersion,
+        next_command: nextCommand,
+    });
+}
 /**
  * Surface the resolved USER.md path + which search rung matched (#2271) so the
  * resolution boundary is visible in doctor output. Uses the shared first-hit-

package/dist/doctor/types.d.ts

@@ -150,5 +150,16 @@ export interface DoctorSeams {
     readonly evaluateAgentHooks?: (projectRoot: string) => AgentHookHealthResult;
     /** Live hook spawn probe for doctor --full (#2852). */
     readonly probeAgentHooksLive?: (projectRoot: string) => AgentHookLiveProbeResult;
+    /**
+     * xBRIEF project-envelope staleness probe (#2971). Injected so doctor can
+     * fail closed on 0.6 project JSON under an xbrief/ layout without re-deriving
+     * the shared `probeXbriefStaleness` path in tests.
+     */
+    readonly probeXbriefEnvelope?: (projectRoot: string) => {
+        readonly declaredVersion: string | null;
+        readonly targetVersion: string;
+        readonly distance: "current" | "behind-minor" | "behind-major";
+        readonly stale: boolean;
+    };
 }
 //# sourceMappingURL=types.d.ts.map

package/dist/escalation/actions.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Operator-facing escalation actions: file, list, resolve, batch-approve (#518).
+ */
+import { type EscalationEvent, type EscalationType } from "./types.js";
+export interface FileEscalationInput {
+    readonly projectRoot: string;
+    readonly type: string;
+    readonly title: string;
+    readonly body?: string;
+    readonly agentId?: string;
+    readonly contextRefs?: readonly string[];
+    readonly slaHours?: number;
+    readonly dangerous?: boolean;
+    readonly id?: string;
+    readonly now?: Date;
+}
+export declare function fileEscalation(input: FileEscalationInput): EscalationEvent;
+export interface ResolveEscalationInput {
+    readonly projectRoot: string;
+    readonly id: string;
+    readonly decision: string;
+    readonly actor?: string;
+    readonly note?: string | null;
+    readonly answer?: string | null;
+    readonly now?: Date;
+}
+export type ResolveEscalationResult = {
+    readonly ok: true;
+    readonly event: EscalationEvent;
+} | {
+    readonly ok: false;
+    readonly code: "not-found" | "already-resolved" | "invalid-decision";
+    readonly message: string;
+};
+export declare function resolveEscalation(input: ResolveEscalationInput): ResolveEscalationResult;
+export interface BatchApproveInput {
+    readonly projectRoot: string;
+    /** Limit to these ids; empty/undefined = all open batch-eligible. */
+    readonly ids?: readonly string[];
+    readonly actor?: string;
+    readonly note?: string | null;
+    /** When false (default), skip `dangerous: true` items. */
+    readonly includeDangerous?: boolean;
+    readonly now?: Date;
+}
+export interface BatchApproveResult {
+    readonly approved: EscalationEvent[];
+    readonly skipped: Array<{
+        id: string;
+        reason: string;
+    }>;
+}
+/**
+ * Bulk-approve only `cmd_approval` and `question` open items.
+ * design_decision / approval / resource / external must use individual resolve.
+ * Dangerous items are skipped unless `includeDangerous` is true.
+ */
+export declare function batchApproveEscalations(input: BatchApproveInput): BatchApproveResult;
+export declare function listEscalationsFiltered(projectRoot: string, opts?: {
+    openOnly?: boolean;
+    type?: EscalationType;
+}): EscalationEvent[];
+//# sourceMappingURL=actions.d.ts.map