@deftai/directive-core 0.99.0 → 0.101.0

package/dist/story-ready/evaluate.js

@@ -1,5 +1,6 @@
 import { readFileSync } from "node:fs";
 import { resolve } from "node:path";
+import { evaluateParentLineage, formatParentLineageLine, } from "../scope/parent-lineage.js";
 import { parseAllocationSection, SOLO_KIND, SWARM_COHORT_KIND, VALID_DISPATCH_KINDS, } from "./allocation.js";
 export const ACTIVE_FOLDER = "active";
 export const ELIGIBLE_STATUS = "running";
@@ -66,7 +67,7 @@ function checkVbrief(vbriefPath) {
                 "is eligible for a story start",
         };
     }
-    return { ok: true };
+    return { ok: true, path, payload: payload };
 }
 function readyMessage(treeNote, suffix) {
     return `OK: ready to start -- ${treeNote}, vBRIEF active+running, ${suffix}`;
@@ -116,6 +117,9 @@ function classifyAllocation(fields, treeNote) {
 /**
  * Pure evaluator — returns exit code + human message. Faithful to
  * `scripts/preflight_story_start.evaluate`.
+ *
+ * #3241: after structural active+running checks, re-check parent requirement
+ * lineage (coverage map + behavioral deltas) when the parent authors IDs.
  */
 export function evaluate(vbriefPath, options = {}) {
     const gitStatus = options.gitStatus ?? null;
@@ -147,15 +151,49 @@ export function evaluate(vbriefPath, options = {}) {
             message: `not ready: ${vbriefCheck.reason}.`,
         };
     }
+    // #3241 parent lineage (fail closed when parent authors IDs and child lacks coverage).
+    const lineage = evaluateParentLineage({
+        child: vbriefCheck.payload,
+        childPath: vbriefCheck.path,
+        projectRoot: options.projectRoot,
+        skip: options.skipParentLineage === true,
+    });
+    if (!lineage.ok) {
+        return {
+            exitCode: 1,
+            dispatchKind: null,
+            parentLineage: lineage,
+            message: `not ready: ${lineage.message}` +
+                (lineage.defect_class !== null ? ` [defect_class=${lineage.defect_class}]` : "") +
+                `\n${formatParentLineageLine(lineage)}`,
+        };
+    }
+    const lineageNote = lineage.applicable
+        ? `parent lineage OK (${lineage.parent_requirement_ids.length} req IDs` +
+            (lineage.negative_invariant_ids.length > 0
+                ? `, ${lineage.negative_invariant_ids.length} negative invariants`
+                : "") +
+            ")"
+        : null;
     const [found, fields] = options.parsed ?? parseAllocationSection(options.allocationContext ?? null);
     if (!found) {
+        const base = readyMessage(treeNote, "no `## Allocation context` section (solo path, #1371 carve-out).");
         return {
             exitCode: 0,
             dispatchKind: null,
-            message: readyMessage(treeNote, "no `## Allocation context` section (solo path, #1371 carve-out)."),
+            parentLineage: lineage,
+            message: lineageNote !== null ? `${base.replace(/\.$/, "")}; ${lineageNote}.` : base,
         };
     }
-    return classifyAllocation(fields, treeNote);
+    const classified = classifyAllocation(fields, treeNote);
+    return {
+        ...classified,
+        parentLineage: lineage,
+        message: classified.exitCode === 0 && lineageNote !== null
+            ? `${classified.message.replace(/\.$/, "")}; ${lineageNote}.`
+            : classified.message,
+    };
 }
+export { evaluateParentLineage, formatParentLineageLine, } from "../scope/parent-lineage.js";
 export { parseAllocationSection, SOLO_KIND, SWARM_COHORT_KIND };
 //# sourceMappingURL=evaluate.js.map

package/dist/triage/actions/candidates-log.d.ts

@@ -1,6 +1,5 @@
 import { resolveCandidatesLogPath } from "../cache-path.js";
-import type { AuditEntry, CandidatesLog } from "./types.js";
-/** Display/back-compat constant; resolution flows through resolveTriageCachePath (#1703). */
+import type { AuditEntry, CandidatesLog } from "./types.js"; /** Display/back-compat constant; resolution flows through resolveTriageCachePath (#1703). */
 export declare const AUDIT_LOG_REL_PATH = "xbrief/.triage-cache/candidates.jsonl";
 export { resolveCandidatesLogPath };
 /** Read every well-formed audit-log row in insertion order (#1698 shared reader). */

package/dist/triage/actions/candidates-log.js

@@ -1,9 +1,9 @@
 import { randomUUID } from "node:crypto";
-import { appendFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
+import { existsSync, mkdirSync, readFileSync } from "node:fs";
+import { dirname, isAbsolute, relative, resolve } from "node:path";
+import { containedWrite } from "../../fs/contained-write.js";
 import { resolveCandidatesLogPath, TRIAGE_CANDIDATES_LOG_REL_PATH } from "../cache-path.js";
 import { CandidatesLogError } from "./errors.js";
-/** Display/back-compat constant; resolution flows through resolveTriageCachePath (#1703). */
 export const AUDIT_LOG_REL_PATH = TRIAGE_CANDIDATES_LOG_REL_PATH;
 export { resolveCandidatesLogPath };
 const VALID_DECISIONS = new Set([
@@ -108,6 +108,32 @@ function resolveLogPath(projectRoot, override) {
     }
     return resolveCandidatesLogPath(projectRoot);
 }
+/**
+ * Containment root for candidates-log product writes (#3245).
+ * Prefer project root when the log is nested under it; otherwise parent dir
+ * (matches intake candidates-log parity for override paths outside the tree).
+ */
+function containmentRootForLog(projectRoot, logPath) {
+    const rootAbs = resolve(projectRoot);
+    const logAbs = resolve(logPath);
+    const parent = dirname(logAbs);
+    mkdirSync(parent, { recursive: true });
+    const rel = relative(rootAbs, logAbs);
+    if (rel.length > 0 && !rel.startsWith("..") && !isAbsolute(rel)) {
+        return rootAbs;
+    }
+    return resolve(parent);
+}
+/** #3245 / #2980: product append refuses leaf symlink follow (in-tree or escape). */
+function appendAuditLine(projectRoot, logPath, line) {
+    const root = containmentRootForLog(projectRoot, logPath);
+    containedWrite({
+        root,
+        target: logPath,
+        data: line.endsWith("\n") ? line : `${line}\n`,
+        mode: "append",
+    });
+}
 function stableStringify(entry) {
     const sortedKeys = Object.keys(entry).sort();
     const sorted = {};
@@ -186,8 +212,7 @@ export function createCandidatesLog(defaultProjectRoot) {
         append(entry, options) {
             validateEntry(entry);
             const logPath = resolveLogPath(defaultProjectRoot, options?.path);
-            mkdirSync(join(logPath, ".."), { recursive: true });
-            appendFileSync(logPath, `${stableStringify(entry)}\n`, { encoding: "utf8" });
+            appendAuditLine(defaultProjectRoot, logPath, `${stableStringify(entry)}\n`);
             return entry.decision_id;
         },
         latestDecision(issueNumber, repo, options) {
@@ -225,7 +250,13 @@ export function rollbackAuditEntry(decisionId, projectRoot, logPathOverride) {
         }
     }
     if (removed) {
-        writeFileSync(path, kept.join(""), { encoding: "utf8" });
+        // #3245: replace rewrite also refuses leaf symlink follow.
+        containedWrite({
+            root: containmentRootForLog(projectRoot, path),
+            target: path,
+            data: kept.join(""),
+            mode: "replace",
+        });
     }
     return removed;
 }

package/dist/triage/bootstrap/gitignore.d.ts

@@ -8,7 +8,7 @@ export declare function gitignoreTriageCacheEntries(projectRoot: string): readon
 export declare function gitattributesTriageCacheGlob(projectRoot: string): string;
 export declare const GITATTRIBUTES_EVAL_RULE = "vbrief/.triage-cache/*.jsonl  merge=union";
 export declare const FORBIDDEN_BLANKET_EVAL_LINES: readonly string[];
-export declare const EVAL_README_BODY = "# `vbrief/.triage-cache/` \u2014 triage working-set files\n\nThis directory holds JSON-lines logs and scratch files that Deft triage and\nslicing workflows emit. Deft configures your repo's `.gitignore` and\n`.gitattributes` so some files stay local while team-shared records can be\ncommitted.\n\n## What lives here\n\n| File | Committed? | Notes |\n| --- | --- | --- |\n| `slices.jsonl` | Yes | Team-shared cohort records from slicing skills. New teammates use prior cohort outputs to spot orphans and avoid re-slicing the same scope. |\n| `candidates.jsonl` | No | Your local triage accept / defer / reject stream. Re-create on a fresh clone with `deft triage:bootstrap`. |\n| `summary-history.jsonl` | No | Local history of `deft triage:summary` output; not required for day-to-day work. |\n| `scope-lifecycle.jsonl` | No | Local audit trail for scope demotions (`deft scope:demote`). Each operator's stream stays on their machine. |\n| `decompositions/` | No | Draft story-decomposition scratch. Produced child story xBRIEFs live in lifecycle folders via `deft scope:decompose`. |\n| `doctor-state.json` | No | Per-clone throttle state for `deft doctor` re-probe timing. |\n| `staleness-tickler-state.json` | No | Per-clone upgrade-tickler throttle state. |\n| `release-availability-state.json` | No | Per-clone release-availability probe throttle state. |\n\nPaths listed as \"No\" above are added to `.gitignore` during bootstrap; anything\nnot listed remains committable by default. The selective ignore entries live in\nthe repo-root `.gitignore` (`vbrief/.triage-cache/candidates.jsonl`,\n`vbrief/.triage-cache/summary-history.jsonl`, `vbrief/.triage-cache/scope-lifecycle.jsonl`,\n`vbrief/.triage-cache/decompositions/`, `vbrief/.triage-cache/doctor-state.json`,\n`vbrief/.triage-cache/staleness-tickler-state.json`, and\n`vbrief/.triage-cache/release-availability-state.json`).\n\n## Fresh clone\n\nIf `candidates.jsonl` is missing, run:\n\n```\ndeft triage:bootstrap\n```\n\nBootstrap rebuilds the local candidates log without altering committed\n`slices.jsonl`.\n\n## Merge behavior for `*.jsonl`\n\nThe repo-root `.gitattributes` may declare:\n\n```\nvbrief/.triage-cache/*.jsonl  merge=union\n```\n\nThe `union` merge driver concatenates both sides' appended lines on auto-merge,\nso parallel append-only edits to the same JSON-lines file rebase without manual\nconflict surgery. It does not dedupe semantically similar records \u2014 downstream\nreaders should tolerate duplicate-looking entries.\n\n## See also\n\n- `.gitignore` \u2014 selective ignore rules for operator-private files\n- `.gitattributes` \u2014 merge driver for committed JSON-lines logs\n";
+export declare const EVAL_README_BODY = "# `vbrief/.triage-cache/` \u2014 triage working-set files\n\nThis directory holds JSON-lines logs and scratch files that Deft triage and\nslicing workflows emit. Deft configures your repo's `.gitignore` and\n`.gitattributes` so some files stay local while team-shared records can be\ncommitted.\n\n## What lives here\n\n| File | Committed? | Notes |\n| --- | --- | --- |\n| `slices.jsonl` | Yes | Team-shared cohort records from slicing skills. New teammates use prior cohort outputs to spot orphans and avoid re-slicing the same scope. |\n| `candidates.jsonl` | No | Your local triage accept / defer / reject stream. Re-create on a fresh clone with `deft triage:bootstrap`. |\n| `summary-history.jsonl` | No | Local history of `deft triage:summary` output; not required for day-to-day work. |\n| `scope-lifecycle.jsonl` | No | Local audit trail for scope demotions (`deft scope:demote`). Each operator's stream stays on their machine. |\n| `decompositions/` | No | Draft story-decomposition scratch. Produced child story xBRIEFs live in lifecycle folders via `deft scope:decompose`. |\n| `doctor-state.json` | No | Per-clone throttle state for `deft doctor` re-probe timing. |\n| `staleness-tickler-state.json` | No | Per-clone upgrade-tickler throttle state. |\n| `release-availability-state.json` | No | Per-clone release-availability probe throttle state. |\n| `scm-label-mirror-discovery-state.json` | No | Per-clone SCM label-mirror discovery tip throttle (#3124). |\n\nPaths listed as \"No\" above are added to `.gitignore` during bootstrap; anything\nnot listed remains committable by default. The selective ignore entries live in\nthe repo-root `.gitignore` (`vbrief/.triage-cache/candidates.jsonl`,\n`vbrief/.triage-cache/summary-history.jsonl`, `vbrief/.triage-cache/scope-lifecycle.jsonl`,\n`vbrief/.triage-cache/decompositions/`, `vbrief/.triage-cache/doctor-state.json`,\n`vbrief/.triage-cache/staleness-tickler-state.json`,\n`vbrief/.triage-cache/release-availability-state.json`, and\n`vbrief/.triage-cache/scm-label-mirror-discovery-state.json`).\n\n## Fresh clone\n\nIf `candidates.jsonl` is missing, run:\n\n```\ndeft triage:bootstrap\n```\n\nBootstrap rebuilds the local candidates log without altering committed\n`slices.jsonl`.\n\n## Merge behavior for `*.jsonl`\n\nThe repo-root `.gitattributes` may declare:\n\n```\nvbrief/.triage-cache/*.jsonl  merge=union\n```\n\nThe `union` merge driver concatenates both sides' appended lines on auto-merge,\nso parallel append-only edits to the same JSON-lines file rebase without manual\nconflict surgery. It does not dedupe semantically similar records \u2014 downstream\nreaders should tolerate duplicate-looking entries.\n\n## See also\n\n- `.gitignore` \u2014 selective ignore rules for operator-private files\n- `.gitattributes` \u2014 merge driver for committed JSON-lines logs\n";
 /** Layout-aware triage-cache README body for the active lifecycle tree (#2344 / #2349). */
 export declare function generateTriageCacheReadmeBody(projectRoot: string): string;
 /** Strip an inline `# ...` comment from a gitignore line. */

package/dist/triage/bootstrap/gitignore.js

@@ -23,6 +23,8 @@ export const GITIGNORE_EVAL_ENTRIES = [
     // Per-clone session state (#3146); selective only — hybrid policy preserved.
     "xbrief/.triage-cache/staleness-tickler-state.json",
     "xbrief/.triage-cache/release-availability-state.json",
+    // SCM label-mirror discovery tip throttle (#3124).
+    "xbrief/.triage-cache/scm-label-mirror-discovery-state.json",
 ];
 /** Layout-aware gitignore lines for triage working-set files (#1703). */
 export function gitignoreTriageCacheEntries(projectRoot) {
@@ -36,6 +38,8 @@ export function gitignoreTriageCacheEntries(projectRoot) {
         // Per-clone session state (#3146); selective only — hybrid policy preserved.
         triageCacheRelPath(projectRoot, "staleness-tickler-state.json"),
         triageCacheRelPath(projectRoot, "release-availability-state.json"),
+        // SCM label-mirror discovery tip throttle (#3124).
+        triageCacheRelPath(projectRoot, "scm-label-mirror-discovery-state.json"),
     ];
 }
 export function gitattributesTriageCacheGlob(projectRoot) {
@@ -116,14 +120,16 @@ committed.
 | \`doctor-state.json\` | No | Per-clone throttle state for \`deft doctor\` re-probe timing. |
 | \`staleness-tickler-state.json\` | No | Per-clone upgrade-tickler throttle state. |
 | \`release-availability-state.json\` | No | Per-clone release-availability probe throttle state. |
+| \`scm-label-mirror-discovery-state.json\` | No | Per-clone SCM label-mirror discovery tip throttle (#3124). |
 
 Paths listed as "No" above are added to \`.gitignore\` during bootstrap; anything
 not listed remains committable by default. The selective ignore entries live in
 the repo-root \`.gitignore\` (\`vbrief/.triage-cache/candidates.jsonl\`,
 \`vbrief/.triage-cache/summary-history.jsonl\`, \`vbrief/.triage-cache/scope-lifecycle.jsonl\`,
 \`vbrief/.triage-cache/decompositions/\`, \`vbrief/.triage-cache/doctor-state.json\`,
-\`vbrief/.triage-cache/staleness-tickler-state.json\`, and
-\`vbrief/.triage-cache/release-availability-state.json\`).
+\`vbrief/.triage-cache/staleness-tickler-state.json\`,
+\`vbrief/.triage-cache/release-availability-state.json\`, and
+\`vbrief/.triage-cache/scm-label-mirror-discovery-state.json\`).
 
 ## Fresh clone
 

package/dist/triage/bootstrap/index.js

@@ -1,7 +1,8 @@
 import { execFileSync } from "node:child_process";
 import { randomUUID } from "node:crypto";
-import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readdirSync, readFileSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
+import { containedWrite } from "../../fs/contained-write.js";
 import { hasArtifactSuffix, resolveLifecycleRoot } from "../../layout/resolve.js";
 import { resolveCandidatesLogPath } from "../cache-path.js";
 import { loadDefaultCacheModule } from "./cache-module.js";
@@ -289,10 +290,21 @@ function buildAuditEntry(repo, issueNumber, sourceFolder, nowIso) {
         reason: `bootstrap backfill: vBRIEF already in vbrief/${sourceFolder}/ at opt-in time`,
     };
 }
+/**
+ * Default audit append for bootstrap backfill (#3288 / #3245 / #2980).
+ * Containment root is the audit parent (project root may be unavailable on inject path);
+ * leaf symlink follow is refused either way.
+ */
 function appendAuditEntryDefault(auditPath, entry) {
-    mkdirSync(dirname(auditPath), { recursive: true });
+    const parent = dirname(auditPath);
+    mkdirSync(parent, { recursive: true });
     const sorted = Object.fromEntries(Object.entries(entry).sort(([a], [b]) => a.localeCompare(b)));
-    writeFileSync(auditPath, `${JSON.stringify(sorted)}\n`, { encoding: "utf8", flag: "a" });
+    containedWrite({
+        root: resolve(parent),
+        target: resolve(auditPath),
+        data: `${JSON.stringify(sorted)}\n`,
+        mode: "append",
+    });
 }
 /** Backfill `accept` audit entries for items already in lifecycle folders. */
 export function stepBackfillAuditLog(projectRoot, repo, options = {}) {

package/dist/triage/classify/index.d.ts

@@ -86,6 +86,7 @@ export declare function validateProject(projectRoot: string): {
 /** Render --list output for a project root. */
 export declare function listProject(projectRoot: string): string;
 import { buildLabelMirrorDigest, type ClassifyAction, DEFAULT_APPLY_BATCH_SIZE, DEFAULT_APPLY_DELAY_MS, DEFAULT_DIGEST_SAMPLE_LIMIT, DEFAULT_IDEMPOTENCY_LABEL, defaultLabelMirrorPolicy, desiredLabelsForClassification, type LabelMirrorDigest, type LabelMirrorEngine, type LabelMirrorFilters, type LabelMirrorItem, type LabelMirrorOptions as LabelMirrorOptionsCore, type LabelMirrorOutcome, type LabelMirrorPolicy, type LabelMirrorSleepFn, type LabelMirrorStatus, labelMirrorOutcomeToJson, type ResolvedLabelMirrorPolicy, renderLabelMirrorReport, resolveLabelMirrorPolicy, validateLabelMirrorPolicy, validateTriageLabelMirrorOnPlan as validateTriageLabelMirrorOnPlanFromModule } from "./label-mirror.js";
+export { formatMirrorDiscoveryDigestCues, formatMirrorDiscoveryTip, formatMirrorDiscoveryTipBody, isMirrorDiscoveryTipDue, MIRROR_DISCOVERY_ACK_COMMAND, MIRROR_DISCOVERY_ANTI_SWALLOW_RULE, MIRROR_DISCOVERY_DRY_RUN_COMMAND, MIRROR_DISCOVERY_EMPTY_ACTION_LABELS_HINT, MIRROR_DISCOVERY_NO_MATCH_DOMINATION_HINT, MIRROR_DISCOVERY_POLICY_SHOW_COMMAND, MIRROR_DISCOVERY_RECOMMENDED_ACTION_LABELS, MIRROR_DISCOVERY_STATE_FILE, type MirrorDiscoveryState, type MirrorDiscoveryTipOptions, maybeFormatMirrorDiscoveryTip, mirrorDiscoveryStateExists, parseMirrorDiscoveryState, readMirrorDiscoveryState, recordMirrorDiscoveryAcked, recordMirrorDiscoverySuccessfulDryRun, resolveMirrorDiscoveryStatePath, } from "./mirror-discovery-tip.js";
 export { buildLabelMirrorDigest, type ClassifyAction, DEFAULT_APPLY_BATCH_SIZE, DEFAULT_APPLY_DELAY_MS, DEFAULT_DIGEST_SAMPLE_LIMIT, DEFAULT_IDEMPOTENCY_LABEL, defaultLabelMirrorPolicy, desiredLabelsForClassification, type LabelMirrorDigest, type LabelMirrorEngine, type LabelMirrorFilters, type LabelMirrorItem, type LabelMirrorOutcome, type LabelMirrorPolicy, type LabelMirrorSleepFn, type LabelMirrorStatus, labelMirrorOutcomeToJson, type ResolvedLabelMirrorPolicy, renderLabelMirrorReport, resolveLabelMirrorPolicy, validateLabelMirrorPolicy, validateTriageLabelMirrorOnPlanFromModule as validateTriageLabelMirrorOnPlan, };
 /** Public options: engine is optional (defaults to this module's classify API). */
 export type LabelMirrorOptions = Omit<LabelMirrorOptionsCore, "engine"> & {

package/dist/triage/classify/index.js

@@ -752,6 +752,8 @@ export function listProject(projectRoot) {
 // Public mirrorLabels injects the classify engine into the pure implementation.
 // ---------------------------------------------------------------------------
 import { buildLabelMirrorDigest, DEFAULT_APPLY_BATCH_SIZE, DEFAULT_APPLY_DELAY_MS, DEFAULT_DIGEST_SAMPLE_LIMIT, DEFAULT_IDEMPOTENCY_LABEL, defaultLabelMirrorPolicy, desiredLabelsForClassification, labelMirrorOutcomeToJson, mirrorLabels as mirrorLabelsCore, renderLabelMirrorReport, resolveLabelMirrorPolicy, validateLabelMirrorPolicy, validateTriageLabelMirrorOnPlan as validateTriageLabelMirrorOnPlanFromModule, } from "./label-mirror.js";
+// Operator discovery tip (#3124) — re-export for CLI + welcome.
+export { formatMirrorDiscoveryDigestCues, formatMirrorDiscoveryTip, formatMirrorDiscoveryTipBody, isMirrorDiscoveryTipDue, MIRROR_DISCOVERY_ACK_COMMAND, MIRROR_DISCOVERY_ANTI_SWALLOW_RULE, MIRROR_DISCOVERY_DRY_RUN_COMMAND, MIRROR_DISCOVERY_EMPTY_ACTION_LABELS_HINT, MIRROR_DISCOVERY_NO_MATCH_DOMINATION_HINT, MIRROR_DISCOVERY_POLICY_SHOW_COMMAND, MIRROR_DISCOVERY_RECOMMENDED_ACTION_LABELS, MIRROR_DISCOVERY_STATE_FILE, maybeFormatMirrorDiscoveryTip, mirrorDiscoveryStateExists, parseMirrorDiscoveryState, readMirrorDiscoveryState, recordMirrorDiscoveryAcked, recordMirrorDiscoverySuccessfulDryRun, resolveMirrorDiscoveryStatePath, } from "./mirror-discovery-tip.js";
 export { buildLabelMirrorDigest, DEFAULT_APPLY_BATCH_SIZE, DEFAULT_APPLY_DELAY_MS, DEFAULT_DIGEST_SAMPLE_LIMIT, DEFAULT_IDEMPOTENCY_LABEL, defaultLabelMirrorPolicy, desiredLabelsForClassification, labelMirrorOutcomeToJson, renderLabelMirrorReport, resolveLabelMirrorPolicy, validateLabelMirrorPolicy, validateTriageLabelMirrorOnPlanFromModule as validateTriageLabelMirrorOnPlan, };
 function defaultLabelMirrorEngine() {
     return {

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

@@ -27,6 +27,7 @@ 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";
+import { formatMirrorDiscoveryDigestCues } from "./mirror-discovery-tip.js";
 export const DEFAULT_IDEMPOTENCY_LABEL = "triaged";
 export const CACHE_DIR_NAME = ".deft-cache";
 export const CACHE_SOURCE = "github-issue";
@@ -903,6 +904,21 @@ export function renderLabelMirrorReport(outcome) {
             ? "Dry-run — re-run with --mirror --re-enrich --apply to write additive labels via SCM (batched; never triage:accept; never removals)."
             : "Dry-run — re-run with --mirror --apply to write these labels via SCM (batched; never triage:accept).");
     }
+    // #3124 SHOULD: digest upgrade cues (empty actionLabels / open no_match domination).
+    const actionLabelsEmpty = Object.keys(outcome.policy.actionLabels).length === 0;
+    const digestCues = formatMirrorDiscoveryDigestCues({
+        planned: outcome.planned,
+        applied: outcome.applied,
+        skipped_no_match: outcome.skipped_no_match,
+        skipped_already_triaged: outcome.skipped_already_triaged,
+        skipped_closed: outcome.skipped_closed,
+        actionLabelsEmpty,
+        dry_run: outcome.dry_run,
+    });
+    if (digestCues.length > 0) {
+        lines.push("");
+        lines.push(...digestCues);
+    }
     return `${lines.join("\n")}\n`;
 }
 /** JSON-serializable outcome including Wave 2 digest aggregates. */

package/dist/triage/classify/mirror-discovery-tip.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Operator discovery tip for SCM label mirror (#3124).
+ *
+ * Throttled existence + get-the-most-out-of-it disclosure for cold session /
+ * triage welcome / doctor. Hides after operator ack or first successful dry-run.
+ * Does not fire on session re-arm (welcome skipped).
+ *
+ * Never auto-apply; never auto-accept into proposed/.
+ */
+/** State file basename under xbrief/.triage-cache/. */
+export declare const MIRROR_DISCOVERY_STATE_FILE = "scm-label-mirror-discovery-state.json";
+/** Display/back-compat relative path. */
+export declare const MIRROR_DISCOVERY_STATE_RELATIVE_PATH: string;
+export interface MirrorDiscoveryState {
+    /** ISO timestamp when the tip was last emitted. */
+    readonly shownAt?: string;
+    /** ISO timestamp when the operator acked (tip stays hidden). */
+    readonly ackedAt?: string;
+    /** ISO timestamp of first successful --mirror dry-run (tip stays hidden). */
+    readonly successfulDryRunAt?: string;
+}
+export interface MirrorDiscoveryTipOptions {
+    readonly now?: Date;
+    readonly readState?: (path: string) => string | null;
+    readonly writeState?: (path: string, content: string) => void;
+    /** When false, evaluate eligibility without persisting shownAt. Default true. */
+    readonly recordShown?: boolean;
+}
+export declare function parseMirrorDiscoveryState(text: string | null): MirrorDiscoveryState;
+export declare function readMirrorDiscoveryState(projectRoot: string, options?: Pick<MirrorDiscoveryTipOptions, "readState">): MirrorDiscoveryState;
+/** True when tip should still surface (not acked and no successful dry-run yet). */
+export declare function isMirrorDiscoveryTipDue(projectRoot: string, options?: Pick<MirrorDiscoveryTipOptions, "readState">): boolean;
+/**
+ * Recommended full five-chip machine map for consumers (#3124 / #2611).
+ * Names only — do not invent vocabulary; labels must exist on GitHub.
+ */
+export declare const MIRROR_DISCOVERY_RECOMMENDED_ACTION_LABELS: {
+    readonly defer: readonly ["triage:deferred"];
+    readonly archive: readonly ["triage:archived"];
+    readonly accept: readonly ["triage:lifecycle-linked"];
+    readonly escalate: readonly ["triage:needs-human"];
+};
+/** Dry-run command shown in the tip (open-only default). */
+export declare const MIRROR_DISCOVERY_DRY_RUN_COMMAND = "deft triage:classify -- --mirror";
+/** Operator ack command that dismisses the tip without a dry-run (#3124 Greptile). */
+export declare const MIRROR_DISCOVERY_ACK_COMMAND = "deft triage:classify -- --ack-discovery";
+/** Policy inspect command. */
+export declare const MIRROR_DISCOVERY_POLICY_SHOW_COMMAND = "deft policy:show --field=plan.policy.triageLabelMirror";
+/**
+ * Agent-facing anti-swallow rule embedded in tip output (#3124).
+ * When this tip fires, agents MUST restate existence + get-the-most in the
+ * user-visible message (not only absorb ceremony output).
+ */
+export declare const MIRROR_DISCOVERY_ANTI_SWALLOW_RULE: string;
+/**
+ * Full operator-facing tip body (existence + get-the-most).
+ * Kept short enough for ceremony but complete enough for PROJECT-DEFINITION edits.
+ */
+export declare function formatMirrorDiscoveryTipBody(): string;
+export declare function formatMirrorDiscoveryTip(): string;
+/**
+ * Emit tip when due; record shownAt. Returns empty string when throttled.
+ * Fail-open on write errors (ceremony must not hard-block).
+ */
+export declare function maybeFormatMirrorDiscoveryTip(projectRoot: string, options?: MirrorDiscoveryTipOptions): string;
+/** Persist operator ack so the tip no longer surfaces. */
+export declare function recordMirrorDiscoveryAcked(projectRoot: string, options?: MirrorDiscoveryTipOptions): void;
+/**
+ * Persist first successful --mirror dry-run so the tip no longer surfaces.
+ * Idempotent: keeps the earliest successfulDryRunAt.
+ */
+export declare function recordMirrorDiscoverySuccessfulDryRun(projectRoot: string, options?: MirrorDiscoveryTipOptions): void;
+/** State path helper for tests / docs. */
+export declare function resolveMirrorDiscoveryStatePath(projectRoot: string): string;
+/** Whether a state file currently exists (tests / diagnostics). */
+export declare function mirrorDiscoveryStateExists(projectRoot: string): boolean;
+export interface MirrorDiscoveryDigestCueInput {
+    readonly planned: number;
+    readonly applied: number;
+    readonly skipped_no_match: number;
+    readonly skipped_already_triaged: number;
+    readonly skipped_closed: number;
+    readonly actionLabelsEmpty: boolean;
+    readonly dry_run: boolean;
+}
+/** Footer when planned rows exist but actionLabels is empty. */
+export declare const MIRROR_DISCOVERY_EMPTY_ACTION_LABELS_HINT: string;
+/** Footer when open no_match dominates under universal rules. */
+export declare const MIRROR_DISCOVERY_NO_MATCH_DOMINATION_HINT: string;
+/**
+ * Build optional digest footer lines for consumer upgrade cues.
+ * Empty when neither condition holds.
+ */
+export declare function formatMirrorDiscoveryDigestCues(input: MirrorDiscoveryDigestCueInput): readonly string[];
+//# sourceMappingURL=mirror-discovery-tip.d.ts.map

package/dist/triage/classify/mirror-discovery-tip.js

@@ -0,0 +1,234 @@
+/**
+ * Operator discovery tip for SCM label mirror (#3124).
+ *
+ * Throttled existence + get-the-most-out-of-it disclosure for cold session /
+ * triage welcome / doctor. Hides after operator ack or first successful dry-run.
+ * Does not fire on session re-arm (welcome skipped).
+ *
+ * Never auto-apply; never auto-accept into proposed/.
+ */
+import { existsSync, mkdirSync, readFileSync } from "node:fs";
+import { basename, dirname, join, resolve } from "node:path";
+import { containedWrite } from "../../fs/contained-write.js";
+import { resolveTriageCachePath } from "../cache-path.js";
+/** State file basename under xbrief/.triage-cache/. */
+export const MIRROR_DISCOVERY_STATE_FILE = "scm-label-mirror-discovery-state.json";
+/** Display/back-compat relative path. */
+export const MIRROR_DISCOVERY_STATE_RELATIVE_PATH = join("xbrief", ".triage-cache", MIRROR_DISCOVERY_STATE_FILE);
+function resolveStatePath(projectRoot) {
+    return resolveTriageCachePath(projectRoot, MIRROR_DISCOVERY_STATE_FILE);
+}
+function defaultReadState(path) {
+    try {
+        return readFileSync(path, "utf8");
+    }
+    catch {
+        return null;
+    }
+}
+function defaultWriteState(path, content) {
+    const dir = dirname(path);
+    mkdirSync(dir, { recursive: true });
+    // Direct contained write (no tmp/rename) — tip state is advisory and small.
+    const base = basename(path);
+    containedWrite({
+        root: resolve(dir),
+        target: base,
+        data: content,
+        mode: "replace",
+    });
+}
+export function parseMirrorDiscoveryState(text) {
+    if (text === null)
+        return {};
+    try {
+        const parsed = JSON.parse(text);
+        if (parsed !== null && typeof parsed === "object" && !Array.isArray(parsed)) {
+            const obj = parsed;
+            return {
+                ...(typeof obj.shownAt === "string" ? { shownAt: obj.shownAt } : {}),
+                ...(typeof obj.ackedAt === "string" ? { ackedAt: obj.ackedAt } : {}),
+                ...(typeof obj.successfulDryRunAt === "string"
+                    ? { successfulDryRunAt: obj.successfulDryRunAt }
+                    : {}),
+            };
+        }
+    }
+    catch {
+        // Corrupt advisory state never blocks ceremony.
+    }
+    return {};
+}
+export function readMirrorDiscoveryState(projectRoot, options = {}) {
+    const path = resolveStatePath(projectRoot);
+    const read = options.readState ?? defaultReadState;
+    return parseMirrorDiscoveryState(read(path));
+}
+function writeMirrorDiscoveryState(projectRoot, state, options = {}) {
+    const path = resolveStatePath(projectRoot);
+    const write = options.writeState ?? defaultWriteState;
+    write(path, `${JSON.stringify(state, null, 2)}\n`);
+}
+/** True when tip should still surface (not acked and no successful dry-run yet). */
+export function isMirrorDiscoveryTipDue(projectRoot, options = {}) {
+    const state = readMirrorDiscoveryState(projectRoot, options);
+    if (state.ackedAt !== undefined && state.ackedAt.length > 0)
+        return false;
+    if (state.successfulDryRunAt !== undefined && state.successfulDryRunAt.length > 0) {
+        return false;
+    }
+    return true;
+}
+/**
+ * Recommended full five-chip machine map for consumers (#3124 / #2611).
+ * Names only — do not invent vocabulary; labels must exist on GitHub.
+ */
+export const MIRROR_DISCOVERY_RECOMMENDED_ACTION_LABELS = {
+    defer: ["triage:deferred"],
+    archive: ["triage:archived"],
+    accept: ["triage:lifecycle-linked"],
+    escalate: ["triage:needs-human"],
+};
+/** Dry-run command shown in the tip (open-only default). */
+export const MIRROR_DISCOVERY_DRY_RUN_COMMAND = "deft triage:classify -- --mirror";
+/** Operator ack command that dismisses the tip without a dry-run (#3124 Greptile). */
+export const MIRROR_DISCOVERY_ACK_COMMAND = "deft triage:classify -- --ack-discovery";
+/** Policy inspect command. */
+export const MIRROR_DISCOVERY_POLICY_SHOW_COMMAND = "deft policy:show --field=plan.policy.triageLabelMirror";
+/**
+ * Agent-facing anti-swallow rule embedded in tip output (#3124).
+ * When this tip fires, agents MUST restate existence + get-the-most in the
+ * user-visible message (not only absorb ceremony output).
+ */
+export const MIRROR_DISCOVERY_ANTI_SWALLOW_RULE = "! Agent anti-swallow (#3124): when this tip fires, restate existence + get-the-most " +
+    "in the **user-visible** message (not ceremony dump alone): feature is default-on; " +
+    "dry-run first; defaults only stamp **triaged** on matches (control stamp, not disposition); " +
+    "board usability is greatly decreased without **actionLabels** (full five-chip map); " +
+    "more matches need **triageAutoClassify**; never auto-accept into proposed/; " +
+    "where policy lives + policy:show; labels must exist on GitHub; " +
+    "applying triaged before actionLabels skips re-enrichment on re-run; " +
+    "point at consumer kit #2611 — do not invent label vocabulary.";
+/**
+ * Full operator-facing tip body (existence + get-the-most).
+ * Kept short enough for ceremony but complete enough for PROJECT-DEFINITION edits.
+ */
+export function formatMirrorDiscoveryTipBody() {
+    const mapJson = JSON.stringify({
+        enabled: true,
+        idempotencyLabel: "triaged",
+        alwaysLabels: ["triaged"],
+        actionLabels: MIRROR_DISCOVERY_RECOMMENDED_ACTION_LABELS,
+    }, null, 2);
+    return [
+        "[deft triage] SCM label mirror discovery (#3124 / #1423):",
+        "  Feature exists and is **default-on** (plan.policy.triageLabelMirror resolves even when absent).",
+        `  Dry-run first (open-only default; --include-closed opt-in): \`${MIRROR_DISCOVERY_DRY_RUN_COMMAND}\``,
+        "  `--apply` writes labels in batches; **never** auto-accepts into proposed/ (triage:accept is separate).",
+        "  Defaults only stamp **`triaged`** on **matches** — a machine control stamp (idempotency), not a disposition board.",
+        "  **Board usability is greatly decreased without `actionLabels`** — every match looks like a single triaged chip.",
+        "  Recommend full five-chip map (create these labels on GitHub first, or apply fails closed):",
+        "    defer→triage:deferred, archive→triage:archived, accept→triage:lifecycle-linked,",
+        "    escalate→triage:needs-human (+ always triaged).",
+        "  Chip setup (all five) is separate from rule aggressiveness — start rules minimal; escalate carefully.",
+        "  More matches → configure `plan.policy.triageAutoClassify` in PROJECT-DEFINITION",
+        '    (xbrief/PROJECT-DEFINITION.xbrief.json → plan["x-directive/policy"] / docs: plan.policy.*).',
+        `  Inspect: \`${MIRROR_DISCOVERY_POLICY_SHOW_COMMAND}\` (and triageAutoClassify).`,
+        "  Labels must **exist on GitHub** (policy JSON alone is insufficient).",
+        "  Warn: applying triaged **before** actionLabels stamps issues that re-run then skips",
+        "    (use --mirror --re-enrich later for additive chips; #3197).",
+        "  Recommended consumer labels + PD sketch: consumer kit **#2611**",
+        "    (content/docs/consumer-issue-label-kit.md) — do not invent new triage:* vocabulary.",
+        "  Depth: commands.md § triage:classify --mirror; tip hides after first successful dry-run",
+        `    or operator ack: \`${MIRROR_DISCOVERY_ACK_COMMAND}\` (not every session re-arm).`,
+        "  Recommended PD sketch:",
+        ...mapJson.split("\n").map((line) => `    ${line}`),
+        MIRROR_DISCOVERY_ANTI_SWALLOW_RULE,
+    ].join("\n");
+}
+export function formatMirrorDiscoveryTip() {
+    return `${formatMirrorDiscoveryTipBody()}\n`;
+}
+/**
+ * Emit tip when due; record shownAt. Returns empty string when throttled.
+ * Fail-open on write errors (ceremony must not hard-block).
+ */
+export function maybeFormatMirrorDiscoveryTip(projectRoot, options = {}) {
+    if (!isMirrorDiscoveryTipDue(projectRoot, options)) {
+        return "";
+    }
+    if (options.recordShown !== false) {
+        try {
+            const now = options.now ?? new Date();
+            const prior = readMirrorDiscoveryState(projectRoot, options);
+            writeMirrorDiscoveryState(projectRoot, {
+                ...prior,
+                shownAt: now.toISOString(),
+            }, options);
+        }
+        catch {
+            // Advisory tip state must never block welcome / session start.
+        }
+    }
+    return formatMirrorDiscoveryTip();
+}
+/** Persist operator ack so the tip no longer surfaces. */
+export function recordMirrorDiscoveryAcked(projectRoot, options = {}) {
+    const now = options.now ?? new Date();
+    const prior = readMirrorDiscoveryState(projectRoot, options);
+    writeMirrorDiscoveryState(projectRoot, {
+        ...prior,
+        ackedAt: now.toISOString(),
+    }, options);
+}
+/**
+ * Persist first successful --mirror dry-run so the tip no longer surfaces.
+ * Idempotent: keeps the earliest successfulDryRunAt.
+ */
+export function recordMirrorDiscoverySuccessfulDryRun(projectRoot, options = {}) {
+    const prior = readMirrorDiscoveryState(projectRoot, options);
+    if (prior.successfulDryRunAt !== undefined && prior.successfulDryRunAt.length > 0) {
+        return;
+    }
+    const now = options.now ?? new Date();
+    writeMirrorDiscoveryState(projectRoot, {
+        ...prior,
+        successfulDryRunAt: now.toISOString(),
+    }, options);
+}
+/** State path helper for tests / docs. */
+export function resolveMirrorDiscoveryStatePath(projectRoot) {
+    return resolveStatePath(projectRoot);
+}
+/** Whether a state file currently exists (tests / diagnostics). */
+export function mirrorDiscoveryStateExists(projectRoot) {
+    return existsSync(resolveStatePath(projectRoot));
+}
+/** Footer when planned rows exist but actionLabels is empty. */
+export const MIRROR_DISCOVERY_EMPTY_ACTION_LABELS_HINT = "Hint (#3124): planned matches will only gain alwaysLabels (triaged) — " +
+    "set plan.policy.triageLabelMirror.actionLabels to map defer/archive/accept/escalate " +
+    "to extra SCM chips (full five recommended; see consumer kit #2611). " +
+    "Board usability is greatly decreased without actionLabels.";
+/** Footer when open no_match dominates under universal rules. */
+export const MIRROR_DISCOVERY_NO_MATCH_DOMINATION_HINT = "Hint (#3124): few open matches under current rules (no_match dominates) — " +
+    "add plan.policy.triageAutoClassify in PROJECT-DEFINITION to classify more of the backlog.";
+/**
+ * Build optional digest footer lines for consumer upgrade cues.
+ * Empty when neither condition holds.
+ */
+export function formatMirrorDiscoveryDigestCues(input) {
+    const lines = [];
+    const writeTotal = input.planned + input.applied;
+    if (writeTotal > 0 && input.actionLabelsEmpty) {
+        lines.push(MIRROR_DISCOVERY_EMPTY_ACTION_LABELS_HINT);
+    }
+    // Open-ish population: exclude closed_skipped from domination base.
+    const openish = writeTotal + input.skipped_no_match + Math.max(0, input.skipped_already_triaged);
+    if (input.skipped_no_match > 0 &&
+        openish > 0 &&
+        input.skipped_no_match >= writeTotal &&
+        input.skipped_no_match * 2 >= openish) {
+        lines.push(MIRROR_DISCOVERY_NO_MATCH_DOMINATION_HINT);
+    }
+    return lines;
+}
+//# sourceMappingURL=mirror-discovery-tip.js.map