@deftai/directive 0.125.0 → 0.125.1

package/dist/authz.js

@@ -11,6 +11,8 @@
  *   deft authz:grant -- --template release-publish --target 0.30.0 [--confirm]
  *   deft authz:grant -- --template finish-loop [--confirm]
  *   deft authz:grant -- --template spec-drift-override --target <baseline> --plan-ref <scopeId> --story-ids <ids> [--confirm]
+ *   deft authz:grant -- --template gate-override --target <refuseCode> --plan-ref <attemptId> \\
+ *       --base-sha <sha> --head-sha <sha> --tree-hash <hash> [--confirm]
  *   deft authz:grant -- --parent <parent.xbrief.json> --draft <draft.json> [--repo owner/name] [--confirm]
  *   deft authz:revoke -- <grant-id> [--confirm]
  *
@@ -27,7 +29,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 { AFK_TEMPLATE_NAMES, AUTHZ_OPERATIONS, CLOSED_VERB_TEMPLATE_NAMES, FINISH_LOOP_TEMPLATE_NAME, formatDecomposeStructuralMintCommand, GATE_OVERRIDE_TEMPLATE_NAME, isAfkTemplateName, isClosedVerbTemplateName, isFinishLoopTemplateName, isGateOverrideTemplateName, mintAfkTemplateGrant, mintDecomposeStructuralApplyGrant, mintGateOverrideTemplateGrant, mintHumanOriginGrant, revokeGrant, showAuthzSnapshot, startUatLease, suspendUatLease, toProjectRelativePosix, } from "@deftai/directive-core/authz";
 import { uatCampaignEndSeal } from "@deftai/directive-core/authz/campaign-end-seal";
 import { isSpecDriftOverrideTemplateName, mintSpecDriftOverrideTemplateGrant, SPEC_DRIFT_OVERRIDE_TEMPLATE_NAME, } from "@deftai/directive-core/policy";
 import { refuseMintWhileUatActive, refuseNonInteractiveMint, resolveHumanPresenceMintSeams, } from "./human-presence-mint.js";
@@ -68,6 +70,11 @@ function parseArgv(argv) {
         target: null,
         parent: null,
         draft: null,
+        baseSha: null,
+        headSha: null,
+        treeHash: null,
+        worktree: null,
+        evaluatorId: null,
         format: "text",
         confirm: false,
     };
@@ -196,6 +203,26 @@ function parseArgv(argv) {
             base.draft = args[++i] ?? null;
             continue;
         }
+        if (a === "--base-sha" || a === "--baseSha") {
+            base.baseSha = args[++i] ?? null;
+            continue;
+        }
+        if (a === "--head-sha" || a === "--headSha") {
+            base.headSha = args[++i] ?? null;
+            continue;
+        }
+        if (a === "--tree-hash" || a === "--treeHash") {
+            base.treeHash = args[++i] ?? null;
+            continue;
+        }
+        if (a === "--worktree") {
+            base.worktree = args[++i] ?? null;
+            continue;
+        }
+        if (a === "--evaluator-id" || a === "--evaluatorId") {
+            base.evaluatorId = args[++i] ?? null;
+            continue;
+        }
         if (a === "--confirm") {
             base.confirm = true;
             continue;
@@ -255,6 +282,11 @@ function helpText() {
         `  Finish-loop (#871): ${FINISH_LOOP_TEMPLATE_NAME} — edit/push/pr/merge (no release ops)`,
         "  Templates call mintHumanOriginGrant only — no second session-auth mint engine.",
         "  Env bypass for a single shell: DEFT_ALLOW_RELEASE_PUBLISH=1 / DEFT_ALLOW_FINISH_LOOP=1.",
+        "",
+        `Gate-override (#5542): ${GATE_OVERRIDE_TEMPLATE_NAME}`,
+        "  deft authz:grant -- --template gate-override --target <refuseCode> --plan-ref <attemptId> \\",
+        "      --base-sha <sha> --head-sha <sha> --tree-hash <hash> [--worktree <id>] [--evaluator-id <id>] [--confirm]",
+        "  operator-cli human-presence only; waived ≠ passed; no independent push/merge.",
     ].join("\n");
 }
 export function main(argv = process.argv.slice(2), seams = {}) {
@@ -481,6 +513,59 @@ export function main(argv = process.argv.slice(2), seams = {}) {
                     process.stdout.write(`  origins=${claim.origins.map((o) => `${o.repo}#${o.issueId}`).join(",")}\n`);
                     return 0;
                 }
+                // Gate-override hatch (#5542 Prefer-A Bound): coverage-applicability refuse waiver.
+                if (args.template !== null && isGateOverrideTemplateName(args.template)) {
+                    if (args.target === null || args.target.trim().length === 0) {
+                        process.stderr.write("authz:grant --template gate-override requires --target <refuseCode>\n");
+                        return 2;
+                    }
+                    if (args.planRef === null || args.planRef.trim().length === 0) {
+                        process.stderr.write("authz:grant --template gate-override requires --plan-ref <attemptId>\n");
+                        return 2;
+                    }
+                    if (args.baseSha === null ||
+                        args.baseSha.trim().length === 0 ||
+                        args.headSha === null ||
+                        args.headSha.trim().length === 0 ||
+                        args.treeHash === null ||
+                        args.treeHash.trim().length === 0) {
+                        process.stderr.write("authz:grant --template gate-override requires --base-sha --head-sha --tree-hash\n");
+                        return 2;
+                    }
+                    const blockedGate = gateConfirm();
+                    if (blockedGate !== null)
+                        return blockedGate;
+                    const mintedGate = mintGateOverrideTemplateGrant({
+                        projectRoot: args.projectRoot,
+                        target: args.target,
+                        planRef: args.planRef,
+                        baseSha: args.baseSha,
+                        headSha: args.headSha,
+                        treeHash: args.treeHash,
+                        actor: args.actor,
+                        expiresAt: args.expiresAt,
+                        // gate-override template is always single-use (#5542 Greptile P2).
+                        singleUse: true,
+                        repo: args.repo,
+                        branch: args.branch,
+                        worktree: args.worktree,
+                        evaluatorId: args.evaluatorId,
+                        failedGateEvidence: args.note,
+                    });
+                    if (!mintedGate.ok) {
+                        process.stderr.write(`authz:grant: ${mintedGate.reason}\n`);
+                        return 2;
+                    }
+                    const gateGrant = mintedGate.grant;
+                    process.stdout.write(`✓ human-origin grant minted id=${gateGrant.id} origin=${gateGrant.origin.kind} ` +
+                        `template=${GATE_OVERRIDE_TEMPLATE_NAME}\n`);
+                    process.stdout.write(`  ops=[${gateGrant.scope.operations.join(",")}] attempt=${gateGrant.scope.planRef} ` +
+                        `surfaces=${gateGrant.scope.surfaces.join(", ")}\n`);
+                    process.stdout.write("  Hatch: waives coverage-applicability refuse for bound attempt/tree only; " +
+                        "waived ≠ passed; reviewObligation=pre-merge-human-review-required.\n");
+                    process.stdout.write("  Authorization SoT: Wave 1 grant store (.deft/authz/grants) — not session-auth / chat.\n");
+                    return 0;
+                }
                 // Spec-drift override hatch (#5350): policy module, not authz/** (class 4).
                 if (args.template !== null && isSpecDriftOverrideTemplateName(args.template)) {
                     if (args.target === null || args.target.trim().length === 0) {
@@ -525,7 +610,7 @@ export function main(argv = process.argv.slice(2), seams = {}) {
                 // AFK template path (#1095 / #871): presets only — still mintHumanOriginGrant.
                 if (args.template !== null && args.template.trim().length > 0) {
                     if (!isAfkTemplateName(args.template)) {
-                        process.stderr.write(`authz:grant unknown --template '${args.template}'; expected one of: ${AFK_TEMPLATE_NAMES.join(", ")}, ${SPEC_DRIFT_OVERRIDE_TEMPLATE_NAME}\n`);
+                        process.stderr.write(`authz:grant unknown --template '${args.template}'; expected one of: ${AFK_TEMPLATE_NAMES.join(", ")}, ${SPEC_DRIFT_OVERRIDE_TEMPLATE_NAME}, ${GATE_OVERRIDE_TEMPLATE_NAME}\n`);
                         return 2;
                     }
                     if (isClosedVerbTemplateName(args.template) &&
@@ -569,7 +654,7 @@ export function main(argv = process.argv.slice(2), seams = {}) {
                     return 0;
                 }
                 if (args.operations.length === 0) {
-                    process.stderr.write("authz:grant requires --operations <edit,push,...>, --template <finish-loop|release-*|spec-drift-override>, " +
+                    process.stderr.write("authz:grant requires --operations <edit,push,...>, --template <finish-loop|release-*|spec-drift-override|gate-override>, " +
                         "or --parent + --draft (structural scope:decompose apply)\n");
                     return 2;
                 }

package/dist/dispatch.d.ts

@@ -12,7 +12,7 @@ export interface DispatchIo {
 /** 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", "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", "verify-spec-drift", "rule-ownership-lint", "verify-story-ready", "verify-review-monitor", "verify-cohort-review-monitors", "verify-l4-owner", "verify-subagent-alive", "verify-subagent-steer", "subagent-pre-cancel", "subagent-steer-write", "design-critique-spend-resolve", "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-reconstruct", "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", "migrate-confidence", "rule-to-verb-parity"];
+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-reconstruct", "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", "tutorial", "migrate-clause-ids", "migrate-confidence", "rule-to-verb-parity"];
 /** Colon aliases for triage-actions (mirrors cli-router SUBCOMMAND_ROUTES). */
 export declare const TRIAGE_ACTION_ALIAS_SUBCOMMANDS: Readonly<Record<string, string>>;
 /** Colon aliases for policy subcommands (mirrors cli-router SUBCOMMAND_ROUTES). */
@@ -23,6 +23,8 @@ export declare const AUTHZ_ACTION_ALIAS_SUBCOMMANDS: Readonly<Record<string, str
 export declare const ESCALATION_ACTION_ALIAS_SUBCOMMANDS: Readonly<Record<string, string>>;
 /** Colon aliases for plan-sequence subcommands (#2402). */
 export declare const PLAN_SEQUENCE_ALIAS_SUBCOMMANDS: Readonly<Record<string, string>>;
+/** Colon aliases for the Directive Tutorial (#4981). */
+export declare const TUTORIAL_ALIAS_SUBCOMMANDS: Readonly<Record<string, string>>;
 /** Colon aliases for product-signal subcommands (#2693). */
 export declare const PRODUCT_SIGNAL_ALIAS_SUBCOMMANDS: Readonly<Record<string, string>>;
 /** Colon aliases for freshness subcommands (#3117). */

package/dist/dispatch.js

@@ -243,6 +243,7 @@ export const CORE_MODULE_VERBS = [
     "decision-write",
     "decision-list",
     "docs-impact",
+    "tutorial",
     "migrate-clause-ids",
     "migrate-confidence",
     "rule-to-verb-parity",
@@ -301,6 +302,20 @@ export const PLAN_SEQUENCE_ALIAS_SUBCOMMANDS = {
     "plan-sequence:advance": "advance",
 };
 const PLAN_SEQUENCE_COLON_ALIASES = Object.fromEntries(Object.keys(PLAN_SEQUENCE_ALIAS_SUBCOMMANDS).map((alias) => [alias, "plan-sequence"]));
+/** Colon aliases for the Directive Tutorial (#4981). */
+export const TUTORIAL_ALIAS_SUBCOMMANDS = {
+    "tutorial:offer": "offer",
+    "tutorial:start": "start",
+    "tutorial:inspect": "inspect",
+    "tutorial:advance": "advance",
+    "tutorial:resume": "resume",
+    "tutorial:skip": "skip",
+    "tutorial:leave": "leave",
+    "tutorial:reset": "reset",
+    "tutorial:decline": "decline",
+    "tutorial:defer": "defer",
+};
+const TUTORIAL_COLON_ALIASES = Object.fromEntries(Object.keys(TUTORIAL_ALIAS_SUBCOMMANDS).map((alias) => [alias, "tutorial"]));
 /** Colon aliases for product-signal subcommands (#2693). */
 export const PRODUCT_SIGNAL_ALIAS_SUBCOMMANDS = {
     "product-signal:status": "status",
@@ -416,6 +431,7 @@ export const VERB_ALIASES = {
     "verify:session-ritual": "verify-session-ritual",
     "verify:plan-sequence": "verify-plan-sequence",
     ...PLAN_SEQUENCE_COLON_ALIASES,
+    ...TUTORIAL_COLON_ALIASES,
     "verify-strategy-output": "validate-strategy-output",
     "validate:strategy-output": "validate-strategy-output",
     "verify:codebase-map-fresh": "codebase-map-fresh",
@@ -2662,6 +2678,10 @@ async function loadCoreModuleHandler(verb, io) {
             const { docsImpactMain } = await import("@deftai/directive-core/dist/docs/docs-impact.js");
             return (argv) => docsImpactMain(argv);
         }
+        case "tutorial": {
+            const { tutorialMain } = await import("@deftai/directive-core/dist/tutorial/cli.js");
+            return tutorialMain;
+        }
         case "migrate-clause-ids": {
             const { mainEntry } = await import("@deftai/directive-core/dist/xbrief-migrate/clause-ids.js");
             return (argv) => mainEntry(argv);
@@ -3013,6 +3033,7 @@ export async function dispatch(argv, io = defaultIo()) {
         const authzSubcommand = verb !== undefined ? AUTHZ_ACTION_ALIAS_SUBCOMMANDS[verb] : undefined;
         const escalationSubcommand = verb !== undefined ? ESCALATION_ACTION_ALIAS_SUBCOMMANDS[verb] : undefined;
         const planSequenceSubcommand = verb !== undefined ? PLAN_SEQUENCE_ALIAS_SUBCOMMANDS[verb] : undefined;
+        const tutorialSubcommand = verb !== undefined ? TUTORIAL_ALIAS_SUBCOMMANDS[verb] : undefined;
         const productSignalSubcommand = verb !== undefined ? PRODUCT_SIGNAL_ALIAS_SUBCOMMANDS[verb] : undefined;
         const freshnessSubcommand = verb !== undefined ? FRESHNESS_ALIAS_SUBCOMMANDS[verb] : undefined;
         const vbriefValidateSubcommand = verb === "verify:vbrief-conformance" && canonical === "vbrief-validate"
@@ -3030,13 +3051,15 @@ export async function dispatch(argv, io = defaultIo()) {
                             ? [escalationSubcommand, ...rest]
                             : planSequenceSubcommand !== undefined && canonical === "plan-sequence"
                                 ? [planSequenceSubcommand, ...rest]
-                                : productSignalSubcommand !== undefined && canonical === "product-signal"
-                                    ? [productSignalSubcommand, ...rest]
-                                    : freshnessSubcommand !== undefined && canonical === "freshness-report"
-                                        ? [freshnessSubcommand, ...rest]
-                                        : vbriefValidateSubcommand !== undefined
-                                            ? [vbriefValidateSubcommand, ...rest]
-                                            : rest;
+                                : tutorialSubcommand !== undefined && canonical === "tutorial"
+                                    ? [tutorialSubcommand, ...rest]
+                                    : productSignalSubcommand !== undefined && canonical === "product-signal"
+                                        ? [productSignalSubcommand, ...rest]
+                                        : freshnessSubcommand !== undefined && canonical === "freshness-report"
+                                            ? [freshnessSubcommand, ...rest]
+                                            : vbriefValidateSubcommand !== undefined
+                                                ? [vbriefValidateSubcommand, ...rest]
+                                                : rest;
         const helpRc = interceptHelp(canonical.replaceAll("-", "_"), handlerArgv, {
             write: io.writeOut,
         });

package/package.json

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