@deftai/directive-core 0.71.1 → 0.73.0

package/dist/category-b-namespace/index.js

@@ -9,7 +9,7 @@
  * order-preserving (the namespaced key takes the legacy key's slot, keeping
  * artifact diffs minimal).
  */
-import { readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { existsSync, readdirSync, readFileSync, statSync, writeFileSync, } from "node:fs";
 import { join, relative, resolve } from "node:path";
 import { hasArtifactSuffix, resolveLifecycleRoot } from "../layout/resolve.js";
 import { LEGACY_PLAN_COMPLETED_NOTE_KEY, LEGACY_PLAN_POLICY_KEY, PLAN_COMPLETED_NOTE_KEY, PLAN_POLICY_KEY, } from "../policy/plan-extensions.js";
@@ -85,7 +85,21 @@ function collectVbriefFiles(dir, acc = []) {
  */
 export function migrateCategoryBCorpus(projectRoot) {
     const root = resolve(projectRoot);
-    const vbriefDir = resolveLifecycleRoot(root);
+    let vbriefDir;
+    try {
+        vbriefDir = resolveLifecycleRoot(root);
+    }
+    catch {
+        // If xbrief/ layout is absent, fall back to vbrief/ for this pre-migration tool
+        // (category-b migration rewrites policy keys regardless of layout stage).
+        const legacyDir = join(root, "vbrief");
+        if (existsSync(legacyDir)) {
+            vbriefDir = legacyDir;
+        }
+        else {
+            return { scanned: 0, changed: [], conflicts: [] };
+        }
+    }
     let scanned = 0;
     const changed = [];
     const conflicts = [];

package/dist/codebase/default-extractor.js

@@ -101,7 +101,15 @@ function sourcePathRel(projectRoot, sourcePath) {
 }
 /** Return the authored codeStructure source path used by the default extractor. */
 export function defaultCodeStructurePath(projectRoot, codeStructurePath) {
-    return codeStructurePath ?? resolveProjectDefinitionPath(projectRoot);
+    if (codeStructurePath !== undefined)
+        return codeStructurePath;
+    try {
+        return resolveProjectDefinitionPath(projectRoot);
+    }
+    catch {
+        // No xbrief/ layout; return canonical path so callers get a predictable "not found" result.
+        return join(projectRoot, "xbrief", "PROJECT-DEFINITION.xbrief.json");
+    }
 }
 function stableId(value) {
     let slug = "";

package/dist/codebase/map.js

@@ -10,7 +10,7 @@ export const GENERATED_SENTINEL = "AUTO-GENERATED by task codebase:map";
 export const DEFAULT_OUTPUT_PATH = ".planning/codebase/MAP.md";
 export const BANNER_TEMPLATE = "<!-- AUTO-GENERATED by task codebase:map -- DO NOT EDIT MANUALLY -->\n" +
     "<!-- Purpose: generated codebase MAP projection -->\n" +
-    "<!-- Source of truth: vbrief/PROJECT-DEFINITION.vbrief.json " +
+    "<!-- Source of truth: xbrief/PROJECT-DEFINITION.xbrief.json " +
     "plan.architecture.codeStructure -->\n" +
     "<!-- Regenerate with: task codebase:map -->\n";
 export function markdownText(value) {

package/dist/doctor/checks.d.ts

@@ -30,6 +30,15 @@ export declare function checkCanonicalVendoredNpmSignpost(projectRoot: string, s
  * deposit is still a working install, just an unpinned one.
  */
 export declare function checkManifestVersionReportable(projectRoot: string, installRoot: string | null, seams?: CheckSeams): CheckResult;
+/**
+ * #2206: check that the consumer `.gitignore` carries the canonical Deft baseline
+ * entries. Advisory (exit-exempt) because missing entries are an adoption risk, not
+ * a broken install.
+ *
+ * Skips when `.gitignore` is absent (greenfield project that has not yet run
+ * `directive init` or `directive update`).
+ */
+export declare function checkGitignoreCoverage(projectRoot: string, seams?: CheckSeams): CheckResult;
 export declare function deriveExitCode(checks: readonly CheckResult[], errors: readonly string[]): number;
 export declare function runChecksImpl(projectRoot: string, seams?: CheckSeams & {
     isDir?: (p: string) => boolean;

package/dist/doctor/checks.js

@@ -1,8 +1,10 @@
 import { join } from "node:path";
+import { CANONICAL_GITIGNORE_BASELINE } from "../init-deposit/gitignore.js";
 import { detectLegacyLayout, legacyLayoutSignpostLine, } from "../init-deposit/legacy-detect.js";
 import { detectCanonicalVendoredManifest, isNpmManaged, NPM_MANAGED_SENTINEL_KEY, NPM_MANAGED_SENTINEL_VALUE, } from "../init-deposit/migrate.js";
 import { resolveLifecycleRoot } from "../layout/resolve.js";
 import { findSkillPathsInText } from "../text/redos-safe.js";
+import { stripGitignoreInlineComment } from "../triage/bootstrap/gitignore.js";
 import { CANONICAL_UPGRADE_COMMAND, GO_BRIDGE_RELEASES_URL, UPGRADING_DOC_URL, } from "./constants.js";
 import { isDeprecationRedirectStub, locateManifest, manifestCandidatePaths, manifestReportableVersion, manifestTagToVersion, parseInstallManifest, parseInstallRootFromAgentsMd, parseManifest, } from "./manifest.js";
 import { readTextSafe } from "./paths.js";
@@ -127,10 +129,14 @@ export function checkManifestAgreement(projectRoot, installRoot, seams = {}) {
     const isFile = seams.isFile ?? ((p) => readText(p, seams) !== null);
     const manifestPath = locateManifest(projectRoot, installRoot, isFile);
     const expectedManifestPath = manifestPath ?? manifestCandidatePaths(projectRoot, installRoot)[0];
-    const bareCandidates = [
-        join(resolveLifecycleRoot(projectRoot), ".deft-version"),
-        join(projectRoot, ".deft-version"),
-    ];
+    let layoutRoot;
+    try {
+        layoutRoot = resolveLifecycleRoot(projectRoot);
+    }
+    catch {
+        layoutRoot = projectRoot; // No xbrief/ layout; fall back to project root for bare version check.
+    }
+    const bareCandidates = [join(layoutRoot, ".deft-version"), join(projectRoot, ".deft-version")];
     const barePath = bareCandidates.find((p) => isFile(p)) ?? null;
     const manifestText = manifestPath ? readText(manifestPath, seams) : null;
     const bareText = barePath ? readText(barePath, seams) : null;
@@ -436,8 +442,80 @@ export function checkManifestVersionReportable(projectRoot, installRoot, seams =
         data: { manifest_path: manifestPath, version: null, sha: null, source: reportable.source },
     };
 }
+/**
+ * Collect the normalised (inline-comment-stripped) gitignore patterns from a
+ * `.gitignore` file text. Uses the shared `stripGitignoreInlineComment` helper
+ * so coverage checks stay consistent with `ensureInitGitignoreLines`.
+ */
+function collectGitignorePresent(text) {
+    const present = new Set();
+    for (const raw of text.split("\n")) {
+        const line = stripGitignoreInlineComment(raw);
+        if (line)
+            present.add(line);
+    }
+    return present;
+}
+function gitignoreLineIsCovered(present, line) {
+    return present.has(line);
+}
+/**
+ * #2206: check that the consumer `.gitignore` carries the canonical Deft baseline
+ * entries. Advisory (exit-exempt) because missing entries are an adoption risk, not
+ * a broken install.
+ *
+ * Skips when `.gitignore` is absent (greenfield project that has not yet run
+ * `directive init` or `directive update`).
+ */
+export function checkGitignoreCoverage(projectRoot, seams = {}) {
+    const gitignorePath = join(projectRoot, ".gitignore");
+    const text = readText(gitignorePath, seams);
+    if (text === null) {
+        return {
+            name: "gitignore-coverage",
+            status: "skip",
+            detail: ".gitignore not found; run `directive init` or `directive update` to create it.",
+            data: { gitignore_path: gitignorePath, missing: [] },
+        };
+    }
+    const present = collectGitignorePresent(text);
+    const missing = [];
+    for (const line of CANONICAL_GITIGNORE_BASELINE) {
+        if (!gitignoreLineIsCovered(present, line)) {
+            missing.push(line);
+        }
+    }
+    // Check .deft/core/ separately — only required for hybrid/greenfield installs.
+    // We conservatively omit it from the missing list here (tracked-deposit projects
+    // legitimately omit it). The update path handles this correctly per layout.
+    if (missing.length === 0) {
+        return {
+            name: "gitignore-coverage",
+            status: "pass",
+            detail: "All canonical Deft .gitignore entries are present.",
+            data: { gitignore_path: gitignorePath, missing: [] },
+        };
+    }
+    return {
+        name: "gitignore-coverage",
+        status: "fail",
+        detail: `Deft .gitignore coverage incomplete: ${missing.length} canonical entr${missing.length === 1 ? "y" : "ies"} ` +
+            `missing (${missing.slice(0, 3).join(", ")}${missing.length > 3 ? ", …" : ""}). ` +
+            "Run `directive update` to add the missing entries (idempotent, safe on re-run). " +
+            `Full missing list: ${JSON.stringify(missing)}.`,
+        data: {
+            gitignore_path: gitignorePath,
+            missing,
+            suggested_fix: "directive update",
+        },
+    };
+}
 export function deriveExitCode(checks, errors) {
-    const exitExempt = new Set(["canonical-vendored-npm-signpost", "manifest-version-reportable"]);
+    const exitExempt = new Set([
+        "canonical-vendored-npm-signpost",
+        "manifest-version-reportable",
+        "gitignore-coverage",
+    ]);
     if (errors.length > 0 || checks.some((c) => c.status === "error")) {
         return 2;
     }
@@ -476,6 +554,7 @@ export function runChecksImpl(projectRoot, seams = {}) {
         checks.push(checkManifestVersionReportable(projectRoot, null, seams));
         checks.push(checkLegacyLayout(projectRoot, seams));
         checks.push(checkCanonicalVendoredNpmSignpost(projectRoot, seams));
+        checks.push(checkGitignoreCoverage(projectRoot, seams));
         return {
             projectRoot,
             installRoot: null,
@@ -491,6 +570,7 @@ export function runChecksImpl(projectRoot, seams = {}) {
     checks.push(checkInstallPathConsistency(projectRoot, installRoot, seams));
     checks.push(checkLegacyLayout(projectRoot, seams));
     checks.push(checkCanonicalVendoredNpmSignpost(projectRoot, seams));
+    checks.push(checkGitignoreCoverage(projectRoot, seams));
     return {
         projectRoot,
         installRoot,

package/dist/doctor/main.js

@@ -373,7 +373,8 @@ function runInstallIntegrityChecks(projectRoot, sink, addFinding, seams) {
             }
             if ((name === "legacy-layout" ||
                 name === "canonical-vendored-npm-signpost" ||
-                name === "manifest-version-reportable") &&
+                name === "manifest-version-reportable" ||
+                name === "gitignore-coverage") &&
                 status === "fail") {
                 sink.warn(`${name}: ${detail}`);
                 addFinding({

package/dist/eval/health.js

@@ -21,7 +21,13 @@ function isFrameworkSourceCheckout(projectRoot) {
     return existsSync(manifest) && existsSync(cliPkg);
 }
 function loadPlan(projectRoot) {
-    const filepath = resolveProjectDefinitionPath(projectRoot);
+    let filepath;
+    try {
+        filepath = resolveProjectDefinitionPath(projectRoot);
+    }
+    catch {
+        return null; // No xbrief/ layout; no project definition.
+    }
     if (!existsSync(filepath)) {
         return null;
     }

package/dist/eval/readback.js

@@ -28,7 +28,13 @@ function parseJsonObjectOrNull(text) {
     return null;
 }
 function readHealthHistoryRows(projectRoot) {
-    const path = healthHistoryPath(projectRoot);
+    let path;
+    try {
+        path = healthHistoryPath(projectRoot);
+    }
+    catch {
+        return []; // No xbrief/ layout; no health history.
+    }
     if (!existsSync(path)) {
         return [];
     }

package/dist/events/attribution-enrichment.d.ts

@@ -0,0 +1,35 @@
+/** Record-shape version for attribution ledger entries (#2376). Bump on shape changes. */
+export declare const ATTRIBUTION_SCHEMA_VERSION: 1;
+/** Project-local, gitignored install-identity file. */
+export declare const INSTALL_ID_REL: string;
+/** Identity + provenance fields stamped onto every attribution record (#2376). */
+export interface AttributionEnrichment {
+    /** Normalized `owner/name` of the origin remote, or null when unavailable. */
+    readonly repo: string | null;
+    /** directive engine version at emit time. */
+    readonly directive_version: string;
+    /** Stable per-checkout uuid, or null when it cannot be read/created. */
+    readonly install_id: string | null;
+    /** Attribution record-shape version. */
+    readonly schema_version: number;
+}
+/**
+ * Read-or-create a stable per-checkout install id in `.deft-cache/install-id`.
+ * Best-effort: returns null (never throws) if the file cannot be read or written.
+ */
+export declare function resolveInstallId(projectRoot: string): string | null;
+export interface BuildAttributionEnrichmentOptions {
+    /** Test seam for origin-repo resolution; defaults to `inferRepoFromGit`. */
+    readonly repoResolver?: (projectRoot: string) => string | null;
+}
+/**
+ * Build the identity/provenance enrichment stamped on attribution records (#2376).
+ *
+ * Memoized per `projectRoot` (identity/version/repo are stable within a session)
+ * so a caller that emits many signals in one run does not spawn a git process and
+ * open the install-id file per event -- mirrors `detectOriginOrg`'s cache to keep
+ * this off the hot emit path (#2377 review). A custom `repoResolver` bypasses the
+ * cache so tests stay deterministic. Every field degrades gracefully; never throws.
+ */
+export declare function buildAttributionEnrichment(projectRoot: string, options?: BuildAttributionEnrichmentOptions): AttributionEnrichment;
+//# sourceMappingURL=attribution-enrichment.d.ts.map

package/dist/events/attribution-enrichment.js

@@ -0,0 +1,74 @@
+import { randomUUID } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { readCorePackageVersion } from "../engine-version.js";
+import { inferRepoFromGit } from "../triage/queue/repo.js";
+/** Record-shape version for attribution ledger entries (#2376). Bump on shape changes. */
+export const ATTRIBUTION_SCHEMA_VERSION = 1;
+/** Project-local, gitignored install-identity file. */
+export const INSTALL_ID_REL = join(".deft-cache", "install-id");
+/**
+ * Read-or-create a stable per-checkout install id in `.deft-cache/install-id`.
+ * Best-effort: returns null (never throws) if the file cannot be read or written.
+ */
+export function resolveInstallId(projectRoot) {
+    const path = resolve(projectRoot, INSTALL_ID_REL);
+    try {
+        if (existsSync(path)) {
+            const existing = readFileSync(path, "utf8").trim();
+            if (existing.length > 0) {
+                return existing;
+            }
+        }
+    }
+    catch {
+        // fall through and try to (re)create
+    }
+    try {
+        const id = randomUUID();
+        mkdirSync(dirname(path), { recursive: true });
+        writeFileSync(path, `${id}\n`, "utf8");
+        return id;
+    }
+    catch {
+        return null;
+    }
+}
+const enrichmentCache = new Map();
+/**
+ * Build the identity/provenance enrichment stamped on attribution records (#2376).
+ *
+ * Memoized per `projectRoot` (identity/version/repo are stable within a session)
+ * so a caller that emits many signals in one run does not spawn a git process and
+ * open the install-id file per event -- mirrors `detectOriginOrg`'s cache to keep
+ * this off the hot emit path (#2377 review). A custom `repoResolver` bypasses the
+ * cache so tests stay deterministic. Every field degrades gracefully; never throws.
+ */
+export function buildAttributionEnrichment(projectRoot, options = {}) {
+    const useCache = options.repoResolver === undefined;
+    if (useCache) {
+        const cached = enrichmentCache.get(projectRoot);
+        if (cached !== undefined) {
+            return cached;
+        }
+    }
+    const resolver = options.repoResolver ?? inferRepoFromGit;
+    let repo = null;
+    try {
+        repo = resolver(projectRoot);
+    }
+    catch {
+        repo = null;
+    }
+    const enrichment = {
+        repo,
+        directive_version: readCorePackageVersion(),
+        install_id: resolveInstallId(projectRoot),
+        schema_version: ATTRIBUTION_SCHEMA_VERSION,
+    };
+    if (useCache) {
+        enrichmentCache.set(projectRoot, enrichment);
+    }
+    return enrichment;
+}
+//# sourceMappingURL=attribution-enrichment.js.map

package/dist/events/attribution-ledger.js

@@ -2,6 +2,7 @@ import { resolve } from "node:path";
 import { DEFAULT_EVENT_LOG, emit } from "../lifecycle/events.js";
 import { isValueFeedbackPathAllowed, resolveValueFeedback, } from "../policy/value-feedback.js";
 import { ATTRIBUTION_EVENT_NAMES } from "./attribution-constants.js";
+import { buildAttributionEnrichment } from "./attribution-enrichment.js";
 export { ALL_ATTRIBUTION_EVENT_NAMES, ATTRIBUTION_EVENT_NAMES, ATTRIBUTION_REQUIRED_PAYLOAD, } from "./attribution-constants.js";
 function resolveLedgerLogPath(projectRoot, logPath) {
     if (logPath !== undefined && logPath !== null) {
@@ -28,9 +29,13 @@ export function emitAttributionSignal(name, payload, options) {
         }
         const signalClass = signalClassForEvent(name);
         const logPath = resolveLedgerLogPath(options.projectRoot, options.logPath);
+        const enrichment = buildAttributionEnrichment(options.projectRoot);
+        // Authoritative fields (signal_class + provenance enrichment) are spread LAST
+        // so a caller payload can never silently shadow them (#2377 review).
         return emit(name, {
-            signal_class: signalClass,
             ...payload,
+            signal_class: signalClass,
+            ...enrichment,
         }, { logPath });
     }
     catch {

package/dist/init-deposit/gitignore.js

@@ -44,7 +44,13 @@ export const CANONICAL_GITIGNORE_BASELINE = [
     "vbrief/*.lock",
     ".deft/core.bak-*/",
     ".deft/*.bak-*",
+    // xBRIEF-era migration-backup directories created by `deft migrate:xbrief` (#2206).
+    ".deft/xbrief-migrate-backup-*/",
     "*.premigrate.*",
+    // Generated version-eval results live under `.eval/results/` (NOT triage-cache)
+    // for both the legacy `vbrief/` tree and the post-#2034 `xbrief/` tree (#2206).
+    "vbrief/.eval/results/",
+    "xbrief/.eval/results/",
 ];
 const DEFT_FRAMEWORK_GITIGNORE_HEADER = "# Deft framework: ignore local-only caches and scratch directories\n";
 const DEFT_CORE_GITIGNORE_RATIONALE = "# Hybrid deposit (#1942): reconstituted by `directive init` like node_modules.\n" +

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

@@ -37,6 +37,30 @@ export declare function stageFrameworkPaths(projectDir: string, paths: readonly
     staged: boolean;
     error: Error | null;
 };
+/**
+ * Framework-internal subdirectories that are shipped as part of the source
+ * repository but are NOT included in the `@deftai/directive-content` npm
+ * package deposited into `.deft/core/`. If one of these paths survives from
+ * a prior git-vendored install, `deft update`'s additive file-swap will never
+ * remove it — causing the deposit-hygiene advisory to persist indefinitely.
+ *
+ * Each entry is a relative path within `.deft/core/`; presence in the CONTENT
+ * root overrides the prune (i.e. if the content package ever ships `packages/`
+ * again, we won't prune it).
+ *
+ * Refs #2347.
+ */
+export declare const STRAY_DEPOSIT_FRAMEWORK_PATHS: readonly ["packages"];
+export interface PruneStrayDepositPathsResult {
+    readonly pruned: string[];
+}
+/**
+ * Remove framework-source subdirectories from `.deft/core/` that are not
+ * present in the deposited content package (#2347). Silently skips any path
+ * that is also present in `contentRoot` (future-safe: if the content package
+ * ever ships `packages/` we stop pruning it).
+ */
+export declare function pruneStrayDepositPaths(deftDir: string, contentRoot: string, io: InitDepositIo): Promise<PruneStrayDepositPathsResult>;
 export declare const COMMIT_HYGIENE_BRANCH_NAME = "chore/deft-framework-upgrade";
 export declare function printCommitGuidance(io: InitDepositIo, paths: readonly string[], staged: boolean): void;
 export interface DepositStagePathsOptions extends StageFrameworkPathsSeams, FrameworkStagePathsOptions {

package/dist/init-deposit/hygiene.js

@@ -6,6 +6,7 @@
  */
 import { execFileSync } from "node:child_process";
 import { existsSync } from "node:fs";
+import { rm, stat } from "node:fs/promises";
 import { join, relative } from "node:path";
 import { gitPorcelain } from "../story-ready/git.js";
 import { CANONICAL_INSTALL_ROOT } from "./constants.js";
@@ -120,6 +121,60 @@ export function stageFrameworkPaths(projectDir, paths, seams = {}) {
         return { staged: false, error };
     }
 }
+/**
+ * Framework-internal subdirectories that are shipped as part of the source
+ * repository but are NOT included in the `@deftai/directive-content` npm
+ * package deposited into `.deft/core/`. If one of these paths survives from
+ * a prior git-vendored install, `deft update`'s additive file-swap will never
+ * remove it — causing the deposit-hygiene advisory to persist indefinitely.
+ *
+ * Each entry is a relative path within `.deft/core/`; presence in the CONTENT
+ * root overrides the prune (i.e. if the content package ever ships `packages/`
+ * again, we won't prune it).
+ *
+ * Refs #2347.
+ */
+export const STRAY_DEPOSIT_FRAMEWORK_PATHS = ["packages"];
+/**
+ * Remove framework-source subdirectories from `.deft/core/` that are not
+ * present in the deposited content package (#2347). Silently skips any path
+ * that is also present in `contentRoot` (future-safe: if the content package
+ * ever ships `packages/` we stop pruning it).
+ */
+export async function pruneStrayDepositPaths(deftDir, contentRoot, io) {
+    const pruned = [];
+    for (const rel of STRAY_DEPOSIT_FRAMEWORK_PATHS) {
+        const depositPath = join(deftDir, rel);
+        const contentPath = join(contentRoot, rel);
+        let isInDeposit = false;
+        let isInContent = false;
+        try {
+            isInDeposit = (await stat(depositPath)).isDirectory();
+        }
+        catch {
+            // absent — nothing to prune
+        }
+        if (!isInDeposit)
+            continue;
+        try {
+            isInContent = (await stat(contentPath)).isDirectory();
+        }
+        catch {
+            // not in content package — safe to prune
+        }
+        if (isInContent)
+            continue;
+        try {
+            await rm(depositPath, { recursive: true, force: true });
+            pruned.push(rel);
+            io.printf(`Pruned stray framework-source tree .deft/core/${rel}/ — not shipped by @deftai/directive-content (#2347).\n`);
+        }
+        catch (cause) {
+            io.printf(`Warning: could not prune .deft/core/${rel}/: ${String(cause)}\n`);
+        }
+    }
+    return { pruned };
+}
 export const COMMIT_HYGIENE_BRANCH_NAME = "chore/deft-framework-upgrade";
 export function printCommitGuidance(io, paths, staged) {
     if (paths.length === 0)

package/dist/init-deposit/refresh.js

@@ -20,8 +20,8 @@ import { resolveLifecycleRoot } from "../layout/resolve.js";
 import { DEV_FALLBACK } from "../platform/constants.js";
 import { checkLocalEngineIntegrity, classify, ENGINE_PACKAGE, plan, renderGlobalInstall, resolveEngine, } from "../resolution/index.js";
 import { gitPorcelain } from "../story-ready/git.js";
-import { ensureInitGitignoreLines } from "./gitignore.js";
-import { depositStagePaths, isInstallerManagedPath, printCommitGuidance } from "./hygiene.js";
+import { ensureInitGitignoreLines, isDepositTrackedInGit } from "./gitignore.js";
+import { depositStagePaths, isInstallerManagedPath, printCommitGuidance, pruneStrayDepositPaths, } 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";
@@ -155,14 +155,20 @@ function syncBareVersionMarker(projectDir, version) {
     const normalized = normalizeVersion(version);
     if (!normalized || normalized === DEV_FALLBACK)
         return;
-    const vbriefDir = resolveLifecycleRoot(projectDir);
+    let vbriefDir = null;
+    try {
+        vbriefDir = resolveLifecycleRoot(projectDir);
+    }
+    catch {
+        // No xbrief/ layout present — write the root-level derivative instead.
+    }
     let targetDir = projectDir;
     try {
-        if (statSync(vbriefDir).isDirectory())
+        if (vbriefDir !== null && statSync(vbriefDir).isDirectory())
             targetDir = vbriefDir;
     }
     catch {
-        // vbrief/ absent — write the root-level derivative instead
+        // xbrief/ absent — write the root-level derivative instead
     }
     try {
         mkdirSync(targetDir, { recursive: true });
@@ -352,6 +358,10 @@ export async function runRefreshDeposit(args, io, seams = {}) {
     const versionSkewNotice = buildVersionSkewNotice(engineVersion, contentVersion, previousDepositVersion);
     await copyContent(contentRoot, deftDir);
     await prunePythonArtifactsFromDeposit(deftDir, projectDir, io);
+    // #2347: prune framework-source paths that the content package does not ship.
+    // The additive file-swap never removes them, causing the deposit-hygiene
+    // advisory to persist across every upgrade until manually cleaned.
+    await pruneStrayDepositPaths(deftDir, contentRoot, io);
     const nowIso = seams.nowIso ?? (() => new Date().toISOString().replace(/\.\d{3}Z$/, "Z"));
     const manifestFields = {
         ref: contentVersion.startsWith("v") ? contentVersion : `v${contentVersion}`,
@@ -372,7 +382,13 @@ export async function runRefreshDeposit(args, io, seams = {}) {
     // fails and the operator must hand-edit the marker).
     syncBareVersionMarker(projectDir, contentVersion);
     const agentsMdUpdated = writeAgentsMd(projectDir, deftDir, io);
-    await depositNeutralization(projectDir, io);
+    // #2148: the deft-core-guard CI workflow is only meaningful when the deposit
+    // is git-tracked (committed vendor layout). On an npm-managed (gitignored)
+    // deposit it creates untracked noise after every `directive update`. Probe
+    // git-tracked status once and share the result with the gitignore upkeep below.
+    const depositTracked = isDepositTrackedInGit(projectDir, seams.gitLsFiles);
+    const skipGuardWorkflow = depositTracked !== true;
+    await depositNeutralization(projectDir, io, { skipGuardWorkflow });
     // #2266: non-destructive `.gitignore` upkeep for framework-owned paths. This
     // NEVER un-tracks a committed deposit -- `ensureInitGitignoreLines` only writes
     // `.gitignore` and leaves an already-tracked `.deft/core` tracked. The

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

@@ -67,6 +67,16 @@ export declare function ensureCodeqlPathsIgnore(projectDir: string, io: InitDepo
 export declare function ensureCoreGuardWorkflow(projectDir: string, io: InitDepositIo): boolean;
 export declare function pruneFrameworkSelfTests(projectDir: string, io: InitDepositIo): Promise<boolean>;
 export declare function pruneVendoredTsTests(projectDir: string, io: InitDepositIo): Promise<number>;
+export interface DepositNeutralizationOptions {
+    /**
+     * #2148: skip depositing `.github/workflows/deft-core-guard.yml` when the
+     * framework deposit is not git-tracked (npm-managed / gitignored layout). The
+     * guard CI check is meaningless when there is no committed `.deft/core/**` to
+     * guard; skipping it prevents the file from re-appearing as untracked noise
+     * after every `directive update`.
+     */
+    readonly skipGuardWorkflow?: boolean;
+}
 /** Best-effort #1430 neutralization deposit (mirrors depositNeutralization). */
-export declare function depositNeutralization(projectDir: string, io: InitDepositIo): Promise<void>;
+export declare function depositNeutralization(projectDir: string, io: InitDepositIo, options?: DepositNeutralizationOptions): Promise<void>;
 //# sourceMappingURL=scaffold.d.ts.map

package/dist/init-deposit/scaffold.js

@@ -10,8 +10,8 @@ import { mkdir, readdir, rm, stat, writeFile } from "node:fs/promises";
 import { platform } from "node:os";
 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";
+import { MIGRATED_ARTIFACT_DIR } from "../xbrief-migrate/constants.js";
 import { CANONICAL_INSTALL_ROOT } from "./constants.js";
 import { installerManagedGuardEre } from "./hygiene.js";
 export { CANONICAL_INSTALL_ROOT };
@@ -322,7 +322,7 @@ function vbriefLifecycleDirsPresent(consumerVbrief) {
     });
 }
 export async function writeConsumerVbrief(projectDir, deftDir, io) {
-    const consumerVbrief = resolveLifecycleRoot(projectDir);
+    const consumerVbrief = join(projectDir, MIGRATED_ARTIFACT_DIR);
     const schemasDst = join(consumerVbrief, "schemas");
     const vbriefMdDst = join(consumerVbrief, "vbrief.md");
     const schemasPresent = existsSync(schemasDst) && statSync(schemasDst).isDirectory();
@@ -774,12 +774,12 @@ export async function pruneVendoredTsTests(projectDir, io) {
     return removed;
 }
 /** Best-effort #1430 neutralization deposit (mirrors depositNeutralization). */
-export async function depositNeutralization(projectDir, io) {
+export async function depositNeutralization(projectDir, io, options = {}) {
     const steps = [
         () => ensureGitattributes(projectDir, io),
         () => ensureGreptileIgnore(projectDir, io),
         () => ensureCodeqlPathsIgnore(projectDir, io),
-        () => ensureCoreGuardWorkflow(projectDir, io),
+        ...(options.skipGuardWorkflow ? [] : [() => ensureCoreGuardWorkflow(projectDir, io)]),
         () => pruneFrameworkSelfTests(projectDir, io),
         async () => (await pruneVendoredTsTests(projectDir, io)) > 0,
     ];

package/dist/integration-e2e/helpers.js

@@ -77,12 +77,12 @@ export function populateCacheLayout(cacheRoot, repo, issueNumbers) {
 }
 export function createConsumerProject(parent) {
     const root = join(parent, "consumer");
-    mkdirSync(join(root, "vbrief", "proposed"), { recursive: true });
-    mkdirSync(join(root, "vbrief", "pending"), { recursive: true });
-    mkdirSync(join(root, "vbrief", "active"), { recursive: true });
-    mkdirSync(join(root, "vbrief", "completed"), { recursive: true });
-    mkdirSync(join(root, "vbrief", "cancelled"), { recursive: true });
-    writeFileSync(join(root, "vbrief", "specification.vbrief.json"), `${JSON.stringify({
+    mkdirSync(join(root, "xbrief", "proposed"), { recursive: true });
+    mkdirSync(join(root, "xbrief", "pending"), { recursive: true });
+    mkdirSync(join(root, "xbrief", "active"), { recursive: true });
+    mkdirSync(join(root, "xbrief", "completed"), { recursive: true });
+    mkdirSync(join(root, "xbrief", "cancelled"), { recursive: true });
+    writeFileSync(join(root, "xbrief", "specification.xbrief.json"), `${JSON.stringify({
         vBRIEFInfo: { version: "0.5" },
         plan: {
             title: "Consumer Project",
@@ -96,7 +96,7 @@ export function createConsumerProject(parent) {
     return root;
 }
 export function writeScopeVbrief(projectRoot, folder, filename, status = "proposed") {
-    const target = join(projectRoot, "vbrief", folder, filename);
+    const target = join(projectRoot, "xbrief", folder, filename);
     writeFileSync(target, `${JSON.stringify({
         vBRIEFInfo: { version: "0.5" },
         plan: {

package/dist/layout/index.d.ts

@@ -1,2 +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";
+export { ARTIFACT_SUFFIXES, hasArtifactSuffix, isLifecycleArtifactPath, 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