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
|
@@ -11,6 +11,7 @@
|
|
|
11
11
|
|
|
12
12
|
Run these when the user asks how the loop is doing, before planning work, or when a gate points at them. All read local Run files; none starts a Run.
|
|
13
13
|
- `stats [--last <n>] [--json]`: failure causes by harness layer (`task_spec`, `context`, `environment`, `verification`, `state`, `model`), false-victory rate per tier, iterations to PASS, revert rate of delivered Runs (from git) and the verification share of tokens. Fix the bottleneck layer first.
|
|
14
|
+
- `recap [--days N] [--for me|lead|client] [--projects <p,...>|all]`: one HTML page of what shipped, with evidence (`docs recap`). Client recaps take one project.
|
|
14
15
|
- `outcome record --run <id> --source mr-comment|revert|bug|incident --location <file[:line]> --summary <text> --by <name>`: a problem people found after delivery. Only record what the human reported; never invent one. Then `calibrate` lists DA misses and wrong dismissals per reviewer prompt version.
|
|
15
16
|
- `debt [--file <path>]` lists trade-offs the Judge accepted and L3 waivers; `debt close <id> --by <name>` only on the human's word.
|
|
16
17
|
- `next`: the next unblocked feature in `.ai-engineering-loop/features.json` and VCR (verified/activated). Finish the active feature before starting another.
|
|
@@ -7,6 +7,7 @@
|
|
|
7
7
|
- Boundary-crossing AC (UI-API, service-DB, queue, IPC): `crossComponent: true`; needs L3.
|
|
8
8
|
- Optional per AC: `verify.command` (Judge PASS needs it green), `rubric` for subjective ACs; Goal `featureId` links `features.json`; Goal `flow` (from/event/to) for UI work: show its table with the draft (`docs goal-contract`).
|
|
9
9
|
- Write the contract JSON to a repository-local file, then `npx ai-engineering-loop goal draft --run <runId> --file <file> --revision <currentRevision>` (publishes the draft and the freeze question to Studio). Show the human the draft and its `impactPreview` in one message.
|
|
10
|
+
- If `goal draft` returns `diagramOptions`, offer the recommended view or freeze; render only the pick (`goal diagram --view <v>`), then ask: freeze, another view, or add AC for `?`/side effects.
|
|
10
11
|
- Wait for the explicit human freeze, then `npx ai-engineering-loop goal freeze --latest --run <runId> --by <name>` (or `--revision <r> --hash <h>`). Add `--confirm-impact` when that answer also accepts the blast radius. T0: `quick start`.
|
|
11
12
|
- Otherwise the freeze writes a DRAFT blast-radius map: `impact show --run <runId>`. ASSISTED: the human confirms or edits it (`impact confirm --by <name> [--allow <glob>] [--remove <path>]`); copy/CSS/comment-only goals: `impact skip --by <name> --reason <text>` (`docs blast-radius-map`).
|
|
12
13
|
- Do not edit production code until the Goal gate passes.
|
package/CHANGELOG.md
CHANGED
|
@@ -6,6 +6,17 @@ All notable changes to this project are documented here. Versions follow [Semant
|
|
|
6
6
|
|
|
7
7
|
_No changes yet._
|
|
8
8
|
|
|
9
|
+
## 2.10.1 - 2026-11-17
|
|
10
|
+
|
|
11
|
+
- **Fixed:** after a Judge `ITERATE`, `verify` refused to record evidence for the new Maker diff ("Verification has already passed its gate") and `gate verification` rejected the old evidence's diff hash, so the Run could not continue. The iteration's verification files now move to `runs/<id>/iterations/<n>/` and the next iteration starts with a fresh bundle.
|
|
12
|
+
|
|
13
|
+
## 2.10.0 - 2026-11-17
|
|
14
|
+
|
|
15
|
+
Cards C-27 and C-28 in `docs/cards/slop-to-gold-2026-11-16.md`.
|
|
16
|
+
|
|
17
|
+
- **Added:** look before you freeze (C-27). Goal `flow` steps may carry `actor`, `guard`, `effects` (with or without an AC) and `hotspot`, plus Goal-level `flowSubject`, `forbiddenTransitions` and `plainSummary`. `goal draft` returns `diagramOptions` and counts of undecided transitions, hotspots and side effects, and its impact preview no longer cuts tests to 10. `goal diagram --view state|storyboard|lanes` renders only the chosen view as an offline HTML page; the state view includes a full state × event transition table. Set a project default with `freeze_diagram` in `workflow.md`.
|
|
18
|
+
- **Added:** `ael recap` (C-28): an evidence-backed HTML recap of the last N days for me, the lead or a client, built only from Run artifacts (`docs recap`).
|
|
19
|
+
|
|
9
20
|
## 2.9.0 - 2026-11-16
|
|
10
21
|
|
|
11
22
|
From "All Code Is Slop (Except Mine)" 08:06-08:46 (card C-26 in `docs/cards/slop-to-gold-2026-11-16.md`).
|
|
@@ -1930,7 +1930,7 @@ function closeFreezeQuestions(runId, actor) {
|
|
|
1930
1930
|
function impactPreview(runId, goal) {
|
|
1931
1931
|
try {
|
|
1932
1932
|
const map = impactMap.buildImpactMap(CWD, { run: loadRun(CWD, runId), goal });
|
|
1933
|
-
return { files: (map.files || []).map((file) => file.path), tests: (map.tests || []).map((t) => t.path || t)
|
|
1933
|
+
return { files: (map.files || []).map((file) => file.path), tests: (map.tests || []).map((t) => t.path || t) };
|
|
1934
1934
|
} catch (err) {
|
|
1935
1935
|
return { error: err.message };
|
|
1936
1936
|
}
|
|
@@ -3163,10 +3163,13 @@ function handleGoal() {
|
|
|
3163
3163
|
expectedRevision: requiredIntegerArg('--revision')
|
|
3164
3164
|
});
|
|
3165
3165
|
extra.impactPreview = impactPreview(runId, draftGoal);
|
|
3166
|
-
// C-21: show the intended user flow as a transition table before freeze.
|
|
3167
3166
|
if (draftGoal && draftGoal.flow != null) {
|
|
3168
3167
|
const flowLib = require('../lib/flow.js');
|
|
3169
|
-
extra.flow = { table: flowLib.renderFlow(draftGoal.flow), mermaid: flowLib.renderMermaid(draftGoal.flow), problems: flowLib.flowProblems(draftGoal.flow), warnings: flowLib.flowWarnings(draftGoal.flow) };
|
|
3168
|
+
extra.flow = { table: flowLib.renderFlow(draftGoal.flow), mermaid: flowLib.renderMermaid(draftGoal.flow), problems: flowLib.flowProblems(draftGoal.flow), warnings: flowLib.flowWarnings(draftGoal.flow), ...flowLib.flowCounts(draftGoal) };
|
|
3169
|
+
const preference = require('../lib/generate-workflow.js').readFreezeDiagram(CWD);
|
|
3170
|
+
extra.diagramOptions = flowLib.diagramOptions(draftGoal, { preference });
|
|
3171
|
+
if (preference === 'off') extra.diagramsOff = true;
|
|
3172
|
+
else extra.diagramHint = `Offer the recommended view or freeze; render one with \`goal diagram --run ${runId} --view <state|storyboard|lanes>\`.`;
|
|
3170
3173
|
}
|
|
3171
3174
|
appendRunLifecycle(CWD, runId, {
|
|
3172
3175
|
type: 'GOAL_DRAFT_UPDATED',
|
|
@@ -3239,8 +3242,10 @@ function handleGoal() {
|
|
|
3239
3242
|
const confirmed = impactMap.confirmImpactMap(CWD, { runId, by: argValue('--by') || 'human' });
|
|
3240
3243
|
extra.impact = { status: confirmed.map ? confirmed.map.status : 'CONFIRMED' };
|
|
3241
3244
|
}
|
|
3245
|
+
} else if (action === 'diagram') {
|
|
3246
|
+
Object.assign(extra, renderGoalDiagram(runId));
|
|
3242
3247
|
} else {
|
|
3243
|
-
const error = new Error('goal must be show, draft, or
|
|
3248
|
+
const error = new Error('goal must be show, draft, freeze, or diagram');
|
|
3244
3249
|
error.code = 'INVALID_USAGE';
|
|
3245
3250
|
throw error;
|
|
3246
3251
|
}
|
|
@@ -3251,6 +3256,61 @@ function handleGoal() {
|
|
|
3251
3256
|
}
|
|
3252
3257
|
}
|
|
3253
3258
|
|
|
3259
|
+
function contentLangArg() {
|
|
3260
|
+
const lang = argValue('--lang');
|
|
3261
|
+
if (lang == null) return null;
|
|
3262
|
+
if (!/^[A-Za-z]{2,3}(-[A-Za-z0-9]{2,8})*$/.test(lang)) {
|
|
3263
|
+
throw Object.assign(new Error('--lang must be a language tag such as id, en or pt-BR'), { code: 'INVALID_USAGE' });
|
|
3264
|
+
}
|
|
3265
|
+
return lang;
|
|
3266
|
+
}
|
|
3267
|
+
|
|
3268
|
+
function renderGoalDiagram(runId) {
|
|
3269
|
+
const view = argValue('--view');
|
|
3270
|
+
const { VIEWS } = require('../lib/flow.js');
|
|
3271
|
+
if (!VIEWS.includes(view)) {
|
|
3272
|
+
throw Object.assign(new Error('goal diagram needs --view state|storyboard|lanes'), { code: 'INVALID_USAGE' });
|
|
3273
|
+
}
|
|
3274
|
+
const run = loadRun(CWD, runId);
|
|
3275
|
+
let goal;
|
|
3276
|
+
let revision;
|
|
3277
|
+
let suffix;
|
|
3278
|
+
if (run.goal?.frozen) {
|
|
3279
|
+
goal = JSON.parse(fs.readFileSync(path.join(CWD, '.ai-engineering-loop', 'runs', runId, 'goal-contract.json'), 'utf8'));
|
|
3280
|
+
revision = null;
|
|
3281
|
+
suffix = 'frozen';
|
|
3282
|
+
} else {
|
|
3283
|
+
const draft = loadGoalDraft(CWD, runId);
|
|
3284
|
+
if (!draft) throw Object.assign(new Error('No Goal draft yet: run `goal draft` first'), { code: 'GOAL_DRAFT_MISSING' });
|
|
3285
|
+
revision = draft.metadata.revision;
|
|
3286
|
+
const requested = argValue('--revision');
|
|
3287
|
+
if (requested != null && Number(requested) !== revision) {
|
|
3288
|
+
throw Object.assign(new Error(`Only the latest draft is kept: it is revision ${revision}. Rerun with --revision ${revision} or without --revision.`), { code: 'GOAL_REVISION_MISMATCH' });
|
|
3289
|
+
}
|
|
3290
|
+
goal = draft.contract;
|
|
3291
|
+
suffix = `r${revision}`;
|
|
3292
|
+
}
|
|
3293
|
+
if (!Array.isArray(goal.flow) || !goal.flow.length) {
|
|
3294
|
+
throw Object.assign(new Error('The Goal has no flow to draw. Add flow steps ({from, event, to}) to the draft, then rerun `goal draft`.'), { code: 'GOAL_FLOW_MISSING' });
|
|
3295
|
+
}
|
|
3296
|
+
const html = require('../lib/flow-diagram.js').renderDiagram(goal, { view, revision, lang: contentLangArg() });
|
|
3297
|
+
const dir = path.join(CWD, '.ai-engineering-loop', 'runs', runId, 'diagrams');
|
|
3298
|
+
fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
|
|
3299
|
+
const file = path.join(dir, `${view}-${suffix}.html`);
|
|
3300
|
+
fs.writeFileSync(file, html, { mode: 0o600 });
|
|
3301
|
+
fs.chmodSync(file, 0o600);
|
|
3302
|
+
if (process.argv.includes('--open')) openStudio(file);
|
|
3303
|
+
const counts = require('../lib/flow.js').flowCounts(goal);
|
|
3304
|
+
return {
|
|
3305
|
+
view,
|
|
3306
|
+
path: file,
|
|
3307
|
+
counts,
|
|
3308
|
+
next: counts.undecided || counts.hotspots || counts.sideEffects
|
|
3309
|
+
? 'Ask the human: freeze, another view, or turn the ? cells, hotspots and side effects into AC, non-goals or forbiddenTransitions (new draft revision).'
|
|
3310
|
+
: 'Ask the human: freeze or another view.'
|
|
3311
|
+
};
|
|
3312
|
+
}
|
|
3313
|
+
|
|
3254
3314
|
function handleActivity() {
|
|
3255
3315
|
const aliases = {
|
|
3256
3316
|
'goal-drafting': 'GOAL_DRAFTING',
|
|
@@ -3706,6 +3766,46 @@ function handleRules() {
|
|
|
3706
3766
|
}
|
|
3707
3767
|
}
|
|
3708
3768
|
|
|
3769
|
+
function handleRecap() {
|
|
3770
|
+
try {
|
|
3771
|
+
const days = argValue('--days') == null ? 7 : Number(argValue('--days'));
|
|
3772
|
+
if (!Number.isInteger(days) || days < 1 || days > 366) {
|
|
3773
|
+
throw Object.assign(new Error('--days must be a whole number from 1 to 366'), { code: 'INVALID_USAGE' });
|
|
3774
|
+
}
|
|
3775
|
+
const { AUDIENCES, renderRecap } = require('../lib/recap-html.js');
|
|
3776
|
+
const audience = argValue('--for') || 'me';
|
|
3777
|
+
if (!AUDIENCES.includes(audience)) throw Object.assign(new Error('--for must be me, lead or client'), { code: 'INVALID_USAGE' });
|
|
3778
|
+
const projectsArg = argValue('--projects');
|
|
3779
|
+
const projects = !projectsArg
|
|
3780
|
+
? [CWD]
|
|
3781
|
+
: projectsArg === 'all'
|
|
3782
|
+
? projectRegistry.listProjects().projects.map((project) => project.path)
|
|
3783
|
+
: projectsArg.split(',').map((item) => path.resolve(CWD, item.trim())).filter(Boolean);
|
|
3784
|
+
if (!projects.length) throw Object.assign(new Error('No projects to recap: register one with `ael projects` or pass --projects <path>'), { code: 'INVALID_USAGE' });
|
|
3785
|
+
if (audience === 'client' && projects.length > 1) {
|
|
3786
|
+
throw Object.assign(new Error('A client recap covers one project only: pass --projects <path> with a single path'), { code: 'INVALID_USAGE' });
|
|
3787
|
+
}
|
|
3788
|
+
const now = argValue('--now') ? new Date(argValue('--now')) : new Date();
|
|
3789
|
+
if (Number.isNaN(now.getTime())) throw Object.assign(new Error('--now must be an ISO date'), { code: 'INVALID_USAGE' });
|
|
3790
|
+
const data = require('../lib/recap.js').collectRecap({ projects, days, now });
|
|
3791
|
+
const html = renderRecap(data, { audience, now, lang: contentLangArg() });
|
|
3792
|
+
const day = (d) => d.toISOString().slice(0, 10);
|
|
3793
|
+
const out = argValue('--out')
|
|
3794
|
+
? path.resolve(CWD, argValue('--out'))
|
|
3795
|
+
: path.join(CWD, '.ai-engineering-loop', 'recaps', `recap-${day(data.window.from)}-${day(now)}-${audience}.html`);
|
|
3796
|
+
fs.mkdirSync(path.dirname(out), { recursive: true });
|
|
3797
|
+
fs.writeFileSync(out, html, { mode: 0o600 });
|
|
3798
|
+
fs.chmodSync(out, 0o600);
|
|
3799
|
+
if (process.argv.includes('--open')) openStudio(out);
|
|
3800
|
+
const summary = { ok: true, path: out, audience, days, projects: data.projects, runs: data.metrics.runs, delivered: data.metrics.delivered };
|
|
3801
|
+
if (process.argv.includes('--json')) console.log(JSON.stringify(summary, null, 2));
|
|
3802
|
+
else log.success(`✓ Recap (${audience}, ${days} days, ${summary.runs} runs, ${summary.delivered} delivered): ${out}`);
|
|
3803
|
+
} catch (error) {
|
|
3804
|
+
log.error(`${error.code || 'RECAP_FAILED'}: ${error.message}`);
|
|
3805
|
+
process.exitCode = 1;
|
|
3806
|
+
}
|
|
3807
|
+
}
|
|
3808
|
+
|
|
3709
3809
|
function handleStats() {
|
|
3710
3810
|
const json = process.argv.includes('--json');
|
|
3711
3811
|
try {
|
|
@@ -4285,6 +4385,7 @@ Commands:
|
|
|
4285
4385
|
draft --from-design <doc.md> [--file <json>] --revision <n> prefill from a design doc, record designRef
|
|
4286
4386
|
freeze --revision <n> --hash <sha256> [--run <id>] [--by <name>]
|
|
4287
4387
|
freeze --latest [--run <id>] --by <name> freeze the newest draft (CLI resolves revision/hash)
|
|
4388
|
+
diagram --view state|storyboard|lanes [--run <id>] [--revision <n>] [--lang <tag>] [--open] draw the Goal flow as HTML
|
|
4288
4389
|
verification Summarize verification.json for compact Judge context
|
|
4289
4390
|
summarize [--run <id>] [--json]
|
|
4290
4391
|
record [--run <id>] [--timeout-ms <n>] [--shell] [--json] -- <executable> [args...]
|
|
@@ -4362,6 +4463,7 @@ Commands:
|
|
|
4362
4463
|
calibrate Compare recorded outcomes with each Run's Finding Ledger: DA misses, wrong dismissals, per reviewer prompt
|
|
4363
4464
|
debt Accepted trade-offs and L3 waivers recorded at delivery: list [--file <path>] | close <id> --by <name> [--note <text>]
|
|
4364
4465
|
next Next unblocked feature from .ai-engineering-loop/features.json, VCR (verified/activated), evidence audit [--json]
|
|
4466
|
+
recap Evidence-backed recap of the last N days as one HTML page [--days 7] [--for me|lead|client] [--projects <p,...>|all] [--out <file>] [--lang <tag>] [--open] [--json]
|
|
4365
4467
|
stats Failure causes by harness layer, false-victory rate, iterations to PASS [--last <n>] [--json]
|
|
4366
4468
|
escalation Compute the minimum Judge model tier from deterministic risk signals
|
|
4367
4469
|
--run <id> target a non-current run
|
|
@@ -4582,6 +4684,9 @@ switch (command) {
|
|
|
4582
4684
|
case 'escalation':
|
|
4583
4685
|
handleEscalation();
|
|
4584
4686
|
break;
|
|
4687
|
+
case 'recap':
|
|
4688
|
+
handleRecap();
|
|
4689
|
+
break;
|
|
4585
4690
|
case 'stats':
|
|
4586
4691
|
handleStats();
|
|
4587
4692
|
break;
|
|
@@ -26,6 +26,7 @@ Additional outcomes are `FAILED`, `SKIPPED`, and `BLOCKED`.
|
|
|
26
26
|
- Structured conditions read only allowlisted run metadata.
|
|
27
27
|
- Legacy gates execute atomically under the workflow lock and mark their corresponding node passed only after existing artifact validation succeeds.
|
|
28
28
|
- Judge `ITERATE` resets Maker and its descendants while preserving upstream analysis.
|
|
29
|
+
- On `ITERATE` the CLI moves that iteration's `verification.json`, `verification-summary.json` and `final-verification.json` to `runs/<id>/iterations/<n>/` and clears the gated-verification marker, so `verify` records fresh evidence for the next Maker diff. Within one iteration, gated evidence stays immutable.
|
|
29
30
|
- Judge `ESCALATE` blocks unfinished nodes.
|
|
30
31
|
|
|
31
32
|
## Commands
|
package/core/goal-contract.md
CHANGED
|
@@ -162,6 +162,44 @@ For UI or multi-step work, add the flow the user should experience as transition
|
|
|
162
162
|
|
|
163
163
|
`goal draft` returns it as a `From | Event | To` table and a Mermaid `stateDiagram-v2` (`flow.mermaid`), with warnings (a state nothing reaches, a state with no way out that is not Done/Error), so the human checks the intent before freeze. A malformed `flow` fails the Goal gate. The PR receipt shows the same diagram (GitHub renders it) and table under "Intended flow", after "Verification artifacts" and before the acceptance criteria.
|
|
164
164
|
|
|
165
|
+
## Look before you freeze: diagrams (C-27)
|
|
166
|
+
|
|
167
|
+
Steps may carry more than `from`, `event`, `to`, so the human can see what else a change touches before freezing:
|
|
168
|
+
|
|
169
|
+
```json
|
|
170
|
+
"flowSubject": "order",
|
|
171
|
+
"flow": [
|
|
172
|
+
{ "from": "Processing", "event": "cancel", "to": "Cancelled", "actor": "user", "guard": "not shipped",
|
|
173
|
+
"effects": [ { "text": "refund to wallet", "ac": "AC-2" }, { "text": "loyalty points revoked?" } ] },
|
|
174
|
+
{ "from": "Shipped", "event": "cancel", "to": "Cancelled", "hotspot": "allowed after shipping?" }
|
|
175
|
+
],
|
|
176
|
+
"forbiddenTransitions": [ { "from": "Delivered", "event": "cancel" } ]
|
|
177
|
+
```
|
|
178
|
+
|
|
179
|
+
- `actor`: who performs the step (user, app, service, db, cron); missing means `user`.
|
|
180
|
+
- `effects[]`: what else changes. An effect with `ac` is covered by that AC; one without `ac` is a **side effect** no AC covers.
|
|
181
|
+
- `hotspot`: an open question (string) or `true`.
|
|
182
|
+
- `flowSubject`: the entity whose status the flow describes.
|
|
183
|
+
- `forbiddenTransitions`: state/event pairs the human decided are invalid.
|
|
184
|
+
- `plainSummary`: one sentence for non-technical readers (used by `recap --for client`, at most 240 characters).
|
|
185
|
+
|
|
186
|
+
The Goal gate rejects an `ac` that is not an AC id, more than 40 steps or 12 effects per step, and forbidden pairs naming an unknown state or event.
|
|
187
|
+
|
|
188
|
+
`goal draft` returns `diagramOptions` (recommended first) and counts in `flow`: `undecided` (state × event pairs nobody decided), `hotspots` (plus conflicting transitions) and `sideEffects`. No file is written. Recommendations: `state` when `flowSubject` is set, `lanes` when steps run across a non-user actor, `storyboard` when every step is a user action. A project sets its default with `- **freeze_diagram**: auto | state | storyboard | lanes | off` in `.ai-engineering-loop/workflow.md` (`off` stops the offer; the command still works).
|
|
189
|
+
|
|
190
|
+
Render only the view the human picks:
|
|
191
|
+
|
|
192
|
+
```bash
|
|
193
|
+
npx ai-engineering-loop goal diagram --view state|storyboard|lanes [--run <id>] [--lang <tag>] [--open]
|
|
194
|
+
```
|
|
195
|
+
|
|
196
|
+
It writes `runs/<id>/diagrams/<view>-r<revision>.html` (`<view>-frozen.html` after freeze): one offline page, light and dark.
|
|
197
|
+
- **state**: a top-to-bottom state machine (`event [guard]`, effect counts, dashed red hotspots) and a transition table over every state × event. A cell is the target, several guarded targets, `conflict`, `invalid` (forbidden) or `?` (undecided).
|
|
198
|
+
- **storyboard**: one card per state in flow order, effects under the action that causes them.
|
|
199
|
+
- **lanes**: one column per actor, steps from top to bottom, so jobs and cron that run later stand out, followed by the same steps as a full-text list.
|
|
200
|
+
|
|
201
|
+
Then ask the human: freeze, another view, or turn `?` cells, hotspots and side effects into AC, non-goals or `forbiddenTransitions` (a new draft revision). A diagram never freezes or changes the Run.
|
|
202
|
+
|
|
165
203
|
## Verification artifacts in the receipt (C-21)
|
|
166
204
|
|
|
167
205
|
The receipt lists `--evidence AC-N=<https-url>` links first, typed as video, screenshot or diagram from the URL. An AC with `crossComponent: true` or a `rubric` is `MISSING` (❌) until it has at least one such link, because a reviewer should be able to look at the behaviour rather than read the diff.
|
package/core/recap.md
ADDED
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
# Recap: what shipped in the last N days
|
|
2
|
+
|
|
3
|
+
`ael recap` turns local Run artifacts into one offline HTML page for a period (C-28). It never changes a Run and never calls a model: every number comes from a Run file.
|
|
4
|
+
|
|
5
|
+
```bash
|
|
6
|
+
npx ai-engineering-loop recap [--days 7] [--for me|lead|client] [--projects <path,...>|all] [--out <file>] [--lang <tag>] [--open] [--json]
|
|
7
|
+
```
|
|
8
|
+
|
|
9
|
+
- `--days`: window length, 1 to 366 (default 7). Runs are grouped by the time in their id.
|
|
10
|
+
- `--for`: which tab opens first. All three are in the file.
|
|
11
|
+
- `--projects`: default is the current project; `all` reads every registered project (`ael projects`). A client recap covers one project only.
|
|
12
|
+
- `--lang`: the language of the Goal text (for example `id`), so screen readers pronounce it right. The page chrome stays English.
|
|
13
|
+
- Output: `.ai-engineering-loop/recaps/recap-<from>-<to>-<for>.html` (mode 0600). It stays local; share it on purpose.
|
|
14
|
+
|
|
15
|
+
There is no built-in schedule. To get one every few days, run it from cron or a scheduled agent.
|
|
16
|
+
|
|
17
|
+
## The three views
|
|
18
|
+
|
|
19
|
+
| View | Shows | Never shows |
|
|
20
|
+
|---|---|---|
|
|
21
|
+
| For me | runs, first-try PASS rate, median cycle time, delivered; activity per day × project; cycle time per run split into goal, maker, verify, review+judge, deliver (from `state.json` history); ITERATE causes | |
|
|
22
|
+
| For the lead | delivered, first-try PASS rate, median cycle time, T2 runs; one card per run with verdict, tier, iterations, green checks, files outside the impact map; an evidence drawer with ACs and their evidence, verification commands with exit code and duration, the Judge reason and links to the artifact files | stdout or stderr |
|
|
23
|
+
| For the client | a "what's new" timeline of delivered runs and what is in progress | file paths, commands, findings, tiers, iterations, branch names |
|
|
24
|
+
|
|
25
|
+
Comparisons ("up 2 vs previous period") appear only when the previous window of the same length has runs.
|
|
26
|
+
|
|
27
|
+
## Text for clients
|
|
28
|
+
|
|
29
|
+
The client sentence is the Goal's `plainSummary`, else `businessOutcome`, else `objective`. When a delivered run falls back to the objective, the lead tab lists it under "Before you share the client tab"; the client tab itself never shows that note. The recap never rewrites it, so write `plainSummary` in the Goal when the work will be shown to a client.
|
package/lib/cli-args.js
CHANGED
|
@@ -24,6 +24,7 @@ const WRITER_COMMANDS = Object.freeze({
|
|
|
24
24
|
valued: ['--host', '--model', '--scenario', '--repeat', '--bin', '--mode', '--timeout', '--host-arg', '--without'],
|
|
25
25
|
positionals: []
|
|
26
26
|
},
|
|
27
|
+
recap: { flags: ['--json', '--open'], valued: ['--days', '--for', '--projects', '--out', '--now', '--lang'], positionals: [] },
|
|
27
28
|
migrate: { flags: ['--json', '--dry-run'], valued: ['--from'], positionals: [] },
|
|
28
29
|
debt: { flags: ['--json'], valued: ['--by', '--note', '--file'], positionals: null },
|
|
29
30
|
outcome: { flags: ['--json'], valued: ['--run', '--source', '--location', '--summary', '--evidence', '--by'], positionals: ['record'] },
|