@deftai/directive 0.103.0 → 0.105.0

package/dist/verify-ac.js

@@ -9,8 +9,9 @@
 import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
+import { resolveSessionCompletedVerifyAcTarget } from "@deftai/directive-core/check";
 import { formatRejectedLedger, resolveLiteralAcceptanceDetailed, } from "@deftai/directive-core/literal-acceptance";
-import { evaluateVerifyAcFromPath, readPlanAcceptance, } from "@deftai/directive-core/product-first-done-gate";
+import { emitVerifyAcTerminalOutcome, evaluateVerifyAcFromPath, readPlanAcceptance, resolveAcceptanceGateProfile, } from "@deftai/directive-core/product-first-done-gate";
 /** Parse verify:ac CLI args. */
 export function parseArgs(argv) {
     const parsed = {
@@ -102,9 +103,20 @@ function listActiveXbriefs(projectRoot) {
         dir: dirs.join(" + "),
     };
 }
+/** Three-state exit: pass=0, fail=1, config=2. A printed pass must not leak 201. */
+export function clampVerifyAcExit(ok, code) {
+    if (ok)
+        return 0;
+    if (code === 2)
+        return 2;
+    return 1;
+}
 /** Evaluate one or many xBRIEF paths; return worst non-zero code (fail closed). */
 function evaluatePaths(paths, options) {
     let worst = 0;
+    // One shared option profile per reader (#3497) — scope:complete resolves its own
+    // profile from the same table, so the two readers cannot drift apart again.
+    const profile = resolveAcceptanceGateProfile(options.softMissingXbrief ? "check" : "standalone");
     for (const path of paths) {
         if (!options.quiet && paths.length > 1) {
             process.stdout.write(`verify:ac — evaluating ${path}\n`);
@@ -113,7 +125,9 @@ function evaluatePaths(paths, options) {
             projectRoot: options.projectRoot,
             quiet: options.quiet,
             softMissingXbrief: options.softMissingXbrief,
-            checkIntegrated: options.softMissingXbrief,
+            checkIntegrated: profile.checkIntegrated,
+            captureFromNarratives: profile.captureFromNarratives,
+            reuseMode: profile.reuseMode,
             env: process.env,
         });
         if (result.message.length > 0) {
@@ -124,9 +138,10 @@ function evaluatePaths(paths, options) {
                 process.stderr.write(`${result.message}\n`);
             }
         }
-        if (result.code !== 0 && (worst === 0 || result.code > worst)) {
+        const code = clampVerifyAcExit(result.ok, result.code);
+        if (code !== 0 && (worst === 0 || code > worst)) {
             // Prefer code 1 (fail) over 2 when both present — still non-zero.
-            worst = result.code;
+            worst = code;
         }
     }
     return worst;
@@ -142,6 +157,11 @@ export function run(argv) {
     const args = parseArgs(argv);
     if (args.error !== undefined) {
         process.stderr.write(`verify_ac: ${args.error}\n`);
+        emitVerifyAcTerminalOutcome({
+            projectRoot: resolve(args.projectRoot),
+            env: process.env,
+            outcome: "config-error",
+        });
         return 2;
     }
     const projectRoot = resolve(args.projectRoot);
@@ -167,19 +187,55 @@ export function run(argv) {
                     "  Pass an explicit path, or use check composition (--soft-missing-xbrief) to evaluate all.\n" +
                     "  Usage: task verify:ac -- <path-to-active.xbrief.json>\n" +
                     "  Refs #3284 product-first done-gate\n");
+                emitVerifyAcTerminalOutcome({
+                    projectRoot,
+                    env: process.env,
+                    outcome: "config-error",
+                });
                 return 1;
             }
         }
         else if (args.softMissingXbrief) {
-            if (!args.quiet) {
+            const completed = resolveSessionCompletedVerifyAcTarget({
+                projectRoot,
+                env: process.env,
+            });
+            if (completed.kind === "target") {
+                paths = [completed.path];
+                if (!args.quiet) {
+                    process.stdout.write(`verify:ac targeting just-completed brief (#3357): ${completed.path}\n`);
+                }
+            }
+            else if (completed.kind === "cannot") {
+                process.stderr.write(`${completed.message}\n`);
+                emitVerifyAcTerminalOutcome({
+                    projectRoot,
+                    env: process.env,
+                    outcome: "config-error",
+                });
+                return 1;
+            }
+            else if (!args.quiet) {
                 process.stdout.write("verify:ac skipped (#3284 soft-missing): no active xBRIEF in xbrief/active/\n");
             }
-            return 0;
+            if (completed.kind === "none") {
+                emitVerifyAcTerminalOutcome({
+                    projectRoot,
+                    env: process.env,
+                    outcome: "soft-missing",
+                });
+                return 0;
+            }
         }
         else {
             process.stderr.write("verify_ac: pass an xBRIEF path or ensure exactly one artifact in xbrief/active/\n" +
                 "  Usage: task verify:ac -- <path-to-active.xbrief.json>\n" +
                 "  Refs #3284 product-first done-gate (mechanism #3267)\n");
+            emitVerifyAcTerminalOutcome({
+                projectRoot,
+                env: process.env,
+                outcome: "config-error",
+            });
             return 2;
         }
     }
@@ -200,14 +256,24 @@ export function run(argv) {
                 }
                 const acceptance = readPlanAcceptance(plan);
                 const resolved = resolveLiteralAcceptanceDetailed(plan, { captureFromNarratives: true });
+                // Executor reads plan.acceptance.commands when the #3267 ledger is empty (#3449).
+                const executorCommands = resolved.commands.length > 0
+                    ? resolved.commands
+                    : acceptance.commands.map((c) => ({
+                        command: c.command,
+                        source: "explicit",
+                        sourceSpan: "plan.acceptance.commands",
+                        cwd: c.cwd ?? null,
+                        expectedExitCode: c.expectedExitCode ?? 0,
+                    }));
                 reports.push({
                     xbrief: xbriefPath,
                     source_rung: acceptance.source_rung,
                     none_stated: acceptance.none_stated,
                     acceptance_commands: acceptance.commands,
-                    count: resolved.commands.length,
+                    count: executorCommands.length,
                     rejected_count: resolved.rejected.length,
-                    commands: resolved.commands.map((c) => ({
+                    commands: executorCommands.map((c) => ({
                         command: c.command,
                         source: c.source,
                         sourceSpan: c.sourceSpan ?? null,

package/dist/verify-completed-tracked.d.ts

@@ -3,11 +3,12 @@ interface ParsedArgs {
     projectRoot: string;
     repo: string | null;
     tip: string | null;
+    issue: number | null;
     quiet: boolean;
     skipGh: boolean;
     error?: string;
 }
-/** Parse verify-completed-tracked CLI args (#3264). */
+/** Parse verify-completed-tracked CLI args (#3264 / #3476). */
 export declare function parseArgs(argv: string[]): ParsedArgs;
 /** Run the gate and return the process exit code. */
 export declare function run(argv: string[]): number;

package/dist/verify-completed-tracked.js

@@ -2,12 +2,21 @@
 import { resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { evaluateCompletedTracked } from "@deftai/directive-core/lifecycle";
-/** Parse verify-completed-tracked CLI args (#3264). */
+function parseIssueNumber(raw) {
+    const trimmed = raw.startsWith("#") ? raw.slice(1) : raw;
+    if (!/^\d+$/.test(trimmed)) {
+        return null;
+    }
+    const value = Number(trimmed);
+    return Number.isInteger(value) && value > 0 ? value : null;
+}
+/** Parse verify-completed-tracked CLI args (#3264 / #3476). */
 export function parseArgs(argv) {
     const parsed = {
         projectRoot: ".",
         repo: null,
         tip: null,
+        issue: null,
         quiet: false,
         skipGh: false,
     };
@@ -52,6 +61,26 @@ export function parseArgs(argv) {
         else if (arg?.startsWith("--tip=")) {
             parsed.tip = arg.slice("--tip=".length);
         }
+        else if (arg === "--issue") {
+            const value = argv[i + 1];
+            if (value === undefined) {
+                return { ...parsed, error: "argument --issue: expected one argument" };
+            }
+            const issue = parseIssueNumber(value);
+            if (issue === null) {
+                return { ...parsed, error: `argument --issue: expected a positive integer, got ${value}` };
+            }
+            parsed.issue = issue;
+            i += 1;
+        }
+        else if (arg?.startsWith("--issue=")) {
+            const value = arg.slice("--issue=".length);
+            const issue = parseIssueNumber(value);
+            if (issue === null) {
+                return { ...parsed, error: `argument --issue: expected a positive integer, got ${value}` };
+            }
+            parsed.issue = issue;
+        }
         else {
             return { ...parsed, error: `unrecognized argument: ${arg}` };
         }
@@ -70,6 +99,7 @@ export function run(argv) {
         quiet: args.quiet,
         repo: args.repo,
         tip: args.tip,
+        issue: args.issue,
         skipGh: args.skipGh,
     });
     if (result.message.length > 0) {

package/dist/verify-literal-ac.js

@@ -128,6 +128,13 @@ export function run(argv) {
                     reason: r.reason,
                     sourceSpan: r.sourceSpan ?? null,
                 })),
+                // Prose-derived captures demoted by structured acceptance commands (#3484).
+                advisory_rejected_count: resolved.advisoryRejected.length,
+                advisory_rejected: resolved.advisoryRejected.map((r) => ({
+                    command: r.command,
+                    reason: r.reason,
+                    sourceSpan: r.sourceSpan ?? null,
+                })),
             };
             process.stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
             if (resolved.rejected.length > 0) {

package/dist/verify-orphan-active.d.ts

@@ -2,6 +2,7 @@
 interface ParsedArgs {
     projectRoot: string;
     repo: string | null;
+    issue: number | null;
     quiet: boolean;
     skipGh: boolean;
     error?: string;

package/dist/verify-orphan-active.js

@@ -2,11 +2,20 @@
 import { resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { evaluate } from "@deftai/directive-core/orphan-active";
+function parseIssueNumber(raw) {
+    const trimmed = raw.startsWith("#") ? raw.slice(1) : raw;
+    if (!/^\d+$/.test(trimmed)) {
+        return null;
+    }
+    const value = Number(trimmed);
+    return Number.isInteger(value) && value > 0 ? value : null;
+}
 /** Parse verify-orphan-active CLI args. */
 export function parseArgs(argv) {
     const parsed = {
         projectRoot: ".",
         repo: null,
+        issue: null,
         quiet: false,
         skipGh: false,
     };
@@ -40,6 +49,26 @@ export function parseArgs(argv) {
         else if (arg?.startsWith("--repo=")) {
             parsed.repo = arg.slice("--repo=".length);
         }
+        else if (arg === "--issue") {
+            const value = argv[i + 1];
+            if (value === undefined) {
+                return { ...parsed, error: "argument --issue: expected one argument" };
+            }
+            const issue = parseIssueNumber(value);
+            if (issue === null) {
+                return { ...parsed, error: `argument --issue: expected a positive integer, got ${value}` };
+            }
+            parsed.issue = issue;
+            i += 1;
+        }
+        else if (arg?.startsWith("--issue=")) {
+            const value = arg.slice("--issue=".length);
+            const issue = parseIssueNumber(value);
+            if (issue === null) {
+                return { ...parsed, error: `argument --issue: expected a positive integer, got ${value}` };
+            }
+            parsed.issue = issue;
+        }
         else {
             return { ...parsed, error: `unrecognized argument: ${arg}` };
         }
@@ -58,6 +87,7 @@ export function run(argv) {
         quiet: args.quiet,
         repo: args.repo,
         skipGh: args.skipGh,
+        issue: args.issue,
     });
     if (result.message.length > 0) {
         if (result.stream === "stdout") {

package/dist/verify-session-ritual.d.ts

@@ -1,5 +1,11 @@
 #!/usr/bin/env node
-import { type DirectivePosture } from "@deftai/directive-core/session";
+import { type DirectivePosture, type VerifyResult } from "@deftai/directive-core/session";
+export interface VerifySessionRitualRunDeps {
+    readonly verifySessionRitual?: (projectRoot: string, options: {
+        tier: "quick" | "gated";
+        posture?: DirectivePosture;
+    }) => VerifyResult;
+}
 interface ParsedArgs {
     projectRoot: string;
     tier: "quick" | "gated";
@@ -9,7 +15,9 @@ interface ParsedArgs {
 }
 /** Parse verify-session-ritual CLI args, mirroring scripts/verify_session_ritual.py. */
 export declare function parseArgs(argv: string[]): ParsedArgs;
+/** True when the ritual failure is the gated cache_fresh step (#3506 / #3507). */
+export declare function isCacheFreshFailureMessage(message: string): boolean;
 /** Run the gate and return the process exit code. */
-export declare function run(argv: string[]): number;
+export declare function run(argv: string[], deps?: VerifySessionRitualRunDeps): number;
 export {};
 //# sourceMappingURL=verify-session-ritual.d.ts.map

package/dist/verify-session-ritual.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import { resolve } from "node:path";
 import { fileURLToPath } from "node:url";
-import { emitBypassWarning, emitVerifyJson, verifySessionRitual, } from "@deftai/directive-core/session";
+import { emitBypassWarning, emitVerifyJson, formatCacheFreshDeferSoftPath, formatRitualRecoveryInstruction, verifySessionRitual, } from "@deftai/directive-core/session";
 function parsePosture(value) {
     if (value === "read-only")
         return "read-only";
@@ -86,15 +86,20 @@ export function parseArgs(argv) {
     }
     return parsed;
 }
+/** True when the ritual failure is the gated cache_fresh step (#3506 / #3507). */
+export function isCacheFreshFailureMessage(message) {
+    return message.includes("cache_fresh") || message.includes("cache-fresh");
+}
 /** Run the gate and return the process exit code. */
-export function run(argv) {
+export function run(argv, deps = {}) {
     const args = parseArgs(argv);
     if (args.error !== undefined) {
         process.stderr.write(`verify_session_ritual: ${args.error}\n`);
         return 2;
     }
     const projectRoot = resolve(args.projectRoot);
-    const result = verifySessionRitual(projectRoot, {
+    const verify = deps.verifySessionRitual ?? verifySessionRitual;
+    const result = verify(projectRoot, {
         tier: args.tier,
         posture: args.posture ?? undefined,
     });
@@ -108,6 +113,14 @@ export function run(argv) {
             process.stdout.write(`${result.message}\n`);
         }
     }
+    else if (result.code === 1) {
+        const recovery = formatRitualRecoveryInstruction(result.recoveryTier ?? "cold");
+        const lines = [result.message, recovery];
+        if (isCacheFreshFailureMessage(result.message)) {
+            lines.push(formatCacheFreshDeferSoftPath());
+        }
+        process.stderr.write(`${lines.join("\n")}\n`);
+    }
     else {
         process.stderr.write(`${result.message}\n`);
     }

package/dist/verify-source-cli/verify-telemetry-coverage.d.ts

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+interface ParsedArgs {
+    projectRoot: string;
+    enforce: boolean;
+    help?: boolean;
+    error?: string;
+}
+/** Parse verify-telemetry-coverage CLI args (#3362). */
+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-telemetry-coverage.d.ts.map

package/dist/verify-source-cli/verify-telemetry-coverage.js

@@ -0,0 +1,67 @@
+#!/usr/bin/env node
+/**
+ * CLI for task verify:telemetry-coverage (#3362).
+ * Warn-only by default; pass --enforce to fail closed.
+ */
+import { resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { evaluateTelemetryCoverage } from "@deftai/directive-core/verify-source";
+/** Parse verify-telemetry-coverage CLI args (#3362). */
+export function parseArgs(argv) {
+    const parsed = { projectRoot: ".", enforce: false };
+    for (let i = 0; i < argv.length; i += 1) {
+        const arg = argv[i];
+        if (arg === "--project-root") {
+            const value = argv[i + 1];
+            if (value === undefined) {
+                return { ...parsed, error: "argument --project-root: expected one argument" };
+            }
+            parsed.projectRoot = value;
+            i += 1;
+        }
+        else if (arg?.startsWith("--project-root=")) {
+            parsed.projectRoot = arg.slice("--project-root=".length);
+        }
+        else if (arg === "--enforce") {
+            parsed.enforce = true;
+        }
+        else if (arg === "--help" || arg === "-h") {
+            return { ...parsed, help: true };
+        }
+        else {
+            return { ...parsed, error: `unrecognized argument: ${arg}` };
+        }
+    }
+    return parsed;
+}
+const HELP_TEXT = "Usage: verify-telemetry-coverage [--project-root <path>] [--enforce]\n" +
+    "  Dead-surface detector for run-summary event kinds (#3362).\n" +
+    "  Default: warn-only (exit 0 with advisory report).\n" +
+    "  --enforce: fail closed (exit 1) when a kind has no caller or fixture.\n";
+/** Run the gate and return the process exit code. */
+export function run(argv) {
+    const args = parseArgs(argv);
+    if (args.help === true) {
+        process.stdout.write(HELP_TEXT);
+        return 0;
+    }
+    if (args.error !== undefined) {
+        process.stderr.write(`verify_telemetry_coverage: ${args.error}\n`);
+        return 2;
+    }
+    const result = evaluateTelemetryCoverage({
+        projectRoot: resolve(args.projectRoot),
+        enforce: args.enforce,
+    });
+    if (result.stream === "stdout") {
+        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-telemetry-coverage.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deftai/directive",
-  "version": "0.103.0",
+  "version": "0.105.0",
   "description": "Directive CLI — npm install path for the Deft Directive framework.",
   "license": "MIT",
   "homepage": "https://deftai.github.io/directive/",
@@ -34,8 +34,8 @@
     "provenance": true
   },
   "dependencies": {
-    "@deftai/directive-core": "^0.103.0",
-    "@deftai/directive-content": "^0.103.0"
+    "@deftai/directive-core": "^0.105.0",
+    "@deftai/directive-content": "^0.105.0"
   },
   "scripts": {
     "build": "tsc -b"