ai-engineering-loop 1.10.0 → 1.11.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.agents/devil-advocate.md +13 -1
- package/.agents/judge.md +10 -0
- package/.agents/skills/backend-development/SKILL.md +272 -0
- package/.agents/skills/backend-development/references/api-design-guidelines.md +95 -0
- package/.agents/skills/backend-development/references/query-and-database-best-practices.md +53 -0
- package/.agents/skills/backend-development/references/security-checklist.md +60 -0
- package/.agents/workflows/ai-engineering-loop.md +4 -4
- package/.claude/agents/devil-advocate.md +13 -1
- package/.claude/agents/judge.md +10 -0
- package/.claude/skills/ai-engineering-loop/SKILL.md +4 -4
- package/.claude/skills/backend-development/SKILL.md +272 -0
- package/.claude/skills/backend-development/references/api-design-guidelines.md +95 -0
- package/.claude/skills/backend-development/references/query-and-database-best-practices.md +53 -0
- package/.claude/skills/backend-development/references/security-checklist.md +60 -0
- package/.gemini/skills/ai-engineering-loop/SKILL.md +4 -4
- package/.gemini/skills/backend-development/SKILL.md +272 -0
- package/.gemini/skills/backend-development/references/api-design-guidelines.md +95 -0
- package/.gemini/skills/backend-development/references/query-and-database-best-practices.md +53 -0
- package/.gemini/skills/backend-development/references/security-checklist.md +60 -0
- package/.grok/agents/devil-advocate.md +13 -1
- package/.grok/agents/judge.md +10 -0
- package/.grok/skills/ai-engineering-loop/SKILL.md +4 -4
- package/.grok/skills/backend-development/SKILL.md +272 -0
- package/.grok/skills/backend-development/references/api-design-guidelines.md +95 -0
- package/.grok/skills/backend-development/references/query-and-database-best-practices.md +53 -0
- package/.grok/skills/backend-development/references/security-checklist.md +60 -0
- package/README.md +33 -1
- package/README.npm.md +8 -1
- package/agents/shared/devil-advocate.body.md +13 -1
- package/agents/shared/judge.body.md +10 -0
- package/bin/ai-engineering-loop.js +207 -2
- package/core/runtime-safety.md +43 -0
- package/lib/budget.js +35 -0
- package/lib/doctor.js +4 -0
- package/lib/run-compaction.js +170 -0
- package/lib/runtime-policy.js +24 -1
- package/lib/safe-context.js +32 -7
- package/lib/smart-context.js +643 -0
- package/lib/studio-server.js +19 -2
- package/lib/sync-hosts.js +20 -0
- package/lib/update-manager.js +147 -0
- package/lib/verification-summary.js +130 -0
- package/package.json +1 -1
- package/policies/review-budget.md +12 -0
- package/studio/app.js +5 -2
|
@@ -46,6 +46,7 @@ const {
|
|
|
46
46
|
assertModeAllowed,
|
|
47
47
|
loadPolicy,
|
|
48
48
|
normalizeMode,
|
|
49
|
+
normalizeReviewProfile,
|
|
49
50
|
updatePolicy
|
|
50
51
|
} = require('../lib/runtime-policy.js');
|
|
51
52
|
const {
|
|
@@ -55,6 +56,17 @@ const {
|
|
|
55
56
|
createContextPack,
|
|
56
57
|
contextPackSummary
|
|
57
58
|
} = require('../lib/safe-context.js');
|
|
59
|
+
const {
|
|
60
|
+
assessSmallTaskFastPath,
|
|
61
|
+
buildContextIndex,
|
|
62
|
+
createDiffHunkPack,
|
|
63
|
+
queryContextIndex,
|
|
64
|
+
relatedContextIndex,
|
|
65
|
+
smartContextSummary
|
|
66
|
+
} = require('../lib/smart-context.js');
|
|
67
|
+
const {
|
|
68
|
+
compactRun
|
|
69
|
+
} = require('../lib/run-compaction.js');
|
|
58
70
|
const {
|
|
59
71
|
defaultCasesDir,
|
|
60
72
|
loadEvaluationCases,
|
|
@@ -65,9 +77,16 @@ const {
|
|
|
65
77
|
const {
|
|
66
78
|
assessRunEscalation
|
|
67
79
|
} = require('../lib/escalation.js');
|
|
80
|
+
const {
|
|
81
|
+
writeVerificationSummary
|
|
82
|
+
} = require('../lib/verification-summary.js');
|
|
68
83
|
const {
|
|
69
84
|
runDoctor
|
|
70
85
|
} = require('../lib/doctor.js');
|
|
86
|
+
const {
|
|
87
|
+
checkForUpdate,
|
|
88
|
+
executeUpdatePlan
|
|
89
|
+
} = require('../lib/update-manager.js');
|
|
71
90
|
const {
|
|
72
91
|
assertBudgetAvailable,
|
|
73
92
|
budgetStatus,
|
|
@@ -1045,9 +1064,11 @@ function handlePolicy() {
|
|
|
1045
1064
|
const mode = argValue('--default-mode');
|
|
1046
1065
|
const allowUnattended = argValue('--allow-unattended');
|
|
1047
1066
|
const requireSandbox = argValue('--require-sandbox');
|
|
1067
|
+
const reviewProfile = argValue('--review-profile');
|
|
1048
1068
|
const perRunLimit = argValue('--per-run-token-limit');
|
|
1049
1069
|
const dailyLimit = argValue('--daily-token-limit');
|
|
1050
1070
|
if (mode != null) changes.defaultMode = normalizeMode(mode);
|
|
1071
|
+
if (reviewProfile != null) changes.reviewProfile = normalizeReviewProfile(reviewProfile);
|
|
1051
1072
|
if (allowUnattended != null) {
|
|
1052
1073
|
changes.allowUnattended = parseBooleanArg('--allow-unattended', allowUnattended);
|
|
1053
1074
|
}
|
|
@@ -1142,6 +1163,35 @@ function handleSandbox() {
|
|
|
1142
1163
|
}
|
|
1143
1164
|
}
|
|
1144
1165
|
|
|
1166
|
+
function handleVerification() {
|
|
1167
|
+
const action = process.argv[3] || 'summarize';
|
|
1168
|
+
const json = process.argv.includes('--json');
|
|
1169
|
+
const runId = argValue('--run');
|
|
1170
|
+
try {
|
|
1171
|
+
if (action !== 'summarize') throw new Error('Unknown verification action. Use summarize');
|
|
1172
|
+
const result = writeVerificationSummary(CWD, { runId });
|
|
1173
|
+
if (json) {
|
|
1174
|
+
console.log(JSON.stringify({
|
|
1175
|
+
ok: true,
|
|
1176
|
+
path: result.path,
|
|
1177
|
+
commandCount: result.summary.commandCount,
|
|
1178
|
+
exitCode: result.summary.exitCode,
|
|
1179
|
+
passed: result.summary.passed,
|
|
1180
|
+
testCounts: result.summary.testCounts
|
|
1181
|
+
}));
|
|
1182
|
+
} else {
|
|
1183
|
+
log.success('✓ verification summary created');
|
|
1184
|
+
console.log(`- Path: ${result.path}`);
|
|
1185
|
+
console.log(`- Commands: ${result.summary.commandCount}, exit code: ${result.summary.exitCode}`);
|
|
1186
|
+
console.log(`- Tests: ${JSON.stringify(result.summary.testCounts)}`);
|
|
1187
|
+
}
|
|
1188
|
+
} catch (err) {
|
|
1189
|
+
if (json) console.log(JSON.stringify({ ok: false, code: err.code || 'VERIFICATION_ERROR', error: err.message }));
|
|
1190
|
+
else log.error(err.message);
|
|
1191
|
+
process.exit(1);
|
|
1192
|
+
}
|
|
1193
|
+
}
|
|
1194
|
+
|
|
1145
1195
|
function handleGate() {
|
|
1146
1196
|
const gate = process.argv[3];
|
|
1147
1197
|
const runId = argValue('--run');
|
|
@@ -1329,16 +1379,95 @@ function commandFiles(startIndex, optionsWithValues = []) {
|
|
|
1329
1379
|
function handleContext() {
|
|
1330
1380
|
const stage = process.argv[3];
|
|
1331
1381
|
const runId = argValue('--run');
|
|
1382
|
+
const profile = argValue('--profile');
|
|
1383
|
+
const base = argValue('--base') || 'HEAD';
|
|
1384
|
+
const query = argValue('--query');
|
|
1385
|
+
const limit = Number(argValue('--limit') || 10);
|
|
1332
1386
|
const json = process.argv.includes('--json');
|
|
1333
|
-
const
|
|
1387
|
+
const includeIgnored = process.argv.includes('--include-ignored');
|
|
1388
|
+
const files = commandFiles(4, ['--run', '--profile', '--base', '--query', '--limit']);
|
|
1334
1389
|
try {
|
|
1335
|
-
|
|
1390
|
+
if (stage === 'index') {
|
|
1391
|
+
const result = buildContextIndex(CWD, { files, includeIgnored });
|
|
1392
|
+
const summary = smartContextSummary(result);
|
|
1393
|
+
if (json) {
|
|
1394
|
+
console.log(JSON.stringify({ ok: true, ...summary }));
|
|
1395
|
+
} else {
|
|
1396
|
+
log.success('✓ smart context index created');
|
|
1397
|
+
console.log(`- Path: ${summary.path}`);
|
|
1398
|
+
console.log(`- Files: ${summary.files}`);
|
|
1399
|
+
}
|
|
1400
|
+
return;
|
|
1401
|
+
}
|
|
1402
|
+
if (stage === 'query') {
|
|
1403
|
+
const result = queryContextIndex(CWD, { query: query || files.join(' '), limit });
|
|
1404
|
+
if (json) {
|
|
1405
|
+
console.log(JSON.stringify({ ok: true, ...result }));
|
|
1406
|
+
} else {
|
|
1407
|
+
log.success('✓ context index query complete');
|
|
1408
|
+
console.log(`- Matches: ${result.matches.length}`);
|
|
1409
|
+
for (const match of result.matches) console.log(` - ${match.path}${match.symbols.length ? ` (${match.symbols.join(', ')})` : ''}`);
|
|
1410
|
+
}
|
|
1411
|
+
return;
|
|
1412
|
+
}
|
|
1413
|
+
if (stage === 'related') {
|
|
1414
|
+
const result = relatedContextIndex(CWD, { file: files[0], limit });
|
|
1415
|
+
if (json) {
|
|
1416
|
+
console.log(JSON.stringify({ ok: true, ...result }));
|
|
1417
|
+
} else {
|
|
1418
|
+
log.success('✓ related context query complete');
|
|
1419
|
+
console.log(`- File: ${result.file}`);
|
|
1420
|
+
for (const match of result.matches) console.log(` - ${match.path}`);
|
|
1421
|
+
}
|
|
1422
|
+
return;
|
|
1423
|
+
}
|
|
1424
|
+
if (stage === 'fast-path') {
|
|
1425
|
+
const result = assessSmallTaskFastPath(CWD, { base, includeIgnored });
|
|
1426
|
+
if (json) {
|
|
1427
|
+
console.log(JSON.stringify({ ok: true, ...result }));
|
|
1428
|
+
} else {
|
|
1429
|
+
log.success(result.eligible ? '✓ small-task fast path eligible' : 'Small-task fast path not eligible');
|
|
1430
|
+
console.log(`- Profile: ${result.recommendedProfile}`);
|
|
1431
|
+
console.log(`- Files: ${result.changedPaths.length}, changed lines: ${result.changedLines}`);
|
|
1432
|
+
if (result.reasons.length) console.log(`- Reasons: ${result.reasons.join(', ')}`);
|
|
1433
|
+
}
|
|
1434
|
+
return;
|
|
1435
|
+
}
|
|
1436
|
+
if (stage === 'compact') {
|
|
1437
|
+
const result = compactRun(CWD, { runId });
|
|
1438
|
+
if (json) {
|
|
1439
|
+
console.log(JSON.stringify({ ok: true, runId: result.summary.runId, paths: result.paths, openFindings: result.summary.openFindings.length }));
|
|
1440
|
+
} else {
|
|
1441
|
+
log.success('✓ run context compacted');
|
|
1442
|
+
console.log(`- Summary: ${result.paths.markdown}`);
|
|
1443
|
+
console.log(`- Machine summary: ${result.paths.summary}`);
|
|
1444
|
+
console.log(`- Open findings: ${result.paths.openFindings}`);
|
|
1445
|
+
}
|
|
1446
|
+
return;
|
|
1447
|
+
}
|
|
1448
|
+
if (stage === 'diff-hunks' || stage === 'diff-pack') {
|
|
1449
|
+
const result = createDiffHunkPack(CWD, { runId, base, profile, includeIgnored });
|
|
1450
|
+
const summary = smartContextSummary(result);
|
|
1451
|
+
if (json) {
|
|
1452
|
+
console.log(JSON.stringify({ ok: true, ...summary }));
|
|
1453
|
+
} else {
|
|
1454
|
+
log.success('✓ smart diff hunk pack created');
|
|
1455
|
+
console.log(`- Path: ${summary.path}`);
|
|
1456
|
+
console.log(`- Review profile: ${summary.reviewProfile}`);
|
|
1457
|
+
console.log(`- Files: ${summary.files}, estimated tokens: ${summary.estimatedTokens}`);
|
|
1458
|
+
console.log(`- Unresolved findings: ${summary.unresolvedFindings}, truncated: ${summary.truncated}`);
|
|
1459
|
+
if (summary.ignoredPaths) console.log(`- Ignored by context policy: ${summary.ignoredPaths}`);
|
|
1460
|
+
}
|
|
1461
|
+
return;
|
|
1462
|
+
}
|
|
1463
|
+
const result = createContextPack(CWD, { runId, stage, files, profile });
|
|
1336
1464
|
const summary = contextPackSummary(result);
|
|
1337
1465
|
if (json) {
|
|
1338
1466
|
console.log(JSON.stringify({ ok: true, ...summary }));
|
|
1339
1467
|
} else {
|
|
1340
1468
|
log.success(`✓ ${stage} context pack created`);
|
|
1341
1469
|
console.log(`- Path: ${summary.path}`);
|
|
1470
|
+
console.log(`- Review profile: ${summary.reviewProfile}`);
|
|
1342
1471
|
console.log(`- Files: ${summary.files}, estimated tokens: ${summary.estimatedTokens}`);
|
|
1343
1472
|
console.log(`- Redactions: ${summary.redactions}, truncated files: ${summary.truncatedFiles}`);
|
|
1344
1473
|
}
|
|
@@ -1443,6 +1572,59 @@ function handleDoctor() {
|
|
|
1443
1572
|
if (!result.ok) process.exit(1);
|
|
1444
1573
|
}
|
|
1445
1574
|
|
|
1575
|
+
function printUpdatePlan(plan) {
|
|
1576
|
+
console.log(`Current: ${plan.currentVersion}`);
|
|
1577
|
+
console.log(`Latest: ${plan.latestVersion}`);
|
|
1578
|
+
console.log(`Install: ${plan.installScope}`);
|
|
1579
|
+
if (plan.updateAvailable) {
|
|
1580
|
+
console.log('\nUpdate available. Recommended commands:');
|
|
1581
|
+
} else {
|
|
1582
|
+
console.log('\nai-engineering-loop is up to date. Sync commands remain safe to run:');
|
|
1583
|
+
}
|
|
1584
|
+
for (const item of plan.commands) console.log(item.display);
|
|
1585
|
+
}
|
|
1586
|
+
|
|
1587
|
+
function handleUpdate() {
|
|
1588
|
+
const action = process.argv[3] || 'check';
|
|
1589
|
+
const json = process.argv.includes('--json');
|
|
1590
|
+
const yes = process.argv.includes('--yes');
|
|
1591
|
+
try {
|
|
1592
|
+
const plan = checkForUpdate(path.join(__dirname, '..'));
|
|
1593
|
+
if (action === 'check' || action === 'plan') {
|
|
1594
|
+
if (json) console.log(JSON.stringify({ ok: true, action, ...plan }));
|
|
1595
|
+
else printUpdatePlan(plan);
|
|
1596
|
+
return;
|
|
1597
|
+
}
|
|
1598
|
+
if (action === 'apply') {
|
|
1599
|
+
if (json && !yes) {
|
|
1600
|
+
throw new Error('update apply requires --yes; use update plan for a dry run');
|
|
1601
|
+
}
|
|
1602
|
+
if (!yes) {
|
|
1603
|
+
printUpdatePlan(plan);
|
|
1604
|
+
throw new Error('Refusing to update without explicit confirmation. Re-run with: ai-engineering-loop update apply --yes');
|
|
1605
|
+
}
|
|
1606
|
+
if (!plan.updateAvailable) {
|
|
1607
|
+
if (json) console.log(JSON.stringify({ ok: true, action, skipped: true, reason: 'UP_TO_DATE', ...plan }));
|
|
1608
|
+
else {
|
|
1609
|
+
console.log('ai-engineering-loop is already up to date.');
|
|
1610
|
+
printUpdatePlan(plan);
|
|
1611
|
+
}
|
|
1612
|
+
return;
|
|
1613
|
+
}
|
|
1614
|
+
if (!json) printUpdatePlan(plan);
|
|
1615
|
+
executeUpdatePlan(plan);
|
|
1616
|
+
if (json) console.log(JSON.stringify({ ok: true, action, applied: true, ...plan }));
|
|
1617
|
+
else log.success('✓ ai-engineering-loop updated and post-update sync completed');
|
|
1618
|
+
return;
|
|
1619
|
+
}
|
|
1620
|
+
throw new Error(`Unknown update action: ${action}`);
|
|
1621
|
+
} catch (err) {
|
|
1622
|
+
if (json) console.log(JSON.stringify({ ok: false, code: err.code || 'UPDATE_FAILED', error: err.message }));
|
|
1623
|
+
else log.error(err.message);
|
|
1624
|
+
process.exit(1);
|
|
1625
|
+
}
|
|
1626
|
+
}
|
|
1627
|
+
|
|
1446
1628
|
function handleRecipe() {
|
|
1447
1629
|
const action = process.argv[3] || 'list';
|
|
1448
1630
|
const id = process.argv[4];
|
|
@@ -1905,6 +2087,8 @@ Commands:
|
|
|
1905
2087
|
show [--run <id>]
|
|
1906
2088
|
draft --file <json> --revision <n> [--run <id>] [--by <agent>]
|
|
1907
2089
|
freeze --revision <n> --hash <sha256> [--run <id>] [--by <name>]
|
|
2090
|
+
verification Summarize verification.json for compact Judge context
|
|
2091
|
+
summarize [--run <id>] [--json]
|
|
1908
2092
|
activity Publish safe Run lifecycle summaries for Studio
|
|
1909
2093
|
goal-drafting | goal-ready | heartbeat | waiting
|
|
1910
2094
|
node-started | node-activity | node-completed | loop-iterated | run-completed
|
|
@@ -1925,6 +2109,7 @@ Commands:
|
|
|
1925
2109
|
show [--json]
|
|
1926
2110
|
set [--default-mode <mode>] [--allow-unattended true|false]
|
|
1927
2111
|
[--require-sandbox true|false]
|
|
2112
|
+
[--review-profile lean|standard|thorough]
|
|
1928
2113
|
[--per-run-token-limit <n>] [--daily-token-limit <n>]
|
|
1929
2114
|
budget Enforce actual provider-reported token usage and emergency pause
|
|
1930
2115
|
status [--run <id>] [--node <id>] [--estimate <n>] [--json]
|
|
@@ -1934,7 +2119,18 @@ Commands:
|
|
|
1934
2119
|
create | capture | abort | status [--run <id>] [--json]
|
|
1935
2120
|
context <stage> <files...>
|
|
1936
2121
|
Build a bounded, redacted context pack for maker, devil-advocate, or judge
|
|
2122
|
+
index [files...] build a private source summary index without file bodies
|
|
2123
|
+
query <term> search index paths and exported symbols without source bodies
|
|
2124
|
+
related <file> list nearby indexed files without reading source bodies
|
|
2125
|
+
diff-hunks build a hunk-only review pack with unresolved findings
|
|
2126
|
+
fast-path assess whether a small task can stay on lean review
|
|
2127
|
+
compact write run-summary.md/json and open-findings.json
|
|
1937
2128
|
--run <id> target a non-current run
|
|
2129
|
+
--profile lean|standard|thorough override runtime policy for one pack
|
|
2130
|
+
--base <git-ref> base ref for diff-hunks; default HEAD
|
|
2131
|
+
--query <term> query term for context query
|
|
2132
|
+
--limit <n> bound query/related result count
|
|
2133
|
+
--include-ignored include CSS, generated, lockfile, and .aelcontextignore paths
|
|
1938
2134
|
--json print only pack metadata; never print packed content
|
|
1939
2135
|
eval Validate the 20-case production evaluation catalog
|
|
1940
2136
|
--results <dir> score host-generated JSON results
|
|
@@ -1945,6 +2141,9 @@ Commands:
|
|
|
1945
2141
|
--json print machine-readable reasons
|
|
1946
2142
|
doctor Check runtime, schemas, host assets, package contents, and eval catalog
|
|
1947
2143
|
--json print machine-readable diagnostics
|
|
2144
|
+
update Check or apply the package update workflow
|
|
2145
|
+
check|plan [--json]
|
|
2146
|
+
apply --yes
|
|
1948
2147
|
recipe Inspect and compile declarative workflow recipes (does not execute nodes)
|
|
1949
2148
|
list [--json]
|
|
1950
2149
|
catalog [--json]
|
|
@@ -2020,6 +2219,9 @@ switch (command) {
|
|
|
2020
2219
|
case 'budget':
|
|
2021
2220
|
handleBudget();
|
|
2022
2221
|
break;
|
|
2222
|
+
case 'verification':
|
|
2223
|
+
handleVerification();
|
|
2224
|
+
break;
|
|
2023
2225
|
case 'sandbox':
|
|
2024
2226
|
handleSandbox();
|
|
2025
2227
|
break;
|
|
@@ -2035,6 +2237,9 @@ switch (command) {
|
|
|
2035
2237
|
case 'doctor':
|
|
2036
2238
|
handleDoctor();
|
|
2037
2239
|
break;
|
|
2240
|
+
case 'update':
|
|
2241
|
+
handleUpdate();
|
|
2242
|
+
break;
|
|
2038
2243
|
case 'recipe':
|
|
2039
2244
|
handleRecipe();
|
|
2040
2245
|
break;
|
package/core/runtime-safety.md
CHANGED
|
@@ -44,6 +44,49 @@ npx ai-engineering-loop budget resume
|
|
|
44
44
|
|
|
45
45
|
`pause` sets the persistent kill switch. It blocks new run and context/model boundaries, while `budget record` remains available so an in-flight response can still be accounted.
|
|
46
46
|
|
|
47
|
+
## Review profile
|
|
48
|
+
|
|
49
|
+
Context packs default to the `lean` review profile so paid conversational hosts do not exhaust tokens on repeated full-file review context. The profile changes context limits and reviewer output expectations only; it does not skip Goal Contract, verification, Devil's Advocate, Judge, or delivery gates.
|
|
50
|
+
|
|
51
|
+
```bash
|
|
52
|
+
npx ai-engineering-loop policy set --review-profile lean
|
|
53
|
+
npx ai-engineering-loop policy set --review-profile standard
|
|
54
|
+
npx ai-engineering-loop policy set --review-profile thorough
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
Use `lean` for normal Codex/GPT Plus-style sessions, `standard` when the diff is broad but still routine, and `thorough` only when the human explicitly opts into a deeper, more expensive review. A single context pack can override the policy without changing future runs:
|
|
58
|
+
|
|
59
|
+
```bash
|
|
60
|
+
npx ai-engineering-loop context devil-advocate --profile thorough <files...>
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
Prefer smart context before opening whole files:
|
|
64
|
+
|
|
65
|
+
```bash
|
|
66
|
+
npx ai-engineering-loop context index
|
|
67
|
+
npx ai-engineering-loop context query createStudioRun
|
|
68
|
+
npx ai-engineering-loop context related lib/studio-server.js
|
|
69
|
+
npx ai-engineering-loop context fast-path --json
|
|
70
|
+
npx ai-engineering-loop context diff-hunks --run <run-id>
|
|
71
|
+
npx ai-engineering-loop context diff-hunks --run <run-id> --include-ignored
|
|
72
|
+
npx ai-engineering-loop verification summarize --run <run-id>
|
|
73
|
+
npx ai-engineering-loop context compact --run <run-id>
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
The index stores file summaries and hashes, never file bodies, and reuses per-hash summaries when files are unchanged. `query` and `related` return metadata only so agents can choose the right files before reading source. `fast-path` keeps low-risk small diffs on lean review and names the reason when a task must use the standard path. The diff-hunk pack stores bounded changed hunks, file summaries, token estimates, unresolved blocking findings from the previous ledger, and a count of paths skipped by context policy. Smart context skips CSS, generated bundles, lockfiles, build output, and `.aelcontextignore` matches by default; pass `--include-ignored` only when those files are the task. The verification summary stores command outcomes, counts, and short failure excerpts without raw stdout. `context compact` writes `run-summary.md`, `run-summary.json`, and `open-findings.json` so iteration 2+ reviewers and Judge start from compact artifacts and request full source or logs only when the hunk or summary cannot prove or disprove a finding.
|
|
77
|
+
|
|
78
|
+
## Package update workflow
|
|
79
|
+
|
|
80
|
+
Agents may check for package updates, but must not update the user's global or project installation without explicit instruction. Use:
|
|
81
|
+
|
|
82
|
+
```bash
|
|
83
|
+
ai-engineering-loop update check
|
|
84
|
+
ai-engineering-loop update plan
|
|
85
|
+
ai-engineering-loop update apply --yes
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
`update plan` prints the exact install, `sync-hosts`, `refresh`, and `doctor` commands for the detected install scope. `update apply --yes` runs those commands explicitly; the separate `--yes` flag is the confirmation boundary.
|
|
89
|
+
|
|
47
90
|
## Unattended Maker isolation
|
|
48
91
|
|
|
49
92
|
After `gate goal`, create the worktree:
|
package/lib/budget.js
CHANGED
|
@@ -110,6 +110,29 @@ function resolveRun(rootDir, runId) {
|
|
|
110
110
|
return current;
|
|
111
111
|
}
|
|
112
112
|
|
|
113
|
+
function pressureRatio(used, limit) {
|
|
114
|
+
if (!Number.isFinite(limit) || limit <= 0) return 0;
|
|
115
|
+
return used / limit;
|
|
116
|
+
}
|
|
117
|
+
|
|
118
|
+
function budgetWarnings({ runPressure, dayPressure, reviewProfile }) {
|
|
119
|
+
const warnings = [];
|
|
120
|
+
if (runPressure >= 0.9) warnings.push(`run token usage is at ${Math.round(runPressure * 100)}%; finish or compact context before another model call`);
|
|
121
|
+
else if (runPressure >= 0.75) warnings.push(`run token usage is at ${Math.round(runPressure * 100)}%; use unresolved findings and changed hunks only`);
|
|
122
|
+
else if (runPressure >= 0.5) warnings.push(`run token usage is at ${Math.round(runPressure * 100)}%; avoid full logs and repeated source dumps`);
|
|
123
|
+
|
|
124
|
+
if (dayPressure >= 0.9) warnings.push(`daily token usage is at ${Math.round(dayPressure * 100)}%; pause non-critical reviews`);
|
|
125
|
+
else if (dayPressure >= 0.75) warnings.push(`daily token usage is at ${Math.round(dayPressure * 100)}%; prefer lean review context`);
|
|
126
|
+
|
|
127
|
+
if (reviewProfile === 'lean' && (runPressure >= 0.75 || dayPressure >= 0.75)) {
|
|
128
|
+
warnings.push('lean review profile is active; keep DA/Judge to focused deltas unless a blocker requires escalation');
|
|
129
|
+
}
|
|
130
|
+
if (reviewProfile === 'thorough') {
|
|
131
|
+
warnings.push('thorough review profile increases context size; use only when the human explicitly accepts the token cost');
|
|
132
|
+
}
|
|
133
|
+
return [...new Set(warnings)];
|
|
134
|
+
}
|
|
135
|
+
|
|
113
136
|
function budgetStatus(rootDir, { runId, nodeId, estimatedTokens = 0, now = new Date() } = {}) {
|
|
114
137
|
validateTokenCount('estimatedTokens', estimatedTokens);
|
|
115
138
|
const run = resolveRun(rootDir, runId);
|
|
@@ -156,6 +179,15 @@ function budgetStatus(rootDir, { runId, nodeId, estimatedTokens = 0, now = new D
|
|
|
156
179
|
if (estimatedTokens === 0 && spentToday >= policy.dailyTokenLimit) {
|
|
157
180
|
reasons.push('daily token limit is exhausted');
|
|
158
181
|
}
|
|
182
|
+
const pressure = {
|
|
183
|
+
run: pressureRatio(projectedThisRun, policy.perRunTokenLimit),
|
|
184
|
+
day: pressureRatio(projectedToday, policy.dailyTokenLimit)
|
|
185
|
+
};
|
|
186
|
+
const warnings = budgetWarnings({
|
|
187
|
+
runPressure: pressure.run,
|
|
188
|
+
dayPressure: pressure.day,
|
|
189
|
+
reviewProfile: policy.reviewProfile
|
|
190
|
+
});
|
|
159
191
|
|
|
160
192
|
return {
|
|
161
193
|
schemaVersion: 1,
|
|
@@ -163,7 +195,9 @@ function budgetStatus(rootDir, { runId, nodeId, estimatedTokens = 0, now = new D
|
|
|
163
195
|
day: utcDay(now),
|
|
164
196
|
allowed: reasons.length === 0,
|
|
165
197
|
reasons: [...new Set(reasons)],
|
|
198
|
+
warnings,
|
|
166
199
|
killSwitch: policy.killSwitch,
|
|
200
|
+
reviewProfile: policy.reviewProfile,
|
|
167
201
|
spentThisRun,
|
|
168
202
|
perRunTokenLimit: policy.perRunTokenLimit,
|
|
169
203
|
remainingThisRun: Math.max(0, policy.perRunTokenLimit - spentThisRun),
|
|
@@ -171,6 +205,7 @@ function budgetStatus(rootDir, { runId, nodeId, estimatedTokens = 0, now = new D
|
|
|
171
205
|
dailyTokenLimit: policy.dailyTokenLimit,
|
|
172
206
|
remainingToday: Math.max(0, policy.dailyTokenLimit - spentToday),
|
|
173
207
|
estimatedTokens,
|
|
208
|
+
pressure,
|
|
174
209
|
...(node ? {
|
|
175
210
|
nodeId,
|
|
176
211
|
spentThisNode,
|
package/lib/doctor.js
CHANGED
|
@@ -8,13 +8,17 @@ const { listRecipes, loadRecipe, validateRecipe } = require('./recipe.js');
|
|
|
8
8
|
|
|
9
9
|
const REQUIRED_HOST_ASSETS = [
|
|
10
10
|
'.claude/skills/ai-engineering-loop/SKILL.md',
|
|
11
|
+
'.claude/skills/backend-development/SKILL.md',
|
|
11
12
|
'.claude/agents/devil-advocate.md',
|
|
12
13
|
'.claude/agents/judge.md',
|
|
13
14
|
'.grok/skills/ai-engineering-loop/SKILL.md',
|
|
15
|
+
'.grok/skills/backend-development/SKILL.md',
|
|
14
16
|
'.grok/agents/devil-advocate.md',
|
|
15
17
|
'.grok/agents/judge.md',
|
|
16
18
|
'.gemini/skills/ai-engineering-loop/SKILL.md',
|
|
19
|
+
'.gemini/skills/backend-development/SKILL.md',
|
|
17
20
|
'.agents/workflows/ai-engineering-loop.md',
|
|
21
|
+
'.agents/skills/backend-development/SKILL.md',
|
|
18
22
|
'.agents/devil-advocate.md',
|
|
19
23
|
'.agents/judge.md'
|
|
20
24
|
];
|
|
@@ -0,0 +1,170 @@
|
|
|
1
|
+
'use strict';
|
|
2
|
+
|
|
3
|
+
const fs = require('fs');
|
|
4
|
+
const path = require('path');
|
|
5
|
+
const { atomicWriteJson, atomicWritePrivateFile, getCurrentRun, loadRun, runsDir } = require('./run-state.js');
|
|
6
|
+
const { writeVerificationSummary } = require('./verification-summary.js');
|
|
7
|
+
const { loadPolicy } = require('./runtime-policy.js');
|
|
8
|
+
|
|
9
|
+
function compactionError(message, code = 'RUN_COMPACTION_ERROR') {
|
|
10
|
+
const err = new Error(message);
|
|
11
|
+
err.code = code;
|
|
12
|
+
return err;
|
|
13
|
+
}
|
|
14
|
+
|
|
15
|
+
function resolveRun(rootDir, runId) {
|
|
16
|
+
if (runId) return loadRun(rootDir, runId);
|
|
17
|
+
const current = getCurrentRun(rootDir);
|
|
18
|
+
if (!current) throw compactionError('No current run. Pass --run <id>.', 'NO_CURRENT_RUN');
|
|
19
|
+
return current;
|
|
20
|
+
}
|
|
21
|
+
|
|
22
|
+
function readOptionalJson(filePath) {
|
|
23
|
+
if (!fs.existsSync(filePath)) return null;
|
|
24
|
+
try {
|
|
25
|
+
return JSON.parse(fs.readFileSync(filePath, 'utf8'));
|
|
26
|
+
} catch {
|
|
27
|
+
return null;
|
|
28
|
+
}
|
|
29
|
+
}
|
|
30
|
+
|
|
31
|
+
function firstPresent(...values) {
|
|
32
|
+
return values.find((value) => value != null && value !== '') ?? null;
|
|
33
|
+
}
|
|
34
|
+
|
|
35
|
+
function compactGoal(goal) {
|
|
36
|
+
if (!goal) return null;
|
|
37
|
+
const criteria = goal.acceptanceCriteria || goal.criteria || [];
|
|
38
|
+
return {
|
|
39
|
+
objective: firstPresent(goal.objective, goal.goal, goal.summary),
|
|
40
|
+
revision: goal.revision || goal.draftRevision || null,
|
|
41
|
+
hash: goal.hash || goal.sha256 || null,
|
|
42
|
+
acceptanceCriteria: criteria.map((criterion) => ({
|
|
43
|
+
id: criterion.id,
|
|
44
|
+
statement: criterion.statement || criterion.description || '',
|
|
45
|
+
failureCases: (criterion.failureCases || []).slice(0, 3)
|
|
46
|
+
}))
|
|
47
|
+
};
|
|
48
|
+
}
|
|
49
|
+
|
|
50
|
+
function compactFindings(findingsDocument) {
|
|
51
|
+
const findings = findingsDocument?.findings || [];
|
|
52
|
+
return findings
|
|
53
|
+
.filter((finding) => finding.validity === 'VALID')
|
|
54
|
+
.filter((finding) => !['ACCEPTABLE', 'DISMISSED', 'FIXED', 'RESOLVED'].includes(String(finding.disposition || '').toUpperCase()))
|
|
55
|
+
.map((finding) => ({
|
|
56
|
+
id: finding.id,
|
|
57
|
+
axis: finding.axis,
|
|
58
|
+
severity: finding.severity,
|
|
59
|
+
disposition: finding.disposition,
|
|
60
|
+
location: finding.location,
|
|
61
|
+
title: finding.title || finding.topic || null
|
|
62
|
+
}));
|
|
63
|
+
}
|
|
64
|
+
|
|
65
|
+
function markdownSummary(document) {
|
|
66
|
+
const goalLines = document.goal
|
|
67
|
+
? [
|
|
68
|
+
`- Objective: ${document.goal.objective || 'Not recorded'}`,
|
|
69
|
+
`- Acceptance criteria: ${document.goal.acceptanceCriteria.length}`,
|
|
70
|
+
`- Goal revision: ${document.goal.revision || 'n/a'}`,
|
|
71
|
+
`- Goal hash: ${document.goal.hash || 'n/a'}`
|
|
72
|
+
]
|
|
73
|
+
: ['- Goal: not recorded'];
|
|
74
|
+
const verification = document.verification
|
|
75
|
+
? [
|
|
76
|
+
`- Passed: ${document.verification.passed}`,
|
|
77
|
+
`- Exit code: ${document.verification.exitCode}`,
|
|
78
|
+
`- Commands: ${document.verification.commandCount}`,
|
|
79
|
+
`- Tests: ${JSON.stringify(document.verification.testCounts)}`
|
|
80
|
+
]
|
|
81
|
+
: ['- Verification: not summarized'];
|
|
82
|
+
const findings = document.openFindings.length
|
|
83
|
+
? document.openFindings.map((finding) => `- ${finding.id} ${finding.severity || ''} ${finding.axis || ''}: ${finding.title || finding.location || 'open'}`)
|
|
84
|
+
: ['- No open VALID non-accepted findings recorded'];
|
|
85
|
+
return [
|
|
86
|
+
`# Run Summary: ${document.runId}`,
|
|
87
|
+
'',
|
|
88
|
+
`Generated: ${document.generatedAt}`,
|
|
89
|
+
'',
|
|
90
|
+
'## State',
|
|
91
|
+
'',
|
|
92
|
+
`- State: ${document.state}`,
|
|
93
|
+
`- Mode: ${document.mode || 'n/a'}`,
|
|
94
|
+
`- Iteration: ${document.iteration}`,
|
|
95
|
+
`- Review profile: ${document.reviewProfile || 'n/a'}`,
|
|
96
|
+
'',
|
|
97
|
+
'## Goal',
|
|
98
|
+
'',
|
|
99
|
+
...goalLines,
|
|
100
|
+
'',
|
|
101
|
+
'## Verification',
|
|
102
|
+
'',
|
|
103
|
+
...verification,
|
|
104
|
+
'',
|
|
105
|
+
'## Open findings',
|
|
106
|
+
'',
|
|
107
|
+
...findings,
|
|
108
|
+
'',
|
|
109
|
+
'## Reviewer read order',
|
|
110
|
+
'',
|
|
111
|
+
'1. This summary',
|
|
112
|
+
'2. verification-summary.json',
|
|
113
|
+
'3. open-findings.json',
|
|
114
|
+
'4. context/diff-hunks.json',
|
|
115
|
+
'5. Full artifacts only when the summaries contradict each other'
|
|
116
|
+
].join('\n');
|
|
117
|
+
}
|
|
118
|
+
|
|
119
|
+
function compactRun(rootDir, { runId } = {}) {
|
|
120
|
+
const run = resolveRun(rootDir, runId);
|
|
121
|
+
const runDir = path.join(runsDir(rootDir), run.runId);
|
|
122
|
+
const goal = readOptionalJson(path.join(runDir, 'goal-contract.json'));
|
|
123
|
+
let verification = readOptionalJson(path.join(runDir, 'verification-summary.json'));
|
|
124
|
+
if (!verification && fs.existsSync(path.join(runDir, 'verification.json'))) {
|
|
125
|
+
verification = writeVerificationSummary(rootDir, { runId: run.runId }).summary;
|
|
126
|
+
}
|
|
127
|
+
const findingsDocument = readOptionalJson(path.join(runDir, 'findings.json'));
|
|
128
|
+
const openFindings = compactFindings(findingsDocument);
|
|
129
|
+
const summary = {
|
|
130
|
+
schemaVersion: 1,
|
|
131
|
+
runId: run.runId,
|
|
132
|
+
generatedAt: new Date().toISOString(),
|
|
133
|
+
state: run.state,
|
|
134
|
+
mode: run.mode || null,
|
|
135
|
+
iteration: run.iteration || 1,
|
|
136
|
+
reviewProfile: loadPolicy(rootDir).reviewProfile,
|
|
137
|
+
goal: compactGoal(goal),
|
|
138
|
+
verification: verification ? {
|
|
139
|
+
passed: verification.passed,
|
|
140
|
+
exitCode: verification.exitCode,
|
|
141
|
+
commandCount: verification.commandCount,
|
|
142
|
+
testCounts: verification.testCounts,
|
|
143
|
+
diffHash: verification.diffHash || null
|
|
144
|
+
} : null,
|
|
145
|
+
openFindings
|
|
146
|
+
};
|
|
147
|
+
const summaryPath = path.join(runDir, 'run-summary.json');
|
|
148
|
+
const markdownPath = path.join(runDir, 'run-summary.md');
|
|
149
|
+
const findingsPath = path.join(runDir, 'open-findings.json');
|
|
150
|
+
atomicWriteJson(summaryPath, summary);
|
|
151
|
+
atomicWritePrivateFile(markdownPath, `${markdownSummary(summary)}\n`);
|
|
152
|
+
atomicWriteJson(findingsPath, {
|
|
153
|
+
schemaVersion: 1,
|
|
154
|
+
runId: run.runId,
|
|
155
|
+
generatedAt: summary.generatedAt,
|
|
156
|
+
findings: openFindings
|
|
157
|
+
});
|
|
158
|
+
return {
|
|
159
|
+
summary,
|
|
160
|
+
paths: {
|
|
161
|
+
summary: path.relative(rootDir, summaryPath).split(path.sep).join('/'),
|
|
162
|
+
markdown: path.relative(rootDir, markdownPath).split(path.sep).join('/'),
|
|
163
|
+
openFindings: path.relative(rootDir, findingsPath).split(path.sep).join('/')
|
|
164
|
+
}
|
|
165
|
+
};
|
|
166
|
+
}
|
|
167
|
+
|
|
168
|
+
module.exports = {
|
|
169
|
+
compactRun
|
|
170
|
+
};
|