ai-engineering-loop 2.9.0 → 2.10.1
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/skills/ael/references/loop-commands.md +1 -0
- package/.agents/skills/ael/references/loop-goal.md +1 -0
- package/CHANGELOG.md +11 -0
- package/bin/ai-engineering-loop.js +109 -4
- package/core/controlled-workflow-runtime.md +1 -0
- package/core/goal-contract.md +38 -0
- package/core/recap.md +29 -0
- package/lib/cli-args.js +1 -0
- package/lib/flow-diagram.js +339 -0
- package/lib/flow.js +104 -19
- package/lib/gates.js +22 -1
- package/lib/generate-workflow.js +17 -0
- package/lib/recap-html.js +216 -0
- package/lib/recap.js +168 -0
- package/lib/run-state.js +2 -1
- package/package.json +1 -1
- package/schemas/goal-contract.schema.json +42 -2
|
@@ -0,0 +1,216 @@
|
|
|
1
|
+
'use strict';
|
|
2
|
+
|
|
3
|
+
const { escapeHtml: esc } = require('./flow-diagram.js');
|
|
4
|
+
const { STAGES, cycle } = require('./recap.js');
|
|
5
|
+
|
|
6
|
+
const AUDIENCES = ['me', 'lead', 'client'];
|
|
7
|
+
const DAY = 86400000;
|
|
8
|
+
|
|
9
|
+
const fmtDate = (d) => d.toLocaleDateString('en-GB', { day: 'numeric', month: 'short', timeZone: 'UTC' });
|
|
10
|
+
function fmtDur(ms) {
|
|
11
|
+
if (!ms) return '0m';
|
|
12
|
+
const m = Math.round(ms / 60000);
|
|
13
|
+
if (m < 60) return `${m}m`;
|
|
14
|
+
const h = Math.floor(m / 60);
|
|
15
|
+
return h < 24 ? `${h}h ${m % 60}m` : `${Math.floor(h / 24)}d ${h % 24}h`;
|
|
16
|
+
}
|
|
17
|
+
const fileUrl = (p) => `file://${encodeURI(p.replace(/\\/g, '/').replace(/^([A-Za-z]):/, '/$1:'))}`;
|
|
18
|
+
|
|
19
|
+
const STYLE = `
|
|
20
|
+
:root{--bg:#f5f7fa;--grid:#e9edf3;--paper:#fff;--ink:#141821;--muted:#4f5867;--line:#d5dbe5;--accent:#4338ca;--accentbg:#eef0ff;--ok:#05603a;--okbg:#dcfae6;--warn:#92400e;--warnbg:#fff3dc;--bad:#b42318;--badbg:#fee4e2;--info:#1849a9;--infobg:#d1e9ff;--goal:#98a2b3;--maker:#7a5af8;--verify:#12b76a;--review:#f79009;--deliver:#2e90fa;--heat:#4338ca;--mono:ui-monospace,SFMono-Regular,Menlo,Consolas,monospace;--sans:system-ui,-apple-system,"Segoe UI",Roboto,sans-serif}
|
|
21
|
+
@media (prefers-color-scheme:dark){:root{--bg:#0d1016;--grid:#171c26;--paper:#161b24;--ink:#eef1f6;--muted:#a8b1c0;--line:#2e3646;--accent:#a5b4fc;--accentbg:#252a4d;--ok:#75e0a7;--okbg:#0b3324;--warn:#fcd27b;--warnbg:#3b2908;--bad:#fda29b;--badbg:#47150f;--info:#84caff;--infobg:#102a56}}
|
|
22
|
+
*{box-sizing:border-box}
|
|
23
|
+
html{-webkit-font-smoothing:antialiased;-moz-osx-font-smoothing:grayscale}
|
|
24
|
+
body{margin:0;background-color:var(--bg);background-image:linear-gradient(var(--grid) 1px,transparent 1px),linear-gradient(90deg,var(--grid) 1px,transparent 1px);background-size:24px 24px;color:var(--ink);font:400 1rem/1.55 var(--sans)}
|
|
25
|
+
.wrap{max-width:74rem;margin:0 auto;padding:2.5rem 1rem 5rem}
|
|
26
|
+
header.top{display:flex;justify-content:space-between;align-items:flex-end;gap:1.5rem;flex-wrap:wrap;margin-bottom:1.5rem}
|
|
27
|
+
.kicker{margin:0;color:var(--muted);font-family:var(--mono);font-size:.8125rem}
|
|
28
|
+
h1{font-size:2rem;line-height:1.15;letter-spacing:-0.02em;margin:.25rem 0 0;font-weight:650}
|
|
29
|
+
h2{font-size:1.25rem;line-height:1.3;letter-spacing:-0.01em;margin:0 0 1rem;font-weight:650}
|
|
30
|
+
h3{font-size:1.0625rem;line-height:1.35;margin:0;font-weight:650;overflow-wrap:break-word}
|
|
31
|
+
h4{font-size:.875rem;color:var(--muted);margin:1.25rem 0 .5rem;font-weight:600}
|
|
32
|
+
p{margin:0}
|
|
33
|
+
.muted{color:var(--muted)}
|
|
34
|
+
code{font-family:var(--mono);font-size:.875rem;background:var(--bg);border:1px solid var(--line);padding:.0625rem .375rem;border-radius:6px;overflow-wrap:anywhere}
|
|
35
|
+
.scope{text-align:end;color:var(--muted);font-size:.9375rem}
|
|
36
|
+
.tabs{display:flex;gap:.5rem;flex-wrap:wrap;margin:0 0 1.5rem}
|
|
37
|
+
.tabs button{font:inherit;font-weight:600;padding:.625rem 1.125rem;border-radius:10px;border:1px solid var(--line);background:var(--paper);color:var(--ink);cursor:pointer}
|
|
38
|
+
.tabs button[aria-pressed=true]{background:var(--accentbg);border-color:var(--accent);color:var(--accent)}
|
|
39
|
+
.tabs button:focus-visible,summary:focus-visible,a:focus-visible{outline:2px solid var(--accent);outline-offset:3px}
|
|
40
|
+
.js section.view:not(.on){display:none}
|
|
41
|
+
section.view{margin-bottom:2.5rem}
|
|
42
|
+
.panel{background:var(--paper);border:1px solid var(--line);border-radius:16px;padding:1.5rem;margin-bottom:1.25rem}
|
|
43
|
+
.metrics{display:grid;grid-template-columns:repeat(auto-fit,minmax(13rem,1fr));gap:1rem;margin-bottom:1.25rem}
|
|
44
|
+
.metric{background:var(--paper);border:1px solid var(--line);border-radius:14px;padding:1.125rem 1.25rem}
|
|
45
|
+
.metric p{color:var(--muted);font-size:.875rem}
|
|
46
|
+
.metric b{display:block;font-size:2.125rem;line-height:1.15;margin:.375rem 0 .25rem;font-weight:650;font-variant-numeric:tabular-nums}
|
|
47
|
+
.delta{font-size:.8125rem;font-variant-numeric:tabular-nums}.delta.good{color:var(--ok)}.delta.bad{color:var(--bad)}.delta.same{color:var(--muted)}
|
|
48
|
+
.scroll{overflow-x:auto}
|
|
49
|
+
table.heat{border-collapse:separate;border-spacing:.375rem;width:100%;min-width:34rem}
|
|
50
|
+
table.heat th{font-weight:600;font-size:.8125rem;color:var(--muted);text-align:center;white-space:nowrap}
|
|
51
|
+
table.heat th[scope=row]{text-align:start;font-family:var(--mono);color:var(--ink)}
|
|
52
|
+
.cell{height:2.75rem;border-radius:8px;display:flex;align-items:center;justify-content:center;font-weight:650;font-variant-numeric:tabular-nums;background:color-mix(in srgb,var(--heat) var(--o),var(--bg));color:var(--ink)}
|
|
53
|
+
.bars{display:flex;flex-direction:column;gap:.875rem}
|
|
54
|
+
.barrow{display:grid;grid-template-columns:minmax(0,18rem) minmax(0,1fr) 5rem;gap:1rem;align-items:center}
|
|
55
|
+
.barlabel b{display:block;font-weight:600;overflow-wrap:break-word}
|
|
56
|
+
.barlabel span{font-size:.8125rem;color:var(--muted);font-family:var(--mono)}
|
|
57
|
+
.bar{display:flex;height:1.375rem;border-radius:6px;overflow:hidden;background:var(--bg);border:1px solid var(--line)}
|
|
58
|
+
.seg{height:100%}
|
|
59
|
+
.seg.goal{background:var(--goal)}.seg.maker{background:var(--maker)}.seg.verify{background:var(--verify)}.seg.review{background:var(--review)}.seg.deliver{background:var(--deliver)}
|
|
60
|
+
.bardetail{grid-column:2/4;font-family:var(--mono);font-size:.8125rem;color:var(--muted);margin-top:-.5rem}
|
|
61
|
+
.bartotal{font-family:var(--mono);text-align:end;font-variant-numeric:tabular-nums}
|
|
62
|
+
.legend{display:flex;gap:.5rem 1.25rem;flex-wrap:wrap;margin-top:1rem;padding-top:.875rem;border-top:1px solid var(--line);font-size:.875rem;color:var(--muted)}
|
|
63
|
+
.legend i{display:inline-block;width:.875rem;height:.875rem;border-radius:3px;margin-right:.375rem;vertical-align:-2px}
|
|
64
|
+
.causes{display:flex;flex-direction:column;gap:.5rem}
|
|
65
|
+
.cause{display:grid;grid-template-columns:12rem 1fr 2.5rem;gap:.75rem;align-items:center;font-family:var(--mono);font-size:.875rem}
|
|
66
|
+
.cause span:last-child{text-align:end;font-variant-numeric:tabular-nums}
|
|
67
|
+
.cause .track{height:.625rem;border-radius:999px;background:var(--bg);overflow:hidden}.cause .track i{display:block;height:100%;background:var(--warn)}
|
|
68
|
+
.pill{display:inline-block;font-size:.8125rem;font-weight:600;line-height:1.4;padding:.1875rem .625rem;border-radius:999px;margin:.125rem .375rem .125rem 0;font-family:var(--mono);white-space:nowrap}
|
|
69
|
+
.pill.ok{background:var(--okbg);color:var(--ok)}.pill.warn{background:var(--warnbg);color:var(--warn)}.pill.bad{background:var(--badbg);color:var(--bad)}.pill.info{background:var(--infobg);color:var(--info)}.pill.muted{background:var(--bg);color:var(--muted);border:1px solid var(--line)}
|
|
70
|
+
.feature{background:var(--paper);border:1px solid var(--line);border-radius:14px;padding:1.25rem 1.5rem;margin-bottom:1rem}
|
|
71
|
+
.feature header{display:flex;justify-content:space-between;gap:1rem;flex-wrap:wrap}
|
|
72
|
+
.feature header p{font-size:.9375rem;margin-top:.25rem;color:var(--muted)}
|
|
73
|
+
.tags{display:flex;flex-wrap:wrap;align-content:flex-start;max-width:28rem}
|
|
74
|
+
details{margin-top:1rem;border-top:1px solid var(--line);padding-top:.75rem}
|
|
75
|
+
summary{cursor:pointer;font-weight:600;color:var(--accent)}
|
|
76
|
+
.list{list-style:none;margin:0;padding:0}.list li{padding:.5rem 0;border-bottom:1px dashed var(--line);max-width:80ch}
|
|
77
|
+
.ev{margin:.375rem 0 0;padding-left:.75rem;border-left:3px solid var(--line);color:var(--muted);font-size:.9375rem}
|
|
78
|
+
.files a{color:var(--accent);font-family:var(--mono);font-size:.875rem;margin-right:1rem}
|
|
79
|
+
.timeline{list-style:none;padding:0;margin:0;position:relative}
|
|
80
|
+
.timeline::before{content:"";position:absolute;left:6.5rem;top:.5rem;bottom:.5rem;width:2px;background:var(--line)}
|
|
81
|
+
.timeline li{display:grid;grid-template-columns:5.75rem 1fr;gap:2.5rem;margin-bottom:2rem;position:relative}
|
|
82
|
+
.timeline li::before{content:"";position:absolute;left:6.125rem;top:.4rem;width:.875rem;height:.875rem;border-radius:50%;background:var(--accent);box-shadow:0 0 0 4px var(--paper)}
|
|
83
|
+
.timeline time{text-align:end;color:var(--muted);font-weight:600;font-variant-numeric:tabular-nums}
|
|
84
|
+
.timeline h3{font-size:1.25rem;margin:.375rem 0}
|
|
85
|
+
.timeline p{font-size:1.0625rem;max-width:62ch;text-wrap:pretty}
|
|
86
|
+
.timeline .proof{color:var(--ok);font-size:.9375rem;margin-top:.5rem}
|
|
87
|
+
.timeline .note{color:var(--warn);font-size:.875rem;margin-top:.375rem}
|
|
88
|
+
.now{display:grid;grid-template-columns:repeat(auto-fit,minmax(16rem,1fr));gap:1rem}
|
|
89
|
+
.now div{background:var(--bg);border:1px solid var(--line);border-radius:12px;padding:1rem}
|
|
90
|
+
.hint{display:none;font-size:.8125rem;color:var(--muted);margin:0 0 .5rem}
|
|
91
|
+
@media (max-width:48rem){.hint{display:block}}
|
|
92
|
+
.empty{color:var(--muted);font-size:1.0625rem;padding:2rem 0;text-align:center}
|
|
93
|
+
.sr{position:absolute;width:1px;height:1px;padding:0;margin:-1px;overflow:hidden;clip:rect(0,0,0,0);white-space:nowrap;border:0}
|
|
94
|
+
footer{color:var(--muted);font-size:.8125rem;margin-top:2rem}
|
|
95
|
+
@media (max-width:48rem){h1{font-size:1.5rem}.scope{text-align:start}.barrow{grid-template-columns:1fr 4rem}.barlabel{grid-column:1/3}.bardetail{grid-column:1/3;margin-top:0}.timeline::before,.timeline li::before{display:none}.timeline li{grid-template-columns:1fr;gap:.25rem}.timeline time{text-align:start}.cause{grid-template-columns:8rem 1fr 2rem}}
|
|
96
|
+
`;
|
|
97
|
+
|
|
98
|
+
function metric(label, value, before, { kind = 'count', lowerIsBetter = false } = {}) {
|
|
99
|
+
const shown = value == null ? '–' : kind === 'dur' ? fmtDur(value) : kind === 'pct' ? `${value}%` : String(value);
|
|
100
|
+
let delta = '<span class="delta same">No earlier data to compare</span>';
|
|
101
|
+
if (before != null && value != null) {
|
|
102
|
+
const diff = value - before;
|
|
103
|
+
if (diff === 0) delta = '<span class="delta same">Same as the previous period</span>';
|
|
104
|
+
else {
|
|
105
|
+
const good = lowerIsBetter ? diff < 0 : diff > 0;
|
|
106
|
+
const amount = kind === 'dur' ? fmtDur(Math.abs(diff)) : kind === 'pct' ? `${Math.abs(diff)} pts` : Math.abs(diff);
|
|
107
|
+
delta = `<span class="delta ${good ? 'good' : 'bad'}">${diff > 0 ? '▲ up' : '▼ down'} ${esc(amount)} vs previous period</span>`;
|
|
108
|
+
}
|
|
109
|
+
}
|
|
110
|
+
return `<div class="metric"><p>${esc(label)}</p><b>${esc(shown)}</b>${delta}</div>`;
|
|
111
|
+
}
|
|
112
|
+
|
|
113
|
+
function heatmap(data) {
|
|
114
|
+
const days = [];
|
|
115
|
+
for (let t = data.window.from.getTime(); t < data.window.to.getTime(); t += DAY) days.push(new Date(t));
|
|
116
|
+
const counts = {};
|
|
117
|
+
for (const run of data.runs) {
|
|
118
|
+
const key = `${run.project}|${run.date.toISOString().slice(0, 10)}`;
|
|
119
|
+
counts[key] = (counts[key] || 0) + 1;
|
|
120
|
+
}
|
|
121
|
+
const max = Math.max(1, ...Object.values(counts));
|
|
122
|
+
const rows = data.projects.map((name) => `<tr><th scope="row">${esc(name)}</th>${days.map((d) => {
|
|
123
|
+
const n = counts[`${name}|${d.toISOString().slice(0, 10)}`] || 0;
|
|
124
|
+
const pct = n ? Math.round(15 + 40 * (n / max)) : 0;
|
|
125
|
+
return `<td><div class="cell" style="--o:${pct}%" title="${esc(`${name}, ${fmtDate(d)}: ${n} run${n === 1 ? '' : 's'}`)}">${n || ''}</div></td>`;
|
|
126
|
+
}).join('')}</tr>`).join('');
|
|
127
|
+
return `<p class="hint">Scroll sideways to see every day →</p><div class="scroll" tabindex="0" role="region" aria-label="Activity per day"><table class="heat"><thead><tr><th></th>${days.map((d) => `<th scope="col">${esc(fmtDate(d))}</th>`).join('')}</tr></thead><tbody>${rows}</tbody></table></div>`;
|
|
128
|
+
}
|
|
129
|
+
|
|
130
|
+
function stageBars(runs) {
|
|
131
|
+
const max = Math.max(1, ...runs.map(cycle));
|
|
132
|
+
const rows = runs.map((run) => {
|
|
133
|
+
const segs = STAGES.map(([name]) => (run.stages[name] ? `<span class="seg ${name}" style="width:${(run.stages[name] / max) * 100}%" title="${esc(`${name}: ${fmtDur(run.stages[name])}`)}"></span>` : '')).join('');
|
|
134
|
+
const detail = STAGES.filter(([name]) => run.stages[name]).map(([name]) => `${name} ${fmtDur(run.stages[name])}`).join(' · ');
|
|
135
|
+
return `<div class="barrow"><div class="barlabel"><b>${esc(run.title)}</b><span>${esc(run.project)} · ${esc(run.state)}</span></div><div class="bar" aria-hidden="true">${segs}</div><div class="bartotal">${esc(fmtDur(cycle(run)))}</div><div class="bardetail">${esc(detail || 'no stage timestamps')}</div></div>`;
|
|
136
|
+
}).join('');
|
|
137
|
+
const legend = STAGES.map(([name]) => `<span><i class="seg ${name}"></i>${name}</span>`).join('');
|
|
138
|
+
return `<div class="bars">${rows}</div><div class="legend">${legend}</div>`;
|
|
139
|
+
}
|
|
140
|
+
|
|
141
|
+
function causes(metrics) {
|
|
142
|
+
const entries = Object.entries(metrics.causes).sort((a, b) => b[1] - a[1]);
|
|
143
|
+
if (!entries.length) return '<p class="muted">No ITERATE verdicts in this period.</p>';
|
|
144
|
+
const max = entries[0][1];
|
|
145
|
+
return `<div class="causes">${entries.map(([cause, n]) => `<div class="cause"><span>${esc(cause)}</span><span class="track"><i style="width:${(n / max) * 100}%"></i></span><span>${n}</span></div>`).join('')}</div>`;
|
|
146
|
+
}
|
|
147
|
+
|
|
148
|
+
function evidence(run) {
|
|
149
|
+
const acs = run.acs.map((ac) => {
|
|
150
|
+
const passed = /^(pass|met|ok|verified)$/i.test(String(ac.status || ''));
|
|
151
|
+
return `<li><span class="pill ${passed ? 'ok' : ac.status ? 'warn' : 'muted'}">${esc(ac.status || 'no status')}</span><b>${esc(ac.id)}</b> ${esc(ac.statement)}${ac.evidence ? `<p class="ev">${esc(ac.evidence.slice(0, 400))}</p>` : ''}</li>`;
|
|
152
|
+
}).join('');
|
|
153
|
+
const commands = run.commands.map((c) => `<li><span class="pill ${c.exitCode === 0 ? 'ok' : 'bad'}">exit ${esc(c.exitCode)}</span><code>${esc(c.command)}</code> <span class="muted">${esc(fmtDur(c.durationMs))}</span></li>`).join('');
|
|
154
|
+
const links = Object.entries(run.files).map(([name, file]) => `<a href="${esc(fileUrl(file))}">${esc(name)}</a>`).join('');
|
|
155
|
+
return `<details><summary>Evidence<span class="sr"> for ${esc(run.title)}</span></summary>
|
|
156
|
+
<h4>Acceptance criteria</h4><ul class="list">${acs || '<li class="muted">None recorded</li>'}</ul>
|
|
157
|
+
<h4>Verification commands</h4><ul class="list">${commands || '<li class="muted">None recorded</li>'}</ul>
|
|
158
|
+
${run.verdictReason ? `<h4>Judge reason</h4><p>${esc(run.verdictReason)}</p>` : ''}
|
|
159
|
+
${run.outOfMap.length ? `<h4>Changed outside the impact map (${run.outOfMap.length})</h4><p class="muted">${run.outOfMap.map(esc).join(', ')}</p>` : ''}
|
|
160
|
+
${links ? `<h4>Artifacts</h4><p class="files">${links}</p>` : ''}
|
|
161
|
+
</details>`;
|
|
162
|
+
}
|
|
163
|
+
|
|
164
|
+
function featureCard(run) {
|
|
165
|
+
const n = run.iterations.length;
|
|
166
|
+
const green = run.commands.filter((c) => c.exitCode === 0).length;
|
|
167
|
+
const tags = [
|
|
168
|
+
run.verdict ? `<span class="pill ${run.verdict === 'PASS' ? 'ok' : 'warn'}">${esc(run.verdict)}</span>` : `<span class="pill muted">${esc(run.state)}</span>`,
|
|
169
|
+
run.tier ? `<span class="pill info">${esc(run.tier)}</span>` : '',
|
|
170
|
+
n ? `<span class="pill ${n > 1 ? 'warn' : 'ok'}">${n} iteration${n > 1 ? 's' : ''}</span>` : '',
|
|
171
|
+
run.commands.length ? `<span class="pill ${green === run.commands.length ? 'ok' : 'bad'}">${green}/${run.commands.length} checks green</span>` : '',
|
|
172
|
+
run.outOfMap.length ? `<span class="pill warn">${run.outOfMap.length} outside impact map</span>` : '',
|
|
173
|
+
run.openFindings ? `<span class="pill warn">${run.openFindings} open findings</span>` : ''
|
|
174
|
+
].join('');
|
|
175
|
+
const meta = [esc(run.project), esc(fmtDate(run.date)), run.branch ? `<code>${esc(run.branch)}</code>` : '', run.approvedBy ? `approved by ${esc(run.approvedBy)}` : ''].filter(Boolean);
|
|
176
|
+
return `<article class="feature"><header><div><h3 style="max-width:60ch">${esc(run.title)}</h3><p>${meta.join(' · ')}</p></div><div class="tags">${tags}</div></header>${evidence(run)}</article>`;
|
|
177
|
+
}
|
|
178
|
+
|
|
179
|
+
function clientView(data) {
|
|
180
|
+
const delivered = data.runs.filter((run) => run.delivered).reverse();
|
|
181
|
+
const items = delivered.map((run) => {
|
|
182
|
+
const green = run.commands.filter((c) => c.exitCode === 0).length;
|
|
183
|
+
const first = run.clientText.split(/(?<=[.!?])\s/)[0];
|
|
184
|
+
const heading = run.title.length <= 80 ? run.title : first;
|
|
185
|
+
const body = heading === first ? run.clientText.slice(first.length).trim() : run.clientText;
|
|
186
|
+
return `<li><time>${esc(fmtDate(run.endedAt))}</time><div><span class="pill info">New</span><h3>${esc(heading)}</h3>${body ? `<p>${esc(body)}</p>` : ''}<p class="proof">Verified: ${run.acs.length} criteria checked, ${green} automated check${green === 1 ? '' : 's'} passed</p></div></li>`;
|
|
187
|
+
}).join('');
|
|
188
|
+
const now = data.runs.filter((run) => !run.delivered && !/ABANDON/.test(run.state));
|
|
189
|
+
return `<div class="panel"><h2>What's new</h2>${items ? `<ol class="timeline">${items}</ol>` : '<p class="empty">Nothing was delivered in this period.</p>'}</div><div class="panel"><h2>In progress now</h2>${now.length ? `<div class="now">${now.map((run) => `<div><h3>${esc(run.title)}</h3><p class="muted">${esc(run.clientText)}</p></div>`).join('')}</div>` : '<p class="muted">Nothing in progress.</p>'}</div>`;
|
|
190
|
+
}
|
|
191
|
+
|
|
192
|
+
function renderRecap(data, { audience = 'me', now = new Date(), lang = null } = {}) {
|
|
193
|
+
if (!AUDIENCES.includes(audience)) throw new Error('--for must be me, lead or client');
|
|
194
|
+
const { metrics, previous: prev, runs } = data;
|
|
195
|
+
const contentLang = lang ? ` lang="${esc(lang)}"` : '';
|
|
196
|
+
const technical = runs.filter((run) => run.delivered && run.clientTextSource === 'objective');
|
|
197
|
+
const empty = `<p class="empty">No runs in the last ${esc(data.window.days)} days. Try a longer window: <code>ael recap --days ${esc(data.window.days * 4)}</code></p>`;
|
|
198
|
+
const me = runs.length ? `<div class="metrics">${metric('Runs', metrics.runs, prev?.runs)}${metric('Passed on the first try', metrics.firstPassRate, prev?.firstPassRate, { kind: 'pct' })}${metric('Median cycle time', metrics.medianCycleMs, prev?.medianCycleMs, { kind: 'dur', lowerIsBetter: true })}${metric('Delivered', metrics.delivered, prev?.delivered)}</div>
|
|
199
|
+
<div class="panel"><h2>Activity per day</h2>${heatmap(data)}</div>
|
|
200
|
+
<div class="panel"><h2>Where the time went</h2>${stageBars(runs)}</div>
|
|
201
|
+
<div class="panel"><h2>Why runs had to iterate</h2>${causes(metrics)}</div>` : `<div class="panel">${empty}</div>`;
|
|
202
|
+
const lead = runs.length ? `<div class="metrics">${metric('Delivered', metrics.delivered, prev?.delivered)}${metric('Passed on the first try', metrics.firstPassRate, prev?.firstPassRate, { kind: 'pct' })}${metric('Median cycle time', metrics.medianCycleMs, prev?.medianCycleMs, { kind: 'dur', lowerIsBetter: true })}${metric('High-risk (T2) runs', metrics.t2, prev?.t2, { lowerIsBetter: true })}</div>${technical.length ? `<div class="panel"><h2>Before you share the client tab</h2><p>${technical.length} delivered run${technical.length === 1 ? ' has' : 's have'} no <code>plainSummary</code>, so the client tab shows the technical objective: ${technical.map((run) => `<b>${esc(run.title)}</b>`).join(', ')}. Add a one-sentence <code>plainSummary</code> to the Goal and rerun the recap.</p></div>` : ''}<h2>Work and its evidence</h2><div${contentLang}>${runs.slice().reverse().map(featureCard).join('')}</div>` : `<div class="panel">${empty}</div>`;
|
|
203
|
+
const tab = (view, text) => `<button type="button" aria-controls="${view}" data-view="${view}" aria-pressed="${view === audience}">${text}</button>`;
|
|
204
|
+
const section = (view, html) => `<section class="view${view === audience ? ' on' : ''}" id="${view}" aria-label="${esc({ me: 'For me', lead: 'For the lead', client: 'For the client' }[view])}">${html}</section>`;
|
|
205
|
+
const range = `${fmtDate(data.window.from)} – ${fmtDate(new Date(data.window.to.getTime() - 1))}`;
|
|
206
|
+
return `<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>${esc(`AEL recap · ${range}`)}</title><style>${STYLE}</style></head><body><main class="wrap">
|
|
207
|
+
<header class="top"><div><p class="kicker">AEL recap · last ${esc(data.window.days)} day${data.window.days === 1 ? '' : 's'}</p><h1>${esc(range)}</h1></div><p class="scope">${esc(data.projects.join(' · '))}<br>${metrics.runs} run${metrics.runs === 1 ? '' : 's'} · ${metrics.delivered} delivered</p></header>
|
|
208
|
+
<nav class="tabs" aria-label="Audience">${tab('me', 'For me')}${tab('lead', 'For the lead')}${tab('client', 'For the client')}</nav>
|
|
209
|
+
${section('me', `<div${contentLang}>${me}</div>`)}
|
|
210
|
+
${section('lead', lead)}
|
|
211
|
+
${section('client', `<div${contentLang}>${clientView(data)}</div>`)}
|
|
212
|
+
<footer>Built from local AEL run artifacts on ${esc(now.toISOString().slice(0, 16).replace('T', ' '))} UTC. Every number comes from a Run file; nothing is written by a model.</footer>
|
|
213
|
+
</main><script>document.documentElement.classList.add('js');document.querySelectorAll('.tabs button').forEach(function(b){b.addEventListener('click',function(){document.querySelectorAll('.tabs button').forEach(function(x){x.setAttribute('aria-pressed',String(x===b));});document.querySelectorAll('section.view').forEach(function(s){s.classList.toggle('on',s.id===b.dataset.view);});});});</script></body></html>`;
|
|
214
|
+
}
|
|
215
|
+
|
|
216
|
+
module.exports = { AUDIENCES, renderRecap };
|
package/lib/recap.js
ADDED
|
@@ -0,0 +1,168 @@
|
|
|
1
|
+
'use strict';
|
|
2
|
+
|
|
3
|
+
const fs = require('fs');
|
|
4
|
+
const path = require('path');
|
|
5
|
+
|
|
6
|
+
const DAY = 86400000;
|
|
7
|
+
const RUN_ID = /^(\d{4})(\d{2})(\d{2})T(\d{2})(\d{2})(\d{2})Z-/;
|
|
8
|
+
const STAGES = [
|
|
9
|
+
['goal', 'STARTED', 'GOAL_FROZEN'],
|
|
10
|
+
['maker', 'GOAL_FROZEN', 'MAKER_COMPLETE'],
|
|
11
|
+
['verify', 'MAKER_COMPLETE', 'VERIFIED'],
|
|
12
|
+
['review', 'VERIFIED', /^JUDGED_/],
|
|
13
|
+
['deliver', 'JUDGED_PASS', 'DELIVERED']
|
|
14
|
+
];
|
|
15
|
+
|
|
16
|
+
const readJson = (file) => {
|
|
17
|
+
try {
|
|
18
|
+
return JSON.parse(fs.readFileSync(file, 'utf8'));
|
|
19
|
+
} catch {
|
|
20
|
+
return null;
|
|
21
|
+
}
|
|
22
|
+
};
|
|
23
|
+
|
|
24
|
+
const readLines = (file) => {
|
|
25
|
+
try {
|
|
26
|
+
return fs.readFileSync(file, 'utf8').split('\n').filter(Boolean).flatMap((line) => {
|
|
27
|
+
try {
|
|
28
|
+
return [JSON.parse(line)];
|
|
29
|
+
} catch {
|
|
30
|
+
return [];
|
|
31
|
+
}
|
|
32
|
+
});
|
|
33
|
+
} catch {
|
|
34
|
+
return [];
|
|
35
|
+
}
|
|
36
|
+
};
|
|
37
|
+
|
|
38
|
+
function runDate(runId) {
|
|
39
|
+
const m = RUN_ID.exec(runId);
|
|
40
|
+
return m ? new Date(Date.UTC(+m[1], +m[2] - 1, +m[3], +m[4], +m[5], +m[6])) : null;
|
|
41
|
+
}
|
|
42
|
+
|
|
43
|
+
function stageDurations(history) {
|
|
44
|
+
const lastAt = (match) => {
|
|
45
|
+
const hits = history.filter((entry) => (match instanceof RegExp ? match.test(entry.to) : entry.to === match));
|
|
46
|
+
return hits.length ? Date.parse(hits[hits.length - 1].at) : null;
|
|
47
|
+
};
|
|
48
|
+
const result = {};
|
|
49
|
+
for (const [name, from, to] of STAGES) {
|
|
50
|
+
const a = lastAt(from);
|
|
51
|
+
const b = lastAt(to);
|
|
52
|
+
result[name] = a && b && b >= a ? b - a : 0;
|
|
53
|
+
}
|
|
54
|
+
return result;
|
|
55
|
+
}
|
|
56
|
+
|
|
57
|
+
function cleanTitle(state = {}, goal = {}) {
|
|
58
|
+
const pick = String(goal.title || '').trim()
|
|
59
|
+
|| String(goal.objective || '').split(/(?<=[.!?])\s/)[0].replace(/[.!?]$/, '').trim()
|
|
60
|
+
|| String(state.displayName || state.task || '').replace(/^(--?[\w-]+(\s+|$))+/, '').trim();
|
|
61
|
+
return pick || 'Untitled run';
|
|
62
|
+
}
|
|
63
|
+
|
|
64
|
+
function clientText(goal) {
|
|
65
|
+
if (String(goal.plainSummary || '').trim()) return [goal.plainSummary.trim(), 'plainSummary'];
|
|
66
|
+
if (String(goal.businessOutcome || '').trim()) return [goal.businessOutcome.trim(), 'businessOutcome'];
|
|
67
|
+
return [String(goal.objective || '').trim(), 'objective'];
|
|
68
|
+
}
|
|
69
|
+
|
|
70
|
+
function loadRun(projectPath, runId) {
|
|
71
|
+
const dir = path.join(projectPath, '.ai-engineering-loop', 'runs', runId);
|
|
72
|
+
const state = readJson(path.join(dir, 'state.json')) || {};
|
|
73
|
+
const goal = readJson(path.join(dir, 'goal-contract.json')) || {};
|
|
74
|
+
const verdict = readJson(path.join(dir, 'verdict.json')) || {};
|
|
75
|
+
const delivery = readJson(path.join(dir, 'delivery.json')) || {};
|
|
76
|
+
const verification = readJson(path.join(dir, 'verification.json')) || {};
|
|
77
|
+
const receipt = readJson(path.join(dir, 'receipt.json')) || {};
|
|
78
|
+
const summary = readJson(path.join(dir, 'run-summary.json')) || {};
|
|
79
|
+
const history = Array.isArray(state.history) ? state.history : [];
|
|
80
|
+
const [text, source] = clientText(goal);
|
|
81
|
+
const acs = Array.isArray(receipt.acceptanceCriteria) && receipt.acceptanceCriteria.length
|
|
82
|
+
? receipt.acceptanceCriteria
|
|
83
|
+
: (goal.acceptanceCriteria || []);
|
|
84
|
+
const files = {};
|
|
85
|
+
for (const name of ['goal-contract.json', 'verification.json', 'verdict.json', 'receipt.md', 'lifecycle.jsonl']) {
|
|
86
|
+
const file = path.join(dir, name);
|
|
87
|
+
if (fs.existsSync(file)) files[name] = file;
|
|
88
|
+
}
|
|
89
|
+
return {
|
|
90
|
+
project: path.basename(projectPath),
|
|
91
|
+
projectPath,
|
|
92
|
+
runId,
|
|
93
|
+
date: runDate(runId),
|
|
94
|
+
endedAt: history.length ? new Date(history[history.length - 1].at) : runDate(runId),
|
|
95
|
+
state: state.state || 'UNKNOWN',
|
|
96
|
+
delivered: state.state === 'DELIVERED',
|
|
97
|
+
tier: state.tier?.current || verdict.tier || null,
|
|
98
|
+
title: cleanTitle(state, goal),
|
|
99
|
+
objective: String(goal.objective || ''),
|
|
100
|
+
clientText: text,
|
|
101
|
+
clientTextSource: source,
|
|
102
|
+
verdict: verdict.verdict || null,
|
|
103
|
+
verdictReason: String(verdict.reason || ''),
|
|
104
|
+
iterations: readLines(path.join(dir, 'iterations.jsonl')).map((entry) => ({ verdict: entry.verdict, cause: entry.cause || null })),
|
|
105
|
+
branch: delivery.destination || null,
|
|
106
|
+
approvedBy: delivery.approvedBy || null,
|
|
107
|
+
commands: (verification.commands || []).map((c) => ({ command: String(c.command || ''), exitCode: c.exitCode, durationMs: c.durationMs || 0 })),
|
|
108
|
+
testCounts: summary.verification?.testCounts || null,
|
|
109
|
+
acs: acs.map((ac) => ({ id: ac.id, statement: ac.statement || '', status: ac.status || null, evidence: typeof ac.evidence === 'string' ? ac.evidence : ac.evidence ? JSON.stringify(ac.evidence) : null })),
|
|
110
|
+
outOfMap: Array.isArray(receipt.impact?.outOfMap) ? receipt.impact.outOfMap : [],
|
|
111
|
+
openFindings: Array.isArray(summary.openFindings) ? summary.openFindings.length : 0,
|
|
112
|
+
stages: stageDurations(history),
|
|
113
|
+
files
|
|
114
|
+
};
|
|
115
|
+
}
|
|
116
|
+
|
|
117
|
+
function runsBetween(projectPath, from, to) {
|
|
118
|
+
let ids = [];
|
|
119
|
+
try {
|
|
120
|
+
ids = fs.readdirSync(path.join(projectPath, '.ai-engineering-loop', 'runs')).filter((id) => RUN_ID.test(id));
|
|
121
|
+
} catch {
|
|
122
|
+
return [];
|
|
123
|
+
}
|
|
124
|
+
return ids.filter((id) => {
|
|
125
|
+
const d = runDate(id);
|
|
126
|
+
return d >= from && d < to;
|
|
127
|
+
}).map((id) => loadRun(projectPath, id));
|
|
128
|
+
}
|
|
129
|
+
|
|
130
|
+
const cycle = (run) => Object.values(run.stages).reduce((a, b) => a + b, 0);
|
|
131
|
+
|
|
132
|
+
function median(values) {
|
|
133
|
+
if (!values.length) return null;
|
|
134
|
+
const sorted = [...values].sort((a, b) => a - b);
|
|
135
|
+
const mid = Math.floor(sorted.length / 2);
|
|
136
|
+
return sorted.length % 2 ? sorted[mid] : (sorted[mid - 1] + sorted[mid]) / 2;
|
|
137
|
+
}
|
|
138
|
+
|
|
139
|
+
function metricsOf(runs) {
|
|
140
|
+
const judged = runs.filter((run) => run.iterations.length);
|
|
141
|
+
const causes = {};
|
|
142
|
+
for (const run of runs) for (const entry of run.iterations) if (entry.verdict !== 'PASS' && entry.cause) causes[entry.cause] = (causes[entry.cause] || 0) + 1;
|
|
143
|
+
return {
|
|
144
|
+
runs: runs.length,
|
|
145
|
+
delivered: runs.filter((run) => run.delivered).length,
|
|
146
|
+
firstPassRate: judged.length ? Math.round((judged.filter((run) => run.iterations[0].verdict === 'PASS').length / judged.length) * 100) : null,
|
|
147
|
+
medianCycleMs: median(runs.filter((run) => run.delivered).map(cycle).filter(Boolean)),
|
|
148
|
+
t2: runs.filter((run) => run.tier === 'T2').length,
|
|
149
|
+
causes
|
|
150
|
+
};
|
|
151
|
+
}
|
|
152
|
+
|
|
153
|
+
function collectRecap({ projects, days = 7, now = new Date() }) {
|
|
154
|
+
const to = now;
|
|
155
|
+
const from = new Date(now.getTime() - days * DAY);
|
|
156
|
+
const prevFrom = new Date(from.getTime() - days * DAY);
|
|
157
|
+
const runs = projects.flatMap((p) => runsBetween(p, from, to)).sort((a, b) => a.date - b.date);
|
|
158
|
+
const previousRuns = projects.flatMap((p) => runsBetween(p, prevFrom, from));
|
|
159
|
+
return {
|
|
160
|
+
window: { from, to, days },
|
|
161
|
+
projects: projects.map((p) => path.basename(p)),
|
|
162
|
+
runs,
|
|
163
|
+
metrics: metricsOf(runs),
|
|
164
|
+
previous: previousRuns.length ? metricsOf(previousRuns) : null
|
|
165
|
+
};
|
|
166
|
+
}
|
|
167
|
+
|
|
168
|
+
module.exports = { STAGES, cleanTitle, collectRecap, cycle, runDate };
|
package/lib/run-state.js
CHANGED
|
@@ -396,6 +396,7 @@ function transitionRunLocked(
|
|
|
396
396
|
incrementIteration = false,
|
|
397
397
|
statePatch = {},
|
|
398
398
|
historyMetadata = {},
|
|
399
|
+
dropArtifacts = [],
|
|
399
400
|
now = new Date()
|
|
400
401
|
} = {}
|
|
401
402
|
) {
|
|
@@ -419,7 +420,7 @@ function transitionRunLocked(
|
|
|
419
420
|
state: to,
|
|
420
421
|
iteration: incrementIteration ? run.iteration + 1 : run.iteration,
|
|
421
422
|
updatedAt: timestamp,
|
|
422
|
-
artifacts: { ...run.artifacts, ...artifacts },
|
|
423
|
+
artifacts: Object.fromEntries(Object.entries({ ...run.artifacts, ...artifacts }).filter(([key]) => !dropArtifacts.includes(key))),
|
|
423
424
|
history: [
|
|
424
425
|
...run.history,
|
|
425
426
|
{
|
package/package.json
CHANGED
|
@@ -136,19 +136,59 @@
|
|
|
136
136
|
"additionalProperties": false
|
|
137
137
|
},
|
|
138
138
|
"flow": {
|
|
139
|
-
"description": "Optional (C-21): the intended
|
|
139
|
+
"description": "Optional (C-21, C-27): the intended flow as transitions. goal draft renders it as a From | Event | To table; goal diagram renders it as a state machine, storyboard or actor lanes before freeze; the receipt shows it next to the verification artifacts.",
|
|
140
140
|
"type": "array",
|
|
141
141
|
"minItems": 1,
|
|
142
|
+
"maxItems": 40,
|
|
142
143
|
"items": {
|
|
143
144
|
"type": "object",
|
|
144
145
|
"required": ["from", "event", "to"],
|
|
145
146
|
"properties": {
|
|
146
147
|
"from": { "type": "string", "minLength": 1 },
|
|
147
148
|
"event": { "type": "string", "minLength": 1 },
|
|
148
|
-
"to": { "type": "string", "minLength": 1 }
|
|
149
|
+
"to": { "type": "string", "minLength": 1 },
|
|
150
|
+
"actor": { "type": "string", "minLength": 1, "description": "Who performs the step (user, app, service, db, cron). Missing means user." },
|
|
151
|
+
"guard": { "type": "string", "minLength": 1 },
|
|
152
|
+
"effects": {
|
|
153
|
+
"type": "array",
|
|
154
|
+
"maxItems": 12,
|
|
155
|
+
"items": {
|
|
156
|
+
"type": "object",
|
|
157
|
+
"required": ["text"],
|
|
158
|
+
"properties": {
|
|
159
|
+
"text": { "type": "string", "minLength": 1 },
|
|
160
|
+
"ac": { "type": "string", "minLength": 1, "description": "Acceptance criterion that covers this effect. Missing means a side effect no AC covers." }
|
|
161
|
+
}
|
|
162
|
+
}
|
|
163
|
+
},
|
|
164
|
+
"hotspot": { "description": "An open question about this transition, or true.", "oneOf": [{ "type": "string", "minLength": 1 }, { "const": true }] }
|
|
149
165
|
}
|
|
150
166
|
}
|
|
151
167
|
},
|
|
168
|
+
"flowSubject": {
|
|
169
|
+
"description": "Optional (C-27): the entity whose status the flow describes; makes the state view the recommended one.",
|
|
170
|
+
"type": "string",
|
|
171
|
+
"minLength": 1
|
|
172
|
+
},
|
|
173
|
+
"forbiddenTransitions": {
|
|
174
|
+
"description": "Optional (C-27): state/event pairs the human decided are invalid; the transition table shows them as invalid instead of undecided.",
|
|
175
|
+
"type": "array",
|
|
176
|
+
"items": {
|
|
177
|
+
"type": "object",
|
|
178
|
+
"required": ["from", "event"],
|
|
179
|
+
"properties": {
|
|
180
|
+
"from": { "type": "string", "minLength": 1 },
|
|
181
|
+
"event": { "type": "string", "minLength": 1 }
|
|
182
|
+
},
|
|
183
|
+
"additionalProperties": false
|
|
184
|
+
}
|
|
185
|
+
},
|
|
186
|
+
"plainSummary": {
|
|
187
|
+
"description": "Optional (C-28): one sentence for non-technical readers, used by `recap --for client`.",
|
|
188
|
+
"type": "string",
|
|
189
|
+
"minLength": 1,
|
|
190
|
+
"maxLength": 240
|
|
191
|
+
},
|
|
152
192
|
"featureId": {
|
|
153
193
|
"description": "Optional (C-15): id of the feature in .ai-engineering-loop/features.json this Goal delivers. Goal freeze marks it active; delivery marks it passing with this Run as evidence.",
|
|
154
194
|
"type": "string",
|