ai-engineering-loop 1.17.0 → 2.1.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 (44) hide show
  1. package/.agents/skills/ai-engineering-loop/SKILL.md +4 -4
  2. package/.agents/skills/ai-engineering-loop/references/loop-commands.md +5 -1
  3. package/.claude/skills/ai-engineering-loop/SKILL.md +4 -4
  4. package/.claude/skills/ai-engineering-loop/references/loop-commands.md +5 -1
  5. package/CHANGELOG.md +52 -0
  6. package/README.md +54 -39
  7. package/bin/ai-engineering-loop.js +221 -16
  8. package/core/bench.md +77 -0
  9. package/core/configuration-precedence.md +11 -1
  10. package/core/local-workflow-studio.md +45 -55
  11. package/core/personal-workflow.md +78 -0
  12. package/core/workflow-recipes.md +2 -0
  13. package/docs/images/studio-hero.svg +59 -47
  14. package/evals/README.md +2 -0
  15. package/evals/cases/25-no-task-onboarding.json +22 -0
  16. package/evals/scenarios/t0-docs-typo.json +31 -0
  17. package/evals/scenarios/t1-empty-state.json +31 -0
  18. package/evals/scenarios/t1-list-pagination.json +33 -0
  19. package/evals/scenarios/t2-auth-session.json +31 -0
  20. package/evals/scenarios/t2-payment-idempotency.json +31 -0
  21. package/evals/scenarios/trap-destructive-reset.json +33 -0
  22. package/evals/scenarios/trap-out-of-scope.json +34 -0
  23. package/evals/scenarios/trap-prompt-injection.json +39 -0
  24. package/lib/bench-targets.js +194 -0
  25. package/lib/bench.js +1236 -0
  26. package/lib/budget.js +32 -0
  27. package/lib/cli-args.js +12 -1
  28. package/lib/doctor.js +17 -2
  29. package/lib/hosts/registry.js +18 -0
  30. package/lib/personal-workflow.js +925 -0
  31. package/lib/recipe.js +90 -13
  32. package/lib/run-state.js +10 -1
  33. package/lib/run-watcher.js +520 -0
  34. package/lib/runtime-files.js +2 -0
  35. package/lib/runtime-policy.js +42 -1
  36. package/lib/studio-runtime.js +8 -3
  37. package/lib/studio-server.js +336 -98
  38. package/lib/user-state.js +34 -1
  39. package/package.json +1 -1
  40. package/schemas/bench-result.schema.json +288 -0
  41. package/schemas/bench-scenario.schema.json +95 -0
  42. package/studio/app.js +2024 -1633
  43. package/studio/index.html +71 -181
  44. package/studio/styles.css +135 -8
@@ -0,0 +1,925 @@
1
+ 'use strict';
2
+
3
+ // Per-user personal workflow (issue #81). Lives only under the AEL home
4
+ // (AEL_HOME / ~/.ai-engineering-loop). Never written into a repository.
5
+ // Proposals are records only; accept --by is the sole mutator of the default.
6
+
7
+ const fs = require('fs');
8
+ const path = require('path');
9
+ const { redactHomePaths, redactSecrets } = require('./safe-context.js');
10
+ const {
11
+ homeDir,
12
+ sha256,
13
+ atomicWritePrivate,
14
+ readJsonFile,
15
+ writeJsonFile,
16
+ readUserConfig,
17
+ writeUserConfig,
18
+ personalRecipePath,
19
+ personalHistoryDir,
20
+ workflowHistoryPath,
21
+ proposalsDir,
22
+ proposalPath
23
+ } = require('./user-state.js');
24
+ const { loadPolicy, normalizeMode } = require('./runtime-policy.js');
25
+ const {
26
+ BACKBONE_CODES,
27
+ RECIPE_ID,
28
+ canonicalJson,
29
+ compileRecipe,
30
+ listRecipes,
31
+ loadRecipe,
32
+ sha256: recipeHash,
33
+ validateRecipe
34
+ } = require('./recipe.js');
35
+ const { stableEdgeId } = require('./recipe-graph.js');
36
+ const { RUN_MODES, RUN_STATES, TERMINAL_STATES, runsDir } = require('./run-state.js');
37
+
38
+ const PERSONAL_ID = 'personal';
39
+ const SUGGEST_WINDOW = 20;
40
+ const SUGGEST_RATIO = 0.8;
41
+ const RISK_WINDOW = 10;
42
+ const RISK_COUNT = 4;
43
+ const LEARNING_MIN = 3;
44
+ const ACTOR_ID = /^[A-Za-z0-9@._-]{1,64}$/;
45
+ const LEARNING_ID = /^[a-z0-9][a-z0-9-]{0,63}$/;
46
+ const GATE_ID = /^[a-z0-9-]{1,40}$/;
47
+ const BACKBONE_TYPES = new Set([
48
+ 'goal-contract', 'maker', 'verification', 'devil-advocate', 'judge', 'delivery', 'report'
49
+ ]);
50
+ const SUMMARY_KEYS = Object.freeze([
51
+ 'schemaVersion', 'at', 'runId', 'state', 'mode', 'tier', 'recipeId', 'iterations',
52
+ 'workflowSource', 'repoHash', 'impact', 'outOfMapCount', 'markdownOnly', 'guard', 'learningIds', 'gates'
53
+ ]);
54
+
55
+ const INTERVIEW_QUESTIONS = Object.freeze([
56
+ {
57
+ id: 'usualTier',
58
+ prompt: 'Usual tier',
59
+ options: ['T0', 'T1', 'T2'],
60
+ fallback: 'T1'
61
+ },
62
+ {
63
+ id: 'mode',
64
+ prompt: 'ASSISTED vs UNATTENDED',
65
+ options: ['ASSISTED', 'UNATTENDED'],
66
+ fallback: 'ASSISTED'
67
+ },
68
+ {
69
+ id: 'extraApproval',
70
+ prompt: 'Extra approval before Maker (docs-light path, design/backend pack, or extra checkpoint)',
71
+ options: ['yes', 'no'],
72
+ fallback: 'no'
73
+ },
74
+ {
75
+ id: 'docsLight',
76
+ prompt: 'Route markdown-only tasks onto a docs-light node',
77
+ options: ['yes', 'no'],
78
+ fallback: 'no'
79
+ },
80
+ {
81
+ id: 'makerIntern',
82
+ prompt: 'Maker intern (host catalog label, or none)',
83
+ options: ['none'],
84
+ fallback: 'none'
85
+ },
86
+ {
87
+ id: 'headsUp',
88
+ prompt: 'Stages to get a heads-up on',
89
+ options: ['none', 'maker', 'delivery'],
90
+ fallback: 'none'
91
+ },
92
+ {
93
+ id: 'extraBeforeGrill',
94
+ prompt: 'Extra step before grill',
95
+ options: ['none'],
96
+ fallback: 'none'
97
+ },
98
+ {
99
+ id: 'extraAfterFreeze',
100
+ prompt: 'Extra step after Goal Contract freeze',
101
+ options: ['none'],
102
+ fallback: 'none'
103
+ },
104
+ {
105
+ id: 'extraAfterPass',
106
+ prompt: 'Extra step after Judge PASS',
107
+ options: ['none'],
108
+ fallback: 'none'
109
+ }
110
+ ]);
111
+
112
+ function workflowError(message, code = 'PERSONAL_WORKFLOW_FAILED', details = []) {
113
+ const error = new Error(message);
114
+ error.code = code;
115
+ error.details = details;
116
+ return error;
117
+ }
118
+
119
+ function canUseUserWorkflow(env = process.env) {
120
+ if (env.AEL_HOME) return true;
121
+ if (env.NODE_TEST_CONTEXT) return false;
122
+ return true;
123
+ }
124
+
125
+ function resolveHome(home, env = process.env) {
126
+ return home || homeDir(env);
127
+ }
128
+
129
+ function clone(value) {
130
+ return JSON.parse(JSON.stringify(value));
131
+ }
132
+
133
+ function builtinRecipe(rootDir, id) {
134
+ return clone(loadRecipe(rootDir, id).recipe);
135
+ }
136
+
137
+ function loadProjectWorkflowConfig(rootDir) {
138
+ return loadPolicy(rootDir).workflow;
139
+ }
140
+
141
+ function readAdapterText(rootDir) {
142
+ try {
143
+ const filePath = path.join(rootDir, '.ai-engineering-loop', 'adapter.md');
144
+ const stat = fs.lstatSync(filePath);
145
+ if (!stat.isFile() || stat.isSymbolicLink()) return '';
146
+ return fs.readFileSync(filePath, 'utf8');
147
+ } catch {
148
+ return '';
149
+ }
150
+ }
151
+
152
+ // One line in adapter.md pins a checkpoint the personal recipe cannot drop:
153
+ // - **required_node**: <id> approval <from> <to> <message>
154
+ function adapterRequiredFragment(rootDir) {
155
+ const nodes = [];
156
+ const edges = [];
157
+ const pattern = /^\s*-\s+\*\*required_node\*\*:\s+([a-z][a-z0-9-]{0,63})\s+(approval)\s+([a-z][a-z0-9-]{0,63})\s+([a-z][a-z0-9-]{0,63})\s+(.+)$/gm;
158
+ for (const match of readAdapterText(rootDir).matchAll(pattern)) {
159
+ const [, id, type, from, to, message] = match;
160
+ nodes.push({ id, type, required: true, message: message.trim() });
161
+ edges.push({ from, to: id });
162
+ edges.push({ from: id, to });
163
+ }
164
+ return { nodes, edges };
165
+ }
166
+
167
+ function projectRequiredFragment(rootDir) {
168
+ const nodes = [];
169
+ const edges = [];
170
+ let entries = [];
171
+ try {
172
+ entries = listRecipes(rootDir).filter((entry) => entry.source === 'project');
173
+ } catch {
174
+ return { nodes, edges };
175
+ }
176
+ for (const entry of entries) {
177
+ let loaded;
178
+ try {
179
+ loaded = loadRecipe(rootDir, entry.id);
180
+ } catch {
181
+ continue;
182
+ }
183
+ const required = (loaded.recipe.nodes || []).filter((node) => node.required === true);
184
+ if (!required.length) continue;
185
+ const ids = new Set(required.map((node) => node.id));
186
+ nodes.push(...required.map((node) => clone(node)));
187
+ for (const edge of loaded.recipe.edges || []) {
188
+ if (ids.has(edge.from) || ids.has(edge.to)) edges.push(clone(edge));
189
+ }
190
+ }
191
+ return { nodes, edges };
192
+ }
193
+
194
+ function repoHash(rootDir) {
195
+ let resolved = String(rootDir || '');
196
+ try {
197
+ resolved = fs.realpathSync(rootDir);
198
+ } catch {
199
+ // Hash the given root even when it is not yet a real path.
200
+ }
201
+ return sha256(resolved);
202
+ }
203
+
204
+ function readPersonalRecipe(home, env = process.env) {
205
+ if (!canUseUserWorkflow(env)) return null;
206
+ const filePath = personalRecipePath(resolveHome(home, env));
207
+ const recipe = readJsonFile(filePath, null);
208
+ if (!recipe || typeof recipe !== 'object' || Array.isArray(recipe)) return null;
209
+ if (recipe.id !== PERSONAL_ID) return null;
210
+ return recipe;
211
+ }
212
+
213
+ function nodeCopy(node) {
214
+ const copy = clone(node);
215
+ delete copy.required;
216
+ return copy;
217
+ }
218
+
219
+ // Insert a required node only when both of its neighbors are already in the
220
+ // graph, so it cannot float off the safety chain or break REPORT_ONLY.
221
+ function overlayRequiredNodes(base, fragment) {
222
+ const recipe = clone(base);
223
+ recipe.nodes = recipe.nodes || [];
224
+ recipe.edges = recipe.edges || [];
225
+ const byId = new Map(recipe.nodes.map((node) => [node.id, node]));
226
+ const typePresent = new Set(recipe.nodes.map((node) => node.type));
227
+ for (const node of fragment.nodes || []) {
228
+ if (byId.has(node.id)) {
229
+ if (node.required === true) {
230
+ const index = recipe.nodes.findIndex((item) => item.id === node.id);
231
+ const replacement = { ...nodeCopy(node), id: node.id };
232
+ recipe.nodes[index] = replacement;
233
+ byId.set(node.id, replacement);
234
+ }
235
+ continue;
236
+ }
237
+ if (BACKBONE_TYPES.has(node.type) && typePresent.has(node.type)) continue;
238
+ const related = (fragment.edges || []).filter((edge) => edge.from === node.id || edge.to === node.id);
239
+ const incoming = related.some((edge) => edge.to === node.id && byId.has(edge.from));
240
+ const outgoing = related.some((edge) => edge.from === node.id && byId.has(edge.to));
241
+ if (!incoming || !outgoing) continue;
242
+ const copy = nodeCopy(node);
243
+ recipe.nodes.push(copy);
244
+ byId.set(copy.id, copy);
245
+ typePresent.add(copy.type);
246
+ }
247
+ const edgeKeys = new Set(recipe.edges.map((edge) => `${edge.from}\0${edge.to}`));
248
+ for (const edge of fragment.edges || []) {
249
+ if (!byId.has(edge.from) || !byId.has(edge.to)) continue;
250
+ const key = `${edge.from}\0${edge.to}`;
251
+ if (edgeKeys.has(key)) continue;
252
+ const id = edge.id && !recipe.edges.some((item) => item.id === edge.id)
253
+ ? edge.id
254
+ : stableEdgeId(edge.from, edge.to);
255
+ recipe.edges.push({ id, from: edge.from, to: edge.to });
256
+ edgeKeys.add(key);
257
+ }
258
+ return recipe;
259
+ }
260
+
261
+ function mergeRequirements(recipe, rootDir, config) {
262
+ let next = clone(recipe);
263
+ if (config && config.mergeRecipe) {
264
+ next = overlayRequiredNodes(next, builtinRecipe(rootDir, config.mergeRecipe));
265
+ }
266
+ next = overlayRequiredNodes(next, projectRequiredFragment(rootDir));
267
+ next = overlayRequiredNodes(next, adapterRequiredFragment(rootDir));
268
+ return next;
269
+ }
270
+
271
+ function compileOrThrow(recipe, mode) {
272
+ const validation = validateRecipe(recipe, mode ? { mode } : {});
273
+ if (!validation.valid) {
274
+ const code = (validation.codes || []).find((item) => String(item).startsWith('BACKBONE_'))
275
+ || 'INVALID_RECIPE';
276
+ throw workflowError(`Recipe ${recipe?.id || '(unknown)'} is invalid`, code, validation.errors);
277
+ }
278
+ return compileRecipe(recipe, mode ? { mode } : {});
279
+ }
280
+
281
+ function builtinFallbackId(mode) {
282
+ return mode === RUN_MODES.REPORT_ONLY ? 'audit' : 'default';
283
+ }
284
+
285
+ function recipeCompatible(recipe, mode) {
286
+ if (!mode) return true;
287
+ return (recipe.compatibleModes || []).includes(mode);
288
+ }
289
+
290
+ function resolveRunWorkflow(rootDir, { mode = null, recipeId = null, home, env = process.env } = {}) {
291
+ const config = loadProjectWorkflowConfig(rootDir);
292
+ const normalizedMode = mode ? normalizeMode(mode) : null;
293
+ const requested = recipeId && RECIPE_ID.test(recipeId) ? recipeId : null;
294
+ const personal = readPersonalRecipe(home, env);
295
+ const fallbackId = builtinFallbackId(normalizedMode);
296
+ const finish = (recipe, source, reason) => {
297
+ const merged = mergeRequirements(recipe, rootDir, config);
298
+ if (source === 'personal') merged.id = PERSONAL_ID;
299
+ return { recipe: merged, source, reason, recipeId: merged.id };
300
+ };
301
+
302
+ if (config.requiredRecipe) {
303
+ const loaded = loadRecipe(rootDir, config.requiredRecipe);
304
+ const reason = requested && requested !== loaded.recipe.id
305
+ ? `requiredRecipe=${config.requiredRecipe} overrides --recipe ${requested}`
306
+ : `requiredRecipe=${config.requiredRecipe}`;
307
+ return finish(loaded.recipe, 'project-required', reason);
308
+ }
309
+
310
+ if (requested && requested !== PERSONAL_ID) {
311
+ const loaded = loadRecipe(rootDir, requested);
312
+ return finish(loaded.recipe, 'builtin', personal ? 'explicit-recipe' : null);
313
+ }
314
+
315
+ if (config.allowPersonal === false) {
316
+ const loaded = loadRecipe(rootDir, fallbackId);
317
+ return finish(loaded.recipe, 'project-required', 'allowPersonal=false');
318
+ }
319
+
320
+ if (requested === PERSONAL_ID && !personal) {
321
+ throw workflowError('Personal workflow is not installed', 'PERSONAL_WORKFLOW_MISSING');
322
+ }
323
+
324
+ if (personal && recipeCompatible(personal, normalizedMode)) {
325
+ return finish(personal, 'personal', null);
326
+ }
327
+
328
+ const loaded = loadRecipe(rootDir, fallbackId);
329
+ return finish(loaded.recipe, 'builtin', null);
330
+ }
331
+
332
+ function majority(values, ratio = SUGGEST_RATIO) {
333
+ if (!values.length) return null;
334
+ const counts = {};
335
+ for (const value of values) {
336
+ if (value == null || value === '') continue;
337
+ counts[value] = (counts[value] || 0) + 1;
338
+ }
339
+ const ranked = Object.entries(counts).sort((left, right) => right[1] - left[1] || left[0].localeCompare(right[0]));
340
+ if (!ranked.length) return null;
341
+ const [value, count] = ranked[0];
342
+ if (count / values.length < ratio) return null;
343
+ return { value, count, total: values.length };
344
+ }
345
+
346
+ function readHistory(home, env = process.env, limit = SUGGEST_WINDOW) {
347
+ if (!canUseUserWorkflow(env)) return [];
348
+ const filePath = workflowHistoryPath(resolveHome(home, env));
349
+ let text;
350
+ try {
351
+ const stat = fs.lstatSync(filePath);
352
+ if (stat.isSymbolicLink() || !stat.isFile()) return [];
353
+ text = fs.readFileSync(filePath, 'utf8');
354
+ } catch {
355
+ return [];
356
+ }
357
+ const rows = [];
358
+ for (const line of text.split('\n')) {
359
+ if (!line.trim()) continue;
360
+ try {
361
+ const row = JSON.parse(line);
362
+ if (row && typeof row === 'object') rows.push(row);
363
+ } catch {
364
+ // Skip a corrupt line; the rest of the index still counts.
365
+ }
366
+ }
367
+ return rows.slice(-limit);
368
+ }
369
+
370
+ function evidenceFor(runIds, counts) {
371
+ return {
372
+ runIds: [...new Set(runIds || [])].sort(),
373
+ counts: counts && typeof counts === 'object' ? counts : {}
374
+ };
375
+ }
376
+
377
+ function activeHistory(home, env) {
378
+ return readHistory(home, env, SUGGEST_WINDOW).filter((row) => row.state !== 'CANCELLED');
379
+ }
380
+
381
+ function interviewQuestions(home, env = process.env) {
382
+ const history = activeHistory(home, env);
383
+ const questions = INTERVIEW_QUESTIONS.map((spec) => {
384
+ let value = spec.fallback;
385
+ let evidence = evidenceFor([], { total: history.length });
386
+ if (spec.id === 'usualTier') {
387
+ const pick = majority(history.map((row) => row.tier).filter(Boolean));
388
+ if (pick) {
389
+ value = pick.value;
390
+ evidence = evidenceFor(
391
+ history.filter((row) => row.tier === pick.value).map((row) => row.runId),
392
+ { [pick.value]: pick.count, total: pick.total }
393
+ );
394
+ }
395
+ } else if (spec.id === 'mode') {
396
+ const pick = majority(history.map((row) => row.mode).filter(Boolean));
397
+ if (pick) {
398
+ value = pick.value;
399
+ evidence = evidenceFor(
400
+ history.filter((row) => row.mode === pick.value).map((row) => row.runId),
401
+ { [pick.value]: pick.count, total: pick.total }
402
+ );
403
+ }
404
+ } else if (spec.id === 'extraApproval') {
405
+ const hits = history.filter((row) => row.recipeId === 'high-risk' || row.extraApproval);
406
+ if (history.length && hits.length / history.length >= SUGGEST_RATIO) {
407
+ value = 'yes';
408
+ evidence = evidenceFor(hits.map((row) => row.runId), { yes: hits.length, total: history.length });
409
+ }
410
+ } else if (spec.id === 'docsLight') {
411
+ const markdown = history.filter((row) => row.markdownOnly);
412
+ const t0 = markdown.filter((row) => row.tier === 'T0');
413
+ if (markdown.length >= 3 && t0.length / markdown.length >= SUGGEST_RATIO) {
414
+ value = 'yes';
415
+ evidence = evidenceFor(t0.map((row) => row.runId), { t0: t0.length, markdown: markdown.length });
416
+ }
417
+ }
418
+ return {
419
+ id: spec.id,
420
+ prompt: spec.prompt,
421
+ options: spec.options.slice(),
422
+ default: value,
423
+ evidence
424
+ };
425
+ });
426
+ return {
427
+ questions,
428
+ pendingProposal: listProposals(home, env)
429
+ .filter((item) => item.status === 'pending')
430
+ .sort((left, right) => String(right.createdAt || '').localeCompare(String(left.createdAt || '')))[0] || null,
431
+ historyCount: history.length
432
+ };
433
+ }
434
+
435
+ function isYes(value) {
436
+ return /^(yes|true|1)$/i.test(String(value || '').trim());
437
+ }
438
+
439
+ function addEdge(recipe, from, to) {
440
+ const key = `${from}\0${to}`;
441
+ if ((recipe.edges || []).some((edge) => `${edge.from}\0${edge.to}` === key)) return;
442
+ recipe.edges = recipe.edges || [];
443
+ recipe.edges.push({ id: stableEdgeId(from, to), from, to });
444
+ }
445
+
446
+ function addNamedApproval(recipe, id, message, fromId, toId) {
447
+ if (recipe.nodes.some((node) => node.id === id)) return;
448
+ recipe.nodes.push({ id, type: 'approval', message });
449
+ addEdge(recipe, fromId, id);
450
+ addEdge(recipe, id, toId);
451
+ }
452
+
453
+ function sanitizeLabel(raw, fallback = 'none') {
454
+ const text = redactHomePaths(redactSecrets(String(raw || '')).text).replace(/\s+/g, ' ').trim();
455
+ if (!text || /^none$/i.test(text)) return fallback;
456
+ if (/api[_-]?key/i.test(text) || /^sk-/i.test(text) || /https?:\/\//i.test(text)) {
457
+ throw workflowError('maker_intern is a host-native label, not a key or URL', 'INTERN_SECRET');
458
+ }
459
+ return text.slice(0, 80);
460
+ }
461
+
462
+ function dropNodes(recipe, predicate) {
463
+ recipe.nodes = recipe.nodes.filter((node) => !predicate(node));
464
+ const ids = new Set(recipe.nodes.map((node) => node.id));
465
+ recipe.edges = (recipe.edges || []).filter((edge) => ids.has(edge.from) && ids.has(edge.to));
466
+ }
467
+
468
+ function recipeFromAnswers(answers, { rootDir } = {}) {
469
+ const requested = answers || {};
470
+ const recipe = builtinRecipe(rootDir, 'default');
471
+ recipe.id = PERSONAL_ID;
472
+ recipe.version = 1;
473
+ const intern = sanitizeLabel(requested.makerIntern, 'none');
474
+ recipe.description = `Personal workflow (maker_intern: ${intern}).`;
475
+ const drops = [].concat(requested.drop || []).map((item) => String(item));
476
+ if (drops.length) dropNodes(recipe, (node) => drops.includes(node.type) || drops.includes(node.id));
477
+ for (const name of [].concat(requested.conditionalSkip || []).map((item) => String(item))) {
478
+ const node = recipe.nodes.find((item) => item.type === name || item.id === name);
479
+ if (node) node.when = { field: 'run.iteration', operator: 'greaterThan', value: 0 };
480
+ }
481
+ if (isYes(requested.removeAssistedApproval) || isYes(requested.removeApproval)) {
482
+ dropNodes(recipe, (node) => node.type === 'approval');
483
+ if (recipe.nodes.some((node) => node.id === 'judge') && recipe.nodes.some((node) => node.id === 'delivery')) {
484
+ addEdge(recipe, 'judge', 'delivery');
485
+ }
486
+ }
487
+ if (requested.judgeModel) {
488
+ const judge = recipe.nodes.find((node) => node.type === 'judge');
489
+ if (judge) judge.modelTier = requested.judgeModel;
490
+ }
491
+ if (isYes(requested.extraApproval)) {
492
+ addNamedApproval(
493
+ recipe,
494
+ 'plan-approval',
495
+ 'Approve the implementation plan before repository mutation.',
496
+ 'goal',
497
+ 'maker'
498
+ );
499
+ }
500
+ if (isYes(requested.docsLight)) {
501
+ const docs = builtinRecipe(rootDir, 'docs-light');
502
+ const node = docs.nodes.find((item) => item.id === 'documentation-context');
503
+ if (node && !recipe.nodes.some((item) => item.id === node.id)) {
504
+ recipe.nodes.push(clone(node));
505
+ addEdge(recipe, 'goal', node.id);
506
+ addEdge(recipe, node.id, 'maker');
507
+ }
508
+ }
509
+ if (requested.headsUp && requested.headsUp !== 'none') {
510
+ const stage = String(requested.headsUp);
511
+ if (stage === 'maker') {
512
+ addNamedApproval(recipe, 'maker-heads-up', 'Heads-up before Maker.', 'goal', 'maker');
513
+ } else if (stage === 'delivery') {
514
+ addNamedApproval(recipe, 'delivery-heads-up', 'Heads-up before delivery.', 'judge', 'delivery');
515
+ }
516
+ }
517
+ for (const [answerKey, nodeId, fromId, toId, label] of [
518
+ ['extraBeforeGrill', 'before-grill', 'goal', 'maker', 'Extra step before grill'],
519
+ ['extraAfterFreeze', 'after-freeze', 'goal', 'maker', 'Extra step after Goal freeze'],
520
+ ['extraAfterPass', 'after-pass', 'judge', 'delivery', 'Extra step after Judge PASS']
521
+ ]) {
522
+ const name = sanitizeLabel(requested[answerKey], 'none');
523
+ if (name !== 'none') {
524
+ addNamedApproval(recipe, nodeId, `${label}: ${name}`, fromId, toId);
525
+ }
526
+ }
527
+ return recipe;
528
+ }
529
+
530
+ function diffRecipeObjects(left, right) {
531
+ const leftNodes = new Map((left.nodes || []).map((node) => [node.id, node]));
532
+ const rightNodes = new Map((right.nodes || []).map((node) => [node.id, node]));
533
+ return {
534
+ left: { id: left.id, version: left.version, sourceHash: recipeHash(left) },
535
+ right: { id: right.id, version: right.version, sourceHash: recipeHash(right) },
536
+ metadataChanged: left.description !== right.description
537
+ || canonicalJson(left.compatibleModes) !== canonicalJson(right.compatibleModes),
538
+ added: [...rightNodes.keys()].filter((id) => !leftNodes.has(id)),
539
+ removed: [...leftNodes.keys()].filter((id) => !rightNodes.has(id)),
540
+ changed: [...rightNodes.keys()].filter((id) => (
541
+ leftNodes.has(id) && canonicalJson(leftNodes.get(id)) !== canonicalJson(rightNodes.get(id))
542
+ ))
543
+ };
544
+ }
545
+
546
+ function proposalId(kind, evidence) {
547
+ const material = canonicalJson({ kind, runIds: evidence.runIds || [], counts: evidence.counts || {} });
548
+ return `pw-${String(kind).replace(/[^a-z0-9-]/g, '').slice(0, 24)}-${sha256(material).slice(0, 8)}`;
549
+ }
550
+
551
+ function writeProposalRecord(record, home, env = process.env) {
552
+ if (!canUseUserWorkflow(env)) {
553
+ throw workflowError('Refusing to write personal workflow outside a sandboxed AEL_HOME during tests', 'AEL_HOME_REQUIRED');
554
+ }
555
+ const resolved = resolveHome(home, env);
556
+ const filePath = proposalPath(record.id, resolved);
557
+ writeJsonFile(filePath, record);
558
+ return filePath;
559
+ }
560
+
561
+ function listProposals(home, env = process.env) {
562
+ if (!canUseUserWorkflow(env)) return [];
563
+ const directory = proposalsDir(resolveHome(home, env));
564
+ let names;
565
+ try {
566
+ names = fs.readdirSync(directory).filter((name) => name.endsWith('.json')).sort();
567
+ } catch {
568
+ return [];
569
+ }
570
+ return names.map((name) => readJsonFile(path.join(directory, name), null)).filter(Boolean);
571
+ }
572
+
573
+ function readProposal(id, home, env = process.env) {
574
+ const record = readJsonFile(proposalPath(id, resolveHome(home, env)), null);
575
+ if (!record) throw workflowError(`Proposal not found: ${id}`, 'PROPOSAL_NOT_FOUND');
576
+ return record;
577
+ }
578
+
579
+ function proposeFromAnswers(answers, { rootDir, home, env = process.env, now = new Date() } = {}) {
580
+ const recipe = recipeFromAnswers(answers || {}, { rootDir });
581
+ compileOrThrow(recipe, answers?.mode === 'UNATTENDED' ? RUN_MODES.UNATTENDED : RUN_MODES.ASSISTED);
582
+ const current = readPersonalRecipe(home, env) || builtinRecipe(rootDir, 'default');
583
+ const diff = diffRecipeObjects(current, recipe);
584
+ const evidence = evidenceFor([], { source: 'interview' });
585
+ const record = {
586
+ schemaVersion: 1,
587
+ id: proposalId('interview', { runIds: [now.toISOString()], counts: { interview: 1 } }),
588
+ status: 'pending',
589
+ kind: 'interview',
590
+ createdAt: now.toISOString(),
591
+ recipe,
592
+ diff,
593
+ evidence,
594
+ answers: answers || {}
595
+ };
596
+ const filePath = writeProposalRecord(record, home, env);
597
+ return { proposal: record, path: filePath, diff };
598
+ }
599
+
600
+ function assertHumanAcceptor(by, mode) {
601
+ if (!by || !ACTOR_ID.test(String(by))) {
602
+ throw workflowError('--by <name> is required (the accepting human)', 'INVALID_APPROVER');
603
+ }
604
+ const normalized = mode ? normalizeMode(mode) : null;
605
+ if (normalized === RUN_MODES.UNATTENDED) {
606
+ throw workflowError('UNATTENDED cannot accept a personal workflow; a human must run workflow accept --by <name>', 'HUMAN_REQUIRED');
607
+ }
608
+ }
609
+
610
+ function installPersonalRecipe(recipe, { home, env = process.env, by, now = new Date() } = {}) {
611
+ if (!canUseUserWorkflow(env)) {
612
+ throw workflowError('Refusing to write personal workflow outside a sandboxed AEL_HOME during tests', 'AEL_HOME_REQUIRED');
613
+ }
614
+ const resolved = home || homeDir(env);
615
+ compileOrThrow(recipe, RUN_MODES.ASSISTED);
616
+ const destination = personalRecipePath(resolved);
617
+ const previous = readPersonalRecipe(resolved, env);
618
+ const next = clone(recipe);
619
+ next.id = PERSONAL_ID;
620
+ if (previous) {
621
+ if (!Number.isSafeInteger(next.version) || next.version <= previous.version) {
622
+ next.version = previous.version + 1;
623
+ }
624
+ const historyFile = path.join(personalHistoryDir(resolved), `${previous.version}.json`);
625
+ if (!fs.existsSync(historyFile)) writeJsonFile(historyFile, previous);
626
+ } else if (!Number.isSafeInteger(next.version) || next.version <= 0) {
627
+ next.version = 1;
628
+ }
629
+ writeJsonFile(destination, next);
630
+ writeUserConfig({ defaultRecipe: PERSONAL_ID, defaultRecipeAcceptedBy: by, defaultRecipeAcceptedAt: now.toISOString() }, resolved);
631
+ return { recipe: next, path: destination, replacedVersion: previous?.version || null };
632
+ }
633
+
634
+ function acceptProposal({ proposalId: id, by, home, mode, env = process.env, now = new Date() } = {}) {
635
+ assertHumanAcceptor(by, mode);
636
+ const record = readProposal(id, home, env);
637
+ if (record.status === 'accepted') {
638
+ throw workflowError(`Proposal already accepted: ${id}`, 'PROPOSAL_ALREADY_ACCEPTED');
639
+ }
640
+ if (!record.recipe) throw workflowError('Proposal has no recipe', 'INVALID_PROPOSAL');
641
+ const installed = installPersonalRecipe(record.recipe, { home, env, by, now });
642
+ const accepted = {
643
+ ...record,
644
+ status: 'accepted',
645
+ acceptedBy: String(by),
646
+ acceptedAt: now.toISOString(),
647
+ recipe: installed.recipe
648
+ };
649
+ writeProposalRecord(accepted, home, env);
650
+ return { proposal: accepted, recipe: installed.recipe, replacedVersion: installed.replacedVersion };
651
+ }
652
+
653
+ function rejectProposal({ proposalId: id, by, home, mode, env = process.env, now = new Date() } = {}) {
654
+ assertHumanAcceptor(by, mode);
655
+ const record = readProposal(id, home, env);
656
+ const rejected = {
657
+ ...record,
658
+ status: 'rejected',
659
+ rejectedBy: String(by),
660
+ rejectedAt: now.toISOString(),
661
+ evidenceHash: sha256(canonicalJson(record.evidence || {}))
662
+ };
663
+ writeProposalRecord(rejected, home, env);
664
+ return { proposal: rejected };
665
+ }
666
+
667
+ function evidenceStrength(evidence) {
668
+ return evidence && Array.isArray(evidence.runIds) ? evidence.runIds.length : 0;
669
+ }
670
+
671
+ function shouldSkipSuggestion(existing, candidate) {
672
+ const sameKind = existing.filter((item) => item.kind === candidate.kind);
673
+ if (sameKind.some((item) => item.status === 'pending')) return true;
674
+ const rejected = sameKind.filter((item) => item.status === 'rejected')
675
+ .sort((left, right) => String(right.rejectedAt || '').localeCompare(String(left.rejectedAt || '')));
676
+ if (!rejected.length) return false;
677
+ return evidenceStrength(candidate.evidence) <= evidenceStrength(rejected[0].evidence);
678
+ }
679
+
680
+ function candidateRecipeWithNode(base, node, fromId, toId) {
681
+ const recipe = clone(base);
682
+ recipe.id = PERSONAL_ID;
683
+ if (!recipe.nodes.some((item) => item.id === node.id)) recipe.nodes.push(clone(node));
684
+ addEdge(recipe, fromId, node.id);
685
+ addEdge(recipe, node.id, toId);
686
+ return recipe;
687
+ }
688
+
689
+ function suggestProposals({ home, rootDir, env = process.env, now = new Date() } = {}) {
690
+ const history = activeHistory(home, env);
691
+ const existing = listProposals(home, env);
692
+ const current = readPersonalRecipe(home, env) || builtinRecipe(rootDir, 'default');
693
+ const created = [];
694
+ const consider = (candidate) => {
695
+ if (shouldSkipSuggestion(existing.concat(created), candidate)) return;
696
+ try {
697
+ compileOrThrow(candidate.recipe, RUN_MODES.ASSISTED);
698
+ } catch {
699
+ return;
700
+ }
701
+ const record = {
702
+ schemaVersion: 1,
703
+ id: proposalId(candidate.kind, candidate.evidence),
704
+ status: 'pending',
705
+ kind: candidate.kind,
706
+ createdAt: now.toISOString(),
707
+ recipe: candidate.recipe,
708
+ diff: diffRecipeObjects(current, candidate.recipe),
709
+ evidence: candidate.evidence
710
+ };
711
+ writeProposalRecord(record, home, env);
712
+ created.push(record);
713
+ };
714
+
715
+ const t1 = history.filter((row) => row.tier === 'T1' && row.state !== 'CANCELLED');
716
+ const t1Confirmed = t1.filter((row) => row.impact === 'confirm' && Number(row.outOfMapCount || 0) === 0);
717
+ if (t1.length >= 5 && t1Confirmed.length / t1.length >= SUGGEST_RATIO) {
718
+ consider({
719
+ kind: 'impact-confirm-t2',
720
+ evidence: evidenceFor(t1Confirmed.map((row) => row.runId), {
721
+ confirmed: t1Confirmed.length,
722
+ t1: t1.length,
723
+ ratio: t1Confirmed.length / t1.length
724
+ }),
725
+ recipe: candidateRecipeWithNode(current, {
726
+ id: 'impact-confirm-t2',
727
+ type: 'approval',
728
+ when: { field: 'run.iteration', operator: 'greaterThan', value: 0 },
729
+ message: 'Confirm the impact map; T1 runs in history were unchanged, so prompt mainly at T2.'
730
+ }, 'goal', 'maker')
731
+ });
732
+ }
733
+
734
+ const markdown = history.filter((row) => row.markdownOnly && row.state !== 'CANCELLED');
735
+ const markdownT0 = markdown.filter((row) => row.tier === 'T0');
736
+ if (markdown.length >= 3 && markdownT0.length / markdown.length >= SUGGEST_RATIO) {
737
+ const docs = builtinRecipe(rootDir, 'docs-light');
738
+ const node = docs.nodes.find((item) => item.id === 'documentation-context') || {
739
+ id: 'documentation-context',
740
+ type: 'approval',
741
+ message: 'Docs-light path for markdown-only tasks.'
742
+ };
743
+ consider({
744
+ kind: 'docs-light-markdown',
745
+ evidence: evidenceFor(markdownT0.map((row) => row.runId), {
746
+ t0: markdownT0.length,
747
+ markdown: markdown.length,
748
+ ratio: markdownT0.length / markdown.length
749
+ }),
750
+ recipe: candidateRecipeWithNode(current, node, 'goal', 'maker')
751
+ });
752
+ }
753
+
754
+ const recentT1 = t1.slice(-RISK_WINDOW);
755
+ const drifted = recentT1.filter((row) => Number(row.outOfMapCount || 0) > 0);
756
+ if (recentT1.length >= RISK_WINDOW && drifted.length >= RISK_COUNT) {
757
+ consider({
758
+ kind: 'impact-checkpoint-t1',
759
+ evidence: evidenceFor(drifted.map((row) => row.runId), {
760
+ drifted: drifted.length,
761
+ window: recentT1.length,
762
+ ratio: drifted.length / recentT1.length
763
+ }),
764
+ recipe: candidateRecipeWithNode(current, {
765
+ id: 'impact-checkpoint',
766
+ type: 'approval',
767
+ message: 'Confirm the blast-radius map before Maker (out-of-map T1 edits).'
768
+ }, 'goal', 'maker')
769
+ });
770
+ }
771
+
772
+ const learningCounts = {};
773
+ for (const row of history) {
774
+ for (const id of row.learningIds || []) {
775
+ learningCounts[id] = learningCounts[id] || { count: 0, runIds: [] };
776
+ learningCounts[id].count += 1;
777
+ learningCounts[id].runIds.push(row.runId);
778
+ }
779
+ }
780
+ const top = Object.entries(learningCounts)
781
+ .filter(([, info]) => info.count >= LEARNING_MIN)
782
+ .sort((left, right) => right[1].count - left[1].count || left[0].localeCompare(right[0]))[0];
783
+ if (top) {
784
+ const [learningId, info] = top;
785
+ consider({
786
+ kind: 'learning-checklist',
787
+ evidence: evidenceFor(info.runIds, { [learningId]: info.count, ratio: info.count / history.length }),
788
+ recipe: (() => {
789
+ const recipe = clone(current);
790
+ recipe.id = PERSONAL_ID;
791
+ recipe.description = `${recipe.description || 'Personal workflow'} [${learningId}]`;
792
+ return recipe;
793
+ })()
794
+ });
795
+ }
796
+
797
+ return { proposals: created, historyCount: history.length };
798
+ }
799
+
800
+ function countsFromRun(rootDir, run) {
801
+ const runDir = path.join(runsDir(rootDir), run.runId);
802
+ let impact = null;
803
+ let outOfMapCount = 0;
804
+ let markdownOnly = false;
805
+ try {
806
+ const map = JSON.parse(fs.readFileSync(path.join(runDir, 'impact-map.json'), 'utf8'));
807
+ if (map.status === 'CONFIRMED') impact = 'confirm';
808
+ else if (map.status === 'SKIPPED') impact = 'skip';
809
+ } catch {
810
+ // Optional artifact.
811
+ }
812
+ try {
813
+ const drift = JSON.parse(fs.readFileSync(path.join(runDir, 'impact-drift.json'), 'utf8'));
814
+ const out = Array.isArray(drift.outOfMap) ? drift.outOfMap : [];
815
+ outOfMapCount = out.length;
816
+ const changed = Array.isArray(drift.changedFiles) ? drift.changedFiles : [];
817
+ markdownOnly = changed.length > 0 && changed.every((file) => /\.(md|markdown)$/i.test(String(file).split(/[/\\]/).pop() || ''));
818
+ } catch {
819
+ // Optional artifact.
820
+ }
821
+ let guardWarn = 0;
822
+ let guardBlock = 0;
823
+ try {
824
+ const summary = require('./guard.js').guardSummary(rootDir, run.runId);
825
+ guardWarn = summary.warn;
826
+ guardBlock = summary.block;
827
+ } catch {
828
+ // Optional artifact.
829
+ }
830
+ let learningIds = [];
831
+ try {
832
+ const doc = JSON.parse(fs.readFileSync(path.join(rootDir, '.ai-engineering-loop', 'learnings.json'), 'utf8'));
833
+ learningIds = (doc.entries || [])
834
+ .filter((entry) => Array.isArray(entry.runIds) && entry.runIds.includes(run.runId))
835
+ .map((entry) => entry.id)
836
+ .filter((id) => LEARNING_ID.test(String(id || '')));
837
+ } catch {
838
+ // Optional artifact.
839
+ }
840
+ const gates = {};
841
+ for (const entry of run.history || []) {
842
+ if (!GATE_ID.test(String(entry.gate || '')) || !RUN_STATES[entry.to]) continue;
843
+ gates[String(entry.gate)] = String(entry.to);
844
+ }
845
+ return {
846
+ impact,
847
+ outOfMapCount,
848
+ markdownOnly,
849
+ guardWarn,
850
+ guardBlock,
851
+ learningIds,
852
+ gates
853
+ };
854
+ }
855
+
856
+ function appendJsonl(filePath, value) {
857
+ fs.mkdirSync(path.dirname(filePath), { recursive: true, mode: 0o700 });
858
+ const noFollow = fs.constants.O_NOFOLLOW || 0;
859
+ let descriptor;
860
+ try {
861
+ descriptor = fs.openSync(
862
+ filePath,
863
+ fs.constants.O_APPEND | fs.constants.O_CREAT | fs.constants.O_WRONLY | noFollow,
864
+ 0o600
865
+ );
866
+ if (!fs.fstatSync(descriptor).isFile()) throw new Error('history is not a regular file');
867
+ fs.writeSync(descriptor, `${JSON.stringify(value)}\n`);
868
+ } finally {
869
+ if (descriptor != null) fs.closeSync(descriptor);
870
+ }
871
+ }
872
+
873
+ function appendRunSummary(rootDir, run, { home, env = process.env, now = new Date() } = {}) {
874
+ if (!run || !TERMINAL_STATES.has(run.state)) return null;
875
+ if (!canUseUserWorkflow(env) && !env.AEL_HOME) return null;
876
+ const resolved = resolveHome(home, env);
877
+ const counts = countsFromRun(rootDir, run);
878
+ const summary = {
879
+ schemaVersion: 1,
880
+ at: (now && typeof now.toISOString === 'function' ? now : new Date()).toISOString(),
881
+ runId: run.runId,
882
+ state: run.state,
883
+ mode: run.mode || null,
884
+ tier: run.tier && run.tier.current ? run.tier.current : null,
885
+ recipeId: run.workflow && run.workflow.recipeId ? run.workflow.recipeId : null,
886
+ workflowSource: run.workflow && run.workflow.workflowSource ? run.workflow.workflowSource : null,
887
+ iterations: run.iteration || 1,
888
+ repoHash: repoHash(rootDir),
889
+ impact: counts.impact,
890
+ outOfMapCount: counts.outOfMapCount,
891
+ markdownOnly: counts.markdownOnly,
892
+ guard: { warn: counts.guardWarn, block: counts.guardBlock },
893
+ learningIds: counts.learningIds,
894
+ gates: counts.gates
895
+ };
896
+ const line = redactHomePaths(redactSecrets(JSON.stringify(summary)).text);
897
+ const parsed = JSON.parse(line);
898
+ const clean = {};
899
+ for (const key of SUMMARY_KEYS) clean[key] = parsed[key];
900
+ appendJsonl(workflowHistoryPath(resolved), clean);
901
+ return clean;
902
+ }
903
+
904
+ module.exports = {
905
+ PERSONAL_ID,
906
+ SUGGEST_WINDOW,
907
+ SUGGEST_RATIO,
908
+ BACKBONE_CODES,
909
+ INTERVIEW_QUESTIONS,
910
+ canUseUserWorkflow,
911
+ repoHash,
912
+ readPersonalRecipe,
913
+ loadProjectWorkflowConfig,
914
+ resolveRunWorkflow,
915
+ interviewQuestions,
916
+ recipeFromAnswers,
917
+ proposeFromAnswers,
918
+ acceptProposal,
919
+ rejectProposal,
920
+ suggestProposals,
921
+ listProposals,
922
+ appendRunSummary,
923
+ diffRecipeObjects,
924
+ compileOrThrow
925
+ };