session-orchestrator 3.16.0

package/scripts/lib/quality-gates-cache.mjs

@@ -0,0 +1,228 @@
+/**
+ * quality-gates-cache.mjs — Baseline quality-gate result cache (#258).
+ *
+ * Purpose:
+ *   Wave-executor Incremental quality checks run once per session but were
+ *   previously re-executed after every implementation wave, even when the
+ *   session's dependency tree and session-start ref hadn't changed. This
+ *   module persists the session-start Baseline result and lets wave-executor
+ *   skip Incremental when the cache is still valid and the working-tree
+ *   diff remains narrow.
+ *
+ * INVARIANT: Full Gate at session-end AND at the Quality wave is NEVER skipped
+ * regardless of cache state. shouldSkipIncremental({ waveRole: 'Quality' })
+ * hard-returns skip=false (reason 'quality-wave-full-gate-mandate') BEFORE any
+ * cache logic runs; the module otherwise only short-circuits Incremental in the
+ * Impl waves of wave-executor.
+ *
+ * Storage:
+ *   .orchestrator/metrics/baseline-results.jsonl  (append-only JSONL, one
+ *   record per session baseline run — consistent with sessions.jsonl,
+ *   events.jsonl, learnings.jsonl, audit.jsonl precedent).
+ *
+ * Record schema (version 1):
+ *   {
+ *     version: 1,
+ *     session_id: string,
+ *     session_start_ref: string,        // git sha captured at session-start
+ *     captured_at: string,              // ISO 8601 UTC
+ *     dependency_hash: string,          // sha256 of package.json + lockfile
+ *     results: {
+ *       typecheck: { status: 'pass'|'fail', error_count?: number },
+ *       test:      { status: 'pass'|'fail' },
+ *       lint:      { status: 'pass'|'fail' }
+ *     }
+ *   }
+ *
+ * Validity rules (see isCacheValid):
+ *   - session_start_ref matches current session
+ *   - dependency_hash matches current package.json + lockfile
+ *   - captured_at within TTL (default 7 days)
+ *   - all results.* statuses === 'pass'
+ *
+ * Skip rule (see shouldSkipIncremental):
+ *   cache valid AND changed-file-count < 50
+ *
+ * Fail-safe: every public function returns a structured result; none throw.
+ * On error, shouldSkipIncremental returns skip=false (Incremental runs),
+ * loadLatestBaselineResult returns null.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { digestMultiBufferSha256 } from './crypto-digest-utils.mjs';
+import { isIgnoredRootFile } from './package-manager.mjs';
+
+const CACHE_RELATIVE_PATH = '.orchestrator/metrics/baseline-results.jsonl';
+const DEFAULT_TTL_DAYS = 7;
+const DEFAULT_SCOPE_THRESHOLD = 50;
+const RECORD_VERSION = 1;
+
+/**
+ * Compute a sha256 hash over package.json plus the active lockfile.
+ * Missing lockfile → hash only package.json.
+ * Missing package.json → returns the sha256 of the empty string (stable null).
+ *
+ * @param {string} repoRoot Absolute path to repo root.
+ * @returns {string} Hex sha256 digest.
+ */
+export function computeDependencyHash(repoRoot) {
+  const buffers = [];
+  const pkgPath = path.join(repoRoot, 'package.json');
+  if (fs.existsSync(pkgPath)) {
+    buffers.push(fs.readFileSync(pkgPath));
+  }
+  // Prefer pnpm-lock.yaml (project standard), then package-lock.json, then yarn.lock.
+  // A gitignored root lockfile is skipped — a stray/local-only lockfile must
+  // not dominate the dependency hash (issue #715 bug class).
+  const lockCandidates = ['pnpm-lock.yaml', 'package-lock.json', 'yarn.lock'];
+  for (const candidate of lockCandidates) {
+    const candidatePath = path.join(repoRoot, candidate);
+    if (fs.existsSync(candidatePath) && !isIgnoredRootFile(repoRoot, candidate)) {
+      buffers.push(fs.readFileSync(candidatePath));
+      break;
+    }
+  }
+  return digestMultiBufferSha256(buffers);
+}
+
+/**
+ * Append one baseline-result record to the JSONL cache.
+ * Creates the metrics directory if missing. Atomic append via appendFileSync.
+ *
+ * @param {object} params
+ * @param {string} params.repoRoot
+ * @param {string} params.sessionId
+ * @param {string} params.sessionStartRef
+ * @param {object} params.results { typecheck, test, lint } — see module header.
+ */
+export function saveBaselineResult({ repoRoot, sessionId, sessionStartRef, results }) {
+  const cachePath = path.join(repoRoot, CACHE_RELATIVE_PATH);
+  const cacheDir = path.dirname(cachePath);
+  fs.mkdirSync(cacheDir, { recursive: true });
+  const record = {
+    version: RECORD_VERSION,
+    session_id: sessionId,
+    session_start_ref: sessionStartRef,
+    captured_at: new Date().toISOString(),
+    dependency_hash: computeDependencyHash(repoRoot),
+    results,
+  };
+  fs.appendFileSync(cachePath, JSON.stringify(record) + '\n');
+}
+
+/**
+ * Return the most recent record from the JSONL cache, or null if the file
+ * is missing, empty, or the last line is unparseable.
+ *
+ * Never throws.
+ *
+ * @param {object} params
+ * @param {string} params.repoRoot
+ * @returns {object|null}
+ */
+export function loadLatestBaselineResult({ repoRoot }) {
+  try {
+    const cachePath = path.join(repoRoot, CACHE_RELATIVE_PATH);
+    if (!fs.existsSync(cachePath)) return null;
+    const raw = fs.readFileSync(cachePath, 'utf8');
+    if (!raw.trim()) return null;
+    const lines = raw.split('\n').filter((line) => line.trim().length > 0);
+    if (lines.length === 0) return null;
+    const last = lines[lines.length - 1];
+    return JSON.parse(last);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Validate a cache record against current session context.
+ *
+ * @param {object} params
+ * @param {string} params.repoRoot
+ * @param {object|null} params.latestRecord
+ * @param {string} params.currentSessionStartRef
+ * @param {number} [params.ttlDays=7]
+ * @returns {{ valid: boolean, reason: string }}
+ */
+export function isCacheValid({ repoRoot, latestRecord, currentSessionStartRef, ttlDays = DEFAULT_TTL_DAYS }) {
+  if (!latestRecord) {
+    return { valid: false, reason: 'no-record' };
+  }
+  if (latestRecord.session_start_ref !== currentSessionStartRef) {
+    return { valid: false, reason: 'session-ref-mismatch' };
+  }
+  const currentDepHash = computeDependencyHash(repoRoot);
+  if (latestRecord.dependency_hash !== currentDepHash) {
+    return { valid: false, reason: 'dependency-changed' };
+  }
+  const capturedAt = Date.parse(latestRecord.captured_at);
+  if (Number.isNaN(capturedAt)) {
+    return { valid: false, reason: 'ttl-expired' };
+  }
+  const ageMs = Date.now() - capturedAt;
+  const ttlMs = ttlDays * 24 * 60 * 60 * 1000;
+  if (ageMs > ttlMs) {
+    return { valid: false, reason: 'ttl-expired' };
+  }
+  const r = latestRecord.results || {};
+  const statuses = [r.typecheck?.status, r.test?.status, r.lint?.status];
+  if (!statuses.every((s) => s === 'pass')) {
+    return { valid: false, reason: 'baseline-had-failures' };
+  }
+  return { valid: true, reason: 'cache-hit' };
+}
+
+/**
+ * High-level convenience used by wave-executor.
+ *
+ * Returns { skip, reason, changedFileCount }. Never throws — on any error
+ * (git failure, unreadable cache, etc.) returns skip=false so Incremental
+ * runs. Fail safe = run Incremental.
+ *
+ * @param {object} params
+ * @param {string} params.repoRoot
+ * @param {string} params.sessionStartRef
+ * @param {number} [params.scopeThreshold=50]
+ * @param {string|null} [params.waveRole=null] Role of the wave being gated.
+ *   When 'Quality' (case-insensitive, whitespace-trimmed — e.g. 'quality',
+ *   ' Quality ' all match), the function hard-returns skip=false BEFORE any
+ *   cache logic so the Quality-wave Full Gate is mechanically un-skippable
+ *   (#724 C6). All other values (null/undefined/Impl-*) preserve the cache
+ *   short-circuit path.
+ * @returns {{ skip: boolean, reason: string, changedFileCount: number }}
+ */
+export function shouldSkipIncremental({ repoRoot, sessionStartRef, scopeThreshold = DEFAULT_SCOPE_THRESHOLD, waveRole = null }) {
+  // C6 (#724): the Quality wave's Full Gate is NEVER skipped, regardless of a
+  // valid cache or a narrow diff. This mirrors the session-end close-safety
+  // invariant and makes the "After Quality: Full Gate" mandate mechanical
+  // rather than prose-only. Hard-return BEFORE any cache/git logic.
+  // Case-insensitive + trimmed match (#F-B) — a coordinator prose typo like
+  // 'quality' or 'Quality ' must not silently disable this invariant.
+  if (String(waveRole ?? '').trim().toLowerCase() === 'quality') {
+    return { skip: false, reason: 'quality-wave-full-gate-mandate', changedFileCount: -1 };
+  }
+  try {
+    const latestRecord = loadLatestBaselineResult({ repoRoot });
+    const validity = isCacheValid({ repoRoot, latestRecord, currentSessionStartRef: sessionStartRef });
+    if (!validity.valid) {
+      return { skip: false, reason: validity.reason, changedFileCount: -1 };
+    }
+    const diff = spawnSync('git', ['diff', '--name-only', `${sessionStartRef}..HEAD`], {
+      cwd: repoRoot,
+      encoding: 'utf8',
+    });
+    if (diff.status !== 0) {
+      return { skip: false, reason: 'git-diff-failed', changedFileCount: -1 };
+    }
+    const changedFileCount = diff.stdout.split('\n').filter((line) => line.trim().length > 0).length;
+    if (changedFileCount >= scopeThreshold) {
+      return { skip: false, reason: 'scope-too-large', changedFileCount };
+    }
+    return { skip: true, reason: 'cache-hit', changedFileCount };
+  } catch (err) {
+    return { skip: false, reason: `error:${err?.message ?? 'unknown'}`, changedFileCount: -1 };
+  }
+}

package/scripts/lib/quality-gates-policy.mjs

@@ -0,0 +1,95 @@
+/**
+ * Quality-gates policy loader.
+ *
+ * Reads .orchestrator/policy/quality-gates.json (issue #183).
+ * Consumed by scripts/run-quality-gate.mjs and the quality-gates skill.
+ *
+ * Policy-file-first: when a valid policy exists, its commands take precedence
+ * over the project-instruction file's Session Config (CLAUDE.md, or AGENTS.md
+ * on Codex CLI — see skills/_shared/instruction-file-resolution.md). Falls
+ * back to caller-provided defaults when the file is missing or malformed.
+ *
+ * Never throws.
+ */
+
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+const REQUIRED_KEYS = ['test', 'typecheck', 'lint'];
+
+/**
+ * Loads and shape-validates the quality-gates policy file.
+ *
+ * @param {string} repoRoot - repository root (where .orchestrator/ lives)
+ * @returns {object|null} parsed policy, or null if missing/invalid
+ */
+export function loadQualityGatesPolicy(repoRoot) {
+  const path = join(repoRoot, '.orchestrator/policy/quality-gates.json');
+  if (!existsSync(path)) return null;
+
+  let parsed;
+  try {
+    parsed = JSON.parse(readFileSync(path, 'utf8'));
+  } catch (err) {
+    process.stderr.write(`⚠ quality-gates policy: malformed JSON at ${path}: ${err.message}\n`);
+    return null;
+  }
+
+  if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    process.stderr.write(`⚠ quality-gates policy: root must be an object (${path})\n`);
+    return null;
+  }
+  if (parsed['version'] !== 1) {
+    process.stderr.write(`⚠ quality-gates policy: unsupported version ${JSON.stringify(parsed['version'])} (${path})\n`);
+    return null;
+  }
+  const commands = parsed['commands'];
+  if (commands === null || typeof commands !== 'object' || Array.isArray(commands)) {
+    process.stderr.write(`⚠ quality-gates policy: commands must be an object (${path})\n`);
+    return null;
+  }
+  for (const key of REQUIRED_KEYS) {
+    const entry = commands[key];
+    if (
+      entry === null ||
+      typeof entry !== 'object' ||
+      Array.isArray(entry) ||
+      typeof entry['command'] !== 'string' ||
+      entry['command'].trim() === ''
+    ) {
+      process.stderr.write(`⚠ quality-gates policy: commands.${key}.command must be a non-empty string (${path})\n`);
+      return null;
+    }
+  }
+  return parsed;
+}
+
+/**
+ * Resolves a command from policy or falls back to the caller's default.
+ *
+ * @param {object|null} policy - result of loadQualityGatesPolicy
+ * @param {"test"|"typecheck"|"lint"} key
+ * @param {string} fallback - fallback command when policy lacks the key
+ * @returns {string}
+ */
+export function resolveCommand(policy, key, fallback) {
+  if (policy && policy.commands && policy.commands[key] && typeof policy.commands[key].command === 'string') {
+    return policy.commands[key].command;
+  }
+  return fallback;
+}
+
+/**
+ * Maps a Session Config key (e.g. "test-command") from the project-instruction
+ * file (CLAUDE.md or AGENTS.md alias) to the policy-file key ("test"). Used by
+ * run-quality-gate.mjs.
+ *
+ * @param {string} configKey
+ * @returns {"test"|"typecheck"|"lint"|null}
+ */
+export function configKeyToPolicyKey(configKey) {
+  if (configKey === 'test-command') return 'test';
+  if (configKey === 'typecheck-command') return 'typecheck';
+  if (configKey === 'lint-command') return 'lint';
+  return null;
+}

package/scripts/lib/recommendations-v0.mjs

@@ -0,0 +1,156 @@
+/**
+ * v0 recommendation heuristic (issue #272, Epic #271 Phase A).
+ *
+ * Deterministic three-branch rule. Consumed by session-end Phase 3.7a Writer
+ * and (via STATE.md handoff) by session-start Phase 1.5 Reader.
+ */
+
+const VALID_MODES = new Set([
+  'housekeeping',
+  'feature',
+  'deep',
+  'discovery',
+  'evolve',
+  'plan-retro',
+]);
+
+/**
+ * Compute the v0 recommendation for the next session.
+ *
+ * Rules (evaluated in order, first match wins):
+ *   1. completion_rate <  0.50  → plan-retro
+ *   2. carryover_ratio ≥ 0.30   → deep
+ *   3. otherwise                → feature
+ *
+ * @param {object} input
+ * @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
+ *   the `priorities` field.
+ * @returns {{mode: string, priorities: number[], rationale: string}}
+ */
+export function computeV0Recommendation({
+  completionRate,
+  carryoverRatio,
+  carryoverIssues = [],
+}) {
+  if (typeof completionRate !== 'number' || Number.isNaN(completionRate)) {
+    throw new TypeError('completionRate must be a number');
+  }
+  if (typeof carryoverRatio !== 'number' || Number.isNaN(carryoverRatio)) {
+    throw new TypeError('carryoverRatio must be a number');
+  }
+
+  const priorities = Array.isArray(carryoverIssues)
+    ? carryoverIssues.slice(0, 5).map((x) => (typeof x === 'number' ? x : parseInt(String(x), 10)))
+    : [];
+
+  let mode;
+  let rationale;
+  if (completionRate < 0.5) {
+    mode = 'plan-retro';
+    rationale = 'v0: completion <50% → retro';
+  } else if (carryoverRatio >= 0.3) {
+    mode = 'deep';
+    rationale = 'v0: carryover ≥30% → deep';
+  } else {
+    mode = 'feature';
+    rationale = 'v0: default clean completion';
+  }
+
+  return { mode, priorities, rationale };
+}
+
+/**
+ * Validate that a recommendation's mode is one of the allowed values.
+ * Defensive for Reader-side parsing — unknown modes are rejected rather than
+ * silently propagated into Phase B's mode-selector.
+ */
+export function isValidMode(mode) {
+  return typeof mode === 'string' && VALID_MODES.has(mode);
+}
+
+// ---------------------------------------------------------------------------
+// Dispatcher precursor SUGGESTIONS (#678, PRD §2 P2.4 / line 56, §4 line 244)
+// ---------------------------------------------------------------------------
+
+/**
+ * Read-only precursor modes the dispatcher MENU may route to (`/discovery`,
+ * `/plan`). These are SUGGESTIONS only — never execution-wave modes. The
+ * non-execution guardrail lives in mode-selector.mjs (global-max swap excludes
+ * these from primary-mode promotion); this set is the source of truth for what
+ * the dispatcher is allowed to offer as a precursor.
+ * @type {ReadonlyArray<string>}
+ */
+export const PRECURSOR_MODES = Object.freeze(['discovery', 'plan-retro']);
+
+/**
+ * True when `mode` is a read-only precursor (discovery / plan-retro). Mirrors
+ * `isNonExecutionMode` in mode-selector/scoring.mjs but kept local so the
+ * dispatcher can import suggestion logic without pulling in the scoring graph.
+ * @param {unknown} mode
+ * @returns {boolean}
+ */
+export function isPrecursorMode(mode) {
+  return typeof mode === 'string' && PRECURSOR_MODES.includes(mode);
+}
+
+/**
+ * Suggest read-only precursor session-types for the dispatcher menu (#678).
+ *
+ * Pure, deterministic, additive. NEVER returns an execution mode — only the
+ * read-only precursors (`discovery` → /discovery, `plan-retro` → /plan). The
+ * dispatcher presents these as optional routes in its owner-confirmation AUQ;
+ * they are suggestions, not the executed primary `mode`.
+ *
+ * Heuristic (both independent — a session may justify both):
+ *   - `plan-retro` when there is real carry-forward to plan/retrospect:
+ *       completion_rate < 0.5  OR  carryover_ratio ≥ 0.3.
+ *   - `discovery` when context/understanding is thin and exploration helps:
+ *       no recent sessions (cold start)  OR  an explicit `discoveryHint`.
+ *
+ * @param {object|null|undefined} signals
+ * @param {number} [signals.completionRate]
+ * @param {number} [signals.carryoverRatio]
+ * @param {Array<unknown>} [signals.recentSessions]
+ * @param {boolean} [signals.discoveryHint] — explicit "explore first" hint.
+ * @returns {Array<{mode: string, route: string, rationale: string}>}
+ *   0–2 entries; deterministic order (plan-retro before discovery when both).
+ */
+export function suggestPrecursors(signals) {
+  if (signals === null || typeof signals !== 'object') {
+    return [];
+  }
+
+  const completionRate =
+    typeof signals.completionRate === 'number' && !Number.isNaN(signals.completionRate)
+      ? signals.completionRate
+      : null;
+  const carryoverRatio =
+    typeof signals.carryoverRatio === 'number' && !Number.isNaN(signals.carryoverRatio)
+      ? signals.carryoverRatio
+      : null;
+  const recentSessions = Array.isArray(signals.recentSessions) ? signals.recentSessions : [];
+
+  /** @type {Array<{mode: string, route: string, rationale: string}>} */
+  const suggestions = [];
+
+  if ((completionRate !== null && completionRate < 0.5) || (carryoverRatio !== null && carryoverRatio >= 0.3)) {
+    suggestions.push({
+      mode: 'plan-retro',
+      route: '/plan',
+      rationale: 'low completion / carryover → plan-retro precursor',
+    });
+  }
+
+  if (recentSessions.length === 0 || signals.discoveryHint === true) {
+    suggestions.push({
+      mode: 'discovery',
+      route: '/discovery',
+      rationale: 'cold start / explore-first hint → discovery precursor',
+    });
+  }
+
+  return suggestions;
+}

package/scripts/lib/reconcile/eligibility.mjs

@@ -0,0 +1,203 @@
+/**
+ * eligibility.mjs — Reconciliation-engine eligibility filter (Epic #693 FA2, issue #695).
+ *
+ * Decides which `learnings.jsonl` entries are eligible to be converted into a
+ * conditional `.claude/rules/*.md` rule. A learning is a plain in-memory JSON
+ * object; this module classifies and partitions such objects without any I/O.
+ *
+ * ── Safe posture (INVERTED allow-list) ───────────────────────────────────────
+ * The engine default-rejects. Only a learning whose `type` is in
+ * {@link CONVERT_TYPES} AND that carries a non-empty `file_paths[]` (the scope a
+ * conditional rule needs) is eligible. Everything else is rejected with a
+ * specific audit reason. This is the safe default the issue demands: a corpus
+ * of unknown types never silently produces a rule.
+ *
+ * ── The file-carrier key ─────────────────────────────────────────────────────
+ * The scope key we read is `file_paths` (an array of repo-relative paths).
+ * Provenance (corrected 2026-07-02, Epic #723 B2): the live corpus historically
+ * carried the scope under `files`, NOT `file_paths` — so this reader matched
+ * nothing (0/108 records had `file_paths`). Two fixes now converge on
+ * `file_paths` and keep this reader correct:
+ *   1. `scripts/backfill-learnings.mjs` normalized the on-disk corpus
+ *      `files` → `file_paths` (one-shot, 2026-07-02).
+ *   2. The schema SSOT (`learnings/schema.mjs` normalizeDialects) renames
+ *      `files` → `file_paths` on every read + migration going forward.
+ * We continue to read `file_paths` — it is now the canonical scope key. The
+ * engine's default JSONL loader also runs records through migrateLegacyLearning
+ * + normalizeLearning, so direct `runReconcile({ repoRoot })` calls see the same
+ * legacy alias + `files`→`file_paths` mapping as the backfill/read funnels.
+ *
+ * ── Type-name mapping (issue → real) ─────────────────────────────────────────
+ *   issue 'fragile-file'    -> real 'fragile-file'    (verbatim; 1 instance)
+ *   issue 'recurring-issue' -> real 'recurring-issue' (verbatim; 1 instance)
+ *   issue 'anti-pattern'    -> real 'anti-pattern'    (verbatim; 22 instances)
+ * Forward-compat spec names with 0 instances today are also included so a future
+ * renamed corpus still converts (they convert nothing now — harmless). See the
+ * CONVERT_TYPES doc for the full 2026-07-02 instance census.
+ *
+ * Pure functions — depends only on the pure `learnings/schema` type registry
+ * (a frozen constant; no I/O). Deterministic, no file I/O.
+ */
+
+import { LEARNING_TYPE_REGISTRY, LEARNING_TTL_DAYS, deriveExpiresAt } from '../learnings/schema.mjs';
+
+/**
+ * Recovery-stub / legacy-backfill placeholder insight signature (issue #741.2).
+ * Legacy-recovery records occasionally carry a stub insight instead of a real
+ * one (e.g. `"(legacy record — insight backfilled during 2026-07-02 recovery)"`).
+ * A placeholder insight would produce an EMPTY rule body downstream (the
+ * renderer has nothing meaningful to render) — reject it honestly at the
+ * eligibility gate instead of letting a hollow rule reach the proposal stage.
+ * @type {RegExp}
+ */
+const PLACEHOLDER_RE = /insight backfilled during .* recovery|^\(?legacy record\b/i;
+
+/**
+ * The learning `type` values that may become a conditional rule. DERIVED
+ * (Epic #723 I1, issue #733 Teil b) from `scripts/lib/learnings/schema.mjs`'s
+ * `LEARNING_TYPE_REGISTRY`: every type whose `ruleConvertible` flag is `true`.
+ *
+ * Instance census (corrected 2026-07-02, Epic #723 B2 — the earlier comment
+ * was a stale mis-count that inverted `fragile-file` and `fragile-pattern`),
+ * kept here as a historical record (the registry itself carries no counts):
+ *   - 'anti-pattern'         — 22 instances
+ *   - 'architecture-pattern' —  2 instances
+ *   - 'convention'           —  1 instance
+ *   - 'design-pattern'       —  1 instance
+ *   - 'fragile-file'         —  1 instance
+ *   - 'recurring-issue'      —  1 instance
+ *   - 'fragile-pattern'      —  0 instances (kept for forward-compat)
+ *   - 'stagnation-class-frequency' — 0 instances (kept for forward-compat)
+ *
+ * The membership is UNCHANGED from the prior hand-maintained literal — every
+ * listed type stays in the allow-list, so a future renamed/backfilled corpus
+ * still converts and 0-instance types convert nothing today.
+ *
+ * @type {Set<string>}
+ */
+export const CONVERT_TYPES = new Set(
+  Object.entries(LEARNING_TYPE_REGISTRY)
+    .filter(([, meta]) => meta.ruleConvertible)
+    .map(([type]) => type)
+);
+
+/**
+ * Classify a single learning record for rule-conversion eligibility.
+ *
+ * INVERTED allow-list: eligible only when the type is in CONVERT_TYPES AND a
+ * non-empty `file_paths[]` is present. The type gate is evaluated before the
+ * file gate, so an out-of-allow-list type is rejected as such even when it
+ * carries file paths.
+ *
+ * Two further gates run AFTER the type + file gates succeed (issue #741):
+ *   - placeholder-insight (#741.2, always-on): an empty or recovery-stub
+ *     insight would produce an empty rule body — rejected honestly rather
+ *     than proposed with hollow content. `minInsightChars` additionally
+ *     rejects an insight that is non-empty but too short to be useful; it is
+ *     opt-in (inert when omitted).
+ *   - already-expired-at-proposal (#741.1c, opt-in via `now`): a learning
+ *     whose natural TTL (`created_at` + per-type TTL) already elapsed before
+ *     proposal time is rejected honestly instead of silently floored back to
+ *     life. Inert when `now` is omitted, so existing single-arg callers are
+ *     unaffected.
+ *
+ * Defensive: a null / non-object record, or one missing `type`, is rejected
+ * (never throws).
+ *
+ * @param {unknown} learning - an in-memory learning object.
+ * @param {{ now?: number, minInsightChars?: number }} [opts] - now: injectable
+ *        clock (ms epoch) gating the expiry check; minInsightChars: opt-in
+ *        minimum insight length gating the placeholder check.
+ * @returns {{ eligible: boolean, reason: string }}
+ */
+export function classifyLearning(learning, { now, minInsightChars } = {}) {
+  if (
+    learning === null ||
+    typeof learning !== 'object' ||
+    Array.isArray(learning) ||
+    typeof learning.type !== 'string' ||
+    learning.type.length === 0
+  ) {
+    return { eligible: false, reason: 'invalid learning record (missing type)' };
+  }
+
+  const { type } = learning;
+
+  // Type gate beats file gate (safe posture: default-reject unknown types).
+  if (!CONVERT_TYPES.has(type)) {
+    return {
+      eligible: false,
+      reason: `type '${type}' not in convert allow-list — default-reject`,
+    };
+  }
+
+  const filePaths = learning.file_paths;
+  if (!Array.isArray(filePaths) || filePaths.length === 0) {
+    return {
+      eligible: false,
+      reason: `eligible type '${type}' but empty file_paths[] — cannot scope a conditional rule`,
+    };
+  }
+
+  // Placeholder-insight gate (#741.2, always-on) — empty or recovery-stub
+  // insight would produce an empty rule body downstream.
+  const insight = typeof learning.insight === 'string' ? learning.insight.trim() : '';
+  if (insight === '' || PLACEHOLDER_RE.test(insight)) {
+    return {
+      eligible: false,
+      reason: `placeholder-insight — insight is empty or a recovery placeholder ("${insight.slice(0, 40)}")`,
+    };
+  }
+  if (typeof minInsightChars === 'number' && minInsightChars > 0 && insight.length < minInsightChars) {
+    return {
+      eligible: false,
+      reason: `placeholder-insight — insight ${insight.length} chars < min-insight-chars ${minInsightChars}`,
+    };
+  }
+
+  // Already-expired-at-proposal gate (#741.1c, opt-in via `now`) — a learning
+  // whose natural TTL already elapsed before proposal time is rejected
+  // honestly rather than silently floored back to life at emit time.
+  if (typeof now === 'number' && Number.isFinite(now)) {
+    const naturalExpiryIso = deriveExpiresAt(learning.created_at, type);
+    const naturalExpiryMs = Date.parse(naturalExpiryIso);
+    if (Number.isFinite(naturalExpiryMs) && naturalExpiryMs < now) {
+      const ttlDays = LEARNING_TTL_DAYS[type] ?? LEARNING_TTL_DAYS.default;
+      return {
+        eligible: false,
+        reason: `already-expired-at-proposal — natural TTL (created_at + ${ttlDays}d) elapsed at ${naturalExpiryIso.slice(0, 10)} before proposal`,
+      };
+    }
+  }
+
+  return {
+    eligible: true,
+    reason: `eligible: ${type} with ${filePaths.length} file path(s)`,
+  };
+}
+
+/**
+ * Partition a list of learnings into eligible records and rejected records
+ * (each rejection carrying the specific audit reason).
+ *
+ * @param {unknown[]} learnings - list of in-memory learning objects.
+ * @param {{ now?: number, minInsightChars?: number }} [opts] - forwarded verbatim
+ *        to {@link classifyLearning} for every record.
+ * @returns {{ eligible: object[], rejected: Array<{ learning: object, reason: string }> }}
+ */
+export function filterEligible(learnings, opts = {}) {
+  const eligible = [];
+  const rejected = [];
+
+  const list = Array.isArray(learnings) ? learnings : [];
+  for (const learning of list) {
+    const { eligible: isEligible, reason } = classifyLearning(learning, opts);
+    if (isEligible) {
+      eligible.push(learning);
+    } else {
+      rejected.push({ learning, reason });
+    }
+  }
+
+  return { eligible, rejected };
+}