@deftai/directive-core 0.68.1 → 0.70.0

package/dist/triage/welcome/onboard.js

@@ -0,0 +1,94 @@
+import { existsSync } from "node:fs";
+import { resolve } from "node:path";
+import { maybeSelfHealCache } from "../../cache/fetch.js";
+import { resolveProjectDefinitionPath } from "../../layout/resolve.js";
+import { DEFAULT_WIP_CAP, SUBSCRIPTION_PRESETS, TRIAGE_SKILL_PATH } from "./constants.js";
+import { formatWelcomeCommand } from "./default-mode.js";
+import { detectPriorState } from "./prior-state.js";
+import { emitOneliner } from "./summary.js";
+import { previewWipRelief, subscriptionPreset, writeTriageScope, writeWipCap } from "./writers.js";
+/** Default triage-scope preset applied when `--onboard` is run without `--preset`. */
+export const DEFAULT_ONBOARD_PRESET = "small";
+function failure(exitCode) {
+    return {
+        exitCode,
+        presetApplied: null,
+        triageScopeChanged: false,
+        wipCapApplied: null,
+        wipCapChanged: false,
+        reliefOffered: false,
+    };
+}
+/**
+ * Non-interactive onboarding for `deft triage:welcome --onboard` (#2295).
+ *
+ * The welcome nudges point every fresh consumer at `--onboard`; this wires that
+ * command to the already-tested core writers instead of the old "not
+ * implemented" stub. It writes the chosen triage-scope preset and (optionally)
+ * a WIP cap via {@link writeTriageScope} / {@link writeWipCap} -- which already
+ * target the canonical `x-directive/policy` key and migrate any legacy bare
+ * block -- previews WIP relief when at/over cap, then prints a completion
+ * summary and the next-step guidance. Flag-driven by design: agents/CI pass
+ * `--preset` / `--wip-cap`; sensible defaults apply otherwise.
+ */
+export function runOnboardMode(projectRoot, options = {}) {
+    const out = options.output ?? ((line) => process.stdout.write(`${line}\n`));
+    const preset = (options.preset ?? DEFAULT_ONBOARD_PRESET).trim() || DEFAULT_ONBOARD_PRESET;
+    if (!Object.hasOwn(SUBSCRIPTION_PRESETS, preset)) {
+        out(`[welcome] Unknown --preset '${preset}'. Choose one of: ${Object.keys(SUBSCRIPTION_PRESETS).join(", ")}.`);
+        return failure(2);
+    }
+    const wipCap = options.wipCap ?? null;
+    if (wipCap !== null && (!Number.isInteger(wipCap) || wipCap < 1)) {
+        out(`[welcome] --wip-cap must be a positive integer, got ${JSON.stringify(options.wipCap)}.`);
+        return failure(2);
+    }
+    const pdPath = resolveProjectDefinitionPath(projectRoot);
+    if (!existsSync(pdPath)) {
+        out(`[welcome] No project definition found at ${pdPath}. Run project setup first (deft-directive-setup) before onboarding triage.`);
+        return failure(2);
+    }
+    const heal = options.selfHealFn ??
+        ((root) => {
+            maybeSelfHealCache(resolve(root));
+        });
+    heal(projectRoot);
+    const rules = subscriptionPreset(preset);
+    const [triageScopeChanged] = writeTriageScope(projectRoot, rules, { presetLabel: preset });
+    let wipCapChanged = false;
+    if (wipCap !== null) {
+        [wipCapChanged] = writeWipCap(projectRoot, wipCap);
+    }
+    emitOneliner(projectRoot, {
+        writeHistory: options.writeHistory !== false,
+        now: options.now,
+        output: out,
+        applyD2Suppression: false,
+    });
+    const state = detectPriorState(projectRoot);
+    let reliefOffered = false;
+    if (state.wipCount >= state.wipCap) {
+        const relief = previewWipRelief(projectRoot);
+        if (relief.eligibleCount > 0) {
+            reliefOffered = true;
+            const demote = formatWelcomeCommand(["scope:demote", "--batch", "--older-than-days", String(relief.olderThanDays)], options.taskPrefix).replace(/\r?\n/g, " ");
+            const eligibleCount = String(relief.eligibleCount).replace(/\r?\n/g, " ");
+            out(`[welcome] WIP ${state.wipCount}/${state.wipCap} at/over cap -- ${eligibleCount} pending scope(s) ` +
+                `older than ${relief.olderThanDays}d are demote-eligible. Relieve with \`${demote}\`.`);
+        }
+    }
+    const capNote = wipCap !== null ? `, wipCap ${wipCap}` : ` (wipCap default ${DEFAULT_WIP_CAP})`;
+    out(`[welcome] Onboarding applied: triage scope preset '${preset}'${capNote}.`);
+    const bootstrap = formatWelcomeCommand(["triage:bootstrap"], options.taskPrefix);
+    const queue = formatWelcomeCommand(["triage:queue", "--limit=10"], options.taskPrefix);
+    out(`[welcome] Next: run \`${bootstrap}\` to populate the triage cache, then \`${queue}\` to pick work. See ${TRIAGE_SKILL_PATH}.`);
+    return {
+        exitCode: 0,
+        presetApplied: preset,
+        triageScopeChanged,
+        wipCapApplied: wipCap,
+        wipCapChanged,
+        reliefOffered,
+    };
+}
+//# sourceMappingURL=onboard.js.map

package/dist/umbrella-current-shape/index.d.ts

@@ -1,3 +1,13 @@
+/**
+ * #2307: only comments authored by a repo maintainer may be treated as the
+ * authoritative current-shape state. GitHub's `author_association` on an issue
+ * comment is the trust signal; anything outside this set (CONTRIBUTOR, NONE,
+ * FIRST_TIME_CONTRIBUTOR, ...) is an untrusted third party and cannot forge a
+ * higher-pass current-shape comment.
+ */
+export declare const MAINTAINER_ASSOCIATIONS: ReadonlySet<string>;
+/** True when a comment's author_association marks it as maintainer-authored (#2307). */
+export declare function isMaintainerAuthored(association: string): boolean;
 /** Matches `## Current shape (as of pass-N)` — same pattern as vbrief-reconcile/umbrellas.ts. */
 export declare const CURRENT_SHAPE_HEADER_RE: RegExp;
 export declare const SECTION_MARKERS: {
@@ -20,6 +30,8 @@ export interface IssueComment {
     readonly body: string;
     readonly htmlUrl: string;
     readonly updatedAt: string;
+    readonly authorLogin: string;
+    readonly authorAssociation: string;
 }
 export interface CurrentShapeComment extends IssueComment {
     readonly pass: number;
@@ -37,6 +49,8 @@ export interface CurrentShapeResult {
     readonly htmlUrl: string;
     readonly pass: number;
     readonly body: string;
+    readonly authorLogin: string;
+    readonly authorAssociation: string;
     readonly sections: SectionPresence;
 }
 export type ScmFetcher = (repo: string, issueNumber: number) => IssueComment[] | {
@@ -55,11 +69,20 @@ export interface RunCurrentShapeOptions {
 /** Merge `gh api --paginate` concatenated JSON array pages into comment rows. */
 export declare function parseCommentsFromGhStdout(stdout: string): IssueComment[];
 export declare function extractPassFromBody(body: string): number | null;
-/** Pick the canonical comment — highest pass-N; tie-break by comment id (latest). */
+/**
+ * Pick the canonical comment — highest pass-N; tie-break by comment id (latest).
+ *
+ * #2307: only MAINTAINER-authored comments (author_association in
+ * {OWNER, MEMBER, COLLABORATOR}) are eligible. A non-maintainer higher-pass
+ * comment is ignored, which defeats the forged-higher-pass primitive: an
+ * attacker cannot inject authoritative state by simply commenting with a bigger
+ * pass number.
+ */
 export declare function selectCurrentShapeComment(comments: readonly IssueComment[]): CurrentShapeComment | null;
 export declare function detectSections(body: string): SectionPresence;
 export declare function sectionsRecord(presence: SectionPresence): Record<string, boolean>;
 export declare const NO_CURRENT_SHAPE_MESSAGE: string;
+export declare const NON_MAINTAINER_CURRENT_SHAPE_MESSAGE: string;
 export declare function fetchCurrentShape(options: {
     repo: string;
     issueNumber: number;
@@ -75,6 +98,7 @@ export declare function fetchCurrentShape(options: {
 export declare function emitCurrentShape(result: CurrentShapeResult, options: {
     jsonMode: boolean;
     writeOut: (text: string) => void;
+    writeErr?: (text: string) => void;
 }): number;
 export declare function runCurrentShape(options: RunCurrentShapeOptions): number;
 export declare function parseCurrentShapeArgv(argv: readonly string[]): {

package/dist/umbrella-current-shape/index.js

@@ -1,7 +1,24 @@
 import { spawnSync } from "node:child_process";
+import { scan } from "../cache/scanner.js";
 import { resolveBinary } from "../scm/binary.js";
 import { SUBPROCESS_MAX_BUFFER } from "../subprocess/max-buffer.js";
 import { resolveRepo } from "../triage/queue/repo.js";
+/**
+ * #2307: only comments authored by a repo maintainer may be treated as the
+ * authoritative current-shape state. GitHub's `author_association` on an issue
+ * comment is the trust signal; anything outside this set (CONTRIBUTOR, NONE,
+ * FIRST_TIME_CONTRIBUTOR, ...) is an untrusted third party and cannot forge a
+ * higher-pass current-shape comment.
+ */
+export const MAINTAINER_ASSOCIATIONS = new Set([
+    "OWNER",
+    "MEMBER",
+    "COLLABORATOR",
+]);
+/** True when a comment's author_association marks it as maintainer-authored (#2307). */
+export function isMaintainerAuthored(association) {
+    return MAINTAINER_ASSOCIATIONS.has(association.toUpperCase());
+}
 /** Matches `## Current shape (as of pass-N)` — same pattern as vbrief-reconcile/umbrellas.ts. */
 export const CURRENT_SHAPE_HEADER_RE = /^## Current shape \(as of pass-(\d+)\)/m;
 export const SECTION_MARKERS = {
@@ -35,11 +52,16 @@ function mapCommentEntry(entry) {
     if (typeof rec.id !== "number" || typeof rec.body !== "string") {
         return null;
     }
+    const user = typeof rec.user === "object" && rec.user !== null
+        ? rec.user
+        : null;
     return {
         id: rec.id,
         body: rec.body,
         htmlUrl: typeof rec.html_url === "string" ? rec.html_url : "",
         updatedAt: typeof rec.updated_at === "string" ? rec.updated_at : "",
+        authorLogin: user !== null && typeof user.login === "string" ? user.login : "",
+        authorAssociation: typeof rec.author_association === "string" ? rec.author_association : "",
     };
 }
 /** Merge `gh api --paginate` concatenated JSON array pages into comment rows. */
@@ -135,10 +157,21 @@ export function extractPassFromBody(body) {
     const pass = Number(match[1]);
     return Number.isFinite(pass) ? pass : null;
 }
-/** Pick the canonical comment — highest pass-N; tie-break by comment id (latest). */
+/**
+ * Pick the canonical comment — highest pass-N; tie-break by comment id (latest).
+ *
+ * #2307: only MAINTAINER-authored comments (author_association in
+ * {OWNER, MEMBER, COLLABORATOR}) are eligible. A non-maintainer higher-pass
+ * comment is ignored, which defeats the forged-higher-pass primitive: an
+ * attacker cannot inject authoritative state by simply commenting with a bigger
+ * pass number.
+ */
 export function selectCurrentShapeComment(comments) {
     let best = null;
     for (const comment of comments) {
+        if (!isMaintainerAuthored(comment.authorAssociation)) {
+            continue;
+        }
         const pass = extractPassFromBody(comment.body);
         if (pass === null) {
             continue;
@@ -188,6 +221,16 @@ export function sectionsRecord(presence) {
 export const NO_CURRENT_SHAPE_MESSAGE = "No ## Current shape (as of pass-N) comment found on this issue. " +
     "Create one per AGENTS.md ## Umbrella current-shape convention (#1152) — " +
     "do not fall back to the issue body (stale by design).";
+// #2307 (Greptile review): a structurally valid current-shape comment authored
+// by a non-maintainer is filtered out for provenance and would otherwise be
+// reported with the generic "not found" message above -- indistinguishable from
+// genuine absence, which makes --strict especially confusing to debug. This
+// message names the provenance filter explicitly so the caller knows the
+// comment exists but was ignored, not that it is missing.
+export const NON_MAINTAINER_CURRENT_SHAPE_MESSAGE = "A ## Current shape (as of pass-N) comment exists but was authored by a " +
+    "non-maintainer (author_association not in OWNER/MEMBER/COLLABORATOR) and is " +
+    "ignored per AGENTS.md ## Umbrella current-shape convention (#1152 / #2307). " +
+    "A maintainer must (re-)post the current-shape comment for it to be authoritative.";
 export function fetchCurrentShape(options) {
     const fetcher = options.fetchComments ?? defaultFetchComments;
     const fetched = fetcher(options.repo, options.issueNumber);
@@ -196,7 +239,15 @@ export function fetchCurrentShape(options) {
     }
     const selected = selectCurrentShapeComment(fetched);
     if (selected === null) {
-        return { ok: false, error: NO_CURRENT_SHAPE_MESSAGE, kind: "not-found" };
+        // Distinguish provenance-filtered absence from genuine absence (#2307).
+        const hadNonMaintainerShape = fetched.some((c) => extractPassFromBody(c.body) !== null && !isMaintainerAuthored(c.authorAssociation));
+        return {
+            ok: false,
+            error: hadNonMaintainerShape
+                ? NON_MAINTAINER_CURRENT_SHAPE_MESSAGE
+                : NO_CURRENT_SHAPE_MESSAGE,
+            kind: "not-found",
+        };
     }
     const sections = detectSections(selected.body);
     return {
@@ -208,11 +259,36 @@ export function fetchCurrentShape(options) {
             htmlUrl: selected.htmlUrl,
             pass: selected.pass,
             body: selected.body,
+            authorLogin: selected.authorLogin,
+            authorAssociation: selected.authorAssociation,
             sections,
         },
     };
 }
 export function emitCurrentShape(result, options) {
+    // #2307: the selected comment body is still attacker-influencable text (a
+    // maintainer can quote/paste untrusted content). Run it through the same
+    // quarantine scanner used for cache content and emit the fenced transform so
+    // injection-shaped sections are quarantined, never rendered as authoritative
+    // instructions.
+    const scanned = scan(result.body);
+    // #2307 fail-closed (Greptile review): a scanner hard-fail (e.g. a credential
+    // pattern) is only FLAGGED by scan() -- detectCredentials sets passed=false
+    // but does NOT redact the secret from transformed_content. Emitting the
+    // transform regardless would forward the raw credential to stdout / CI logs /
+    // JSON consumers. Mirror buildIssueVbrief (#2306, issue:ingest), which throws
+    // ScannerHardFailError and writes nothing: refuse to emit and return non-zero.
+    if (!scanned.passed) {
+        const details = scanned.flags
+            .filter((f) => f.severity === "hard-fail")
+            .map((f) => f.detail)
+            .join("; ");
+        const writeErr = options.writeErr ?? ((text) => process.stderr.write(text));
+        writeErr(`umbrella:current-shape: refused issue #${result.issueNumber}: quarantine scanner hard-fail` +
+            (details.length > 0 ? ` (${details})` : "") +
+            " -- nothing written.\n");
+        return 1;
+    }
     if (options.jsonMode) {
         const payload = {
             issueNumber: result.issueNumber,
@@ -220,7 +296,10 @@ export function emitCurrentShape(result, options) {
             commentId: result.commentId,
             htmlUrl: result.htmlUrl,
             pass: result.pass,
-            body: result.body,
+            body: scanned.transformed_content,
+            authorLogin: result.authorLogin,
+            authorAssociation: result.authorAssociation,
+            scannerPassed: scanned.passed,
             sections: sectionsRecord(result.sections),
             missingSections: result.sections.missing,
             missingOptionalSections: result.sections.optionalMissing,
@@ -228,7 +307,7 @@ export function emitCurrentShape(result, options) {
         options.writeOut(`${JSON.stringify(payload)}\n`);
     }
     else {
-        options.writeOut(`${result.body}\n`);
+        options.writeOut(`${scanned.transformed_content}\n`);
     }
     return 0;
 }
@@ -260,6 +339,7 @@ export function runCurrentShape(options) {
     return emitCurrentShape(fetched.result, {
         jsonMode: options.jsonMode ?? false,
         writeOut,
+        writeErr,
     });
 }
 export function parseCurrentShapeArgv(argv) {

package/dist/user-config/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./resolve-user-md.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/user-config/index.js

@@ -0,0 +1,2 @@
+export * from "./resolve-user-md.js";
+//# sourceMappingURL=index.js.map

package/dist/user-config/resolve-user-md.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Shared USER.md resolver (#2271).
+ *
+ * Resolves the USER.md user-config file across an explicit first-hit-wins
+ * search order so session-start, the CLI bootstrap, and doctor all share a
+ * single source of truth for "where does USER.md live?" — and so it resolves
+ * automatically in mismatched / headless sandboxes where `$HOME` is not a
+ * persistent mount (the #2124 Cowork gap) with zero manual `DEFT_USER_PATH`.
+ *
+ * Search order (first hit wins):
+ *   1. `DEFT_USER_PATH` — explicit override, highest precedence, points at the
+ *      USER.md file directly. Always wins as the resolved path whether or not
+ *      the file exists yet (presence is reported separately via `found`).
+ *   2. Workspace-local bridged config (`<projectRoot>/.deft/USER.md`) — a
+ *      persistent location inside the workspace that survives a non-persistent
+ *      `$HOME`.
+ *   3. Bridged platform config dir (`%APPDATA%\deft\USER.md` on Windows,
+ *      `~/.config/deft/USER.md` elsewhere) — the historical default location.
+ *   4. Sensible default (the rung-3 path) + a `no USER.md found; using
+ *      defaults` diagnostic. This branch NEVER throws.
+ */
+/** Exact diagnostic phrase emitted when USER.md is absent on every rung. */
+export declare const NO_USER_MD_DIAGNOSTIC = "no USER.md found; using defaults";
+/** The USER.md filename joined onto every candidate config directory. */
+export declare const USER_MD_FILENAME = "USER.md";
+/**
+ * Workspace-local config directory (relative to the project root). This is the
+ * bridged, persistent location inside the workspace that keeps preferences
+ * reachable even when the platform config dir under `$HOME` is not mounted.
+ */
+export declare const WORKSPACE_LOCAL_CONFIG_DIR = ".deft";
+/** Which search rung produced the resolved path. */
+export type UserMdRung = "env-override" | "workspace-local" | "platform-config" | "default";
+export interface ResolveUserMdResult {
+    /**
+     * The resolved USER.md path. For rungs 2-3 this is always an existing file.
+     * For rung 1 (`env-override`) it is the override path whether or not the file
+     * exists yet (check `found`). For the `default` rung it is the sensible
+     * default location (which does not exist).
+     */
+    readonly path: string;
+    /** Which search rung matched. */
+    readonly rung: UserMdRung;
+    /** True when a USER.md file actually exists at `path`. */
+    readonly found: boolean;
+    /** One-line human-readable diagnostic describing the resolution boundary. */
+    readonly diagnostic: string;
+    /** Candidate paths inspected, in search order (for diagnostics / tests). */
+    readonly searched: readonly string[];
+}
+export interface ResolveUserMdOptions {
+    /** Workspace root for the workspace-local rung. Defaults to `process.cwd()`. */
+    readonly projectRoot?: string;
+    /** Environment source (reads `DEFT_USER_PATH` / `APPDATA`). Defaults to `process.env`. */
+    readonly env?: NodeJS.ProcessEnv;
+    /** Platform id for the platform-config rung. Defaults to `process.platform`. */
+    readonly platform?: NodeJS.Platform;
+    /** Home directory for the platform-config rung. Defaults to `os.homedir()`. */
+    readonly homeDir?: string;
+    /** File-existence probe. Defaults to an `existsSync` + `isFile` check. */
+    readonly fileExists?: (path: string) => boolean;
+}
+/**
+ * Resolve the platform config directory (`%APPDATA%\deft` / `~/.config/deft`).
+ * Mirrors `init-deposit`'s `userConfigDir()` platform branch but takes the
+ * platform / env / home as injectable inputs and deliberately does NOT honor
+ * `DEFT_USER_PATH` — that override is rung 1, handled by the caller.
+ */
+export declare function platformUserConfigDir(platform: NodeJS.Platform, env: NodeJS.ProcessEnv, homeDir: string): string;
+/**
+ * Resolve the USER.md path across the first-hit-wins search order. Never
+ * throws: an absent USER.md degrades to the sensible default location with a
+ * clear `no USER.md found; using defaults` diagnostic.
+ */
+export declare function resolveUserMdPath(options?: ResolveUserMdOptions): ResolveUserMdResult;
+//# sourceMappingURL=resolve-user-md.d.ts.map

package/dist/user-config/resolve-user-md.js

@@ -0,0 +1,120 @@
+/**
+ * Shared USER.md resolver (#2271).
+ *
+ * Resolves the USER.md user-config file across an explicit first-hit-wins
+ * search order so session-start, the CLI bootstrap, and doctor all share a
+ * single source of truth for "where does USER.md live?" — and so it resolves
+ * automatically in mismatched / headless sandboxes where `$HOME` is not a
+ * persistent mount (the #2124 Cowork gap) with zero manual `DEFT_USER_PATH`.
+ *
+ * Search order (first hit wins):
+ *   1. `DEFT_USER_PATH` — explicit override, highest precedence, points at the
+ *      USER.md file directly. Always wins as the resolved path whether or not
+ *      the file exists yet (presence is reported separately via `found`).
+ *   2. Workspace-local bridged config (`<projectRoot>/.deft/USER.md`) — a
+ *      persistent location inside the workspace that survives a non-persistent
+ *      `$HOME`.
+ *   3. Bridged platform config dir (`%APPDATA%\deft\USER.md` on Windows,
+ *      `~/.config/deft/USER.md` elsewhere) — the historical default location.
+ *   4. Sensible default (the rung-3 path) + a `no USER.md found; using
+ *      defaults` diagnostic. This branch NEVER throws.
+ */
+import { statSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+/** Exact diagnostic phrase emitted when USER.md is absent on every rung. */
+export const NO_USER_MD_DIAGNOSTIC = "no USER.md found; using defaults";
+/** The USER.md filename joined onto every candidate config directory. */
+export const USER_MD_FILENAME = "USER.md";
+/**
+ * Workspace-local config directory (relative to the project root). This is the
+ * bridged, persistent location inside the workspace that keeps preferences
+ * reachable even when the platform config dir under `$HOME` is not mounted.
+ */
+export const WORKSPACE_LOCAL_CONFIG_DIR = ".deft";
+function defaultFileExists(path) {
+    try {
+        return statSync(path).isFile();
+    }
+    catch {
+        // Any stat error (ENOENT, permission, ...) means "not a resolvable USER.md
+        // file". Deliberately NOT falling back to existsSync, which cannot tell a
+        // directory from a file and would report a dir at this path as a found file.
+        return false;
+    }
+}
+/**
+ * Resolve the platform config directory (`%APPDATA%\deft` / `~/.config/deft`).
+ * Mirrors `init-deposit`'s `userConfigDir()` platform branch but takes the
+ * platform / env / home as injectable inputs and deliberately does NOT honor
+ * `DEFT_USER_PATH` — that override is rung 1, handled by the caller.
+ */
+export function platformUserConfigDir(platform, env, homeDir) {
+    if (platform === "win32") {
+        const appData = env.APPDATA?.trim();
+        return appData ? join(appData, "deft") : join(homeDir, "AppData", "Roaming", "deft");
+    }
+    return join(homeDir, ".config", "deft");
+}
+/**
+ * Resolve the USER.md path across the first-hit-wins search order. Never
+ * throws: an absent USER.md degrades to the sensible default location with a
+ * clear `no USER.md found; using defaults` diagnostic.
+ */
+export function resolveUserMdPath(options = {}) {
+    const env = options.env ?? process.env;
+    const platform = options.platform ?? process.platform;
+    const homeDir = options.homeDir ?? homedir();
+    const projectRoot = options.projectRoot ?? process.cwd();
+    const fileExists = options.fileExists ?? defaultFileExists;
+    const searched = [];
+    // Rung 1: DEFT_USER_PATH override (full file path); always wins.
+    const override = env.DEFT_USER_PATH?.trim();
+    if (override) {
+        const overridePath = resolve(override);
+        searched.push(overridePath);
+        const found = fileExists(overridePath);
+        return {
+            path: overridePath,
+            rung: "env-override",
+            found,
+            diagnostic: found
+                ? `USER.md resolved from DEFT_USER_PATH: ${overridePath}`
+                : `USER.md path from DEFT_USER_PATH does not exist yet: ${overridePath}`,
+            searched,
+        };
+    }
+    // Rung 2: workspace-local bridged config.
+    const workspacePath = resolve(join(projectRoot, WORKSPACE_LOCAL_CONFIG_DIR, USER_MD_FILENAME));
+    searched.push(workspacePath);
+    if (fileExists(workspacePath)) {
+        return {
+            path: workspacePath,
+            rung: "workspace-local",
+            found: true,
+            diagnostic: `USER.md resolved from workspace-local config: ${workspacePath}`,
+            searched,
+        };
+    }
+    // Rung 3: bridged platform config dir.
+    const platformPath = join(platformUserConfigDir(platform, env, homeDir), USER_MD_FILENAME);
+    searched.push(platformPath);
+    if (fileExists(platformPath)) {
+        return {
+            path: platformPath,
+            rung: "platform-config",
+            found: true,
+            diagnostic: `USER.md resolved from platform config dir: ${platformPath}`,
+            searched,
+        };
+    }
+    // Rung 4: sensible default + diagnostic (never throws).
+    return {
+        path: platformPath,
+        rung: "default",
+        found: false,
+        diagnostic: `${NO_USER_MD_DIAGNOSTIC} (searched: ${searched.join(", ")})`,
+        searched,
+    };
+}
+//# sourceMappingURL=resolve-user-md.js.map

package/dist/vbrief-build/project-definition-io.d.ts

@@ -1,4 +1,10 @@
 import type { JsonObject } from "./types.js";
+/**
+ * Absolute path to the PROJECT-DEFINITION artifact. Layout-aware (#2302):
+ * resolves `xbrief/PROJECT-DEFINITION.xbrief.json` on a migrated tree, else the
+ * legacy `vbrief/PROJECT-DEFINITION.vbrief.json`, so loader not-found messages
+ * name the path that actually applies to the project's layout.
+ */
 export declare function projectDefinitionPath(projectRoot: string): string;
 export interface MutationLockDeps {
     readonly sleepMs?: (ms: number) => void;

package/dist/vbrief-build/project-definition-io.js

@@ -2,12 +2,17 @@ import { randomBytes } from "node:crypto";
 import { closeSync, existsSync, mkdirSync, openSync, readFileSync, renameSync, unlinkSync, writeFileSync, writeSync, } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 import { resolveProjectDefinitionPath } from "../layout/resolve.js";
-import { PROJECT_DEFINITION_REL_PATH } from "./constants.js";
 import { pythonJsonPretty } from "./json.js";
 import { ProjectDefinitionIOError } from "./types.js";
 const mutationThreadLock = { held: false };
+/**
+ * Absolute path to the PROJECT-DEFINITION artifact. Layout-aware (#2302):
+ * resolves `xbrief/PROJECT-DEFINITION.xbrief.json` on a migrated tree, else the
+ * legacy `vbrief/PROJECT-DEFINITION.vbrief.json`, so loader not-found messages
+ * name the path that actually applies to the project's layout.
+ */
 export function projectDefinitionPath(projectRoot) {
-    return join(projectRoot, PROJECT_DEFINITION_REL_PATH);
+    return resolveProjectDefinitionPath(resolve(projectRoot));
 }
 function defaultSleep(ms) {
     const end = Date.now() + ms;

package/dist/vbrief-validate/precutover.js

@@ -103,9 +103,13 @@ export function detectPreCutover(projectRoot) {
 /** Last release that ships `scripts/migrate_vbrief.py` on the consumer deposit path (#2068). */
 export const FROZEN_PRECUTOVER_MIGRATION_TAG = "v0.59.0";
 export function frozenPreCutoverMigrationGuidance() {
-    return (`Current npm releases no longer ship in-product \`task migrate:vbrief\`. Pin framework ${FROZEN_PRECUTOVER_MIGRATION_TAG} ` +
-        `(frozen Go installer or git tag), install Python 3.11+ and uv, run \`task migrate:vbrief\` once from that payload, ` +
-        `then upgrade to current npm. See UPGRADING.md § Frozen pre-v0.20 document-model migration (#2068).`);
+    return (`Current npm releases no longer ship in-product \`task migrate:vbrief\`. Best-effort path (anchored on the ` +
+        `${FROZEN_PRECUTOVER_MIGRATION_TAG} git tag, from which GitHub serves a source tarball on demand): pin framework ` +
+        `${FROZEN_PRECUTOVER_MIGRATION_TAG}, install Python 3.11+ and uv, run \`task migrate:vbrief\` once from that payload, ` +
+        `then upgrade to current npm. This is a two-hop chain: pre-v0.20 flat model -> vBRIEF v0.6 (on ${FROZEN_PRECUTOVER_MIGRATION_TAG}) ` +
+        `-> xBRIEF via \`deft migrate:xbrief\` on current npm. If the ${FROZEN_PRECUTOVER_MIGRATION_TAG} payload is unavailable, ` +
+        `fall back to a manual fresh start: \`directive init\` a new project on current npm and hand-port your spec content. ` +
+        `See UPGRADING.md § Frozen pre-v0.20 document-model migration (#2068).`);
 }
 export function renderPrecutoverLine(projectRoot) {
     const { preCutover, reasons } = detectPreCutover(projectRoot);

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

@@ -10,4 +10,14 @@ export declare const LEGACY_INFO_ROOT_KEY: "vBRIEFInfo";
 export declare const MIGRATED_INFO_ROOT_KEY: "xBRIEFInfo";
 /** Item-only status value added in xBRIEF v0.8. */
 export declare const V08_ITEM_STATUS_AUTO: "auto";
+/**
+ * Filename of the explicit deprecation marker written into a legacy `vbrief/`
+ * root that is retained for read-compatibility after convergence (#2270). Its
+ * presence is what tells `doctor` the folder is NOT an active source of truth.
+ */
+export declare const VBRIEF_DEPRECATION_MARKER_FILENAME: "DEPRECATED.md";
+/** Sentinel line identifying a deft-written `vbrief/` deprecation marker (#2270). */
+export declare const VBRIEF_DEPRECATION_MARKER_SENTINEL: "<!-- deft:vbrief-deprecated -->";
+/** Body written into the retained legacy `vbrief/` deprecation marker (#2270). */
+export declare const VBRIEF_DEPRECATION_MARKER_BODY: "<!-- deft:vbrief-deprecated -->\n# Deprecated: legacy `vbrief/` root\n\nThis project has migrated to the `xbrief/` lifecycle layout. This `vbrief/`\ndirectory is retained only for read-compatibility and is **not** an active\nsource of truth. Do not add new scope work here — use `xbrief/` instead.\n\nOnce you no longer need read-compatibility with the legacy layout, delete this\n`vbrief/` directory. Re-running `deft migrate:xbrief` re-checks convergence.\n";
 //# sourceMappingURL=constants.d.ts.map

package/dist/xbrief-migrate/constants.js

@@ -11,4 +11,23 @@ export const LEGACY_INFO_ROOT_KEY = "vBRIEFInfo";
 export const MIGRATED_INFO_ROOT_KEY = "xBRIEFInfo";
 /** Item-only status value added in xBRIEF v0.8. */
 export const V08_ITEM_STATUS_AUTO = "auto";
+/**
+ * Filename of the explicit deprecation marker written into a legacy `vbrief/`
+ * root that is retained for read-compatibility after convergence (#2270). Its
+ * presence is what tells `doctor` the folder is NOT an active source of truth.
+ */
+export const VBRIEF_DEPRECATION_MARKER_FILENAME = "DEPRECATED.md";
+/** Sentinel line identifying a deft-written `vbrief/` deprecation marker (#2270). */
+export const VBRIEF_DEPRECATION_MARKER_SENTINEL = "<!-- deft:vbrief-deprecated -->";
+/** Body written into the retained legacy `vbrief/` deprecation marker (#2270). */
+export const VBRIEF_DEPRECATION_MARKER_BODY = `${VBRIEF_DEPRECATION_MARKER_SENTINEL}
+# Deprecated: legacy \`vbrief/\` root
+
+This project has migrated to the \`xbrief/\` lifecycle layout. This \`vbrief/\`
+directory is retained only for read-compatibility and is **not** an active
+source of truth. Do not add new scope work here — use \`xbrief/\` instead.
+
+Once you no longer need read-compatibility with the legacy layout, delete this
+\`vbrief/\` directory. Re-running \`deft migrate:xbrief\` re-checks convergence.
+`;
 //# sourceMappingURL=constants.js.map

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

@@ -3,9 +3,43 @@ export interface LegacyVbriefLayoutDetection {
     legacyLayout: boolean;
     reasons: string[];
 }
+/**
+ * Discriminated convergence state of the `vbrief/` + `xbrief/` lifecycle roots
+ * (#2270). Distinguishes the ambiguous dual-empty-root case that `migrate:xbrief`
+ * must converge from the states that are already unambiguous.
+ *
+ * - `none` — neither root carries content (nothing to converge).
+ * - `xbrief-only` — canonical `xbrief/` with content and no `vbrief/`.
+ * - `xbrief-marker` — `vbrief/` retained behind an explicit deprecation marker.
+ * - `empty-vbrief` — a stray, fully-migrated empty `vbrief/` (the ambiguous root
+ *   to clean up: remove it, or mark it when read-compat retention is requested).
+ * - `legacy-only` — `vbrief/` holds content and there is no canonical `xbrief/`;
+ *   a full migration is required.
+ * - `dual-populated` — both roots hold content with no marker; converge by
+ *   marking the legacy tree deprecated (never destructively merged).
+ */
+export type XbriefConvergenceState = "none" | "xbrief-only" | "xbrief-marker" | "empty-vbrief" | "legacy-only" | "dual-populated";
+/** Structured convergence probe of the two lifecycle roots (#2270). */
+export interface XbriefConvergenceDetection {
+    state: XbriefConvergenceState;
+    vbriefPresent: boolean;
+    vbriefEmpty: boolean;
+    vbriefHasMarker: boolean;
+    xbriefPresent: boolean;
+    xbriefHasContent: boolean;
+}
 /**
  * Detect whether `projectRoot` still uses the legacy vbrief on-disk layout.
  * Mirrors the structured-reasons pattern from `detectPreCutover` (#793).
  */
 export declare function detectLegacyVbriefLayout(projectRoot: string): LegacyVbriefLayoutDetection;
+/**
+ * Classify the convergence state of the `vbrief/` and `xbrief/` lifecycle roots
+ * so the orchestrator can converge to a single unambiguous root (#2270). Unlike
+ * {@link detectLegacyVbriefLayout} (which only asks "is there anything legacy?"),
+ * this probe distinguishes the ambiguous dual-empty-root case from an already
+ * unambiguous layout, and never falls back to a `run migrate:xbrief` dead end
+ * for a `vbrief/` that is merely an empty leftover.
+ */
+export declare function detectXbriefConvergence(projectRoot: string): XbriefConvergenceDetection;
 //# sourceMappingURL=detect.d.ts.map