@deftai/directive-core 0.64.0 → 0.66.0

package/dist/intake/issue-ingest.js

@@ -1,12 +1,13 @@
 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";
 import { slugify, TODAY } from "../vbrief-build/build.js";
 import { EMITTED_VBRIEF_VERSION } from "../vbrief-build/constants.js";
-import { findAcHeading, parseCheckboxItems, parseListItems, sliceAcSection, stripCodeBlocks, } from "./markdown-scanners.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"];
 const STATUS_MAP = {
@@ -23,9 +24,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;
@@ -70,7 +71,7 @@ export function extractPlanItems(body) {
     if (body.length === 0) {
         return [];
     }
-    const text = stripCodeBlocks(body);
+    const text = stripFencedCodeBlocks(body);
     const checkboxItems = parseCheckboxItems(text);
     if (checkboxItems.length > 0) {
         return checkboxItems.map((item) => ({ title: item.title, status: item.status }));
@@ -148,7 +149,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;
@@ -241,7 +242,7 @@ export function buildIssueVbrief(issue, status, repoUrl) {
         const references = [
             {
                 uri: url,
-                type: "x-vbrief/github-issue",
+                type: "x-xbrief/github-issue",
                 title: `Issue #${number}: ${title}`,
             },
         ];
@@ -313,11 +314,11 @@ export function fetchSingleIssue(repo, number, options = {}) {
     }
 }
 export function fetchIssue(repo, number, options = {}) {
-    const cached = fetchFromCache(repo, number, options);
-    if (cached !== null) {
-        return cached;
+    const live = fetchSingleIssue(repo, number, options);
+    if (live !== null) {
+        return live;
     }
-    return fetchSingleIssue(repo, number, options);
+    return fetchFromCache(repo, number, options);
 }
 export function ingestOne(issue, options) {
     const number = Number(issue.number);
@@ -402,9 +403,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();
@@ -457,7 +460,7 @@ export function issueIngestMain(args) {
 }
 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/markdown-scanners.d.ts

@@ -2,7 +2,9 @@
  * Linear-time markdown scanners for issue body parsing (#1784 / #1248).
  * Avoids nested/polynomial regex on issue bodies (ReDoS-safe).
  */
-/** Strip fenced and inline code spans before cross-ref / plan-item extraction. */
+/** Strip fenced code blocks only (preserves inline backtick spans). */
+export declare function stripFencedCodeBlocks(body: string): string;
+/** Strip fenced and inline code spans before cross-ref extraction. */
 export declare function stripCodeBlocks(body: string): string;
 export interface CheckboxItem {
     readonly title: string;

package/dist/intake/markdown-scanners.js

@@ -2,16 +2,23 @@
  * Linear-time markdown scanners for issue body parsing (#1784 / #1248).
  * Avoids nested/polynomial regex on issue bodies (ReDoS-safe).
  */
-/** Strip fenced and inline code spans before cross-ref / plan-item extraction. */
+/** Strip fenced code blocks only (preserves inline backtick spans). */
+export function stripFencedCodeBlocks(body) {
+    if (body.length === 0) {
+        return "";
+    }
+    return stripFencedCodeBlocksInner(body);
+}
+/** Strip fenced and inline code spans before cross-ref extraction. */
 export function stripCodeBlocks(body) {
     if (body.length === 0) {
         return "";
     }
-    let text = stripFencedCodeBlocks(body);
+    let text = stripFencedCodeBlocksInner(body);
     text = stripInlineCode(text);
     return text;
 }
-function stripFencedCodeBlocks(text) {
+function stripFencedCodeBlocksInner(text) {
     let out = "";
     let i = 0;
     while (i < text.length) {

package/dist/intake/reconcile-issues.js

@@ -1,7 +1,9 @@
 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";
 import { resolveProjectRepo } from "../slice/project-context.js";
 export const LIFECYCLE_FOLDERS = [
@@ -12,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+)$/;
@@ -105,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;
@@ -406,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;
@@ -643,6 +649,7 @@ export function applyLifecycleFixes(vbriefDir, report, projectRoot = null) {
             failures.push(`failed to move ${relPath} -> ${destFolder}/`);
             continue;
         }
+        updateDecomposedChildBackReferences(data, src, dst, vbriefDir);
         moved += 1;
     }
     return [moved, skipped, failures];
@@ -665,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);

package/dist/orchestration/judgment-policy.js

@@ -1,6 +1,7 @@
 /**
  * Judgment-gate policy resolution (#1419). Port of scripts/policy.py judgment-gate section.
  */
+import { readPlanPolicy } from "../policy/plan-extensions.js";
 import { loadProjectDefinition } from "../policy/resolve.js";
 export const GATE_CLASSES = new Set(["mechanical", "declared"]);
 export const GATE_TIERS = new Set(["auto", "review", "block"]);
@@ -175,12 +176,9 @@ function defaultPolicy(source, error = null) {
     return { gates: [], disabled: [], source, error };
 }
 function getPolicyBlock(data) {
-    const plan = data.plan;
-    if (typeof plan === "object" && plan !== null && !Array.isArray(plan)) {
-        const policy = plan.policy;
-        if (typeof policy === "object" && policy !== null && !Array.isArray(policy)) {
-            return policy;
-        }
+    const policy = readPlanPolicy(data.plan);
+    if (typeof policy === "object" && policy !== null && !Array.isArray(policy)) {
+        return policy;
     }
     return {};
 }

package/dist/orchestration/verify-judgment-gates.d.ts

@@ -2,6 +2,7 @@
  * Risk-tiered judgment-gate engine (#1419 Slice 3). Port of scripts/verify_judgment_gates.py.
  */
 import { type JudgmentGatesPolicy } from "./judgment-policy.js";
+/** Display/back-compat constant; resolution flows through resolveAuditDir (#2109). */
 export declare const AUDIT_DIR_REL = "vbrief/.audit";
 export declare const CLEARANCE_LOG_NAME = "judgment-gate-clearances.jsonl";
 export declare const UNIVERSAL_SOURCE = "universal";

package/dist/orchestration/verify-judgment-gates.js

@@ -5,8 +5,10 @@ import { execFileSync } from "node:child_process";
 import { createHash, randomUUID } from "node:crypto";
 import { appendFileSync, existsSync, mkdirSync, readFileSync, statSync } from "node:fs";
 import { join, resolve } from "node:path";
+import { resolveAuditDir } from "../layout/resolve.js";
 import { resolveJudgmentGates } from "./judgment-policy.js";
 import { matchAny } from "./pathspec.js";
+/** Display/back-compat constant; resolution flows through resolveAuditDir (#2109). */
 export const AUDIT_DIR_REL = "vbrief/.audit";
 export const CLEARANCE_LOG_NAME = "judgment-gate-clearances.jsonl";
 export const UNIVERSAL_SOURCE = "universal";
@@ -131,7 +133,7 @@ export function reportBlocking(report) {
     return report.outcomes.filter(outcomeBlocking);
 }
 export function clearanceLogPath(projectRoot) {
-    return join(projectRoot, AUDIT_DIR_REL, CLEARANCE_LOG_NAME);
+    return join(resolveAuditDir(projectRoot), CLEARANCE_LOG_NAME);
 }
 function utcNowIso(now) {
     return (now ?? new Date()).toISOString().replace(/\.\d{3}Z$/, "Z");
@@ -161,7 +163,7 @@ export function readClearances(projectRoot, logPath) {
 }
 export function recordClearance(projectRoot, options) {
     const path = options.log_path ?? clearanceLogPath(projectRoot);
-    mkdirSync(join(projectRoot, AUDIT_DIR_REL), { recursive: true });
+    mkdirSync(resolveAuditDir(projectRoot), { recursive: true });
     const entry = {
         clearance_id: randomUUID(),
         timestamp: utcNowIso(options.now),

package/dist/policy/autonomy.js

@@ -1,3 +1,4 @@
+import { readPlanPolicy } from "./plan-extensions.js";
 import { loadProjectDefinition } from "./resolve.js";
 export const AUTONOMY_LEVELS = ["observe", "escalate", "execute"];
 export const DEFAULT_AUTONOMY_LEVEL = "escalate";
@@ -81,12 +82,9 @@ export function validateAutonomy(value) {
     return errors;
 }
 function getPolicyBlock(data) {
-    const plan = data.plan;
-    if (typeof plan === "object" && plan !== null && !Array.isArray(plan)) {
-        const policy = plan.policy;
-        if (typeof policy === "object" && policy !== null && !Array.isArray(policy)) {
-            return policy;
-        }
+    const policy = readPlanPolicy(data.plan);
+    if (typeof policy === "object" && policy !== null && !Array.isArray(policy)) {
+        return policy;
     }
     return {};
 }

package/dist/policy/capacity.js

@@ -1,3 +1,4 @@
+import { readPlanPolicy } from "../policy/plan-extensions.js";
 import { loadProjectDefinition } from "../policy/resolve.js";
 export const DEFAULT_CAPACITY_UNIT = "vbrief-count";
 export const CAPACITY_UNIT_COST = "cost";
@@ -124,12 +125,9 @@ export function validateCapacityAllocation(value) {
     return errors;
 }
 function getPolicyBlock(data) {
-    const plan = data.plan;
-    if (typeof plan === "object" && plan !== null && !Array.isArray(plan)) {
-        const policy = plan.policy;
-        if (typeof policy === "object" && policy !== null && !Array.isArray(policy)) {
-            return policy;
-        }
+    const policy = readPlanPolicy(data.plan);
+    if (typeof policy === "object" && policy !== null && !Array.isArray(policy)) {
+        return policy;
     }
     return {};
 }

package/dist/policy/decisions.d.ts

@@ -1,3 +1,4 @@
+/** Display/back-compat constant; resolution flows through resolveAuditDir (#2109). */
 export declare const PENDING_DECISIONS_AUDIT_DIR_REL = "vbrief/.audit";
 export declare const PENDING_DECISIONS_LOG_NAME = "pending-human-decisions.jsonl";
 export declare const DECISION_STATUS_PENDING = "pending";

package/dist/policy/decisions.js

@@ -1,12 +1,14 @@
 import { existsSync, readFileSync } from "node:fs";
-import { join, resolve } from "node:path";
+import { join } from "node:path";
+import { resolveAuditDir } from "../layout/resolve.js";
+/** Display/back-compat constant; resolution flows through resolveAuditDir (#2109). */
 export const PENDING_DECISIONS_AUDIT_DIR_REL = "vbrief/.audit";
 export const PENDING_DECISIONS_LOG_NAME = "pending-human-decisions.jsonl";
 export const DECISION_STATUS_PENDING = "pending";
 export const DECISION_STATUS_RESOLVED = "resolved";
 export const DEFAULT_PENDING_DECISIONS_THRESHOLD = 5;
 export function pendingDecisionsLogPath(projectRoot) {
-    return join(resolve(projectRoot), PENDING_DECISIONS_AUDIT_DIR_REL, PENDING_DECISIONS_LOG_NAME);
+    return join(resolveAuditDir(projectRoot), PENDING_DECISIONS_LOG_NAME);
 }
 function parseIsoTs(value) {
     if (typeof value !== "string" || value.length === 0) {

package/dist/policy/index.d.ts

@@ -2,6 +2,7 @@ export * from "./autonomy.js";
 export * from "./capacity.js";
 export * from "./decisions.js";
 export * from "./disclosure.js";
+export * from "./plan-extensions.js";
 export * from "./resolve.js";
 export * from "./wip.js";
 export declare const FIELD_ALLOW_DIRECT_COMMITS = "plan.policy.allowDirectCommitsToMaster";