ai-engineering-loop 2.2.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 (103) 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 +35 -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/orchestration-model.md +8 -7
  19. package/core/repo-config-schema.md +2 -2
  20. package/core/runtime-safety.md +3 -3
  21. package/lib/auto-update.js +8 -14
  22. package/lib/claimed-vs-reality.js +2 -2
  23. package/lib/cli-args.js +3 -1
  24. package/lib/docs.js +1 -1
  25. package/lib/doctor.js +0 -6
  26. package/lib/escalation.js +1 -1
  27. package/lib/fsutil.js +88 -0
  28. package/lib/gates.js +69 -27
  29. package/lib/generate-workflow.js +0 -29
  30. package/lib/goal-runtime.js +3 -2
  31. package/lib/guard-hooks.js +26 -7
  32. package/lib/guard.js +100 -10
  33. package/lib/hosts/doctor.js +1 -5
  34. package/lib/impact-map.js +4 -9
  35. package/lib/jsonl-ledger.js +104 -0
  36. package/lib/learn.js +4 -9
  37. package/lib/loop-groups.js +0 -25
  38. package/lib/migrations.js +1 -5
  39. package/lib/no-progress.js +119 -0
  40. package/lib/node-evidence.js +1 -5
  41. package/lib/orchestration.js +5 -361
  42. package/lib/personal-workflow.js +1 -1
  43. package/lib/quick.js +152 -0
  44. package/lib/receipt.js +1 -5
  45. package/lib/recipe-builder.js +3 -35
  46. package/lib/recipe-graph.js +2 -63
  47. package/lib/recipe.js +2 -4
  48. package/lib/review-ingest.js +116 -0
  49. package/lib/run-abandon.js +2 -1
  50. package/lib/run-compaction.js +4 -12
  51. package/lib/run-interactions.js +16 -71
  52. package/lib/run-lifecycle.js +25 -77
  53. package/lib/run-state.js +68 -17
  54. package/lib/run-watcher.js +11 -14
  55. package/lib/runtime-files.js +45 -1
  56. package/lib/safe-context.js +17 -6
  57. package/lib/sandbox.js +2 -1
  58. package/lib/smart-context.js +3 -13
  59. package/lib/spawn-command.js +94 -0
  60. package/lib/studio-layout.js +2 -8
  61. package/lib/studio-runtime.js +2 -1
  62. package/lib/studio-server.js +25 -5
  63. package/lib/tier.js +36 -10
  64. package/lib/user-state.js +2 -17
  65. package/lib/verification-lanes.js +115 -0
  66. package/lib/verification-recorder.js +110 -22
  67. package/lib/workflow-runtime.js +7 -4
  68. package/package.json +1 -2
  69. package/policies/review-budget.md +1 -1
  70. package/.claude/skills/ai-engineering-loop/SKILL.md +0 -62
  71. package/.claude/skills/ai-engineering-loop/references/loop-commands.md +0 -24
  72. package/.claude/skills/ai-engineering-loop/references/loop-deliver.md +0 -10
  73. package/.claude/skills/ai-engineering-loop/references/loop-goal.md +0 -11
  74. package/.claude/skills/ai-engineering-loop/references/loop-hosts.md +0 -48
  75. package/.claude/skills/ai-engineering-loop/references/loop-maker.md +0 -14
  76. package/.claude/skills/ai-engineering-loop/references/loop-review.md +0 -20
  77. package/.claude/skills/ai-engineering-loop/references/loop-risky.md +0 -9
  78. package/.claude/skills/ai-engineering-loop/references/loop-verify.md +0 -20
  79. package/.claude/skills/animate/RECIPES.md +0 -324
  80. package/.claude/skills/animate/SKILL.md +0 -207
  81. package/.claude/skills/animate-expo/RECIPES.md +0 -385
  82. package/.claude/skills/animate-expo/SKILL.md +0 -263
  83. package/.claude/skills/animation-vocabulary/SKILL.md +0 -181
  84. package/.claude/skills/apple-design/SKILL.md +0 -290
  85. package/.claude/skills/ask-sonner/API.md +0 -64
  86. package/.claude/skills/ask-sonner/SKILL.md +0 -88
  87. package/.claude/skills/backend-development/SKILL.md +0 -272
  88. package/.claude/skills/backend-development/references/api-design-guidelines.md +0 -95
  89. package/.claude/skills/backend-development/references/query-and-database-best-practices.md +0 -53
  90. package/.claude/skills/backend-development/references/security-checklist.md +0 -60
  91. package/.claude/skills/emil-design-eng/SKILL.md +0 -674
  92. package/.claude/skills/find-animation-opportunities/SKILL.md +0 -140
  93. package/.claude/skills/improve-animations/AUDIT.md +0 -115
  94. package/.claude/skills/improve-animations/PLAN-TEMPLATE.md +0 -73
  95. package/.claude/skills/improve-animations/SKILL.md +0 -109
  96. package/.claude/skills/mobile-native/SKILL.md +0 -311
  97. package/.claude/skills/pick-ui-library/SKILL.md +0 -85
  98. package/.claude/skills/prototype/PICKER.md +0 -197
  99. package/.claude/skills/prototype/SKILL.md +0 -98
  100. package/.claude/skills/review-animations/SKILL.md +0 -120
  101. package/.claude/skills/review-animations/STANDARDS.md +0 -187
  102. package/.claude/skills/write-swift/SKILL.md +0 -396
  103. package/lib/intern-catalog.js +0 -53
@@ -7,10 +7,16 @@
7
7
  const fs = require('fs');
8
8
  const path = require('path');
9
9
  const { HOSTS, getHost, guardrailSupport } = require('./hosts/registry.js');
10
+ const { atomicWrite, jsonText } = require('./fsutil.js');
10
11
 
11
12
  const HOOK_MARKER = 'ai-engineering-loop guard check';
13
+ // Matches pinned (ai-engineering-loop@x.y.z) and older unpinned commands.
14
+ const HOOK_PATTERN = /ai-engineering-loop(?:@\S+)? guard check/;
12
15
  const CLAUDE_MATCHER = 'Edit|Write|MultiEdit|NotebookEdit|Bash';
13
- const CLAUDE_COMMAND = 'npx --yes ai-engineering-loop guard check --hook claude';
16
+ const { version: PACKAGE_VERSION } = require('../package.json');
17
+
18
+ // Pinned so a hook never resolves whatever version the registry serves today.
19
+ const CLAUDE_COMMAND = `npx --yes ai-engineering-loop@${PACKAGE_VERSION} guard check --hook claude`;
14
20
 
15
21
  function hooksError(message, code = 'INVALID_USAGE') {
16
22
  const error = new Error(message);
@@ -46,14 +52,11 @@ function readSettings(filePath) {
46
52
  }
47
53
 
48
54
  function writeSettings(filePath, value) {
49
- fs.mkdirSync(path.dirname(filePath), { recursive: true });
50
- const temporary = `${filePath}.${process.pid}.tmp`;
51
- fs.writeFileSync(temporary, `${JSON.stringify(value, null, 2)}\n`);
52
- fs.renameSync(temporary, filePath);
55
+ atomicWrite(filePath, jsonText(value));
53
56
  }
54
57
 
55
58
  function isOurHook(hook) {
56
- return typeof hook?.command === 'string' && hook.command.includes(HOOK_MARKER);
59
+ return typeof hook?.command === 'string' && HOOK_PATTERN.test(hook.command);
57
60
  }
58
61
 
59
62
  function ourEntries(settings) {
@@ -76,7 +79,23 @@ function installHooks(rootDir, { host: hostId = 'claude' } = {}) {
76
79
  const host = hookHost(hostId);
77
80
  const filePath = settingsPath(rootDir, host);
78
81
  const settings = readSettings(filePath);
79
- if (ourEntries(settings).length) return { ...hooksStatus(rootDir, { host: host.id }), changed: false };
82
+ const existing = ourEntries(settings);
83
+ if (existing.length) {
84
+ const current = existing.every((entry) => entry.hooks.every((hook) => !isOurHook(hook) || hook.command === CLAUDE_COMMAND));
85
+ if (current) return { ...hooksStatus(rootDir, { host: host.id }), changed: false };
86
+ // Re-pin hooks written by an older install (unpinned or another version).
87
+ writeSettings(filePath, {
88
+ ...settings,
89
+ hooks: {
90
+ ...settings.hooks,
91
+ PreToolUse: settings.hooks.PreToolUse.map((entry) => ({
92
+ ...entry,
93
+ hooks: (entry.hooks || []).map((hook) => (isOurHook(hook) ? { ...hook, command: CLAUDE_COMMAND } : hook))
94
+ }))
95
+ }
96
+ });
97
+ return { ...hooksStatus(rootDir, { host: host.id }), changed: true };
98
+ }
80
99
  const hooks = settings.hooks && typeof settings.hooks === 'object' ? settings.hooks : {};
81
100
  const preToolUse = Array.isArray(hooks.PreToolUse) ? hooks.PreToolUse : [];
82
101
  writeSettings(filePath, {
package/lib/guard.js CHANGED
@@ -8,6 +8,7 @@
8
8
 
9
9
  const fs = require('fs');
10
10
  const path = require('path');
11
+ const { readJsonOptional } = require('./fsutil.js');
11
12
  const { RUN_MODES, TERMINAL_STATES, atomicWriteJson, getCurrentRun, loadRun, runsDir } = require('./run-state.js');
12
13
  const { loadPolicy } = require('./runtime-policy.js');
13
14
  const { redactHomePaths, redactSecrets } = require('./safe-context.js');
@@ -48,12 +49,14 @@ function parseGuardInput(input, tool) {
48
49
  };
49
50
  }
50
51
 
51
- // Shell segments split on ; && || | and newlines; quotes are kept simple on
52
+ // Shell segments split on ; && || | & and newlines; quotes are kept simple on
52
53
  // purpose: a quoted "rm -rf" still warns, which errs on the safe side.
53
54
  function segments(command) {
54
55
  return String(command || '')
55
- .split(/\n|;|&&|\|\||\|/)
56
- .map((part) => part.trim().split(/\s+/).filter(Boolean).map((token) => token.replace(/^['"]|['"]$/g, '')))
56
+ .split(/\n|;|&&|\|\||\||&/)
57
+ .map((part) => part.trim().split(/\s+/).filter(Boolean)
58
+ // `\rm` and `"rm"` bypass aliases but run the same binary.
59
+ .map((token) => token.replace(/^['"]|['"]$/g, '').replace(/^\\+/, '')))
57
60
  .filter((tokens) => tokens.length);
58
61
  }
59
62
 
@@ -113,6 +116,50 @@ const DESTRUCTIVE_RULES = Object.freeze([
113
116
  return git?.name === 'reset' && git.args.includes('--hard');
114
117
  }
115
118
  },
119
+ {
120
+ id: 'find-delete',
121
+ reason: 'find -delete removes every matching file without confirmation',
122
+ test: (tokens) => {
123
+ const start = commandIndex(tokens, 'find');
124
+ if (start === -1) return false;
125
+ const args = tokens.slice(start + 1);
126
+ const exec = args.findIndex((arg) => arg === '-exec' || arg === '-execdir' || arg === '-ok');
127
+ return args.includes('-delete') || (exec !== -1 && commandIndex(args.slice(exec + 1), 'rm') === 0);
128
+ }
129
+ },
130
+ {
131
+ id: 'git-checkout-discard',
132
+ reason: 'git checkout -- <paths> (or --force) discards uncommitted work',
133
+ test: (tokens) => {
134
+ const git = gitSubcommand(tokens);
135
+ if (git?.name !== 'checkout') return false;
136
+ return git.args.includes('--') || git.args.includes('.') || git.args.includes('--force') ||
137
+ /f/.test(shortFlags(git.args));
138
+ }
139
+ },
140
+ {
141
+ id: 'git-restore',
142
+ reason: 'git restore discards uncommitted work in the working tree',
143
+ test: (tokens) => {
144
+ const git = gitSubcommand(tokens);
145
+ if (git?.name !== 'restore') return false;
146
+ const stagedOnly = (git.args.includes('--staged') || /S/.test(shortFlags(git.args))) &&
147
+ !git.args.includes('--worktree') && !/W/.test(shortFlags(git.args));
148
+ return !stagedOnly;
149
+ }
150
+ },
151
+ {
152
+ id: 'git-branch-force-delete',
153
+ reason: 'git branch -D deletes a branch even when it is not merged',
154
+ test: (tokens) => {
155
+ const git = gitSubcommand(tokens);
156
+ if (git?.name !== 'branch') return false;
157
+ const flags = shortFlags(git.args);
158
+ const remove = /d/i.test(flags) || git.args.includes('--delete');
159
+ const force = flags.includes('D') || flags.includes('f') || git.args.includes('--force');
160
+ return remove && force;
161
+ }
162
+ },
116
163
  {
117
164
  id: 'git-clean-force',
118
165
  reason: 'git clean -fd deletes untracked files and directories',
@@ -153,12 +200,7 @@ function activeRun(rootDir, runId) {
153
200
 
154
201
  function readFrozenGoal(rootDir, run) {
155
202
  const filePath = path.join(runsDir(rootDir), run.runId, 'goal-contract.json');
156
- if (!fs.existsSync(filePath)) return null;
157
- try {
158
- return JSON.parse(fs.readFileSync(filePath, 'utf8'));
159
- } catch {
160
- return null;
161
- }
203
+ return readJsonOptional(filePath);
162
204
  }
163
205
 
164
206
  // Allowed = the frozen Goal's scope.allowedPaths plus the confirmed impact
@@ -212,10 +254,45 @@ function repoRelative(rootDir, filePath) {
212
254
  return null;
213
255
  }
214
256
 
257
+ // CLI-owned Run ledgers and evidence. Agents produce their artifacts through
258
+ // gates and the recorder; a direct edit here could forge verification or
259
+ // replay state, so it is never exempt like the rest of .ai-engineering-loop/.
260
+ const RUN_EVIDENCE_FILES = new Set([
261
+ 'state.json',
262
+ 'plan.json',
263
+ 'workflow-state.json',
264
+ 'events.jsonl',
265
+ 'lifecycle.jsonl',
266
+ 'interactions.jsonl',
267
+ 'verification.json',
268
+ 'verification-summary.json',
269
+ 'sandbox-evidence.json',
270
+ 'impact-map.json',
271
+ 'impact-drift.json',
272
+ 'guard-events.json',
273
+ 'receipt.json',
274
+ 'receipt.md',
275
+ 'CANCELLED'
276
+ ]);
277
+
278
+ function runEvidenceFinding(relative) {
279
+ const parts = relative.split('/');
280
+ if (parts[0] !== '.ai-engineering-loop' || parts[1] !== 'runs') return null;
281
+ const protectedFile = (parts.length === 3 && parts[2] === 'current.json') ||
282
+ (parts.length === 4 && RUN_EVIDENCE_FILES.has(parts[3])) ||
283
+ (parts.length >= 4 && parts[3].toLowerCase().startsWith('verification'));
284
+ return protectedFile
285
+ ? { id: 'run-evidence', reason: `${relative} is CLI-owned Run evidence; use the CLI instead of editing it` }
286
+ : null;
287
+ }
288
+
215
289
  function scopeFindings(rootDir, filePath, scope) {
216
290
  if (!filePath) return [];
217
291
  const relative = repoRelative(rootDir, filePath);
218
- if (relative != null && (relative === '.ai-engineering-loop' || relative.startsWith('.ai-engineering-loop/'))) return [];
292
+ if (relative != null && (relative === '.ai-engineering-loop' || relative.startsWith('.ai-engineering-loop/'))) {
293
+ const evidence = runEvidenceFinding(relative);
294
+ return evidence ? [evidence] : [];
295
+ }
219
296
  if (relative == null) {
220
297
  return scope.allowedPaths ? [{ id: 'outside-repository', reason: 'edit target is outside the repository and the Run scope' }] : [];
221
298
  }
@@ -289,6 +366,18 @@ function checkGuard(rootDir, { tool, input, runId, now = new Date() } = {}) {
289
366
  return result;
290
367
  }
291
368
 
369
+ // When guard check itself fails inside a hook, fail closed unless the Run is
370
+ // ASSISTED (a human is approving each call anyway).
371
+ function hookFailureExitCode(rootDir, runId) {
372
+ let mode = null;
373
+ try {
374
+ mode = activeRun(rootDir, runId)?.mode || loadPolicy(rootDir).defaultMode;
375
+ } catch {
376
+ mode = null;
377
+ }
378
+ return mode === RUN_MODES.ASSISTED ? 1 : 2;
379
+ }
380
+
292
381
  function loadGuardEvents(rootDir, runId) {
293
382
  const filePath = path.join(runsDir(rootDir), runId, GUARD_EVENTS_FILE);
294
383
  if (!fs.existsSync(filePath)) return [];
@@ -330,6 +419,7 @@ module.exports = {
330
419
  destructiveFindings,
331
420
  runScope,
332
421
  checkGuard,
422
+ hookFailureExitCode,
333
423
  loadGuardEvents,
334
424
  guardSummary,
335
425
  claudeHookOutput
@@ -4,18 +4,14 @@
4
4
  // skill it can see across the folders it scans, whether they are identical,
5
5
  // and which AEL files a sync would still write. Read-only.
6
6
 
7
- const crypto = require('crypto');
8
7
  const fs = require('fs');
9
8
  const path = require('path');
9
+ const { sha256 } = require('../fsutil.js');
10
10
  const { HOSTS, guardrailSupport, usesSharedSkills } = require('./registry.js');
11
11
  const { certificationLabel } = require('./table.js');
12
12
 
13
13
  const CORE_SKILL = 'ai-engineering-loop';
14
14
 
15
- function sha256(buf) {
16
- return crypto.createHash('sha256').update(buf).digest('hex');
17
- }
18
-
19
15
  function realOrSelf(file) {
20
16
  try {
21
17
  return fs.realpathSync(file);
package/lib/impact-map.js CHANGED
@@ -5,9 +5,9 @@
5
5
  // Stage 3 (Maker). A human confirms or edits it; the confirmed paths become
6
6
  // the Run's allowed scope (#59), and verify reports drift outside it.
7
7
 
8
- const crypto = require('crypto');
9
8
  const fs = require('fs');
10
9
  const path = require('path');
10
+ const { ACTOR_ID, readJsonOptional, sha256: hashBytes } = require('./fsutil.js');
11
11
  const { atomicWriteJson, getCurrentRun, loadRun, runsDir } = require('./run-state.js');
12
12
  const { sha256 } = require('./recipe.js');
13
13
 
@@ -329,7 +329,7 @@ function writeMap(rootDir, run, map) {
329
329
 
330
330
  function actorId(actor) {
331
331
  const value = String(actor || '').trim();
332
- if (!/^[A-Za-z0-9@._-]{1,64}$/.test(value)) {
332
+ if (!ACTOR_ID.test(value)) {
333
333
  throw impactError('--by <name> must be a short account identifier', 'INVALID_USAGE');
334
334
  }
335
335
  return value;
@@ -434,7 +434,7 @@ function detectImpactDrift(rootDir, { runId, now = new Date() } = {}) {
434
434
  const drift = {
435
435
  schemaVersion: 1,
436
436
  runId: run.runId,
437
- diffHash: crypto.createHash('sha256').update(raw).digest('hex'),
437
+ diffHash: hashBytes(raw),
438
438
  mapStatus: map ? map.status : 'MISSING',
439
439
  ...(map?.status === 'SKIPPED' ? { skipReason: map.skipReason } : {}),
440
440
  checkedAt: now.toISOString(),
@@ -448,12 +448,7 @@ function detectImpactDrift(rootDir, { runId, now = new Date() } = {}) {
448
448
 
449
449
  function loadImpactDrift(rootDir, runId) {
450
450
  const filePath = driftPath(rootDir, runId);
451
- if (!fs.existsSync(filePath)) return null;
452
- try {
453
- return JSON.parse(fs.readFileSync(filePath, 'utf8'));
454
- } catch {
455
- return null;
456
- }
451
+ return readJsonOptional(filePath);
457
452
  }
458
453
 
459
454
  function driftFindings(drift) {
@@ -0,0 +1,104 @@
1
+ 'use strict';
2
+
3
+ // Append-only, hash-chained JSONL ledger inside a Run directory, shared by run
4
+ // interactions and run lifecycle. One writer at a time (a lock file next to
5
+ // the ledger), each event hashes its own material including the previous
6
+ // event's hash, and reads reject a ledger that was edited, reordered, or grew
7
+ // past its bound.
8
+
9
+ const fs = require('fs');
10
+ const path = require('path');
11
+ const { sha256 } = require('./recipe.js');
12
+ const { assertRunId, loadRun, runsDir } = require('./run-state.js');
13
+ const { repairJsonlTail, splitJsonlLines } = require('./runtime-files.js');
14
+
15
+ const LOCK_STALE_MS = 60_000;
16
+
17
+ function ledgerError(message, code) {
18
+ const error = new Error(message);
19
+ error.code = code;
20
+ return error;
21
+ }
22
+
23
+ function materialHash(event) {
24
+ const { hash, ...material } = event;
25
+ return sha256(material);
26
+ }
27
+
28
+ // fileName: ledger file inside the Run directory. types: allowed event types.
29
+ // codes/messages: what callers see when the ledger is busy or invalid.
30
+ function createLedger({ fileName, maxBytes, types, codes, messages }) {
31
+ function ledgerPath(rootDir, runId) {
32
+ assertRunId(runId);
33
+ loadRun(rootDir, runId);
34
+ return path.join(runsDir(rootDir), runId, fileName);
35
+ }
36
+
37
+ function read(rootDir, runId) {
38
+ const file = ledgerPath(rootDir, runId);
39
+ if (!fs.existsSync(file)) return [];
40
+ const stat = fs.lstatSync(file);
41
+ if (stat.isSymbolicLink() || !stat.isFile() || stat.nlink !== 1 || stat.size > maxBytes) {
42
+ throw ledgerError(messages.bounded, codes.invalid);
43
+ }
44
+ const events = splitJsonlLines(fs.readFileSync(file, 'utf8')).lines.map((line) => {
45
+ try { return JSON.parse(line); } catch { return null; }
46
+ });
47
+ let previousHash = null;
48
+ for (const [index, event] of events.entries()) {
49
+ if (!event || event.runId !== runId || event.sequence !== index + 1 ||
50
+ event.previousHash !== previousHash || event.hash !== materialHash(event) ||
51
+ !types.has(event.type)) {
52
+ throw ledgerError(`${messages.event} ${index + 1} failed integrity validation`, codes.invalid);
53
+ }
54
+ previousHash = event.hash;
55
+ }
56
+ return events;
57
+ }
58
+
59
+ function withLock(rootDir, runId, operation) {
60
+ const lock = `${ledgerPath(rootDir, runId)}.lock`;
61
+ let descriptor;
62
+ try {
63
+ try {
64
+ descriptor = fs.openSync(lock, 'wx', 0o600);
65
+ } catch (error) {
66
+ if (error.code !== 'EEXIST') throw error;
67
+ const stat = fs.lstatSync(lock);
68
+ if (stat.isSymbolicLink() || !stat.isFile() || Date.now() - stat.mtimeMs <= LOCK_STALE_MS) {
69
+ throw ledgerError(messages.busy, codes.busy);
70
+ }
71
+ fs.unlinkSync(lock);
72
+ descriptor = fs.openSync(lock, 'wx', 0o600);
73
+ }
74
+ // A crash mid-append can leave a torn last line; repair it before the
75
+ // writer reads and appends so a new record never fuses with it.
76
+ repairJsonlTail(ledgerPath(rootDir, runId));
77
+ return operation();
78
+ } finally {
79
+ if (descriptor != null) {
80
+ fs.closeSync(descriptor);
81
+ try { fs.unlinkSync(lock); } catch {}
82
+ }
83
+ }
84
+ }
85
+
86
+ // Call inside withLock, with the events just read.
87
+ function append(rootDir, runId, events, fields, now) {
88
+ const material = {
89
+ schemaVersion: 1,
90
+ runId,
91
+ sequence: events.length + 1,
92
+ previousHash: events.at(-1)?.hash || null,
93
+ at: now.toISOString(),
94
+ ...fields
95
+ };
96
+ const event = { ...material, hash: sha256(material) };
97
+ fs.appendFileSync(ledgerPath(rootDir, runId), `${JSON.stringify(event)}\n`, { encoding: 'utf8', mode: 0o600, flag: 'a' });
98
+ return event;
99
+ }
100
+
101
+ return { read, withLock, append };
102
+ }
103
+
104
+ module.exports = { createLedger };
package/lib/learn.js CHANGED
@@ -6,9 +6,9 @@
6
6
  // .ai-engineering-loop/learnings.json (+ learnings.md). Context packs inject
7
7
  // the most relevant entries within their token budget.
8
8
 
9
- const crypto = require('crypto');
10
9
  const fs = require('fs');
11
10
  const path = require('path');
11
+ const { readJsonOptional, sha256 } = require('./fsutil.js');
12
12
  const { atomicWriteJson, atomicWritePrivateFile, runsDir } = require('./run-state.js');
13
13
  const { listRunHistory } = require('./run-history.js');
14
14
  const { estimateTokens, redactHomePaths, redactSecrets } = require('./safe-context.js');
@@ -98,13 +98,8 @@ function isLesson(finding) {
98
98
 
99
99
  function readExisting(rootDir) {
100
100
  const filePath = learningsPath(rootDir);
101
- if (!fs.existsSync(filePath)) return null;
102
- try {
103
- const value = JSON.parse(fs.readFileSync(filePath, 'utf8'));
104
- return value?.schemaVersion === 1 ? value : null;
105
- } catch {
106
- return null;
107
- }
101
+ const value = readJsonOptional(filePath);
102
+ return value?.schemaVersion === 1 ? value : null;
108
103
  }
109
104
 
110
105
  function collectOccurrences(rootDir) {
@@ -137,7 +132,7 @@ function clusterOccurrences(occurrences) {
137
132
  const cluster = clusters.find((entry) => entry.axis === item.axis && jaccard(entry.words, item.words) >= CLUSTER_THRESHOLD);
138
133
  if (!cluster) {
139
134
  clusters.push({
140
- id: `L-${crypto.createHash('sha256').update(`${item.axis}|${item.words.join(' ')}`).digest('hex').slice(0, 10)}`,
135
+ id: `L-${sha256(`${item.axis}|${item.words.join(' ')}`).slice(0, 10)}`,
141
136
  axis: item.axis,
142
137
  words: item.words,
143
138
  items: [item]
@@ -6,10 +6,6 @@ const MAX_LOOP_GROUPS = 16;
6
6
  const MAX_LOOP_ITERATIONS = 100;
7
7
  const MAX_LOOP_LABEL = 40;
8
8
 
9
- function clone(value) {
10
- return JSON.parse(JSON.stringify(value));
11
- }
12
-
13
9
  function reachable(edges, from, to, allowed) {
14
10
  const pending = [from];
15
11
  const seen = new Set();
@@ -114,31 +110,10 @@ function validateLoopGroups(recipe) {
114
110
  return { valid: errors.length === 0, errors: [...new Set(errors)] };
115
111
  }
116
112
 
117
- function createLoopGroup(recipe, group) {
118
- const next = clone(recipe);
119
- next.loopGroups = [...(next.loopGroups || []), clone(group)];
120
- const validation = validateLoopGroups(next);
121
- if (!validation.valid) {
122
- const error = new Error(`Loop Group is invalid: ${validation.errors.join('; ')}`);
123
- error.code = 'INVALID_LOOP_GROUP';
124
- error.details = validation.errors;
125
- throw error;
126
- }
127
- return next;
128
- }
129
-
130
- function removeLoopGroup(recipe, groupId) {
131
- const next = clone(recipe);
132
- next.loopGroups = (next.loopGroups || []).filter((group) => group.id !== groupId);
133
- return next;
134
- }
135
-
136
113
  module.exports = {
137
114
  LOOP_ID,
138
115
  MAX_LOOP_GROUPS,
139
116
  MAX_LOOP_ITERATIONS,
140
117
  MAX_LOOP_LABEL,
141
- createLoopGroup,
142
- removeLoopGroup,
143
118
  validateLoopGroups
144
119
  };
package/lib/migrations.js CHANGED
@@ -47,10 +47,6 @@ function pendingMigrations({ from, to, dir = MIGRATIONS_DIR }) {
47
47
  return loadMigrations(dir).filter((m) => m.major > fromMajor && m.major <= toMajor);
48
48
  }
49
49
 
50
- function crossesMajor(from, to) {
51
- return parseVersion(to)[0] > parseVersion(from)[0];
52
- }
53
-
54
50
  function runMigrations({ from, to, projects = [], home = homeDir(), dir = MIGRATIONS_DIR, dryRun = false, now = new Date() }) {
55
51
  const statePath = userStatePath('migrations.json', home);
56
52
  const state = readJsonFile(statePath, { schemaVersion: 1, applied: {} });
@@ -81,4 +77,4 @@ function runMigrations({ from, to, projects = [], home = homeDir(), dir = MIGRAT
81
77
  return { from, to, migrations: report };
82
78
  }
83
79
 
84
- module.exports = { MIGRATIONS_DIR, loadMigrations, pendingMigrations, crossesMajor, runMigrations };
80
+ module.exports = { MIGRATIONS_DIR, loadMigrations, pendingMigrations, runMigrations };
@@ -0,0 +1,119 @@
1
+ 'use strict';
2
+
3
+ // Iteration ceiling from the run's recipe and no-progress detection between
4
+ // Judge iterations (iteration-policy.md, no-progress-policy.md).
5
+
6
+ const crypto = require('crypto');
7
+ const fs = require('fs');
8
+ const path = require('path');
9
+ const { runsDir } = require('./run-state.js');
10
+
11
+ const DEFAULT_MAX_ITERATIONS = 3;
12
+ const MAX_ITERATIONS_CEILING = 5;
13
+ const ITERATIONS_FILE = 'iterations.jsonl';
14
+
15
+ function clampIterations(value) {
16
+ if (!Number.isSafeInteger(value)) return DEFAULT_MAX_ITERATIONS;
17
+ return Math.min(MAX_ITERATIONS_CEILING, Math.max(1, value));
18
+ }
19
+
20
+ // The loop group that decides at the Judge node sets the ceiling. Runs without
21
+ // a workflow (legacy) or with an unreadable plan keep the default.
22
+ function runMaxIterations(rootDir, run) {
23
+ if (!run?.workflow) return DEFAULT_MAX_ITERATIONS;
24
+ let plan;
25
+ try {
26
+ plan = JSON.parse(fs.readFileSync(path.join(runsDir(rootDir), run.runId, 'plan.json'), 'utf8'));
27
+ } catch {
28
+ return DEFAULT_MAX_ITERATIONS;
29
+ }
30
+ const judgeIds = new Set((plan.nodes || [])
31
+ .filter((node) => node && (node.legacyGate === 'judge' || node.type === 'judge'))
32
+ .map((node) => node.id));
33
+ const group = (plan.loopGroups || []).find((candidate) => judgeIds.has(candidate.decisionNodeId))
34
+ || (plan.loopGroups || []).find((candidate) => (candidate.nodeIds || []).some((id) => judgeIds.has(id)));
35
+ return group ? clampIterations(group.maxIterations) : DEFAULT_MAX_ITERATIONS;
36
+ }
37
+
38
+ function normalizeText(value) {
39
+ return String(value || '').toLowerCase().replace(/\s+/g, ' ').trim();
40
+ }
41
+
42
+ function findingSignature(finding) {
43
+ return crypto.createHash('sha256')
44
+ .update(`${normalizeText(finding.location)}\n${normalizeText(finding.failureScenario)}`)
45
+ .digest('hex')
46
+ .slice(0, 16);
47
+ }
48
+
49
+ function iterationsPath(rootDir, runId) {
50
+ return path.join(runsDir(rootDir), runId, ITERATIONS_FILE);
51
+ }
52
+
53
+ function readIterations(rootDir, runId) {
54
+ let text;
55
+ try {
56
+ text = fs.readFileSync(iterationsPath(rootDir, runId), 'utf8');
57
+ } catch {
58
+ return [];
59
+ }
60
+ const entries = [];
61
+ for (const line of text.split('\n')) {
62
+ if (!line.trim()) continue;
63
+ try {
64
+ entries.push(JSON.parse(line));
65
+ } catch {
66
+ // A torn trailing line is ignored; the next append starts a fresh line.
67
+ }
68
+ }
69
+ return entries;
70
+ }
71
+
72
+ // Returns the NO_PROGRESS reason when this ITERATE repeats the previous
73
+ // iteration: the same non-empty blocking findings, or an unchanged diff.
74
+ function detectNoProgress(rootDir, run, { diffHash, blockingFindings = [] }) {
75
+ const previous = readIterations(rootDir, run.runId)
76
+ .filter((entry) => entry.verdict === 'ITERATE' && entry.iteration < run.iteration)
77
+ .pop();
78
+ if (!previous) return null;
79
+ if (diffHash && previous.diffHash === diffHash) {
80
+ return `NO_PROGRESS: iteration ${run.iteration} has the same Maker diff as iteration ${previous.iteration}`;
81
+ }
82
+ const signatures = blockingFindings.map(findingSignature).sort();
83
+ const before = [...(previous.blockingSignatures || [])].sort();
84
+ if (signatures.length && signatures.length === before.length && signatures.every((sig, i) => sig === before[i])) {
85
+ return `NO_PROGRESS: iteration ${run.iteration} repeats the blocking findings of iteration ${previous.iteration}`;
86
+ }
87
+ return null;
88
+ }
89
+
90
+ function recordIteration(rootDir, run, { verdict, diffHash, blockingFindings = [], now = new Date() }) {
91
+ const entry = {
92
+ iteration: run.iteration,
93
+ verdict,
94
+ diffHash: diffHash || null,
95
+ blockingSignatures: blockingFindings.map(findingSignature),
96
+ at: now.toISOString()
97
+ };
98
+ const filePath = iterationsPath(rootDir, run.runId);
99
+ let prefix = '';
100
+ try {
101
+ const current = fs.readFileSync(filePath, 'utf8');
102
+ if (current && !current.endsWith('\n')) prefix = '\n';
103
+ } catch {
104
+ // first entry
105
+ }
106
+ fs.appendFileSync(filePath, `${prefix}${JSON.stringify(entry)}\n`, { mode: 0o600 });
107
+ return entry;
108
+ }
109
+
110
+ module.exports = {
111
+ DEFAULT_MAX_ITERATIONS,
112
+ MAX_ITERATIONS_CEILING,
113
+ ITERATIONS_FILE,
114
+ runMaxIterations,
115
+ findingSignature,
116
+ readIterations,
117
+ detectNoProgress,
118
+ recordIteration
119
+ };
@@ -4,9 +4,9 @@
4
4
  // proof in state.json artifacts and run files, not on workflow nodes.
5
5
  // nodes[id].artifact stays authoritative for agent and artifact-check nodes.
6
6
 
7
- const crypto = require('crypto');
8
7
  const fs = require('fs');
9
8
  const path = require('path');
9
+ const { sha256: sha256Bytes } = require('./fsutil.js');
10
10
  const { runsDir } = require('./run-state.js');
11
11
  const { readAllRunLifecycle } = require('./run-lifecycle.js');
12
12
  const { isBlockingFinding } = require('./orchestration.js');
@@ -46,10 +46,6 @@ const BOUNDARY_TYPES = new Set([
46
46
  'WORKFLOW_EXECUTION_STARTED'
47
47
  ]);
48
48
 
49
- function sha256Bytes(bytes) {
50
- return crypto.createHash('sha256').update(bytes).digest('hex');
51
- }
52
-
53
49
  function runDirectory(rootDir, runId) {
54
50
  return path.join(runsDir(rootDir), runId);
55
51
  }