ai-engineering-loop 2.8.0 → 2.10.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.
@@ -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.
@@ -4,6 +4,7 @@
4
4
  - Branch on mode. REPORT_ONLY: never edit repository files; write `RUN_DIR/report.json` with summary and recommendations, then the report review (`loop-report`), run `gate report`, and stop. ASSISTED: the parent (or intern) is Maker; delivery later needs human approval. UNATTENDED: `sandbox create --run <runId>`, Maker works only in the returned worktreePath, never the parent checkout, then `sandbox capture --run <runId>`.
5
5
  - Maker intern: read `maker_intern` from workflow.md (missing or `none` = parent is Maker). Confirm it through the host model catalog; otherwise the parent is Maker and you report INVOCATION_UNAVAILABLE. The intern cannot skip later gates or spawn DA/Judge.
6
6
  - Guardrails: Claude Code enforces them after `hooks install`. Elsewhere, before an out-of-scope edit or a destructive command (`rm -rf`, `DROP TABLE`, `git push --force`, `git reset --hard`, `git clean -fd`) run `guard check --tool edit --path <file>` or `--tool bash --command "<cmd>"`: `warn` = ask the human, `block` = do not run it.
7
+ - No code comments in product code (C-26): put intent in names, types, tests; rationale in the commit.
7
8
  - Bugs: red repro first. Features: one red test per AC row, then green.
8
9
  - After package and manifest edits are stable, run `npx ai-engineering-loop refresh` once (drift during red-green is expected; do not refresh per test cycle).
9
10
  - `eslint --fix` and other auto-fixers run before `gate maker`, never after.
@@ -38,7 +38,7 @@ Report Spec and Standards as separate findings. Do not rerank one axis with the
38
38
 
39
39
  **Standards** (`axis: "standards"`): `.ai-engineering-loop/conventions.md` plus the smell baseline below. Judgement calls: severity MEDIUM or LOW. Set `hardConvention: true` only when conventions.md states a hard rule that this hunk violates. A smell that hides an AC defect is Spec, not Standards.
40
40
 
41
- Skip style nits unless they hide a defect. The CLI adds `comment-justification` findings for new suppressions and workaround comments: decide whether the root cause should be fixed instead; dismiss one only with evidence. Learnings in the pack carry `confidence`; never raise BLOCKER or HIGH only because a `tentative` (one-Run) learning was not followed.
41
+ Skip style nits unless they hide a defect. The CLI adds `comment-justification` findings for new suppressions and workaround comments: decide whether the root cause should be fixed instead; dismiss one only with evidence. It also adds blocking `no-comments` findings (C-26) for any other comment added in product code; never ask the Maker to add a comment. Learnings in the pack carry `confidence`; never raise BLOCKER or HIGH only because a `tentative` (one-Run) learning was not followed.
42
42
 
43
43
  Rubric ACs: when an AC in the Goal Contract has `rubric`, add `rubricScores: [{ac, criterion, pass, evidence}]` to the ledger, one per criterion. `evidence` must be observed (screenshot path, DOM snapshot, measured value), never an impression. A criterion you cannot observe is `pass: false`.
44
44
 
@@ -39,7 +39,7 @@ Report Spec and Standards as separate findings. Do not rerank one axis with the
39
39
 
40
40
  **Standards** (`axis: "standards"`): `.ai-engineering-loop/conventions.md` plus the smell baseline below. Judgement calls: severity MEDIUM or LOW. Set `hardConvention: true` only when conventions.md states a hard rule that this hunk violates. A smell that hides an AC defect is Spec, not Standards.
41
41
 
42
- Skip style nits unless they hide a defect. The CLI adds `comment-justification` findings for new suppressions and workaround comments: decide whether the root cause should be fixed instead; dismiss one only with evidence. Learnings in the pack carry `confidence`; never raise BLOCKER or HIGH only because a `tentative` (one-Run) learning was not followed.
42
+ Skip style nits unless they hide a defect. The CLI adds `comment-justification` findings for new suppressions and workaround comments: decide whether the root cause should be fixed instead; dismiss one only with evidence. It also adds blocking `no-comments` findings (C-26) for any other comment added in product code; never ask the Maker to add a comment. Learnings in the pack carry `confidence`; never raise BLOCKER or HIGH only because a `tentative` (one-Run) learning was not followed.
43
43
 
44
44
  Rubric ACs: when an AC in the Goal Contract has `rubric`, add `rubricScores: [{ac, criterion, pass, evidence}]` to the ledger, one per criterion. `evidence` must be observed (screenshot path, DOM snapshot, measured value), never an impression. A criterion you cannot observe is `pass: false`.
45
45
 
package/CHANGELOG.md CHANGED
@@ -6,9 +6,23 @@ All notable changes to this project are documented here. Versions follow [Semant
6
6
 
7
7
  _No changes yet._
8
8
 
9
+ ## 2.10.0 - 2026-11-17
10
+
11
+ Cards C-27 and C-28 in `docs/cards/slop-to-gold-2026-11-16.md`.
12
+
13
+ - **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`.
14
+ - **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`).
15
+
16
+ ## 2.9.0 - 2026-11-16
17
+
18
+ From "All Code Is Slop (Except Mine)" 08:06-08:46 (card C-26 in `docs/cards/slop-to-gold-2026-11-16.md`).
19
+
20
+ - **Added:** no comments in product code by default (C-26): every comment line a change adds in a non-test product file (besides suppressions and workaround comments, which stay C-18 findings) becomes one blocking `no-comments` finding per file (`hardConvention: true`, HIGH), so the Judge returns ITERATE. Comment detection follows each language's syntax and ignores strings, shebangs, license headers, `@generated` and tool directives. Opt out per project with `"comments": "allow"` in `.ai-engineering-loop/rules.json`; a reviewer may dismiss one finding only with evidence.
21
+ - **Changed:** C-18 suppression detection now follows each file's comment syntax and also covers `prettier-ignore`, `biome-ignore`, `stylelint-disable`, `rubocop:disable` and `pylint: disable`.
22
+
9
23
  ## 2.8.0 - 2026-11-16
10
24
 
11
- From "All Code Is Slop (Except Mine)" (cards C-17..C-24 in `docs/cards/slop-to-gold-2026-11-16.md`).
25
+ From "All Code Is Slop (Except Mine)" (cards C-17..C-25 in `docs/cards/slop-to-gold-2026-11-16.md`).
12
26
 
13
27
  - **Added:** ratchet rules: `learn promote --scope diff` judges only lines the change adds (`$AEL_ADDED_LINES_FILE`, `$AEL_CHANGED_FILES`), so a rule can be promoted on a codebase with old violations; `doctor --harness` reports each diff rule's legacy backlog (C-17).
14
28
  - **Added:** suppressions (`eslint-disable`, `@ts-ignore`, `# noqa`, ...) and workaround comments added in product code become `comment-justification` review findings (HIGH without a reason, otherwise MEDIUM); reviewers may dismiss them only with evidence (C-18).
@@ -31,7 +31,7 @@ Report Spec and Standards as separate findings. Do not rerank one axis with the
31
31
 
32
32
  **Standards** (`axis: "standards"`): `.ai-engineering-loop/conventions.md` plus the smell baseline below. Judgement calls: severity MEDIUM or LOW. Set `hardConvention: true` only when conventions.md states a hard rule that this hunk violates. A smell that hides an AC defect is Spec, not Standards.
33
33
 
34
- Skip style nits unless they hide a defect. The CLI adds `comment-justification` findings for new suppressions and workaround comments: decide whether the root cause should be fixed instead; dismiss one only with evidence. Learnings in the pack carry `confidence`; never raise BLOCKER or HIGH only because a `tentative` (one-Run) learning was not followed.
34
+ Skip style nits unless they hide a defect. The CLI adds `comment-justification` findings for new suppressions and workaround comments: decide whether the root cause should be fixed instead; dismiss one only with evidence. It also adds blocking `no-comments` findings (C-26) for any other comment added in product code; never ask the Maker to add a comment. Learnings in the pack carry `confidence`; never raise BLOCKER or HIGH only because a `tentative` (one-Run) learning was not followed.
35
35
 
36
36
  Rubric ACs: when an AC in the Goal Contract has `rubric`, add `rubricScores: [{ac, criterion, pass, evidence}]` to the ledger, one per criterion. `evidence` must be observed (screenshot path, DOM snapshot, measured value), never an impression. A criterion you cannot observe is `pass: false`.
37
37
 
@@ -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;
@@ -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.
@@ -106,6 +106,16 @@ Agents write comments to justify not doing the right thing, and comments cannot
106
106
 
107
107
  Docs, changelogs, data files and tests are skipped. Unlike C-11, a reviewer may downgrade these with `dismissal: {by, evidence}` (for example generated code); dropping or downgrading one without evidence fails the review gate.
108
108
 
109
+ ## 3d. No Comments in Product Code (C-26)
110
+
111
+ Comments go stale, humans skip them, agents use them to justify not doing the right thing, and nothing enforces them. So AEL bans new comments in product code by default. At `gate review` every other comment line added in a non-test product file (not a suppression or justification, which stay C-18 findings) becomes one `source: "no-comments"` finding per file: `axis: "standards"`, `hardConvention: true`, **HIGH**, VALID, with the line numbers as evidence. It blocks, so the Judge returns ITERATE until the comments are gone.
112
+
113
+ Where the intent goes instead: names, types, tests and lint rules (`learn promote`); rationale goes in the commit message, PR body or `docs/`.
114
+
115
+ Detection follows the file's comment syntax: `//`, `/* */` and `*` lines in C-family, JS/TS, Go, Rust, CSS and similar; `#` in Python, shell, Ruby, Terraform, Makefile and Dockerfile; `<!-- -->` in HTML, Vue, Svelte; `--` in SQL and Lua. Markers inside string literals do not count, nor does `#` glued to a name (JS `#private`). Always allowed: shebangs, `SPDX-License-Identifier`, copyright and `@license`, `@generated`, TS `/// <reference`, `//go:build`/`//go:generate`, encoding lines, `#region`. Docs, data and config files (`.md`, `.json`, `.yml`, `.toml`, ...) and tests are skipped.
116
+
117
+ A reviewer can downgrade a finding (for example public API docs that a doc generator reads) only with `dismissal: {by, evidence}`. A project that needs comments (a library shipping JSDoc, for example) opts out for every Run by having a human add `"comments": "allow"` to `.ai-engineering-loop/rules.json`; C-18 findings still apply.
118
+
109
119
  ## 4. The 4 Verification Gates
110
120
 
111
121
  1. **Gate 1: Unit & Integration Tests**: All unit and edge-case tests must pass with 0 failures.
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'] },
@@ -1,18 +1,19 @@
1
1
  'use strict';
2
2
 
3
- // C-18 ("All Code Is Slop (Except Mine)", 06:46-08:46): agents write comments
4
- // to justify not doing the right thing, and comments cannot be enforced.
5
- // New suppressions and justification comments in product code become
6
- // standards findings, so the reviewer must decide: root cause or patch?
7
- // Unlike C-11 integrity findings, a reviewer may dismiss these with evidence.
8
-
9
3
  const fs = require('fs');
10
4
  const path = require('path');
11
5
  const { isTestFile, parseDiff } = require('./verification-integrity.js');
12
6
 
13
7
  const SOURCE = 'comment-justification';
14
- const SKIP_FILE = /\.(md|mdx|txt|rst|json|lock|ya?ml|toml|csv|svg|snap)$|(^|\/)(CHANGELOG|LICENSE)/i;
15
- const COMMENT = /(\/\/|\/\*|^\s*\*|(^|\s)#|<!--|(^|\s)--\s)/;
8
+ const NO_COMMENTS_SOURCE = 'no-comments';
9
+ const SKIP_FILE = /\.(md|mdx|txt|rst|json|jsonc|lock|ya?ml|toml|ini|cfg|conf|env|csv|svg|snap|xml|plist)$|(^|\/)(CHANGELOG|LICENSE|NOTICE|README)[^/]*$/i;
10
+
11
+ const SLASH = /\.(c|h|cc|cpp|hpp|cs|java|kt|kts|scala|swift|go|rs|js|jsx|mjs|cjs|ts|tsx|mts|cts|dart|php|css|scss|less|groovy|proto|zig|sol)$/i;
12
+ const HASH = /\.(py|pyi|sh|bash|zsh|fish|rb|pl|pm|r|ps1|tf|hcl|nix|cmake|mk)$|(^|\/)(Makefile|Dockerfile|Gemfile|Rakefile|BUILD|WORKSPACE)$/i;
13
+ const MARKUP = /\.(html?|vue|svelte|astro)$/i;
14
+ const DASH = /\.(sql|lua|hs|elm)$/i;
15
+
16
+ const ALLOWED = /^#!|SPDX-License-Identifier|\bcopyright\b|@license|@preserve|@generated|^\/\/\/\s*<reference|^\/\/go:(build|generate|embed)|^\/\/\s*\+build|-\*-\s*coding|^#\s*(region|endregion)\b|^\/\/\s*#(region|endregion)\b|webpackChunkName|@vite-ignore/i;
16
17
  const SUPPRESS = [
17
18
  { pattern: /eslint-disable(?:-next-line|-line)?/, reason: /eslint-disable\S*(?:\s.*?)?\s--\s+(.{10,})/ },
18
19
  { pattern: /@ts-ignore/, reason: /@ts-ignore\s+(.{10,})/ },
@@ -21,31 +22,84 @@ const SUPPRESS = [
21
22
  { pattern: /#\s*noqa/, reason: /noqa\S*\s+#?\s*(.{10,})/ },
22
23
  { pattern: /\/\/\s*nolint/, reason: /nolint\S*\s+\/\/\s*(.{10,})/ },
23
24
  { pattern: /NOSONAR/, reason: /NOSONAR\s+(.{10,})/ },
24
- { pattern: /istanbul ignore|c8 ignore/, reason: /ignore \w+\s+(.{10,})/ }
25
+ { pattern: /istanbul ignore|c8 ignore/, reason: /ignore \w+\s+(.{10,})/ },
26
+ { pattern: /prettier-ignore|biome-ignore|stylelint-disable|rubocop:disable|pylint:\s*disable/, reason: /(?:prettier-ignore|biome-ignore\S*|stylelint-disable\S*|rubocop:disable\S*|pylint:\s*disable\S*)\s+.*?(?:--|:)\s*(.{10,})/ }
25
27
  ];
26
28
  const JUSTIFICATION = /\b(work-?around|quick[- ]?fix|hack(y)?|temporary|temp fix|for now|band-?aid|kludge|until we|proper fix later|fix (this )?later)\b/i;
27
29
 
28
- function loadExtraPatterns(rootDir) {
30
+ function commentIndex(text, marker) {
31
+ let quote = null;
32
+ for (let i = 0; i < text.length; i += 1) {
33
+ const ch = text[i];
34
+ if (quote) {
35
+ if (ch === '\\') i += 1;
36
+ else if (ch === quote) quote = null;
37
+ continue;
38
+ }
39
+ if (ch === '"' || ch === "'" || ch === '`') {
40
+ quote = ch;
41
+ continue;
42
+ }
43
+ if (text.startsWith(marker, i)) {
44
+ if (marker === '#' && i > 0 && !/\s/.test(text[i - 1])) continue;
45
+ return i;
46
+ }
47
+ }
48
+ return -1;
49
+ }
50
+
51
+ function commentOf(file, text) {
52
+ if (SLASH.test(file)) {
53
+ if (/^\s*\*(?!\*\/)/.test(text) && !/^\s*\*\s*[\w(]+\s*[=;)]/.test(text)) return text.trim();
54
+ for (const marker of ['//', '/*']) {
55
+ const at = commentIndex(text, marker);
56
+ if (at !== -1) return text.slice(at).trim();
57
+ }
58
+ const jsx = text.indexOf('{/*');
59
+ return jsx !== -1 ? text.slice(jsx).trim() : null;
60
+ }
61
+ if (HASH.test(file)) {
62
+ const at = commentIndex(text, '#');
63
+ return at !== -1 ? text.slice(at).trim() : null;
64
+ }
65
+ if (MARKUP.test(file)) {
66
+ const at = text.indexOf('<!--');
67
+ if (at !== -1) return text.slice(at).trim();
68
+ const slash = commentIndex(text, '//');
69
+ return slash !== -1 && /^\s*\/\//.test(text) ? text.slice(slash).trim() : null;
70
+ }
71
+ if (DASH.test(file)) {
72
+ const at = commentIndex(text, '--');
73
+ return at !== -1 ? text.slice(at).trim() : null;
74
+ }
75
+ return null;
76
+ }
77
+
78
+ function loadProjectRules(rootDir) {
29
79
  try {
30
- const value = JSON.parse(fs.readFileSync(path.join(rootDir, '.ai-engineering-loop', 'rules.json'), 'utf8'));
31
- return (value.justificationPatterns || []).map((text) => new RegExp(text, 'i'));
80
+ return JSON.parse(fs.readFileSync(path.join(rootDir, '.ai-engineering-loop', 'rules.json'), 'utf8'));
32
81
  } catch {
33
- return [];
82
+ return {};
34
83
  }
35
84
  }
36
85
 
37
- function scanComments(diffText, { extraPatterns = [] } = {}) {
86
+ function loadExtraPatterns(rootDir) {
87
+ return (loadProjectRules(rootDir).justificationPatterns || []).map((text) => new RegExp(text, 'i'));
88
+ }
89
+
90
+ function scanComments(diffText, { extraPatterns = [], noComments = true } = {}) {
38
91
  const findings = [];
39
92
  let n = 0;
40
93
  for (const file of parseDiff(diffText)) {
41
94
  if (file.deleted || isTestFile(file.path) || SKIP_FILE.test(file.path)) continue;
95
+ const plain = [];
42
96
  for (const added of file.added) {
43
- const text = added.text;
44
- if (!COMMENT.test(text)) continue;
97
+ const comment = commentOf(file.path, added.text);
98
+ if (!comment) continue;
45
99
  const location = `${file.path}:${added.line}`;
46
- const suppress = SUPPRESS.find((item) => item.pattern.test(text));
100
+ const suppress = SUPPRESS.find((item) => item.pattern.test(comment));
47
101
  if (suppress) {
48
- const reasoned = suppress.reason.test(text);
102
+ const reasoned = suppress.reason.test(comment);
49
103
  findings.push({
50
104
  id: `COMMENT-${++n}`,
51
105
  axis: 'standards',
@@ -53,59 +107,81 @@ function scanComments(diffText, { extraPatterns = [] } = {}) {
53
107
  failureScenario: reasoned
54
108
  ? 'A lint/type/coverage suppression was added; it hides the signal instead of fixing what the check found'
55
109
  : 'A lint/type/coverage suppression was added with no reason; the next agent will copy it as the established pattern',
56
- evidence: `added line: ${text.trim().slice(0, 160)}`,
110
+ evidence: `added line: ${added.text.trim().slice(0, 160)}`,
57
111
  severity: reasoned ? 'MEDIUM' : 'HIGH',
58
112
  validity: 'VALID',
59
113
  disposition: 'WEAK',
60
- concreteAlternativeDiff: `- ${text.trim()}\n+ (remove the suppression and fix the code the check flagged)`,
114
+ concreteAlternativeDiff: `- ${added.text.trim()}\n+ (remove the suppression and fix the code the check flagged)`,
61
115
  source: SOURCE
62
116
  });
63
117
  continue;
64
118
  }
65
- const custom = extraPatterns.find((pattern) => pattern.test(text));
66
- if (JUSTIFICATION.test(text) || custom) {
119
+ if (ALLOWED.test(comment)) continue;
120
+ if (JUSTIFICATION.test(comment) || extraPatterns.some((pattern) => pattern.test(comment))) {
67
121
  findings.push({
68
122
  id: `COMMENT-${++n}`,
69
123
  axis: 'standards',
70
124
  location,
71
125
  failureScenario: 'A comment justifies a workaround instead of fixing the root cause; comments cannot be enforced and the workaround spreads',
72
- evidence: `added line: ${text.trim().slice(0, 160)}`,
126
+ evidence: `added line: ${added.text.trim().slice(0, 160)}`,
73
127
  severity: 'MEDIUM',
74
128
  validity: 'VALID',
75
129
  disposition: 'WEAK',
76
130
  source: SOURCE
77
131
  });
132
+ continue;
78
133
  }
134
+ plain.push(added);
135
+ }
136
+ if (noComments && plain.length) {
137
+ const lines = plain.map((added) => added.line);
138
+ findings.push({
139
+ id: `NOCOMMENT-${++n}`,
140
+ axis: 'standards',
141
+ hardConvention: true,
142
+ location: `${file.path}:${lines[0]}`,
143
+ failureScenario: `${plain.length} comment line(s) added in product code; comments go stale, cannot be enforced, and agents copy them as license to explain instead of fix`,
144
+ evidence: `comment lines ${lines.slice(0, 12).join(', ')}${lines.length > 12 ? ', ...' : ''}; first: ${plain[0].text.trim().slice(0, 120)}`,
145
+ severity: 'HIGH',
146
+ validity: 'VALID',
147
+ disposition: 'WEAK',
148
+ concreteAlternativeDiff: `- ${plain[0].text.trim()}\n+ (delete it: put intent in names, types, tests or a lint rule; put rationale in the commit message or docs/)`,
149
+ source: NO_COMMENTS_SOURCE
150
+ });
79
151
  }
80
152
  }
81
153
  return findings;
82
154
  }
83
155
 
84
156
  function scanRunComments(rootDir, run) {
157
+ const rules = loadProjectRules(rootDir);
85
158
  try {
86
- return scanComments(fs.readFileSync(path.join(rootDir, run.artifacts.diff.path), 'utf8'), { extraPatterns: loadExtraPatterns(rootDir) });
159
+ return scanComments(fs.readFileSync(path.join(rootDir, run.artifacts.diff.path), 'utf8'), {
160
+ extraPatterns: (rules.justificationPatterns || []).map((text) => new RegExp(text, 'i')),
161
+ noComments: rules.comments !== 'allow'
162
+ });
87
163
  } catch {
88
164
  return [];
89
165
  }
90
166
  }
91
167
 
92
- // Reviewers may downgrade these, but only with dismissal.evidence.
93
168
  function mergeCommentFindings(ledger, findings) {
94
169
  const errors = [];
95
- const existing = new Map((ledger.findings || []).filter((item) => item.source === SOURCE).map((item) => [item.location, item]));
170
+ const sources = new Set([SOURCE, NO_COMMENTS_SOURCE]);
171
+ const existing = new Map((ledger.findings || []).filter((item) => sources.has(item.source)).map((item) => [`${item.source}|${item.location}`, item]));
96
172
  const additions = [];
97
173
  for (const item of findings) {
98
- const present = existing.get(item.location);
174
+ const present = existing.get(`${item.source}|${item.location}`);
99
175
  if (!present) {
100
176
  additions.push(item);
101
177
  continue;
102
178
  }
103
- const downgraded = present.validity !== 'VALID' || present.severity !== item.severity;
179
+ const downgraded = present.validity !== 'VALID' || present.severity !== item.severity || (item.hardConvention && present.hardConvention !== true);
104
180
  if (downgraded && !String(present.dismissal?.evidence || '').trim()) {
105
- errors.push(`${present.id} (${present.location}) was downgraded without dismissal.evidence. FIX: restore it, or add dismissal: {by, evidence} explaining why the suppression or workaround is the right call here.`);
181
+ errors.push(`${present.id} (${present.location}) was downgraded without dismissal.evidence. FIX: restore it, or add dismissal: {by, evidence} explaining why this comment or suppression must stay.`);
106
182
  }
107
183
  }
108
184
  return { ledger: { ...ledger, findings: [...(ledger.findings || []), ...additions] }, added: additions.length, errors };
109
185
  }
110
186
 
111
- module.exports = { SOURCE, mergeCommentFindings, scanComments, scanRunComments };
187
+ module.exports = { NO_COMMENTS_SOURCE, SOURCE, commentOf, loadExtraPatterns, mergeCommentFindings, scanComments, scanRunComments };