@deftai/directive 0.84.0 → 0.86.0

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

@@ -73,6 +73,7 @@ export const SUBCOMMAND_ROUTES = {
     "policy:enforce-branches": ["policy", "enforce-branches"],
     "policy:allow-direct-commits": ["policy", "allow-direct-commits"],
     "policy:enable-value-feedback": ["policy", "enable-value-feedback"],
+    "policy:clear-value-feedback": ["policy", "clear-value-feedback"],
     "product-signal:status": ["product-signal", "status"],
     "product-signal:enable": ["product-signal", "enable"],
     "product-signal:consent": ["product-signal", "consent"],

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", "hook-dispatch", "umbrella-current-shape", "changelog-check", "change-init", "commit-lint", "coverage-hotspots", "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", "lifecycle-event", "session-start", "plan-sequence", "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-skill-external-fetch-gate", "verify-contract-drift", "verify-cursor-tier1", "verify-go-freeze", "verify-scm-boundary", "verify-session-ritual", "verify-plan-sequence", "verify-stubs", "verify-xbrief-drift", "rule-ownership-lint", "verify-story-ready", "verify-review-monitor", "review-monitor-register", "verify-tools", "verify-wip-cap", "verify-orphan-active", "verify-agents-md-budget", "verify-agents-md-advisory", "verify-eval-health-relocation", "verify-eval-triggers-relocation", "eval-health", "eval-run", "eval-report", "eval-triggers"];
+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", "hook-dispatch", "umbrella-current-shape", "changelog-check", "change-init", "commit-lint", "coverage-hotspots", "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", "lifecycle-event", "session-start", "plan-sequence", "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-skill-external-fetch-gate", "verify-contract-drift", "verify-cursor-tier1", "verify-go-freeze", "verify-scm-boundary", "verify-session-ritual", "verify-plan-sequence", "verify-stubs", "verify-xbrief-drift", "rule-ownership-lint", "verify-story-ready", "verify-review-monitor", "verify-subagent-alive", "review-monitor-register", "review-monitor-release", "verify-tools", "verify-wip-cap", "verify-orphan-active", "verify-agents-md-budget", "verify-agents-md-advisory", "verify-eval-health-relocation", "verify-eval-triggers-relocation", "eval-health", "eval-run", "eval-report", "eval-triggers"];
 /** 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", "issue-sync-from-xbrief", "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", "product-signal"];
+export declare const CORE_MODULE_VERBS: readonly ["scm", "github-auth-modes", "github-body", "issue-emit", "issue-ingest", "issue-sync-from-xbrief", "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", "rule-map", "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", "product-signal"];
 /** 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). */

package/dist/dispatch.js

@@ -8,10 +8,12 @@ import { existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, readSync
 import { homedir, tmpdir } from "node:os";
 import { basename, dirname, isAbsolute, join, relative, resolve } from "node:path";
 import { engineInfo, userConfig } from "@deftai/directive-core";
+import { assertWriteTargetSafe } from "@deftai/directive-core/dist/fs/projection-containment.js";
 import { parseInitArgv, runInitDepositCli } from "@deftai/directive-core/init-deposit";
 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";
+import { atomicWriteProjectDefinition } from "@deftai/directive-core/vbrief-build";
 const HANDLER_KEYS = [
     "run",
     "main",
@@ -114,7 +116,9 @@ export const CLI_MODULE_VERBS = [
     "rule-ownership-lint",
     "verify-story-ready",
     "verify-review-monitor",
+    "verify-subagent-alive",
     "review-monitor-register",
+    "review-monitor-release",
     "verify-tools",
     "verify-wip-cap",
     "verify-orphan-active",
@@ -151,6 +155,7 @@ export const CORE_MODULE_VERBS = [
     "export-spec",
     "project-render",
     "roadmap-render",
+    "rule-map",
     "spec-render",
     "spec-validate",
     "code-structure-validate",
@@ -188,6 +193,7 @@ export const POLICY_ACTION_ALIAS_SUBCOMMANDS = {
     "policy:enforce-branches": "enforce-branches",
     "policy:allow-direct-commits": "allow-direct-commits",
     "policy:enable-value-feedback": "enable-value-feedback",
+    "policy:clear-value-feedback": "clear-value-feedback",
 };
 const POLICY_ACTION_COLON_ALIASES = Object.fromEntries(Object.keys(POLICY_ACTION_ALIAS_SUBCOMMANDS).map((alias) => [alias, "policy"]));
 /** Colon aliases for plan-sequence subcommands (#2402). */
@@ -229,7 +235,10 @@ export const VERB_ALIASES = {
     "vbrief:activate": "vbrief-activate",
     "verify:story-ready": "verify-story-ready",
     "verify:review-monitor": "verify-review-monitor",
+    "verify:subagent-alive": "verify-subagent-alive",
+    "agent:monitor": "subagent-monitor",
     "review-monitor:register": "review-monitor-register",
+    "review-monitor:release": "review-monitor-release",
     "verify:tools": "verify-tools",
     "verify:investigation": "verify-investigation",
     "verify:judgment-gates": "verify-judgment-gates",
@@ -279,6 +288,7 @@ export const VERB_ALIASES = {
     "spec:render": "spec-render",
     "prd:render": "prd-render",
     "project:render": "project-render",
+    "docs:rule-map": "rule-map",
     "project:export-spec": "export-spec",
     "pr:watch": "pr-watch",
     doctor: "doctor",
@@ -2027,7 +2037,8 @@ function writeWipCap(projectRoot, cap, actor, note) {
     const { path, data, policyBlock } = loadProjectDefinitionForWrite(projectRoot);
     const previous = policyBlock.wipCap;
     policyBlock.wipCap = cap;
-    writeFileSync(path, `${JSON.stringify(data, null, 2)}\n`, "utf8");
+    assertWriteTargetSafe(projectRoot, path);
+    atomicWriteProjectDefinition(path, data);
     const changed = previous !== cap;
     const parts = [`actor=${actor}`, `wipCap=${cap}`, `previous=${pyRepr(previous)}`];
     if (note)
@@ -2041,7 +2052,8 @@ function writeSubagentBackend(projectRoot, backendId, actor, note) {
     const { path, data, policyBlock } = loadProjectDefinitionForWrite(projectRoot);
     const previous = policyBlock.swarmSubagentBackend;
     policyBlock.swarmSubagentBackend = backendId;
-    writeFileSync(path, `${JSON.stringify(data, null, 2)}\n`, "utf8");
+    assertWriteTargetSafe(projectRoot, path);
+    atomicWriteProjectDefinition(path, data);
     const changed = previous !== backendId;
     const parts = [
         `actor=${actor}`,
@@ -2298,6 +2310,10 @@ async function loadCoreModuleHandler(verb, io) {
             const { runProjectRenderCli } = await import("./render-cli/project-render-cli.js");
             return (argv) => runProjectRenderCli(argv);
         }
+        case "rule-map": {
+            const { runRuleMapCli } = await import("./render-cli/rule-map-cli.js");
+            return (argv) => runRuleMapCli(argv);
+        }
         case "export-spec": {
             const { runExportSpecCli } = await import("./render-cli/export-spec-cli.js");
             return (argv) => runExportSpecCli(argv);

package/dist/doctor.d.ts

@@ -1,5 +1,14 @@
 #!/usr/bin/env node
-/** Advisory when a consumer deposit carries git-vendored framework source (#2142 / #2347). */
-export declare function renderStrayPackagesAdvisoryLine(projectRoot: string): string;
+export interface DepositFileSetHygieneResult {
+    readonly absent: readonly string[];
+    readonly contentRoot: string | null;
+    readonly skipped: boolean;
+}
+export interface EvaluateDepositFileSetOptions {
+    readonly contentRoot?: string;
+}
+/** Compare `.deft/core/` against `@deftai/directive-content` (#2804). */
+export declare function evaluateDepositFileSetHygiene(projectRoot: string, options?: EvaluateDepositFileSetOptions): DepositFileSetHygieneResult;
+export declare function renderDepositFileSetHygieneLine(projectRoot: string, result?: DepositFileSetHygieneResult): string;
 export declare function run(argv: string[]): number;
 //# sourceMappingURL=doctor.d.ts.map

package/dist/doctor.js

@@ -2,20 +2,45 @@
 import { existsSync } from "node:fs";
 import { join } from "node:path";
 import { fileURLToPath } from "node:url";
+import { resolveContentPackageRoot } from "@deftai/directive-core/dist/content-root.js";
 import { parseDoctorFlags } from "@deftai/directive-core/dist/doctor/flags.js";
 import { cmdDoctor } from "@deftai/directive-core/dist/doctor/main.js";
+import { findPackageAbsentDepositPathsSync } from "@deftai/directive-core/dist/init-deposit/hygiene.js";
 import { renderPrecutoverLine } from "@deftai/directive-core/dist/vbrief-validate/precutover.js";
 import { renderStaleHeaderLine, renderXbriefMigrationLine, } from "@deftai/directive-core/xbrief-migrate";
-/** Advisory when a consumer deposit carries git-vendored framework source (#2142 / #2347). */
-export function renderStrayPackagesAdvisoryLine(projectRoot) {
-    const packagesDir = join(projectRoot, ".deft", "core", "packages");
-    if (!existsSync(packagesDir)) {
-        return "Deposit hygiene: none -- .deft/core contains no stray packages/ source tree.";
+/** Compare `.deft/core/` against `@deftai/directive-content` (#2804). */
+export function evaluateDepositFileSetHygiene(projectRoot, options = {}) {
+    const deftDir = join(projectRoot, ".deft", "core");
+    if (!existsSync(deftDir)) {
+        return { absent: [], contentRoot: null, skipped: true };
     }
-    return ("Deposit hygiene: advisory -- .deft/core/packages/ is present (git-vendored framework source, " +
-        "not shipped by npm @deftai/directive-content). " +
-        "Run `directive update` to auto-prune this stray tree, then commit the result (#2347). " +
-        "Or remove it manually: `git rm -r --cached .deft/core/packages && git commit -m 'chore: remove stray framework source'`.");
+    const contentRoot = options.contentRoot ?? resolveContentPackageRoot(projectRoot);
+    if (contentRoot === null || !existsSync(contentRoot)) {
+        return { absent: [], contentRoot: null, skipped: true };
+    }
+    return {
+        absent: findPackageAbsentDepositPathsSync(deftDir, contentRoot),
+        contentRoot,
+        skipped: false,
+    };
+}
+export function renderDepositFileSetHygieneLine(projectRoot, result = evaluateDepositFileSetHygiene(projectRoot)) {
+    const deftDir = join(projectRoot, ".deft", "core");
+    if (!existsSync(deftDir)) {
+        return "Deposit hygiene: none -- no .deft/core deposit.";
+    }
+    if (result.skipped) {
+        return ("Deposit hygiene: skip -- @deftai/directive-content is not installed " +
+            "(cannot compare deposit file-set).");
+    }
+    if (result.absent.length === 0) {
+        return "Deposit hygiene: none -- .deft/core file-set matches @deftai/directive-content.";
+    }
+    const sample = result.absent.slice(0, 5).join(", ");
+    const suffix = result.absent.length > 5 ? ` (+${result.absent.length - 5} more)` : "";
+    return (`Deposit hygiene: fail -- ${result.absent.length} package-absent file(s) in .deft/core ` +
+        `(not shipped by @deftai/directive-content). Examples: ${sample}${suffix}. ` +
+        "Run `directive update` to auto-prune these stale deposit files (#2804).");
 }
 export function run(argv) {
     // #2022: surface pre-cutover (pre-v0.20 document model) migration state alongside the
@@ -23,14 +48,20 @@ export function run(argv) {
     // --json (so the machine-readable report stays valid), on --help, and when unknown flags
     // are present (so an invalid invocation still mirrors the core error path exactly).
     const flags = parseDoctorFlags(argv);
+    let depositHygieneExit = 0;
     if (!flags.json && !flags.help && flags.unknown.length === 0) {
         const projectRoot = flags.projectRoot ?? process.cwd();
+        const depositResult = evaluateDepositFileSetHygiene(projectRoot);
         process.stdout.write(`${renderPrecutoverLine(projectRoot)}\n`);
         process.stdout.write(`${renderXbriefMigrationLine(projectRoot)}\n`);
         process.stdout.write(`${renderStaleHeaderLine(projectRoot)}\n`);
-        process.stdout.write(`${renderStrayPackagesAdvisoryLine(projectRoot)}\n`);
+        process.stdout.write(`${renderDepositFileSetHygieneLine(projectRoot, depositResult)}\n`);
+        if (flags.full && !depositResult.skipped && depositResult.absent.length > 0) {
+            depositHygieneExit = 1;
+        }
     }
-    return cmdDoctor(argv);
+    const doctorExit = cmdDoctor(argv);
+    return Math.max(depositHygieneExit, doctorExit);
 }
 if (process.argv[1] !== undefined && fileURLToPath(import.meta.url) === process.argv[1]) {
     process.exit(run(process.argv.slice(2)));

package/dist/entrypoint.d.ts

@@ -0,0 +1,6 @@
+/**
+ * True when this module is the process entrypoint, including npm bin symlinks.
+ * Node passes the symlink path in argv[1]; compare via realpath on both sides.
+ */
+export declare function isDirectEntrypoint(moduleUrl: string | URL): boolean;
+//# sourceMappingURL=entrypoint.d.ts.map

package/dist/entrypoint.js

@@ -0,0 +1,19 @@
+import { realpathSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+/**
+ * True when this module is the process entrypoint, including npm bin symlinks.
+ * Node passes the symlink path in argv[1]; compare via realpath on both sides.
+ */
+export function isDirectEntrypoint(moduleUrl) {
+    const argv1 = process.argv[1];
+    if (argv1 === undefined)
+        return false;
+    try {
+        const modulePath = fileURLToPath(moduleUrl);
+        return realpathSync(argv1) === realpathSync(modulePath);
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=entrypoint.js.map

package/dist/hook-bin.d.ts

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

package/dist/hook-bin.js

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+import { isDirectEntrypoint } from "./entrypoint.js";
+import { run } from "./hook-dispatch.js";
+// Keep PreToolUse off the general CLI router's cold path.
+export function main(argv = process.argv.slice(2)) {
+    return run(argv);
+}
+if (isDirectEntrypoint(import.meta.url)) {
+    process.exit(main());
+}
+//# sourceMappingURL=hook-bin.js.map

package/dist/init-cli/help.d.ts

@@ -0,0 +1,9 @@
+import type { DispatchIo } from "../dispatch.js";
+/** Flags that request usage text without executing a mutating install path (#2828). */
+export declare const INIT_CLI_HELP_FLAGS: readonly ["--help", "-h", "/help", "/h"];
+/** True when argv includes a help flag anywhere in the token list. */
+export declare function argvWantsHelp(argv: readonly string[]): boolean;
+export declare function printUpdateHelp(io: DispatchIo): void;
+export declare function printInitHelp(io: DispatchIo): void;
+export declare function printMigrateHelp(io: DispatchIo): void;
+//# sourceMappingURL=help.d.ts.map

package/dist/init-cli/help.js

@@ -0,0 +1,42 @@
+/** Flags that request usage text without executing a mutating install path (#2828). */
+export const INIT_CLI_HELP_FLAGS = ["--help", "-h", "/help", "/h"];
+/** True when argv includes a help flag anywhere in the token list. */
+export function argvWantsHelp(argv) {
+    const flags = INIT_CLI_HELP_FLAGS;
+    return argv.some((arg) => flags.includes(arg));
+}
+export function printUpdateHelp(io) {
+    io.writeOut("Usage: directive update [options]\n" +
+        "       deft update [options]\n\n" +
+        "Refresh the framework deposit in an existing Directive project and self-heal the engine.\n\n" +
+        "Options:\n" +
+        "  --repo-root <path>          Project root (default: current directory)\n" +
+        "  --json                      Machine-readable summary on stdout\n" +
+        "  --yes, --non-interactive  Run without prompts\n" +
+        "  --dry-run, --plan           Classify and print the refresh plan without writing\n" +
+        "  -h, --help                  Show this help\n");
+}
+export function printInitHelp(io) {
+    io.writeOut("Usage: directive init [options]\n" +
+        "       deft init [options]\n\n" +
+        "Set up Directive in the current project (greenfield scaffold or brownfield adoption).\n\n" +
+        "Options:\n" +
+        "  --repo-root <path>          Project root (default: current directory)\n" +
+        "  --json                      Machine-readable summary on stdout\n" +
+        "  --yes, --non-interactive  Run without prompts\n" +
+        "  --dry-run, --plan           Classify and print the dispatch plan without writing\n" +
+        "  --headless                  Emit a { version, files } manifest with no side effects\n" +
+        "  --output <path>             Manifest output path for --headless (default: stdout)\n" +
+        "  -h, --help                  Show this help\n");
+}
+export function printMigrateHelp(io) {
+    io.writeOut("Usage: directive migrate [options]\n" +
+        "       deft migrate [options]\n\n" +
+        "Stamp a canonical-vendored .deft/core deposit as npm-managed (provenance only).\n\n" +
+        "Options:\n" +
+        "  --repo-root <path>          Project root (default: current directory)\n" +
+        "  --json                      Machine-readable summary on stdout\n" +
+        "  --untrack-core              Un-commit .deft/core from git (destructive index mutation)\n" +
+        "  -h, --help                  Show this help\n");
+}
+//# sourceMappingURL=help.js.map

package/dist/init-cli/init.js

@@ -1,5 +1,6 @@
 import { parseInitArgv, runInitDispatchCli, runInitHeadlessCli, } from "@deftai/directive-core/init-deposit";
 import { CANONICAL_INIT_ARGV, INIT_DRY_RUN_FLAGS, INIT_HEADLESS_FLAGS, INIT_OUTPUT_FLAGS, } from "./constants.js";
+import { argvWantsHelp, printInitHelp } from "./help.js";
 /** True when the user argv asked for a classify-only dispatch plan (`--dry-run`/`--plan`). */
 export function isInitDryRun(argv) {
     const flags = INIT_DRY_RUN_FLAGS;
@@ -53,6 +54,10 @@ export function parseInitOutputPath(argv) {
  * `headlessSeams` injects the content-resolution seam for the headless path.
  */
 export function runInit(argv, io, seams, headlessSeams) {
+    if (argvWantsHelp(argv)) {
+        printInitHelp(io);
+        return Promise.resolve(0);
+    }
     if (isInitHeadless(argv)) {
         return runInitHeadlessCli({
             outputPath: parseInitOutputPath(argv),

package/dist/init-cli/migrate.js

@@ -1,5 +1,6 @@
 import { parseInitArgv, runMigrateCli, runUntrackCoreCli, } from "@deftai/directive-core/init-deposit";
 import { CANONICAL_MIGRATE_ARGV, MIGRATE_UNTRACK_CORE_FLAG } from "./constants.js";
+import { argvWantsHelp, printMigrateHelp } from "./help.js";
 /**
  * `directive migrate` (alias `deft migrate`) -- stage-2 provenance verb (#1941):
  * stamp a canonical-vendored `.deft/core` deposit as npm-managed. Thin wrapper
@@ -19,6 +20,10 @@ function hasUntrackCoreFlag(argv) {
     return argv.some((arg) => arg === MIGRATE_UNTRACK_CORE_FLAG || arg === `/${MIGRATE_UNTRACK_CORE_FLAG.slice(2)}`);
 }
 export function runMigrate(argv, io) {
+    if (argvWantsHelp(argv)) {
+        printMigrateHelp(io);
+        return 0;
+    }
     const args = parseInitArgv(CANONICAL_MIGRATE_ARGV, argv);
     // `migrate --untrack-core` selects the destructive un-track subcommand;
     // bare `migrate` keeps the provenance-stamp behavior below.

package/dist/init-cli/update.js

@@ -1,11 +1,16 @@
 import { parseUpdateArgv, runRefreshDepositCli } from "@deftai/directive-core/init-deposit";
 import { CANONICAL_UPDATE_ARGV, UPDATE_DRY_RUN_FLAGS } from "./constants.js";
+import { argvWantsHelp, printUpdateHelp } from "./help.js";
 /** True when the user argv asked for a classify-only dry-run (`--dry-run`/`--plan`). */
 export function isUpdateDryRun(argv) {
     const flags = UPDATE_DRY_RUN_FLAGS;
     return argv.some((arg) => flags.includes(arg));
 }
 export function runUpdate(argv, io) {
+    if (argvWantsHelp(argv)) {
+        printUpdateHelp(io);
+        return Promise.resolve(0);
+    }
     const args = parseUpdateArgv(CANONICAL_UPDATE_ARGV, argv);
     return runRefreshDepositCli({
         ...args,

package/dist/policy.d.ts

@@ -7,7 +7,7 @@ interface ShowArgs {
     error?: string;
 }
 interface SetArgs {
-    cmd: "show" | "enforce-branches" | "allow-direct-commits" | "enable-value-feedback" | "resolve";
+    cmd: "show" | "enforce-branches" | "allow-direct-commits" | "enable-value-feedback" | "clear-value-feedback" | "resolve";
     confirm: boolean;
     actor: string;
     note: string;

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, policyColonInvocation, projectDefinitionPath, pythonListRepr, pythonStringRepr, registeredPolicyNames, renderJson, renderText, resolvePolicy, resolveValueFeedback, setPolicy, } from "@deftai/directive-core/policy";
+import { clearValueFeedback, 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 " +
@@ -114,7 +114,7 @@ export function parseShowArgs(argv) {
 /** Parse argv for the policy CLI (show + set subcommands). */
 export function parseArgs(argv) {
     if (argv.length === 0) {
-        const usage = "usage: policy [show|enforce-branches|allow-direct-commits|enable-value-feedback|resolve] ...";
+        const usage = "usage: policy [show|enforce-branches|allow-direct-commits|enable-value-feedback|clear-value-feedback|resolve] ...";
         return makeSetError(usage);
     }
     const cmd = argv[0];
@@ -148,13 +148,16 @@ export function parseArgs(argv) {
     }
     if (cmd === "enforce-branches" ||
         cmd === "allow-direct-commits" ||
-        cmd === "enable-value-feedback") {
+        cmd === "enable-value-feedback" ||
+        cmd === "clear-value-feedback") {
         let confirm = false;
         let actor = cmd === "enforce-branches"
             ? policyColonInvocation("enforce-branches")
             : cmd === "allow-direct-commits"
                 ? policyColonInvocation("allow-direct-commits")
-                : policyColonInvocation("enable-value-feedback");
+                : cmd === "enable-value-feedback"
+                    ? policyColonInvocation("enable-value-feedback")
+                    : policyColonInvocation("clear-value-feedback");
         let note = "";
         let projectRoot = ".";
         for (let i = 1; i < argv.length; i += 1) {
@@ -327,6 +330,14 @@ function runSet(args) {
         return 2;
     }
 }
+function runClearValueFeedback(args) {
+    const result = clearValueFeedback(pathResolve(args.projectRoot), {
+        actor: args.actor,
+        note: args.note,
+    });
+    process.stdout.write(result.stdout);
+    return result.exitCode;
+}
 /** Run the policy CLI; returns process exit code. */
 export function run(argv) {
     const args = parseArgs(argv);
@@ -351,6 +362,9 @@ export function run(argv) {
     if (args.cmd === "enable-value-feedback") {
         return runEnableValueFeedback(args);
     }
+    if (args.cmd === "clear-value-feedback") {
+        return runClearValueFeedback(args);
+    }
     return 2;
 }
 if (process.argv[1] !== undefined && fileURLToPath(import.meta.url) === process.argv[1]) {

package/dist/render-cli/rule-map-cli.d.ts

@@ -0,0 +1,2 @@
+export declare function runRuleMapCli(argv: readonly string[]): number;
+//# sourceMappingURL=rule-map-cli.d.ts.map

package/dist/render-cli/rule-map-cli.js

@@ -0,0 +1,5 @@
+import { ruleMapMain } from "@deftai/directive-core/render";
+export function runRuleMapCli(argv) {
+    return ruleMapMain(argv);
+}
+//# sourceMappingURL=rule-map-cli.js.map

package/dist/review-monitor-register.d.ts

@@ -6,8 +6,10 @@ interface ParsedArgs {
     platformPrimitive: PlatformPrimitive | null;
     repo: string | null;
     headSha: string | null;
+    owner: string | null;
     projectRoot: string;
     parentSessionId: string | null;
+    force: boolean;
     help: boolean;
     error?: string;
 }

package/dist/review-monitor-register.js

@@ -10,8 +10,10 @@ export function parseRegisterArgs(argv) {
         platformPrimitive: null,
         repo: null,
         headSha: null,
+        owner: null,
         projectRoot: ".",
         parentSessionId: null,
+        force: false,
         help: false,
     };
     for (let i = 0; i < argv.length; i += 1) {
@@ -19,7 +21,10 @@ export function parseRegisterArgs(argv) {
         if (arg === "--help" || arg === "-h") {
             return { ...acc, help: true };
         }
-        if (arg === "--pr") {
+        if (arg === "--force") {
+            acc.force = true;
+        }
+        else if (arg === "--pr") {
             const value = argv[i + 1];
             if (value === undefined) {
                 return { ...acc, error: "argument --pr: expected one argument" };
@@ -78,6 +83,17 @@ export function parseRegisterArgs(argv) {
         else if (arg?.startsWith("--repo=")) {
             acc.repo = arg.slice("--repo=".length);
         }
+        else if (arg === "--owner") {
+            const value = argv[i + 1];
+            if (value === undefined) {
+                return { ...acc, error: "argument --owner: expected one argument" };
+            }
+            acc.owner = value;
+            i += 1;
+        }
+        else if (arg?.startsWith("--owner=")) {
+            acc.owner = arg.slice("--owner=".length);
+        }
         else if (arg === "--head-sha") {
             const value = argv[i + 1];
             if (value === undefined) {
@@ -142,23 +158,24 @@ export function run(argv) {
         process.stderr.write("review_monitor_register: --platform-primitive is required\n");
         return 2;
     }
-    try {
-        const { path, record } = registerReviewMonitor({
-            pr: args.pr,
-            repo: args.repo,
-            headSha: args.headSha,
-            platformPrimitive: args.platformPrimitive,
-            monitorAgentId: args.monitorAgentId,
-            projectRoot: resolve(args.projectRoot),
-            parentSessionId: args.parentSessionId,
-        });
-        process.stdout.write(`review_monitor_register: recorded PR #${record.pr} monitor ${record.monitor_agent_id} at ${path}\n`);
-        return 0;
+    const result = registerReviewMonitor({
+        pr: args.pr,
+        repo: args.repo,
+        headSha: args.headSha,
+        owner: args.owner,
+        platformPrimitive: args.platformPrimitive,
+        monitorAgentId: args.monitorAgentId,
+        projectRoot: resolve(args.projectRoot),
+        parentSessionId: args.parentSessionId,
+        force: args.force,
+    });
+    if (result.exitCode === 0) {
+        process.stdout.write(`${result.message}\n`);
     }
-    catch (err) {
-        process.stderr.write(`review_monitor_register: ${String(err.message ?? err)}\n`);
-        return 2;
+    else {
+        process.stderr.write(`${result.message}\n`);
     }
+    return result.exitCode;
 }
 if (process.argv[1] !== undefined && fileURLToPath(import.meta.url) === process.argv[1]) {
     process.exit(run(process.argv.slice(2)));

package/dist/review-monitor-release.d.ts

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+interface ParsedArgs {
+    pr: number | null;
+    repo: string | null;
+    monitorAgentId: string | null;
+    owner: string | null;
+    projectRoot: string;
+    help: boolean;
+    error?: string;
+}
+export declare function parseReleaseArgs(argv: readonly string[]): ParsedArgs;
+export declare function run(argv: readonly string[]): number;
+export {};
+//# sourceMappingURL=review-monitor-release.d.ts.map

package/dist/review-monitor-release.js

@@ -0,0 +1,123 @@
+#!/usr/bin/env node
+import { resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { RELEASE_HELP, releaseReviewMonitor } from "@deftai/directive-core/review-monitor";
+export function parseReleaseArgs(argv) {
+    const acc = {
+        pr: null,
+        repo: null,
+        monitorAgentId: null,
+        owner: null,
+        projectRoot: ".",
+        help: false,
+    };
+    for (let i = 0; i < argv.length; i += 1) {
+        const arg = argv[i];
+        if (arg === "--help" || arg === "-h") {
+            return { ...acc, help: true };
+        }
+        if (arg === "--pr") {
+            const value = argv[i + 1];
+            if (value === undefined) {
+                return { ...acc, error: "argument --pr: expected one argument" };
+            }
+            const n = Number(value);
+            if (!Number.isInteger(n) || n <= 0) {
+                return { ...acc, error: `invalid --pr value: ${value}` };
+            }
+            acc.pr = n;
+            i += 1;
+        }
+        else if (arg?.startsWith("--pr=")) {
+            const n = Number(arg.slice("--pr=".length));
+            if (!Number.isInteger(n) || n <= 0) {
+                return { ...acc, error: `invalid --pr value: ${arg}` };
+            }
+            acc.pr = n;
+        }
+        else if (arg === "--repo") {
+            const value = argv[i + 1];
+            if (value === undefined) {
+                return { ...acc, error: "argument --repo: expected one argument" };
+            }
+            acc.repo = value;
+            i += 1;
+        }
+        else if (arg?.startsWith("--repo=")) {
+            acc.repo = arg.slice("--repo=".length);
+        }
+        else if (arg === "--monitor-agent-id") {
+            const value = argv[i + 1];
+            if (value === undefined) {
+                return { ...acc, error: "argument --monitor-agent-id: expected one argument" };
+            }
+            acc.monitorAgentId = value;
+            i += 1;
+        }
+        else if (arg?.startsWith("--monitor-agent-id=")) {
+            acc.monitorAgentId = arg.slice("--monitor-agent-id=".length);
+        }
+        else if (arg === "--owner") {
+            const value = argv[i + 1];
+            if (value === undefined) {
+                return { ...acc, error: "argument --owner: expected one argument" };
+            }
+            acc.owner = value;
+            i += 1;
+        }
+        else if (arg?.startsWith("--owner=")) {
+            acc.owner = arg.slice("--owner=".length);
+        }
+        else if (arg === "--project-root") {
+            const value = argv[i + 1];
+            if (value === undefined) {
+                return { ...acc, error: "argument --project-root: expected one argument" };
+            }
+            acc.projectRoot = value;
+            i += 1;
+        }
+        else if (arg?.startsWith("--project-root=")) {
+            acc.projectRoot = arg.slice("--project-root=".length);
+        }
+        else if (arg?.startsWith("-")) {
+            return { ...acc, error: `unrecognized argument: ${arg}` };
+        }
+        else {
+            return { ...acc, error: `unrecognized argument: ${arg}` };
+        }
+    }
+    return acc;
+}
+export function run(argv) {
+    const args = parseReleaseArgs(argv);
+    if (args.help) {
+        process.stdout.write(RELEASE_HELP);
+        return 0;
+    }
+    if (args.error !== undefined) {
+        process.stderr.write(`review_monitor_release: ${args.error}\n`);
+        return 2;
+    }
+    if (args.pr === null) {
+        process.stderr.write("review_monitor_release: --pr is required\n");
+        return 2;
+    }
+    const result = releaseReviewMonitor({
+        pr: args.pr,
+        repo: args.repo,
+        monitorAgentId: args.monitorAgentId,
+        owner: args.owner,
+        projectRoot: resolve(args.projectRoot),
+    });
+    if (result.exitCode === 0) {
+        process.stdout.write(`${result.message}\n`);
+    }
+    else {
+        process.stderr.write(`${result.message}\n`);
+    }
+    return result.exitCode;
+}
+if (process.argv[1] !== undefined && fileURLToPath(import.meta.url) === process.argv[1]) {
+    process.exit(run(process.argv.slice(2)));
+}
+//# sourceMappingURL=review-monitor-release.js.map

package/dist/vbrief-preflight.d.ts

@@ -2,6 +2,7 @@
 interface ParsedArgs {
     vbriefPath: string | null;
     emitJson: boolean;
+    help?: boolean;
     error?: string;
 }
 /** Parse vbrief-preflight / xbrief:preflight CLI args (#810 / #2449). */

package/dist/vbrief-preflight.js

@@ -1,6 +1,15 @@
 #!/usr/bin/env node
 import { fileURLToPath } from "node:url";
 import { emitJson, evaluate, PREFLIGHT_USAGE_HINT } from "@deftai/directive-core/preflight";
+const HELP_TEXT = `usage: xbrief:preflight [--vbrief-path PATH | PATH] [--json] [--help]
+
+Implementation-intent gate (#810): exits 0 only when the xBRIEF is in
+xbrief/active/ (or legacy vbrief/active/) AND plan.status == 'running'.
+
+Examples:
+  deft xbrief:preflight -- xbrief/active/<story>.xbrief.json
+  deft xbrief:preflight --vbrief-path xbrief/active/<story>.xbrief.json
+`;
 const PATH_FLAG_NAMES = ["--vbrief-path", "--brief-path", "--xbrief-path"];
 function assignPathFlag(parsed, value) {
     if (value === undefined || value.length === 0) {
@@ -19,15 +28,30 @@ export function parseArgs(argv) {
     };
     for (let i = 0; i < argv.length; i += 1) {
         const arg = argv[i];
+        if (arg === "--") {
+            continue;
+        }
         if (arg === "--json") {
             parsed.emitJson = true;
             continue;
         }
         if (arg === "--help" || arg === "-h") {
-            return parsed;
+            return { ...parsed, help: true };
         }
         if (PATH_FLAG_NAMES.includes(arg)) {
-            const next = assignPathFlag(parsed, argv[i + 1]);
+            // Task wrappers bake `--vbrief-path {{.CLI_ARGS}}`, so
+            // `task xbrief:preflight -- --help` arrives as `--vbrief-path --help`.
+            const nextToken = argv[i + 1];
+            if (nextToken === "--help" || nextToken === "-h") {
+                return { ...parsed, help: true };
+            }
+            if (nextToken !== undefined && nextToken.startsWith("-")) {
+                return {
+                    ...parsed,
+                    error: "argument --vbrief-path: expected one argument",
+                };
+            }
+            const next = assignPathFlag(parsed, nextToken);
             if (next?.error !== undefined)
                 return next;
             parsed.vbriefPath = next?.vbriefPath ?? null;
@@ -66,6 +90,10 @@ export function parseArgs(argv) {
 /** Run the gate and return the process exit code (parse errors -> 2). */
 export function run(argv) {
     const args = parseArgs(argv);
+    if (args.help) {
+        process.stdout.write(HELP_TEXT);
+        return 0;
+    }
     if (args.error !== undefined) {
         process.stderr.write(`preflight_implementation: ${args.error}\n`);
         return 2;

package/dist/verify-encoding.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import { resolve } from "node:path";
-import { fileURLToPath } from "node:url";
 import { evaluate } from "@deftai/directive-core";
+import { isDirectEntrypoint } from "./entrypoint.js";
 /** Parse the verify-encoding CLI args, mirroring the Python argparse surface. */
 export function parseArgs(argv) {
     const parsed = {
@@ -77,10 +77,7 @@ export function run(argv) {
     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,
-// where process.argv[1] is a native backslash path and import.meta.url is a
-// forward-slash file:// URL -- a raw `file://${process.argv[1]}` never matches.
-if (process.argv[1] !== undefined && fileURLToPath(import.meta.url) === process.argv[1]) {
+if (isDirectEntrypoint(import.meta.url)) {
     process.exit(run(process.argv.slice(2)));
 }
 //# sourceMappingURL=verify-encoding.js.map

package/dist/verify-subagent-alive.d.ts

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+export declare const SUBAGENT_ALIVE_HELP = "verify:subagent-alive \u2014 fail-closed worker liveness gate (#2824)\n\nUsage:\n  task verify:subagent-alive -- [options]\n  task agent:monitor -- [options]   (alias: raw heartbeat sweep)\n\nOptions:\n  --scratch-dir PATH       Heartbeat directory (repeatable; default: .deft-scratch/subagent-status)\n  --require-agent ID       In-flight worker that MUST have a fresh heartbeat (repeatable)\n  --threshold-minutes N    Staleness threshold (default: 30)\n  --json                   Machine-readable output\n\nExit codes:\n  0  All required agents fresh (or no required agents and sweep clean)\n  1  Missing/STALE/malformed heartbeat \u2014 prints REDISPATCH_OK for takeover\n  2  Config error (invalid args, missing scratch dir with no records)\n";
+export interface VerifySubagentAliveArgs {
+    scratchDirs: string[];
+    requireAgents: string[];
+    thresholdMinutes: number;
+    emitJson: boolean;
+    help: boolean;
+    error?: string;
+}
+export declare function parseVerifySubagentAliveArgs(argv: readonly string[]): VerifySubagentAliveArgs;
+export interface SubagentAliveVerdict {
+    exitCode: number;
+    redispatchOk: boolean;
+    message: string;
+    json?: Record<string, unknown>;
+}
+/** Evaluate liveness for required in-flight workers. */
+export declare function evaluateSubagentAliveGate(args: VerifySubagentAliveArgs, cwd?: string): SubagentAliveVerdict;
+export declare function run(argv: readonly string[]): number;
+//# sourceMappingURL=verify-subagent-alive.d.ts.map

package/dist/verify-subagent-alive.js

@@ -0,0 +1,199 @@
+#!/usr/bin/env node
+/**
+ * Fail-closed worker liveness gate (#2824). Wraps subagent-monitor with
+ * REDISPATCH_OK on missing/STALE heartbeats for registered in-flight workers.
+ */
+import { resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { DEFAULT_THRESHOLD_MINUTES, defaultScratchDir, EXIT_EXTERNAL_ERROR, EXIT_OK, EXIT_STALE, recordOk, sweepAllOk, sweepScratchDirs, } from "@deftai/directive-core/orchestration";
+export const SUBAGENT_ALIVE_HELP = `verify:subagent-alive — fail-closed worker liveness gate (#2824)
+
+Usage:
+  task verify:subagent-alive -- [options]
+  task agent:monitor -- [options]   (alias: raw heartbeat sweep)
+
+Options:
+  --scratch-dir PATH       Heartbeat directory (repeatable; default: .deft-scratch/subagent-status)
+  --require-agent ID       In-flight worker that MUST have a fresh heartbeat (repeatable)
+  --threshold-minutes N    Staleness threshold (default: 30)
+  --json                   Machine-readable output
+
+Exit codes:
+  0  All required agents fresh (or no required agents and sweep clean)
+  1  Missing/STALE/malformed heartbeat — prints REDISPATCH_OK for takeover
+  2  Config error (invalid args, missing scratch dir with no records)
+`;
+export function parseVerifySubagentAliveArgs(argv) {
+    const acc = {
+        scratchDirs: [],
+        requireAgents: [],
+        thresholdMinutes: DEFAULT_THRESHOLD_MINUTES,
+        emitJson: false,
+        help: false,
+    };
+    for (let i = 0; i < argv.length; i += 1) {
+        const arg = argv[i];
+        if (arg === "--help" || arg === "-h") {
+            return { ...acc, help: true };
+        }
+        if (arg === "--json") {
+            acc.emitJson = true;
+        }
+        else if (arg === "--scratch-dir") {
+            const value = argv[i + 1];
+            if (value === undefined) {
+                return { ...acc, error: "argument --scratch-dir: expected one argument" };
+            }
+            acc.scratchDirs.push(value);
+            i += 1;
+        }
+        else if (arg?.startsWith("--scratch-dir=")) {
+            acc.scratchDirs.push(arg.slice("--scratch-dir=".length));
+        }
+        else if (arg === "--threshold-minutes") {
+            const value = argv[i + 1];
+            if (value === undefined) {
+                return { ...acc, error: "argument --threshold-minutes: expected one argument" };
+            }
+            acc.thresholdMinutes = Number(value);
+            i += 1;
+        }
+        else if (arg?.startsWith("--threshold-minutes=")) {
+            acc.thresholdMinutes = Number(arg.slice("--threshold-minutes=".length));
+        }
+        else if (arg === "--require-agent") {
+            const value = argv[i + 1];
+            if (value === undefined) {
+                return { ...acc, error: "argument --require-agent: expected one argument" };
+            }
+            acc.requireAgents.push(value);
+            i += 1;
+        }
+        else if (arg?.startsWith("--require-agent=")) {
+            acc.requireAgents.push(arg.slice("--require-agent=".length));
+        }
+        else if (arg?.startsWith("-")) {
+            return { ...acc, error: `unrecognized argument: ${arg}` };
+        }
+        else {
+            return { ...acc, error: `unrecognized argument: ${arg}` };
+        }
+    }
+    return acc;
+}
+function scratchEntries(scratchDirs, cwd) {
+    if (scratchDirs.length > 0) {
+        return scratchDirs.map((p) => ({ readPath: resolve(cwd, p), label: p }));
+    }
+    const defaultDir = defaultScratchDir(cwd);
+    return [{ readPath: defaultDir, label: defaultDir }];
+}
+/** Evaluate liveness for required in-flight workers. */
+export function evaluateSubagentAliveGate(args, cwd = process.cwd()) {
+    if (args.error !== undefined) {
+        return {
+            exitCode: EXIT_EXTERNAL_ERROR,
+            redispatchOk: false,
+            message: `verify_subagent_alive: ${args.error}`,
+        };
+    }
+    if (Number.isNaN(args.thresholdMinutes) || args.thresholdMinutes <= 0) {
+        return {
+            exitCode: EXIT_EXTERNAL_ERROR,
+            redispatchOk: false,
+            message: `verify_subagent_alive: --threshold-minutes must be positive, got ${args.thresholdMinutes}`,
+        };
+    }
+    const entries = scratchEntries(args.scratchDirs, cwd);
+    const sweep = sweepScratchDirs(entries, { thresholdMinutes: args.thresholdMinutes });
+    const configError = sweep.sweep_errors.length > 0 && sweep.records.length === 0;
+    const missingAgents = [];
+    for (const agentId of args.requireAgents) {
+        const rec = sweep.records.find((r) => r.agent_id === agentId);
+        if (rec === undefined || !recordOk(rec)) {
+            missingAgents.push(agentId);
+        }
+    }
+    const requiredUnhealthy = missingAgents.length > 0;
+    // When --require-agent is set, only named workers gate the verdict; unrelated
+    // stale records in a shared scratch dir must not trigger REDISPATCH_OK (#2824).
+    const sweepUnhealthy = args.requireAgents.length === 0 && !sweepAllOk(sweep);
+    const unhealthy = sweepUnhealthy || requiredUnhealthy;
+    if (args.emitJson) {
+        return {
+            exitCode: configError ? EXIT_EXTERNAL_ERROR : unhealthy ? EXIT_STALE : EXIT_OK,
+            redispatchOk: unhealthy && !configError,
+            message: "",
+            json: {
+                all_ok: !unhealthy && !configError,
+                redispatch_ok: unhealthy && !configError,
+                required_agents: [...args.requireAgents],
+                missing_or_stale_agents: missingAgents,
+                sweep: {
+                    scratch_dirs: sweep.scratch_dirs,
+                    threshold_minutes: sweep.threshold_minutes,
+                    stale_count: sweep.records.filter((r) => r.is_stale).length,
+                    malformed_count: sweep.records.filter((r) => r.failures.length > 0).length,
+                    sweep_errors: sweep.sweep_errors,
+                },
+            },
+        };
+    }
+    if (configError) {
+        const detail = sweep.sweep_errors.join("; ");
+        return {
+            exitCode: EXIT_EXTERNAL_ERROR,
+            redispatchOk: false,
+            message: `verify_subagent_alive: config error — ${detail}`,
+        };
+    }
+    if (!unhealthy) {
+        const count = args.requireAgents.length > 0 ? args.requireAgents.length : sweep.records.length;
+        return {
+            exitCode: EXIT_OK,
+            redispatchOk: false,
+            message: `verify_subagent_alive: all ${count} monitored worker(s) alive`,
+        };
+    }
+    const lines = ["verify_subagent_alive: worker liveness gate FAILED"];
+    if (requiredUnhealthy) {
+        lines.push(`  Missing or STALE required agent(s): ${missingAgents.join(", ")}`);
+    }
+    if (sweepUnhealthy && args.requireAgents.length === 0) {
+        const stale = sweep.records.filter((r) => r.is_stale).length;
+        const malformed = sweep.records.filter((r) => r.failures.length > 0).length;
+        lines.push(`  Sweep: ${stale} stale, ${malformed} malformed record(s)`);
+    }
+    lines.push("");
+    lines.push("REDISPATCH_OK: host-reported running + missing/STALE heartbeat authorizes takeover.");
+    lines.push("Re-dispatch a replacement worker; do not wait on Cursor false-alive state.");
+    return {
+        exitCode: EXIT_STALE,
+        redispatchOk: true,
+        message: lines.join("\n"),
+    };
+}
+export function run(argv) {
+    const args = parseVerifySubagentAliveArgs(argv);
+    if (args.help) {
+        process.stdout.write(SUBAGENT_ALIVE_HELP);
+        return EXIT_OK;
+    }
+    const verdict = evaluateSubagentAliveGate(args);
+    if (args.emitJson && verdict.json !== undefined) {
+        process.stdout.write(`${JSON.stringify(verdict.json, null, 2)}\n`);
+    }
+    else if (verdict.message.length > 0) {
+        if (verdict.exitCode === EXIT_OK) {
+            process.stdout.write(`${verdict.message}\n`);
+        }
+        else {
+            process.stderr.write(`${verdict.message}\n`);
+        }
+    }
+    return verdict.exitCode;
+}
+if (process.argv[1] !== undefined && fileURLToPath(import.meta.url) === process.argv[1]) {
+    process.exit(run(process.argv.slice(2)));
+}
+//# sourceMappingURL=verify-subagent-alive.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deftai/directive",
-  "version": "0.84.0",
+  "version": "0.86.0",
   "description": "Directive CLI — npm install path for the Deft Directive framework.",
   "type": "module",
   "main": "./dist/index.js",
@@ -9,6 +9,7 @@
     "directive": "./dist/bin.js",
     "deft": "./dist/bin.js",
     "deft-ts": "./dist/bin.js",
+    "deft-hook": "./dist/hook-bin.js",
     "deft-verify-encoding": "./dist/verify-encoding.js"
   },
   "exports": {
@@ -31,8 +32,8 @@
     "provenance": true
   },
   "dependencies": {
-    "@deftai/directive-core": "^0.84.0",
-    "@deftai/directive-content": "^0.84.0"
+    "@deftai/directive-core": "^0.86.0",
+    "@deftai/directive-content": "^0.86.0"
   },
   "scripts": {
     "build": "tsc -b"