ruvnet-brain 4.6.3 → 4.7.0

package/plugin/scripts/project-progression-session-start.mjs

@@ -1,320 +0,0 @@
-import fs from 'node:fs';
-import path from 'node:path';
-import os from 'node:os';
-import { spawnSync } from 'node:child_process';
-import { ProjectProgressionStore } from './project-progression-store.mjs';
-import { resolveProjectStore } from './project-store-resolver.mjs';
-import { withProgressionReader } from './project-progression-reader.mjs';
-import { drainCaptureQueue, queuedWork } from './session-snapshot-hook.mjs';
-import { replayTurnQueue } from './turn-outcome-capture.mjs';
-import { STAGE_BUDGETS_MS } from './session-start-budget.mjs';
-import { operatorProgressionSuspension } from './project-progression-suspension.mjs';
-
-const PROGRESSION_NAMESPACE = 'project-progression';
-
-export const SESSION_CONTINUITY_LIMIT_BYTES = 8 * 1024;
-// Keep the restore's enforced wall-clock ceiling identical to the SessionStart latency contract.
-// The fast path normally completes in milliseconds; when the managed CLI fallback cannot fit this
-// stage, the caller reports UNKNOWN with its reason instead of consuming the rest of the hook budget.
-export const SESSION_CONTINUITY_DEADLINE_MS = STAGE_BUDGETS_MS.restore;
-
-const RESTORED_HEADER = '[RuvNet Brain — PROJECT CONTINUITY RESTORED]';
-const UNKNOWN_HEADER = '[RuvNet Brain — PROJECT CONTINUITY UNKNOWN]';
-
-const UNKNOWN_EXPLANATIONS = Object.freeze({
-  'canonical-path': 'The canonical project AgentDB path could not be verified.',
-  'initialization-failed': 'The canonical project AgentDB could not be initialized through managed Ruflo.',
-  'managed-ruflo-unavailable': 'The managed global Ruflo CLI is unavailable.',
-  'pagination-unavailable': 'Structural AgentDB pagination is unavailable on the managed global Ruflo CLI.',
-  'malformed-store': 'Structural AgentDB output is malformed or internally inconsistent.',
-  'exact-readback': 'An exact-listed AgentDB row could not be read back by its exact key.',
-  'outbox-replay': 'The durable progression outbox could not be replayed safely.',
-  'output-bound': 'The full checkpoint and a goal/action-preserving bounded summary do not fit the host context; no checkpoint state was injected.',
-  'no-coherent-state': 'No coherent progression head survived validation.',
-  'restore-failed': 'The exact structural restore did not complete.',
-  'deadline-exceeded': 'The SessionStart restore deadline expired; no project restoration is claimed and durable work is retained.',
-  // MEASURED, and named rather than hidden. The in-process read path costs ~15ms for six snapshots;
-  // the `ruflo memory` CLI fallback costs 3634ms for the same six and does NOT fit the 2500ms
-  // restore deadline. Both produce an identical result, so this is a SPEED limit, not a correctness
-  // one — but a user whose store is encrypted, or whose Node lacks node:sqlite, will lose continuity
-  // past a handful of snapshots, and they deserve to be told which of the two it was.
-  'fallback-too-slow': 'The in-process read path was unavailable, and the managed Ruflo CLI fallback'
-    + ' could not finish inside the restore deadline.',
-});
-
-/**
- * UNKNOWN IS NOT NEUTRAL WHEN THERE WAS SOMETHING TO FIND.
- *
- * "I could not read your store" and "your store is empty" render almost identically to a reader, and
- * the first is a FAILURE: verified progression exists on disk and the session is about to proceed
- * without it. So when the canonical store exists and holds progression rows, the banner says so in
- * as many words and the result carries `severity: 'error'` for any surface that colours its output.
- * When we cannot even count the rows, the severity stays 'warning' — claiming a failure we cannot
- * evidence would be the same sin one step over.
- */
-function unknown(reason, { rowCount = null } = {}) {
-  const explanation = UNKNOWN_EXPLANATIONS[reason] ?? UNKNOWN_EXPLANATIONS['restore-failed'];
-  const failing = Number.isInteger(rowCount) && rowCount > 0;
-  const header = failing ? `${UNKNOWN_HEADER} — RESTORE FAILED` : UNKNOWN_HEADER;
-  const evidence = failing
-    ? ` ${rowCount} verified progression row(s) are present in the canonical store and could NOT be restored;`
-      + ' treat this as a failure to recover known state, not as a project without history.'
-    : '';
-  return {
-    status: 'unknown',
-    reason,
-    severity: failing ? 'error' : 'warning',
-    rowCount,
-    context: `${header}\n${explanation}${evidence}`
-      + ' Do not claim project state was restored; verify the canonical store before relying on remembered state.',
-  };
-}
-
-/**
- * Count committed progression rows WITHOUT paying for a restore. Used only to decide how loudly an
- * UNKNOWN should speak, so it never throws and never falls back to a CLI spawn: a count we cannot
- * take cheaply is reported as null ("cannot tell"), which downgrades the banner rather than the run.
- */
-function committedRowCount(canonicalAgentDbPath, options) {
-  try {
-    const result = withProgressionReader(canonicalAgentDbPath,
-      (reader) => reader.listKeys(PROGRESSION_NAMESPACE).length, options);
-    return result.ok ? result.value : null;
-  } catch { return null; }
-}
-
-function classify(error) {
-  const message = String(error?.message ?? error ?? '');
-  if (/deadline exceeded|deadline exhausted/i.test(message)) return 'deadline-exceeded';
-  if (/ruflo was not found|managed global ruflo/i.test(message)) return 'managed-ruflo-unavailable';
-  if (/canonical agentdb initialization failed/i.test(message)) return 'initialization-failed';
-  if (/structural pagination failed/i.test(message)
-    && /unknown option|page-info|--offset|unsupported/i.test(message)) return 'pagination-unavailable';
-  if (/malformed pagination|pagination total changed|non-advancing pagination|duplicate progression key/i.test(message)) {
-    return 'malformed-store';
-  }
-  if (/exact retrieval failed|exact key\/payload identity mismatch|readback is not json/i.test(message)) {
-    return 'exact-readback';
-  }
-  if (/outbox|replay/i.test(message)) return 'outbox-replay';
-  if (/resume payload.*bound/i.test(message)) return 'output-bound';
-  if (/no coherent progression state/i.test(message)) return 'no-coherent-state';
-  return 'restore-failed';
-}
-
-function validResume(result) {
-  if (!result || typeof result !== 'object' || typeof result.rendered !== 'string') return false;
-  let parsed;
-  try { parsed = JSON.parse(result.rendered); } catch { return false; }
-  return parsed?.schema === 'ruvnet-brain.project-resume'
-    && parsed.schemaVersion === 1
-    && Array.isArray(parsed.heads)
-    && parsed.heads.length > 0
-    && parsed.state && typeof parsed.state === 'object'
-    && Array.isArray(parsed.state.resumeConflicts)
-    && JSON.stringify(parsed) === JSON.stringify(result.payload);
-}
-
-function resultStatus(result) {
-  return Number.isInteger(result?.status) ? result.status : 1;
-}
-
-function resultText(result, field) {
-  const value = result?.[field];
-  return Buffer.isBuffer(value) ? value.toString('utf8') : String(value ?? '');
-}
-
-/**
- * One line, only when there is something to say. Durable-but-uncommitted snapshots are evidence the
- * session must know about: they will be committed at the next capture boundary, and until then the
- * restored head is not the newest thing that happened.
- */
-function pendingNotice(pendingReplay) {
-  if (!Number.isInteger(pendingReplay) || pendingReplay < 1) return '';
-  return `\n${pendingReplay} uncommitted snapshot(s) pending replay; they commit at the next capture`
-    + ' boundary (Stop / PreCompact / SessionEnd) or when you run /ruvnet-brain:checkpoint.';
-}
-
-function isProject(resolution) {
-  if (resolution.kind === 'git') return true;
-  return ['.swarm', '.claude-flow', 'package.json', 'pyproject.toml', 'Cargo.toml', 'go.mod']
-    .some((name) => fs.existsSync(path.join(resolution.projectRoot, name)));
-}
-
-/**
- * ADR-073 §6 — continuity-unavailable. A directory that is not a writable adopted project has no
- * continuity to restore and no store to blame, so this is neither a success nor a failure: it is the
- * absence of the question. Distinct from `unknown`, which means the question was asked and missed.
- */
-function unavailable(reason) {
-  return {
-    status: 'unavailable',
-    reason,
-    severity: 'info',
-    context: '[RuvNet Brain — PROJECT CONTINUITY UNAVAILABLE]\n'
-      + 'This working directory is not a writable adopted project. No AgentDB store was created and no project state was restored.',
-  };
-}
-
-/**
- * Restore one canonical project's progression at the shared SessionStart boundary.
- * Empty projects are silent. Any adopted-but-unverifiable store is explicit UNKNOWN.
- */
-export function restoreProgressionForSession({
-  env = process.env,
-  cwd = process.cwd(),
-  storeFactory,
-  maxOutputBytes = SESSION_CONTINUITY_LIMIT_BYTES,
-  deadlineMs = SESSION_CONTINUITY_DEADLINE_MS,
-  deadlineAt: inheritedDeadlineAt = Infinity,
-  signal,
-  writable = (projectRoot) => {
-    try { fs.accessSync(projectRoot, fs.constants.W_OK); return true; } catch { return false; }
-  },
-} = {}) {
-  const deadlineAt = Math.min(inheritedDeadlineAt, Date.now() + deadlineMs);
-  const checkDeadline = () => { if (signal?.aborted || Date.now() >= deadlineAt) throw new Error('restore deadline exceeded'); };
-  const boundedRunner = (binary, args, options) => {
-    checkDeadline();
-    const result = spawnSync(binary, args, { ...options,
-      timeout: Math.max(1, Math.floor(Math.min(options.timeout || Infinity, deadlineAt - Date.now()))), killSignal: 'SIGKILL' });
-    if (result.error) throw new Error('restore deadline exceeded');
-    checkDeadline(); return result;
-  };
-  const projectDir = env.CLAUDE_PROJECT_DIR || cwd;
-  try {
-    checkDeadline();
-    if (operatorProgressionSuspension(env)) {
-      // Turn recording is independent: suspension must not strand ordinary AgentDB capture.
-      const turns = replayTurnQueue({ projectDir, env, home: env.HOME || os.homedir(), synchronous: true,
-        deadlineMs: deadlineAt, runner: boundedRunner });
-      return { status: 'unavailable', reason: 'operator-suspended', severity: 'info', pendingTurns: turns.pending,
-        context: '[RuvNet Brain — PROJECT CONTINUITY UNAVAILABLE]\nAutomatic progression capture, replay and restore are operator-suspended. Evidence and queues are preserved. Ordinary AgentDB memory and explicit checkpoints remain available; no project progression was restored.' };
-    }
-  } catch (error) { return unknown(classify(error)); }
-  let resolution;
-  try {
-    resolution = resolveProjectStore({ projectDir, deadlineAt });
-    checkDeadline();
-  } catch (error) {
-    return unknown(/deadline|timed out/i.test(error.message) ? 'deadline-exceeded' : 'canonical-path');
-  }
-
-  if (!isProject(resolution)) return unavailable('non-project');
-  if (!writable(resolution.projectRoot)) return unavailable('read-only');
-  const initializing = !fs.existsSync(resolution.canonicalAgentDbPath);
-  const rowCount = initializing ? 0 : committedRowCount(resolution.canonicalAgentDbPath, { deadlineAt, signal });
-  const miss = (reason) => unknown(reason, { rowCount });
-
-  const prefix = `${RESTORED_HEADER}\n`;
-  // Reserve room for the status prefix, the bounded-summary explanation, and any pending-outbox
-  // notice appended after the payload. The final complete context is still checked below.
-  const payloadLimit = maxOutputBytes - Buffer.byteLength(prefix, 'utf8') - 400;
-  if (!Number.isSafeInteger(payloadLimit) || payloadLimit < 1) return miss('output-bound');
-
-  let store;
-  try {
-    checkDeadline();
-    const makeStore = storeFactory ?? ((options) => new ProjectProgressionStore({
-      ...options,
-      env,
-      runner: boundedRunner,
-    }));
-    store = makeStore({
-      projectDir,
-      requestedStorePath: resolution.canonicalAgentDbPath,
-      deadlineAt, signal,
-    });
-    const home = env.HOME || env.USERPROFILE || os.homedir();
-    const turns = replayTurnQueue({ projectDir, env, home, synchronous: true, runner: boundedRunner, deadlineMs: deadlineAt });
-    checkDeadline();
-    if (turns.pending > 0 || turns.failed > 0) {
-      const failed = miss('outbox-replay');
-      return { ...failed, pendingTurns: turns.pending,
-        context: `${failed.context} Durable turn recording remains pending; no older checkpoint was injected.` };
-    }
-    const suspended = ['persisted turn capture opt-out', 'turn capture policy unreadable or invalid'].includes(turns.skipped);
-    if (turns.skipped && !suspended && !['RUVNET_TURN_CAPTURE=off',
-      'no project memory db; persisted opt-in required'].includes(turns.skipped)) return miss('outbox-replay');
-    if (suspended && initializing) return {
-      status: 'unavailable', reason: 'capture-suspended', severity: 'info',
-      context: '[RuvNet Brain — PROJECT CONTINUITY UNAVAILABLE]\nCapture consent suspends replay; no canonical store was created.',
-    };
-    if (suspended && (store.pendingReplayCount?.() > 0 || queuedWork(resolution.projectRoot) > 0)) {
-      const failed = miss('outbox-replay');
-      return { ...failed, context: `${failed.context} Replay is suspended by capture consent; no older checkpoint was injected.` };
-    }
-    // ADR-105 rule 6: restoring a session never creates a store. A project's store is created only by the
-    // consent-gated native enrollment (project-memory-enrollment.mjs), never by SessionStart and never when
-    // consent is absent or RUVNET_TURN_CAPTURE=off.
-    if (initializing) return {
-      status: 'unavailable', reason: 'not-enrolled', severity: 'info',
-      context: '[RuvNet Brain — PROJECT CONTINUITY UNAVAILABLE]\nNo canonical project store exists yet; it is created by consent-gated native enrollment at the first captured boundary. Nothing to restore.',
-    };
-    if (!suspended) {
-      const queue = drainCaptureQueue({ projectDir, budgetMs: Math.max(0, deadlineAt - Date.now()),
-        deadlineAt, signal, env, makeStoreFactory: () => () => store });
-      checkDeadline();
-      if (queue.state !== 'settled') {
-        const failed = miss('outbox-replay');
-        return { ...failed, pendingReplay: queue.pending,
-          context: `${failed.context} Durable capture work remains pending; no older checkpoint was injected.` };
-      }
-    }
-    // A pending snapshot is newer observable work. Never label an older committed head restored
-    // while that work remains unverified. Replay uses the same managed exact-readback store path.
-    let restored;
-    try {
-      restored = store.restoreLatest({ maxOutputBytes: payloadLimit, replayPending: !suspended, projectToBound: true });
-      checkDeadline();
-    } catch (error) {
-      if (store.pendingReplayCount?.() > 0) {
-        const failed = miss('outbox-replay');
-        return { ...failed, pendingReplay: store.pendingReplayCount(),
-          context: `${failed.context} ${store.pendingReplayCount()} durable snapshot(s) remain pending; no older checkpoint was injected.` };
-      }
-      throw error;
-    }
-    if (!validResume(restored)) return miss('malformed-store');
-    const summaryNotice = restored.projected
-      ? '\n[BOUNDED CONTINUITY SUMMARY] The merged current goal and next action are preserved exactly; '
-        + 'a null value means the journal heads conflict. '
-        + 'Other omitted details remain in the canonical AgentDB records; consult the listed head keys '
-        + 'and omission digests. Omitted fields are marked and are not empty.'
-      : '';
-    const context = `${prefix}${summaryNotice}\n${restored.rendered}${pendingNotice(restored.pendingReplay)}`;
-    if (Buffer.byteLength(context, 'utf8') > maxOutputBytes) return miss('output-bound');
-    return {
-      status: restored.projected ? 'restored-summary' : 'restored',
-      severity: restored.projected ? 'warning' : 'info',
-      degraded: restored.projected === true,
-      pendingReplay: restored.pendingReplay,
-      context,
-    };
-  } catch (error) {
-    // A structurally enumerated, genuinely empty namespace is normal for a newly adopted project.
-    if (/no coherent progression state/i.test(String(error?.message ?? ''))
-      && Array.isArray(error?.rejectedCandidates) && error.rejectedCandidates.length === 0) {
-      if (initializing && !fs.existsSync(resolution.canonicalAgentDbPath)) return miss('initialization-failed');
-      const pending = pendingNotice(error?.pendingReplay);
-      return {
-        status: initializing ? 'initialized' : 'empty',
-        severity: 'info',
-        pendingReplay: error?.pendingReplay ?? 0,
-        context: (initializing
-          ? '[RuvNet Brain — PROJECT CONTINUITY INITIALIZED]\nThe canonical AgentDB store is ready; no prior progression snapshot exists yet.'
-          : '[RuvNet Brain — PROJECT CONTINUITY EMPTY]\nThe canonical AgentDB store was structurally enumerated and contains no prior progression snapshot.')
-          + pending,
-      };
-    }
-    // NAME WHICH PATH RAN OUT OF TIME. "restore-failed" over a store full of rows tells the user
-    // nothing they can act on; "the fast path was unavailable because <reason>, and the CLI fallback
-    // is too slow for this deadline" tells them exactly what to fix.
-    const readPath = typeof store?.lastReadPath === 'string' ? store.lastReadPath : '';
-    if (/deadline exceeded/i.test(String(error?.message ?? '')) && readPath.startsWith('ruflo-cli')) {
-      const missed = miss('fallback-too-slow');
-      return { ...missed, context: `${missed.context} Read path: ${readPath}.` };
-    }
-    return miss(classify(error));
-  }
-}

package/plugin/scripts/project-progression-sources.mjs

@@ -1,246 +0,0 @@
-/**
- * project-progression-sources.mjs — where a snapshot's facts actually come from.
- *
- * Every field a capture stores must be traceable to a REAL source: the git index, the user's own
- * work ledger, the owner's own `project-state-current` note, the previous snapshot head, or a
- * bounded transcript reference. Nothing here invents state, and nothing here copies the
- * conversation: the transcript contributes a REFERENCE (path + line/byte span + a sha256 of the
- * exact excerpt read) plus tightly-bounded DERIVED strings, never the prompt or the reply itself.
- *
- * Kept separate from the producer so each file stays small and so the readers can be tested against
- * real fixtures without constructing a whole snapshot.
- */
-import crypto from 'node:crypto';
-import fs from 'node:fs';
-import os from 'node:os';
-import path from 'node:path';
-import { execFileSync } from 'node:child_process';
-
-/** The transcript-derived bound. Deliberately far below the hook's 4096-byte observation limit. */
-export const DERIVED_TEXT_LIMIT = 240;
-/** How much of a transcript tail may be READ (never stored) to derive those bounded strings. */
-export const TRANSCRIPT_TAIL_BYTES = 256 * 1024;
-
-const sha256 = (value) => crypto.createHash('sha256').update(value).digest('hex');
-
-/** A stable digest for "there is genuinely nothing to digest here", never an empty string. */
-const ABSENT_DIGEST = sha256('ruvnet-brain:absent');
-
-function checkDeadline(deadlineAt, signal) {
-  if (signal?.aborted || Date.now() >= deadlineAt) throw new Error('restore deadline exceeded');
-}
-function git(cwd, args, deadlineAt = Infinity, signal) {
-  checkDeadline(deadlineAt, signal);
-  try {
-    return execFileSync('git', args, {
-      cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], maxBuffer: 64 * 1024 * 1024,
-      ...(Number.isFinite(deadlineAt) ? { timeout: Math.max(1, Math.floor(deadlineAt - Date.now())), killSignal: 'SIGKILL' } : {}),
-    });
-  } catch (error) {
-    checkDeadline(deadlineAt, signal);
-    if (error.code === 'ETIMEDOUT' && Number.isFinite(deadlineAt)) throw new Error('restore deadline exceeded');
-    return null;
-  }
-}
-
-/**
- * The Brain's OWN state that may sit inside the customer's project: the AgentDB store and its sidecars
- * (`.swarm/` — memory.db, -wal/-shm, the outbox and queue files) and what ruflo leaves in a cwd
- * (`.claude-flow/`, `ruvector.db`). It is not the customer's source. Every capture writes `.swarm/`, so
- * counting it made every later boundary look like a changed tree: the no-op path was never taken and
- * memory.db grew at every boundary. Excluded by pathspec, so it does not depend on the user's gitignore
- * (it only looked fine on machines whose global gitignore lists `.swarm/`).
- */
-export const BRAIN_STATE_PATHSPEC_EXCLUDES = Object.freeze([':(exclude).swarm', ':(exclude).claude-flow', ':(exclude)ruvector.db']);
-const SOURCE_PATHSPEC = ['--', '.', ...BRAIN_STATE_PATHSPEC_EXCLUDES];
-
-/**
- * The source identity, with each digest defined EXACTLY (each one EXCLUDING the Brain's own state,
- * BRAIN_STATE_PATHSPEC_EXCLUDES above):
- *   trackedDigest   sha256 of `git ls-files -s` (mode + blob oid + stage + path for every tracked file)
- *   untrackedDigest sha256 of one `<content-sha256> <path>` line per untracked, non-ignored file —
- *                   the NAMES alone would call two different working trees identical
- *   dirtyTreeDigest sha256 of `git diff HEAD` (staged AND unstaged, against the commit)
- *
- * KNOWN RACE, recorded rather than pretended away: the working tree can change while these three
- * commands run. HEAD is read before and after; when they differ, `headStable` is false and the
- * digests describe a tree that existed at no single instant. A capture still happens — a slightly
- * smeared snapshot is worth far more than no snapshot — but it never claims to be atomic.
- */
-export function readSourceIdentity({ checkoutRoot, kind = 'git', deadlineAt = Infinity, signal } = {}) {
-  checkDeadline(deadlineAt, signal);
-  const worktreeId = sha256(checkoutRoot);
-  if (kind !== 'git') {
-    // A non-git project has no index, no HEAD and no diff. Say that in the fields rather than
-    // fabricating hashes of nothing, and keep every value a non-empty string as the contract requires.
-    return {
-      identity: {
-        checkoutPath: checkoutRoot, worktreeId, branch: 'non-git', head: 'non-git',
-        trackedDigest: ABSENT_DIGEST, untrackedDigest: ABSENT_DIGEST, dirtyTreeDigest: ABSENT_DIGEST,
-      },
-      headStable: true,
-      kind,
-    };
-  }
-
-  const headBefore = git(checkoutRoot, ['rev-parse', 'HEAD'], deadlineAt, signal)?.trim() || 'unborn';
-  const branch = git(checkoutRoot, ['rev-parse', '--abbrev-ref', 'HEAD'], deadlineAt, signal)?.trim() || 'detached';
-  const tracked = git(checkoutRoot, ['ls-files', '-s', ...SOURCE_PATHSPEC], deadlineAt, signal);
-  const untrackedList = git(checkoutRoot, ['ls-files', '--others', '--exclude-standard', ...SOURCE_PATHSPEC], deadlineAt, signal);
-  const diff = git(checkoutRoot, ['diff', 'HEAD', ...SOURCE_PATHSPEC], deadlineAt, signal);
-  const headAfter = git(checkoutRoot, ['rev-parse', 'HEAD'], deadlineAt, signal)?.trim() || 'unborn';
-
-  const untrackedLines = String(untrackedList ?? '').split('\n').filter(Boolean).map((relative) => {
-    checkDeadline(deadlineAt, signal);
-    let content;
-    if (Number.isFinite(deadlineAt) && fs.statSync(path.join(checkoutRoot, relative)).size > 64 * 1024 * 1024) throw new Error('source identity file exceeds bounded read');
-    try { content = fs.readFileSync(path.join(checkoutRoot, relative)); } catch { return `unreadable ${relative}`; }
-    const digest = sha256(content); checkDeadline(deadlineAt, signal);
-    return `${digest} ${relative}`;
-  });
-  checkDeadline(deadlineAt, signal);
-
-  return {
-    identity: {
-      checkoutPath: checkoutRoot,
-      worktreeId,
-      branch,
-      head: headBefore,
-      trackedDigest: tracked === null ? ABSENT_DIGEST : sha256(tracked),
-      untrackedDigest: untrackedList === null ? ABSENT_DIGEST : sha256(untrackedLines.join('\n')),
-      dirtyTreeDigest: diff === null ? ABSENT_DIGEST : sha256(diff),
-    },
-    headStable: headBefore === headAfter,
-    headAfter,
-    kind,
-  };
-}
-
-/**
- * The user's own work ledger, read-only, resolved exactly as continuation-gate.mjs resolves it:
- * RUVNET_WORK_LEDGER, else ~/.config/ruvnet-brain/work-ledgers/<projectId with ':' → '-'>.json.
- * This is the AUTHORITATIVE source for open work, because the user put it there.
- */
-export function readWorkLedger({ projectId, env = process.env, home = os.homedir() } = {}) {
-  const file = env.RUVNET_WORK_LEDGER
-    || path.join(home, '.config', 'ruvnet-brain', 'work-ledgers', `${String(projectId).replace(':', '-')}.json`);
-  let parsed;
-  try { parsed = JSON.parse(fs.readFileSync(file, 'utf8')); } catch {
-    return { file, present: false, open: [], done: [], objective: null };
-  }
-  const items = Array.isArray(parsed?.items) ? parsed.items : [];
-  const text = (item) => (typeof item?.text === 'string' ? item.text : '');
-  return {
-    file,
-    present: true,
-    open: items.filter((item) => item && !item.done).map(text).filter(Boolean),
-    done: items.filter((item) => item?.done).map(text).filter(Boolean),
-    objective: parsed?.objective && typeof parsed.objective === 'object' ? parsed.objective : null,
-  };
-}
-
-/**
- * The owner's own convention: append-only `project-state-current-<epochms>[-slug]` free-text notes.
- * 378 of them exist in this repo's canonical store. They are narrative, not schema, so only the head
- * of the newest one is carried, as CONTEXT — never as an instruction and never as authority.
- */
-export function readOwnerNote(readRows, { limit = 600 } = {}) {
-  let rows;
-  try { rows = readRows(); } catch { return null; }
-  if (!Array.isArray(rows) || rows.length === 0) return null;
-  const newest = rows
-    .filter((row) => typeof row?.key === 'string' && row.key.startsWith('project-state-current'))
-    .sort((left, right) => String(left.key).localeCompare(String(right.key)))
-    .at(-1);
-  if (!newest || typeof newest.content !== 'string' || !newest.content.trim()) return null;
-  const excerpt = newest.content.slice(0, limit);
-  return {
-    key: newest.key,
-    namespace: newest.namespace ?? null,
-    excerpt,
-    truncated: newest.content.length > limit,
-    excerptSha256: sha256(excerpt),
-  };
-}
-
-function firstSentence(value) {
-  const collapsed = String(value).replace(/\s+/g, ' ').trim();
-  if (!collapsed) return '';
-  const stop = collapsed.search(/[.!?](\s|$)/);
-  const sentence = stop > 0 ? collapsed.slice(0, stop + 1) : collapsed;
-  return sentence.length <= DERIVED_TEXT_LIMIT ? sentence : `${sentence.slice(0, DERIVED_TEXT_LIMIT)}…`;
-}
-
-function claudeTranscriptRows(text) {
-  const rows = [];
-  const lines = text.split('\n');
-  // The first line of a mid-file tail is almost always a fragment; dropping it is correct, not lossy.
-  for (const line of lines.slice(1)) {
-    if (!line.trim()) continue;
-    try { rows.push(JSON.parse(line)); } catch { /* a partial line in a live-appended file */ }
-  }
-  return rows;
-}
-
-function textOf(message) {
-  if (typeof message?.content === 'string') return message.content;
-  if (!Array.isArray(message?.content)) return '';
-  return message.content.filter((block) => block?.type === 'text' && typeof block.text === 'string')
-    .map((block) => block.text).join('\n');
-}
-
-/**
- * A BOUNDED, NON-VERBATIM reading of the transcript tail.
- *
- * THE PRIVACY BOUNDARY, stated as a rule rather than a hope: the prompt and the assistant's reply
- * are READ here and are NEVER RETURNED. What comes back is a REFERENCE (path, line span, byte span,
- * and the sha256 of the exact bytes read, so an auditor can prove what was consulted) plus at most
- * two DERIVED single sentences, each capped at DERIVED_TEXT_LIMIT. Anything inferred this way is
- * marked non-authoritative by the producer; the ledger and the owner's note outrank it always.
- *
- * Unknown or unreadable formats return `skipped` with a reason. A host whose transcript we cannot
- * parse must cost the capture nothing at all.
- */
-export function readTranscriptReference(transcriptPath, { host = 'claude', tailBytes = TRANSCRIPT_TAIL_BYTES } = {}) {
-  if (typeof transcriptPath !== 'string' || !transcriptPath) {
-    return { skipped: 'no transcript path supplied' };
-  }
-  if (host !== 'claude') return { skipped: `transcript format unknown for host ${host}` };
-  let stat;
-  try { stat = fs.statSync(transcriptPath); } catch { return { skipped: 'transcript is unreadable' }; }
-  if (!stat.isFile() || stat.size === 0) return { skipped: 'transcript is empty or not a file' };
-  if (!/\.jsonl$/i.test(transcriptPath)) return { skipped: 'transcript is not a JSONL transcript' };
-
-  const byteOffset = Math.max(0, stat.size - tailBytes);
-  const byteLength = stat.size - byteOffset;
-  let buffer;
-  try {
-    const handle = fs.openSync(transcriptPath, 'r');
-    try {
-      buffer = Buffer.alloc(byteLength);
-      fs.readSync(handle, buffer, 0, byteLength, byteOffset);
-    } finally { fs.closeSync(handle); }
-  } catch { return { skipped: 'transcript tail could not be read' }; }
-
-  const rows = claudeTranscriptRows(buffer.toString('utf8'));
-  if (rows.length === 0) return { skipped: 'transcript tail contained no parseable records' };
-  const lastUser = [...rows].reverse()
-    .find((row) => row?.type === 'user' && row.message?.role === 'user' && textOf(row.message).trim());
-  const lastAssistant = [...rows].reverse()
-    .find((row) => row?.type === 'assistant' && textOf(row.message).trim());
-
-  return {
-    reference: {
-      path: transcriptPath,
-      byteOffset,
-      byteLength,
-      recordsRead: rows.length,
-      excerptSha256: sha256(buffer),
-      format: 'claude-jsonl',
-    },
-    // DERIVED ONLY. Callers must not treat these as the user's words; they are a bounded
-    // single-sentence reduction, recorded so an abandoned session still knows what it was doing.
-    derivedGoal: lastUser ? firstSentence(textOf(lastUser.message)) : '',
-    derivedNextAction: lastAssistant ? firstSentence(textOf(lastAssistant.message)) : '',
-  };
-}