@deftai/directive-core 0.95.0 → 0.97.0

package/dist/triage/classify/label-mirror.js

@@ -1,10 +1,14 @@
 /**
- * Tier-1 deterministic SCM label mirror (#1423 Wave 1).
+ * Tier-1 deterministic SCM label mirror (#1423 Wave 1 + Wave 2 bootstrap).
  *
  * Classifies cached issues with the existing #1129 engine, then mirrors the
  * outcome as SCM labels (dry-run default, --apply to write). Never accepts into
  * the xBRIEF lifecycle and never writes proposed/ scopes.
  *
+ * Wave 2 (#3125): open-only default, operator digest (totals + by state/rule/action
+ * + samples), batched rate-limit-aware apply. Bootstrap mass-triage entrypoint is
+ * `triage:classify -- --mirror` with these filters (not triage:accept).
+ *
  * Intentionally does NOT import from ./index.js (SLizard P1 cycle). The classify
  * engine is injected via LabelMirrorEngine / mirrorLabels() wrapper in index.ts.
  */
@@ -16,11 +20,18 @@ import { readPlanPolicy } from "../../policy/plan-extensions.js";
 import { ScmLabelClient } from "../../vbrief-reconcile/labels.js";
 import { isRepoMutationAllowed } from "../../vbrief-reconcile/repo-guard.js";
 import { latestDecisions, readAuditLog } from "../actions/candidates-log.js";
+import { authorLoginFromRawIssue, matchesAuthorFilter, } from "../author-filter.js";
 import { resolveCandidatesLogPath } from "../cache-path.js";
 import { iterCachedIssues } from "../summary/index.js";
 export const DEFAULT_IDEMPOTENCY_LABEL = "triaged";
 export const CACHE_DIR_NAME = ".deft-cache";
 export const CACHE_SOURCE = "github-issue";
+/** Default apply batch size for rate-limit awareness (#3125). */
+export const DEFAULT_APPLY_BATCH_SIZE = 10;
+/** Default delay between apply batches in ms (#3125). */
+export const DEFAULT_APPLY_DELAY_MS = 1000;
+/** Default sample count in human digest (#3125). */
+export const DEFAULT_DIGEST_SAMPLE_LIMIT = 15;
 const VALID_ACTIONS = new Set(["defer", "archive", "escalate", "accept"]);
 /**
  * Repo-qualified xBRIEF github-issue keys (`owner/name\\0number`).
@@ -308,10 +319,72 @@ function loadLatestDecisionMap(projectRoot) {
 function decisionMapHas(map, repo, issueNumber) {
     return map.has(`${repo}\0${issueNumber}`);
 }
+function defaultSleepMs(ms) {
+    if (ms <= 0) {
+        return;
+    }
+    // Sync sleep: LabelClient.apply is sync; keep mirrorLabels non-async (#3125).
+    const sab = new SharedArrayBuffer(4);
+    const ia = new Int32Array(sab);
+    Atomics.wait(ia, 0, 0, ms);
+}
+function normalizeIssueState(raw) {
+    if (typeof raw !== "string" || raw.trim().length === 0) {
+        return null;
+    }
+    return raw.trim().toLowerCase();
+}
+function isClosedState(state) {
+    return state === "closed";
+}
+/** Build digest aggregates + samples from mirror items (#3125). */
+export function buildLabelMirrorDigest(items, sampleLimit = DEFAULT_DIGEST_SAMPLE_LIMIT) {
+    const limit = Number.isFinite(sampleLimit) && sampleLimit >= 0
+        ? Math.floor(sampleLimit)
+        : DEFAULT_DIGEST_SAMPLE_LIMIT;
+    const byState = {};
+    const byRule = {};
+    const byAction = {};
+    const writeItems = items.filter((i) => i.status === "planned" || i.status === "applied");
+    for (const item of writeItems) {
+        const st = item.state ?? "unknown";
+        byState[st] = (byState[st] ?? 0) + 1;
+        const rule = item.ruleKind ?? "(none)";
+        byRule[rule] = (byRule[rule] ?? 0) + 1;
+        const action = item.action ?? "(none)";
+        byAction[action] = (byAction[action] ?? 0) + 1;
+    }
+    const samples = writeItems.slice(0, limit);
+    return {
+        by_state: byState,
+        by_rule: byRule,
+        by_action: byAction,
+        samples,
+        sample_limit: limit,
+        sample_truncated: writeItems.length > limit,
+    };
+}
+function formatMissingLabelHint(message, labels) {
+    const lower = message.toLowerCase();
+    const looksMissing = lower.includes("not found") ||
+        lower.includes("could not add label") ||
+        lower.includes("invalid label") ||
+        lower.includes("unknown label") ||
+        (lower.includes("label") && (lower.includes("404") || lower.includes("does not exist")));
+    if (!looksMissing) {
+        return message;
+    }
+    const want = labels.length > 0 ? labels.join(", ") : "triaged";
+    return (`${message} — ensure label(s) exist on the repo before --apply ` +
+        `(create missing labels e.g. \`gh label create "${want.split(",")[0]?.trim() ?? "triaged"}"\`; ` +
+        `idempotency + actionLabels must exist or apply fails closed per issue).`);
+}
 /**
- * Run Tier-1 label mirror over the github-issue cache.
+ * Run Tier-1 label mirror over the github-issue cache (bootstrap mass-triage surface).
  * Dry-run by default (no SCM writes). Pass dryRun: false to apply.
+ * Default state filter is open-only (#3125); pass includeClosed: true for archive stamps.
  * Requires options.engine (classify/index wrapper injects it).
+ * Never calls triage:accept / never writes proposed/ xBRIEFs.
  */
 export function mirrorLabels(projectRoot, options) {
     const root = resolve(projectRoot);
@@ -321,12 +394,39 @@ export function mirrorLabels(projectRoot, options) {
     const useLiveLabels = options.useLiveLabels ?? !dryRun;
     const client = options.client ?? (useLiveLabels || !dryRun ? new ScmLabelClient() : undefined);
     const engine = options.engine;
+    const includeClosed = options.includeClosed === true;
+    const authorFilter = options.authorFilter !== undefined && options.authorFilter !== null
+        ? options.authorFilter
+        : null;
+    const sampleLimit = options.sampleLimit ?? DEFAULT_DIGEST_SAMPLE_LIMIT;
+    const batchSize = options.batchSize !== undefined
+        ? Math.max(1, Math.floor(options.batchSize))
+        : DEFAULT_APPLY_BATCH_SIZE;
+    const delayMs = options.delayMs !== undefined && options.delayMs >= 0
+        ? Math.floor(options.delayMs)
+        : dryRun
+            ? 0
+            : DEFAULT_APPLY_DELAY_MS;
+    const sleepMs = options.sleepMs ?? defaultSleepMs;
+    const repoFilter = options.repo !== undefined && options.repo !== null && options.repo.trim().length > 0
+        ? options.repo.trim()
+        : null;
+    const filters = {
+        include_closed: includeClosed,
+        repo: repoFilter,
+        author: authorFilter !== null ? authorFilter.display : null,
+        author_logins: authorFilter !== null ? authorFilter.allowLogins : null,
+    };
     const items = [];
     const outcomeBase = {
         project_root: root,
         dry_run: dryRun,
         policy,
+        filters,
+        batch_size: dryRun ? undefined : batchSize,
+        delay_ms: dryRun ? undefined : delayMs,
     };
+    const emptyDigest = buildLabelMirrorDigest([], sampleLimit);
     if (!policy.enabled) {
         return [
             0,
@@ -339,11 +439,15 @@ export function mirrorLabels(projectRoot, options) {
                 skipped_already_triaged: 0,
                 skipped_no_match: 0,
                 skipped_unreadable: 0,
+                skipped_closed: 0,
+                skipped_author: 0,
                 errors: 0,
+                digest: emptyDigest,
                 items: [
                     {
                         repo: "",
                         issue_number: 0,
+                        state: null,
                         action: null,
                         reason: null,
                         ruleKind: null,
@@ -365,8 +469,8 @@ export function mirrorLabels(projectRoot, options) {
     const decisions = loadLatestDecisionMap(root);
     const now = options.now ?? new Date();
     let pairs = iterCachedIssues(cacheRoot);
-    if (options.repo !== undefined && options.repo !== null && options.repo.trim().length > 0) {
-        const want = options.repo.trim().toLowerCase();
+    if (repoFilter !== null) {
+        const want = repoFilter.toLowerCase();
         pairs = pairs.filter(([repo]) => repo.toLowerCase() === want);
     }
     let planned = 0;
@@ -375,7 +479,10 @@ export function mirrorLabels(projectRoot, options) {
     let skippedAlready = 0;
     let skippedNoMatch = 0;
     let skippedUnreadable = 0;
+    let skippedClosed = 0;
+    let skippedAuthor = 0;
     let errors = 0;
+    let applyWritesSinceSleep = 0;
     for (const [repo, issueNumber] of pairs) {
         const issue = readCachedRawIssue(cacheRoot, repo, issueNumber);
         if (issue === null) {
@@ -383,6 +490,7 @@ export function mirrorLabels(projectRoot, options) {
             items.push({
                 repo,
                 issue_number: issueNumber,
+                state: null,
                 action: null,
                 reason: null,
                 ruleKind: null,
@@ -394,6 +502,48 @@ export function mirrorLabels(projectRoot, options) {
             });
             continue;
         }
+        const state = normalizeIssueState(issue.state);
+        // Open-only default: skip closed before classify (avoids mass-stamping archive).
+        if (!includeClosed && isClosedState(state)) {
+            skippedClosed += 1;
+            items.push({
+                repo,
+                issue_number: issueNumber,
+                state,
+                action: null,
+                reason: null,
+                ruleKind: null,
+                current: issueLabelNames(issue).sort(),
+                desired: [],
+                add: [],
+                status: "skipped_closed",
+                message: "open-only default; pass includeClosed / --include-closed to mirror closed issues",
+            });
+            continue;
+        }
+        // Author filter (#3129): AND with open-only / other filters; missing author = non-match.
+        if (authorFilter !== null) {
+            const login = authorLoginFromRawIssue(issue);
+            if (!matchesAuthorFilter(login, authorFilter)) {
+                skippedAuthor += 1;
+                items.push({
+                    repo,
+                    issue_number: issueNumber,
+                    state,
+                    action: null,
+                    reason: null,
+                    ruleKind: null,
+                    current: issueLabelNames(issue).sort(),
+                    desired: [],
+                    add: [],
+                    status: "skipped_author",
+                    message: login === null
+                        ? `author filter ${authorFilter.display}: missing author on cache row (unknown — excluded)`
+                        : `author filter ${authorFilter.display}: author.login=${login} does not match`,
+                });
+                continue;
+            }
+        }
         let current;
         if (useLiveLabels && client !== undefined) {
             try {
@@ -406,6 +556,7 @@ export function mirrorLabels(projectRoot, options) {
                     items.push({
                         repo,
                         issue_number: issueNumber,
+                        state,
                         action: null,
                         reason: null,
                         ruleKind: null,
@@ -427,6 +578,7 @@ export function mirrorLabels(projectRoot, options) {
             items.push({
                 repo,
                 issue_number: issueNumber,
+                state,
                 action: null,
                 reason: null,
                 ruleKind: null,
@@ -455,6 +607,7 @@ export function mirrorLabels(projectRoot, options) {
             items.push({
                 repo,
                 issue_number: issueNumber,
+                state,
                 action: null,
                 reason: null,
                 ruleKind: null,
@@ -473,6 +626,7 @@ export function mirrorLabels(projectRoot, options) {
             items.push({
                 repo,
                 issue_number: issueNumber,
+                state,
                 action: classification.action,
                 reason: classification.reason,
                 ruleKind: classification.ruleKind,
@@ -488,6 +642,7 @@ export function mirrorLabels(projectRoot, options) {
             items.push({
                 repo,
                 issue_number: issueNumber,
+                state,
                 action: classification.action,
                 reason: classification.reason,
                 ruleKind: classification.ruleKind,
@@ -498,7 +653,7 @@ export function mirrorLabels(projectRoot, options) {
             });
             continue;
         }
-        // --apply path: SCM boundary + write
+        // --apply path: SCM boundary + write (batched + delay for rate-limit awareness)
         const mutateGate = isRepoMutationAllowed(repo, root, {
             allowCrossRepo: options.allowCrossRepo,
             allowlist: options.repoAllowlist,
@@ -509,6 +664,7 @@ export function mirrorLabels(projectRoot, options) {
             items.push({
                 repo,
                 issue_number: issueNumber,
+                state,
                 action: classification.action,
                 reason: classification.reason,
                 ruleKind: classification.ruleKind,
@@ -525,6 +681,7 @@ export function mirrorLabels(projectRoot, options) {
             items.push({
                 repo,
                 issue_number: issueNumber,
+                state,
                 action: classification.action,
                 reason: classification.reason,
                 ruleKind: classification.ruleKind,
@@ -537,11 +694,18 @@ export function mirrorLabels(projectRoot, options) {
             continue;
         }
         try {
+            // Count every SCM write *attempt* toward the batch (including failures) so
+            // rate-limit delay still applies under partial failure storms (#3125 Greptile P1).
+            if (applyWritesSinceSleep > 0 && applyWritesSinceSleep % batchSize === 0 && delayMs > 0) {
+                sleepMs(delayMs);
+            }
+            applyWritesSinceSleep += 1;
             client.apply(repo, issueNumber, add, []);
             applied += 1;
             items.push({
                 repo,
                 issue_number: issueNumber,
+                state,
                 action: classification.action,
                 reason: classification.reason,
                 ruleKind: classification.ruleKind,
@@ -553,9 +717,11 @@ export function mirrorLabels(projectRoot, options) {
         }
         catch (exc) {
             errors += 1;
+            const rawMsg = exc instanceof Error ? exc.message : String(exc);
             items.push({
                 repo,
                 issue_number: issueNumber,
+                state,
                 action: classification.action,
                 reason: classification.reason,
                 ruleKind: classification.ruleKind,
@@ -563,10 +729,12 @@ export function mirrorLabels(projectRoot, options) {
                 desired,
                 add,
                 status: "error",
-                message: exc instanceof Error ? exc.message : String(exc),
+                message: formatMissingLabelHint(rawMsg, add),
             });
+            // Partial failure: continue remaining issues (idempotent re-run skips applied).
         }
     }
+    const digest = buildLabelMirrorDigest(items, sampleLimit);
     const outcome = {
         ...outcomeBase,
         scanned: pairs.length,
@@ -576,35 +744,75 @@ export function mirrorLabels(projectRoot, options) {
         skipped_already_triaged: skippedAlready,
         skipped_no_match: skippedNoMatch,
         skipped_unreadable: skippedUnreadable,
+        skipped_closed: skippedClosed,
+        skipped_author: skippedAuthor,
         errors,
+        digest,
         items,
     };
     return [errors > 0 ? 1 : 0, outcome];
 }
-/** Human-readable digest for dry-run / apply reports. */
+function formatCountMap(map) {
+    const keys = Object.keys(map).sort();
+    if (keys.length === 0) {
+        return ["  (none)"];
+    }
+    return keys.map((k) => `  ${k}: ${map[k]}`);
+}
+/** Human-readable digest for dry-run / apply reports (bootstrap mass-triage UX). */
 export function renderLabelMirrorReport(outcome) {
     const lines = [];
     const mode = outcome.dry_run ? "dry-run" : "apply";
-    lines.push(`triage:classify --mirror (${mode})`);
+    lines.push(`triage:classify --mirror (${mode}) — bootstrap mass-triage (#1423 Wave 2)`);
+    const stateFilter = outcome.filters.include_closed ? "all (include-closed)" : "open-only";
+    const repoPart = outcome.filters.repo ?? "*";
+    const authorPart = outcome.filters.author ?? "*";
+    lines.push(`filters: state=${stateFilter} repo=${repoPart} author=${authorPart}`);
     lines.push(`scanned=${outcome.scanned} planned=${outcome.planned} applied=${outcome.applied} ` +
         `unchanged=${outcome.unchanged} already_triaged=${outcome.skipped_already_triaged} ` +
-        `no_match=${outcome.skipped_no_match} unreadable=${outcome.skipped_unreadable} ` +
-        `errors=${outcome.errors}`);
+        `no_match=${outcome.skipped_no_match} closed_skipped=${outcome.skipped_closed} ` +
+        `author_skipped=${outcome.skipped_author} ` +
+        `unreadable=${outcome.skipped_unreadable} errors=${outcome.errors}`);
     lines.push(`idempotencyLabel=${outcome.policy.idempotencyLabel} alwaysLabels=${JSON.stringify(outcome.policy.alwaysLabels)}`);
+    if (!outcome.dry_run) {
+        lines.push(`apply: batch_size=${outcome.batch_size ?? DEFAULT_APPLY_BATCH_SIZE} delay_ms=${outcome.delay_ms ?? DEFAULT_APPLY_DELAY_MS}`);
+    }
     lines.push("");
-    const plannedOrApplied = outcome.items.filter((i) => i.status === "planned" || i.status === "applied");
-    lines.push(outcome.dry_run ? "Would add labels:" : "Added labels:");
-    if (plannedOrApplied.length === 0) {
+    lines.push("By state (planned/applied):");
+    lines.push(...formatCountMap(outcome.digest.by_state));
+    lines.push("By rule (planned/applied):");
+    lines.push(...formatCountMap(outcome.digest.by_rule));
+    lines.push("By action (planned/applied):");
+    lines.push(...formatCountMap(outcome.digest.by_action));
+    lines.push("");
+    const writeTotal = outcome.planned + outcome.applied;
+    lines.push(outcome.dry_run
+        ? `Samples (up to ${outcome.digest.sample_limit} of ${writeTotal} planned):`
+        : `Samples (up to ${outcome.digest.sample_limit} of ${writeTotal} applied/planned):`);
+    if (outcome.digest.samples.length === 0) {
         lines.push("- none");
     }
     else {
-        for (const item of plannedOrApplied) {
+        for (const item of outcome.digest.samples) {
             const actionPart = item.action !== null ? ` action=${item.action}` : "";
             const rulePart = item.ruleKind !== null ? ` rule=${item.ruleKind}` : "";
+            const statePart = item.state !== null ? ` state=${item.state}` : "";
             const addPart = sanitizeReportFragment(item.add.join(", +"));
-            lines.push(`- ${item.repo}#${item.issue_number}:${actionPart}${rulePart} +${addPart}`);
+            lines.push(`- ${item.repo}#${item.issue_number}:${statePart}${actionPart}${rulePart} +${addPart}`);
+        }
+        if (outcome.digest.sample_truncated) {
+            const remaining = writeTotal - outcome.digest.samples.length;
+            lines.push(`… and ${remaining} more (use --json for full items list)`);
         }
     }
+    if (outcome.skipped_closed > 0) {
+        lines.push("");
+        lines.push(`Skipped closed (open-only default): ${outcome.skipped_closed} — re-run with --include-closed to include archive`);
+    }
+    if (outcome.skipped_author > 0) {
+        lines.push("");
+        lines.push(`Skipped (author filter ${outcome.filters.author ?? "?"}): ${outcome.skipped_author}`);
+    }
     const already = outcome.items.filter((i) => i.status === "skipped_already_triaged");
     if (already.length > 0) {
         lines.push("");
@@ -617,19 +825,19 @@ export function renderLabelMirrorReport(outcome) {
     const errs = outcome.items.filter((i) => i.status === "error");
     if (errs.length > 0) {
         lines.push("");
-        lines.push("Errors:");
+        lines.push(`Errors (partial failure report; ${errs.length} of ${outcome.scanned}):`);
         for (const item of errs) {
             const msg = sanitizeReportFragment(item.message ?? "unknown error");
             lines.push(`- ${item.repo}#${item.issue_number}: ${msg}`);
         }
     }
-    if (outcome.dry_run && plannedOrApplied.length > 0) {
+    if (outcome.dry_run && writeTotal > 0) {
         lines.push("");
-        lines.push("Dry-run -- re-run with --mirror --apply to write these labels via SCM.");
+        lines.push("Dry-run — re-run with --mirror --apply to write these labels via SCM (batched; never triage:accept).");
     }
     return `${lines.join("\n")}\n`;
 }
-/** JSON-serializable outcome (stable key order not required). */
+/** JSON-serializable outcome including Wave 2 digest aggregates. */
 export function labelMirrorOutcomeToJson(outcome) {
     return {
         project_root: outcome.project_root,
@@ -641,25 +849,47 @@ export function labelMirrorOutcomeToJson(outcome) {
         skipped_already_triaged: outcome.skipped_already_triaged,
         skipped_no_match: outcome.skipped_no_match,
         skipped_unreadable: outcome.skipped_unreadable,
+        skipped_closed: outcome.skipped_closed,
+        skipped_author: outcome.skipped_author,
         errors: outcome.errors,
+        filters: {
+            include_closed: outcome.filters.include_closed,
+            repo: outcome.filters.repo,
+            author: outcome.filters.author,
+            author_logins: outcome.filters.author_logins,
+        },
+        digest: {
+            by_state: { ...outcome.digest.by_state },
+            by_rule: { ...outcome.digest.by_rule },
+            by_action: { ...outcome.digest.by_action },
+            sample_limit: outcome.digest.sample_limit,
+            sample_truncated: outcome.digest.sample_truncated,
+            samples: outcome.digest.samples.map((i) => itemToJson(i)),
+        },
+        ...(outcome.batch_size !== undefined ? { batch_size: outcome.batch_size } : {}),
+        ...(outcome.delay_ms !== undefined ? { delay_ms: outcome.delay_ms } : {}),
         policy: {
             enabled: outcome.policy.enabled,
             idempotencyLabel: outcome.policy.idempotencyLabel,
             alwaysLabels: [...outcome.policy.alwaysLabels],
             actionLabels: Object.fromEntries(Object.entries(outcome.policy.actionLabels).map(([k, v]) => [k, [...(v ?? [])]])),
         },
-        items: outcome.items.map((i) => ({
-            repo: i.repo,
-            issue_number: i.issue_number,
-            action: i.action,
-            reason: i.reason,
-            ruleKind: i.ruleKind,
-            current: [...i.current],
-            desired: [...i.desired],
-            add: [...i.add],
-            status: i.status,
-            ...(i.message !== undefined ? { message: i.message } : {}),
-        })),
+        items: outcome.items.map((i) => itemToJson(i)),
+    };
+}
+function itemToJson(i) {
+    return {
+        repo: i.repo,
+        issue_number: i.issue_number,
+        state: i.state,
+        action: i.action,
+        reason: i.reason,
+        ruleKind: i.ruleKind,
+        current: [...i.current],
+        desired: [...i.desired],
+        add: [...i.add],
+        status: i.status,
+        ...(i.message !== undefined ? { message: i.message } : {}),
     };
 }
 /** Validate triageLabelMirror on a plan object (vbrief_validate hook). */

package/dist/triage/help/registry-data.d.ts

@@ -114,12 +114,12 @@ export declare const registryData: {
         readonly "task triage:queue": {
             readonly name: "task triage:queue";
             readonly summary: "Ranked candidate list";
-            readonly refs: "(D11 / #1128)";
-            readonly description: "Print the ranked triage queue from the local cache. Groups (display order): [ORPHAN] -> [RESUME] -> [URGENT] -> untriaged -> other -> [BLOCKED]. Within-group default = updated_at desc; consumer plan.policy.triageRankingLabels[] re-orders within-group by matched-label declared order. Items whose linked vBRIEF is blocked (status:blocked / unresolved depends_on) are demoted into [BLOCKED] unless --include-blocked is passed (#1286).";
-            readonly usage: "task triage:queue [-- --limit=N] [--include-blocked] [--repo=owner/name]";
-            readonly flags: readonly [readonly ["--limit N", "10", "Max rows to print."], readonly ["--include-blocked", "(off)", "Re-surface blocked items into their natural group (#1286)."], readonly ["--repo owner/name", "(git remote)", "Explicit repo override."]];
-            readonly examples: readonly ["task triage:queue", "task triage:queue -- --limit=20 --state=accept", "task triage:queue -- --format=json | jq '.[] | select(.score > 5)'"];
-            readonly see_also: readonly ["task triage:show", "task triage:audit", "#1119 / D11"];
+            readonly refs: "(D11 / #1128, #3129 / #1318 Layer 1)";
+            readonly description: "Print the ranked triage queue from the local cache. Groups (display order): [ORPHAN] -> [RESUME] -> [URGENT] -> untriaged -> other -> [BLOCKED]. Within-group default = updated_at desc; consumer plan.policy.triageRankingLabels[] re-orders within-group by matched-label declared order. Items whose linked vBRIEF is blocked (status:blocked / unresolved depends_on) are demoted into [BLOCKED] unless --include-blocked is passed (#1286). Optional --author LOGIN filters to cache author.login (exact; @me resolves to authenticated login; comma allow-list; missing author counted as unknown and disclosed in the header) (#3129 / #1318 Layer 1).";
+            readonly usage: "task triage:queue [-- --limit=N] [--include-blocked] [--repo=owner/name] [--author LOGIN|@me] [--author-mine]";
+            readonly flags: readonly [readonly ["--limit N", "10", "Max rows to print."], readonly ["--include-blocked", "(off)", "Re-surface blocked items into their natural group (#1286)."], readonly ["--repo owner/name", "(git remote)", "Explicit repo override."], readonly ["--author LOGIN|@me", "(none)", "Only issues whose cache author.login matches (exact; @me = gh user; comma allow-list) (#3129)."], readonly ["--author-mine", "(off)", "Alias for --author @me (#1318 / #3129)."]];
+            readonly examples: readonly ["task triage:queue", "task triage:queue -- --limit=20", "task triage:queue -- --author @me", "task triage:queue -- --author alice,bob --limit=20"];
+            readonly see_also: readonly ["task triage:show", "task triage:audit", "task triage:classify", "#1119 / D11", "#3129"];
             readonly placeholder: false;
         };
         readonly "task triage:audit": {
@@ -168,13 +168,13 @@ export declare const registryData: {
         };
         readonly "task triage:classify": {
             readonly name: "task triage:classify";
-            readonly summary: "Inspect / validate auto-classification surface; Tier-1 SCM label mirror";
-            readonly refs: "(D10 / #1129, #1423 Wave 1)";
-            readonly description: "Inspect or validate the auto-classification rule set. --list renders effective rules (framework universal first, consumer overrides next). --validate exits non-zero on a malformed plan.policy.triageAutoClassify or triageLabelMirror. --mirror runs the Tier-1 deterministic SCM label mirror over the github-issue cache (dry-run default; --apply writes via SCM boundary). Never calls triage:accept / never writes proposed/ xBRIEFs.";
-            readonly usage: "task triage:classify -- [--list | --validate | --mirror [--apply] [--repo owner/name] [--json] [--allow-cross-repo]]";
-            readonly flags: readonly [readonly ["--list", "(default)", "Print effective rules + hold markers."], readonly ["--validate", "(off)", "Validate plan.policy.triageAutoClassify + triageLabelMirror."], readonly ["--mirror", "(off)", "Tier-1 label mirror: classify cache → planned/applied labels (dry-run default)."], readonly ["--apply", "(off)", "With --mirror: write labels via SCM (requires github SCM boundary)."], readonly ["--repo owner/name", "(all cached)", "Limit mirror to one repo."], readonly ["--json", "(off)", "With --mirror: structured JSON outcome."], readonly ["--allow-cross-repo", "(off)", "With --mirror --apply: allow non-project repos (#2601)."]];
-            readonly examples: readonly ["task triage:classify -- --list", "task triage:classify -- --validate", "task triage:classify -- --mirror", "task triage:classify -- --mirror --apply --repo owner/name"];
-            readonly see_also: readonly ["task triage:bootstrap", "task triage:queue", "task vbrief:reconcile:labels", "#1119 / D10", "#1423"];
+            readonly summary: "Inspect / validate auto-classification; bootstrap mass-triage label mirror";
+            readonly refs: "(D10 / #1129, #1423 Wave 1–2 / #3125, #3129)";
+            readonly description: "Inspect or validate the auto-classification rule set. --list renders effective rules (framework universal first, consumer overrides next). --validate exits non-zero on a malformed plan.policy.triageAutoClassify or triageLabelMirror. --mirror is the bootstrap mass-triage entrypoint (#3125): classifies the github-issue cache and mirrors outcomes as SCM labels. Open-only by default (opt-in --include-closed); optional --author LOGIN scopes plan/apply to matching author.login (AND with open-only; #3129); dry-run digest shows totals + by state/rule/action + samples and surfaces the author filter; --apply batches writes with rate-limit delay. Never calls triage:accept / never writes proposed/ xBRIEFs.";
+            readonly usage: "task triage:classify -- [--list | --validate | --mirror [--apply] [--include-closed] [--author LOGIN|@me] [--repo owner/name] [--batch-size N] [--delay-ms N] [--sample-limit N] [--json] [--allow-cross-repo]]";
+            readonly flags: readonly [readonly ["--list", "(default)", "Print effective rules + hold markers."], readonly ["--validate", "(off)", "Validate plan.policy.triageAutoClassify + triageLabelMirror."], readonly ["--mirror", "(off)", "Bootstrap mass-triage label mirror: classify cache → planned/applied labels (dry-run default, open-only)."], readonly ["--apply", "(off)", "With --mirror: write labels via SCM (batched; requires github SCM boundary)."], readonly ["--include-closed", "(off)", "With --mirror: include closed issues (default open-only avoids archive mass-stamp)."], readonly ["--author LOGIN|@me", "(none)", "With --mirror: only plan/apply issues whose cache author.login matches (exact; @me; comma allow-list) (#3129)."], readonly ["--author-mine", "(off)", "With --mirror: alias for --author @me (#3129)."], readonly ["--repo owner/name", "(all cached)", "Limit mirror to one repo."], readonly ["--batch-size N", "10", "With --mirror --apply: writes per batch before delay."], readonly ["--delay-ms N", "1000", "With --mirror --apply: ms sleep between batches (rate-limit)."], readonly ["--sample-limit N", "15", "With --mirror: max samples in human digest."], readonly ["--json", "(off)", "With --mirror: structured JSON outcome including digest aggregates."], readonly ["--allow-cross-repo", "(off)", "With --mirror --apply: allow non-project repos (#2601)."]];
+            readonly examples: readonly ["task triage:classify -- --list", "task triage:classify -- --validate", "task triage:classify -- --mirror", "task triage:classify -- --mirror --author @me --repo owner/name", "task triage:classify -- --mirror --repo owner/name --json", "task triage:classify -- --mirror --apply --repo owner/name --batch-size 10 --delay-ms 1000", "task triage:classify -- --mirror --include-closed --repo owner/name"];
+            readonly see_also: readonly ["task triage:bootstrap", "task triage:queue", "task vbrief:reconcile:labels", "#1119 / D10", "#1423", "#3125", "#3129"];
             readonly placeholder: false;
         };
         readonly "task triage:bootstrap": {
@@ -298,37 +298,48 @@ export declare const registryData: {
             readonly see_also: readonly ["task triage:subscribe", "task triage:scope", "#1119 / D14"];
             readonly placeholder: false;
         };
-        readonly "task triage:audit:prune": {
-            readonly name: "task triage:audit:prune";
-            readonly summary: "Operator-invoked archive of closed-terminal entries";
-            readonly refs: "(D19, coming)";
-            readonly description: "Move closed-terminal audit entries (accept/reject/mark-duplicate after the upstream issue is closed) into the archive sidecar so the live cache stays focused on open work.";
-            readonly usage: "task triage:audit:prune [-- --dry-run] [--older-than-days N]";
-            readonly flags: readonly [readonly ["--dry-run", "(off)", "Preview eligible entries without writing."], readonly ["--older-than-days N", "30", "Age threshold."]];
-            readonly examples: readonly ["task triage:audit:prune -- --dry-run"];
-            readonly see_also: readonly ["task triage:archive-list", "task triage:restore-from-archive", "#1119 / D19"];
-            readonly placeholder: true;
+        readonly "task triage:cache-archive": {
+            readonly name: "task triage:cache-archive";
+            readonly summary: "Reversible archive of closed github-issue cache entries";
+            readonly refs: "(#1137)";
+            readonly description: "Move closed-and-aged live `.deft-cache/github-issue/` entries under `.deft-cache/archived/github-issue/...` with archive-meta.json. Operator-only; never auto on check/session/sync. Distinct from task cache:prune (TTL hard-delete). Skips issues referenced in xbrief/{proposed,pending,active}. Alias: cache:archive-closed.";
+            readonly usage: "task triage:cache-archive -- [--dry-run] [--older-than-days 30] [--repo owner/name] [--json] [--terminal-decision-only]";
+            readonly flags: readonly [readonly ["--dry-run", "(off)", "Report eligible entries without moving."], readonly ["--older-than-days N", "30", "Minimum age of closed_at (or fetched_at/mtime fallback)."], readonly ["--repo owner/name", "(all)", "Limit to one repo."], readonly ["--json", "(off)", "Structured summary."], readonly ["--terminal-decision-only", "(off)", "Only archive when latest candidates decision is reject or mark-duplicate."]];
+            readonly examples: readonly ["task triage:cache-archive -- --dry-run", "task triage:cache-archive -- --older-than-days 30 --repo deftai/directive"];
+            readonly see_also: readonly ["task triage:archive-list", "task triage:restore-from-archive", "task cache:prune", "#1137"];
+            readonly placeholder: false;
         };
         readonly "task triage:archive-list": {
             readonly name: "task triage:archive-list";
-            readonly summary: "List archived entries";
-            readonly refs: "(D19, coming)";
-            readonly description: "Read-only listing of archived audit entries from the archive sidecar. Useful before restoring an entry.";
-            readonly usage: "task triage:archive-list [-- --since=WINDOW]";
-            readonly flags: readonly [readonly ["--since WINDOW", "(all)", "Time window (e.g. '30d', '6mo')."]];
-            readonly examples: readonly ["task triage:archive-list"];
-            readonly see_also: readonly ["task triage:audit:prune", "#1119 / D19"];
-            readonly placeholder: true;
+            readonly summary: "List archived github-issue cache entries";
+            readonly refs: "(#1137)";
+            readonly description: "List `.deft-cache/archived/github-issue/...` entries newest archived_at first. Alias: cache:archive-list.";
+            readonly usage: "task triage:archive-list -- [--repo owner/name] [--format=json] [--since ISO] [--limit N]";
+            readonly flags: readonly [readonly ["--repo owner/name", "(all)", "Limit to one repo."], readonly ["--format=json", "text", "JSON listing."], readonly ["--since ISO", "(none)", "Only entries archived at/after this timestamp."], readonly ["--limit N", "(none)", "Cap result count."]];
+            readonly examples: readonly ["task triage:archive-list -- --format=json"];
+            readonly see_also: readonly ["task triage:cache-archive", "task triage:restore-from-archive", "#1137"];
+            readonly placeholder: false;
         };
         readonly "task triage:restore-from-archive": {
             readonly name: "task triage:restore-from-archive";
-            readonly summary: "Restore archived entry to live cache";
-            readonly refs: "(D19, coming)";
-            readonly description: "Move an archived entry back to the live audit log so it becomes visible to triage:queue / triage:audit again.";
-            readonly usage: "task triage:restore-from-archive -- <N>";
-            readonly flags: readonly [readonly ["<N>", "(required)", "Archived entry number to restore."]];
-            readonly examples: readonly ["task triage:restore-from-archive -- 42"];
-            readonly see_also: readonly ["task triage:archive-list", "#1119 / D19"];
+            readonly summary: "Restore archived issue entry to live cache";
+            readonly refs: "(#1137)";
+            readonly description: "Move an archived github-issue entry back to the live key path. Idempotent if already live with matching content; refuse live conflict unless --force. Alias: cache:restore-from-archive.";
+            readonly usage: "task triage:restore-from-archive -- --issue N --repo owner/name [--force]";
+            readonly flags: readonly [readonly ["--issue N", "(required unless --key)", "Issue number."], readonly ["--repo owner/name", "(required with --issue)", "Upstream repo."], readonly ["--key owner/repo/N", "(alt)", "Full cache key."], readonly ["--force", "(off)", "Replace live path when content differs."]];
+            readonly examples: readonly ["task triage:restore-from-archive -- --issue 1234 --repo deftai/directive"];
+            readonly see_also: readonly ["task triage:cache-archive", "task triage:show", "#1137"];
+            readonly placeholder: false;
+        };
+        readonly "task triage:audit:prune": {
+            readonly name: "task triage:audit:prune";
+            readonly summary: "Legacy name — use triage:cache-archive";
+            readonly refs: "(#1137 supersedes D19 name)";
+            readonly description: "Historical D19 placeholder name. Implemented surface is task triage:cache-archive (reversible closed github-issue cache archive). Do not confuse with task cache:prune (TTL hard-delete).";
+            readonly usage: "task triage:cache-archive -- [--dry-run] [--older-than-days N]";
+            readonly flags: readonly [readonly ["--dry-run", "(off)", "Preview eligible entries without writing."], readonly ["--older-than-days N", "30", "Age threshold."]];
+            readonly examples: readonly ["task triage:cache-archive -- --dry-run"];
+            readonly see_also: readonly ["task triage:cache-archive", "task triage:archive-list", "#1137"];
             readonly placeholder: true;
         };
         readonly "task triage:audit-log:rotate": {