@deftai/directive-core 0.68.0 → 0.69.0

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

@@ -43,6 +43,24 @@ export declare function resolveInitGitignoreLines(projectDir: string, gitLsFiles
 export declare function ensureInitGitignoreLines(projectDir: string, io: InitDepositIo, options?: {
     gitLsFiles?: GitLsFiles;
 }): EnsureInitGitignoreResult;
+/**
+ * The reconciled ignore set for the vendored→hybrid un-commit (#2269): the
+ * canonical baseline (which already covers `.deft/.cli/`, `.deft/ritual-state.json`,
+ * and the `.deft-cache/` path) plus the `.deft/core/` deposit entry that
+ * greenfield init born-ignores. `package.json` is deliberately absent — the
+ * committed pin MUST stay tracked so content can be reconstituted after the
+ * deposit is un-committed.
+ */
+export declare const UNTRACK_CORE_GITIGNORE_LINES: readonly string[];
+/**
+ * Reconcile `.gitignore` for the `migrate --untrack-core` path: force the
+ * `.deft/core/` deposit entry (init leaves a tracked deposit alone, but
+ * un-track has just removed it from the index, so it MUST now be ignored) plus
+ * the canonical baseline, and never ignore the committed `package.json` pin.
+ * Idempotent: a second run over an already-reconciled `.gitignore` makes no
+ * change.
+ */
+export declare function ensureUntrackCoreGitignoreLines(projectDir: string, io: InitDepositIo): EnsureInitGitignoreResult;
 /**
  * Copy the content package into `.deft/core`, reporting whether the deposit was
  * absent before copy (reconstitution). Always refreshes when present.

package/dist/init-deposit/gitignore.js

@@ -22,6 +22,7 @@ const DEFT_CORE_COVERING_LINES = new Set([".deft/core/", ".deft/core"]);
  */
 export const CANONICAL_GITIGNORE_BASELINE = [
     ".deft-cache/",
+    ".deft/.cli/",
     ".deft/ritual-state.json",
     ".deft/last-session.json",
     ".deft/routing.local.json",
@@ -95,14 +96,20 @@ export function resolveInitGitignoreLines(projectDir, gitLsFiles = defaultGitLsF
     };
 }
 /**
- * Ensure the consumer `.gitignore` carries the canonical baseline plus, for
- * greenfield installs, the `.deft/core/` ignore entry. Heals forbidden blanket
- * `vbrief/.eval/` lines (#1464). Never un-commits a tracked deposit (#1941).
+ * Ignore entries the deft framework MUST NEVER add to `.gitignore`. The
+ * committed `package.json` pin (#2264) is the reconstitution anchor for the
+ * un-committed deposit; ignoring it would silently drop the pin from version
+ * control and break `migrate --untrack-core`'s reconstitution guarantee (#2269).
  */
-export function ensureInitGitignoreLines(projectDir, io, options = {}) {
-    const gitLsFiles = options.gitLsFiles ?? defaultGitLsFiles;
-    const { lines: targetLines, includeDeftCore } = resolveInitGitignoreLines(projectDir, gitLsFiles);
-    const tracked = isDepositTrackedInGit(projectDir, gitLsFiles);
+const NEVER_IGNORE_LINES = new Set(["package.json", "/package.json"]);
+/**
+ * Read, heal, and reconcile `.gitignore` against `targetLines`. Shared by the
+ * greenfield-init and the vendored→hybrid un-commit reconcilers so the
+ * read/heal/append/write path lives in exactly one place. Pure of any caller
+ * messaging — the callers decide what to print from the returned record. The
+ * `package.json` pin is filtered out unconditionally (#2269 invariant).
+ */
+function reconcileGitignoreFile(projectDir, targetLines, includeDeftCoreRationale) {
     const path = join(projectDir, ".gitignore");
     let existing = "";
     if (existsSync(path)) {
@@ -134,16 +141,20 @@ export function ensureInitGitignoreLines(projectDir, io, options = {}) {
     }
     const additions = [];
     for (const line of targetLines) {
+        // Invariant (#2269): never ignore the committed package.json pin.
+        if (NEVER_IGNORE_LINES.has(line.trim()))
+            continue;
         if (!gitignoreCoversLine(present, line)) {
             additions.push(line);
         }
     }
     if (!blanketRemoved && additions.length === 0) {
-        io.printf(".gitignore already covers the canonical deft entries — skipping.\n");
         return {
             changed: false,
+            additions,
+            blanketRemoved,
             deftCoreIgnored: gitignoreCoversLine(present, GITIGNORE_DEFT_CORE_LINE),
-            skippedDeftCoreBecauseTracked: tracked === true,
+            alreadyCovered: true,
         };
     }
     let healed = kept.join("\n");
@@ -159,7 +170,7 @@ export function ensureInitGitignoreLines(projectDir, io, options = {}) {
             body += "\n";
         }
         body += DEFT_FRAMEWORK_GITIGNORE_HEADER;
-        if (includeDeftCore && additions.includes(GITIGNORE_DEFT_CORE_LINE)) {
+        if (includeDeftCoreRationale && additions.includes(GITIGNORE_DEFT_CORE_LINE)) {
             body += DEFT_CORE_GITIGNORE_RATIONALE;
         }
         for (const add of additions) {
@@ -172,22 +183,90 @@ export function ensureInitGitignoreLines(projectDir, io, options = {}) {
     catch (cause) {
         throw new Error(`could not write .gitignore: ${String(cause)}`);
     }
-    if (additions.length > 0) {
-        io.printf(`.gitignore updated with canonical entries: ${additions.join(", ")}\n`);
+    const finalPresent = collectPresentGitignoreLines(body);
+    return {
+        changed: true,
+        additions,
+        blanketRemoved,
+        deftCoreIgnored: gitignoreCoversLine(finalPresent, GITIGNORE_DEFT_CORE_LINE),
+        alreadyCovered: false,
+    };
+}
+/**
+ * Ensure the consumer `.gitignore` carries the canonical baseline plus, for
+ * greenfield installs, the `.deft/core/` ignore entry. Heals forbidden blanket
+ * `vbrief/.eval/` lines (#1464). Never un-commits a tracked deposit (#1941).
+ */
+export function ensureInitGitignoreLines(projectDir, io, options = {}) {
+    const gitLsFiles = options.gitLsFiles ?? defaultGitLsFiles;
+    const { lines: targetLines, includeDeftCore } = resolveInitGitignoreLines(projectDir, gitLsFiles);
+    const tracked = isDepositTrackedInGit(projectDir, gitLsFiles);
+    const res = reconcileGitignoreFile(projectDir, targetLines, includeDeftCore);
+    if (res.alreadyCovered) {
+        io.printf(".gitignore already covers the canonical deft entries — skipping.\n");
+        return {
+            changed: false,
+            deftCoreIgnored: res.deftCoreIgnored,
+            skippedDeftCoreBecauseTracked: tracked === true,
+        };
     }
-    if (blanketRemoved) {
+    if (res.additions.length > 0) {
+        io.printf(`.gitignore updated with canonical entries: ${res.additions.join(", ")}\n`);
+    }
+    if (res.blanketRemoved) {
         io.printf(".gitignore healed: removed forbidden blanket vbrief/.eval/ line (#1464).\n");
     }
     if (tracked === true) {
         io.printf(".deft/core is tracked in git — leaving it tracked; vendored→hybrid un-commit is #1941.\n");
     }
-    const finalPresent = collectPresentGitignoreLines(body);
     return {
         changed: true,
-        deftCoreIgnored: gitignoreCoversLine(finalPresent, GITIGNORE_DEFT_CORE_LINE),
+        deftCoreIgnored: res.deftCoreIgnored,
         skippedDeftCoreBecauseTracked: tracked === true,
     };
 }
+/**
+ * The reconciled ignore set for the vendored→hybrid un-commit (#2269): the
+ * canonical baseline (which already covers `.deft/.cli/`, `.deft/ritual-state.json`,
+ * and the `.deft-cache/` path) plus the `.deft/core/` deposit entry that
+ * greenfield init born-ignores. `package.json` is deliberately absent — the
+ * committed pin MUST stay tracked so content can be reconstituted after the
+ * deposit is un-committed.
+ */
+export const UNTRACK_CORE_GITIGNORE_LINES = [
+    ...CANONICAL_GITIGNORE_BASELINE,
+    GITIGNORE_DEFT_CORE_LINE,
+];
+/**
+ * Reconcile `.gitignore` for the `migrate --untrack-core` path: force the
+ * `.deft/core/` deposit entry (init leaves a tracked deposit alone, but
+ * un-track has just removed it from the index, so it MUST now be ignored) plus
+ * the canonical baseline, and never ignore the committed `package.json` pin.
+ * Idempotent: a second run over an already-reconciled `.gitignore` makes no
+ * change.
+ */
+export function ensureUntrackCoreGitignoreLines(projectDir, io) {
+    const res = reconcileGitignoreFile(projectDir, UNTRACK_CORE_GITIGNORE_LINES, false);
+    if (res.alreadyCovered) {
+        io.printf(".gitignore already ignores .deft/core/ and the canonical deft entries — skipping.\n");
+        return {
+            changed: false,
+            deftCoreIgnored: res.deftCoreIgnored,
+            skippedDeftCoreBecauseTracked: false,
+        };
+    }
+    if (res.additions.length > 0) {
+        io.printf(`.gitignore updated with canonical entries: ${res.additions.join(", ")}\n`);
+    }
+    if (res.blanketRemoved) {
+        io.printf(".gitignore healed: removed forbidden blanket vbrief/.eval/ line (#1464).\n");
+    }
+    return {
+        changed: true,
+        deftCoreIgnored: res.deftCoreIgnored,
+        skippedDeftCoreBecauseTracked: false,
+    };
+}
 /**
  * Copy the content package into `.deft/core`, reporting whether the deposit was
  * absent before copy (reconstitution). Always refreshes when present.

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

@@ -0,0 +1,87 @@
+/**
+ * `directive init --headless` — manifest emitter for no-shell consumer products
+ * (#2268 / epic #2203).
+ *
+ * Hosted consumer products (e.g. deftai/deftvisage#1036) have no shell or npm
+ * access to the end user's machine. This module serialises the merged keystone
+ * `plan()` schema into a `{ version, files: [{ path, content, encoding }] }`
+ * manifest with ALL execution side effects suppressed: no interactive prompts,
+ * no git operations, no git-hook installation, and no filesystem writes outside
+ * the explicit `--output` target. It makes no git-repo assumption and runs
+ * against an empty / non-existent directory.
+ *
+ * Single-sourcing (the #2268 acceptance): the manifest is DERIVED from `plan()`
+ * — the collected file set is threaded through `plan(..., { files })` and read
+ * back out of {@link ResolutionPlan.files}. There is no separate "what would
+ * init produce" reimplementation; the collectors here are the manifest-only,
+ * read-only counterparts of the executing deposit path in `scaffold.ts` /
+ * `init-deposit.ts` (they reuse the same render helpers WITHOUT filesystem or
+ * git writes).
+ *
+ * On registry / content-resolution failure the CLI wrapper exits non-zero and
+ * emits a JSON error object so the calling backend can treat it as non-fatal
+ * (never a crash or a partial write).
+ */
+import type { ResolutionFile } from "@deftai/directive-types";
+/** The five xBRIEF lifecycle folders scaffolded into a fresh project. */
+export declare const HEADLESS_XBRIEF_LIFECYCLE_DIRS: readonly ["proposed", "pending", "active", "completed", "cancelled"];
+/** A single file entry in the headless manifest. */
+export type HeadlessManifestFile = ResolutionFile;
+/** The serialised headless manifest shape. */
+export interface HeadlessManifest {
+    /** Resolved framework version the manifest was built against. */
+    readonly version: string;
+    /** All files a consumer backend should materialise for a fresh install. */
+    readonly files: readonly HeadlessManifestFile[];
+}
+/**
+ * JSON error object emitted on a registry / content-resolution failure. The
+ * calling backend treats a non-zero exit + this object as non-fatal.
+ */
+export interface HeadlessManifestErrorObject {
+    readonly success: false;
+    readonly error: string;
+    readonly error_code: string;
+}
+/** Injectable seams; defaults are the real content-package resolution path. */
+export interface HeadlessManifestSeams {
+    /** Resolve the installed content-package root. Default: real npm resolution. */
+    readonly resolveContentRoot?: () => Promise<string>;
+    /** Override the resolved version (default: read the content package.json). */
+    readonly readVersion?: (contentRoot: string) => string;
+    /** Deterministic UTC ISO timestamp for the VERSION marker (default: now). */
+    readonly nowIso?: () => string;
+    /** Deterministic managed-section session id (default: fixed headless token). */
+    readonly newSession?: () => string;
+}
+/**
+ * Build the headless manifest. Reads the content package read-only, collects
+ * the fresh-install file set (payload + version-consistent AGENTS.md + xBRIEF
+ * scaffold + pinned package.json), threads it through `plan()` so the manifest
+ * is single-sourced from the resolution schema, and returns the serialisable
+ * shape. Performs NO filesystem writes and NO git operations.
+ *
+ * Throws (never partially writes) on content-resolution failure; the CLI
+ * wrapper converts the throw into a JSON error object + non-zero exit.
+ */
+export declare function buildHeadlessManifest(seams?: HeadlessManifestSeams): Promise<HeadlessManifest>;
+export interface RunInitHeadlessCliOptions {
+    /** Explicit `--output` target, or null to emit the manifest to stdout. */
+    readonly outputPath: string | null;
+    readonly writeOut: (text: string) => void;
+    readonly writeErr: (text: string) => void;
+    readonly seams?: HeadlessManifestSeams;
+    /**
+     * Filesystem write seam (test-only). The default creates the parent directory
+     * and writes the file; an injected seam OWNS all filesystem contact (including
+     * directory creation), so the manifest write stays fully isolatable in tests.
+     */
+    readonly writeFile?: (path: string, data: string) => void;
+}
+/**
+ * CLI-facing entrypoint for `directive init --headless`. Emits the manifest to
+ * `--output` (the ONLY permitted filesystem write) or stdout, and on failure
+ * writes a JSON error object to stdout and returns exit code 1.
+ */
+export declare function runInitHeadlessCli(options: RunInitHeadlessCliOptions): Promise<number>;
+//# sourceMappingURL=headless-manifest.d.ts.map

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

@@ -0,0 +1,261 @@
+/**
+ * `directive init --headless` — manifest emitter for no-shell consumer products
+ * (#2268 / epic #2203).
+ *
+ * Hosted consumer products (e.g. deftai/deftvisage#1036) have no shell or npm
+ * access to the end user's machine. This module serialises the merged keystone
+ * `plan()` schema into a `{ version, files: [{ path, content, encoding }] }`
+ * manifest with ALL execution side effects suppressed: no interactive prompts,
+ * no git operations, no git-hook installation, and no filesystem writes outside
+ * the explicit `--output` target. It makes no git-repo assumption and runs
+ * against an empty / non-existent directory.
+ *
+ * Single-sourcing (the #2268 acceptance): the manifest is DERIVED from `plan()`
+ * — the collected file set is threaded through `plan(..., { files })` and read
+ * back out of {@link ResolutionPlan.files}. There is no separate "what would
+ * init produce" reimplementation; the collectors here are the manifest-only,
+ * read-only counterparts of the executing deposit path in `scaffold.ts` /
+ * `init-deposit.ts` (they reuse the same render helpers WITHOUT filesystem or
+ * git writes).
+ *
+ * On registry / content-resolution failure the CLI wrapper exits non-zero and
+ * emits a JSON error object so the calling backend can treat it as non-fatal
+ * (never a crash or a partial write).
+ */
+import { mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join, relative, resolve, sep } from "node:path";
+import { ContentPackageNotFoundError, resolveInstalledContentRoot, } from "../deposit/resolve-content.js";
+import { readCorePackageVersion } from "../engine-version.js";
+import { agentsRefreshPlan } from "../platform/agents-md.js";
+import { plan } from "../resolution/plan.js";
+import { CANONICAL_INSTALL_ROOT } from "./constants.js";
+import { buildInstallManifestText, PIN_DEPENDENCY_NAME } from "./scaffold.js";
+/** POSIX-relative path of the payload VERSION marker inside the manifest. */
+const PAYLOAD_VERSION_PATH = `${CANONICAL_INSTALL_ROOT}/VERSION`;
+/** Provenance stamp written into the emitted `.deft/core/VERSION` marker. */
+const HEADLESS_FETCHED_BY = "directive-init-headless";
+/** The five xBRIEF lifecycle folders scaffolded into a fresh project. */
+export const HEADLESS_XBRIEF_LIFECYCLE_DIRS = [
+    "proposed",
+    "pending",
+    "active",
+    "completed",
+    "cancelled",
+];
+const XBRIEF_LIFECYCLE_GITKEEP = `# Keeps this xbrief/ lifecycle directory present in version control so the
+# deft-directive-setup pre-cutover guard does not fire on a fresh headless
+# install. Emitted by \`directive init --headless\` (#2268).
+`;
+function defaultNowIso() {
+    return new Date().toISOString().replace(/\.\d{3}Z$/, "Z");
+}
+/** Read the resolved version from the content package.json (engine fallback). */
+function resolveVersion(contentRoot, seams) {
+    if (seams.readVersion)
+        return seams.readVersion(contentRoot);
+    try {
+        const parsed = JSON.parse(readFileSync(join(contentRoot, "package.json"), "utf8"));
+        if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+            const version = parsed.version;
+            if (version?.trim())
+                return version.trim();
+        }
+    }
+    catch {
+        // Fall through to the engine version.
+    }
+    return readCorePackageVersion();
+}
+/**
+ * Decide the manifest encoding for a file's raw bytes. UTF-8 text round-trips
+ * losslessly; anything else (or bytes carrying a NUL) is base64 so binary
+ * payload assets survive JSON serialisation without corruption.
+ */
+function encodeBytes(buf) {
+    if (!buf.includes(0)) {
+        const text = buf.toString("utf8");
+        if (Buffer.from(text, "utf8").equals(buf)) {
+            return { content: text, encoding: "utf-8" };
+        }
+    }
+    return { content: buf.toString("base64"), encoding: "base64" };
+}
+/** POSIX-normalise a path (manifest paths are always forward-slash). */
+function toPosix(p) {
+    return sep === "/" ? p : p.split(sep).join("/");
+}
+/**
+ * Walk the content-package tree read-only and collect one manifest entry per
+ * file, prefixed with the canonical install root. The manifest-only counterpart
+ * of `reconstituteDepositFromContent` — it materialises bytes into memory
+ * instead of copying them onto disk.
+ */
+function collectPayloadFiles(contentRoot) {
+    const out = [];
+    const stack = [contentRoot];
+    while (stack.length > 0) {
+        const dir = stack.pop();
+        if (dir === undefined)
+            continue;
+        for (const entry of readdirSync(dir, { withFileTypes: true })) {
+            const full = join(dir, entry.name);
+            if (entry.isDirectory()) {
+                stack.push(full);
+            }
+            else if (entry.isFile()) {
+                const rel = toPosix(relative(contentRoot, full));
+                const { content, encoding } = encodeBytes(readFileSync(full));
+                out.push({ path: `${CANONICAL_INSTALL_ROOT}/${rel}`, content, encoding });
+            }
+        }
+    }
+    return out;
+}
+/**
+ * Render the version-consistent `.deft/core/VERSION` marker. The `sha=` slot is
+ * stamped with the resolved version (headless mode has no git checkout), which
+ * is what keeps the emitted AGENTS.md managed section and the payload provably
+ * consistent against a single resolved version.
+ */
+function collectVersionFile(version, nowIso) {
+    const tag = version.startsWith("v") ? version : `v${version}`;
+    const body = buildInstallManifestText({
+        ref: tag,
+        sha: version,
+        tag,
+        installRoot: CANONICAL_INSTALL_ROOT,
+        fetchedAt: nowIso,
+        fetchedBy: HEADLESS_FETCHED_BY,
+    });
+    return { path: PAYLOAD_VERSION_PATH, content: body, encoding: "utf-8" };
+}
+/**
+ * Render the greenfield AGENTS.md (unmanaged header + attributed managed
+ * section) from the SAME content root as the payload, so the managed section
+ * can never drift from the deposited framework version. The managed-section
+ * `sha=` is stamped with the resolved version for version-consistency.
+ */
+function collectAgentsMdFile(contentRoot, version, nowIso, sessionId) {
+    const agentsResult = agentsRefreshPlan("headless-project", {
+        frameworkRoot: contentRoot,
+        resolveSha: () => version,
+        nowIso: () => nowIso,
+        newSession: () => sessionId,
+        readAgents: () => null,
+    });
+    const newContent = agentsResult.new_content;
+    if (typeof newContent !== "string") {
+        throw new Error(`AGENTS.md render produced no content (state: ${String(agentsResult.state)})`);
+    }
+    return { path: "AGENTS.md", content: newContent, encoding: "utf-8" };
+}
+/** The five xBRIEF lifecycle `.gitkeep` files (empty dirs can't ride a manifest). */
+function collectXbriefScaffoldFiles() {
+    return HEADLESS_XBRIEF_LIFECYCLE_DIRS.map((sub) => ({
+        path: `xbrief/${sub}/.gitkeep`,
+        content: XBRIEF_LIFECYCLE_GITKEEP,
+        encoding: "utf-8",
+    }));
+}
+/** The pinned `package.json` devDependency snippet (exact, private workspace). */
+function collectPackageJsonFile(version) {
+    const pinVersion = version.trim().replace(/^v/i, "");
+    const pkg = {
+        private: true,
+        devDependencies: { [PIN_DEPENDENCY_NAME]: pinVersion },
+    };
+    return {
+        path: "package.json",
+        content: `${JSON.stringify(pkg, null, 2)}\n`,
+        encoding: "utf-8",
+    };
+}
+/**
+ * Greenfield fact-set for the headless manifest. `hasDeftCore: false` routes
+ * `plan()` to `init` mode (Row 2), before any engine/pin reconciliation — no
+ * git-repo assumption, no reachable-engine requirement.
+ */
+function headlessGreenfieldFacts() {
+    return {
+        hasGit: false,
+        hasAppCode: false,
+        hasDeftCore: false,
+        deftCorePayloadVersion: null,
+        hasManagedSection: false,
+        managedSectionSha: null,
+        hasVbrief: false,
+        hasXbrief: false,
+        preCutoverArtifacts: false,
+        engineReachable: false,
+        engineVersion: null,
+        pinVersion: null,
+    };
+}
+/**
+ * Build the headless manifest. Reads the content package read-only, collects
+ * the fresh-install file set (payload + version-consistent AGENTS.md + xBRIEF
+ * scaffold + pinned package.json), threads it through `plan()` so the manifest
+ * is single-sourced from the resolution schema, and returns the serialisable
+ * shape. Performs NO filesystem writes and NO git operations.
+ *
+ * Throws (never partially writes) on content-resolution failure; the CLI
+ * wrapper converts the throw into a JSON error object + non-zero exit.
+ */
+export async function buildHeadlessManifest(seams = {}) {
+    const resolveContentRoot = seams.resolveContentRoot ?? resolveInstalledContentRoot;
+    const contentRoot = await resolveContentRoot();
+    const version = resolveVersion(contentRoot, seams);
+    const nowIso = (seams.nowIso ?? defaultNowIso)();
+    const sessionId = (seams.newSession ?? (() => "headlessmanif"))();
+    const payload = collectPayloadFiles(contentRoot).filter((file) => file.path !== PAYLOAD_VERSION_PATH);
+    const files = [
+        ...payload,
+        collectVersionFile(version, nowIso),
+        collectAgentsMdFile(contentRoot, version, nowIso, sessionId),
+        ...collectXbriefScaffoldFiles(),
+        collectPackageJsonFile(version),
+    ].sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+    // Single-source the manifest from plan(): the collected set rides the
+    // ResolutionPlan.files channel, and we read it back out — no reimplementation.
+    const resolved = plan(headlessGreenfieldFacts(), {}, { files });
+    return { version, files: resolved.files };
+}
+/**
+ * CLI-facing entrypoint for `directive init --headless`. Emits the manifest to
+ * `--output` (the ONLY permitted filesystem write) or stdout, and on failure
+ * writes a JSON error object to stdout and returns exit code 1.
+ */
+export async function runInitHeadlessCli(options) {
+    try {
+        const manifest = await buildHeadlessManifest(options.seams);
+        const serialized = `${JSON.stringify(manifest, null, 2)}\n`;
+        if (options.outputPath) {
+            const abs = resolve(options.outputPath);
+            const writeFile = options.writeFile ??
+                ((path, data) => {
+                    mkdirSync(dirname(path), { recursive: true });
+                    writeFileSync(path, data);
+                });
+            writeFile(abs, serialized);
+            options.writeErr(`directive init --headless: wrote ${manifest.files.length}-file manifest (v${manifest.version}) to ${abs}\n`);
+        }
+        else {
+            options.writeOut(serialized);
+        }
+        return 0;
+    }
+    catch (cause) {
+        const message = cause instanceof Error ? cause.message : String(cause);
+        const error_code = cause instanceof ContentPackageNotFoundError
+            ? "content_resolution_failed"
+            : "headless_manifest_failed";
+        const errorObject = {
+            success: false,
+            error: message,
+            error_code,
+        };
+        options.writeOut(`${JSON.stringify(errorObject, null, 2)}\n`);
+        return 1;
+    }
+}
+//# sourceMappingURL=headless-manifest.js.map

package/dist/init-deposit/hygiene.js

@@ -11,6 +11,8 @@ 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";
+// The lifecycle dir names are identical across the legacy `vbrief/` tree and the
+// post-#2034 / #2110 `xbrief/` tree, so both allowlist families reuse this list.
 const VBRIEF_LIFECYCLE_DIRS = ["proposed", "pending", "active", "completed", "cancelled"];
 /** Single source of truth for installer-managed paths (#1440 / #1576). */
 export function installerManagedMatchers() {
@@ -24,11 +26,20 @@ export function installerManagedMatchers() {
         { exact: CODEQL_CONFIG_REL },
         { exact: CORE_GUARD_WORKFLOW_REL },
         { exact: "Taskfile.yml" },
+        // Legacy vbrief/ tree -- retained for not-yet-migrated consumers.
         { exact: "vbrief/.deft-version" },
         { exact: "vbrief/vbrief.md" },
         { prefix: "vbrief/schemas/" },
         { prefix: "vbrief/migration/" },
         ...VBRIEF_LIFECYCLE_DIRS.map((sub) => ({ exact: `vbrief/${sub}/.gitkeep` })),
+        // Migrated xbrief/ tree (#2034 / #2110). The framework-managed version marker
+        // now lives at xbrief/.deft-version, so it MUST be allowlisted or every routine
+        // `deft update` framework-deposit PR trips no-mixed-core-and-app (#2277).
+        { exact: "xbrief/.deft-version" },
+        { exact: "xbrief/xbrief.md" },
+        { prefix: "xbrief/schemas/" },
+        { prefix: "xbrief/migration/" },
+        ...VBRIEF_LIFECYCLE_DIRS.map((sub) => ({ exact: `xbrief/${sub}/.gitkeep` })),
     ];
 }
 function escapeEre(value) {

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

@@ -1,6 +1,9 @@
+export * from "./headless-manifest.js";
 export * from "./init-deposit.js";
+export * from "./init-dispatch.js";
 export * from "./legacy-detect.js";
 export * from "./migrate.js";
 export * from "./refresh.js";
 export * from "./scaffold.js";
+export * from "./untrack-core.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/init-deposit/index.js

@@ -1,6 +1,9 @@
+export * from "./headless-manifest.js";
 export * from "./init-deposit.js";
+export * from "./init-dispatch.js";
 export * from "./legacy-detect.js";
 export * from "./migrate.js";
 export * from "./refresh.js";
 export * from "./scaffold.js";
+export * from "./untrack-core.js";
 //# sourceMappingURL=index.js.map