@deftai/directive 0.100.0 → 0.101.0

package/dist/agents-refresh.js

@@ -1,10 +1,13 @@
 #!/usr/bin/env node
 /**
  * agents:refresh — rewrite AGENTS.md managed section from the canonical template (#768 / #1996).
+ * #3286: when the managed section is already current, print one-line
+ * "unchanged - sha match" (content-based; always plans against the live AGENTS.md).
  */
 import { resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { applyAgentsRefresh } from "@deftai/directive-core/platform";
+import { formatDepositShaMatchLine } from "@deftai/directive-core/session";
 export function parseAgentsRefreshArgs(argv) {
     let projectRoot = process.cwd();
     let check = false;
@@ -40,6 +43,9 @@ export function runAgentsRefresh(argv) {
         process.stderr.write(`agents:refresh: ${args.error}\n`);
         return 2;
     }
+    // Always plan against live AGENTS.md (#3286 Greptile P1: deposit fingerprint
+    // alone cannot detect local managed-section edits). Content-current → one-line
+    // sha-match phrasing for harness parsers.
     // The read->compute->write is serialized behind an advisory lock and written
     // atomically inside applyAgentsRefresh, so concurrent refreshers cannot clobber
     // one another's session= write or observe a partial write (#1329).
@@ -54,7 +60,8 @@ export function runAgentsRefresh(argv) {
         return 1;
     }
     if (state === "current") {
-        process.stdout.write("AGENTS.md managed section is current — no changes.\n");
+        // #3286: one-line no-op phrasing when managed section already matches template.
+        process.stdout.write(`${formatDepositShaMatchLine("agents:refresh")}\n`);
         return 0;
     }
     if (state === "template-missing" || state === "template-malformed" || state === "unreadable") {

package/dist/authz.js

@@ -1,7 +1,8 @@
 #!/usr/bin/env node
 /**
- * Authz CLI (#2944 Wave 1 + #1095 Wave 4 + #3110): human-origin grants + UAT lease +
- * AFK closed-verb templates (mint via mintHumanOriginGrant only).
+ * Authz CLI (#2944 Wave 1 + #1095 Wave 4 + #3110 + #3291): human-origin grants + UAT lease +
+ * AFK closed-verb templates + structural scope:decompose apply grants
+ * (mint via mintHumanOriginGrant / mintDecomposeStructuralApplyGrant only).
  *
  *   deft authz:show
  *   deft authz:uat-start -- --campaign <id> [--actor <name>] [--note <text>] [--confirm]
@@ -9,6 +10,7 @@
  *   deft authz:grant -- --operations edit,push --surfaces 'src/**' --cohort <id> ... [--confirm]
  *   deft authz:grant -- --template release-publish --target 0.30.0 [--confirm]
  *   deft authz:grant -- --template finish-loop [--confirm]
+ *   deft authz:grant -- --parent <parent.xbrief.json> --draft <draft.json> [--repo owner/name] [--confirm]
  *   deft authz:revoke -- <grant-id> [--confirm]
  *
  * **UAT-active hard refuse (#3110):** while any UAT lease is active, ALL mutating
@@ -20,8 +22,9 @@
  * TTY + controlling terminal + `--confirm` + typed phrase `mint`; agent/CI env
  * markers refuse fail-closed. Argv `--confirm` alone is never enough.
  */
-import { closeSync, openSync, readSync } from "node:fs";
-import { AFK_TEMPLATE_NAMES, AUTHZ_OPERATIONS, CLOSED_VERB_TEMPLATE_NAMES, FINISH_LOOP_TEMPLATE_NAME, isAfkTemplateName, isClosedVerbTemplateName, isFinishLoopTemplateName, loadAuthzState, mintAfkTemplateGrant, mintHumanOriginGrant, revokeGrant, showAuthzSnapshot, startUatLease, suspendUatLease, } from "@deftai/directive-core/authz";
+import { closeSync, existsSync, openSync, readSync } from "node:fs";
+import { isAbsolute, resolve } from "node:path";
+import { AFK_TEMPLATE_NAMES, AUTHZ_OPERATIONS, CLOSED_VERB_TEMPLATE_NAMES, FINISH_LOOP_TEMPLATE_NAME, formatDecomposeStructuralMintCommand, isAfkTemplateName, isClosedVerbTemplateName, isFinishLoopTemplateName, loadAuthzState, mintAfkTemplateGrant, mintDecomposeStructuralApplyGrant, mintHumanOriginGrant, revokeGrant, showAuthzSnapshot, startUatLease, suspendUatLease, toProjectRelativePosix, } from "@deftai/directive-core/authz";
 /**
  * Env markers that indicate an agent/host/CI shell even when stdin reports a TTY
  * (pseudo-terminal residual; #3110 Greptile). Presence refuses mutating authz.
@@ -104,6 +107,8 @@ function parseArgv(argv) {
         grantId: null,
         template: null,
         target: null,
+        parent: null,
+        draft: null,
         format: "text",
         confirm: false,
     };
@@ -224,6 +229,14 @@ function parseArgv(argv) {
             base.target = args[++i] ?? null;
             continue;
         }
+        if (a === "--parent") {
+            base.parent = args[++i] ?? null;
+            continue;
+        }
+        if (a === "--draft") {
+            base.draft = args[++i] ?? null;
+            continue;
+        }
         if (a === "--confirm") {
             base.confirm = true;
             continue;
@@ -248,6 +261,8 @@ function helpText() {
         "      [--stories 2944] [--plan-ref <id>] [--repo owner/name] [--branch <b>] [--expires ISO] [--confirm]",
         "  deft authz:grant -- --template release-publish --target 0.30.0 [--actor <name>] [--expires ISO] [--confirm]",
         "  deft authz:grant -- --template finish-loop [--actor <name>] [--expires ISO] [--confirm]",
+        "  deft authz:grant -- --parent <parent.xbrief.json> --draft <draft.json> \\",
+        "      [--repo owner/name] [--expires ISO] [--single-use] [--actor <name>] [--confirm]",
         "  deft authz:revoke -- <grant-id> [--confirm]",
         "",
         "Human-origin grants are minted only via this CLI (origin.kind=operator-cli).",
@@ -263,6 +278,16 @@ function helpText() {
         "  End UAT only after the lease is cleared out-of-band (state edit / suspend path",
         "  that does not run while the lease is active) — or suspend before re-minting.",
         "",
+        "Structural scope:decompose apply (#3239 / #3291):",
+        "  Pass --parent + --draft (paths under project root). Digest is SHA-256 of exact",
+        "  draft bytes; binds parent, target, worktree, and optional --repo. Mints only",
+        "  scope.decompose.apply.structural via mintDecomposeStructuralApplyGrant.",
+        "  Example (after --check validates the draft):",
+        "    deft authz:grant -- --parent xbrief/pending/epic.xbrief.json \\",
+        "        --draft xbrief/.triage-cache/decompositions/draft.json --confirm",
+        "  Then: deft scope:decompose -- <parent> --draft <draft>",
+        "  scope:decompose --check remains ungated (no structural grant required).",
+        "",
         `AFK templates (#1095 / #871): ${AFK_TEMPLATE_NAMES.join(", ")}`,
         `  Closed-verb (#1095): ${CLOSED_VERB_TEMPLATE_NAMES.join(", ")} — require --target`,
         `  Finish-loop (#871): ${FINISH_LOOP_TEMPLATE_NAME} — edit/push/pr/merge (no release ops)`,
@@ -487,6 +512,75 @@ export function main(argv = process.argv.slice(2), seams = {}) {
                 return 0;
             }
             case "grant": {
+                // Structural decompose apply path (#3291): --parent + --draft → mintDecomposeStructuralApplyGrant.
+                const parentRaw = args.parent?.trim() ?? "";
+                const draftRaw = args.draft?.trim() ?? "";
+                const hasParent = parentRaw.length > 0;
+                const hasDraft = draftRaw.length > 0;
+                if (hasParent !== hasDraft) {
+                    process.stderr.write("authz:grant structural mint requires both --parent <path> and --draft <path>\n" +
+                        `  Example: ${formatDecomposeStructuralMintCommand(hasParent ? parentRaw : "xbrief/pending/parent.xbrief.json", hasDraft ? draftRaw : "xbrief/.triage-cache/decompositions/draft.json", { repo: args.repo })}\n`);
+                    return 2;
+                }
+                if (hasParent && hasDraft) {
+                    if (args.template !== null && args.template.trim().length > 0) {
+                        process.stderr.write("authz:grant: --parent/--draft structural mint cannot be combined with --template\n");
+                        return 2;
+                    }
+                    if (args.operations.length > 0) {
+                        process.stderr.write("authz:grant: --parent/--draft structural mint cannot be combined with --operations " +
+                            "(operation is fixed to scope.decompose.apply.structural)\n");
+                        return 2;
+                    }
+                    const root = resolve(args.projectRoot);
+                    const parentAbs = isAbsolute(parentRaw) ? resolve(parentRaw) : resolve(root, parentRaw);
+                    const draftAbs = isAbsolute(draftRaw) ? resolve(draftRaw) : resolve(root, draftRaw);
+                    const parentRel = toProjectRelativePosix(root, parentAbs);
+                    const draftRel = toProjectRelativePosix(root, draftAbs);
+                    if (parentRel === null) {
+                        process.stderr.write(`authz:grant: --parent path is outside project root: ${parentRaw}\n`);
+                        return 2;
+                    }
+                    if (draftRel === null) {
+                        process.stderr.write(`authz:grant: --draft path is outside project root: ${draftRaw}\n`);
+                        return 2;
+                    }
+                    if (!existsSync(parentAbs)) {
+                        process.stderr.write(`authz:grant: --parent path does not exist: ${parentRaw}\n`);
+                        return 2;
+                    }
+                    if (!existsSync(draftAbs)) {
+                        process.stderr.write(`authz:grant: --draft path does not exist: ${draftRaw}\n`);
+                        return 2;
+                    }
+                    const blocked = gateConfirm();
+                    if (blocked !== null)
+                        return blocked;
+                    const grant = mintDecomposeStructuralApplyGrant({
+                        projectRoot: root,
+                        parentPath: parentAbs,
+                        draftPath: draftAbs,
+                        actor: args.actor,
+                        repo: args.repo,
+                        expiresAt: args.expiresAt,
+                        singleUse: args.singleUse,
+                    });
+                    // 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`);
+                    process.stdout.write(`  ops=[${grant.scope.operations.join(",")}] digest=${digest.slice(0, 12)}…\n`);
+                    process.stdout.write(`  parent=${parentRel} draft=${draftRel}\n`);
+                    if (grant.scope.repo) {
+                        process.stdout.write(`  repo=${grant.scope.repo}\n`);
+                    }
+                    process.stdout.write(`  worktree=${grant.scope.worktree || root}\n`);
+                    if (grant.semantics.singleUse) {
+                        process.stdout.write("  single-use=true (spent on first successful apply)\n");
+                    }
+                    process.stdout.write("  Apply: deft scope:decompose -- <parent> --draft <draft>\n" +
+                        "  Authorization SoT: Wave 1 grant store (.deft/authz/grants) — not session-auth.\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)) {
@@ -529,7 +623,8 @@ 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,...> or --template <finish-loop|release-*> \n");
+                    process.stderr.write("authz:grant requires --operations <edit,push,...>, --template <finish-loop|release-*>, " +
+                        "or --parent + --draft (structural scope:decompose apply)\n");
                     return 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", "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-completed-tracked", "verify-literal-ac", "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-completed-tracked", "verify-literal-ac", "verify-ac", "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-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"];
 /** Colon aliases for triage-actions (mirrors cli-router SUBCOMMAND_ROUTES). */

package/dist/dispatch.js

@@ -139,6 +139,7 @@ export const CLI_MODULE_VERBS = [
     "verify-orphan-active",
     "verify-completed-tracked",
     "verify-literal-ac",
+    "verify-ac",
     "verify-agents-md-budget",
     "verify-agents-md-advisory",
     "verify-eval-health-relocation",
@@ -284,6 +285,8 @@ export const VERB_ALIASES = {
     "verify:completed-tracked": "verify-completed-tracked",
     "verify:literal-ac": "verify-literal-ac",
     "verify:literal-acceptance": "verify-literal-ac",
+    "verify:ac": "verify-ac",
+    "verify:acceptance": "verify-ac",
     "verify:agents-md-budget": "verify-agents-md-budget",
     "verify:agents-md-advisory": "verify-agents-md-advisory",
     "verify:eval-health-relocation": "verify-eval-health-relocation",

package/dist/session-start.d.ts

@@ -27,6 +27,11 @@ export interface ParsedSessionStartArgs {
         maxBudget?: number;
         hardBudget?: boolean;
     };
+    /**
+     * #3286: compact orientation output (terse machine format). Verbose remains
+     * the default; also settable via DEFT_SESSION_COMPACT=1.
+     */
+    compact: boolean;
     error?: string;
 }
 /** Parse session:start CLI args, mirroring scripts/session_start.py. */

package/dist/session-start.js

@@ -30,6 +30,7 @@ export function parseArgs(argv) {
         ceremonyDialInputs: {},
         ceremonyDepthOverride: null,
         effortBudgetHost: {},
+        compact: false,
     };
     const dialInputs = {};
     for (let i = 0; i < argv.length; i += 1) {
@@ -268,6 +269,10 @@ export function parseArgs(argv) {
         else if (arg === "--hard-budget") {
             parsed.effortBudgetHost.hardBudget = true;
         }
+        else if (arg === "--compact") {
+            // #3286: terse machine orientation output (opt-in; verbose remains default)
+            parsed.compact = true;
+        }
         else {
             return { ...parsed, error: `unrecognized argument: ${arg}` };
         }
@@ -328,6 +333,8 @@ export function run(argv) {
             ceremonyTier: args.ceremonyTier,
             ceremonyDialInputs: args.ceremonyDialInputs,
             effortBudgetSeams: { hostDescriptor, environ: process.env },
+            // #3286: --compact flag; DEFT_SESSION_COMPACT still resolved inside core.
+            compact: args.compact ? true : undefined,
             ...(args.ceremonyDepthOverride !== null
                 ? {
                     ceremonyDial: selectCeremonyDepth({

package/dist/triage-classify.d.ts

@@ -17,6 +17,11 @@ export interface ParsedArgs {
      * (#3197). Requires --mirror; dry-run by default until --apply.
      */
     reEnrich: boolean;
+    /**
+     * Dismiss SCM label-mirror discovery tip without running a dry-run (#3124).
+     * Standalone production entry for recordMirrorDiscoveryAcked.
+     */
+    ackDiscovery: boolean;
     /** Raw --author value (LOGIN, @me, comma allow-list); null = no filter (#3129). */
     author: string | null;
     /** Apply batch size (rate-limit awareness). */

package/dist/triage-classify.js

@@ -3,7 +3,7 @@ import { statSync } from "node:fs";
 import { resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { resolveAuthorFilter, } from "@deftai/directive-core/dist/triage/author-filter.js";
-import { labelMirrorOutcomeToJson, listProject, mirrorLabels, renderLabelMirrorReport, validateProject, } from "@deftai/directive-core/dist/triage/classify/index.js";
+import { labelMirrorOutcomeToJson, listProject, mirrorDiscoveryStateExists, mirrorLabels, recordMirrorDiscoveryAcked, recordMirrorDiscoverySuccessfulDryRun, renderLabelMirrorReport, validateProject, } from "@deftai/directive-core/dist/triage/classify/index.js";
 function parseNonNegInt(raw, flag) {
     const n = Number.parseInt(raw, 10);
     if (!Number.isFinite(n) || String(n) !== raw.trim() || n < 0) {
@@ -37,6 +37,7 @@ export function parseArgs(argv) {
         allowCrossRepo: false,
         includeClosed: false,
         reEnrich: false,
+        ackDiscovery: false,
         author: null,
         batchSize: null,
         delayMs: null,
@@ -68,6 +69,9 @@ export function parseArgs(argv) {
         else if (arg === "--re-enrich") {
             parsed.reEnrich = true;
         }
+        else if (arg === "--ack-discovery") {
+            parsed.ackDiscovery = true;
+        }
         else if (arg === "--author-mine") {
             parsed.author = "@me";
         }
@@ -179,6 +183,8 @@ export function parseArgs(argv) {
         else if (arg === "--help" || arg === "-h") {
             return parsed;
         }
+        else if (arg === "--") {
+        }
         else if (arg?.startsWith("-")) {
             return { ...parsed, error: `unrecognized arguments: ${arg}` };
         }
@@ -206,6 +212,14 @@ export function parseArgs(argv) {
             error: "--include-closed / --author / --batch-size / --delay-ms / --sample-limit require --mirror (#3125 / #3129)",
         };
     }
+    // --ack-discovery is standalone (production entry for tip dismissal without dry-run).
+    // Combining with --mirror is allowed: ack runs first, then mirror proceeds.
+    if (parsed.ackDiscovery && (parsed.doList || parsed.doValidate) && !parsed.doMirror) {
+        return {
+            ...parsed,
+            error: "--ack-discovery cannot combine with --list/--validate without --mirror",
+        };
+    }
     return parsed;
 }
 /** Run the CLI and return the process exit code. */
@@ -237,6 +251,29 @@ export function run(argv, options = {}) {
         }
         return result.code;
     }
+    // #3124: production entry for operator ack (dismiss tip without dry-run).
+    if (args.ackDiscovery) {
+        try {
+            recordMirrorDiscoveryAcked(projectRoot);
+            const statePresent = mirrorDiscoveryStateExists(projectRoot);
+            if (args.json) {
+                process.stdout.write(`${JSON.stringify({ ok: true, ack_discovery: true, projectRoot, statePresent }, null, 2)}\n`);
+            }
+            else {
+                process.stdout.write("[deft triage] SCM label-mirror discovery tip acknowledged " +
+                    `(state ${statePresent ? "persisted" : "missing"}) — ` +
+                    "will not re-surface until state is cleared.\n");
+            }
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            process.stderr.write(`ERR: failed to record discovery ack: ${msg}\n`);
+            return 1;
+        }
+        if (!args.doMirror) {
+            return 0;
+        }
+    }
     if (args.doMirror) {
         let authorFilter = null;
         // Flag present (including empty `--author=`) must resolve or fail closed —
@@ -268,6 +305,15 @@ export function run(argv, options = {}) {
         else {
             process.stdout.write(renderLabelMirrorReport(outcome));
         }
+        // #3124: first successful --mirror dry-run hides the operator discovery tip.
+        if (code === 0 && outcome.dry_run) {
+            try {
+                recordMirrorDiscoverySuccessfulDryRun(projectRoot);
+            }
+            catch {
+                // Advisory tip state — never change the classify exit code.
+            }
+        }
         return code;
     }
     // Default / --list: print effective rules

package/dist/verify-ac.d.ts

@@ -0,0 +1,26 @@
+#!/usr/bin/env node
+interface ParsedArgs {
+    projectRoot: string;
+    xbriefPath: string | null;
+    quiet: boolean;
+    captureOnly: boolean;
+    softMissingXbrief: boolean;
+    error?: string;
+}
+/** Parse verify:ac CLI args. */
+export declare function parseArgs(argv: string[]): ParsedArgs;
+/** Result of scanning lifecycle active/ for scope artifacts. */
+export type FindActiveXbriefResult = {
+    readonly kind: "one";
+    readonly path: string;
+} | {
+    readonly kind: "none";
+} | {
+    readonly kind: "many";
+    readonly paths: readonly string[];
+    readonly dir: string;
+};
+/** Run the gate and return the process exit code. */
+export declare function run(argv: string[]): number;
+export {};
+//# sourceMappingURL=verify-ac.d.ts.map

package/dist/verify-ac.js

@@ -0,0 +1,244 @@
+#!/usr/bin/env node
+/**
+ * CLI: task verify:ac — product-first acceptance criteria gate (#3284).
+ *
+ * Runs plan.acceptance.commands (or #3267 literal ledger) verbatim.
+ * Primary name for the product-first done-gate; verify:literal-ac remains
+ * the #3267 mechanism alias.
+ */
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { formatRejectedLedger, resolveLiteralAcceptanceDetailed, } from "@deftai/directive-core/literal-acceptance";
+import { evaluateVerifyAcFromPath, readPlanAcceptance, } from "@deftai/directive-core/product-first-done-gate";
+/** Parse verify:ac CLI args. */
+export function parseArgs(argv) {
+    const parsed = {
+        projectRoot: ".",
+        xbriefPath: null,
+        quiet: false,
+        captureOnly: false,
+        softMissingXbrief: false,
+    };
+    const positionals = [];
+    for (let i = 0; i < argv.length; i += 1) {
+        const arg = argv[i];
+        if (arg === "--quiet") {
+            parsed.quiet = true;
+        }
+        else if (arg === "--capture-only") {
+            parsed.captureOnly = true;
+        }
+        else if (arg === "--soft-missing-xbrief") {
+            parsed.softMissingXbrief = 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 === "--xbrief" || arg === "--vbrief") {
+            const value = argv[i + 1];
+            if (value === undefined) {
+                return { ...parsed, error: `argument ${arg}: expected one argument` };
+            }
+            parsed.xbriefPath = value;
+            i += 1;
+        }
+        else if (arg?.startsWith("--xbrief=") || arg?.startsWith("--vbrief=")) {
+            parsed.xbriefPath = arg.slice(arg.indexOf("=") + 1);
+        }
+        else if (arg?.startsWith("-")) {
+            return { ...parsed, error: `unrecognized argument: ${arg}` };
+        }
+        else if (arg !== undefined) {
+            positionals.push(arg);
+        }
+    }
+    if (parsed.xbriefPath === null && positionals.length > 0) {
+        parsed.xbriefPath = positionals[0] ?? null;
+    }
+    return parsed;
+}
+function listActiveXbriefs(projectRoot) {
+    // Greptile conf residual #3284: scan BOTH lifecycle roots (xbrief + read-accepted
+    // vbrief). Returning after the first non-empty root left the other unchecked.
+    const paths = [];
+    const dirs = [];
+    for (const dirName of ["xbrief", "vbrief"]) {
+        const active = join(projectRoot, dirName, "active");
+        if (!existsSync(active))
+            continue;
+        let names = [];
+        try {
+            names = readdirSync(active)
+                .filter((n) => n.endsWith(".xbrief.json") || n.endsWith(".vbrief.json"))
+                .sort();
+        }
+        catch {
+            continue;
+        }
+        if (names.length === 0)
+            continue;
+        dirs.push(active);
+        for (const n of names) {
+            paths.push(join(active, n));
+        }
+    }
+    if (paths.length === 0)
+        return { kind: "none" };
+    if (paths.length === 1) {
+        return { kind: "one", path: paths[0] };
+    }
+    return {
+        kind: "many",
+        paths,
+        dir: dirs.join(" + "),
+    };
+}
+/** Evaluate one or many xBRIEF paths; return worst non-zero code (fail closed). */
+function evaluatePaths(paths, options) {
+    let worst = 0;
+    for (const path of paths) {
+        if (!options.quiet && paths.length > 1) {
+            process.stdout.write(`verify:ac — evaluating ${path}\n`);
+        }
+        const result = evaluateVerifyAcFromPath(path, {
+            projectRoot: options.projectRoot,
+            quiet: options.quiet,
+            softMissingXbrief: options.softMissingXbrief,
+            checkIntegrated: options.softMissingXbrief,
+        });
+        if (result.message.length > 0) {
+            if (result.ok) {
+                process.stdout.write(`${result.message}\n`);
+            }
+            else {
+                process.stderr.write(`${result.message}\n`);
+            }
+        }
+        if (result.code !== 0 && (worst === 0 || result.code > worst)) {
+            // Prefer code 1 (fail) over 2 when both present — still non-zero.
+            worst = result.code;
+        }
+    }
+    return worst;
+}
+function asRecord(value) {
+    if (typeof value === "object" && value !== null && !Array.isArray(value)) {
+        return value;
+    }
+    return null;
+}
+/** 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_ac: ${args.error}\n`);
+        return 2;
+    }
+    const projectRoot = resolve(args.projectRoot);
+    let paths = [];
+    if (args.xbriefPath !== null) {
+        paths = [resolve(projectRoot, args.xbriefPath)];
+    }
+    else {
+        const found = listActiveXbriefs(projectRoot);
+        if (found.kind === "one") {
+            paths = [found.path];
+        }
+        else if (found.kind === "many") {
+            // Greptile #3284: multi-active must verify EVERY active scope, not skip.
+            if (args.softMissingXbrief || args.captureOnly) {
+                paths = [...found.paths];
+                if (!args.quiet) {
+                    process.stdout.write(`verify:ac multi-active (#3284): evaluating ${paths.length} scopes in ${found.dir}\n`);
+                }
+            }
+            else {
+                process.stderr.write(`verify_ac: ${found.paths.length} active scopes in ${found.dir}.\n` +
+                    "  Pass an explicit path, or use check composition (--soft-missing-xbrief) to evaluate all.\n" +
+                    "  Usage: task verify:ac -- <path-to-active.xbrief.json>\n" +
+                    "  Refs #3284 product-first done-gate\n");
+                return 1;
+            }
+        }
+        else if (args.softMissingXbrief) {
+            if (!args.quiet) {
+                process.stdout.write("verify:ac skipped (#3284 soft-missing): no active xBRIEF in xbrief/active/\n");
+            }
+            return 0;
+        }
+        else {
+            process.stderr.write("verify_ac: pass an xBRIEF path or ensure exactly one artifact in xbrief/active/\n" +
+                "  Usage: task verify:ac -- <path-to-active.xbrief.json>\n" +
+                "  Refs #3284 product-first done-gate (mechanism #3267)\n");
+            return 2;
+        }
+    }
+    if (args.captureOnly) {
+        // Capture-only: report each path (multi-active) as a list.
+        const reports = [];
+        for (const xbriefPath of paths) {
+            try {
+                const data = asRecord(JSON.parse(readFileSync(xbriefPath, "utf8")));
+                if (data === null) {
+                    process.stderr.write(`verify_ac: xBRIEF top-level is not an object: ${xbriefPath}\n`);
+                    return 2;
+                }
+                const plan = asRecord(data.plan);
+                if (plan === null) {
+                    process.stderr.write(`verify_ac: xBRIEF missing plan object: ${xbriefPath}\n`);
+                    return 2;
+                }
+                const acceptance = readPlanAcceptance(plan);
+                const resolved = resolveLiteralAcceptanceDetailed(plan, { captureFromNarratives: true });
+                reports.push({
+                    xbrief: xbriefPath,
+                    source_rung: acceptance.source_rung,
+                    none_stated: acceptance.none_stated,
+                    acceptance_commands: acceptance.commands,
+                    count: resolved.commands.length,
+                    rejected_count: resolved.rejected.length,
+                    commands: resolved.commands.map((c) => ({
+                        command: c.command,
+                        source: c.source,
+                        sourceSpan: c.sourceSpan ?? null,
+                        cwd: c.cwd ?? null,
+                        expectedExitCode: c.expectedExitCode ?? 0,
+                    })),
+                    rejected: resolved.rejected.map((r) => ({
+                        command: r.command,
+                        reason: r.reason,
+                        sourceSpan: r.sourceSpan ?? null,
+                    })),
+                });
+                if (resolved.rejected.length > 0) {
+                    process.stderr.write(`${formatRejectedLedger(resolved.rejected)}\n`);
+                }
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                process.stderr.write(`verify_ac: ${msg}\n`);
+                return 2;
+            }
+        }
+        process.stdout.write(`${JSON.stringify(reports.length === 1 ? reports[0] : { scopes: reports }, null, 2)}\n`);
+        return 0;
+    }
+    return evaluatePaths(paths, {
+        projectRoot,
+        quiet: args.quiet,
+        softMissingXbrief: args.softMissingXbrief,
+    });
+}
+if (process.argv[1] !== undefined && fileURLToPath(import.meta.url) === process.argv[1]) {
+    process.exit(run(process.argv.slice(2)));
+}
+//# sourceMappingURL=verify-ac.js.map

package/package.json

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