session-orchestrator 3.16.0

package/scripts/lib/sessions-staleness-banner.mjs

@@ -0,0 +1,247 @@
+/**
+ * sessions-staleness-banner.mjs — #724
+ *
+ * Deterministic session-start nudge for the "close-through" gap: sessions
+ * that end (agents stop, work happens) without ever writing a
+ * `.orchestrator/metrics/sessions.jsonl` ledger record. W1-D4 fleet finding:
+ * 141 `orchestrator.session.started` events vs. 39 sessions.jsonl records in
+ * this repo (~27% close-through rate) — the ledger silently under-counts
+ * completed sessions with no signal to the operator.
+ *
+ * Mirrors the contract used by the sibling Phase 4 banners
+ * (`scripts/lib/reconcile-nudge-banner.mjs`, `scripts/lib/vault-staleness-banner.mjs`,
+ * `scripts/lib/loop-readiness-banner.mjs`): a single `checkXxx({repoRoot})`
+ * entry point that is COMPLETELY try/catch-wrapped (never throws) and returns
+ * either `null` (silent no-op) or `{severity:'warn'|'alert', message, ...extra}`.
+ *
+ * Design — self-exclusion over time, NOT lock-presence (load-bearing
+ * correction; see issue #724 discussion): Phase 4 always runs INSIDE an
+ * active session — Phase 1.2 has already acquired `.orchestrator/session.lock`
+ * by the time this probe fires. Gating on "no live lock" would make the
+ * banner structurally silent forever. Instead:
+ *
+ *   - `lastLedgerAt`      = `completed_at` of the last PARSEABLE
+ *                           `sessions.jsonl` record (scanned from EOF
+ *                           backward, skipping malformed lines).
+ *   - `cutoff`            = the CURRENT session's `session.lock`
+ *                           `started_at` (via `readLock()`); when no lock is
+ *                           readable, `cutoff = now` (all events count).
+ *   - `lastForeignEventAt`= the NEWEST `events.jsonl` line whose `timestamp`
+ *                           is STRICTLY BEFORE `cutoff` — this structurally
+ *                           excludes the current session's own events without
+ *                           needing a `session_id` filter (most event lines
+ *                           don't carry one; see the mission-log sample in
+ *                           `.orchestrator/metrics/events.jsonl`).
+ *   - `deltaHours`        = (lastForeignEventAt − lastLedgerAt) / 1h, only
+ *                           meaningful when > 0 (foreign activity happened
+ *                           AFTER the last ledger entry).
+ *
+ * Severity: warn above `2 × DEFAULT_TTL_HOURS` (8h, imported from
+ * `session-lock.mjs` rather than duplicated), alert above 24h.
+ *
+ * Plain-JS — no Zod dependency. Never throws. Never mutates input. No
+ * `console.*` calls (repo ESLint `no-console` rule).
+ *
+ * Cross-references:
+ *  - `.claude/rules/verification-before-completion.md` — evidence-before-claims.
+ *  - `scripts/lib/session-lock.mjs` — `readLock()`, `DEFAULT_TTL_HOURS`.
+ *  - `scripts/lib/reconcile-nudge-banner.mjs` / `vault-staleness-banner.mjs` /
+ *    `loop-readiness-banner.mjs` — the banner-shape template.
+ *  - `scripts/backfill-abandoned-sessions.mjs` — the CLI this banner's
+ *    message recommends running (`--dry-run` is its default/safe mode).
+ *  - `scripts/lib/session-close-backfill.mjs` — the backfill engine
+ *    (`synthesizeRecord`) that produces the abandoned-session stubs seen in
+ *    `sessions.jsonl` (e.g. `_backfill_source: "events-jsonl"`).
+ *  - `skills/session-start/SKILL.md` Phase 4 — banner render site.
+ *  - Issue #724.
+ */
+
+import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+
+import { readLock, DEFAULT_TTL_HOURS } from './session-lock.mjs';
+
+/** Repo-relative path to the session ledger (one record per closed session). */
+const SESSIONS_PATH = '.orchestrator/metrics/sessions.jsonl';
+
+/** Repo-relative path to the generic telemetry stream (one line per event). */
+const EVENTS_PATH = '.orchestrator/metrics/events.jsonl';
+
+/** warn threshold: 2x the session-lock default TTL (8h) — imported, not duplicated. */
+export const WARN_THRESHOLD_HOURS = DEFAULT_TTL_HOURS * 2;
+
+/** alert threshold: a full day behind is a strong close-through signal. */
+export const ALERT_THRESHOLD_HOURS = 24;
+
+/**
+ * Read a JSONL file's non-empty lines. Returns `null` when the file is
+ * absent or unreadable, `[]` when it exists but has no non-empty lines.
+ * Never throws.
+ *
+ * @param {string} filePath
+ * @returns {string[]|null}
+ */
+function readJsonlLines(filePath) {
+  if (!existsSync(filePath)) return null;
+  let raw;
+  try {
+    raw = readFileSync(filePath, 'utf8');
+  } catch {
+    return null;
+  }
+  return raw.split('\n').filter((line) => line.length > 0);
+}
+
+/**
+ * Scan `sessions.jsonl` lines from EOF backward and return the `completed_at`
+ * of the last PARSEABLE record that carries a valid ISO timestamp. Malformed
+ * or non-conforming lines (bad JSON, missing/invalid `completed_at`) are
+ * skipped, not treated as fatal.
+ *
+ * @param {string[]} lines
+ * @returns {{iso: string, ms: number}|null}
+ */
+function lastLedgerEntry(lines) {
+  for (let i = lines.length - 1; i >= 0; i--) {
+    let record;
+    try {
+      record = JSON.parse(lines[i]);
+    } catch {
+      continue;
+    }
+    if (!record || typeof record !== 'object' || typeof record.completed_at !== 'string') continue;
+    const ms = Date.parse(record.completed_at);
+    if (!Number.isFinite(ms)) continue;
+    return { iso: record.completed_at, ms };
+  }
+  return null;
+}
+
+/**
+ * Scan ALL `events.jsonl` lines and return the newest one whose `timestamp`
+ * is strictly before `cutoffMs`. This is the self-exclusion mechanism: the
+ * current session's own events (all >= cutoff, since cutoff is this
+ * session's lock `started_at`) are structurally excluded without needing a
+ * `session_id` filter. Malformed lines and lines with a missing/invalid
+ * `timestamp` are skipped.
+ *
+ * @param {string[]} lines
+ * @param {number} cutoffMs
+ * @returns {{iso: string, ms: number}|null}
+ */
+function newestForeignEvent(lines, cutoffMs) {
+  let best = null;
+  for (const line of lines) {
+    let record;
+    try {
+      record = JSON.parse(line);
+    } catch {
+      continue;
+    }
+    if (!record || typeof record !== 'object' || typeof record.timestamp !== 'string') continue;
+    const ms = Date.parse(record.timestamp);
+    if (!Number.isFinite(ms)) continue;
+    if (ms >= cutoffMs) continue; // not "foreign" — belongs to (or postdates) the current session
+    if (best === null || ms > best.ms) best = { iso: record.timestamp, ms };
+  }
+  return best;
+}
+
+/**
+ * Resolve the cutoff instant (in epoch ms) that separates "the current
+ * session's own events" from "foreign/pre-session events". Prefers the
+ * current session's `session.lock` `started_at`; falls back to `now` when no
+ * lock is readable (or its `started_at` is unparseable) — in that fallback
+ * case every events.jsonl line counts as a candidate "foreign" event.
+ *
+ * Known limitation: the cutoff uses `lock.started_at` as recorded at lock
+ * acquisition time — a `forceAcquire()` takeover (stale-lock override) or
+ * cross-machine clock skew can shift this value away from the wall-clock
+ * instant the CURRENT process actually started, which can widen or narrow
+ * the "foreign" window by the skew amount. This banner is advisory-only
+ * tolerance (a nudge, never a gate), so an imprecise cutoff only affects when
+ * the warn/alert nudge fires, never blocks anything.
+ *
+ * @param {string} repoRoot
+ * @param {number} nowMs
+ * @returns {number}
+ */
+function resolveCutoffMs(repoRoot, nowMs) {
+  let lock;
+  try {
+    lock = readLock({ repoRoot });
+  } catch {
+    return nowMs;
+  }
+  if (!lock || typeof lock.started_at !== 'string') return nowMs;
+  const parsed = Date.parse(lock.started_at);
+  return Number.isFinite(parsed) ? parsed : nowMs;
+}
+
+/**
+ * Check sessions-ledger staleness and produce a session-start banner.
+ *
+ * Silent (`null`) when: `sessions.jsonl` is missing/empty/entirely
+ * unparseable, `events.jsonl` is missing/empty, no foreign (pre-cutoff)
+ * event exists, the foreign event is not after the last ledger entry, or the
+ * resulting gap is under the warn threshold. Never throws.
+ *
+ * @param {{repoRoot: string, now?: number}} opts
+ *   - `repoRoot`: REQUIRED absolute path to the repo root.
+ *   - `now`: optional injectable clock (epoch ms); defaults to `Date.now()`.
+ *     Used only as the cutoff fallback when no session.lock is readable.
+ * @returns {null | {
+ *   severity: 'warn'|'alert',
+ *   message: string,
+ *   lastLedgerAt: string,
+ *   lastForeignEventAt: string,
+ *   deltaHours: number,
+ * }}
+ */
+export function checkSessionsStaleness({ repoRoot, now = Date.now() } = {}) {
+  try {
+    if (!repoRoot || typeof repoRoot !== 'string') return null;
+
+    const nowMs = typeof now === 'number' && Number.isFinite(now) ? now : Date.now();
+
+    const sessionLines = readJsonlLines(path.join(repoRoot, SESSIONS_PATH));
+    if (sessionLines === null || sessionLines.length === 0) return null;
+
+    const ledger = lastLedgerEntry(sessionLines);
+    if (ledger === null) return null;
+
+    const eventLines = readJsonlLines(path.join(repoRoot, EVENTS_PATH));
+    if (eventLines === null || eventLines.length === 0) return null;
+
+    const cutoffMs = resolveCutoffMs(repoRoot, nowMs);
+
+    const foreign = newestForeignEvent(eventLines, cutoffMs);
+    if (foreign === null) return null;
+
+    const deltaMs = foreign.ms - ledger.ms;
+    if (deltaMs <= 0) return null; // foreign activity is not AFTER the last ledger entry
+
+    const deltaHours = Math.round((deltaMs / 3600000) * 10) / 10;
+    if (deltaHours <= WARN_THRESHOLD_HOURS) return null;
+
+    const severity = deltaHours > ALERT_THRESHOLD_HOURS ? 'alert' : 'warn';
+
+    const base =
+      `sessions-staleness: last sessions.jsonl entry ${ledger.iso} is ${deltaHours}h behind ` +
+      `pre-session events.jsonl activity ${foreign.iso} — possible close-through gap ` +
+      `(sessions ended without a ledger record; run node scripts/backfill-abandoned-sessions.mjs --dry-run)`;
+
+    const message = severity === 'alert' ? `🚨 ${base} — gap exceeds 24h.` : `⚠ ${base}.`;
+
+    return {
+      severity,
+      message,
+      lastLedgerAt: ledger.iso,
+      lastForeignEventAt: foreign.iso,
+      deltaHours,
+    };
+  } catch {
+    // Defensive catch-all — banner must never throw.
+    return null;
+  }
+}

package/scripts/lib/skill-evolution/blast-radius-classifier.mjs

@@ -0,0 +1,114 @@
+/**
+ * blast-radius-classifier.mjs — R5 blast-radius classifier for the C2
+ * auto-repair engine (Epic #643 Skill Self-Evolution Foundation / issue #647).
+ *
+ * The heart of the gate-per-artifact-type design: maps a repair target's path
+ * to a `{ targetType, gate, posture }` triple that the auto-repair engine uses
+ * to decide whether a change may be applied autonomously (behind a gate) or
+ * must always go through a merge request.
+ *
+ * SECURITY (R5 traversal safety): the classifier is PATH-TRAVERSAL-SAFE and
+ * FAIL-CLOSED. `targetPath` is never trusted lexically — it is resolved against
+ * a canonicalised `repoRoot` and any path that escapes the repo (or is
+ * otherwise ambiguous) is classified as `unknown` with the safest posture
+ * (`always-mr`). The ONLY input that yields `autonomous-gated` is the repo's
+ * own ROOT `CLAUDE.md` / `AGENTS.md`.
+ *
+ * No throwing: every code path returns a valid classification triple.
+ *
+ * Consumers:
+ *  - C2 auto-repair engine (issue #647) — decides apply-vs-MR per repair target.
+ */
+
+import path from 'node:path';
+import fs from 'node:fs';
+
+/**
+ * @typedef {'plugin-skill' | 'local-skill' | 'local-config' | 'unknown'} TargetType
+ * @typedef {'none' | 'config-validation'} Gate
+ * @typedef {'always-mr' | 'autonomous-gated'} Posture
+ * @typedef {{ targetType: TargetType, gate: Gate, posture: Posture }} Classification
+ */
+
+/**
+ * The fail-closed default: returned for any path that escapes the repo, is
+ * empty/ambiguous, or matches no known artifact type. Never silent-applies.
+ * @type {Classification}
+ */
+const FAIL_CLOSED = Object.freeze({
+  targetType: 'unknown',
+  gate: 'none',
+  posture: 'always-mr',
+});
+
+/**
+ * Classify a repair target's path into its blast-radius triple.
+ *
+ * The path is resolved against a canonicalised `repoRoot` before any
+ * classification rule is applied; paths that resolve outside the repo are
+ * fail-closed to `unknown` / `always-mr`. Path rules are applied first-match-wins
+ * against the repo-relative POSIX path:
+ *
+ *   1. `.claude/skills` (or under it) → local-skill   / none              / always-mr
+ *   2. `skills`         (or under it) → plugin-skill   / none              / always-mr
+ *   3. ROOT `CLAUDE.md` / `AGENTS.md` → local-config   / config-validation / autonomous-gated
+ *   4. anything else                  → unknown        / none              / always-mr (fail-closed)
+ *
+ * @param {string} targetPath — repair target path (relative or absolute); not trusted lexically.
+ * @param {{ repoRoot: string }} options — `repoRoot` is the repository root to resolve against.
+ * @returns {Classification} the blast-radius triple; never throws.
+ */
+export function classifyTarget(targetPath, { repoRoot } = {}) {
+  // Guard the inputs — fail-closed on anything we cannot work with.
+  if (typeof targetPath !== 'string' || typeof repoRoot !== 'string' || repoRoot.length === 0) {
+    return { ...FAIL_CLOSED };
+  }
+
+  // Canonicalise the repo root. realpathSync resolves symlinks so a symlinked
+  // repoRoot still anchors the escape check correctly. If it throws (e.g. the
+  // root does not exist yet), fall back to a lexical resolve.
+  let root;
+  try {
+    root = fs.realpathSync(path.resolve(repoRoot));
+  } catch {
+    root = path.resolve(repoRoot);
+  }
+
+  // Resolve the target against the canonical root, then compute the repo-relative
+  // path. We do NOT inspect `targetPath` lexically before this point.
+  const abs = path.resolve(root, targetPath);
+  let rel = path.relative(root, abs);
+
+  // ESCAPE CHECK (fail-closed): empty rel means the target IS the root itself;
+  // a `..` prefix or an absolute rel means the target escaped the repo. Either
+  // way → unknown / always-mr. Never throw.
+  if (rel === '' || rel.startsWith('..') || path.isAbsolute(rel)) {
+    return { ...FAIL_CLOSED };
+  }
+
+  // Normalize separators to POSIX so the rules below are platform-independent.
+  rel = rel.split(path.sep).join('/');
+
+  // Rule 1 — local (project) skills under `.claude/skills`.
+  if (rel === '.claude/skills' || rel.startsWith('.claude/skills/')) {
+    return { targetType: 'local-skill', gate: 'none', posture: 'always-mr' };
+  }
+
+  // Rule 2 — plugin skills under `skills`.
+  if (rel === 'skills' || rel.startsWith('skills/')) {
+    return { targetType: 'plugin-skill', gate: 'none', posture: 'always-mr' };
+  }
+
+  // Rule 3 — ROOT instruction files ONLY (no path separator in rel). A nested
+  // `subdir/CLAUDE.md` falls through to the fail-closed default below.
+  if (rel === 'CLAUDE.md' || rel === 'AGENTS.md') {
+    return {
+      targetType: 'local-config',
+      gate: 'config-validation',
+      posture: 'autonomous-gated',
+    };
+  }
+
+  // Rule 4 — fail-closed default for everything else.
+  return { ...FAIL_CLOSED };
+}

package/scripts/lib/skill-evolution/candidate-intake.mjs

@@ -0,0 +1,270 @@
+/**
+ * candidate-intake.mjs — Pure transform for the #647 C2 auto-repair engine.
+ *
+ * Ingests the two repair-candidate feeders and normalises them into a single
+ * `RepairCandidate[]` shape:
+ *   1. `/evolve` learnings (`.orchestrator/metrics/learnings.jsonl` records)
+ *   2. `claude-md-drift-check` output (`driftResult.errors[]`)
+ *
+ * This module is a PURE transform: it performs NO I/O. It never reads or writes
+ * any file. Persistence and the `processed_at` / `superseded_by` lifecycle are
+ * OWNED BY the sibling `idempotency.mjs` module — this module only emits the
+ * raw candidates with those fields nulled out.
+ *
+ * The `id` field is a deterministic short hash of (source, target_path,
+ * fingerprint), so the same input always yields the same id. That determinism
+ * is the idempotency key the sibling module relies on.
+ *
+ * Part of Epic #643 → issue #647 (C2 auto-repair engine).
+ */
+
+import { createHash } from 'node:crypto';
+
+/**
+ * @typedef {Object} RepairCandidate
+ * @property {string}      id              Deterministic short hash (idempotency key).
+ * @property {1}          schema_version  Schema version, always 1.
+ * @property {'evolve-learning'|'drift-check'} source  Originating feeder.
+ * @property {string}     source_ref      Back-reference into the source feeder.
+ * @property {string}     target_path     Repo-relative path the repair targets.
+ * @property {number}     evidence        Numeric confidence/strength of the signal.
+ * @property {'confidence'|'filesystem-fact'} evidence_kind  Interpretation of `evidence`.
+ * @property {string}     proposed_change Short human-readable description of the fix.
+ * @property {string}     rationale       Why this candidate exists.
+ * @property {string}     created_at      ISO timestamp when the candidate was minted.
+ * @property {null}       processed_at    Always null (idempotency.mjs sets this later).
+ * @property {null}       superseded_by   Always null (idempotency.mjs sets this later).
+ */
+
+/** Drift-check checks that map to error candidates → `proposed_change` template. */
+const DRIFT_PROPOSED_CHANGE = {
+  'path-resolver': () => 'Update/remove stale absolute path',
+  'project-count-sync': () => 'Sync project count',
+  'session-file-existence': () => 'Remove/repoint missing session-file ref',
+  'issue-reference-freshness': () =>
+    'Move/remove closed issue ref out of forward-looking section',
+  'session-config-parity': () => 'Add missing Session Config key',
+  'vault-dir-parity': () => 'Reconcile vault-dir between CLAUDE.md and AGENTS.md',
+};
+
+/** Path-extraction regex: repo-relative dir paths OR bare known-extension filenames. */
+const PATH_RE =
+  /(scripts|skills|hooks|tests|docs)\/[\w./-]+|\b[\w-]+\.(mjs|md|json|js|ts)\b/;
+
+/** Prescriptive-verb regex: the insight must propose an action, not merely describe. */
+const PRESCRIPTIVE_RE =
+  /\b(fix|change|switch|default|pin|port|remove|add|update|replace|disable|enable|require)\b/i;
+
+/** Drift-check statuses that mean "no candidates to emit". */
+const DRIFT_INERT_STATUSES = new Set(['skipped', 'skipped-mode-off', undefined]);
+
+/**
+ * Slugify a string for use inside the deterministic fingerprint. The exact form
+ * is internal (it only feeds the hash) — kebab-case, alnum-only, collapsed.
+ * @param {string} input
+ * @returns {string}
+ */
+function slug(input) {
+  return String(input ?? '')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+}
+
+/**
+ * Build the deterministic candidate id from its idempotency triple.
+ * @param {string} source
+ * @param {string} targetPath
+ * @param {string} fingerprint
+ * @returns {string}
+ */
+function makeId(source, targetPath, fingerprint) {
+  const hash = createHash('sha256')
+    .update(source + '\0' + targetPath + '\0' + fingerprint)
+    .digest('hex')
+    .slice(0, 8);
+  return `rc-${hash}`;
+}
+
+/**
+ * Extract the first repo-relative path from a candidate's text fields.
+ * @param {string} text
+ * @returns {string|null}
+ */
+function extractPath(text) {
+  const match = PATH_RE.exec(String(text ?? ''));
+  return match ? match[0] : null;
+}
+
+/**
+ * Map a single learning record to a RepairCandidate, or null when it fails any
+ * actionable filter. learnings.jsonl records are NOT uniform — only `confidence`
+ * and `created_at` are guaranteed — so id/subject/insight/evidence are handled
+ * defensively.
+ * @param {Record<string, unknown>} learning
+ * @param {number} evidenceFloor
+ * @param {string} nowIso
+ * @returns {RepairCandidate|null}
+ */
+function learningToCandidate(learning, evidenceFloor, nowIso) {
+  if (!learning || typeof learning !== 'object') return null;
+
+  // Filter 1: confidence gate.
+  const confidence = /** @type {unknown} */ (learning.confidence);
+  if (typeof confidence !== 'number' || !Number.isFinite(confidence)) return null;
+  if (confidence < evidenceFloor) return null;
+
+  // Filter 4: not expired (missing expires_at ⇒ live).
+  const expiresAt = learning.expires_at;
+  if (typeof expiresAt === 'string' && expiresAt.length > 0 && expiresAt < nowIso) {
+    return null;
+  }
+
+  const subject = typeof learning.subject === 'string' ? learning.subject : '';
+  const insight = typeof learning.insight === 'string' ? learning.insight : '';
+
+  // Filter 2: resolvable target path from subject OR insight.
+  const targetPath = extractPath(subject) ?? extractPath(insight);
+  if (!targetPath) return null;
+
+  // Filter 3: insight must be prescriptive.
+  if (!PRESCRIPTIVE_RE.test(insight)) return null;
+
+  const source = 'evolve-learning';
+  const sourceRef = typeof learning.id === 'string' && learning.id.length > 0
+    ? learning.id
+    : null;
+  const fingerprint = slug(targetPath + '-' + insight.slice(0, 80));
+
+  return {
+    id: makeId(source, targetPath, fingerprint),
+    schema_version: 1,
+    source,
+    source_ref: sourceRef,
+    target_path: targetPath,
+    evidence: confidence,
+    evidence_kind: 'confidence',
+    proposed_change: insight,
+    rationale: `evolve learning (confidence ${confidence}): ${insight}`,
+    created_at: nowIso,
+    processed_at: null,
+    superseded_by: null,
+  };
+}
+
+/**
+ * Map a single drift-check error to a RepairCandidate. Drift errors are
+ * filesystem facts (evidence 1.0). Unknown checks fall back to a generic
+ * proposed-change derived from the check name.
+ * @param {Record<string, unknown>} err
+ * @param {string} nowIso
+ * @returns {RepairCandidate|null}
+ */
+function driftErrorToCandidate(err, nowIso) {
+  if (!err || typeof err !== 'object') return null;
+
+  const check = typeof err.check === 'string' ? err.check : '';
+  const file = typeof err.file === 'string' ? err.file : '';
+  const line = err.line ?? '';
+  const message = typeof err.message === 'string' ? err.message : '';
+
+  // target_path is required — drift errors carry a repo-relative file already.
+  if (!file) return null;
+
+  const source = 'drift-check';
+  const sourceRef = `${check}:${file}:${line}`;
+
+  // Per-check proposed-change templates; command-count needs the actual count.
+  let proposedChange;
+  if (check === 'command-count') {
+    // Prefer the STRUCTURED bare claimed number (checker.mjs:495 exposes
+    // `command_count: { actual, claimed }` where `claimed` is `parseInt(m[1])`).
+    // `err.extracted` is the FULL regex match (e.g. "8 commands"); using it here
+    // produced the malformed double-word `'8 commands commands'` that the engine
+    // whitelist regex (engine.mjs COMMAND_COUNT_SHAPE) correctly rejects — making
+    // autonomous-apply dead code for this shape (#651 FIX 1).
+    const claimed =
+      (err.command_count && typeof err.command_count === 'object' && err.command_count !== null
+        ? /** @type {Record<string, unknown>} */ (err.command_count).claimed
+        : undefined) ?? err.extracted ?? '?';
+    const actual =
+      err.command_count && typeof err.command_count === 'object' && err.command_count !== null
+        ? /** @type {Record<string, unknown>} */ (err.command_count).actual ?? '?'
+        : '?';
+    proposedChange = `Update narrative '${claimed} commands' to actual ${actual}`;
+  } else if (Object.prototype.hasOwnProperty.call(DRIFT_PROPOSED_CHANGE, check)) {
+    proposedChange = DRIFT_PROPOSED_CHANGE[check]();
+  } else {
+    proposedChange = `Resolve drift-check '${check}'`;
+  }
+
+  const fingerprint = slug(file + '-' + message.slice(0, 80));
+
+  return {
+    id: makeId(source, file, fingerprint),
+    schema_version: 1,
+    source,
+    source_ref: sourceRef,
+    target_path: file,
+    evidence: 1.0,
+    evidence_kind: 'filesystem-fact',
+    proposed_change: proposedChange,
+    rationale: message,
+    created_at: nowIso,
+    processed_at: null,
+    superseded_by: null,
+  };
+}
+
+/**
+ * Ingest the two repair-candidate feeders and return a normalised
+ * `RepairCandidate[]`. Pure transform — performs no I/O.
+ *
+ * @param {Object} params
+ * @param {Array<Record<string, unknown>>} [params.learnings] - `/evolve` learning records.
+ * @param {{ status?: string, errors?: Array<Record<string, unknown>>, warnings?: unknown[] }|null} [params.driftResult]
+ *        claude-md-drift-check output. Only `errors[]` are mapped; `warnings[]`
+ *        are skipped. A null result, or a status of `skipped`/`skipped-mode-off`/
+ *        undefined, emits zero drift candidates.
+ * @param {string} [params.repoRoot] - repo root (accepted for caller symmetry; unused in the pure transform).
+ * @param {number} [params.evidenceFloor=0.5] - minimum learning confidence to qualify.
+ * @param {string} [params.now] - ISO timestamp for `created_at` + expiry checks (test determinism).
+ * @returns {RepairCandidate[]}
+ */
+export function extractCandidates({
+  learnings,
+  driftResult,
+  // eslint-disable-next-line no-unused-vars -- accepted for caller symmetry; pure transform does no path resolution
+  repoRoot,
+  evidenceFloor = 0.5,
+  now,
+} = {}) {
+  const nowIso = typeof now === 'string' && now.length > 0 ? now : new Date().toISOString();
+  const floor = Number.isFinite(evidenceFloor) ? evidenceFloor : 0.5;
+
+  /** @type {RepairCandidate[]} */
+  const candidates = [];
+
+  // Feeder 1: /evolve learnings.
+  if (Array.isArray(learnings)) {
+    for (const learning of learnings) {
+      const candidate = learningToCandidate(learning, floor, nowIso);
+      if (candidate) candidates.push(candidate);
+    }
+  }
+
+  // Feeder 2: drift-check errors (skip when inert).
+  if (
+    driftResult &&
+    typeof driftResult === 'object' &&
+    !DRIFT_INERT_STATUSES.has(driftResult.status) &&
+    Array.isArray(driftResult.errors)
+  ) {
+    for (const err of driftResult.errors) {
+      const candidate = driftErrorToCandidate(err, nowIso);
+      if (candidate) candidates.push(candidate);
+    }
+  }
+
+  return candidates;
+}