@deftai/directive 0.66.2 → 0.68.0

package/dist/install-upgrade.js

@@ -1,84 +1,86 @@
 #!/usr/bin/env node
-import { resolve } from "node:path";
 import { fileURLToPath } from "node:url";
-import { runInstallUpgrade } from "@deftai/directive-core/install-upgrade";
-export function parseArgs(argv) {
-    let projectRoot = ".";
-    let frameworkRoot = resolve(import.meta.dirname, "..", "..", "..");
-    let migrate = false;
-    let force = false;
+import { runUpdate } from "./init-cli/update.js";
+/**
+ * #2064: `deft install-upgrade` is now a thin redirect onto the SAME code path
+ * as `directive update` (`runRefreshDeposit`). The two verbs previously had
+ * overlapping-but-divergent semantics: `directive update` file-swaps the
+ * vendored `.deft/core` payload, rewrites the install manifest (#2056), and
+ * regenerates the `.deft-version` marker (#2055), whereas the old
+ * `install-upgrade` only wrote the marker/manifest and refreshed AGENTS.md
+ * WITHOUT swapping the payload -- so on a stale deposit it reported a confident
+ * false no-op ("Project already at X. Nothing to do.") that steered operators
+ * away from the command that actually works. Consolidating to one path removes
+ * that hazard and gives consumers a single upgrade mental model:
+ *   npm i -g @deftai/directive@latest -> deft update -> deft migrate -> deft doctor
+ *
+ * The legacy `.deft/VERSION` cleanup that only `install-upgrade` used to perform
+ * is folded into the shared `runRefreshDeposit` path (see
+ * `migrateLegacyInstallManifest` in init-deposit/refresh.ts) so no manifest
+ * behavior is dropped. Layout migration (the old `--migrate` flag) is the
+ * separate `deft migrate` step in the canonical flow above.
+ */
+/** One-line notice emitted on the redirect so operators learn the canonical verb. */
+export const REDIRECT_NOTICE = "install-upgrade: delegating to `directive update` -- the single canonical " +
+    "upgrade verb (run `deft update` directly; use `deft migrate` for layout " +
+    "migration). Refs #2064.\n";
+/**
+ * Translate the historical `install-upgrade` flag surface onto the
+ * `directive update` argv. `--project-root <p>` maps to `--repo-root <p>`;
+ * `--framework-root` is dropped (update resolves its own content root) and the
+ * legacy `--migrate` / `--force` flags are dropped (layout migration is now the
+ * separate `deft migrate` step). Any other argv passes through unchanged.
+ */
+export function translateArgs(argv) {
+    const out = [];
     for (let i = 0; i < argv.length; i += 1) {
         const arg = argv[i] ?? "";
-        if (arg === "--migrate") {
-            migrate = true;
-        }
-        else if (arg === "--force") {
-            force = true;
-        }
-        else if (arg === "--project-root") {
+        if (arg === "--project-root") {
+            out.push("--repo-root");
             const value = argv[i + 1];
-            if (value === undefined) {
-                return {
-                    projectRoot,
-                    frameworkRoot,
-                    migrate,
-                    force,
-                    error: "argument --project-root: expected one argument",
-                };
+            if (value !== undefined) {
+                out.push(value);
+                i += 1;
             }
-            projectRoot = value;
-            i += 1;
         }
         else if (arg.startsWith("--project-root=")) {
-            projectRoot = arg.slice("--project-root=".length);
+            out.push(`--repo-root=${arg.slice("--project-root=".length)}`);
         }
         else if (arg === "--framework-root") {
-            const value = argv[i + 1];
-            if (value === undefined) {
-                return {
-                    projectRoot,
-                    frameworkRoot,
-                    migrate,
-                    force,
-                    error: "argument --framework-root: expected one argument",
-                };
-            }
-            frameworkRoot = value;
-            i += 1;
+            i += 1; // drop the flag and its value
         }
-        else if (arg.startsWith("--framework-root=")) {
-            frameworkRoot = arg.slice("--framework-root=".length);
+        else if (arg.startsWith("--framework-root=") || arg === "--migrate" || arg === "--force") {
+            // Intentionally dropped: update resolves its own content root, and layout
+            // migration is the separate `deft migrate` step in the canonical flow.
         }
         else {
-            return { projectRoot, frameworkRoot, migrate, force, error: `unrecognized argument: ${arg}` };
+            out.push(arg);
         }
     }
-    if (process.env.DEFT_ROOT && process.env.DEFT_ROOT.length > 0) {
-        frameworkRoot = process.env.DEFT_ROOT;
-    }
-    return { projectRoot, frameworkRoot, migrate, force };
+    return out;
 }
-export function run(argv) {
-    const args = parseArgs(argv);
-    if (args.error !== undefined) {
-        process.stderr.write(`install-upgrade: ${args.error}\n`);
-        return 2;
-    }
-    return runInstallUpgrade({
-        projectRoot: args.projectRoot,
-        frameworkRoot: args.frameworkRoot,
-        migrate: args.migrate,
-        force: args.force,
-    }, {
+function defaultIo() {
+    return {
         writeOut: (text) => {
             process.stdout.write(text);
         },
         writeErr: (text) => {
             process.stderr.write(text);
         },
-    });
+    };
+}
+/**
+ * Redirect handler: emit the one-line notice, then delegate to the identical
+ * code path `directive update` uses so deposit state + stdout are identical.
+ */
+export async function run(argv, io = defaultIo(), deps = {}) {
+    const update = deps.runUpdate ?? runUpdate;
+    io.writeErr(REDIRECT_NOTICE);
+    return update(translateArgs(argv), io);
 }
 if (process.argv[1] !== undefined && fileURLToPath(import.meta.url) === process.argv[1]) {
-    process.exit(run(process.argv.slice(2)));
+    run(process.argv.slice(2)).then((code) => {
+        process.exit(code);
+    });
 }
 //# sourceMappingURL=install-upgrade.js.map

package/dist/pr-watch.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export declare function run(argv: string[]): number;
+//# sourceMappingURL=pr-watch.d.ts.map

package/dist/pr-watch.js

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+import { fileURLToPath } from "node:url";
+import { cmdPrWatch } from "@deftai/directive-core/dist/pr-watch/main.js";
+export function run(argv) {
+    return cmdPrWatch(argv);
+}
+if (process.argv[1] !== undefined && fileURLToPath(import.meta.url) === process.argv[1]) {
+    process.exit(run(process.argv.slice(2)));
+}
+//# sourceMappingURL=pr-watch.js.map

package/dist/toolchain-check.d.ts

@@ -1,3 +1,7 @@
 #!/usr/bin/env node
-export declare function run(argv?: readonly string[]): number;
+import { type CommandRunner } from "@deftai/directive-core/verify-env";
+export interface ToolchainCheckRunOptions {
+    readonly runner?: CommandRunner;
+}
+export declare function run(argv?: readonly string[], options?: ToolchainCheckRunOptions): number;
 //# sourceMappingURL=toolchain-check.d.ts.map

package/dist/toolchain-check.js

@@ -1,9 +1,9 @@
 #!/usr/bin/env node
 import { fileURLToPath } from "node:url";
 import { runToolchainCheck } from "@deftai/directive-core/verify-env";
-export function run(argv = process.argv.slice(2)) {
+export function run(argv = process.argv.slice(2), options = {}) {
     const consumer = argv.includes("--consumer");
-    const result = runToolchainCheck(undefined, { consumer });
+    const result = runToolchainCheck(options.runner, { consumer });
     for (const line of result.lines) {
         process.stdout.write(`${line}\n`);
     }

package/dist/triage-queue.d.ts

@@ -1,9 +1,11 @@
 #!/usr/bin/env node
+import { type LiveOpenIssuesReader } from "@deftai/directive-core/dist/triage/queue/index.js";
 interface ParsedArgs {
     projectRoot: string;
     repo: string | null;
     limit: number;
     includeBlocked: boolean;
+    reconcile: boolean;
     cacheRoot: string | null;
     auditLog: string | null;
     slicesLog: string | null;
@@ -11,7 +13,11 @@ interface ParsedArgs {
 }
 /** Parse triage-queue CLI args for the queue subcommand. */
 export declare function parseArgs(argv: string[]): ParsedArgs;
+/** Optional injection seam for `run` (tests supply a stub live-open reader). */
+export interface RunOptions {
+    readonly liveOpenReader?: LiveOpenIssuesReader;
+}
 /** Run triage:queue and return process exit code. */
-export declare function run(argv: string[]): number;
+export declare function run(argv: string[], options?: RunOptions): number;
 export {};
 //# sourceMappingURL=triage-queue.d.ts.map

package/dist/triage-queue.js

@@ -1,7 +1,8 @@
 #!/usr/bin/env node
-import { dirname, resolve } from "node:path";
+import { resolve } from "node:path";
 import { fileURLToPath } from "node:url";
-import { activeReferencedIssueNumbers, buildQueue, collectOrphanIssueNumbers, DEFAULT_QUEUE_LIMIT, loadCachedIssues, loadSliceRecords, readAuditEntries, renderQueue, resolveRankingLabels, resolveRepo, } from "@deftai/directive-core/dist/triage/queue/index.js";
+import { resolveEvalPath } from "@deftai/directive-core/dist/layout/resolve.js";
+import { activeReferencedIssueNumbers, buildQueue, collectOrphanIssueNumbers, DEFAULT_QUEUE_LIMIT, loadCachedIssues, loadSliceRecords, readAuditEntries, reconcileLiveOpenState, renderQueue, resolveRankingLabels, resolveRepo, } from "@deftai/directive-core/dist/triage/queue/index.js";
 import { resolveScopeIgnores } from "@deftai/directive-core/dist/triage/scope-drift/index.js";
 /** Parse triage-queue CLI args for the queue subcommand. */
 export function parseArgs(argv) {
@@ -10,6 +11,7 @@ export function parseArgs(argv) {
         repo: process.env.DEFT_TRIAGE_REPO ?? null,
         limit: DEFAULT_QUEUE_LIMIT,
         includeBlocked: false,
+        reconcile: true,
         cacheRoot: null,
         auditLog: null,
         slicesLog: null,
@@ -23,6 +25,10 @@ export function parseArgs(argv) {
             parsed.includeBlocked = true;
             continue;
         }
+        if (arg === "--no-reconcile") {
+            parsed.reconcile = false;
+            continue;
+        }
         if (arg === "--project-root") {
             const value = argv[i + 1];
             if (value === undefined) {
@@ -116,15 +122,8 @@ export function parseArgs(argv) {
     }
     return parsed;
 }
-function resolveFrameworkRoot() {
-    const fromEnv = process.env.DEFT_ROOT?.trim() ?? "";
-    if (fromEnv.length > 0) {
-        return resolve(fromEnv);
-    }
-    return resolve(dirname(fileURLToPath(import.meta.url)), "..", "..");
-}
 /** Run triage:queue and return process exit code. */
-export function run(argv) {
+export function run(argv, options = {}) {
     const args = parseArgs(argv);
     if (args.error !== undefined) {
         process.stderr.write(`triage_queue: ${args.error}\n`);
@@ -136,18 +135,23 @@ export function run(argv) {
         process.stderr.write("triage:queue: --repo OWNER/NAME (or $DEFT_TRIAGE_REPO) is required.\n");
         return 2;
     }
-    const issuesForQueue = loadCachedIssues(repo, { projectRoot });
+    const cachedForQueue = loadCachedIssues(repo, { projectRoot });
+    // Reconcile the cached candidate set against live open/closed state so a
+    // just-closed/merged issue never lingers in the queue as [untriaged] until
+    // the cache refreshes (#2238). Fails open: a read error passes candidates
+    // through unchanged rather than emptying the queue.
+    const issuesForQueue = args.reconcile
+        ? reconcileLiveOpenState(cachedForQueue, repo, options.liveOpenReader)
+        : cachedForQueue;
     const issuesWithClosed = loadCachedIssues(repo, { projectRoot, includeClosed: true });
     const issuesByNumber = new Map(issuesWithClosed.map((row) => [row.number, row]));
     const auditEntries = readAuditEntries(repo, {
-        frameworkRoot: resolveFrameworkRoot(),
-        auditLogPath: args.auditLog,
+        auditLogPath: args.auditLog ?? resolveEvalPath(projectRoot, "candidates.jsonl"),
     });
     const rankingLabels = resolveRankingLabels(projectRoot);
     const activeRefs = activeReferencedIssueNumbers(projectRoot);
     const sliceRecords = loadSliceRecords({
-        frameworkRoot: resolveFrameworkRoot(),
-        slicesLogPath: args.slicesLog,
+        slicesLogPath: args.slicesLog ?? resolveEvalPath(projectRoot, "slices.jsonl"),
     });
     const orphanNumbers = collectOrphanIssueNumbers(sliceRecords, issuesByNumber);
     const limit = args.limit === 0 ? null : Math.max(0, args.limit);

package/dist/verify-agents-md-advisory.d.ts

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+interface ParsedArgs {
+    projectRoot: string;
+    quiet: boolean;
+    enforce: boolean;
+    error?: string;
+}
+/** Parse verify-agents-md-advisory CLI args. */
+export declare function parseArgs(argv: string[]): ParsedArgs;
+/**
+ * Run the advisory and return the process exit code.
+ *
+ * Default posture is advisory: the command ALWAYS exits 0 (it never
+ * fail-closes a consumer build). The opt-in `--enforce` flag promotes an
+ * over-budget unmanaged region to exit 1 for consumers who want a hard cap.
+ */
+export declare function run(argv: string[]): number;
+export {};
+//# sourceMappingURL=verify-agents-md-advisory.d.ts.map

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

@@ -0,0 +1,65 @@
+#!/usr/bin/env node
+import { resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { evaluate } from "@deftai/directive-core/agents-md-advisory";
+/** Parse verify-agents-md-advisory CLI args. */
+export function parseArgs(argv) {
+    const parsed = {
+        projectRoot: ".",
+        quiet: false,
+        enforce: false,
+    };
+    for (let i = 0; i < argv.length; i += 1) {
+        const arg = argv[i];
+        if (arg === "--quiet") {
+            parsed.quiet = true;
+        }
+        else if (arg === "--enforce") {
+            parsed.enforce = 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 {
+            return { ...parsed, error: `unrecognized argument: ${arg}` };
+        }
+    }
+    return parsed;
+}
+/**
+ * Run the advisory and return the process exit code.
+ *
+ * Default posture is advisory: the command ALWAYS exits 0 (it never
+ * fail-closes a consumer build). The opt-in `--enforce` flag promotes an
+ * over-budget unmanaged region to exit 1 for consumers who want a hard cap.
+ */
+export function run(argv) {
+    const args = parseArgs(argv);
+    if (args.error !== undefined) {
+        process.stderr.write(`verify_agents_md_advisory: ${args.error}\n`);
+        return 2;
+    }
+    const projectRoot = resolve(args.projectRoot);
+    const result = evaluate(projectRoot, { quiet: args.quiet, enforce: args.enforce });
+    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-agents-md-advisory.js.map

package/dist/verify-agents-md-budget.d.ts

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+interface ParsedArgs {
+    projectRoot: string;
+    quiet: boolean;
+    error?: string;
+}
+/** Parse verify-agents-md-budget 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-agents-md-budget.d.ts.map

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

@@ -0,0 +1,55 @@
+#!/usr/bin/env node
+import { resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { evaluate } from "@deftai/directive-core/agents-md-budget";
+/** Parse verify-agents-md-budget CLI args. */
+export function parseArgs(argv) {
+    const parsed = {
+        projectRoot: ".",
+        quiet: false,
+    };
+    for (let i = 0; i < argv.length; i += 1) {
+        const arg = argv[i];
+        if (arg === "--quiet") {
+            parsed.quiet = 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 {
+            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_agents_md_budget: ${args.error}\n`);
+        return 2;
+    }
+    const projectRoot = resolve(args.projectRoot);
+    const result = evaluate(projectRoot, { quiet: args.quiet });
+    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-agents-md-budget.js.map

package/dist/verify-forward-coverage.d.ts

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+import { type ForwardCoverageMode } from "@deftai/directive-core";
+interface ParsedArgs {
+    mode: ForwardCoverageMode;
+    projectRoot: string;
+    allowList: string | null;
+    quiet: boolean;
+    error?: string;
+}
+/** Parse the verify-forward-coverage CLI args, mirroring the verify-encoding surface. */
+export declare function parseArgs(argv: string[]): ParsedArgs;
+/** Run the gate and return the process exit code (argv parse error -> 2). */
+export declare function run(argv: string[]): number;
+export {};
+//# sourceMappingURL=verify-forward-coverage.d.ts.map

package/dist/verify-forward-coverage.js

@@ -0,0 +1,77 @@
+#!/usr/bin/env node
+import { resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { evaluateForwardCoverage } from "@deftai/directive-core";
+/** Parse the verify-forward-coverage CLI args, mirroring the verify-encoding surface. */
+export function parseArgs(argv) {
+    const parsed = {
+        mode: "head",
+        projectRoot: ".",
+        allowList: null,
+        quiet: false,
+    };
+    for (let i = 0; i < argv.length; i += 1) {
+        const arg = argv[i];
+        if (arg === "--staged") {
+            parsed.mode = "staged";
+        }
+        else if (arg === "--head") {
+            parsed.mode = "head";
+        }
+        else if (arg === "--quiet") {
+            parsed.quiet = 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 === "--allow-list") {
+            const value = argv[i + 1];
+            if (value === undefined) {
+                return { ...parsed, error: "argument --allow-list: expected one argument" };
+            }
+            parsed.allowList = value;
+            i += 1;
+        }
+        else if (arg?.startsWith("--allow-list=")) {
+            parsed.allowList = arg.slice("--allow-list=".length);
+        }
+        else {
+            return { ...parsed, error: `unrecognized argument: ${arg}` };
+        }
+    }
+    return parsed;
+}
+/** Run the gate and return the process exit code (argv parse error -> 2). */
+export function run(argv) {
+    const args = parseArgs(argv);
+    if (args.error !== undefined) {
+        process.stderr.write(`verify_forward_coverage: ${args.error}\n`);
+        return 2;
+    }
+    const projectRoot = resolve(args.projectRoot);
+    const allowListPath = args.allowList !== null ? resolve(args.allowList) : null;
+    const result = evaluateForwardCoverage(projectRoot, { mode: args.mode, allowListPath });
+    if (result.exitCode === 0) {
+        if (!args.quiet) {
+            process.stdout.write(`${result.message}\n`);
+        }
+    }
+    else {
+        process.stderr.write(`${result.message}\n`);
+    }
+    return result.exitCode;
+}
+// Only execute when invoked directly as a binary (not when imported in tests).
+// Normalize both sides via fileURLToPath so the guard fires on Windows too.
+if (process.argv[1] !== undefined && fileURLToPath(import.meta.url) === process.argv[1]) {
+    process.exit(run(process.argv.slice(2)));
+}
+//# sourceMappingURL=verify-forward-coverage.js.map

package/dist/verify-source-cli/verify-biome-config.d.ts

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+interface ParsedArgs {
+    projectRoot: string;
+    error?: string;
+}
+/** Parse verify-biome-config CLI args (#2190). */
+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-biome-config.d.ts.map

package/dist/verify-source-cli/verify-biome-config.js

@@ -0,0 +1,46 @@
+#!/usr/bin/env node
+import { resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { evaluateBiomeConfigGuard } from "@deftai/directive-core/verify-source";
+/** Parse verify-biome-config CLI args (#2190). */
+export function parseArgs(argv) {
+    const parsed = { projectRoot: "." };
+    for (let i = 0; i < argv.length; i += 1) {
+        const arg = argv[i];
+        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 {
+            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_biome_config: ${args.error}\n`);
+        return 2;
+    }
+    const result = evaluateBiomeConfigGuard(resolve(args.projectRoot));
+    if (result.code === 0) {
+        process.stdout.write(`${result.message}\n`);
+    }
+    else {
+        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-biome-config.js.map

package/dist/verify-story-ready.d.ts

@@ -5,6 +5,8 @@ interface ParsedArgs {
     allocationContext: string | null;
     allowDirty: boolean;
     emitJson: boolean;
+    skipRouting: boolean;
+    roles: string[];
     help?: boolean;
     error?: string;
 }