@orchestrator-claude/definitions 3.37.0 → 3.37.2

package/hooks/lib/capability-scanner.ts

@@ -9,8 +9,8 @@
  * All functions are fail-open: they return defaults on error, never throw.
  */
 
-import { readFileSync, readdirSync, existsSync, statSync, writeFileSync } from 'node:fs';
-import { join } from 'node:path';
+import { readFileSync, readdirSync, existsSync, statSync, writeFileSync, mkdirSync } from 'node:fs';
+import { join, dirname } from 'node:path';
 import { parse as parseYaml, stringify as stringifyYaml } from 'yaml';
 
 // ─── Types ───────────────────────────────────────────────
@@ -365,21 +365,64 @@ export function buildCapabilityIndex(opts: {
   };
 }
 
-// ─── Vault Persistence ───────────────────────────────────
+// ─── Cache Persistence (TD-235 half B, S445 VETOR 1) ─────
+//
+// The scan cache used to be written INTO `project-guidelines/.vault-config.yaml`
+// (`writeCapabilitiesToVault` / `readCapabilitiesFromVault`, removed in S445).
+// That file is git-TRACKED and hand-written above the `capabilities:` block
+// (governance lines 1-101, machine block from 102 — measured S445), so ordinary
+// operation dirtied version control: `needsRescan` compares
+// `~/.claude/plugins/installed_plugins.json`'s mtime, a trigger EXTERNAL to the
+// repo that changes even mid-session.
+//
+// It was not merely noisy. S426 commit 16c8e936 zeroed `plugins:` and deleted
+// 297 lines of that tracked file, invisibly, because the old writer parsed the
+// WHOLE document and re-serialized it — a parse hiccup or a partial scan
+// rewrote governance content as a side effect of a cache refresh.
+//
+// The cache is now a standalone file under the gitignored state dir. The
+// tracked vault config is read-only from here on (`readVaultSummary`), which
+// makes the S426 failure mode structurally impossible rather than merely
+// unlikely: no code path in this module writes to it.
+
+/** File name of the standalone cache inside the state directory. */
+const CAPABILITY_CACHE_FILENAME = 'capability-cache.yaml';
+
+type EnvLike = Record<string, string | undefined>;
 
 /**
- * Write CapabilityIndex to the `capabilities:` section of vault config YAML.
- * Performs surgical merge — only touches `capabilities:`, preserves all other sections.
- * Fails silently on error.
+ * Resolve where the capability cache lives.
+ *
+ * Precedence is deliberately IDENTICAL to every other state-dir consumer in
+ * the hook tree — `ORCHESTRATOR_STATE_DIR` wins outright, else
+ * `<projectRoot>/.orchestrator/.state` (see `lib/api-client.ts:51-55` and
+ * `subagent-start.ts:268-273`, both measured S445). `.orchestrator/.state/` is
+ * gitignored, so the cache is unversioned by construction.
+ *
+ * `env` is a parameter read at CALL time rather than a module-load `const`
+ * (the shape `api-client.ts` uses): this module is imported by test files that
+ * set the override per-case, and a module-load read would freeze the value
+ * before they run.
  */
-export function writeCapabilitiesToVault(vaultConfigPath: string, index: CapabilityIndex): void {
-  try {
-    let config: Record<string, unknown> = {};
-    if (existsSync(vaultConfigPath)) {
-      const raw = readFileSync(vaultConfigPath, 'utf-8');
-      config = (parseYaml(raw) as Record<string, unknown>) ?? {};
-    }
+export function resolveCapabilityCachePath(
+  projectRoot: string,
+  env: EnvLike = process.env
+): string {
+  const override = env.ORCHESTRATOR_STATE_DIR;
+  const stateDir =
+    override !== undefined && override !== ''
+      ? override
+      : join(projectRoot, '.orchestrator', '.state');
+  return join(stateDir, CAPABILITY_CACHE_FILENAME);
+}
 
+/**
+ * Write the CapabilityIndex to its own cache file, creating the state
+ * directory if needed. Never reads or writes any other file — in particular
+ * never the vault config. Fails silently (fail-open, module-wide posture).
+ */
+export function writeCapabilityCache(cachePath: string, index: CapabilityIndex): void {
+  try {
     const pluginEntries = index.plugins.map((p) => {
       const entry: Record<string, unknown> = { name: p.name };
       if (p.version !== 'unknown') entry.version = p.version;
@@ -391,7 +434,8 @@ export function writeCapabilitiesToVault(vaultConfigPath: string, index: Capabil
       return entry;
     });
 
-    config.capabilities = {
+    const payload = {
+      schema: 'capability-cache/v1',
       last_scanned: index.lastScanned,
       installed_plugins_mtime: index.installedPluginsMtime,
       plugins: pluginEntries,
@@ -399,27 +443,42 @@ export function writeCapabilitiesToVault(vaultConfigPath: string, index: Capabil
       gaps: index.gaps,
     };
 
-    writeFileSync(vaultConfigPath, stringifyYaml(config, { lineWidth: 120 }));
+    mkdirSync(dirname(cachePath), { recursive: true });
+    writeFileSync(cachePath, stringifyYaml(payload, { lineWidth: 120 }));
   } catch {
     // fail-open
   }
 }
 
 /**
- * Read cached CapabilityIndex from vault config's `capabilities:` section.
- * Returns null if section doesn't exist or on any error.
+ * Read the cached CapabilityIndex from its standalone cache file.
+ *
+ * Returns `null` when the cache is absent, unreadable or corrupt. That `null`
+ * is load-bearing: the caller (`buildMatrixLine` in session-start.ts — its
+ * post-compact.ts twin was retired in S454) treats it as "rescan", so a
+ * missing cache produces a FRESH
+ * scan — never an empty matrix that reads like a legitimate one. That
+ * hollow-but-plausible matrix is the original defect; it must not return
+ * through this door.
+ *
+ * `vaultConfigPath` is used READ-ONLY, for the vault summary (tier/stack/
+ * maturity/pack), which stays sourced from the tracked governance file rather
+ * than being frozen into the cache.
  */
-export function readCapabilitiesFromVault(vaultConfigPath: string): CapabilityIndex | null {
+export function readCapabilityCache(
+  cachePath: string,
+  vaultConfigPath: string
+): CapabilityIndex | null {
   try {
-    if (!existsSync(vaultConfigPath)) return null;
-    const raw = readFileSync(vaultConfigPath, 'utf-8');
-    const config = parseYaml(raw) as Record<string, unknown>;
-    const caps = config?.capabilities as Record<string, unknown> | undefined;
-    if (!caps) return null;
+    if (!existsSync(cachePath)) return null;
+    const raw = readFileSync(cachePath, 'utf-8');
+    const cache = parseYaml(raw) as Record<string, unknown> | null;
+    if (!cache || typeof cache !== 'object') return null;
+    if (cache.last_scanned === undefined && cache.plugins === undefined) return null;
 
     // Guard against malformed YAML where plugins is not an array (IMP-002)
-    const rawPlugins = Array.isArray(caps.plugins)
-      ? (caps.plugins as Record<string, unknown>[])
+    const rawPlugins = Array.isArray(cache.plugins)
+      ? (cache.plugins as Record<string, unknown>[])
       : [];
     const plugins: PluginCapability[] = rawPlugins.map((p) => ({
       name: (p.name as string) ?? '',
@@ -432,13 +491,13 @@ export function readCapabilitiesFromVault(vaultConfigPath: string): CapabilityIn
     }));
 
     return {
-      lastScanned: (caps.last_scanned as string) ?? '',
-      installedPluginsMtime: (caps.installed_plugins_mtime as string) ?? '',
+      lastScanned: (cache.last_scanned as string) ?? '',
+      installedPluginsMtime: (cache.installed_plugins_mtime as string) ?? '',
       plugins,
       agents: [], // agents are always scanned fresh (fast, <10ms)
       vault: readVaultSummary(vaultConfigPath),
-      routing: (caps.routing as Record<string, string>) ?? {},
-      gaps: (caps.gaps as string[]) ?? [],
+      routing: (cache.routing as Record<string, string>) ?? {},
+      gaps: (cache.gaps as string[]) ?? [],
     };
   } catch {
     return null;
@@ -501,29 +560,202 @@ export interface MemoryEntry {
 }
 
 /**
- * Format filtered memory entries as compact injection.
- * Returns empty string if no entries (skip injection).
+ * RF-010 Parte 2 (ADR-P4 v2): per-entry summary truncation cap, applied
+ * unconditionally to every `selected` entry — regardless of how long the
+ * source `summary` really is. The v1.0 plan assumed ~150 chars; the real
+ * fleet (measured S436 across all `.claude/agent-memory/*\/memory-index.yaml`
+ * indexes) has summaries up to ~3720 chars, median ~280-900 depending on
+ * agent, with `orchestrator`'s own index alone at p50=902/p90=1505. See
+ * implementation-report.md (TASK-009) for the full distribution and the
+ * explicit answer to "does 200 preserve signal or decapitate the memory".
+ *
+ * 200 → 300 (S436, TASK-010): gate decision among 280/300/311/200. 311 is
+ * the highest cap that still emits all 20 `filterRelevantMemories`-selected
+ * entries with zero AGGREGATE_CHAR_BUDGET drops against the real,
+ * currently-binding corpus (`orchestrator/memory-index.yaml`, 596 entries,
+ * the fleet's largest/most-consulted index) as of 2026-08-01 — verified via
+ * a byte-matched reimplementation, not the raw `20 * (cap + ~60 overhead) =
+ * 8000` arithmetic that first (wrongly) produced 340 and was found to drop
+ * 2/20 (see project_s436_cap340_orchestrator_index_overflow.md). 300 sits
+ * 11 chars below that boundary. Past 311 the aggregate budget starts
+ * dropping the tail, and — because dropped entries stop contributing chars
+ * at all — a still-higher cap delivers LESS total injected content, not
+ * more (measured: 311 → 20 entries/7924 chars; 312 → 19/1 dropped; 340 →
+ * 18 entries/7731 chars, 2 dropped).
+ *
+ * This is a real-corpus guarantee, not a guarantee for every conceivable
+ * input shape: `capability-scanner.test.ts` also documents two verified
+ * synthetic worst cases (the fleet-wide-longest filename applied uniformly
+ * across all 20 entries; orchestrator's own 20 longest-named entries) that
+ * already exceed 300 with a single drop each. 300 was accepted anyway
+ * because neither shape has ever been the real `filterRelevantMemories`
+ * output for any live index — see the regression test's own comment block
+ * for the exact boundaries (284 and 292 respectively) and margins.
+ */
+export const PER_ENTRY_SUMMARY_CHAR_CAP = 300;
+
+/**
+ * Aggregate output budget — defense-in-depth safety net UNDER the
+ * externally-verified 10.000-char `additionalContext` ceiling (three
+ * independent sources, S433/S434 Ressalva 1 — treated as verified, not
+ * re-checked here beyond the cheap `<=10000` assertion in the test suite).
+ * Even with the per-entry cap above, this still stops the line-building
+ * loop early if the running total approaches it (e.g. many entries, or
+ * unexpectedly wide multibyte/unicode expansion).
+ */
+const AGGREGATE_CHAR_BUDGET = 8000;
+
+/** Reserve headroom for the optional "+K truncadas..." header suffix so
+ * that appending it after the line-budget loop can never push the final
+ * output past AGGREGATE_CHAR_BUDGET. Generous relative to the suffix's
+ * actual worst-case length (~50 chars even at 4-digit K). */
+const SUFFIX_RESERVE = 64;
+
+/** Canonical type ordering for the per-type header — mirrors the
+ * feedback→project→reference→user priority `filterRelevantMemories` uses. */
+const MEMORY_TYPES = ['feedback', 'project', 'reference', 'user'] as const;
+
+function truncateSummary(summary: string, cap: number): string {
+  return summary.length > cap ? `${summary.slice(0, cap)}…` : summary;
+}
+
+/**
+ * TD-318 (S514): the ONE field formatMemoryContext dereferences per entry.
+ * `readMemoryIndex`'s guard requires only `file:` (S480 contract, pinned by
+ * memory-index-silent-failure.test.ts case 5), so an entry with `file:` and
+ * no `summary:` reaches here — and `truncateSummary(undefined)` threw,
+ * the caller's try/catch swallowed it, and the WHOLE block vanished:
+ * measured on trc-platform-mobile, 1 of 140 entries → 0 injected, no
+ * INDISPONÍVEL line (S480 guards the read, not the format). One bad line
+ * must not zero the good ones beside it.
  */
-export function formatMemoryContext(entries: MemoryEntry[]): string {
-  if (entries.length === 0) return '';
+function hasRenderableSummary(entry: MemoryEntry): boolean {
+  return typeof entry.summary === 'string';
+}
 
-  const byType: Record<string, number> = {};
-  for (const e of entries) {
-    byType[e.type] = (byType[e.type] ?? 0) + 1;
+/** Header line of the warning appended when entries were skipped (TD-318). */
+export const MEMORY_SKIPPED_WARNING_PREFIX = '- [AVISO] ';
+
+function countByType(list: MemoryEntry[]): Record<string, number> {
+  const counts: Record<string, number> = {};
+  for (const e of list) {
+    counts[e.type] = (counts[e.type] ?? 0) + 1;
   }
-  const typeSummary = Object.entries(byType)
-    .map(([t, n]) => `${n} ${t}`)
-    .join(', ');
+  return counts;
+}
 
-  const recentNames = entries
-    .slice(0, 5)
-    .map((e) => e.file.replace(/\.md$/, '').replace(/^(feedback|project|reference|user)_/, ''))
-    .join(', ');
+/**
+ * Format the composition-approved memory entries (`selected` — the output
+ * of `filterRelevantMemories`/TASK-008) as a compact `[MEMORY-CONTEXT]`
+ * injection, against the backdrop of the full unfiltered index
+ * (`allEntries`) used only to derive the per-type `M` denominators.
+ *
+ * Each entry's `summary` is truncated to `PER_ENTRY_SUMMARY_CHAR_CAP`
+ * (200) chars with an ellipsis. The whole output additionally respects
+ * `AGGREGATE_CHAR_BUDGET` (8000 chars): if that budget would be exceeded
+ * before every `selected` entry has been rendered, the loop stops and the
+ * header names how many were dropped this way
+ * (`; +K truncadas por orçamento de caracteres`) — distinguishing "the
+ * composition (TASK-008) approved N" from "N minus what the char budget
+ * still had to cut".
+ *
+ * Returns empty string if `selected` is empty (skip injection), even when
+ * `allEntries` is not — an empty composition means nothing relevant
+ * survived TASK-008's filter/quota, independent of the source index size.
+ */
+export function formatMemoryContext(selected: MemoryEntry[], allEntries: MemoryEntry[]): string {
+  // TD-318: split BEFORE anything dereferences `summary`. Skipped entries
+  // are named in a trailing warning line so the author sees what to fix —
+  // the previous behaviour was a swallowed throw and an empty block.
+  const renderable = selected.filter(hasRenderableSummary);
+  const skipped = selected.filter((e) => !hasRenderableSummary(e));
+  const warning =
+    skipped.length > 0
+      ? `${MEMORY_SKIPPED_WARNING_PREFIX}${String(skipped.length)} entrada(s) sem 'summary:' pulada(s) ` +
+        `— conserte o índice: ${skipped.map((e) => e.file).join(', ')}`
+      : '';
+
+  if (renderable.length === 0) return warning ? `[MEMORY-CONTEXT] 0 memórias\n${warning}` : '';
+
+  const selectedCounts = countByType(renderable);
+  const totalCounts = countByType(allEntries);
+  const perTypeSummary = MEMORY_TYPES.map(
+    (t) => `${t}: ${selectedCounts[t] ?? 0}/${totalCounts[t] ?? 0}`
+  ).join(', ');
+
+  const headerBase =
+    `[MEMORY-CONTEXT] ${renderable.length} de ${allEntries.length} memórias ` +
+    `(${perTypeSummary}); critério: cota mínima de 2 por tipo não-feedback + ` +
+    `prioridade feedback→recência no restante`;
+
+  const availableForLines =
+    AGGREGATE_CHAR_BUDGET - headerBase.length - SUFFIX_RESERVE - (warning ? warning.length + 1 : 0);
+  const lines: string[] = [];
+  let used = 0;
+  let droppedByBudget = 0;
+
+  for (let i = 0; i < renderable.length; i++) {
+    const entry = renderable[i]!;
+    const name = entry.file.replace(/\.md$/, '');
+    const truncated = truncateSummary(entry.summary, PER_ENTRY_SUMMARY_CHAR_CAP);
+    const line = `- [${entry.type}] ${name}: ${truncated}`;
+
+    if (used + line.length + 1 > availableForLines) {
+      droppedByBudget = renderable.length - i;
+      break;
+    }
+    lines.push(line);
+    used += line.length + 1;
+  }
 
-  return [
-    `[MEMORY-CONTEXT] ${entries.length} entries: ${typeSummary}`,
-    `recent: ${recentNames}`,
-  ].join('\n');
+  const header =
+    droppedByBudget > 0
+      ? `${headerBase}; +${droppedByBudget} truncadas por orçamento de caracteres`
+      : headerBase;
+
+  return [header, ...lines, warning].filter(Boolean).join('\n');
+}
+
+// ─── Memory Index Validation (TD-318) ────────────────────
+
+/** One defect found by `validateMemoryIndexEntries`. */
+export interface MemoryIndexDefect {
+  /** 0-based position in the index; the file name when the entry has one. */
+  position: number;
+  file: string | null;
+  /** Field names that are missing or of the wrong type. */
+  missing: string[];
+}
+
+/**
+ * Full-shape validator for a memory index, meant to FAIL LOUD in CI/lint
+ * (TD-318) — the read-side guard (`isWellFormedMemoryEntry`) is
+ * deliberately minimal (S480), so this is where an author learns that an
+ * entry is missing `summary:` BEFORE it reaches a session. Checks every
+ * field the injection path dereferences: `file`, `type`, `summary`,
+ * `last_accessed` (strings) and `tags` (array). Pure: takes the parsed
+ * entries (either on-disk form, already unwrapped), returns defects, never
+ * throws.
+ */
+export function validateMemoryIndexEntries(entries: unknown[]): MemoryIndexDefect[] {
+  const defects: MemoryIndexDefect[] = [];
+  entries.forEach((value, position) => {
+    if (typeof value !== 'object' || value === null) {
+      defects.push({ position, file: null, missing: ['(não é um objeto)'] });
+      return;
+    }
+    const e = value as Record<string, unknown>;
+    const missing: string[] = [];
+    for (const field of ['file', 'type', 'summary', 'last_accessed']) {
+      const v = e[field];
+      if (typeof v !== 'string' || v.length === 0) missing.push(field);
+    }
+    if (!Array.isArray(e.tags)) missing.push('tags');
+    if (missing.length > 0) {
+      defects.push({ position, file: typeof e.file === 'string' ? e.file : null, missing });
+    }
+  });
+  return defects;
 }
 
 // ─── Memory Index Reading ────────────────────────────────
@@ -533,17 +765,124 @@ interface MemoryIndex {
   entries: MemoryEntry[];
 }
 
+/**
+ * Type guard: is `value` a well-formed enough MemoryEntry to keep?
+ * Minimal bar (just `file`, a required string) — good enough to avoid
+ * downstream crashes in formatMemoryContext/filterRelevantMemories, without
+ * this module taking on full schema validation.
+ */
+function isWellFormedMemoryEntry(value: unknown): value is MemoryEntry {
+  return (
+    typeof value === 'object' && value !== null && typeof (value as MemoryEntry).file === 'string'
+  );
+}
+
 /**
  * Read memory-index.yaml and return parsed entries.
- * Returns null if file missing or corrupt (fail-open).
+ *
+ * Accepts TWO on-disk forms (TASK-026/RF-010 Parte 0):
+ *   1. Flat top-level array — `- file: ...` at the YAML root. This is the
+ *      CANONICAL form per CLAUDE.md's Memory Protocol and what 17/19 real
+ *      `.claude/agent-memory/*\/memory-index.yaml` indexes use.
+ *   2. Nested `entries:` array — kept for backward compatibility with the
+ *      2 real indexes still using it (`orchestrator`, `azure-devops-engineer`).
+ *
+ * `Array.isArray(parsed)` MUST be checked before touching `parsed.entries`:
+ * on a real Array, `.entries` resolves to `Array.prototype.entries` (a
+ * function), which is truthy and silently survives a naive
+ * `parsed?.entries ?? null` (or `?? parsed`) fallback — the historical bug
+ * this function fixes. Never reintroduce that shape.
+ *
+ * Malformed individual entries inside an otherwise-valid array (not an
+ * object, or missing the required `file` key) are SKIPPED rather than
+ * nulling the whole index — one bad `- ` line in one contributor's index
+ * should not blank out every valid entry that sits beside it.
+ *
+ * Returns null if the file is missing, the YAML is invalid, or the parsed
+ * shape is neither a flat array nor a dict with an `entries` array
+ * (fail-open).
  */
-export function readMemoryIndex(indexPath: string): MemoryEntry[] | null {
+export interface MemoryIndexDiagnostic {
+  /**
+   * Por que um índice QUE EXISTE não produziu entradas utilizáveis.
+   * Ausente = nada a relatar (arquivo inexistente, ou leitura bem-sucedida).
+   * NUNCA é preenchido quando o arquivo simplesmente não existe: ausência de
+   * memória é legítima e deve seguir silenciosa.
+   */
+  reason?: string;
+}
+
+export function readMemoryIndex(
+  indexPath: string,
+  diag?: MemoryIndexDiagnostic
+): MemoryEntry[] | null {
   try {
+    // Arquivo ausente = ausência LEGÍTIMA. Sem diagnóstico, sem ruído.
     if (!existsSync(indexPath)) return null;
     const raw = readFileSync(indexPath, 'utf-8');
-    const parsed = parseYaml(raw) as MemoryIndex;
-    return parsed?.entries ?? null;
-  } catch {
+
+    let parsed: unknown;
+    try {
+      parsed = parseYaml(raw);
+    } catch (err) {
+      // Ponto mudo nº 1 (S480): o catch externo engolia isto e devolvia null,
+      // então o `Memory context failed` do chamador NUNCA disparava — ele só
+      // vê exceção, e aqui nenhuma escapa. Um índice de 8 KB que quebrou por
+      // dois espaços de indentação ficava indistinguível de índice inexistente.
+      if (diag) diag.reason = `YAML inválido em ${indexPath}: ${String(err).split('\n')[0]}`;
+      return null;
+    }
+
+    let candidate: unknown[] | null = null;
+    if (Array.isArray(parsed)) {
+      candidate = parsed;
+    } else if (
+      typeof parsed === 'object' &&
+      parsed !== null &&
+      Array.isArray((parsed as MemoryIndex).entries)
+    ) {
+      candidate = (parsed as MemoryIndex).entries;
+    }
+    if (candidate === null) {
+      // Ponto mudo nº 2 (S480): forma não reconhecida devolvia null calado.
+      // Medido: o índice da Root usava a chave `memories:` e 25 memórias nunca
+      // foram lidas, nem uma vez. O diagnóstico NOMEIA AS CHAVES encontradas --
+      // é isso que diz ao autor o que corrigir. Aceitar `memories:` como
+      // terceira forma foi considerado e RECUSADO: cada apelido novo torna o
+      // contrato mais frouxo e convida a uma quarta chave. O leitor recusa alto;
+      // quem conserta é quem escreve.
+      const chaves =
+        typeof parsed === 'object' && parsed !== null && !Array.isArray(parsed)
+          ? Object.keys(parsed as Record<string, unknown>).join(', ')
+          : typeof parsed;
+      if (diag) {
+        diag.reason =
+          `formato não reconhecido em ${indexPath} — topo tem [${chaves}]; ` +
+          `esperado uma lista no topo ou a chave 'entries:'`;
+      }
+      return null;
+    }
+
+    const bemFormadas = candidate.filter(isWellFormedMemoryEntry);
+    // Ponto mudo nº 3 (S480): descartar entradas mal-formadas é o desenho certo
+    // (uma linha ruim não pode zerar as boas ao lado), mas descartar TODAS saía
+    // como lista vazia -- e lista vazia é truthy, então o `if (!memoryEntries)`
+    // do chamador não pegava e a linha sumia no filter(Boolean).
+    if (diag && candidate.length > 0) {
+      const descartadas = candidate.length - bemFormadas.length;
+      if (bemFormadas.length === 0) {
+        diag.reason =
+          `${candidate.length} entrada(s) lidas e NENHUMA bem-formada em ${indexPath} ` +
+          `— toda entrada precisa da chave 'file:'`;
+      } else if (descartadas > 0) {
+        diag.reason =
+          `${descartadas} de ${candidate.length} entrada(s) descartadas em ${indexPath} ` +
+          `(falta a chave 'file:')`;
+      }
+    }
+    return bemFormadas;
+  } catch (err) {
+    if (diag) diag.reason = `falha ao ler ${indexPath}: ${String(err).split('\n')[0]}`;
     return null;
   }
 }
@@ -552,6 +891,41 @@ export function readMemoryIndex(indexPath: string): MemoryEntry[] | null {
  * Filter memory entries by relevance for session injection.
  * Keeps: recent (14 days), all feedback, tag matches.
  * Returns max 20 entries, sorted by type priority then recency.
+ *
+ * QUOTA (HIGH-001, RF-010 Parte 1, S435): a flat `feedback`-first priority
+ * sort followed by a hard 20-entry cap made `project`/`reference`/`user`
+ * types MATHEMATICALLY unreachable whenever relevant `feedback` entries
+ * alone met or exceeded 20 — not because they were less relevant, but
+ * purely from cut-off arithmetic. Measured on the real fleet pre-fix:
+ * `orchestrator` (593 entries) selected 20/20 feedback, losing `project`,
+ * `user` and `reference` entirely; `implementer` (70) and
+ * `orchestrator-implementer` (30) each lost `project`.
+ *
+ * Fix: reserve up to `RESERVED_SLOTS_PER_TYPE` of the most-recent relevant
+ * entries for every non-`feedback` type that has at least one relevant
+ * entry (never forces in an irrelevant entry just to fill the quota — a
+ * type with 0 relevant entries gets 0 reserved slots, unchanged). The
+ * remaining budget is filled by walking the entries in the ORIGINAL
+ * priority order (feedback → project → reference → user, recency),
+ * skipping anything already reserved, exactly as before this fix — so an
+ * index small enough that nothing overflows the cap produces the identical
+ * selected set and order as the pre-fix implementation.
+ *
+ * TD-248 (S442): the fix above still computed the quota over `relevant` —
+ * i.e. AFTER the 14-day recency filter below had already run. A type whose
+ * every entry happened to be older than 14 days (and matched no
+ * contextTags) never entered `relevant` at all, so it never entered
+ * `nonFeedbackTypes` either, and got 0 reserved slots — the exact
+ * starvation the quota exists to prevent, just moved one step later
+ * (temporal starvation instead of feedback-volume starvation). Fixed by
+ * computing `reserved` over `entries` (the full, unfiltered index): every
+ * non-feedback type gets its `RESERVED_SLOTS_PER_TYPE` most-recent entries
+ * reserved regardless of age, and a reserved entry is admitted to the
+ * final selection even when `relevant` would have excluded it. MAX_TOTAL
+ * stays 20 — feedback cedes slots to the reservation, as before; the cap
+ * was not raised. contextTags plumbing is untouched (still unreachable at
+ * every production call site — see call-site note at the bottom of this
+ * function).
  */
 export function filterRelevantMemories(
   entries: MemoryEntry[],
@@ -559,6 +933,8 @@ export function filterRelevantMemories(
 ): MemoryEntry[] {
   const now = Date.now();
   const fourteenDays = 14 * 24 * 60 * 60 * 1000;
+  const MAX_TOTAL = 20;
+  const RESERVED_SLOTS_PER_TYPE = 2;
 
   const relevant = entries.filter((e) => {
     if (e.type === 'feedback') return true;
@@ -574,14 +950,45 @@ export function filterRelevantMemories(
     reference: 2,
     user: 3,
   };
-  relevant.sort((a, b) => {
+  const byPriorityThenRecency = (a: MemoryEntry, b: MemoryEntry): number => {
     const pa = typePriority[a.type] ?? 9;
     const pb = typePriority[b.type] ?? 9;
     if (pa !== pb) return pa - pb;
     return b.last_accessed.localeCompare(a.last_accessed);
-  });
+  };
+  relevant.sort(byPriorityThenRecency);
+
+  // Reserve the most-recent RESERVED_SLOTS_PER_TYPE entries for each
+  // non-feedback type present in the FULL index (TD-248), not just
+  // `relevant` — see the TD-248 doc-comment above for why. A reserved
+  // entry is admitted to the final selection even when it fails the
+  // `relevant` filter (older than 14 days, no contextTags match).
+  const reserved = new Set<MemoryEntry>();
+  const nonFeedbackTypes = new Set(entries.filter((e) => e.type !== 'feedback').map((e) => e.type));
+  for (const type of nonFeedbackTypes) {
+    const ofType = entries
+      .filter((e) => e.type === type)
+      .sort((a, b) => b.last_accessed.localeCompare(a.last_accessed));
+    for (const entry of ofType.slice(0, RESERVED_SLOTS_PER_TYPE)) {
+      reserved.add(entry);
+    }
+  }
+
+  const selected = new Set<MemoryEntry>(reserved);
+  for (const entry of relevant) {
+    if (selected.size >= MAX_TOTAL) break;
+    if (reserved.has(entry)) continue;
+    selected.add(entry);
+  }
 
-  return relevant.slice(0, 20);
+  // Final ordering: priority then recency. Reserved entries pulled in from
+  // OUTSIDE `relevant` (their type had zero entries inside the 14-day
+  // window) are not present in `relevant`, so `relevant.filter` can no
+  // longer be the source of the returned array (pre-TD-248 approach) —
+  // sort `selected` directly instead. For entries that WERE already in
+  // `relevant`, this produces the identical order as before (same
+  // comparator, stable sort).
+  return [...selected].sort(byPriorityThenRecency);
 }
 
 /**