@deftai/directive 0.67.0 → 0.68.0

package/dist/agents-refresh.js

@@ -2,10 +2,9 @@
 /**
  * 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";
+import { applyAgentsRefresh } from "@deftai/directive-core/platform";
 export function parseAgentsRefreshArgs(argv) {
     let projectRoot = process.cwd();
     let check = false;
@@ -41,8 +40,13 @@ export function runAgentsRefresh(argv) {
         process.stderr.write(`agents:refresh: ${args.error}\n`);
         return 2;
     }
-    const plan = agentsRefreshPlan(args.projectRoot);
-    const state = String(plan.state ?? "unknown");
+    // The read->compute->write is serialized behind an advisory lock and written
+    // atomically inside applyAgentsRefresh, so concurrent refreshers cannot clobber
+    // one another's session= write or observe a partial write (#1329).
+    const { state, path, writable } = applyAgentsRefresh(args.projectRoot, {
+        check: args.check,
+        dryRun: args.dryRun,
+    });
     if (args.check) {
         if (state === "current")
             return 0;
@@ -57,17 +61,14 @@ export function runAgentsRefresh(argv) {
         process.stderr.write(`agents:refresh failed: ${state}\n`);
         return 2;
     }
-    const newContent = plan.new_content;
-    if (typeof newContent !== "string") {
+    if (!writable) {
         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;
 }

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

@@ -35,6 +35,7 @@ export const PR_VERB_MAP = {
     "check-protected-issues": "pr-protected-issues",
     "check-closing-keywords": "pr-closing-keywords",
     "wait-mergeable-and-merge": "pr-wait-mergeable",
+    watch: "pr-watch",
 };
 /** verify:* aliases that map to non-verify-* handler stems. */
 export const VERIFY_VERB_MAP = {

package/dist/dispatch.d.ts

@@ -10,9 +10,9 @@ 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", "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-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"];
+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"];
 /** 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", "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"];
+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"];
 /** Colon aliases for triage-actions (mirrors cli-router SUBCOMMAND_ROUTES). */
 export declare const TRIAGE_ACTION_ALIAS_SUBCOMMANDS: Readonly<Record<string, string>>;
 /** Task-style aliases (framework_commands / Taskfile names). */

package/dist/dispatch.js

@@ -51,6 +51,7 @@ export const CLI_MODULE_VERBS = [
     "pr-monitor",
     "pr-protected-issues",
     "pr-wait-mergeable",
+    "pr-watch",
     "preflight-cache",
     "preflight-gh",
     "probe-session",
@@ -86,6 +87,7 @@ export const CLI_MODULE_VERBS = [
     "vbrief-validation",
     "verify-branch",
     "verify-encoding",
+    "verify-forward-coverage",
     "verify-hooks-installed",
     "verify-investigation",
     "verify-judgment-gates",
@@ -120,6 +122,7 @@ export const CORE_MODULE_VERBS = [
     "reconcile-issues",
     "swarm-launch",
     "swarm-complete-cohort",
+    "swarm-finalize-cohort",
     "swarm-readiness",
     "swarm-routing-verify",
     "swarm-routing-set",
@@ -163,6 +166,7 @@ const TRIAGE_ACTION_COLON_ALIASES = Object.fromEntries(Object.keys(TRIAGE_ACTION
 /** Task-style aliases (framework_commands / Taskfile names). */
 export const VERB_ALIASES = {
     "verify:encoding": "verify-encoding",
+    "verify:forward-coverage": "verify-forward-coverage",
     "verify:branch": "verify-branch",
     "verify:vbrief-conformance": "vbrief-validate",
     "verify:wip-cap": "verify-wip-cap",
@@ -2160,6 +2164,10 @@ async function loadCoreModuleHandler(verb, io) {
             const { completeCohortMain } = await import("@deftai/directive-core/dist/swarm/complete-cohort-cli.js");
             return completeCohortMain;
         }
+        case "swarm-finalize-cohort": {
+            const { finalizeCohortMain } = await import("@deftai/directive-core/dist/swarm/finalize-cohort-cli.js");
+            return finalizeCohortMain;
+        }
         case "swarm-readiness": {
             const { readinessMain } = await import("@deftai/directive-core/dist/swarm/readiness-cli.js");
             return readinessMain;

package/dist/install-upgrade.d.ts

@@ -1,11 +1,41 @@
 #!/usr/bin/env node
-export interface ParsedInstallUpgradeArgs {
-    projectRoot: string;
-    frameworkRoot: string;
-    migrate: boolean;
-    force: boolean;
-    error?: string;
+import type { DispatchIo } from "./dispatch.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 declare const REDIRECT_NOTICE: string;
+export interface InstallUpgradeDeps {
+    /** Injectable seam so tests can drive the shared update path with fixtures. */
+    readonly runUpdate?: (argv: readonly string[], io: DispatchIo) => Promise<number>;
 }
-export declare function parseArgs(argv: readonly string[]): ParsedInstallUpgradeArgs;
-export declare function run(argv: readonly string[]): number;
+/**
+ * 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 declare function translateArgs(argv: readonly string[]): string[];
+/**
+ * Redirect handler: emit the one-line notice, then delegate to the identical
+ * code path `directive update` uses so deposit state + stdout are identical.
+ */
+export declare function run(argv: readonly string[], io?: DispatchIo, deps?: InstallUpgradeDeps): Promise<number>;
 //# sourceMappingURL=install-upgrade.d.ts.map

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-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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deftai/directive",
-  "version": "0.67.0",
+  "version": "0.68.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.67.0",
-    "@deftai/directive-content": "^0.67.0"
+    "@deftai/directive-core": "^0.68.0",
+    "@deftai/directive-content": "^0.68.0"
   },
   "scripts": {
     "build": "tsc -b"