@deftai/directive 0.98.0 → 0.98.1

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

@@ -188,6 +188,9 @@ function routeNamespaceVerb(ns, verb, rest) {
             return { kind: "dispatch", argv: ["scope-decompose", ...rest] };
         if (verb === "undo")
             return { kind: "dispatch", argv: ["scope-undo", ...rest] };
+        if (verb === "record-approved-scope") {
+            return { kind: "dispatch", argv: ["scope-record-approved-scope", ...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", "lifecycle-event", "lifecycle-stats", "session-start", "session-ready", "plan-sequence", "slice", "subagent-monitor", "toolchain-check", "triage-actions", "triage-bootstrap", "triage-bulk", "triage-classify", "triage-help", "triage-queue", "triage-reconcile", "triage-refresh", "triage-scope", "triage-scope-drift", "triage-smoketest", "triage-subscribe", "triage-summary", "triage-welcome", "ts-check-lane", "vbrief-activate", "vbrief-build", "vbrief-preflight", "vbrief-reconcile", "vbrief-validate", "vbrief-validation", "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-content-manifest", "verify-skill-external-fetch-gate", "verify-contract-drift", "verify-cursor-tier1", "verify-openclaw-tier1", "verify-go-freeze", "verify-scm-boundary", "verify-session-ritual", "verify-plan-sequence", "verify-stubs", "verify-xbrief-drift", "rule-ownership-lint", "verify-story-ready", "verify-review-monitor", "verify-l4-owner", "verify-subagent-alive", "review-monitor-register", "review-monitor-release", "verify-tools", "verify-wip-cap", "verify-orphan-active", "verify-agents-md-budget", "verify-agents-md-advisory", "verify-eval-health-relocation", "verify-eval-triggers-relocation", "eval-health", "eval-run", "eval-report", "eval-triggers"];
+export declare const CLI_MODULE_VERBS: readonly ["agents-refresh", "cache", "check", "capacity-backfill", "capacity-show", "codebase-default-extractor", "codebase-map", "codebase-map-fresh", "codebase-projection-registry", "codebase-provider", "doctor", "install-upgrade", "install-uninstall", "migrate-preflight", "migrate-xbrief", "migrate-category-b", "framework-check-updates", "hook-dispatch", "umbrella-current-shape", "changelog-check", "change-init", "commit-lint", "coverage-hotspots", "policy", "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", "lifecycle-event", "lifecycle-stats", "session-start", "session-ready", "plan-sequence", "slice", "subagent-monitor", "toolchain-check", "triage-actions", "triage-bootstrap", "triage-bulk", "triage-classify", "triage-help", "triage-queue", "triage-reconcile", "triage-refresh", "triage-scope", "triage-scope-drift", "triage-smoketest", "triage-subscribe", "triage-summary", "triage-welcome", "ts-check-lane", "vbrief-activate", "vbrief-build", "vbrief-preflight", "vbrief-reconcile", "vbrief-validate", "vbrief-validation", "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-content-manifest", "verify-skill-external-fetch-gate", "verify-contract-drift", "verify-cursor-tier1", "verify-openclaw-tier1", "verify-go-freeze", "verify-scm-boundary", "verify-session-ritual", "verify-plan-sequence", "verify-stubs", "verify-xbrief-drift", "rule-ownership-lint", "verify-story-ready", "verify-review-monitor", "verify-l4-owner", "verify-subagent-alive", "review-monitor-register", "review-monitor-release", "verify-tools", "verify-wip-cap", "verify-orphan-active", "verify-agents-md-budget", "verify-agents-md-advisory", "verify-eval-health-relocation", "verify-eval-triggers-relocation", "eval-health", "eval-run", "eval-report", "eval-triggers"];
 /** Core-only CLI entrypoints without a packages/cli wrapper. */
 export declare const CORE_MODULE_VERBS: readonly ["scm", "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-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"];
 /** Colon aliases for triage-actions (mirrors cli-router SUBCOMMAND_ROUTES). */

package/dist/dispatch.js

@@ -68,6 +68,7 @@ export const CLI_MODULE_VERBS = [
     "release-publish",
     "release-rollback",
     "scope-lifecycle",
+    "scope-record-approved-scope",
     "lifecycle-event",
     "lifecycle-stats",
     "session-start",
@@ -267,6 +268,7 @@ export const VERB_ALIASES = {
     "verify:forward-coverage": "verify-forward-coverage",
     "verify:test-boundary": "verify-test-boundary",
     "verify:scope-provenance": "verify-scope-provenance",
+    "scope:record-approved-scope": "scope-record-approved-scope",
     "verify:consumer-check-contract": "verify-consumer-check-contract",
     "coverage:hotspots": "coverage-hotspots",
     "verify:branch": "verify-branch",
@@ -2529,6 +2531,7 @@ const SCOPE_COMMAND_NAMES = [
     "scope:complete",
     "scope:demote",
     "scope:undo",
+    "scope:record-approved-scope",
 ];
 /**
  * Deduplicated command names for `directive commands`, preferring colon-style

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

@@ -0,0 +1,22 @@
+#!/usr/bin/env node
+/** True when `candidate` is the same as or a descendant of `root` after realpath. */
+export declare function isPathInsideRoot(root: string, candidate: string): boolean;
+export interface ParsedArgs {
+    projectRoot: string;
+    xbriefPath: string;
+    actor: string;
+    kind: string;
+    /** Optional override for recorded xbriefRelPath (defaults: pending→active map). */
+    xbriefRelPath: string;
+    quiet: boolean;
+    error?: string;
+}
+/**
+ * Map pending/ → active/ for path-bound approval records.
+ * Returns null when the source cannot be expressed as a repo-relative path under projectRoot
+ * (absolute outside-root paths must not be stamped into xbriefRelPath — #3205 Greptile).
+ */
+export declare function resolveApprovalXbriefRelPath(sourceRelOrAbs: string, projectRoot: string, override?: string): string | null;
+export declare function parseArgs(argv: string[]): ParsedArgs;
+export declare function run(argv: string[]): number;
+//# sourceMappingURL=scope-record-approved-scope.d.ts.map

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

@@ -0,0 +1,253 @@
+#!/usr/bin/env node
+/**
+ * CLI for scope:record-approved-scope (#3205).
+ *
+ * Deposits a human-origin approved-scope digest under
+ * `.deft/approved-scope/<plan-id>.json` so verify:scope-provenance can
+ * authorize pending→active and operator-approved expansion without same-PR
+ * self-authorization.
+ */
+import { existsSync, lstatSync, readFileSync, realpathSync } from "node:fs";
+import { basename, join, relative, resolve, sep } from "node:path";
+import { scopeProvenance } from "@deftai/directive-core";
+import { isDirectEntrypoint } from "./entrypoint.js";
+/** True when `candidate` is the same as or a descendant of `root` after realpath. */
+export function isPathInsideRoot(root, candidate) {
+    let rootReal;
+    let candReal;
+    try {
+        rootReal = realpathSync(root);
+        // realpathSync fails if path does not exist; fall back to resolve for missing targets
+        candReal = existsSync(candidate) ? realpathSync(candidate) : resolve(candidate);
+    }
+    catch {
+        return false;
+    }
+    const rel = relative(rootReal, candReal);
+    if (rel === "")
+        return true;
+    if (rel.startsWith(`..${sep}`) ||
+        rel === ".." ||
+        rel.startsWith("../") ||
+        rel.startsWith("..\\")) {
+        return false;
+    }
+    // Absolute relative() means different drive/root (win32)
+    if (resolve(rel) === rel && rel.includes(":"))
+        return false;
+    return !rel.startsWith("..");
+}
+const { buildApprovedScopeRecord, isHumanApprovalStamp, writeApprovedScopeRecord } = scopeProvenance;
+function usage() {
+    return ("usage: scope:record-approved-scope -- <xbrief-path> --actor <name> " +
+        "[--kind operator] [--project-root <dir>] [--xbrief-rel-path <posix>] [--quiet]\n" +
+        "  Writes .deft/approved-scope/<plan-id>.json with a humanApproval stamp (#3205).\n" +
+        "  Agent-shaped stamps are refused. Path-binds to xbrief/active/ by default when " +
+        "the source is under pending/ or active/.");
+}
+/**
+ * Map pending/ → active/ for path-bound approval records.
+ * Returns null when the source cannot be expressed as a repo-relative path under projectRoot
+ * (absolute outside-root paths must not be stamped into xbriefRelPath — #3205 Greptile).
+ */
+export function resolveApprovalXbriefRelPath(sourceRelOrAbs, projectRoot, override) {
+    if (override !== undefined && override.trim().length > 0) {
+        const o = override.replace(/\\/g, "/").replace(/^\.\//, "");
+        if (o.startsWith("/") || /^[A-Za-z]:\//.test(o))
+            return null;
+        return o;
+    }
+    const root = resolve(projectRoot);
+    const abs = resolve(sourceRelOrAbs.includes(":") ||
+        sourceRelOrAbs.startsWith("/") ||
+        sourceRelOrAbs.startsWith("\\")
+        ? sourceRelOrAbs
+        : join(root, sourceRelOrAbs));
+    // Lexical + realpath containment (symlink to outside root must fail closed — #3205 Greptile).
+    if (!isPathInsideRoot(root, abs)) {
+        return null;
+    }
+    let rel = relative(root, abs).replace(/\\/g, "/");
+    if (rel.length === 0 || rel.startsWith("../") || rel === "..") {
+        return null;
+    }
+    try {
+        if (existsSync(abs) && lstatSync(abs).isSymbolicLink() && !isPathInsideRoot(root, abs)) {
+            return null;
+        }
+    }
+    catch {
+        return null;
+    }
+    // Normalize pending → active for future-active binding (issue #3205 multi-PR).
+    if (rel.startsWith("xbrief/pending/")) {
+        rel = `xbrief/active/${basename(rel)}`;
+    }
+    else if (rel.startsWith("vbrief/pending/")) {
+        rel = `vbrief/active/${basename(rel)}`;
+    }
+    return rel;
+}
+export function parseArgs(argv) {
+    const parsed = {
+        projectRoot: ".",
+        xbriefPath: "",
+        actor: "",
+        kind: "operator",
+        xbriefRelPath: "",
+        quiet: false,
+    };
+    const positionals = [];
+    for (let i = 0; i < argv.length; i += 1) {
+        const arg = argv[i];
+        if (arg === "--help" || arg === "-h") {
+            return { ...parsed, error: usage() };
+        }
+        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 === "--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 === "--xbrief-rel-path") {
+            const value = argv[i + 1];
+            if (value === undefined) {
+                return { ...parsed, error: "argument --xbrief-rel-path: expected one argument" };
+            }
+            parsed.xbriefRelPath = value;
+            i += 1;
+        }
+        else if (arg?.startsWith("--xbrief-rel-path=")) {
+            parsed.xbriefRelPath = arg.slice("--xbrief-rel-path=".length);
+        }
+        else if (arg?.startsWith("-")) {
+            return { ...parsed, error: `unrecognized argument: ${arg}` };
+        }
+        else if (arg !== undefined) {
+            positionals.push(arg);
+        }
+    }
+    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) {
+    const args = parseArgs(argv);
+    if (args.error !== undefined) {
+        process.stderr.write(`scope_record_approved_scope: ${args.error}\n`);
+        return 2;
+    }
+    const projectRoot = resolve(args.projectRoot);
+    const xbriefAbs = resolve(projectRoot, args.xbriefPath);
+    if (!existsSync(xbriefAbs)) {
+        // Also try absolute path as given
+        const alt = resolve(args.xbriefPath);
+        if (!existsSync(alt)) {
+            process.stderr.write(`scope_record_approved_scope: xBRIEF not found: ${args.xbriefPath}\n`);
+            return 2;
+        }
+    }
+    const fullPath = existsSync(xbriefAbs) ? xbriefAbs : resolve(args.xbriefPath);
+    if (!isPathInsideRoot(projectRoot, fullPath)) {
+        process.stderr.write("scope_record_approved_scope: xBRIEF path escapes --project-root " +
+            "(symlink or absolute outside-root targets refused) (#3205).\n");
+        return 2;
+    }
+    let raw;
+    try {
+        raw = readFileSync(fullPath, "utf8");
+    }
+    catch (err) {
+        process.stderr.write(`scope_record_approved_scope: failed to read xBRIEF: ${String(err)}\n`);
+        return 2;
+    }
+    let payload;
+    try {
+        payload = JSON.parse(raw);
+    }
+    catch {
+        process.stderr.write("scope_record_approved_scope: xBRIEF is not valid JSON\n");
+        return 2;
+    }
+    const stamp = {
+        kind: args.kind.trim(),
+        actor: args.actor.trim(),
+        mintedAt: new Date().toISOString().replace(/\.\d{3}Z$/, "Z"),
+        mintedVia: "scope:record-approved-scope",
+    };
+    if (!isHumanApprovalStamp(stamp)) {
+        process.stderr.write("scope_record_approved_scope: refused agent/non-human stamp " +
+            `(kind=${stamp.kind}, actor=${stamp.actor}). Use a human operator actor ` +
+            "and kind in {operator,human,user,cli,github-user,interactive,renewed-approval} (#3205).\n");
+        return 1;
+    }
+    const xbriefRelPath = resolveApprovalXbriefRelPath(fullPath, projectRoot, args.xbriefRelPath.length > 0 ? args.xbriefRelPath : undefined);
+    if (xbriefRelPath === null) {
+        process.stderr.write("scope_record_approved_scope: xBRIEF path must resolve under --project-root " +
+            "(repo-relative path required for approval binding) (#3205).\n");
+        return 2;
+    }
+    const record = buildApprovedScopeRecord({
+        xbriefRelPath,
+        payload,
+        humanApproval: stamp,
+        xbriefRawText: raw,
+    });
+    const outPath = writeApprovedScopeRecord(projectRoot, record);
+    if (!args.quiet) {
+        process.stdout.write(`scope_record_approved_scope: wrote ${outPath}\n` +
+            `  planId: ${record.planId}\n` +
+            `  xbriefRelPath: ${record.xbriefRelPath}\n` +
+            `  fileScopeDigest: ${record.fileScopeDigest}\n` +
+            `  paths: ${record.fileScope.length}\n` +
+            `  humanApproval: ${stamp.kind}/${stamp.actor}\n` +
+            "  Next: commit this file on the merge base (or a prior PR) before " +
+            "activation/expansion in the implementation change set (#3205).\n");
+    }
+    return 0;
+}
+if (isDirectEntrypoint(import.meta.url)) {
+    process.exit(run(process.argv.slice(2)));
+}
+//# sourceMappingURL=scope-record-approved-scope.js.map

package/package.json

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