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.
@@ -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).slice(0, 10) };
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 freeze');
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
@@ -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'] },