@deftai/directive 0.118.0 → 0.119.0

package/dist/authz.js

@@ -24,6 +24,7 @@
  */
 import { existsSync } from "node:fs";
 import { isAbsolute, resolve } from "node:path";
+import { onePrUnit } from "@deftai/directive-core";
 import { AFK_TEMPLATE_NAMES, AUTHZ_OPERATIONS, CLOSED_VERB_TEMPLATE_NAMES, FINISH_LOOP_TEMPLATE_NAME, formatDecomposeStructuralMintCommand, isAfkTemplateName, isClosedVerbTemplateName, isFinishLoopTemplateName, mintAfkTemplateGrant, mintDecomposeStructuralApplyGrant, mintHumanOriginGrant, revokeGrant, showAuthzSnapshot, startUatLease, suspendUatLease, toProjectRelativePosix, } from "@deftai/directive-core/authz";
 import { refuseMintWhileUatActive, refuseNonInteractiveMint, resolveHumanPresenceMintSeams, } from "./human-presence-mint.js";
 export { AUTHZ_AGENT_SHELL_ENV_MARKERS, AUTHZ_INTERACTIVE_CONFIRM_PHRASE, } from "./human-presence-mint.js";
@@ -416,6 +417,35 @@ export function main(argv = process.argv.slice(2), seams = {}) {
                         "  Authorization SoT: Wave 1 grant store (.deft/authz/grants) — not session-auth.\n");
                     return 0;
                 }
+                if (args.template !== null && args.template.trim().toLowerCase() === "one-pr-unit") {
+                    if (args.repo === null || args.repo.trim().length === 0) {
+                        process.stderr.write("authz:grant --template one-pr-unit requires --repo owner/name\n");
+                        return 2;
+                    }
+                    if (args.issueIds.length < 2) {
+                        process.stderr.write("authz:grant --template one-pr-unit requires --issue-ids with at least two origins\n");
+                        return 2;
+                    }
+                    const blocked = gateConfirm();
+                    if (blocked !== null)
+                        return blocked;
+                    if ((process.env.DEFT_ONE_PR_UNIT_APP ?? "").trim().length === 0) {
+                        process.stderr.write("authz:grant --template one-pr-unit requires DEFT_ONE_PR_UNIT_APP (durable Directive App store). " +
+                            "The in-process simulator is test-only and is discarded on process exit.\n");
+                        return 2;
+                    }
+                    const claim = onePrUnit.mintOnePrUnitGrant({
+                        actor: args.actor,
+                        approvalRef: args.note ?? "authz:grant --template one-pr-unit",
+                        rationale: args.note ?? "one-PR-unit",
+                        origins: args.issueIds.map((issueId) => ({ repo: args.repo, issueId })),
+                        repo: args.repo,
+                    });
+                    process.stdout.write(`✓ one-PR-unit claim minted id=${claim.id} state=${claim.state} (reserved unbound)\n`);
+                    process.stdout.write("  Opaque id is not a bearer. Only the App store plus the bound PR node id authorizes.\n");
+                    process.stdout.write(`  origins=${claim.origins.map((o) => `${o.repo}#${o.issueId}`).join(",")}\n`);
+                    return 0;
+                }
                 // AFK template path (#1095 / #871): presets only — still mintHumanOriginGrant.
                 if (args.template !== null && args.template.trim().length > 0) {
                     if (!isAfkTemplateName(args.template)) {

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

@@ -190,6 +190,12 @@ function routeNamespaceVerb(ns, verb, rest) {
         if (verb === "record-approved-scope") {
             return { kind: "dispatch", argv: ["scope-record-approved-scope", ...rest] };
         }
+        if (verb === "record-observable-scope") {
+            return { kind: "dispatch", argv: ["scope-record-observable-scope", ...rest] };
+        }
+        if (verb === "record-intent-constraint") {
+            return { kind: "dispatch", argv: ["scope-record-intent-constraint", ...rest] };
+        }
     }
     if (ns === "verify") {
         const verifyStem = VERIFY_VERB_MAP[verb];

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", "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", "scope-lifecycle", "scope-record-approved-scope", "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", "verify-branch", "verify-encoding", "verify-forward-coverage", "verify-test-boundary", "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-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", "verify-branch", "verify-encoding", "verify-forward-coverage", "verify-test-boundary", "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"];
 /** 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", "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). */

package/dist/dispatch.js

@@ -67,8 +67,11 @@ export const CLI_MODULE_VERBS = [
     "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",
@@ -162,6 +165,8 @@ export const CLI_MODULE_VERBS = [
     "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",
@@ -294,6 +299,8 @@ export const VERB_ALIASES = {
     "verify:test-boundary": "verify-test-boundary",
     "verify:scope-provenance": "verify-scope-provenance",
     "scope:record-approved-scope": "scope-record-approved-scope",
+    "scope:record-observable-scope": "scope-record-observable-scope",
+    "scope:record-intent-constraint": "scope-record-intent-constraint",
     "verify:consumer-check-contract": "verify-consumer-check-contract",
     "coverage:hotspots": "coverage-hotspots",
     "verify:branch": "verify-branch",
@@ -313,6 +320,8 @@ export const VERB_ALIASES = {
     "verify:eval-health-relocation": "verify-eval-health-relocation",
     "verify:eval-triggers-relocation": "verify-eval-triggers-relocation",
     "verify:evaluator-surface": "verify-evaluator-surface",
+    "verify:observable-scope": "verify-observable-scope",
+    "verify:intent-constraint": "verify-intent-constraint",
     "verify:consumer-test-lane": "verify-consumer-test-lane",
     "verify:hooks-installed": "verify-hooks-installed",
     "verify:no-task-runtime": "verify-no-task-runtime",
@@ -424,6 +433,7 @@ export const VERB_ALIASES = {
     "scm:status": "scm-readiness",
     "scm:readiness": "scm-readiness",
     "scm:sync-default": "scm-sync-default",
+    "release:wait-npm": "release-wait-npm",
 };
 /** CLI modules living under verify-source-cli/ or content-validate-cli/ subdirs. */
 const SUBDIR_CLI_STEMS = {
@@ -2640,6 +2650,8 @@ const SCOPE_COMMAND_NAMES = [
     "scope:demote",
     "scope:undo",
     "scope:record-approved-scope",
+    "scope:record-observable-scope",
+    "scope:record-intent-constraint",
 ];
 /**
  * Deduplicated command names for `directive commands`, preferring colon-style

package/dist/release-wait-npm.d.ts

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

package/dist/release-wait-npm.js

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+import { fileURLToPath } from "node:url";
+import { cmdReleaseWaitNpm } from "@deftai/directive-core/dist/release/cli-drift-report.js";
+export function run(argv) {
+    return cmdReleaseWaitNpm(argv);
+}
+if (process.argv[1] !== undefined && fileURLToPath(import.meta.url) === process.argv[1]) {
+    process.exit(run(process.argv.slice(2)));
+}
+//# sourceMappingURL=release-wait-npm.js.map

package/dist/scope-record-intent-constraint.d.ts

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+import { type HumanPresenceMintSeams } from "./human-presence-mint.js";
+export interface ParsedArgs {
+    projectRoot: string;
+    xbriefPath: string;
+    actor: string;
+    kind: string;
+    quiet: boolean;
+    confirm: boolean;
+    help?: boolean;
+    error?: string;
+}
+export declare function parseArgs(argv: string[]): ParsedArgs;
+export declare function run(argv: string[], seams?: HumanPresenceMintSeams): number;
+//# sourceMappingURL=scope-record-intent-constraint.d.ts.map

package/dist/scope-record-intent-constraint.js

@@ -0,0 +1,178 @@
+#!/usr/bin/env node
+/**
+ * CLI for scope:record-intent-constraint (#4541).
+ *
+ * Human-presence mint of `.deft/intent-constraint/<plan-id>.json` from
+ * `plan["x-directive/intentConstraint"]`. --actor is display-only.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { basename, relative, resolve } from "node:path";
+import { buildIntentConstraintRecord, extractIntentConstraintFromPlan, parseIntentConstraintContract, writeIntentConstraintRecord, } from "@deftai/directive-core/intent-constraint";
+import { isDirectEntrypoint } from "./entrypoint.js";
+import { refuseMintWhileUatActive, refuseNonInteractiveMint, resolveHumanPresenceMintSeams, } from "./human-presence-mint.js";
+import { isPathInsideRoot } from "./scope-record-approved-scope.js";
+function usage() {
+    return ("usage: scope:record-intent-constraint -- <xbrief-path> --actor <name> --confirm " +
+        "[--kind operator] [--project-root <dir>] [--quiet]\n" +
+        '  Writes .deft/intent-constraint/<plan-id>.json from plan["x-directive/intentConstraint"].\n' +
+        "  --actor is display only and never authorizes mint. Mint requires a real TTY, " +
+        "controlling terminal, --confirm, and typed phrase mint (#3110). Agent/CI shells refuse.");
+}
+function extractPlanId(payload) {
+    if (payload === null || typeof payload !== "object" || Array.isArray(payload))
+        return null;
+    const plan = payload.plan;
+    if (plan === null || typeof plan !== "object" || Array.isArray(plan))
+        return null;
+    const id = plan.id;
+    return typeof id === "string" && id.trim().length > 0 ? id.trim() : null;
+}
+export function parseArgs(argv) {
+    const parsed = {
+        projectRoot: ".",
+        xbriefPath: "",
+        actor: "",
+        kind: "operator",
+        quiet: false,
+        confirm: false,
+    };
+    const positionals = [];
+    for (let i = 0; i < argv.length; i += 1) {
+        const arg = argv[i];
+        if (arg === "--")
+            continue;
+        if (arg === "--help" || arg === "-h")
+            return { ...parsed, help: true };
+        if (arg === "--quiet")
+            parsed.quiet = true;
+        else if (arg === "--confirm")
+            parsed.confirm = 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 === "--actor") {
+            const value = argv[i + 1];
+            if (value === undefined)
+                return { ...parsed, error: "argument --actor: expected one argument" };
+            parsed.actor = value;
+            i += 1;
+        }
+        else if (arg?.startsWith("--actor=")) {
+            parsed.actor = arg.slice("--actor=".length);
+        }
+        else if (arg === "--kind") {
+            const value = argv[i + 1];
+            if (value === undefined)
+                return { ...parsed, error: "argument --kind: expected one argument" };
+            parsed.kind = value;
+            i += 1;
+        }
+        else if (arg?.startsWith("--kind=")) {
+            parsed.kind = arg.slice("--kind=".length);
+        }
+        else if (arg?.startsWith("-")) {
+            return { ...parsed, error: `unrecognized argument: ${arg}` };
+        }
+        else if (arg !== undefined) {
+            positionals.push(arg);
+        }
+    }
+    if (parsed.help)
+        return parsed;
+    if (positionals.length === 0)
+        return { ...parsed, error: `missing xBRIEF path\n${usage()}` };
+    if (positionals.length > 1) {
+        return { ...parsed, error: `unexpected extra args: ${positionals.slice(1).join(" ")}` };
+    }
+    parsed.xbriefPath = positionals[0] ?? "";
+    if (parsed.actor.trim().length === 0) {
+        return {
+            ...parsed,
+            error: `argument --actor is required (human operator identity)\n${usage()}`,
+        };
+    }
+    return parsed;
+}
+export function run(argv, seams = {}) {
+    const args = parseArgs(argv);
+    if (args.help) {
+        process.stdout.write(`${usage()}\n`);
+        return 0;
+    }
+    if (args.error !== undefined) {
+        process.stderr.write(`scope_record_intent_constraint: ${args.error}\n`);
+        return 2;
+    }
+    const projectRoot = resolve(args.projectRoot);
+    const uat = refuseMintWhileUatActive("scope:record-intent-constraint", projectRoot);
+    if (uat !== null)
+        return uat;
+    const resolved = resolveHumanPresenceMintSeams(seams);
+    const refused = refuseNonInteractiveMint({
+        verb: "scope:record-intent-constraint",
+        confirm: args.confirm,
+        isTty: resolved.isTty,
+        environ: resolved.environ,
+        hasControllingTerminal: resolved.hasControllingTerminal,
+        readInteractiveConfirm: resolved.readInteractiveConfirm,
+    });
+    if (refused !== null)
+        return refused;
+    const xbriefAbs = resolve(projectRoot, args.xbriefPath);
+    const fullPath = existsSync(xbriefAbs) ? xbriefAbs : resolve(args.xbriefPath);
+    if (!existsSync(fullPath)) {
+        process.stderr.write(`scope_record_intent_constraint: xBRIEF not found: ${args.xbriefPath}\n`);
+        return 2;
+    }
+    if (!isPathInsideRoot(projectRoot, fullPath)) {
+        process.stderr.write("scope_record_intent_constraint: xBRIEF path escapes --project-root.\n");
+        return 2;
+    }
+    let payload;
+    const rawText = readFileSync(fullPath, "utf8");
+    try {
+        payload = JSON.parse(rawText);
+    }
+    catch (err) {
+        process.stderr.write(`scope_record_intent_constraint: invalid JSON: ${String(err)}\n`);
+        return 2;
+    }
+    const planId = extractPlanId(payload) ?? basename(fullPath, ".xbrief.json");
+    const contract = parseIntentConstraintContract(extractIntentConstraintFromPlan(payload));
+    if ("error" in contract) {
+        process.stderr.write(`scope_record_intent_constraint: ${contract.error}\n`);
+        return 2;
+    }
+    const rel = relative(projectRoot, fullPath).replace(/\\/g, "/");
+    const rec = buildIntentConstraintRecord({
+        planId,
+        xbriefRelPath: rel.startsWith("xbrief/pending/") ? `xbrief/active/${basename(rel)}` : rel,
+        constraints: contract.constraints,
+        humanApproval: {
+            kind: args.kind,
+            actor: args.actor,
+            mintedAt: new Date().toISOString().replace(/\.\d{3}Z$/, "Z"),
+            mintedVia: "scope:record-intent-constraint",
+        },
+    });
+    if ("error" in rec) {
+        process.stderr.write(`scope_record_intent_constraint: ${rec.error}\n`);
+        return 2;
+    }
+    const path = writeIntentConstraintRecord(projectRoot, rec);
+    if (!args.quiet) {
+        process.stdout.write(`Wrote ${path}\nCommit this record on the merge base before the implementation change PR.\n`);
+    }
+    return 0;
+}
+if (isDirectEntrypoint(import.meta.url)) {
+    process.exit(run(process.argv.slice(2)));
+}
+//# sourceMappingURL=scope-record-intent-constraint.js.map

package/dist/scope-record-observable-scope.d.ts

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+import { type HumanPresenceMintSeams } from "./human-presence-mint.js";
+export interface ParsedArgs {
+    projectRoot: string;
+    xbriefPath: string;
+    actor: string;
+    kind: string;
+    quiet: boolean;
+    confirm: boolean;
+    help?: boolean;
+    error?: string;
+}
+export declare function parseArgs(argv: string[]): ParsedArgs;
+export declare function run(argv: string[], seams?: HumanPresenceMintSeams): number;
+//# sourceMappingURL=scope-record-observable-scope.d.ts.map

package/dist/scope-record-observable-scope.js

@@ -0,0 +1,180 @@
+#!/usr/bin/env node
+/**
+ * CLI for scope:record-observable-scope (#4495).
+ *
+ * Human-presence mint of `.deft/observable-scope/<plan-id>.json` from
+ * `plan["x-directive/observableChange"]`. --actor is display-only.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { basename, relative, resolve } from "node:path";
+import { buildObservableScopeRecord, extractObservableChangeFromPlan, parseObservableChangeContract, writeObservableScopeRecord, } from "@deftai/directive-core/observable-scope";
+import { isDirectEntrypoint } from "./entrypoint.js";
+import { refuseMintWhileUatActive, refuseNonInteractiveMint, resolveHumanPresenceMintSeams, } from "./human-presence-mint.js";
+import { isPathInsideRoot } from "./scope-record-approved-scope.js";
+function usage() {
+    return ("usage: scope:record-observable-scope -- <xbrief-path> --actor <name> --confirm " +
+        "[--kind operator] [--project-root <dir>] [--quiet]\n" +
+        '  Writes .deft/observable-scope/<plan-id>.json from plan["x-directive/observableChange"].\n' +
+        "  --actor is display only and never authorizes mint. Mint requires a real TTY, " +
+        "controlling terminal, --confirm, and typed phrase mint (#3110). Agent/CI shells refuse.");
+}
+function extractPlanId(payload) {
+    if (payload === null || typeof payload !== "object" || Array.isArray(payload))
+        return null;
+    const plan = payload.plan;
+    if (plan === null || typeof plan !== "object" || Array.isArray(plan))
+        return null;
+    const id = plan.id;
+    return typeof id === "string" && id.trim().length > 0 ? id.trim() : null;
+}
+export function parseArgs(argv) {
+    const parsed = {
+        projectRoot: ".",
+        xbriefPath: "",
+        actor: "",
+        kind: "operator",
+        quiet: false,
+        confirm: false,
+    };
+    const positionals = [];
+    for (let i = 0; i < argv.length; i += 1) {
+        const arg = argv[i];
+        if (arg === "--")
+            continue;
+        if (arg === "--help" || arg === "-h")
+            return { ...parsed, help: true };
+        if (arg === "--quiet")
+            parsed.quiet = true;
+        else if (arg === "--confirm")
+            parsed.confirm = 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 === "--actor") {
+            const value = argv[i + 1];
+            if (value === undefined)
+                return { ...parsed, error: "argument --actor: expected one argument" };
+            parsed.actor = value;
+            i += 1;
+        }
+        else if (arg?.startsWith("--actor=")) {
+            parsed.actor = arg.slice("--actor=".length);
+        }
+        else if (arg === "--kind") {
+            const value = argv[i + 1];
+            if (value === undefined)
+                return { ...parsed, error: "argument --kind: expected one argument" };
+            parsed.kind = value;
+            i += 1;
+        }
+        else if (arg?.startsWith("--kind=")) {
+            parsed.kind = arg.slice("--kind=".length);
+        }
+        else if (arg?.startsWith("-")) {
+            return { ...parsed, error: `unrecognized argument: ${arg}` };
+        }
+        else if (arg !== undefined) {
+            positionals.push(arg);
+        }
+    }
+    if (parsed.help)
+        return parsed;
+    if (positionals.length === 0)
+        return { ...parsed, error: `missing xBRIEF path\n${usage()}` };
+    if (positionals.length > 1) {
+        return { ...parsed, error: `unexpected extra args: ${positionals.slice(1).join(" ")}` };
+    }
+    parsed.xbriefPath = positionals[0] ?? "";
+    if (parsed.actor.trim().length === 0) {
+        return {
+            ...parsed,
+            error: `argument --actor is required (human operator identity)\n${usage()}`,
+        };
+    }
+    return parsed;
+}
+export function run(argv, seams = {}) {
+    const args = parseArgs(argv);
+    if (args.help) {
+        process.stdout.write(`${usage()}\n`);
+        return 0;
+    }
+    if (args.error !== undefined) {
+        process.stderr.write(`scope_record_observable_scope: ${args.error}\n`);
+        return 2;
+    }
+    const projectRoot = resolve(args.projectRoot);
+    const uat = refuseMintWhileUatActive("scope:record-observable-scope", projectRoot);
+    if (uat !== null)
+        return uat;
+    const resolved = resolveHumanPresenceMintSeams(seams);
+    const refused = refuseNonInteractiveMint({
+        verb: "scope:record-observable-scope",
+        confirm: args.confirm,
+        isTty: resolved.isTty,
+        environ: resolved.environ,
+        hasControllingTerminal: resolved.hasControllingTerminal,
+        readInteractiveConfirm: resolved.readInteractiveConfirm,
+    });
+    if (refused !== null)
+        return refused;
+    const xbriefAbs = resolve(projectRoot, args.xbriefPath);
+    const fullPath = existsSync(xbriefAbs) ? xbriefAbs : resolve(args.xbriefPath);
+    if (!existsSync(fullPath)) {
+        process.stderr.write(`scope_record_observable_scope: xBRIEF not found: ${args.xbriefPath}\n`);
+        return 2;
+    }
+    if (!isPathInsideRoot(projectRoot, fullPath)) {
+        process.stderr.write("scope_record_observable_scope: xBRIEF path escapes --project-root.\n");
+        return 2;
+    }
+    let payload;
+    const rawText = readFileSync(fullPath, "utf8");
+    try {
+        payload = JSON.parse(rawText);
+    }
+    catch (err) {
+        process.stderr.write(`scope_record_observable_scope: invalid JSON: ${String(err)}\n`);
+        return 2;
+    }
+    const planId = extractPlanId(payload) ?? basename(fullPath, ".xbrief.json");
+    const contract = parseObservableChangeContract(extractObservableChangeFromPlan(payload));
+    if ("error" in contract) {
+        process.stderr.write(`scope_record_observable_scope: ${contract.error}\n`);
+        return 2;
+    }
+    const rel = relative(projectRoot, fullPath).replace(/\\/g, "/");
+    const rec = buildObservableScopeRecord({
+        planId,
+        xbriefRelPath: rel.startsWith("xbrief/pending/") ? `xbrief/active/${basename(rel)}` : rel,
+        allowedChanges: contract.allowedChanges,
+        mustPreserve: contract.mustPreserve,
+        changeKind: contract.changeKind,
+        humanApproval: {
+            kind: args.kind,
+            actor: args.actor,
+            mintedAt: new Date().toISOString().replace(/\.\d{3}Z$/, "Z"),
+            mintedVia: "scope:record-observable-scope",
+        },
+    });
+    if ("error" in rec) {
+        process.stderr.write(`scope_record_observable_scope: ${rec.error}\n`);
+        return 2;
+    }
+    const path = writeObservableScopeRecord(projectRoot, rec);
+    if (!args.quiet) {
+        process.stdout.write(`Wrote ${path}\nCommit this record on the merge base before the UI change PR.\n`);
+    }
+    return 0;
+}
+if (isDirectEntrypoint(import.meta.url)) {
+    process.exit(run(process.argv.slice(2)));
+}
+//# sourceMappingURL=scope-record-observable-scope.js.map

package/dist/session-start.d.ts

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import { type CeremonyDepth, type CeremonyDialInputs } from "@deftai/directive-core/policy";
-import { type PrimaryClaimException, type SessionCeremonyTier } from "@deftai/directive-core/session";
+import { type PrimaryClaimException, type SessionCeremonyTier, type SessionPosture } from "@deftai/directive-core/session";
 export interface ParsedSessionStartArgs {
     projectRoot: string;
     deferValues: string[];
@@ -43,6 +43,8 @@ export interface ParsedSessionStartArgs {
     primaryClaimException: PrimaryClaimException | null;
     /** #3611: explicit lifecycle owner injected by a host hook bridge. */
     sessionId: string | null;
+    /** Trusted --posture argv (#4444). */
+    posture: SessionPosture | null;
     error?: string;
 }
 /** Parse session:start CLI args, mirroring scripts/session_start.py. */

package/dist/session-start.js

@@ -2,7 +2,7 @@
 import { resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { CEREMONY_DEPTHS, normalizeCeremonyModelTier, normalizeCeremonyProjectShape, normalizeCeremonyTaskSize, selectCeremonyDepth, } from "@deftai/directive-core/policy";
-import { COLD_CEREMONY_TIER, PRIMARY_CLAIM_EXCEPTIONS, parseDeferrals, READ_ONLY_POSTURE, REARM_CEREMONY_TIER, resolveProductionHostEffortDescriptor, ritualStatePath, runSessionStart, SESSION_CEREMONY_TIERS, } from "@deftai/directive-core/session";
+import { COLD_CEREMONY_TIER, PRIMARY_CLAIM_EXCEPTIONS, parseDeferrals, parseSessionPostureToken, READ_ONLY_POSTURE, REARM_CEREMONY_TIER, REQUIREMENTS_POSTURE, resolveProductionHostEffortDescriptor, ritualStatePath, runSessionStart, SESSION_CEREMONY_TIERS, } from "@deftai/directive-core/session";
 function parseCeremonyDepth(raw) {
     const value = raw.trim().toLowerCase();
     if (CEREMONY_DEPTHS.includes(value)) {
@@ -44,6 +44,7 @@ export function parseArgs(argv) {
         occupant: null,
         primaryClaimException: null,
         sessionId: null,
+        posture: null,
     };
     const dialInputs = {};
     for (let i = 0; i < argv.length; i += 1) {
@@ -372,6 +373,53 @@ export function parseArgs(argv) {
             }
             parsed.occupant = value;
         }
+        else if (arg === "--posture") {
+            const value = argv[i + 1];
+            if (value === undefined || value.startsWith("--")) {
+                return {
+                    ...parsed,
+                    error: "argument --posture: expected one argument (read-only|mutation|requirements)",
+                };
+            }
+            const parsedPosture = parseSessionPostureToken(value);
+            if (parsedPosture.error !== null) {
+                return { ...parsed, error: parsedPosture.error };
+            }
+            if (parsedPosture.token === "assist") {
+                return {
+                    ...parsed,
+                    error: "argument --posture=docs|assist is scratch-only; set DEFT_SESSION_POSTURE=assist. Tracked docs use --posture=requirements",
+                };
+            }
+            if (parsedPosture.token === null) {
+                return {
+                    ...parsed,
+                    error: "argument --posture: expected one argument (read-only|mutation|requirements)",
+                };
+            }
+            parsed.posture = parsedPosture.token;
+            i += 1;
+        }
+        else if (arg?.startsWith("--posture=")) {
+            const value = arg.slice("--posture=".length);
+            const parsedPosture = parseSessionPostureToken(value);
+            if (parsedPosture.error !== null) {
+                return { ...parsed, error: parsedPosture.error };
+            }
+            if (parsedPosture.token === "assist") {
+                return {
+                    ...parsed,
+                    error: "argument --posture=docs|assist is scratch-only; set DEFT_SESSION_POSTURE=assist. Tracked docs use --posture=requirements",
+                };
+            }
+            if (parsedPosture.token === null) {
+                return {
+                    ...parsed,
+                    error: "argument --posture: expected one argument (read-only|mutation|requirements)",
+                };
+            }
+            parsed.posture = parsedPosture.token;
+        }
         else {
             return { ...parsed, error: `unrecognized argument: ${arg}` };
         }
@@ -427,7 +475,7 @@ export function run(argv) {
         result = runSessionStart(projectRoot, {
             deferrals,
             writeHistory: !args.noHistory,
-            posture: args.readOnly ? READ_ONLY_POSTURE : undefined,
+            posture: args.readOnly ? READ_ONLY_POSTURE : (args.posture ?? undefined),
             allowOptionalNetwork: args.withNetwork ? true : undefined,
             ceremonyTier: args.ceremonyTier,
             ceremonyDialInputs: args.ceremonyDialInputs,
@@ -474,7 +522,7 @@ export function run(argv) {
     }
     if (result.code === 0) {
         const posture = result.payload.posture;
-        if (posture === READ_ONLY_POSTURE) {
+        if (posture === READ_ONLY_POSTURE || posture === REQUIREMENTS_POSTURE) {
             process.stdout.write(`[deft] ${String(result.payload.message)}\n`);
         }
         else {

package/dist/verify-intent-constraint.d.ts

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+interface ParsedArgs {
+    projectRoot: string;
+    originRef?: string;
+    staged: boolean;
+    quiet: boolean;
+    planId?: string;
+    error?: string;
+}
+/** Parse verify-intent-constraint CLI args. */
+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-intent-constraint.d.ts.map

package/dist/verify-intent-constraint.js

@@ -0,0 +1,86 @@
+#!/usr/bin/env node
+import { resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { evaluateIntentConstraint } from "@deftai/directive-core/intent-constraint";
+/** Parse verify-intent-constraint CLI args. */
+export function parseArgs(argv) {
+    const parsed = { projectRoot: ".", staged: false, quiet: false };
+    for (let i = 0; i < argv.length; i += 1) {
+        const arg = argv[i];
+        if (arg === "--quiet") {
+            parsed.quiet = true;
+        }
+        else if (arg === "--staged") {
+            parsed.staged = 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 === "--origin-ref") {
+            const value = argv[i + 1];
+            if (value === undefined) {
+                return { ...parsed, error: "argument --origin-ref: expected one argument" };
+            }
+            parsed.originRef = value;
+            i += 1;
+        }
+        else if (arg?.startsWith("--origin-ref=")) {
+            parsed.originRef = arg.slice("--origin-ref=".length);
+        }
+        else if (arg === "--plan-id") {
+            const value = argv[i + 1];
+            if (value === undefined) {
+                return { ...parsed, error: "argument --plan-id: expected one argument" };
+            }
+            parsed.planId = value;
+            i += 1;
+        }
+        else if (arg?.startsWith("--plan-id=")) {
+            parsed.planId = arg.slice("--plan-id=".length);
+        }
+        else if (arg === "--base-ref") {
+            return {
+                ...parsed,
+                error: "unrecognized argument: --base-ref (baseline is the computed merge base; use --origin-ref to name the origin default)",
+            };
+        }
+        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_intent_constraint: ${args.error}\n`);
+        return 2;
+    }
+    const result = evaluateIntentConstraint({
+        projectRoot: resolve(args.projectRoot),
+        originRef: args.originRef,
+        staged: args.staged,
+        quiet: args.quiet,
+        planId: args.planId,
+    });
+    if (result.message.length > 0) {
+        if (result.stream === "stdout")
+            process.stdout.write(`${result.message}\n`);
+        else if (result.stream === "stderr")
+            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-intent-constraint.js.map

package/dist/verify-observable-scope.d.ts

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+interface ParsedArgs {
+    projectRoot: string;
+    originRef?: string;
+    staged: boolean;
+    quiet: boolean;
+    planId?: string;
+    error?: string;
+}
+/** Parse verify-observable-scope CLI args. */
+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-observable-scope.d.ts.map

package/dist/verify-observable-scope.js

@@ -0,0 +1,86 @@
+#!/usr/bin/env node
+import { resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { evaluateObservableScope } from "@deftai/directive-core/observable-scope";
+/** Parse verify-observable-scope CLI args. */
+export function parseArgs(argv) {
+    const parsed = { projectRoot: ".", staged: false, quiet: false };
+    for (let i = 0; i < argv.length; i += 1) {
+        const arg = argv[i];
+        if (arg === "--quiet") {
+            parsed.quiet = true;
+        }
+        else if (arg === "--staged") {
+            parsed.staged = 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 === "--origin-ref") {
+            const value = argv[i + 1];
+            if (value === undefined) {
+                return { ...parsed, error: "argument --origin-ref: expected one argument" };
+            }
+            parsed.originRef = value;
+            i += 1;
+        }
+        else if (arg?.startsWith("--origin-ref=")) {
+            parsed.originRef = arg.slice("--origin-ref=".length);
+        }
+        else if (arg === "--plan-id") {
+            const value = argv[i + 1];
+            if (value === undefined) {
+                return { ...parsed, error: "argument --plan-id: expected one argument" };
+            }
+            parsed.planId = value;
+            i += 1;
+        }
+        else if (arg?.startsWith("--plan-id=")) {
+            parsed.planId = arg.slice("--plan-id=".length);
+        }
+        else if (arg === "--base-ref") {
+            return {
+                ...parsed,
+                error: "unrecognized argument: --base-ref (baseline is the computed merge base; use --origin-ref to name the origin default)",
+            };
+        }
+        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_observable_scope: ${args.error}\n`);
+        return 2;
+    }
+    const result = evaluateObservableScope({
+        projectRoot: resolve(args.projectRoot),
+        originRef: args.originRef,
+        staged: args.staged,
+        quiet: args.quiet,
+        planId: args.planId,
+    });
+    if (result.message.length > 0) {
+        if (result.stream === "stdout")
+            process.stdout.write(`${result.message}\n`);
+        else if (result.stream === "stderr")
+            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-observable-scope.js.map

package/dist/verify-pr-closeout-attestable.d.ts

@@ -4,6 +4,7 @@ interface ParsedArgs {
     repo: string | null;
     pr: number | null;
     quiet: boolean;
+    onePrUnitId: string | null;
     error?: string;
 }
 /** Parse verify-pr-closeout-attestable CLI args. */

package/dist/verify-pr-closeout-attestable.js

@@ -12,7 +12,13 @@ function parsePrNumber(raw) {
 }
 /** Parse verify-pr-closeout-attestable CLI args. */
 export function parseArgs(argv) {
-    const parsed = { projectRoot: ".", repo: null, pr: null, quiet: false };
+    const parsed = {
+        projectRoot: ".",
+        repo: null,
+        pr: null,
+        quiet: false,
+        onePrUnitId: null,
+    };
     for (let i = 0; i < argv.length; i += 1) {
         const arg = argv[i];
         if (arg === "--quiet") {
@@ -60,6 +66,17 @@ export function parseArgs(argv) {
             }
             parsed.pr = pr;
         }
+        else if (arg === "--one-pr-unit") {
+            const value = argv[i + 1];
+            if (value === undefined) {
+                return { ...parsed, error: "argument --one-pr-unit: expected one argument" };
+            }
+            parsed.onePrUnitId = value;
+            i += 1;
+        }
+        else if (arg?.startsWith("--one-pr-unit=")) {
+            parsed.onePrUnitId = arg.slice("--one-pr-unit=".length);
+        }
         else {
             return { ...parsed, error: `unrecognized argument: ${arg}` };
         }
@@ -79,6 +96,7 @@ export function run(argv) {
     const result = evaluate(resolve(args.projectRoot), args.pr, {
         repo: args.repo,
         quiet: args.quiet,
+        onePrUnitId: args.onePrUnitId,
     });
     if (result.message.length > 0) {
         if (result.stream === "stdout") {

package/dist/verify-source-cli/verify-closing-keywords.js

@@ -118,12 +118,12 @@ export function resolveClosingKeywordsSource(env, runGit = defaultRunGit) {
 export function buildClosingKeywordsCheckArgv(env, extra = [], runGit = defaultRunGit) {
     const source = resolveClosingKeywordsSource(env, runGit);
     if (source.kind === "pr") {
-        return { argv: ["--mode", "fp", "--pr", source.pr, ...extra] };
+        return { argv: ["--mode", "both", "--pr", source.pr, ...extra] };
     }
     if (source.kind === "missing-base" || source.kind === "stale-base") {
         return { argv: [], error: source.reason };
     }
-    return { argv: ["--mode", "fp", "--from-git-range", source.range, ...extra] };
+    return { argv: ["--mode", "both", "--from-git-range", source.range, ...extra] };
 }
 export function run(argv, env = process.env, invoke = cmdPrCheckClosingKeywords, runGit = defaultRunGit) {
     const built = buildClosingKeywordsCheckArgv(env, argv, runGit);

package/dist/verify-story-ready.js

@@ -2,7 +2,7 @@
 import { readFileSync } from "node:fs";
 import { resolve } from "node:path";
 import { fileURLToPath } from "node:url";
-import { evaluate, gitPorcelain, parseAllocationSection } from "@deftai/directive-core/story-ready";
+import { evaluate, gitPorcelain, gitRevParseAbbrev, parseAllocationSection, } from "@deftai/directive-core/story-ready";
 import { ROUTING_GATED_DISPATCH_PROVIDERS, resolveDispatchProvider, verifyRouting, } from "@deftai/directive-core/swarm";
 /** Parse verify-story-ready CLI args, mirroring the Python argparse surface. */
 export function parseArgs(argv) {
@@ -149,6 +149,7 @@ export function run(argv) {
         allowDirty: args.allowDirty,
         parsed,
         projectRoot,
+        onePrUnitBranch: gitRevParseAbbrev(projectRoot),
     });
     if (result.exitCode === 0 && !args.skipRouting) {
         const provider = resolveDispatchProvider(process.env);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deftai/directive",
-  "version": "0.118.0",
+  "version": "0.119.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.118.0",
-    "@deftai/directive-content": "^0.118.0"
+    "@deftai/directive-core": "^0.119.0",
+    "@deftai/directive-content": "^0.119.0"
   },
   "scripts": {
     "build": "tsc -b"