cyc-stack 0.9.1 → 0.11.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (48) hide show
  1. package/.claude-plugin/plugin.json +1 -1
  2. package/.codex-plugin/plugin.json +1 -1
  3. package/.cursor-plugin/plugin.json +1 -1
  4. package/README.md +3 -2
  5. package/bin/cyc.mjs +72 -20
  6. package/docs/README.md +2 -0
  7. package/docs/context.md +18 -10
  8. package/docs/project-tools.md +2 -12
  9. package/docs/runtime.md +5 -1
  10. package/docs/work-assessments.md +4 -4
  11. package/docs/work-queue.md +187 -0
  12. package/methods/cyc-build/SKILL.md +1 -1
  13. package/methods/cyc-context/SKILL.md +28 -20
  14. package/methods/cyc-context/references/evidence.md +1 -1
  15. package/methods/cyc-context/references/templates.md +30 -18
  16. package/methods/cyc-design/frontend-design/SKILL.md +132 -21
  17. package/methods/cyc-design/frontend-design/references/color.md +43 -56
  18. package/methods/cyc-design/frontend-design/references/craft-rules.md +17 -14
  19. package/methods/cyc-design/frontend-design/references/decision-sheet.md +95 -93
  20. package/methods/cyc-design/frontend-design/references/experience-review.md +15 -6
  21. package/methods/cyc-design/frontend-design/references/field-guide.md +439 -0
  22. package/methods/cyc-design/frontend-design/references/generic-tells.md +83 -32
  23. package/methods/cyc-design/frontend-design/references/layout-archetypes.md +5 -5
  24. package/methods/cyc-design/frontend-design/references/patterns.md +108 -0
  25. package/methods/cyc-design/frontend-design/references/reference-standards.md +118 -22
  26. package/methods/cyc-design/frontend-design/references/typography.md +59 -44
  27. package/methods/cyc-design/frontend-design/references/ux-foundations.md +2 -1
  28. package/methods/cyc-design/frontend-design/references/visual-material.md +43 -8
  29. package/methods/cyc-design/frontend-design/scripts/contrast.mjs +39 -0
  30. package/methods/cyc-design/frontend-design/scripts/first-screen.mjs +911 -0
  31. package/methods/cyc-design/frontend-design/scripts/photo-text.mjs +230 -0
  32. package/methods/cyc-verify/SKILL.md +1 -1
  33. package/package.json +6 -1
  34. package/plugin.json +1 -1
  35. package/scripts/catalog.mjs +5 -3
  36. package/scripts/context-review.mjs +364 -261
  37. package/scripts/hub-page.mjs +275 -0
  38. package/scripts/hub.mjs +139 -0
  39. package/scripts/project-tools.mjs +14 -6
  40. package/scripts/queue-board.mjs +287 -0
  41. package/scripts/queue.mjs +283 -0
  42. package/scripts/run-gate.mjs +8 -5
  43. package/scripts/runtime.mjs +270 -19
  44. package/scripts/source-snapshot.mjs +20 -2
  45. package/scripts/work-review.mjs +4 -3
  46. package/skills/cyc/SKILL.md +12 -4
  47. package/skills/cyc/references/playbooks/experience.md +2 -0
  48. package/skills/cyc/references/playbooks/plan.md +2 -0
@@ -3,14 +3,13 @@ import { dirname, join, relative, resolve } from 'node:path';
3
3
  import { randomUUID } from 'node:crypto';
4
4
  import { spawnSync } from 'node:child_process';
5
5
  import { createHash } from 'node:crypto';
6
- import { readRun, contextUpdate } from './runtime.mjs';
6
+ import { readRun } from './runtime.mjs';
7
7
  import { contextLinks } from './project-tools.mjs';
8
+ import { changeFile } from './source-snapshot.mjs';
8
9
 
9
- // Component context docs under docs/context/ and their quality check. A doc is for one component,
10
- // in a fixed AI-readable layout, and the index (the table of contents) carries enough per component
11
- // that a task can read the index plus the matched docs instead of every doc. `review` proposes
12
- // doc updates from completed controller runs and `--write` applies them; `lint` checks the rules
13
- // below and the index's freshness against Git; `measure` counts what the index path costs to read.
10
+ // Project context under docs/context/. A component doc says what is true now (Covers, Current view,
11
+ // Lessons); the index is its table of contents; a change record says what one completed run did
12
+ // and how its checks ended, published after verification and so never verified source.
14
13
 
15
14
  export const contextFolder = 'docs/context';
16
15
  export const indexName = `${contextFolder}/INDEX.md`;
@@ -21,32 +20,39 @@ const runIdText = /[A-Za-z0-9][A-Za-z0-9._-]{3,}/;
21
20
  const hashText = /(?:sha256:)?[0-9a-f]{7,64}/;
22
21
  const lastChangeLine = new RegExp(`^Last changed by AI: (?:none recorded|(${dateText.source}) · run (${runIdText.source}) · files: (.+))$`);
23
22
  const historyHeading = new RegExp(`^### (${dateText.source}) · run (${runIdText.source})(?: · (.*))?$`);
23
+ const changeHeading = new RegExp(`^# (${dateText.source}) · run (${runIdText.source})(?: · (.*))?$`);
24
24
  const lessonLine = new RegExp(`^- (${dateText.source}) · ([^:]+): (.+)$`);
25
25
  const fileItem = new RegExp(`^\`?([^\`@\\s]+)\`?@(${hashText.source})$`);
26
- const sectionOrder = ['Current view', 'Lessons', 'History'];
26
+ const conflictMarker = /^(?:<{7} |={7}$|>{7} |\|{7} )/;
27
+ const recordItem = new RegExp(`^(.+)@(${hashText.source}|deleted)$`);
28
+ const newestFirst = (a, b) => { const when = entry => entry.fields.completed ?? entry.date; return when(a) < when(b) ? 1 : when(a) > when(b) ? -1 : a.run < b.run ? -1 : 1; };
29
+ const noNote = 'no component note recorded';
30
+ const sectionOrder = ['Current view', 'Lessons'];
27
31
  export const maxDocLines = 300;
28
32
 
29
- // Each rule is named in a lint issue so the fix is clear. They are structure rules only: a doc can
30
- // pass every one and still be wrong about the component.
33
+ // Each rule is named in a lint issue so the fix is clear. Structure only: a doc can pass every one
34
+ // and still be wrong. "Earlier layout" still has a Last-changed line and History; migrate converts it.
31
35
  export const rules = {
32
36
  name: `The file name is kebab-case (${docFileName.source}); INDEX.md, error-ledger.md and verify-recipe.md are not component docs.`,
33
37
  title: 'The first non-empty line is the only H1, naming the one component the doc covers.',
34
38
  covers: 'A "Covers:" line lists one or more project-relative path patterns (comma-separated, forward slashes, no parent segments).',
35
- 'last-change': 'A "Last changed by AI:" line reads "none recorded" or "<YYYY-MM-DD> · run <id> · files: <paths>".',
36
- sections: `The H2 sections are exactly ${sectionOrder.map(name => `"## ${name}"`).join(', ')}, once each, in that order.`,
39
+ sections: 'The H2 sections are exactly "## Current view" then "## Lessons"; the earlier layout ends with "## History".',
37
40
  'current-view': 'Current view has prose and no <placeholder> left from the template.',
38
41
  'lesson-dated': 'Every line under Lessons is a bullet "- <YYYY-MM-DD> · <source>: <lesson>".',
39
- 'history-entry': 'Every History entry heads with "### <YYYY-MM-DD> · run <id>", newest first, and nothing but entries appears under History.',
40
- evidence: 'Every History entry has a "**Files:**" line listing each file as path@<sha256 or commit>.',
41
- 'last-change-current': 'The "Last changed by AI" line names the newest History entry.',
42
- size: `The doc has at most ${maxDocLines} lines; consolidate older entries past that.`,
43
- 'toc-columns': 'The index table has Component (or Area), Covers, Doc (or Record), Last AI change and Lessons columns.',
42
+ size: `The doc has at most ${maxDocLines} lines.`,
43
+ 'last-change': 'Earlier layout: the "Last changed by AI:" line reads "none recorded" or "<YYYY-MM-DD> · run <id> · files: <paths>".',
44
+ 'history-entry': 'Earlier layout: every History entry heads with "### <YYYY-MM-DD> · run <id>", newest first, and nothing else appears under History.',
45
+ evidence: 'Earlier layout: every History entry has a "**Files:**" line listing each file as path@<sha256 or commit>.',
46
+ 'last-change-current': 'Earlier layout: the "Last changed by AI" line names the newest History entry.',
47
+ 'toc-columns': 'The index table has Component (or Area), Covers and Doc (or Record) columns, and no per-run columns (Last AI change, Lessons).',
44
48
  'toc-link': 'Every index Doc link resolves to an existing file.',
45
49
  'toc-unindexed': 'Every component doc in docs/context/ has exactly one index row.',
46
50
  'toc-covers': 'An index row\'s Covers equals its doc\'s Covers line.',
47
- 'toc-last-change': 'An index row\'s Last AI change starts with the doc\'s last-change date and run.',
48
- 'toc-lessons': 'An index row\'s Lessons cell starts with the doc\'s lesson count.',
49
- 'stale-against-git': 'A covered path was committed after the doc\'s last commit, so the doc may describe code that has changed.'
51
+ 'toc-conflict': 'The index has no merge conflict markers; cyc context index --write keeps both sides\' rows.',
52
+ 'stale-against-git': 'A covered path was committed after the doc and the change records that name it, so the doc may describe code that has changed.',
53
+ 'change-name': 'The changes folder holds only records named <YYYY-MM-DD>-<run>.md and digests named <YYYY-MM>.md.',
54
+ 'change-entry': 'A change entry heads with "# <YYYY-MM-DD> · run <id> · <goal>", has a "Result:" line and lists files as "- path@<hash>"; a record holds the one entry its name gives, a digest its month\'s.',
55
+ 'change-duplicate': 'A run has one change entry.'
50
56
  };
51
57
 
52
58
  const text = value => typeof value === 'string' && value.trim().length > 0;
@@ -138,18 +144,20 @@ export function parseDoc(source, name = 'doc.md') {
138
144
  } catch (error) { issue('covers', error.message, coversIndex); covers = []; }
139
145
  }
140
146
  const lastIndex = lines.findIndex(line => /^Last changed by AI:/.test(line));
147
+ // The earlier layout kept its history in the doc; it still parses, and migrate converts it.
148
+ const legacy = lastIndex !== -1 || lines.includes('## History');
141
149
  let lastChange = null;
142
- if (lastIndex === -1) issue('last-change', 'Missing "Last changed by AI:" line.');
143
- else {
150
+ if (legacy && lastIndex === -1) issue('last-change', 'Missing "Last changed by AI:" line.');
151
+ else if (legacy) {
144
152
  const match = lines[lastIndex].match(lastChangeLine);
145
153
  if (!match) issue('last-change', `Unreadable line: ${lines[lastIndex]}`, lastIndex);
146
154
  else lastChange = match[1] ? { date: match[1], run: match[2], files: match[3].split(',').map(p => p.trim().replaceAll('`', '')).filter(Boolean) } : 'none recorded';
147
155
  }
148
156
  const h2 = lines.map((line, index) => [line, index]).filter(([line]) => /^## /.test(line));
149
- const names = h2.map(([line]) => line.slice(3).trim());
150
- if (names.join('\n') !== sectionOrder.join('\n')) issue('sections', `Found sections: ${names.map(n => `"## ${n}"`).join(', ') || 'none'}.`);
157
+ const names = h2.map(([line]) => line.slice(3));
158
+ if (names.join('\n') !== [...sectionOrder, ...(legacy ? ['History'] : [])].join('\n')) issue('sections', `Found sections: ${names.map(n => `"## ${n}"`).join(', ') || 'none'}.`);
151
159
  const section = name => {
152
- const at = h2.findIndex(([line]) => line.slice(3).trim() === name);
160
+ const at = h2.findIndex(([line]) => line.slice(3) === name);
153
161
  if (at === -1) return null;
154
162
  const start = h2[at][1] + 1, end = at + 1 < h2.length ? h2[at + 1][1] : lines.length;
155
163
  return { start, lines: lines.slice(start, end) };
@@ -182,6 +190,9 @@ export function parseDoc(source, name = 'doc.md') {
182
190
  continue;
183
191
  }
184
192
  if (!entry) { if (line.trim()) issue('history-entry', 'Text under History outside an entry.', at); continue; }
193
+ const field = line.match(/^\*\*(Changed|Learned|Decisive check):\*\*\s*(.*)$/);
194
+ if (field) entry[field[1] === 'Decisive check' ? 'proof' : field[1].toLowerCase()] = field[2];
195
+ if (!field && line.trim() && !/^\*\*Files:\*\*/.test(line)) (entry.extra ??= []).push(line.trim());
185
196
  if (/^\*\*Files:\*\*/.test(line)) {
186
197
  entry.hasFiles = true;
187
198
  for (const item of line.slice('**Files:**'.length).split(',').map(s => s.trim()).filter(Boolean)) {
@@ -199,7 +210,7 @@ export function parseDoc(source, name = 'doc.md') {
199
210
  } else if (lastChange && lastChange !== 'none recorded') issue('last-change-current', 'Last changed names a run with no History entry.', lastIndex);
200
211
  }
201
212
  if (lines.length > maxDocLines) issue('size', `${lines.length} lines.`);
202
- return { name, title, covers, lastChange, lessons, history, currentView: view?.lines.join('\n').trim() ?? '', lines: lines.length, issues };
213
+ return { name, title, covers, layout: legacy ? 'earlier' : 'current', lastChange, lessons, history, currentView: view?.lines.join('\n').trim() ?? '', lines: lines.length, issues };
203
214
  }
204
215
 
205
216
  export function listDocs(root) {
@@ -220,22 +231,37 @@ const columnAliases = { component: ['component', 'area'], covers: ['covers'], do
220
231
 
221
232
  export function parseIndex(source) {
222
233
  const lines = source.replace(/^/, '').replaceAll('\r\n', '\n').split('\n');
223
- const table = { header: null, headerLine: -1, separatorLine: -1, columns: {}, rows: [], lines };
234
+ const table = { header: null, headerLine: -1, separatorLine: -1, columns: {}, rows: [], markers: [], lines };
235
+ let side = null, base = false;
224
236
  for (const [index, line] of lines.entries()) {
237
+ // Conflict markers inside the table are not rows: both sides' rows are read, and a side with its
238
+ // own header (the earlier five-column index) is read by column name. A conflict that opens on
239
+ // anything but a table row belongs to the prose below the table.
240
+ if (table.header && conflictMarker.test(line)) {
241
+ if (line[0] === '<' && !/^\s*\|/.test(lines[index + 1] ?? '')) break;
242
+ // In a three-way conflict the rows between "|||||||" and "=======" are the base, not a side.
243
+ base = line[0] === '|';
244
+ if (line[0] === '>') side = null;
245
+ table.markers.push(index); continue;
246
+ }
225
247
  if (!/^\s*\|/.test(line)) { if (table.header && (table.rows.length || table.separatorLine >= 0)) break; table.header = null; continue; }
226
- const cells = line.trim().replace(/^\||\|$/g, '').split(/(?<!\\)\|/).map(c => c.trim().replaceAll('\\|', '|'));
248
+ let cells = line.trim().replace(/^\||\|$/g, '').split(/(?<!\\)\|/).map(c => c.trim().replaceAll('\\|', '|'));
227
249
  if (!table.header) {
228
250
  if (!cells.some(c => c.toLowerCase() === 'covers')) continue;
229
251
  table.header = cells; table.headerLine = index;
230
252
  for (const [key, aliases] of Object.entries(columnAliases)) table.columns[key] = cells.findIndex(c => aliases.includes(c.toLowerCase()));
231
253
  continue;
232
254
  }
233
- if (cells.every(c => /^:?-+:?$/.test(c))) { table.separatorLine = index; continue; }
255
+ if (cells.every(c => /^:?-+:?$/.test(c))) { if (table.separatorLine < 0) { table.separatorLine = index; table.separator = cells; } continue; }
256
+ if (base) continue;
257
+ // A header inside the table is the other side of a conflict only when its separator row follows.
258
+ if (cells.some(c => c.toLowerCase() === 'covers') && /^\s*\|[\s:|-]+\|\s*$/.test(lines[index + 1] ?? '')) { side = cells.map(c => c.toLowerCase()); continue; }
259
+ if (side) cells = table.header.map(name => cells[side.indexOf(name.toLowerCase())] ?? '');
234
260
  if (cells.length !== table.header.length) { table.rows.push({ line: index, malformed: true, cells }); continue; }
235
261
  const cell = key => table.columns[key] >= 0 ? cells[table.columns[key]] : '';
236
262
  const links = contextLinks(cell('doc'));
237
263
  const link = cell('doc').match(/\[[^\]]+\]\(([^)#]+)[^)]*\)/);
238
- table.rows.push({ line: index, cells, component: cell('component'), covers: cell('covers').replaceAll('`', '').split(',').map(p => p.trim()).filter(Boolean), docText: cell('doc'), links, link: link ? decodeURIComponent(link[1]) : null, lastChange: cell('lastChange'), lessons: cell('lessons') });
264
+ table.rows.push({ line: index, cells, component: cell('component'), covers: cell('covers').replaceAll('`', '').split(',').map(p => p.trim()).filter(Boolean), docText: cell('doc'), links, link: link ? decodeURIComponent(link[1]) : null });
239
265
  }
240
266
  return table;
241
267
  }
@@ -254,10 +280,12 @@ function gitAvailable(root) {
254
280
  }
255
281
  const pathspec = pattern => pattern === 'all' ? '.' : /[?*]/.test(pattern) ? `:(glob)${pattern}` : pattern;
256
282
 
257
- // Freshness against Git: the doc's last commit against the last commit that touched a covered path.
258
- // Same commit, or the doc committed later, is fresh. Uncommitted edits to covered paths are reported
259
- // as dirty, never as stale: they have no commit yet, and the doc may be edited in the same change.
260
- export function docFreshness(root, docPath, covers) {
283
+ // Freshness against Git: the doc's last commit against the last commit touching a covered path.
284
+ // A run that revalidates a doc without rewording it leaves the bytes it verified in its change
285
+ // record, so a later covered commit makes the doc stale unless every covered file it moved is, as
286
+ // committed, what a record made after the doc's last commit verified. `records` are the committed
287
+ // entries naming the doc. Uncommitted covered edits are dirty, never stale: they have no commit yet.
288
+ export function docFreshness(root, docPath, covers, records = []) {
261
289
  if (!gitAvailable(root)) return { status: 'unknown', reason: 'Not a Git checkout; freshness was not compared.' };
262
290
  const last = args => { const r = git(root, ['log', '-1', '--format=%H%x09%cI%x09%s', ...args]); if (r.status !== 0) throw Error(r.stderr.trim() || 'git log failed'); const [commit, date, subject] = r.stdout.trim().split('\t'); return commit ? { commit, date, subject } : null; };
263
291
  let doc, coveredCommit;
@@ -272,7 +300,13 @@ export function docFreshness(root, docPath, covers) {
272
300
  // The doc's commit being an ancestor of the covered commit is decisive; dates only break a tie
273
301
  // across branches, and two commits in the same second compare equal by date.
274
302
  const later = coveredCommit.commit !== doc.commit && (git(root, ['merge-base', '--is-ancestor', doc.commit, coveredCommit.commit]).status === 0 || coveredCommit.date > doc.date);
275
- if (later) return { status: 'stale', docCommit: doc, coveredCommit, dirtyPaths };
303
+ if (later) {
304
+ const bound = new Map();
305
+ for (const entry of records) if (Date.parse(entry.fields.completed ?? `${entry.date}T23:59:59Z`) >= Date.parse(doc.date)) for (const file of entry.files) if (!bound.has(file.path)) bound.set(file.path, file.hash);
306
+ const committed = path => { const shown = spawnSync('git', ['-C', root, 'show', `${coveredCommit.commit}:./${path}`], { windowsHide: true, timeout: 5000, maxBuffer: 64 * 1024 * 1024 }); return shown.status === 0 ? `sha256:${sha(shown.stdout)}` : 'deleted'; };
307
+ const moved = git(root, ['diff', '--relative', '--name-only', '-z', doc.commit, coveredCommit.commit, '--', ...covers.map(pathspec)]);
308
+ if (moved.status !== 0 || moved.stdout.split('\0').filter(Boolean).some(path => bound.get(path) !== committed(path))) return { status: 'stale', docCommit: doc, coveredCommit, dirtyPaths };
309
+ }
276
310
  return { status: dirtyPaths.length ? 'dirty' : 'fresh', docCommit: doc, coveredCommit, dirtyPaths };
277
311
  }
278
312
 
@@ -289,7 +323,17 @@ export function lintIndex(root, { git: checkGit = true, docs: selectedDocs } = {
289
323
  }
290
324
  const table = parseIndex(read(root, indexName));
291
325
  if (!table.header) { issue('toc-columns', 'No table with a Covers column.'); return { path: indexName, exists, ok: false, rows: [], issues, freshness }; }
292
- for (const [key, index] of Object.entries(table.columns)) if (index === -1) issue('toc-columns', `Missing column ${columnAliases[key].join(' or ')}.`, table.headerLine);
326
+ for (const key of ['component', 'covers', 'doc']) if (table.columns[key] === -1) issue('toc-columns', `Missing column ${columnAliases[key].join(' or ')}.`, table.headerLine);
327
+ if (table.columns.lastChange >= 0 || table.columns.lessons >= 0) issue('toc-columns', 'Per-run columns (Last AI change, Lessons) are no longer kept; cyc context index --write drops them.', table.headerLine);
328
+ if (table.lines.some(line => conflictMarker.test(line))) issue('toc-conflict', 'Merge conflict markers remain; cyc context index --write keeps both sides\' rows.');
329
+ // Only committed records can vouch for a doc against Git; one written or edited since is not history yet.
330
+ const named = new Map();
331
+ if (checkGit) {
332
+ // Compared with HEAD, so a record that is untracked, modified or only staged is left out.
333
+ const changes = readChanges(root), listed = args => git(root, [...args, '--', changes.folder]).stdout?.split('\0') ?? [];
334
+ const loose = new Set([...listed(['ls-files', '-z', '-o']), ...listed(['diff', '--relative', '--name-only', '-z', 'HEAD'])]);
335
+ for (const entry of changes.entries) if (!loose.has(entry.file)) for (const { doc } of entry.components) named.set(doc, [...(named.get(doc) ?? []), entry]);
336
+ }
293
337
  const seen = new Map();
294
338
  const rows = [];
295
339
  for (const row of table.rows) {
@@ -307,12 +351,8 @@ export function lintIndex(root, { git: checkGit = true, docs: selectedDocs } = {
307
351
  const parsed = lintDoc(root, docPath);
308
352
  entry.docIssues = parsed.issues.length;
309
353
  if ([...parsed.covers].sort().join(',') !== [...row.covers].sort().join(',')) issue('toc-covers', `Row covers [${row.covers.join(', ')}] but ${docPath} covers [${parsed.covers.join(', ')}].`, row.line);
310
- const expectLast = parsed.lastChange && parsed.lastChange !== 'none recorded' ? `${parsed.lastChange.date} · run ${shortRun(parsed.lastChange.run)}` : 'none recorded';
311
- if (table.columns.lastChange >= 0 && !row.lastChange.startsWith(expectLast)) issue('toc-last-change', `Row says "${oneLine(row.lastChange, 60)}", the doc says "${expectLast}".`, row.line);
312
- const expectLessons = parsed.lessons.length ? String(parsed.lessons.length) : 'none';
313
- if (table.columns.lessons >= 0 && !(row.lessons === expectLessons || row.lessons.startsWith(`${expectLessons} `))) issue('toc-lessons', `Row says "${oneLine(row.lessons, 60)}", the doc has ${parsed.lessons.length} lesson(s).`, row.line);
314
354
  if (checkGit) {
315
- const fresh = docFreshness(root, docPath, parsed.covers);
355
+ const fresh = docFreshness(root, docPath, parsed.covers, named.get(docPath));
316
356
  freshness.push({ doc: docPath, ...fresh });
317
357
  if (fresh.status === 'stale') issue('stale-against-git', `${docPath}: ${fresh.coveredCommit.commit.slice(0, 7)} (${day(fresh.coveredCommit.date)}, ${oneLine(fresh.coveredCommit.subject, 60)}) touched covered paths after the doc's last commit ${fresh.docCommit.commit.slice(0, 7)} (${day(fresh.docCommit.date)}).`, row.line);
318
358
  }
@@ -321,7 +361,7 @@ export function lintIndex(root, { git: checkGit = true, docs: selectedDocs } = {
321
361
  return { path: indexName, exists, ok: !issues.length, rows, issues, freshness };
322
362
  }
323
363
 
324
- const docSummary = result => ({ path: result.path, ok: result.ok, issues: result.issues, lines: result.lines, lessons: result.lessons.length, history: result.history.length });
364
+ const docSummary = result => ({ path: result.path, ok: result.ok, layout: result.layout, issues: result.issues, lines: result.lines, lessons: result.lessons.length, history: result.history.length });
325
365
 
326
366
  export function lintContext(root, { doc, git: checkGit = true } = {}) {
327
367
  root = realpathSync(root);
@@ -331,8 +371,8 @@ export function lintContext(root, { doc, git: checkGit = true } = {}) {
331
371
  return { ok: result.ok, docs: [docSummary(result)], rules, note: 'Structure rules only: a passing doc can still be wrong about its component.' };
332
372
  }
333
373
  const docs = listDocs(root).map(name => docSummary(lintDoc(root, `${contextFolder}/${name}`)));
334
- const index = lintIndex(root, { git: checkGit });
335
- return { ok: docs.every(d => d.ok) && index.ok, index: { path: index.path, exists: index.exists, ok: index.ok, issues: index.issues, freshness: index.freshness }, docs, rules, note: 'Structure and freshness rules only: a passing doc can still be wrong about its component, and a fresh doc is one whose covered paths have no later commit, not one that is correct.' };
374
+ const index = lintIndex(root, { git: checkGit }), changes = readChanges(root);
375
+ return { ok: docs.every(d => d.ok) && index.ok && !changes.issues.length, index: { path: index.path, exists: index.exists, ok: index.ok, issues: index.issues, freshness: index.freshness }, docs, changes: { path: changes.folder, entries: changes.entries.length, issues: changes.issues }, rules, note: 'Structure and freshness rules only: a passing doc can still be wrong about its component, and a fresh doc is one whose covered paths have no later commit, not one that is correct.' };
336
376
  }
337
377
 
338
378
  // A current start plans records before scope freezes. Old stored runs without this
@@ -397,7 +437,7 @@ export function checkRetention(root, state, files) {
397
437
  }
398
438
  const index = lintIndex(root, { git: false, docs: plan.features.map(f => f.doc) });
399
439
  if (!index.exists) issue('toc-link', `Missing target index ${plan.index}.`);
400
- issues.push(...index.issues);
440
+ issues.push(...index.issues, ...readChanges(root).issues);
401
441
  for (const feature of plan.features) {
402
442
  const doc = feature.doc;
403
443
  if (!existsSync(local(root, doc))) { issue('feature-doc', `Missing canonical record for ${feature.id}.`, doc); continue; }
@@ -409,19 +449,10 @@ export function checkRetention(root, state, files) {
409
449
  if (!selected.paths.length || selected.paths.some(path => !covered(parsed.covers, path))) issue('feature-coverage', `Covers must resolve representative feature paths: ${selected.paths.join(', ') || 'none planned'}.`, doc);
410
450
  const rows = index.rows.filter(row => row.componentDoc && row.doc === doc);
411
451
  if (rows.length !== 1 || selected.paths.some(path => !covered(rows[0]?.covers ?? [], path))) issue('feature-index', 'A canonical resolving index row must map the feature entrypoints.', doc);
412
- const latest = parsed.history[0];
413
- if (parsed.history.filter(h => h.run === state.id).length !== 1) issue('feature-history', 'Keep exactly one entry for the current run.', doc);
414
- if (latest?.run !== state.id) issue('feature-history', 'Current feature work needs its own dated History entry before verification.', doc);
415
- if (!selected.files.length || !latest?.files.length) issue('feature-evidence', 'Current History needs actual selected source evidence.', doc);
416
- for (const item of latest?.files ?? []) {
417
- try {
418
- const path = canonicalPattern(item.path, { patterns: false });
419
- if (support(path, plan.folder) || !files[path] || !files[path].startsWith(item.hash.replace(/^sha256:/, ''))) issue('feature-evidence', `Missing/stale current source evidence: ${path}.`, doc);
420
- } catch (error) { issue('feature-evidence', error.message, doc); }
421
- }
422
- for (const item of selected.files) if (!latest?.files.some(f => f.path === item.path)) issue('feature-evidence', `No current source evidence for ${item.path}.`, doc);
452
+ // The run state, not a doc entry, binds the authored view to the bytes it was written against.
453
+ if (!selected.files.length) issue('feature-evidence', 'The record needs actual selected implementation source; supporting files and unrelated hashes cannot stand in.', doc);
423
454
  const authored = state.contextPreparation?.authored?.[feature.id];
424
- if (!authored || authored.viewHash !== sha(parsed.currentView) || authored.sourcesHash !== sha(JSON.stringify(selected.files))) issue('feature-authoring', 'Author or revalidate the focused Current view against this source; generated History alone is not retained feature knowledge.', doc);
455
+ if (!authored || authored.viewHash !== sha(parsed.currentView) || authored.sourcesHash !== sha(JSON.stringify(selected.files))) issue('feature-authoring', 'Author or revalidate the focused Current view against this source; a scaffold or an unchanged view after a source change is not retained feature knowledge.', doc);
425
456
  if (!files[doc] || !files[plan.index]) issue('feature-source', 'Canonical context/index must be included in verified source, not ignored runtime data.', doc);
426
457
  docs.push(doc);
427
458
  }
@@ -432,48 +463,44 @@ export function checkRetention(root, state, files) {
432
463
  return { ok: !issues.length, status: issues.length ? 'pending' : 'retained', docs, issues, note: 'Layout, mapping, provenance and source checks only; authored semantic truth and user acceptance are not certified.' };
433
464
  }
434
465
 
435
- // Only the caller's active, scoped runtime transaction may invoke this writer.
436
- // It uses observations available now; final receipts stay outside covered source.
437
- export function prepareRetention(root, state, { records = [], summary = '', reason = '' } = {}, files, permit) {
466
+ // Only the caller's active, scoped runtime transaction may invoke this writer. It writes what is
467
+ // true now: the authored Current view and an optional lesson. What the run did is its change record.
468
+ const filled = value => text(value) && !/^<[\s\S]*>$/.test(value.trim());
469
+ export function prepareRetention(root, state, { records = [] } = {}, files, permit) {
438
470
  const plan = retentionOf(state);
439
471
  if (!plan || plan.disposition !== 'required') return { paths: [], authored: {} };
440
- if (!Array.isArray(records) || new Set(records.map(r => r?.id)).size !== records.length || records.some(r => !plan.features.some(f => f.id === r?.id) || !text(r.currentView) || /<(?:write|describe|fill|actual|placeholder|todo)\b/i.test(r.currentView))) throw Error('learning.context needs unique planned ids and actual nonplaceholder currentView text.');
441
- const writes = [], authored = {};
472
+ if (!Array.isArray(records) || new Set(records.map(r => r?.id)).size !== records.length || records.some(r => !plan.features.some(f => f.id === r?.id) || !text(r.currentView) || /<(?:write|describe|fill|actual|placeholder|todo)\b/i.test(r.currentView) || ['changed', 'lesson'].some(key => r[key] !== undefined && !filled(r[key])))) throw Error('learning.context needs unique planned ids and actual nonplaceholder currentView text (and changed/lesson when given).');
473
+ const writes = [], authored = {}, bound = {}, notes = { ...state.contextPreparation?.notes };
442
474
  const date = state.contextPreparation?.date ?? new Date().toISOString().slice(0, 10);
443
475
  for (const feature of plan.features) {
444
476
  const exists = existsSync(local(root, feature.doc)), selected = featureFiles(root, state, feature, files);
445
477
  let source = exists ? read(root, feature.doc) : newDocSource(feature.id.replaceAll('-', ' '), selected.files.length ? selected.files.map(f => f.path) : selected.paths);
446
- let parsed = parseDoc(source, fileName(feature.doc));
447
- if (parsed.issues.some(i => ['sections', 'title', 'last-change'].includes(i.rule)) || parsed.issues.some(i => i.rule === 'last-change-current') && parsed.lastChange?.run !== state.id) throw Error(`Repair existing context metadata/history first: ${feature.doc}. Do not invent an older run entry.`);
478
+ if (parseDoc(source, fileName(feature.doc)).issues.some(i => ['sections', 'title', 'last-change', 'last-change-current'].includes(i.rule))) throw Error(`Repair existing context metadata/history first: ${feature.doc}. Do not invent an older run entry.`);
448
479
  const record = records.find(r => r.id === feature.id);
449
- if (record) source = source.replace(/(## Current view\n)[\s\S]*?(?=\n## Lessons)/, (_, heading) => `${heading}\n${record.currentView.trim()}\n`);
450
- parsed = parseDoc(source, fileName(feature.doc));
451
- const viewHash = sha(parsed.currentView), sourcesHash = sha(JSON.stringify(selected.files));
480
+ if (record) {
481
+ source = source.replace(/(## Current view\n)[\s\S]*?(?=\n## Lessons)/, (_, heading) => `${heading}\n${record.currentView.trim()}\n`);
482
+ if (record.changed) notes[feature.id] = oneLine(record.changed, 300);
483
+ // One lesson per run and component: a repeated preparation replaces it, never adds a second.
484
+ if (record.lesson) {
485
+ const lines = source.split('\n'), at = lines.indexOf('## Lessons'), end = lines.indexOf('## History');
486
+ const kept = lines.filter((line, i) => !(i > at && (end < 0 || i < end) && line.includes(` · run ${shortRun(state.id)}: `)));
487
+ kept.splice(at + 1, 0, '', `- ${date} · run ${shortRun(state.id)}: ${oneLine(record.lesson, 400)}`, '');
488
+ source = `${kept.join('\n').replace(/\n{3,}/g, '\n\n').replace(/\n*$/, '')}\n`;
489
+ }
490
+ }
491
+ const viewHash = sha(parseDoc(source, fileName(feature.doc)).currentView), sourcesHash = sha(JSON.stringify(selected.files));
452
492
  const prior = state.contextPreparation?.authored?.[feature.id];
453
493
  if (record || viewHash !== (state.contextPreparation?.views?.[feature.id] ?? feature.baselineViewHash) || prior?.viewHash === viewHash && prior.sourcesHash === sourcesHash) authored[feature.id] = { viewHash, sourcesHash };
454
- // Keep a repairable scaffold when no implementation anchor exists. Empty
455
- // evidence must not overwrite valid metadata with an unreadable History.
456
- if (!selected.files.length) {
457
- if (!exists || read(root, feature.doc) !== source) writes.push({ path: feature.doc, source });
458
- continue;
459
- }
460
- // Replace only this still-active run's preparation, preserving completed history.
461
- const lines = source.split('\n');
462
- for (const own of parsed.history.filter(h => h.run === state.id).reverse()) {
463
- const next = parsed.history.find(h => h.line > own.line);
464
- lines.splice(own.line - 1, (next ? next.line - 1 : source.split('\n').length) - (own.line - 1));
465
- }
466
- source = lines.join('\n');
467
- const entry = [`### ${date} · run ${state.id} · ${oneLine(state.goal, 100)}`, `**Changed:** ${oneLine(summary || state.goal, 400)}`, `**Learned:** ${oneLine(reason || 'See the authored Current view; no user acceptance is inferred.', 400)}`, `**Decisive check:** Planned commands: ${state.commands.map(c => [c.command, ...c.args].join(' ')).join('; ') || 'none'}. Final outcomes are not yet claimed; inspect run ${state.id} command receipts separately. Local receipts may not travel with source.`, `**Files:** ${selected.files.map(f => `${f.path}@sha256:${f.sha256}`).join(', ')}`].join('\n');
468
- source = applyEntry(source, { entry, lessons: [], lastChange: `Last changed by AI: ${date} · run ${state.id} · files: ${selected.files.map(f => f.path).join(', ')}` });
494
+ // Kept with the binding, so a record published later can still name the bytes this view was written against.
495
+ bound[feature.id] = selected.files;
469
496
  if (!exists || read(root, feature.doc) !== source) writes.push({ path: feature.doc, source });
470
497
  }
471
498
  for (const path of [...writes.map(w => w.path), plan.index]) { local(root, path); permit(path); }
472
499
  const staging = local(root, `.cyc/runs/${state.id}/context-staging`);
473
500
  for (const w of writes) { mkdirSync(dirname(local(root, w.path)), { recursive: true }); atomicWrite(local(root, w.path), w.source, staging); }
474
- if (!existsSync(local(root, plan.index))) { mkdirSync(dirname(local(root, plan.index)), { recursive: true }); atomicWrite(local(root, plan.index), '# Feature context\n\n| Component | Covers | Doc | Last AI change | Lessons |\n| --- | --- | --- | --- | --- |\n', staging); }
501
+ if (!existsSync(local(root, plan.index))) { mkdirSync(dirname(local(root, plan.index)), { recursive: true }); atomicWrite(local(root, plan.index), newIndexSource, staging); }
475
502
  refreshIndex(root, { staging, docs: plan.features.map(f => f.doc) });
476
- return { paths: writes.map(w => w.path), date, authored, views: Object.fromEntries(plan.features.map(f => [f.id, sha(parseDoc(read(root, f.doc), fileName(f.doc)).currentView)])) };
503
+ return { paths: writes.map(w => w.path), date, authored, selected: bound, notes, views: Object.fromEntries(plan.features.map(f => [f.id, sha(parseDoc(read(root, f.doc), fileName(f.doc)).currentView)])) };
477
504
  }
478
505
 
479
506
  // ---------------------------------------------------------------- run records
@@ -502,8 +529,8 @@ function ledgerEntriesFor(root, state) {
502
529
  return entries.filter(e => e.mentions).map(({ id, title, path }) => ({ id, title, path }));
503
530
  }
504
531
 
505
- // What a component doc entry needs, read from the run's own record: nothing here is invented, and
506
- // a field the run did not record is said to be missing.
532
+ // What a change record needs, read from the run's own state: nothing here is invented, and a field
533
+ // the run did not record is said to be missing.
507
534
  export function runRecord(root, state) {
508
535
  const { folder: contextFolder } = contextLocation(root);
509
536
  const passed = stage => state.handoffs.findLast(h => h.stage === stage && h.status === 'passed');
@@ -516,7 +543,6 @@ export function runRecord(root, state) {
516
543
  const files = (final?.artifacts ?? []).map(({ path, sha256 }) => ({ path, sha256 }));
517
544
  const learning = deliver?.assessment?.learning, errors = deliver?.assessment?.errorHistory;
518
545
  const retries = state.history.filter(h => h.type === 'retry' && text(h.reason)).map(h => h.reason);
519
- const failed = state.handoffs.filter(h => h.status === 'failed').map(h => h.summary);
520
546
  const proof = state.testProof;
521
547
  const exemption = verify?.assessment?.testProof;
522
548
  const checks = (state.verification?.results ?? []).map(r => `${r.id} ${r.passed ? 'passed' : 'failed'} (exit ${r.exitCode})`);
@@ -531,26 +557,104 @@ export function runRecord(root, state) {
531
557
  for (const reason of retries) lessons.push(`Retry: ${oneLine(reason, 400)}`);
532
558
  for (const entry of ledger) lessons.push(`Ledger ${entry.id}: ${entry.title}`);
533
559
  const contextDocs = (deliver?.contextDocs ?? files.map(f => f.path)).filter(p => isComponentDoc(p, contextFolder));
534
- return { runId: state.id, date, completedAt, goal: state.goal, playbook: state.playbook, status: state.status, session: state.session ?? null, files,
535
- changed: build.map(h => oneLine(h.summary.replace(/^Built: /, ''), 400)),
536
- learning: learning ? { status: learning.status, reason: oneLine(learning.reason, 400), artifacts: learning.artifacts ?? [] } : null,
537
- errorHistory: errors ? { status: errors.status, reason: oneLine(errors.reason, 400), artifacts: errors.artifacts ?? [] } : null,
538
- retries, failedHandoffs: failed, failures: state.failures ?? 0, ledgerEntries: ledger, decisiveCheck, checks, lessons: [...new Set(lessons)], contextDocs };
560
+ return { runId: state.id, date, completedAt, goal: state.goal, playbook: state.playbook, files, changed: build.map(h => oneLine(h.summary.replace(/^Built: /, ''), 400)), decisiveCheck, checks, lessons: [...new Set(lessons)], contextDocs };
561
+ }
562
+
563
+ // ---------------------------------------------------------------- change records
564
+
565
+ // <context folder>/changes holds one record per completed run, <date>-<run>.md, and monthly digests,
566
+ // <YYYY-MM>.md. Both are entries in one format, so a digest is its records joined.
567
+ function changeSource({ date, run, goal, result, completed, proof, changed, learned, components, files, full = false }) {
568
+ // A run's own record is kept short; migrated history is kept whole.
569
+ const line = (value, max = 2000) => oneLine(value, full ? Infinity : max).replaceAll('\\|', '|');
570
+ return [`# ${date} · run ${run} · ${line(goal, 100)}`, '', `Result: ${line(result)}`, ...(completed ? [`Completed: ${completed}`] : []), `Proof: ${line(proof)}`, `Changed: ${line(changed)}`, `Learned: ${line(learned)}`, '',
571
+ 'Components:', ...components.map(c => `- ${c.doc}: ${line(c.note || noNote)}`), '', 'Files:', ...files.map(f => `- ${f.path}@${f.hash}`), ''].join('\n');
572
+ }
573
+
574
+ export function parseChanges(source, file) {
575
+ const entries = [];
576
+ let entry = null, list = null;
577
+ for (const line of source.replace(/^/, '').replaceAll('\r\n', '\n').split('\n')) {
578
+ const head = line.match(changeHeading);
579
+ if (head) { entries.push(entry = { file, date: head[1], run: head[2], goal: head[3] ?? '', fields: {}, components: [], files: [], issues: [], lines: [] }); list = null; }
580
+ // Text before the first entry would be lost when records are joined, so it is reported.
581
+ if (!entry) { if (line.trim()) entries.stray = true; continue; }
582
+ entry.lines.push(line);
583
+ if (head || !line.trim()) continue;
584
+ const field = line.match(/^(Result|Completed|Proof|Changed|Learned|Components|Files):\s*(.*)$/);
585
+ const item = line.match(/^- (.+)$/);
586
+ // A path may hold spaces or "@": the hash is what follows the last "@".
587
+ const bound = list === 'Files' && item?.[1].match(recordItem);
588
+ if (field) { list = ['Components', 'Files'].includes(field[1]) ? field[1] : null; if (!list) entry.fields[field[1].toLowerCase()] = field[2]; }
589
+ else if (list === 'Components' && item) { const at = item[1].indexOf(': '); entry.components.push({ doc: at < 0 ? item[1] : item[1].slice(0, at), note: at < 0 || item[1].slice(at + 2) === noNote ? '' : item[1].slice(at + 2) }); }
590
+ else if (bound) entry.files.push({ path: bound[1], hash: bound[2] });
591
+ else entry.issues.push(`Unreadable line: ${oneLine(line, 80)}`);
592
+ }
593
+ for (const item of entries) item.source = `${item.lines.join('\n').replace(/\n*$/, '')}\n`;
594
+ return entries;
595
+ }
596
+
597
+ // Every entry in the changes folder, newest first, with the folder's lint issues.
598
+ export function readChanges(root) {
599
+ const folder = `${contextLocation(root).folder}/changes`, path = local(root, folder), entries = [], issues = [], files = [];
600
+ const issue = (rule, message) => issues.push({ rule, message });
601
+ for (const name of existsSync(path) ? readdirSync(path).sort() : []) {
602
+ const file = `${folder}/${name}`;
603
+ if (!changeFile.test(name) || !lstatSync(join(path, name)).isFile()) { issue('change-name', `${file} is not a change record or a monthly digest.`); continue; }
604
+ files.push(name);
605
+ const found = parseChanges(read(root, file), file), digest = name.length === 10;
606
+ if (!found.length || found.stray || (digest ? found.some(e => !e.date.startsWith(name.slice(0, 7))) : found.length !== 1 || found[0].date !== name.slice(0, 10) || !found[0].run.startsWith(name.slice(11, -3)))) issue('change-entry', `${file} does not hold ${digest ? 'only entries of its month' : 'the one entry its name gives'}.`);
607
+ for (const entry of found) {
608
+ if (!entry.fields.result || entry.issues.length) issue('change-entry', `${file}, run ${entry.run}: ${entry.issues[0] ?? 'no "Result:" line.'}`);
609
+ if (entries.some(e => e.run === entry.run)) issue('change-duplicate', `Run ${entry.run} has more than one entry; the second is in ${file}.`);
610
+ entries.push(entry);
611
+ }
612
+ }
613
+ entries.sort(newestFirst);
614
+ return { folder, files, entries, issues };
539
615
  }
540
616
 
541
- function entryMarkdown(record, files) {
542
- const learned = record.lessons.length ? record.lessons.join(' ') : 'No reusable learning recorded for this run.';
543
- return [
544
- `### ${record.date} · run ${record.runId} · ${oneLine(record.goal, 100)}`,
545
- `**Changed:** ${record.changed.join(' ') || 'No Build summary recorded.'}`,
546
- `**Learned:** ${learned}`,
547
- `**Decisive check:** ${record.decisiveCheck}${record.checks.length ? ` Checks: ${record.checks.join(', ')}.` : ''}`,
548
- `**Files:** ${files.map(f => `${f.path}@sha256:${f.sha256.slice(0, 12)}`).join(', ')}`
549
- ].join('\n');
617
+ // A completed run's record, from its own state. `files` are the verified bytes at completion; a
618
+ // later catch-up has only the delivery handoff's hashes. Only a run that planned a doc names it:
619
+ // a record that names a doc says the run verified the doc against these bytes.
620
+ export function changeFor(root, state, files) {
621
+ if (state.status !== 'complete') throw Error(`Run ${state.id} is ${state.status}; only a completed run leaves a change record.`);
622
+ const { folder } = contextLocation(root), plan = retentionOf(state), record = runRecord(root, state);
623
+ const planned = plan?.disposition === 'required', source = path => !support(path, folder);
624
+ const bound = planned && files
625
+ ? [...[...new Set([...Object.keys(files).filter(p => files[p] !== state.initialSource.files[p]), ...plan.features.flatMap(f => featureFiles(root, state, f, files).files.map(item => item.path))])].filter(source).map(path => ({ path, hash: `sha256:${files[path]}` })),
626
+ ...Object.keys(state.initialSource.files).filter(p => !(p in files) && source(p)).map(path => ({ path, hash: 'deleted' }))].sort((a, b) => a.path < b.path ? -1 : 1)
627
+ : [...new Map([...record.files, ...Object.values(state.contextPreparation?.selected ?? {}).flat()].filter(f => source(f.path)).map(f => [f.path, { path: f.path, hash: `sha256:${f.sha256}` }])).values()];
628
+ const accepted = state.verification?.acceptedPreexistingFailures ?? [];
629
+ const result = !state.requiresChecks ? 'completed · no executable checks, agent-reviewed evidence'
630
+ : `passed${accepted.length ? ` with accepted pre-existing failures (${accepted.join(', ')})` : ''} · ${record.checks.join(', ') || 'check results not recorded'}`;
631
+ return { name: `${record.date}-${shortRun(state.id)}.md`, source: changeSource({ date: record.date, run: state.id, goal: state.goal, result, completed: record.completedAt, proof: record.decisiveCheck, changed: record.changed.join(' ') || 'No Build summary recorded.', learned: record.lessons.join(' ') || 'No reusable learning recorded for this run.',
632
+ components: planned ? plan.features.map(f => ({ doc: f.doc, note: state.contextPreparation?.notes?.[f.id] })) : [], files: bound }) };
633
+ }
634
+
635
+ // Published once per run. Catch-up keeps an entry that is already there; the completing run
636
+ // (`files` given) owns its record, so entries it did not write are removed, never adopted.
637
+ export function publishChange(root, state, files) {
638
+ const staging = local(root, `.cyc/runs/${state.id}/context-staging`);
639
+ let known = readChanges(root);
640
+ const mine = known.entries.filter(entry => entry.run === state.id);
641
+ if (mine.length && !files) return { path: mine[0].file, created: false };
642
+ const change = changeFor(root, state, files);
643
+ if (mine.length === 1 && mine[0].source === change.source) return { path: mine[0].file, created: false };
644
+ for (const file of new Set(mine.map(entry => entry.file))) {
645
+ const rest = parseChanges(read(root, file)).filter(entry => entry.run !== state.id);
646
+ if (rest.length) atomicWrite(local(root, file), rest.map(entry => entry.source).join('\n'), staging);
647
+ else unlinkSync(local(root, file));
648
+ }
649
+ if (mine.length) known = readChanges(root);
650
+ const name = known.files.includes(change.name) ? `${change.name.slice(0, 11)}${state.id}.md` : change.name;
651
+ if (known.files.includes(name)) throw Error(`${known.folder}/${name} already holds another entry; remove it.`);
652
+ mkdirSync(local(root, known.folder), { recursive: true });
653
+ atomicWrite(local(root, `${known.folder}/${name}`), change.source, staging);
654
+ return { path: `${known.folder}/${name}`, created: true };
550
655
  }
551
- const lessonBullets = record => record.lessons.map(lesson => `- ${record.date} · run ${shortRun(record.runId)}: ${lesson}`);
552
656
 
553
- // ---------------------------------------------------------------- review: propose and write
657
+ // ---------------------------------------------------------------- review: propose and publish
554
658
 
555
659
  function componentsOf(root) {
556
660
  const { folder: contextFolder, index: indexName } = contextLocation(root);
@@ -563,187 +667,186 @@ function componentsOf(root) {
563
667
  return { exists, components };
564
668
  }
565
669
 
670
+ // Runs that already have a record: a change entry, or a History entry in a doc of the earlier layout.
566
671
  function recordedRuns(root, docs) {
567
- const { folder: contextFolder } = contextLocation(root);
568
- const runs = new Map();
569
- for (const name of docs) {
570
- const parsed = parseDoc(read(root, `${contextFolder}/${name}`), name);
571
- for (const entry of parsed.history) runs.set(entry.run, [...(runs.get(entry.run) ?? []), `${contextFolder}/${name}`]);
672
+ const { folder } = contextLocation(root), runs = new Map();
673
+ for (const entry of readChanges(root).entries) runs.set(entry.run, { file: entry.file, docs: new Set() });
674
+ for (const name of docs) for (const entry of parseDoc(read(root, `${folder}/${name}`), name).history) {
675
+ const known = runs.get(entry.run) ?? { file: null, docs: new Set() };
676
+ known.docs.add(`${folder}/${name}`);
677
+ runs.set(entry.run, known);
572
678
  }
573
679
  return runs;
574
680
  }
575
681
 
682
+ const newIndexSource = '# Context index\n\nRead this index first, then only the docs whose Covers match the paths you are about to change.\n\n| Component | Covers | Doc |\n| --- | --- | --- |\n';
576
683
  function newDocSource(title, covers) {
577
- return `# ${title}\n\nCovers: ${covers.join(', ')}\n\nLast changed by AI: none recorded\n\n## Current view\n\n<Write what the code cannot tell a reader: the invariant, its writers and readers, the adopted decisions and the known dead ends.>\n\n## Lessons\n\n## History\n`;
578
- }
579
-
580
- // Insert the entry under History and the lessons under Lessons, newest first, and set the
581
- // last-change line. The Current view is the author's; it is never edited here.
582
- export function applyEntry(source, { entry, lessons, lastChange }) {
583
- const lines = source.replaceAll('\r\n', '\n').split('\n');
584
- const at = name => lines.findIndex(line => line === `## ${name}`);
585
- const history = at('History'), lessonsAt = at('Lessons'), last = lines.findIndex(line => /^Last changed by AI:/.test(line));
586
- if (history === -1 || lessonsAt === -1 || last === -1) throw Error('The doc lacks the fixed layout (Last changed by AI line, ## Lessons, ## History); fix it with cyc context lint before writing to it.');
587
- const entryDate = entry.split('\n')[0].match(historyHeading)?.[1];
588
- const existing = lines.flatMap((line, index) => index > history && historyHeading.test(line) ? [{ index, date: line.match(historyHeading)[1] }] : []);
589
- const insertion = existing.find(item => item.date <= entryDate)?.index ?? (existing.length ? lines.length : history + 1);
590
- lines.splice(insertion, 0, '', ...entry.split('\n'), '');
591
- if (lessons.length) {
592
- const bullets = lines.flatMap((line, index) => index > lessonsAt && index < at('History') && lessonLine.test(line) ? [{ index, date: line.match(lessonLine)[1] }] : []);
593
- const lessonDate = lessons[0].match(lessonLine)?.[1];
594
- const first = bullets.find(item => item.date <= lessonDate)?.index ?? (bullets.length ? at('History') : lessonsAt + 1);
595
- lines.splice(first, 0, '', ...lessons);
596
- }
597
- // Catching up an older missing run must not relabel a newer current view.
598
- if (!existing.length || entryDate >= existing[0].date) lines[last] = lastChange;
599
- return `${lines.join('\n').replace(/\n{3,}/g, '\n\n').replace(/\n*$/, '')}\n`;
600
- }
601
-
602
- function indexCells(root, docPath) {
603
- const parsed = parseDoc(read(root, docPath), fileName(docPath));
604
- const last = parsed.lastChange && parsed.lastChange !== 'none recorded' ? `${parsed.lastChange.date} · run ${shortRun(parsed.lastChange.run)}${parsed.history[0]?.title ? ` · ${oneLine(parsed.history[0].title, 80)}` : ''}` : 'none recorded';
605
- const lessons = parsed.lessons.length ? `${parsed.lessons.length} · latest: ${oneLine(parsed.lessons[0].text, 80)}` : 'none';
606
- return { parsed, last, lessons };
607
- }
608
-
609
- export function refreshIndex(root, { staging, docs } = {}) {
610
- const { folder: contextFolder, index: indexName } = contextLocation(root);
611
- const table = parseIndex(read(root, indexName));
612
- if (!table.header) throw Error(`${indexName} has no table with a Covers column.`);
613
- const lines = table.lines;
614
- const columns = { ...table.columns };
615
- const width = table.header.length;
616
- const added = [];
617
- for (const [key, label] of [['lastChange', 'Last AI change'], ['lessons', 'Lessons']]) if (columns[key] === -1) { columns[key] = width + added.length; added.push(label); }
618
- const render = cells => `| ${cells.map(c => c.replaceAll('|', '\\|')).join(' | ')} |`;
619
- if (added.length) {
620
- lines[table.headerLine] = render([...table.header, ...added]);
621
- if (table.separatorLine >= 0) lines[table.separatorLine] = render([...Array(width + added.length)].map(() => '---'));
622
- }
623
- const seen = new Set();
684
+ return `# ${title}\n\nCovers: ${covers.join(', ')}\n\n## Current view\n\n<Write what the code cannot tell a reader: the invariant, its writers and readers, the adopted decisions and the known dead ends.>\n\n## Lessons\n`;
685
+ }
686
+
687
+ // Rebuild the index from the docs: Covers follows each doc, the earlier per-run columns are dropped,
688
+ // a new doc's row goes in sorted position so two branches seldom add at the same line, and a merge
689
+ // conflict keeps both sides' rows, one per doc. Other rows and columns stay as written.
690
+ export function refreshIndex(root, { staging, docs, write = true } = {}) {
691
+ const { folder, index } = contextLocation(root);
692
+ const table = parseIndex(read(root, index));
693
+ if (!table.header) throw Error(`${index} has no table with a Covers column.`);
694
+ const dropped = ['lastChange', 'lessons'].map(key => table.columns[key]).filter(at => at >= 0);
695
+ const render = cells => `| ${cells.filter((_, at) => !dropped.includes(at)).map(c => c.replaceAll('|', '\\|')).join(' | ')} |`;
696
+ const rows = [], seen = new Set();
624
697
  for (const row of table.rows) {
625
- if (row.malformed) continue;
626
- const docPath = resolveLink(root, row.link);
627
- const cells = [...row.cells, ...added.map(() => '')];
628
- if (isComponentDoc(docPath, contextFolder) && existsSync(local(root, docPath))) {
629
- seen.add(docPath);
630
- if (!docs || docs.includes(docPath)) {
631
- const { parsed, last, lessons } = indexCells(root, docPath);
632
- if (parsed.covers.length) cells[columns.covers] = parsed.covers.join(', ');
633
- cells[columns.lastChange] = last; cells[columns.lessons] = lessons;
634
- }
698
+ if (row.malformed) { rows.push({ text: table.lines[row.line] }); continue; }
699
+ const doc = resolveLink(root, row.link), owned = isComponentDoc(doc, folder) && existsSync(local(root, doc)), cells = [...row.cells];
700
+ if (owned && seen.has(doc)) continue;
701
+ if (owned) {
702
+ seen.add(doc);
703
+ const covers = !docs || docs.includes(doc) ? parseDoc(read(root, doc), fileName(doc)).covers : [];
704
+ if (covers.length) cells[table.columns.covers] = covers.join(', ');
635
705
  }
636
- lines[row.line] = render(cells);
706
+ rows.push({ text: render(cells), doc: owned ? doc : null });
637
707
  }
638
- const lastRow = table.rows.length ? table.rows.at(-1).line : table.separatorLine;
639
- const appended = [];
708
+ let addedRows = 0;
640
709
  for (const name of listDocs(root)) {
641
- const docPath = `${contextFolder}/${name}`;
642
- if (seen.has(docPath) || docs && !docs.includes(docPath)) continue;
643
- const { parsed, last, lessons } = indexCells(root, docPath);
644
- const cells = [...Array(width + added.length)].map(() => '');
645
- if (columns.component >= 0) cells[columns.component] = parsed.title ?? name;
646
- cells[columns.covers] = parsed.covers.join(', ');
647
- cells[columns.doc] = `[${parsed.title ?? name}](${name})`;
648
- cells[columns.lastChange] = last; cells[columns.lessons] = lessons;
649
- appended.push(render(cells));
650
- }
651
- lines.splice(lastRow + 1, 0, ...appended);
652
- const content = `${lines.join('\n').replace(/\n*$/, '')}\n`;
653
- if (read(root, indexName) !== content) atomicWrite(local(root, indexName), content, staging);
654
- return { addedColumns: added, addedRows: appended.length };
655
- }
656
-
657
- export function reviewContext(root, { run, since, all = false, write = false, newDoc, updateRun } = {}) {
710
+ const doc = `${folder}/${name}`;
711
+ if (seen.has(doc) || docs && !docs.includes(doc)) continue;
712
+ const parsed = parseDoc(read(root, doc), name), cells = table.header.map(() => '');
713
+ if (table.columns.component >= 0) cells[table.columns.component] = parsed.title ?? name;
714
+ cells[table.columns.covers] = parsed.covers.join(', ');
715
+ cells[table.columns.doc] = `[${parsed.title ?? name}](${name})`;
716
+ const owned = rows.flatMap((row, at) => row.doc ? [at] : []);
717
+ rows.splice(owned.find(at => rows[at].doc > doc) ?? (owned.length ? owned.at(-1) + 1 : rows.length), 0, { text: render(cells), doc });
718
+ addedRows++;
719
+ }
720
+ // A conflict that opens just above the header covers the whole table, so its opening marker goes too.
721
+ const opened = /^<{7} /.test(table.lines[table.headerLine - 1] ?? '') ? 1 : 0, count = mark => table.markers.filter(at => table.lines[at][0] === mark).length;
722
+ if (count('<') + opened !== count('=') || count('=') !== count('>')) throw Error(`${index} has a merge conflict that reaches beyond its table; resolve it by hand.`);
723
+ const start = table.headerLine - opened;
724
+ const end = Math.max(table.headerLine, table.separatorLine, ...table.rows.map(row => row.line), ...table.markers);
725
+ const content = `${[...table.lines.slice(0, start), render(table.header), render(table.separator ?? table.header.map(() => '---')), ...rows.map(row => row.text), ...table.lines.slice(end + 1)].join('\n').replace(/\n*$/, '')}\n`;
726
+ const current = read(root, index) === content;
727
+ if (write && !current) atomicWrite(local(root, index), content, staging);
728
+ return { current, addedRows, droppedColumns: dropped.map(at => table.header[at]) };
729
+ }
730
+
731
+ export function indexContext(root, { write = false } = {}) {
732
+ root = realpathSync(root);
733
+ const { index } = contextLocation(root);
734
+ if (!existsSync(local(root, index))) throw Error(`${index} does not exist.`);
735
+ const result = refreshIndex(root, { write });
736
+ const conflict = read(root, index).split('\n').some(line => conflictMarker.test(line));
737
+ return { ok: !conflict && (write || result.current), path: index, ...result, written: write && !result.current, ...(conflict ? { conflict: 'Merge conflict markers remain outside the table rows; resolve them by hand.' } : {}) };
738
+ }
739
+
740
+ // Completed runs that lack a change record. --write publishes them from the runs' own state and
741
+ // never edits a doc: a doc that should have changed needs a normal run that plans it.
742
+ export function reviewContext(root, { run, since, all = false, write = false } = {}) {
658
743
  root = realpathSync(root);
659
- const { folder: contextFolder, index: indexName } = contextLocation(root);
660
- if (newDoc !== undefined && (!docFileName.test(`${newDoc}.md`) || reservedDocs.has(`${newDoc}.md`))) throw Error(`--new needs a kebab-case component name (${docFileName.source} without .md).`);
661
744
  if (since !== undefined && !/^\d{4}-\d{2}-\d{2}$/.test(since)) throw Error('--since needs YYYY-MM-DD.');
662
- const { exists, components } = componentsOf(root);
663
- const docs = listDocs(root);
664
- const recorded = recordedRuns(root, docs);
745
+ const recorded = recordedRuns(root, listDocs(root));
665
746
  let states;
666
747
  if (run) {
667
748
  const state = readRun(root, run);
668
749
  if (state.status !== 'complete') throw Error(`Run ${run} is ${state.status}; context proposals come from completed runs.`);
669
750
  states = [state];
670
751
  } else states = completedRuns(root);
671
- const records = states.map(state => runRecord(root, state)).filter(record => !since || record.date >= since).sort((a, b) => a.completedAt.localeCompare(b.completedAt) || a.runId.localeCompare(b.runId));
672
- const proposals = [];
673
- const unmappedAll = new Map();
674
- for (const record of records) {
675
- const perComponent = new Map();
676
- const unmapped = [];
677
- const retained = new Set([...record.contextDocs, ...(record.learning?.artifacts ?? []), ...(record.errorHistory?.artifacts ?? [])]);
678
- for (const file of record.files) {
679
- if (file.path.startsWith('.cyc/') || [indexName, `${contextFolder}/error-ledger.md`, `${contextFolder}/verify-recipe.md`, `${contextFolder}/recipes.json`].includes(file.path)) continue;
680
- let mapped = false;
681
- for (const component of components) {
682
- if (!covered(component.covers, file.path)) continue;
683
- mapped = true;
684
- const key = component.doc ?? component.component;
685
- if (!perComponent.has(key)) perComponent.set(key, { ...component, files: [] });
686
- perComponent.get(key).files.push(file);
687
- }
688
- if (!mapped && !retained.has(file.path) && !file.path.startsWith('.cyc/')) unmapped.push(file);
689
- }
690
- const proposal = { runId: record.runId, date: record.date, goal: record.goal, playbook: record.playbook, contextDocsTouched: record.contextDocs,
691
- components: [...perComponent.values()].map(component => {
692
- const alreadyRecorded = (recorded.get(record.runId) ?? []).includes(component.doc);
693
- const touched = !!component.doc && (record.contextDocs.includes(component.doc) || (record.learning?.artifacts ?? []).includes(component.doc));
694
- return { component: component.component, doc: component.doc, writable: component.inFolder, touched, alreadyRecorded, shouldHaveBeenTouched: !touched && component.inFolder, files: component.files, entry: entryMarkdown(record, component.files), lessons: lessonBullets(record) };
695
- }),
696
- unmapped, lessons: record.lessons, decisiveCheck: record.decisiveCheck, learning: record.learning, errorHistory: record.errorHistory, ledgerEntries: record.ledgerEntries };
697
- // A run is caught up only when every writable component has its entry and no changed file
698
- // remains unmapped. Explicit --run/--all keep the complete diagnostic view.
699
- if (!run && !all && recorded.has(record.runId) && !unmapped.length && !proposal.components.some(component => component.writable && !component.alreadyRecorded)) continue;
700
- if (unmapped.length && newDoc) {
701
- const path = `${contextFolder}/${newDoc}.md`;
702
- proposal.newDoc = { path, covers: unmapped.map(f => f.path), entry: entryMarkdown(record, unmapped), lessons: lessonBullets(record), exists: existsSync(local(root, path)) };
703
- }
704
- for (const file of unmapped) unmappedAll.set(file.path, [...(unmappedAll.get(file.path) ?? []), record.runId]);
705
- proposals.push(proposal);
706
- }
707
- const result = { ok: true, index: { path: indexName, exists, components: components.length, componentDocs: docs.length }, runs: proposals, unmappedFiles: [...unmappedAll].map(([path, runs]) => ({ path, runs })), written: null,
708
- note: write ? 'Entries were appended from the runs\' own records; the Current view of each doc is yours to update. Review the diff before committing.' : 'Read-only proposal from completed run records: nothing was written. Add --write to append these entries and refresh the index; --new NAME creates a doc for unmapped files.' };
752
+ const pending = [];
753
+ const runs = states.map(state => ({ state, record: runRecord(root, state) })).filter(({ record }) => !since || record.date >= since)
754
+ .sort((a, b) => a.record.completedAt.localeCompare(b.record.completedAt) || a.record.runId.localeCompare(b.record.runId)).flatMap(({ state, record }) => {
755
+ const known = recorded.get(record.runId);
756
+ // Explicit --run/--all also list runs that already have a record.
757
+ if (known && !run && !all) return [];
758
+ if (!known) pending.push(state);
759
+ return [{ runId: record.runId, date: record.date, goal: record.goal, playbook: record.playbook, contextDocsTouched: record.contextDocs, record: known?.file ?? null, earlierDocs: [...(known?.docs ?? [])], ...(known ? {} : { change: changeFor(root, state) }) }];
760
+ });
761
+ const result = { ok: true, runs, written: null, note: `${write ? 'Records were published from the runs\' own state; no doc was edited.' : 'Read-only: --write publishes each missing change record.'} A doc that should have changed needs a normal run that plans it.` };
709
762
  if (!write) return result;
710
- if (!updateRun) throw Error('Completed-run catch-up needs a new active scoped update: context review --run SOURCE_ID --write --update-run UPDATE_ID. Use context prepare for current work; a reply packet cannot verify changed context.');
711
- const writePaths = [...new Set([indexName, ...proposals.flatMap(p => [...p.components.filter(c => c.writable && !c.alreadyRecorded).map(c => c.doc), ...(p.newDoc ? [p.newDoc.path] : [])])])];
712
- return contextUpdate(root, updateRun, writePaths, state => {
713
- const retention = retentionOf(state);
714
- if (!state.requiresChecks || !state.commands.length || retention?.disposition !== 'required' || writePaths.some(path => path !== indexName && !retention.features.some(f => f.doc === path))) throw Error('Catch-up needs a required feature-context plan covering these records and executable final verification. Start an implementation update with those canonical docs before Build; advisory catch-up cannot complete the repair.');
715
- const staging = local(root, `.cyc/runs/${updateRun}/context-staging`);
716
- const written = [];
717
- for (const proposal of proposals) {
718
- for (const component of proposal.components) {
719
- if (!component.writable || component.alreadyRecorded) continue;
720
- const source = read(root, component.doc);
721
- const parsed = parseDoc(source, fileName(component.doc));
722
- const blocking = parsed.issues.filter(i => ['sections', 'last-change', 'title'].includes(i.rule));
723
- if (blocking.length) { written.push({ doc: component.doc, runId: proposal.runId, written: false, reason: `Fix first: ${blocking.map(i => `${i.rule} (${i.message})`).join('; ')}` }); continue; }
724
- const lastChange = `Last changed by AI: ${proposal.date} · run ${proposal.runId} · files: ${component.files.map(f => f.path).join(', ')}`;
725
- atomicWrite(local(root, component.doc), applyEntry(source, { entry: component.entry, lessons: component.lessons, lastChange }), staging);
726
- recorded.set(proposal.runId, [...(recorded.get(proposal.runId) ?? []), component.doc]);
727
- written.push({ doc: component.doc, runId: proposal.runId, written: true });
728
- }
729
- if (proposal.newDoc) {
730
- const { path, covers, entry, lessons } = proposal.newDoc;
731
- const title = newDoc.split('-').map((w, i) => i ? w : w[0].toUpperCase() + w.slice(1)).join(' ');
732
- const source = existsSync(local(root, path)) ? read(root, path) : newDocSource(title, covers);
733
- if (parseDoc(source, `${newDoc}.md`).history.some(e => e.run === proposal.runId)) continue;
734
- mkdirSync(dirname(local(root, path)), { recursive: true });
735
- atomicWrite(local(root, path), applyEntry(source, { entry, lessons, lastChange: `Last changed by AI: ${proposal.date} · run ${proposal.runId} · files: ${covers.join(', ')}` }), staging);
736
- written.push({ doc: path, runId: proposal.runId, written: true, created: !proposal.newDoc.exists });
763
+ const written = pending.map(state => ({ runId: state.id, ...publishChange(root, state) }));
764
+ const lint = lintContext(root, { git: false });
765
+ return { ...result, written, lint: { ok: lint.ok, index: lint.index.issues, docs: lint.docs.filter(d => !d.ok).map(d => ({ path: d.path, issues: d.issues })), changes: lint.changes.issues } };
766
+ }
767
+
768
+ // A component's history: the entries that name its doc or changed a file it covers, newest first.
769
+ export function historyContext(root, { doc } = {}) {
770
+ root = realpathSync(root);
771
+ const { folder } = contextLocation(root), path = !doc ? null : /[\\/]/.test(doc) ? doc.replaceAll('\\', '/') : `${folder}/${doc.replace(/\.md$/, '')}.md`;
772
+ if (path && !(isComponentDoc(path, folder) && existsSync(local(root, path)))) throw Error(`${path} is not a component doc in ${folder}.`);
773
+ const covers = path ? parseDoc(read(root, path), fileName(path)).covers : [], own = file => !path || covered(covers, file.path);
774
+ const entries = readChanges(root).entries.filter(entry => !path || entry.components.some(c => c.doc === path) || entry.files.some(own))
775
+ .map(entry => ({ date: entry.date, run: entry.run, goal: entry.goal, result: entry.fields.result ?? 'not recorded', changed: entry.components.find(c => c.doc === path)?.note || entry.fields.changed, learned: entry.fields.learned, proof: entry.fields.proof, files: entry.files.filter(own).map(f => f.path), record: entry.file }));
776
+ return { ok: true, doc: path, entries, note: 'Each entry is what that run recorded at completion, not the state of the code now.' };
777
+ }
778
+
779
+ // A month's digest holds its entries, newest first. A run already in it is kept as written; a
780
+ // record that says something else for that run is a conflict to resolve, not text to drop.
781
+ function writeDigest(root, folder, month, entries) {
782
+ const path = `${folder}/${month}.md`, all = new Map();
783
+ for (const entry of [...(existsSync(local(root, path)) ? parseChanges(read(root, path), path) : []), ...entries]) {
784
+ if (!all.has(entry.run)) all.set(entry.run, entry);
785
+ else if (all.get(entry.run).source !== entry.source) throw Error(`Run ${entry.run} has two entries with different text for ${month}; keep one before folding.`);
786
+ }
787
+ mkdirSync(local(root, folder), { recursive: true });
788
+ atomicWrite(local(root, path), [...all.values()].sort(newestFirst).map(entry => entry.source).join('\n'), local(root, '.cyc/runtime/context-staging'));
789
+ if (parseChanges(read(root, path), path).length !== all.size) throw Error(`${path} did not keep every entry; nothing was removed.`);
790
+ }
791
+
792
+ // Fold earlier months' records into their digests. A record is removed only once its digest holds it.
793
+ export function rollupContext(root, { before = new Date().toISOString().slice(0, 7), write = false } = {}) {
794
+ root = realpathSync(root);
795
+ if (!/^\d{4}-\d{2}$/.test(before)) throw Error('--before needs YYYY-MM.');
796
+ const known = readChanges(root), blocking = known.issues.find(issue => issue.rule !== 'change-duplicate');
797
+ if (blocking) throw Error(`Repair the changes folder first: ${blocking.message}`);
798
+ const months = new Map();
799
+ for (const name of known.files) if (name.length > 10 && name.slice(0, 7) < before) months.set(name.slice(0, 7), [...(months.get(name.slice(0, 7)) ?? []), `${known.folder}/${name}`]);
800
+ const digests = [...months].sort().map(([month, records]) => ({ path: `${known.folder}/${month}.md`, records }));
801
+ if (write) for (const [month, records] of months) {
802
+ writeDigest(root, known.folder, month, known.entries.filter(entry => records.includes(entry.file)));
803
+ for (const file of records) unlinkSync(local(root, file));
804
+ }
805
+ return { ok: true, before, digests, written: write, note: 'A digest holds the full text of the records it replaces.' };
806
+ }
807
+
808
+ // Convert docs of the earlier layout: History entries become change entries in monthly digests and
809
+ // the doc keeps Covers, Current view and Lessons. Nothing is dropped: what one doc said differently
810
+ // about a run goes in that doc's line, and a doc that cannot be converted completely stops the
811
+ // whole conversion. What an entry did not record stays "not recorded".
812
+ export function migrateContext(root, { write = false } = {}) {
813
+ root = realpathSync(root);
814
+ const { folder, index } = contextLocation(root), known = readChanges(root);
815
+ const runs = new Map(), docs = [], skipped = [];
816
+ for (const name of listDocs(root)) {
817
+ const path = `${folder}/${name}`, source = read(root, path), parsed = parseDoc(source, name);
818
+ if (parsed.layout !== 'earlier') continue;
819
+ const blocking = parsed.issues.find(issue => ['sections', 'history-entry', 'evidence', 'last-change', 'last-change-current'].includes(issue.rule));
820
+ // A run that already has an entry keeps it. The doc's History for that run may go only if the
821
+ // entry names the doc and already holds every part of it, as after an interrupted migration.
822
+ const parts = h => [h.date, h.title, h.changed, h.learned, h.proof, ...(h.extra ?? []), ...h.files.map(f => `${f.path}@${f.hash}`)].filter(Boolean).map(part => oneLine(part, Infinity).replaceAll('\\|', '|'));
823
+ const recorded = parsed.history.find(h => known.entries.some(entry => entry.run === h.run && !(entry.components.some(c => c.doc === path) && parts(h).every(part => entry.source.includes(part)))));
824
+ if (blocking || recorded) { skipped.push({ path, reason: blocking ? `${blocking.rule}: ${blocking.message}` : `Run ${recorded.run} already has a change entry that does not name this doc or lacks part of its History; reconcile the two first.` }); continue; }
825
+ for (const h of parsed.history) {
826
+ const run = runs.get(h.run) ?? { date: h.date, run: h.run, goal: h.title, changed: h.changed, learned: h.learned, proof: h.proof, components: [], files: new Map() };
827
+ const own = [['Date', h.date, run.date], ['Goal', h.title, run.goal], ['Changed', h.changed, run.changed], ['Learned', h.learned, run.learned], ['Proof', h.proof, run.proof]].filter(([, mine, theirs]) => mine && mine !== theirs).map(([label, mine]) => `${label}: ${mine}`);
828
+ run.components.push({ doc: path, note: [...own, ...(h.extra ?? [])].join(' / ') });
829
+ for (const file of h.files) run.files.set(`${file.path}@${file.hash}`, file);
830
+ runs.set(h.run, run);
737
831
  }
832
+ const lines = source.split('\n');
833
+ docs.push({ path, entries: parsed.history.length, source: `${lines.slice(0, lines.indexOf('## History')).filter(line => !/^Last changed by AI:/.test(line)).join('\n').replace(/\n{3,}/g, '\n\n').replace(/\n*$/, '')}\n` });
738
834
  }
739
- let index = null;
740
- if (written.some(w => w.written)) {
741
- if (!existsSync(local(root, indexName))) { mkdirSync(dirname(local(root, indexName)), { recursive: true }); atomicWrite(local(root, indexName), '# Context index\n\nRead the index, then the docs whose Covers match the paths you are about to change.\n\n| Component | Covers | Doc | Last AI change | Lessons |\n| --- | --- | --- | --- | --- |\n', staging); }
742
- index = refreshIndex(root, { staging });
835
+ const months = new Map(), missing = 'not recorded';
836
+ for (const run of runs.values()) {
837
+ if (known.entries.some(entry => entry.run === run.run)) continue;
838
+ const [entry] = parseChanges(changeSource({ ...run, full: true, result: `${missing} (migrated from the doc History of the earlier layout)`, proof: run.proof ?? missing, changed: run.changed ?? missing, learned: run.learned ?? missing, files: [...run.files.values()] }));
839
+ months.set(run.date.slice(0, 7), [...(months.get(run.date.slice(0, 7)) ?? []), entry]);
743
840
  }
744
- const lint = lintContext(root, { git: false });
745
- return { ...result, written, indexRefreshed: index, lint: { ok: lint.ok, index: lint.index.issues, docs: lint.docs.filter(d => !d.ok).map(d => ({ path: d.path, issues: d.issues })) } };
746
- });
841
+ write &&= !skipped.length;
842
+ if (write) {
843
+ const staging = local(root, '.cyc/runtime/context-staging');
844
+ for (const [month, entries] of months) writeDigest(root, known.folder, month, entries);
845
+ for (const doc of docs) atomicWrite(local(root, doc.path), doc.source, staging);
846
+ if (docs.length && existsSync(local(root, index))) refreshIndex(root, { staging });
847
+ }
848
+ return { ok: !skipped.length, docs: docs.map(({ path, entries }) => ({ path, entries })), runs: [...months.values()].flat().length, digests: [...months.keys()].sort().map(month => `${known.folder}/${month}.md`), skipped, written: write,
849
+ note: skipped.length ? 'Nothing was converted: repair the skipped docs first, so no history is dropped.' : 'Docs and the index are verified source. Outcomes the earlier entries did not record stay "not recorded".' };
747
850
  }
748
851
 
749
852
  // ---------------------------------------------------------------- measure: what the index path costs