ai-engineering-loop 1.12.0 → 1.14.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 (68) hide show
  1. package/.agents/workflows/ai-engineering-loop.md +47 -11
  2. package/.claude/commands/ai-engineering-loop.md +1 -1
  3. package/.claude/skills/ai-engineering-loop/SKILL.md +26 -44
  4. package/.claude/skills/ai-engineering-loop/references/loop-commands.md +20 -0
  5. package/.claude/skills/ai-engineering-loop/references/loop-deliver.md +8 -0
  6. package/.claude/skills/ai-engineering-loop/references/loop-goal.md +10 -0
  7. package/.claude/skills/ai-engineering-loop/references/loop-maker.md +8 -0
  8. package/.claude/skills/ai-engineering-loop/references/loop-review.md +18 -0
  9. package/.claude/skills/ai-engineering-loop/references/loop-risky.md +9 -0
  10. package/.claude/skills/ai-engineering-loop/references/loop-verify.md +20 -0
  11. package/.gemini/skills/ai-engineering-loop/SKILL.md +24 -37
  12. package/.gemini/skills/ai-engineering-loop/references/loop-commands.md +20 -0
  13. package/.gemini/skills/ai-engineering-loop/references/loop-deliver.md +8 -0
  14. package/.gemini/skills/ai-engineering-loop/references/loop-goal.md +10 -0
  15. package/.gemini/skills/ai-engineering-loop/references/loop-maker.md +8 -0
  16. package/.gemini/skills/ai-engineering-loop/references/loop-review.md +18 -0
  17. package/.gemini/skills/ai-engineering-loop/references/loop-risky.md +9 -0
  18. package/.gemini/skills/ai-engineering-loop/references/loop-verify.md +20 -0
  19. package/.grok/skills/ai-engineering-loop/SKILL.md +29 -61
  20. package/.grok/skills/ai-engineering-loop/references/loop-commands.md +20 -0
  21. package/.grok/skills/ai-engineering-loop/references/loop-deliver.md +8 -0
  22. package/.grok/skills/ai-engineering-loop/references/loop-goal.md +10 -0
  23. package/.grok/skills/ai-engineering-loop/references/loop-maker.md +8 -0
  24. package/.grok/skills/ai-engineering-loop/references/loop-review.md +18 -0
  25. package/.grok/skills/ai-engineering-loop/references/loop-risky.md +9 -0
  26. package/.grok/skills/ai-engineering-loop/references/loop-verify.md +20 -0
  27. package/CHANGELOG.md +69 -0
  28. package/README.md +52 -1
  29. package/README.npm.md +6 -2
  30. package/THIRD_PARTY_NOTICES.md +29 -0
  31. package/adapters/dot/skills/dot-dev-skill-router/SKILL.md +24 -16
  32. package/adapters/project-onboarding/SKILL.md +27 -0
  33. package/adapters/project-onboarding/references/output.md +29 -0
  34. package/adapters/quality/skills/ael-code-simplifier/SKILL.md +43 -0
  35. package/adapters/quality/skills/ael-receiving-code-review/SKILL.md +37 -0
  36. package/bin/ai-engineering-loop.js +1137 -78
  37. package/core/artifact-gates.md +32 -1
  38. package/core/root-cause-analysis.md +6 -0
  39. package/core/runtime-safety.md +32 -4
  40. package/core/verification-loop.md +6 -0
  41. package/evals/cases/21-tier-t0-docs.json +34 -0
  42. package/evals/cases/22-tier-t1-small-pass.json +30 -0
  43. package/evals/cases/23-tier-t1-blocker.json +26 -0
  44. package/evals/cases/24-tier-t1-auth-escalates.json +30 -0
  45. package/lib/agent-artifacts.js +250 -0
  46. package/lib/auto-update.js +486 -0
  47. package/lib/budget.js +31 -1
  48. package/lib/claimed-vs-reality.js +134 -0
  49. package/lib/cli-args.js +84 -0
  50. package/lib/docs.js +91 -0
  51. package/lib/doctor.js +7 -1
  52. package/lib/gates.js +114 -1
  53. package/lib/host-skill-build.js +121 -0
  54. package/lib/migrations.js +84 -0
  55. package/lib/project-registry.js +148 -0
  56. package/lib/run-state.js +6 -3
  57. package/lib/safe-context.js +62 -4
  58. package/lib/sync-hosts.js +356 -28
  59. package/lib/tier.js +134 -0
  60. package/lib/update-manager.js +17 -1
  61. package/lib/update-notice.js +192 -0
  62. package/lib/user-state.js +80 -0
  63. package/lib/verification-recorder.js +268 -0
  64. package/lib/workflow-runtime.js +26 -1
  65. package/migrations/README.md +21 -0
  66. package/package.json +7 -2
  67. package/policies/review-budget.md +1 -1
  68. package/schemas/verification.schema.json +2 -2
@@ -108,10 +108,26 @@ function buildUpdatePlan({ packageName, currentVersion, latestVersion, installSc
108
108
  installScope,
109
109
  updateAvailable: comparison < 0,
110
110
  upToDate: comparison >= 0,
111
- commands: updateCommands(packageName, installScope)
111
+ commands: withMigrationStep(updateCommands(packageName, installScope), { currentVersion, latestVersion, installScope })
112
112
  };
113
113
  }
114
114
 
115
+ // Crossing a major: run the new version's migrations right after the install
116
+ // (decision 6 on #37; see migrations/README.md).
117
+ function withMigrationStep(commands, { currentVersion, latestVersion, installScope }) {
118
+ let crosses = false;
119
+ try {
120
+ crosses = parseVersion(latestVersion)[0] > parseVersion(currentVersion)[0];
121
+ } catch {
122
+ crosses = false;
123
+ }
124
+ if (!crosses) return commands;
125
+ const step = installScope === 'global'
126
+ ? command('ai-engineering-loop', ['migrate', '--from', currentVersion])
127
+ : command('npx', ['ai-engineering-loop', 'migrate', '--from', currentVersion]);
128
+ return [commands[0], step, ...commands.slice(1)];
129
+ }
130
+
115
131
  function checkForUpdate(rootDir, {
116
132
  latestVersion,
117
133
  installScope,
@@ -0,0 +1,192 @@
1
+ 'use strict';
2
+
3
+ // Update notice (decision 1 on #37). Project installs are notify-only, so the
4
+ // notice has to be worth reading: current -> target, 2-4 changelog highlights
5
+ // for the versions in between, one copy-pasteable command for the detected
6
+ // package manager, and how to silence it. Shown on an interactive stderr only,
7
+ // at most once per 24 hours per project, never in CI or --json output.
8
+
9
+ const fs = require('fs');
10
+ const path = require('path');
11
+ const https = require('https');
12
+ const { compareVersions } = require('./update-manager.js');
13
+
14
+ const NOTICE_INTERVAL_MS = 24 * 60 * 60 * 1000;
15
+ const MAX_HIGHLIGHTS = 4;
16
+ const truthy = (value) => ['1', 'true', 'yes'].includes(String(value || '').trim().toLowerCase());
17
+
18
+ function detectPackageManager(projectDir) {
19
+ const has = (file) => fs.existsSync(path.join(projectDir, file));
20
+ try {
21
+ const pkg = JSON.parse(fs.readFileSync(path.join(projectDir, 'package.json'), 'utf8'));
22
+ const declared = String(pkg.packageManager || '').split('@')[0];
23
+ if (['npm', 'pnpm', 'yarn', 'bun'].includes(declared)) return declared;
24
+ } catch {
25
+ // No package.json: fall through to lockfiles.
26
+ }
27
+ if (has('pnpm-lock.yaml')) return 'pnpm';
28
+ if (has('yarn.lock')) return 'yarn';
29
+ if (has('bun.lockb') || has('bun.lock')) return 'bun';
30
+ return 'npm';
31
+ }
32
+
33
+ // Global installs: infer the manager from where this package lives.
34
+ function detectGlobalPackageManager(packageRoot) {
35
+ const p = String(packageRoot).replace(/\\/g, '/').toLowerCase();
36
+ if (p.includes('/pnpm/')) return 'pnpm';
37
+ if (p.includes('/.bun/')) return 'bun';
38
+ if (p.includes('/yarn/')) return 'yarn';
39
+ return 'npm';
40
+ }
41
+
42
+ function updateCommand({ packageName, target, scope, manager }) {
43
+ const spec = `${packageName}@${target}`;
44
+ if (scope === 'global') {
45
+ return {
46
+ npm: `npm install -g ${spec}`,
47
+ pnpm: `pnpm add -g ${spec}`,
48
+ yarn: `yarn global add ${spec}`,
49
+ bun: `bun add -g ${spec}`
50
+ }[manager] || `npm install -g ${spec}`;
51
+ }
52
+ return {
53
+ npm: `npm install -D ${spec}`,
54
+ pnpm: `pnpm add -D ${spec}`,
55
+ yarn: `yarn add -D ${spec}`,
56
+ bun: `bun add -d ${spec}`
57
+ }[manager] || `npm install -D ${spec}`;
58
+ }
59
+
60
+ function clean(line) {
61
+ return line
62
+ .replace(/^\s*[-*]\s+/, '')
63
+ .replace(/^#+\s+/, '')
64
+ .replace(/\*\*([^*]+?):?\*\*:?\s*/g, '$1: ')
65
+ .replace(/`([^`]+)`/g, '$1')
66
+ .replace(/\s*\(#\d+\)\s*$/, '')
67
+ .replace(/\s+/g, ' ')
68
+ .trim();
69
+ }
70
+
71
+ function truncate(text, max = 96) {
72
+ return text.length <= max ? text : `${text.slice(0, max - 1).trimEnd()}…`;
73
+ }
74
+
75
+ // Highlights from CHANGELOG sections `## <version>` with current < version <= target.
76
+ // Prefers `###` subsection titles (they summarize a change); falls back to bullets.
77
+ function changelogHighlights(changelog, { current, target, max = MAX_HIGHLIGHTS } = {}) {
78
+ const lines = String(changelog || '').replace(/\r\n?/g, '\n').split('\n');
79
+ const titles = [];
80
+ const bullets = [];
81
+ let inRange = false;
82
+ for (const line of lines) {
83
+ const version = line.match(/^##\s+\[?v?(\d+\.\d+\.\d+(?:-[\w.]+)?)\]?/);
84
+ if (version) {
85
+ try {
86
+ inRange = compareVersions(version[1], current) > 0 && compareVersions(version[1], target) <= 0;
87
+ } catch {
88
+ inRange = false;
89
+ }
90
+ continue;
91
+ }
92
+ if (/^##\s/.test(line)) {
93
+ inRange = false;
94
+ continue;
95
+ }
96
+ if (!inRange) continue;
97
+ if (/^###\s/.test(line)) titles.push(truncate(clean(line)));
98
+ else if (/^\s*[-*]\s+\S/.test(line)) bullets.push(truncate(clean(line)));
99
+ }
100
+ const picked = titles.length >= 2 ? titles : [...titles, ...bullets];
101
+ return picked.filter(Boolean).slice(0, max);
102
+ }
103
+
104
+ function formatNotice({ packageName, current, target, bump, scope, manager, highlights = [], policy, reason }) {
105
+ const lines = [`ai-engineering-loop ${current} -> ${target} available (${bump}).`];
106
+ for (const item of highlights.slice(0, MAX_HIGHLIGHTS)) lines.push(` • ${item}`);
107
+ if (bump === 'major') lines.push(' Major release: read the migration notes in CHANGELOG.md before updating.');
108
+ const cmd = updateCommand({ packageName, target, scope, manager });
109
+ lines.push(` Update: ${scope === 'global' && bump !== 'major' && policy === 'notify' ? `${cmd} (or auto-apply: ai-engineering-loop update policy minor)` : cmd}`);
110
+ if (scope === 'global') lines.push(' Then: ai-engineering-loop sync-hosts');
111
+ lines.push(' Silence: AEL_NO_UPDATE_NOTICE=1, or ai-engineering-loop update policy off');
112
+ if (reason === 'PINNED') lines.push(' (outside your pin; change it with update policy --pin)');
113
+ return lines.join('\n');
114
+ }
115
+
116
+ // Where and how often the notice may appear.
117
+ function noticeAllowed({ env = process.env, argv = process.argv, stderrIsTTY = process.stderr.isTTY } = {}) {
118
+ if (truthy(env.AEL_NO_UPDATE_NOTICE) || truthy(env.CI)) return false;
119
+ if (argv.includes('--json')) return false;
120
+ return Boolean(stderrIsTTY) || truthy(env.AEL_FORCE_UPDATE_NOTICE);
121
+ }
122
+
123
+ function noticeDue(cache, projectKey, now = new Date()) {
124
+ const last = cache && cache.notices && cache.notices[projectKey];
125
+ if (!last || !last.at) return true;
126
+ const age = now.getTime() - Date.parse(last.at);
127
+ return !(age >= 0 && age < NOTICE_INTERVAL_MS);
128
+ }
129
+
130
+ function markNoticeShown(cache, projectKey, target, now = new Date()) {
131
+ const notices = { ...(cache.notices || {}) };
132
+ notices[projectKey] = { version: target, at: now.toISOString() };
133
+ // Keep the map small.
134
+ const keys = Object.keys(notices);
135
+ if (keys.length > 200) for (const key of keys.slice(0, keys.length - 200)) delete notices[key];
136
+ return { ...cache, notices };
137
+ }
138
+
139
+ // Background only: the target's CHANGELOG.md from the npm CDN (package files)
140
+ // or the GitHub tag. Resolves null on any failure; 3 s budget per request.
141
+ function fetchText(url, timeoutMs) {
142
+ return new Promise((resolve) => {
143
+ const req = https.get(url, { timeout: timeoutMs, headers: { 'user-agent': 'ai-engineering-loop' } }, (res) => {
144
+ if (res.statusCode !== 200) {
145
+ res.resume();
146
+ resolve(null);
147
+ return;
148
+ }
149
+ let body = '';
150
+ res.setEncoding('utf8');
151
+ res.on('data', (chunk) => {
152
+ body += chunk;
153
+ if (body.length > 512 * 1024) req.destroy();
154
+ });
155
+ res.on('end', () => resolve(body));
156
+ });
157
+ req.on('timeout', () => req.destroy());
158
+ req.on('error', () => resolve(null));
159
+ });
160
+ }
161
+
162
+ async function fetchChangelog({ packageName, target, repositorySlug, env = process.env, timeoutMs = 3000 }) {
163
+ if (env.AEL_UPDATE_CHANGELOG_FILE) {
164
+ try {
165
+ return fs.readFileSync(env.AEL_UPDATE_CHANGELOG_FILE, 'utf8');
166
+ } catch {
167
+ return null;
168
+ }
169
+ }
170
+ if (truthy(env.AEL_UPDATE_OFFLINE)) return null;
171
+ const urls = [`https://cdn.jsdelivr.net/npm/${packageName}@${target}/CHANGELOG.md`];
172
+ if (repositorySlug) urls.push(`https://raw.githubusercontent.com/${repositorySlug}/v${target}/CHANGELOG.md`);
173
+ for (const url of urls) {
174
+ const text = await fetchText(url, timeoutMs);
175
+ if (text) return text;
176
+ }
177
+ return null;
178
+ }
179
+
180
+ module.exports = {
181
+ NOTICE_INTERVAL_MS,
182
+ MAX_HIGHLIGHTS,
183
+ detectPackageManager,
184
+ detectGlobalPackageManager,
185
+ updateCommand,
186
+ changelogHighlights,
187
+ formatNotice,
188
+ noticeAllowed,
189
+ noticeDue,
190
+ markNoticeShown,
191
+ fetchChangelog
192
+ };
@@ -0,0 +1,80 @@
1
+ 'use strict';
2
+
3
+ // User-level (per machine) AEL state lives in <home>/.ai-engineering-loop/.
4
+ // It is never part of a repository. `home` resolves AEL_HOME first so tests and
5
+ // sandboxes never touch the real home directory.
6
+
7
+ const crypto = require('crypto');
8
+ const fs = require('fs');
9
+ const os = require('os');
10
+ const path = require('path');
11
+
12
+ function homeDir(env = process.env) {
13
+ if (env.AEL_HOME) return env.AEL_HOME;
14
+ return os.homedir();
15
+ }
16
+
17
+ function userStateDir(home = homeDir()) {
18
+ return path.join(home, '.ai-engineering-loop');
19
+ }
20
+
21
+ function userStatePath(name, home = homeDir()) {
22
+ if (!/^[a-z0-9][a-z0-9.-]*$/.test(name)) throw new Error(`Invalid user-state file name: ${name}`);
23
+ return path.join(userStateDir(home), name);
24
+ }
25
+
26
+ function sha256(content) {
27
+ return crypto.createHash('sha256').update(content).digest('hex');
28
+ }
29
+
30
+ function atomicWritePrivate(filePath, content) {
31
+ fs.mkdirSync(path.dirname(filePath), { recursive: true, mode: 0o700 });
32
+ const temporary = `${filePath}.${process.pid}.${crypto.randomBytes(4).toString('hex')}.tmp`;
33
+ try {
34
+ fs.writeFileSync(temporary, content, { mode: 0o600 });
35
+ fs.renameSync(temporary, filePath);
36
+ } finally {
37
+ try {
38
+ fs.unlinkSync(temporary);
39
+ } catch {
40
+ // Rename succeeded or nothing was written.
41
+ }
42
+ }
43
+ }
44
+
45
+ function readJsonFile(filePath, fallback) {
46
+ try {
47
+ const stat = fs.lstatSync(filePath);
48
+ if (stat.isSymbolicLink()) return fallback;
49
+ return JSON.parse(fs.readFileSync(filePath, 'utf8'));
50
+ } catch {
51
+ return fallback;
52
+ }
53
+ }
54
+
55
+ function writeJsonFile(filePath, value) {
56
+ atomicWritePrivate(filePath, `${JSON.stringify(value, null, 2)}\n`);
57
+ }
58
+
59
+ function readUserConfig(home = homeDir()) {
60
+ const value = readJsonFile(userStatePath('config.json', home), {});
61
+ return value && typeof value === 'object' && !Array.isArray(value) ? value : {};
62
+ }
63
+
64
+ function writeUserConfig(patch, home = homeDir()) {
65
+ const next = { ...readUserConfig(home), ...patch };
66
+ writeJsonFile(userStatePath('config.json', home), next);
67
+ return next;
68
+ }
69
+
70
+ module.exports = {
71
+ homeDir,
72
+ userStateDir,
73
+ userStatePath,
74
+ sha256,
75
+ atomicWritePrivate,
76
+ readJsonFile,
77
+ writeJsonFile,
78
+ readUserConfig,
79
+ writeUserConfig
80
+ };
@@ -0,0 +1,268 @@
1
+ 'use strict';
2
+
3
+ const { spawn } = require('child_process');
4
+ const fs = require('fs');
5
+ const path = require('path');
6
+ const {
7
+ atomicWriteJson,
8
+ getCurrentRun,
9
+ getGitRevision,
10
+ loadRun,
11
+ runsDir
12
+ } = require('./run-state.js');
13
+ const { hashFile } = require('./gates.js');
14
+ const { redactHomePaths, redactSecrets } = require('./safe-context.js');
15
+ const { writeVerificationSummary } = require('./verification-summary.js');
16
+
17
+ const MAX_CAPTURE_BYTES = 256 * 1024;
18
+ const DEFAULT_TIMEOUT_MS = 30 * 60 * 1000;
19
+ const MAX_TIMEOUT_MS = 60 * 60 * 1000;
20
+ const KILL_GRACE_MS = 2_000;
21
+
22
+ function recorderError(message, code = 'VERIFICATION_RECORD_FAILED') {
23
+ const error = new Error(message);
24
+ error.code = code;
25
+ return error;
26
+ }
27
+
28
+ function resolveRun(rootDir, runId) {
29
+ if (runId) return loadRun(rootDir, runId);
30
+ const current = getCurrentRun(rootDir);
31
+ if (!current) throw recorderError('No current Run. Pass --run <id> or start a Run first.', 'NO_CURRENT_RUN');
32
+ return current;
33
+ }
34
+
35
+ function validateRecordingRequest({ command, args, timeoutMs, shell }) {
36
+ if (typeof command !== 'string' || !command.trim() || command.includes('\0')) {
37
+ throw recorderError('Provide an executable after `--`, for example `verification record -- npm test`.', 'INVALID_COMMAND');
38
+ }
39
+ if (!Array.isArray(args) || args.some((argument) => typeof argument !== 'string' || argument.includes('\0'))) {
40
+ throw recorderError('Command arguments must be strings without NUL characters.', 'INVALID_COMMAND');
41
+ }
42
+ if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > MAX_TIMEOUT_MS) {
43
+ throw recorderError(`Timeout must be between 1 and ${MAX_TIMEOUT_MS} milliseconds.`, 'INVALID_TIMEOUT');
44
+ }
45
+ if (shell && args.length > 0) {
46
+ throw recorderError('With --shell, pass one quoted command string after `--`; shell argument arrays are intentionally unsupported.', 'INVALID_COMMAND');
47
+ }
48
+ }
49
+
50
+ function resolveDiff(rootDir, run) {
51
+ const artifact = run.artifacts?.diff;
52
+ if (!artifact?.path || !artifact.sha256) {
53
+ throw recorderError('Maker evidence is not gated yet. Run `gate maker` before recording verification.', 'MAKER_NOT_GATED');
54
+ }
55
+ const root = fs.realpathSync(rootDir);
56
+ const absolute = path.resolve(root, artifact.path);
57
+ const relative = path.relative(root, absolute);
58
+ if (relative === '..' || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
59
+ throw recorderError('The gated Maker diff path escapes the repository.', 'UNSAFE_DIFF_PATH');
60
+ }
61
+ const stat = fs.lstatSync(absolute);
62
+ if (!stat.isFile() || stat.isSymbolicLink() || hashFile(absolute) !== artifact.sha256) {
63
+ throw recorderError('The gated Maker diff is missing, unsafe, or changed. Re-run the Maker gate.', 'STALE_DIFF');
64
+ }
65
+ return artifact.sha256;
66
+ }
67
+
68
+ function readExistingBundle(filePath, { runId, gitRevision, diffHash }) {
69
+ if (!fs.existsSync(filePath)) {
70
+ return { schemaVersion: 1, runId, gitRevision, diffHash, commands: [] };
71
+ }
72
+ let bundle;
73
+ try {
74
+ bundle = JSON.parse(fs.readFileSync(filePath, 'utf8'));
75
+ } catch (cause) {
76
+ throw recorderError(`Existing verification.json is invalid: ${cause.message}`, 'INVALID_VERIFICATION');
77
+ }
78
+ if (
79
+ bundle.schemaVersion !== 1
80
+ || bundle.runId !== runId
81
+ || bundle.gitRevision !== gitRevision
82
+ || bundle.diffHash !== diffHash
83
+ || !Array.isArray(bundle.commands)
84
+ ) {
85
+ throw recorderError(
86
+ 'Existing verification.json belongs to another Run, revision, or Maker diff. Reconcile it before recording more commands.',
87
+ 'STALE_VERIFICATION'
88
+ );
89
+ }
90
+ return bundle;
91
+ }
92
+
93
+ function captureStream(stream) {
94
+ const chunks = [];
95
+ let bytes = 0;
96
+ let truncated = false;
97
+ stream.on('data', (chunk) => {
98
+ const remaining = MAX_CAPTURE_BYTES - bytes;
99
+ if (remaining <= 0) {
100
+ truncated = true;
101
+ return;
102
+ }
103
+ const captured = chunk.length > remaining ? chunk.subarray(0, remaining) : chunk;
104
+ chunks.push(captured);
105
+ bytes += captured.length;
106
+ if (captured.length < chunk.length) truncated = true;
107
+ });
108
+ return {
109
+ value: () => Buffer.concat(chunks).toString('utf8'),
110
+ truncated: () => truncated
111
+ };
112
+ }
113
+
114
+ function displayCommand(command, args) {
115
+ const sensitiveArgument = /^--?(?:api[-_]?key|access[-_]?token|auth[-_]?token|token|password|secret|authorization)$/i;
116
+ let redactNext = false;
117
+ const safeParts = [command, ...args].map((part) => {
118
+ if (redactNext) {
119
+ redactNext = false;
120
+ return '[REDACTED ARGUMENT]';
121
+ }
122
+ if (sensitiveArgument.test(part)) {
123
+ redactNext = true;
124
+ return part;
125
+ }
126
+ return redactHomePaths(redactSecrets(part).text);
127
+ });
128
+ const rendered = safeParts
129
+ .map((part) => (/\s|["']/u.test(part) ? JSON.stringify(part) : part))
130
+ .join(' ');
131
+ return redactHomePaths(redactSecrets(rendered).text);
132
+ }
133
+
134
+ function runCommand(command, args, { cwd, timeoutMs, shell }) {
135
+ return new Promise((resolve) => {
136
+ const started = new Date();
137
+ let timedOut = false;
138
+ let launchError = null;
139
+ let forceKillTimer = null;
140
+ const child = spawn(command, shell ? [] : args, {
141
+ cwd,
142
+ env: process.env,
143
+ shell: Boolean(shell),
144
+ stdio: ['ignore', 'pipe', 'pipe']
145
+ });
146
+ const stdout = captureStream(child.stdout);
147
+ const stderr = captureStream(child.stderr);
148
+
149
+ const timeout = setTimeout(() => {
150
+ timedOut = true;
151
+ child.kill('SIGTERM');
152
+ forceKillTimer = setTimeout(() => child.kill('SIGKILL'), KILL_GRACE_MS);
153
+ forceKillTimer.unref?.();
154
+ }, timeoutMs);
155
+ timeout.unref?.();
156
+
157
+ child.once('error', (error) => {
158
+ launchError = error;
159
+ });
160
+ child.once('close', (code, signal) => {
161
+ clearTimeout(timeout);
162
+ if (forceKillTimer) clearTimeout(forceKillTimer);
163
+ const finished = new Date();
164
+ const rawStdout = stdout.value();
165
+ const rawStderr = launchError ? launchError.message : stderr.value();
166
+ const stdoutValue = redactHomePaths(redactSecrets(rawStdout).text);
167
+ const stderrValue = redactHomePaths(redactSecrets(rawStderr).text);
168
+ resolve({
169
+ command: displayCommand(command, args),
170
+ executionIdentity: `pid:${child.pid || process.pid}`,
171
+ startTime: started.toISOString(),
172
+ endTime: finished.toISOString(),
173
+ durationMs: Math.max(0, finished.getTime() - started.getTime()),
174
+ exitCode: launchError ? 127 : (timedOut ? (code ?? 124) : (code ?? 1)),
175
+ signal: signal || null,
176
+ timeoutStatus: timedOut ? 'TIMED_OUT' : 'COMPLETED',
177
+ stdout: stdoutValue || '(no stdout)',
178
+ stdoutWasEmpty: stdoutValue.length === 0,
179
+ stderr: stderrValue,
180
+ stdoutTruncated: stdout.truncated(),
181
+ stderrTruncated: stderr.truncated(),
182
+ ...(launchError ? { launchError: true } : {}),
183
+ ...(timedOut ? { summary: `Command timed out after ${timeoutMs} ms.` } : {})
184
+ });
185
+ });
186
+ });
187
+ }
188
+
189
+ async function recordVerificationCommand(rootDir, {
190
+ runId,
191
+ command,
192
+ args = [],
193
+ shell = false,
194
+ timeoutMs = DEFAULT_TIMEOUT_MS
195
+ } = {}) {
196
+ validateRecordingRequest({ command, args, timeoutMs, shell });
197
+ const run = resolveRun(rootDir, runId);
198
+ if (run.artifacts?.verification) {
199
+ throw recorderError('Verification has already passed its gate. Do not mutate gated evidence; start a new verification iteration instead.', 'VERIFICATION_ALREADY_GATED');
200
+ }
201
+
202
+ const diffHash = resolveDiff(rootDir, run);
203
+ const gitRevision = getGitRevision(rootDir);
204
+ const filePath = path.join(runsDir(rootDir), run.runId, 'verification.json');
205
+ const bundle = readExistingBundle(filePath, { runId: run.runId, gitRevision, diffHash });
206
+ const result = await runCommand(command, args, { cwd: rootDir, timeoutMs, shell });
207
+ bundle.commands.push(result);
208
+ atomicWriteJson(filePath, bundle);
209
+
210
+ const summary = writeVerificationSummary(rootDir, { runId: run.runId }).summary;
211
+ return {
212
+ runId: run.runId,
213
+ path: path.relative(rootDir, filePath).split(path.sep).join('/'),
214
+ command: result,
215
+ summary
216
+ };
217
+ }
218
+
219
+ // Issue #34: run several verification commands in one CLI call. Independent
220
+ // commands run in parallel by default (`serial: true` opts out); results are
221
+ // appended to verification.json in the given order, in one atomic write.
222
+ async function recordVerificationCommands(rootDir, {
223
+ runId,
224
+ commands = [],
225
+ serial = false,
226
+ timeoutMs = DEFAULT_TIMEOUT_MS
227
+ } = {}) {
228
+ if (!Array.isArray(commands) || commands.length === 0) {
229
+ throw recorderError('Provide at least one verification command.', 'INVALID_COMMAND');
230
+ }
231
+ for (const item of commands) {
232
+ validateRecordingRequest({ command: item.command, args: item.args || [], timeoutMs, shell: Boolean(item.shell) });
233
+ }
234
+ const run = resolveRun(rootDir, runId);
235
+ if (run.artifacts?.verification) {
236
+ throw recorderError('Verification has already passed its gate. Do not mutate gated evidence; start a new verification iteration instead.', 'VERIFICATION_ALREADY_GATED');
237
+ }
238
+ const diffHash = resolveDiff(rootDir, run);
239
+ const gitRevision = getGitRevision(rootDir);
240
+ const filePath = path.join(runsDir(rootDir), run.runId, 'verification.json');
241
+ const bundle = readExistingBundle(filePath, { runId: run.runId, gitRevision, diffHash });
242
+ const exec = (item) => runCommand(item.command, item.args || [], { cwd: rootDir, timeoutMs, shell: Boolean(item.shell) });
243
+ let results;
244
+ if (serial) {
245
+ results = [];
246
+ for (const item of commands) results.push(await exec(item));
247
+ } else {
248
+ results = await Promise.all(commands.map(exec));
249
+ }
250
+ bundle.commands.push(...results);
251
+ atomicWriteJson(filePath, bundle);
252
+ const summary = writeVerificationSummary(rootDir, { runId: run.runId }).summary;
253
+ return {
254
+ runId: run.runId,
255
+ path: path.relative(rootDir, filePath).split(path.sep).join('/'),
256
+ commands: results,
257
+ summary,
258
+ passed: results.every((r) => r.exitCode === 0 && r.timeoutStatus === 'COMPLETED')
259
+ };
260
+ }
261
+
262
+ module.exports = {
263
+ recordVerificationCommands,
264
+ DEFAULT_TIMEOUT_MS,
265
+ MAX_CAPTURE_BYTES,
266
+ MAX_TIMEOUT_MS,
267
+ recordVerificationCommand
268
+ };
@@ -441,7 +441,32 @@ function assertReady(workflow, nodeId) {
441
441
  if (!node) throw runtimeError(`Unknown workflow node: ${nodeId}`, 'UNKNOWN_WORKFLOW_NODE');
442
442
  const runtimeNode = workflow.state.nodes[nodeId];
443
443
  if (runtimeNode.status !== NODE_STATES.READY) {
444
- throw runtimeError(`Node ${nodeId} is ${runtimeNode.status}, not READY`, 'NODE_NOT_READY');
444
+ const dependencies = (node.dependsOn || [])
445
+ .map((dependencyId) => ({
446
+ node: workflow.plan.nodes.find((candidate) => candidate.id === dependencyId),
447
+ state: workflow.state.nodes[dependencyId]
448
+ }))
449
+ .filter(({ state }) => state && !SUCCESS_STATES.has(state.status));
450
+ const details = dependencies.map(({ node: dependency, state }) =>
451
+ `Prerequisite node '${dependency?.id || 'unknown'}' is ${state.status}${dependency?.displayName ? ` (${dependency.displayName})` : ''}.`
452
+ );
453
+ const readyApproval = dependencies.length === 1
454
+ && dependencies[0].node?.type === 'approval'
455
+ && dependencies[0].state.status === NODE_STATES.READY
456
+ ? dependencies[0].node
457
+ : null;
458
+ if (readyApproval) {
459
+ details.push(
460
+ `Approve it explicitly with: ai-engineering-loop node approve ${readyApproval.id} --yes --by <name> --run ${workflow.run.runId}`
461
+ );
462
+ } else if (runtimeNode.reason) {
463
+ details.push(`Reason: ${runtimeNode.reason}.`);
464
+ }
465
+ throw runtimeError(
466
+ `Node ${nodeId} is ${runtimeNode.status}, not READY`,
467
+ 'NODE_NOT_READY',
468
+ details
469
+ );
445
470
  }
446
471
  return node;
447
472
  }
@@ -0,0 +1,21 @@
1
+ # Major-version migrations
2
+
3
+ `update apply` runs `ai-engineering-loop migrate --from <old-version>` with the
4
+ new version whenever an update crosses a major (1.x -> 2.x). For each major in
5
+ `(old, new]` that has a `migrations/<major>.js`, AEL runs `migrateHome` once and
6
+ `migrateProject` once per registered project, and records what ran in
7
+ `~/.ai-engineering-loop/migrations.json`.
8
+
9
+ ```js
10
+ // migrations/2.js
11
+ module.exports = {
12
+ major: 2,
13
+ description: 'Rename X to Y in project context',
14
+ migrateHome({ home }) {},
15
+ migrateProject({ projectDir }) {}
16
+ };
17
+ ```
18
+
19
+ Rules: idempotent (safe to run twice), no network, touch only AEL-managed files,
20
+ and describe the change in CHANGELOG.md under the major's heading. No migration
21
+ ships yet (1.x).
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "ai-engineering-loop",
3
- "version": "1.12.0",
3
+ "version": "1.14.0",
4
4
  "description": "A visual workspace that helps AI coding agents plan, build, review, and ship reliable software.",
5
5
  "main": "bin/ai-engineering-loop.js",
6
6
  "bin": {
@@ -27,6 +27,8 @@
27
27
  ".claude/skills/",
28
28
  "LICENSE",
29
29
  "THIRD_PARTY_NOTICES.md",
30
+ "CHANGELOG.md",
31
+ "migrations/",
30
32
  "SECURITY.md",
31
33
  "SUPPORT.md",
32
34
  "README.md"
@@ -38,7 +40,10 @@
38
40
  "eval": "node bin/ai-engineering-loop.js eval",
39
41
  "audit:package": "node scripts/audit-package.js",
40
42
  "verify:release": "node scripts/verify-release.js",
41
- "prepublishOnly": "npm test && npm run doctor && npm run eval && npm run audit:package"
43
+ "prepublishOnly": "npm run check:skills && npm test && npm run doctor && npm run eval && npm run audit:package",
44
+ "build:skills": "node scripts/build-host-skills.js",
45
+ "check:skills": "node scripts/build-host-skills.js --check",
46
+ "measure": "node scripts/measure.js"
42
47
  },
43
48
  "engines": {
44
49
  "node": ">=18"
@@ -15,7 +15,7 @@ Host files (`.claude/agents/`, `.grok/agents/`, `.agents/`) may differ only in Y
15
15
  - Pass artifact **paths**, not Maker chat.
16
16
  - Use the runtime policy `reviewProfile` to size context packs. Default `lean` protects Codex/GPT Plus-style sessions from repeated full-file prompts while keeping all gates intact.
17
17
  - Prefer `npx ai-engineering-loop context diff-hunks --run <run-id>` for review. It writes a private hunk-only pack with file summaries and unresolved findings, so reviewers do not need full source bodies unless a cited hunk is insufficient.
18
- - Run `npx ai-engineering-loop verification summarize --run <run-id>` after writing `verification.json`; pass the summary path to Judge before raw logs.
18
+ - Prefer `npx ai-engineering-loop verification record --run <run-id> -- <executable> [args...]` to capture bounded, redacted command evidence without invoking a shell implicitly; it writes `verification.json` and refreshes its summary. Run `verification summarize --run <run-id>` when evidence was authored manually, and pass the compact summary to Judge before any raw logs.
19
19
  - Spawn DA and Judge as siblings. Do not nest.
20
20
  - Prefer named types `devil-advocate` and `judge`. Use `general-purpose` only if the named type is rejected.
21
21
  - Skip `*.css`, `*report-css*`, generated/vendor. Do not run `git log`.
@@ -20,9 +20,9 @@
20
20
  "executionIdentity": { "type": "string", "minLength": 1 },
21
21
  "startTime": { "type": "string", "minLength": 1 },
22
22
  "endTime": { "type": "string", "minLength": 1 },
23
- "exitCode": { "const": 0 },
23
+ "exitCode": { "type": ["integer", "null"] },
24
24
  "stdout": { "type": "string", "minLength": 1 },
25
- "timeoutStatus": { "const": "COMPLETED" }
25
+ "timeoutStatus": { "enum": ["COMPLETED", "TIMED_OUT", "NOT_RUN"] }
26
26
  },
27
27
  "additionalProperties": true
28
28
  }