@deftai/directive-core 0.84.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/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/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/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

package/dist/xbrief-migrate/migrate-project.js

@@ -3,7 +3,7 @@ import { dirname, join, relative, resolve } from "node:path";
 import { checkGitClean } from "../migrate-preflight/index.js";
 import { agentsRefreshPlan } from "../platform/agents-md.js";
 import { patchAgentsMdHeader, renderHeaderPatchSummary } from "./agents-header.js";
-import { LEGACY_ARTIFACT_DIR, LEGACY_ARTIFACT_SUFFIX, MIGRATED_ARTIFACT_DIR, MIGRATED_ARTIFACT_SUFFIX, VBRIEF_DEPRECATION_MARKER_BODY, VBRIEF_DEPRECATION_MARKER_FILENAME, } from "./constants.js";
+import { LEGACY_ARTIFACT_DIR, LEGACY_ARTIFACT_SUFFIX, MIGRATED_ARTIFACT_DIR, MIGRATED_ARTIFACT_SUFFIX, OBSOLETE_FRAMEWORK_NARRATIVE_FILENAME, VBRIEF_DEPRECATION_MARKER_BODY, VBRIEF_DEPRECATION_MARKER_FILENAME, } from "./constants.js";
 import { detectLegacyVbriefLayout, detectXbriefConvergence } from "./detect.js";
 import { hasVbriefDeprecationMarker, isDirectory, isEffectivelyEmptyDir } from "./fs-helpers.js";
 import { assertMigrationSourceSafe } from "./migration-containment.js";
@@ -24,6 +24,21 @@ function collectFiles(root, acc = []) {
     }
     return acc;
 }
+/** True when a legacy lifecycle file is an obsolete framework narrative (#2806). */
+export function shouldOmitLegacyMigrationFile(relativePath) {
+    return relativePath.replace(/\\/g, "/") === OBSOLETE_FRAMEWORK_NARRATIVE_FILENAME;
+}
+/**
+ * Remove a stale `xbrief/vbrief.md` left by an earlier migrate:xbrief run.
+ * Project JSON records and `xbrief/schemas/` are untouched (#2806).
+ */
+export function removeStaleMigratedFrameworkNarrative(projectRoot) {
+    const stale = join(projectRoot, MIGRATED_ARTIFACT_DIR, OBSOLETE_FRAMEWORK_NARRATIVE_FILENAME);
+    if (!existsSync(stale))
+        return false;
+    rmSync(stale, { force: true });
+    return true;
+}
 function mapRelativePath(relativePath) {
     return relativePath
         .split(/[/\\]/)
@@ -81,6 +96,8 @@ function migrateLegacyTree(projectRoot, legacyDir, options) {
     try {
         for (const srcPath of files) {
             const rel = relative(legacyDir, srcPath);
+            if (shouldOmitLegacyMigrationFile(rel))
+                continue;
             const destPath = join(stagedDir, mapRelativePath(rel));
             writeMigratedFile(srcPath, destPath);
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deftai/directive-core",
-  "version": "0.84.0",
+  "version": "0.85.0",
   "description": "TypeScript engine core for the Directive framework.",
   "type": "module",
   "main": "./dist/index.js",
@@ -317,8 +317,8 @@
     "provenance": true
   },
   "dependencies": {
-    "@deftai/directive-content": "^0.84.0",
-    "@deftai/directive-types": "^0.84.0",
+    "@deftai/directive-content": "^0.85.0",
+    "@deftai/directive-types": "^0.85.0",
     "archiver": "^8.0.0"
   },
   "scripts": {