ai-engineering-loop 2.1.0 → 2.3.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 (108) hide show
  1. package/.agents/skills/ai-engineering-loop/SKILL.md +4 -4
  2. package/.agents/skills/ai-engineering-loop/references/loop-deliver.md +2 -2
  3. package/.agents/skills/ai-engineering-loop/references/loop-goal.md +3 -3
  4. package/.agents/skills/ai-engineering-loop/references/loop-maker.md +1 -0
  5. package/.agents/skills/ai-engineering-loop/references/loop-review.md +3 -4
  6. package/.agents/skills/ai-engineering-loop/references/loop-verify.md +3 -3
  7. package/.claude/agents/judge.md +5 -2
  8. package/.grok/agents/judge.md +5 -2
  9. package/CHANGELOG.md +46 -0
  10. package/agents/maker.md +1 -1
  11. package/agents/shared/judge.body.md +5 -2
  12. package/bin/ai-engineering-loop.js +303 -77
  13. package/core/definition-of-done.md +2 -2
  14. package/core/escalation-policy.md +1 -1
  15. package/core/goal-contract.md +1 -1
  16. package/core/iteration-policy.md +2 -1
  17. package/core/judge-policy.md +10 -4
  18. package/core/local-workflow-studio.md +12 -7
  19. package/core/orchestration-model.md +8 -7
  20. package/core/repo-config-schema.md +2 -2
  21. package/core/runtime-safety.md +3 -3
  22. package/lib/auto-update.js +8 -14
  23. package/lib/claimed-vs-reality.js +2 -2
  24. package/lib/cli-args.js +3 -1
  25. package/lib/docs.js +1 -1
  26. package/lib/doctor.js +0 -6
  27. package/lib/escalation.js +1 -1
  28. package/lib/fsutil.js +88 -0
  29. package/lib/gates.js +69 -27
  30. package/lib/generate-workflow.js +0 -29
  31. package/lib/goal-runtime.js +3 -2
  32. package/lib/guard-hooks.js +26 -7
  33. package/lib/guard.js +100 -10
  34. package/lib/hosts/doctor.js +1 -5
  35. package/lib/impact-map.js +4 -9
  36. package/lib/jsonl-ledger.js +104 -0
  37. package/lib/learn.js +4 -9
  38. package/lib/loop-groups.js +0 -25
  39. package/lib/migrations.js +1 -5
  40. package/lib/no-progress.js +119 -0
  41. package/lib/node-evidence.js +873 -0
  42. package/lib/orchestration.js +5 -361
  43. package/lib/personal-workflow.js +1 -1
  44. package/lib/quick.js +152 -0
  45. package/lib/receipt.js +1 -5
  46. package/lib/recipe-builder.js +3 -35
  47. package/lib/recipe-graph.js +2 -63
  48. package/lib/recipe.js +2 -4
  49. package/lib/review-ingest.js +116 -0
  50. package/lib/run-abandon.js +2 -1
  51. package/lib/run-checkout.js +8 -13
  52. package/lib/run-compaction.js +4 -12
  53. package/lib/run-interactions.js +16 -71
  54. package/lib/run-lifecycle.js +25 -77
  55. package/lib/run-state.js +68 -17
  56. package/lib/run-watcher.js +11 -14
  57. package/lib/runtime-files.js +45 -1
  58. package/lib/safe-context.js +17 -6
  59. package/lib/sandbox.js +2 -1
  60. package/lib/smart-context.js +3 -13
  61. package/lib/spawn-command.js +94 -0
  62. package/lib/studio-layout.js +2 -8
  63. package/lib/studio-runtime.js +2 -1
  64. package/lib/studio-server.js +25 -5
  65. package/lib/tier.js +36 -10
  66. package/lib/user-state.js +2 -17
  67. package/lib/verification-lanes.js +115 -0
  68. package/lib/verification-recorder.js +110 -22
  69. package/lib/workflow-runtime.js +7 -4
  70. package/package.json +1 -2
  71. package/policies/review-budget.md +1 -1
  72. package/studio/app.js +734 -132
  73. package/studio/index.html +13 -4
  74. package/studio/styles.css +75 -20
  75. package/.claude/skills/ai-engineering-loop/SKILL.md +0 -62
  76. package/.claude/skills/ai-engineering-loop/references/loop-commands.md +0 -24
  77. package/.claude/skills/ai-engineering-loop/references/loop-deliver.md +0 -10
  78. package/.claude/skills/ai-engineering-loop/references/loop-goal.md +0 -11
  79. package/.claude/skills/ai-engineering-loop/references/loop-hosts.md +0 -48
  80. package/.claude/skills/ai-engineering-loop/references/loop-maker.md +0 -14
  81. package/.claude/skills/ai-engineering-loop/references/loop-review.md +0 -20
  82. package/.claude/skills/ai-engineering-loop/references/loop-risky.md +0 -9
  83. package/.claude/skills/ai-engineering-loop/references/loop-verify.md +0 -20
  84. package/.claude/skills/animate/RECIPES.md +0 -324
  85. package/.claude/skills/animate/SKILL.md +0 -207
  86. package/.claude/skills/animate-expo/RECIPES.md +0 -385
  87. package/.claude/skills/animate-expo/SKILL.md +0 -263
  88. package/.claude/skills/animation-vocabulary/SKILL.md +0 -181
  89. package/.claude/skills/apple-design/SKILL.md +0 -290
  90. package/.claude/skills/ask-sonner/API.md +0 -64
  91. package/.claude/skills/ask-sonner/SKILL.md +0 -88
  92. package/.claude/skills/backend-development/SKILL.md +0 -272
  93. package/.claude/skills/backend-development/references/api-design-guidelines.md +0 -95
  94. package/.claude/skills/backend-development/references/query-and-database-best-practices.md +0 -53
  95. package/.claude/skills/backend-development/references/security-checklist.md +0 -60
  96. package/.claude/skills/emil-design-eng/SKILL.md +0 -674
  97. package/.claude/skills/find-animation-opportunities/SKILL.md +0 -140
  98. package/.claude/skills/improve-animations/AUDIT.md +0 -115
  99. package/.claude/skills/improve-animations/PLAN-TEMPLATE.md +0 -73
  100. package/.claude/skills/improve-animations/SKILL.md +0 -109
  101. package/.claude/skills/mobile-native/SKILL.md +0 -311
  102. package/.claude/skills/pick-ui-library/SKILL.md +0 -85
  103. package/.claude/skills/prototype/PICKER.md +0 -197
  104. package/.claude/skills/prototype/SKILL.md +0 -98
  105. package/.claude/skills/review-animations/SKILL.md +0 -120
  106. package/.claude/skills/review-animations/STANDARDS.md +0 -187
  107. package/.claude/skills/write-swift/SKILL.md +0 -396
  108. package/lib/intern-catalog.js +0 -53
@@ -13,8 +13,22 @@
13
13
  const fs = require('fs');
14
14
  const os = require('os');
15
15
  const path = require('path');
16
- const crypto = require('crypto');
16
+ const { readJsonOptional, sha256: sha256Text } = require('../lib/fsutil.js');
17
17
  const { execSync, spawn } = require('child_process');
18
+
19
+ // Command modules load on first use, so a hot path such as
20
+ // `guard check --hook` (run before every tool call) loads only what it
21
+ // touches. lazyModule: a namespace that requires the file on first property
22
+ // read. lazyFunctions: destructure functions now, require the file on first
23
+ // call. Modules whose constants are read at load time stay eager.
24
+ function lazyModule(file) {
25
+ let mod;
26
+ return new Proxy({}, { get: (_, key) => (mod ||= require(file))[key] });
27
+ }
28
+
29
+ function lazyFunctions(file) {
30
+ return new Proxy({}, { get: (_, key) => (...params) => require(file)[key](...params) });
31
+ }
18
32
  const {
19
33
  homeDir,
20
34
  applyHostSync,
@@ -22,9 +36,9 @@ const {
22
36
  resolveHostSelection,
23
37
  planHostSync,
24
38
  formatHostSyncReport
25
- } = require('../lib/sync-hosts.js');
26
- const hostCommands = require('../lib/hosts/commands.js');
27
- const { listDocs, readDoc } = require('../lib/docs.js');
39
+ } = lazyFunctions('../lib/sync-hosts.js');
40
+ const hostCommands = lazyModule('../lib/hosts/commands.js');
41
+ const { listDocs, readDoc } = lazyFunctions('../lib/docs.js');
28
42
  const {
29
43
  wantsCommandHelp,
30
44
  unknownWriterArgs,
@@ -36,16 +50,16 @@ const {
36
50
  writeShippedAdapter,
37
51
  formatGenerateAdapterReport,
38
52
  parseTypeArg
39
- } = require('../lib/generate-adapter.js');
40
- const { detectAdapter } = require('../lib/adapter-detect.js');
41
- const { checkAdapter } = require('../lib/adapter-check.js');
53
+ } = lazyFunctions('../lib/generate-adapter.js');
54
+ const { detectAdapter } = lazyFunctions('../lib/adapter-detect.js');
55
+ const { checkAdapter } = lazyFunctions('../lib/adapter-check.js');
42
56
  const {
43
57
  writeWorkflowOverlay,
44
58
  formatGenerateWorkflowReport,
45
59
  parseWriteArg,
46
60
  workflowMarkdown,
47
61
  lessonsMarkdown
48
- } = require('../lib/generate-workflow.js');
62
+ } = lazyFunctions('../lib/generate-workflow.js');
49
63
  const {
50
64
  RUN_MODES,
51
65
  TERMINAL_STATES,
@@ -66,23 +80,23 @@ const {
66
80
  const {
67
81
  applyGate,
68
82
  judgeRequirement
69
- } = require('../lib/gates.js');
70
- const { initialTierState } = require('../lib/tier.js');
71
- const impactMap = require('../lib/impact-map.js');
72
- const guard = require('../lib/guard.js');
73
- const guardHooks = require('../lib/guard-hooks.js');
74
- const receipts = require('../lib/receipt.js');
75
- const { learn } = require('../lib/learn.js');
83
+ } = lazyFunctions('../lib/gates.js');
84
+ const { initialTierState } = lazyFunctions('../lib/tier.js');
85
+ const impactMap = lazyModule('../lib/impact-map.js');
86
+ const guard = lazyModule('../lib/guard.js');
87
+ const guardHooks = lazyModule('../lib/guard-hooks.js');
88
+ const receipts = lazyModule('../lib/receipt.js');
89
+ const { learn } = lazyFunctions('../lib/learn.js');
76
90
  const {
77
91
  runBench,
78
92
  compareBenches,
79
93
  formatCompare,
80
94
  parseBenchTimeoutSeconds
81
- } = require('../lib/bench.js');
95
+ } = lazyFunctions('../lib/bench.js');
82
96
  const {
83
97
  createContextPack,
84
98
  contextPackSummary
85
- } = require('../lib/safe-context.js');
99
+ } = lazyFunctions('../lib/safe-context.js');
86
100
  const {
87
101
  assessSmallTaskFastPath,
88
102
  buildContextIndex,
@@ -90,51 +104,51 @@ const {
90
104
  queryContextIndex,
91
105
  relatedContextIndex,
92
106
  smartContextSummary
93
- } = require('../lib/smart-context.js');
107
+ } = lazyFunctions('../lib/smart-context.js');
94
108
  const {
95
109
  compactRun
96
- } = require('../lib/run-compaction.js');
110
+ } = lazyFunctions('../lib/run-compaction.js');
97
111
  const {
98
112
  defaultCasesDir,
99
113
  loadEvaluationCases,
100
114
  loadResults,
101
115
  scoreEvaluationResults,
102
116
  catalogSummary
103
- } = require('../lib/evaluation.js');
117
+ } = lazyFunctions('../lib/evaluation.js');
104
118
  const {
105
119
  assessRunEscalation
106
- } = require('../lib/escalation.js');
120
+ } = lazyFunctions('../lib/escalation.js');
107
121
  const {
108
122
  writeVerificationSummary
109
- } = require('../lib/verification-summary.js');
123
+ } = lazyFunctions('../lib/verification-summary.js');
110
124
  const {
111
125
  recordVerificationCommands,
112
126
  recordVerificationCommand
113
- } = require('../lib/verification-recorder.js');
127
+ } = lazyFunctions('../lib/verification-recorder.js');
114
128
  const {
115
129
  scaffoldArtifact,
116
130
  validateArtifactFile
117
- } = require('../lib/agent-artifacts.js');
131
+ } = lazyFunctions('../lib/agent-artifacts.js');
118
132
  const {
119
133
  createClaimedVsRealityTemplate
120
- } = require('../lib/claimed-vs-reality.js');
134
+ } = lazyFunctions('../lib/claimed-vs-reality.js');
121
135
  const {
122
136
  runDoctor
123
- } = require('../lib/doctor.js');
137
+ } = lazyFunctions('../lib/doctor.js');
124
138
  const {
125
139
  checkForUpdate,
126
140
  detectInstallScope,
127
141
  executeUpdatePlan
128
- } = require('../lib/update-manager.js');
129
- const autoUpdate = require('../lib/auto-update.js');
130
- const projectRegistry = require('../lib/project-registry.js');
142
+ } = lazyFunctions('../lib/update-manager.js');
143
+ const autoUpdate = lazyModule('../lib/auto-update.js');
144
+ const projectRegistry = lazyModule('../lib/project-registry.js');
131
145
  const {
132
146
  assertBudgetAvailable,
133
147
  budgetStatus,
134
148
  recordTokenUsage,
135
149
  recordUsageUnavailable,
136
150
  setKillSwitch
137
- } = require('../lib/budget.js');
151
+ } = lazyFunctions('../lib/budget.js');
138
152
  const {
139
153
  PRIVATE_RUNTIME_GITIGNORE
140
154
  } = require('../lib/runtime-files.js');
@@ -142,23 +156,23 @@ const {
142
156
  appendRunAnswer,
143
157
  appendRunQuestion,
144
158
  listRunInteractions
145
- } = require('../lib/run-interactions.js');
159
+ } = lazyFunctions('../lib/run-interactions.js');
146
160
  const {
147
161
  appendRunLifecycle,
148
162
  listRunLifecycle,
149
163
  runAgentPresence
150
- } = require('../lib/run-lifecycle.js');
164
+ } = lazyFunctions('../lib/run-lifecycle.js');
151
165
  const {
152
166
  freezeGoal,
153
167
  loadGoalDraft,
154
168
  saveGoalDraft
155
- } = require('../lib/goal-runtime.js');
169
+ } = lazyFunctions('../lib/goal-runtime.js');
156
170
  const {
157
171
  abortSandbox,
158
172
  captureSandbox,
159
173
  createSandbox,
160
174
  sandboxStatus
161
- } = require('../lib/sandbox.js');
175
+ } = lazyFunctions('../lib/sandbox.js');
162
176
  const {
163
177
  compileRecipe,
164
178
  explainPlan,
@@ -167,7 +181,7 @@ const {
167
181
  mermaidPlan,
168
182
  simulatePlan,
169
183
  validateRecipe
170
- } = require('../lib/recipe.js');
184
+ } = lazyFunctions('../lib/recipe.js');
171
185
  const {
172
186
  applyWorkflowGate,
173
187
  approveWorkflowNode,
@@ -178,21 +192,21 @@ const {
178
192
  retryWorkflowNode,
179
193
  startWorkflowNode,
180
194
  workflowStatus
181
- } = require('../lib/workflow-runtime.js');
195
+ } = lazyFunctions('../lib/workflow-runtime.js');
182
196
  const {
183
197
  cloneRecipe,
184
198
  diffRecipes,
185
199
  inspectRecipe,
186
200
  installRecipe,
187
201
  recipeCatalog
188
- } = require('../lib/recipe-builder.js');
202
+ } = lazyFunctions('../lib/recipe-builder.js');
189
203
  const {
190
204
  createHandoff,
191
205
  handoffBrief,
192
206
  readHandoff,
193
207
  verifyHandoff
194
- } = require('../lib/handoff.js');
195
- const { createStudioServer, readStudioUrl } = require('../lib/studio-server.js');
208
+ } = lazyFunctions('../lib/handoff.js');
209
+ const { createStudioServer, readStudioUrl } = lazyFunctions('../lib/studio-server.js');
196
210
 
197
211
  const VERSION = require('../package.json').version;
198
212
  const CWD = process.cwd();
@@ -215,19 +229,15 @@ const REQUIRED_FILES = [
215
229
  // .ael-generated.json) or is package-owned; otherwise the new template goes to
216
230
  // `<file>.ael-new` and the user's file is left alone.
217
231
  // Legacy projects (no .ael-generated.json yet, decision 5 on #37): the first
218
- // such refresh overwrites AEL-managed files directly and deletes obsolete
219
- // AEL-managed files, after copying the old content into a snapshot under
220
- // .ai-engineering-loop/.ael-backup/<timestamp>/. Hashes are recorded so later
221
- // refreshes use the normal flow. Only paths this writer generates (or lists in
222
- // OBSOLETE_CONTEXT_FILES) are touched; files written with overwrite:false
232
+ // such refresh overwrites AEL-managed files directly, after copying the old
233
+ // content into a snapshot under .ai-engineering-loop/.ael-backup/<timestamp>/.
234
+ // Hashes are recorded so later refreshes use the normal flow. Only paths this
235
+ // writer generates are touched; files written with overwrite:false
223
236
  // (lessons, glossary, ...) and every other user file are left alone.
224
237
  let CONTEXT_WRITE_SAFE = false;
225
238
  let CONTEXT_WRITE_LEGACY = null; // { root, snapshotDir } during a legacy refresh
226
239
  const CONTEXT_WRITE_REPORT = { updated: [], aelNew: [], kept: [], seen: new Set(), snapshot: [], removed: [], obsoleteKept: [] };
227
240
  const PACKAGE_OWNED_CONTEXT = new Set(['metadata.json']);
228
- // Context files older AEL versions generated and this one no longer does
229
- // (relative to .ai-engineering-loop/). Deleted on the first legacy refresh.
230
- const OBSOLETE_CONTEXT_FILES = Object.freeze([]);
231
241
  const GENERATED_HASHES_FILE = '.ael-generated.json';
232
242
 
233
243
  function generatedHashesPath(filePath) {
@@ -235,11 +245,7 @@ function generatedHashesPath(filePath) {
235
245
  }
236
246
 
237
247
  function readGeneratedHashes(filePath) {
238
- try {
239
- return JSON.parse(fs.readFileSync(generatedHashesPath(filePath), 'utf8'));
240
- } catch {
241
- return {};
242
- }
248
+ return readJsonOptional(generatedHashesPath(filePath), {});
243
249
  }
244
250
 
245
251
  function writeGeneratedHashes(filePath, hashes) {
@@ -252,14 +258,10 @@ function writeGeneratedHashes(filePath, hashes) {
252
258
 
253
259
  function recordGeneratedHash(filePath, content) {
254
260
  const hashes = readGeneratedHashes(filePath);
255
- hashes[path.basename(filePath)] = require('crypto').createHash('sha256').update(content).digest('hex');
261
+ hashes[path.basename(filePath)] = sha256Text(content);
256
262
  writeGeneratedHashes(filePath, hashes);
257
263
  }
258
264
 
259
- function sha256Text(content) {
260
- return require('crypto').createHash('sha256').update(content).digest('hex');
261
- }
262
-
263
265
  function snapshotContextFile(filePath) {
264
266
  if (!CONTEXT_WRITE_LEGACY || !fs.existsSync(filePath)) return;
265
267
  const rel = path.relative(CONTEXT_WRITE_LEGACY.root, filePath);
@@ -300,8 +302,8 @@ function writeContextFile(filePath, content, { overwrite = true } = {}) {
300
302
 
301
303
  // After a non-destructive refresh: remove AEL-managed files this version no
302
304
  // longer generates. Normal flow: only files whose recorded hash still matches
303
- // (edited ones are reported and kept). Legacy flow: OBSOLETE_CONTEXT_FILES,
304
- // snapshotted first.
305
+ // (edited ones are reported and kept); removed files are snapshotted first
306
+ // during a legacy refresh.
305
307
  function removeObsoleteContextFiles(contextDir) {
306
308
  const root = path.resolve(contextDir);
307
309
  const candidates = new Map();
@@ -322,12 +324,6 @@ function removeObsoleteContextFiles(contextDir) {
322
324
  candidates.set(path.join(dir, name), { hash, dir, name });
323
325
  }
324
326
  }
325
- if (CONTEXT_WRITE_LEGACY) {
326
- for (const rel of OBSOLETE_CONTEXT_FILES) {
327
- const abs = path.resolve(root, rel);
328
- if (abs.startsWith(root + path.sep)) candidates.set(abs, { hash: null, dir: path.dirname(abs), name: path.basename(abs), legacy: true });
329
- }
330
- }
331
327
  for (const [abs, info] of candidates) {
332
328
  if (CONTEXT_WRITE_REPORT.seen.has(abs)) continue;
333
329
  const rel = path.relative(root, abs).split(path.sep).join('/');
@@ -338,7 +334,7 @@ function removeObsoleteContextFiles(contextDir) {
338
334
  stat = null;
339
335
  }
340
336
  if (stat && stat.isFile()) {
341
- if (!info.legacy && sha256Text(fs.readFileSync(abs)) !== info.hash) {
337
+ if (sha256Text(fs.readFileSync(abs)) !== info.hash) {
342
338
  CONTEXT_WRITE_REPORT.obsoleteKept.push(rel);
343
339
  continue;
344
340
  }
@@ -399,7 +395,7 @@ function readFileSafe(filePath) {
399
395
  function getFileChecksum(filePath) {
400
396
  const content = readFileSafe(filePath);
401
397
  if (!content) return null;
402
- return crypto.createHash('sha256').update(content).digest('hex').slice(0, 16);
398
+ return sha256Text(content).slice(0, 16);
403
399
  }
404
400
 
405
401
  /**
@@ -501,6 +497,14 @@ function analyzeRepository(rootDir) {
501
497
  const pm = discovery.packageManager;
502
498
  if (scripts['test:unit']) discovery.scripts.testUnit = `${pm} run test:unit`;
503
499
  else if (scripts['test']) discovery.scripts.testUnit = `${pm} test`;
500
+ // Fast verification lane (`verify --related`): the runner's own
501
+ // related-test selection, through the project's test script when it has one.
502
+ const testScript = scripts['test:unit'] ? 'test:unit' : (scripts['test'] ? 'test' : null);
503
+ const viaScript = (extra) => (testScript ? `${pm} run ${testScript}${pm === 'npm' ? ' --' : ''} ${extra}` : null);
504
+ if (allDeps['vitest']) discovery.scripts.testRelated = `npx vitest related --run --passWithNoTests {files}`;
505
+ else if (allDeps['jest'] || allDeps['ts-jest']) {
506
+ discovery.scripts.testRelated = viaScript('--findRelatedTests --passWithNoTests {files}') || 'npx jest --findRelatedTests --passWithNoTests {files}';
507
+ }
504
508
 
505
509
  if (scripts['typecheck']) discovery.scripts.typecheck = `${pm} run typecheck`;
506
510
  else if (scripts['type-check']) discovery.scripts.typecheck = `${pm} run type-check`;
@@ -664,6 +668,7 @@ ${discovery.topLevelDirs.map((d) => `- \`${d}/\``).join('\n') || '- Flat directo
664
668
  - **lint**: \`${discovery.scripts.lint}\`
665
669
  - **build**: \`${discovery.scripts.build}\`
666
670
  ${discovery.scripts.e2e ? `- **e2e**: \`${discovery.scripts.e2e}\`` : ''}
671
+ ${discovery.scripts.testRelated ? `- **test_related**: \`${discovery.scripts.testRelated}\`` : ''}
667
672
 
668
673
  ## Verification Protocol
669
674
  - Default order, cheapest first, stop at the first failure: build -> typecheck -> lint -> test_unit -> security scan (for example \`npm audit --omit=dev\`) -> e2e (optional).
@@ -1252,6 +1257,27 @@ function detectGrokHost() {
1252
1257
  }
1253
1258
  }
1254
1259
 
1260
+ // Top lessons from earlier Runs (learn.js), ranked for the files in play.
1261
+ function runLearnings() {
1262
+ try {
1263
+ const { selectLearnings } = require('../lib/learn.js');
1264
+ return selectLearnings(CWD, { files: workingTreePaths(CWD), budgetTokens: 600, limit: 5 }).learnings;
1265
+ } catch {
1266
+ return [];
1267
+ }
1268
+ }
1269
+
1270
+ // Lessons are mined when a Run ends (delivered or escalated), so the next Run
1271
+ // sees them without a manual `learn`. Best effort: never fails the gate.
1272
+ function autoLearn(run) {
1273
+ if (!run || !['DELIVERED', 'ESCALATED'].includes(run.state) || process.env.AEL_NO_AUTO_LEARN === '1') return;
1274
+ try {
1275
+ learn(CWD, {});
1276
+ } catch (err) {
1277
+ console.error(`! learnings not updated: ${err.message}`);
1278
+ }
1279
+ }
1280
+
1255
1281
  function workingTreePaths(rootDir) {
1256
1282
  try {
1257
1283
  return execSync('git status --porcelain --untracked-files=all', { cwd: rootDir, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] })
@@ -1450,6 +1476,7 @@ function handleRun() {
1450
1476
  const h = hostSkillStatus({ home: homeDir(), version: VERSION });
1451
1477
  return { stale: h.stale, staleFiles: h.staleFiles, installedVersion: h.installedVersion, packageVersion: VERSION };
1452
1478
  })(),
1479
+ learnings: runLearnings(),
1453
1480
  studioUrl: readStudioUrl(CWD)
1454
1481
  }, null, 2));
1455
1482
  return;
@@ -1849,6 +1876,7 @@ function executeGate(gate, runId) {
1849
1876
  : applyGate(CWD, gate, { runId: target.runId });
1850
1877
  if (gate === 'goal') ensureImpactMap(target.runId);
1851
1878
  if (gate === 'verification') recordImpactDrift(target.runId);
1879
+ autoLearn(run);
1852
1880
  const runCompleted = run.state === 'DELIVERED' || run.state === 'REPORTED';
1853
1881
  appendRunLifecycle(CWD, target.runId, {
1854
1882
  type: runCompleted
@@ -1863,6 +1891,34 @@ function executeGate(gate, runId) {
1863
1891
  return run;
1864
1892
  }
1865
1893
 
1894
+ const FREEZE_QUESTION = /^Freeze Goal draft revision \d+/;
1895
+
1896
+ // The freeze answers the pending freeze question(s) that `goal draft` asked,
1897
+ // so Studio does not keep showing them. Best effort.
1898
+ function closeFreezeQuestions(runId, actor) {
1899
+ try {
1900
+ const { listRunInteractions, appendRunAnswer } = require('../lib/run-interactions.js');
1901
+ for (const question of listRunInteractions(CWD, runId).pending) {
1902
+ if (FREEZE_QUESTION.test(question.message)) {
1903
+ appendRunAnswer(CWD, runId, question.questionId, { message: 'Goal frozen', actor });
1904
+ }
1905
+ }
1906
+ } catch (err) {
1907
+ console.error(`! freeze question not closed: ${err.message}`);
1908
+ }
1909
+ }
1910
+
1911
+ // Blast radius of a Goal draft, so the human sees it with the Goal and can
1912
+ // confirm both in one stop (`goal freeze --confirm-impact`). Best effort.
1913
+ function impactPreview(runId, goal) {
1914
+ try {
1915
+ const map = impactMap.buildImpactMap(CWD, { run: loadRun(CWD, runId), goal });
1916
+ return { files: (map.files || []).map((file) => file.path), tests: (map.tests || []).map((t) => t.path || t).slice(0, 10) };
1917
+ } catch (err) {
1918
+ return { error: err.message };
1919
+ }
1920
+ }
1921
+
1866
1922
  // Blast-radius map (#71): written into the Run once the Goal is frozen, so it
1867
1923
  // exists before Stage 3. Best effort: a scan failure never blocks a gate.
1868
1924
  function ensureImpactMap(runId) {
@@ -1913,6 +1969,15 @@ function captureMakerDiff(run) {
1913
1969
  return { path: path.relative(CWD, target).split(path.sep).join('/'), files: untracked.length };
1914
1970
  }
1915
1971
 
1972
+ function reviewLedgerBinding(run) {
1973
+ try {
1974
+ const ledger = JSON.parse(fs.readFileSync(path.join(CWD, '.ai-engineering-loop', 'runs', run.runId, 'findings.json'), 'utf8'));
1975
+ return require('../lib/review-ingest.js').checkLedgerBinding(CWD, run, ledger).binding;
1976
+ } catch {
1977
+ return null;
1978
+ }
1979
+ }
1980
+
1916
1981
  function handleGate() {
1917
1982
  const gate = process.argv[3];
1918
1983
  const runId = argValue('--run');
@@ -1928,6 +1993,7 @@ function handleGate() {
1928
1993
  }
1929
1994
  const run = executeGate(gate, target.runId);
1930
1995
  const judge = gate === 'review' && run.tier ? judgeRequirement(CWD, run) : null;
1996
+ const ledgerBinding = gate === 'review' ? reviewLedgerBinding(run) : null;
1931
1997
  const guardEvents = guard.guardSummary(CWD, run.runId);
1932
1998
  if (json) {
1933
1999
  console.log(JSON.stringify({
@@ -1938,6 +2004,7 @@ function handleGate() {
1938
2004
  gate,
1939
2005
  ...(run.tier ? { tier: run.tier.current } : {}),
1940
2006
  ...(judge ? { judgeRequired: judge.required, judgeReasons: judge.reasons } : {}),
2007
+ ...(ledgerBinding ? { ledgerBinding } : {}),
1941
2008
  guard: guardEvents
1942
2009
  }));
1943
2010
  } else {
@@ -1948,6 +2015,9 @@ function handleGate() {
1948
2015
  if (guardEvents.warn || guardEvents.block) {
1949
2016
  console.log(`- Guard: ${guardEvents.block} blocked, ${guardEvents.warn} warned (${guardEvents.rules.join(', ')}); see guard-events.json`);
1950
2017
  }
2018
+ if (ledgerBinding === 'UNBOUND') {
2019
+ console.log('- Ledger: UNBOUND (hand-written findings.json). Prefer `review ingest` so the ledger is bound to the reviewer output.');
2020
+ }
1951
2021
  if (judge) {
1952
2022
  console.log(judge.required
1953
2023
  ? `- Judge: REQUIRED (${judge.reasons.join('; ')}). Spawn the Judge subagent, write verdict.json, then gate judge.`
@@ -3010,6 +3080,7 @@ function handleGoal() {
3010
3080
  try {
3011
3081
  const runId = requiredRunId('goal');
3012
3082
  let result;
3083
+ const extra = {};
3013
3084
  if (action === 'show') {
3014
3085
  result = loadGoalDraft(CWD, runId);
3015
3086
  } else if (action === 'draft') {
@@ -3019,10 +3090,12 @@ function handleGoal() {
3019
3090
  actor: argValue('--by') || 'agent',
3020
3091
  message: argValue('--message') || 'Updating the Goal draft'
3021
3092
  });
3022
- result = saveGoalDraft(CWD, runId, readBoundedJsonInput(argValue('--file')), {
3093
+ const draftGoal = readBoundedJsonInput(argValue('--file'));
3094
+ result = saveGoalDraft(CWD, runId, draftGoal, {
3023
3095
  actor: argValue('--by') || 'agent',
3024
3096
  expectedRevision: requiredIntegerArg('--revision')
3025
3097
  });
3098
+ extra.impactPreview = impactPreview(runId, draftGoal);
3026
3099
  appendRunLifecycle(CWD, runId, {
3027
3100
  type: 'GOAL_DRAFT_UPDATED',
3028
3101
  phase: 'goal',
@@ -3035,6 +3108,17 @@ function handleGoal() {
3035
3108
  actor: argValue('--by') || 'agent',
3036
3109
  message: `Goal draft revision ${result.metadata.revision} is ready for review`
3037
3110
  });
3111
+ // The freeze question is persisted with the draft, so Studio shows it
3112
+ // without a separate `interaction question` call.
3113
+ try {
3114
+ extra.question = appendRunQuestion(CWD, runId, {
3115
+ message: `Freeze Goal draft revision ${result.metadata.revision} (and accept its blast radius)?`,
3116
+ actor: argValue('--by') || 'agent'
3117
+ });
3118
+ appendRunLifecycle(CWD, runId, { type: 'AGENT_WAITING', phase: 'goal', actor: argValue('--by') || 'agent', message: `Waiting for answer to Q${extra.question.number}` });
3119
+ } catch (err) {
3120
+ extra.question = { error: err.message };
3121
+ }
3038
3122
  } else if (action === 'freeze') {
3039
3123
  const latest = process.argv.includes('--latest');
3040
3124
  const latestDraft = latest ? loadGoalDraft(CWD, runId) : null;
@@ -3076,12 +3160,19 @@ function handleGoal() {
3076
3160
  message: 'Goal Contract frozen'
3077
3161
  });
3078
3162
  ensureImpactMap(runId);
3163
+ closeFreezeQuestions(runId, argValue('--by') || 'human');
3164
+ // One human stop: the same person accepts the Goal and its blast radius
3165
+ // (shown as impactPreview with the draft).
3166
+ if (process.argv.includes('--confirm-impact')) {
3167
+ const confirmed = impactMap.confirmImpactMap(CWD, { runId, by: argValue('--by') || 'human' });
3168
+ extra.impact = { status: confirmed.map ? confirmed.map.status : 'CONFIRMED' };
3169
+ }
3079
3170
  } else {
3080
3171
  const error = new Error('goal must be show, draft, or freeze');
3081
3172
  error.code = 'INVALID_USAGE';
3082
3173
  throw error;
3083
3174
  }
3084
- console.log(JSON.stringify({ ok: true, runId, [action === 'show' ? 'draft' : 'result']: result }, null, 2));
3175
+ console.log(JSON.stringify({ ok: true, runId, [action === 'show' ? 'draft' : 'result']: result, ...extra }, null, 2));
3085
3176
  } catch (error) {
3086
3177
  log.error(`${error.code || 'GOAL_FAILED'}: ${error.message}`);
3087
3178
  process.exitCode = 1;
@@ -3257,20 +3348,61 @@ async function handleVerify() {
3257
3348
  try {
3258
3349
  const runId = requiredRunId('verify');
3259
3350
  const shell = process.argv.includes('--shell');
3351
+ const related = process.argv.includes('--related');
3352
+ const final = process.argv.includes('--final');
3353
+ if (related && final) throw Object.assign(new Error('--related and --final cannot be combined'), { code: 'INVALID_USAGE' });
3260
3354
  let texts = repeatedArg('--cmd');
3261
- if (texts.length === 0) {
3262
- const fallback = defaultVerificationCommand();
3263
- if (!fallback) throw Object.assign(new Error('No --cmd given and no test_unit command in .ai-engineering-loop/verification.md'), { code: 'INVALID_COMMAND' });
3264
- texts = [fallback];
3355
+ const lanes = require('../lib/verification-lanes.js');
3356
+ let commandsToRun;
3357
+ if (related && texts.length === 0) {
3358
+ const target = loadRun(CWD, runId);
3359
+ commandsToRun = [lanes.relatedCommand(CWD, target, { split: splitCommand, shell })];
3360
+ } else {
3361
+ if (texts.length === 0) {
3362
+ const fallback = defaultVerificationCommand();
3363
+ if (!fallback) throw Object.assign(new Error('No --cmd given and no test_unit command in .ai-engineering-loop/verification.md'), { code: 'INVALID_COMMAND' });
3364
+ texts = [fallback];
3365
+ }
3366
+ commandsToRun = texts.map((text) => splitCommand(text, shell));
3265
3367
  }
3266
3368
  const timeoutValue = argValue('--timeout-ms');
3369
+ if (final) {
3370
+ const target = loadRun(CWD, runId);
3371
+ if (target.state !== 'JUDGED_PASS') throw Object.assign(new Error(`verify --final needs a Judge PASS (state is ${target.state})`), { code: 'INVALID_STATE' });
3372
+ const status = lanes.finalVerificationStatus(CWD, target);
3373
+ let recordedFinal = null;
3374
+ if (status.required && !status.satisfied) {
3375
+ recordedFinal = await recordVerificationCommands(CWD, {
3376
+ runId,
3377
+ commands: commandsToRun,
3378
+ target: 'final',
3379
+ fresh: process.argv.includes('--fresh'),
3380
+ serial: process.argv.includes('--serial'),
3381
+ ...(timeoutValue == null ? {} : { timeoutMs: parsePositiveIntegerArg('--timeout-ms', timeoutValue) })
3382
+ });
3383
+ }
3384
+ const result = {
3385
+ ok: recordedFinal ? recordedFinal.passed : true,
3386
+ runId,
3387
+ final: recordedFinal
3388
+ ? { path: recordedFinal.path, commands: recordedFinal.commands.map((c) => ({ command: c.command, exitCode: c.exitCode, reused: Boolean(c.reused) })) }
3389
+ : { reused: true, reason: status.reason }
3390
+ };
3391
+ if (json) console.log(JSON.stringify(result));
3392
+ else if (result.ok) log.success(`✓ final verification ${recordedFinal ? 'passed' : `not needed (${status.reason})`}; deliver next`);
3393
+ else log.error('Final verification failed; fix it before delivery.');
3394
+ if (!result.ok) process.exitCode = 1;
3395
+ return;
3396
+ }
3267
3397
  const recorded = await recordVerificationCommands(CWD, {
3268
3398
  runId,
3269
- commands: texts.map((text) => splitCommand(text, shell)),
3399
+ commands: commandsToRun,
3270
3400
  serial: process.argv.includes('--serial'),
3401
+ fresh: process.argv.includes('--fresh'),
3402
+ ...(related ? { scope: 'related' } : {}),
3271
3403
  ...(timeoutValue == null ? {} : { timeoutMs: parsePositiveIntegerArg('--timeout-ms', timeoutValue) })
3272
3404
  });
3273
- const commands = recorded.commands.map((c) => ({ command: c.command, exitCode: c.exitCode, timeoutStatus: c.timeoutStatus }));
3405
+ const commands = recorded.commands.map((c) => ({ command: c.command, exitCode: c.exitCode, timeoutStatus: c.timeoutStatus, ...(c.scope ? { scope: c.scope } : {}), ...(c.reused ? { reused: true } : {}) }));
3274
3406
  if (!recorded.passed) {
3275
3407
  autoHeartbeat(runId, 'verification', 'Verification failed; Maker must fix before review');
3276
3408
  const result = { ok: false, code: 'VERIFICATION_FAILED', runId, commands, gate: null };
@@ -3301,6 +3433,7 @@ async function handleVerify() {
3301
3433
  impactDrift: { mapStatus: drift.mapStatus, outOfMap: drift.outOfMap },
3302
3434
  compact: compact.paths,
3303
3435
  claimedVsReality: claimed,
3436
+ ...(related ? { scope: 'related', finalRequired: 'Run `verify --final` after Judge PASS, before delivery.' } : {}),
3304
3437
  next: run.tier && run.tier.current === 'T0'
3305
3438
  ? 'Fill claimed-vs-reality, then gate review and gate judge'
3306
3439
  : 'Fill claimed-vs-reality, then review-pack and spawn the Devil\'s Advocate'
@@ -3364,7 +3497,8 @@ function handleGuard() {
3364
3497
  } catch (err) {
3365
3498
  if (hook) {
3366
3499
  console.error(`ai-engineering-loop guard: ${err.message}`);
3367
- process.exitCode = 1;
3500
+ // Exit 2 makes Claude Code block the call; exit 1 would let it run.
3501
+ process.exitCode = guard.hookFailureExitCode(CWD, argValue('--run'));
3368
3502
  return;
3369
3503
  }
3370
3504
  stageJsonError(err, json, 'GUARD_FAILED');
@@ -3678,6 +3812,83 @@ function handleBench() {
3678
3812
  }
3679
3813
  }
3680
3814
 
3815
+ // Command: review ingest (ledger bound to the reviewer output; lib/review-ingest.js)
3816
+ // Writes findings.json from the raw child output, gates review, and gates the
3817
+ // Judge too when the deterministic verdict is allowed.
3818
+ function handleReview() {
3819
+ const json = process.argv.includes('--json');
3820
+ try {
3821
+ if (process.argv[3] !== 'ingest') throw Object.assign(new Error('Usage: review ingest --run <id> --child-id <id> --file <child-output>'), { code: 'INVALID_USAGE' });
3822
+ const { ingestReview } = require('../lib/review-ingest.js');
3823
+ const ingested = ingestReview(CWD, { runId: argValue('--run'), childId: argValue('--child-id'), file: argValue('--file') });
3824
+ let run = executeGate('review', ingested.runId);
3825
+ const judge = run.tier ? judgeRequirement(CWD, run) : { required: true, reasons: ['NO_TIER'] };
3826
+ if (!judge.required) run = executeGate('judge', ingested.runId);
3827
+ const result = {
3828
+ ok: true,
3829
+ runId: run.runId,
3830
+ state: run.state,
3831
+ iteration: run.iteration,
3832
+ findings: ingested.findings,
3833
+ ledgerBinding: 'BOUND',
3834
+ judgeRequired: judge.required,
3835
+ judgeReasons: judge.reasons,
3836
+ next: judge.required
3837
+ ? 'Spawn the Judge with the ledger and contract, write verdict.json, then gate judge.'
3838
+ : (run.state === 'JUDGED_PASS' ? 'Deliver after human approval.' : `Judge returned ${run.state}; fix and re-verify.`)
3839
+ };
3840
+ if (json) console.log(JSON.stringify(result));
3841
+ else {
3842
+ log.success(`✓ review ingested (${ingested.findings} finding(s), bound to the reviewer output)`);
3843
+ console.log(`- State: ${run.state}, iteration ${run.iteration}`);
3844
+ console.log(`- Next: ${result.next}`);
3845
+ }
3846
+ } catch (err) {
3847
+ stageJsonError(err, json, 'REVIEW_INGEST_FAILED');
3848
+ }
3849
+ }
3850
+
3851
+ // Command: quick start|finish (T0 in two calls; lib/quick.js)
3852
+ function handleQuick() {
3853
+ const action = process.argv[3];
3854
+ const json = process.argv.includes('--json');
3855
+ const { startQuick, finishQuick } = require('../lib/quick.js');
3856
+ try {
3857
+ let result;
3858
+ if (action === 'start') {
3859
+ const valued = new Set(['--mode', '--run', '--cmd', '--timeout-ms']);
3860
+ const words = [];
3861
+ for (let index = 4; index < process.argv.length; index += 1) {
3862
+ const arg = process.argv[index];
3863
+ if (valued.has(arg)) { index += 1; continue; }
3864
+ if (arg.startsWith('--')) continue;
3865
+ words.push(arg);
3866
+ }
3867
+ result = startQuick(CWD, { task: words.join(' '), mode: argValue('--mode') });
3868
+ } else if (action === 'finish') {
3869
+ const timeoutValue = argValue('--timeout-ms');
3870
+ result = finishQuick(CWD, {
3871
+ runId: argValue('--run'),
3872
+ commands: repeatedArg('--cmd'),
3873
+ shell: process.argv.includes('--shell'),
3874
+ serial: process.argv.includes('--serial'),
3875
+ timeoutMs: timeoutValue == null ? null : parsePositiveIntegerArg('--timeout-ms', timeoutValue)
3876
+ });
3877
+ } else {
3878
+ throw Object.assign(new Error('Usage: quick start "<task>" [--mode assisted] | quick finish [--run <id>] [--cmd "<command>"]...'), { code: 'INVALID_USAGE' });
3879
+ }
3880
+ if (json) console.log(JSON.stringify(result));
3881
+ else {
3882
+ (result.ok ? log.success : log.warn)(`${result.ok ? '✓' : '!'} quick ${action}: Run ${result.runId} (${result.tier}${result.state ? `, ${result.state}` : ''})`);
3883
+ for (const item of result.learnings || []) console.log(`- Learning [${item.severity}]: ${item.lesson}`);
3884
+ console.log(`- Next: ${result.next}`);
3885
+ }
3886
+ if (!result.ok) process.exitCode = 1;
3887
+ } catch (err) {
3888
+ stageJsonError(err, json, 'QUICK_FAILED');
3889
+ }
3890
+ }
3891
+
3681
3892
  function handleLearn() {
3682
3893
  const json = process.argv.includes('--json');
3683
3894
  try {
@@ -3835,9 +4046,18 @@ Commands:
3835
4046
  escalation Compute the minimum Judge model tier from deterministic risk signals
3836
4047
  --run <id> target a non-current run
3837
4048
  --json print machine-readable reasons
4049
+ review ingest --run <id> --child-id <id> --file <child-output> [--json]
4050
+ bind findings.json to the Devil's Advocate output, gate review, and gate the
4051
+ Judge too when the deterministic verdict is allowed
4052
+ quick T0 in two calls: start creates the Run and a derived Goal; finish gates the
4053
+ working-tree diff, verifies, writes claimed-vs-reality, and runs review + judge
4054
+ start "<task>" [--mode assisted|unattended] | finish [--run <id>] [--cmd "<command>"]...
3838
4055
  verify Record verification commands, gate them, compact, and scaffold claimed-vs-reality
3839
- [--run <id>] [--cmd "<command>"]... [--shell] [--serial] [--timeout-ms <n>] [--json]
4056
+ [--run <id>] [--cmd "<command>"]... [--shell] [--serial] [--timeout-ms <n>] [--fresh] [--json]
3840
4057
  default command: test_unit from .ai-engineering-loop/verification.md; commands run in parallel
4058
+ --related fast lane: test_related with {files} = changed files of the gated diff
4059
+ --final after Judge PASS: full run delivery needs when verification was related-only
4060
+ --fresh re-run commands that already passed for the same diff and revision
3841
4061
  impact Blast-radius map of the frozen Goal before Stage 3 (written to the Run on Goal freeze)
3842
4062
  map [--run <id>] [--limit <n>] [--force] [--json] files, modules, endpoints, DB tables, tests
3843
4063
  show [--run <id>] [--json]
@@ -4056,6 +4276,12 @@ switch (command) {
4056
4276
  case 'learn':
4057
4277
  handleLearn();
4058
4278
  break;
4279
+ case 'quick':
4280
+ handleQuick();
4281
+ break;
4282
+ case 'review':
4283
+ handleReview();
4284
+ break;
4059
4285
  case 'verify-receipt':
4060
4286
  handleVerifyReceipt();
4061
4287
  break;