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.
- package/.claude-plugin/plugin.json +1 -1
- package/.codex-plugin/plugin.json +1 -1
- package/.cursor-plugin/plugin.json +1 -1
- package/README.md +3 -2
- package/bin/cyc.mjs +72 -20
- package/docs/README.md +2 -0
- package/docs/context.md +18 -10
- package/docs/project-tools.md +2 -12
- package/docs/runtime.md +5 -1
- package/docs/work-assessments.md +4 -4
- package/docs/work-queue.md +187 -0
- package/methods/cyc-build/SKILL.md +1 -1
- package/methods/cyc-context/SKILL.md +28 -20
- package/methods/cyc-context/references/evidence.md +1 -1
- package/methods/cyc-context/references/templates.md +30 -18
- package/methods/cyc-design/frontend-design/SKILL.md +132 -21
- package/methods/cyc-design/frontend-design/references/color.md +43 -56
- package/methods/cyc-design/frontend-design/references/craft-rules.md +17 -14
- package/methods/cyc-design/frontend-design/references/decision-sheet.md +95 -93
- package/methods/cyc-design/frontend-design/references/experience-review.md +15 -6
- package/methods/cyc-design/frontend-design/references/field-guide.md +439 -0
- package/methods/cyc-design/frontend-design/references/generic-tells.md +83 -32
- package/methods/cyc-design/frontend-design/references/layout-archetypes.md +5 -5
- package/methods/cyc-design/frontend-design/references/patterns.md +108 -0
- package/methods/cyc-design/frontend-design/references/reference-standards.md +118 -22
- package/methods/cyc-design/frontend-design/references/typography.md +59 -44
- package/methods/cyc-design/frontend-design/references/ux-foundations.md +2 -1
- package/methods/cyc-design/frontend-design/references/visual-material.md +43 -8
- package/methods/cyc-design/frontend-design/scripts/contrast.mjs +39 -0
- package/methods/cyc-design/frontend-design/scripts/first-screen.mjs +911 -0
- package/methods/cyc-design/frontend-design/scripts/photo-text.mjs +230 -0
- package/methods/cyc-verify/SKILL.md +1 -1
- package/package.json +6 -1
- package/plugin.json +1 -1
- package/scripts/catalog.mjs +5 -3
- package/scripts/context-review.mjs +364 -261
- package/scripts/hub-page.mjs +275 -0
- package/scripts/hub.mjs +139 -0
- package/scripts/project-tools.mjs +14 -6
- package/scripts/queue-board.mjs +287 -0
- package/scripts/queue.mjs +283 -0
- package/scripts/run-gate.mjs +8 -5
- package/scripts/runtime.mjs +270 -19
- package/scripts/source-snapshot.mjs +20 -2
- package/scripts/work-review.mjs +4 -3
- package/skills/cyc/SKILL.md +12 -4
- package/skills/cyc/references/playbooks/experience.md +2 -0
- 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
|
|
6
|
+
import { readRun } from './runtime.mjs';
|
|
7
7
|
import { contextLinks } from './project-tools.mjs';
|
|
8
|
+
import { changeFile } from './source-snapshot.mjs';
|
|
8
9
|
|
|
9
|
-
//
|
|
10
|
-
//
|
|
11
|
-
//
|
|
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
|
|
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.
|
|
30
|
-
//
|
|
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
|
-
|
|
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
|
-
|
|
40
|
-
|
|
41
|
-
'
|
|
42
|
-
|
|
43
|
-
'
|
|
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-
|
|
48
|
-
'
|
|
49
|
-
'
|
|
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)
|
|
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)
|
|
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
|
-
|
|
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
|
|
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
|
|
258
|
-
//
|
|
259
|
-
//
|
|
260
|
-
|
|
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)
|
|
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 [
|
|
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
|
-
|
|
413
|
-
if (
|
|
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;
|
|
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
|
-
//
|
|
437
|
-
|
|
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
|
-
|
|
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)
|
|
450
|
-
|
|
451
|
-
|
|
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
|
-
//
|
|
455
|
-
|
|
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),
|
|
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
|
|
506
|
-
//
|
|
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,
|
|
535
|
-
|
|
536
|
-
|
|
537
|
-
|
|
538
|
-
|
|
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
|
-
|
|
542
|
-
|
|
543
|
-
|
|
544
|
-
|
|
545
|
-
|
|
546
|
-
|
|
547
|
-
|
|
548
|
-
|
|
549
|
-
|
|
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
|
|
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
|
|
568
|
-
const runs
|
|
569
|
-
for (const name of docs) {
|
|
570
|
-
const
|
|
571
|
-
|
|
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\
|
|
578
|
-
}
|
|
579
|
-
|
|
580
|
-
//
|
|
581
|
-
//
|
|
582
|
-
|
|
583
|
-
|
|
584
|
-
const
|
|
585
|
-
const
|
|
586
|
-
if (
|
|
587
|
-
const
|
|
588
|
-
const
|
|
589
|
-
const
|
|
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
|
|
627
|
-
|
|
628
|
-
if (
|
|
629
|
-
seen.add(
|
|
630
|
-
|
|
631
|
-
|
|
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
|
-
|
|
706
|
+
rows.push({ text: render(cells), doc: owned ? doc : null });
|
|
637
707
|
}
|
|
638
|
-
|
|
639
|
-
const appended = [];
|
|
708
|
+
let addedRows = 0;
|
|
640
709
|
for (const name of listDocs(root)) {
|
|
641
|
-
const
|
|
642
|
-
if (seen.has(
|
|
643
|
-
const
|
|
644
|
-
|
|
645
|
-
|
|
646
|
-
cells[columns.
|
|
647
|
-
|
|
648
|
-
|
|
649
|
-
|
|
650
|
-
}
|
|
651
|
-
|
|
652
|
-
const
|
|
653
|
-
if (
|
|
654
|
-
|
|
655
|
-
|
|
656
|
-
|
|
657
|
-
|
|
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
|
|
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
|
|
672
|
-
const
|
|
673
|
-
|
|
674
|
-
|
|
675
|
-
|
|
676
|
-
|
|
677
|
-
|
|
678
|
-
|
|
679
|
-
|
|
680
|
-
|
|
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
|
-
|
|
711
|
-
const
|
|
712
|
-
return
|
|
713
|
-
|
|
714
|
-
|
|
715
|
-
|
|
716
|
-
|
|
717
|
-
|
|
718
|
-
|
|
719
|
-
|
|
720
|
-
|
|
721
|
-
|
|
722
|
-
|
|
723
|
-
|
|
724
|
-
|
|
725
|
-
|
|
726
|
-
|
|
727
|
-
|
|
728
|
-
|
|
729
|
-
|
|
730
|
-
|
|
731
|
-
|
|
732
|
-
|
|
733
|
-
|
|
734
|
-
|
|
735
|
-
|
|
736
|
-
|
|
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
|
-
|
|
740
|
-
|
|
741
|
-
if (
|
|
742
|
-
|
|
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
|
-
|
|
745
|
-
|
|
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
|