ai-engineering-loop 2.14.1 → 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.
- package/.agents/skills/ael/SKILL.md +4 -4
- package/.agents/skills/ael/references/loop-commands.md +6 -3
- package/.agents/skills/ael/references/loop-deliver.md +1 -0
- package/.agents/skills/ael/references/loop-goal.md +7 -4
- package/.agents/skills/ael/references/loop-hosts.md +1 -0
- package/.agents/skills/ael/references/loop-modes.md +1 -0
- package/CHANGELOG.md +23 -1
- package/README.md +1 -0
- package/adapters/project-onboarding/SKILL.md +2 -0
- package/agents/instruction-only/AGENTS.md +1 -1
- package/bin/ai-engineering-loop.js +446 -39
- package/core/coordinator.md +33 -0
- package/core/garden.md +18 -0
- package/core/goal-contract.md +23 -1
- package/core/overnight-contract.md +62 -0
- package/core/prototype-spike.md +28 -0
- package/core/root-cause-analysis.md +27 -0
- package/core/run-isolation.md +19 -0
- package/core/verification-loop.md +2 -0
- package/core/verification-one-pager.md +34 -0
- package/core/weekly-process-sampling.md +32 -0
- package/lib/agent-artifacts.js +6 -0
- package/lib/cli-args.js +5 -3
- package/lib/design-ref.js +15 -0
- package/lib/driver-scaffold.js +1 -1
- package/lib/feature-map.js +427 -1
- package/lib/features.js +20 -1
- package/lib/garden.js +171 -0
- package/lib/gates.js +18 -0
- package/lib/git-readiness.js +6 -1
- package/lib/goal-runtime.js +31 -1
- package/lib/harness-audit.js +1 -1
- package/lib/issue-repro.js +460 -0
- package/lib/learn.js +34 -0
- package/lib/overnight.js +179 -0
- package/lib/pr-babysit.js +277 -0
- package/lib/run-isolation.js +25 -4
- package/lib/spike.js +104 -0
- package/lib/ste.js +15 -0
- package/package.json +1 -1
- package/schemas/goal-contract.schema.json +13 -0
|
@@ -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 = {
|
|
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.
|
|
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.
|
|
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]
|
|
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
|
-
|
|
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(
|
|
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')
|
|
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:
|
|
3675
|
+
actor: human,
|
|
3457
3676
|
message: 'Goal Contract frozen'
|
|
3458
3677
|
});
|
|
3459
3678
|
ensureImpactMap(runId);
|
|
3460
|
-
closeFreezeQuestions(runId,
|
|
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:
|
|
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) => ({
|
|
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
|
-
|
|
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
|
|
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)
|
|
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
|
-
|
|
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>]
|
|
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 <
|
|
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
|
|
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
|
|
@@ -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
|
|
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;
|