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
package/lib/run-state.js CHANGED
@@ -4,6 +4,7 @@ const crypto = require('crypto');
4
4
  const fs = require('fs');
5
5
  const path = require('path');
6
6
  const { execFileSync } = require('child_process');
7
+ const { ACTOR_ID, renameWithRetry, sleepSync, writePrivateFile, writePrivateJson } = require('./fsutil.js');
7
8
 
8
9
  const RUN_STATES = Object.freeze({
9
10
  STARTED: 'STARTED',
@@ -57,25 +58,59 @@ function assertRunId(runId) {
57
58
  return runId;
58
59
  }
59
60
 
60
- function atomicWritePrivateFile(filePath, content) {
61
- fs.mkdirSync(path.dirname(filePath), { recursive: true });
62
- const temporary = `${filePath}.${process.pid}.${crypto.randomBytes(4).toString('hex')}.tmp`;
63
- try {
64
- fs.writeFileSync(temporary, content, { mode: 0o600 });
65
- fs.renameSync(temporary, filePath);
66
- fs.chmodSync(filePath, 0o600);
67
- } finally {
61
+ const LOCK_STALE_MS = 60_000;
62
+ const LOCK_WAIT_MS = 10_000;
63
+
64
+ // Exclusive lock for read-modify-write updates. Waits for a live holder and
65
+ // steals a lock older than LOCK_STALE_MS (a crashed writer). Never creates
66
+ // the lock's directory, so a lookup of an unknown Run leaves no trace.
67
+ function withFileLock(lockPath, operation, { waitMs = LOCK_WAIT_MS, staleMs = LOCK_STALE_MS } = {}) {
68
+ const deadline = Date.now() + waitMs;
69
+ let descriptor;
70
+ for (;;) {
68
71
  try {
69
- fs.unlinkSync(temporary);
70
- } catch {
71
- // Rename succeeded or no temporary file was written.
72
+ descriptor = fs.openSync(lockPath, 'wx', 0o600);
73
+ fs.writeSync(descriptor, `${process.pid}\n`);
74
+ break;
75
+ } catch (error) {
76
+ // No directory means nothing to protect yet; the operation reports it.
77
+ if (error.code === 'ENOENT') return operation();
78
+ if (error.code !== 'EEXIST') throw error;
79
+ let stale = false;
80
+ try {
81
+ const stat = fs.lstatSync(lockPath);
82
+ if (stat.isSymbolicLink() || !stat.isFile()) {
83
+ const err = new Error(`${path.basename(lockPath)} must be a regular file`);
84
+ err.code = 'UNSAFE_LOCK';
85
+ throw err;
86
+ }
87
+ stale = Date.now() - stat.mtimeMs > staleMs;
88
+ } catch (statError) {
89
+ if (statError.code === 'UNSAFE_LOCK') throw statError;
90
+ continue;
91
+ }
92
+ if (stale) {
93
+ try { fs.unlinkSync(lockPath); } catch {}
94
+ continue;
95
+ }
96
+ if (Date.now() >= deadline) {
97
+ const err = new Error(`Another update holds ${path.basename(lockPath)}; try again`);
98
+ err.code = 'RUN_STATE_BUSY';
99
+ throw err;
100
+ }
101
+ sleepSync(25);
72
102
  }
73
103
  }
104
+ try {
105
+ return operation();
106
+ } finally {
107
+ fs.closeSync(descriptor);
108
+ try { fs.unlinkSync(lockPath); } catch {}
109
+ }
74
110
  }
75
111
 
76
- function atomicWriteJson(filePath, value) {
77
- atomicWritePrivateFile(filePath, `${JSON.stringify(value, null, 2)}\n`);
78
- }
112
+ const atomicWritePrivateFile = writePrivateFile;
113
+ const atomicWriteJson = writePrivateJson;
79
114
 
80
115
  function readJson(filePath, label) {
81
116
  try {
@@ -300,7 +335,15 @@ function createOrResumeRun(
300
335
  };
301
336
  }
302
337
 
303
- function updateRunDisplayName(rootDir, runId, displayName, { actor = 'human', now = new Date() } = {}) {
338
+ function runStateLockPath(rootDir, runId) {
339
+ return `${runStatePath(rootDir, runId)}.lock`;
340
+ }
341
+
342
+ function updateRunDisplayName(rootDir, runId, displayName, options = {}) {
343
+ return withFileLock(runStateLockPath(rootDir, runId), () => updateRunDisplayNameLocked(rootDir, runId, displayName, options));
344
+ }
345
+
346
+ function updateRunDisplayNameLocked(rootDir, runId, displayName, { actor = 'human', now = new Date() } = {}) {
304
347
  const run = loadRun(rootDir, runId);
305
348
  const proposed = String(displayName || '').trim().replace(/\s+/g, ' ');
306
349
  if (!proposed || proposed.length > 100 || /[\u0000-\u001f/\\]/.test(proposed)) {
@@ -308,7 +351,7 @@ function updateRunDisplayName(rootDir, runId, displayName, { actor = 'human', no
308
351
  err.code = 'INVALID_RUN_DISPLAY_NAME';
309
352
  throw err;
310
353
  }
311
- if (!/^[A-Za-z0-9@._-]{1,64}$/.test(String(actor))) {
354
+ if (!ACTOR_ID.test(String(actor))) {
312
355
  const err = new Error('Display Name actor must be a short account identifier');
313
356
  err.code = 'INVALID_RUN_ACTOR';
314
357
  throw err;
@@ -336,7 +379,13 @@ function updateRunDisplayName(rootDir, runId, displayName, { actor = 'human', no
336
379
  return next;
337
380
  }
338
381
 
339
- function transitionRun(
382
+ // Locked so concurrent gates, Studio actions, and display-name edits re-read
383
+ // the latest state instead of overwriting each other's history.
384
+ function transitionRun(rootDir, runId, to, options = {}) {
385
+ return withFileLock(runStateLockPath(rootDir, runId), () => transitionRunLocked(rootDir, runId, to, options));
386
+ }
387
+
388
+ function transitionRunLocked(
340
389
  rootDir,
341
390
  runId,
342
391
  to,
@@ -406,6 +455,8 @@ module.exports = {
406
455
  currentRunPath,
407
456
  atomicWritePrivateFile,
408
457
  atomicWriteJson,
458
+ renameWithRetry,
459
+ withFileLock,
409
460
  getGitRevision,
410
461
  newRunId,
411
462
  runDisplayMetadata,
@@ -159,10 +159,6 @@ function summarizeReceipt(value, context = {}) {
159
159
  }
160
160
  }
161
161
 
162
- function summarizeNamedArtifact(name, value, context) {
163
- return ARTIFACT_FILES[name]?.summarize(value, context) || { present: true };
164
- }
165
-
166
162
  function compactPresence(rootDir, runId) {
167
163
  try {
168
164
  const presence = runAgentPresence(rootDir, runId);
@@ -277,16 +273,18 @@ function createRunWatcher(rootDir, options = {}) {
277
273
  }
278
274
 
279
275
  function emitLifecycle(runId) {
280
- const after = lifecycleCursor.get(runId) || 0;
281
- let listed;
282
- try {
283
- listed = listRunLifecycle(rootDir, runId, { after, limit: 100 });
284
- } catch {
285
- return;
286
- }
287
- if (listed.events.length) {
276
+ for (;;) {
277
+ const after = lifecycleCursor.get(runId) || 0;
278
+ let listed;
279
+ try {
280
+ listed = listRunLifecycle(rootDir, runId, { after, limit: 100 });
281
+ } catch {
282
+ return;
283
+ }
284
+ if (!listed.events.length) break;
288
285
  lifecycleCursor.set(runId, listed.nextSequence);
289
286
  publish('lifecycle', runId, listed);
287
+ if (listed.events.length < 100) break;
290
288
  }
291
289
  emitPresence(runId);
292
290
  }
@@ -329,7 +327,7 @@ function createRunWatcher(rootDir, options = {}) {
329
327
 
330
328
  function seedLifecycleCursor(runId) {
331
329
  try {
332
- const all = listRunLifecycle(rootDir, runId, { after: 0, limit: 100 });
330
+ const all = listRunLifecycle(rootDir, runId, { after: 0, limit: 1, latest: true });
333
331
  lifecycleCursor.set(runId, all.nextSequence);
334
332
  } catch {
335
333
  lifecycleCursor.set(runId, 0);
@@ -516,5 +514,4 @@ module.exports = {
516
514
  createRunWatcher,
517
515
  envWatchEnabled,
518
516
  loadArtifactSummaries,
519
- summarizeNamedArtifact
520
517
  };
@@ -51,8 +51,52 @@ function ensurePrivateRuntimeIgnores(rootDir) {
51
51
  return true;
52
52
  }
53
53
 
54
+ // A crash mid-append can leave an unterminated last line in a JSONL ledger.
55
+ // Readers keep complete lines and a tail that still parses; an unparseable
56
+ // tail is reported as torn instead of failing the whole ledger.
57
+ function splitJsonlLines(text) {
58
+ const lines = String(text).split('\n');
59
+ const tail = lines.pop();
60
+ const complete = lines.filter(Boolean);
61
+ if (!tail) return { lines: complete, tornTail: null };
62
+ try {
63
+ JSON.parse(tail);
64
+ return { lines: [...complete, tail], tornTail: null };
65
+ } catch {
66
+ return { lines: complete, tornTail: tail };
67
+ }
68
+ }
69
+
70
+ // Writers call this before appending so a new record never fuses with a torn
71
+ // tail. A parseable tail only lacks its newline; an unparseable one is moved
72
+ // to a quarantine file next to the ledger and truncated away.
73
+ function repairJsonlTail(filePath) {
74
+ let buffer;
75
+ try {
76
+ if (!fs.lstatSync(filePath).isFile()) return null;
77
+ buffer = fs.readFileSync(filePath);
78
+ } catch (cause) {
79
+ if (cause.code === 'ENOENT') return null;
80
+ throw cause;
81
+ }
82
+ if (buffer.length === 0 || buffer[buffer.length - 1] === 0x0a) return null;
83
+ const end = buffer.lastIndexOf(0x0a) + 1;
84
+ const tail = buffer.subarray(end).toString('utf8');
85
+ try {
86
+ JSON.parse(tail);
87
+ fs.appendFileSync(filePath, '\n');
88
+ return { repaired: 'newline' };
89
+ } catch {}
90
+ const quarantine = `${filePath}.torn-${Date.now()}-${process.pid}`;
91
+ fs.writeFileSync(quarantine, tail, { mode: 0o600 });
92
+ fs.truncateSync(filePath, end);
93
+ return { repaired: 'quarantined', quarantine };
94
+ }
95
+
54
96
  module.exports = {
55
97
  PRIVATE_RUNTIME_PATTERNS,
56
98
  PRIVATE_RUNTIME_GITIGNORE,
57
- ensurePrivateRuntimeIgnores
99
+ ensurePrivateRuntimeIgnores,
100
+ repairJsonlTail,
101
+ splitJsonlLines
58
102
  };
@@ -1,8 +1,8 @@
1
1
  'use strict';
2
2
 
3
- const crypto = require('crypto');
4
3
  const fs = require('fs');
5
4
  const path = require('path');
5
+ const { sha256 } = require('./fsutil.js');
6
6
  const { atomicWriteJson, getCurrentRun, loadRun, runsDir } = require('./run-state.js');
7
7
  const { assertBudgetAvailable } = require('./budget.js');
8
8
  const { loadPolicy, normalizeReviewProfile } = require('./runtime-policy.js');
@@ -96,8 +96,23 @@ function redactSecrets(input) {
96
96
  replace(/\bgh[pousr]_[A-Za-z0-9]{12,}\b/g, 'github-token', '[REDACTED GITHUB TOKEN]');
97
97
  replace(/\bAKIA[A-Z0-9]{16}\b/g, 'aws-access-key', '[REDACTED AWS ACCESS KEY]');
98
98
  replace(/\bsk-(?:live-|test-)?[A-Za-z0-9_-]{8,}\b/g, 'api-token', '[REDACTED API TOKEN]');
99
+ replace(/\b(?:sk|rk)_(?:live|test)_[A-Za-z0-9]{10,}\b/g, 'stripe-key', '[REDACTED STRIPE KEY]');
100
+ replace(/\bnpm_[A-Za-z0-9]{20,}\b/g, 'npm-token', '[REDACTED NPM TOKEN]');
101
+ replace(/\bxox[abposr]-[A-Za-z0-9-]{10,}/g, 'slack-token', '[REDACTED SLACK TOKEN]');
99
102
  replace(
100
- /(\b(?:api[_-]?key|access[_-]?token|auth[_-]?token|token|secret|password|authorization)\b\s*[:=]\s*["']?)([^"'\s,;]+)/gi,
103
+ /\beyJ[A-Za-z0-9_-]{8,}\.eyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]+/g,
104
+ 'jwt',
105
+ '[REDACTED JWT]'
106
+ );
107
+ replace(
108
+ /\b([a-z][a-z0-9+.-]*:\/\/)([^\s:@/]+):(?!\[REDACTED)([^\s@/]+)@/gi,
109
+ 'url-credentials',
110
+ (_match, scheme, user) => `${scheme}${user}:[REDACTED]@`
111
+ );
112
+ // Key names may be embedded in identifiers (AWS_SECRET_ACCESS_KEY, _password,
113
+ // clientSecret) and JSON keys close their quote before the separator.
114
+ replace(
115
+ /((?<![A-Za-z0-9])(?:api[_-]?key|access[_-]?key|private[_-]?key|access[_-]?token|auth[_-]?token|client[_-]?secret|token|secret|password|passwd|authorization)(?:[_-][A-Za-z0-9]+)*(?![A-Za-z0-9])["']?\s*[:=]\s*["']?)(?!\[REDACTED)([^"'\s,;]+)/gi,
101
116
  'key-value-secret',
102
117
  (_match, prefix) => `${prefix}[REDACTED]`
103
118
  );
@@ -120,10 +135,6 @@ function redactHomePaths(input) {
120
135
  .replace(/\\\\[A-Za-z0-9._-]+\\[A-Za-z0-9._$-]+/g, '[REDACTED HOME]');
121
136
  }
122
137
 
123
- function sha256(content) {
124
- return crypto.createHash('sha256').update(content).digest('hex');
125
- }
126
-
127
138
  function estimateTokens(text) {
128
139
  return Math.ceil(String(text || '').length / 4);
129
140
  }
package/lib/sandbox.js CHANGED
@@ -5,6 +5,7 @@ const fs = require('fs');
5
5
  const os = require('os');
6
6
  const path = require('path');
7
7
  const { execFileSync } = require('child_process');
8
+ const { sha256 } = require('./fsutil.js');
8
9
  const {
9
10
  RUN_MODES,
10
11
  RUN_STATES,
@@ -259,7 +260,7 @@ function captureSandbox(rootDir, { runId, now = new Date() } = {}) {
259
260
  runId: owned.run.runId,
260
261
  sandboxed: true,
261
262
  baseRevision: owned.metadata.baseRevision,
262
- diffSha256: crypto.createHash('sha256').update(diff).digest('hex'),
263
+ diffSha256: sha256(diff),
263
264
  capturedAt: now.toISOString()
264
265
  };
265
266
  git(rootDir, ['worktree', 'remove', '--force', owned.worktree]);
@@ -1,9 +1,9 @@
1
1
  'use strict';
2
2
 
3
- const crypto = require('crypto');
4
3
  const fs = require('fs');
5
4
  const path = require('path');
6
5
  const { execFileSync } = require('child_process');
6
+ const { readJsonOptional, sha256 } = require('./fsutil.js');
7
7
  const { atomicWriteJson, getCurrentRun, loadRun, runsDir } = require('./run-state.js');
8
8
  const { assertBudgetAvailable } = require('./budget.js');
9
9
  const { ensurePrivateRuntimeIgnores } = require('./runtime-files.js');
@@ -66,10 +66,6 @@ function smartContextError(message, code = 'SMART_CONTEXT_ERROR') {
66
66
  return err;
67
67
  }
68
68
 
69
- function sha256(content) {
70
- return crypto.createHash('sha256').update(content).digest('hex');
71
- }
72
-
73
69
  function contextRoot(rootDir) {
74
70
  return path.join(rootDir, '.ai-engineering-loop', 'context');
75
71
  }
@@ -209,14 +205,8 @@ function summarizeFile(rootDir, relativePath) {
209
205
 
210
206
  function readCachedSummary(rootDir, sourceSha) {
211
207
  const filePath = path.join(summaryCacheDir(rootDir), `${sourceSha}.json`);
212
- if (!fs.existsSync(filePath)) return null;
213
- try {
214
- const cached = JSON.parse(fs.readFileSync(filePath, 'utf8'));
215
- if (cached.sourceSha256 !== sourceSha) return null;
216
- return cached;
217
- } catch {
218
- return null;
219
- }
208
+ const cached = readJsonOptional(filePath);
209
+ return cached?.sourceSha256 === sourceSha ? cached : null;
220
210
  }
221
211
 
222
212
  function writeCachedSummary(rootDir, summary) {
@@ -478,7 +468,16 @@ function boundedHunks(file, limits, remainingBytes) {
478
468
  function impactDriftSummary(rootDir, runId) {
479
469
  const drift = require('./impact-map.js').loadImpactDrift(rootDir, runId);
480
470
  if (!drift) return null;
481
- return { mapStatus: drift.mapStatus, outOfMap: (drift.outOfMap || []).slice(0, 50) };
471
+ const summary = { mapStatus: drift.mapStatus, outOfMap: (drift.outOfMap || []).slice(0, 50) };
472
+ // Design drift (#98): two short lines for the Devil's Advocate, not the lists.
473
+ if (drift.design) {
474
+ const d = drift.design;
475
+ summary.design = [
476
+ `Design ${d.path}${d.docChanged ? ' changed after the Goal was drafted' : ''}: ${d.unplanned.length} changed file(s) outside its plan${d.unplanned.length ? ` (${d.unplanned.slice(0, 3).join(', ')}${d.unplanned.length > 3 ? ', ...' : ''})` : ''}.`,
477
+ `${d.untouched.length} planned file(s) untouched${d.untouched.length ? ` (${d.untouched.slice(0, 3).join(', ')}${d.untouched.length > 3 ? ', ...' : ''})` : ''}; check whether the plan or the diff is wrong.`
478
+ ];
479
+ }
480
+ return summary;
482
481
  }
483
482
 
484
483
  function createDiffHunkPack(rootDir, { runId, base = 'HEAD', profile, includeIgnored = false } = {}) {
@@ -0,0 +1,94 @@
1
+ 'use strict';
2
+
3
+ // Cross-platform helpers for spawning commands without a shell.
4
+ // - Windows cannot spawn npm, npx, or other .cmd/.bat shims directly, and
5
+ // Node >= 18.20 refuses to try (EINVAL). resolveSpawn() finds the command on
6
+ // PATH via PATHEXT and runs batch shims through cmd.exe with escaped args.
7
+ // - killProcessTree() stops a command and everything it started, so an
8
+ // orphaned grandchild cannot keep the output pipes open.
9
+
10
+ const { spawn } = require('child_process');
11
+ const fs = require('fs');
12
+ const path = require('path');
13
+
14
+ const CMD_META = /([()\][%!^"`<>&|;, *?])/g;
15
+ const DEFAULT_PATHEXT = '.COM;.EXE;.BAT;.CMD';
16
+
17
+ function envValue(env, name) {
18
+ const key = Object.keys(env).find((item) => item.toUpperCase() === name);
19
+ return key ? env[key] : undefined;
20
+ }
21
+
22
+ function isFile(filePath) {
23
+ try {
24
+ return fs.statSync(filePath).isFile();
25
+ } catch {
26
+ return false;
27
+ }
28
+ }
29
+
30
+ function findOnPath(command, env) {
31
+ const extensions = String(envValue(env, 'PATHEXT') || DEFAULT_PATHEXT)
32
+ .split(';').map((item) => item.trim()).filter(Boolean);
33
+ const hasExtension = extensions.some((ext) => command.toLowerCase().endsWith(ext.toLowerCase()));
34
+ const candidates = hasExtension ? [command] : extensions.map((ext) => `${command}${ext.toLowerCase()}`);
35
+ const directories = /[\\/]/.test(command)
36
+ ? ['']
37
+ : String(envValue(env, 'PATH') || '').split(';').map((item) => item.trim().replace(/^"|"$/g, '')).filter(Boolean);
38
+ for (const directory of directories) {
39
+ for (const candidate of candidates) {
40
+ const full = directory ? path.join(directory, candidate) : candidate;
41
+ if (isFile(full)) return full;
42
+ }
43
+ }
44
+ return null;
45
+ }
46
+
47
+ function escapeArgument(argument, doubleEscape) {
48
+ let value = String(argument)
49
+ .replace(/(\\*)"/g, '$1$1\\"')
50
+ .replace(/(\\*)$/, '$1$1');
51
+ value = `"${value}"`.replace(CMD_META, '^$1');
52
+ return doubleEscape ? value.replace(CMD_META, '^$1') : value;
53
+ }
54
+
55
+ function resolveSpawn(command, args = [], { platform = process.platform, env = process.env } = {}) {
56
+ if (platform !== 'win32') return { command, args, options: {} };
57
+ const resolved = findOnPath(command, env);
58
+ if (!resolved) return { command, args, options: {} };
59
+ if (!/\.(?:cmd|bat)$/i.test(resolved)) return { command: resolved, args, options: {} };
60
+ // node_modules/.bin shims re-expand %* through cmd once more.
61
+ const doubleEscape = /node_modules[\\/]\.bin[\\/][^\\/]+\.cmd$/i.test(resolved);
62
+ const line = [resolved.replace(CMD_META, '^$1'), ...args.map((arg) => escapeArgument(arg, doubleEscape))].join(' ');
63
+ return {
64
+ command: envValue(env, 'COMSPEC') || 'cmd.exe',
65
+ args: ['/d', '/s', '/c', `"${line}"`],
66
+ options: { windowsVerbatimArguments: true }
67
+ };
68
+ }
69
+
70
+ // POSIX: the child must have been spawned with `detached: true` so it leads
71
+ // its own process group. Windows: taskkill /T walks the tree.
72
+ function killProcessTree(child, signal = 'SIGTERM', { platform = process.platform } = {}) {
73
+ if (!child?.pid) return;
74
+ if (platform === 'win32') {
75
+ try {
76
+ spawn('taskkill', ['/pid', String(child.pid), '/T', '/F'], { stdio: 'ignore', windowsHide: true })
77
+ .on('error', () => { try { child.kill(signal); } catch {} });
78
+ } catch {
79
+ try { child.kill(signal); } catch {}
80
+ }
81
+ return;
82
+ }
83
+ try {
84
+ process.kill(-child.pid, signal);
85
+ } catch {
86
+ try { child.kill(signal); } catch {}
87
+ }
88
+ }
89
+
90
+ module.exports = {
91
+ escapeArgument,
92
+ killProcessTree,
93
+ resolveSpawn
94
+ };
@@ -1,10 +1,10 @@
1
1
  'use strict';
2
2
 
3
- const crypto = require('crypto');
4
3
  const fs = require('fs');
5
4
  const path = require('path');
6
5
  const { NODE_ID, RECIPE_ID } = require('./recipe.js');
7
6
  const { ensurePrivateRuntimeIgnores } = require('./runtime-files.js');
7
+ const { writePrivateJson } = require('./fsutil.js');
8
8
 
9
9
  const MIN_SCALE = 0.2;
10
10
  const MAX_SCALE = 2.5;
@@ -94,13 +94,7 @@ function saveStudioLayout(rootDir, recipeId, value, { nodeIds } = {}) {
94
94
  if (fs.existsSync(destination) && fs.lstatSync(destination).isSymbolicLink()) {
95
95
  throw layoutError('Studio layout must not be a symbolic link', 'UNSAFE_STUDIO_LAYOUT');
96
96
  }
97
- const temporary = `${destination}.${process.pid}.${crypto.randomBytes(4).toString('hex')}.tmp`;
98
- try {
99
- fs.writeFileSync(temporary, `${JSON.stringify(layout, null, 2)}\n`, { mode: 0o600 });
100
- fs.renameSync(temporary, destination);
101
- } finally {
102
- try { fs.unlinkSync(temporary); } catch {}
103
- }
97
+ writePrivateJson(destination, layout);
104
98
  return layout;
105
99
  }
106
100
 
@@ -1,5 +1,6 @@
1
1
  'use strict';
2
2
 
3
+ const { ACTOR_ID } = require('./fsutil.js');
3
4
  const { compileRecipe } = require('./recipe.js');
4
5
  const {
5
6
  RUN_MODES,
@@ -100,7 +101,7 @@ function cancelStudioRun(
100
101
  }
101
102
  const cleanActor = String(actor || '').trim();
102
103
  const cleanReason = String(reason || '').trim();
103
- if (!/^[A-Za-z0-9@._-]{1,64}$/.test(cleanActor)) {
104
+ if (!ACTOR_ID.test(cleanActor)) {
104
105
  throw studioRuntimeError('Cancellation actor must be a short account identifier', 'INVALID_RUN_ACTOR');
105
106
  }
106
107
  if (!cleanReason || cleanReason.length > 500) {
@@ -13,6 +13,7 @@ const {
13
13
  } = require('./recipe-builder.js');
14
14
  const { getCurrentRun, loadRun, updateRunDisplayName } = require('./run-state.js');
15
15
  const { ensurePrivateRuntimeIgnores } = require('./runtime-files.js');
16
+ const { writePrivateJson } = require('./fsutil.js');
16
17
  const {
17
18
  compactPresence,
18
19
  createRunWatcher,
@@ -188,10 +189,7 @@ function writeStudioAdvertisement(rootDir, { url, port }) {
188
189
  root: resolvedRoot(rootDir),
189
190
  startedAt: new Date().toISOString()
190
191
  };
191
- const temporary = `${filePath}.${process.pid}.tmp`;
192
- fs.writeFileSync(temporary, `${JSON.stringify(payload, null, 2)}\n`, { mode: 0o600 });
193
- fs.renameSync(temporary, filePath);
194
- fs.chmodSync(filePath, 0o600);
192
+ writePrivateJson(filePath, payload);
195
193
  }
196
194
 
197
195
  function clearStudioAdvertisement(rootDir) {
@@ -299,7 +297,7 @@ function liveSnapshot(rootDir, runId) {
299
297
  snapshot.budget = { spentThisRun: 0, perRunTokenLimit: 0 };
300
298
  }
301
299
  try {
302
- snapshot.lifecycle = listRunLifecycle(rootDir, run.runId, { after: 0, limit: 100 });
300
+ snapshot.lifecycle = listRunLifecycle(rootDir, run.runId, { after: 0, limit: 100, latest: true });
303
301
  } catch {
304
302
  snapshot.lifecycle = { runId: run.runId, events: [], nextSequence: 0 };
305
303
  }
@@ -390,6 +388,21 @@ function localHostname(hostHeader) {
390
388
  }
391
389
  }
392
390
 
391
+ // The SameSite cookie alone does not stop CSRF: every localhost port is the
392
+ // same site. Mutations need proof of same origin (exact Origin match) or the
393
+ // explicit token header, and a JSON body type, which a cross-origin form or
394
+ // simple fetch cannot send without a CORS preflight this server never grants.
395
+ function mutationRejection(request, hostHeader, token) {
396
+ const contentType = String(request.headers['content-type'] || '').split(';')[0].trim().toLowerCase();
397
+ if (contentType !== 'application/json') {
398
+ return { status: 415, message: 'Studio mutations require content-type application/json' };
399
+ }
400
+ if (constantTimeEqual(request.headers['x-ael-studio-token'], token)) return null;
401
+ const origin = request.headers.origin;
402
+ if (origin && origin === `http://${hostHeader}`) return null;
403
+ return { status: 403, message: 'Cross-origin Studio mutation rejected' };
404
+ }
405
+
393
406
  function createStudioServer(rootDir, {
394
407
  token = crypto.randomBytes(24).toString('base64url'),
395
408
  watch,
@@ -424,6 +437,13 @@ function createStudioServer(rootDir, {
424
437
  response.writeHead(401).end('Studio session required');
425
438
  return;
426
439
  }
440
+ if (!['GET', 'HEAD'].includes(request.method)) {
441
+ const csrf = mutationRejection(request, hostHeader, token);
442
+ if (csrf) {
443
+ response.writeHead(csrf.status).end(csrf.message);
444
+ return;
445
+ }
446
+ }
427
447
  response.setHeader('content-security-policy', "default-src 'self'; script-src 'self'; style-src 'self'; img-src 'self' data:; connect-src 'self'; object-src 'none'; base-uri 'none'; frame-ancestors 'none'");
428
448
  response.setHeader('x-content-type-options', 'nosniff');
429
449
  response.setHeader('referrer-policy', 'no-referrer');
package/lib/sync-hosts.js CHANGED
@@ -21,7 +21,7 @@ function packageRoot() {
21
21
 
22
22
  // Host packs. `core` is always installed; the others are opt-in so unrelated
23
23
  // skills do not enter every session's skill index (issue #31).
24
- const HOST_PACKS = Object.freeze(['core', 'backend', 'design', 'quality']);
24
+ const HOST_PACKS = Object.freeze(['core', 'backend', 'design', 'quality', 'spec']);
25
25
  const DEFAULT_HOST_PACKS = Object.freeze(['core']);
26
26
  const MANIFEST_FILE = 'host-manifest.json';
27
27
 
@@ -101,6 +101,27 @@ function adoptedSkillFiles(destRoot) {
101
101
  ];
102
102
  }
103
103
 
104
+ // Spec pack (#96): host-neutral ael-spec-* skills generated from the EGM fork
105
+ // by scripts/sync-spec-pack.js. Personas and standards stay in the package
106
+ // and are read with `ai-engineering-loop docs <name>`.
107
+ const SPEC_SKILL_FILES = Object.freeze({
108
+ 'ael-spec-brainstorm': ['SKILL.md'],
109
+ 'ael-spec-draft': ['SKILL.md', 'references/design_doc.md'],
110
+ 'ael-spec-review': ['SKILL.md'],
111
+ 'ael-spec-review-loop': ['SKILL.md'],
112
+ 'ael-spec-resolve': ['SKILL.md'],
113
+ 'ael-spec-drift': ['SKILL.md']
114
+ });
115
+
116
+ function specSkillFiles(destRoot) {
117
+ return Object.entries(SPEC_SKILL_FILES).flatMap(([skill, files]) => files.map((file) => ({
118
+ src: `adapters/spec/skills/${skill}/${file}`,
119
+ dest: path.join(destRoot, skill, file),
120
+ mode: 'upsert',
121
+ pack: 'spec'
122
+ })));
123
+ }
124
+
104
125
  // Loop stage references sit beside each host's SKILL.md (issue #35).
105
126
  const LOOP_REFERENCE_FILES = Object.freeze([
106
127
  'loop-commands.md',
@@ -135,7 +156,8 @@ function skillFolderFiles(skillsDir) {
135
156
  { src: 'adapters/quality/skills/task-impact-inquiry/SKILL.md', dest: path.join(skillsDir, 'task-impact-inquiry/SKILL.md'), mode: 'upsert' },
136
157
  { src: 'adapters/generate-adapter/SKILL.md', dest: path.join(skillsDir, 'generate-adapter/SKILL.md'), mode: 'upsert' },
137
158
  { src: 'adapters/generate-workflow/SKILL.md', dest: path.join(skillsDir, 'generate-workflow/SKILL.md'), mode: 'upsert' },
138
- ...adoptedSkillFiles(skillsDir)
159
+ ...adoptedSkillFiles(skillsDir),
160
+ ...specSkillFiles(skillsDir)
139
161
  ];
140
162
  }
141
163
 
@@ -626,6 +648,7 @@ function formatHostSyncReport(results, { version, dryRun = false } = {}) {
626
648
 
627
649
  module.exports = {
628
650
  QUALITY_SKILLS,
651
+ SPEC_SKILL_FILES,
629
652
  LOOP_REFERENCE_FILES,
630
653
  HOST_PACKS,
631
654
  DEFAULT_HOST_PACKS,