cyc-stack 0.0.0-stage → 0.7.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/.agents/plugins/marketplace.json +12 -0
- package/.claude-plugin/marketplace.json +14 -0
- package/.claude-plugin/plugin.json +17 -0
- package/.codex-plugin/plugin.json +33 -0
- package/.cursor-plugin/marketplace.json +13 -0
- package/.cursor-plugin/plugin.json +19 -0
- package/INSTALL.md +153 -0
- package/LICENSE +21 -0
- package/README.md +436 -2
- package/bin/cyc.mjs +294 -0
- package/catalog/playbooks.json +20 -0
- package/docs/README.md +30 -0
- package/docs/assets/cyc-method-library.svg +39 -0
- package/docs/assets/cyc-overview.svg +44 -0
- package/docs/assets/cyc-readme-banner-mobile.svg +31 -0
- package/docs/assets/cyc-readme-banner.svg +39 -0
- package/docs/assets/cyc-workflow-diagram.svg +415 -0
- package/docs/code-quality.md +42 -0
- package/docs/context.md +40 -0
- package/docs/cyc-method-map.md +58 -0
- package/docs/cyc-workflow.md +188 -0
- package/docs/engineering/code-standards.md +103 -0
- package/docs/engineering/domain-design.md +81 -0
- package/docs/engineering/failure-handling.md +105 -0
- package/docs/impact-analysis.md +70 -0
- package/docs/installation.md +198 -0
- package/docs/onboarding-recovery.md +75 -0
- package/docs/principles.md +49 -0
- package/docs/project-tools.md +108 -0
- package/docs/response-standard.md +202 -0
- package/docs/runtime.md +249 -0
- package/docs/skill-contract.md +70 -0
- package/docs/skill-craft.md +23 -0
- package/docs/validation.md +39 -0
- package/docs/work-assessments.md +180 -0
- package/hooks/claude.json +10 -0
- package/hooks/codex.json +28 -0
- package/hooks/cursor.json +8 -0
- package/methods/cyc-build/SKILL.md +65 -0
- package/methods/cyc-build/references/file-writes.md +11 -0
- package/methods/cyc-challenge/SKILL.md +48 -0
- package/methods/cyc-context/SKILL.md +76 -0
- package/methods/cyc-context/references/evidence.md +27 -0
- package/methods/cyc-context/references/templates.md +54 -0
- package/methods/cyc-context/scripts/evidence.mjs +61 -0
- package/methods/cyc-correct/SKILL.md +43 -0
- package/methods/cyc-deliver/SKILL.md +52 -0
- package/methods/cyc-design/SKILL.md +50 -0
- package/methods/cyc-design/frontend-design/SKILL.md +43 -0
- package/methods/cyc-design/frontend-design/references/color.md +77 -0
- package/methods/cyc-design/frontend-design/references/craft-rules.md +61 -0
- package/methods/cyc-design/frontend-design/references/decision-sheet.md +110 -0
- package/methods/cyc-design/frontend-design/references/experience-review.md +58 -0
- package/methods/cyc-design/frontend-design/references/generic-tells.md +76 -0
- package/methods/cyc-design/frontend-design/references/layout-archetypes.md +188 -0
- package/methods/cyc-design/frontend-design/references/reference-standards.md +38 -0
- package/methods/cyc-design/frontend-design/references/typography.md +51 -0
- package/methods/cyc-design/frontend-design/references/ux-foundations.md +45 -0
- package/methods/cyc-design/frontend-design/references/visual-material.md +42 -0
- package/methods/cyc-error-ledger/SKILL.md +53 -0
- package/methods/cyc-error-ledger/references/entry-format.md +38 -0
- package/methods/cyc-explore/SKILL.md +41 -0
- package/methods/cyc-frame/SKILL.md +49 -0
- package/methods/cyc-impact/SKILL.md +64 -0
- package/methods/cyc-reflect/SKILL.md +48 -0
- package/methods/cyc-remember/SKILL.md +53 -0
- package/methods/cyc-scout/SKILL.md +67 -0
- package/methods/cyc-setup/SKILL.md +60 -0
- package/methods/cyc-teach/SKILL.md +40 -0
- package/methods/cyc-understand/SKILL.md +40 -0
- package/methods/cyc-understand/references/diagnose.md +53 -0
- package/methods/cyc-verify/SKILL.md +87 -0
- package/methods/cyc-verify/references/recipe.md +53 -0
- package/package.json +91 -4
- package/plugin.json +40 -0
- package/rules/cyc-delivery.mdc +33 -0
- package/scripts/baseline-worker.mjs +10 -0
- package/scripts/catalog.mjs +29 -0
- package/scripts/claude-project-hook.mjs +12 -0
- package/scripts/context-review.mjs +600 -0
- package/scripts/host-activation.mjs +66 -0
- package/scripts/install.mjs +387 -0
- package/scripts/onboarding.mjs +110 -0
- package/scripts/packet.mjs +107 -0
- package/scripts/project-tools.mjs +196 -0
- package/scripts/recovery.mjs +66 -0
- package/scripts/response-gate.mjs +105 -0
- package/scripts/response-hook.mjs +237 -0
- package/scripts/response-mode.mjs +12 -0
- package/scripts/run-gate.mjs +264 -0
- package/scripts/runtime.mjs +1832 -0
- package/scripts/source-hash-worker.mjs +5 -0
- package/scripts/source-snapshot.mjs +405 -0
- package/scripts/test-output.mjs +268 -0
- package/scripts/work-review.mjs +326 -0
- package/skills/cyc/SKILL.md +132 -0
- package/skills/cyc/references/playbooks/bug-fix.md +13 -0
- package/skills/cyc/references/playbooks/evaluate.md +13 -0
- package/skills/cyc/references/playbooks/experience.md +7 -0
- package/skills/cyc/references/playbooks/explore.md +9 -0
- package/skills/cyc/references/playbooks/feature.md +14 -0
- package/skills/cyc/references/playbooks/handoff.md +11 -0
- package/skills/cyc/references/playbooks/investigation.md +7 -0
- package/skills/cyc/references/playbooks/performance.md +7 -0
- package/skills/cyc/references/playbooks/plan.md +11 -0
- package/skills/cyc/references/playbooks/refactor.md +12 -0
- package/skills/cyc/references/playbooks/reflect.md +11 -0
- package/skills/cyc/references/playbooks/resume.md +11 -0
- package/skills/cyc/references/playbooks/review.md +9 -0
- package/skills/cyc/references/playbooks/teach.md +11 -0
- package/skills/cyc/references/playbooks/verify.md +7 -0
|
@@ -0,0 +1,268 @@
|
|
|
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);
|
|
259
|
+
|
|
260
|
+
// Diagnostic hints only. A TypeError or load failure can itself be the real old bug;
|
|
261
|
+
// only a case-specific reason review can establish the meaning of a failure.
|
|
262
|
+
export function failureHint(entry) {
|
|
263
|
+
const error = `${entry.error ?? ''}\n${(entry.details ?? []).join('\n')}`;
|
|
264
|
+
if (/ERR_MODULE_NOT_FOUND|Cannot find (?:module|package)|does not provide an export|ModuleNotFoundError/.test(error)) return 'module-load';
|
|
265
|
+
if (/AssertionError|ERR_ASSERTION|assertion failed|Expected:|expected .* to /i.test(error)) return 'assertion';
|
|
266
|
+
if (/timeout|timed out|ENOENT|ECONNREFUSED/.test(error)) return 'execution-or-setup';
|
|
267
|
+
return 'unclassified';
|
|
268
|
+
}
|
|
@@ -0,0 +1,326 @@
|
|
|
1
|
+
import { digest } from './response-gate.mjs';
|
|
2
|
+
|
|
3
|
+
// These checks establish recorded process evidence, not the truth of an agent's judgment.
|
|
4
|
+
const text = value => typeof value === 'string' && value.trim().length > 0;
|
|
5
|
+
const object = value => value && typeof value === 'object' && !Array.isArray(value);
|
|
6
|
+
const requireText = (value, name) => { if (!text(value)) throw new Error(`${name} needs meaningful evidence.`); };
|
|
7
|
+
const requireChoice = (value, choices, name) => { if (!choices.includes(value)) throw new Error(`${name} must be ${choices.join(', ')}.`); };
|
|
8
|
+
export const reviewPath = state => `.cyc/runs/${state.id}/review.md`;
|
|
9
|
+
|
|
10
|
+
export function assessmentRequirements(state, stage) {
|
|
11
|
+
if (state.workContractVersion !== 1) return [];
|
|
12
|
+
const keys = ({ scout: ['context', 'approach', 'alignment', 'consumers'], verify: ['semanticReview', 'consumerChecks'], deliver: ['learning', 'errorHistory'] })[stage] ?? [];
|
|
13
|
+
return stage === 'verify' && state.evidenceVersion === 1 ? [...keys, 'criterionChecks'] : keys;
|
|
14
|
+
}
|
|
15
|
+
|
|
16
|
+
export const criterionClauses = state => state.criteria.flatMap(c => (c.clauses ?? [{ id: undefined }]).map(clause => ({ id: c.id, clause: clause.id })));
|
|
17
|
+
|
|
18
|
+
// Coverage records describe source provenance. They do not attest reviewer independence.
|
|
19
|
+
export function reviewCoverage(state, review, sourceHash) {
|
|
20
|
+
const refs = review?.receipts ?? [];
|
|
21
|
+
const entries = refs.map(id => (state.reviewReceipts ?? []).find(r => r.id === id));
|
|
22
|
+
if (!entries.length) return { status: review?.reviewer === 'self' ? 'self-assessment' : 'unlinked', entries: [] };
|
|
23
|
+
const stale = entries.some(r => !r || r.status !== 'recorded' || r.sourceHash !== sourceHash || r.criteriaHash !== (state.criteriaHash ?? digest(JSON.stringify(state.criteria))));
|
|
24
|
+
const kinds = new Set(entries.filter(Boolean).map(r => r.reviewer));
|
|
25
|
+
return { status: stale ? 'stale' : kinds.size > 1 ? 'mixed' : 'source-linked', entries };
|
|
26
|
+
}
|
|
27
|
+
|
|
28
|
+
export function validateProofReview(state, review) {
|
|
29
|
+
if (state.evidenceVersion !== 1 || !state.testProof?.passed || state.testProof.mode === 'green') return;
|
|
30
|
+
if (!object(review) || !Array.isArray(review.cases) || !review.cases.length) throw new Error('Diagnostic red needs proofReview.cases with a reason review of decisive failures; run prove-red first.');
|
|
31
|
+
if (!['current-proof', state.testProof.receiptPath].includes(review.receipt)) throw new Error('proofReview must reference the current proof receipt.');
|
|
32
|
+
if (new Set(review.cases.map(c => c?.id)).size !== review.cases.length) throw new Error('proofReview case ids must be unique.');
|
|
33
|
+
for (const item of review.cases) {
|
|
34
|
+
if (!state.testProof.failures?.some(f => f.id === item?.id)) throw new Error(`Unknown proof failure ${item?.id}.`);
|
|
35
|
+
requireChoice(item.category, ['behavioral', 'new-interface', 'setup', 'unclassified'], 'Proof category');
|
|
36
|
+
requireText(item.reason, 'Proof reason');
|
|
37
|
+
if (item.category === 'behavioral') requireText(item.boundary, 'Existing observable boundary');
|
|
38
|
+
}
|
|
39
|
+
const decisive = state.playbook === 'bug-fix' ? ['behavioral'] : ['behavioral', 'new-interface'];
|
|
40
|
+
if (!review.cases.some(c => decisive.includes(c.category))) throw new Error('No decisive behavioral proof for this bug fix (features may prove a new interface); setup and unclassified failures remain diagnostic.');
|
|
41
|
+
}
|
|
42
|
+
|
|
43
|
+
// Fields the controller records when the agent leaves them out, limited to what its own record
|
|
44
|
+
// shows: nothing reusable was recorded; a run that is not a bug fix had no failed attempt; or the
|
|
45
|
+
// project keeps no context history to consult. A bug fix's cause, consumer evidence and review
|
|
46
|
+
// findings are judgment, and always come from the agent.
|
|
47
|
+
export function derivedAssessment(state, stage, { contextHistory = true } = {}) {
|
|
48
|
+
if (state.workContractVersion !== 1) return {};
|
|
49
|
+
if (stage === 'scout') return contextHistory ? {} : {
|
|
50
|
+
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: [] }
|
|
51
|
+
};
|
|
52
|
+
if (stage === 'deliver') return {
|
|
53
|
+
learning: { status: 'none', reason: 'Not given at finish: no reusable learning was recorded for this run.', artifacts: [] },
|
|
54
|
+
...(state.playbook !== 'bug-fix' && !state.failures ? { errorHistory: { status: 'none', reason: 'Not given at finish: this run recorded no failed attempt.', artifacts: [] } } : {})
|
|
55
|
+
};
|
|
56
|
+
return {};
|
|
57
|
+
}
|
|
58
|
+
|
|
59
|
+
// A fill-in skeleton for the current stage, so agents never need to read the contract docs to
|
|
60
|
+
// write a valid assessment. Angle-bracket strings and "a | b" choices are placeholders that
|
|
61
|
+
// validation rejects, so a template submitted unedited can never pass.
|
|
62
|
+
export function assessmentTemplate(state, stage) {
|
|
63
|
+
const required = assessmentRequirements(state, stage);
|
|
64
|
+
if (!required.length) return null;
|
|
65
|
+
const scoutConsumers = state.handoffs?.findLast(item => item.stage === 'scout' && item.status === 'passed')?.assessment?.consumers ?? [];
|
|
66
|
+
const templates = {
|
|
67
|
+
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>'] },
|
|
68
|
+
approach: { kind: 'reuse | extend | repair | create', evidence: '<existing code you found and why this approach>' },
|
|
69
|
+
alignment: { status: 'clear | confirmed', evidence: '<why the request is unambiguous, or what the user confirmed>' },
|
|
70
|
+
consumers: [{ id: 'direct', description: '<the behavior you are changing>', check: '<how you will verify it>' }],
|
|
71
|
+
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: [] },
|
|
72
|
+
consumerChecks: (scoutConsumers.length ? scoutConsumers : [{ id: 'direct' }]).map(item => ({ id: item.id, result: 'passed', evidence: '<the command or observation that showed it works>' })),
|
|
73
|
+
criterionChecks: criterionClauses(state).map(item => ({ ...item, scenario: '<named scenario for this original outcome/clause>', check: '<configured command id>', receipt: 'current-verification', result: 'passed', origin: 'agent-reported', evidence: '<what this scenario established; not a suite count>' })),
|
|
74
|
+
learning: { status: 'none | recorded | pending-acceptance', reason: '<why nothing is reusable, or what was recorded>', artifacts: [] },
|
|
75
|
+
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'] : [] }
|
|
76
|
+
};
|
|
77
|
+
return Object.fromEntries(required.map(key => [key, templates[key]]));
|
|
78
|
+
}
|
|
79
|
+
|
|
80
|
+
// Accept common spellings of the same structure, in place. Evidence is never filled in: every
|
|
81
|
+
// reason, finding, and check result still has to come from the agent.
|
|
82
|
+
function normalizeAssessment(assessment) {
|
|
83
|
+
const canonical = paths => Array.isArray(paths) ? paths.map(path => typeof path === 'string' ? path.replaceAll('\\', '/').replace(/^\.\//, '') : path) : paths;
|
|
84
|
+
const { context, semanticReview, consumerChecks, learning, errorHistory } = assessment;
|
|
85
|
+
if (object(context)) {
|
|
86
|
+
if (context.status === 'none' && context.sources === undefined) context.sources = [];
|
|
87
|
+
context.sources = canonical(context.sources);
|
|
88
|
+
// "none" says no matched history exists; files listed with it are what was read while
|
|
89
|
+
// looking, not history sources. Keep the claim and record them as read.
|
|
90
|
+
if (context.status === 'none' && Array.isArray(context.sources) && context.sources.length) {
|
|
91
|
+
context.read = [...new Set([...(Array.isArray(context.read) ? context.read : []), ...context.sources])];
|
|
92
|
+
context.sources = [];
|
|
93
|
+
}
|
|
94
|
+
if (Array.isArray(context.read)) context.read = [...new Set(canonical(context.read))];
|
|
95
|
+
}
|
|
96
|
+
for (const entry of [learning, errorHistory]) {
|
|
97
|
+
if (!object(entry)) continue;
|
|
98
|
+
if (entry.status === 'none' && entry.artifacts === undefined) entry.artifacts = [];
|
|
99
|
+
entry.artifacts = canonical(entry.artifacts);
|
|
100
|
+
}
|
|
101
|
+
const findings = (Array.isArray(semanticReview?.findings) ? semanticReview.findings : []).filter(object);
|
|
102
|
+
const taken = new Set(findings.map(finding => finding.id));
|
|
103
|
+
let next = 1;
|
|
104
|
+
for (const finding of findings) {
|
|
105
|
+
// An id is only a label, so an unused one is supplied. Status and evidence still come from the agent.
|
|
106
|
+
if (finding.id === undefined) { while (taken.has(`f${next}`)) next += 1; finding.id = `f${next}`; taken.add(finding.id); }
|
|
107
|
+
// "dismissed: out of scope" states the status, then its evidence. Only a status word set off by
|
|
108
|
+
// a colon or a spaced dash counts, so "Fixed-width output still misaligns" names no status.
|
|
109
|
+
// Any other resolution is the agent's evidence; a missing status is still refused.
|
|
110
|
+
const spelled = typeof finding.resolution === 'string' ? /^\s*(resolved|fixed|dismissed|open)\s*(?::|\s[-–—]|$)\s*/i.exec(finding.resolution) : null;
|
|
111
|
+
if (finding.status === undefined && spelled) {
|
|
112
|
+
finding.status = spelled[1];
|
|
113
|
+
const rest = finding.resolution.slice(spelled[0].length).trim();
|
|
114
|
+
if (rest) finding.evidence ??= rest;
|
|
115
|
+
} else if (typeof finding.resolution === 'string' && finding.resolution.trim()) finding.evidence ??= finding.resolution.trim();
|
|
116
|
+
if (typeof finding.status === 'string' && /^(?:resolved|fixed|dismissed|open)$/i.test(finding.status.trim())) finding.status = finding.status.trim().toLowerCase();
|
|
117
|
+
if (finding.status === 'fixed') finding.status = 'resolved';
|
|
118
|
+
finding.evidence ??= finding.reason;
|
|
119
|
+
}
|
|
120
|
+
for (const check of Array.isArray(consumerChecks) ? consumerChecks : []) if (object(check) && check.result === 'pass') check.result = 'passed';
|
|
121
|
+
}
|
|
122
|
+
|
|
123
|
+
const findingShape = 'Each finding is {"id": "...", "status": "resolved | dismissed | open", "evidence": "..."}.';
|
|
124
|
+
|
|
125
|
+
export function validateAssessment(state, packet, fingerprint) {
|
|
126
|
+
const required = assessmentRequirements(state, packet.stage);
|
|
127
|
+
if (packet.status !== 'passed' || !required.length) return [];
|
|
128
|
+
const assessment = packet.assessment;
|
|
129
|
+
if (!object(assessment)) throw new Error(`Passing ${packet.stage} needs an assessment: ${required.join(', ')}. Use --assessment FILE or packet.assessment.`);
|
|
130
|
+
normalizeAssessment(assessment);
|
|
131
|
+
const missing = required.filter(key => !(key in assessment));
|
|
132
|
+
if (missing.length) throw new Error(`Assessment is missing ${missing.join(', ')}. Run next returns a fill-in assessmentTemplate.`);
|
|
133
|
+
const placeholder = findPlaceholder(assessment);
|
|
134
|
+
if (placeholder) throw new Error(`Replace the template placeholder at ${placeholder} with real evidence.`);
|
|
135
|
+
const artifacts = [];
|
|
136
|
+
const files = (paths, name, requiredFile = false) => {
|
|
137
|
+
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'}.`);
|
|
138
|
+
for (const path of paths) {
|
|
139
|
+
if (path.includes('\\') || path.split('/').some(part => part === '..' || part === '.')) throw new Error('Assessment paths must be canonical project-relative paths using forward slashes.');
|
|
140
|
+
if (path.replaceAll('\\', '/') === reviewPath(state)) throw new Error('The generated review cannot be its own assessment evidence.');
|
|
141
|
+
artifacts.push(fingerprint(path));
|
|
142
|
+
}
|
|
143
|
+
};
|
|
144
|
+
if (packet.stage === 'scout') {
|
|
145
|
+
const { context, approach, alignment, consumers } = assessment;
|
|
146
|
+
requireChoice(context?.status, ['used', 'none'], 'context.status');
|
|
147
|
+
requireText(context.evidence, 'Context lookup');
|
|
148
|
+
requireText(context.freshness, 'Context freshness');
|
|
149
|
+
files(context.sources, 'context.sources', context.status === 'used');
|
|
150
|
+
if (context.status === 'none' && context.sources.length) throw new Error('No-context assessment cannot list used sources.');
|
|
151
|
+
// Read files are not fingerprinted (the build changes them), but they stay inside the project.
|
|
152
|
+
const projectRelative = path => text(path) && !path.startsWith('/') && !/^[a-zA-Z]:/.test(path) && path.split('/').every(part => part && part !== '.' && part !== '..');
|
|
153
|
+
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 "..".');
|
|
154
|
+
requireChoice(approach?.kind, ['reuse', 'extend', 'repair', 'create'], 'approach.kind');
|
|
155
|
+
requireText(approach.evidence, 'Existing functionality and chosen approach');
|
|
156
|
+
requireChoice(alignment?.status, ['clear', 'confirmed', 'needs-input'], 'alignment.status');
|
|
157
|
+
requireText(alignment.evidence, 'Developer alignment');
|
|
158
|
+
if (alignment.status === 'needs-input') throw new Error('Unresolved developer alignment must be recorded blocked, not passed.');
|
|
159
|
+
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.');
|
|
160
|
+
for (const consumer of consumers) {
|
|
161
|
+
if (!/^[a-zA-Z0-9_-]+$/.test(consumer?.id ?? '')) throw new Error('Consumer needs a stable id.');
|
|
162
|
+
requireText(consumer.description, 'Consumer description');
|
|
163
|
+
requireText(consumer.check, 'Consumer check');
|
|
164
|
+
}
|
|
165
|
+
}
|
|
166
|
+
if (packet.stage === 'verify') {
|
|
167
|
+
const { semanticReview, consumerChecks } = assessment;
|
|
168
|
+
requireChoice(semanticReview?.reviewer, ['self', 'fresh-context', 'peer'], 'semanticReview.reviewer');
|
|
169
|
+
for (const axis of ['intent', 'consumers', 'conventions']) requireText(semanticReview[axis], `Semantic review ${axis}`);
|
|
170
|
+
if (!Array.isArray(semanticReview.findings)) throw new Error('Semantic review needs findings (an empty array means no findings).');
|
|
171
|
+
const findingKey = item => state.evidenceVersion === 1 ? JSON.stringify([item?.reviewId ?? null, item?.id]) : item?.id;
|
|
172
|
+
if (new Set(semanticReview.findings.map(findingKey)).size !== semanticReview.findings.length) throw new Error(`Review finding ids must be unique within their receipt scope. ${findingShape}`);
|
|
173
|
+
for (const finding of semanticReview.findings) {
|
|
174
|
+
try {
|
|
175
|
+
requireText(finding?.id, 'Finding id');
|
|
176
|
+
requireChoice(finding.status, ['resolved', 'dismissed', 'open'], `Finding ${finding.id} status`);
|
|
177
|
+
requireText(finding.evidence, `Finding ${finding.id} resolution or dismissal`);
|
|
178
|
+
} catch (error) { throw new Error(`${error.message} ${findingShape}`); }
|
|
179
|
+
if (finding.status === 'open') throw new Error('Open semantic review findings prevent passing verification.');
|
|
180
|
+
}
|
|
181
|
+
const scout = state.handoffs.findLast(item => item.stage === 'scout' && item.status === 'passed');
|
|
182
|
+
if (!Array.isArray(consumerChecks) || new Set(consumerChecks.map(item => item?.id)).size !== consumerChecks.length) throw new Error('Consumer checks must have unique ids.');
|
|
183
|
+
for (const consumer of scout?.assessment?.consumers ?? []) {
|
|
184
|
+
if (!consumerChecks.some(item => item?.id === consumer.id)) throw new Error(`Missing check for affected consumer ${consumer.id}.`);
|
|
185
|
+
}
|
|
186
|
+
for (const check of consumerChecks) {
|
|
187
|
+
requireText(check?.id, 'Consumer check id');
|
|
188
|
+
requireText(check.evidence, 'Consumer check result');
|
|
189
|
+
if (check.result !== 'passed') throw new Error(`Consumer ${check.id} is not verified; repair or record a blocked handoff.`);
|
|
190
|
+
}
|
|
191
|
+
if (state.evidenceVersion === 1) {
|
|
192
|
+
const checks = assessment.criterionChecks;
|
|
193
|
+
if (!Array.isArray(checks)) throw new Error('criterionChecks needs original outcome/clause scenarios.');
|
|
194
|
+
const key = c => JSON.stringify([c?.id, c?.clause ?? null]);
|
|
195
|
+
const expected = criterionClauses(state);
|
|
196
|
+
if (new Set(checks.map(key)).size !== checks.length) throw new Error('Duplicate criterion/clause check.');
|
|
197
|
+
for (const c of expected) if (!checks.some(item => key(item) === key(c))) throw new Error(`Missing scenario for ${c.id}${c.clause ? `/${c.clause}` : ''}.`);
|
|
198
|
+
for (const check of checks) {
|
|
199
|
+
if (!expected.some(c => key(c) === key(check))) throw new Error(`Unknown criterion/clause ${check?.id}/${check?.clause}.`);
|
|
200
|
+
requireText(check.scenario, 'Criterion scenario'); requireText(check.evidence, 'Scenario observation');
|
|
201
|
+
if (!state.commands?.some(c => c.id === check.check)) throw new Error(`Unknown configured check ${check.check}.`);
|
|
202
|
+
if (check.result !== 'passed') throw new Error(`Criterion ${check.id} is unverified; repair or record a blocked handoff.`);
|
|
203
|
+
if (check.origin !== 'agent-reported') throw new Error('Scenario results are agent-reported; command success alone does not establish a named assertion.');
|
|
204
|
+
requireText(check.receipt, 'Scenario receipt');
|
|
205
|
+
}
|
|
206
|
+
if (semanticReview.reviewer !== 'self' && !semanticReview.receipts?.length) throw new Error('Fresh/peer review needs source-linked review receipts, not a reviewer label alone.');
|
|
207
|
+
if (semanticReview.receipts !== undefined && (!Array.isArray(semanticReview.receipts) || new Set(semanticReview.receipts).size !== semanticReview.receipts.length)) throw new Error('Review receipts need unique ids.');
|
|
208
|
+
// The runtime performs source and receipt-byte checks with the actual snapshot.
|
|
209
|
+
if (!assessment.testProof?.status || assessment.testProof.status !== 'exempt') validateProofReview(state, assessment.proofReview);
|
|
210
|
+
}
|
|
211
|
+
}
|
|
212
|
+
if (packet.stage === 'deliver') {
|
|
213
|
+
for (const name of ['learning', 'errorHistory']) {
|
|
214
|
+
const entry = assessment[name];
|
|
215
|
+
requireChoice(entry?.status, name === 'learning' ? ['recorded', 'none', 'pending-acceptance'] : ['recorded', 'none'], `${name}.status`);
|
|
216
|
+
requireText(entry.reason, `${name} disposition`);
|
|
217
|
+
files(entry.artifacts, `${name}.artifacts`, entry.status !== 'none');
|
|
218
|
+
if (entry.status === 'none' && entry.artifacts.length) throw new Error(`${name}: none cannot list recorded artifacts.`);
|
|
219
|
+
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.');
|
|
220
|
+
}
|
|
221
|
+
const history = assessment.errorHistory;
|
|
222
|
+
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.`);
|
|
223
|
+
if (history.status === 'recorded' && !history.artifacts.includes(state.ledgerPath)) throw new Error(`Error history must reference the selected ledger: ${state.ledgerPath}.`);
|
|
224
|
+
}
|
|
225
|
+
return artifacts;
|
|
226
|
+
}
|
|
227
|
+
|
|
228
|
+
function findPlaceholder(value, path = 'assessment') {
|
|
229
|
+
if (typeof value === 'string') return /^<[\s\S]*>$/.test(value.trim()) ? path : null;
|
|
230
|
+
if (Array.isArray(value)) { for (const [index, item] of value.entries()) { const found = findPlaceholder(item, `${path}[${index}]`); if (found) return found; } return null; }
|
|
231
|
+
if (value && typeof value === 'object') { for (const [key, item] of Object.entries(value)) { const found = findPlaceholder(item, `${path}.${key}`); if (found) return found; } }
|
|
232
|
+
return null;
|
|
233
|
+
}
|
|
234
|
+
|
|
235
|
+
const safe = value => String(value ?? '').replaceAll('&', '&').replaceAll('<', '<').replaceAll('>', '>').replaceAll('|', '\\|').replaceAll('`', '\\`').replaceAll('\r', '').replaceAll('\n', ' ');
|
|
236
|
+
|
|
237
|
+
export function renderReview(state, currentSourceHash, artifactIssues = []) {
|
|
238
|
+
const passed = stage => state.handoffs.findLast(item => item.stage === stage && item.status === 'passed');
|
|
239
|
+
const scout = state.workContractVersion === 1 ? passed('scout')?.assessment : null;
|
|
240
|
+
const verification = passed('verify');
|
|
241
|
+
const delivery = passed('deliver');
|
|
242
|
+
const current = state.verification?.passed && state.verification.sourceHash === currentSourceHash;
|
|
243
|
+
const semanticCurrent = verification?.sourceHash === currentSourceHash;
|
|
244
|
+
const evidenceCurrent = (delivery ?? verification)?.sourceHash === currentSourceHash && !artifactIssues.length && (!state.requiresChecks || current);
|
|
245
|
+
const lines = [
|
|
246
|
+
'# Change review', '', safe(state.goal), '',
|
|
247
|
+
`Run: ${safe(state.id)} · Status: ${safe(state.status)} · Playbook: ${safe(state.playbook)}`,
|
|
248
|
+
`Contract: ${state.workContractVersion === 1 ? 'implementation assessments v1' : 'legacy/advisory handoffs; implementation assessments not required'}`,
|
|
249
|
+
`Current covered source: ${safe(currentSourceHash)}`, '',
|
|
250
|
+
`Delivery evidence: ${evidenceCurrent ? 'current' : 'not yet established or stale'}. Recorded run status is historical when evidence is stale.`, '',
|
|
251
|
+
'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.', '',
|
|
252
|
+
'## Outcome and criteria', '', '| Criterion | Result | Evidence |', '| --- | --- | --- |'
|
|
253
|
+
];
|
|
254
|
+
for (const criterion of state.criteria) {
|
|
255
|
+
const result = (delivery ?? verification)?.criteria.find(item => item.id === criterion.id);
|
|
256
|
+
lines.push(`| ${safe(criterion.description)} | ${safe(result ? (!evidenceCurrent ? 'stale / unverified' : result.result) : 'unverified')} | ${safe(result?.evidence ?? 'Not yet established')} |`);
|
|
257
|
+
for (const clause of criterion.clauses ?? []) {
|
|
258
|
+
const check = verification?.assessment?.criterionChecks?.find(c => c.id === criterion.id && c.clause === clause.id);
|
|
259
|
+
lines.push(`| ${safe(criterion.id)}/${safe(clause.id)}: ${safe(clause.description)} | ${check && evidenceCurrent ? safe(check.result) : 'unverified'} | ${check ? `${safe(check.scenario)} — ${safe(check.evidence)} (agent-reported)` : 'No scenario evidence recorded'} |`);
|
|
260
|
+
}
|
|
261
|
+
}
|
|
262
|
+
lines.push('', '## Context, approach, and alignment', '');
|
|
263
|
+
if (scout) {
|
|
264
|
+
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)}`);
|
|
265
|
+
} else lines.push('No current Scout assessment recorded.');
|
|
266
|
+
lines.push('', '## Changes', '');
|
|
267
|
+
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)})`));
|
|
268
|
+
const preexisting = (state.acceptedFailures ?? []).filter(item => state.verification?.acceptedPreexistingFailures?.includes(item.id));
|
|
269
|
+
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'}.`);
|
|
270
|
+
for (const result of state.verification?.results ?? []) {
|
|
271
|
+
const accepted = preexisting.find(item => item.id === result.id);
|
|
272
|
+
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(' '))}`);
|
|
273
|
+
}
|
|
274
|
+
const proof = state.testProof;
|
|
275
|
+
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.`);
|
|
276
|
+
const exemption = verification?.assessment?.testProof;
|
|
277
|
+
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.`);
|
|
278
|
+
else if (exemption?.status === 'exempt') lines.push(`Test proof: exempt. ${safe(exemption.reason)}`);
|
|
279
|
+
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)}` : ''}`);
|
|
280
|
+
else if (state.sourceCapture?.version === 1) lines.push('Test proof: not yet established; run-start originals are available through Git and/or captured source.');
|
|
281
|
+
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).');
|
|
282
|
+
const assessment = state.workContractVersion === 1 ? verification?.assessment : null;
|
|
283
|
+
if (assessment) {
|
|
284
|
+
const coverage = reviewCoverage(state, assessment.semanticReview, currentSourceHash);
|
|
285
|
+
if (coverage.entries.length && artifactIssues.length) coverage.status = 'unverified (receipt/evidence unavailable)';
|
|
286
|
+
const reviewers = coverage.entries.length ? [...new Set(coverage.entries.filter(Boolean).map(r => r.reviewer))].join(' + ') : assessment.semanticReview.reviewer;
|
|
287
|
+
lines.push(`Semantic review: ${coverage.status === 'self-assessment' ? (semanticCurrent ? 'current' : 'stale') : coverage.status}; reviewer: ${safe(reviewers)}; provenance: agent-reported. Final assessment: ${semanticCurrent ? 'current' : 'stale'}.`);
|
|
288
|
+
for (const receipt of coverage.entries) lines.push(receipt ? `- Review ${safe(receipt.id)}: ${safe(receipt.reviewer)}, ${receipt.sourceHash === currentSourceHash ? 'matching source' : 'stale source'}; scope: ${safe(receipt.scope.length ? receipt.scope.join(', ') : 'whole covered source')}; identity: ${safe(receipt.identity ?? 'unknown')}; evidence: ${safe(receipt.path)}.` : '- Review receipt missing.');
|
|
289
|
+
if (state.evidenceVersion === 1) {
|
|
290
|
+
lines.push(`Original requirements: ${safe(state.requirements.sha256)}. Scenario observations below are agent-reported, not automatically verified named runner results.`);
|
|
291
|
+
for (const criterion of state.criteria) for (const clause of criterion.clauses ?? []) lines.push(`- Original clause ${safe(criterion.id)}/${safe(clause.id)}: ${safe(clause.description)}`);
|
|
292
|
+
for (const check of assessment.criterionChecks ?? []) lines.push(`- Outcome ${safe(check.id)}${check.clause ? `/${safe(check.clause)}` : ''}: ${evidenceCurrent ? safe(check.result) : 'stale / unverified'} — ${safe(check.scenario)}; check ${safe(check.check)}, receipt ${safe(check.receipt)}; ${safe(check.evidence)}`);
|
|
293
|
+
}
|
|
294
|
+
for (const failure of proof?.failures ?? []) {
|
|
295
|
+
const reason = assessment.proofReview?.cases?.find(c => c.id === failure.id);
|
|
296
|
+
lines.push(`- Baseline failure ${safe(failure.id)}: ${safe(failure.name)} — ${safe(reason?.category ?? 'unclassified')}; hint: ${safe(failure.hint)}. ${safe(reason?.reason ?? 'No semantic reason review recorded.')} ${reason?.boundary ? `Boundary: ${safe(reason.boundary)}.` : ''}`);
|
|
297
|
+
}
|
|
298
|
+
for (const axis of ['intent', 'consumers', 'conventions']) lines.push(`- ${axis}: ${safe(assessment.semanticReview[axis])}`);
|
|
299
|
+
for (const check of assessment.consumerChecks) lines.push(`- Consumer ${safe(check.id)}: ${safe(check.result)} — ${safe(check.evidence)}`);
|
|
300
|
+
if (!assessment.semanticReview.findings.length) lines.push('- No semantic findings recorded.');
|
|
301
|
+
for (const finding of assessment.semanticReview.findings) lines.push(`- ${finding.reviewId ? `${safe(finding.reviewId)}/` : ''}${safe(finding.id)} (${safe(finding.status)}): ${safe(finding.evidence)}`);
|
|
302
|
+
} else lines.push('No passing semantic-review assessment recorded.');
|
|
303
|
+
lines.push('', '## Learning and error history', '');
|
|
304
|
+
lines.push(`Project ledger lookup: ${safe(state.projectLedgerPath ?? state.ledgerPath ?? 'not captured')}. Error history target: ${safe(state.ledgerPath ?? 'not captured')}.`);
|
|
305
|
+
if (state.ledgerNote) lines.push(`Run-local history: ${safe(state.ledgerNote)} This does not claim the shared project ledger was updated.`);
|
|
306
|
+
for (const name of ['learning', 'errorHistory']) {
|
|
307
|
+
const entry = state.workContractVersion === 1 ? delivery?.assessment?.[name] : null;
|
|
308
|
+
lines.push(entry ? `- ${name} (${safe(entry.status)}): ${safe(entry.reason)}${entry.artifacts.length ? ` — ${entry.artifacts.map(safe).join(', ')}` : ''}` : `- ${name}: not yet recorded.`);
|
|
309
|
+
}
|
|
310
|
+
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)}.`);
|
|
311
|
+
lines.push('', '## Recovery, remaining risks, and decisions', '');
|
|
312
|
+
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)}` : ''}`);
|
|
313
|
+
if (state.proofRecovery?.preservationError) lines.push(`- Proof recovery record: ${safe(state.proofRecovery.preservationError)}`);
|
|
314
|
+
for (const issue of artifactIssues) lines.push(`- Stale artifact: ${safe(issue)}`);
|
|
315
|
+
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 }))}`);
|
|
316
|
+
for (const handoff of state.handoffs.filter(item => item.status !== 'passed')) {
|
|
317
|
+
lines.push(`- ${safe(handoff.status)} at ${safe(handoff.stage)}: ${safe(handoff.summary)}`);
|
|
318
|
+
const findings = handoff.assessment?.semanticReview?.findings;
|
|
319
|
+
if (Array.isArray(findings)) for (const finding of findings) lines.push(` - ${safe(finding?.id)} (${safe(finding?.status)}): ${safe(finding?.evidence)}`);
|
|
320
|
+
if (handoff.nextAction) lines.push(` - Next: ${safe(handoff.nextAction)}`);
|
|
321
|
+
}
|
|
322
|
+
lines.push(`- ${safe(delivery?.summary ?? 'No passing delivery recorded.')}`);
|
|
323
|
+
if (delivery?.nextAction) lines.push(`- Next decision: ${safe(delivery.nextAction)}`);
|
|
324
|
+
lines.push('- Publication and merge approval remain governed by the user and project.', '');
|
|
325
|
+
return lines.join('\n');
|
|
326
|
+
}
|