@codedology/code-forge 0.7.7 → 0.9.0

package/src/cli/status.mjs

@@ -0,0 +1,212 @@
+/**
+ * `code-forge status [--run <id>] [--json]` (B64a, issue #13 item 6): a short status of a run, so
+ * the orchestrator checks progress with one command instead of reading logs or polling
+ * transcripts.
+ *
+ * Read-only: it reads the run record (`~/.code-forge/runs/<id>.json`, as `run status` does — no
+ * lock), the project's ledger rows and the workspace config (for `budget.usd`), and writes
+ * nothing — no ledger row, no file, no lock. The data comes from `briefStatus`
+ * (`src/state/brief-status.mjs`); this file finds the runs, counts open findings and renders.
+ *
+ * With `--run`, that run (ended or not). Without it, every run that is not ended whose workspace
+ * is the current repository (`projectRootFor(cwd)`, compared on realpaths), newest first (by
+ * `started_at`, then run id); with none, `no active run` (exit 0; `{"runs":[]}` with `--json`).
+ * An unknown `--run` exits 1; a usage error (unknown flag, a positional) exits 2.
+ *
+ * Text: at most {@link STATUS_MAX_LINES} lines per run, runs separated by one blank line:
+ *   run <id> · <status> · <plan|brief> · spent $<x>[ of $<budget>]
+ *   <id> <state> <level> · <model or -> · gate <pass|fail|none>[ (<gate>)] · findings <n>
+ *   … +<k> more blocks                  (only when the open blocks do not fit)
+ *   closed <a> · stopped <b>            (only when any exist; printed last, but block lines are
+ *                                        dropped first to keep it inside the cap)
+ * The gate field is `gate pass`, `gate fail (<gate>)`, `gate fail` (no gate named) or `gate none`.
+ * `<x>` is `run status`'s spent_usd with 2 decimals, followed by `+?` when some session has no
+ * known price (`run status`'s unknown_usd_sessions > 0); the whole amount is `$?` when the ledger
+ * cannot be read. A run record with no status shows `-`.
+ *
+ * `--json`: exactly one line, `{"runs":[{run_id, status, mode, spent_usd, unknown_usd_sessions,
+ * budget_usd, blocks, more, closed, stopped}]}` — every block that is neither closed nor stopped
+ * (no cap), `more` always 0, `spent_usd` and `unknown_usd_sessions` null when the ledger cannot be
+ * read, `status` null when the record has none.
+ *
+ * The run lock (`<runs>/<id>.lock`, taken by the worker and the block verbs) is never taken nor
+ * waited on: a held lock does not delay `status`.
+ *
+ * Findings: the number of distinct (file, finding) pairs the block gate would refuse today
+ * (`checkBlockReviews`, `src/review/gate-check.mjs` — the same rules `block close` applies: the
+ * latest review of each file left it open and no valid waiver, ruling or later approval cleared
+ * it). The files are the ones the block's review rows name (`reviewedFiles`, the selection
+ * `block close` uses for reviewed files), each at the content hash of its LAST review row (only
+ * review rows — the events `reviewedFiles` counts — supply a hash; other rows never do). A file
+ * whose review rows carry no hash is checked at the empty hash: the gate counts a refusal row
+ * with no `content_hash` for every hash of its file (fail closed), so its open findings count.
+ * The gate's other refusals (unreviewed, unsigned, proof, rule breaks) are not findings and are
+ * not counted. No transcript, diff or review text is ever read or printed.
+ *
+ * The run key is only read (`loadKey`: a stat and a read, never a create or a write); with no
+ * key, a zero key stands in, so no signed waiver or approval verifies (fail closed).
+ */
+
+import { readdir, realpath } from 'node:fs/promises';
+import path from 'node:path';
+import { loadProjectConfig, projectRootFor } from '../config/load.mjs';
+import { budgetUsdOf } from '../ledger/spend.mjs';
+import { readAllRows } from '../ledger/write.mjs';
+import { findingsKey, openFindingsOf } from '../review/open-findings.mjs';
+import { briefStatus } from '../state/brief-status.mjs';
+import { parseFlags } from '../state/cli-args.mjs';
+import { runsDir, StateError } from '../state/paths.mjs';
+import { readRun } from '../state/run.mjs';
+import { writeSafe } from '../util/redact.mjs';
+
+const USAGE = 'usage: code-forge status [--run <id>] [--json]\n';
+
+/** The hard cap on text lines per run. */
+const STATUS_MAX_LINES = 10;
+
+/**
+ * @typedef {import('../state/brief-status.mjs').RunStatus} RunStatus
+ */
+
+/** @param {string} p @returns {Promise<string>} */
+async function realOr(p) {
+  try {
+    return await realpath(p);
+  } catch {
+    return path.resolve(p);
+  }
+}
+
+/**
+ * The status data of one run.
+ * @param {Record<string, any>} record
+ * @returns {Promise<RunStatus>}
+ */
+async function statusOf(record) {
+  /** @type {Array<Record<string, any>> | null} null: the ledger cannot be read */
+  let rows = null;
+  try {
+    rows = await readAllRows(record.project);
+  } catch {
+    rows = null;
+  }
+  let budget = null;
+  try {
+    const loaded = await loadProjectConfig(record.workspace);
+    budget = loaded.ok ? budgetUsdOf(loaded.config) : null;
+  } catch {
+    budget = null;
+  }
+  const key = await findingsKey(record);
+  const runId = String(record.run_id);
+  const all = rows ?? [];
+  /** @type {Map<string, Array<Record<string, any>>>} the run's rows, grouped by block once */
+  const byBlock = new Map();
+  for (const r of all) {
+    if (r?.run !== runId || typeof r.block !== 'string') continue;
+    const list = byBlock.get(r.block);
+    if (list) list.push(r);
+    else byBlock.set(r.block, [r]);
+  }
+  return briefStatus({ record, rows, budget, findingsOf: (block) => openFindingsOf({ block, runId, mine: byBlock.get(block) ?? [], rows: all, key }) });
+}
+
+/**
+ * Every run that is not ended whose workspace is `root`, newest first.
+ * @param {string} root
+ * @returns {Promise<Array<Record<string, any>>>}
+ */
+async function activeRunsFor(root) {
+  const want = await realOr(root);
+  let names;
+  try {
+    names = await readdir(runsDir());
+  } catch {
+    return [];
+  }
+  const records = [];
+  for (const name of names) {
+    if (!name.endsWith('.json')) continue;
+    let record;
+    try {
+      record = await readRun(name.slice(0, -'.json'.length));
+    } catch {
+      continue; // not a run record (a bad id, unparsable): not a run to show
+    }
+    if (!record || typeof record !== 'object' || record.status === 'ended' || typeof record.workspace !== 'string') continue;
+    if ((await realOr(record.workspace)) !== want) continue;
+    records.push(record);
+  }
+  const at = (/** @type {Record<string, any>} */ r) => (typeof r.started_at === 'string' ? r.started_at : '');
+  return records.sort((a, b) => at(b).localeCompare(at(a)) || String(b.run_id).localeCompare(String(a.run_id)));
+}
+
+/** @param {number} n @returns {string} */
+const usd = (n) => `$${n.toFixed(2)}`;
+
+/**
+ * The text lines of one run, at most {@link STATUS_MAX_LINES}.
+ * @param {RunStatus} s @returns {string[]}
+ */
+export function runLines(s) {
+  const spent = s.spent_usd === null ? '$?' : `${usd(s.spent_usd)}${(s.unknown_usd_sessions ?? 0) > 0 ? '+?' : ''}`;
+  const lines = [`run ${s.run_id} · ${s.status ?? '-'} · ${s.mode} · spent ${spent}${s.budget_usd !== null ? ` of ${usd(s.budget_usd)}` : ''}`];
+  const tally = s.closed + s.stopped > 0 ? `closed ${s.closed} · stopped ${s.stopped}` : null;
+  const room = STATUS_MAX_LINES - 1 - (tally === null ? 0 : 1);
+  const shown = s.blocks.length <= room ? s.blocks : s.blocks.slice(0, room - 1);
+  for (const b of shown) {
+    lines.push(`${b.id} ${b.state} ${b.level ?? '-'} · ${b.model ?? '-'} · gate ${b.gate.result}${b.gate.name ? ` (${b.gate.name})` : ''} · findings ${b.findings}`);
+  }
+  if (shown.length < s.blocks.length) lines.push(`… +${s.blocks.length - shown.length} more blocks`);
+  if (tally !== null) lines.push(tally);
+  return lines;
+}
+
+/**
+ * @param {string[]} args
+ * @returns {Promise<number>}
+ */
+export default async function status(args) {
+  const out = (/** @type {string} */ s) => writeSafe(process.stdout, s);
+  const err = (/** @type {string} */ s) => writeSafe(process.stderr, s);
+  let flags;
+  try {
+    const parsed = parseFlags(args, { values: ['run'], booleans: ['json'] });
+    if (parsed.positionals.length > 0) throw new StateError('usage', `unexpected argument ${JSON.stringify(parsed.positionals[0])}`);
+    flags = parsed.flags;
+  } catch (thrown) {
+    err(`status: ${thrown?.message ?? String(thrown)}\n${USAGE}`);
+    return 2;
+  }
+  const json = flags.json === true;
+  try {
+    /** @type {Array<Record<string, any>>} */
+    let records;
+    if (typeof flags.run === 'string') {
+      const id = flags.run;
+      const record = await readRun(id).catch((thrown) => (thrown?.code === 'no-run' ? null : Promise.reject(thrown)));
+      if (!record || typeof record !== 'object') {
+        err(`status: no run record for ${id}\n`); // the wording every verb uses for an unknown run
+        return 1;
+      }
+      records = [record];
+    } else {
+      records = await activeRunsFor(projectRootFor(process.cwd()));
+    }
+    const shown = [];
+    for (const record of records) shown.push(await statusOf(record));
+    if (json) {
+      out(`${JSON.stringify({ runs: shown })}\n`); // briefStatus builds exactly the clause-3 run object
+      return 0;
+    }
+    if (shown.length === 0) {
+      out('no active run\n');
+      return 0;
+    }
+    out(`${shown.map((s) => runLines(s).join('\n')).join('\n\n')}\n`);
+    return 0;
+  } catch (thrown) {
+    err(`status: ${thrown?.message ?? String(thrown)}\n`);
+    return 1;
+  }
+}

package/src/config/validate.mjs

@@ -62,6 +62,7 @@
 import { Ajv2020 } from 'ajv/dist/2020.js';
 import schema from '../../schema/code-forge.schema.json' with { type: 'json' };
 import { redact } from '../util/redact.mjs';
+import { TEST_FILES_TOKEN } from '../util/gate-token.mjs';
 import { checkEffort, displayEffort } from '../engines/efforts.mjs';
 import { CLOSED_BOOK_LEVELS, CODEX_CLOSED_BOOK_REFUSAL, isNoClosedBookProvider, OPEN_BOOK_CODEX_WARNING, openBookCodexAllowed } from './closed-book.mjs';
 import { isKnownId, resolveLevel } from './known-ids.mjs';
@@ -458,19 +459,52 @@ function isArgvArray(value) {
   return Array.isArray(value) && value.length > 0 && value.every((item) => typeof item === 'string') && value[0].length > 0;
 }
 
-function checkGatesNotArgvArray(cfg) {
-  const issues = [];
-  for (const key of GATE_KEYS) {
-    const value = cfg?.gates?.[key];
-    if (value !== undefined && value !== null && !isArgvArray(value)) {
-      issues.push({
-        rule: 'gates-not-argv-array',
-        severity: 'error',
-        message: `gates.${key} must be a non-empty argv array of strings, or null`,
-      });
+/** B60: the keys a gate given as an object may have. */
+const GATE_OBJECT_KEYS = new Set(['argv', 'env']);
+/** B60: an environment variable name. */
+const ENV_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
+
+/**
+ * Rule 9's messages for one gate: an argv array, `{argv, env}` (B60), or null. A message names a
+ * bad key or env variable NAME, never an env value.
+ * @param {string} key @param {unknown} value @returns {string[]}
+ */
+function gateMessages(key, value) {
+  if (value === undefined || value === null) return [];
+  // B60: `{test_files}` may expand to nothing, so it cannot be the command — and as the only item a
+  // full-suite run would be an empty argv
+  /** @param {string[]} argv @returns {string[]} */
+  const tokenMessages = (argv) =>
+    argv.length === 1 && argv[0] === TEST_FILES_TOKEN
+      ? [`gates.${key}: '${TEST_FILES_TOKEN}' cannot be the only item (the full suite would run an empty command)`]
+      : argv[0] === TEST_FILES_TOKEN
+        ? [`gates.${key}: '${TEST_FILES_TOKEN}' cannot be the command (argv[0])`]
+        : [];
+  if (typeof value !== 'object' || Array.isArray(value)) {
+    if (!isArgvArray(value)) return [`gates.${key} must be a non-empty argv array of strings, an {argv, env} object, or null`];
+    return tokenMessages(/** @type {string[]} */ (value));
+  }
+  const gate = /** @type {Record<string, unknown>} */ (value);
+  const messages = Object.keys(gate)
+    .filter((k) => !GATE_OBJECT_KEYS.has(k))
+    .map((k) => `gates.${key}: unknown key ${JSON.stringify(k)} (an object gate has only argv and env)`);
+  if (!isArgvArray(gate.argv)) messages.push(`gates.${key}.argv must be a non-empty argv array of strings`);
+  else messages.push(...tokenMessages(/** @type {string[]} */ (gate.argv)));
+  if (gate.env !== undefined) {
+    if (gate.env === null || typeof gate.env !== 'object' || Array.isArray(gate.env)) {
+      messages.push(`gates.${key}.env must be a map of variable names to string values`);
+    } else {
+      for (const [name, envValue] of Object.entries(gate.env)) {
+        if (!ENV_NAME.test(name)) messages.push(`gates.${key}.env: ${JSON.stringify(name)} is not a variable name (letters, digits and _, not starting with a digit)`);
+        else if (typeof envValue !== 'string') messages.push(`gates.${key}.env.${name} must be a string`);
+      }
     }
   }
-  return issues;
+  return messages;
+}
+
+function checkGatesNotArgvArray(cfg) {
+  return GATE_KEYS.flatMap((key) => gateMessages(key, cfg?.gates?.[key]).map((message) => ({ rule: 'gates-not-argv-array', severity: 'error', message })));
 }
 
 // ── 10. secret-looking-value (ERROR) ────────────────────────────────────────

package/src/context/pack.mjs

@@ -0,0 +1,319 @@
+/**
+ * The coder context pack (block B63a; issue #13 item 5, issue #10 item 2).
+ *
+ * The top-level `context` key of `.code-forge.yml` names what every coder task should carry:
+ *
+ *   context:
+ *     rules: [CLAUDE.md, docs/conventions.md]   repository-relative files, in order
+ *     lessons: docs/lessons.md                  one repository-relative file
+ *     commands: {build: [...], test: [...], lint: [...], format: [...]}   argv arrays, each optional
+ *     max_lines: 300                            the pack's line cap (integer >= 20)
+ *     require_coder_tests: false                B63b: close needs the coder's `TESTS … exit=0` line
+ *
+ * `assemblePack` turns it into ONE pack for a block, in this order: the header (run, block, level,
+ * owned files, test files when the block has them, worktree path and branch when it has one), the
+ * commands (never run; each argv shown POSIX shell-quoted, so a pasted line expands nothing), each
+ * rules file, then the lessons file — every file section headed by its source path (an empty
+ * file: the heading alone). Over `max_lines` the lessons are cut first, then the
+ * rules from the last file backwards, each cut section ending in `[cut: N lines dropped]`; the
+ * header and the commands are never cut.
+ *
+ * `reviewDigest` is the ONE builder of the review packets' rules digest (`## project rules`, ≤ 60
+ * lines, `packet.mjs`): the rules files' text, then a `### lessons` subheading and the lessons.
+ * With no `context` key it is '' — the packet is then byte-identical to before (`(none)`). A file
+ * it cannot read throws: the worker answers that ticket `review.unavailable`, `context-unreadable`.
+ *
+ * Files are always read from the MAIN tree's root (`repoRoot`), never from a block worktree a coder
+ * can write to. A path that is absolute, has a `..` segment, or leads out of the repository through
+ * a symlink (a broken one too: its target is checked) is refused, and so is a missing file
+ * (`ContextError`). A control character (a newline included) in a command token, a rules or
+ * lessons path, or a header value (owned or test file, worktree path or branch) is refused, so
+ * nothing can forge a line of the pack. Command lines go through `redact`, as the rules and
+ * lessons do. The `context` key is not
+ * authority: it is not fixed for the run, and `run reload` takes a change to it — except B63b's
+ * `context.require_coder_tests`, which tightens `block close`: it is read from the run-start
+ * snapshot only (`requireCoderTests`, `src/state/config-snapshot.mjs`) and `run reload` refuses a
+ * change to it. It plays no part in the pack.
+ */
+
+import { lstatSync, readFileSync, readlinkSync, realpathSync } from 'node:fs';
+import path from 'node:path';
+import { estimateTokens } from '../review/packet.mjs';
+import { splitLines } from '../review/context.mjs';
+import { redact } from '../util/redact.mjs';
+
+/** The pack's line cap when `context.max_lines` is not set. */
+export const DEFAULT_MAX_LINES = 300;
+
+/** The smallest `context.max_lines` accepted. */
+export const MIN_MAX_LINES = 20;
+
+/** The `context.commands` keys, in the order the pack lists them. */
+export const COMMAND_KEYS = Object.freeze(['build', 'test', 'lint', 'format']);
+
+/** The subheading the lessons get in the review digest. */
+export const DIGEST_LESSONS_HEADING = '### lessons';
+
+/**
+ * A refusal with a stable `code`. Thrown here: `bad-context` (a bad `context` value),
+ * `control-character` (in a path or a header value), `outside`, `missing` (ENOENT), `unreadable`
+ * (any other lstat or read error, with its code), `not-file`. Thrown by `src/cli/context.mjs`:
+ * `no-block`, `bad-config`, `no-context`, `no-run-root`, `write-failed`.
+ */
+export class ContextError extends Error {
+  /** @param {string} code @param {string} message */
+  constructor(code, message) {
+    super(message);
+    this.name = 'ContextError';
+    this.code = code;
+  }
+}
+
+/** C0 and C1 control characters and DEL: a newline among them. */
+const CONTROL = /[\u0000-\u001f\u007f-\u009f]/;
+
+/** @param {unknown} v @returns {v is Record<string, unknown>} */
+const isMapping = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
+
+/**
+ * @typedef {object} ContextSettings
+ * @property {string[]} rules
+ * @property {string | null} lessons
+ * @property {Record<string, string[]>} commands - only the keys that are set.
+ * @property {number} maxLines
+ */
+
+/**
+ * The `context` key of a config, checked; null when the key is absent.
+ * @param {Record<string, any> | null | undefined} cfg
+ * @returns {ContextSettings | null}
+ * @throws {ContextError} `bad-context`, naming the key.
+ */
+export function contextSettings(cfg) {
+  const raw = cfg?.context;
+  if (raw === undefined || raw === null) return null;
+  if (!isMapping(raw)) throw new ContextError('bad-context', 'context must be a mapping');
+  const rules = raw.rules ?? [];
+  if (!Array.isArray(rules) || !rules.every((r) => typeof r === 'string' && r.length > 0)) throw new ContextError('bad-context', 'context.rules must be a list of file paths');
+  // `CLAUDE.md` and `./CLAUDE.md` are the same file
+  if (new Set(rules.map((r) => path.posix.normalize(r))).size !== rules.length) throw new ContextError('bad-context', 'context.rules names a file twice');
+  const lessons = raw.lessons ?? null;
+  if (lessons !== null && (typeof lessons !== 'string' || lessons.length === 0)) throw new ContextError('bad-context', 'context.lessons must be one file path');
+  const commandsRaw = raw.commands ?? {};
+  if (!isMapping(commandsRaw)) throw new ContextError('bad-context', 'context.commands must be a mapping');
+  /** @type {Record<string, string[]>} */
+  const commands = {};
+  for (const key of Object.keys(commandsRaw)) {
+    if (!COMMAND_KEYS.includes(key)) throw new ContextError('bad-context', `context.commands.${key} is not one of ${COMMAND_KEYS.join(', ')}`);
+  }
+  for (const key of COMMAND_KEYS) {
+    const argv = commandsRaw[key];
+    if (argv === undefined || argv === null) continue;
+    if (!Array.isArray(argv) || argv.length === 0 || !argv.every((a) => typeof a === 'string' && a.length > 0)) throw new ContextError('bad-context', `context.commands.${key} must be an argv list of non-empty strings`);
+    if (argv.some((a) => CONTROL.test(a))) throw new ContextError('bad-context', `context.commands.${key} contains a control character`);
+    commands[key] = [...argv];
+  }
+  // B63b: authority, read by `block close` from the run-start snapshot only; checked here so a
+  // pack is never built from a config that carries a malformed value
+  const requireTests = raw.require_coder_tests ?? false;
+  if (typeof requireTests !== 'boolean') throw new ContextError('bad-context', 'context.require_coder_tests must be true or false');
+  const maxLines = raw.max_lines ?? DEFAULT_MAX_LINES;
+  if (!Number.isInteger(maxLines) || /** @type {number} */ (maxLines) < MIN_MAX_LINES) throw new ContextError('bad-context', `context.max_lines must be an integer >= ${MIN_MAX_LINES}`);
+  return { rules: [...rules], lessons: /** @type {string | null} */ (lessons), commands, maxLines: /** @type {number} */ (maxLines) };
+}
+
+/** How many symlinks one path may pass through before it counts as a loop (as the kernel's ELOOP). */
+const MAX_LINK_HOPS = 40;
+
+/**
+ * `abs` with every symlink on it resolved, as far as its components exist — a symlink whose target
+ * is missing (a broken link) is still followed through its `readlink` text, so where it POINTS is
+ * what is checked. A component that does not exist ends the walk (the rest is joined as given); a
+ * link loop ends it at the link.
+ * @param {string} abs - absolute, without `..` segments. @returns {string}
+ */
+function walkLinks(abs) {
+  const parts = abs.split(path.sep).filter(Boolean);
+  let cur = path.parse(abs).root;
+  let hops = 0;
+  while (parts.length > 0) {
+    const next = path.join(cur, /** @type {string} */ (parts.shift()));
+    let st;
+    try {
+      st = lstatSync(next);
+    } catch {
+      return path.join(next, ...parts);
+    }
+    if (!st.isSymbolicLink()) {
+      cur = next;
+      continue;
+    }
+    hops += 1;
+    if (hops > MAX_LINK_HOPS) return path.join(next, ...parts);
+    // `cur` holds no symlink, so resolving the target's `..` against it is exact
+    const target = path.resolve(cur, readlinkSync(next));
+    parts.unshift(...target.split(path.sep).filter(Boolean));
+    cur = path.parse(target).root;
+  }
+  return cur;
+}
+
+/** @param {string} root @param {string} p @returns {boolean} `p` is `root` or under it. */
+const inside = (root, p) => {
+  const rel = path.relative(root, p);
+  // only a real `..` segment leaves the root: a file named `..notes.md` is inside
+  return !(rel === '..' || rel.startsWith(`..${path.sep}`) || path.isAbsolute(rel));
+};
+
+/**
+ * The real path of the context file `rel` (named by `key`) under `repoRoot`.
+ * @param {string} repoRoot - the main tree's root. @param {string} rel @param {string} key
+ * @returns {string}
+ * @throws {ContextError} `control-character`, `outside`, `missing`, `unreadable`, `not-file`
+ */
+export function resolveContextFile(repoRoot, rel, key) {
+  const shown = JSON.stringify(rel);
+  if (CONTROL.test(rel)) throw new ContextError('control-character', `${key}: ${shown} contains a control character`);
+  if (path.isAbsolute(rel) || rel.split(/[\\/]/).includes('..')) {
+    throw new ContextError('outside', `${key}: ${shown} is outside the repository (give a path relative to the repository root)`);
+  }
+  const root = realpathSync(repoRoot);
+  // every symlink on the way is followed — a broken one too, by its target — and the end checked
+  const real = walkLinks(path.resolve(root, rel));
+  if (!inside(root, real)) throw new ContextError('outside', `${key}: ${shown} leads outside the repository`);
+  let st;
+  try {
+    st = lstatSync(real);
+  } catch (err) {
+    const code = /** @type {NodeJS.ErrnoException} */ (err).code ?? 'error';
+    if (code === 'ENOENT') throw new ContextError('missing', `${key}: ${shown} does not exist`);
+    throw new ContextError('unreadable', `${key}: ${shown} cannot be read (${code})`);
+  }
+  // still a link here: a loop (or more than MAX_LINK_HOPS links) — nothing to read
+  if (st.isSymbolicLink()) throw new ContextError('missing', `${key}: ${shown} does not exist`);
+  if (!st.isFile()) throw new ContextError('not-file', `${key}: ${shown} is not a file`);
+  return real;
+}
+
+/**
+ * @param {string} repoRoot @param {string} rel @param {string} key
+ * @returns {string[]} the file's lines (redacted, trailing whitespace of the file dropped); none
+ *   for an empty or whitespace-only file.
+ * @throws {ContextError} as {@link resolveContextFile}, or `unreadable` when the read fails.
+ */
+function readLines(repoRoot, rel, key) {
+  const file = resolveContextFile(repoRoot, rel, key);
+  let raw;
+  try {
+    raw = readFileSync(file, 'utf8');
+  } catch (err) {
+    throw new ContextError('unreadable', `${key}: ${JSON.stringify(rel)} cannot be read (${/** @type {NodeJS.ErrnoException} */ (err).code ?? 'error'})`);
+  }
+  const text = /** @type {string} */ (redact(raw)).trimEnd();
+  return text === '' ? [] : splitLines(text);
+}
+
+/**
+ * Every rules file and the lessons file, read. A missing or outside file is a refusal.
+ * @param {string} repoRoot @param {ContextSettings} settings
+ * @returns {{rules: Array<{path: string, lines: string[]}>, lessons: {path: string, lines: string[]} | null}}
+ * @throws {ContextError}
+ */
+export function readSources(repoRoot, settings) {
+  const rules = settings.rules.map((rel) => ({ path: rel, lines: readLines(repoRoot, rel, 'context.rules') }));
+  const lessons = settings.lessons === null ? null : { path: settings.lessons, lines: readLines(repoRoot, settings.lessons, 'context.lessons') };
+  return { rules, lessons };
+}
+
+/**
+ * The token as a POSIX shell would take it back: bare when it holds only characters no shell
+ * expands, else in single quotes (an embedded `'` as `'\\''`), so a pasted line never expands
+ * `$x`, a backtick, a glob or a brace.
+ * @param {string} token @returns {string}
+ */
+const argvToken = (token) => (/^[A-Za-z0-9_@%+=:,./-]+$/.test(token) ? token : `'${token.replaceAll("'", "'\\''")}'`);
+
+/** @param {string[]} argv @returns {string} */
+export const argvText = (argv) => argv.map(argvToken).join(' ');
+
+/**
+ * @typedef {object} PackBlock
+ * @property {string} run
+ * @property {string} block
+ * @property {string | null} [level]
+ * @property {string[]} [owned]
+ * @property {string[] | null} [tests]
+ * @property {{path: string, branch: string} | null} [worktree]
+ */
+
+/**
+ * Build the pack text for a block (pure over what it is given).
+ * @param {{settings: ContextSettings, sources: ReturnType<typeof readSources>, block: PackBlock}} opts
+ * @returns {{text: string, lines: number, cut: number}} `cut`: the lines dropped.
+ * @throws {ContextError} `control-character` when a header value holds one.
+ */
+export function assemblePack({ settings, sources, block }) {
+  /** @type {Array<[string, unknown]>} */
+  const values = [['level', block.level], ...(block.owned ?? []).map((f) => /** @type {[string, unknown]} */ (['owned file', f])), ...(block.tests ?? []).map((f) => /** @type {[string, unknown]} */ (['test file', f]))];
+  if (block.worktree) values.push(['worktree path', block.worktree.path], ['worktree branch', block.worktree.branch]);
+  for (const [label, v] of values) {
+    if (typeof v === 'string' && CONTROL.test(v)) throw new ContextError('control-character', `block ${block.block}: ${label} ${JSON.stringify(v)} contains a control character`);
+  }
+  const header = ['# code-forge context pack', '## block', `run: ${block.run}`, `block: ${block.block}`, `level: ${block.level ?? '(unknown)'}`, 'owned files:'];
+  for (const f of block.owned ?? []) header.push(`- ${f}`);
+  if (Array.isArray(block.tests) && block.tests.length > 0) {
+    header.push('test files:');
+    for (const f of block.tests) header.push(`- ${f}`);
+  }
+  if (block.worktree) header.push(`worktree: ${block.worktree.path}`, `branch: ${block.worktree.branch}`);
+  header.push('## commands (never run by code-forge)');
+  const keys = COMMAND_KEYS.filter((k) => Object.hasOwn(settings.commands, k));
+  if (keys.length === 0) header.push('(none)');
+  // a command line can name a secret (a token in an argv): it is redacted as rules and lessons are
+  for (const k of keys) header.push(`${k}: ${redact(argvText(settings.commands[k]))}`);
+
+  /** @type {Array<{heading: string, body: string[], dropped: number}>} */
+  const sections = sources.rules.map((r) => ({ heading: `## rules: ${r.path}`, body: [...r.lines], dropped: 0 }));
+  if (sources.lessons) sections.push({ heading: `## lessons: ${sources.lessons.path}`, body: [...sources.lessons.lines], dropped: 0 });
+
+  const total = () => header.length + sections.reduce((n, s) => n + 1 + s.body.length + (s.dropped > 0 ? 1 : 0), 0);
+  // cut order: the lessons first, then the rules from the last file backwards
+  for (const s of [...sections].reverse()) {
+    let excess = total() - settings.maxLines;
+    if (excess <= 0) break;
+    // the marker takes one line: a section is only cut when that leaves it shorter
+    if (s.body.length < 2) continue;
+    const drop = Math.min(s.body.length, excess + 1);
+    s.body = s.body.slice(0, s.body.length - drop);
+    s.dropped = drop;
+  }
+  const out = [...header];
+  for (const s of sections) {
+    out.push(s.heading, ...s.body);
+    if (s.dropped > 0) out.push(`[cut: ${s.dropped} lines dropped]`);
+  }
+  return { text: `${out.join('\n')}\n`, lines: out.length, cut: sections.reduce((n, s) => n + s.dropped, 0) };
+}
+
+/**
+ * The review packets' rules digest (`## project rules`), built from the MAIN tree each time a
+ * packet is built: the rules files' lines in order, then `### lessons` and the lessons' lines.
+ * '' when the config has no `context` key (the packet stays as it was), or names no rules and no
+ * lessons. `packet.mjs` keeps the first 60 lines and trims from the end over budget, rules and
+ * lessons together.
+ * @param {{repoRoot: string, cfg: Record<string, any> | null | undefined}} opts
+ * @returns {string}
+ * @throws {ContextError} a bad `context` value, or a rules or lessons file that is missing,
+ *   outside the repository or unreadable — the worker makes that ticket `review.unavailable`
+ *   with `reason: context-unreadable` (no review runs without the rules it was promised).
+ */
+export function reviewDigest({ repoRoot, cfg }) {
+  const settings = contextSettings(cfg);
+  if (settings === null) return '';
+  const out = settings.rules.flatMap((rel) => readLines(repoRoot, rel, 'context.rules'));
+  if (settings.lessons !== null) out.push(DIGEST_LESSONS_HEADING, ...readLines(repoRoot, settings.lessons, 'context.lessons'));
+  return out.join('\n');
+}
+
+/** @param {string} text @returns {number} the pack's estimated tokens (the review packets' bytes / 4). */
+export const packTokens = (text) => estimateTokens(text);

package/src/doctor/index.mjs

@@ -1,9 +1,9 @@
 /**
  * `code-forge doctor` (plan §2.3; block B13b): every row, in print order. `--quick` = the three
  * rows the skill's preflight needs (config, harness links, Jev key resolution); the full run adds
- * the PATH/Solo/gate rows, the live Jev call, ledger, `tmp`, the provider CLI probes (presence,
- * version, flags, one call per role builder, isolation, path deny, Codex rules), the worker
- * start/stop, the signer key and the `signer: same-user boundary only` line.
+ * the PATH/Solo/gate rows, the live Jev call, ledger, `tmp`, `review state` (B69), the provider
+ * CLI probes (presence, version, flags, one call per role builder, isolation, path deny, Codex
+ * rules), the worker start/stop, the signer key and the `signer: same-user boundary only` line.
  */
 
 import { randomBytes } from 'node:crypto';
@@ -13,7 +13,7 @@ import path from 'node:path';
 import { cliNameForProvider } from '../engines/provider-cli.mjs';
 import { newRunId } from '../state/paths.mjs';
 import { runRoot } from '../util/tmp.mjs';
-import { checkCommands, checkConfig, checkJev, checkKeys, checkLedger, checkLinks, checkReviewConcurrency, checkTmp, checkTools } from './local.mjs';
+import { checkCommands, checkConfig, checkJev, checkKeys, checkLedger, checkLinks, checkReviewConcurrency, checkReviewState, checkTmp, checkTools } from './local.mjs';
 import { configuredProviders, pingRoles, probeCli, probeCodexRules, probeIsolation, probePathDeny } from './probes.mjs';
 import { row } from './rows.mjs';
 import { probeWorkerAndSigner, SIGNER_ROW } from './worker-probe.mjs';
@@ -68,6 +68,7 @@ export async function runDoctor(opts = {}, deps = {}) {
   rows.push(...(await checkTools(toolOpts)));
   rows.push(...(await checkLedger()));
   rows.push(...checkTmp(cfg));
+  rows.push(...(await checkReviewState(cfg)));
   rows.push(checkReviewConcurrency(cfg));
   if (!cfg) {
     rows.push(row('probes', 'FAIL', 'probes', 'skipped: no valid config'));