@deftai/directive-core 0.100.0 → 0.101.0

package/dist/session/session-start.js

@@ -14,6 +14,7 @@ import { humanMergeDisclosureLine, resolveHumanMergePolicy, } from "../policy/re
 import { resolvePolicy } from "../policy/resolve.js";
 import { maybeFormatProductSignalConsentPrompt } from "../product-signal/consent-prompt.js";
 import { formatFrameworkCommand } from "../render/framework-commands.js";
+import { RunSummaryEmitter } from "../run-summary/emit.js";
 import { formatScmReadinessLines, probeScmReadiness, scmReadinessToDict, } from "../scm/readiness.js";
 import { maybeRunStalenessTickler } from "../staleness-tickler/run.js";
 import { runDefaultMode } from "../triage/welcome/default-mode.js";
@@ -23,10 +24,12 @@ import { verifyRequiredTools } from "../verify-env/verify-tools.js";
 import { maybeFormatCoverageCheckResumeNudge } from "./coverage-check-resume-nudge.js";
 import { effortBudgetToDict, maybeFormatEffortBudgetLines, resolveProductionHostEffortDescriptor, } from "./effort-budget.js";
 import { defaultGitRunner, gitHead, gitIsAncestor, worktreePath } from "./git.js";
+import { runOrientationCompression, } from "./orientation-compression.js";
 import { emitSessionStartProcessCost } from "./process-cost.js";
 import { probeSessionReleaseAvailability, } from "./release-availability.js";
 import { newRitualStatePayload, readRitualState, ritualStatePath, ritualStep, writeRitualState, } from "./ritual-sentinel.js";
 import { timestampIso } from "./time.js";
+import { runToolchainPreflight, toolchainPreflightToDict, } from "./toolchain-preflight.js";
 export const SESSION_POSTURES = ["read-only", "mutation"];
 export const READ_ONLY_POSTURE = "read-only";
 export const MUTATION_POSTURE = "mutation";
@@ -952,6 +955,120 @@ export function runSessionStart(projectRoot, options = {}) {
         });
         stepTimings.push({ name: "verify_tools", duration_ms: durationMs });
     }
+    // #3282 / #3286: orientation compression — compose doctor + toolchain preflight
+    // (+ agents:refresh / cache-fresh deposit-sha fast-paths) as inline sections with
+    // per-section status lines. Composition of existing steps, not a new monolith.
+    // Read-only posture never reaches here (#2176). Dual-path Later (`deft orient`)
+    // remains open — see orientation bundle.later.
+    let toolchainPreflightResult = null;
+    let orientationBundle = null;
+    {
+        const stepStarted = performance.now();
+        if (options.orientation === null) {
+            // Explicit skip (tests): still honour legacy preflight-only path when set.
+            if (options.toolchainPreflight === null) {
+                stepTimings.push({ name: "orientation", duration_ms: 0, skipped: true });
+                stepTimings.push({ name: "toolchain_preflight", duration_ms: 0, skipped: true });
+            }
+            else if (options.toolchainPreflight !== undefined) {
+                toolchainPreflightResult = options.toolchainPreflight;
+                lines.push(...toolchainPreflightResult.lines);
+                stepTimings.push({
+                    name: "toolchain_preflight",
+                    duration_ms: elapsedMs(stepStarted),
+                });
+            }
+            else {
+                stepTimings.push({ name: "orientation", duration_ms: 0, skipped: true });
+            }
+        }
+        else if (options.orientation !== undefined) {
+            orientationBundle = options.orientation;
+            toolchainPreflightResult = orientationBundle.preflight;
+            lines.push(...orientationBundle.lines);
+            for (const section of orientationBundle.sections) {
+                stepTimings.push({
+                    name: section.name,
+                    duration_ms: section.durationMs,
+                    ...(section.status === "skipped" ? { skipped: true } : {}),
+                });
+                // Record gated ritual steps so verify:session-ritual can skip re-runs.
+                // Do not overwrite explicit --defer (deferred_reason) records.
+                if ((section.name === "doctor" || section.name === "cache_fresh") &&
+                    !gatedSteps[section.name]?.deferred_reason) {
+                    gatedSteps[section.name] = ritualStep({
+                        ok: section.ok,
+                        ts: instant,
+                        message: section.lines[0] ?? section.status,
+                        exitCode: section.exitCode,
+                        durationMs: section.durationMs,
+                        command: section.name === "doctor" ? ["doctor"] : ["verify:cache-fresh"],
+                    });
+                }
+            }
+            stepTimings.push({ name: "orientation", duration_ms: elapsedMs(stepStarted) });
+        }
+        else {
+            try {
+                // Skip composed doctor/cache_fresh work when those gated steps are deferred.
+                const doctorDeferred = Boolean(gatedSteps.doctor?.deferred_reason);
+                const cacheDeferred = Boolean(gatedSteps.cache_fresh?.deferred_reason);
+                orientationBundle = runOrientationCompression({
+                    projectRoot,
+                    frameworkRoot: options.frameworkRoot ?? projectRoot,
+                    compact: options.compact,
+                    env: options.env,
+                    now: instant,
+                    toolchainPreflight: options.toolchainPreflight,
+                    toolchainPreflightOptions: options.toolchainPreflightOptions,
+                    includeDoctor: !doctorDeferred,
+                    includeCacheFresh: !cacheDeferred,
+                    ...options.orientationOptions,
+                });
+                toolchainPreflightResult = orientationBundle.preflight;
+                lines.push(...orientationBundle.lines);
+                for (const section of orientationBundle.sections) {
+                    stepTimings.push({
+                        name: section.name,
+                        duration_ms: section.durationMs,
+                        ...(section.status === "skipped" ? { skipped: true } : {}),
+                    });
+                    if ((section.name === "doctor" || section.name === "cache_fresh") &&
+                        !gatedSteps[section.name]?.deferred_reason) {
+                        gatedSteps[section.name] = ritualStep({
+                            ok: section.ok,
+                            ts: instant,
+                            message: section.lines[0] ?? section.status,
+                            exitCode: section.exitCode,
+                            durationMs: section.durationMs,
+                            command: section.name === "doctor" ? ["doctor"] : ["verify:cache-fresh"],
+                        });
+                    }
+                }
+                stepTimings.push({ name: "orientation", duration_ms: elapsedMs(stepStarted) });
+            }
+            catch {
+                // fail-open: orientation composition must not abort session:start —
+                // fall back to preflight-only (#3282).
+                try {
+                    if (options.toolchainPreflight !== null) {
+                        toolchainPreflightResult =
+                            options.toolchainPreflight ??
+                                runToolchainPreflight({
+                                    projectRoot,
+                                    frameworkRoot: options.frameworkRoot ?? projectRoot,
+                                    ...options.toolchainPreflightOptions,
+                                });
+                        lines.push(...toolchainPreflightResult.lines);
+                    }
+                }
+                catch {
+                    // ignore
+                }
+                stepTimings.push({ name: "orientation", duration_ms: elapsedMs(stepStarted) });
+            }
+        }
+    }
     // #3214: rapid/minimal skip informational cold-path ceremony only.
     if (!quickSteps.triage_welcome && !skipFatPath) {
         const stepStarted = performance.now();
@@ -1086,6 +1203,7 @@ export function runSessionStart(projectRoot, options = {}) {
             reasons: [...provisionalDial.reasons],
         },
     };
+    const preflightDict = toolchainPreflightResult !== null ? toolchainPreflightToDict(toolchainPreflightResult) : null;
     const payload = {
         ...newRitualStatePayload({
             sessionId: coldSessionId,
@@ -1097,6 +1215,8 @@ export function runSessionStart(projectRoot, options = {}) {
         }),
         // #3214: record dial choice on ritual-state for audit / later re-arm context.
         ceremony_dial: dialDict,
+        // #3282: durable preflight snapshot for harness / later check degraded mode.
+        ...(preflightDict !== null ? { toolchain_preflight: preflightDict } : {}),
     };
     let statePath;
     try {
@@ -1120,8 +1240,45 @@ export function runSessionStart(projectRoot, options = {}) {
         .filter(([, step]) => !step.ok && !step.deferred_reason)
         .map(([name]) => name);
     // verify_tools is recorded on quick_steps; failure makes ready=false.
+    // #3282: toolchain preflight degraded mode does NOT flip ready=false by itself —
+    // agents still proceed with a named skip report at check time.
     const code = failed.length > 0 ? 1 : 0;
     const totalMs = elapsedMs(overallStarted);
+    // #3282 / #3286: event-driven run-summary (dial + preflight + orientation call
+    // count for dual-path Later graduation trigger) — fail-open, silent when unset.
+    if (options.emitRunSummary !== false) {
+        try {
+            const emitter = new RunSummaryEmitter({
+                projectRoot,
+                sessionId: coldSessionId,
+                env: options.env,
+            });
+            emitter.emitSessionStart({
+                ceremony_dial: dialDict,
+                preflight: preflightDict ?? undefined,
+                ceremony_tier: COLD_CEREMONY_TIER,
+                ready: code === 0,
+                exit_code: code,
+                ...(orientationBundle !== null
+                    ? {
+                        orientation_call_count: orientationBundle.orientationCallCount,
+                        orientation_compact: orientationBundle.compact,
+                        deposit_sha: orientationBundle.depositSha,
+                        orientation_later_status: orientationBundle.later.status,
+                        orientation_sections: orientationBundle.sections.map((s) => ({
+                            name: s.name,
+                            status: s.status,
+                            ok: s.ok,
+                            sha_match: s.shaMatch,
+                        })),
+                    }
+                    : {}),
+            });
+        }
+        catch {
+            // fail-open
+        }
+    }
     // #3117: bind live deposit generation when payload surfaces load (cold path).
     let freshnessBind = null;
     try {
@@ -1153,6 +1310,24 @@ export function runSessionStart(projectRoot, options = {}) {
         exit_code: code,
         ceremony_tier: COLD_CEREMONY_TIER,
         ceremony_dial: dialDict,
+        ...(preflightDict !== null ? { toolchain_preflight: preflightDict } : {}),
+        ...(orientationBundle !== null
+            ? {
+                orientation: {
+                    deposit_sha: orientationBundle.depositSha,
+                    compact: orientationBundle.compact,
+                    call_count: orientationBundle.orientationCallCount,
+                    later: orientationBundle.later,
+                    sections: orientationBundle.sections.map((s) => ({
+                        name: s.name,
+                        status: s.status,
+                        ok: s.ok,
+                        sha_match: s.shaMatch,
+                        exit_code: s.exitCode,
+                    })),
+                },
+            }
+            : {}),
         state_path: statePath,
         ...(freshnessBind ? { freshness: freshnessBind } : {}),
         quick_steps: quickSteps,

package/dist/session/toolchain-preflight.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Done-gate toolchain preflight at session start (#3282).
+ *
+ * Verifies the framework done-gate's own toolchain (task binary, package
+ * manager, node, optional CLI dist) up front so agents get a named cause +
+ * remedy in one turn instead of reverse-engineering `directive check` failures.
+ *
+ * Never bootstraps tooling the PRODUCT does not need. Failures name cause and
+ * remedy without embedding env values.
+ */
+export declare const TOOLCHAIN_PREFLIGHT_TOOLS: readonly ["task", "pnpm", "node", "git"];
+export type ToolchainPreflightTool = (typeof TOOLCHAIN_PREFLIGHT_TOOLS)[number];
+export type ToolchainPreflightStatus = "ok" | "missing" | "degraded";
+export interface ToolchainPreflightFinding {
+    readonly tool: ToolchainPreflightTool | "cli_dist";
+    readonly present: boolean;
+    /** Machine-stable cause code (never embeds env values). */
+    readonly cause: string | null;
+    /** Operator/agent remedy command or instruction. */
+    readonly remedy: string | null;
+}
+export interface ToolchainPreflightResult {
+    readonly status: ToolchainPreflightStatus;
+    readonly ok: boolean;
+    /** True when missing tools would force check into degraded/skip mode. */
+    readonly degraded: boolean;
+    readonly findings: readonly ToolchainPreflightFinding[];
+    /** Human lines for session:start stdout (named cause + remedy). */
+    readonly lines: readonly string[];
+    /**
+     * Gate ids that check should skip when this preflight is degraded.
+     * Product-ordering of remaining gates is owned by #3284.
+     */
+    readonly skipGateIds: readonly string[];
+}
+export interface ToolchainPreflightOptions {
+    readonly projectRoot?: string;
+    readonly frameworkRoot?: string;
+    /** which(name) seam for tests. */
+    readonly which?: (name: string) => string | null;
+    /** existsSync seam for tests. */
+    readonly exists?: (path: string) => boolean;
+    /**
+     * When true (default), also probe for a built CLI dist under frameworkRoot
+     * (framework-source dogfood). Consumers without a local dist are fine when
+     * a global `deft`/`directive` is on PATH.
+     */
+    readonly probeCliDist?: boolean;
+}
+/**
+ * Gates that specifically need a package manager / built dist.
+ * When task/node is missing, the orchestrator skips *all* scheduled gates
+ * (dynamic from gate-lists), not this static list — avoids hardcode drift.
+ */
+export declare const PNPM_DEPENDENT_GATE_IDS: readonly string[];
+/** Sentinel skip id meaning "every gate in the active check composition". */
+export declare const SKIP_ALL_GATES = "*";
+/**
+ * Run done-gate toolchain preflight. Pure probe — never installs or builds.
+ */
+export declare function runToolchainPreflight(options?: ToolchainPreflightOptions): ToolchainPreflightResult;
+/** Serialize preflight for run-summary / ritual-state (no env values). */
+export declare function toolchainPreflightToDict(result: ToolchainPreflightResult): Record<string, unknown>;
+//# sourceMappingURL=toolchain-preflight.d.ts.map

package/dist/session/toolchain-preflight.js

@@ -0,0 +1,151 @@
+/**
+ * Done-gate toolchain preflight at session start (#3282).
+ *
+ * Verifies the framework done-gate's own toolchain (task binary, package
+ * manager, node, optional CLI dist) up front so agents get a named cause +
+ * remedy in one turn instead of reverse-engineering `directive check` failures.
+ *
+ * Never bootstraps tooling the PRODUCT does not need. Failures name cause and
+ * remedy without embedding env values.
+ */
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { defaultWhich } from "../doctor/which.js";
+export const TOOLCHAIN_PREFLIGHT_TOOLS = ["task", "pnpm", "node", "git"];
+const REMEDY = {
+    task: "Install go-task: https://taskfile.dev/installation/ (e.g. winget install Task.Task / brew install go-task)",
+    pnpm: "Enable pnpm via corepack: corepack enable && corepack prepare pnpm@latest --activate",
+    node: "Install Node 20+ (see .nvmrc); then corepack enable",
+    git: "Install Git: https://git-scm.com/downloads",
+};
+const CAUSE = {
+    task: "go-task binary not found on PATH",
+    pnpm: "pnpm binary not found on PATH",
+    node: "node binary not found on PATH",
+    git: "git binary not found on PATH",
+};
+/**
+ * Gates that specifically need a package manager / built dist.
+ * When task/node is missing, the orchestrator skips *all* scheduled gates
+ * (dynamic from gate-lists), not this static list — avoids hardcode drift.
+ */
+export const PNPM_DEPENDENT_GATE_IDS = [
+    "toolchain:check",
+    "toolchain:check-consumer",
+    "ts:check-lane",
+];
+/** Sentinel skip id meaning "every gate in the active check composition". */
+export const SKIP_ALL_GATES = "*";
+function probeTool(tool, which) {
+    const present = which(tool) !== null;
+    return {
+        tool,
+        present,
+        cause: present ? null : CAUSE[tool],
+        remedy: present ? null : REMEDY[tool],
+    };
+}
+function probeCliDist(frameworkRoot, which, exists) {
+    const globalCli = which("deft") !== null || which("directive") !== null;
+    if (globalCli) {
+        return { tool: "cli_dist", present: true, cause: null, remedy: null };
+    }
+    if (frameworkRoot) {
+        const distBin = join(frameworkRoot, "packages", "cli", "dist", "bin.js");
+        if (exists(distBin)) {
+            return { tool: "cli_dist", present: true, cause: null, remedy: null };
+        }
+        return {
+            tool: "cli_dist",
+            present: false,
+            cause: "CLI dist missing and no global deft/directive on PATH",
+            remedy: "Run `task build` (framework source) or `npm i -g @deftai/directive@latest`",
+        };
+    }
+    return {
+        tool: "cli_dist",
+        present: false,
+        cause: "no global deft/directive on PATH",
+        remedy: "Install: npm i -g @deftai/directive@latest",
+    };
+}
+function formatFindingLine(finding) {
+    if (finding.present) {
+        return `[deft preflight] ${finding.tool}: ok`;
+    }
+    const cause = finding.cause ?? "missing";
+    const remedy = finding.remedy ?? "install the tool";
+    return `[deft preflight] ${finding.tool}: MISSING — cause: ${cause}; remedy: ${remedy}`;
+}
+/**
+ * Run done-gate toolchain preflight. Pure probe — never installs or builds.
+ */
+export function runToolchainPreflight(options = {}) {
+    const which = options.which ?? defaultWhich;
+    const exists = options.exists ?? existsSync;
+    const findings = [];
+    for (const tool of TOOLCHAIN_PREFLIGHT_TOOLS) {
+        findings.push(probeTool(tool, which));
+    }
+    if (options.probeCliDist !== false) {
+        findings.push(probeCliDist(options.frameworkRoot ?? options.projectRoot, which, exists));
+    }
+    const missingCritical = findings.filter((f) => !f.present && (f.tool === "task" || f.tool === "pnpm" || f.tool === "node"));
+    const taskMissing = findings.some((f) => f.tool === "task" && !f.present);
+    const pnpmMissing = findings.some((f) => f.tool === "pnpm" && !f.present);
+    const nodeMissing = findings.some((f) => f.tool === "node" && !f.present);
+    const skip = new Set();
+    if (taskMissing || nodeMissing) {
+        // Dynamic: orchestrator expands SKIP_ALL_GATES to the live gate list.
+        skip.add(SKIP_ALL_GATES);
+    }
+    else if (pnpmMissing) {
+        for (const id of PNPM_DEPENDENT_GATE_IDS) {
+            skip.add(id);
+        }
+    }
+    const degraded = missingCritical.length > 0;
+    const ok = !degraded;
+    const status = ok ? "ok" : "degraded";
+    const lines = [];
+    lines.push(`[deft preflight] toolchain status: ${status}`);
+    for (const finding of findings) {
+        if (!finding.present) {
+            lines.push(formatFindingLine(finding));
+        }
+    }
+    if (ok) {
+        lines.push("[deft preflight] done-gate toolchain ready (task, pnpm, node)");
+    }
+    else {
+        lines.push("[deft preflight] degraded mode: directive check will skip toolchain-dependent gates " +
+            "with a named skip report rather than bootstrapping product-unneeded tooling (#3282)");
+        if (skip.size > 0) {
+            lines.push(`[deft preflight] gates subject to skip when degraded: ${[...skip].sort().join(", ")}`);
+        }
+    }
+    return {
+        status,
+        ok,
+        degraded,
+        findings,
+        lines,
+        skipGateIds: [...skip].sort(),
+    };
+}
+/** Serialize preflight for run-summary / ritual-state (no env values). */
+export function toolchainPreflightToDict(result) {
+    return {
+        status: result.status,
+        ok: result.ok,
+        degraded: result.degraded,
+        findings: result.findings.map((f) => ({
+            tool: f.tool,
+            present: f.present,
+            cause: f.cause,
+            remedy: f.remedy,
+        })),
+        skip_gate_ids: [...result.skipGateIds],
+    };
+}
+//# sourceMappingURL=toolchain-preflight.js.map

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. */