@eventmodelers/cli 1.0.162 → 2.0.1

package/shared/build-kit/lib/slice-curation.js

@@ -0,0 +1,40 @@
+// When the loop spends a turn on the learnings. The curator is an LLM turn that only writes events —
+// `learn --merge` and `learn --retract` — and the loop marks the review done afterwards (`learnings-curated`),
+// whatever came of the turn: a curator that failed or timed out does not make the loop retry in a tight loop,
+// the next review comes after more learnings have piled up.
+
+import { appendEvent, readEvents } from './slice-events.js';
+import { fold, needsCuration } from './slice-state.js';
+import { curationRequest } from './slice-learnings.js';
+
+const DEFAULT_THRESHOLD = 10;
+
+// Learnings recorded since the last review before a turn is worth it: RALPH_CURATE_AFTER, 0 switches
+// curation off.
+export function curationThreshold(env = process.env) {
+  const raw = env.RALPH_CURATE_AFTER;
+  if (raw === undefined || raw === '') return DEFAULT_THRESHOLD;
+  const n = Number(raw);
+  return Number.isInteger(n) && n >= 0 ? n : DEFAULT_THRESHOLD;
+}
+
+// Runs a curation turn when enough new learnings are waiting and no slice is being built. `onCurate(prompt,
+// { env })` is the runner's agent turn; `env` must reach the agent's process (EVENTMODELERS_CURATING=1 makes
+// `learn` refuse to record new learnings — the curator tidies, it does not add facts). It is passed along
+// instead of set on process.env because the runners build their child environment once, at load time.
+// Returns whether a turn was run.
+export async function curateIfDue({ kitDir, meta, onCurate, threshold = curationThreshold() }) {
+  if (!onCurate || !threshold) return false;
+  const state = fold(readEvents(kitDir));
+  if (!needsCuration(state, threshold)) return false;
+  if (Object.values(state.slices).some((s) => s.claim)) return false;
+
+  console.log(`[ralph] ${state.learnings.filter((l) => !l.curated).length} new learnings — curating them.`);
+  try {
+    await onCurate(curationRequest(state.learnings), { env: { EVENTMODELERS_CURATING: '1' } });
+  } catch (err) {
+    console.error('[ralph] The curation turn failed — the learnings stay as they are:', err.message);
+  }
+  appendEvent(kitDir, { type: 'learnings-curated' }, meta);
+  return true;
+}

package/shared/build-kit/lib/slice-events.js

@@ -0,0 +1,93 @@
+// The slice-state event store, local to this checkout and never committed:
+//   .build-kit/events/<id>.json  one standalone JSON file per event
+//   .build-kit/events.log        append-only index, one event id per line — its order is the event order
+// An event exists once its id is in the index. A file the index doesn't list (a crash between the two
+// writes) is never applied, and an index line without a readable file is skipped. `fold` (slice-state.js)
+// derives all state from readEvents.
+
+import { appendFileSync, closeSync, existsSync, fstatSync, mkdirSync, openSync, readFileSync, readSync, renameSync, writeFileSync } from 'fs';
+import { randomUUID } from 'crypto';
+import { join } from 'path';
+
+export const EVENTS_DIR = 'events';
+export const INDEX_FILE = 'events.log';
+
+const ID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+
+// True when the index ends in the middle of a line — a crash during an append left a fragment.
+function endsMidLine(path) {
+  if (!existsSync(path)) return false;
+  const fd = openSync(path, 'r');
+  try {
+    const { size } = fstatSync(fd);
+    if (size === 0) return false;
+    const last = Buffer.alloc(1);
+    readSync(fd, last, 0, 1, size - 1);
+    return last[0] !== 0x0a;
+  } finally {
+    closeSync(fd);
+  }
+}
+
+// Tags label any event (an area, a topic, who it is for). Anything but non-blank strings is dropped, the
+// rest trimmed and de-duplicated; an event without usable tags has no `tags` field at all.
+export function normalizeTags(tags) {
+  if (!Array.isArray(tags)) return [];
+  return [...new Set(tags.filter((t) => typeof t === 'string').map((t) => t.trim()).filter(Boolean))];
+}
+
+// Where an event came from: the agent that wrote it, what kind it is (BUILD or MODELING) and the organization and
+// board it ran against. Only these four keys are kept (never a token or anything else that wandered into the config), blank values
+// dropped; no usable metadata means no `meta` field.
+const META_KEYS = ['agent_id', 'agent_type', 'organization_id', 'board_id'];
+export function normalizeMeta(meta) {
+  const clean = {};
+  for (const key of META_KEYS) {
+    const value = typeof meta?.[key] === 'string' ? meta[key].trim() : '';
+    if (value) clean[key] = value;
+  }
+  return clean;
+}
+
+// The event file is written whole (temp file, then rename) before its id is indexed, so a reader that
+// finds the id finds a complete file. The index line is one short append-mode write, so lines from
+// concurrent processes never interleave however large the event. After a torn index line the new id
+// starts on a fresh line instead of being glued onto the fragment. Returns the event id.
+export function appendEvent(kitDir, event, meta) {
+  const dir = join(kitDir, EVENTS_DIR);
+  mkdirSync(dir, { recursive: true });
+  const id = randomUUID();
+  const tmp = join(dir, `${id}.tmp`);
+  // The caller's metadata is the only metadata: one carried in the event itself is dropped.
+  const { tags, meta: _ignored, ...rest } = event;
+  const cleanTags = normalizeTags(tags);
+  const cleanMeta = normalizeMeta(meta);
+  writeFileSync(tmp, JSON.stringify({
+    at: new Date().toISOString(),
+    ...rest,
+    ...(cleanTags.length ? { tags: cleanTags } : {}),
+    ...(Object.keys(cleanMeta).length ? { meta: cleanMeta } : {}),
+    id,
+  }, null, 2), 'utf-8');
+  renameSync(tmp, join(dir, `${id}.json`));
+  const index = join(kitDir, INDEX_FILE);
+  appendFileSync(index, `${endsMidLine(index) ? '\n' : ''}${id}\n`, 'utf-8');
+  return id;
+}
+
+// All events in index order; with `tag`, only those carrying it.
+export function readEvents(kitDir, { tag } = {}) {
+  const index = join(kitDir, INDEX_FILE);
+  if (!existsSync(index)) return [];
+  const events = [];
+  const seen = new Set();
+  for (const line of readFileSync(index, 'utf-8').split('\n')) {
+    const id = line.trim();
+    if (!ID.test(id) || seen.has(id)) continue;
+    seen.add(id);
+    try {
+      events.push(JSON.parse(readFileSync(join(kitDir, EVENTS_DIR, `${id}.json`), 'utf-8')));
+    } catch { /* indexed but missing or unreadable — skipped */ }
+  }
+  return tag === undefined ? events : events.filter((e) => e.tags?.includes(tag));
+}

package/shared/build-kit/lib/slice-git.js

@@ -0,0 +1,86 @@
+// The git side of a claim: what state a build starts from, and undoing a failed attempt. Nothing here
+// knows about slice state — the caller passes `base` and `cleanTree` (recorded on the `claimed` event).
+
+import { existsSync } from 'fs';
+import { execFileSync } from 'child_process';
+import { basename, dirname, join } from 'path';
+
+// The kit dir (.build-kit: slices, event store), .eventmodelers (credentials) and progress.txt belong to
+// the loop and the agent's bookkeeping, never to a slice's code — they are outside every check and every
+// discard below.
+function treePathspec(kitDir) {
+  return ['.', `:(exclude)${basename(kitDir)}`, ':(exclude).eventmodelers', ':(exclude)progress.txt'];
+}
+
+function gitIn(projectDir, ...args) {
+  return execFileSync('git', args, { cwd: projectDir, encoding: 'utf-8', stdio: ['ignore', 'pipe', 'pipe'] });
+}
+
+function currentBranch(projectDir) {
+  try { return gitIn(projectDir, 'symbolic-ref', '-q', '--short', 'HEAD').trim(); } catch { return null; }
+}
+
+// true: clean, false: uncommitted changes, null: not a git repo / git unavailable.
+export function isTreeClean(kitDir) {
+  const projectDir = dirname(kitDir);
+  if (!existsSync(join(projectDir, '.git'))) return null;
+  try {
+    return gitIn(projectDir, 'status', '--porcelain', '--', ...treePathspec(kitDir)).trim() === '';
+  } catch {
+    return null;
+  }
+}
+
+// The git state a claim starts from: the checked-out branch (null when detached), its commit, and the
+// local branches that exist. null when this is not a git repo / git is unavailable.
+export function gitBase(kitDir) {
+  const projectDir = dirname(kitDir);
+  if (!existsSync(join(projectDir, '.git'))) return null;
+  try {
+    const branch = gitIn(projectDir, 'symbolic-ref', '-q', '--short', 'HEAD').trim();
+    const head = gitIn(projectDir, 'rev-parse', 'HEAD').trim();
+    const branches = gitIn(projectDir, 'for-each-ref', '--format=%(refname:short)', 'refs/heads').split('\n').filter(Boolean);
+    return { branch, head, branches };
+  } catch {
+    return null; // e.g. detached HEAD or a repo without commits — nothing safe to restore later
+  }
+}
+
+// A build that ended without recording an outcome did not finish, and the attempt is undone as if it
+// never happened: uncommitted work is discarded, the branch the claim started on is checked out again
+// and every `feature/*` branch created since is deleted — so the retry starts from the state the
+// claim saw, not on top of a half-done build. Only when the tree was clean when the slice was claimed;
+// otherwise the changes may be a person's own work, and the loop leaves them alone. Commits on the
+// starting branch itself are never rewritten.
+// Returns what was thrown away ({ changed, created, branch }) for the caller to record, or null when
+// nothing was touched.
+export function discardUnfinishedWork(kitDir, planned, cleanTree, base = null) {
+  const projectDir = dirname(kitDir);
+  if (cleanTree !== true) {
+    if (cleanTree === false) console.warn(`[ralph] "${planned.title}" ended unfinished, but the working tree had uncommitted changes before the build — leaving them in place.`);
+    return null;
+  }
+  try {
+    const spec = treePathspec(kitDir);
+    const changed = gitIn(projectDir, 'status', '--porcelain', '--', ...spec).trim();
+    const branch = currentBranch(projectDir);
+    const created = base?.branches
+      ? gitIn(projectDir, 'for-each-ref', '--format=%(refname:short)', 'refs/heads/feature').split('\n')
+          .filter((b) => b && !base.branches.includes(b))
+      : [];
+    const onOtherBranch = Boolean(base?.branch) && branch !== base.branch;
+    if (!changed && !created.length && !onOtherBranch) return null;
+
+    // Scoped to the build's own paths, so the kit dir, .eventmodelers and progress.txt keep any staging.
+    gitIn(projectDir, 'reset', '-q', 'HEAD', '--', ...spec);
+    gitIn(projectDir, 'checkout', '--', ...spec);
+    gitIn(projectDir, 'clean', '-fdq', '--', ...spec);
+    if (onOtherBranch) gitIn(projectDir, 'checkout', '-q', base.branch);
+    for (const b of created) gitIn(projectDir, 'branch', '-D', b);
+    console.log(`[ralph] Discarded the unfinished attempt at "${planned.title}"${created.length ? ` (deleted ${created.join(', ')})` : ''}:\n${changed}`);
+    return { changed, created, branch };
+  } catch (err) {
+    console.error(`[ralph] Could not discard the unfinished work of "${planned.title}":`, err.message);
+    return null;
+  }
+}

package/shared/build-kit/lib/slice-learnings.js

@@ -0,0 +1,197 @@
+// Learnings as events, and AGENTS.md as their projection (`renderLearnings`). The build agent records a
+// learning with `eventmodelers learn` and withdraws a wrong one with `learn --retract`; nobody edits the
+// file by hand — but when someone does (an older prompt, a pull that merged teammates' lines), the lines
+// are adopted as learnings first, so a regeneration never loses them.
+
+import { existsSync, readFileSync, renameSync, writeFileSync } from 'fs';
+import { join } from 'path';
+import { appendEvent, readEvents } from './slice-events.js';
+import { fold, learningKey, renderLearnings } from './slice-state.js';
+
+export const AGENTS_FILE = 'AGENTS.md';
+const SCOPES = ['system', 'repo'];
+
+// What an AGENTS.md says as learnings. A `##` (or deeper) heading sets the topic; a top-level `#` is the file's
+// title and no topic. Bullets are learnings, and so are plain lines added after the list has begun (a hand-appended
+// line) — but not the paragraph a file opens with: whatever comes before the first bullet or sub-heading is an
+// introduction. A file with no bullets and no sub-heading at all is a hand-written list and is read line by line.
+// The generated comment and fenced code are never learnings.
+export function parseAgentsFile(text) {
+  const items = [];
+  let topic;
+  let fenced = false;
+  let started = false;
+  let structured = false;
+  for (const raw of text.split('\n')) {
+    const line = raw.trim();
+    if (line.startsWith('```')) { fenced = !fenced; continue; }
+    if (fenced || !line || line.startsWith('<!--')) continue;
+    const heading = line.match(/^(#{1,6})\s+(.*)$/);
+    if (heading) {
+      if (heading[1].length > 1) { topic = heading[2].trim() || undefined; started = true; structured = true; }
+      continue;
+    }
+    const bullet = /^[-*]\s+/.test(line);
+    if (bullet) { started = true; structured = true; }
+    const learning = line.replace(/^[-*]\s+/, '').trim();
+    if (learning) items.push({ topic, text: learning, introduction: !started });
+  }
+  return items.filter((i) => structured ? !i.introduction : true).map(({ topic: t, text: x }) => ({ topic: t, text: x }));
+}
+
+function writeIfChanged(path, content) {
+  if (existsSync(path) && readFileSync(path, 'utf-8') === content) return false;
+  const tmp = `${path}.${process.pid}.tmp`;
+  writeFileSync(tmp, content, 'utf-8');
+  renameSync(tmp, path);
+  return true;
+}
+
+// Writes AGENTS.md from the log, without reading it first. Used right after this module's own events —
+// adopting then would take the line a retraction just removed for a hand edit and bring it back.
+// Nothing is written while there is nothing learned (a project without learnings gets no file).
+function projectLearnings(kitDir, state) {
+  const content = renderLearnings(state);
+  return content ? writeIfChanged(join(kitDir, AGENTS_FILE), content) : false;
+}
+
+// The entry point before anything reads learnings: adopts what AGENTS.md says that the log does not know
+// yet, then writes the file from the log. Returns { state, written }.
+export function syncLearnings({ kitDir, meta }) {
+  const path = join(kitDir, AGENTS_FILE);
+  let state = fold(readEvents(kitDir));
+  if (existsSync(path)) {
+    const known = new Set(state.learnings.map((l) => learningKey(l.text)));
+    let adopted = false;
+    for (const { topic, text } of parseAgentsFile(readFileSync(path, 'utf-8'))) {
+      const key = learningKey(text);
+      if (known.has(key)) continue;
+      known.add(key);
+      appendEvent(kitDir, { type: 'learning-recorded', text, ...(topic ? { topic } : {}), scope: 'repo', tags: ['adopted'] }, meta);
+      adopted = true;
+    }
+    if (adopted) state = fold(readEvents(kitDir));
+  }
+  return { state, written: projectLearnings(kitDir, state) };
+}
+
+// Records one learning. A learning the file already has is not recorded again (returned with
+// duplicate: true), so an agent does not have to diff before it calls.
+export function recordLearning({ kitDir, text, topic, tags, scope = 'repo', slice, meta }) {
+  const clean = String(text ?? '').trim();
+  if (!clean) throw new Error('the learning is empty');
+  if (!SCOPES.includes(scope)) throw new Error(`scope must be ${SCOPES.join(' or ')}, not "${scope}"`);
+  const { state } = syncLearnings({ kitDir, meta });
+  const existing = state.learnings.find((l) => learningKey(l.text) === learningKey(clean));
+  if (existing) return { id: existing.id, duplicate: true };
+  const id = appendEvent(kitDir, { type: 'learning-recorded', text: clean, ...(topic?.trim() ? { topic: topic.trim() } : {}), scope, ...(slice ? { slice } : {}), tags }, meta);
+  projectLearnings(kitDir, fold(readEvents(kitDir)));
+  return { id, duplicate: false };
+}
+
+// A learning by its id or by a unique prefix of it (`learnings --ids` shows the first eight characters).
+function resolveLearning(learnings, id) {
+  const wanted = String(id ?? '').trim();
+  if (!wanted) throw new Error('name the learning by its id (see `learnings --ids`)');
+  const matches = learnings.filter((l) => l.id === wanted || l.id.startsWith(wanted));
+  if (!matches.length) throw new Error(`no learning with id "${wanted}"`);
+  if (matches.length > 1 && !matches.some((l) => l.id === wanted)) throw new Error(`"${wanted}" matches ${matches.length} learnings — use more of the id`);
+  return matches.find((l) => l.id === wanted) ?? matches[0];
+}
+
+// Withdraws a learning by id or by a unique prefix of it; `reason` says why (the curator gives one).
+export function retractLearning({ kitDir, id, reason, meta }) {
+  const { state } = syncLearnings({ kitDir, meta });
+  const target = resolveLearning(state.learnings, id);
+  appendEvent(kitDir, { type: 'learning-retracted', learning: target.id, ...(reason?.trim() ? { reason: reason.trim() } : {}) }, meta);
+  projectLearnings(kitDir, fold(readEvents(kitDir)));
+  return { id: target.id, text: target.text };
+}
+
+export function listLearnings(kitDir) {
+  return fold(readEvents(kitDir)).learnings.map(({ id, text, topic, scope, tags }) => ({ id, text, topic, scope, tags }));
+}
+
+// The curator's merge: two or more learnings that say the same thing become one. The event keeps what
+// the sources said, so a bad merge can be repaired. Sources of different scopes need the scope named.
+export function mergeLearnings({ kitDir, ids, text, topic, scope, tags, reason, meta }) {
+  const { state } = syncLearnings({ kitDir, meta });
+  const sources = [...new Set((ids ?? []).map((id) => resolveLearning(state.learnings, id)))];
+  if (sources.length < 2) throw new Error('a merge needs at least two learnings');
+  const clean = String(text ?? '').trim();
+  if (!clean) throw new Error('the merged learning is empty');
+  if (scope !== undefined && !SCOPES.includes(scope)) throw new Error(`scope must be ${SCOPES.join(' or ')}, not "${scope}"`);
+  if (scope === undefined && new Set(sources.map((l) => l.scope)).size > 1) throw new Error('the learnings have different scopes — name the scope of the merged one');
+  const id = appendEvent(kitDir, {
+    type: 'learning-merged',
+    learnings: sources.map((l) => l.id),
+    text: clean,
+    ...(topic?.trim() ? { topic: topic.trim() } : {}),
+    ...(scope ? { scope } : {}),
+    tags,
+    ...(reason?.trim() ? { reason: reason.trim() } : {}),
+    sources: sources.map(({ id, text: was }) => ({ id, text: was })),
+  }, meta);
+  projectLearnings(kitDir, fold(readEvents(kitDir)));
+  return { id };
+}
+
+// What the curator (an LLM turn) is told: the learnings with their ids, and the two things it may do.
+// It changes the list only through those commands — AGENTS.md is regenerated from the events.
+export function curationRequest(learnings) {
+  if (!learnings.length) return '';
+  const list = learnings.map((l) => `  ${l.id.slice(0, 8)}  [${l.topic ?? 'General'}]  (${l.scope})  ${l.text}${l.tags?.length ? `  ${l.tags.map((t) => `#${t}`).join(' ')}` : ''}`).join('\n');
+  return `You are the curator of this project's learnings. Below is everything recorded so far: id, [topic], (scope), the learning, #tags. \`.build-kit/AGENTS.md\` is generated from this list — never edit that file. You change the list only with these two commands:
+
+- Merge learnings that say the same thing into one terse line:
+  npx @eventmodelers/cli learn --merge <id,id,…> "<combined text>" --reason "<why they are the same>"
+  (add --topic to set the heading, and --scope when the sources have different scopes)
+- Retract a learning that is wrong or obsolete:
+  npx @eventmodelers/cli learn --retract <id> --reason "<what you found>"
+
+Rules:
+- No new learnings — recording one is refused while you curate. Merge or retract only.
+- Retract only with evidence you have checked: the code, the git log, the slice definitions. Put it in --reason. If you cannot judge a learning, keep it.
+- A merge must not lose information: the combined text says everything its sources said, in one line, and adds nothing.
+- Learnings with scope "system" are about the modeled domain; merge or retract them only when the evidence is in the slices or the code.
+- Leave learnings that are fine alone. Finish with one line saying what you merged and retracted.
+
+Learnings:
+${list}
+`;
+}
+
+// ── learnings a turn states in its reply ────────────────────────────────────────
+// The locked-down modeling agent cannot run `learn` (its Bash is an allowlist, and it takes chat from any
+// collaborator on the board), so it ends a reply with `Learning [<topic>]: <one terse line>` lines and the
+// CLI — trusted code — records them. A reply yields at most five learnings of at most 300 characters:
+// what a board collaborator can talk the agent into saying stays small.
+const MAX_TURN_LEARNINGS = 5;
+const MAX_LEARNING_LENGTH = 300;
+const TURN_LEARNING = /^\s*(?:[-*]\s+)?learning(?:\s*\[([^\]]{1,60})\])?:\s*(.*?)\s*$/i;
+
+export function parseTurnLearnings(reply) {
+  const found = [];
+  let fenced = false;
+  for (const line of String(reply ?? '').split('\n')) {
+    if (line.trim().startsWith('```')) { fenced = !fenced; continue; }
+    if (fenced) continue;
+    const m = TURN_LEARNING.exec(line);
+    if (!m) continue;
+    const text = m[2];
+    if (!text || /^none\.?$/i.test(text) || text.length > MAX_LEARNING_LENGTH) continue;
+    found.push({ topic: m[1]?.trim() || undefined, text });
+    if (found.length === MAX_TURN_LEARNINGS) break;
+  }
+  return found;
+}
+
+// Records what a turn's reply states as modeling learnings (scope system: they are about the model).
+// Returns how many were new.
+export function recordTurnLearnings({ kitDir, reply, meta }) {
+  let recorded = 0;
+  for (const { topic, text } of parseTurnLearnings(reply)) {
+    if (!recordLearning({ kitDir, text, topic, scope: 'system', tags: ['modeling'], meta }).duplicate) recorded++;
+  }
+  return recorded;
+}

package/shared/build-kit/lib/slice-projection.js

@@ -0,0 +1,101 @@
+// Slice status in `.slices/<ctx>/index.json` and `slice.json` is a read-only view of the event log — the
+// build agent reads those files, but nothing writes status into them except this projection.
+
+import { existsSync, readFileSync, readdirSync, renameSync, writeFileSync } from 'fs';
+import { join } from 'path';
+import { appendEvent, readEvents } from './slice-events.js';
+import { fold } from './slice-state.js';
+
+// The loop's status for a slice, falling back to what the board said when the log knows nothing of it.
+export function statusOf(state, slice) {
+  return state.slices[slice.id]?.status ?? slice.status;
+}
+
+// Records what the board shows. Only changes become events, so a refresh every few seconds does not
+// grow the log. `meta` (agent, organization, board) is stamped on each event. Returns the folded state.
+export function observeBoard(kitDir, boardSlices, meta, current = fold(readEvents(kitDir))) {
+  const state = current;
+  let changed = false;
+  for (const { id, status } of boardSlices) {
+    if (!id || !status || state.slices[id]?.lastBoardStatus === status) continue;
+    appendEvent(kitDir, { type: 'board-observed', slice: id, status }, meta);
+    changed = true;
+  }
+  return changed ? fold(readEvents(kitDir)) : state;
+}
+
+// The build agent still records its outcome by editing a slice's status in index.json (until it has a
+// command of its own). While a slice is claimed the projection keeps that file equal to the log, so any
+// difference is the agent's edit — adopted as `agent-recorded`. This runs before every refresh and before
+// settling, or the next projection would write the log's InProgress over the agent's Done.
+// Returns the folded state.
+export function adoptAgentEdits(kitDir, state, meta) {
+  const claimed = Object.entries(state.slices).filter(([, s]) => s.claim).map(([id]) => id);
+  const slicesDir = join(kitDir, '.slices');
+  if (!claimed.length || !existsSync(slicesDir)) return state;
+  let adopted = false;
+  for (const ctx of readdirSync(slicesDir, { withFileTypes: true })) {
+    if (!ctx.isDirectory()) continue;
+    let index;
+    try { index = JSON.parse(readFileSync(join(slicesDir, ctx.name, 'index.json'), 'utf-8')); } catch { continue; }
+    for (const entry of index.slices ?? []) {
+      if (!claimed.includes(entry.id) || !entry.status || entry.status === state.slices[entry.id].status) continue;
+      appendEvent(kitDir, { type: 'agent-recorded', slice: entry.id, status: entry.status }, meta);
+      adopted = true;
+    }
+  }
+  return adopted ? fold(readEvents(kitDir)) : state;
+}
+
+function writeJsonAtomic(path, data) {
+  const tmp = `${path}.${process.pid}.tmp`;
+  writeFileSync(tmp, JSON.stringify(data, null, 2), 'utf-8');
+  renameSync(tmp, path);
+}
+
+// Sets status (and the Blocked note) on one parsed file's object; true when anything changed.
+function apply(target, slice, extra = {}) {
+  const want = { status: slice.status, blockedReason: slice.blocked?.reason, blockedAt: slice.blocked?.at, ...extra };
+  let changed = false;
+  for (const [key, value] of Object.entries(want)) {
+    if (value === undefined) {
+      if (key !== 'status' && key in target) { delete target[key]; changed = true; }
+    } else if (JSON.stringify(target[key]) !== JSON.stringify(value)) {
+      target[key] = value;
+      changed = true;
+    }
+  }
+  return changed;
+}
+
+// Writes the derived status into every index.json entry (and its `definition`) and slice.json the log
+// has a status for. Everything else in those files is left alone, and a file is only rewritten when
+// something changed. Returns how many files were written.
+export function projectStatus(kitDir, state) {
+  const slicesDir = join(kitDir, '.slices');
+  if (!existsSync(slicesDir)) return 0;
+  let written = 0;
+  for (const ctx of readdirSync(slicesDir, { withFileTypes: true })) {
+    if (!ctx.isDirectory()) continue;
+    const indexPath = join(slicesDir, ctx.name, 'index.json');
+    if (!existsSync(indexPath)) continue;
+    let index;
+    try { index = JSON.parse(readFileSync(indexPath, 'utf-8')); } catch { continue; }
+    let indexChanged = false;
+    for (const entry of index.slices ?? []) {
+      const slice = state.slices[entry.id];
+      if (!slice?.status) continue;
+      if (apply(entry, slice)) indexChanged = true;
+      if (entry.definition && entry.definition.status !== slice.status) { entry.definition.status = slice.status; indexChanged = true; }
+      const slicePath = join(slicesDir, ctx.name, entry.folder ?? '', 'slice.json');
+      if (!entry.folder || !existsSync(slicePath)) continue;
+      try {
+        const data = JSON.parse(readFileSync(slicePath, 'utf-8'));
+        // slice.json is what the build agent reads, so it also carries what the last failed attempt tried.
+        if (apply(data, slice, { lastAttempt: slice.lastFailure ?? undefined })) { writeJsonAtomic(slicePath, data); written++; }
+      } catch { /* an unreadable slice.json is left for the next full fetch to repair */ }
+    }
+    if (indexChanged) { writeJsonAtomic(indexPath, index); written++; }
+  }
+  return written;
+}