@deftai/directive 0.73.0 → 0.74.0

package/dist/dispatch.d.ts

@@ -15,6 +15,8 @@ export declare const CLI_MODULE_VERBS: readonly ["agents-refresh", "cache", "che
 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). */
 export declare const TRIAGE_ACTION_ALIAS_SUBCOMMANDS: Readonly<Record<string, string>>;
+/** Colon aliases for policy subcommands (mirrors cli-router SUBCOMMAND_ROUTES). */
+export declare const POLICY_ACTION_ALIAS_SUBCOMMANDS: Readonly<Record<string, string>>;
 /** Task-style aliases (framework_commands / Taskfile names). */
 export declare const VERB_ALIASES: Readonly<Record<string, string>>;
 /** Pinned ghx version (display only) — keep in lockstep with .github/workflows/ci.yml env.GHX_VERSION. */
@@ -148,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

@@ -9,7 +9,7 @@ import { homedir, tmpdir } from "node:os";
 import { basename, dirname, isAbsolute, join, relative, resolve } from "node:path";
 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 { appendAuditLog, disclosureLine, migrateLegacyPolicyKey, PLAN_POLICY_KEY, policyColonInvocation, policySetInvocation, 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";
 const HANDLER_KEYS = [
@@ -168,6 +168,14 @@ export const TRIAGE_ACTION_ALIAS_SUBCOMMANDS = {
     "triage:history": "history",
 };
 const TRIAGE_ACTION_COLON_ALIASES = Object.fromEntries(Object.keys(TRIAGE_ACTION_ALIAS_SUBCOMMANDS).map((alias) => [alias, "triage-actions"]));
+/** Colon aliases for policy subcommands (mirrors cli-router SUBCOMMAND_ROUTES). */
+export const POLICY_ACTION_ALIAS_SUBCOMMANDS = {
+    "policy:show": "show",
+    "policy:enforce-branches": "enforce-branches",
+    "policy:allow-direct-commits": "allow-direct-commits",
+    "policy:enable-value-feedback": "enable-value-feedback",
+};
+const POLICY_ACTION_COLON_ALIASES = Object.fromEntries(Object.keys(POLICY_ACTION_ALIAS_SUBCOMMANDS).map((alias) => [alias, "policy"]));
 /** Task-style aliases (framework_commands / Taskfile names). */
 export const VERB_ALIASES = {
     "verify:encoding": "verify-encoding",
@@ -211,6 +219,7 @@ export const VERB_ALIASES = {
     "triage:queue": "triage-queue",
     "triage:scope": "triage-scope",
     ...TRIAGE_ACTION_COLON_ALIASES,
+    ...POLICY_ACTION_COLON_ALIASES,
     "agents:refresh": "agents-refresh",
     "migrate:preflight": "migrate-preflight",
     "migrate:xbrief": "migrate-xbrief",
@@ -1747,7 +1756,9 @@ const POLICY_CAPABILITY_COST_DISCLOSURE = "\u26a0 Capability-cost disclosure --
     "  \u2022 verify:branch will pass on the default branch.\n" +
     "  \u2022 The CI sanity check (head_ref != base_ref) is still independent and " +
     "will continue to flag master->master PRs.\n" +
-    "  \u2022 This change is reversible: run `task policy:enforce-branches` to " +
+    "  \u2022 This change is reversible: run `" +
+    policyColonInvocation("enforce-branches") +
+    "` to " +
     "re-enable the gate.\n" +
     "  \u2022 The change is recorded to meta/policy-changes.log for auditability.";
 const POLICY_WIP_CAP_DISCLOSURE = "\u26a0 Capability-cost disclosure -- changing plan.policy.wipCap " +
@@ -1802,15 +1813,15 @@ function sanitizeNote(note) {
 function defaultPolicySetActor(cmd) {
     switch (cmd) {
         case "enforce-branches":
-            return "task policy:enforce-branches";
+            return policyColonInvocation("enforce-branches");
         case "allow-direct-commits":
-            return "task policy:allow-direct-commits";
+            return policyColonInvocation("allow-direct-commits");
         case "wip-cap":
-            return "task policy:wip-cap";
+            return policySetInvocation("wip-cap");
         case "subagent-backend":
-            return "task policy:subagent-backend";
+            return policySetInvocation("subagent-backend");
         case "subagent-backends":
-            return "task policy:subagent-backends";
+            return policySetInvocation("subagent-backends");
     }
 }
 /** Mirror Python `Path(...).expanduser()` for a leading `~` / `~/` segment. */
@@ -2027,7 +2038,7 @@ function applyBranchPolicy(args, io) {
         if (!args.confirm) {
             io.writeOut(`${POLICY_CAPABILITY_COST_DISCLOSURE}\n`);
             io.writeOut("\n");
-            io.writeOut("Re-run with --confirm to apply: task policy:allow-direct-commits -- --confirm\n");
+            io.writeOut(`Re-run with --confirm to apply: ${policyColonInvocation("allow-direct-commits", " -- --confirm")}\n`);
             return 1;
         }
         target = true;
@@ -2071,7 +2082,7 @@ function applyWipCap(args, io) {
     if (!args.confirm) {
         io.writeOut(`${POLICY_WIP_CAP_DISCLOSURE}\n`);
         io.writeOut("\n");
-        io.writeOut(`Re-run with --confirm to apply: task policy:wip-cap -- --set ${cap} --confirm\n`);
+        io.writeOut(`Re-run with --confirm to apply: ${policySetInvocation("wip-cap", ` -- --set ${cap} --confirm`)}\n`);
         return 1;
     }
     let res;
@@ -2346,32 +2357,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",
+];
 /**
- * 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 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 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);
@@ -2393,6 +2498,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`);
@@ -2401,11 +2510,14 @@ export async function dispatch(argv, io = defaultIo()) {
     try {
         const handler = await loadHandler(canonical, io);
         const triageSubcommand = verb !== undefined ? TRIAGE_ACTION_ALIAS_SUBCOMMANDS[verb] : undefined;
+        const policySubcommand = verb !== undefined ? POLICY_ACTION_ALIAS_SUBCOMMANDS[verb] : undefined;
         const handlerArgv = canonical === "framework-commands" && verb !== undefined && verb !== canonical
             ? [verb, ...rest]
             : triageSubcommand !== undefined && canonical === "triage-actions"
                 ? [triageSubcommand, ...rest]
-                : rest;
+                : policySubcommand !== undefined && canonical === "policy"
+                    ? [policySubcommand, ...rest]
+                    : rest;
         return await invokeHandler(handler, handlerArgv);
     }
     catch (err) {

package/dist/policy.js

@@ -6,7 +6,7 @@
 import { existsSync } from "node:fs";
 import { resolve as pathResolve, relative } from "node:path";
 import { fileURLToPath } from "node:url";
-import { describeShadowedPlanExtension, detectShadowedPlanExtensions, disclosureLine, enableValueFeedback, FIELD_VALUE_FEEDBACK, FIELD_VALUE_FEEDBACK_CLI_ALIAS, formatValueFeedbackStatusLine, inspectAllPolicies, inspectOnePolicy, loadProjectDefinition, projectDefinitionPath, pythonListRepr, pythonStringRepr, registeredPolicyNames, renderJson, renderText, resolvePolicy, resolveValueFeedback, setPolicy, } from "@deftai/directive-core/policy";
+import { describeShadowedPlanExtension, detectShadowedPlanExtensions, disclosureLine, enableValueFeedback, FIELD_VALUE_FEEDBACK, FIELD_VALUE_FEEDBACK_CLI_ALIAS, formatValueFeedbackStatusLine, inspectAllPolicies, inspectOnePolicy, loadProjectDefinition, policyColonInvocation, projectDefinitionPath, pythonListRepr, pythonStringRepr, registeredPolicyNames, renderJson, renderText, resolvePolicy, resolveValueFeedback, setPolicy, } from "@deftai/directive-core/policy";
 const CAPABILITY_COST_DISCLOSURE = "\u26a0 Capability-cost disclosure -- enabling direct commits to the default " +
     "branch turns OFF the deft branch-protection policy.\n" +
     "  \u2022 Pre-commit + pre-push hooks will no longer block default-branch " +
@@ -14,7 +14,9 @@ const CAPABILITY_COST_DISCLOSURE = "\u26a0 Capability-cost disclosure -- enablin
     "  \u2022 verify:branch will pass on the default branch.\n" +
     "  \u2022 The CI sanity check (head_ref != base_ref) is still independent and " +
     "will continue to flag master->master PRs.\n" +
-    "  \u2022 This change is reversible: run `task policy:enforce-branches` to " +
+    "  \u2022 This change is reversible: run `" +
+    policyColonInvocation("enforce-branches") +
+    "` to " +
     "re-enable the gate.\n" +
     "  \u2022 The change is recorded to meta/policy-changes.log for auditability.";
 function makeSetError(message) {
@@ -121,7 +123,7 @@ export function parseArgs(argv) {
         return {
             cmd: "show",
             confirm: false,
-            actor: "task policy:show",
+            actor: policyColonInvocation("show"),
             note: "",
             projectRoot: show.projectRoot,
             format: show.format,
@@ -149,10 +151,10 @@ export function parseArgs(argv) {
         cmd === "enable-value-feedback") {
         let confirm = false;
         let actor = cmd === "enforce-branches"
-            ? "task policy:enforce-branches"
+            ? policyColonInvocation("enforce-branches")
             : cmd === "allow-direct-commits"
-                ? "task policy:allow-direct-commits"
-                : "task policy:enable-value-feedback";
+                ? policyColonInvocation("allow-direct-commits")
+                : policyColonInvocation("enable-value-feedback");
         let note = "";
         let projectRoot = ".";
         for (let i = 1; i < argv.length; i += 1) {
@@ -291,7 +293,7 @@ function runSet(args) {
     const projectRoot = pathResolve(args.projectRoot);
     if (args.cmd === "allow-direct-commits" && !args.confirm) {
         process.stdout.write(`${CAPABILITY_COST_DISCLOSURE}\n\n`);
-        process.stdout.write("Re-run with --confirm to apply: task policy:allow-direct-commits -- --confirm\n");
+        process.stdout.write(`Re-run with --confirm to apply: ${policyColonInvocation("allow-direct-commits", " -- --confirm")}\n`);
         return 1;
     }
     const target = args.cmd === "allow-direct-commits";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deftai/directive",
-  "version": "0.73.0",
+  "version": "0.74.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.0",
-    "@deftai/directive-content": "^0.73.0"
+    "@deftai/directive-core": "^0.74.0",
+    "@deftai/directive-content": "^0.74.0"
   },
   "scripts": {
     "build": "tsc -b"