@deftai/directive 0.56.2 → 0.57.0

package/dist/agents-refresh.d.ts

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+export interface AgentsRefreshArgs {
+    projectRoot: string;
+    check: boolean;
+    dryRun: boolean;
+    error?: string;
+}
+export declare function parseAgentsRefreshArgs(argv: readonly string[]): AgentsRefreshArgs;
+export declare function runAgentsRefresh(argv: readonly string[]): number;
+export declare function run(argv: readonly string[]): number;
+//# sourceMappingURL=agents-refresh.d.ts.map

package/dist/agents-refresh.js

@@ -0,0 +1,82 @@
+#!/usr/bin/env node
+/**
+ * agents:refresh — rewrite AGENTS.md managed section from the canonical template (#768 / #1996).
+ */
+import { writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { agentsRefreshPlan } from "@deftai/directive-core/platform";
+export function parseAgentsRefreshArgs(argv) {
+    let projectRoot = process.cwd();
+    let check = false;
+    let dryRun = false;
+    for (let i = 0; i < argv.length; i += 1) {
+        const arg = argv[i] ?? "";
+        if (arg === "--check") {
+            check = true;
+        }
+        else if (arg === "--dry-run") {
+            dryRun = true;
+        }
+        else if (arg === "--project-root") {
+            const next = argv[i + 1];
+            if (next === undefined) {
+                return { projectRoot, check, dryRun, error: "missing --project-root value" };
+            }
+            projectRoot = next;
+            i += 1;
+        }
+        else if (arg.startsWith("--project-root=")) {
+            projectRoot = arg.slice("--project-root=".length);
+        }
+        else {
+            return { projectRoot, check, dryRun, error: `unrecognized argument: ${arg}` };
+        }
+    }
+    return { projectRoot: resolve(projectRoot), check, dryRun };
+}
+export function runAgentsRefresh(argv) {
+    const args = parseAgentsRefreshArgs(argv);
+    if (args.error !== undefined) {
+        process.stderr.write(`agents:refresh: ${args.error}\n`);
+        return 2;
+    }
+    const plan = agentsRefreshPlan(args.projectRoot);
+    const state = String(plan.state ?? "unknown");
+    if (args.check) {
+        if (state === "current")
+            return 0;
+        process.stderr.write(`agents:refresh --check: AGENTS.md state is ${state}\n`);
+        return 1;
+    }
+    if (state === "current") {
+        process.stdout.write("AGENTS.md managed section is current — no changes.\n");
+        return 0;
+    }
+    if (state === "template-missing" || state === "template-malformed" || state === "unreadable") {
+        process.stderr.write(`agents:refresh failed: ${state}\n`);
+        return 2;
+    }
+    const newContent = plan.new_content;
+    if (typeof newContent !== "string") {
+        process.stderr.write("agents:refresh failed: plan produced no new_content\n");
+        return 2;
+    }
+    const path = String(plan.path ?? resolve(args.projectRoot, "AGENTS.md"));
+    if (args.dryRun) {
+        process.stdout.write(`[dry-run] would write ${path} (state=${state})\n`);
+        return 0;
+    }
+    writeFileSync(path, newContent, "utf8");
+    process.stdout.write(`AGENTS.md updated (state=${state}).\n`);
+    return 0;
+}
+export function run(argv) {
+    return runAgentsRefresh(argv);
+}
+/* v8 ignore start -- entry guard */
+if (process.argv[1] !== undefined && fileURLToPath(import.meta.url) === process.argv[1]) {
+    process.exit(run(process.argv.slice(2)));
+}
+/* v8 ignore stop */
+//# sourceMappingURL=agents-refresh.js.map

package/dist/cli-router/route-argv.js

@@ -126,6 +126,12 @@ function routeNamespaceVerb(ns, verb, rest) {
     if (resolveCanonicalVerb(colonKey) !== null) {
         return { kind: "dispatch", argv: [colonKey, ...rest] };
     }
+    if (ns === "framework" && verb === "doctor") {
+        return { kind: "dispatch", argv: ["doctor", ...rest] };
+    }
+    if (ns === "agents" && verb === "refresh") {
+        return { kind: "dispatch", argv: ["agents-refresh", ...rest] };
+    }
     if (ns === "scope") {
         if (SCOPE_LIFECYCLE_VERBS.has(verb)) {
             return { kind: "dispatch", argv: ["scope-lifecycle", verb, ...rest] };

package/dist/dispatch.d.ts

@@ -8,7 +8,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 ["cache", "check", "capacity-backfill", "capacity-show", "codebase-default-extractor", "codebase-map", "codebase-map-fresh", "codebase-projection-registry", "codebase-provider", "doctor", "parity", "policy", "pr-closing-keywords", "pr-merge-readiness", "pr-monitor", "pr-protected-issues", "pr-wait-mergeable", "preflight-cache", "preflight-gh", "probe-session", "release", "release-e2e", "release-publish", "release-rollback", "scope-lifecycle", "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-hooks-installed", "verify-investigation", "verify-judgment-gates", "verify-no-task-runtime", "validate-links", "validate-strategy-output", "verify-bridge-drift", "verify-capacity", "verify-content-manifest", "verify-go-freeze", "verify-scm-boundary", "verify-session-ritual", "verify-stubs", "rule-ownership-lint", "verify-story-ready", "verify-tools", "verify-wip-cap"];
+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", "parity", "policy", "pr-closing-keywords", "pr-merge-readiness", "pr-monitor", "pr-protected-issues", "pr-wait-mergeable", "preflight-cache", "preflight-gh", "probe-session", "release", "release-e2e", "release-publish", "release-rollback", "scope-lifecycle", "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-hooks-installed", "verify-investigation", "verify-judgment-gates", "verify-no-task-runtime", "validate-links", "validate-strategy-output", "verify-bridge-drift", "verify-capacity", "verify-content-manifest", "verify-go-freeze", "verify-scm-boundary", "verify-session-ritual", "verify-stubs", "rule-ownership-lint", "verify-story-ready", "verify-tools", "verify-wip-cap"];
 /** 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-readiness", "swarm-routing-verify", "swarm-routing-set", "swarm-verify-review-clean", "swarm-worktrees", "framework-commands", "pack-render", "packs-slice", "prd-render", "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", "scope-undo", "scope-demote", "scope-decompose", "changelog-resolve-unreleased", "architecture-preflight-sor"];
 /** Task-style aliases (framework_commands / Taskfile names). */

package/dist/dispatch.js

@@ -17,6 +17,7 @@ const HANDLER_KEYS = [
 ];
 /** CLI modules in packages/cli/src (excluding parity harnesses and bin/index). */
 export const CLI_MODULE_VERBS = [
+    "agents-refresh",
     "cache",
     "check",
     "capacity-backfill",
@@ -158,6 +159,7 @@ export const VERB_ALIASES = {
     "triage:scope": "triage-scope",
     "triage:accept": "triage-actions",
     "triage:status": "triage-actions",
+    "agents:refresh": "agents-refresh",
     "session:start": "framework-commands",
     "toolchain:check": "toolchain-check",
     "ts:check-lane": "ts-check-lane",

package/dist/doc-cli-parity.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Doc ↔ CLI parity gate (#1996).
+ *
+ * Extracts npm-canonical CLI invocations from UPGRADING.md and the AGENTS.md
+ * managed-section template, then asserts each resolves through the top-level
+ * router to a registered dispatcher verb (or an explicitly allowlisted legacy
+ * back-compat surface documented post-#1912).
+ */
+/** Documented legacy surfaces that remain in prose but are not npm-router verbs. */
+export declare const LEGACY_DOC_VERB_KEYS: Set<string>;
+export interface DocCliReference {
+    readonly source: string;
+    readonly raw: string;
+    readonly normalized: string;
+}
+export interface DocCliParityFailure {
+    readonly source: string;
+    readonly raw: string;
+    readonly reason: string;
+}
+/** Pull CLI command references from UPGRADING.md + agents-entry managed section. */
+export declare function extractDocCliReferences(repoRoot?: string): DocCliReference[];
+/** Strip flags/placeholders; return null when the literal is not a CLI verb invocation. */
+export declare function normalizeDocCommand(raw: string): string | null;
+/** Validate one normalized doc command against the router + registeredVerbs(). */
+export declare function validateDocCliCommand(normalized: string): string | null;
+/** Run the parity gate; returns failure rows (empty == pass). */
+export declare function collectDocCliParityFailures(repoRoot?: string): DocCliParityFailure[];
+//# sourceMappingURL=doc-cli-parity.d.ts.map

package/dist/doc-cli-parity.js

@@ -0,0 +1,159 @@
+/**
+ * Doc ↔ CLI parity gate (#1996).
+ *
+ * Extracts npm-canonical CLI invocations from UPGRADING.md and the AGENTS.md
+ * managed-section template, then asserts each resolves through the top-level
+ * router to a registered dispatcher verb (or an explicitly allowlisted legacy
+ * back-compat surface documented post-#1912).
+ */
+import { readFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { hasCommand } from "@deftai/directive-core/render";
+import { routeArgv } from "./cli-router/route-argv.js";
+import { registeredVerbs, resolveCanonicalVerb, VERB_ALIASES } from "./dispatch.js";
+/** Documented legacy surfaces that remain in prose but are not npm-router verbs. */
+export const LEGACY_DOC_VERB_KEYS = new Set(["setup", "upgrade", "relocate"]);
+const CLI_PREFIX_RE = /^(?:directive|deft|npx @deftai\/directive)\s+/;
+const BACKTICK_COMMAND_RE = /`((?:directive|deft|npx @deftai\/directive)\s+[^`]+)`/g;
+const TOP_LEVEL_UX = new Set(["init", "update", "migrate"]);
+function repoRootFromModule() {
+    return resolve(import.meta.dirname, "..", "..", "..");
+}
+function extractManagedSection(text) {
+    const open = text.indexOf("<!-- deft:managed-section");
+    if (open < 0)
+        return text;
+    const close = text.indexOf("<!-- /deft:managed-section -->", open);
+    if (close < 0)
+        return text.slice(open);
+    return text.slice(open, close);
+}
+/** Pull CLI command references from UPGRADING.md + agents-entry managed section. */
+export function extractDocCliReferences(repoRoot = repoRootFromModule()) {
+    const sources = [
+        ["content/UPGRADING.md", readFileSync(join(repoRoot, "content/UPGRADING.md"), "utf8")],
+        [
+            "content/templates/agents-entry.md",
+            extractManagedSection(readFileSync(join(repoRoot, "content/templates/agents-entry.md"), "utf8")),
+        ],
+    ];
+    const seen = new Set();
+    const out = [];
+    for (const [source, text] of sources) {
+        for (const match of text.matchAll(BACKTICK_COMMAND_RE)) {
+            const raw = match[1]?.trim() ?? "";
+            if (!CLI_PREFIX_RE.test(raw))
+                continue;
+            const normalized = normalizeDocCommand(raw);
+            if (normalized === null)
+                continue;
+            const key = `${source}\0${normalized}`;
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            out.push({ source, raw, normalized });
+        }
+    }
+    return out.sort((a, b) => a.source.localeCompare(b.source) || a.normalized.localeCompare(b.normalized));
+}
+function stripAnglePlaceholders(text) {
+    let out = text;
+    let start = out.indexOf("<");
+    while (start >= 0) {
+        const end = out.indexOf(">", start + 1);
+        if (end < 0)
+            break;
+        out = `${out.slice(0, start)}${out.slice(end + 1)}`;
+        start = out.indexOf("<");
+    }
+    return out.trim();
+}
+/** Strip flags/placeholders; return null when the literal is not a CLI verb invocation. */
+export function normalizeDocCommand(raw) {
+    let rest = raw.replace(CLI_PREFIX_RE, "").trim();
+    if (rest.length === 0)
+        return null;
+    const dd = rest.indexOf(" --");
+    if (dd >= 0)
+        rest = rest.slice(0, dd).trim();
+    rest = rest.replace(/\s+\[[^\]]*\]/g, "").trim();
+    rest = rest.replace(/\s+--[^\s]+(\s+[^\s]+)?/g, "").trim();
+    rest = stripAnglePlaceholders(rest);
+    if (rest.includes("/") || rest.includes(".md") || rest.includes("*"))
+        return null;
+    if (/^deft-install\b/.test(rest))
+        return null;
+    if (/^deft-directive\b/.test(rest))
+        return null;
+    if (/^deftai\b/.test(rest))
+        return null;
+    const first = rest.split(/\s+/)[0] ?? "";
+    if (!/^[\w:-]+$/.test(first))
+        return null;
+    if (first.includes(":")) {
+        return first;
+    }
+    return first;
+}
+function tokenizeDocVerb(normalized) {
+    if (normalized.includes(":")) {
+        const colon = normalized.indexOf(":");
+        return [normalized.slice(0, colon), normalized.slice(colon + 1)];
+    }
+    return [normalized];
+}
+function colonKeyFromNormalized(normalized) {
+    if (normalized.includes(":"))
+        return normalized;
+    return null;
+}
+function isRegisteredHandler(flatVerb) {
+    const verbs = new Set(registeredVerbs());
+    if (verbs.has(flatVerb))
+        return true;
+    const canon = resolveCanonicalVerb(flatVerb);
+    return canon !== null && verbs.has(canon);
+}
+/** Validate one normalized doc command against the router + registeredVerbs(). */
+export function validateDocCliCommand(normalized) {
+    const colonKey = colonKeyFromNormalized(normalized);
+    if (colonKey !== null) {
+        if (LEGACY_DOC_VERB_KEYS.has(colonKey)) {
+            return null;
+        }
+        if (colonKey in VERB_ALIASES || hasCommand(colonKey)) {
+            return null;
+        }
+    }
+    else if (LEGACY_DOC_VERB_KEYS.has(normalized)) {
+        return null;
+    }
+    const tokens = tokenizeDocVerb(normalized);
+    const routed = routeArgv(tokens);
+    if (routed.kind === "stub") {
+        return routed.stubMessage ?? "routes to stub handler";
+    }
+    const head = routed.argv[0];
+    if (head === undefined || head.length === 0) {
+        return "router produced empty argv";
+    }
+    if (TOP_LEVEL_UX.has(head)) {
+        return null;
+    }
+    if (isRegisteredHandler(head)) {
+        return null;
+    }
+    return `unregistered handler '${head}' (tokens=${JSON.stringify(tokens)}, routed=${JSON.stringify(routed.argv.slice(0, 3))})`;
+}
+/** Run the parity gate; returns failure rows (empty == pass). */
+export function collectDocCliParityFailures(repoRoot = repoRootFromModule()) {
+    const failures = [];
+    for (const ref of extractDocCliReferences(repoRoot)) {
+        const reason = validateDocCliCommand(ref.normalized);
+        if (reason !== null) {
+            failures.push({ source: ref.source, raw: ref.raw, reason });
+        }
+    }
+    return failures;
+}
+//# sourceMappingURL=doc-cli-parity.js.map

package/package.json

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