@deftai/directive-core 0.66.2 → 0.68.0

package/dist/init-deposit/hygiene.js

@@ -0,0 +1,176 @@
+/**
+ * Scoped staging + installer-managed allowlist for TS-native init/update (#1453).
+ *
+ * Mirrors cmd/deft-install/hygiene.go + deposit.go installerManagedMatchers.
+ * Refs #1576, #1453, #1430.
+ */
+import { execFileSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { join, relative } from "node:path";
+import { gitPorcelain } from "../story-ready/git.js";
+import { CANONICAL_INSTALL_ROOT } from "./constants.js";
+export const CODEQL_CONFIG_REL = ".github/codeql/codeql-config.yml";
+export const CORE_GUARD_WORKFLOW_REL = ".github/workflows/deft-core-guard.yml";
+const VBRIEF_LIFECYCLE_DIRS = ["proposed", "pending", "active", "completed", "cancelled"];
+/** Single source of truth for installer-managed paths (#1440 / #1576). */
+export function installerManagedMatchers() {
+    return [
+        { exact: "AGENTS.md" },
+        { prefix: ".agents/" },
+        { prefix: ".githooks/" },
+        { exact: ".gitattributes" },
+        { exact: ".gitignore" },
+        { exact: "greptile.json" },
+        { exact: CODEQL_CONFIG_REL },
+        { exact: CORE_GUARD_WORKFLOW_REL },
+        { exact: "Taskfile.yml" },
+        { exact: "vbrief/.deft-version" },
+        { exact: "vbrief/vbrief.md" },
+        { prefix: "vbrief/schemas/" },
+        { prefix: "vbrief/migration/" },
+        ...VBRIEF_LIFECYCLE_DIRS.map((sub) => ({ exact: `vbrief/${sub}/.gitkeep` })),
+    ];
+}
+function escapeEre(value) {
+    return value.replace(/[.^$*+?()[\]{}|\\]/g, "\\$&");
+}
+function matcherToEre(matcher) {
+    if (matcher.exact)
+        return `^${escapeEre(matcher.exact)}$`;
+    return `^${escapeEre(matcher.prefix ?? "")}`;
+}
+/** POSIX ERE alternation embedded in the deposited deft-core-guard workflow. */
+export function installerManagedGuardEre() {
+    return installerManagedMatchers()
+        .map((matcher) => matcherToEre(matcher))
+        .join("|");
+}
+function matchesInstallerManaged(path, matchers) {
+    for (const matcher of matchers) {
+        if (matcher.exact && path === matcher.exact)
+            return true;
+        if (matcher.prefix && path.startsWith(matcher.prefix))
+            return true;
+    }
+    return false;
+}
+export function isInstallerManagedPath(path) {
+    return matchesInstallerManaged(path, installerManagedMatchers());
+}
+export function frameworkStagePaths(projectDir, deftDir, options = {}) {
+    const paths = [];
+    const seen = new Set();
+    const add = (rel) => {
+        const normalized = rel.replace(/\\/g, "/");
+        if (!normalized || normalized === "." || seen.has(normalized))
+            return;
+        if (!existsSync(join(projectDir, normalized)))
+            return;
+        seen.add(normalized);
+        paths.push(normalized);
+    };
+    const relDeft = relative(projectDir, deftDir);
+    if (relDeft && !relDeft.startsWith("..") && !relDeft.startsWith("/")) {
+        add(relDeft);
+    }
+    for (const matcher of installerManagedMatchers()) {
+        if (matcher.exact === "Taskfile.yml" && !options.includeTaskfile)
+            continue;
+        if (matcher.exact) {
+            add(matcher.exact);
+        }
+        else if (matcher.prefix) {
+            add(matcher.prefix.replace(/\/$/, ""));
+        }
+    }
+    return paths;
+}
+/** Best-effort scoped `git add` — never fails the install/update (#1453 Layer 2b). */
+export function stageFrameworkPaths(projectDir, paths, seams = {}) {
+    if (paths.length === 0)
+        return { staged: false, error: null };
+    const readPorcelain = seams.gitPorcelain ?? gitPorcelain;
+    if (readPorcelain(projectDir) === null)
+        return { staged: false, error: null };
+    const runGitAdd = seams.runGitAdd ??
+        ((root, stagePaths) => {
+            execFileSync("git", ["add", ...stagePaths], {
+                cwd: root,
+                encoding: "utf8",
+                stdio: ["ignore", "pipe", "pipe"],
+            });
+        });
+    try {
+        runGitAdd(projectDir, paths);
+        return { staged: true, error: null };
+    }
+    catch (cause) {
+        const error = cause instanceof Error ? cause : new Error(String(cause));
+        return { staged: false, error };
+    }
+}
+export const COMMIT_HYGIENE_BRANCH_NAME = "chore/deft-framework-upgrade";
+export function printCommitGuidance(io, paths, staged) {
+    if (paths.length === 0)
+        return;
+    const addCmd = `git add ${paths.join(" ")}`;
+    io.printf("\nCommit hygiene (#1453, #1671): keep the framework deposit in its OWN branch/PR.\n");
+    io.printf("Do NOT use `git add -A` -- mixing the payload with your own files trips the\n");
+    io.printf("deft-core-guard CI check.\n");
+    if (staged) {
+        io.printf("The installer already staged ONLY these framework + installer-managed paths:\n");
+        io.printf(`  ${addCmd}\n`);
+    }
+    else {
+        io.printf("Stage ONLY these framework + installer-managed paths:\n");
+        io.printf(`  ${addCmd}\n`);
+    }
+    io.printf("Then take the framework deposit through the full PR lifecycle so deft-core-guard\n");
+    io.printf("evaluates a clean, standalone PR:\n");
+    io.printf(`  1. Branch: git switch -c ${COMMIT_HYGIENE_BRANCH_NAME}\n`);
+    io.printf('  2. Commit: git commit -m "chore(deft): update framework payload"\n');
+    io.printf(`  3. Push:   git push -u origin ${COMMIT_HYGIENE_BRANCH_NAME}\n`);
+    io.printf('  4. PR:     gh pr create --fill --title "chore(deft): update framework payload"\n');
+    io.printf("  5. Merge:  gh pr merge --squash --delete-branch   # after deft-core-guard passes\n");
+}
+function defaultCachedNames(projectDir) {
+    try {
+        const out = execFileSync("git", ["diff", "--cached", "--name-only", "-z"], {
+            cwd: projectDir,
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        return out
+            .split("\0")
+            .map((entry) => entry.trim().replace(/\\/g, "/"))
+            .filter(Boolean);
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Narrow the candidate stage paths to those that actually have staged index
+ * changes. A candidate file matches when the cached name is identical; a
+ * candidate directory (e.g. ``.deft/core``) matches when any cached name lives
+ * beneath it. This keeps ``staged_paths`` honest for downstream automation --
+ * it reports what git actually staged, not every path passed to ``git add``.
+ */
+function actuallyStagedPaths(stagePaths, cachedNames) {
+    return stagePaths.filter((candidate) => cachedNames.some((name) => name === candidate || name.startsWith(`${candidate}/`)));
+}
+export function depositStagePaths(projectDir, options = {}) {
+    const deftDir = join(projectDir, CANONICAL_INSTALL_ROOT);
+    const stagePaths = frameworkStagePaths(projectDir, deftDir, {
+        includeTaskfile: options.includeTaskfile ?? false,
+    });
+    const { staged } = stageFrameworkPaths(projectDir, stagePaths, options);
+    const readCachedNames = options.readCachedNames ?? defaultCachedNames;
+    const cachedNames = staged ? readCachedNames(projectDir) : [];
+    return {
+        stagePaths,
+        staged,
+        stagedPaths: staged ? actuallyStagedPaths(stagePaths, cachedNames) : [],
+    };
+}
+//# sourceMappingURL=hygiene.js.map

package/dist/init-deposit/init-deposit.d.ts

@@ -19,6 +19,7 @@ export interface InitDepositResult {
     readonly taskfileWired: boolean;
     readonly configDir: string;
     readonly legacyLayout: boolean;
+    readonly stagedPaths: string[];
 }
 export interface InitDepositSeams {
     resolveContentRoot?: () => Promise<string>;

package/dist/init-deposit/init-deposit.js

@@ -13,6 +13,7 @@ import { prunePythonArtifactsFromDeposit } from "../deposit/python-free.js";
 import { resolveInstalledContentRoot } from "../deposit/resolve-content.js";
 import { readCorePackageVersion } from "../engine-version.js";
 import { ensureInitGitignoreLines, reconstituteDepositFromContent } from "./gitignore.js";
+import { depositStagePaths, printCommitGuidance } from "./hygiene.js";
 import { buildLegacyRefusalJson, buildLegacyRefusalMessage, detectLegacyLayout, LEGACY_LAYOUT_REFUSED_EXIT_CODE, LegacyLayoutRefusedError, } from "./legacy-detect.js";
 import { printMigrateNudgeIfNeeded } from "./migrate.js";
 import { CANONICAL_INSTALL_ROOT, depositNeutralization, ensureTaskfile, writeAgentsMd, writeAgentsSkills, writeConsumerGitHooks, writeConsumerVbrief, writeInstallManifest, } from "./scaffold.js";
@@ -93,7 +94,7 @@ export function buildInstallSummaryJson(result, options) {
         strategy: "vendor",
         dirty_tree: false,
         dirty_files: [],
-        staged_paths: [],
+        staged_paths: result.stagedPaths,
         backup_path: "",
         previous_version: "",
     };
@@ -150,6 +151,10 @@ export async function runInitDeposit(args, io, seams = {}) {
         taskfileWired = ensureTaskfile(projectDir, io);
     }
     const configDir = createUserConfigDir(io);
+    const { stagePaths, staged, stagedPaths } = depositStagePaths(projectDir, {
+        includeTaskfile: taskfileWired,
+    });
+    printCommitGuidance(io, stagePaths, staged);
     return {
         projectDir,
         deftDir,
@@ -157,6 +162,7 @@ export async function runInitDeposit(args, io, seams = {}) {
         taskfileWired,
         configDir,
         legacyLayout: false,
+        stagedPaths,
     };
 }
 /** CLI-facing wrapper: runs deposit, emits JSON or wizard UX, returns exit code. */

package/dist/init-deposit/refresh.d.ts

@@ -22,6 +22,8 @@ export interface RefreshDepositResult {
     readonly agentsMdUpdated: boolean;
     readonly versionSkewNotice: string | null;
     readonly legacyLayout: boolean;
+    readonly taskfileWired: boolean;
+    readonly stagedPaths: string[];
 }
 export interface RefreshDepositSeams {
     resolveContentRoot?: () => Promise<string>;

package/dist/init-deposit/refresh.js

@@ -7,7 +7,7 @@
  *
  * Refs #1942, #1430, #1671.
  */
-import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, renameSync, statSync, writeFileSync } from "node:fs";
 import { join, resolve } from "node:path";
 import { copyTree } from "../deposit/copy-tree.js";
 import { prunePythonArtifactsFromDeposit } from "../deposit/python-free.js";
@@ -17,31 +17,11 @@ import { readCorePackageVersion } from "../engine-version.js";
 import { resolveLifecycleRoot } from "../layout/resolve.js";
 import { DEV_FALLBACK } from "../platform/constants.js";
 import { gitPorcelain } from "../story-ready/git.js";
+import { depositStagePaths, isInstallerManagedPath, printCommitGuidance } from "./hygiene.js";
 import { parseInitArgv } from "./init-deposit.js";
 import { buildLegacyRefusalJson, buildLegacyRefusalMessage, detectLegacyLayout, LEGACY_LAYOUT_REFUSED_EXIT_CODE, LegacyLayoutRefusedError, } from "./legacy-detect.js";
 import { printMigrateNudgeIfNeeded } from "./migrate.js";
-import { CANONICAL_INSTALL_ROOT, depositNeutralization, writeAgentsMd, writeInstallManifest, } from "./scaffold.js";
-const INSTALLER_MANAGED_EXACT = new Set([
-    "AGENTS.md",
-    ".gitattributes",
-    ".gitignore",
-    "greptile.json",
-    ".github/codeql/codeql-config.yml",
-    ".github/workflows/deft-core-guard.yml",
-    "vbrief/.deft-version",
-    "vbrief/vbrief.md",
-    "vbrief/proposed/.gitkeep",
-    "vbrief/pending/.gitkeep",
-    "vbrief/active/.gitkeep",
-    "vbrief/completed/.gitkeep",
-    "vbrief/cancelled/.gitkeep",
-]);
-const INSTALLER_MANAGED_PREFIXES = [
-    ".agents/",
-    ".githooks/",
-    "vbrief/schemas/",
-    "vbrief/migration/",
-];
+import { CANONICAL_INSTALL_ROOT, depositNeutralization, ensureTaskfile, writeAgentsMd, writeInstallManifest, } from "./scaffold.js";
 function normalizeVersion(version) {
     return version.trim().replace(/^v/, "");
 }
@@ -110,10 +90,34 @@ function syncBareVersionMarker(projectDir, version) {
         // best-effort, mirrors install-upgrade marker write
     }
 }
-function isInstallerManagedPath(path) {
-    if (INSTALLER_MANAGED_EXACT.has(path))
-        return true;
-    return INSTALLER_MANAGED_PREFIXES.some((prefix) => path.startsWith(prefix));
+/**
+ * Retire a stale legacy `.deft/VERSION` after the canonical `.deft/core/VERSION`
+ * has been (re)written (#2064). Folded in from the former `install-upgrade`
+ * path so the shared refresh transaction covers the v0.27.x -> v0.28 manifest
+ * transition (#1046 PR-B) that the doctor's `install-manifest-disagreement`
+ * check still cites `task upgrade` to repair. Only acts when the canonical
+ * manifest lives at `<project>/.deft/core/VERSION` and a legacy
+ * `<project>/.deft/VERSION` disagrees; renames the legacy file to
+ * `.deft/VERSION.premigrate` (best-effort, never fatal).
+ */
+function migrateLegacyInstallManifest(projectDir, canonicalManifestPath) {
+    const canonical = resolve(canonicalManifestPath);
+    const expectedParent = resolve(projectDir, ".deft", "core");
+    if (resolve(canonical, "..") !== expectedParent)
+        return;
+    const legacy = join(projectDir, ".deft", "VERSION");
+    if (!existsSync(legacy) || !statSync(legacy).isFile())
+        return;
+    try {
+        const legacyVersion = manifestTagToVersion(parseInstallManifest(readFileSync(legacy, "utf8")));
+        const canonicalVersion = manifestTagToVersion(parseInstallManifest(readFileSync(canonical, "utf8")));
+        if (legacyVersion !== null && legacyVersion === canonicalVersion)
+            return;
+        renameSync(legacy, join(projectDir, ".deft", "VERSION.premigrate"));
+    }
+    catch {
+        // best-effort
+    }
 }
 function unquoteGitPath(path) {
     if (path.length >= 2 && path.startsWith('"') && path.endsWith('"')) {
@@ -206,7 +210,7 @@ export function buildUpdateSummaryJson(result, options) {
         update: true,
         non_interactive: options.nonInteractive,
         upgrade: options.upgrade,
-        taskfile_wired: false,
+        taskfile_wired: result.taskfileWired,
         missing_tools: [],
         maintainer_mode: false,
         maintainer_tools: [],
@@ -217,7 +221,7 @@ export function buildUpdateSummaryJson(result, options) {
         strategy: "file-swap",
         dirty_tree: false,
         dirty_files: [],
-        staged_paths: [],
+        staged_paths: result.stagedPaths,
         backup_path: "",
         previous_version: result.previousDepositVersion ?? "",
         content_version: result.contentVersion,
@@ -268,13 +272,25 @@ export async function runRefreshDeposit(args, io, seams = {}) {
         fetchedBy: "directive-update",
         ...(previousManagedBy ? { managedBy: previousManagedBy } : {}),
     };
-    writeInstallManifest(projectDir, deftDir, manifestFields);
+    const writtenManifestPath = writeInstallManifest(projectDir, deftDir, manifestFields);
+    // #2064: retire a stale legacy .deft/VERSION now that the canonical
+    // .deft/core/VERSION has been rewritten (folded in from install-upgrade so no
+    // manifest behavior is lost by the redirect). Best-effort; never fatal.
+    migrateLegacyInstallManifest(projectDir, writtenManifestPath);
     // #2055: regenerate the bare .deft-version derivative so it agrees with the
     // freshly written manifest tag (otherwise doctor's manifest-agreement check
     // fails and the operator must hand-edit the marker).
     syncBareVersionMarker(projectDir, contentVersion);
     const agentsMdUpdated = writeAgentsMd(projectDir, deftDir, io);
     await depositNeutralization(projectDir, io);
+    let taskfileWired = false;
+    if (args.nonInteractive) {
+        taskfileWired = ensureTaskfile(projectDir, io);
+    }
+    const { stagePaths, staged, stagedPaths } = depositStagePaths(projectDir, {
+        includeTaskfile: taskfileWired,
+    });
+    printCommitGuidance(io, stagePaths, staged);
     const readPorcelain = seams.gitPorcelain ?? gitPorcelain;
     printRefreshSideEffects(io, frameworkRefreshSideEffects(projectDir, readPorcelain));
     if (versionSkewNotice) {
@@ -289,6 +305,8 @@ export async function runRefreshDeposit(args, io, seams = {}) {
         agentsMdUpdated,
         versionSkewNotice,
         legacyLayout: false,
+        taskfileWired,
+        stagedPaths,
     };
 }
 /** CLI-facing wrapper: runs refresh, emits JSON or wizard UX, returns exit code. */

package/dist/init-deposit/scaffold.d.ts

@@ -4,10 +4,9 @@
  *
  * Refs #1942, #1430, #1463, #1179.
  */
-export interface InitDepositIo {
-    printf: (text: string) => void;
-}
-export declare const CANONICAL_INSTALL_ROOT = ".deft/core";
+import { CANONICAL_INSTALL_ROOT, type InitDepositIo } from "./constants.js";
+export type { InitDepositIo };
+export { CANONICAL_INSTALL_ROOT };
 export declare const CORE_GLOB = ".deft/core/**";
 export declare const MINIMAL_TASKFILE = "version: '3'\n\n# Taskfile for this project.\n# Installed by deft-install --yes (Epic-4). Add your own tasks below or in\n# additional included files. The deft include makes all framework tasks\n# (task check, task vbrief:*, task doctor, etc.) available from the project root.\n\nincludes:\n  deft:\n    taskfile: ./.deft/core/Taskfile.yml\n    optional: true\n";
 export declare const CANONICAL_TASKFILE_INCLUDE = "taskfile: ./.deft/core/Taskfile.yml";

package/dist/init-deposit/scaffold.js

@@ -12,7 +12,9 @@ import { dirname, join, relative } from "node:path";
 import { copyTree } from "../deposit/copy-tree.js";
 import { resolveLifecycleRoot } from "../layout/resolve.js";
 import { agentsRefreshPlan } from "../platform/agents-md.js";
-export const CANONICAL_INSTALL_ROOT = ".deft/core";
+import { CANONICAL_INSTALL_ROOT } from "./constants.js";
+import { installerManagedGuardEre } from "./hygiene.js";
+export { CANONICAL_INSTALL_ROOT };
 export const CORE_GLOB = ".deft/core/**";
 const CODEQL_CONFIG_REL = ".github/codeql/codeql-config.yml";
 const CORE_GUARD_WORKFLOW_REL = ".github/workflows/deft-core-guard.yml";
@@ -475,29 +477,6 @@ export function writeConsumerGitHooks(projectDir, deftDir, io, seams = {}) {
     }
     return filesDeposited || configWired;
 }
-function escapeEre(value) {
-    return value.replace(/[.^$*+?()[\]{}|\\]/g, "\\$&");
-}
-function installerManagedGuardEre() {
-    const matchers = [
-        { exact: "AGENTS.md" },
-        { prefix: ".agents/" },
-        { prefix: ".githooks/" },
-        { exact: ".gitattributes" },
-        { exact: ".gitignore" },
-        { exact: "greptile.json" },
-        { exact: CODEQL_CONFIG_REL },
-        { exact: CORE_GUARD_WORKFLOW_REL },
-        { exact: "vbrief/.deft-version" },
-        { exact: "vbrief/vbrief.md" },
-        { prefix: "vbrief/schemas/" },
-        { prefix: "vbrief/migration/" },
-        ...VBRIEF_LIFECYCLE_DIRS.map((sub) => ({ exact: `vbrief/${sub}/.gitkeep` })),
-    ];
-    return matchers
-        .map((m) => (m.exact ? `^${escapeEre(m.exact)}$` : `^${escapeEre(m.prefix ?? "")}`))
-        .join("|");
-}
 function githubActionsExpr(expression) {
     return ["$", "{{ ", expression, " }}"].join("");
 }

package/dist/intake/github-auth-modes.d.ts

@@ -48,6 +48,7 @@ export interface GitHubAuthModesCliArgs {
     githubAuthMode?: string | null;
     repo?: string;
     json?: boolean;
+    runGh?: GhRunner;
 }
 export declare function githubAuthModesMain(args: GitHubAuthModesCliArgs): number;
 export { probeRuntimeCapabilities };

package/dist/intake/github-auth-modes.js

@@ -257,6 +257,7 @@ export function resultToDict(result) {
 export function githubAuthModesMain(args) {
     const result = validateGithubAuthForWorker(args.githubAuthMode ?? null, {
         repo: args.repo ?? DEFAULT_VALIDATION_REPO,
+        runGh: args.runGh,
     });
     if (args.json) {
         process.stdout.write(`${JSON.stringify(resultToDict(result), null, 2)}\n`);

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

@@ -1,3 +1,4 @@
+import { LEGACY_ARTIFACT_SUFFIX, LEGACY_INFO_ROOT_KEY, MIGRATED_ARTIFACT_SUFFIX, MIGRATED_INFO_ROOT_KEY } from "../xbrief-migrate/constants.js";
 import { type ScmCallFn } from "./reconcile-issues.js";
 export declare const INGEST_STATUSES: readonly ["proposed", "pending", "active"];
 export type IngestStatus = (typeof INGEST_STATUSES)[number];
@@ -22,8 +23,11 @@ export declare function scanProvenanceRefs(vbriefDir: string): Map<number, strin
 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 declare function buildIssueVbrief(issue: Record<string, unknown>, status: IngestStatus, repoUrl: string, options?: {
+    infoRootKey?: typeof LEGACY_INFO_ROOT_KEY | typeof MIGRATED_INFO_ROOT_KEY;
+    infoVersion?: string;
+}): [Record<string, unknown>, string];
+export declare function targetFilename(number: number, title: string, artifactSuffix?: typeof LEGACY_ARTIFACT_SUFFIX | typeof MIGRATED_ARTIFACT_SUFFIX): string;
 export interface FetchIssueOptions {
     readonly cwd?: string | null;
     readonly cacheRoot?: string | null;

package/dist/intake/issue-ingest.js

@@ -1,5 +1,5 @@
 import { mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
-import { join, resolve } from "node:path";
+import { basename, join, resolve } from "node:path";
 import { cacheGet } from "../cache/operations.js";
 import { hasArtifactSuffix, resolveLifecycleRoot } from "../layout/resolve.js";
 import { call } from "../scm/call.js";
@@ -7,6 +7,7 @@ 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 { LEGACY_ARTIFACT_SUFFIX, LEGACY_INFO_ROOT_KEY, LEGACY_VBRIEF_VERSION, MIGRATED_ARTIFACT_DIR, MIGRATED_ARTIFACT_SUFFIX, MIGRATED_INFO_ROOT_KEY, VBRIEF_VERSION, } from "../xbrief-migrate/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"];
@@ -17,6 +18,53 @@ const STATUS_MAP = {
     pending: ["pending", "pending"],
     active: ["active", "running"],
 };
+function readDeclaredInfoVersion(vbriefDir, infoRootKey, artifactSuffix, fallbackVersion) {
+    const projectDefinitionPath = join(vbriefDir, `PROJECT-DEFINITION${artifactSuffix}`);
+    try {
+        const parsed = JSON.parse(readFileSync(projectDefinitionPath, "utf8"));
+        const info = parsed[infoRootKey];
+        if (info !== null && typeof info === "object" && !Array.isArray(info)) {
+            const declared = info.version;
+            if (typeof declared === "string" && declared.length > 0) {
+                return declared;
+            }
+        }
+    }
+    catch {
+        // Fall back to the schema-default version when no declaration is available.
+    }
+    return fallbackVersion;
+}
+/**
+ * Decide the emission format (`.xbrief.json` + `xBRIEFInfo` vs legacy `.vbrief.json`
+ * + `vBRIEFInfo`) for an ingested scope artifact.
+ *
+ * The decision is STRUCTURAL and keyed on the resolved lifecycle root directory
+ * (`vbriefDir`), which is itself produced by `resolveLifecycleLayout` / `resolveLifecycleRoot`
+ * -- the exact same layout-decision logic `project:render` uses. This guarantees the two
+ * surfaces cannot diverge (#2149 finding #1): whichever tree `resolveLifecycleLayout` selected
+ * (`xbrief/` when migrated, else `vbrief/`) is the tree ingest writes into, and the emission
+ * format always matches that directory.
+ *
+ * It deliberately does NOT content-scan the tree for legacy markers (`detectLegacyVbriefLayout`).
+ * A historical vBRIEF-serialized artifact sitting in `xbrief/completed/` is migrated content,
+ * not a legacy layout, and must NOT force legacy emission on a migrated project (#2149 finding #3).
+ */
+function resolveIngestEmissionLayout(vbriefDir) {
+    const migrated = basename(vbriefDir) === MIGRATED_ARTIFACT_DIR;
+    if (!migrated) {
+        return {
+            artifactSuffix: LEGACY_ARTIFACT_SUFFIX,
+            infoRootKey: LEGACY_INFO_ROOT_KEY,
+            infoVersion: LEGACY_VBRIEF_VERSION,
+        };
+    }
+    return {
+        artifactSuffix: MIGRATED_ARTIFACT_SUFFIX,
+        infoRootKey: MIGRATED_INFO_ROOT_KEY,
+        infoVersion: readDeclaredInfoVersion(vbriefDir, MIGRATED_INFO_ROOT_KEY, MIGRATED_ARTIFACT_SUFFIX, VBRIEF_VERSION),
+    };
+}
 const CONTROL_CHAR_LABELS = {
     "\b": "U+0008 backspace",
     "\t": "U+0009 tab",
@@ -230,7 +278,7 @@ export function issueCommentThread(issue) {
 export function issueCommentsAlreadyFetched(issue) {
     return Object.hasOwn(issue, ISSUE_COMMENT_THREAD_KEY);
 }
-export function buildIssueVbrief(issue, status, repoUrl) {
+export function buildIssueVbrief(issue, status, repoUrl, options = {}) {
     const number = Number(issue.number);
     const title = (typeof issue.title === "string" && issue.title.length > 0
         ? issue.title
@@ -291,20 +339,23 @@ export function buildIssueVbrief(issue, status, repoUrl) {
         }
         plan.references = references;
     }
+    const infoRootKey = options.infoRootKey ?? LEGACY_INFO_ROOT_KEY;
+    const infoVersion = options.infoVersion ?? EMITTED_VBRIEF_VERSION;
+    const briefLabel = infoRootKey === MIGRATED_INFO_ROOT_KEY ? "xBRIEF" : "vBRIEF";
     return [
         {
-            vBRIEFInfo: {
-                version: EMITTED_VBRIEF_VERSION,
-                description: `Scope vBRIEF ingested from GitHub issue #${number}`,
+            [infoRootKey]: {
+                version: infoVersion,
+                description: `Scope ${briefLabel} ingested from GitHub issue #${number}`,
             },
             plan,
         },
         folder,
     ];
 }
-export function targetFilename(number, title) {
+export function targetFilename(number, title, artifactSuffix = LEGACY_ARTIFACT_SUFFIX) {
     const slug = slugify(title) || `issue-${number}`;
-    return `${TODAY}-${number}-${slug}.vbrief.json`;
+    return `${TODAY}-${number}-${slug}${artifactSuffix}`;
 }
 export function fetchFromCache(repo, number, options = {}) {
     const key = `${repo}/${number}`;
@@ -423,8 +474,12 @@ export function ingestOne(issue, options) {
         cwd: options.cwd,
         cacheRoot: options.cacheRoot,
     });
-    const [vbrief, folder] = buildIssueVbrief(enriched, options.status, options.repoUrl);
-    const filename = targetFilename(number, String(issue.title ?? ""));
+    const emissionLayout = resolveIngestEmissionLayout(options.vbriefDir);
+    const [vbrief, folder] = buildIssueVbrief(enriched, options.status, options.repoUrl, {
+        infoRootKey: emissionLayout.infoRootKey,
+        infoVersion: emissionLayout.infoVersion,
+    });
+    const filename = targetFilename(number, String(issue.title ?? ""), emissionLayout.artifactSuffix);
     const target = join(options.vbriefDir, folder, filename);
     if (options.dryRun) {
         return ["dryrun", target, `DRY-RUN would write ${folder}/${filename}`];
@@ -568,6 +623,7 @@ export function ingestSingleForAccept(n, repo, options = {}) {
         vbriefDir,
         status: options.status ?? "proposed",
         repoUrl,
+        cwd: root,
     });
     return [result, path];
 }

package/dist/integration-e2e/helpers.d.ts

@@ -11,7 +11,6 @@ export interface DispatchCall {
     projectRoot: string;
     frameworkRoot: string;
 }
-export declare function isFrameworkSourceContext(frameworkRoot: string, projectRoot: string): boolean;
 /** Mirror ``scripts/_project_context.dispatch_task_check`` for consumer-task e2e. */
 export declare function dispatchTaskCheck(frameworkRoot: string, projectRoot: string, runner: (command: string, projectRoot: string, frameworkRoot: string) => {
     code: number;

package/dist/integration-e2e/helpers.js

@@ -1,6 +1,6 @@
 import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
-import { join, resolve } from "node:path";
+import { join } from "node:path";
 import { afterEach } from "vitest";
 import { restIssueListPaginated, setPaginatedLister, setSingleIssueFetcher, setSleepFn, } from "../cache/fetch.js";
 import { auditPath } from "../cache/paths.js";
@@ -108,14 +108,10 @@ export function writeScopeVbrief(projectRoot, folder, filename, status = "propos
     }, null, 2)}\n`, "utf8");
     return target;
 }
-export function isFrameworkSourceContext(frameworkRoot, projectRoot) {
-    return resolve(frameworkRoot) === resolve(projectRoot);
-}
+import { resolveCheckTarget } from "../check/orchestrator.js";
 /** Mirror ``scripts/_project_context.dispatch_task_check`` for consumer-task e2e. */
 export function dispatchTaskCheck(frameworkRoot, projectRoot, runner) {
-    const target = isFrameworkSourceContext(frameworkRoot, projectRoot)
-        ? "check:framework-source"
-        : "check:consumer";
+    const target = resolveCheckTarget(frameworkRoot, projectRoot);
     return runner(target, projectRoot, frameworkRoot).code;
 }
 /** Hermetic mirror of ``tests/integration/test_scm_smoke._probe_rate_limit``. */

package/dist/layout/lifecycle-ref.d.ts

@@ -0,0 +1,15 @@
+/** Lifecycle folders searched when a folder-qualified ref dangles (#1926). */
+export declare const LIFECYCLE_SCOPE_FOLDERS: readonly ["proposed", "pending", "active", "completed", "cancelled"];
+export interface ResolveLifecycleArtifactRefOptions {
+    /** When false, only resolve the literal path (for rewrite matching). Default true (#1926). */
+    readonly allowCrossFolderSearch?: boolean;
+}
+/**
+ * Resolve a lifecycle-relative artifact reference to an absolute path.
+ *
+ * When the direct path is missing but the ref names a lifecycle artifact
+ * (folder-qualified or bare basename), search all lifecycle folders for the
+ * same filename (#1926).
+ */
+export declare function resolveLifecycleArtifactRef(rel: string, lifecycleRoot: string, options?: ResolveLifecycleArtifactRefOptions): string;
+//# sourceMappingURL=lifecycle-ref.d.ts.map