session-orchestrator 3.17.0 → 3.19.0

package/scripts/lib/quality-gate.mjs

@@ -60,7 +60,10 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync, renameSync } from '
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
+import { emitEvent, sessionAttribution } from './events.mjs';
+import { admitSuiteCounts, extractTestCounts } from './gates/gate-helpers.mjs';
 import { redactDiagnosticsBundle } from './quality-gate/diagnostics.mjs';
+
 export { redactDiagnosticsBundle } from './quality-gate/diagnostics.mjs';
 
 // ---------------------------------------------------------------------------
@@ -361,6 +364,44 @@ export function detectSharedLibTouch(opts) {
   return { touched: matched.length > 0, paths: matched };
 }
 
+/**
+ * INPUT ADAPTER for this module's `counts` field (#954, #967 item 2).
+ *
+ * Holds NO admission policy of its own. Every verdict — including both
+ * rejections this function used to make itself — is delegated to
+ * {@link admitSuiteCounts}, the single policy shared with the CLI producer
+ * `suiteCountsFromGateStdout` (`scripts/run-quality-gate.mjs`). Before that
+ * convergence the two producers wrote the SAME event field under DIFFERENT
+ * rules (this one admitted `passed > total` and a negative `passed`), so a
+ * consumer had to know two policies to read one field.
+ *
+ * What stays here is the part the shared policy cannot see: the raw-text tail
+ * parse. `extractTestCounts` has no "did it match?" channel — it returns
+ * `0/0/0` both for "no `<N> passed` marker in the output" and for a genuinely
+ * empty run — so a text-less input is handed to the policy as `null` rather
+ * than as a zero triple, and the policy refuses it. The result is `null`, never
+ * a zero triple: `counts.failed === 0` means "measured, zero failures"; an
+ * ABSENT `counts` means "not measured".
+ *
+ * That null hand-over is ALSO how this adapter reports "the gate loop never
+ * reached the test step" (#969 MED-2). A `null` output fails the string check on
+ * the first line, so the positional evidence and the unparseable-text case land
+ * on the SAME channel the policy already has to check. The policy previously
+ * took a second `measured` boolean for the positional case; it was unreachable
+ * with a non-null triple precisely because this line runs first, and two ways to
+ * say "not measured" is one more than the field can be read with.
+ *
+ * @param {string|null} output — captured stdout+stderr tail from the test gate,
+ *   or `null` when the gate loop never reached the test step.
+ * @returns {{ passed: number, failed: number, total: number }|null}
+ */
+function suiteCountsFromOutput(output) {
+  if (typeof output !== 'string' || output.length === 0) {
+    return admitSuiteCounts(null);
+  }
+  return admitSuiteCounts(extractTestCounts(output));
+}
+
 /**
  * Coerce `maxRetries` to [0, MAX_RETRIES_HARD_CAP] integer.
  *
@@ -379,6 +420,97 @@ function coerceMaxRetries(n) {
 // Public API
 // ---------------------------------------------------------------------------
 
+/**
+ * Emit exactly one `orchestrator.quality_gate.{passed,failed}` event per
+ * `runQualityGateWithRetry` CALL (#928b).
+ *
+ * NO DOUBLE-COUNTING. The two gate paths never nest:
+ *   - `scripts/run-quality-gate.mjs` spawns `scripts/lib/gates/gate-*.mjs`
+ *     directly and does not import this module;
+ *   - this module spawns the resolved gate COMMANDS (and `parse-config.mjs`)
+ *     directly and does not invoke that wrapper.
+ * A single run therefore passes through exactly one emitter.
+ *
+ * Granularity is the CALL, not the attempt: the retry loop may run the gates
+ * up to `maxRetries + 1` times, but emitting per attempt would inflate every
+ * rate computed over these events. `attempts` carries that detail instead.
+ * `variant: 'auto-fix-loop'` distinguishes this path from the CLI's
+ * baseline/incremental/full-gate/per-file variants.
+ *
+ * The destination is pinned to the `repoRoot` this gate actually ran against,
+ * via the `opts.repoRoot` parameter (#941; formerly a hand-built `opts.filePath`
+ * recipe, #611). `emitEvent`'s BARE default resolution goes through the
+ * module-level `SO_PROJECT_DIR` constant, which ignores `repoRoot` entirely — so
+ * a caller running the gate against another tree (every unit test does, using a
+ * tmp `repoRoot`) would otherwise append synthetic records to the REAL repo's
+ * telemetry. That is not a test-hygiene nicety: injected `quality_gate.failed`
+ * records are exactly what `/eval`'s gate-health dimension reads, so the
+ * instrument would be scored against its own test fixtures.
+ *
+ * `counts` (#954) carries the suite numbers this gate already had in hand. It
+ * is OMITTED — never zero-filled — whenever the final attempt did not reach the
+ * test gate (fail-fast on lint/typecheck) or its output carried no parseable
+ * count. See {@link suiteCountsFromOutput}.
+ *
+ * IT DOES NOT YET REPLACE THE PROSE PATH (#957/F1 — the earlier wording here
+ * claimed it did). `waves[].suite_passed` / `suite_failed` still travel as prose
+ * through two LLM hops: `skills/wave-executor/wave-loop.md` step 7 hand-writes
+ * them, `skills/session-end/metrics-collection.md` § 1.7 parses them back out of
+ * the STATE.md Wave History header into sessions.jsonl. `counts` is a SECOND,
+ * machine-measured emission of the same fact, and as of 2026-07-31 it has zero
+ * readers (`grep -c '"counts"' .orchestrator/metrics/events.jsonl` → 0 across
+ * 4404 `orchestrator.quality_gate.*` records).
+ *
+ * Retiring the prose path needs a producer change no docblock can make:
+ * `waves[].*` is PER-WAVE, and gate events carry no `wave_number` (0 of those
+ * 4404 records). A session-end reader could only attribute a gate event to a
+ * wave by a wall-clock window whose own boundaries (`waves[].started_at` /
+ * `completed_at`) are themselves LLM-written — one LLM hop traded for another,
+ * against the posture `scripts/lib/eval/session-resolve.mjs` already documents
+ * for window-attributed gate events ("a contaminated window means
+ * gate-attribution is unsafe"). The concrete remaining work is named in
+ * `skills/session-end/metrics-collection.md` § 1.7.
+ *
+ * Note also that THIS emitter only runs under `verification-auto-fix.enabled:
+ * true` (default `false`, and `false` in this repo's Session Config). The gate
+ * that actually fires between waves is the `scripts/run-quality-gate.mjs`
+ * wrapper, which emits its own `counts` via `suiteCountsFromGateStdout` — under
+ * the SAME admission policy since #967 item 2 (`admitSuiteCounts`), so a
+ * consumer reads one field with one set of rules regardless of which producer
+ * wrote it.
+ *
+ * Extraction margin: {@link suiteCountsFromOutput} sees only the
+ * `OUTPUT_TAIL_LINES` (50) tail `runCheck` retains. Measured on `npm test`
+ * (vitest 2026-07-31), the `Tests` summary line sits 5 lines from the end — 45
+ * lines of headroom. A runner epilogue longer than that (coverage table, long
+ * unhandled-error dump) pushes the summary out of the window; `counts` is then
+ * omitted, which fails safe but is indistinguishable from "no test gate ran".
+ *
+ * Best-effort: never throws, never alters the gate verdict.
+ *
+ * @param {string} repoRoot
+ * @param {boolean} ok
+ * @param {number} attempts
+ * @param {string|null} gate
+ * @param {{passed: number, failed: number, total: number}|null} [counts]
+ */
+async function emitGateEvent(repoRoot, ok, attempts, gate, counts) {
+  try {
+    await emitEvent(
+      `orchestrator.quality_gate.${ok ? 'passed' : 'failed'}`,
+      {
+        variant: 'auto-fix-loop',
+        exit_code: ok ? 0 : 1,
+        attempts,
+        ...(gate ? { gate } : {}),
+        ...(counts ? { counts } : {}),
+        ...sessionAttribution(repoRoot),
+      },
+      { repoRoot },
+    );
+  } catch { /* best-effort telemetry — gate result is authoritative */ }
+}
+
 /**
  * Run quality gate (lint → typecheck → test, fail-fast), dispatching a fixer
  * callback on each failure up to `maxRetries` times.
@@ -421,6 +553,14 @@ export async function runQualityGateWithRetry(opts) {
   const allFailures = [];
   let attempt = 0;
   let lastFailure = null;
+  /**
+   * Suite counts observed in the CURRENT attempt only (#954). Re-assigned
+   * unconditionally after every attempt's gate loop, so a failure that
+   * fail-fasts on lint can never re-report a stale count from an earlier
+   * attempt's test run.
+   * @type {{passed: number, failed: number, total: number}|null}
+   */
+  let testCounts = null;
 
   // Total loop budget = maxRetries + 1 (one initial run + up to maxRetries fixer-driven retries).
   const totalAttempts = maxRetries + 1;
@@ -428,10 +568,30 @@ export async function runQualityGateWithRetry(opts) {
   while (attempt < totalAttempts) {
     attempt += 1;
     let gateFailure = null;
+    /**
+     * The test gate's captured output for THIS attempt — `null` until the
+     * `test` branch below assigns it, which happens only if the gate loop
+     * actually reaches the test step. A fail-fast on lint or typecheck leaves
+     * it `null`.
+     *
+     * That null-ness is the positional evidence {@link admitSuiteCounts}
+     * cannot observe for itself: the shared policy sees a candidate triple and
+     * nothing else, never the control flow that produced it. It reaches the
+     * policy AS the null triple {@link suiteCountsFromOutput} hands over, so an
+     * unmeasured gate can never publish a zero triple attributed to a run that
+     * never happened.
+     * @type {string|null}
+     */
+    let testOutput = null;
 
     for (const gate of GATE_ORDER) {
       const cmd = commands[gate];
       const result = runGate(cmd, repoRoot);
+      if (gate === 'test') {
+        // The numbers are in hand right here — capture them at the seam rather
+        // than letting them travel as prose (#954).
+        testOutput = result.output;
+      }
       if (result.exitCode === 0) {
         process.stderr.write(`🔁 quality-gate attempt ${attempt}/${totalAttempts} (gate=${gate}): pass\n`);
         continue;
@@ -449,9 +609,14 @@ export async function runQualityGateWithRetry(opts) {
       break;
     }
 
+    // Non-fatal by construction: an unmeasured, unparseable or inconsistent
+    // run yields null, which the emitter omits rather than zero-fills.
+    testCounts = suiteCountsFromOutput(testOutput);
+
     if (gateFailure === null) {
       // All gates passed this attempt.
       writeLastGreenSha(repoRoot);
+      await emitGateEvent(repoRoot, true, attempt, null, testCounts);
       return { ok: true, attempts: attempt };
     }
 
@@ -516,6 +681,8 @@ export async function runQualityGateWithRetry(opts) {
     `❌ quality-gate exhausted retries (${attempt}), writing diagnostics to ${bundlePath ?? '<unwritable>'}\n`,
   );
 
+  await emitGateEvent(repoRoot, false, attempt, lastFailure?.gate ?? null, testCounts);
+
   const out = {
     ok: false,
     attempts: attempt,

package/scripts/lib/recommendations-v0.mjs

@@ -26,7 +26,7 @@ const VALID_MODES = new Set([
  * @param {number} input.completionRate  — 0.00..1.00; share of planned issues closed
  * @param {number} input.carryoverRatio  — 0.00..1.00; carryover / planned (0 when planned=0)
  * @param {Array<number|string>} [input.carryoverIssues] — IDs/IIDs of carried-over issues,
- *   pre-sorted (priority:critical/high first, FIFO tiebreak). Sliced to 0-5 entries for
+ *   pre-sorted (priority::critical/high first, FIFO tiebreak). Sliced to 0-5 entries for
  *   the `priorities` field.
  * @returns {{mode: string, priorities: number[], rationale: string}}
  */

package/scripts/lib/reconcile/eligibility.mjs

@@ -135,7 +135,7 @@ export function classifyLearning(learning, { now, minInsightChars } = {}) {
   if (!Array.isArray(filePaths) || filePaths.length === 0) {
     return {
       eligible: false,
-      reason: `eligible type '${type}' but empty file_paths[] — cannot scope a conditional rule`,
+      reason: `eligible type '${type}' but empty file_paths[] — cannot scope a conditional rule (propose with --file-paths to make this convertible)`,
     };
   }
 

package/scripts/lib/reconcile/emitter.mjs

@@ -65,13 +65,26 @@ function kebab(s) {
     .replace(/^-+|-+$/g, '');
 }
 
+// Glob metacharacters (issue #900-follow-up, Q3-MED). A top-level
+// (dirname==='.') file_paths entry is emitted AS THE GLOB ITSELF below — so a
+// stray '**' or '[ab]' entry (e.g. from an OLD learning record predating the
+// #900 C / schema.mjs argv-boundary guards) must never reach the renderer
+// verbatim, or it would produce an effectively always-on rule glob. Skipped
+// here as defense-in-depth even though the argv (memory-propose.mjs) and
+// schema (memory-proposals/schema.mjs) layers already reject these at write
+// time — this emitter also processes learnings.jsonl entries that predate
+// those guards.
+const GLOB_METACHAR_RE = /[*?[\]{}]/;
+
 /**
  * Derive non-empty directory globs from a learning's `file_paths`.
  *
  * For each path: take its directory (`path.dirname`) and emit `<dir>/**`. When
  * the file sits at the repo top level (`dirname` === '.'), emit the bare
- * basename pattern instead of `./**` (e.g. `"foo.mjs"`). Results are deduped,
- * order-preserving on first occurrence.
+ * basename pattern instead of `./**` (e.g. `"foo.mjs"`). Entries containing a
+ * glob metacharacter (`* ? [ ] { }`) are skipped entirely — see
+ * {@link GLOB_METACHAR_RE}. Results are deduped, order-preserving on first
+ * occurrence.
  *
  * @param {string[]} filePaths
  * @returns {string[]}
@@ -81,6 +94,7 @@ function globsFromFilePaths(filePaths) {
   const seen = new Set();
   for (const raw of filePaths) {
     if (typeof raw !== 'string' || raw === '') continue;
+    if (GLOB_METACHAR_RE.test(raw)) continue;
     const normalized = raw.replace(/\\/g, '/');
     const dir = dirname(normalized);
     const pattern = dir === '.' ? normalized : `${dir}/**`;
@@ -181,8 +195,13 @@ function computeExpiresAt(learning, ruleExpiryDays, now, minRuleDays) {
  * @param {object} [opts]
  * @param {number} [opts.ruleExpiryDays] - explicit expiry window in days; when a
  *   finite number, overrides the per-type TTL.
- * @param {number|Date} [opts.now] - injectable clock used ONLY as a fallback when
- *   `created_at` is missing/unparseable (keeps expiry deterministic in tests).
+ * @param {number|Date} [opts.now] - injectable clock (defaults to `Date.now()`).
+ *   Used for BOTH the born-dead expiry floor (`now + minRuleDays`, applied on
+ *   every call — see {@link computeExpiresAt}) and, secondarily, as the base
+ *   date when `created_at` is missing/unparseable. Because the floor consults
+ *   it unconditionally, any test asserting a literal `expiresAt` MUST inject
+ *   `now` — otherwise the wall clock eventually raises the floor past the
+ *   derived expiry and the assertion silently starts measuring the floor.
  * @param {number} [opts.minRuleDays] - floor window (days) applied to the
  *   emitted expiry so it never falls in the past — see
  *   {@link computeExpiresAt} and {@link MIN_RULE_DAYS_DEFAULT}. Defaults

package/scripts/lib/reconcile/engine.mjs

@@ -62,7 +62,24 @@
  * @property {number} eligible
  * @property {number} proposed
  * @property {number} rejected
+ * @property {number} capped   - count of eligible learnings that were NOT proposed
+ *        this run purely because of the `maxProposalsPerRun` volume brake (issue
+ *        #900 D — confidence-sorted, lowest-confidence entries cut first). Each
+ *        capped learning is ALSO counted inside `rejected` (with a `capped — ...`
+ *        reason) — `totalLearnings === proposed + rejected` still holds unchanged;
+ *        `capped` is a diagnostic sub-count that lets a report distinguish
+ *        "genuinely ineligible" rejections from "eligible but cut by the volume
+ *        brake" ones at a glance.
  * @property {boolean} written
+ * @property {number} [skipped] - how many persisted sidecar lines the store's
+ *        read-side shape guard rejected and this run therefore DROPPED from disk
+ *        (`mergeCandidates` rewrites the store in full, never appends — see
+ *        `idempotency.mjs`). PRESENT-vs-ABSENT is load-bearing and must not be
+ *        collapsed: `0` means "the store was inspected and nothing was dropped",
+ *        while ABSENCE means "the store was never inspected this run" — the case
+ *        under `dryRun` (merge skipped entirely), on the empty short-circuit, on
+ *        the top-level error path, and when the merge seam reports no count.
+ *        Defaulting the absent case to `0` would be a false all-clear.
  *
  * @typedef {Object} ReconcileResult
  * @property {ReconcileProposal[]} proposals
@@ -78,11 +95,24 @@ import { migrateLegacyLearning, normalizeLearning } from '../learnings/schema.mj
 import { filterEligible } from './eligibility.mjs';
 import { toActivationMetadata } from './emitter.mjs';
 import { renderRule } from './renderer.mjs';
-import { makeCandidateId, mergeCandidates as realMergeCandidates } from './idempotency.mjs';
+import {
+  DEFAULT_STORE_PATH,
+  buildCandidate,
+  makeCandidateId,
+  mergeCandidates as realMergeCandidates,
+} from './idempotency.mjs';
 
 /** Default repo-relative location of the learnings corpus. */
 const DEFAULT_LEARNINGS_PATH = '.orchestrator/metrics/learnings.jsonl';
 
+/**
+ * Default volume brake (issue #900 D) — mirrors the `reconcile.max-proposals-
+ * per-run` Session Config default in `scripts/lib/config/reconcile.mjs`. Applied
+ * even when a caller omits `maxProposalsPerRun` entirely, so the engine never
+ * silently proposes an unbounded number of rules in one run.
+ */
+const DEFAULT_MAX_PROPOSALS_PER_RUN = 10;
+
 /**
  * Build a fully-zeroed result (the empty / error shape). Touches no disk.
  * @param {string} [error]
@@ -98,6 +128,7 @@ function zeroedResult(error) {
       eligible: 0,
       proposed: 0,
       rejected: 0,
+      capped: 0,
       written: false,
     },
   };
@@ -186,33 +217,31 @@ function learningType(learning) {
 }
 
 /**
- * Build a sidecar ReconcileCandidate line-record (idempotency.mjs schema) for a
- * proposed or rejected learning. `created_at` is stamped from the injectable
- * clock so output stays deterministic under test.
+ * Surface a shape-guard drop on stderr. The sidecar is a mutable work-queue that
+ * `mergeCandidates` rewrites in FULL, so a record the read-side shape guard
+ * rejects is not merely ignored — it is gone from disk after this run. The count
+ * alone makes that loss attributable; this WARN is what makes it VISIBLE, since
+ * the summary field only helps a caller that thinks to read it.
+ *
+ * Never throws: a failing diagnostic must not break the never-throws contract of
+ * {@link runReconcile} (a broken stderr pipe would otherwise zero the result).
  *
- * @param {Object} params
- * @param {string} params.id
- * @param {string|null} params.learningKey
- * @param {string} params.slug
- * @param {'proposed'|'rejected'} params.status
- * @param {string} params.reason
- * @param {number} params.confidence
- * @param {string} params.createdAt - ISO timestamp.
- * @returns {import('./idempotency.mjs').ReconcileCandidate}
+ * @param {number} skipped - drop count (> 0 by the time this is called).
+ * @returns {void}
  */
-function buildCandidate({ id, learningKey, slug, status, reason, confidence, createdAt }) {
-  return {
-    id,
-    schema_version: 1,
-    learning_key: typeof learningKey === 'string' ? learningKey : '',
-    slug,
-    status,
-    reason,
-    confidence,
-    created_at: createdAt,
-    processed_at: null,
-    superseded_by: null,
-  };
+function warnDroppedStoreRecords(skipped) {
+  try {
+    console.warn(
+      `⚠️  reconcile: ${skipped} record(s) in ${DEFAULT_STORE_PATH} failed the ` +
+        `candidate shape guard and were DROPPED by this merge — the store is ` +
+        `rewritten in full, so they are no longer on disk. Expected shape: a ` +
+        `ReconcileCandidate with \`learning_key\` + \`created_at\` (see ` +
+        `scripts/lib/reconcile/idempotency.mjs). Only \`mergeCandidates\` may ` +
+        `write this store; hand-written or report records do not belong in it.`,
+    );
+  } catch {
+    // A diagnostic must never become the failure it reports on.
+  }
 }
 
 /**
@@ -236,6 +265,11 @@ function buildCandidate({ id, learningKey, slug, status, reason, confidence, cre
  *        eligibility placeholder-insight check (forwarded to `filterEligible`). Inert
  *        (no additional rejections) when omitted.
  * @param {number|Date} [params.now]      - injectable clock (emitter fallback + candidate `created_at`).
+ * @param {number} [params.maxProposalsPerRun] - volume brake (issue #900 D): after
+ *        sorting eligible learnings by confidence DESC, only the top N are proposed;
+ *        the rest are recorded as `capped` rejections. Defaults to
+ *        {@link DEFAULT_MAX_PROPOSALS_PER_RUN} (10) when omitted, non-finite, or < 1
+ *        — the brake is ALWAYS active, matching the Session Config default.
  * @param {boolean} [params.dryRun]       - when true, compute proposals but SKIP the merge entirely
  *        (also accepted as `opts.dryRun`; either location sets it).
  * @param {Object} [opts]                 - DI seams (all default to real behaviour).
@@ -249,7 +283,15 @@ function buildCandidate({ id, learningKey, slug, status, reason, confidence, cre
  * @returns {Promise<ReconcileResult>}
  */
 export async function runReconcile(
-  { repoRoot, ruleExpiryDays, minRuleDays, minInsightChars, now, dryRun: dryRunParam } = {},
+  {
+    repoRoot,
+    ruleExpiryDays,
+    minRuleDays,
+    minInsightChars,
+    now,
+    maxProposalsPerRun: maxProposalsPerRunParam,
+    dryRun: dryRunParam,
+  } = {},
   opts = {},
 ) {
   try {
@@ -258,6 +300,12 @@ export async function runReconcile(
     // (the documented DI seam) — either location flips it on.
     const dryRun = dryRunParam === true || opts.dryRun === true;
     const merge = typeof opts.merge === 'function' ? opts.merge : realMergeCandidates;
+    // Volume brake (#900 D) — always active; a missing/invalid override falls
+    // back to the same default the Session Config parser uses.
+    const maxProposalsPerRun =
+      Number.isFinite(maxProposalsPerRunParam) && maxProposalsPerRunParam >= 1
+        ? Math.floor(maxProposalsPerRunParam)
+        : DEFAULT_MAX_PROPOSALS_PER_RUN;
 
     // --- Pipeline step 1 — load learnings ----------------------------------
     /** @type {Array<Record<string, unknown>>} */
@@ -289,6 +337,21 @@ export async function runReconcile(
       minInsightChars,
     });
 
+    // --- Pipeline step 3b — volume brake (#900 D) ---------------------------
+    // Sort eligible learnings by confidence DESC (ties keep their original,
+    // stable relative order) and keep only the top `maxProposalsPerRun`. The
+    // rest are cut BEFORE they ever reach the emitter — never proposed this
+    // run — and recorded as `capped` rejections in step 4b below so a report
+    // stays honest about the cut instead of silently dropping them.
+    const confidenceOf = (l) =>
+      l && typeof l === 'object' && typeof l.confidence === 'number' ? l.confidence : 0;
+    const sortedEligible = eligible
+      .map((learning, index) => ({ learning, index }))
+      .sort((a, b) => confidenceOf(b.learning) - confidenceOf(a.learning) || a.index - b.index)
+      .map(({ learning }) => learning);
+    const keptEligible = sortedEligible.slice(0, maxProposalsPerRun);
+    const cappedEligible = sortedEligible.slice(maxProposalsPerRun);
+
     /** @type {ReconcileProposal[]} */
     const proposals = [];
     /** @type {ReconcileRejection[]} */
@@ -297,7 +360,7 @@ export async function runReconcile(
     const candidates = [];
 
     // --- Pipeline step 4 — per eligible learning (wrapped per-item) ---------
-    for (const learning of eligible) {
+    for (const learning of keptEligible) {
       try {
         const metadata = toActivationMetadata(learning, { ruleExpiryDays, now, minRuleDays });
         const { slug, path, content } = renderRule(learning, metadata);
@@ -352,6 +415,34 @@ export async function runReconcile(
       }
     }
 
+    // --- Pipeline step 4b — capped-eligible learnings (#900 D) --------------
+    // Learnings that passed eligibility but were cut by the volume brake are
+    // NEVER passed to the emitter — recorded directly as rejections (with a
+    // `capped — ...` reason) so a report distinguishes this from a genuine
+    // ineligibility rejection.
+    for (const learning of cappedEligible) {
+      const learningKey = rejectedLearningKey(learning);
+      const type = learningType(learning);
+      const reason = `capped — max-proposals-per-run (${maxProposalsPerRun}) reached; ${cappedEligible.length} lower-confidence eligible learning(s) not proposed this run`;
+      rejected.push({
+        learningKey,
+        type,
+        reason,
+        status: 'rejected',
+      });
+      candidates.push(
+        buildCandidate({
+          id: makeCandidateId(learningKey ?? '', `rejected-${type}`),
+          learningKey,
+          slug: '',
+          status: 'rejected',
+          reason,
+          confidence: confidenceOf(learning),
+          createdAt,
+        }),
+      );
+    }
+
     // --- Pipeline step 5 — per rejected learning (eligibility rejects) ------
     for (const { learning, reason } of rejectedLearnings) {
       const learningKey = rejectedLearningKey(learning);
@@ -382,28 +473,45 @@ export async function runReconcile(
     // The engine's ONLY disk write — and it is skipped entirely under dryRun.
     // It never writes `.claude/rules/` (FA3 / #696 owns that, post-approval).
     let written = false;
+    // `undefined` (NOT 0) until the merge actually inspects the store — absence
+    // means "not checked", 0 means "checked, nothing dropped". See the
+    // ReconcileSummary `skipped` typedef.
+    /** @type {number|undefined} */
+    let skipped;
     if (!dryRun) {
       try {
         const mergeResult = merge({ candidates, repoRoot });
         written = !!(mergeResult && mergeResult.written === true);
+        // Only a finite count from the seam counts as "inspected". A merge seam
+        // that reports nothing leaves `skipped` absent rather than fabricating 0.
+        if (mergeResult && Number.isFinite(mergeResult.skipped)) {
+          skipped = Number(mergeResult.skipped);
+        }
       } catch {
-        // Merge failure is non-fatal; proposals still returned, written stays false.
+        // Merge failure is non-fatal; proposals still returned, written stays
+        // false and `skipped` stays absent (the store was never inspected).
         written = false;
       }
     }
 
+    // Make an attributable drop VISIBLE, not merely recorded (WARN, never throw).
+    if (typeof skipped === 'number' && skipped > 0) warnDroppedStoreRecords(skipped);
+
     // --- Pipeline step 7 — summary -----------------------------------------
-    return {
-      proposals,
-      rejected,
-      summary: {
-        totalLearnings,
-        eligible: eligible.length,
-        proposed: proposals.length,
-        rejected: rejected.length,
-        written,
-      },
+    /** @type {ReconcileSummary} */
+    const summary = {
+      totalLearnings,
+      eligible: eligible.length,
+      proposed: proposals.length,
+      rejected: rejected.length,
+      capped: cappedEligible.length,
+      written,
     };
+    // Additive + absence-preserving: the key exists ONLY when the store was
+    // actually inspected, so no consumer can read a false `skipped: 0`.
+    if (typeof skipped === 'number') summary.skipped = skipped;
+
+    return { proposals, rejected, summary };
   } catch (err) {
     // never-throws top-level guard.
     const msg = err && err.message ? err.message : String(err);