@deftai/directive-core 0.83.0 → 0.85.0

package/dist/review-monitor/verify.js

@@ -1,8 +1,9 @@
 import { existsSync, statSync } from "node:fs";
 import { resolve } from "node:path";
 import { sweepScratchDirs } from "../orchestration/subagent-monitor.js";
+import { resolveRepo } from "../triage/queue/repo.js";
 import { EXIT_CONFIG_ERROR, EXIT_NOT_READY, EXIT_READY, MONITORING_TIER_1, MONITORING_TIER_3, } from "./constants.js";
-import { defaultSubagentStatusDir, findActiveMonitorForPr, readReviewMonitorFile, reviewMonitorPath, } from "./record.js";
+import { defaultSubagentStatusDir, fetchActiveMonitorFromGithub, readReviewMonitorFile, reviewMonitorPath, } from "./record.js";
 import { isTier1, probeMonitoringTier } from "./tier-detection.js";
 function spawnRedirect(probe) {
     const primitive = probe.primitive ?? "sub-agent";
@@ -59,6 +60,8 @@ export function evaluateReviewMonitorGate(args) {
     const callSite = args.callSite ?? "unspecified";
     const staleMinutes = args.staleMinutes ?? 30;
     const now = args.now ?? new Date();
+    // Legacy `.deft/review-monitor.json` is obsolete (#2814); explicit no-op read documents migration.
+    readReviewMonitorFile(reviewMonitorPath(projectRoot));
     if (args.approach3 === true) {
         if (isTier1(tier)) {
             return {
@@ -103,33 +106,43 @@ export function evaluateReviewMonitorGate(args) {
             callSite,
         };
     }
-    const path = reviewMonitorPath(projectRoot);
-    const { data, error } = readReviewMonitorFile(path);
-    if (data === null) {
+    const repo = resolveRepo(args.repo ?? null, projectRoot);
+    if (repo === null) {
         return {
             exitCode: EXIT_CONFIG_ERROR,
-            message: `verify_review_monitor: ${error ?? "could not read review-monitor state"}`,
+            message: "verify_review_monitor: could not resolve owner/repo — pass --repo OWNER/REPO or run inside a git repo with origin",
             tier,
             monitorRecord: null,
             heartbeatActive: false,
             callSite,
         };
     }
-    const monitorRecord = findActiveMonitorForPr(data, args.pr, {
+    const githubMonitor = fetchActiveMonitorFromGithub(repo, args.pr, {
         now,
-        staleMinutes,
         headSha: args.headSha ?? null,
+        seams: args.seams,
     });
+    if (githubMonitor !== null && typeof githubMonitor === "object" && "error" in githubMonitor) {
+        return {
+            exitCode: EXIT_CONFIG_ERROR,
+            message: `verify_review_monitor: ${githubMonitor.error}`,
+            tier,
+            monitorRecord: null,
+            heartbeatActive: false,
+            callSite,
+        };
+    }
+    const monitorRecord = githubMonitor;
     const heartbeatActive = hasActivePollingHeartbeat(projectRoot, args.pr, {
         now,
         staleMinutes,
     });
-    if (monitorRecord !== null || heartbeatActive) {
-        const via = monitorRecord !== null ? "review-monitor record" : "subagent heartbeat";
+    if (monitorRecord !== null) {
         return {
             exitCode: EXIT_READY,
-            message: `verify_review_monitor: active review-monitor for PR #${args.pr} via ${via} ` +
-                `(call-site=${callSite}, tier=1, descriptor=${tier.descriptor ?? "unknown"}).`,
+            message: `verify_review_monitor: active GitHub review-owner lease for PR #${args.pr} ` +
+                `(monitor_agent_id=${monitorRecord.monitor_agent_id}, owner=${monitorRecord.owner}, ` +
+                `call-site=${callSite}, tier=1, descriptor=${tier.descriptor ?? "unknown"}).`,
             tier,
             monitorRecord,
             heartbeatActive,
@@ -141,15 +154,20 @@ export function evaluateReviewMonitorGate(args) {
         : callSite === "swarm-phase6-cascade"
             ? "Swarm Phase 6 post force-push (#380)"
             : "Solo drive-to merge-ready / review-cycle ownership";
+    const heartbeatHint = heartbeatActive
+        ? "  Note: local subagent heartbeat is present but is not a GitHub review-owner lease (#2814).\n"
+        : "";
     return {
         exitCode: EXIT_NOT_READY,
-        message: `verify_review_monitor: Tier 1 available but no active review-monitor for PR #${args.pr} (#2655).\n` +
+        message: `verify_review_monitor: Tier 1 available but no active GitHub review-owner lease for PR #${args.pr} (#2814).\n` +
+            heartbeatHint +
             `  Call site: ${siteHint}.\n` +
             `  Detected descriptor=${tier.descriptor ?? "unknown"} primitive=${tier.primitive ?? "none"}.\n` +
+            `  Legacy .deft/review-monitor.json is ignored.\n` +
             `  ${spawnRedirect(tier)}`,
         tier,
         monitorRecord: null,
-        heartbeatActive: false,
+        heartbeatActive,
         callSite,
     };
 }
@@ -160,6 +178,7 @@ export function verifyResultToJson(result) {
         heartbeat_active: result.heartbeatActive,
         message: result.message,
         monitor_agent_id: result.monitorRecord?.monitor_agent_id ?? null,
+        monitor_owner: result.monitorRecord?.owner ?? null,
         monitor_record: result.monitorRecord,
         ready: result.exitCode === EXIT_READY,
         tier: result.tier.tier,

package/dist/scm/gh-rest.d.ts

@@ -53,9 +53,15 @@ export interface RestIssueListOptions {
 export declare function restIssueList(repo: string, options?: RestIssueListOptions, seams?: GhRestSeams): Record<string, unknown>[];
 export declare const REST_MAX_PER_PAGE = 100;
 export declare const REST_PAGINATION_MAX_PAGES = 100;
-export declare const PUBLIC_HELPERS: readonly ["restCreateIssue", "restPostComment", "restUpdateIssue", "restCreateLabel", "restCloseIssue", "restOpenPr", "restMergePr", "restIssueView", "restPrView", "restIssueList", "restIssueListPaginated"];
+export declare const PUBLIC_HELPERS: readonly ["restCreateIssue", "restPostComment", "restUpdateComment", "restDeleteComment", "restGetUser", "restUpdateIssue", "restCreateLabel", "restCloseIssue", "restOpenPr", "restMergePr", "restIssueView", "restPrView", "restIssueList", "restIssueListPaginated"];
 export declare function restCreateIssue(repo: string, title: string, body: string, labels?: readonly string[], seams?: GhRestSeams): Record<string, unknown>;
 export declare function restPostComment(repo: string, n: number, body: string, seams?: GhRestSeams): Record<string, unknown>;
+/** `PATCH /repos/{owner}/{repo}/issues/comments/{id}` -- edit a PR/issue comment in place. */
+export declare function restUpdateComment(repo: string, commentId: number, body: string, seams?: GhRestSeams): Record<string, unknown>;
+/** `DELETE /repos/{owner}/{repo}/issues/comments/{id}` -- remove a duplicate claim comment. */
+export declare function restDeleteComment(repo: string, commentId: number, seams?: GhRestSeams): Record<string, unknown>;
+/** `GET /user` -- authenticated GitHub login for review-owner claims. */
+export declare function restGetUser(seams?: GhRestSeams): Record<string, unknown>;
 export declare function restUpdateIssue(repo: string, n: number, patch: Record<string, unknown>, seams?: GhRestSeams): Record<string, unknown>;
 export declare function restCreateLabel(repo: string, name: string, color: string, description: string, seams?: GhRestSeams): Record<string, unknown>;
 export declare function restCloseIssue(repo: string, n: number, reason?: string | null, seams?: GhRestSeams): Record<string, unknown>;

package/dist/scm/gh-rest.js

@@ -171,6 +171,9 @@ export const REST_PAGINATION_MAX_PAGES = 100;
 export const PUBLIC_HELPERS = [
     "restCreateIssue",
     "restPostComment",
+    "restUpdateComment",
+    "restDeleteComment",
+    "restGetUser",
     "restUpdateIssue",
     "restCreateLabel",
     "restCloseIssue",
@@ -226,6 +229,38 @@ export function restPostComment(repo, n, body, seams = {}) {
         ...seams,
     });
 }
+/** `PATCH /repos/{owner}/{repo}/issues/comments/{id}` -- edit a PR/issue comment in place. */
+export function restUpdateComment(repo, commentId, body, seams = {}) {
+    const [owner, name] = splitRepo(repo);
+    const endpoint = `repos/${owner}/${name}/issues/comments/${commentId}`;
+    return execMutation([endpoint, "--method", "PATCH"], {
+        endpoint,
+        payload: { body },
+        hint: "verify repo permissions and comment id; check gh auth status",
+        ...seams,
+    });
+}
+/** `DELETE /repos/{owner}/{repo}/issues/comments/{id}` -- remove a duplicate claim comment. */
+export function restDeleteComment(repo, commentId, seams = {}) {
+    const [owner, name] = splitRepo(repo);
+    const endpoint = `repos/${owner}/${name}/issues/comments/${commentId}`;
+    return execMutation([endpoint, "--method", "DELETE"], {
+        endpoint,
+        payload: {},
+        hint: "verify repo permissions and comment id; check gh auth status",
+        ...seams,
+    });
+}
+/** `GET /user` -- authenticated GitHub login for review-owner claims. */
+export function restGetUser(seams = {}) {
+    return execApi(["user"], {
+        endpoint: "user",
+        payload: null,
+        hint: "verify gh auth status (`gh auth login`)",
+        runGhApiFn: seams.runGhApiFn,
+        whichFn: seams.whichFn,
+    });
+}
 export function restUpdateIssue(repo, n, patch, seams = {}) {
     const [owner, name] = splitRepo(repo);
     const endpoint = `repos/${owner}/${name}/issues/${n}`;

package/dist/scope/decompose.js

@@ -9,6 +9,7 @@
 import { accessSync, constants, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { basename, dirname, isAbsolute, join, resolve, sep } from "node:path";
 import { referenceTypeMatches } from "@deftai/directive-types";
+import { assertWriteTargetSafe, ProjectionContainmentError } from "../fs/projection-containment.js";
 import { hasArtifactSuffix, LEGACY_ARTIFACT_DIR, MIGRATED_ARTIFACT_DIR, resolveLifecycleRoot, } from "../layout/resolve.js";
 import { referenceWithDefaultTrust, slugify } from "../vbrief-build/build.js";
 import { EMITTED_VBRIEF_VERSION } from "../vbrief-build/constants.js";
@@ -52,7 +53,8 @@ function loadJson(path) {
     }
     return data;
 }
-function writeJson(path, data) {
+function writeJson(projectRoot, path, data) {
+    assertWriteTargetSafe(projectRoot, path);
     mkdirSync(dirname(path), { recursive: true });
     writeFileSync(path, formatBriefJson(data), "utf8");
 }
@@ -871,7 +873,7 @@ export function applyDecomposition(opts) {
     }
     for (let i = 0; i < childPaths.length; i += 1) {
         // biome-ignore lint/style/noNonNullAssertion: loop bound ensures these exist
-        writeJson(childPaths[i].target, childDocs[i]);
+        writeJson(projectRoot, childPaths[i].target, childDocs[i]);
     }
     let parentPlan = parent.plan;
     if (parentPlan === null || parentPlan === undefined) {
@@ -911,7 +913,7 @@ export function applyDecomposition(opts) {
     planObj.references = dedupeReferences(references
         .filter((r) => typeof r === "object" && r !== null && !Array.isArray(r))
         .map((r) => r));
-    writeJson(parentPath, parent);
+    writeJson(projectRoot, parentPath, parent);
     actions.push(`UPDATE ${parentRel} references`);
     return actions;
 }
@@ -1022,6 +1024,10 @@ export function decomposeMain(argv) {
             process.stderr.write(`ERROR: ${err.message}\n`);
             return 1;
         }
+        if (err instanceof ProjectionContainmentError) {
+            process.stderr.write(`ERROR: ${err.message}\n`);
+            return 2;
+        }
         process.stderr.write(`ERROR: ${String(err)}\n`);
         return 1;
     }

package/dist/session/git.d.ts

@@ -10,5 +10,7 @@ export declare function gitHead(projectRoot: string, runGit?: GitRunner): {
     error: string | null;
 };
 export declare function worktreePath(projectRoot: string, runGit?: GitRunner): string;
+/** True when `ancestor` is reachable from `descendant` (same commit counts). */
+export declare function gitIsAncestor(projectRoot: string, ancestor: string, descendant: string, runGit?: GitRunner): boolean | null;
 export declare function detectBranch(projectRoot: string, runGit?: GitRunner): string | null;
 //# sourceMappingURL=git.d.ts.map

package/dist/session/git.js

@@ -35,6 +35,20 @@ export function worktreePath(projectRoot, runGit = defaultGitRunner) {
     }
     return resolve(projectRoot);
 }
+/** True when `ancestor` is reachable from `descendant` (same commit counts). */
+export function gitIsAncestor(projectRoot, ancestor, descendant, runGit = defaultGitRunner) {
+    if (ancestor === descendant) {
+        return true;
+    }
+    const { code } = runGit(projectRoot, ["merge-base", "--is-ancestor", ancestor, descendant]);
+    if (code === 0) {
+        return true;
+    }
+    if (code === 1) {
+        return false;
+    }
+    return null;
+}
 export function detectBranch(projectRoot, runGit = defaultGitRunner) {
     const sym = runGit(projectRoot, ["symbolic-ref", "--short", "HEAD"]);
     if (sym.code === 0 && sym.stdout.trim()) {

package/dist/session/session-start.js

@@ -5,6 +5,7 @@ import { MIGRATE_COMPLETION_NUDGE, shouldEmitMigrateNudge } from "../init-deposi
 import { detectEnvironmentContext, environmentContextToDict, formatEnvironmentContext, } from "../platform/shell-context.js";
 import { disclosureLine } from "../policy/disclosure.js";
 import { resolvePolicy } from "../policy/resolve.js";
+import { maybeFormatProductSignalConsentPrompt } from "../product-signal/consent-prompt.js";
 import { maybeRunStalenessTickler } from "../staleness-tickler/run.js";
 import { runDefaultMode } from "../triage/welcome/default-mode.js";
 import { resolveUserMdPath } from "../user-config/resolve-user-md.js";
@@ -380,6 +381,10 @@ export function runSessionStart(projectRoot, options = {}) {
     catch {
         // observability only — session start must not abort on transient eval readback I/O
     }
+    const consentPrompt = maybeFormatProductSignalConsentPrompt({ projectRoot });
+    if (consentPrompt.length > 0) {
+        lines.push(consentPrompt.trimEnd());
+    }
     const payload = newRitualStatePayload({
         sessionId: (options.newSessionId ?? randomUUID)(),
         gitHead: gitHeadValue,

package/dist/session/verify-session-ritual.js

@@ -1,6 +1,6 @@
 import { existsSync } from "node:fs";
 import { formatFrameworkCommand } from "../render/framework-commands.js";
-import { defaultGitRunner, gitHead, worktreePath } from "./git.js";
+import { defaultGitRunner, gitHead, gitIsAncestor, worktreePath } from "./git.js";
 import { pythonJsonDump } from "./json.js";
 import { ENV_SESSION_POSTURE, readOnlyPostureMessage, resolveSessionPosture, ritualStateIsPostureAuthority, } from "./posture.js";
 import { defaultRitualRunner } from "./ritual-entrypoint.js";
@@ -59,6 +59,10 @@ function runGatedStep(projectRoot, payload, stepName, runner, now) {
     }
     return null;
 }
+function headDriftRecoveryMessage() {
+    return (`session ritual state is stale because git HEAD changed discontinuously. ` +
+        `Run \`${formatFrameworkCommand(["session:start"])}\` again.`);
+}
 function evaluateLoadedState(projectRoot, state, input) {
     const runGit = input.runGit ?? defaultGitRunner;
     const { head: currentHead, error: headError } = gitHead(projectRoot, runGit);
@@ -73,10 +77,22 @@ function evaluateLoadedState(projectRoot, state, input) {
         ];
     }
     if (state.gitHead !== currentHead) {
-        return [
-            1,
-            `session ritual state is stale because git HEAD changed. Run \`${formatFrameworkCommand(["session:start"])}\` again.`,
-        ];
+        const forward = gitIsAncestor(projectRoot, state.gitHead, currentHead, runGit);
+        if (forward === null) {
+            return [2, "could not verify git history for session ritual"];
+        }
+        if (!forward) {
+            return [1, headDriftRecoveryMessage()];
+        }
+        if (input.rebindForwardHead) {
+            const payload = { ...state.raw, git_head: currentHead };
+            try {
+                writeRitualState(projectRoot, payload);
+            }
+            catch (exc) {
+                return [2, `could not rebind session ritual git HEAD: ${String(exc)}`];
+            }
+        }
     }
     const staleness = resolveSessionRitualStalenessHours(projectRoot);
     if (staleness.source === "default-on-error") {
@@ -157,6 +173,7 @@ export function inspectSessionRitual(projectRoot, options = {}) {
         tier,
         now: options.now ?? new Date(),
         runGit: options.runGit,
+        rebindForwardHead: false,
     });
     return {
         code,
@@ -246,6 +263,7 @@ export function verifySessionRitual(projectRoot, options = {}) {
             tier: "quick",
             now: instant,
             runGit: options.runGit,
+            rebindForwardHead: true,
         });
         if (precheckCode !== 0) {
             return {
@@ -259,6 +277,21 @@ export function verifySessionRitual(projectRoot, options = {}) {
                 ritualStateRequired,
             };
         }
+        const reloadedAfterPrecheck = readRitualState(projectRoot);
+        state = reloadedAfterPrecheck[0];
+        err = reloadedAfterPrecheck[1];
+        if (state === null) {
+            return {
+                code: 2,
+                message: err ?? "ritual state invalid after precheck",
+                tier,
+                statePath,
+                bypassed: false,
+                wouldFailCode: null,
+                posture,
+                ritualStateRequired,
+            };
+        }
         const payload = { ...state.raw };
         const gated = { ...payload.gated_steps };
         payload.gated_steps = gated;
@@ -303,6 +336,7 @@ export function verifySessionRitual(projectRoot, options = {}) {
         tier,
         now: instant,
         runGit: options.runGit,
+        rebindForwardHead: true,
     });
     if (isBypassed) {
         return {

package/dist/swarm/routing-set-cli.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 import { resolve } from "node:path";
 import { fileURLToPath } from "node:url";
+import { PROJECTION_CONTAINMENT_REFUSED_EXIT_CODE, ProjectionContainmentError, } from "../fs/projection-containment.js";
 import { getPlatformCapabilities } from "../intake/platform-capabilities.js";
 import { EXIT_CONFIG_ERROR, EXIT_OK } from "./constants.js";
 import { dispatchProviderFromRuntime, HARNESS_BOUND_PROVIDERS, ROUTING_MODE_HARNESS_DEFAULT, ROUTING_MODE_PINNED, resolveRoutingPath, SWARM_WORKER_ROLES, writeModelDecision, } from "./routing.js";
@@ -66,11 +67,21 @@ export function routingSetMain(argv = process.argv.slice(2)) {
             "so only --harness-default is recordable here.\n");
         return EXIT_CONFIG_ERROR;
     }
-    const path = resolveRoutingPath(resolve(projectRoot));
-    writeModelDecision(path, resolvedProvider, role, {
-        model,
-        mode: harnessDefault ? ROUTING_MODE_HARNESS_DEFAULT : ROUTING_MODE_PINNED,
-    });
+    const root = resolve(projectRoot);
+    const path = resolveRoutingPath(root);
+    try {
+        writeModelDecision(root, path, resolvedProvider, role, {
+            model,
+            mode: harnessDefault ? ROUTING_MODE_HARNESS_DEFAULT : ROUTING_MODE_PINNED,
+        });
+    }
+    catch (err) {
+        if (err instanceof ProjectionContainmentError) {
+            process.stderr.write(`ERROR: ${err.message}\n`);
+            return PROJECTION_CONTAINMENT_REFUSED_EXIT_CODE;
+        }
+        throw err;
+    }
     const modelText = model ?? "<harness default>";
     process.stdout.write(`Recorded route: provider '${resolvedProvider}', role '${role}' -> model ${modelText}.\n` +
         `Route file: ${path}\n`);

package/dist/swarm/routing.d.ts

@@ -62,5 +62,5 @@ export declare function resolveDispatchProvider(environ?: NodeJS.ProcessEnv): st
  * `decidedAt` when the caller did not supply one. Used by the interactive
  * resolver path (resolver step 5) and the `swarm:routing-set` task.
  */
-export declare function writeModelDecision(path: string, provider: string, role: string, decision: RouteDecision): void;
+export declare function writeModelDecision(projectRoot: string, path: string, provider: string, role: string, decision: RouteDecision): void;
 //# sourceMappingURL=routing.d.ts.map

package/dist/swarm/routing.js

@@ -16,6 +16,7 @@
 import { execFileSync } from "node:child_process";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, isAbsolute, join, resolve } from "node:path";
+import { assertWriteTargetSafe } from "../fs/projection-containment.js";
 /**
  * The fixed worker-role vocabulary (reused from #1531). No separate tier
  * vocabulary to start; decisions are strictly per-role.
@@ -201,9 +202,10 @@ function assertSafeRoutingKey(kind, key) {
  * `decidedAt` when the caller did not supply one. Used by the interactive
  * resolver path (resolver step 5) and the `swarm:routing-set` task.
  */
-export function writeModelDecision(path, provider, role, decision) {
+export function writeModelDecision(projectRoot, path, provider, role, decision) {
     assertSafeRoutingKey("provider", provider);
     assertSafeRoutingKey("role", role);
+    assertWriteTargetSafe(projectRoot, path);
     const { data } = loadRoutingFile(path);
     // Null-prototype write targets so a computed provider/role key can only ever
     // set an own property and can never reach `Object.prototype`, even if the

package/dist/task-surface/index.js

@@ -2,10 +2,24 @@ import { execFileSync } from "node:child_process";
 import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
 import { join, resolve } from "node:path";
 import { LEGACY_VBRIEF_VERSION } from "@deftai/directive-types";
+import { assertProjectionContained, assertWriteTargetSafe, ProjectionContainmentError, } from "../fs/projection-containment.js";
 const UNRELEASED_RE = /## \[Unreleased\][ \t]*\n([\s\S]*?)(?=\n## \[|$)/;
 const CHANGE_NAME_RE = /^[\w][\w-]*$/;
 const COMMIT_TYPES = "feat|fix|docs|chore|refactor|test|style|perf|ci|build|revert";
 const COMMIT_SUBJECT_RE = new RegExp(`^(${COMMIT_TYPES})(\\(.+\\))?!?: .+`);
+/** Refuse task-surface writes that escape via repo-controlled symlinks (#2807). */
+function projectionTarget(projectDir, ...relSegments) {
+    const target = join(resolve(projectDir), ...relSegments);
+    assertProjectionContained(projectDir, target);
+    return target;
+}
+function containmentExitCode(io, err) {
+    if (err instanceof ProjectionContainmentError) {
+        io.writeErr(`FAIL: ${err.message}\n`);
+        return 2;
+    }
+    return null;
+}
 function proposalTemplate(name) {
     return {
         vBRIEFInfo: { version: LEGACY_VBRIEF_VERSION },
@@ -67,19 +81,35 @@ export function runChangeInit(projectRoot, name, io) {
         io.writeOut("FAIL: Name must contain only alphanumeric characters, underscores, and hyphens\n");
         return 1;
     }
-    const base = join(resolve(projectRoot), "history", "changes", trimmed);
-    if (existsSync(base)) {
-        io.writeOut(`FAIL: ${base} already exists\n`);
-        return 1;
+    const projectAbs = resolve(projectRoot);
+    try {
+        const base = projectionTarget(projectAbs, join("history", "changes", trimmed));
+        if (existsSync(base)) {
+            io.writeOut(`FAIL: ${base} already exists\n`);
+            return 1;
+        }
+        const specsDir = join(base, "specs");
+        assertProjectionContained(projectAbs, specsDir);
+        mkdirSync(specsDir, { recursive: true });
+        const proposalPath = join(base, "proposal.xbrief.json");
+        const tasksPath = join(base, "tasks.xbrief.json");
+        assertWriteTargetSafe(projectAbs, proposalPath);
+        assertWriteTargetSafe(projectAbs, tasksPath);
+        writeFileSync(proposalPath, `${JSON.stringify(proposalTemplate(trimmed), null, 2)}\n`, "utf8");
+        writeFileSync(tasksPath, `${JSON.stringify(tasksTemplate(trimmed), null, 2)}\n`, "utf8");
+        io.writeOut(`OK: Created change proposal at ${base}/\n`);
+        for (const file of ["proposal.xbrief.json", "tasks.xbrief.json", "specs/"]) {
+            io.writeOut(`  - ${file}\n`);
+        }
+        return 0;
     }
-    mkdirSync(join(base, "specs"), { recursive: true });
-    writeFileSync(join(base, "proposal.xbrief.json"), `${JSON.stringify(proposalTemplate(trimmed), null, 2)}\n`, "utf8");
-    writeFileSync(join(base, "tasks.xbrief.json"), `${JSON.stringify(tasksTemplate(trimmed), null, 2)}\n`, "utf8");
-    io.writeOut(`OK: Created change proposal at ${base}/\n`);
-    for (const file of ["proposal.xbrief.json", "tasks.xbrief.json", "specs/"]) {
-        io.writeOut(`  - ${file}\n`);
+    catch (err) {
+        const code = containmentExitCode(io, err);
+        if (code !== null) {
+            return code;
+        }
+        throw err;
     }
-    return 0;
 }
 /** Port of ``task commit:lint`` inline Python (#2022 Phase 2). */
 export function runCommitLint(projectRoot, io) {
@@ -119,8 +149,18 @@ export function runInstallUninstall(projectRoot, io) {
     const filtered = lines.filter((line) => !line.startsWith("See deft/main.md") && !line.startsWith("Skills: deft/skills/"));
     const next = filtered.join("");
     if (next !== original) {
-        writeFileSync(path, next, "utf8");
-        io.writeOut("Removed deft entry from AGENTS.md\n");
+        try {
+            assertWriteTargetSafe(resolve(projectRoot), path);
+            writeFileSync(path, next, "utf8");
+            io.writeOut("Removed deft entry from AGENTS.md\n");
+        }
+        catch (err) {
+            const code = containmentExitCode(io, err);
+            if (code !== null) {
+                return code;
+            }
+            throw err;
+        }
     }
     else {
         io.writeOut("No deft entry found in AGENTS.md\n");

package/dist/value/readback.js

@@ -2,6 +2,7 @@ import { appendFileSync, existsSync, mkdirSync, readFileSync } from "node:fs";
 import { join, resolve } from "node:path";
 import { runningInsideDeftRepo } from "../doctor/paths.js";
 import { ALL_ATTRIBUTION_EVENT_NAMES } from "../events/attribution-constants.js";
+import { assertWriteTargetSafe, ProjectionContainmentError } from "../fs/projection-containment.js";
 import { DEFAULT_EVENT_LOG, readEvents } from "../lifecycle/events.js";
 import { policyColonInvocation } from "../policy/policy-invocation.js";
 import { isValueFeedbackPathAllowed, resolveValueFeedback, } from "../policy/value-feedback.js";
@@ -229,10 +230,14 @@ function appendReadbackHistory(projectRoot, eventId, line, options = {}) {
         line,
     };
     try {
+        assertWriteTargetSafe(projectRoot, path);
         mkdirSync(join(path, ".."), { recursive: true });
         appendFileSync(path, `${JSON.stringify(record)}\n`, "utf8");
     }
-    catch {
+    catch (err) {
+        if (err instanceof ProjectionContainmentError) {
+            throw err;
+        }
         // observability only
     }
 }

package/dist/xbrief-migrate/constants.d.ts

@@ -4,6 +4,12 @@ export { LEGACY_VBRIEF_VERSION, VBRIEF_REFERENCE_PREFIX, VBRIEF_VERSION, XBRIEF_
 export declare const V08_CONTAINER_ITEM_TYPES: Set<string>;
 export declare const LEGACY_ARTIFACT_DIR: "vbrief";
 export declare const MIGRATED_ARTIFACT_DIR: "xbrief";
+/**
+ * Obsolete framework support narrative at the lifecycle root. Legacy
+ * `migrate:xbrief` copied this to `xbrief/vbrief.md` with broken framework
+ * links; consumer projections use `xbrief.md` instead (#2806).
+ */
+export declare const OBSOLETE_FRAMEWORK_NARRATIVE_FILENAME: "vbrief.md";
 export declare const LEGACY_ARTIFACT_SUFFIX: ".vbrief.json";
 export declare const MIGRATED_ARTIFACT_SUFFIX: ".xbrief.json";
 export declare const LEGACY_INFO_ROOT_KEY: "vBRIEFInfo";

package/dist/xbrief-migrate/constants.js

@@ -5,6 +5,12 @@ export { LEGACY_VBRIEF_VERSION, VBRIEF_REFERENCE_PREFIX, VBRIEF_VERSION, XBRIEF_
 export const V08_CONTAINER_ITEM_TYPES = new Set([...VALID_PLAN_ITEM_TYPES].filter((t) => t !== "task"));
 export const LEGACY_ARTIFACT_DIR = "vbrief";
 export const MIGRATED_ARTIFACT_DIR = "xbrief";
+/**
+ * Obsolete framework support narrative at the lifecycle root. Legacy
+ * `migrate:xbrief` copied this to `xbrief/vbrief.md` with broken framework
+ * links; consumer projections use `xbrief.md` instead (#2806).
+ */
+export const OBSOLETE_FRAMEWORK_NARRATIVE_FILENAME = "vbrief.md";
 export const LEGACY_ARTIFACT_SUFFIX = ".vbrief.json";
 export const MIGRATED_ARTIFACT_SUFFIX = ".xbrief.json";
 export const LEGACY_INFO_ROOT_KEY = "vBRIEFInfo";

package/dist/xbrief-migrate/index.d.ts

@@ -1,9 +1,9 @@
 export { detectStaleUnmanagedHeader, type HeaderPatchOutcome, type HeaderRewriteResult, type HeaderTokenReplacement, LEGACY_HEADER_TOKENS, patchAgentsMdHeader, renderHeaderPatchSummary, renderStaleHeaderLine, rewriteUnmanagedHeaderTokens, type StaleHeaderDetection, } from "./agents-header.js";
-export { VBRIEF_DEPRECATION_MARKER_BODY, VBRIEF_DEPRECATION_MARKER_FILENAME, VBRIEF_DEPRECATION_MARKER_SENTINEL, } from "./constants.js";
+export { OBSOLETE_FRAMEWORK_NARRATIVE_FILENAME, VBRIEF_DEPRECATION_MARKER_BODY, VBRIEF_DEPRECATION_MARKER_FILENAME, VBRIEF_DEPRECATION_MARKER_SENTINEL, } from "./constants.js";
 export { detectLegacyVbriefLayout, detectXbriefConvergence, type LegacyVbriefLayoutDetection, type XbriefConvergenceDetection, type XbriefConvergenceState, } from "./detect.js";
 export { BUILTIN_ALLOW_LIST, type DriftEvaluateOptions, type DriftEvaluateResult, type DriftFinding, type DriftScanMode, evaluateXbriefDrift, LEGACY_REFERENCE_PREFIX, scanCorpusToken, } from "./drift-gate.js";
 export { hasVbriefDeprecationMarker, isDirectory, isEffectivelyEmptyDir, } from "./fs-helpers.js";
-export { convergeLegacyVbriefRoot, emitXbriefMigration, runXbriefMigration, runXbriefMigrationCli, type VbriefConvergeAction, type XbriefMigrationArgs, type XbriefMigrationIo, type XbriefMigrationOutcome, } from "./migrate-project.js";
+export { convergeLegacyVbriefRoot, emitXbriefMigration, removeStaleMigratedFrameworkNarrative, runXbriefMigration, runXbriefMigrationCli, shouldOmitLegacyMigrationFile, type VbriefConvergeAction, type XbriefMigrationArgs, type XbriefMigrationIo, type XbriefMigrationOutcome, } from "./migrate-project.js";
 export { renderXbriefMigrationLine, xbriefMigrationGuidance } from "./signpost.js";
 export { assertFeatureEmissionAllowed, assertLayoutAwareWritePath, FeatureEmissionRejectedError, type JsonObject, type JsonValue, readDeclaredArtifactVersion, resolveLayoutAwareRelativePath, rewriteEmbeddedTokens, SplitLayoutRejectedError, TransformError, transformArtifactV06ToV08, transformArtifactV06ToV08Transactional, } from "./transforms.js";
 export { isPatchOnlyUpgrade, parseSemverPrefix } from "./version.js";

package/dist/xbrief-migrate/index.js

@@ -1,9 +1,9 @@
 export { detectStaleUnmanagedHeader, LEGACY_HEADER_TOKENS, patchAgentsMdHeader, renderHeaderPatchSummary, renderStaleHeaderLine, rewriteUnmanagedHeaderTokens, } from "./agents-header.js";
-export { VBRIEF_DEPRECATION_MARKER_BODY, VBRIEF_DEPRECATION_MARKER_FILENAME, VBRIEF_DEPRECATION_MARKER_SENTINEL, } from "./constants.js";
+export { OBSOLETE_FRAMEWORK_NARRATIVE_FILENAME, VBRIEF_DEPRECATION_MARKER_BODY, VBRIEF_DEPRECATION_MARKER_FILENAME, VBRIEF_DEPRECATION_MARKER_SENTINEL, } from "./constants.js";
 export { detectLegacyVbriefLayout, detectXbriefConvergence, } from "./detect.js";
 export { BUILTIN_ALLOW_LIST, evaluateXbriefDrift, LEGACY_REFERENCE_PREFIX, scanCorpusToken, } from "./drift-gate.js";
 export { hasVbriefDeprecationMarker, isDirectory, isEffectivelyEmptyDir, } from "./fs-helpers.js";
-export { convergeLegacyVbriefRoot, emitXbriefMigration, runXbriefMigration, runXbriefMigrationCli, } from "./migrate-project.js";
+export { convergeLegacyVbriefRoot, emitXbriefMigration, removeStaleMigratedFrameworkNarrative, runXbriefMigration, runXbriefMigrationCli, shouldOmitLegacyMigrationFile, } from "./migrate-project.js";
 export { renderXbriefMigrationLine, xbriefMigrationGuidance } from "./signpost.js";
 export { assertFeatureEmissionAllowed, assertLayoutAwareWritePath, FeatureEmissionRejectedError, readDeclaredArtifactVersion, resolveLayoutAwareRelativePath, rewriteEmbeddedTokens, SplitLayoutRejectedError, TransformError, transformArtifactV06ToV08, transformArtifactV06ToV08Transactional, } from "./transforms.js";
 export { isPatchOnlyUpgrade, parseSemverPrefix } from "./version.js";

package/dist/xbrief-migrate/migrate-project.d.ts

@@ -33,6 +33,13 @@ export type XbriefMigrationOutcome = {
     readonly kind: "config";
     readonly message: string;
 };
+/** True when a legacy lifecycle file is an obsolete framework narrative (#2806). */
+export declare function shouldOmitLegacyMigrationFile(relativePath: string): boolean;
+/**
+ * Remove a stale `xbrief/vbrief.md` left by an earlier migrate:xbrief run.
+ * Project JSON records and `xbrief/schemas/` are untouched (#2806).
+ */
+export declare function removeStaleMigratedFrameworkNarrative(projectRoot: string): boolean;
 /**
  * Converge a leftover legacy `vbrief/` root to an unambiguous state (#2270).
  * An effectively-empty tree is removed by default (single canonical root); a