@deftai/directive 0.119.8 → 0.119.10

package/dist/verify-ac.js

@@ -6,12 +6,13 @@
  * Primary name for the product-first done-gate; verify:literal-ac remains
  * the #3267 mechanism alias.
  */
+import { spawnSync } from "node:child_process";
 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 { emitVerifyAcTerminalOutcome, evaluateVerifyAcFromPath, readPlanAcceptance, resolveAcceptanceGateProfile, } from "@deftai/directive-core/product-first-done-gate";
+import { emitVerifyAcTerminalOutcome, evaluateVerifyAcFromPath, readAdmittedSourceDigest, readAdmittedSourceSentences, readPlanAcceptance, resolveAcceptanceGateProfile, } from "@deftai/directive-core/product-first-done-gate";
 /** Parse verify:ac CLI args. */
 export function parseArgs(argv) {
     const parsed = {
@@ -111,6 +112,84 @@ export function clampVerifyAcExit(ok, code) {
         return 2;
     return 1;
 }
+/**
+ * Spec-path briefs persist the refused GitHub body under plan.metadata.issueBody
+ * (#4524 / #5055), including empty string when the origin body was empty. Live
+ * recovery must use the Bound-remedy harvest (Overview), not body-normative REST.
+ */
+function planHasSpecPathRefusedBody(plan) {
+    const meta = asRecord(plan.metadata);
+    if (meta === null) {
+        return false;
+    }
+    return Object.hasOwn(meta, "issueBody") && typeof meta.issueBody === "string";
+}
+/**
+ * Spec-path admitted source = Overview harvest remainder (#5055).
+ * Fail closed when Overview is empty — do not fall through to the refused body.
+ */
+function fetchSpecPathHarvest(plan) {
+    const narratives = asRecord(plan.narratives);
+    const overview = narratives?.Overview;
+    if (typeof overview === "string" && overview.trim().length > 0) {
+        return { ok: true, text: overview };
+    }
+    return {
+        ok: false,
+        reason: "Spec-path Bound-remedy harvest unavailable (Overview empty); refuse offline / restore from git",
+    };
+}
+/**
+ * Live REST body for the origin issue (body-normative admitted source, #5055).
+ * Fail closed on forge outage — do not skip.
+ */
+function fetchOriginIssueBody(plan) {
+    const refs = Array.isArray(plan.references) ? plan.references : [];
+    let issueUrl = null;
+    for (const entry of refs) {
+        if (typeof entry !== "object" || entry === null || Array.isArray(entry)) {
+            continue;
+        }
+        const row = entry;
+        if (row.type === "x-xbrief/github-issue" && typeof row.uri === "string") {
+            issueUrl = row.uri;
+            break;
+        }
+    }
+    if (issueUrl === null) {
+        return { ok: false, reason: "no github-issue reference on the brief for live REST" };
+    }
+    const match = issueUrl.match(/github\.com\/([^/]+)\/([^/]+)\/issues\/(\d+)/i);
+    if (match === null) {
+        return { ok: false, reason: `unparseable github-issue uri: ${issueUrl}` };
+    }
+    const owner = match[1] ?? "";
+    const repo = match[2] ?? "";
+    const number = match[3] ?? "";
+    const apiPath = `repos/${owner}/${repo}/issues/${number}`;
+    const proc = spawnSync("gh", ["api", apiPath, "--jq", ".body"], {
+        encoding: "utf8",
+        env: process.env,
+    });
+    if (proc.error) {
+        return { ok: false, reason: `forge outage: ${proc.error.message}` };
+    }
+    if (proc.status !== 0) {
+        const detail = `${proc.stderr ?? ""}${proc.stdout ?? ""}`.trim() || `gh api exited ${String(proc.status)}`;
+        return { ok: false, reason: `forge outage: ${detail}` };
+    }
+    return { ok: true, text: typeof proc.stdout === "string" ? proc.stdout : "" };
+}
+/**
+ * Live admitted-source text for digest compare / missing-pin recovery (#5055).
+ * Spec-path → Bound-remedy harvest; body-normative → origin issue body.
+ */
+function fetchAdmittedSourceForPlan(plan) {
+    if (planHasSpecPathRefusedBody(plan)) {
+        return fetchSpecPathHarvest(plan);
+    }
+    return fetchOriginIssueBody(plan);
+}
 /** Evaluate one or many xBRIEF paths; return worst non-zero code (fail closed). */
 function evaluatePaths(paths, options) {
     let worst = 0;
@@ -121,6 +200,28 @@ function evaluatePaths(paths, options) {
         if (!options.quiet && paths.length > 1) {
             process.stdout.write(`verify:ac — evaluating ${path}\n`);
         }
+        let fetchAdmittedSourceText;
+        try {
+            const raw = JSON.parse(readFileSync(path, "utf8"));
+            const root = asRecord(raw);
+            const plan = asRecord(root?.plan);
+            // Arm live admitted-source fetch when a pin is present (digest compare), a
+            // digest remains after pin delete (honor recorded digest), or Spec-path
+            // refused-body metadata marks harvest recovery (#5055). Spec-path callbacks
+            // return the Bound-remedy harvest, not the refused raw issue body. Body-
+            // normative both-deleted recovery prefers git HEAD / merge-base so
+            // pre-#5055 briefs without a pin are not suddenly floored by live REST.
+            if (plan !== null) {
+                const pin = readAdmittedSourceSentences(plan.acceptance);
+                const digest = readAdmittedSourceDigest(plan.acceptance);
+                if (pin !== null || digest !== null || planHasSpecPathRefusedBody(plan)) {
+                    fetchAdmittedSourceText = () => fetchAdmittedSourceForPlan(plan);
+                }
+            }
+        }
+        catch {
+            // Path evaluation still runs; unreadable brief is handled inside evaluateVerifyAcFromPath.
+        }
         const result = evaluateVerifyAcFromPath(path, {
             projectRoot: options.projectRoot,
             quiet: options.quiet,
@@ -129,6 +230,7 @@ function evaluatePaths(paths, options) {
             captureFromNarratives: profile.captureFromNarratives,
             reuseMode: profile.reuseMode,
             env: process.env,
+            ...(fetchAdmittedSourceText !== undefined ? { fetchAdmittedSourceText } : {}),
         });
         if (result.message.length > 0) {
             if (result.ok) {

package/dist/verify-class-checks.d.ts

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+interface ParsedArgs {
+    projectRoot: string;
+    baseRef: string | null;
+    quiet: boolean;
+    error?: string;
+}
+export declare function parseArgs(argv: string[]): ParsedArgs;
+export declare function run(argv: string[]): number;
+export {};
+//# sourceMappingURL=verify-class-checks.d.ts.map

package/dist/verify-class-checks.js

@@ -0,0 +1,71 @@
+#!/usr/bin/env node
+/**
+ * CLI for verify:class-checks (#4980 / #3145 class).
+ */
+import { resolve } from "node:path";
+import { classChecks } from "@deftai/directive-core";
+import { isDirectEntrypoint } from "./entrypoint.js";
+export function parseArgs(argv) {
+    const parsed = {
+        projectRoot: ".",
+        baseRef: null,
+        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 if (arg === "--base-ref") {
+            const value = argv[i + 1];
+            if (value === undefined) {
+                return { ...parsed, error: "argument --base-ref: expected one argument" };
+            }
+            parsed.baseRef = value;
+            i += 1;
+        }
+        else if (arg?.startsWith("--base-ref=")) {
+            parsed.baseRef = arg.slice("--base-ref=".length);
+        }
+        else {
+            return { ...parsed, error: `unrecognized argument: ${arg}` };
+        }
+    }
+    return parsed;
+}
+export function run(argv) {
+    const args = parseArgs(argv);
+    if (args.error !== undefined) {
+        process.stderr.write(`verify_class_checks: ${args.error}\n`);
+        return 2;
+    }
+    const projectRoot = resolve(args.projectRoot);
+    const result = classChecks.evaluateClassChecks(projectRoot, {
+        baseRef: args.baseRef,
+        quiet: args.quiet,
+    });
+    if (result.exitCode === 0) {
+        if (!args.quiet) {
+            process.stdout.write(`${result.message}\n`);
+        }
+    }
+    else {
+        process.stderr.write(`${result.message}\n`);
+    }
+    return result.exitCode;
+}
+if (isDirectEntrypoint(import.meta.url)) {
+    process.exit(run(process.argv.slice(2)));
+}
+//# sourceMappingURL=verify-class-checks.js.map

package/dist/verify-completed-write-guard.js

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+import { spawnSync } from "node:child_process";
 /**
  * CLI for verify:completed-write-guard (#3679).
  */
@@ -55,6 +56,17 @@ export function run(argv) {
     const projectRoot = resolve(args.projectRoot);
     const result = evaluateCompletedWriteGuard(projectRoot, {
         ...(args.baseRef.length > 0 ? { baseRef: args.baseRef } : {}),
+        runGh: (command) => {
+            const proc = spawnSync(command[0] ?? "gh", command.slice(1), {
+                cwd: projectRoot,
+                encoding: "utf8",
+                timeout: 15_000,
+            });
+            return {
+                returncode: proc.status ?? 1,
+                stdout: proc.stdout ?? "",
+            };
+        },
     });
     if (result.message.length > 0 && !args.quiet) {
         if (result.code === 0) {

package/dist/verify-operator-scope-limit.d.ts

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+interface ParsedArgs {
+    promptFile?: string;
+    prompt?: string;
+    surfacesFile?: string;
+    briefOut?: string;
+    artifactOut?: string;
+    projectRoot: string;
+    quiet: boolean;
+    error?: string;
+}
+/** Parse verify-operator-scope-limit CLI args. */
+export declare function parseArgs(argv: string[]): ParsedArgs;
+/** Run the gate and return the process exit code (0 clean/warn, 2 config). */
+export declare function run(argv: string[]): number;
+export {};
+//# sourceMappingURL=verify-operator-scope-limit.d.ts.map

package/dist/verify-operator-scope-limit.js

@@ -0,0 +1,285 @@
+#!/usr/bin/env node
+/**
+ * Warn-first operator scope-limit check (#4545).
+ *
+ * Seeds a hard ceiling from an operator prompt (closed lexicon) and lists
+ * shipped surfaces not traceable to a recorded requirement line. Warn-first:
+ * untraceable surfaces print WARN and exit 0; config errors exit 2.
+ *
+ * Default path always persists a durable ceiling artifact (or merges into
+ * --brief-out). Without --surfaces-file, runs a default app/actions inventory;
+ * empty inventory warns that surfaces were not checked (does not silent-skip).
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { applyCeilingToBrief, evaluateUntraceableSurfaces, inventoryDefaultSurfaces, OPERATOR_SCOPE_CEILING_ARTIFACT_REL, SURFACES_NOT_CHECKED_REMEDIATION, seedOperatorScopeCeiling, UNTRACEABLE_SURFACE_REMEDIATION, } from "@deftai/directive-core/operator-scope-limit";
+/** Parse verify-operator-scope-limit CLI args. */
+export function parseArgs(argv) {
+    const parsed = { quiet: false, projectRoot: "." };
+    for (let i = 0; i < argv.length; i += 1) {
+        const arg = argv[i];
+        if (arg === "--quiet") {
+            parsed.quiet = true;
+        }
+        else if (arg === "--prompt-file") {
+            const value = argv[i + 1];
+            if (value === undefined) {
+                return { ...parsed, error: "argument --prompt-file: expected one argument" };
+            }
+            parsed.promptFile = value;
+            i += 1;
+        }
+        else if (arg?.startsWith("--prompt-file=")) {
+            parsed.promptFile = arg.slice("--prompt-file=".length);
+        }
+        else if (arg === "--prompt") {
+            const value = argv[i + 1];
+            if (value === undefined) {
+                return { ...parsed, error: "argument --prompt: expected one argument" };
+            }
+            parsed.prompt = value;
+            i += 1;
+        }
+        else if (arg?.startsWith("--prompt=")) {
+            parsed.prompt = arg.slice("--prompt=".length);
+        }
+        else if (arg === "--surfaces-file") {
+            const value = argv[i + 1];
+            if (value === undefined) {
+                return { ...parsed, error: "argument --surfaces-file: expected one argument" };
+            }
+            parsed.surfacesFile = value;
+            i += 1;
+        }
+        else if (arg?.startsWith("--surfaces-file=")) {
+            parsed.surfacesFile = arg.slice("--surfaces-file=".length);
+        }
+        else if (arg === "--brief-out") {
+            const value = argv[i + 1];
+            if (value === undefined) {
+                return { ...parsed, error: "argument --brief-out: expected one argument" };
+            }
+            parsed.briefOut = value;
+            i += 1;
+        }
+        else if (arg?.startsWith("--brief-out=")) {
+            parsed.briefOut = arg.slice("--brief-out=".length);
+        }
+        else if (arg === "--artifact-out") {
+            const value = argv[i + 1];
+            if (value === undefined) {
+                return { ...parsed, error: "argument --artifact-out: expected one argument" };
+            }
+            parsed.artifactOut = value;
+            i += 1;
+        }
+        else if (arg?.startsWith("--artifact-out=")) {
+            parsed.artifactOut = arg.slice("--artifact-out=".length);
+        }
+        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;
+}
+function loadPrompt(args) {
+    if (typeof args.prompt === "string") {
+        return { ok: true, prompt: args.prompt };
+    }
+    if (typeof args.promptFile === "string" && args.promptFile.length > 0) {
+        try {
+            return { ok: true, prompt: readFileSync(resolve(args.promptFile), "utf8") };
+        }
+        catch (err) {
+            return {
+                ok: false,
+                detail: `failed to read --prompt-file: ${err instanceof Error ? err.message : String(err)}`,
+            };
+        }
+    }
+    return {
+        ok: false,
+        detail: "required: --prompt <text> or --prompt-file <path>",
+    };
+}
+function loadSurfacesFile(surfacesFile) {
+    try {
+        const raw = readFileSync(resolve(surfacesFile), "utf8");
+        const parsed = JSON.parse(raw);
+        if (!Array.isArray(parsed)) {
+            return { ok: false, detail: "--surfaces-file must be a JSON array" };
+        }
+        const surfaces = [];
+        for (const entry of parsed) {
+            if (entry === null || typeof entry !== "object" || Array.isArray(entry)) {
+                return { ok: false, detail: "--surfaces-file entries must be objects" };
+            }
+            const obj = entry;
+            if ((obj.kind !== "server-action" && obj.kind !== "route" && obj.kind !== "page") ||
+                typeof obj.id !== "string" ||
+                obj.id.trim().length === 0) {
+                return {
+                    ok: false,
+                    detail: "--surfaces-file entries need kind (server-action|route|page) and id",
+                };
+            }
+            surfaces.push({
+                kind: obj.kind,
+                id: obj.id,
+                path: typeof obj.path === "string" ? obj.path : undefined,
+            });
+        }
+        return { ok: true, surfaces };
+    }
+    catch (err) {
+        return {
+            ok: false,
+            detail: `failed to read --surfaces-file: ${err instanceof Error ? err.message : String(err)}`,
+        };
+    }
+}
+function writeJsonFile(path, value) {
+    try {
+        mkdirSync(dirname(path), { recursive: true });
+        writeFileSync(path, `${JSON.stringify(value, null, 2)}\n`, "utf8");
+        return { ok: true };
+    }
+    catch (err) {
+        return {
+            ok: false,
+            detail: `failed to write ${path}: ${err instanceof Error ? err.message : String(err)}`,
+        };
+    }
+}
+function loadExistingBrief(path) {
+    if (!existsSync(path))
+        return null;
+    try {
+        const raw = JSON.parse(readFileSync(path, "utf8"));
+        if (raw === null || typeof raw !== "object" || Array.isArray(raw))
+            return null;
+        return raw;
+    }
+    catch {
+        return null;
+    }
+}
+/** Persist ceiling: explicit outs, else default durable artifact under project root. */
+function persistCeiling(input) {
+    const { projectRoot, ceiling, artifactOut, briefOut } = input;
+    let durablePath = null;
+    if (typeof artifactOut === "string" && artifactOut.length > 0) {
+        const path = resolve(artifactOut);
+        const wrote = writeJsonFile(path, ceiling);
+        if (!wrote.ok)
+            return wrote;
+        durablePath = path;
+    }
+    if (typeof briefOut === "string" && briefOut.length > 0) {
+        const path = resolve(briefOut);
+        const existing = loadExistingBrief(path);
+        const base = existing ??
+            {
+                xBRIEFInfo: { version: "0.8" },
+                plan: { status: "draft", metadata: {} },
+            };
+        // Merge/add ceiling onto existing proposed/active brief — never replace scope.
+        const merged = applyCeilingToBrief(base, ceiling);
+        const wrote = writeJsonFile(path, merged);
+        if (!wrote.ok)
+            return wrote;
+        durablePath = path;
+    }
+    if (durablePath === null) {
+        const path = resolve(projectRoot, OPERATOR_SCOPE_CEILING_ARTIFACT_REL);
+        const wrote = writeJsonFile(path, ceiling);
+        if (!wrote.ok)
+            return wrote;
+        durablePath = path;
+    }
+    return { ok: true, durablePath };
+}
+/** Run the gate and return the process exit code (0 clean/warn, 2 config). */
+export function run(argv) {
+    const args = parseArgs(argv);
+    if (args.error !== undefined) {
+        process.stderr.write(`verify_operator_scope_limit: ${args.error}\n`);
+        return 2;
+    }
+    const projectRoot = resolve(args.projectRoot);
+    const promptLoad = loadPrompt(args);
+    if (!promptLoad.ok) {
+        process.stderr.write(`verify_operator_scope_limit: ${promptLoad.detail}\n`);
+        return 2;
+    }
+    const seeded = seedOperatorScopeCeiling(promptLoad.prompt, null);
+    if (!seeded.ok) {
+        process.stderr.write(`verify_operator_scope_limit: ${seeded.detail}\n`);
+        // No phrase is a returned miss — still exit 2 so callers know ceiling was not recorded.
+        return 2;
+    }
+    const persisted = persistCeiling({
+        projectRoot,
+        ceiling: seeded.ceiling,
+        artifactOut: args.artifactOut,
+        briefOut: args.briefOut,
+    });
+    if (!persisted.ok) {
+        process.stderr.write(`verify_operator_scope_limit: ${persisted.detail}\n`);
+        return 2;
+    }
+    let surfaces = [];
+    let surfacesSource = "default-inventory";
+    if (typeof args.surfacesFile === "string" && args.surfacesFile.length > 0) {
+        const surfacesLoad = loadSurfacesFile(args.surfacesFile);
+        if (!surfacesLoad.ok) {
+            process.stderr.write(`verify_operator_scope_limit: ${surfacesLoad.detail}\n`);
+            return 2;
+        }
+        surfaces = surfacesLoad.surfaces;
+        surfacesSource = "surfaces-file";
+    }
+    else {
+        surfaces = inventoryDefaultSurfaces(projectRoot);
+        surfacesSource = "default-inventory";
+    }
+    if (surfaces.length === 0) {
+        if (!args.quiet) {
+            process.stdout.write(`operator-scope-limit WARN: surfaces were not checked ` +
+                `(source=${surfacesSource}; durable=${persisted.durablePath}; ` +
+                `phrase=${JSON.stringify(seeded.ceiling.matchedPhrase)}; ` +
+                `requirements=${seeded.ceiling.requirementLines.length}). ` +
+                `Remediation: ${SURFACES_NOT_CHECKED_REMEDIATION}\n`);
+        }
+        // Warn-first: missing inventory does not fail the process.
+        return 0;
+    }
+    const result = evaluateUntraceableSurfaces({
+        requirementLines: seeded.ceiling.requirementLines,
+        surfaces,
+    });
+    if (!args.quiet) {
+        process.stdout.write(`${result.message} (durable=${persisted.durablePath}; source=${surfacesSource})\n`);
+        if (result.severity === "warn") {
+            process.stdout.write(`Remediation: ${UNTRACEABLE_SURFACE_REMEDIATION}\n`);
+        }
+    }
+    // Warn-first: untraceable surfaces do not fail the process.
+    return 0;
+}
+if (process.argv[1] !== undefined && fileURLToPath(import.meta.url) === process.argv[1]) {
+    process.exit(run(process.argv.slice(2)));
+}
+//# sourceMappingURL=verify-operator-scope-limit.js.map

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

@@ -9,6 +9,11 @@ interface ParsedArgs {
     approach3: boolean;
     approach3Warned: boolean;
     emitJson: boolean;
+    /** When true, also run the #4882 merge-path arm observer (attested flags). */
+    mergePathArm: boolean;
+    liveWait: boolean;
+    explicitFinish: boolean;
+    stickyLease: boolean;
     help: boolean;
     error?: string;
 }