@deftai/directive 0.119.9 → 0.119.10

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", "authz", "escalation-cli", "pr-closing-keywords", "pr-merge-readiness", "pr-monitor", "pr-protected-issues", "pr-wait-mergeable", "pr-watch", "pr-finish-loop", "directive-finish-loop", "preflight-cache", "preflight-gh", "probe-session", "release", "release-e2e", "release-publish", "release-rollback", "release-wait-npm", "scope-lifecycle", "scope-record-approved-scope", "scope-record-observable-scope", "scope-record-intent-constraint", "scm-sync-default", "lifecycle-event", "lifecycle-stats", "session-start", "session-ready", "occupancy-steal", "occupancy-release", "occupancy-heartbeat", "occupancy-grant", "plan-sequence", "slice", "subagent-monitor", "toolchain-check", "triage-actions", "triage-bootstrap", "triage-bulk", "triage-classify", "triage-strip-withdrawn", "triage-evaluate", "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", "xbrief-create", "xbrief-verify", "xbrief-adopt-stored-plan-id", "verify-branch", "verify-encoding", "verify-forward-coverage", "verify-test-boundary", "verify-class-checks", "verify-scope-provenance", "verify-consumer-check-contract", "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-contained-writes", "verify-telemetry-coverage", "verify-content-manifest", "verify-deposit-closure", "verify-consumer-hard-stops", "verify-closing-keywords", "verify-skill-external-fetch-gate", "verify-semantic-single-source", "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", "verify-spec-prd-fresh", "rule-ownership-lint", "verify-story-ready", "verify-review-monitor", "verify-l4-owner", "verify-subagent-alive", "verify-subagent-steer", "review-monitor-register", "review-monitor-release", "verify-tools", "verify-wip-cap", "verify-orphan-active", "verify-pr-closeout-attestable", "verify-lifecycle-visible", "verify-completed-tracked", "verify-completed-write-guard", "verify-literal-ac", "verify-ac", "verify-agents-md-budget", "verify-agents-md-advisory", "verify-eval-health-relocation", "verify-eval-triggers-relocation", "verify-evaluator-surface", "verify-observable-scope", "verify-intent-constraint", "verify-consumer-test-lane", "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", "authz", "escalation-cli", "pr-closing-keywords", "pr-merge-readiness", "pr-monitor", "pr-protected-issues", "pr-wait-mergeable", "pr-watch", "pr-finish-loop", "directive-finish-loop", "preflight-cache", "preflight-gh", "probe-session", "release", "release-e2e", "release-publish", "release-rollback", "release-wait-npm", "scope-lifecycle", "scope-record-approved-scope", "scope-record-observable-scope", "scope-record-intent-constraint", "scm-sync-default", "lifecycle-event", "lifecycle-stats", "session-start", "session-ready", "occupancy-steal", "occupancy-release", "occupancy-heartbeat", "occupancy-grant", "plan-sequence", "slice", "subagent-monitor", "toolchain-check", "triage-actions", "triage-bootstrap", "triage-bulk", "triage-classify", "triage-strip-withdrawn", "triage-evaluate", "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", "xbrief-create", "xbrief-verify", "xbrief-adopt-stored-plan-id", "verify-branch", "verify-encoding", "verify-forward-coverage", "verify-test-boundary", "verify-class-checks", "verify-scope-provenance", "verify-consumer-check-contract", "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-contained-writes", "verify-telemetry-coverage", "verify-content-manifest", "verify-deposit-closure", "verify-consumer-hard-stops", "verify-closing-keywords", "verify-skill-external-fetch-gate", "verify-semantic-single-source", "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", "verify-spec-prd-fresh", "rule-ownership-lint", "verify-story-ready", "verify-review-monitor", "verify-l4-owner", "verify-subagent-alive", "verify-subagent-steer", "review-monitor-register", "review-monitor-release", "verify-tools", "verify-wip-cap", "verify-orphan-active", "verify-pr-closeout-attestable", "verify-lifecycle-visible", "verify-completed-tracked", "verify-completed-write-guard", "verify-literal-ac", "verify-ac", "verify-agents-md-budget", "verify-agents-md-advisory", "verify-eval-health-relocation", "verify-eval-triggers-relocation", "verify-evaluator-surface", "verify-observable-scope", "verify-operator-scope-limit", "verify-intent-constraint", "verify-consumer-test-lane", "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", "scm-readiness", "github-auth-modes", "github-body", "issue-emit", "issue-ingest", "issue-sync-from-xbrief", "reconcile-issues", "swarm-launch", "swarm-complete-cohort", "swarm-finalize-cohort", "swarm-pre-dispatch", "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", "project-write-narratives", "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", "freshness-report", "decision-write", "decision-list", "docs-impact"];
+export declare const CORE_MODULE_VERBS: readonly ["scm", "scm-readiness", "github-auth-modes", "github-body", "issue-emit", "issue-ingest", "issue-sync-from-xbrief", "reconcile-issues", "swarm-launch", "swarm-complete-cohort", "swarm-finalize-cohort", "swarm-finalize-owed", "swarm-pre-dispatch", "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", "project-write-narratives", "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", "freshness-report", "decision-write", "decision-list", "docs-impact"];
 /** 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

@@ -169,6 +169,7 @@ export const CLI_MODULE_VERBS = [
     "verify-eval-triggers-relocation",
     "verify-evaluator-surface",
     "verify-observable-scope",
+    "verify-operator-scope-limit",
     "verify-intent-constraint",
     "verify-consumer-test-lane",
     "eval-health",
@@ -189,6 +190,7 @@ export const CORE_MODULE_VERBS = [
     "swarm-launch",
     "swarm-complete-cohort",
     "swarm-finalize-cohort",
+    "swarm-finalize-owed",
     "swarm-pre-dispatch",
     "swarm-readiness",
     "swarm-routing-verify",
@@ -328,6 +330,7 @@ export const VERB_ALIASES = {
     "verify:eval-triggers-relocation": "verify-eval-triggers-relocation",
     "verify:evaluator-surface": "verify-evaluator-surface",
     "verify:observable-scope": "verify-observable-scope",
+    "verify:operator-scope-limit": "verify-operator-scope-limit",
     "verify:intent-constraint": "verify-intent-constraint",
     "verify:consumer-test-lane": "verify-consumer-test-lane",
     "verify:hooks-installed": "verify-hooks-installed",
@@ -2455,6 +2458,10 @@ async function loadCoreModuleHandler(verb, io) {
             const { finalizeCohortMain } = await import("@deftai/directive-core/dist/swarm/finalize-cohort-cli.js");
             return finalizeCohortMain;
         }
+        case "swarm-finalize-owed": {
+            const { finalizeOwedMain } = await import("@deftai/directive-core/dist/swarm/finalize-owed-cli.js");
+            return finalizeOwedMain;
+        }
         case "swarm-pre-dispatch": {
             const { preDispatchMain } = await import("@deftai/directive-core/dist/swarm/pre-dispatch-cli.js");
             return preDispatchMain;

package/dist/session-start.d.ts

@@ -4,6 +4,8 @@ import { type PrimaryClaimException, type SessionCeremonyTier, type SessionPostu
 export interface ParsedSessionStartArgs {
     projectRoot: string;
     deferValues: string[];
+    /** #4919: defer finalize-owed session gate with a recorded reason. */
+    deferOwedReason: string | null;
     emitJson: boolean;
     noHistory: boolean;
     readOnly: boolean;

package/dist/session-start.js

@@ -30,6 +30,7 @@ export function parseArgs(argv) {
     const parsed = {
         projectRoot: ".",
         deferValues: [],
+        deferOwedReason: null,
         emitJson: false,
         noHistory: false,
         readOnly: false,
@@ -124,6 +125,21 @@ export function parseArgs(argv) {
             }
             parsed.deferValues.push(value);
         }
+        else if (arg === "--defer-owed") {
+            const value = argv[i + 1];
+            if (value === undefined || value.startsWith("--")) {
+                return { ...parsed, error: "argument --defer-owed: expected one argument" };
+            }
+            parsed.deferOwedReason = value;
+            i += 1;
+        }
+        else if (arg?.startsWith("--defer-owed=")) {
+            const value = arg.slice("--defer-owed=".length);
+            if (value.length === 0 || value.startsWith("--")) {
+                return { ...parsed, error: "argument --defer-owed: expected one argument" };
+            }
+            parsed.deferOwedReason = value;
+        }
         else if (arg === "--task-size" || arg === "--ceremony-task-size") {
             const value = argv[i + 1];
             if (value === undefined) {
@@ -487,6 +503,7 @@ export function run(argv) {
             occupant: args.occupant ?? undefined,
             primaryClaimException: args.primaryClaimException ?? undefined,
             sessionId: args.sessionId ?? undefined,
+            deferOwedReason: args.deferOwedReason,
             ...(args.ceremonyDepthOverride !== null
                 ? {
                     ceremonyDial: selectCeremonyDepth({

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

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import { resolve } from "node:path";
 import { fileURLToPath } from "node:url";
-import { evaluateMergePathArm, } from "@deftai/directive-core/dist/pr-watch/main.js";
+import { bindLivePhaseCorrectWait, evaluateMergePathArm, } from "@deftai/directive-core/dist/pr-watch/main.js";
 import { EXIT_CONFIG_ERROR, EXIT_NOT_READY, evaluateReviewMonitorGate, isTier1, REVIEW_MONITOR_HELP, verifyResultToJson, } from "@deftai/directive-core/review-monitor";
 const CALL_SITES = new Set([
     "solo",
@@ -134,13 +134,15 @@ export function run(argv) {
     const args = parseVerifyReviewMonitorArgs(argv);
     if (args.help) {
         process.stdout.write(REVIEW_MONITOR_HELP);
-        process.stdout.write("\n#4882 merge-path arm observer (optional):\n" +
+        process.stdout.write("\n#4882 / #5020 merge-path arm observer (optional):\n" +
             "  --merge-path-arm       Fail closed when neither live wait nor explicit finish\n" +
-            "  --live-wait            Attest a still-running phase-correct wait for this PR\n" +
-            "                         (Tier 1: bound to gate lease evidence for --pr)\n" +
+            "  --live-wait            Require still-running wait evidence for this PR\n" +
+            "                         (Tier 1: lease + active polling heartbeat with pid liveness;\n" +
+            "                         lease+flag alone is not armed — #5020)\n" +
             "  --explicit-finish      Attest option-C BLOCKED/FAILED finish for this PR\n" +
             "  --sticky-lease         Attest a fresh sticky lease (not sufficient alone)\n" +
-            "  Prefer Approach 1 / native pr:watch; homemade line-parsed --json is not an arm.\n");
+            "  Prefer Approach 1 / native pr:watch or post-CLEAN pr:wait-mergeable-and-merge;\n" +
+            "  homemade line-parsed --json is not an arm.\n");
         return 0;
     }
     if (args.error !== undefined) {
@@ -167,21 +169,29 @@ export function run(argv) {
     });
     let arm = null;
     if (args.mergePathArm) {
-        // Bind --live-wait to gate-observed lease evidence on Tier 1 for this PR.
-        // Bare flags must not arm when Tier 1 requires a lease and none is present.
+        // Bind --live-wait to lease (#5018) + process-liveness heartbeat (#5020) on Tier 1.
         const leaseEvidence = result.monitorRecord !== null;
-        const liveBound = args.liveWait && (!isTier1(result.tier) || leaseEvidence);
+        const liveBind = bindLivePhaseCorrectWait({
+            liveWaitFlag: args.liveWait,
+            tierIs1: isTier1(result.tier),
+            leaseEvidence,
+            heartbeatActive: result.heartbeatActive,
+            pr: args.pr,
+        });
         arm = evaluateMergePathArm({
-            livePhaseCorrectWait: liveBound,
+            livePhaseCorrectWait: liveBind.livePhaseCorrectWait,
             explicitFinish: args.explicitFinish,
             stickyLeaseActive: args.stickyLease || leaseEvidence,
         });
-        if (args.liveWait && !liveBound && !args.explicitFinish && !arm.armed) {
+        if (args.liveWait &&
+            !liveBind.livePhaseCorrectWait &&
+            !args.explicitFinish &&
+            !arm.armed &&
+            liveBind.message !== null) {
             arm = {
                 armed: false,
                 reason: "unarmed_stand_down",
-                message: `unarmed stand-down: --live-wait attestation unbound to lease evidence ` +
-                    `for PR #${args.pr} (Tier 1); sticky lease alone is not a live arm (#4882)`,
+                message: liveBind.message,
             };
         }
     }
@@ -196,6 +206,7 @@ export function run(argv) {
                 explicit_finish: args.explicitFinish,
                 sticky_lease: args.stickyLease,
                 lease_evidence: result.monitorRecord !== null,
+                heartbeat_active: result.heartbeatActive,
             };
             // Combined gate+arm: unarmed fails closed even when the monitor gate is ready.
             if (!arm.armed && result.exitCode !== EXIT_CONFIG_ERROR) {

package/dist/verify-scope-provenance.js

@@ -1,6 +1,10 @@
 #!/usr/bin/env node
 /**
- * CLI for verify:scope-provenance (#3145).
+ * CLI for verify:scope-provenance (#3145 / #4956 / #4774).
+ *
+ * Membership against the declared allowlist (mint / brief file_scope) is
+ * evaluated inside evaluateScopeProvenance; this CLI only forwards
+ * --base-ref / --enforce.
  */
 import { resolve } from "node:path";
 import { scopeProvenance } from "@deftai/directive-core";

package/package.json

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