@deftai/directive 0.85.0 → 0.87.0

package/dist/dispatch.d.ts

@@ -10,7 +10,7 @@ export interface DispatchIo {
     writeErr: (text: string) => void;
 }
 /** CLI modules in packages/cli/src (excluding parity harnesses and bin/index). */
-export declare const CLI_MODULE_VERBS: readonly ["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"];
+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-openclaw-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", "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). */

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",
@@ -105,6 +107,7 @@ export const CLI_MODULE_VERBS = [
     "verify-skill-external-fetch-gate",
     "verify-contract-drift",
     "verify-cursor-tier1",
+    "verify-openclaw-tier1",
     "verify-go-freeze",
     "verify-scm-boundary",
     "verify-session-ritual",
@@ -250,6 +253,7 @@ export const VERB_ALIASES = {
     "verify:skill-external-fetch-gate": "verify-skill-external-fetch-gate",
     "verify:contract-drift": "verify-contract-drift",
     "verify:cursor-tier1": "verify-cursor-tier1",
+    "verify:openclaw-tier1": "verify-openclaw-tier1",
     "verify:go-freeze": "verify-go-freeze",
     "verify:bridge-drift": "verify-bridge-drift",
     "verify:scm-boundary": "verify-scm-boundary",
@@ -309,6 +313,7 @@ const SUBDIR_CLI_STEMS = {
     "verify-skill-external-fetch-gate": "verify-source-cli/verify-skill-external-fetch-gate",
     "verify-contract-drift": "verify-source-cli/verify-contract-drift",
     "verify-cursor-tier1": "verify-source-cli/verify-cursor-tier1",
+    "verify-openclaw-tier1": "verify-source-cli/verify-openclaw-tier1",
     "verify-scm-boundary": "verify-source-cli/verify-scm-boundary",
     "verify-xbrief-drift": "verify-source-cli/verify-xbrief-drift",
     "verify-go-freeze": "gates-cli/verify-go-freeze",
@@ -2035,7 +2040,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)
@@ -2049,7 +2055,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}`,

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.js

@@ -1,11 +1,11 @@
 #!/usr/bin/env node
-import { fileURLToPath } from "node:url";
+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 (process.argv[1] !== undefined && fileURLToPath(import.meta.url) === process.argv[1]) {
+if (isDirectEntrypoint(import.meta.url)) {
     process.exit(main());
 }
 //# sourceMappingURL=hook-bin.js.map

package/dist/hook-dispatch.d.ts

@@ -11,13 +11,64 @@ export interface HookDispatchCliSeams {
     readonly writeOut?: (text: string) => void;
     readonly writeErr?: (text: string) => void;
     readonly cwd?: () => string;
+    /**
+     * Sleep between empty-stdin retry polls (#2864). Injected in tests so delayed
+     * payloads can be simulated without real wall-clock waits.
+     */
+    readonly sleepMs?: (ms: number) => void;
+    /**
+     * Empty-stdin retry budget in ms (default {@link DEFAULT_STDIN_EMPTY_RETRY_MS}).
+     * Set `0` to disable retries (single read). Tests for true-empty paths often
+     * set this to 0 for speed; delayed-payload tests set a positive budget.
+     */
+    readonly stdinEmptyRetryMs?: number;
+    /** Clock for empty-stdin deadline; defaults to `Date.now` (tests inject synthetic clocks). */
+    readonly nowMs?: () => number;
 }
+/**
+ * How long to re-poll stdin after an empty first read before concluding the host
+ * sent nothing (#2864). Keeps well under Cursor's deposited `timeout: 5` while
+ * covering short non-blocking delivery races (reporter matrix rows K/L).
+ */
+export declare const DEFAULT_STDIN_EMPTY_RETRY_MS = 250;
+/** Interval between empty-stdin re-polls while the retry budget remains. */
+export declare const STDIN_EMPTY_RETRY_INTERVAL_MS = 25;
+/**
+ * Read hook stdin with a short empty-read retry budget (#2864).
+ *
+ * A single `readFileSync(0)` on a non-blocking descriptor can return zero bytes
+ * before the host has attached a writer. That is indistinguishable from a true
+ * empty payload if we never re-poll. We re-read for up to `emptyRetryMs`; true
+ * empty (every poll empty through the budget) still yields empty for the deny
+ * path. Delayed payloads that arrive within the budget are accepted.
+ */
+export declare function readStdinHardened(readOnce: () => string, options?: {
+    emptyRetryMs?: number;
+    sleepMs?: (ms: number) => void;
+    nowMs?: () => number;
+}): string;
 export declare function parseArgs(argv: readonly string[]): ParsedArgs;
 export interface ParsedPayload {
     readonly payload: unknown;
     readonly context: HookPayloadContext;
 }
 export declare function parsePayload(raw: string): ParsedPayload;
+/**
+ * Provider-neutral hook dispatch CLI entry (`deft hook:dispatch` / `deft-hook`).
+ *
+ * ## Exit-code contract (#2864)
+ *
+ * | Exit | Meaning |
+ * |------|---------|
+ * | `0`  | A host decision was rendered to stdout (allow **or** deny). Hosts must parse stdout; exit status does **not** encode the verdict. |
+ * | `2`  | Argv / configuration error (unsupported host/event, missing flags, unrecognized args). |
+ *
+ * This process never returns `1` for a rendered verdict. Cursor `failClosed`
+ * deposits that report "exit code 1" are therefore process-level failures
+ * (crash, signal kill under host timeout, spawn environment), not `run()` deny
+ * paths. Empty-stdin denies still exit `0` with a Cursor JSON body carrying
+ * `code: "stdin-empty"`.
+ */
 export declare function run(argv: string[], seams?: HookDispatchCliSeams): number;
 export {};
 //# sourceMappingURL=hook-dispatch.d.ts.map

package/dist/hook-dispatch.js

@@ -3,6 +3,52 @@ import { readFileSync } from "node:fs";
 import { resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { decideHook, hookPayloadTopLevelKeys, isHookEvent, isHookHost, normalizeHookProjectRoot, projectRootFromHookPayload, renderHostDecision, } from "@deftai/directive-core/hooks";
+/**
+ * How long to re-poll stdin after an empty first read before concluding the host
+ * sent nothing (#2864). Keeps well under Cursor's deposited `timeout: 5` while
+ * covering short non-blocking delivery races (reporter matrix rows K/L).
+ */
+export const DEFAULT_STDIN_EMPTY_RETRY_MS = 250;
+/** Interval between empty-stdin re-polls while the retry budget remains. */
+export const STDIN_EMPTY_RETRY_INTERVAL_MS = 25;
+function defaultSleepMs(ms) {
+    if (ms <= 0)
+        return;
+    try {
+        Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+    }
+    catch {
+        const end = Date.now() + ms;
+        while (Date.now() < end) {
+            /* spin — last-resort fallback when Atomics.wait is unavailable */
+        }
+    }
+}
+/**
+ * Read hook stdin with a short empty-read retry budget (#2864).
+ *
+ * A single `readFileSync(0)` on a non-blocking descriptor can return zero bytes
+ * before the host has attached a writer. That is indistinguishable from a true
+ * empty payload if we never re-poll. We re-read for up to `emptyRetryMs`; true
+ * empty (every poll empty through the budget) still yields empty for the deny
+ * path. Delayed payloads that arrive within the budget are accepted.
+ */
+export function readStdinHardened(readOnce, options = {}) {
+    const emptyRetryMs = options.emptyRetryMs ?? DEFAULT_STDIN_EMPTY_RETRY_MS;
+    const sleepMs = options.sleepMs ?? defaultSleepMs;
+    const nowMs = options.nowMs ?? (() => Date.now());
+    let raw = readOnce();
+    if (raw.trim().length > 0 || emptyRetryMs <= 0)
+        return raw;
+    const deadline = nowMs() + emptyRetryMs;
+    while (nowMs() < deadline) {
+        sleepMs(STDIN_EMPTY_RETRY_INTERVAL_MS);
+        raw = readOnce();
+        if (raw.trim().length > 0)
+            return raw;
+    }
+    return raw;
+}
 function takeValue(argv, index, flag) {
     const token = argv[index];
     const prefix = `${flag}=`;
@@ -111,6 +157,22 @@ export function parsePayload(raw) {
         return { payload: {}, context: { parseFailed: true } };
     }
 }
+/**
+ * Provider-neutral hook dispatch CLI entry (`deft hook:dispatch` / `deft-hook`).
+ *
+ * ## Exit-code contract (#2864)
+ *
+ * | Exit | Meaning |
+ * |------|---------|
+ * | `0`  | A host decision was rendered to stdout (allow **or** deny). Hosts must parse stdout; exit status does **not** encode the verdict. |
+ * | `2`  | Argv / configuration error (unsupported host/event, missing flags, unrecognized args). |
+ *
+ * This process never returns `1` for a rendered verdict. Cursor `failClosed`
+ * deposits that report "exit code 1" are therefore process-level failures
+ * (crash, signal kill under host timeout, spawn environment), not `run()` deny
+ * paths. Empty-stdin denies still exit `0` with a Cursor JSON body carrying
+ * `code: "stdin-empty"`.
+ */
 export function run(argv, seams = {}) {
     const args = parseArgs(argv);
     const writeOut = seams.writeOut ?? ((text) => process.stdout.write(text));
@@ -119,9 +181,14 @@ export function run(argv, seams = {}) {
         writeErr(`${args.error ?? "invalid hook-dispatch arguments"}\n`);
         return 2;
     }
-    const readStdin = seams.readStdin ?? (() => readFileSync(0, "utf8"));
+    const readOnce = seams.readStdin ?? (() => readFileSync(0, "utf8"));
+    const rawStdin = readStdinHardened(readOnce, {
+        emptyRetryMs: seams.stdinEmptyRetryMs,
+        sleepMs: seams.sleepMs,
+        nowMs: seams.nowMs,
+    });
     const cwd = (seams.cwd ?? process.cwd)();
-    const { payload, context: payloadContext } = parsePayload(readStdin());
+    const { payload, context: payloadContext } = parsePayload(rawStdin);
     const projectRoot = normalizeHookProjectRoot(args.projectRoot ? resolve(args.projectRoot) : projectRootFromHookPayload(payload, cwd));
     const decision = decideHook({
         host: args.host,
@@ -133,12 +200,16 @@ export function run(argv, seams = {}) {
     const rendered = renderHostDecision(args.host, decision);
     if (rendered.length > 0)
         writeOut(`${rendered}\n`);
-    if (decision.code === "invalid-input" && args.host === "cursor") {
+    if ((decision.code === "invalid-input" || decision.code === "stdin-empty") &&
+        args.host === "cursor") {
         // Keys are already embedded in decision.message; stderr helps operators tailing logs.
         const keys = hookPayloadTopLevelKeys(payload);
         if (keys.length > 0) {
             writeErr(`Directive hook diagnostic: payload top-level keys: ${keys.join(", ")}\n`);
         }
+        else if (decision.code === "stdin-empty") {
+            writeErr("Directive hook diagnostic: stdin was empty after empty-read retry budget\n");
+        }
     }
     if (decision.code === "session-start-degraded")
         writeErr(`${decision.message}\n`);

package/dist/review-monitor-register.js

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
 import { resolve } from "node:path";
 import { fileURLToPath } from "node:url";
-import { REGISTER_HELP, registerReviewMonitor, } from "@deftai/directive-core/review-monitor";
-const PRIMITIVES = new Set(["start_agent", "spawn_subagent", "cursor-task"]);
+import { PLATFORM_PRIMITIVE_SET, REGISTER_HELP, registerReviewMonitor, } from "@deftai/directive-core/review-monitor";
+const PRIMITIVES = PLATFORM_PRIMITIVE_SET;
 export function parseRegisterArgs(argv) {
     const acc = {
         pr: null,

package/dist/triage-queue.d.ts

@@ -1,23 +1,34 @@
 #!/usr/bin/env node
 import { type LiveOpenIssuesReader } from "@deftai/directive-core/dist/triage/queue/index.js";
-interface ParsedArgs {
+export type ShowFormat = "default" | "operator";
+interface CommonArgs {
     projectRoot: string;
     repo: string | null;
+    cacheRoot: string | null;
+    auditLog: string | null;
+    error?: string;
+}
+interface QueueArgs extends CommonArgs {
+    cmd: "queue";
     limit: number;
     includeBlocked: boolean;
     reconcile: boolean;
-    cacheRoot: string | null;
-    auditLog: string | null;
     slicesLog: string | null;
-    error?: string;
 }
-/** Parse triage-queue CLI args for the queue subcommand. */
-export declare function parseArgs(argv: string[]): ParsedArgs;
+interface ShowArgs extends CommonArgs {
+    cmd: "show";
+    number: number | null;
+    format: ShowFormat;
+}
+/** Parse triage-queue CLI args (queue subcommand — default). */
+export declare function parseArgs(argv: string[]): QueueArgs;
+/** Parse show subcommand args. */
+export declare function parseShowArgs(argv: string[]): ShowArgs;
 /** 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. */
+/** Run triage:queue or triage:show and return process exit code. */
 export declare function run(argv: string[], options?: RunOptions): number;
 export {};
 //# sourceMappingURL=triage-queue.d.ts.map

package/dist/triage-queue.js

@@ -1,20 +1,88 @@
 #!/usr/bin/env node
+/**
+ * triage:queue / triage:show CLI (#1128 / #2890).
+ *
+ * Subcommands:
+ *   queue  — ranked queue (default when first token is not show/audit)
+ *   show   — per-issue detail; --format=operator for Phase 3 brief backbone
+ *
+ * audit remains routed here by Taskfile; not reimplemented in this story.
+ */
 import { resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { ensureTriageCacheHydrated } from "@deftai/directive-core/dist/cache/empty-populate.js";
+import { findByIssue } from "@deftai/directive-core/dist/triage/actions/candidates-log.js";
 import { resolveTriageCachePath } from "@deftai/directive-core/dist/triage/cache-path.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 { activeReferencedIssueNumbers, buildQueue, collectOrphanIssueNumbers, DEFAULT_QUEUE_LIMIT, loadCachedIssueDetail, loadCachedIssues, loadSliceRecords, readAuditEntries, reconcileLiveOpenState, renderOperatorBrief, renderQueue, renderShow, 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) {
-    const parsed = {
+function baseArgs() {
+    return {
         projectRoot: process.env.DEFT_PROJECT_ROOT ?? ".",
         repo: process.env.DEFT_TRIAGE_REPO ?? null,
+        cacheRoot: null,
+        auditLog: null,
+    };
+}
+function parseCommonFlag(arg, argv, i, parsed) {
+    if (arg === "--project-root") {
+        const value = argv[i + 1];
+        if (value === undefined) {
+            return { consumed: 0, error: "argument --project-root: expected one argument" };
+        }
+        parsed.projectRoot = value;
+        return { consumed: 1 };
+    }
+    if (arg?.startsWith("--project-root=")) {
+        parsed.projectRoot = arg.slice("--project-root=".length);
+        return { consumed: 0 };
+    }
+    if (arg === "--repo") {
+        const value = argv[i + 1];
+        if (value === undefined) {
+            return { consumed: 0, error: "argument --repo: expected one argument" };
+        }
+        parsed.repo = value;
+        return { consumed: 1 };
+    }
+    if (arg?.startsWith("--repo=")) {
+        parsed.repo = arg.slice("--repo=".length);
+        return { consumed: 0 };
+    }
+    if (arg === "--cache-root") {
+        const value = argv[i + 1];
+        if (value === undefined) {
+            return { consumed: 0, error: "argument --cache-root: expected one argument" };
+        }
+        parsed.cacheRoot = value;
+        return { consumed: 1 };
+    }
+    if (arg?.startsWith("--cache-root=")) {
+        parsed.cacheRoot = arg.slice("--cache-root=".length);
+        return { consumed: 0 };
+    }
+    if (arg === "--audit-log") {
+        const value = argv[i + 1];
+        if (value === undefined) {
+            return { consumed: 0, error: "argument --audit-log: expected one argument" };
+        }
+        parsed.auditLog = value;
+        return { consumed: 1 };
+    }
+    if (arg?.startsWith("--audit-log=")) {
+        parsed.auditLog = arg.slice("--audit-log=".length);
+        return { consumed: 0 };
+    }
+    return null;
+}
+/** Parse triage-queue CLI args (queue subcommand — default). */
+export function parseArgs(argv) {
+    const common = baseArgs();
+    const parsed = {
+        ...common,
+        cmd: "queue",
         limit: DEFAULT_QUEUE_LIMIT,
         includeBlocked: false,
         reconcile: true,
-        cacheRoot: null,
-        auditLog: null,
         slicesLog: null,
     };
     for (let i = 0; i < argv.length; i += 1) {
@@ -30,30 +98,12 @@ export function parseArgs(argv) {
             parsed.reconcile = false;
             continue;
         }
-        if (arg === "--project-root") {
-            const value = argv[i + 1];
-            if (value === undefined) {
-                return { ...parsed, error: "argument --project-root: expected one argument" };
+        const commonHit = parseCommonFlag(arg, argv, i, parsed);
+        if (commonHit !== null) {
+            if (commonHit.error !== undefined) {
+                return { ...parsed, error: commonHit.error };
             }
-            parsed.projectRoot = value;
-            i += 1;
-            continue;
-        }
-        if (arg?.startsWith("--project-root=")) {
-            parsed.projectRoot = arg.slice("--project-root=".length);
-            continue;
-        }
-        if (arg === "--repo") {
-            const value = argv[i + 1];
-            if (value === undefined) {
-                return { ...parsed, error: "argument --repo: expected one argument" };
-            }
-            parsed.repo = value;
-            i += 1;
-            continue;
-        }
-        if (arg?.startsWith("--repo=")) {
-            parsed.repo = arg.slice("--repo=".length);
+            i += commonHit.consumed;
             continue;
         }
         if (arg === "--limit") {
@@ -78,54 +128,90 @@ export function parseArgs(argv) {
             parsed.limit = parsedLimit;
             continue;
         }
-        if (arg === "--cache-root") {
+        if (arg === "--slices-log") {
             const value = argv[i + 1];
             if (value === undefined) {
-                return { ...parsed, error: "argument --cache-root: expected one argument" };
+                return { ...parsed, error: "argument --slices-log: expected one argument" };
             }
-            parsed.cacheRoot = value;
+            parsed.slicesLog = value;
             i += 1;
             continue;
         }
-        if (arg?.startsWith("--cache-root=")) {
-            parsed.cacheRoot = arg.slice("--cache-root=".length);
+        if (arg?.startsWith("--slices-log=")) {
+            parsed.slicesLog = arg.slice("--slices-log=".length);
             continue;
         }
-        if (arg === "--audit-log") {
-            const value = argv[i + 1];
-            if (value === undefined) {
-                return { ...parsed, error: "argument --audit-log: expected one argument" };
-            }
-            parsed.auditLog = value;
-            i += 1;
-            continue;
+        if (arg?.startsWith("-")) {
+            return { ...parsed, error: `unrecognized argument: ${arg}` };
         }
-        if (arg?.startsWith("--audit-log=")) {
-            parsed.auditLog = arg.slice("--audit-log=".length);
+    }
+    return parsed;
+}
+/** Parse show subcommand args. */
+export function parseShowArgs(argv) {
+    const common = baseArgs();
+    const parsed = {
+        ...common,
+        cmd: "show",
+        number: null,
+        format: "default",
+    };
+    // Skip leading "show" token if present
+    let start = 0;
+    if (argv[0] === "show") {
+        start = 1;
+    }
+    for (let i = start; i < argv.length; i += 1) {
+        const arg = argv[i];
+        const commonHit = parseCommonFlag(arg, argv, i, parsed);
+        if (commonHit !== null) {
+            if (commonHit.error !== undefined) {
+                return { ...parsed, error: commonHit.error };
+            }
+            i += commonHit.consumed;
             continue;
         }
-        if (arg === "--slices-log") {
+        if (arg === "--format") {
             const value = argv[i + 1];
             if (value === undefined) {
-                return { ...parsed, error: "argument --slices-log: expected one argument" };
+                return { ...parsed, error: "argument --format: expected one argument" };
             }
-            parsed.slicesLog = value;
+            if (value !== "default" && value !== "operator" && value !== "plain" && value !== "text") {
+                return {
+                    ...parsed,
+                    error: `argument --format: invalid choice: '${value}' (choose from default, operator)`,
+                };
+            }
+            parsed.format = value === "operator" ? "operator" : "default";
             i += 1;
             continue;
         }
-        if (arg?.startsWith("--slices-log=")) {
-            parsed.slicesLog = arg.slice("--slices-log=".length);
+        if (arg?.startsWith("--format=")) {
+            const value = arg.slice("--format=".length);
+            if (value !== "default" && value !== "operator" && value !== "plain" && value !== "text") {
+                return {
+                    ...parsed,
+                    error: `argument --format: invalid choice: '${value}' (choose from default, operator)`,
+                };
+            }
+            parsed.format = value === "operator" ? "operator" : "default";
             continue;
         }
         if (arg?.startsWith("-")) {
             return { ...parsed, error: `unrecognized argument: ${arg}` };
         }
+        // positional issue number — strict positive int (reject "42abc" / "42.5")
+        if (!/^[1-9]\d*$/u.test(arg ?? "")) {
+            return { ...parsed, error: `argument number: invalid int value: '${arg}'` };
+        }
+        parsed.number = Number(arg);
+    }
+    if (parsed.number === null && parsed.error === undefined) {
+        return { ...parsed, error: "triage:show: issue number is required (e.g. triage:show -- 42)" };
     }
     return parsed;
 }
-/** Run triage:queue and return process exit code. */
-export function run(argv, options = {}) {
-    const args = parseArgs(argv);
+function runQueue(args, options = {}) {
     if (args.error !== undefined) {
         process.stderr.write(`triage_queue: ${args.error}\n`);
         return 2;
@@ -138,10 +224,6 @@ export function run(argv, options = {}) {
     }
     ensureTriageCacheHydrated(projectRoot, { repo });
     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;
@@ -177,6 +259,69 @@ export function run(argv, options = {}) {
     })}\n`);
     return 0;
 }
+function runShow(args) {
+    if (args.error !== undefined) {
+        process.stderr.write(`triage:show: ${args.error}\n`);
+        return 2;
+    }
+    const projectRoot = resolve(args.projectRoot);
+    const repo = resolveRepo(args.repo, projectRoot);
+    if (repo === null) {
+        process.stderr.write("triage:show: --repo OWNER/NAME (or $DEFT_TRIAGE_REPO) is required.\n");
+        return 2;
+    }
+    const number = args.number;
+    if (number === null) {
+        process.stderr.write("triage:show: issue number is required\n");
+        return 2;
+    }
+    const cacheRoot = args.cacheRoot !== null && args.cacheRoot.length > 0 ? resolve(args.cacheRoot) : null;
+    ensureTriageCacheHydrated(projectRoot, {
+        repo,
+        ...(cacheRoot !== null ? { cacheRoot } : {}),
+    });
+    const issue = loadCachedIssueDetail(repo, number, {
+        projectRoot,
+        cacheRoot,
+    });
+    const logPath = args.auditLog ?? resolveTriageCachePath(projectRoot, "candidates.jsonl");
+    const history = findByIssue(number, repo, logPath)
+        .slice()
+        .sort((a, b) => String(a.timestamp ?? "").localeCompare(String(b.timestamp ?? "")));
+    const latest = history.length > 0 ? (history[history.length - 1] ?? null) : null;
+    const activeRefs = activeReferencedIssueNumbers(projectRoot);
+    const inActive = activeRefs.has(number);
+    if (args.format === "operator") {
+        process.stdout.write(`${renderOperatorBrief({
+            issue,
+            repo,
+            number,
+            latestDecision: latest,
+            inActiveXbrief: inActive,
+        })}\n`);
+    }
+    else {
+        process.stdout.write(`${renderShow({
+            issue,
+            repo,
+            number,
+            latestDecision: latest,
+            history,
+            inActiveXbrief: inActive,
+        })}\n`);
+    }
+    return issue !== null ? 0 : 1;
+}
+/** Run triage:queue or triage:show and return process exit code. */
+export function run(argv, options = {}) {
+    const first = argv[0];
+    if (first === "show") {
+        return runShow(parseShowArgs(argv));
+    }
+    // Other subcommands (e.g. audit) keep prior queue-module routing until
+    // separately ported; only `show` is specialized here (#2890).
+    return runQueue(parseArgs(argv), options);
+}
 if (process.argv[1] !== undefined && fileURLToPath(import.meta.url) === process.argv[1]) {
     process.exit(run(process.argv.slice(2)));
 }

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-source-cli/verify-openclaw-tier1.d.ts

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

package/dist/verify-source-cli/verify-openclaw-tier1.js

@@ -0,0 +1,51 @@
+#!/usr/bin/env node
+import { resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { evaluateOpenclawTier1 } from "@deftai/directive-core/verify-source";
+/** Parse verify-openclaw-tier1 CLI args (#2875). */
+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_openclaw_tier1: ${args.error}\n`);
+        return 2;
+    }
+    const result = evaluateOpenclawTier1(resolve(args.projectRoot), { quiet: args.quiet });
+    if (result.code === 0) {
+        if (!args.quiet && result.message.length > 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-openclaw-tier1.js.map

package/package.json

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