@deftai/directive 0.119.13 → 0.120.0

package/dist/authz.js

@@ -27,6 +27,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 { uatCampaignEndSeal } from "@deftai/directive-core/authz/campaign-end-seal";
 import { refuseMintWhileUatActive, refuseNonInteractiveMint, resolveHumanPresenceMintSeams, } from "./human-presence-mint.js";
 export { AUTHZ_AGENT_SHELL_ENV_MARKERS, AUTHZ_INTERACTIVE_CONFIRM_PHRASE, } from "./human-presence-mint.js";
 function parseOps(raw) {
@@ -328,13 +329,18 @@ export function main(argv = process.argv.slice(2), seams = {}) {
                 const blocked = gateConfirm();
                 if (blocked !== null)
                     return blocked;
-                const { lease } = startUatLease({
+                // Result narrowing; pinActive mint wiring stays parked (class 4).
+                const started = startUatLease({
                     projectRoot: args.projectRoot,
                     campaignId: args.campaign,
                     actor: args.actor,
                     note: args.note,
                 });
-                process.stdout.write(`✓ UAT lease ACTIVE campaign=${lease.campaignId} (human-origin operator-cli)\n`);
+                if (!started.ok) {
+                    process.stderr.write(`authz:uat-start: ${started.reason}\n`);
+                    return 2;
+                }
+                process.stdout.write(`✓ UAT lease ACTIVE campaign=${started.lease.campaignId} (human-origin operator-cli)\n`);
                 process.stdout.write("  Product edit/push/PR/merge denied until a named fix cohort grant is minted.\n");
                 process.stdout.write("  Tests, evidence capture, and issue filing remain allowed.\n");
                 return 0;
@@ -343,10 +349,18 @@ export function main(argv = process.argv.slice(2), seams = {}) {
                 const blocked = gateConfirm();
                 if (blocked !== null)
                     return blocked;
-                const state = suspendUatLease({
+                // Sealed campaign-end only after CLI human-presence gateConfirm (#4233).
+                // pinActive mint wiring stays parked (class 4 follow-up).
+                const suspended = suspendUatLease({
                     projectRoot: args.projectRoot,
                     actor: args.actor,
+                    campaignEndSeal: uatCampaignEndSeal(),
                 });
+                if (!suspended.ok) {
+                    process.stderr.write(`authz:uat-suspend: ${suspended.reason}\n`);
+                    return 2;
+                }
+                const state = suspended.state;
                 if (state.uat === null) {
                     process.stdout.write("UAT lease was already inactive.\n");
                 }
@@ -400,7 +414,7 @@ export function main(argv = process.argv.slice(2), seams = {}) {
                     const blocked = gateConfirm();
                     if (blocked !== null)
                         return blocked;
-                    const grant = mintDecomposeStructuralApplyGrant({
+                    const minted = mintDecomposeStructuralApplyGrant({
                         projectRoot: root,
                         parentPath: parentAbs,
                         draftPath: draftAbs,
@@ -409,6 +423,11 @@ export function main(argv = process.argv.slice(2), seams = {}) {
                         expiresAt: args.expiresAt,
                         singleUse: args.singleUse,
                     });
+                    if (!minted.ok) {
+                        process.stderr.write(`authz:grant: ${minted.reason}\n`);
+                        return 2;
+                    }
+                    const grant = minted.grant;
                     // mintDecomposeStructuralApplyGrant always sets contentDigest + worktree.
                     const digest = grant.scope.contentDigest || "";
                     process.stdout.write(`✓ human-origin structural grant minted id=${grant.id} origin=${grant.origin.kind}\n`);
@@ -474,7 +493,7 @@ export function main(argv = process.argv.slice(2), seams = {}) {
                     const blocked = gateConfirm();
                     if (blocked !== null)
                         return blocked;
-                    const grant = mintAfkTemplateGrant({
+                    const minted = mintAfkTemplateGrant({
                         projectRoot: args.projectRoot,
                         template: args.template,
                         target: args.target,
@@ -489,6 +508,11 @@ export function main(argv = process.argv.slice(2), seams = {}) {
                         issueIds: args.issueIds,
                         cohortId: args.cohort,
                     });
+                    if (!minted.ok) {
+                        process.stderr.write(`authz:grant: ${minted.reason}\n`);
+                        return 2;
+                    }
+                    const grant = minted.grant;
                     process.stdout.write(`✓ human-origin grant minted id=${grant.id} origin=${grant.origin.kind} ` +
                         `template=${args.template}\n`);
                     if (isFinishLoopTemplateName(args.template)) {
@@ -511,7 +535,7 @@ export function main(argv = process.argv.slice(2), seams = {}) {
                     if (blocked !== null)
                         return blocked;
                 }
-                const grant = mintHumanOriginGrant({
+                const minted = mintHumanOriginGrant({
                     projectRoot: args.projectRoot,
                     actor: args.actor,
                     operations: args.operations,
@@ -525,6 +549,11 @@ export function main(argv = process.argv.slice(2), seams = {}) {
                     expiresAt: args.expiresAt,
                     singleUse: args.singleUse,
                 });
+                if (!minted.ok) {
+                    process.stderr.write(`authz:grant: ${minted.reason}\n`);
+                    return 2;
+                }
+                const grant = minted.grant;
                 process.stdout.write(`✓ human-origin grant minted id=${grant.id} origin=${grant.origin.kind}\n`);
                 process.stdout.write(`  ops=[${grant.scope.operations.join(",")}] cohort=${grant.scope.cohortId ?? "-"}\n`);
                 if (grant.scope.surfaces.length > 0) {
@@ -542,10 +571,15 @@ export function main(argv = process.argv.slice(2), seams = {}) {
                     if (blocked !== null)
                         return blocked;
                 }
-                const revoked = revokeGrant({
+                const revokedResult = revokeGrant({
                     projectRoot: args.projectRoot,
                     grantId: args.grantId,
                 });
+                if (!revokedResult.ok) {
+                    process.stderr.write(`authz:revoke: ${revokedResult.reason}\n`);
+                    return 2;
+                }
+                const revoked = revokedResult.grant;
                 if (revoked === null) {
                     process.stderr.write(`authz: grant not found: ${args.grantId}\n`);
                     return 1;

package/dist/changelog-check.js

@@ -2,14 +2,19 @@
 import { resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { runChangelogCheck } from "@deftai/directive-core/task-surface";
-function parseProjectRoot(argv) {
+function parseChangelogCheckArgs(argv) {
     let projectRoot = ".";
+    let againstMergeBase = false;
     for (let i = 0; i < argv.length; i += 1) {
         const arg = argv[i] ?? "";
         if (arg === "--project-root") {
             const value = argv[i + 1];
             if (value === undefined) {
-                return { projectRoot, error: "argument --project-root: expected one argument" };
+                return {
+                    projectRoot,
+                    againstMergeBase,
+                    error: "argument --project-root: expected one argument",
+                };
             }
             projectRoot = value;
             i += 1;
@@ -17,14 +22,17 @@ function parseProjectRoot(argv) {
         else if (arg.startsWith("--project-root=")) {
             projectRoot = arg.slice("--project-root=".length);
         }
+        else if (arg === "--against-merge-base") {
+            againstMergeBase = true;
+        }
         else {
-            return { projectRoot, error: `unrecognized argument: ${arg}` };
+            return { projectRoot, againstMergeBase, error: `unrecognized argument: ${arg}` };
         }
     }
-    return { projectRoot };
+    return { projectRoot, againstMergeBase };
 }
 export function run(argv) {
-    const args = parseProjectRoot(argv);
+    const args = parseChangelogCheckArgs(argv);
     if (args.error !== undefined) {
         process.stderr.write(`changelog-check: ${args.error}\n`);
         return 2;
@@ -36,7 +44,7 @@ export function run(argv) {
         writeErr: (text) => {
             process.stderr.write(text);
         },
-    });
+    }, { againstMergeBase: args.againstMergeBase });
 }
 if (process.argv[1] !== undefined && fileURLToPath(import.meta.url) === process.argv[1]) {
     process.exit(run(process.argv.slice(2)));

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", "ownership-doctor", "ownership-fix", "verify-ownership", "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-presentation-coverage", "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-consumer-header-placeholder", "verify-agents-md-advisory", "verify-persisted-planning-narratives", "verify-eval-health-relocation", "verify-eval-triggers-relocation", "verify-evaluator-surface", "verify-observable-scope", "verify-operator-scope-limit", "verify-presentation-ceiling", "verify-intent-constraint", "verify-durable-effect-acquisition", "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", "ownership-doctor", "ownership-fix", "verify-ownership", "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", "pre-pr-run", "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-presentation-coverage", "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-consumer-header-placeholder", "verify-agents-md-advisory", "verify-persisted-planning-narratives", "verify-eval-health-relocation", "verify-eval-triggers-relocation", "verify-evaluator-surface", "verify-observable-scope", "verify-operator-scope-limit", "verify-presentation-ceiling", "verify-intent-constraint", "verify-durable-effect-acquisition", "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-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", "migrate-clause-ids"];
 /** Colon aliases for triage-actions (mirrors cli-router SUBCOMMAND_ROUTES). */

package/dist/dispatch.js

@@ -64,6 +64,7 @@ export const CLI_MODULE_VERBS = [
     "pr-watch",
     "pr-finish-loop",
     "directive-finish-loop",
+    "pre-pr-run",
     "preflight-cache",
     "preflight-gh",
     "probe-session",
@@ -310,6 +311,7 @@ export const FRESHNESS_ALIAS_SUBCOMMANDS = {
 const FRESHNESS_COLON_ALIASES = Object.fromEntries(Object.keys(FRESHNESS_ALIAS_SUBCOMMANDS).map((alias) => [alias, "freshness-report"]));
 /** Task-style aliases (framework_commands / Taskfile names). */
 export const VERB_ALIASES = {
+    "pre-pr:run": "pre-pr-run",
     "hook:dispatch": "hook-dispatch",
     "verify:encoding": "verify-encoding",
     "verify:forward-coverage": "verify-forward-coverage",

package/dist/pre-pr-run.d.ts

@@ -0,0 +1,39 @@
+#!/usr/bin/env node
+interface ParsedArgs {
+    repo: string;
+    baseSha: string;
+    headSha: string;
+    treeHash: string;
+    prBodyHash: string;
+    prNodeId: string | null;
+    approvedRevision: string;
+    scope: string[];
+    acceptance: string;
+    generation: number;
+    skillVersion: string;
+    policyVersion: string;
+    runId: string | null;
+    complete: boolean;
+    observeCommand: boolean;
+    observeSemantic: boolean;
+    phase: string | null;
+    command: string;
+    exitCode: number | null;
+    inputHash: string | null;
+    skipReason: string | null;
+    suppliedContentsHash: string;
+    controllerObservedHash: string;
+    criteriaDigest: string | null;
+    reviewedFiles: string[];
+    reviewerReportRef: string | null;
+    markComplete: boolean;
+    skillOpen: boolean;
+    evaluate: boolean;
+    json: boolean;
+    help: boolean;
+    error?: string;
+}
+export declare function parseArgs(argv: string[]): ParsedArgs;
+export declare function run(argv: string[]): number;
+export {};
+//# sourceMappingURL=pre-pr-run.d.ts.map

package/dist/pre-pr-run.js

@@ -0,0 +1,514 @@
+#!/usr/bin/env node
+/**
+ * Agent-facing pre-PR controller entry (#4912 Limb 3).
+ * `deft pre-pr:run` starts the prescribed workflow. Opening the skill file
+ * is not completion. Generic mark-complete cannot mint a pass.
+ */
+import { completeRun, computeControllerObservedHash, controllerPublisher, digestApprovedCriteria, evaluateLivePrePrCheck, getDefaultPrePrStore, markComplete, noteSkillFileOpen, observeCommandPhase, PRE_PR_PHASE_IDS, phaseSpec, resolveRecordFromStore, startControllerRun, submitReviewerReport, } from "@deftai/directive-core/pre-pr-controller";
+import { isDirectEntrypoint } from "./entrypoint.js";
+const USAGE = `Usage: deft pre-pr:run [options]
+
+Start the repository-controlled pre-PR workflow. Opening the skill file is
+not completion. A generic mark-complete cannot mint a pass.
+
+Options:
+  --repo <owner/name>
+  --base-sha <sha>
+  --head-sha <sha>
+  --tree-hash <sha>
+  --pr-body-hash <hex>
+  --pr-node-id <id>
+  --approved-revision <sha>
+  --scope <path>          (repeatable)
+  --acceptance <text>
+  --generation <n>
+  --skill-version <ver>
+  --policy-version <ver>
+  --run-id <id>           lookup hint only
+  --complete              publisher-backed complete (fails without observables)
+  --observe-command       record a command-observable phase before --complete
+  --observe-semantic      record semantic / final-no-change evidence
+  --phase <id>
+  --command <text>
+  --exit-code <n>         required with --observe-command; omit is a parse error
+  --input-hash <hex>
+  --skip-reason <text>    skip also requires a non-zero --exit-code
+  --supplied-contents-hash <hex>
+  --controller-observed-hash <hex>
+                          optional; must match independently hashed reviewed files
+  --criteria-digest <hex>
+  --reviewed-file <path>  (repeatable)
+  --reviewer-report-ref <ref>
+  --mark-complete         always refuses; cannot mint a pass
+  --skill-open            always refuses; opening the skill is not completion
+  --evaluate              evaluate live binding against the private store
+  --json
+  --help
+`;
+export function parseArgs(argv) {
+    const parsed = {
+        repo: "",
+        baseSha: "",
+        headSha: "",
+        treeHash: "",
+        prBodyHash: "",
+        prNodeId: null,
+        approvedRevision: "",
+        scope: [],
+        acceptance: "",
+        generation: 1,
+        skillVersion: "0.1",
+        policyVersion: "1",
+        runId: null,
+        complete: false,
+        observeCommand: false,
+        observeSemantic: false,
+        phase: null,
+        command: "",
+        exitCode: null,
+        inputHash: null,
+        skipReason: null,
+        suppliedContentsHash: "",
+        controllerObservedHash: "",
+        criteriaDigest: null,
+        reviewedFiles: [],
+        reviewerReportRef: null,
+        markComplete: false,
+        skillOpen: false,
+        evaluate: false,
+        json: false,
+        help: false,
+    };
+    for (let i = 0; i < argv.length; i += 1) {
+        const arg = argv[i];
+        if (arg === "--help" || arg === "-h") {
+            parsed.help = true;
+        }
+        else if (arg === "--json") {
+            parsed.json = true;
+        }
+        else if (arg === "--complete") {
+            parsed.complete = true;
+        }
+        else if (arg === "--observe-command") {
+            parsed.observeCommand = true;
+        }
+        else if (arg === "--observe-semantic") {
+            parsed.observeSemantic = true;
+        }
+        else if (arg === "--phase" || arg?.startsWith("--phase=")) {
+            const value = arg === "--phase" ? argv[i + 1] : arg.slice("--phase=".length);
+            if (value === undefined)
+                return { ...parsed, error: "argument --phase: expected one argument" };
+            parsed.phase = value;
+            if (arg === "--phase")
+                i += 1;
+        }
+        else if (arg === "--command" || arg?.startsWith("--command=")) {
+            const value = arg === "--command" ? argv[i + 1] : arg.slice("--command=".length);
+            if (value === undefined)
+                return { ...parsed, error: "argument --command: expected one argument" };
+            parsed.command = value;
+            if (arg === "--command")
+                i += 1;
+        }
+        else if (arg === "--exit-code" || arg?.startsWith("--exit-code=")) {
+            const value = arg === "--exit-code" ? argv[i + 1] : arg.slice("--exit-code=".length);
+            if (value === undefined) {
+                return { ...parsed, error: "argument --exit-code: expected one argument" };
+            }
+            const n = Number.parseInt(value, 10);
+            if (!Number.isFinite(n)) {
+                return { ...parsed, error: "argument --exit-code: expected an integer" };
+            }
+            parsed.exitCode = n;
+            if (arg === "--exit-code")
+                i += 1;
+        }
+        else if (arg === "--input-hash" || arg?.startsWith("--input-hash=")) {
+            const value = arg === "--input-hash" ? argv[i + 1] : arg.slice("--input-hash=".length);
+            if (value === undefined) {
+                return { ...parsed, error: "argument --input-hash: expected one argument" };
+            }
+            parsed.inputHash = value;
+            if (arg === "--input-hash")
+                i += 1;
+        }
+        else if (arg === "--skip-reason" || arg?.startsWith("--skip-reason=")) {
+            const value = arg === "--skip-reason" ? argv[i + 1] : arg.slice("--skip-reason=".length);
+            if (value === undefined) {
+                return { ...parsed, error: "argument --skip-reason: expected one argument" };
+            }
+            parsed.skipReason = value;
+            if (arg === "--skip-reason")
+                i += 1;
+        }
+        else if (arg === "--supplied-contents-hash" || arg?.startsWith("--supplied-contents-hash=")) {
+            const value = arg === "--supplied-contents-hash"
+                ? argv[i + 1]
+                : arg.slice("--supplied-contents-hash=".length);
+            if (value === undefined) {
+                return { ...parsed, error: "argument --supplied-contents-hash: expected one argument" };
+            }
+            parsed.suppliedContentsHash = value;
+            if (arg === "--supplied-contents-hash")
+                i += 1;
+        }
+        else if (arg === "--controller-observed-hash" ||
+            arg?.startsWith("--controller-observed-hash=")) {
+            const value = arg === "--controller-observed-hash"
+                ? argv[i + 1]
+                : arg.slice("--controller-observed-hash=".length);
+            if (value === undefined) {
+                return {
+                    ...parsed,
+                    error: "argument --controller-observed-hash: expected one argument",
+                };
+            }
+            parsed.controllerObservedHash = value;
+            if (arg === "--controller-observed-hash")
+                i += 1;
+        }
+        else if (arg === "--criteria-digest" || arg?.startsWith("--criteria-digest=")) {
+            const value = arg === "--criteria-digest" ? argv[i + 1] : arg.slice("--criteria-digest=".length);
+            if (value === undefined) {
+                return { ...parsed, error: "argument --criteria-digest: expected one argument" };
+            }
+            parsed.criteriaDigest = value;
+            if (arg === "--criteria-digest")
+                i += 1;
+        }
+        else if (arg === "--reviewed-file" || arg?.startsWith("--reviewed-file=")) {
+            const value = arg === "--reviewed-file" ? argv[i + 1] : arg.slice("--reviewed-file=".length);
+            if (value === undefined) {
+                return { ...parsed, error: "argument --reviewed-file: expected one argument" };
+            }
+            parsed.reviewedFiles.push(value);
+            if (arg === "--reviewed-file")
+                i += 1;
+        }
+        else if (arg === "--reviewer-report-ref" || arg?.startsWith("--reviewer-report-ref=")) {
+            const value = arg === "--reviewer-report-ref" ? argv[i + 1] : arg.slice("--reviewer-report-ref=".length);
+            if (value === undefined) {
+                return { ...parsed, error: "argument --reviewer-report-ref: expected one argument" };
+            }
+            parsed.reviewerReportRef = value;
+            if (arg === "--reviewer-report-ref")
+                i += 1;
+        }
+        else if (arg === "--mark-complete") {
+            parsed.markComplete = true;
+        }
+        else if (arg === "--skill-open") {
+            parsed.skillOpen = true;
+        }
+        else if (arg === "--evaluate") {
+            parsed.evaluate = true;
+        }
+        else if (arg === "--repo" || arg?.startsWith("--repo=")) {
+            const value = arg === "--repo" ? argv[i + 1] : arg.slice("--repo=".length);
+            if (value === undefined)
+                return { ...parsed, error: "argument --repo: expected one argument" };
+            parsed.repo = value;
+            if (arg === "--repo")
+                i += 1;
+        }
+        else if (arg === "--base-sha" || arg?.startsWith("--base-sha=")) {
+            const value = arg === "--base-sha" ? argv[i + 1] : arg.slice("--base-sha=".length);
+            if (value === undefined)
+                return { ...parsed, error: "argument --base-sha: expected one argument" };
+            parsed.baseSha = value;
+            if (arg === "--base-sha")
+                i += 1;
+        }
+        else if (arg === "--head-sha" || arg?.startsWith("--head-sha=")) {
+            const value = arg === "--head-sha" ? argv[i + 1] : arg.slice("--head-sha=".length);
+            if (value === undefined)
+                return { ...parsed, error: "argument --head-sha: expected one argument" };
+            parsed.headSha = value;
+            if (arg === "--head-sha")
+                i += 1;
+        }
+        else if (arg === "--tree-hash" || arg?.startsWith("--tree-hash=")) {
+            const value = arg === "--tree-hash" ? argv[i + 1] : arg.slice("--tree-hash=".length);
+            if (value === undefined)
+                return { ...parsed, error: "argument --tree-hash: expected one argument" };
+            parsed.treeHash = value;
+            if (arg === "--tree-hash")
+                i += 1;
+        }
+        else if (arg === "--pr-body-hash" || arg?.startsWith("--pr-body-hash=")) {
+            const value = arg === "--pr-body-hash" ? argv[i + 1] : arg.slice("--pr-body-hash=".length);
+            if (value === undefined) {
+                return { ...parsed, error: "argument --pr-body-hash: expected one argument" };
+            }
+            parsed.prBodyHash = value;
+            if (arg === "--pr-body-hash")
+                i += 1;
+        }
+        else if (arg === "--pr-node-id" || arg?.startsWith("--pr-node-id=")) {
+            const value = arg === "--pr-node-id" ? argv[i + 1] : arg.slice("--pr-node-id=".length);
+            if (value === undefined) {
+                return { ...parsed, error: "argument --pr-node-id: expected one argument" };
+            }
+            parsed.prNodeId = value;
+            if (arg === "--pr-node-id")
+                i += 1;
+        }
+        else if (arg === "--approved-revision" || arg?.startsWith("--approved-revision=")) {
+            const value = arg === "--approved-revision" ? argv[i + 1] : arg.slice("--approved-revision=".length);
+            if (value === undefined) {
+                return { ...parsed, error: "argument --approved-revision: expected one argument" };
+            }
+            parsed.approvedRevision = value;
+            if (arg === "--approved-revision")
+                i += 1;
+        }
+        else if (arg === "--scope" || arg?.startsWith("--scope=")) {
+            const value = arg === "--scope" ? argv[i + 1] : arg.slice("--scope=".length);
+            if (value === undefined)
+                return { ...parsed, error: "argument --scope: expected one argument" };
+            parsed.scope.push(value);
+            if (arg === "--scope")
+                i += 1;
+        }
+        else if (arg === "--acceptance" || arg?.startsWith("--acceptance=")) {
+            const value = arg === "--acceptance" ? argv[i + 1] : arg.slice("--acceptance=".length);
+            if (value === undefined) {
+                return { ...parsed, error: "argument --acceptance: expected one argument" };
+            }
+            parsed.acceptance = value;
+            if (arg === "--acceptance")
+                i += 1;
+        }
+        else if (arg === "--generation" || arg?.startsWith("--generation=")) {
+            const value = arg === "--generation" ? argv[i + 1] : arg.slice("--generation=".length);
+            if (value === undefined) {
+                return { ...parsed, error: "argument --generation: expected one argument" };
+            }
+            const n = Number.parseInt(value, 10);
+            if (!Number.isFinite(n) || n < 1) {
+                return { ...parsed, error: "argument --generation: expected a positive integer" };
+            }
+            parsed.generation = n;
+            if (arg === "--generation")
+                i += 1;
+        }
+        else if (arg === "--skill-version" || arg?.startsWith("--skill-version=")) {
+            const value = arg === "--skill-version" ? argv[i + 1] : arg.slice("--skill-version=".length);
+            if (value === undefined) {
+                return { ...parsed, error: "argument --skill-version: expected one argument" };
+            }
+            parsed.skillVersion = value;
+            if (arg === "--skill-version")
+                i += 1;
+        }
+        else if (arg === "--policy-version" || arg?.startsWith("--policy-version=")) {
+            const value = arg === "--policy-version" ? argv[i + 1] : arg.slice("--policy-version=".length);
+            if (value === undefined) {
+                return { ...parsed, error: "argument --policy-version: expected one argument" };
+            }
+            parsed.policyVersion = value;
+            if (arg === "--policy-version")
+                i += 1;
+        }
+        else if (arg === "--run-id" || arg?.startsWith("--run-id=")) {
+            const value = arg === "--run-id" ? argv[i + 1] : arg.slice("--run-id=".length);
+            if (value === undefined)
+                return { ...parsed, error: "argument --run-id: expected one argument" };
+            parsed.runId = value;
+            if (arg === "--run-id")
+                i += 1;
+        }
+        else {
+            return { ...parsed, error: `unrecognized argument: ${arg}` };
+        }
+    }
+    return parsed;
+}
+function emit(json, payload, text, err) {
+    const line = json ? `${JSON.stringify(payload)}\n` : `${text}\n`;
+    if (err)
+        process.stderr.write(line);
+    else
+        process.stdout.write(line);
+}
+function asPhaseId(value) {
+    return PRE_PR_PHASE_IDS.includes(value) ? value : null;
+}
+export function run(argv) {
+    const args = parseArgs(argv);
+    if (args.help) {
+        process.stdout.write(USAGE);
+        return 0;
+    }
+    if (args.error !== undefined) {
+        process.stderr.write(`pre_pr_run: ${args.error}\n`);
+        return 2;
+    }
+    if (args.skillOpen) {
+        const d = noteSkillFileOpen();
+        emit(args.json, d, d.message, true);
+        return 1;
+    }
+    const store = getDefaultPrePrStore();
+    if (args.markComplete) {
+        const d = markComplete(store, args.runId ?? "");
+        emit(args.json, d, d.message, true);
+        return 1;
+    }
+    if (args.observeCommand || args.observeSemantic) {
+        if (args.runId === null || args.runId.length === 0) {
+            process.stderr.write("pre_pr_run: observe requires --run-id\n");
+            return 2;
+        }
+        if (args.phase === null || args.phase.length === 0) {
+            process.stderr.write("pre_pr_run: observe requires --phase\n");
+            return 2;
+        }
+        const phase = asPhaseId(args.phase);
+        if (phase === null) {
+            process.stderr.write(`pre_pr_run: unknown phase ${args.phase}\n`);
+            return 2;
+        }
+        const rec = store.getById(args.runId);
+        if (args.observeCommand) {
+            if (args.exitCode === null) {
+                process.stderr.write("pre_pr_run: --observe-command requires --exit-code\n");
+                return 2;
+            }
+            if (args.skipReason !== null && args.skipReason.length > 0 && args.exitCode === 0) {
+                process.stderr.write("pre_pr_run: skip requires a non-zero --exit-code plus --skip-reason\n");
+                return 2;
+            }
+            const spec = phaseSpec(phase);
+            const d = observeCommandPhase(store, args.runId, {
+                phaseId: phase,
+                command: args.command.length > 0 ? args.command : (spec.command ?? ""),
+                exitCode: args.exitCode,
+                inputHash: args.inputHash ?? rec?.inputHash ?? "",
+                skipReason: args.skipReason,
+            });
+            emit(args.json, d, d.message, !d.ok);
+            return d.ok ? 0 : 1;
+        }
+        if (args.suppliedContentsHash.length === 0) {
+            process.stderr.write("pre_pr_run: --observe-semantic requires --supplied-contents-hash\n");
+            return 2;
+        }
+        if (args.reviewedFiles.length === 0) {
+            process.stderr.write("pre_pr_run: --observe-semantic requires --reviewed-file\n");
+            return 2;
+        }
+        const observed = computeControllerObservedHash({ reviewedFiles: args.reviewedFiles });
+        if (observed === null) {
+            process.stderr.write("pre_pr_run: --observe-semantic could not hash reviewed-file contents\n");
+            return 2;
+        }
+        if (args.controllerObservedHash.length > 0 && args.controllerObservedHash !== observed) {
+            process.stderr.write("pre_pr_run: --controller-observed-hash does not match independently hashed reviewed-file contents\n");
+            return 1;
+        }
+        if (args.suppliedContentsHash !== observed) {
+            process.stderr.write("pre_pr_run: --supplied-contents-hash does not match independently hashed reviewed-file contents\n");
+            return 1;
+        }
+        const d = submitReviewerReport(store, args.runId, {
+            phaseId: phase,
+            reviewedFileManifest: args.reviewedFiles,
+            suppliedContentsHash: args.suppliedContentsHash,
+            criteriaDigest: args.criteriaDigest ?? rec?.criteria.digest ?? "",
+            reviewerReportRef: args.reviewerReportRef,
+            controllerObservedHash: observed,
+        });
+        emit(args.json, d, d.message, !d.ok);
+        return d.ok ? 0 : 1;
+    }
+    if (args.evaluate) {
+        if (args.repo.length === 0 || args.baseSha.length === 0 || args.headSha.length === 0) {
+            process.stderr.write("pre_pr_run: --evaluate requires --repo --base-sha --head-sha\n");
+            return 2;
+        }
+        if (args.prBodyHash.length === 0) {
+            process.stderr.write("pre_pr_run: --evaluate requires --pr-body-hash\n");
+            return 2;
+        }
+        const record = resolveRecordFromStore(store, {
+            id: args.runId,
+            prNodeId: args.prNodeId,
+        });
+        const headSource = args.approvedRevision.length > 0
+            ? args.approvedRevision
+            : (record?.criteria.sourceRevisionSha ?? args.headSha);
+        const liveApproved = digestApprovedCriteria({
+            sourceRevisionSha: headSource,
+            scopePaths: args.scope,
+            acceptanceText: args.acceptance,
+            generation: args.generation,
+        });
+        const d = evaluateLivePrePrCheck({
+            store,
+            liveBinding: {
+                repo: args.repo,
+                baseSha: args.baseSha,
+                headSha: args.headSha,
+                prNodeId: args.prNodeId,
+                prBodyHash: args.prBodyHash,
+            },
+            presentedRunId: args.runId,
+            approvedCriteria: liveApproved,
+            currentGeneration: args.generation,
+            headCriteria: liveApproved,
+        });
+        emit(args.json, d, d.message, !d.ok);
+        return d.ok ? 0 : 1;
+    }
+    if (args.complete) {
+        if (args.runId === null || args.runId.length === 0) {
+            process.stderr.write("pre_pr_run: --complete requires --run-id\n");
+            return 2;
+        }
+        const d = completeRun(store, controllerPublisher(), args.runId);
+        emit(args.json, d, d.message, !d.ok);
+        return d.ok ? 0 : 1;
+    }
+    if (args.repo.length === 0 ||
+        args.baseSha.length === 0 ||
+        args.headSha.length === 0 ||
+        args.treeHash.length === 0 ||
+        args.prBodyHash.length === 0 ||
+        args.approvedRevision.length === 0) {
+        process.stderr.write("pre_pr_run: start requires --repo --base-sha --head-sha --tree-hash --pr-body-hash --approved-revision\n");
+        return 2;
+    }
+    const criteria = digestApprovedCriteria({
+        sourceRevisionSha: args.approvedRevision,
+        scopePaths: args.scope,
+        acceptanceText: args.acceptance,
+        generation: args.generation,
+    });
+    const started = startControllerRun(store, {
+        repo: args.repo,
+        baseSha: args.baseSha,
+        headSha: args.headSha,
+        treeHash: args.treeHash,
+        prBodyHash: args.prBodyHash,
+        prNodeId: args.prNodeId,
+        criteria,
+        skillVersion: args.skillVersion,
+        policyVersion: args.policyVersion,
+        approvedRevisionSha: args.approvedRevision,
+        runId: args.runId ?? undefined,
+    });
+    if (!started.ok) {
+        emit(args.json, started.decision, started.decision.message, true);
+        return 1;
+    }
+    const payload = { ok: started.ok, runId: started.runId, hint: "run id is a lookup hint only" };
+    emit(args.json, payload, `started ${started.runId} (lookup hint only; private store is authoritative)`, false);
+    return 0;
+}
+if (isDirectEntrypoint(import.meta.url)) {
+    process.exit(run(process.argv.slice(2)));
+}
+//# sourceMappingURL=pre-pr-run.js.map

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

@@ -6,9 +6,12 @@ interface ParsedArgs {
     issue: number | null;
     quiet: boolean;
     skipGh: boolean;
+    /** Opt-in discovery when --issue is set; unscoped defaults to on (#3495). */
+    discover: boolean | null;
+    enforce: boolean;
     error?: string;
 }
-/** Parse verify-completed-tracked CLI args (#3264 / #3476). */
+/** Parse verify-completed-tracked CLI args (#3264 / #3476 / #3495). */
 export declare function parseArgs(argv: string[]): ParsedArgs;
 /** Run the gate and return the process exit code. */
 export declare function run(argv: string[]): number;

package/dist/verify-completed-tracked.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import { resolve } from "node:path";
 import { fileURLToPath } from "node:url";
-import { COMPLETED_TRACKED_PROGRESS_MIN_BLOBS, COMPLETED_TRACKED_PROGRESS_THRESHOLD_MS, evaluateCompletedTracked, shouldAnnounceProgress, shouldAnnounceUpFrontCount, } from "@deftai/directive-core/lifecycle";
+import { COMPLETED_TRACKED_PROGRESS_MIN_BLOBS, COMPLETED_TRACKED_PROGRESS_THRESHOLD_MS, evaluateCompletedTracked, evaluateShippedClosedDiscovery, shouldAnnounceProgress, shouldAnnounceUpFrontCount, } from "@deftai/directive-core/lifecycle";
 function parseIssueNumber(raw) {
     const trimmed = raw.startsWith("#") ? raw.slice(1) : raw;
     if (!/^\d+$/.test(trimmed)) {
@@ -10,7 +10,7 @@ function parseIssueNumber(raw) {
     const value = Number(trimmed);
     return Number.isInteger(value) && value > 0 ? value : null;
 }
-/** Parse verify-completed-tracked CLI args (#3264 / #3476). */
+/** Parse verify-completed-tracked CLI args (#3264 / #3476 / #3495). */
 export function parseArgs(argv) {
     const parsed = {
         projectRoot: ".",
@@ -19,6 +19,8 @@ export function parseArgs(argv) {
         issue: null,
         quiet: false,
         skipGh: false,
+        discover: null,
+        enforce: false,
     };
     for (let i = 0; i < argv.length; i += 1) {
         const arg = argv[i];
@@ -28,6 +30,15 @@ export function parseArgs(argv) {
         else if (arg === "--skip-gh") {
             parsed.skipGh = true;
         }
+        else if (arg === "--discover") {
+            parsed.discover = true;
+        }
+        else if (arg === "--no-discover") {
+            parsed.discover = false;
+        }
+        else if (arg === "--enforce") {
+            parsed.enforce = true;
+        }
         else if (arg === "--project-root") {
             const value = argv[i + 1];
             if (value === undefined) {
@@ -87,6 +98,16 @@ export function parseArgs(argv) {
     }
     return parsed;
 }
+function shouldRunDiscovery(args) {
+    if (args.discover === false) {
+        return false;
+    }
+    if (args.discover === true || args.enforce) {
+        return true;
+    }
+    // Warn-first default: unscoped corpus scans discover; --issue N stays land-only.
+    return args.issue === null;
+}
 /** Run the gate and return the process exit code. */
 export function run(argv) {
     const args = parseArgs(argv);
@@ -97,7 +118,7 @@ export function run(argv) {
     const projectRoot = resolve(args.projectRoot);
     const thresholdMs = resolveProgressThresholdMs();
     let announced = false;
-    const result = evaluateCompletedTracked(projectRoot, {
+    const land = evaluateCompletedTracked(projectRoot, {
         quiet: args.quiet,
         repo: args.repo,
         tip: args.tip,
@@ -117,15 +138,45 @@ export function run(argv) {
             writeProgress(event);
         },
     });
-    if (result.message.length > 0) {
-        if (result.stream === "stdout") {
-            process.stdout.write(`${result.message}\n`);
+    let discoveryCode = 0;
+    let discoveryMessage = "";
+    let discoveryStream = "none";
+    if (shouldRunDiscovery(args)) {
+        const discovery = evaluateShippedClosedDiscovery(projectRoot, {
+            quiet: args.quiet,
+            repo: args.repo,
+            tip: args.tip,
+            skipGh: args.skipGh,
+            enforce: args.enforce,
+        });
+        discoveryCode = discovery.code;
+        discoveryMessage = discovery.message;
+        discoveryStream = discovery.stream;
+    }
+    // Scoped land fail-closed must not be softened by discovery warn (#3495 Reject).
+    if (land.message.length > 0) {
+        if (land.stream === "stdout") {
+            process.stdout.write(`${land.message}\n`);
         }
-        else if (result.stream === "stderr") {
-            process.stderr.write(`${result.message}\n`);
+        else if (land.stream === "stderr") {
+            process.stderr.write(`${land.message}\n`);
         }
     }
-    return result.code;
+    if (discoveryMessage.length > 0) {
+        if (discoveryStream === "stdout") {
+            process.stdout.write(`${discoveryMessage}\n`);
+        }
+        else if (discoveryStream === "stderr") {
+            process.stderr.write(`${discoveryMessage}\n`);
+        }
+    }
+    if (land.code === 2 || discoveryCode === 2) {
+        return 2;
+    }
+    if (land.code === 1 || discoveryCode === 1) {
+        return 1;
+    }
+    return 0;
 }
 function resolveProgressThresholdMs() {
     const raw = process.env.DEFT_COMPLETED_TRACKED_PROGRESS_MS;

package/package.json

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