ai-engineering-loop 2.2.0 → 2.4.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 (133) 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-risky.md +1 -0
  7. package/.agents/skills/ai-engineering-loop/references/loop-verify.md +3 -3
  8. package/.claude/agents/judge.md +5 -2
  9. package/.grok/agents/judge.md +5 -2
  10. package/CHANGELOG.md +60 -0
  11. package/README.md +1 -0
  12. package/THIRD_PARTY_NOTICES.md +11 -0
  13. package/adapters/spec/LICENSE +202 -0
  14. package/adapters/spec/NOTICE-AEL.md +26 -0
  15. package/adapters/spec/agents/ael-spec-codebase-details.md +71 -0
  16. package/adapters/spec/agents/ael-spec-comprehension.md +71 -0
  17. package/adapters/spec/agents/ael-spec-design.md +65 -0
  18. package/adapters/spec/agents/ael-spec-implementation-readiness.md +64 -0
  19. package/adapters/spec/agents/ael-spec-structural.md +67 -0
  20. package/adapters/spec/agents/ael-spec-style.md +68 -0
  21. package/adapters/spec/agents/ael-spec-synthesizer.md +73 -0
  22. package/adapters/spec/agents/ael-spec-zoom-out.md +76 -0
  23. package/adapters/spec/skills/ael-spec-brainstorm/SKILL.md +265 -0
  24. package/adapters/spec/skills/ael-spec-draft/SKILL.md +315 -0
  25. package/adapters/spec/skills/ael-spec-draft/references/design_doc.md +179 -0
  26. package/adapters/spec/skills/ael-spec-drift/SKILL.md +68 -0
  27. package/adapters/spec/skills/ael-spec-resolve/SKILL.md +188 -0
  28. package/adapters/spec/skills/ael-spec-review/SKILL.md +403 -0
  29. package/adapters/spec/skills/ael-spec-review-loop/SKILL.md +191 -0
  30. package/adapters/spec/standards/ael-spec-execution-instructions.md +36 -0
  31. package/adapters/spec/standards/ael-spec-feature-spec-standard.md +38 -0
  32. package/adapters/spec/standards/ael-spec-heilmeier-standard.md +32 -0
  33. package/adapters/spec/standards/ael-spec-implementation-readiness-standard.md +36 -0
  34. package/adapters/spec/standards/ael-spec-re-implementation-standard.md +39 -0
  35. package/adapters/spec/standards/ael-spec-zoom-out-standard.md +62 -0
  36. package/agents/maker.md +1 -1
  37. package/agents/shared/judge.body.md +5 -2
  38. package/bin/ai-engineering-loop.js +344 -78
  39. package/core/definition-of-done.md +2 -2
  40. package/core/escalation-policy.md +1 -1
  41. package/core/goal-contract.md +1 -1
  42. package/core/iteration-policy.md +2 -1
  43. package/core/judge-policy.md +10 -4
  44. package/core/orchestration-model.md +8 -7
  45. package/core/repo-config-schema.md +2 -2
  46. package/core/runtime-safety.md +3 -3
  47. package/core/spec-pack.md +47 -0
  48. package/lib/auto-update.js +8 -14
  49. package/lib/claimed-vs-reality.js +2 -2
  50. package/lib/cli-args.js +3 -1
  51. package/lib/design-ref.js +178 -0
  52. package/lib/docs.js +1 -1
  53. package/lib/doctor.js +0 -6
  54. package/lib/escalation.js +1 -1
  55. package/lib/fsutil.js +88 -0
  56. package/lib/gates.js +70 -27
  57. package/lib/generate-workflow.js +0 -29
  58. package/lib/goal-runtime.js +8 -2
  59. package/lib/guard-hooks.js +26 -7
  60. package/lib/guard.js +100 -10
  61. package/lib/hosts/doctor.js +17 -7
  62. package/lib/impact-map.js +31 -8
  63. package/lib/jsonl-ledger.js +104 -0
  64. package/lib/learn.js +4 -9
  65. package/lib/loop-groups.js +0 -25
  66. package/lib/migrations.js +1 -5
  67. package/lib/no-progress.js +119 -0
  68. package/lib/node-evidence.js +1 -5
  69. package/lib/orchestration.js +5 -361
  70. package/lib/personal-workflow.js +1 -1
  71. package/lib/quick.js +152 -0
  72. package/lib/receipt.js +13 -6
  73. package/lib/recipe-builder.js +3 -35
  74. package/lib/recipe-graph.js +2 -63
  75. package/lib/recipe.js +2 -4
  76. package/lib/review-ingest.js +116 -0
  77. package/lib/run-abandon.js +2 -1
  78. package/lib/run-compaction.js +4 -12
  79. package/lib/run-interactions.js +16 -71
  80. package/lib/run-lifecycle.js +25 -77
  81. package/lib/run-state.js +68 -17
  82. package/lib/run-watcher.js +11 -14
  83. package/lib/runtime-files.js +45 -1
  84. package/lib/safe-context.js +17 -6
  85. package/lib/sandbox.js +2 -1
  86. package/lib/smart-context.js +13 -14
  87. package/lib/spawn-command.js +94 -0
  88. package/lib/studio-layout.js +2 -8
  89. package/lib/studio-runtime.js +2 -1
  90. package/lib/studio-server.js +25 -5
  91. package/lib/sync-hosts.js +25 -2
  92. package/lib/tier.js +36 -10
  93. package/lib/user-state.js +2 -17
  94. package/lib/verification-lanes.js +115 -0
  95. package/lib/verification-recorder.js +110 -22
  96. package/lib/workflow-runtime.js +7 -4
  97. package/package.json +1 -2
  98. package/policies/review-budget.md +1 -1
  99. package/schemas/goal-contract.schema.json +87 -11
  100. package/.claude/skills/ai-engineering-loop/SKILL.md +0 -62
  101. package/.claude/skills/ai-engineering-loop/references/loop-commands.md +0 -24
  102. package/.claude/skills/ai-engineering-loop/references/loop-deliver.md +0 -10
  103. package/.claude/skills/ai-engineering-loop/references/loop-goal.md +0 -11
  104. package/.claude/skills/ai-engineering-loop/references/loop-hosts.md +0 -48
  105. package/.claude/skills/ai-engineering-loop/references/loop-maker.md +0 -14
  106. package/.claude/skills/ai-engineering-loop/references/loop-review.md +0 -20
  107. package/.claude/skills/ai-engineering-loop/references/loop-risky.md +0 -9
  108. package/.claude/skills/ai-engineering-loop/references/loop-verify.md +0 -20
  109. package/.claude/skills/animate/RECIPES.md +0 -324
  110. package/.claude/skills/animate/SKILL.md +0 -207
  111. package/.claude/skills/animate-expo/RECIPES.md +0 -385
  112. package/.claude/skills/animate-expo/SKILL.md +0 -263
  113. package/.claude/skills/animation-vocabulary/SKILL.md +0 -181
  114. package/.claude/skills/apple-design/SKILL.md +0 -290
  115. package/.claude/skills/ask-sonner/API.md +0 -64
  116. package/.claude/skills/ask-sonner/SKILL.md +0 -88
  117. package/.claude/skills/backend-development/SKILL.md +0 -272
  118. package/.claude/skills/backend-development/references/api-design-guidelines.md +0 -95
  119. package/.claude/skills/backend-development/references/query-and-database-best-practices.md +0 -53
  120. package/.claude/skills/backend-development/references/security-checklist.md +0 -60
  121. package/.claude/skills/emil-design-eng/SKILL.md +0 -674
  122. package/.claude/skills/find-animation-opportunities/SKILL.md +0 -140
  123. package/.claude/skills/improve-animations/AUDIT.md +0 -115
  124. package/.claude/skills/improve-animations/PLAN-TEMPLATE.md +0 -73
  125. package/.claude/skills/improve-animations/SKILL.md +0 -109
  126. package/.claude/skills/mobile-native/SKILL.md +0 -311
  127. package/.claude/skills/pick-ui-library/SKILL.md +0 -85
  128. package/.claude/skills/prototype/PICKER.md +0 -197
  129. package/.claude/skills/prototype/SKILL.md +0 -98
  130. package/.claude/skills/review-animations/SKILL.md +0 -120
  131. package/.claude/skills/review-animations/STANDARDS.md +0 -187
  132. package/.claude/skills/write-swift/SKILL.md +0 -396
  133. package/lib/intern-catalog.js +0 -53
@@ -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
  }