@deftai/directive-core 0.65.0 → 0.66.1

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

@@ -1,6 +1,17 @@
 import { type ScmCallFn } from "./reconcile-issues.js";
 export declare const INGEST_STATUSES: readonly ["proposed", "pending", "active"];
 export type IngestStatus = (typeof INGEST_STATUSES)[number];
+/** GitHub issue comment thread entry (REST `repos/.../issues/N/comments`). */
+export interface IssueComment {
+    readonly id?: number;
+    readonly body?: string;
+    readonly user?: {
+        readonly login?: string;
+    };
+    readonly created_at?: string;
+}
+/** Enriched on issues after `fetchIssue` when the comment thread is non-empty (#2143). */
+export declare const ISSUE_COMMENT_THREAD_KEY: "issueCommentThread";
 export declare function bodyControlCharacterLabels(body: string): string[];
 export declare function warnBodyControlCharacters(number: number, body: string): void;
 export declare function extractPlanItems(body: string): Record<string, string>[];
@@ -8,6 +19,9 @@ export declare function extractAcSectionItems(text: string): Record<string, stri
 export declare function extractCrossRefs(body: string, repoUrl: string, exclude?: ReadonlySet<number>): Record<string, string>[];
 export declare function provenanceIssueNumber(data: Record<string, unknown>): number | null;
 export declare function scanProvenanceRefs(vbriefDir: string): Map<number, string[]>;
+export declare function composeOverviewWithComments(body: string, comments: readonly IssueComment[]): string;
+export declare function issueCommentThread(issue: Record<string, unknown>): IssueComment[];
+export declare function issueCommentsAlreadyFetched(issue: Record<string, unknown>): boolean;
 export declare function buildIssueVbrief(issue: Record<string, unknown>, status: IngestStatus, repoUrl: string): [Record<string, unknown>, string];
 export declare function targetFilename(number: number, title: string): string;
 export interface FetchIssueOptions {
@@ -16,6 +30,10 @@ export interface FetchIssueOptions {
     readonly scmCall?: ScmCallFn;
 }
 export declare function fetchFromCache(repo: string, number: number, options?: FetchIssueOptions): Record<string, unknown> | null;
+export declare function fetchIssueComments(repo: string, number: number, options?: FetchIssueOptions): IssueComment[];
+export declare function attachIssueCommentThread(issue: Record<string, unknown>, comments: readonly IssueComment[]): Record<string, unknown>;
+export declare function repoSlugFromUrl(repoUrl: string): string | null;
+export declare function enrichIssueWithComments(issue: Record<string, unknown>, repoUrl: string, options?: FetchIssueOptions): Record<string, unknown>;
 export declare function fetchSingleIssue(repo: string, number: number, options?: FetchIssueOptions): Record<string, unknown> | null;
 export declare function fetchIssue(repo: string, number: number, options?: FetchIssueOptions): Record<string, unknown> | null;
 export type IngestResult = "created" | "dryrun" | "duplicate";
@@ -25,6 +43,9 @@ export declare function ingestOne(issue: Record<string, unknown>, options: {
     repoUrl: string;
     dryRun?: boolean;
     existingRefs?: Map<number, string[]>;
+    scmCall?: ScmCallFn;
+    cwd?: string | null;
+    cacheRoot?: string | null;
 }): [IngestResult, string | null, string];
 export declare function ingestBulk(issues: Record<string, unknown>[], options: {
     vbriefDir: string;
@@ -32,6 +53,9 @@ export declare function ingestBulk(issues: Record<string, unknown>[], options: {
     repoUrl: string;
     label?: string | null;
     dryRun?: boolean;
+    scmCall?: ScmCallFn;
+    cwd?: string | null;
+    cacheRoot?: string | null;
 }): Record<string, string[] | number>;
 export declare function resolveRepoUrl(repo: string): string;
 export interface IssueIngestCliArgs {

package/dist/intake/issue-ingest.js

@@ -1,6 +1,7 @@
 import { mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
 import { join, resolve } from "node:path";
 import { cacheGet } from "../cache/operations.js";
+import { hasArtifactSuffix, resolveLifecycleRoot } from "../layout/resolve.js";
 import { call } from "../scm/call.js";
 import { resolveProjectRoot } from "../scope/project-context.js";
 import { resolveProjectRepo } from "../slice/project-context.js";
@@ -9,6 +10,8 @@ import { EMITTED_VBRIEF_VERSION } from "../vbrief-build/constants.js";
 import { findAcHeading, parseCheckboxItems, parseListItems, sliceAcSection, stripCodeBlocks, stripFencedCodeBlocks, } from "./markdown-scanners.js";
 import { detectRepo, extractReferencesFromVbrief, fetchOpenIssues, GITHUB_ISSUE_REF_TYPES, LIFECYCLE_FOLDERS, parseIssueNumber, } from "./reconcile-issues.js";
 export const INGEST_STATUSES = ["proposed", "pending", "active"];
+/** Enriched on issues after `fetchIssue` when the comment thread is non-empty (#2143). */
+export const ISSUE_COMMENT_THREAD_KEY = "issueCommentThread";
 const STATUS_MAP = {
     proposed: ["proposed", "proposed"],
     pending: ["pending", "pending"],
@@ -23,9 +26,9 @@ const CONTROL_CHAR_LABELS = {
 const ORIGIN_URL_PATTERN = /https?:\/\/github\.com\/[^/\s]+\/[^/\s]+\/issues\/(\d+)/;
 const ORIGIN_BARE_PATTERN = /issue\s*#(\d+)/i;
 const CROSS_REF_PATTERNS = [
-    ["x-vbrief/closes", /\b(?:close[sd]?|fix(?:e[sd])?|resolve[sd]?)\s+#(\d+)\b/i],
-    ["x-vbrief/blocks", /\bblocked[\s-]+by\s+#(\d+)\b/i],
-    ["x-vbrief/refs", /\b(?:refs?|references?|see\s+also|related(?:\s+to)?)\s+#(\d+)\b/i],
+    ["x-xbrief/closes", /\b(?:close[sd]?|fix(?:e[sd])?|resolve[sd]?)\s+#(\d+)\b/i],
+    ["x-xbrief/blocks", /\bblocked[\s-]+by\s+#(\d+)\b/i],
+    ["x-xbrief/refs", /\b(?:refs?|references?|see\s+also|related(?:\s+to)?)\s+#(\d+)\b/i],
 ];
 function hasNonIndentationPrefix(text, index) {
     const lineStart = text.lastIndexOf("\n", index) + 1;
@@ -148,7 +151,7 @@ export function scanProvenanceRefs(vbriefDir) {
             continue;
         }
         const files = readdirSync(folderPath)
-            .filter((f) => f.endsWith(".vbrief.json"))
+            .filter((f) => hasArtifactSuffix(f))
             .sort();
         for (const filename of files) {
             let data;
@@ -191,6 +194,42 @@ export function scanProvenanceRefs(vbriefDir) {
     }
     return issueToVbriefs;
 }
+export function composeOverviewWithComments(body, comments) {
+    if (comments.length === 0) {
+        return body;
+    }
+    const parts = [];
+    if (body.length > 0) {
+        parts.push(body);
+        parts.push("");
+        parts.push("---");
+        parts.push("");
+    }
+    parts.push("## Issue comment thread");
+    parts.push("");
+    parts.push("_The issue body is the original write-up; maintainer comments below may supersede it. Read the full thread before building a dispatch envelope (#2143)._");
+    parts.push("");
+    for (const comment of comments) {
+        const author = comment.user?.login ?? "unknown";
+        const when = comment.created_at ?? "";
+        const header = when.length > 0 ? `### Comment by @${author} (${when})` : `### Comment by @${author}`;
+        parts.push(header);
+        parts.push("");
+        parts.push(typeof comment.body === "string" ? comment.body : "");
+        parts.push("");
+    }
+    return parts.join("\n").trimEnd();
+}
+export function issueCommentThread(issue) {
+    const raw = issue[ISSUE_COMMENT_THREAD_KEY];
+    if (!Array.isArray(raw)) {
+        return [];
+    }
+    return raw.filter((entry) => entry !== null && typeof entry === "object");
+}
+export function issueCommentsAlreadyFetched(issue) {
+    return Object.hasOwn(issue, ISSUE_COMMENT_THREAD_KEY);
+}
 export function buildIssueVbrief(issue, status, repoUrl) {
     const number = Number(issue.number);
     const title = (typeof issue.title === "string" && issue.title.length > 0
@@ -200,6 +239,8 @@ export function buildIssueVbrief(issue, status, repoUrl) {
         (repoUrl.length > 0 ? `${repoUrl}/issues/${number}` : "");
     const bodyRaw = issue.body;
     const bodyStr = typeof bodyRaw === "string" && bodyRaw.length > 0 ? bodyRaw : "";
+    const commentThread = issueCommentThread(issue);
+    const overviewSource = commentThread.length > 0 ? composeOverviewWithComments(bodyStr, commentThread) : bodyStr;
     const labelsRaw = issue.labels;
     const labelNames = [];
     if (Array.isArray(labelsRaw)) {
@@ -220,9 +261,9 @@ export function buildIssueVbrief(issue, status, repoUrl) {
         Description: title,
         Origin: url.length > 0 ? `Ingested from ${url}` : `Ingested from issue #${number}`,
     };
-    if (bodyStr.length > 0) {
-        warnBodyControlCharacters(number, bodyStr);
-        narratives.Overview = bodyStr;
+    if (overviewSource.length > 0) {
+        warnBodyControlCharacters(number, overviewSource);
+        narratives.Overview = overviewSource;
     }
     if (labelNames.length > 0) {
         narratives.Labels = labelNames.join(", ");
@@ -241,12 +282,12 @@ export function buildIssueVbrief(issue, status, repoUrl) {
         const references = [
             {
                 uri: url,
-                type: "x-vbrief/github-issue",
+                type: "x-xbrief/github-issue",
                 title: `Issue #${number}: ${title}`,
             },
         ];
-        if (bodyStr.length > 0 && repoUrl.length > 0) {
-            references.push(...extractCrossRefs(bodyStr, repoUrl, new Set([number])));
+        if (overviewSource.length > 0 && repoUrl.length > 0) {
+            references.push(...extractCrossRefs(overviewSource, repoUrl, new Set([number])));
         }
         plan.references = references;
     }
@@ -283,6 +324,47 @@ export function fetchFromCache(repo, number, options = {}) {
         return null;
     }
 }
+export function fetchIssueComments(repo, number, options = {}) {
+    const scmCall = options.scmCall ?? call;
+    let result;
+    try {
+        result = scmCall("github-issue", "api", [`repos/${repo}/issues/${number}/comments`], {
+            timeout: 30,
+            cwd: options.cwd ?? undefined,
+        });
+    }
+    catch {
+        return [];
+    }
+    if (result.returncode !== 0) {
+        return [];
+    }
+    try {
+        const parsed = JSON.parse(result.stdout);
+        return Array.isArray(parsed) ? parsed : [];
+    }
+    catch {
+        return [];
+    }
+}
+export function attachIssueCommentThread(issue, comments) {
+    return { ...issue, [ISSUE_COMMENT_THREAD_KEY]: [...comments] };
+}
+export function repoSlugFromUrl(repoUrl) {
+    const match = /github\.com\/([^/\s]+\/[^/\s]+)/.exec(repoUrl);
+    return match?.[1] ?? null;
+}
+export function enrichIssueWithComments(issue, repoUrl, options = {}) {
+    if (issueCommentsAlreadyFetched(issue)) {
+        return issue;
+    }
+    const repo = repoSlugFromUrl(repoUrl);
+    const number = Number(issue.number);
+    if (repo === null || !Number.isFinite(number)) {
+        return issue;
+    }
+    return attachIssueCommentThread(issue, fetchIssueComments(repo, number, options));
+}
 export function fetchSingleIssue(repo, number, options = {}) {
     const scmCall = options.scmCall ?? call;
     let result;
@@ -315,9 +397,15 @@ export function fetchSingleIssue(repo, number, options = {}) {
 export function fetchIssue(repo, number, options = {}) {
     const live = fetchSingleIssue(repo, number, options);
     if (live !== null) {
-        return live;
+        const comments = fetchIssueComments(repo, number, options);
+        return attachIssueCommentThread(live, comments);
+    }
+    const cached = fetchFromCache(repo, number, options);
+    if (cached === null) {
+        return null;
     }
-    return fetchFromCache(repo, number, options);
+    const comments = fetchIssueComments(repo, number, options);
+    return attachIssueCommentThread(cached, comments);
 }
 export function ingestOne(issue, options) {
     const number = Number(issue.number);
@@ -330,7 +418,12 @@ export function ingestOne(issue, options) {
             `#${number} already ingested at ${existing}`,
         ];
     }
-    const [vbrief, folder] = buildIssueVbrief(issue, options.status, options.repoUrl);
+    const enriched = enrichIssueWithComments(issue, options.repoUrl, {
+        scmCall: options.scmCall,
+        cwd: options.cwd,
+        cacheRoot: options.cacheRoot,
+    });
+    const [vbrief, folder] = buildIssueVbrief(enriched, options.status, options.repoUrl);
     const filename = targetFilename(number, String(issue.title ?? ""));
     const target = join(options.vbriefDir, folder, filename);
     if (options.dryRun) {
@@ -402,9 +495,11 @@ export function issueIngestMain(args) {
         process.stderr.write("Error: Use either a single issue number OR --all, not both\n");
         return 2;
     }
-    const vbriefDir = resolve(args.vbriefDir ?? "./vbrief");
-    mkdirSync(vbriefDir, { recursive: true });
     const projectRoot = resolveProjectRoot(args.projectRoot ?? undefined);
+    const vbriefDir = args.vbriefDir
+        ? resolve(args.vbriefDir)
+        : resolveLifecycleRoot(args.projectRoot ? resolve(args.projectRoot) : resolve("."));
+    mkdirSync(vbriefDir, { recursive: true });
     let repo = resolveProjectRepo(args.repo ?? undefined, projectRoot);
     if (repo === null) {
         repo = detectRepo();
@@ -426,6 +521,7 @@ export function issueIngestMain(args) {
             repoUrl,
             label: args.label,
             dryRun: args.dryRun,
+            cwd: projectRoot,
         });
         const created = summary.created;
         const duplicate = summary.duplicate;
@@ -451,13 +547,14 @@ export function issueIngestMain(args) {
         status,
         repoUrl,
         dryRun: args.dryRun,
+        cwd: projectRoot,
     });
     process.stdout.write(`${msg}\n`);
     return result === "duplicate" ? 1 : 0;
 }
 export function ingestSingleForAccept(n, repo, options = {}) {
     const root = resolve(options.projectRoot ?? process.cwd());
-    const vbriefDir = resolve(root, "vbrief");
+    const vbriefDir = resolveLifecycleRoot(root);
     mkdirSync(vbriefDir, { recursive: true });
     const repoUrl = resolveRepoUrl(repo);
     const issue = fetchIssue(repo, n, {

package/dist/intake/reconcile-issues.js

@@ -1,6 +1,7 @@
 import { execFileSync } from "node:child_process";
 import { mkdirSync, readdirSync, readFileSync, renameSync, statSync, writeFileSync } from "node:fs";
 import { join, resolve } from "node:path";
+import { hasArtifactSuffix, resolveLifecycleRoot } from "../layout/resolve.js";
 import { call } from "../scm/call.js";
 import { updateDecomposedChildBackReferences } from "../scope/decomposed-refs.js";
 import { resolveProjectRoot } from "../scope/project-context.js";
@@ -13,7 +14,11 @@ export const LIFECYCLE_FOLDERS = [
     "cancelled",
 ];
 export const TERMINAL_LIFECYCLE_FOLDERS = new Set(["completed", "cancelled"]);
-export const GITHUB_ISSUE_REF_TYPES = new Set(["github-issue", "x-vbrief/github-issue"]);
+export const GITHUB_ISSUE_REF_TYPES = new Set([
+    "github-issue",
+    "x-vbrief/github-issue",
+    "x-xbrief/github-issue",
+]);
 export const CANCELLED_STATE_REASONS = new Set(["NOT_PLANNED", "DUPLICATE"]);
 const ISSUE_URL_PATTERN = /https:\/\/github\.com\/([^/\s]+)\/([^/\s]+)\/issues\/(\d+)/;
 const ISSUE_ID_PATTERN = /^#(\d+)$/;
@@ -106,7 +111,7 @@ export function scanVbriefDir(vbriefDir) {
             continue;
         }
         const files = readdirSync(folderPath)
-            .filter((f) => f.endsWith(".vbrief.json"))
+            .filter((f) => hasArtifactSuffix(f))
             .sort();
         for (const filename of files) {
             let data;
@@ -407,7 +412,7 @@ export function scanLifecycleAnchors(vbriefDir) {
             continue;
         }
         const files = readdirSync(folderPath)
-            .filter((f) => f.endsWith(".vbrief.json"))
+            .filter((f) => hasArtifactSuffix(f))
             .sort();
         for (const filename of files) {
             let data;
@@ -667,7 +672,9 @@ export function detectRepo() {
     return null;
 }
 export function reconcileMain(args) {
-    const vbriefDir = resolve(args.vbriefDir ?? "./vbrief");
+    const vbriefDir = args.vbriefDir
+        ? resolve(args.vbriefDir)
+        : resolveLifecycleRoot(args.projectRoot ? resolve(args.projectRoot) : resolve("."));
     try {
         if (!statSync(vbriefDir).isDirectory()) {
             process.stderr.write(`Error: vbrief directory not found: ${vbriefDir}\n`);

package/dist/layout/index.d.ts

@@ -0,0 +1,2 @@
+export { ARTIFACT_SUFFIXES, hasArtifactSuffix, isLifecycleArtifactPath, LEGACY_ARTIFACT_DIR, LEGACY_ARTIFACT_SUFFIX, LEGACY_INFO_ROOT_KEY, LIFECYCLE_DIR_NAMES, type LifecycleLayout, MIGRATED_ARTIFACT_DIR, MIGRATED_ARTIFACT_SUFFIX, MIGRATED_INFO_ROOT_KEY, projectDefinitionFilename, projectDefinitionRelPath, resolveAuditDir, resolveAuditPath, resolveEvalDir, resolveEvalPath, resolveLifecycleFolder, resolveLifecycleLayout, resolveLifecycleRoot, resolveProjectDefinitionPath, resolveSpecArtifactPath, specArtifactRelPath, stripArtifactSuffix, } from "./resolve.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/layout/index.js

@@ -0,0 +1,2 @@
+export { ARTIFACT_SUFFIXES, hasArtifactSuffix, isLifecycleArtifactPath, LEGACY_ARTIFACT_DIR, LEGACY_ARTIFACT_SUFFIX, LEGACY_INFO_ROOT_KEY, LIFECYCLE_DIR_NAMES, MIGRATED_ARTIFACT_DIR, MIGRATED_ARTIFACT_SUFFIX, MIGRATED_INFO_ROOT_KEY, projectDefinitionFilename, projectDefinitionRelPath, resolveAuditDir, resolveAuditPath, resolveEvalDir, resolveEvalPath, resolveLifecycleFolder, resolveLifecycleLayout, resolveLifecycleRoot, resolveProjectDefinitionPath, resolveSpecArtifactPath, specArtifactRelPath, stripArtifactSuffix, } from "./resolve.js";
+//# sourceMappingURL=index.js.map

package/dist/layout/resolve.d.ts

@@ -0,0 +1,87 @@
+import { LEGACY_ARTIFACT_DIR, LEGACY_ARTIFACT_SUFFIX, LEGACY_INFO_ROOT_KEY, MIGRATED_ARTIFACT_DIR, MIGRATED_ARTIFACT_SUFFIX, MIGRATED_INFO_ROOT_KEY } from "../xbrief-migrate/constants.js";
+export { LEGACY_ARTIFACT_DIR, LEGACY_ARTIFACT_SUFFIX, LEGACY_INFO_ROOT_KEY, MIGRATED_ARTIFACT_DIR, MIGRATED_ARTIFACT_SUFFIX, MIGRATED_INFO_ROOT_KEY, };
+/**
+ * Lifecycle directory names recognized by the layout-aware resolver, in
+ * preference order (migrated `xbrief` first, legacy `vbrief` second).
+ */
+export declare const LIFECYCLE_DIR_NAMES: readonly ["xbrief", "vbrief"];
+/**
+ * Artifact filename suffixes recognized by the layout-aware resolver, in
+ * preference order (`.xbrief.json` first, `.vbrief.json` second).
+ */
+export declare const ARTIFACT_SUFFIXES: readonly [".xbrief.json", ".vbrief.json"];
+/** The on-disk lifecycle layout an engine call site should resolve against (#2109). */
+export interface LifecycleLayout {
+    /** The lifecycle directory name -- `xbrief` when migrated, else `vbrief`. */
+    readonly artifactDir: typeof MIGRATED_ARTIFACT_DIR | typeof LEGACY_ARTIFACT_DIR;
+    /** The artifact filename suffix matching `artifactDir`. */
+    readonly artifactSuffix: typeof MIGRATED_ARTIFACT_SUFFIX | typeof LEGACY_ARTIFACT_SUFFIX;
+    /** The `*BRIEFInfo` root key matching `artifactDir`. */
+    readonly infoRootKey: typeof MIGRATED_INFO_ROOT_KEY | typeof LEGACY_INFO_ROOT_KEY;
+    /** Absolute path to the resolved lifecycle root (`<projectRoot>/<artifactDir>`). */
+    readonly root: string;
+    /** True when the resolved layout is the migrated `xbrief` layout. */
+    readonly migrated: boolean;
+}
+/** True when `name` ends with any recognized artifact suffix (.xbrief.json or .vbrief.json). */
+export declare function hasArtifactSuffix(name: string): boolean;
+/**
+ * Strip whichever recognized artifact suffix `name` ends with. Returns `name`
+ * unchanged when it carries no recognized suffix.
+ */
+export declare function stripArtifactSuffix(name: string): string;
+/**
+ * True when a POSIX-style path is a lifecycle artifact under either layout
+ * root (`xbrief/` or `vbrief/`) carrying either artifact suffix.
+ */
+export declare function isLifecycleArtifactPath(posix: string): boolean;
+/**
+ * Resolve the active lifecycle layout for `projectRoot` (#2109 part 1).
+ *
+ * Prefers the migrated `xbrief/` layout only when BOTH the `xbrief/` directory
+ * exists AND it contains at least one `.xbrief.json` artifact; otherwise falls
+ * back to the legacy `vbrief/` layout. With only `vbrief/` present (today's
+ * repo) the result is the legacy layout, so existing behavior is unchanged.
+ */
+export declare function resolveLifecycleLayout(projectRoot: string): LifecycleLayout;
+/** Convenience accessor for the absolute resolved lifecycle root directory. */
+export declare function resolveLifecycleRoot(projectRoot: string): string;
+/**
+ * Absolute path to a lifecycle folder under the resolved layout root
+ * (e.g. `<root>/<xbrief|vbrief>/active`). Layout-aware (#2109 part 2a).
+ */
+export declare function resolveLifecycleFolder(projectRoot: string, folder: string): string;
+/** Absolute path to the resolved lifecycle `.eval` cache directory (#2109 part 2a). */
+export declare function resolveEvalDir(projectRoot: string): string;
+/** Absolute path to a file or subpath under the resolved `.eval` cache directory. */
+export declare function resolveEvalPath(projectRoot: string, ...segments: string[]): string;
+/** Absolute path to the resolved lifecycle `.audit` directory (#2109 part 2a). */
+export declare function resolveAuditDir(projectRoot: string): string;
+/** Absolute path to a file or subpath under the resolved `.audit` directory. */
+export declare function resolveAuditPath(projectRoot: string, ...segments: string[]): string;
+/**
+ * The PROJECT-DEFINITION artifact filename for the resolved layout
+ * (`PROJECT-DEFINITION.xbrief.json` when migrated, else `.vbrief.json`).
+ */
+export declare function projectDefinitionFilename(projectRoot: string): string;
+/** Absolute path to the resolved PROJECT-DEFINITION artifact (#2109 part 2a). */
+export declare function resolveProjectDefinitionPath(projectRoot: string): string;
+/**
+ * POSIX-style display path to the resolved PROJECT-DEFINITION artifact relative
+ * to the project root (e.g. `vbrief/PROJECT-DEFINITION.vbrief.json`).
+ */
+export declare function projectDefinitionRelPath(projectRoot: string): string;
+/**
+ * Absolute path to the resolved specification artifact (#2132).
+ *
+ * Prefers `xbrief/specification.xbrief.json` on a migrated tree; falls back to
+ * `vbrief/specification.vbrief.json` on an unmigrated tree. Consistent with the
+ * layout resolver used by the #2109 Part-2a call-site sweep.
+ */
+export declare function resolveSpecArtifactPath(projectRoot: string): string;
+/**
+ * POSIX-style display path to the resolved specification artifact relative to
+ * the project root (e.g. `xbrief/specification.xbrief.json`).
+ */
+export declare function specArtifactRelPath(projectRoot: string): string;
+//# sourceMappingURL=resolve.d.ts.map

package/dist/layout/resolve.js

@@ -0,0 +1,159 @@
+import { readdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { LEGACY_ARTIFACT_DIR, LEGACY_ARTIFACT_SUFFIX, LEGACY_INFO_ROOT_KEY, MIGRATED_ARTIFACT_DIR, MIGRATED_ARTIFACT_SUFFIX, MIGRATED_INFO_ROOT_KEY, } from "../xbrief-migrate/constants.js";
+export { LEGACY_ARTIFACT_DIR, LEGACY_ARTIFACT_SUFFIX, LEGACY_INFO_ROOT_KEY, MIGRATED_ARTIFACT_DIR, MIGRATED_ARTIFACT_SUFFIX, MIGRATED_INFO_ROOT_KEY, };
+/**
+ * Lifecycle directory names recognized by the layout-aware resolver, in
+ * preference order (migrated `xbrief` first, legacy `vbrief` second).
+ */
+export const LIFECYCLE_DIR_NAMES = [MIGRATED_ARTIFACT_DIR, LEGACY_ARTIFACT_DIR];
+/**
+ * Artifact filename suffixes recognized by the layout-aware resolver, in
+ * preference order (`.xbrief.json` first, `.vbrief.json` second).
+ */
+export const ARTIFACT_SUFFIXES = [MIGRATED_ARTIFACT_SUFFIX, LEGACY_ARTIFACT_SUFFIX];
+function isDirectory(path) {
+    try {
+        return statSync(path).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+/** True when `name` ends with any recognized artifact suffix (.xbrief.json or .vbrief.json). */
+export function hasArtifactSuffix(name) {
+    return ARTIFACT_SUFFIXES.some((suffix) => name.endsWith(suffix));
+}
+/**
+ * Strip whichever recognized artifact suffix `name` ends with. Returns `name`
+ * unchanged when it carries no recognized suffix.
+ */
+export function stripArtifactSuffix(name) {
+    for (const suffix of ARTIFACT_SUFFIXES) {
+        if (name.endsWith(suffix)) {
+            return name.slice(0, -suffix.length);
+        }
+    }
+    return name;
+}
+/**
+ * True when a POSIX-style path is a lifecycle artifact under either layout
+ * root (`xbrief/` or `vbrief/`) carrying either artifact suffix.
+ */
+export function isLifecycleArtifactPath(posix) {
+    const underLifecycleDir = LIFECYCLE_DIR_NAMES.some((dir) => posix.startsWith(`${dir}/`));
+    return underLifecycleDir && hasArtifactSuffix(posix);
+}
+/** Walk `root` looking for any `.xbrief.json` file (bounded iterative scan). */
+function containsMigratedArtifact(root) {
+    const stack = [root];
+    while (stack.length > 0) {
+        const dir = stack.pop();
+        if (dir === undefined || !isDirectory(dir)) {
+            continue;
+        }
+        for (const entry of readdirSync(dir, { withFileTypes: true })) {
+            if (entry.isDirectory()) {
+                stack.push(join(dir, entry.name));
+            }
+            else if (entry.isFile() && entry.name.endsWith(MIGRATED_ARTIFACT_SUFFIX)) {
+                return true;
+            }
+        }
+    }
+    return false;
+}
+/**
+ * Resolve the active lifecycle layout for `projectRoot` (#2109 part 1).
+ *
+ * Prefers the migrated `xbrief/` layout only when BOTH the `xbrief/` directory
+ * exists AND it contains at least one `.xbrief.json` artifact; otherwise falls
+ * back to the legacy `vbrief/` layout. With only `vbrief/` present (today's
+ * repo) the result is the legacy layout, so existing behavior is unchanged.
+ */
+export function resolveLifecycleLayout(projectRoot) {
+    const migratedRoot = join(projectRoot, MIGRATED_ARTIFACT_DIR);
+    if (isDirectory(migratedRoot) && containsMigratedArtifact(migratedRoot)) {
+        return {
+            artifactDir: MIGRATED_ARTIFACT_DIR,
+            artifactSuffix: MIGRATED_ARTIFACT_SUFFIX,
+            infoRootKey: MIGRATED_INFO_ROOT_KEY,
+            root: migratedRoot,
+            migrated: true,
+        };
+    }
+    return {
+        artifactDir: LEGACY_ARTIFACT_DIR,
+        artifactSuffix: LEGACY_ARTIFACT_SUFFIX,
+        infoRootKey: LEGACY_INFO_ROOT_KEY,
+        root: join(projectRoot, LEGACY_ARTIFACT_DIR),
+        migrated: false,
+    };
+}
+/** Convenience accessor for the absolute resolved lifecycle root directory. */
+export function resolveLifecycleRoot(projectRoot) {
+    return resolveLifecycleLayout(projectRoot).root;
+}
+/**
+ * Absolute path to a lifecycle folder under the resolved layout root
+ * (e.g. `<root>/<xbrief|vbrief>/active`). Layout-aware (#2109 part 2a).
+ */
+export function resolveLifecycleFolder(projectRoot, folder) {
+    return join(resolveLifecycleRoot(projectRoot), folder);
+}
+/** Absolute path to the resolved lifecycle `.eval` cache directory (#2109 part 2a). */
+export function resolveEvalDir(projectRoot) {
+    return join(resolveLifecycleRoot(projectRoot), ".eval");
+}
+/** Absolute path to a file or subpath under the resolved `.eval` cache directory. */
+export function resolveEvalPath(projectRoot, ...segments) {
+    return join(resolveEvalDir(projectRoot), ...segments);
+}
+/** Absolute path to the resolved lifecycle `.audit` directory (#2109 part 2a). */
+export function resolveAuditDir(projectRoot) {
+    return join(resolveLifecycleRoot(projectRoot), ".audit");
+}
+/** Absolute path to a file or subpath under the resolved `.audit` directory. */
+export function resolveAuditPath(projectRoot, ...segments) {
+    return join(resolveAuditDir(projectRoot), ...segments);
+}
+/**
+ * The PROJECT-DEFINITION artifact filename for the resolved layout
+ * (`PROJECT-DEFINITION.xbrief.json` when migrated, else `.vbrief.json`).
+ */
+export function projectDefinitionFilename(projectRoot) {
+    return `PROJECT-DEFINITION${resolveLifecycleLayout(projectRoot).artifactSuffix}`;
+}
+/** Absolute path to the resolved PROJECT-DEFINITION artifact (#2109 part 2a). */
+export function resolveProjectDefinitionPath(projectRoot) {
+    const layout = resolveLifecycleLayout(projectRoot);
+    return join(layout.root, `PROJECT-DEFINITION${layout.artifactSuffix}`);
+}
+/**
+ * POSIX-style display path to the resolved PROJECT-DEFINITION artifact relative
+ * to the project root (e.g. `vbrief/PROJECT-DEFINITION.vbrief.json`).
+ */
+export function projectDefinitionRelPath(projectRoot) {
+    const layout = resolveLifecycleLayout(projectRoot);
+    return `${layout.artifactDir}/PROJECT-DEFINITION${layout.artifactSuffix}`;
+}
+/**
+ * Absolute path to the resolved specification artifact (#2132).
+ *
+ * Prefers `xbrief/specification.xbrief.json` on a migrated tree; falls back to
+ * `vbrief/specification.vbrief.json` on an unmigrated tree. Consistent with the
+ * layout resolver used by the #2109 Part-2a call-site sweep.
+ */
+export function resolveSpecArtifactPath(projectRoot) {
+    const layout = resolveLifecycleLayout(projectRoot);
+    return join(layout.root, `specification${layout.artifactSuffix}`);
+}
+/**
+ * POSIX-style display path to the resolved specification artifact relative to
+ * the project root (e.g. `xbrief/specification.xbrief.json`).
+ */
+export function specArtifactRelPath(projectRoot) {
+    const layout = resolveLifecycleLayout(projectRoot);
+    return `${layout.artifactDir}/specification${layout.artifactSuffix}`;
+}
+//# sourceMappingURL=resolve.js.map

package/dist/lifecycle/lifecycle-hygiene.d.ts

@@ -9,7 +9,7 @@ export declare const LIFECYCLE_FOLDERS: readonly ["proposed", "pending", "active
 /** plan.status values that make an epic terminal. */
 export declare const TERMINAL_STATUSES: Set<string>;
 /** Child reference type that marks an epic as decomposed. */
-export declare const CHILD_REF_TYPE = "x-vbrief/plan";
+export declare const CHILD_REF_TYPE = "x-xbrief/plan";
 /** Durable tech-debt acceptance ledger relative path segments. */
 export declare const TECH_DEBT_LEDGER_RELPATH: readonly ["vbrief", ".audit", "epic-tech-debt-accepted.jsonl"];
 /** Session-start nudge tiers (rate-of-harm ranking). */

package/dist/lifecycle/lifecycle-hygiene.js

@@ -1,7 +1,10 @@
 import { appendFileSync, existsSync, mkdirSync, readdirSync, readFileSync, statSync, } from "node:fs";
 import { basename, join, resolve } from "node:path";
+import { referenceTypeMatches } from "@deftai/directive-types";
 import { computeReport } from "../capacity/show.js";
+import { hasArtifactSuffix, resolveLifecycleRoot } from "../layout/resolve.js";
 import { resolveCapacityAllocation } from "../policy/capacity.js";
+import { readPlanPolicy } from "../policy/plan-extensions.js";
 import { loadProjectDefinition } from "../policy/resolve.js";
 /** Default dormancy (days) past which a partially-completed epic is stranded. */
 export const EPIC_STRANDED_DAYS_DEFAULT = 30;
@@ -20,7 +23,7 @@ export const LIFECYCLE_FOLDERS = [
 /** plan.status values that make an epic terminal. */
 export const TERMINAL_STATUSES = new Set(["completed", "cancelled", "failed"]);
 /** Child reference type that marks an epic as decomposed. */
-export const CHILD_REF_TYPE = "x-vbrief/plan";
+export const CHILD_REF_TYPE = "x-xbrief/plan";
 /** Durable tech-debt acceptance ledger relative path segments. */
 export const TECH_DEBT_LEDGER_RELPATH = [
     "vbrief",
@@ -48,7 +51,7 @@ export function resolveEpicThresholds(projectRoot) {
     if (data !== null && typeof data === "object") {
         const plan = data.plan;
         if (typeof plan === "object" && plan !== null && !Array.isArray(plan)) {
-            const pol = plan.policy;
+            const pol = readPlanPolicy(plan);
             if (typeof pol === "object" && pol !== null && !Array.isArray(pol)) {
                 const cap = pol.capacityAllocation;
                 if (typeof cap === "object" && cap !== null && !Array.isArray(cap)) {
@@ -125,7 +128,7 @@ function childRefNames(plan) {
             continue;
         }
         const rec = ref;
-        if (rec.type !== CHILD_REF_TYPE) {
+        if (!referenceTypeMatches(String(rec.type ?? ""), "plan")) {
             continue;
         }
         const uri = rec.uri;
@@ -137,14 +140,14 @@ function childRefNames(plan) {
 }
 function iterVbriefs(projectRoot) {
     const out = [];
-    const vroot = join(resolve(projectRoot), "vbrief");
+    const vroot = resolveLifecycleRoot(projectRoot);
     for (const folder of LIFECYCLE_FOLDERS) {
         const fdir = join(vroot, folder);
         if (!existsSync(fdir)) {
             continue;
         }
         const children = readdirSync(fdir)
-            .filter((name) => name.endsWith(".vbrief.json"))
+            .filter((name) => hasArtifactSuffix(name))
             .sort();
         for (const name of children) {
             const child = join(fdir, name);