@deftai/directive 0.68.0 → 0.69.0

package/dist/dispatch.d.ts

@@ -147,7 +147,11 @@ export declare function runPolicySet(argv: string[], io: DispatchIo): number;
 export declare function resolveCanonicalVerb(verb: string): string | null;
 /** Sorted list of all registered verb names (canonical + aliases). */
 export declare function registeredVerbs(): readonly string[];
-/** Print dispatcher help listing every registered verb. */
+/**
+ * Print dispatcher help. Leads with the three-command model (init / update /
+ * doctor) + first-run guidance so a no-arg `directive` orients a newcomer before
+ * the exhaustive verb list, which stays available below for power users (#2273).
+ */
 export declare function printHelp(io?: DispatchIo): void;
 /** Dispatch argv to a registered verb; returns the handler exit code. */
 export declare function dispatch(argv: string[], io?: DispatchIo): Promise<number>;

package/dist/dispatch.js

@@ -7,8 +7,8 @@ import { createHash } from "node:crypto";
 import { existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, readSync, rmSync, statSync, writeFileSync, } from "node:fs";
 import { homedir, tmpdir } from "node:os";
 import { basename, dirname, isAbsolute, join, relative, resolve } from "node:path";
-import { engineInfo } from "@deftai/directive-core";
-import { parseInitArgv, runInitDepositCli, userConfigDir, } from "@deftai/directive-core/init-deposit";
+import { engineInfo, userConfig } from "@deftai/directive-core";
+import { parseInitArgv, runInitDepositCli } from "@deftai/directive-core/init-deposit";
 import { appendAuditLog, disclosureLine, migrateLegacyPolicyKey, PLAN_POLICY_KEY, projectDefinitionPath, resolvePolicy, resolveWipCap, setPolicy, } from "@deftai/directive-core/policy";
 import { defaultWhich } from "@deftai/directive-core/scm";
 import { KNOWN_SUBAGENT_BACKEND_IDS, probeSubagentBackends, resolveSwarmSubagentBackend, } from "@deftai/directive-core/swarm";
@@ -1501,16 +1501,20 @@ function bootstrapPhaseLabel(phase) {
         return "project";
     return "spec";
 }
-function resolveBootstrapUserMdPath() {
-    const override = process.env.DEFT_USER_PATH?.trim();
-    if (override)
-        return resolve(override);
-    return join(userConfigDir(), "USER.md");
+/**
+ * Bootstrap USER.md path resolver (#2271). Delegates to the shared first-hit-
+ * wins resolver so the CLI bootstrap, session-start, and doctor share one
+ * source of truth. DEFT_USER_PATH precedence is preserved by the shared
+ * resolver (rung 1). `projectRoot` scopes the workspace-local rung so a bridged
+ * `<projectRoot>/.deft/USER.md` resolves without a manual DEFT_USER_PATH.
+ */
+function resolveBootstrapUserMdPath(projectRoot) {
+    return userConfig.resolveUserMdPath(projectRoot !== undefined ? { projectRoot } : {}).path;
 }
 function defaultBootstrapDeps() {
     return {
         deftCorePresent: (projectRoot) => isDirSafe(join(resolve(projectRoot), ".deft", "core")),
-        userMdPresent: () => isFileSafe(resolveBootstrapUserMdPath()),
+        userMdPresent: (projectRoot) => isFileSafe(resolveBootstrapUserMdPath(projectRoot)),
         projectDefPresent: (projectRoot) => isFileSafe(projectDefinitionPath(projectRoot)),
         runInitDeposit: async (projectRoot, io) => {
             const initArgs = parseInitArgv(["--yes", "--repo-root", projectRoot, "--json"], []);
@@ -2323,9 +2327,29 @@ export function registeredVerbs() {
     ]);
     return [...names].sort();
 }
-/** Print dispatcher help listing every registered verb. */
+/**
+ * Print dispatcher help. Leads with the three-command model (init / update /
+ * doctor) + first-run guidance so a no-arg `directive` orients a newcomer before
+ * the exhaustive verb list, which stays available below for power users (#2273).
+ */
 export function printHelp(io = defaultIo()) {
-    io.writeOut("Usage: directive <verb> [args...]\n\nRegistered verbs:\n");
+    io.writeOut("directive -- the Deft Directive CLI\n" +
+        "\n" +
+        "Start here (most projects only need these three):\n" +
+        "  directive init      Set up Directive in the current project (first-time setup)\n" +
+        "  directive update    Refresh an existing install and self-heal the engine\n" +
+        "  directive doctor    Diagnose the install and print the one next step\n" +
+        "\n" +
+        "First run? From the project root:\n" +
+        "  1. npm i -g @deftai/directive   (Node >= 20)\n" +
+        "     (pnpm: pnpm add -g @deftai/directive -- ensure PNPM_HOME is on PATH, run `pnpm setup` if needed)\n" +
+        "  2. directive init\n" +
+        "  3. directive doctor\n" +
+        "New clone where `directive` will not run? Read the Cold-start bootstrap block at the top of README.md.\n" +
+        "\n" +
+        "Usage: directive <verb> [args...]\n" +
+        "\n" +
+        "Registered verbs:\n");
     for (const name of registeredVerbs()) {
         io.writeOut(`  ${name}\n`);
     }

package/dist/init-cli/constants.d.ts

@@ -2,6 +2,41 @@
 export declare const CANONICAL_INIT_ARGV: readonly ["--yes", "--repo-root", ".", "--json"];
 /** Canonical headless upgrade argv (#1339 / #1409). */
 export declare const CANONICAL_UPDATE_ARGV: readonly ["--yes", "--upgrade", "--repo-root", ".", "--json"];
+/**
+ * Flags that make `directive update` classify + print its plan without executing
+ * the refresh (#2266). Recognised in the USER argv (never part of the canonical
+ * always-applied argv above, which must stay a real refresh).
+ */
+export declare const UPDATE_DRY_RUN_FLAGS: readonly ["--dry-run", "--plan"];
+/**
+ * Flags that make `directive init` classify + print the dispatch plan without
+ * executing any deposit/refresh/migrate (#2265). Mirrors {@link UPDATE_DRY_RUN_FLAGS};
+ * recognised in the USER argv, never part of the canonical always-applied argv
+ * above (which must stay a real adoption dispatch).
+ */
+export declare const INIT_DRY_RUN_FLAGS: readonly ["--dry-run", "--plan"];
+/**
+ * Flags that switch `directive init` into headless manifest-emit mode (#2268):
+ * serialise the merged keystone `plan()` into a `{ version, files }` manifest
+ * with ALL execution side effects suppressed. Recognised in the USER argv; NOT
+ * part of the canonical always-applied argv above (which must stay a real,
+ * executing adoption dispatch — a headless flag there would silently suppress
+ * every install's side effects).
+ */
+export declare const INIT_HEADLESS_FLAGS: readonly ["--headless", "/headless"];
+/**
+ * Flag naming the manifest output target for `--headless` (#2268). Accepts the
+ * `--output=<path>` and `--output <path>` forms; when absent the manifest is
+ * written to stdout. Writing this file is the ONLY filesystem side effect the
+ * headless path is permitted to perform.
+ */
+export declare const INIT_OUTPUT_FLAGS: readonly ["--output", "/output"];
 /** Canonical migrate argv: defaults to cwd, human-readable unless --json (#1941). */
 export declare const CANONICAL_MIGRATE_ARGV: readonly ["--repo-root", "."];
+/**
+ * Subcommand flag selecting the vendored→hybrid `.deft/core` un-commit (#2269).
+ * `migrate --untrack-core` dispatches to the destructive un-track path; bare
+ * `migrate` keeps its non-destructive provenance-stamp behavior.
+ */
+export declare const MIGRATE_UNTRACK_CORE_FLAG = "--untrack-core";
 //# sourceMappingURL=constants.d.ts.map

package/dist/init-cli/constants.js

@@ -2,6 +2,41 @@
 export const CANONICAL_INIT_ARGV = ["--yes", "--repo-root", ".", "--json"];
 /** Canonical headless upgrade argv (#1339 / #1409). */
 export const CANONICAL_UPDATE_ARGV = ["--yes", "--upgrade", "--repo-root", ".", "--json"];
+/**
+ * Flags that make `directive update` classify + print its plan without executing
+ * the refresh (#2266). Recognised in the USER argv (never part of the canonical
+ * always-applied argv above, which must stay a real refresh).
+ */
+export const UPDATE_DRY_RUN_FLAGS = ["--dry-run", "--plan"];
+/**
+ * Flags that make `directive init` classify + print the dispatch plan without
+ * executing any deposit/refresh/migrate (#2265). Mirrors {@link UPDATE_DRY_RUN_FLAGS};
+ * recognised in the USER argv, never part of the canonical always-applied argv
+ * above (which must stay a real adoption dispatch).
+ */
+export const INIT_DRY_RUN_FLAGS = ["--dry-run", "--plan"];
+/**
+ * Flags that switch `directive init` into headless manifest-emit mode (#2268):
+ * serialise the merged keystone `plan()` into a `{ version, files }` manifest
+ * with ALL execution side effects suppressed. Recognised in the USER argv; NOT
+ * part of the canonical always-applied argv above (which must stay a real,
+ * executing adoption dispatch — a headless flag there would silently suppress
+ * every install's side effects).
+ */
+export const INIT_HEADLESS_FLAGS = ["--headless", "/headless"];
+/**
+ * Flag naming the manifest output target for `--headless` (#2268). Accepts the
+ * `--output=<path>` and `--output <path>` forms; when absent the manifest is
+ * written to stdout. Writing this file is the ONLY filesystem side effect the
+ * headless path is permitted to perform.
+ */
+export const INIT_OUTPUT_FLAGS = ["--output", "/output"];
 /** Canonical migrate argv: defaults to cwd, human-readable unless --json (#1941). */
 export const CANONICAL_MIGRATE_ARGV = ["--repo-root", "."];
+/**
+ * Subcommand flag selecting the vendored→hybrid `.deft/core` un-commit (#2269).
+ * `migrate --untrack-core` dispatches to the destructive un-track path; bare
+ * `migrate` keeps its non-destructive provenance-stamp behavior.
+ */
+export const MIGRATE_UNTRACK_CORE_FLAG = "--untrack-core";
 //# sourceMappingURL=constants.js.map

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

@@ -1,3 +1,26 @@
+import { type HeadlessManifestSeams, type InitDispatchSeams } from "@deftai/directive-core/init-deposit";
 import type { DispatchIo } from "../dispatch.js";
-export declare function runInit(argv: readonly string[], io: DispatchIo): Promise<number>;
+/** True when the user argv asked for a classify-only dispatch plan (`--dry-run`/`--plan`). */
+export declare function isInitDryRun(argv: readonly string[]): boolean;
+/** True when the user argv asked for headless manifest-emit mode (`--headless`). */
+export declare function isInitHeadless(argv: readonly string[]): boolean;
+/**
+ * Resolve the `--output=<path>` / `--output <path>` target for headless mode.
+ * Returns null when no output flag is present (manifest goes to stdout).
+ */
+export declare function parseInitOutputPath(argv: readonly string[]): string | null;
+/**
+ * `directive init` — the universal adoption dispatcher (#2265). Classifies the
+ * directory via the shared keystone plan() fact-set and dispatches to
+ * scaffold / brownfield-install / delegate-to-update / route-to-migrate.
+ *
+ * When `--headless` is present (#2268), init short-circuits the executing
+ * dispatch and instead serialises the merged `plan()` schema into a
+ * `{ version, files }` manifest with ALL execution side effects suppressed
+ * (no prompts, no git, no hook install, no writes outside `--output`).
+ *
+ * The optional `seams` argument is test-only injection for the dispatch path;
+ * `headlessSeams` injects the content-resolution seam for the headless path.
+ */
+export declare function runInit(argv: readonly string[], io: DispatchIo, seams?: InitDispatchSeams, headlessSeams?: HeadlessManifestSeams): Promise<number>;
 //# sourceMappingURL=init.d.ts.map

package/dist/init-cli/init.js

@@ -1,11 +1,75 @@
-import { parseInitArgv, runInitDepositCli } from "@deftai/directive-core/init-deposit";
-import { CANONICAL_INIT_ARGV } from "./constants.js";
-export function runInit(argv, io) {
+import { parseInitArgv, runInitDispatchCli, runInitHeadlessCli, } from "@deftai/directive-core/init-deposit";
+import { CANONICAL_INIT_ARGV, INIT_DRY_RUN_FLAGS, INIT_HEADLESS_FLAGS, INIT_OUTPUT_FLAGS, } from "./constants.js";
+/** True when the user argv asked for a classify-only dispatch plan (`--dry-run`/`--plan`). */
+export function isInitDryRun(argv) {
+    const flags = INIT_DRY_RUN_FLAGS;
+    return argv.some((arg) => flags.includes(arg));
+}
+/** True when the user argv asked for headless manifest-emit mode (`--headless`). */
+export function isInitHeadless(argv) {
+    const flags = INIT_HEADLESS_FLAGS;
+    return argv.some((arg) => flags.includes(arg));
+}
+/**
+ * Resolve the `--output=<path>` / `--output <path>` target for headless mode.
+ * Returns null when no output flag is present (manifest goes to stdout).
+ */
+export function parseInitOutputPath(argv) {
+    const flags = INIT_OUTPUT_FLAGS;
+    for (let i = 0; i < argv.length; i += 1) {
+        const arg = argv[i];
+        if (arg === undefined)
+            continue;
+        for (const flag of flags) {
+            if (arg === flag) {
+                const next = argv[i + 1];
+                // A next token that is itself a flag (leading `-`) is NOT a path — treat
+                // `--output --headless` as a missing value rather than writing a file
+                // literally named `--headless`. Absolute POSIX paths (`/foo`) are kept.
+                if (next === undefined || next.length === 0 || next.startsWith("-"))
+                    return null;
+                return next;
+            }
+            const prefix = `${flag}=`;
+            if (arg.startsWith(prefix)) {
+                const value = arg.slice(prefix.length);
+                return value.length > 0 ? value : null;
+            }
+        }
+    }
+    return null;
+}
+/**
+ * `directive init` — the universal adoption dispatcher (#2265). Classifies the
+ * directory via the shared keystone plan() fact-set and dispatches to
+ * scaffold / brownfield-install / delegate-to-update / route-to-migrate.
+ *
+ * When `--headless` is present (#2268), init short-circuits the executing
+ * dispatch and instead serialises the merged `plan()` schema into a
+ * `{ version, files }` manifest with ALL execution side effects suppressed
+ * (no prompts, no git, no hook install, no writes outside `--output`).
+ *
+ * The optional `seams` argument is test-only injection for the dispatch path;
+ * `headlessSeams` injects the content-resolution seam for the headless path.
+ */
+export function runInit(argv, io, seams, headlessSeams) {
+    if (isInitHeadless(argv)) {
+        return runInitHeadlessCli({
+            outputPath: parseInitOutputPath(argv),
+            writeOut: io.writeOut,
+            writeErr: io.writeErr,
+            seams: headlessSeams,
+        });
+    }
     const args = parseInitArgv(CANONICAL_INIT_ARGV, argv);
-    return runInitDepositCli({
-        ...args,
+    return runInitDispatchCli({
+        projectDir: args.projectDir,
+        jsonOut: args.jsonOut,
+        nonInteractive: args.nonInteractive,
+        dryRun: isInitDryRun(argv),
         writeOut: io.writeOut,
         writeErr: io.writeErr,
+        seams,
     });
 }
 //# sourceMappingURL=init.js.map

package/dist/init-cli/migrate.js

@@ -1,9 +1,13 @@
-import { parseInitArgv, runMigrateCli } from "@deftai/directive-core/init-deposit";
-import { CANONICAL_MIGRATE_ARGV } from "./constants.js";
+import { parseInitArgv, runMigrateCli, runUntrackCoreCli, } from "@deftai/directive-core/init-deposit";
+import { CANONICAL_MIGRATE_ARGV, MIGRATE_UNTRACK_CORE_FLAG } from "./constants.js";
 /**
  * `directive migrate` (alias `deft migrate`) -- stage-2 provenance verb (#1941):
  * stamp a canonical-vendored `.deft/core` deposit as npm-managed. Thin wrapper
  * over the core orchestrator; maps the three-state result to a 0/1/2 exit code.
+ *
+ * `directive migrate --untrack-core` (#2269) branches to the vendored→hybrid
+ * un-commit path: `git rm --cached -r .deft/core` gated on a committed pin, plus
+ * `.gitignore` reconciliation. The destructive index mutation lives ONLY there.
  */
 const NO_EFFECT_CONFIRMATION_FLAGS = new Set([
     "--yes",
@@ -11,8 +15,21 @@ const NO_EFFECT_CONFIRMATION_FLAGS = new Set([
     "/yes",
     "/non-interactive",
 ]);
+function hasUntrackCoreFlag(argv) {
+    return argv.some((arg) => arg === MIGRATE_UNTRACK_CORE_FLAG || arg === `/${MIGRATE_UNTRACK_CORE_FLAG.slice(2)}`);
+}
 export function runMigrate(argv, io) {
     const args = parseInitArgv(CANONICAL_MIGRATE_ARGV, argv);
+    // `migrate --untrack-core` selects the destructive un-track subcommand;
+    // bare `migrate` keeps the provenance-stamp behavior below.
+    if (hasUntrackCoreFlag(argv)) {
+        return runUntrackCoreCli({
+            projectDir: args.projectDir,
+            jsonOut: args.jsonOut,
+            writeOut: io.writeOut,
+            writeErr: io.writeErr,
+        });
+    }
     // `migrate` reuses `parseInitArgv`, which understands the init/update headless
     // confirmation flags. migrate has no interactive prompts, so acknowledge the
     // flag rather than silently swallowing it (a natural reflex from init/update).

package/dist/init-cli/update.d.ts

@@ -1,3 +1,5 @@
 import type { DispatchIo } from "../dispatch.js";
+/** True when the user argv asked for a classify-only dry-run (`--dry-run`/`--plan`). */
+export declare function isUpdateDryRun(argv: readonly string[]): boolean;
 export declare function runUpdate(argv: readonly string[], io: DispatchIo): Promise<number>;
 //# sourceMappingURL=update.d.ts.map

package/dist/init-cli/update.js

@@ -1,9 +1,15 @@
 import { parseUpdateArgv, runRefreshDepositCli } from "@deftai/directive-core/init-deposit";
-import { CANONICAL_UPDATE_ARGV } from "./constants.js";
+import { CANONICAL_UPDATE_ARGV, UPDATE_DRY_RUN_FLAGS } from "./constants.js";
+/** True when the user argv asked for a classify-only dry-run (`--dry-run`/`--plan`). */
+export function isUpdateDryRun(argv) {
+    const flags = UPDATE_DRY_RUN_FLAGS;
+    return argv.some((arg) => flags.includes(arg));
+}
 export function runUpdate(argv, io) {
     const args = parseUpdateArgv(CANONICAL_UPDATE_ARGV, argv);
     return runRefreshDepositCli({
         ...args,
+        dryRun: isUpdateDryRun(argv),
         writeOut: io.writeOut,
         writeErr: io.writeErr,
     });

package/dist/migrate-xbrief.d.ts

@@ -3,6 +3,7 @@ export interface ParsedMigrateXbriefArgs {
     projectRoot: string;
     frameworkRoot: string;
     force: boolean;
+    keepLegacy: boolean;
     error?: string;
 }
 export declare function parseArgs(argv: readonly string[]): ParsedMigrateXbriefArgs;

package/dist/migrate-xbrief.js

@@ -6,11 +6,15 @@ export function parseArgs(argv) {
     let projectRoot = ".";
     let explicitFrameworkRoot;
     let force = false;
+    let keepLegacy = false;
     for (let i = 0; i < argv.length; i += 1) {
         const arg = argv[i] ?? "";
         if (arg === "--force") {
             force = true;
         }
+        else if (arg === "--keep-legacy") {
+            keepLegacy = true;
+        }
         else if (arg === "--project-root") {
             const value = argv[i + 1];
             if (value === undefined) {
@@ -18,6 +22,7 @@ export function parseArgs(argv) {
                     projectRoot,
                     frameworkRoot: resolveFrameworkRootForProject(projectRoot, explicitFrameworkRoot),
                     force,
+                    keepLegacy,
                     error: "argument --project-root: expected one argument",
                 };
             }
@@ -34,6 +39,7 @@ export function parseArgs(argv) {
                     projectRoot,
                     frameworkRoot: resolveFrameworkRootForProject(projectRoot, explicitFrameworkRoot),
                     force,
+                    keepLegacy,
                     error: "argument --framework-root: expected one argument",
                 };
             }
@@ -48,12 +54,13 @@ export function parseArgs(argv) {
                 projectRoot,
                 frameworkRoot: resolveFrameworkRootForProject(projectRoot, explicitFrameworkRoot),
                 force,
+                keepLegacy,
                 error: `unrecognized argument: ${arg}`,
             };
         }
     }
     const frameworkRoot = resolveFrameworkRootForProject(projectRoot, explicitFrameworkRoot);
-    return { projectRoot, frameworkRoot, force };
+    return { projectRoot, frameworkRoot, force, keepLegacy };
 }
 export function run(argv) {
     const args = parseArgs(argv);
@@ -65,6 +72,7 @@ export function run(argv) {
         projectRoot: args.projectRoot,
         frameworkRoot: args.frameworkRoot,
         force: args.force,
+        keepLegacy: args.keepLegacy,
     }, {
         writeOut: (text) => {
             process.stdout.write(text);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deftai/directive",
-  "version": "0.68.0",
+  "version": "0.69.0",
   "description": "Directive CLI — npm install path for the Deft Directive framework.",
   "type": "module",
   "main": "./dist/index.js",
@@ -31,8 +31,8 @@
     "provenance": true
   },
   "dependencies": {
-    "@deftai/directive-core": "^0.68.0",
-    "@deftai/directive-content": "^0.68.0"
+    "@deftai/directive-core": "^0.69.0",
+    "@deftai/directive-content": "^0.69.0"
   },
   "scripts": {
     "build": "tsc -b"