cyc-stack 0.0.0-stage → 0.6.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 (112) hide show
  1. package/.agents/plugins/marketplace.json +12 -0
  2. package/.claude-plugin/marketplace.json +14 -0
  3. package/.claude-plugin/plugin.json +17 -0
  4. package/.codex-plugin/plugin.json +33 -0
  5. package/.cursor-plugin/marketplace.json +13 -0
  6. package/.cursor-plugin/plugin.json +19 -0
  7. package/INSTALL.md +108 -0
  8. package/LICENSE +21 -0
  9. package/README.md +359 -2
  10. package/bin/cyc.mjs +285 -0
  11. package/catalog/playbooks.json +20 -0
  12. package/docs/README.md +30 -0
  13. package/docs/assets/cyc-method-library.svg +39 -0
  14. package/docs/assets/cyc-overview.svg +44 -0
  15. package/docs/assets/cyc-readme-banner-mobile.svg +31 -0
  16. package/docs/assets/cyc-readme-banner.svg +39 -0
  17. package/docs/assets/cyc-workflow-diagram.svg +415 -0
  18. package/docs/code-quality.md +42 -0
  19. package/docs/context.md +40 -0
  20. package/docs/cyc-method-map.md +58 -0
  21. package/docs/cyc-workflow.md +188 -0
  22. package/docs/engineering/code-standards.md +103 -0
  23. package/docs/engineering/domain-design.md +81 -0
  24. package/docs/engineering/failure-handling.md +99 -0
  25. package/docs/impact-analysis.md +70 -0
  26. package/docs/installation.md +196 -0
  27. package/docs/onboarding-recovery.md +75 -0
  28. package/docs/principles.md +49 -0
  29. package/docs/project-tools.md +108 -0
  30. package/docs/response-standard.md +202 -0
  31. package/docs/runtime.md +247 -0
  32. package/docs/skill-contract.md +70 -0
  33. package/docs/skill-craft.md +23 -0
  34. package/docs/validation.md +39 -0
  35. package/docs/work-assessments.md +102 -0
  36. package/hooks/claude.json +10 -0
  37. package/hooks/codex.json +28 -0
  38. package/hooks/cursor.json +8 -0
  39. package/methods/cyc-build/SKILL.md +65 -0
  40. package/methods/cyc-build/references/file-writes.md +11 -0
  41. package/methods/cyc-challenge/SKILL.md +48 -0
  42. package/methods/cyc-context/SKILL.md +76 -0
  43. package/methods/cyc-context/references/evidence.md +27 -0
  44. package/methods/cyc-context/references/templates.md +54 -0
  45. package/methods/cyc-context/scripts/evidence.mjs +61 -0
  46. package/methods/cyc-correct/SKILL.md +43 -0
  47. package/methods/cyc-deliver/SKILL.md +52 -0
  48. package/methods/cyc-design/SKILL.md +50 -0
  49. package/methods/cyc-design/frontend-design/SKILL.md +43 -0
  50. package/methods/cyc-design/frontend-design/references/color.md +77 -0
  51. package/methods/cyc-design/frontend-design/references/craft-rules.md +61 -0
  52. package/methods/cyc-design/frontend-design/references/decision-sheet.md +110 -0
  53. package/methods/cyc-design/frontend-design/references/experience-review.md +58 -0
  54. package/methods/cyc-design/frontend-design/references/generic-tells.md +76 -0
  55. package/methods/cyc-design/frontend-design/references/layout-archetypes.md +188 -0
  56. package/methods/cyc-design/frontend-design/references/reference-standards.md +38 -0
  57. package/methods/cyc-design/frontend-design/references/typography.md +51 -0
  58. package/methods/cyc-design/frontend-design/references/ux-foundations.md +45 -0
  59. package/methods/cyc-design/frontend-design/references/visual-material.md +42 -0
  60. package/methods/cyc-error-ledger/SKILL.md +53 -0
  61. package/methods/cyc-error-ledger/references/entry-format.md +38 -0
  62. package/methods/cyc-explore/SKILL.md +41 -0
  63. package/methods/cyc-frame/SKILL.md +49 -0
  64. package/methods/cyc-impact/SKILL.md +64 -0
  65. package/methods/cyc-reflect/SKILL.md +48 -0
  66. package/methods/cyc-remember/SKILL.md +53 -0
  67. package/methods/cyc-scout/SKILL.md +67 -0
  68. package/methods/cyc-setup/SKILL.md +60 -0
  69. package/methods/cyc-teach/SKILL.md +40 -0
  70. package/methods/cyc-understand/SKILL.md +40 -0
  71. package/methods/cyc-understand/references/diagnose.md +53 -0
  72. package/methods/cyc-verify/SKILL.md +84 -0
  73. package/methods/cyc-verify/references/recipe.md +53 -0
  74. package/package.json +93 -4
  75. package/plugin.json +40 -0
  76. package/rules/cyc-delivery.mdc +33 -0
  77. package/scripts/baseline-worker.mjs +10 -0
  78. package/scripts/catalog.mjs +29 -0
  79. package/scripts/check-response.mjs +13 -0
  80. package/scripts/claude-project-hook.mjs +12 -0
  81. package/scripts/context-review.mjs +600 -0
  82. package/scripts/host-activation.mjs +66 -0
  83. package/scripts/install.mjs +387 -0
  84. package/scripts/onboarding.mjs +110 -0
  85. package/scripts/packet.mjs +107 -0
  86. package/scripts/project-tools.mjs +196 -0
  87. package/scripts/recovery.mjs +66 -0
  88. package/scripts/response-gate.mjs +105 -0
  89. package/scripts/response-hook.mjs +237 -0
  90. package/scripts/response-mode.mjs +12 -0
  91. package/scripts/run-gate.mjs +264 -0
  92. package/scripts/runtime.mjs +1723 -0
  93. package/scripts/source-hash-worker.mjs +5 -0
  94. package/scripts/source-snapshot.mjs +405 -0
  95. package/scripts/test-output.mjs +258 -0
  96. package/scripts/work-review.mjs +257 -0
  97. package/skills/cyc/SKILL.md +130 -0
  98. package/skills/cyc/references/playbooks/bug-fix.md +13 -0
  99. package/skills/cyc/references/playbooks/evaluate.md +13 -0
  100. package/skills/cyc/references/playbooks/experience.md +7 -0
  101. package/skills/cyc/references/playbooks/explore.md +9 -0
  102. package/skills/cyc/references/playbooks/feature.md +14 -0
  103. package/skills/cyc/references/playbooks/handoff.md +11 -0
  104. package/skills/cyc/references/playbooks/investigation.md +7 -0
  105. package/skills/cyc/references/playbooks/performance.md +7 -0
  106. package/skills/cyc/references/playbooks/plan.md +11 -0
  107. package/skills/cyc/references/playbooks/refactor.md +12 -0
  108. package/skills/cyc/references/playbooks/reflect.md +11 -0
  109. package/skills/cyc/references/playbooks/resume.md +11 -0
  110. package/skills/cyc/references/playbooks/review.md +9 -0
  111. package/skills/cyc/references/playbooks/teach.md +11 -0
  112. package/skills/cyc/references/playbooks/verify.md +7 -0
@@ -0,0 +1,258 @@
1
+ // Reads test runner output (TAP from node --test and tap, mocha, jest) so a suite that already had
2
+ // a failing test can still show what the new tests did. Each reader returns the failing tests keyed
3
+ // by file and title, each with its error and diagnostics, how many tests passed, and the lines that
4
+ // are not test results. Unrecognized output returns null, and callers keep comparing whole outputs.
5
+
6
+ const backslash = String.fromCharCode(92);
7
+ const slashes = value => value.split(backslash).join('/');
8
+ const plain = value => value.replace(new RegExp(`${String.fromCharCode(27)}\\[[0-9;]*m`, 'g'), '');
9
+ // Kept output is the last 32,000 characters of each stream; longer output keeps a parsed summary.
10
+ export const outputLimit = 32000;
11
+
12
+ // Only what changes between identical runs is ignored: timestamps, clock times, durations, and the
13
+ // process ID in node's warnings, "(node:12316) [DEP0040] DeprecationWarning: ...".
14
+ export const stable = line => line
15
+ .replace(/\(node:\d+\)/g, '(node:<pid>)')
16
+ .replace(/\d{4}-\d{2}-\d{2}[T ]\d{2}:\d{2}:\d{2}(?:\.\d+)?Z?/g, '<time>')
17
+ .replace(/\b\d{1,2}:\d{2}:\d{2}(?:\.\d+)?\b/g, '<time>')
18
+ .replace(/\b\d+(?:\.\d+)?\s?(?:ms|s|sec|seconds|m|min)\b/g, '<duration>')
19
+ .replace(/\b(time|duration(?:_ms)?)[=:]\s?\d+(?:\.\d+)?/g, '$1=<duration>');
20
+
21
+ // One shape for every reader: failures keyed by file and title, counted when they repeat.
22
+ function collector() {
23
+ const failing = new Map();
24
+ let passingCount = 0;
25
+ const other = new Map();
26
+ return {
27
+ fail(entry) {
28
+ const key = `${entry.file ?? ''}::${entry.path.join(' > ')}`;
29
+ const known = failing.get(key);
30
+ if (known) known.count += 1; else failing.set(key, { ...entry, count: 1 });
31
+ },
32
+ pass(count = 1) { passingCount += count; },
33
+ note(line) { const text = slashes(line.trim()); if (text) other.set(stable(text), text); },
34
+ done: () => ({ failing, passingCount, other })
35
+ };
36
+ }
37
+ const fileLike = segment => /\.(?:[cm]?[jt]sx?)$/.test(segment);
38
+
39
+ const resultLine = /^(\s*)(not ok|ok)\b(?:\s+\d+)?(?:\s+-)?\s*(.*)$/;
40
+ const subtestLine = /^(\s*)# Subtest: (.*)$/;
41
+ const bookkeeping = /^\s*(?:TAP version \d+|\d+\.\.\d+(?:\s+#.*)?|# (?:tests|suites|pass|fail|cancelled|skipped|todo|duration_ms|time)\b.*|Bail out!.*)$/;
42
+
43
+ // A YAML value as node:test writes it: 'single quoted' (with '' for a quote), or bare.
44
+ const yamlValue = raw => { const value = raw.trim(); return value.startsWith("'") && value.endsWith("'") ? value.slice(1, -1).replace(/''/g, "'") : value; };
45
+
46
+ // TAP: returns null unless the output contains TAP test results.
47
+ export function readTap(output) {
48
+ const lines = (output ?? '').split(/\r?\n/);
49
+ if (!lines.some(line => resultLine.test(line))) return null;
50
+ const out = collector();
51
+ const open = [];
52
+ const pending = [];
53
+ let last = null;
54
+ let yaml = null;
55
+ const record = entry => {
56
+ if (!entry || entry.group || entry.skipped) return;
57
+ // tap's own reporter has no location; its subtests are named after the test file.
58
+ entry.file ??= entry.path.slice(0, -1).map(slashes).find(fileLike);
59
+ if (entry.failed) out.fail(entry); else out.pass();
60
+ };
61
+ const settle = () => { while (pending.length) record(pending.shift()); };
62
+ for (const line of lines) {
63
+ if (yaml) {
64
+ // A failed test's diagnostics belong to that test: its file, error, and stack.
65
+ if (new RegExp(`^ {${yaml.indent}}\\.\\.\\.\\s*$`).test(line)) { settle(); yaml = null; continue; }
66
+ const indent = /^\s*/.exec(line)[0].length;
67
+ // A block value (error: |-) continues on the lines indented under its key.
68
+ if (yaml.block !== undefined && indent > yaml.block) { yaml.entry.error += `${yaml.entry.error ? '\n' : ''}${line.trim()}`; yaml.entry.details.push(slashes(line.trim())); continue; }
69
+ yaml.block = undefined;
70
+ const field = /^\s*(location|type|error):\s*(.*)$/.exec(line);
71
+ if (field?.[1] === 'location') yaml.entry.file = slashes(yamlValue(field[2]).split(backslash + backslash).join(backslash)).replace(/:\d+(?::\d+)?$/, '');
72
+ else if (field?.[1] === 'type' && yamlValue(field[2]) === 'suite') yaml.entry.group = true;
73
+ else if (field?.[1] === 'error' && yaml.entry.error === undefined) {
74
+ if (/^[|>][-+]?$/.test(field[2].trim())) { yaml.entry.error = ''; yaml.block = indent; }
75
+ else yaml.entry.error = yamlValue(field[2]);
76
+ }
77
+ yaml.entry.details.push(slashes(line.trim()));
78
+ continue;
79
+ }
80
+ // Diagnostics start only directly under a test result; a stray --- elsewhere is ordinary output.
81
+ const start = /^(\s*)---\s*$/.exec(line);
82
+ if (start && last && start[1].length > last.indent) { yaml = { indent: start[1].length, entry: last.entry }; last = null; continue; }
83
+ settle();
84
+ last = null;
85
+ const header = subtestLine.exec(line);
86
+ if (header) { open.push({ indent: header[1].length, name: header[2].trim(), children: false }); continue; }
87
+ if (/^\s*}\s*$/.test(line) && open.at(-1)?.buffered) { open.pop(); continue; }
88
+ const test = resultLine.exec(line);
89
+ if (test) {
90
+ const indent = test[1].length;
91
+ let [name, directive = ''] = test[3].split(/\s+#\s+/);
92
+ while (open.length && open.at(-1).indent > indent) open.pop();
93
+ const closes = open.at(-1)?.indent === indent && !open.at(-1).buffered ? open.pop() : null;
94
+ for (const parent of open) parent.children = true;
95
+ // tap's buffered subtests: "ok 1 - name {" opens a group closed by "}".
96
+ const buffered = /\s\{$/.test(name);
97
+ if (buffered) name = name.replace(/\s*\{$/, '');
98
+ const entry = { path: [...open.map(item => item.name), name.trim()], leaf: name.trim(), failed: test[2] === 'not ok', skipped: /^(?:todo|skip)\b/i.test(directive.trim()), group: Boolean(closes?.children) || buffered, details: [] };
99
+ if (buffered) open.push({ indent, name: name.trim(), children: false, buffered: true });
100
+ pending.push(entry);
101
+ last = { indent, entry };
102
+ continue;
103
+ }
104
+ if (bookkeeping.test(line) || !line.trim()) continue;
105
+ out.note(line);
106
+ }
107
+ settle();
108
+ return out.done();
109
+ }
110
+
111
+ // The file of a failure: the frame that ran the test (mocha's Context, jest's Object), else the
112
+ // first frame outside node internals and dependencies.
113
+ const frameFile = (lines, preferred) => {
114
+ const frames = lines.map(line => /\(?((?:file:\/\/\/)?[^\s()]+?):\d+:\d+\)?\s*$/.exec(line.trim().replace(/^at\s+/, ''))?.[1]).filter(Boolean)
115
+ .map(path => slashes(path.replace(/^file:\/\/\//, ''))).filter(path => !/^node:|\/node_modules\//.test(path));
116
+ const chosen = lines.findIndex(line => preferred.test(line));
117
+ const fromPreferred = chosen >= 0 ? /\(?((?:file:\/\/\/)?[^\s()]+?):\d+:\d+\)?\s*$/.exec(lines[chosen].trim())?.[1] : null;
118
+ return fromPreferred ? slashes(fromPreferred.replace(/^file:\/\/\//, '')) : frames[0];
119
+ };
120
+
121
+ const indentOf = line => /^\s*/.exec(line)[0].length;
122
+ // A suite title in a reporter's test list: indented, with the next nonblank line indented further.
123
+ const suiteTitle = (lines, index) => {
124
+ const next = lines.slice(index + 1).find(line => line.trim());
125
+ return indentOf(lines[index]) >= 2 && next !== undefined && indentOf(next) > indentOf(lines[index]);
126
+ };
127
+
128
+ // mocha: every reporter prints "N passing" and then numbers each failure, its title on one line
129
+ // per suite level, the last ending with ":", followed by the error and stack.
130
+ export function readMocha(output) {
131
+ const lines = plain(output ?? '').split(/\r?\n/);
132
+ const summary = lines.findIndex(line => /^\s*\d+ passing\b/.test(line));
133
+ if (summary < 0) return null;
134
+ const out = collector();
135
+ out.pass(Number(/(\d+) passing/.exec(lines[summary])[1]));
136
+ // Before the summary: the reporter's list of results and suite titles, and any other output,
137
+ // such as a warning or a console line, which is kept.
138
+ const listed = lines.slice(0, summary);
139
+ listed.forEach((line, index) => {
140
+ if (!line.trim() || /^\s*(?:[✔✓√]|\d+\)|-)\s/.test(line) || /^[\s.,!․]+$/.test(line) || suiteTitle(listed, index)) return;
141
+ out.note(line);
142
+ });
143
+ let current = null;
144
+ // The title's parts, one per line: part k (after the first) is indented 5 + 2k spaces, and mocha
145
+ // appends ":" to the last part only, so a suite title that itself ends with ":" stays whole.
146
+ const closeTitle = () => { if (current?.open) { current.open = false; current.title[current.title.length - 1] = current.title.at(-1).replace(/:$/, ''); } };
147
+ const finish = () => {
148
+ if (!current) return;
149
+ closeTitle();
150
+ const errorLines = current.body.slice(0, Math.max(0, current.body.findIndex(line => /^\s*at\s/.test(line)))).map(line => line.trim()).filter(Boolean);
151
+ out.fail({ path: current.title, leaf: current.title.at(-1), file: frameFile(current.body, /Context\.<anonymous>/), error: errorLines.join('\n'), details: current.body.map(line => slashes(line.trim())).filter(Boolean) });
152
+ current = null;
153
+ };
154
+ let afterFailures = false;
155
+ for (const line of lines.slice(summary + 1)) {
156
+ const header = /^ {2}\d+\) (.*)$/.exec(line);
157
+ if (header) { finish(); current = { title: [header[1].trim()], body: [], open: true }; continue; }
158
+ if (current?.open) {
159
+ if (line.trim() && indentOf(line) === 5 + 2 * current.title.length) { current.title.push(line.trim()); continue; }
160
+ closeTitle();
161
+ }
162
+ // A coverage report or another tool's output after mocha's own is not part of a failure.
163
+ if (/^(?:-{3,}|={3,}|ERROR:|File\s+\||All files|npm (?:ERR!|error))/.test(line)) { finish(); afterFailures = true; }
164
+ if (current && !afterFailures) { current.body.push(line); continue; }
165
+ if (/^\s*\d+ (?:pending|failing)\b/.test(line)) continue;
166
+ if (afterFailures || !current) out.note(line);
167
+ }
168
+ finish();
169
+ return out.done();
170
+ }
171
+
172
+ // jest: "FAIL <file>" heads each failing file; each failure is "● Suite › test", then the message,
173
+ // a code frame, and the stack. "Tests: … N passed" counts the passing tests. "● Console" is not a
174
+ // test: it heads the console output of a file, which is kept as other output.
175
+ export function readJest(output) {
176
+ const lines = plain(output ?? '').split(/\r?\n/);
177
+ const totals = lines.find(line => /^\s*Tests:\s+/.test(line));
178
+ if (!totals || !lines.some(line => /^\s*(?:PASS|FAIL)\s+\S/.test(line))) return null;
179
+ const out = collector();
180
+ out.pass(Number(/(\d+) passed/.exec(totals)?.[1] ?? 0));
181
+ let file = null;
182
+ let current = null;
183
+ let inConsole = false;
184
+ let repeated = false;
185
+ const finish = () => {
186
+ if (!current) return;
187
+ const message = [];
188
+ for (const line of current.body) { if (/^\s*(?:>?\s*\d+\s*\||\|)|^\s*at\s/.test(line)) break; if (line.trim()) message.push(line.trim()); }
189
+ out.fail({ path: current.title, leaf: current.title.at(-1), file, error: message.join('\n'), details: current.body.map(line => slashes(line.trim())).filter(Boolean) });
190
+ current = null;
191
+ };
192
+ lines.forEach((line, index) => {
193
+ // With more than 20 suites, jest prints every failure again under this heading; read it once.
194
+ if (/^\s*Summary of all failing tests\s*$/.test(line)) { finish(); repeated = true; return; }
195
+ if (repeated && !/^\s*Test Suites:\s/.test(line)) return;
196
+ repeated = false;
197
+ // A console block's lines are indented under its heading; its stack frames move with edits.
198
+ if (inConsole && (!line.trim() || indentOf(line) >= 4)) { if (!/^\s*at\s/.test(line)) out.note(line); return; }
199
+ inConsole = false;
200
+ // "FAIL <file>", or "FAIL <project> <file>" with projects; a slow file ends with "(5.2 s)".
201
+ const head = /^\s*(PASS|FAIL)\s+(.+?)\s*$/.exec(line);
202
+ if (head) {
203
+ finish();
204
+ const words = head[2].replace(/\s+\([^)]*\)$/, '').split(/\s+/);
205
+ file = slashes(words.findLast(fileLike) ?? words.at(-1));
206
+ return;
207
+ }
208
+ if (/^\s*● Console\s*$/.test(line)) { finish(); inConsole = true; return; }
209
+ const failure = /^\s*● (.+)$/.exec(line);
210
+ if (failure) { finish(); current = { title: failure[1].split(' › ').map(part => part.trim()), body: [] }; return; }
211
+ if (/^\s*(?:Test Suites|Tests|Snapshots|Time):\s|^\s*Ran all test suites/.test(line)) { finish(); return; }
212
+ if (current) { current.body.push(line); return; }
213
+ if (/^\s*[✓✕○√×]\s/.test(line) || suiteTitle(lines, index)) return;
214
+ out.note(line);
215
+ });
216
+ finish();
217
+ return out.done();
218
+ }
219
+
220
+ // Readers from the most to the least distinctive report. mocha and jest have their own summaries,
221
+ // while any line starting with "ok" looks like TAP, so TAP comes first only when it declares its version.
222
+ const declaredTap = output => /^TAP version \d+/m.test(output ?? '') ? readTap(output) : null;
223
+ const readers = [declaredTap, readJest, readMocha, readTap];
224
+
225
+ // A runner writes its report to one stream (jest to stderr, the others to stdout). Each reader
226
+ // tries both streams before a weaker one does; the other stream is kept whole as other output,
227
+ // so a warning there is never read as part of a failure.
228
+ export function readTestOutput(stdout, stderr = '') {
229
+ for (const reader of readers) {
230
+ for (const [report, rest] of [[stdout, stderr], [stderr, stdout]]) {
231
+ const tests = reader(report);
232
+ if (!tests) continue;
233
+ for (const line of plain(rest ?? '').split(/\r?\n/)) { const text = slashes(line.trim()); if (text) tests.other.set(stable(text), text); }
234
+ return tests;
235
+ }
236
+ }
237
+ return null;
238
+ }
239
+
240
+ // What runCommands keeps for output longer than its tail: the parsed results, whole. runCommands
241
+ // reads at most 64 MB of each stream for this, so a summary is bounded by its output; one that would
242
+ // still exceed summaryLimit characters keeps only counts, is marked incomplete, and counts as cut off.
243
+ export const summaryLimit = 4_000_000;
244
+ export function summarizeTests(stdout, stderr = '', limit = summaryLimit) {
245
+ const tests = readTestOutput(stdout, stderr);
246
+ if (!tests) return null;
247
+ const summary = { failing: [...tests.failing], passingCount: tests.passingCount, other: [...tests.other], complete: true };
248
+ return JSON.stringify(summary).length <= limit ? summary : { failing: [], passingCount: tests.passingCount, other: [], failingCount: tests.failing.size, complete: false };
249
+ }
250
+
251
+ // The parsed results of one check: its stored summary, or its kept output when it was not cut off.
252
+ export function testsOf(result) {
253
+ if (result?.tests) return result.tests.complete ? { failing: new Map(result.tests.failing), passingCount: result.tests.passingCount, other: new Map(result.tests.other) } : null;
254
+ return readTestOutput(result?.stdout ?? '', result?.stderr ?? '');
255
+ }
256
+
257
+ // Output whose earlier lines were dropped, with no complete summary to stand in for them.
258
+ export const cutOff = result => result?.tests ? !result.tests.complete : [result?.stdout, result?.stderr].some(stream => (stream ?? '').length >= outputLimit);
@@ -0,0 +1,257 @@
1
+ // These checks establish recorded process evidence, not the truth of an agent's judgment.
2
+ const text = value => typeof value === 'string' && value.trim().length > 0;
3
+ const object = value => value && typeof value === 'object' && !Array.isArray(value);
4
+ const requireText = (value, name) => { if (!text(value)) throw new Error(`${name} needs meaningful evidence.`); };
5
+ const requireChoice = (value, choices, name) => { if (!choices.includes(value)) throw new Error(`${name} must be ${choices.join(', ')}.`); };
6
+ export const reviewPath = state => `.cyc/runs/${state.id}/review.md`;
7
+
8
+ export function assessmentRequirements(state, stage) {
9
+ if (state.workContractVersion !== 1) return [];
10
+ return ({ scout: ['context', 'approach', 'alignment', 'consumers'], verify: ['semanticReview', 'consumerChecks'], deliver: ['learning', 'errorHistory'] })[stage] ?? [];
11
+ }
12
+
13
+ // Fields the controller records when the agent leaves them out, limited to what its own record
14
+ // shows: nothing reusable was recorded; a run that is not a bug fix had no failed attempt; or the
15
+ // project keeps no context history to consult. A bug fix's cause, consumer evidence and review
16
+ // findings are judgment, and always come from the agent.
17
+ export function derivedAssessment(state, stage, { contextHistory = true } = {}) {
18
+ if (state.workContractVersion !== 1) return {};
19
+ if (stage === 'scout') return contextHistory ? {} : {
20
+ context: { status: 'none', evidence: 'Not given at start: this project has no docs/context/INDEX.md and no ledger, so there was no recorded history to consult.', freshness: 'No recorded history exists to go stale.', sources: [] }
21
+ };
22
+ if (stage === 'deliver') return {
23
+ learning: { status: 'none', reason: 'Not given at finish: no reusable learning was recorded for this run.', artifacts: [] },
24
+ ...(state.playbook !== 'bug-fix' && !state.failures ? { errorHistory: { status: 'none', reason: 'Not given at finish: this run recorded no failed attempt.', artifacts: [] } } : {})
25
+ };
26
+ return {};
27
+ }
28
+
29
+ // A fill-in skeleton for the current stage, so agents never need to read the contract docs to
30
+ // write a valid assessment. Angle-bracket strings and "a | b" choices are placeholders that
31
+ // validation rejects, so a template submitted unedited can never pass.
32
+ export function assessmentTemplate(state, stage) {
33
+ const required = assessmentRequirements(state, stage);
34
+ if (!required.length) return null;
35
+ const scoutConsumers = state.handoffs?.findLast(item => item.stage === 'scout' && item.status === 'passed')?.assessment?.consumers ?? [];
36
+ const templates = {
37
+ context: { status: 'used | none', evidence: '<what you searched for prior context>', freshness: '<why that context is still current, or why none applies>', sources: ['<project-relative path; [] when status is none>'] },
38
+ approach: { kind: 'reuse | extend | repair | create', evidence: '<existing code you found and why this approach>' },
39
+ alignment: { status: 'clear | confirmed', evidence: '<why the request is unambiguous, or what the user confirmed>' },
40
+ consumers: [{ id: 'direct', description: '<the behavior you are changing>', check: '<how you will verify it>' }],
41
+ semanticReview: { reviewer: 'self | fresh-context | peer', intent: '<does the diff do what was asked, nothing more>', consumers: '<are dependents still correct>', conventions: '<does it match project style>', findings: [] },
42
+ consumerChecks: (scoutConsumers.length ? scoutConsumers : [{ id: 'direct' }]).map(item => ({ id: item.id, result: 'passed', evidence: '<the command or observation that showed it works>' })),
43
+ learning: { status: 'none | recorded | pending-acceptance', reason: '<why nothing is reusable, or what was recorded>', artifacts: [] },
44
+ errorHistory: { status: state.playbook === 'bug-fix' || state.failures > 0 ? 'recorded' : 'none | recorded', reason: '<what failed and how it was resolved, or why there was no error>', artifacts: state.playbook === 'bug-fix' || state.failures > 0 ? [state.ledgerPath ?? 'docs/context/error-ledger.md'] : [] }
45
+ };
46
+ return Object.fromEntries(required.map(key => [key, templates[key]]));
47
+ }
48
+
49
+ // Accept common spellings of the same structure, in place. Evidence is never filled in: every
50
+ // reason, finding, and check result still has to come from the agent.
51
+ function normalizeAssessment(assessment) {
52
+ const canonical = paths => Array.isArray(paths) ? paths.map(path => typeof path === 'string' ? path.replaceAll('\\', '/').replace(/^\.\//, '') : path) : paths;
53
+ const { context, semanticReview, consumerChecks, learning, errorHistory } = assessment;
54
+ if (object(context)) {
55
+ if (context.status === 'none' && context.sources === undefined) context.sources = [];
56
+ context.sources = canonical(context.sources);
57
+ // "none" says no matched history exists; files listed with it are what was read while
58
+ // looking, not history sources. Keep the claim and record them as read.
59
+ if (context.status === 'none' && Array.isArray(context.sources) && context.sources.length) {
60
+ context.read = [...new Set([...(Array.isArray(context.read) ? context.read : []), ...context.sources])];
61
+ context.sources = [];
62
+ }
63
+ if (Array.isArray(context.read)) context.read = [...new Set(canonical(context.read))];
64
+ }
65
+ for (const entry of [learning, errorHistory]) {
66
+ if (!object(entry)) continue;
67
+ if (entry.status === 'none' && entry.artifacts === undefined) entry.artifacts = [];
68
+ entry.artifacts = canonical(entry.artifacts);
69
+ }
70
+ const findings = (Array.isArray(semanticReview?.findings) ? semanticReview.findings : []).filter(object);
71
+ const taken = new Set(findings.map(finding => finding.id));
72
+ let next = 1;
73
+ for (const finding of findings) {
74
+ // An id is only a label, so an unused one is supplied. Status and evidence still come from the agent.
75
+ if (finding.id === undefined) { while (taken.has(`f${next}`)) next += 1; finding.id = `f${next}`; taken.add(finding.id); }
76
+ // "dismissed: out of scope" states the status, then its evidence. Only a status word set off by
77
+ // a colon or a spaced dash counts, so "Fixed-width output still misaligns" names no status.
78
+ // Any other resolution is the agent's evidence; a missing status is still refused.
79
+ const spelled = typeof finding.resolution === 'string' ? /^\s*(resolved|fixed|dismissed|open)\s*(?::|\s[-–—]|$)\s*/i.exec(finding.resolution) : null;
80
+ if (finding.status === undefined && spelled) {
81
+ finding.status = spelled[1];
82
+ const rest = finding.resolution.slice(spelled[0].length).trim();
83
+ if (rest) finding.evidence ??= rest;
84
+ } else if (typeof finding.resolution === 'string' && finding.resolution.trim()) finding.evidence ??= finding.resolution.trim();
85
+ if (typeof finding.status === 'string' && /^(?:resolved|fixed|dismissed|open)$/i.test(finding.status.trim())) finding.status = finding.status.trim().toLowerCase();
86
+ if (finding.status === 'fixed') finding.status = 'resolved';
87
+ finding.evidence ??= finding.reason;
88
+ }
89
+ for (const check of Array.isArray(consumerChecks) ? consumerChecks : []) if (object(check) && check.result === 'pass') check.result = 'passed';
90
+ }
91
+
92
+ const findingShape = 'Each finding is {"id": "...", "status": "resolved | dismissed | open", "evidence": "..."}.';
93
+
94
+ export function validateAssessment(state, packet, fingerprint) {
95
+ const required = assessmentRequirements(state, packet.stage);
96
+ if (packet.status !== 'passed' || !required.length) return [];
97
+ const assessment = packet.assessment;
98
+ if (!object(assessment)) throw new Error(`Passing ${packet.stage} needs an assessment: ${required.join(', ')}. Use --assessment FILE or packet.assessment.`);
99
+ normalizeAssessment(assessment);
100
+ const missing = required.filter(key => !(key in assessment));
101
+ if (missing.length) throw new Error(`Assessment is missing ${missing.join(', ')}. Run next returns a fill-in assessmentTemplate.`);
102
+ const placeholder = findPlaceholder(assessment);
103
+ if (placeholder) throw new Error(`Replace the template placeholder at ${placeholder} with real evidence.`);
104
+ const artifacts = [];
105
+ const files = (paths, name, requiredFile = false) => {
106
+ if (!Array.isArray(paths) || paths.some(path => !text(path)) || new Set(paths).size !== paths.length || (requiredFile && !paths.length)) throw new Error(`${name} needs ${requiredFile ? 'at least one' : 'an array of unique'} project-relative artifact path${requiredFile ? '' : 's'}.`);
107
+ for (const path of paths) {
108
+ if (path.includes('\\') || path.split('/').some(part => part === '..' || part === '.')) throw new Error('Assessment paths must be canonical project-relative paths using forward slashes.');
109
+ if (path.replaceAll('\\', '/') === reviewPath(state)) throw new Error('The generated review cannot be its own assessment evidence.');
110
+ artifacts.push(fingerprint(path));
111
+ }
112
+ };
113
+ if (packet.stage === 'scout') {
114
+ const { context, approach, alignment, consumers } = assessment;
115
+ requireChoice(context?.status, ['used', 'none'], 'context.status');
116
+ requireText(context.evidence, 'Context lookup');
117
+ requireText(context.freshness, 'Context freshness');
118
+ files(context.sources, 'context.sources', context.status === 'used');
119
+ if (context.status === 'none' && context.sources.length) throw new Error('No-context assessment cannot list used sources.');
120
+ // Read files are not fingerprinted (the build changes them), but they stay inside the project.
121
+ const projectRelative = path => text(path) && !path.startsWith('/') && !/^[a-zA-Z]:/.test(path) && path.split('/').every(part => part && part !== '.' && part !== '..');
122
+ if (context.read !== undefined && (!Array.isArray(context.read) || !context.read.every(projectRelative))) throw new Error('context.read needs an array of project-relative paths using forward slashes, with no "..".');
123
+ requireChoice(approach?.kind, ['reuse', 'extend', 'repair', 'create'], 'approach.kind');
124
+ requireText(approach.evidence, 'Existing functionality and chosen approach');
125
+ requireChoice(alignment?.status, ['clear', 'confirmed', 'needs-input'], 'alignment.status');
126
+ requireText(alignment.evidence, 'Developer alignment');
127
+ if (alignment.status === 'needs-input') throw new Error('Unresolved developer alignment must be recorded blocked, not passed.');
128
+ if (!Array.isArray(consumers) || !consumers.length || new Set(consumers.map(item => item?.id)).size !== consumers.length) throw new Error('Scout needs unique consumers, including the directly affected behavior.');
129
+ for (const consumer of consumers) {
130
+ if (!/^[a-zA-Z0-9_-]+$/.test(consumer?.id ?? '')) throw new Error('Consumer needs a stable id.');
131
+ requireText(consumer.description, 'Consumer description');
132
+ requireText(consumer.check, 'Consumer check');
133
+ }
134
+ }
135
+ if (packet.stage === 'verify') {
136
+ const { semanticReview, consumerChecks } = assessment;
137
+ requireChoice(semanticReview?.reviewer, ['self', 'fresh-context', 'peer'], 'semanticReview.reviewer');
138
+ for (const axis of ['intent', 'consumers', 'conventions']) requireText(semanticReview[axis], `Semantic review ${axis}`);
139
+ if (!Array.isArray(semanticReview.findings)) throw new Error('Semantic review needs findings (an empty array means no findings).');
140
+ if (new Set(semanticReview.findings.map(item => item?.id)).size !== semanticReview.findings.length) throw new Error(`Review finding ids must be unique. ${findingShape}`);
141
+ for (const finding of semanticReview.findings) {
142
+ try {
143
+ requireText(finding?.id, 'Finding id');
144
+ requireChoice(finding.status, ['resolved', 'dismissed', 'open'], `Finding ${finding.id} status`);
145
+ requireText(finding.evidence, `Finding ${finding.id} resolution or dismissal`);
146
+ } catch (error) { throw new Error(`${error.message} ${findingShape}`); }
147
+ if (finding.status === 'open') throw new Error('Open semantic review findings prevent passing verification.');
148
+ }
149
+ const scout = state.handoffs.findLast(item => item.stage === 'scout' && item.status === 'passed');
150
+ if (!Array.isArray(consumerChecks) || new Set(consumerChecks.map(item => item?.id)).size !== consumerChecks.length) throw new Error('Consumer checks must have unique ids.');
151
+ for (const consumer of scout?.assessment?.consumers ?? []) {
152
+ if (!consumerChecks.some(item => item?.id === consumer.id)) throw new Error(`Missing check for affected consumer ${consumer.id}.`);
153
+ }
154
+ for (const check of consumerChecks) {
155
+ requireText(check?.id, 'Consumer check id');
156
+ requireText(check.evidence, 'Consumer check result');
157
+ if (check.result !== 'passed') throw new Error(`Consumer ${check.id} is not verified; repair or record a blocked handoff.`);
158
+ }
159
+ }
160
+ if (packet.stage === 'deliver') {
161
+ for (const name of ['learning', 'errorHistory']) {
162
+ const entry = assessment[name];
163
+ requireChoice(entry?.status, name === 'learning' ? ['recorded', 'none', 'pending-acceptance'] : ['recorded', 'none'], `${name}.status`);
164
+ requireText(entry.reason, `${name} disposition`);
165
+ files(entry.artifacts, `${name}.artifacts`, entry.status !== 'none');
166
+ if (entry.status === 'none' && entry.artifacts.length) throw new Error(`${name}: none cannot list recorded artifacts.`);
167
+ if (entry.status === 'pending-acceptance' && entry.artifacts.some(path => !path.replaceAll('\\', '/').startsWith(`.cyc/runs/${state.id}/`))) throw new Error('Pending learning belongs in this run directory until acceptance; do not present it as established project knowledge.');
168
+ }
169
+ const history = assessment.errorHistory;
170
+ if ((state.playbook === 'bug-fix' || state.failures > 0) && history.status !== 'recorded') throw new Error(`Bug fixes and runs with recorded failures need error-history evidence: set errorHistory.status to "recorded", give the cause and fix in reason, and list ${state.ledgerPath} in artifacts after adding the entry there.`);
171
+ if (history.status === 'recorded' && !history.artifacts.includes(state.ledgerPath)) throw new Error(`Error history must reference the selected ledger: ${state.ledgerPath}.`);
172
+ }
173
+ return artifacts;
174
+ }
175
+
176
+ function findPlaceholder(value, path = 'assessment') {
177
+ if (typeof value === 'string') return /^<[\s\S]*>$/.test(value.trim()) ? path : null;
178
+ if (Array.isArray(value)) { for (const [index, item] of value.entries()) { const found = findPlaceholder(item, `${path}[${index}]`); if (found) return found; } return null; }
179
+ if (value && typeof value === 'object') { for (const [key, item] of Object.entries(value)) { const found = findPlaceholder(item, `${path}.${key}`); if (found) return found; } }
180
+ return null;
181
+ }
182
+
183
+ const safe = value => String(value ?? '').replaceAll('&', '&amp;').replaceAll('<', '&lt;').replaceAll('>', '&gt;').replaceAll('|', '\\|').replaceAll('`', '\\`').replaceAll('\r', '').replaceAll('\n', ' ');
184
+
185
+ export function renderReview(state, currentSourceHash, artifactIssues = []) {
186
+ const passed = stage => state.handoffs.findLast(item => item.stage === stage && item.status === 'passed');
187
+ const scout = state.workContractVersion === 1 ? passed('scout')?.assessment : null;
188
+ const verification = passed('verify');
189
+ const delivery = passed('deliver');
190
+ const current = state.verification?.passed && state.verification.sourceHash === currentSourceHash;
191
+ const semanticCurrent = verification?.sourceHash === currentSourceHash;
192
+ const evidenceCurrent = (delivery ?? verification)?.sourceHash === currentSourceHash && !artifactIssues.length && (!state.requiresChecks || current);
193
+ const lines = [
194
+ '# Change review', '', safe(state.goal), '',
195
+ `Run: ${safe(state.id)} · Status: ${safe(state.status)} · Playbook: ${safe(state.playbook)}`,
196
+ `Contract: ${state.workContractVersion === 1 ? 'implementation assessments v1' : 'legacy/advisory handoffs; implementation assessments not required'}`,
197
+ `Current covered source: ${safe(currentSourceHash)}`, '',
198
+ `Delivery evidence: ${evidenceCurrent ? 'current' : 'not yet established or stale'}. Recorded run status is historical when evidence is stale.`, '',
199
+ 'Generated from recorded evidence. Agent assessments are self-reported; this document does not establish human approval or authorize publication. Refresh with `cyc run review --run ID` after external changes. Reuse this document for developer review and an authorized PR.', '',
200
+ '## Outcome and criteria', '', '| Criterion | Result | Evidence |', '| --- | --- | --- |'
201
+ ];
202
+ for (const criterion of state.criteria) {
203
+ const result = (delivery ?? verification)?.criteria.find(item => item.id === criterion.id);
204
+ lines.push(`| ${safe(criterion.description)} | ${safe(result ? (!evidenceCurrent ? 'stale / unverified' : result.result) : 'unverified')} | ${safe(result?.evidence ?? 'Not yet established')} |`);
205
+ }
206
+ lines.push('', '## Context, approach, and alignment', '');
207
+ if (scout) {
208
+ lines.push(`- Context (${safe(scout.context.status)}): ${safe(scout.context.evidence)}`, `- Freshness: ${safe(scout.context.freshness)}`, `- Sources: ${scout.context.sources.map(safe).join(', ') || 'none'}${scout.context.read?.length ? `; read: ${scout.context.read.map(safe).join(', ')}` : ''}`, `- Approach (${safe(scout.approach.kind)}): ${safe(scout.approach.evidence)}`, `- Alignment (${safe(scout.alignment.status)}): ${safe(scout.alignment.evidence)}`);
209
+ } else lines.push('No current Scout assessment recorded.');
210
+ lines.push('', '## Changes', '');
211
+ for (const handoff of state.handoffs.filter(item => item.stage === 'build' && item.status === 'passed')) lines.push(`- ${safe(handoff.summary)}`, ...handoff.artifacts.map(item => ` - ${safe(item.path)} (${safe(item.sha256)})`));
212
+ const preexisting = (state.acceptedFailures ?? []).filter(item => state.verification?.acceptedPreexistingFailures?.includes(item.id));
213
+ lines.push('', '## Verification and semantic review', '', `Configured checks: ${!state.requiresChecks ? 'not required for this advisory route' : current ? `passed on current covered source${preexisting.length ? `, with ${preexisting.length} accepted pre-existing failure${preexisting.length > 1 ? 's' : ''}` : ''}` : 'not current and passing'}.`);
214
+ for (const result of state.verification?.results ?? []) {
215
+ const accepted = preexisting.find(item => item.id === result.id);
216
+ lines.push(`- ${safe(result.id)}: ${result.passed ? 'passed' : accepted ? `failed, as it did on the run-start code; accepted: ${safe(accepted.reason)}` : 'failed'} (exit ${safe(result.exitCode)}); ${safe([result.command, ...result.args].join(' '))}`);
217
+ }
218
+ const proof = state.testProof;
219
+ if (state.sourceCapture?.version === 1) lines.push(`Run-start recovery record: ${state.base ? 'Git base plus ' : ''}${safe(state.sourceCapture.files.length)} captured originals, ${safe(state.sourceCapture.bytes)} stored bytes. Capture follows selected source and task scope; it is not a checkout backup.`);
220
+ const exemption = verification?.assessment?.testProof;
221
+ if (state.proofRecovery) lines.push(`Test proof: halted after a source conflict or restoration failure. Candidate backup: ${safe(state.proofRecovery.backupPath)}. Preserve current files; compare and merge deliberately.`);
222
+ else if (exemption?.status === 'exempt') lines.push(`Test proof: exempt. ${safe(exemption.reason)}`);
223
+ else if (proof) lines.push(`Test proof (${proof.mode === 'green' ? 'must pass on the original code' : 'must fail on the original code'}): ${proof.passed ? 'proven' : 'not proven'}. ${safe(proof.verdict)} Tests: ${Object.keys(proof.testFiles).map(safe).join(', ')}.${proof.claim ? ` Claim a reply may make: ${safe(proof.claim)}` : ''}`);
224
+ else if (state.sourceCapture?.version === 1) lines.push('Test proof: not yet established; run-start originals are available through Git and/or captured source.');
225
+ else if (['bug-fix', 'feature', 'refactor'].includes(state.playbook) && state.base === null) lines.push('Test proof: unavailable (this older run has no Git base or run-start source capture).');
226
+ const assessment = state.workContractVersion === 1 ? verification?.assessment : null;
227
+ if (assessment) {
228
+ lines.push(`Semantic review: ${semanticCurrent ? 'current' : 'stale'}; reviewer: ${safe(assessment.semanticReview.reviewer)}.`);
229
+ for (const axis of ['intent', 'consumers', 'conventions']) lines.push(`- ${axis}: ${safe(assessment.semanticReview[axis])}`);
230
+ for (const check of assessment.consumerChecks) lines.push(`- Consumer ${safe(check.id)}: ${safe(check.result)} — ${safe(check.evidence)}`);
231
+ if (!assessment.semanticReview.findings.length) lines.push('- No semantic findings recorded.');
232
+ for (const finding of assessment.semanticReview.findings) lines.push(`- ${safe(finding.id)} (${safe(finding.status)}): ${safe(finding.evidence)}`);
233
+ } else lines.push('No passing semantic-review assessment recorded.');
234
+ lines.push('', '## Learning and error history', '');
235
+ lines.push(`Project ledger lookup: ${safe(state.projectLedgerPath ?? state.ledgerPath ?? 'not captured')}. Error history target: ${safe(state.ledgerPath ?? 'not captured')}.`);
236
+ if (state.ledgerNote) lines.push(`Run-local history: ${safe(state.ledgerNote)} This does not claim the shared project ledger was updated.`);
237
+ for (const name of ['learning', 'errorHistory']) {
238
+ const entry = state.workContractVersion === 1 ? delivery?.assessment?.[name] : null;
239
+ lines.push(entry ? `- ${name} (${safe(entry.status)}): ${safe(entry.reason)}${entry.artifacts.length ? ` — ${entry.artifacts.map(safe).join(', ')}` : ''}` : `- ${name}: not yet recorded.`);
240
+ }
241
+ if (delivery) lines.push(`- Context docs touched: ${delivery.contextDocs?.length ? delivery.contextDocs.map(safe).join(', ') : 'none'}. Propose the component doc entry with cyc context review --run ${safe(state.id)}.`);
242
+ lines.push('', '## Recovery, remaining risks, and decisions', '');
243
+ for (const conflict of state.proofRecovery?.conflicts ?? []) lines.push(`- Proof conflict ${safe(conflict.path)}: ${safe(conflict.reason)}${conflict.savedUnexpected ? ` Unexpected bytes saved at ${safe(conflict.savedUnexpected)}.` : ''}${conflict.preservationError ? ` ${safe(conflict.preservationError)}` : ''}`);
244
+ if (state.proofRecovery?.preservationError) lines.push(`- Proof recovery record: ${safe(state.proofRecovery.preservationError)}`);
245
+ for (const issue of artifactIssues) lines.push(`- Stale artifact: ${safe(issue)}`);
246
+ for (const event of state.history.filter(item => ['attempt-failed', 'retry', 'blocked', 'exhausted', 'guard-halt', 'stopped', 'paused'].includes(item.type))) lines.push(`- ${safe(event.type)}: ${safe(event.reason ?? event.action ?? JSON.stringify({ protectedChanges: event.protectedChanges, outOfScope: event.outOfScope }))}`);
247
+ for (const handoff of state.handoffs.filter(item => item.status !== 'passed')) {
248
+ lines.push(`- ${safe(handoff.status)} at ${safe(handoff.stage)}: ${safe(handoff.summary)}`);
249
+ const findings = handoff.assessment?.semanticReview?.findings;
250
+ if (Array.isArray(findings)) for (const finding of findings) lines.push(` - ${safe(finding?.id)} (${safe(finding?.status)}): ${safe(finding?.evidence)}`);
251
+ if (handoff.nextAction) lines.push(` - Next: ${safe(handoff.nextAction)}`);
252
+ }
253
+ lines.push(`- ${safe(delivery?.summary ?? 'No passing delivery recorded.')}`);
254
+ if (delivery?.nextAction) lines.push(`- Next decision: ${safe(delivery.nextAction)}`);
255
+ lines.push('- Publication and merge approval remain governed by the user and project.', '');
256
+ return lines.join('\n');
257
+ }