@deftai/directive 0.73.1 → 0.75.0

package/dist/dispatch.d.ts

@@ -10,7 +10,7 @@ export interface DispatchIo {
     writeErr: (text: string) => void;
 }
 /** CLI modules in packages/cli/src (excluding parity harnesses and bin/index). */
-export declare const CLI_MODULE_VERBS: readonly ["agents-refresh", "cache", "check", "capacity-backfill", "capacity-show", "codebase-default-extractor", "codebase-map", "codebase-map-fresh", "codebase-projection-registry", "codebase-provider", "doctor", "install-upgrade", "install-uninstall", "migrate-preflight", "migrate-xbrief", "migrate-category-b", "framework-check-updates", "umbrella-current-shape", "changelog-check", "change-init", "commit-lint", "policy", "pr-closing-keywords", "pr-merge-readiness", "pr-monitor", "pr-protected-issues", "pr-wait-mergeable", "pr-watch", "preflight-cache", "preflight-gh", "probe-session", "release", "release-e2e", "release-publish", "release-rollback", "scope-lifecycle", "session-start", "slice", "subagent-monitor", "toolchain-check", "triage-actions", "triage-bootstrap", "triage-bulk", "triage-classify", "triage-help", "triage-queue", "triage-reconcile", "triage-refresh", "triage-scope", "triage-scope-drift", "triage-smoketest", "triage-subscribe", "triage-summary", "triage-welcome", "ts-check-lane", "vbrief-activate", "vbrief-build", "vbrief-preflight", "vbrief-reconcile", "vbrief-validate", "vbrief-validation", "verify-branch", "verify-encoding", "verify-forward-coverage", "verify-hooks-installed", "verify-investigation", "verify-judgment-gates", "verify-no-task-runtime", "validate-links", "validate-strategy-output", "verify-biome-config", "verify-bridge-drift", "verify-capacity", "verify-content-manifest", "verify-contract-drift", "verify-cursor-tier1", "verify-go-freeze", "verify-scm-boundary", "verify-session-ritual", "verify-stubs", "verify-xbrief-drift", "rule-ownership-lint", "verify-story-ready", "verify-tools", "verify-wip-cap", "verify-agents-md-budget", "verify-agents-md-advisory", "eval-health", "eval-run", "eval-report"];
+export declare const CLI_MODULE_VERBS: readonly ["agents-refresh", "cache", "check", "capacity-backfill", "capacity-show", "codebase-default-extractor", "codebase-map", "codebase-map-fresh", "codebase-projection-registry", "codebase-provider", "doctor", "install-upgrade", "install-uninstall", "migrate-preflight", "migrate-xbrief", "migrate-category-b", "framework-check-updates", "umbrella-current-shape", "changelog-check", "change-init", "commit-lint", "policy", "pr-closing-keywords", "pr-merge-readiness", "pr-monitor", "pr-protected-issues", "pr-wait-mergeable", "pr-watch", "preflight-cache", "preflight-gh", "probe-session", "release", "release-e2e", "release-publish", "release-rollback", "scope-lifecycle", "session-start", "slice", "subagent-monitor", "toolchain-check", "triage-actions", "triage-bootstrap", "triage-bulk", "triage-classify", "triage-help", "triage-queue", "triage-reconcile", "triage-refresh", "triage-scope", "triage-scope-drift", "triage-smoketest", "triage-subscribe", "triage-summary", "triage-welcome", "ts-check-lane", "vbrief-activate", "vbrief-build", "vbrief-preflight", "vbrief-reconcile", "vbrief-validate", "vbrief-validation", "verify-branch", "verify-encoding", "verify-forward-coverage", "verify-hooks-installed", "verify-investigation", "verify-judgment-gates", "verify-no-task-runtime", "validate-links", "validate-strategy-output", "verify-biome-config", "verify-bridge-drift", "verify-capacity", "verify-content-manifest", "verify-contract-drift", "verify-cursor-tier1", "verify-go-freeze", "verify-scm-boundary", "verify-session-ritual", "verify-stubs", "verify-xbrief-drift", "rule-ownership-lint", "verify-story-ready", "verify-tools", "verify-wip-cap", "verify-agents-md-budget", "verify-agents-md-advisory", "verify-eval-health-relocation", "eval-health", "eval-run", "eval-report"];
 /** Core-only CLI entrypoints without a packages/cli wrapper. */
 export declare const CORE_MODULE_VERBS: readonly ["scm", "github-auth-modes", "github-body", "issue-emit", "issue-ingest", "reconcile-issues", "swarm-launch", "swarm-complete-cohort", "swarm-finalize-cohort", "swarm-readiness", "swarm-routing-verify", "swarm-routing-set", "swarm-verify-review-clean", "swarm-worktrees", "framework-commands", "pack-render", "packs-slice", "prd-render", "export-spec", "project-render", "roadmap-render", "spec-render", "spec-validate", "code-structure-validate", "pack-migrate-skills", "pack-migrate-rules", "pack-migrate-strategies", "pack-migrate-patterns", "pack-migrate-swarm-spec", "policy-set", "setup-ghx", "scope-undo", "scope-demote", "scope-decompose", "changelog-resolve-unreleased", "architecture-preflight-sor", "feedback-file", "value-readback"];
 /** Colon aliases for triage-actions (mirrors cli-router SUBCOMMAND_ROUTES). */
@@ -150,9 +150,21 @@ 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. 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).
+ * Deduplicated command names for `directive commands`, preferring colon-style
+ * task verbs over dash-style canonical stems when both exist (#2172).
+ */
+export declare function preferredCommandNames(): readonly string[];
+/** Major.minor label for the curated help title (#2172). */
+export declare function helpVersionLabel(): string;
+/**
+ * Print the exhaustive registered-command list for `directive commands` (#2172).
+ * Lists deduplicated preferred names (colon-style when available).
+ */
+export declare function printCommandsList(io?: DispatchIo): void;
+/**
+ * Print curated top-level help: title/version, usage, common options, grouped
+ * common commands, and a pointer to `directive commands` for the full list
+ * (#2172). Preserves the init/update/doctor first-run guidance from #2273.
  */
 export declare function printHelp(io?: DispatchIo): void;
 /** Dispatch argv to a registered verb; returns the handler exit code. */

package/dist/dispatch.js

@@ -111,6 +111,7 @@ export const CLI_MODULE_VERBS = [
     "verify-wip-cap",
     "verify-agents-md-budget",
     "verify-agents-md-advisory",
+    "verify-eval-health-relocation",
     "eval-health",
     "eval-run",
     "eval-report",
@@ -185,6 +186,7 @@ export const VERB_ALIASES = {
     "verify:wip-cap": "verify-wip-cap",
     "verify:agents-md-budget": "verify-agents-md-budget",
     "verify:agents-md-advisory": "verify-agents-md-advisory",
+    "verify:eval-health-relocation": "verify-eval-health-relocation",
     "verify:hooks-installed": "verify-hooks-installed",
     "verify:no-task-runtime": "verify-no-task-runtime",
     "vbrief:validate": "vbrief-validate",
@@ -2357,32 +2359,126 @@ export function registeredVerbs() {
     ]);
     return [...names].sort();
 }
+/** Top-level UX commands routed before the flat dispatcher (#1670). */
+const TOP_LEVEL_COMMAND_NAMES = [
+    "init",
+    "update",
+    "migrate",
+    "bootstrap",
+    "doctor",
+    "check",
+];
+/** Scope lifecycle verbs exposed as scope:<verb> in help (#2172). */
+const SCOPE_COMMAND_NAMES = [
+    "scope:promote",
+    "scope:activate",
+    "scope:complete",
+    "scope:demote",
+    "scope:undo",
+];
+/**
+ * Deduplicated command names for `directive commands`, preferring colon-style
+ * task verbs over dash-style canonical stems when both exist (#2172).
+ */
+export function preferredCommandNames() {
+    const aliasKeys = Object.keys(VERB_ALIASES);
+    const aliasedCanonicals = new Set(Object.values(VERB_ALIASES));
+    const unaliasedCanonicals = [...CLI_MODULE_VERBS, ...CORE_MODULE_VERBS].filter((verb) => !aliasedCanonicals.has(verb));
+    return [
+        ...new Set([
+            ...TOP_LEVEL_COMMAND_NAMES,
+            ...SCOPE_COMMAND_NAMES,
+            ...aliasKeys,
+            ...unaliasedCanonicals,
+        ]),
+    ].sort();
+}
+/** Major.minor label for the curated help title (#2172). */
+export function helpVersionLabel() {
+    const version = engineInfo().version;
+    const match = /^(\d+\.\d+)/.exec(version);
+    return match ? `v${match[1]}` : `v${version}`;
+}
+const CURATED_HELP_GROUPS = [
+    {
+        title: "Getting started",
+        commands: [
+            { name: "init", summary: "Set up Directive in the current project (first-time setup)" },
+            { name: "update", summary: "Refresh an existing install and self-heal the engine" },
+            { name: "doctor", summary: "Diagnose the install and print the one next step" },
+        ],
+    },
+    {
+        title: "Session & ritual",
+        commands: [{ name: "session:start", summary: "Record session-start ritual state" }],
+    },
+    {
+        title: "Quality & gates",
+        commands: [{ name: "check", summary: "Run install and lifecycle quality gates" }],
+    },
+    {
+        title: "Work queue & triage",
+        commands: [
+            { name: "triage:welcome", summary: "Session orientation and triage one-liner" },
+            { name: "triage:queue", summary: "Ranked work queue for what to do next" },
+        ],
+    },
+    {
+        title: "Scope lifecycle",
+        commands: [{ name: "scope:promote", summary: "Promote a scope xBRIEF to pending" }],
+    },
+    {
+        title: "Project artifacts",
+        commands: [
+            { name: "project:render", summary: "Render PROJECT-DEFINITION projection" },
+            { name: "spec:render", summary: "Render specification projection" },
+        ],
+    },
+];
+function formatHelpCommand(command) {
+    const padding = " ".repeat(Math.max(1, 22 - command.name.length));
+    return `  ${command.name}${padding}${command.summary}\n`;
+}
+/**
+ * Print the exhaustive registered-command list for `directive commands` (#2172).
+ * Lists deduplicated preferred names (colon-style when available).
+ */
+export function printCommandsList(io = defaultIo()) {
+    io.writeOut("Registered commands:\n");
+    for (const name of preferredCommandNames()) {
+        io.writeOut(`  ${name}\n`);
+    }
+}
 /**
- * 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).
+ * Print curated top-level help: title/version, usage, common options, grouped
+ * common commands, and a pointer to `directive commands` for the full list
+ * (#2172). Preserves the init/update/doctor first-run guidance from #2273.
  */
 export function printHelp(io = defaultIo()) {
-    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" +
+    io.writeOut(`Directive ${helpVersionLabel()}\n`);
+    io.writeOut("AI development framework CLI for project lifecycle, scope, and quality gates.\n\n");
+    io.writeOut("Usage:\n");
+    io.writeOut("  directive <command> [options]\n");
+    io.writeOut("  directive help\n");
+    io.writeOut("  directive commands          List every registered command\n\n");
+    io.writeOut("Options:\n");
+    io.writeOut("  -h, --help                  Show this help\n");
+    io.writeOut("  -V, --version               Print version information\n\n");
+    for (const group of CURATED_HELP_GROUPS) {
+        io.writeOut(`${group.title}:\n`);
+        for (const command of group.commands) {
+            io.writeOut(formatHelpCommand(command));
+        }
+        io.writeOut("\n");
+    }
+    io.writeOut("Commands use colon style (e.g. triage:queue); dash-style aliases remain supported.\n" +
+        "Run `directive commands` for the full registered-command list.\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`);
-    }
+        "New clone where `directive` will not run? Read the Cold-start bootstrap block at the top of README.md.\n");
 }
 async function invokeHandler(handler, argv) {
     const code = await handler(argv);
@@ -2404,6 +2500,10 @@ export async function dispatch(argv, io = defaultIo()) {
         return 0;
     }
     const [verb, ...rest] = argv;
+    if (verb === "commands") {
+        printCommandsList(io);
+        return 0;
+    }
     const canonical = resolveCanonicalVerb(verb ?? "");
     if (canonical === null) {
         io.writeErr(`directive: unknown verb '${verb}'\n`);

package/dist/verify-agents-md-budget.js

@@ -47,6 +47,22 @@ export function run(argv) {
             process.stderr.write(`${result.message}\n`);
         }
     }
+    if (result.northStarMessage !== undefined && result.northStarMessage.length > 0) {
+        if (result.northStarStream === "stdout") {
+            process.stdout.write(`${result.northStarMessage}\n`);
+        }
+        else if (result.northStarStream === "stderr") {
+            process.stderr.write(`${result.northStarMessage}\n`);
+        }
+    }
+    else if (result.advisoryMessage !== undefined && result.advisoryMessage.length > 0) {
+        if (result.advisoryStream === "stdout") {
+            process.stdout.write(`${result.advisoryMessage}\n`);
+        }
+        else if (result.advisoryStream === "stderr") {
+            process.stderr.write(`${result.advisoryMessage}\n`);
+        }
+    }
     return result.code;
 }
 if (process.argv[1] !== undefined && fileURLToPath(import.meta.url) === process.argv[1]) {

package/dist/verify-eval-health-relocation.d.ts

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+interface ParsedArgs {
+    projectRoot: string;
+    baseRef?: string;
+    staged: boolean;
+    quiet: boolean;
+    seedBaseline: boolean;
+    paths: string[];
+    error?: string;
+}
+/** Parse verify-eval-health-relocation CLI args. */
+export declare function parseArgs(argv: string[]): ParsedArgs;
+/** Run the gate and return the process exit code. */
+export declare function run(argv: string[]): number;
+export {};
+//# sourceMappingURL=verify-eval-health-relocation.d.ts.map

package/dist/verify-eval-health-relocation.js

@@ -0,0 +1,93 @@
+#!/usr/bin/env node
+import { resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { evaluate } from "@deftai/directive-core/eval-health-relocation";
+/** Parse verify-eval-health-relocation CLI args. */
+export function parseArgs(argv) {
+    const parsed = {
+        projectRoot: ".",
+        staged: false,
+        quiet: false,
+        seedBaseline: false,
+        paths: [],
+    };
+    for (let i = 0; i < argv.length; i += 1) {
+        const arg = argv[i];
+        if (arg === "--quiet") {
+            parsed.quiet = true;
+        }
+        else if (arg === "--staged") {
+            parsed.staged = true;
+        }
+        else if (arg === "--seed-baseline") {
+            parsed.seedBaseline = true;
+        }
+        else if (arg === "--project-root") {
+            const value = argv[i + 1];
+            if (value === undefined) {
+                return { ...parsed, error: "argument --project-root: expected one argument" };
+            }
+            parsed.projectRoot = value;
+            i += 1;
+        }
+        else if (arg?.startsWith("--project-root=")) {
+            parsed.projectRoot = arg.slice("--project-root=".length);
+        }
+        else if (arg === "--base-ref") {
+            const value = argv[i + 1];
+            if (value === undefined) {
+                return { ...parsed, error: "argument --base-ref: expected one argument" };
+            }
+            parsed.baseRef = value;
+            i += 1;
+        }
+        else if (arg?.startsWith("--base-ref=")) {
+            parsed.baseRef = arg.slice("--base-ref=".length);
+        }
+        else if (arg === "--path") {
+            const value = argv[i + 1];
+            if (value === undefined) {
+                return { ...parsed, error: "argument --path: expected one argument" };
+            }
+            parsed.paths.push(value);
+            i += 1;
+        }
+        else if (arg?.startsWith("--path=")) {
+            parsed.paths.push(arg.slice("--path=".length));
+        }
+        else {
+            return { ...parsed, error: `unrecognized argument: ${arg}` };
+        }
+    }
+    return parsed;
+}
+/** Run the gate and return the process exit code. */
+export function run(argv) {
+    const args = parseArgs(argv);
+    if (args.error !== undefined) {
+        process.stderr.write(`verify_eval_health_relocation: ${args.error}\n`);
+        return 2;
+    }
+    const projectRoot = resolve(args.projectRoot);
+    const result = evaluate({
+        projectRoot,
+        baseRef: args.baseRef,
+        staged: args.staged,
+        quiet: args.quiet,
+        seedBaseline: args.seedBaseline,
+        paths: args.paths.length > 0 ? args.paths : undefined,
+    });
+    if (result.message.length > 0) {
+        if (result.stream === "stdout") {
+            process.stdout.write(`${result.message}\n`);
+        }
+        else if (result.stream === "stderr") {
+            process.stderr.write(`${result.message}\n`);
+        }
+    }
+    return result.code;
+}
+if (process.argv[1] !== undefined && fileURLToPath(import.meta.url) === process.argv[1]) {
+    process.exit(run(process.argv.slice(2)));
+}
+//# sourceMappingURL=verify-eval-health-relocation.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deftai/directive",
-  "version": "0.73.1",
+  "version": "0.75.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.73.1",
-    "@deftai/directive-content": "^0.73.1"
+    "@deftai/directive-core": "^0.75.0",
+    "@deftai/directive-content": "^0.75.0"
   },
   "scripts": {
     "build": "tsc -b"