ai-engineering-loop 2.14.0 → 2.15.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.
Files changed (48) hide show
  1. package/.agents/skills/ael/SKILL.md +4 -4
  2. package/.agents/skills/ael/references/loop-commands.md +6 -3
  3. package/.agents/skills/ael/references/loop-deliver.md +1 -0
  4. package/.agents/skills/ael/references/loop-goal.md +7 -4
  5. package/.agents/skills/ael/references/loop-hosts.md +1 -0
  6. package/.agents/skills/ael/references/loop-modes.md +1 -0
  7. package/CHANGELOG.md +31 -1
  8. package/README.md +1 -0
  9. package/adapters/project-onboarding/SKILL.md +2 -0
  10. package/agents/instruction-only/AGENTS.md +1 -1
  11. package/bin/ai-engineering-loop.js +447 -40
  12. package/core/coordinator.md +33 -0
  13. package/core/garden.md +18 -0
  14. package/core/goal-contract.md +23 -1
  15. package/core/overnight-contract.md +62 -0
  16. package/core/prototype-spike.md +28 -0
  17. package/core/root-cause-analysis.md +27 -0
  18. package/core/run-isolation.md +19 -0
  19. package/core/verification-loop.md +2 -0
  20. package/core/verification-one-pager.md +34 -0
  21. package/core/weekly-process-sampling.md +32 -0
  22. package/lib/agent-artifacts.js +6 -0
  23. package/lib/cli-args.js +5 -3
  24. package/lib/design-ref.js +15 -0
  25. package/lib/driver-scaffold.js +1 -1
  26. package/lib/feature-map.js +427 -1
  27. package/lib/features.js +20 -1
  28. package/lib/garden.js +171 -0
  29. package/lib/gates.js +18 -0
  30. package/lib/git-readiness.js +6 -1
  31. package/lib/goal-runtime.js +31 -1
  32. package/lib/harness-audit.js +1 -1
  33. package/lib/issue-repro.js +460 -0
  34. package/lib/learn.js +34 -0
  35. package/lib/overnight.js +179 -0
  36. package/lib/pr-babysit.js +277 -0
  37. package/lib/run-isolation.js +25 -4
  38. package/lib/spike.js +104 -0
  39. package/lib/ste.js +15 -0
  40. package/lib/verification-lanes.js +1 -2
  41. package/package.json +1 -1
  42. package/schemas/goal-contract.schema.json +13 -0
  43. package/README.npm.md +0 -104
  44. package/docs/images/ael-hero.svg +0 -19
  45. package/docs/images/engineering-loop-overview.svg +0 -114
  46. package/docs/images/social-preview.png +0 -0
  47. package/docs/images/studio-hero-orange.svg +0 -136
  48. package/docs/images/studio-hero.svg +0 -136
@@ -909,12 +909,38 @@ function handleInit() {
909
909
  REQUIRED_FILES.forEach((f) => console.log(` - .ai-engineering-loop/${f}`));
910
910
  log.dim('\nProject context is private by default. Remove .ai-engineering-loop/ from .gitignore if you want to share it.');
911
911
  if (!agentSkillState().installed) log.warn(SETUP_HINT);
912
+ offerFeatureMapScaffold();
912
913
  } else {
913
914
  log.error(`\n✗ Initialization validation failed: ${validation.reason}`);
914
915
  process.exit(1);
915
916
  }
916
917
  }
917
918
 
919
+ // Optional next step. A TTY may say yes; everyone else only sees the command.
920
+ function offerFeatureMapScaffold() {
921
+ const hint = 'Optional next step: `ael feature-map scaffold` drafts .ai-engineering-loop/feature-map.md from routes, OpenAPI, pages, or the README. It does not overwrite a map you edit.';
922
+ try {
923
+ if (fs.existsSync(path.join(CONTEXT_DIR, 'feature-map.md'))) return;
924
+ if (!process.stdin.isTTY || !process.stdout.isTTY) {
925
+ log.dim(hint);
926
+ return;
927
+ }
928
+ process.stdout.write('Draft a feature map from routes, OpenAPI, pages, or the README? [y/N]: ');
929
+ const buffer = Buffer.alloc(16);
930
+ const bytes = fs.readSync(0, buffer, 0, buffer.length, null);
931
+ const answer = buffer.toString('utf8', 0, bytes).trim().toLowerCase();
932
+ if (answer !== 'y' && answer !== 'yes') {
933
+ log.dim(hint);
934
+ return;
935
+ }
936
+ const result = require('../lib/feature-map.js').scaffoldFeatureMap(CWD);
937
+ if (result.written) log.success(`✓ ${result.written} (${result.rows} row(s) from ${result.signals.join(', ') || 'stub'})`);
938
+ else log.dim(hint);
939
+ } catch {
940
+ log.dim(hint);
941
+ }
942
+ }
943
+
918
944
  // Command: status
919
945
  function statusJson() {
920
946
  const result = {
@@ -1033,7 +1059,51 @@ function handleStatus() {
1033
1059
  }
1034
1060
 
1035
1061
  // Command: refresh
1062
+ function handleGarden() {
1063
+ const json = process.argv.includes('--json');
1064
+ if (process.argv.includes('--non-destructive')) {
1065
+ stageJsonError(Object.assign(new Error('--garden does not reconcile context. Nothing was written.'), {
1066
+ code: 'INVALID_USAGE',
1067
+ why: 'Garden only reports stale learnings, feature-map rows, and old Runs.',
1068
+ fix: 'ael refresh --garden'
1069
+ }), json, 'INVALID_USAGE');
1070
+ }
1071
+ try {
1072
+ const garden = require('../lib/garden.js');
1073
+ const apply = process.argv.includes('--yes');
1074
+ const result = apply ? garden.applyGarden(CWD) : garden.planGarden(CWD);
1075
+ if (json) {
1076
+ console.log(JSON.stringify({ ok: true, ...result }, null, 2));
1077
+ return;
1078
+ }
1079
+ console.log(`Garden${apply ? '' : ' (dry-run, nothing written)'}`);
1080
+ if (!result.learnings.length) console.log('Learnings: nothing stale');
1081
+ for (const item of result.learnings) console.log(`Learning ${item.id}: ${item.action} (${item.reason})`);
1082
+ if (result.featureMapSkipped) console.log(`Feature map: skipped (${result.featureMapSkipped})`);
1083
+ else if (!result.featureMap.length) console.log('Feature map: nothing stale');
1084
+ for (const row of result.featureMap) console.log(`Feature ${row.id}: ${row.action}${row.reason ? ` (${row.reason})` : ''} ${row.paths.join(', ')}`);
1085
+ if (!result.runs.length) console.log('Runs: nothing old');
1086
+ for (const row of result.runs) console.log(`Run ${row.runId} ${row.state} ${row.ageDays}d: ${row.action}. ${row.note}`);
1087
+ console.log(apply
1088
+ ? `Wrote: ${result.written.join(', ') || '(nothing)'}`
1089
+ : `Would write: ${result.writes.join(', ') || '(nothing)'}. Apply with: ael refresh --garden --yes`);
1090
+ } catch (err) {
1091
+ stageJsonError(err, json, 'GARDEN_FAILED');
1092
+ }
1093
+ }
1094
+
1036
1095
  function handleRefresh() {
1096
+ if (process.argv.includes('--garden')) {
1097
+ handleGarden();
1098
+ return;
1099
+ }
1100
+ if (process.argv.includes('--yes')) {
1101
+ stageJsonError(Object.assign(new Error('--yes applies a garden tidy. Nothing was written.'), {
1102
+ code: 'INVALID_USAGE',
1103
+ why: 'refresh --yes is not a context refresh.',
1104
+ fix: 'ael refresh --garden --yes'
1105
+ }), process.argv.includes('--json'), 'INVALID_USAGE');
1106
+ }
1037
1107
  if (process.argv.includes('--non-destructive')) {
1038
1108
  handleSafeRefresh();
1039
1109
  return;
@@ -1196,22 +1266,34 @@ function handleSetup() {
1196
1266
  }
1197
1267
  const interactive = process.stdin.isTTY && process.stdout.isTTY && !json && autoUpdate.autoUpdateAllowedHere();
1198
1268
  if (!yes && !interactive) {
1199
- const plan = { ok: true, wrote: false, detected: rows.filter((row) => row.detected).map((row) => row.id), wouldEnable: ids };
1269
+ const plan = {
1270
+ ok: false,
1271
+ wrote: false,
1272
+ code: 'SETUP_NOT_CONFIRMED',
1273
+ detected: rows.filter((row) => row.detected).map((row) => row.id),
1274
+ wouldEnable: ids,
1275
+ why: 'A non-interactive session cannot ask, so setup does not write host files.',
1276
+ fix: 'ai-engineering-loop setup --yes'
1277
+ };
1200
1278
  if (json) console.log(JSON.stringify(plan, null, 2));
1201
1279
  else {
1202
- console.log(hostCommands.formatHostsList(rows, selection));
1203
1280
  console.log(`Would enable: ${ids.join(', ') || '(none detected)'}`);
1204
- console.log('Nothing was written. Run "ai-engineering-loop setup --yes" (optionally --hosts a,b --mode auto|manual) to install.');
1281
+ console.log('Nothing was written.');
1282
+ console.error(`FIX: ${plan.fix}`);
1205
1283
  }
1284
+ process.exitCode = 2;
1206
1285
  return;
1207
1286
  }
1208
1287
  let mode = hostCommands.setupMode({ modeArg, interactive: false });
1288
+ if (!ids.length) {
1289
+ const message = 'No coding agent detected, so nothing was installed. Install Claude Code, Cursor, Codex, OpenCode, or another supported agent, then rerun `ai-engineering-loop setup --yes`.';
1290
+ if (json) console.log(JSON.stringify({ ok: false, wrote: false, code: 'NO_HOSTS', enabled: [], error: message, fix: 'Install a supported coding agent, then `ai-engineering-loop setup --yes`.' }));
1291
+ else console.error(message);
1292
+ process.exitCode = 1;
1293
+ return;
1294
+ }
1209
1295
  if (!yes) {
1210
1296
  console.log(hostCommands.formatHostsList(rows, selection));
1211
- if (!ids.length) {
1212
- console.log('No AI agent detected. Install one, or pick hosts with "setup --hosts <id,...>".');
1213
- return;
1214
- }
1215
1297
  const ok = readTtyLine(`Install the loop for ${ids.join(', ')}? [Y/n] `, 'y');
1216
1298
  if (!['y', 'yes'].includes(ok)) {
1217
1299
  console.log('Nothing was written.');
@@ -1347,7 +1429,7 @@ function workingTreePaths(rootDir) {
1347
1429
  function startWorktreeRun(task, runArgs, runJson, realLog) {
1348
1430
  const isolation = require('../lib/run-isolation.js');
1349
1431
  try {
1350
- const worktree = isolation.createWorktree(CWD, { task });
1432
+ const worktree = isolation.createWorktree(CWD, { task, baseRef: argValue('--base') });
1351
1433
  const passthrough = [];
1352
1434
  for (const flag of ['--mode', '--recipe', '--tier', '--tier-reason']) {
1353
1435
  const value = argValue(flag);
@@ -1361,14 +1443,14 @@ function startWorktreeRun(task, runArgs, runJson, realLog) {
1361
1443
  started = { ok: false, error: (child.stderr || child.stdout || 'run did not start').trim() };
1362
1444
  }
1363
1445
  if (!started.ok) throw Object.assign(new Error(`Worktree created at ${worktree.path}, but the Run did not start: ${started.error}`), { code: started.code || 'RUN_FAILED' });
1364
- isolation.registerWorktree(worktree.mainRoot, { runId: started.runId, path: worktree.path, branch: worktree.branch, base: worktree.base, task, state: 'active', createdAt: new Date().toISOString() });
1365
- const result = { ...started, worktree: { path: worktree.path, branch: worktree.branch, mainCheckout: worktree.mainRoot }, next: `Work only in ${worktree.path} for this Run.` };
1446
+ isolation.registerWorktree(worktree.mainRoot, { runId: started.runId, path: worktree.path, branch: worktree.branch, base: worktree.base, baseRef: worktree.baseRef, task, state: 'active', createdAt: new Date().toISOString() });
1447
+ const result = { ...started, worktree: { path: worktree.path, branch: worktree.branch, baseRef: worktree.baseRef, mainCheckout: worktree.mainRoot }, next: `Work only in ${worktree.path} for this Run.` };
1366
1448
  if (runJson) realLog(JSON.stringify(result, null, 2));
1367
1449
  else {
1368
1450
  console.log = realLog;
1369
1451
  log.success(`✓ Run ${started.runId} started in a new worktree`);
1370
1452
  console.log(`- Path: ${worktree.path}`);
1371
- console.log(`- Branch: ${worktree.branch} (from ${worktree.base.slice(0, 12)})`);
1453
+ console.log(`- Branch: ${worktree.branch} (from ${worktree.baseRef})`);
1372
1454
  console.log(`- Work only in that folder for this Run. After deliver, Stage 9 removes the worktree when it is clean.`);
1373
1455
  }
1374
1456
  } catch (err) {
@@ -1382,7 +1464,23 @@ function startWorktreeRun(task, runArgs, runJson, realLog) {
1382
1464
  function handlePr() {
1383
1465
  const json = process.argv.includes('--json');
1384
1466
  try {
1385
- if (args[1] !== 'status') throw Object.assign(new Error('Use: pr status [--run <id> | --branch <name> | --pr <number>] [--json]'), { code: 'INVALID_USAGE' });
1467
+ if (args[1] === 'babysit') {
1468
+ const runId = argValue('--run');
1469
+ if (!runId) throw Object.assign(new Error('Use: pr babysit --run <id> [--json]'), { code: 'INVALID_USAGE', fix: 'ai-engineering-loop pr babysit --run <id>' });
1470
+ const result = require('../lib/pr-babysit.js').babysit(CWD, { runId });
1471
+ if (json) console.log(JSON.stringify({ ok: true, ...result }, null, 2));
1472
+ else {
1473
+ console.log(`PR #${result.pr} (${result.branch || 'branch unknown'}): ${result.action}${result.reason ? ` (${result.reason})` : ''}`);
1474
+ console.log(result.message);
1475
+ if (result.fixRunId) console.log(`- fix run: ${result.fixRunId}${result.tier ? ` (${result.tier})` : ''}`);
1476
+ if (result.pushed) console.log(`- pushed ${result.branch}`);
1477
+ if (result.next) console.log(`- next: ${result.next}`);
1478
+ for (const blocker of result.blockers || []) console.log(`- blocker: ${blocker}`);
1479
+ if (result.url) console.log(`- ${result.url}`);
1480
+ }
1481
+ return;
1482
+ }
1483
+ if (args[1] !== 'status') throw Object.assign(new Error('Use: pr status [--run <id> | --branch <name> | --pr <number>] [--json] | pr babysit --run <id> [--json]'), { code: 'INVALID_USAGE' });
1386
1484
  const explicit = argValue('--pr') || argValue('--branch');
1387
1485
  const runId = argValue('--run') || (explicit ? null : getCurrentRun(CWD)?.runId) || null;
1388
1486
  const status = require('../lib/pr-status.js').prStatus(CWD, { runId, branch: argValue('--branch'), pr: argValue('--pr') });
@@ -1395,9 +1493,10 @@ function handlePr() {
1395
1493
  console.log(`- ${status.url}`);
1396
1494
  }
1397
1495
  } catch (err) {
1398
- if (json) console.log(JSON.stringify({ ok: false, code: err.code || 'PR_STATUS_FAILED', error: err.message, ...(err.fix ? { fix: err.fix } : {}) }));
1496
+ if (json) console.log(JSON.stringify({ ok: false, code: err.code || 'PR_STATUS_FAILED', error: err.message, ...(err.why ? { why: err.why } : {}), ...(err.fix ? { fix: err.fix } : {}) }));
1399
1497
  else {
1400
1498
  log.error(err.message);
1499
+ if (err.why) console.error(`WHY: ${err.why}`);
1401
1500
  if (err.fix) console.error(`FIX: ${err.fix}`);
1402
1501
  }
1403
1502
  process.exitCode = 1;
@@ -1501,9 +1600,74 @@ function currentRunSafe(dir) {
1501
1600
  }
1502
1601
  }
1503
1602
 
1603
+ function requiredFlag(name, fix) {
1604
+ const index = process.argv.indexOf(name);
1605
+ if (index === -1) return null;
1606
+ const value = process.argv[index + 1];
1607
+ if (!value || value.startsWith('-')) {
1608
+ throw Object.assign(new Error(`${name} needs a value.`), { code: 'INVALID_USAGE', why: 'The bug report source was missing.', fix });
1609
+ }
1610
+ return value;
1611
+ }
1612
+
1613
+ // Bug report -> one red-repro Goal. The Run itself is unchanged after the draft.
1614
+ function reproIntake() {
1615
+ const fromIssue = requiredFlag('--from-issue', 'ael run --from-issue <url|#n>');
1616
+ const fromReport = requiredFlag('--from-report', 'ael outcome repro --file <path>');
1617
+ if (!fromIssue && !fromReport) return null;
1618
+ if (fromIssue && fromReport) {
1619
+ throw Object.assign(new Error('Pass --from-issue or --from-report, not both.'), { code: 'INVALID_USAGE', why: 'One bug report starts one Run.', fix: 'ael run --from-issue <url|#n>' });
1620
+ }
1621
+ const issueRepro = require('../lib/issue-repro.js');
1622
+ return fromIssue ? issueRepro.readIssue(CWD, fromIssue) : issueRepro.readReportFile(CWD, fromReport);
1623
+ }
1624
+
1625
+ const RUN_FLAGS = new Set(['--new', '--json', '--worktree', '--abandon', '--yes', '--force-live', '--help', '-h']);
1626
+ const RUN_VALUED = ['--mode', '--recipe', '--tier', '--tier-reason', '--from-issue', '--from-report', '--run', '--reason', '--by', '--base'];
1627
+
1628
+ function rejectUnknownRunFlags(runArgs) {
1629
+ const valued = new Set(RUN_VALUED);
1630
+ for (let index = 0; index < runArgs.length; index += 1) {
1631
+ const token = runArgs[index];
1632
+ if (token === '--') break;
1633
+ if (!token.startsWith('--')) continue;
1634
+ if (RUN_FLAGS.has(token)) continue;
1635
+ if (valued.has(token)) {
1636
+ index += 1;
1637
+ continue;
1638
+ }
1639
+ const known = [...RUN_FLAGS, ...RUN_VALUED].filter((flag) => flag.startsWith('--'));
1640
+ let suggestion = null;
1641
+ let best = 4;
1642
+ for (const flag of known) {
1643
+ const distance = editDistance(token, flag);
1644
+ if (distance > 0 && distance < best) {
1645
+ suggestion = flag;
1646
+ best = distance;
1647
+ }
1648
+ }
1649
+ throw Object.assign(new Error(`Unknown flag ${token}.${suggestion ? ` Did you mean \`${suggestion}\`?` : ''}`), {
1650
+ code: 'INVALID_USAGE',
1651
+ why: 'Unknown flags are not the task. Treating them as the task can start or replace the active Run.',
1652
+ fix: 'Run `ael help run` for the flags. Quote the task: ael run "Add CSV export".'
1653
+ });
1654
+ }
1655
+ }
1656
+
1504
1657
  function handleRun() {
1505
1658
  if (process.argv.includes('--abandon')) return handleRunAbandon();
1506
1659
  const runJson = process.argv.includes('--json');
1660
+ try {
1661
+ rejectUnknownRunFlags(process.argv.slice(3));
1662
+ } catch (err) {
1663
+ if (runJson) console.log(JSON.stringify({ ok: false, code: err.code, error: err.message, why: err.why, fix: err.fix }));
1664
+ else {
1665
+ log.error(err.message);
1666
+ console.error(`WHY: ${err.why}`);
1667
+ console.error(`FIX: ${err.fix}`);
1668
+ }
1669
+ process.exit(1);
1670
+ }
1507
1671
  const gitState = require('../lib/git-readiness.js').gitReadiness(CWD);
1508
1672
  if (!gitState.ok) {
1509
1673
  if (runJson) console.log(JSON.stringify({ ok: false, code: gitState.code, error: `Cannot start a Run: ${gitState.message}.`, why: gitState.why, fix: gitState.fix }));
@@ -1534,16 +1698,48 @@ function handleRun() {
1534
1698
  const taskParts = [];
1535
1699
  for (let index = 0; index < runArgs.length; index++) {
1536
1700
  if (['--new', '--json', '--worktree'].includes(runArgs[index])) continue;
1537
- if (['--mode', '--recipe', '--tier', '--tier-reason'].includes(runArgs[index])) {
1701
+ if (['--mode', '--recipe', '--tier', '--tier-reason', '--base'].includes(runArgs[index])) {
1702
+ index += 1;
1703
+ continue;
1704
+ }
1705
+ if (['--from-issue', '--from-report'].includes(runArgs[index])) {
1538
1706
  index += 1;
1539
1707
  continue;
1540
1708
  }
1541
1709
  taskParts.push(runArgs[index]);
1542
1710
  }
1543
- const task = taskParts.join(' ').trim();
1544
- if (runArgs.includes('--worktree')) return startWorktreeRun(task, runArgs, runJson, realLog);
1711
+ let task = taskParts.join(' ').trim();
1545
1712
  let runResult;
1713
+ let repro = null;
1546
1714
  try {
1715
+ repro = reproIntake();
1716
+ if (repro && task) {
1717
+ throw Object.assign(new Error('A bug-report Run takes its task from the report.'), { code: 'INVALID_USAGE', why: 'The issue title is the task, so extra words would start a different Run.', fix: 'ael run --from-issue <url|#n>' });
1718
+ }
1719
+ if (repro) task = repro.title;
1720
+ if (process.argv.includes('--base')) {
1721
+ const baseRef = argValue('--base');
1722
+ if (!baseRef || baseRef.startsWith('-')) {
1723
+ throw Object.assign(new Error('--base needs a branch or commit.'), {
1724
+ code: 'INVALID_USAGE',
1725
+ why: 'A stacked Run starts from a commit that already exists in this repository.',
1726
+ fix: 'ael run --worktree --base <branch> "<task>"'
1727
+ });
1728
+ }
1729
+ if (!runArgs.includes('--worktree')) {
1730
+ throw Object.assign(new Error('--base starts a stacked worktree and does not switch this checkout.'), {
1731
+ code: 'INVALID_USAGE',
1732
+ why: 'Checking out another branch here would mix this Run with the stack.',
1733
+ fix: 'ael run --worktree --base <branch> "<task>"'
1734
+ });
1735
+ }
1736
+ }
1737
+ if (runArgs.includes('--worktree')) {
1738
+ if (repro) {
1739
+ throw Object.assign(new Error('--from-issue starts the Run in this checkout.'), { code: 'INVALID_USAGE', why: 'The red-repro Goal is drafted on the Run created here.', fix: 'ael run --from-issue <url|#n>' });
1740
+ }
1741
+ return startWorktreeRun(task, runArgs, runJson, realLog);
1742
+ }
1547
1743
  const current = getCurrentRun(CWD);
1548
1744
  if (!task && (forceNew || !current || TERMINAL_STATES.has(current.state))) {
1549
1745
  throw Object.assign(new Error('run needs a task when no Run is in progress'), { code: 'INVALID_USAGE', why: 'A Run is bound to one task; an empty task cannot be tiered, gated or delivered.', fix: 'ai-engineering-loop run "Add CSV export to the report page"' });
@@ -1613,6 +1809,7 @@ function handleRun() {
1613
1809
  ...(requestedRunId ? { runId: requestedRunId } : {})
1614
1810
  });
1615
1811
  assertBudgetAvailable(CWD, { runId: runResult.run.runId });
1812
+ if (repro) runResult.repro = require('../lib/issue-repro.js').attachReproGoal(CWD, runResult.run.runId, repro);
1616
1813
  } catch (err) {
1617
1814
  console.log = realLog;
1618
1815
  if (runJson) {
@@ -1663,11 +1860,21 @@ function handleRun() {
1663
1860
  return hint ? { worktreeHint: hint } : {};
1664
1861
  })(),
1665
1862
  ...specHintField(runResult),
1863
+ ...(runResult.repro ? { repro: runResult.repro } : {}),
1666
1864
  studioUrl: readStudioUrl(CWD)
1667
1865
  }, null, 2));
1668
1866
  return;
1669
1867
  }
1670
1868
  console.log(`- Run: ${runResult.run.runId} (${runResult.resumed ? 'resumed' : 'created'})`);
1869
+ if (runResult.repro) {
1870
+ const draft = runResult.repro;
1871
+ console.log(`- Red repro: ${draft.failingBehavior}`);
1872
+ console.log(`- Verify (fails today): ${draft.command}`);
1873
+ console.log(`- Issue reader: read-only (${draft.source}${draft.ref ? `, ${draft.ref}` : ''}).`);
1874
+ console.log(draft.drafted
1875
+ ? `- Goal draft revision ${draft.revision}. Next: \`goal show --run ${runResult.run.runId} --human\`, then the human freezes. Maker, verify, Devil's Advocate, Judge, and deliver --approve follow.`
1876
+ : `- Goal draft already present (revision ${draft.revision}).`);
1877
+ }
1671
1878
  if (runResult.run.tier) {
1672
1879
  const t = runResult.run.tier;
1673
1880
  console.log(`- Tier: ${t.current} (${t.source}; ${t.reasons.map((r) => r.code).join(', ')})`);
@@ -1697,7 +1904,9 @@ function handleRun() {
1697
1904
  log.dim(SETUP_HINT);
1698
1905
  }
1699
1906
  log.bold('Agent checklist:');
1700
- console.log('1. Grill if needed (docs grill-policy), then freeze a failure-table Goal Contract');
1907
+ console.log(runResult.repro
1908
+ ? '1. Red-repro Goal is drafted. Show it and wait for the human to freeze (docs root-cause-analysis)'
1909
+ : '1. Grill if needed (docs grill-policy), then freeze a failure-table Goal Contract');
1701
1910
  if (runResult.run.mode === RUN_MODES.REPORT_ONLY) {
1702
1911
  console.log('2. Analyze evidence without changing repository files');
1703
1912
  console.log('3. Write report.json; if the host has a subagent tool, have ONE fresh devil-advocate challenge it (no Judge), and record `review` in report.json (loop-maker)');
@@ -3370,6 +3579,14 @@ function handleGoal() {
3370
3579
  if (draftGoal && draftGoal._templateOnly === true) {
3371
3580
  throw Object.assign(new Error(`${argValue('--file')} is still the scaffold template`), { code: 'TEMPLATE_ONLY', why: 'A template with <...> placeholders would freeze a Goal nobody wrote.', fix: 'Replace every <...> with the real goal, delete `_templateOnly` and `_howTo`, then rerun `goal draft`.' });
3372
3581
  }
3582
+ const restatementErrors = require('../lib/gates.js').restatementProblems(draftGoal);
3583
+ if (restatementErrors.length) {
3584
+ throw Object.assign(new Error(`Goal draft is missing a restatement: ${restatementErrors.join('; ')}`), {
3585
+ code: 'RESTATEMENT_MISSING',
3586
+ why: 'A freeze without a restatement locks the method the human suggested, not the problem the agent understood.',
3587
+ fix: 'Add restatement { problem, doneWhen, failIf, unknowns } to the Goal JSON. State the problem and the outcomes in your own words. Leave the steps out. Then rerun `goal draft`.'
3588
+ });
3589
+ }
3373
3590
  const draftFile = argValue('--file');
3374
3591
  if (draftFile && !path.resolve(CWD, draftFile).startsWith(path.join(CWD, '.ai-engineering-loop') + path.sep)) {
3375
3592
  extra.warning = `Goal draft file ${draftFile} is outside .ai-engineering-loop/, so it will show up in the Maker diff. Keep drafts in .ai-engineering-loop/drafts/.`;
@@ -3379,6 +3596,7 @@ function handleGoal() {
3379
3596
  actor: argValue('--by') || 'agent',
3380
3597
  expectedRevision: requiredIntegerArg('--revision')
3381
3598
  });
3599
+ extra.repoRoot = require('../lib/git-readiness.js').gitTopLevel(CWD);
3382
3600
  extra.impactPreview = impactPreview(runId, draftGoal);
3383
3601
  const ste = require('../lib/ste.js');
3384
3602
  const humanPath = path.join(runsDir(CWD), runId, 'goal.md');
@@ -3445,23 +3663,24 @@ function handleGoal() {
3445
3663
  }
3446
3664
  }
3447
3665
  result = freezeGoal(CWD, runId, {
3448
- actor: argValue('--by') || 'human',
3666
+ actor: argValue('--by'),
3449
3667
  expectedRevision: latest ? latestDraft.metadata.revision : requiredIntegerArg('--revision'),
3450
3668
  expectedHash
3451
3669
  });
3670
+ const human = result.goal.actor;
3452
3671
  appendRunLifecycle(CWD, runId, {
3453
3672
  type: goalNode ? 'NODE_COMPLETED' : 'GOAL_FROZEN',
3454
3673
  ...(goalNode ? { nodeId: goalNode.id } : {}),
3455
3674
  phase: 'goal',
3456
- actor: argValue('--by') || 'human',
3675
+ actor: human,
3457
3676
  message: 'Goal Contract frozen'
3458
3677
  });
3459
3678
  ensureImpactMap(runId);
3460
- closeFreezeQuestions(runId, argValue('--by') || 'human');
3679
+ closeFreezeQuestions(runId, human);
3461
3680
  // One human stop: the same person accepts the Goal and its blast radius
3462
3681
  // (shown as impactPreview with the draft).
3463
3682
  if (process.argv.includes('--confirm-impact')) {
3464
- const confirmed = impactMap.confirmImpactMap(CWD, { runId, by: argValue('--by') || 'human' });
3683
+ const confirmed = impactMap.confirmImpactMap(CWD, { runId, by: human });
3465
3684
  extra.impact = { status: confirmed.map ? confirmed.map.status : 'CONFIRMED' };
3466
3685
  }
3467
3686
  } else if (action === 'diagram') {
@@ -3479,6 +3698,7 @@ function handleGoal() {
3479
3698
  process.stdout.write(fs.readFileSync(path.join(CWD, extra.human.path), 'utf8'));
3480
3699
  console.log('');
3481
3700
  }
3701
+ if (action === 'draft') console.log(`- Repo: ${extra.repoRoot || 'unresolved'}`);
3482
3702
  if (extra.impactPreview) console.log(`- Impact preview: ${JSON.stringify(extra.impactPreview).slice(0, 200)}`);
3483
3703
  if (extra.warning) console.log(`! ${extra.warning}`);
3484
3704
  console.log(action === 'draft' ? `- Next: the human reads this and says freeze; then \`goal freeze --latest --run ${runId} --by <name>\`. Agents: add --json.` : '- Next: Maker (implement), then `gate maker --from-git`. Agents: add --json.');
@@ -3719,6 +3939,13 @@ function repeatedArg(name) {
3719
3939
  return values;
3720
3940
  }
3721
3941
 
3942
+ function commandOutputTail(value, limit = 800) {
3943
+ const text = String(value || '').trim();
3944
+ if (!text || text === '(no stdout)') return '';
3945
+ const tail = text.split('\n').slice(-12).join('\n');
3946
+ return tail.length > limit ? tail.slice(-limit) : tail;
3947
+ }
3948
+
3722
3949
  async function handleVerify() {
3723
3950
  const json = process.argv.includes('--json');
3724
3951
  try {
@@ -3840,16 +4067,32 @@ async function handleVerify() {
3840
4067
  ...(related ? { scope: 'related' } : {}),
3841
4068
  ...(timeoutValue == null ? {} : { timeoutMs: parsePositiveIntegerArg('--timeout-ms', timeoutValue) })
3842
4069
  });
3843
- const commands = recorded.commands.map((c) => ({ command: c.command, exitCode: c.exitCode, timeoutStatus: c.timeoutStatus, ...(c.layer ? { layer: c.layer } : {}), ...(c.scope ? { scope: c.scope } : {}), ...(c.reused ? { reused: true } : {}) }));
4070
+ const commands = recorded.commands.map((c) => ({
4071
+ command: c.command,
4072
+ exitCode: c.exitCode,
4073
+ timeoutStatus: c.timeoutStatus,
4074
+ ...(c.layer ? { layer: c.layer } : {}),
4075
+ ...(c.scope ? { scope: c.scope } : {}),
4076
+ ...(c.reused ? { reused: true } : {}),
4077
+ ...(!recorded.passed && (c.exitCode !== 0 || c.timeoutStatus !== 'COMPLETED') ? {
4078
+ stdoutTail: commandOutputTail(c.stdout),
4079
+ stderrTail: commandOutputTail(c.stderr)
4080
+ } : {})
4081
+ }));
3844
4082
  if (!recorded.passed) {
3845
4083
  autoHeartbeat(runId, 'verification', 'Verification failed; Maker must fix before review');
3846
4084
  const baselineModule = require('../lib/baseline.js');
3847
4085
  const failures = baselineModule.classifyAgainstBaseline(baselineModule.loadBaseline(CWD, runId), recorded.commands);
3848
- const result = { ok: false, code: 'VERIFICATION_FAILED', runId, commands, skipped: recorded.skipped, failures, gate: null };
4086
+ const result = { ok: false, code: 'VERIFICATION_FAILED', runId, commands, skipped: recorded.skipped, failures, gate: null, evidence: `.ai-engineering-loop/runs/${runId}/verification.json` };
3849
4087
  if (json) console.log(JSON.stringify(result));
3850
4088
  else {
3851
4089
  log.error('Verification failed; the gate was not attempted.');
3852
- for (const c of commands) console.log(`- ${c.command}: exit ${c.exitCode} (${c.timeoutStatus})`);
4090
+ console.log(`- Evidence: .ai-engineering-loop/runs/${runId}/verification.json`);
4091
+ for (const c of commands) {
4092
+ console.log(`- ${c.command}: exit ${c.exitCode} (${c.timeoutStatus})`);
4093
+ if (c.stderrTail) console.log(`- stderr:\n${c.stderrTail}`);
4094
+ if (c.stdoutTail) console.log(`- stdout:\n${c.stdoutTail}`);
4095
+ }
3853
4096
  for (const skippedCommand of recorded.skipped) console.log(`- ${skippedCommand}: skipped (an earlier, cheaper check failed)`);
3854
4097
  for (const c of recorded.commands.filter((item) => item.exitCode !== 0)) {
3855
4098
  const rulesLib = require('../lib/rules.js');
@@ -3920,7 +4163,17 @@ function handleOutcome() {
3920
4163
  const json = process.argv.includes('--json');
3921
4164
  try {
3922
4165
  const action = args[1] && !args[1].startsWith('--') ? args[1] : null;
3923
- if (action !== 'record') throw Object.assign(new Error('outcome supports: record --run <id> --source mr-comment|revert|bug|incident --location <file[:line]> --summary <text> --by <name> [--evidence <path|url>]'), { code: 'INVALID_USAGE' });
4166
+ if (action === 'repro') {
4167
+ const file = argValue('--file');
4168
+ if (!file || file.startsWith('-')) {
4169
+ throw Object.assign(new Error('outcome repro needs --file <path> with the pasted bug report.'), { code: 'INVALID_USAGE', why: 'Without a live issue reader, the bug report is a local file.', fix: 'ael outcome repro --file .ai-engineering-loop/drafts/bug-report.md' });
4170
+ }
4171
+ process.once('exit', () => projectRegistry.registerProject(CWD));
4172
+ process.argv = [process.argv[0], process.argv[1], 'run', '--from-report', file, ...(json ? ['--json'] : [])];
4173
+ return handleRun();
4174
+ }
4175
+ if (action !== 'record') throw Object.assign(new Error('outcome supports: record --run <id> --source mr-comment|revert|bug|incident --location <file[:line]> --summary <text> --by <name> [--evidence <path|url>] | repro --file <path>'), { code: 'INVALID_USAGE' });
4176
+ if (argValue('--file')) throw Object.assign(new Error('outcome record does not take --file.'), { code: 'INVALID_USAGE', fix: 'ael outcome repro --file <path>' });
3924
4177
  const entry = require('../lib/calibration.js').recordOutcome(CWD, {
3925
4178
  runId: argValue('--run'),
3926
4179
  source: argValue('--source'),
@@ -3974,8 +4227,14 @@ function handleNext() {
3974
4227
  const json = process.argv.includes('--json');
3975
4228
  try {
3976
4229
  const features = require('../lib/features.js');
3977
- const document = features.loadFeatures(CWD);
3978
- if (!document) throw Object.assign(new Error('No .ai-engineering-loop/features.json. FIX: create it with {"schemaVersion":1,"features":[{"id","title","behavior","verify","status":"not_started","priority","dependsOn":[]}]}.'), { code: 'NO_FEATURES' });
4230
+ const document = features.loadFeatures(CWD) || features.featuresFromMap(CWD);
4231
+ if (!document) {
4232
+ throw Object.assign(new Error(`No feature list. FIX: run \`ael feature-map scaffold\`, or create .ai-engineering-loop/features.json with ${features.FEATURES_EXAMPLE}`), {
4233
+ code: 'NO_FEATURES',
4234
+ why: 'next needs a feature list. features.json is the ledger; feature-map.md is the map scaffold writes.',
4235
+ fix: 'ael feature-map scaffold'
4236
+ });
4237
+ }
3979
4238
  const next = features.nextFeature(document);
3980
4239
  const ratio = features.vcr(document);
3981
4240
  const problems = features.auditFeatures(CWD, document);
@@ -4253,16 +4512,24 @@ function handleReviewPack() {
4253
4512
  try {
4254
4513
  const changed = require('../lib/verification-lanes.js').relatedFiles(CWD, run);
4255
4514
  openDebt = require('../lib/debt.js').openDebtFor(CWD, changed);
4256
- if (openDebt.length && pack.path) {
4257
- const lines = ['', '## Open debt on changed files', '', ...openDebt.map((item) => `- ${item.id} ${item.location}: ${item.debt} (deferred: ${item.whyDeferred}; risk ${item.risk})`)];
4258
- fs.appendFileSync(path.join(CWD, pack.path), `${lines.join('\n')}\n`);
4259
- }
4260
- // C-22: user-facing features this diff touches, with how to reach them.
4261
4515
  const featureMap = require('../lib/feature-map.js');
4262
4516
  touchedFeatures = featureMap.featuresForFiles(CWD, changed);
4263
- if (touchedFeatures.length && pack.path) fs.appendFileSync(path.join(CWD, pack.path), `${featureMap.renderForPack(touchedFeatures)}\n`);
4264
4517
  const unconfirmed = require('../lib/provenance.js').renderUnconfirmed(require('../lib/provenance.js').loadProvenance(CWD, runId), '## Unconfirmed assumptions in the Goal (raise a finding if the code relies on one)');
4265
- if (unconfirmed.length && pack.path) fs.appendFileSync(path.join(CWD, pack.path), `\n${unconfirmed.join('\n')}\n`);
4518
+ const sections = [];
4519
+ if (openDebt.length) {
4520
+ sections.push(['## Open debt on changed files', '', ...openDebt.map((item) => `- ${item.id} ${item.location}: ${item.debt} (deferred: ${item.whyDeferred}; risk ${item.risk})`)].join('\n'));
4521
+ }
4522
+ const featuresNote = featureMap.renderForPack(touchedFeatures).trim();
4523
+ if (featuresNote) sections.push(featuresNote);
4524
+ if (unconfirmed.length) sections.push(unconfirmed.join('\n').trim());
4525
+ // Appendices used to be concatenated onto the JSON file, which made
4526
+ // escalation and gate judge reject it. Rewrite the whole document.
4527
+ if (sections.length && pack.path) {
4528
+ const abs = path.join(CWD, pack.path);
4529
+ const document = JSON.parse(fs.readFileSync(abs, 'utf8'));
4530
+ document.appendices = sections;
4531
+ require('../lib/fsutil.js').writePrivateJson(abs, document);
4532
+ }
4266
4533
  } catch {
4267
4534
  openDebt = [];
4268
4535
  }
@@ -4617,6 +4884,25 @@ function handleSources() {
4617
4884
  }
4618
4885
  }
4619
4886
 
4887
+ function handleFeatureMap() {
4888
+ const json = process.argv.includes('--json');
4889
+ try {
4890
+ if (args[1] !== 'scaffold') throw Object.assign(new Error('Use: feature-map scaffold [--json]'), { code: 'INVALID_USAGE' });
4891
+ const result = require('../lib/feature-map.js').scaffoldFeatureMap(CWD);
4892
+ if (json) {
4893
+ console.log(JSON.stringify({ ok: true, ...result }, null, 2));
4894
+ return;
4895
+ }
4896
+ if (result.preserved) console.log(`! ${result.file} was edited; new draft saved as ${result.written}`);
4897
+ else if (result.written) console.log(`✓ ${result.written} (${result.rows} row(s) from ${result.signals.join(', ') || 'stub'})`);
4898
+ else console.log(`- ${result.file} unchanged`);
4899
+ if (!result.rows) console.log('No routes, OpenAPI, pages, README feature bullets, package.json bin, or src directories found. Next: add a ## Features list or fill the stub table, then rerun `ael feature-map scaffold`.');
4900
+ else console.log('Check the rows, then `driver scaffold` to add a driver for each feature.');
4901
+ } catch (err) {
4902
+ stageJsonError(err, json, 'FEATURE_MAP_FAILED');
4903
+ }
4904
+ }
4905
+
4620
4906
  function handleDriver() {
4621
4907
  const json = process.argv.includes('--json');
4622
4908
  try {
@@ -4671,6 +4957,99 @@ function learnFromTranscripts(json) {
4671
4957
  }
4672
4958
  }
4673
4959
 
4960
+ function handleSpike() {
4961
+ const json = process.argv.includes('--json');
4962
+ const sub = args[1];
4963
+ const fail = (err) => stageJsonError(err, json, 'SPIKE_FAILED');
4964
+ if (sub !== 'record' && sub !== 'show') {
4965
+ fail(Object.assign(new Error('Use: spike record --discarded --question <text> --learned <text> | spike show'), {
4966
+ code: 'INVALID_USAGE',
4967
+ why: 'A spike note is recorded before the Goal freeze, or shown.',
4968
+ fix: 'ael spike record --discarded --question "<one question>" --learned "<what the contract should say>"'
4969
+ }));
4970
+ }
4971
+ try {
4972
+ const spike = require('../lib/spike.js');
4973
+ if (sub === 'show') {
4974
+ const result = spike.showSpike(CWD, { runId: argValue('--run') });
4975
+ if (json) console.log(JSON.stringify(result, null, 2));
4976
+ else if (!result.recorded) console.log(result.runId ? `Run ${result.runId} has no spike. A spike is optional.` : 'No current Run.');
4977
+ else if (!result.ok) {
4978
+ console.error(`${result.code}: ${result.error}`);
4979
+ if (result.fix) console.error(`FIX: ${result.fix}`);
4980
+ } else console.log(`Spike discarded. Question: ${result.spike.question}`);
4981
+ if (!result.ok) process.exitCode = 1;
4982
+ return;
4983
+ }
4984
+ const result = spike.recordSpike(CWD, {
4985
+ runId: argValue('--run'),
4986
+ question: argValue('--question'),
4987
+ learned: argValue('--learned'),
4988
+ discarded: process.argv.includes('--discarded')
4989
+ });
4990
+ if (json) console.log(JSON.stringify({ ok: true, ...result }, null, 2));
4991
+ else console.log(`Recorded ${result.path}. Draft the Goal from that note, then ask the human to freeze.`);
4992
+ } catch (err) {
4993
+ fail(err);
4994
+ }
4995
+ }
4996
+
4997
+ function handleOvernight() {
4998
+ const json = process.argv.includes('--json');
4999
+ const sub = args[1] && !String(args[1]).startsWith('-') ? args[1] : 'check';
5000
+ const fail = (err) => stageJsonError(err, json, 'OVERNIGHT_FAILED');
5001
+ if (sub !== 'check') {
5002
+ fail(Object.assign(new Error('Use: overnight check [--run <id>] [--json]'), {
5003
+ code: 'INVALID_USAGE',
5004
+ why: 'The overnight contract is checked against one Run.',
5005
+ fix: 'ael overnight check --run <id>'
5006
+ }));
5007
+ }
5008
+ try {
5009
+ const valued = new Set(['--run']);
5010
+ const flags = new Set(['--json']);
5011
+ const scoped = process.argv.slice(3);
5012
+ for (let index = 0; index < scoped.length; index += 1) {
5013
+ const token = scoped[index];
5014
+ if (token === 'check') continue;
5015
+ if (!token.startsWith('-')) {
5016
+ throw Object.assign(new Error(`Unexpected argument ${token}.`), { code: 'INVALID_USAGE', fix: 'ael overnight check --run <id>' });
5017
+ }
5018
+ if (valued.has(token)) {
5019
+ const value = scoped[index + 1];
5020
+ if (!value || value.startsWith('-')) throw Object.assign(new Error(`${token} needs a value.`), { code: 'INVALID_USAGE', fix: 'ael overnight check --run <id>' });
5021
+ index += 1;
5022
+ continue;
5023
+ }
5024
+ if (!flags.has(token)) throw Object.assign(new Error(`Unknown flag ${token}.`), { code: 'INVALID_USAGE', fix: 'ael overnight check --run <id>' });
5025
+ }
5026
+ const result = require('../lib/overnight.js').morningReview(CWD, { runId: argValue('--run') });
5027
+ if (json) console.log(JSON.stringify(result, null, 2));
5028
+ else {
5029
+ console.log(`Overnight contract (${result.contract.id})`);
5030
+ if (!result.runId) {
5031
+ console.log('No current Run.');
5032
+ console.log(`May: ${result.contract.mayDo.join('; ')}`);
5033
+ console.log(`Must not: ${result.contract.mustNot.join('; ')}`);
5034
+ console.log(`Stop when: ${result.contract.stopWhen.join(', ')}`);
5035
+ console.log('FIX: ael overnight check --run <id>');
5036
+ } else {
5037
+ console.log(`Run ${result.runId} ${result.mode} ${result.state}`);
5038
+ console.log(`Applies: ${result.applies ? 'yes' : 'no'}`);
5039
+ console.log(`May continue: ${result.mayContinue ? 'yes' : 'no'}`);
5040
+ console.log(`Stop: ${result.stopReason || '(none)'}`);
5041
+ console.log(`Morning missing: ${result.morning.missing.join(', ') || '(none)'}`);
5042
+ console.log(`Questions: ${result.morning.questions.length}`);
5043
+ if (!result.violations.length) console.log('Violations: (none)');
5044
+ for (const item of result.violations) console.log(`Violation ${item.id}: ${item.why} FIX: ${item.fix}`);
5045
+ }
5046
+ }
5047
+ if (!result.ok) process.exitCode = 1;
5048
+ } catch (err) {
5049
+ fail(err);
5050
+ }
5051
+ }
5052
+
4674
5053
  function handleLearn() {
4675
5054
  const json = process.argv.includes('--json');
4676
5055
  if (args[1] === 'promote') {
@@ -4758,13 +5137,21 @@ Commands:
4758
5137
  status Check the validity, readiness, and baseline freshness of context
4759
5138
  --json print context, host-skill freshness, and studioUrl (tokenless Studio identity; browser session comes from ael studio)
4760
5139
  refresh Reconcile drifted context against repository non-destructively
5140
+ --non-destructive keep filled files and write *.ael-new
5141
+ --garden [--json] report stale learnings, dead feature-map rows, and old Runs; writes nothing
5142
+ --garden --yes prune those learnings and move fully dead feature-map rows; Runs stay
5143
+ See docs garden.
4761
5144
  run [task] Start or resume a stateful engineering run and instruct the agent (never writes to home)
4762
5145
  --new start a new run even when another run is active
4763
5146
  --worktree start this task in a new git worktree (use when another run is unfinished)
5147
+ --base <branch> with --worktree, start from that local commit (stacked PRs; docs coordinator)
4764
5148
  --mode report-only|assisted|unattended
4765
5149
  --recipe <id> bind an immutable compiled workflow plan
4766
5150
  --tier T0|T1|T2 --tier-reason <text> override the automatic tier (recorded)
4767
5151
  --json print runId, tier, tier reasons, subagent count, recipe, workflowSource, and studioUrl (tokenless; browser session comes from ael studio)
5152
+ --from-issue <url|#n> read one GitHub (gh) or GitLab (glab) issue and draft a red-repro Goal, then the normal loop
5153
+ read-only: never comments or edits the issue. No gh/glab: outcome repro --file <path>
5154
+ --from-report <path> same draft from a pasted report (outcome repro --file)
4768
5155
  --abandon [--run <id>] --reason <text> --by <name> [--yes] [--force-live] [--json]
4769
5156
  close a stale run as CANCELLED (kept on disk) and release current.json;
4770
5157
  ASSISTED asks to confirm, UNATTENDED needs --yes from a human
@@ -4777,11 +5164,11 @@ Commands:
4777
5164
  --json print machine-readable gate output
4778
5165
  goal Share one revision-bound Goal draft between the Agent and Studio
4779
5166
  show [--run <id>]
4780
- draft --file <json> --revision <n> [--run <id>] [--by <agent>]
5167
+ draft --file <json> --revision <n> [--run <id>] [--by <agent>] prints repoRoot (git toplevel)
4781
5168
  draft --from-design <doc.md> [--file <json>] --revision <n> prefill from a design doc, record designRef
4782
- freeze --revision <n> --hash <sha256> [--run <id>] [--by <name>]
5169
+ freeze --revision <n> --hash <sha256> [--run <id>] --by <human>
4783
5170
  show --human [--run <id>] the Goal as plain Markdown for people (STE style: short active sentences)
4784
- freeze --latest [--run <id>] --by <name> freeze the newest draft (CLI resolves revision/hash)
5171
+ freeze --latest [--run <id>] --by <human> newest draft; --by is the person who agreed (not agent or ael-agent)
4785
5172
  diagram --view state|storyboard|lanes [--run <id>] [--revision <n>] [--lang <tag>] [--open] draw the Goal flow as HTML
4786
5173
  verification Summarize verification.json for compact Judge context
4787
5174
  summarize [--run <id>] [--json]
@@ -4857,13 +5244,15 @@ Commands:
4857
5244
  bench compare <benchIdA> <benchIdB> [--json] read-only side-by-side table
4858
5245
  outcome record --run <id> --source mr-comment|revert|bug|incident --location <file[:line]> --summary <text> --by <name>
4859
5246
  a post-delivery problem traced to a Run (input for calibrate)
5247
+ repro --file <path> [--json] pasted bug report -> one red-repro Goal, then the normal loop (read-only)
4860
5248
  calibrate Compare recorded outcomes with each Run's Finding Ledger: DA misses, wrong dismissals, per reviewer prompt
4861
5249
  debt Accepted trade-offs and L3 waivers recorded at delivery: list [--file <path>] | close <id> --by <name> [--note <text>]
4862
5250
  next Next unblocked feature from .ai-engineering-loop/features.json, VCR (verified/activated), evidence audit [--json]
4863
5251
  worktree Clean up AEL worktrees: prune [--audit] [--include-scratch] [--yes] [--json] (never removes changed tracked files, open PRs or foreign worktrees)
4864
- pr One read-only PR snapshot via gh: status [--run <id> | --branch <name> | --pr <n>] [--json]; records merge.json when merged
5252
+ pr Pull request after delivery. status [--run <id> | --branch <name> | --pr <n>] [--json] reads once and records merge.json when merged. babysit --run <id> [--json] polls with backoff, starts a T0 or T1 fix on that same branch when checks fail, and leaves the merge to you
4865
5253
  sources Where the agent digs before asking (read-only): show | refresh | hint | record --source <id> --ref <ref> --line <text>
4866
5254
  driver Scaffold a reusable verification driver per feature-map row: scaffold [--feature <id>] [--surface web|api|cli|launch]
5255
+ feature-map Draft .ai-engineering-loop/feature-map.md from routes, OpenAPI, pages, or the README: scaffold [--json]
4867
5256
  safety Record the one fact a change is safe because of [record --fact <text> --cmd <proof>] (T2 Judge PASS needs level 4+)
4868
5257
  measurement Record how a performance number was measured [record --ac <id> --runs <n> --spread <pct> --effect <pct> --limiter <text>]
4869
5258
  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]
@@ -4913,6 +5302,15 @@ Commands:
4913
5302
  built-in instead of --check: --forbid-import "<fromGlob> -> <toGlob>" | --forbid-api "<regex>" [--except <glob>]
4914
5303
  rules check <ruleId> run a built-in rule on the added lines (used by verify)
4915
5304
  turn a recurring review lesson into an executable L1 rule (.ai-engineering-loop/rules.json)
5305
+ spike Record a throwaway prototype before the Goal freeze
5306
+ record --discarded --question <text> --learned <text> [--run <id>] [--json]
5307
+ show [--run <id>] [--json]
5308
+ Refuses a spike that is not discarded, or a Goal that is already frozen.
5309
+ See docs prototype-spike. No arena.
5310
+ overnight Check an UNATTENDED Run against the overnight contract
5311
+ check [--run <id>] [--json]
5312
+ exit 1 when it delivered without a person, or a stop is missing the morning files
5313
+ See docs overnight-contract.
4916
5314
  learn Mine past Runs' VALID findings into .ai-engineering-loop/learnings.json (+ .md) for context packs
4917
5315
  [--dry-run] [--prune] [--max-age-runs <n>] [--json]
4918
5316
  deterministic and deduped with runId provenance; --prune drops lessons whose files are gone
@@ -4993,7 +5391,7 @@ function printHelp() {
4993
5391
  }
4994
5392
 
4995
5393
  function commandNames() {
4996
- return [...new Set(helpText().split('\n').map((line) => (line.match(/^ ([a-z][\w-]*)(?: \[task\])?\s+(?=[A-Z])/) || [])[1]).filter(Boolean))];
5394
+ return [...new Set(helpText().split('\n').map((line) => (line.match(/^ ([a-z][\w-]*)(?: (?:\[[^\]]+\]|<[^>]+>))*(?:\s{2,}|\s+(?=[A-Z])|\s*$)/) || [])[1]).filter(Boolean))];
4997
5395
  }
4998
5396
 
4999
5397
  function shortHelp() {
@@ -5001,7 +5399,7 @@ function shortHelp() {
5001
5399
 
5002
5400
  Start here:
5003
5401
  npm i -g ai-engineering-loop Node 18+ and git required
5004
- ael setup install the ael skill into your coding agents
5402
+ ael setup install the ael skill (agents and scripts: ael setup --yes)
5005
5403
  ael init write .ai-engineering-loop/ for this project
5006
5404
  Then tell your agent: "Use AI Engineering Loop to build <your feature>"
5007
5405
 
@@ -5181,6 +5579,9 @@ switch (command) {
5181
5579
  case 'driver':
5182
5580
  handleDriver();
5183
5581
  break;
5582
+ case 'feature-map':
5583
+ handleFeatureMap();
5584
+ break;
5184
5585
  case 'worktree':
5185
5586
  handleWorktree();
5186
5587
  break;
@@ -5229,6 +5630,12 @@ switch (command) {
5229
5630
  case 'learn':
5230
5631
  handleLearn();
5231
5632
  break;
5633
+ case 'overnight':
5634
+ handleOvernight();
5635
+ break;
5636
+ case 'spike':
5637
+ handleSpike();
5638
+ break;
5232
5639
  case 'quick':
5233
5640
  handleQuick();
5234
5641
  break;