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.
- package/.agents/skills/ai-engineering-loop/SKILL.md +4 -4
- package/.agents/skills/ai-engineering-loop/references/loop-deliver.md +2 -2
- package/.agents/skills/ai-engineering-loop/references/loop-goal.md +3 -3
- package/.agents/skills/ai-engineering-loop/references/loop-maker.md +1 -0
- package/.agents/skills/ai-engineering-loop/references/loop-review.md +3 -4
- package/.agents/skills/ai-engineering-loop/references/loop-verify.md +3 -3
- package/.claude/agents/judge.md +5 -2
- package/.grok/agents/judge.md +5 -2
- package/CHANGELOG.md +35 -0
- package/agents/maker.md +1 -1
- package/agents/shared/judge.body.md +5 -2
- package/bin/ai-engineering-loop.js +303 -77
- package/core/definition-of-done.md +2 -2
- package/core/escalation-policy.md +1 -1
- package/core/goal-contract.md +1 -1
- package/core/iteration-policy.md +2 -1
- package/core/judge-policy.md +10 -4
- package/core/orchestration-model.md +8 -7
- package/core/repo-config-schema.md +2 -2
- package/core/runtime-safety.md +3 -3
- package/lib/auto-update.js +8 -14
- package/lib/claimed-vs-reality.js +2 -2
- package/lib/cli-args.js +3 -1
- package/lib/docs.js +1 -1
- package/lib/doctor.js +0 -6
- package/lib/escalation.js +1 -1
- package/lib/fsutil.js +88 -0
- package/lib/gates.js +69 -27
- package/lib/generate-workflow.js +0 -29
- package/lib/goal-runtime.js +3 -2
- package/lib/guard-hooks.js +26 -7
- package/lib/guard.js +100 -10
- package/lib/hosts/doctor.js +1 -5
- package/lib/impact-map.js +4 -9
- package/lib/jsonl-ledger.js +104 -0
- package/lib/learn.js +4 -9
- package/lib/loop-groups.js +0 -25
- package/lib/migrations.js +1 -5
- package/lib/no-progress.js +119 -0
- package/lib/node-evidence.js +1 -5
- package/lib/orchestration.js +5 -361
- package/lib/personal-workflow.js +1 -1
- package/lib/quick.js +152 -0
- package/lib/receipt.js +1 -5
- package/lib/recipe-builder.js +3 -35
- package/lib/recipe-graph.js +2 -63
- package/lib/recipe.js +2 -4
- package/lib/review-ingest.js +116 -0
- package/lib/run-abandon.js +2 -1
- package/lib/run-compaction.js +4 -12
- package/lib/run-interactions.js +16 -71
- package/lib/run-lifecycle.js +25 -77
- package/lib/run-state.js +68 -17
- package/lib/run-watcher.js +11 -14
- package/lib/runtime-files.js +45 -1
- package/lib/safe-context.js +17 -6
- package/lib/sandbox.js +2 -1
- package/lib/smart-context.js +3 -13
- package/lib/spawn-command.js +94 -0
- package/lib/studio-layout.js +2 -8
- package/lib/studio-runtime.js +2 -1
- package/lib/studio-server.js +25 -5
- package/lib/tier.js +36 -10
- package/lib/user-state.js +2 -17
- package/lib/verification-lanes.js +115 -0
- package/lib/verification-recorder.js +110 -22
- package/lib/workflow-runtime.js +7 -4
- package/package.json +1 -2
- package/policies/review-budget.md +1 -1
- package/.claude/skills/ai-engineering-loop/SKILL.md +0 -62
- package/.claude/skills/ai-engineering-loop/references/loop-commands.md +0 -24
- package/.claude/skills/ai-engineering-loop/references/loop-deliver.md +0 -10
- package/.claude/skills/ai-engineering-loop/references/loop-goal.md +0 -11
- package/.claude/skills/ai-engineering-loop/references/loop-hosts.md +0 -48
- package/.claude/skills/ai-engineering-loop/references/loop-maker.md +0 -14
- package/.claude/skills/ai-engineering-loop/references/loop-review.md +0 -20
- package/.claude/skills/ai-engineering-loop/references/loop-risky.md +0 -9
- package/.claude/skills/ai-engineering-loop/references/loop-verify.md +0 -20
- package/.claude/skills/animate/RECIPES.md +0 -324
- package/.claude/skills/animate/SKILL.md +0 -207
- package/.claude/skills/animate-expo/RECIPES.md +0 -385
- package/.claude/skills/animate-expo/SKILL.md +0 -263
- package/.claude/skills/animation-vocabulary/SKILL.md +0 -181
- package/.claude/skills/apple-design/SKILL.md +0 -290
- package/.claude/skills/ask-sonner/API.md +0 -64
- package/.claude/skills/ask-sonner/SKILL.md +0 -88
- package/.claude/skills/backend-development/SKILL.md +0 -272
- package/.claude/skills/backend-development/references/api-design-guidelines.md +0 -95
- package/.claude/skills/backend-development/references/query-and-database-best-practices.md +0 -53
- package/.claude/skills/backend-development/references/security-checklist.md +0 -60
- package/.claude/skills/emil-design-eng/SKILL.md +0 -674
- package/.claude/skills/find-animation-opportunities/SKILL.md +0 -140
- package/.claude/skills/improve-animations/AUDIT.md +0 -115
- package/.claude/skills/improve-animations/PLAN-TEMPLATE.md +0 -73
- package/.claude/skills/improve-animations/SKILL.md +0 -109
- package/.claude/skills/mobile-native/SKILL.md +0 -311
- package/.claude/skills/pick-ui-library/SKILL.md +0 -85
- package/.claude/skills/prototype/PICKER.md +0 -197
- package/.claude/skills/prototype/SKILL.md +0 -98
- package/.claude/skills/review-animations/SKILL.md +0 -120
- package/.claude/skills/review-animations/STANDARDS.md +0 -187
- package/.claude/skills/write-swift/SKILL.md +0 -396
- package/lib/intern-catalog.js +0 -53
|
@@ -0,0 +1,115 @@
|
|
|
1
|
+
'use strict';
|
|
2
|
+
|
|
3
|
+
// Verification lanes: a fast `related` lane for iterations and one `final`
|
|
4
|
+
// full run before delivery when the gated verification was related-only.
|
|
5
|
+
|
|
6
|
+
const fs = require('fs');
|
|
7
|
+
const path = require('path');
|
|
8
|
+
const { runsDir } = require('./run-state.js');
|
|
9
|
+
const { extractChangedPaths } = require('./escalation.js');
|
|
10
|
+
|
|
11
|
+
const FINAL_FILE = 'final-verification.json';
|
|
12
|
+
const FILES_TOKEN = '{files}';
|
|
13
|
+
|
|
14
|
+
function laneError(message, code) {
|
|
15
|
+
return Object.assign(new Error(message), { code });
|
|
16
|
+
}
|
|
17
|
+
|
|
18
|
+
// `- **key**: `command`` lines from .ai-engineering-loop/verification.md.
|
|
19
|
+
function verificationCommands(rootDir) {
|
|
20
|
+
let text = '';
|
|
21
|
+
try {
|
|
22
|
+
text = fs.readFileSync(path.join(rootDir, '.ai-engineering-loop', 'verification.md'), 'utf8');
|
|
23
|
+
} catch {
|
|
24
|
+
return {};
|
|
25
|
+
}
|
|
26
|
+
const commands = {};
|
|
27
|
+
for (const match of text.matchAll(/\*\*([a-z0-9_]+)\*\*:\s*`([^`]+)`/gi)) {
|
|
28
|
+
if (!Object.hasOwn(commands, match[1])) commands[match[1]] = match[2].trim();
|
|
29
|
+
}
|
|
30
|
+
return commands;
|
|
31
|
+
}
|
|
32
|
+
|
|
33
|
+
// Changed files of the gated Maker diff that still exist (deleted files have
|
|
34
|
+
// no tests to relate to).
|
|
35
|
+
function relatedFiles(rootDir, run) {
|
|
36
|
+
const artifact = run.artifacts?.diff;
|
|
37
|
+
if (!artifact?.path) throw laneError('Maker evidence is not gated yet. Run `gate maker` first.', 'MAKER_NOT_GATED');
|
|
38
|
+
const diff = fs.readFileSync(path.join(rootDir, artifact.path), 'utf8');
|
|
39
|
+
return [...new Set(extractChangedPaths(diff))]
|
|
40
|
+
.filter((file) => !file.startsWith('.ai-engineering-loop/'))
|
|
41
|
+
.filter((file) => {
|
|
42
|
+
try {
|
|
43
|
+
return fs.statSync(path.join(rootDir, file)).isFile();
|
|
44
|
+
} catch {
|
|
45
|
+
return false;
|
|
46
|
+
}
|
|
47
|
+
});
|
|
48
|
+
}
|
|
49
|
+
|
|
50
|
+
// Expand `{files}` in the project's test_related command. `split` is the
|
|
51
|
+
// CLI's command splitter so quoting rules stay identical to `--cmd`.
|
|
52
|
+
function relatedCommand(rootDir, run, { split, shell = false } = {}) {
|
|
53
|
+
const template = verificationCommands(rootDir).test_related;
|
|
54
|
+
if (!template) {
|
|
55
|
+
throw laneError(
|
|
56
|
+
'No test_related command in .ai-engineering-loop/verification.md. Add e.g. - **test_related**: `npx jest --findRelatedTests {files}`, or pass --cmd.',
|
|
57
|
+
'NO_RELATED_COMMAND'
|
|
58
|
+
);
|
|
59
|
+
}
|
|
60
|
+
if (!template.includes(FILES_TOKEN)) {
|
|
61
|
+
throw laneError(`test_related must contain ${FILES_TOKEN}`, 'INVALID_RELATED_COMMAND');
|
|
62
|
+
}
|
|
63
|
+
const files = relatedFiles(rootDir, run);
|
|
64
|
+
if (!files.length) {
|
|
65
|
+
throw laneError('The gated diff has no existing files to relate tests to; run the full `verify`.', 'NO_RELATED_FILES');
|
|
66
|
+
}
|
|
67
|
+
if (shell) {
|
|
68
|
+
const quoted = files.map((file) => `'${file.replace(/'/g, `'\\''`)}'`).join(' ');
|
|
69
|
+
return { ...split(template.split(FILES_TOKEN).join(quoted), true), files };
|
|
70
|
+
}
|
|
71
|
+
const parsed = split(template.replace(FILES_TOKEN, 'AEL_FILES_PLACEHOLDER'), false);
|
|
72
|
+
const args = parsed.args.flatMap((arg) => (arg === 'AEL_FILES_PLACEHOLDER' ? files : [arg]));
|
|
73
|
+
return { ...parsed, args, files };
|
|
74
|
+
}
|
|
75
|
+
|
|
76
|
+
function readJson(filePath) {
|
|
77
|
+
try {
|
|
78
|
+
return JSON.parse(fs.readFileSync(filePath, 'utf8'));
|
|
79
|
+
} catch {
|
|
80
|
+
return null;
|
|
81
|
+
}
|
|
82
|
+
}
|
|
83
|
+
|
|
84
|
+
const passed = (record) => record && record.exitCode === 0 && record.timeoutStatus === 'COMPLETED';
|
|
85
|
+
const isFull = (record) => (record.scope || 'full') !== 'related';
|
|
86
|
+
|
|
87
|
+
// Whether delivery needs (or already has) a full run for the gated diff.
|
|
88
|
+
function finalVerificationStatus(rootDir, run) {
|
|
89
|
+
const dir = path.join(runsDir(rootDir), run.runId);
|
|
90
|
+
const bundle = readJson(path.join(dir, 'verification.json'));
|
|
91
|
+
const commands = bundle?.commands || [];
|
|
92
|
+
if (!commands.length || commands.some(isFull)) {
|
|
93
|
+
return { required: false, satisfied: true, reason: 'gated verification already ran full scope' };
|
|
94
|
+
}
|
|
95
|
+
const final = readJson(path.join(dir, FINAL_FILE));
|
|
96
|
+
const diffHash = run.artifacts?.diff?.sha256;
|
|
97
|
+
if (!final) return { required: true, satisfied: false, reason: `missing ${FINAL_FILE}; run \`verify --final --run ${run.runId}\`` };
|
|
98
|
+
if (final.runId !== run.runId || final.diffHash !== diffHash) {
|
|
99
|
+
return { required: true, satisfied: false, reason: `${FINAL_FILE} is not bound to the gated Maker diff` };
|
|
100
|
+
}
|
|
101
|
+
const records = final.commands || [];
|
|
102
|
+
if (!records.length || !records.every(passed)) {
|
|
103
|
+
return { required: true, satisfied: false, reason: `${FINAL_FILE} has a failing or missing command` };
|
|
104
|
+
}
|
|
105
|
+
return { required: true, satisfied: true, reason: 'final full verification passed' };
|
|
106
|
+
}
|
|
107
|
+
|
|
108
|
+
module.exports = {
|
|
109
|
+
FINAL_FILE,
|
|
110
|
+
FILES_TOKEN,
|
|
111
|
+
verificationCommands,
|
|
112
|
+
relatedFiles,
|
|
113
|
+
relatedCommand,
|
|
114
|
+
finalVerificationStatus
|
|
115
|
+
};
|
|
@@ -8,16 +8,19 @@ const {
|
|
|
8
8
|
getCurrentRun,
|
|
9
9
|
getGitRevision,
|
|
10
10
|
loadRun,
|
|
11
|
-
runsDir
|
|
11
|
+
runsDir,
|
|
12
|
+
withFileLock
|
|
12
13
|
} = require('./run-state.js');
|
|
13
14
|
const { hashFile } = require('./gates.js');
|
|
14
15
|
const { redactHomePaths, redactSecrets } = require('./safe-context.js');
|
|
15
16
|
const { writeVerificationSummary } = require('./verification-summary.js');
|
|
17
|
+
const { killProcessTree, resolveSpawn } = require('./spawn-command.js');
|
|
16
18
|
|
|
17
19
|
const MAX_CAPTURE_BYTES = 256 * 1024;
|
|
18
20
|
const DEFAULT_TIMEOUT_MS = 30 * 60 * 1000;
|
|
19
21
|
const MAX_TIMEOUT_MS = 60 * 60 * 1000;
|
|
20
22
|
const KILL_GRACE_MS = 2_000;
|
|
23
|
+
const PIPE_DRAIN_MS = 10_000;
|
|
21
24
|
|
|
22
25
|
function recorderError(message, code = 'VERIFICATION_RECORD_FAILED') {
|
|
23
26
|
const error = new Error(message);
|
|
@@ -137,29 +140,54 @@ function runCommand(command, args, { cwd, timeoutMs, shell }) {
|
|
|
137
140
|
let timedOut = false;
|
|
138
141
|
let launchError = null;
|
|
139
142
|
let forceKillTimer = null;
|
|
140
|
-
|
|
143
|
+
let pipeTimer = null;
|
|
144
|
+
let settled = false;
|
|
145
|
+
const target = shell ? { command, args: [], options: {} } : resolveSpawn(command, args);
|
|
146
|
+
// POSIX: lead a process group so a timeout can stop grandchildren too.
|
|
147
|
+
const detached = process.platform !== 'win32';
|
|
148
|
+
const child = spawn(target.command, target.args, {
|
|
141
149
|
cwd,
|
|
142
150
|
env: process.env,
|
|
143
151
|
shell: Boolean(shell),
|
|
144
|
-
|
|
152
|
+
detached,
|
|
153
|
+
windowsHide: true,
|
|
154
|
+
stdio: ['ignore', 'pipe', 'pipe'],
|
|
155
|
+
...target.options
|
|
145
156
|
});
|
|
146
157
|
const stdout = captureStream(child.stdout);
|
|
147
158
|
const stderr = captureStream(child.stderr);
|
|
159
|
+
// A detached group no longer receives the terminal's Ctrl-C; forward it.
|
|
160
|
+
const forward = (signal) => {
|
|
161
|
+
killProcessTree(child, 'SIGKILL');
|
|
162
|
+
process.removeListener('SIGINT', onSigint);
|
|
163
|
+
process.removeListener('SIGTERM', onSigterm);
|
|
164
|
+
process.kill(process.pid, signal);
|
|
165
|
+
};
|
|
166
|
+
const onSigint = () => forward('SIGINT');
|
|
167
|
+
const onSigterm = () => forward('SIGTERM');
|
|
168
|
+
if (detached) {
|
|
169
|
+
process.once('SIGINT', onSigint);
|
|
170
|
+
process.once('SIGTERM', onSigterm);
|
|
171
|
+
}
|
|
148
172
|
|
|
149
173
|
const timeout = setTimeout(() => {
|
|
150
174
|
timedOut = true;
|
|
151
|
-
child
|
|
152
|
-
forceKillTimer = setTimeout(() => child
|
|
175
|
+
killProcessTree(child, 'SIGTERM');
|
|
176
|
+
forceKillTimer = setTimeout(() => killProcessTree(child, 'SIGKILL'), KILL_GRACE_MS);
|
|
153
177
|
forceKillTimer.unref?.();
|
|
154
178
|
}, timeoutMs);
|
|
155
179
|
timeout.unref?.();
|
|
156
180
|
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
child.once('close', (code, signal) => {
|
|
181
|
+
const finish = (code, signal) => {
|
|
182
|
+
if (settled) return;
|
|
183
|
+
settled = true;
|
|
161
184
|
clearTimeout(timeout);
|
|
162
185
|
if (forceKillTimer) clearTimeout(forceKillTimer);
|
|
186
|
+
if (pipeTimer) clearTimeout(pipeTimer);
|
|
187
|
+
process.removeListener('SIGINT', onSigint);
|
|
188
|
+
process.removeListener('SIGTERM', onSigterm);
|
|
189
|
+
child.stdout?.destroy();
|
|
190
|
+
child.stderr?.destroy();
|
|
163
191
|
const finished = new Date();
|
|
164
192
|
const rawStdout = stdout.value();
|
|
165
193
|
const rawStderr = launchError ? launchError.message : stderr.value();
|
|
@@ -182,7 +210,55 @@ function runCommand(command, args, { cwd, timeoutMs, shell }) {
|
|
|
182
210
|
...(launchError ? { launchError: true } : {}),
|
|
183
211
|
...(timedOut ? { summary: `Command timed out after ${timeoutMs} ms.` } : {})
|
|
184
212
|
});
|
|
213
|
+
};
|
|
214
|
+
|
|
215
|
+
child.once('error', (error) => {
|
|
216
|
+
launchError = error;
|
|
217
|
+
if (!child.pid) finish(null, null);
|
|
218
|
+
});
|
|
219
|
+
// 'close' waits for the pipes; a grandchild that escaped the group can
|
|
220
|
+
// hold them open forever. After the child exits, give the pipes a grace
|
|
221
|
+
// period to drain and then stop waiting.
|
|
222
|
+
child.once('exit', (code, signal) => {
|
|
223
|
+
pipeTimer = setTimeout(() => {
|
|
224
|
+
killProcessTree(child, 'SIGKILL');
|
|
225
|
+
finish(code, signal);
|
|
226
|
+
}, timedOut ? KILL_GRACE_MS : PIPE_DRAIN_MS);
|
|
227
|
+
pipeTimer.unref?.();
|
|
185
228
|
});
|
|
229
|
+
child.once('close', (code, signal) => finish(code, signal));
|
|
230
|
+
});
|
|
231
|
+
}
|
|
232
|
+
|
|
233
|
+
// Commands can run for minutes, and other recorders may finish meanwhile.
|
|
234
|
+
// Re-read the Run and the bundle under a lock right before writing so no
|
|
235
|
+
// result is lost and nothing lands after the verification gate.
|
|
236
|
+
const passedRecord = (record) => record.exitCode === 0 && record.timeoutStatus === 'COMPLETED';
|
|
237
|
+
|
|
238
|
+
// Re-read under a lock right before writing so concurrent recorders never
|
|
239
|
+
// drop each other's results. `final` writes final-verification.json, which is
|
|
240
|
+
// recorded after the verification gate and has no summary.
|
|
241
|
+
function appendRecordedCommands(rootDir, runId, results, { filePath, gitRevision, diffHash, final = false }) {
|
|
242
|
+
return withFileLock(`${filePath}.lock`, () => {
|
|
243
|
+
const run = loadRun(rootDir, runId);
|
|
244
|
+
if (!final && run.artifacts?.verification) {
|
|
245
|
+
throw recorderError('Verification passed its gate while the command ran. Do not mutate gated evidence; start a new verification iteration instead.', 'VERIFICATION_ALREADY_GATED');
|
|
246
|
+
}
|
|
247
|
+
if (resolveDiff(rootDir, run) !== diffHash) {
|
|
248
|
+
throw recorderError('The gated Maker diff changed while the command ran. Re-run the Maker gate.', 'STALE_DIFF');
|
|
249
|
+
}
|
|
250
|
+
const bundle = readExistingBundle(filePath, { runId, gitRevision, diffHash });
|
|
251
|
+
// A re-run on the same diff supersedes that command's earlier failure; the
|
|
252
|
+
// failure stays on record under `superseded` and the gate sees the latest.
|
|
253
|
+
const rerun = new Set(results.map((result) => result.command));
|
|
254
|
+
const stale = bundle.commands.filter((record) => rerun.has(record.command) && !passedRecord(record));
|
|
255
|
+
if (stale.length) {
|
|
256
|
+
bundle.superseded = [...(bundle.superseded || []), ...stale];
|
|
257
|
+
bundle.commands = bundle.commands.filter((record) => !stale.includes(record));
|
|
258
|
+
}
|
|
259
|
+
bundle.commands.push(...results);
|
|
260
|
+
atomicWriteJson(filePath, bundle);
|
|
261
|
+
return final ? null : writeVerificationSummary(rootDir, { runId }).summary;
|
|
186
262
|
});
|
|
187
263
|
}
|
|
188
264
|
|
|
@@ -202,12 +278,9 @@ async function recordVerificationCommand(rootDir, {
|
|
|
202
278
|
const diffHash = resolveDiff(rootDir, run);
|
|
203
279
|
const gitRevision = getGitRevision(rootDir);
|
|
204
280
|
const filePath = path.join(runsDir(rootDir), run.runId, 'verification.json');
|
|
205
|
-
|
|
281
|
+
readExistingBundle(filePath, { runId: run.runId, gitRevision, diffHash });
|
|
206
282
|
const result = await runCommand(command, args, { cwd: rootDir, timeoutMs, shell });
|
|
207
|
-
|
|
208
|
-
atomicWriteJson(filePath, bundle);
|
|
209
|
-
|
|
210
|
-
const summary = writeVerificationSummary(rootDir, { runId: run.runId }).summary;
|
|
283
|
+
const summary = appendRecordedCommands(rootDir, run.runId, [result], { filePath, gitRevision, diffHash });
|
|
211
284
|
return {
|
|
212
285
|
runId: run.runId,
|
|
213
286
|
path: path.relative(rootDir, filePath).split(path.sep).join('/'),
|
|
@@ -219,11 +292,18 @@ async function recordVerificationCommand(rootDir, {
|
|
|
219
292
|
// Issue #34: run several verification commands in one CLI call. Independent
|
|
220
293
|
// commands run in parallel by default (`serial: true` opts out); results are
|
|
221
294
|
// appended to verification.json in the given order, in one atomic write.
|
|
295
|
+
// `scope` tags records ('related' for the fast lane, 'full' otherwise).
|
|
296
|
+
// `target: 'final'` writes final-verification.json for a run whose gated
|
|
297
|
+
// verification was related-only. A passing record for the same command, diff,
|
|
298
|
+
// and revision is reused unless `fresh` is set.
|
|
222
299
|
async function recordVerificationCommands(rootDir, {
|
|
223
300
|
runId,
|
|
224
301
|
commands = [],
|
|
225
302
|
serial = false,
|
|
226
|
-
timeoutMs = DEFAULT_TIMEOUT_MS
|
|
303
|
+
timeoutMs = DEFAULT_TIMEOUT_MS,
|
|
304
|
+
scope = null,
|
|
305
|
+
target = 'verification',
|
|
306
|
+
fresh = false
|
|
227
307
|
} = {}) {
|
|
228
308
|
if (!Array.isArray(commands) || commands.length === 0) {
|
|
229
309
|
throw recorderError('Provide at least one verification command.', 'INVALID_COMMAND');
|
|
@@ -232,14 +312,22 @@ async function recordVerificationCommands(rootDir, {
|
|
|
232
312
|
validateRecordingRequest({ command: item.command, args: item.args || [], timeoutMs, shell: Boolean(item.shell) });
|
|
233
313
|
}
|
|
234
314
|
const run = resolveRun(rootDir, runId);
|
|
235
|
-
|
|
315
|
+
const final = target === 'final';
|
|
316
|
+
if (!final && run.artifacts?.verification) {
|
|
236
317
|
throw recorderError('Verification has already passed its gate. Do not mutate gated evidence; start a new verification iteration instead.', 'VERIFICATION_ALREADY_GATED');
|
|
237
318
|
}
|
|
238
319
|
const diffHash = resolveDiff(rootDir, run);
|
|
239
320
|
const gitRevision = getGitRevision(rootDir);
|
|
240
|
-
const filePath = path.join(runsDir(rootDir), run.runId, 'verification.json');
|
|
321
|
+
const filePath = path.join(runsDir(rootDir), run.runId, final ? 'final-verification.json' : 'verification.json');
|
|
241
322
|
const bundle = readExistingBundle(filePath, { runId: run.runId, gitRevision, diffHash });
|
|
242
|
-
const exec = (item) =>
|
|
323
|
+
const exec = async (item) => {
|
|
324
|
+
const display = displayCommand(item.command, item.args || []);
|
|
325
|
+
const previous = fresh ? null : bundle.commands.find((record) => record.command === display && passedRecord(record)
|
|
326
|
+
&& (record.scope || 'full') === (scope || 'full'));
|
|
327
|
+
if (previous) return { ...previous, reused: true };
|
|
328
|
+
const result = await runCommand(item.command, item.args || [], { cwd: rootDir, timeoutMs, shell: Boolean(item.shell) });
|
|
329
|
+
return scope ? { ...result, scope } : result;
|
|
330
|
+
};
|
|
243
331
|
let results;
|
|
244
332
|
if (serial) {
|
|
245
333
|
results = [];
|
|
@@ -247,15 +335,15 @@ async function recordVerificationCommands(rootDir, {
|
|
|
247
335
|
} else {
|
|
248
336
|
results = await Promise.all(commands.map(exec));
|
|
249
337
|
}
|
|
250
|
-
|
|
251
|
-
|
|
252
|
-
|
|
338
|
+
const summary = appendRecordedCommands(rootDir, run.runId, results.filter((result) => !result.reused), {
|
|
339
|
+
filePath, gitRevision, diffHash, final
|
|
340
|
+
});
|
|
253
341
|
return {
|
|
254
342
|
runId: run.runId,
|
|
255
343
|
path: path.relative(rootDir, filePath).split(path.sep).join('/'),
|
|
256
344
|
commands: results,
|
|
257
345
|
summary,
|
|
258
|
-
passed: results.every(
|
|
346
|
+
passed: results.every(passedRecord)
|
|
259
347
|
};
|
|
260
348
|
}
|
|
261
349
|
|
package/lib/workflow-runtime.js
CHANGED
|
@@ -2,8 +2,10 @@
|
|
|
2
2
|
|
|
3
3
|
const fs = require('fs');
|
|
4
4
|
const path = require('path');
|
|
5
|
+
const { ACTOR_ID } = require('./fsutil.js');
|
|
5
6
|
const { sha256 } = require('./recipe.js');
|
|
6
7
|
const { redactSecrets } = require('./safe-context.js');
|
|
8
|
+
const { repairJsonlTail, splitJsonlLines } = require('./runtime-files.js');
|
|
7
9
|
const {
|
|
8
10
|
RUN_STATES,
|
|
9
11
|
atomicWriteJson,
|
|
@@ -205,7 +207,7 @@ function readEvents(filePath, runId, graphHash) {
|
|
|
205
207
|
throw runtimeError('Workflow event log must be a regular file', 'INVALID_WORKFLOW_EVENTS');
|
|
206
208
|
}
|
|
207
209
|
const text = fs.readFileSync(filePath, 'utf8');
|
|
208
|
-
const events = text
|
|
210
|
+
const events = splitJsonlLines(text).lines.map((line, index) => {
|
|
209
211
|
try {
|
|
210
212
|
return JSON.parse(line);
|
|
211
213
|
} catch (cause) {
|
|
@@ -286,6 +288,7 @@ function appendEvent(filePath, event) {
|
|
|
286
288
|
const noFollow = fs.constants.O_NOFOLLOW || 0;
|
|
287
289
|
let descriptor;
|
|
288
290
|
try {
|
|
291
|
+
repairJsonlTail(filePath);
|
|
289
292
|
descriptor = fs.openSync(
|
|
290
293
|
filePath,
|
|
291
294
|
fs.constants.O_APPEND | fs.constants.O_WRONLY | noFollow
|
|
@@ -431,7 +434,7 @@ function resetLoopNodes(workflow, group, iteration, now) {
|
|
|
431
434
|
}
|
|
432
435
|
|
|
433
436
|
function assertDecisionActor(actor) {
|
|
434
|
-
if (
|
|
437
|
+
if (!ACTOR_ID.test(String(actor || ''))) {
|
|
435
438
|
throw runtimeError('actor must be a short account identifier', 'INVALID_LOOP_ACTOR');
|
|
436
439
|
}
|
|
437
440
|
}
|
|
@@ -950,7 +953,7 @@ function retryWorkflowNode(rootDir, nodeId, { runId, now = new Date() } = {}) {
|
|
|
950
953
|
function approveWorkflowNode(rootDir, nodeId, { runId, approvedBy = 'human', now = new Date() } = {}) {
|
|
951
954
|
const resolved = resolveRunId(rootDir, runId);
|
|
952
955
|
return withWorkflowLock(rootDir, resolved, () => {
|
|
953
|
-
if (
|
|
956
|
+
if (!ACTOR_ID.test(approvedBy)) {
|
|
954
957
|
throw runtimeError('approvedBy must be a short account identifier', 'INVALID_APPROVER');
|
|
955
958
|
}
|
|
956
959
|
const workflow = loadWorkflow(rootDir, resolved);
|
|
@@ -1080,7 +1083,7 @@ function cancelWorkflowRun(
|
|
|
1080
1083
|
const resolved = resolveRunId(rootDir, runId);
|
|
1081
1084
|
return withWorkflowLock(rootDir, resolved, () => {
|
|
1082
1085
|
let workflow = loadWorkflow(rootDir, resolved);
|
|
1083
|
-
if (
|
|
1086
|
+
if (!ACTOR_ID.test(String(actor))) {
|
|
1084
1087
|
throw runtimeError('Cancellation actor must be a short account identifier', 'INVALID_RUN_ACTOR');
|
|
1085
1088
|
}
|
|
1086
1089
|
const cleanReason = redactSecrets(String(reason || '').trim()).text;
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "ai-engineering-loop",
|
|
3
|
-
"version": "2.
|
|
3
|
+
"version": "2.3.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": {
|
|
@@ -22,7 +22,6 @@
|
|
|
22
22
|
".agents/",
|
|
23
23
|
".grok/",
|
|
24
24
|
".claude/agents/",
|
|
25
|
-
".claude/skills/",
|
|
26
25
|
"LICENSE",
|
|
27
26
|
"THIRD_PARTY_NOTICES.md",
|
|
28
27
|
"CHANGELOG.md",
|
|
@@ -11,7 +11,7 @@ Host files (`.claude/agents/`, `.grok/agents/`, `.agents/`) may differ only in Y
|
|
|
11
11
|
|
|
12
12
|
## Shared spawn rules
|
|
13
13
|
|
|
14
|
-
-
|
|
14
|
+
- Reviewers read the `review-pack` output or `RUN_DIR/diff.patch`; do not write a separate `tasks/current.diff`.
|
|
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.
|
|
@@ -1,62 +0,0 @@
|
|
|
1
|
-
---
|
|
2
|
-
name: ai-engineering-loop
|
|
3
|
-
description: Use when the user runs /ai-engineering-loop, says "run the engineering loop" or "devil's advocate review", asks to init or refresh living project context, or wants the Maker / Devil's Advocate / Judge engineering loop.
|
|
4
|
-
---
|
|
5
|
-
<!-- Generated from skill-src/ by npm run build:skills; do not edit. -->
|
|
6
|
-
|
|
7
|
-
# AI Engineering Loop
|
|
8
|
-
|
|
9
|
-
Stage details: `references/loop-*.md` beside this file (also via `docs`), read only on entering that stage. Specs and references: `npx ai-engineering-loop docs <name> [--section <h>]`; never read whole spec directories.
|
|
10
|
-
|
|
11
|
-
## Host rules
|
|
12
|
-
|
|
13
|
-
Same skill on every host. Before the first DA or Judge spawn, read your host's section in `loop-hosts` (exact tool, allowed keys, fallbacks).
|
|
14
|
-
1. Spawn `devil-advocate` then `judge` as fresh siblings with the host's own subagent tool, passing only keys its schema has; wait for each, never in the background or nested; `general-purpose` only if the named type is rejected. Never use a browser subagent as reviewer.
|
|
15
|
-
2. No subagent tool: same budgets in this session as `CONTEXT_ISOLATION_ONLY`; never claim independent execution.
|
|
16
|
-
3. A tool says "cannot determine the safety" or returns HTTP 400: stop that tool, do not retry, continue read-only, and tell the user (`loop-hosts`).
|
|
17
|
-
4. Models: the host catalog (`/models`, `grok models`); never type a model name.
|
|
18
|
-
|
|
19
|
-
## Commands
|
|
20
|
-
|
|
21
|
-
`init|status|refresh|sync-hosts|generate-adapter|generate-workflow`: run `npx ai-engineering-loop <command>` (`loop-commands`); do not commit unless asked. No task: offer `workflow interview` or a task; no Run. Otherwise: the loop.
|
|
22
|
-
|
|
23
|
-
## Loop
|
|
24
|
-
|
|
25
|
-
Map (not a second OS) of the 8-stage loop: Specify (stages 0-1), Make (stages 2-4), Review (stages 5-7), Deliver (stage 8). Parent = Maker + orchestrator; Devil's Advocate (DA) and Judge are fresh **siblings**, never nested or resumed. Gate failures override prose. Never edit `state.json`/`current.json`.
|
|
26
|
-
|
|
27
|
-
Tier (from `run --json`; it only rises). Do not skip Goal Contract, verification, Devil's Advocate, or Judge gates; the tier only decides who fills them.
|
|
28
|
-
- **T0** trivial (docs, typo, lint): `gate goal`, Maker, `verify`, claimed-vs-reality, `gate review`, `gate judge` (deterministic); no subagents.
|
|
29
|
-
- **T1** normal: frozen Goal, red test, `verify`, lean DA, `gate review --json`; spawn Judge only on `judgeRequired`.
|
|
30
|
-
- **T2** risky (HIGH_RISK_PATH, DOT business logic, >10 files): add `loop-risky` (blast radius, Judge on STRONG_MODEL). Unseen risk: `run --new --tier T2 --tier-reason <why>`.
|
|
31
|
-
|
|
32
|
-
0. `run --json [--mode report-only|assisted|unattended]` (`RUN_DIR` = `.ai-engineering-loop/runs/<runId>/`). Do not run `sync-hosts` per run; if `hostSkills.stale`, ask the user. Read `.ai-engineering-loop/glossary.md`, plus `lessons.md`/`workflow.md` if present.
|
|
33
|
-
1. Goal Contract: `loop-goal`. 2-4. Maker: `loop-maker`, then `gate maker`. 5. Verify: `loop-verify`. 6-7. DA and Judge: `loop-review`. 8. Deliver: `loop-deliver`.
|
|
34
|
-
|
|
35
|
-
Invariants (every tier):
|
|
36
|
-
- AC is a failure table. Do not freeze sunny-path-only. Chat agreement is not freeze.
|
|
37
|
-
- One red test per AC row (bugs: red repro) before the fix.
|
|
38
|
-
- Write claimed-vs-reality.md after `gate verification` passes. Do not spawn Devil's Advocate if the file is missing or any Claimed row lacks Reality.
|
|
39
|
-
- ITERATE at most to iteration 3, each with a **new** DA.
|
|
40
|
-
- Never infer human approval.
|
|
41
|
-
- After each child `budget record` real usage or `--unavailable`; never invent counts.
|
|
42
|
-
- No secrets or hidden reasoning in activity messages.
|
|
43
|
-
|
|
44
|
-
## Report header
|
|
45
|
-
|
|
46
|
-
When a subagent returned its own result (Grok: its own `subagent_id`):
|
|
47
|
-
|
|
48
|
-
```
|
|
49
|
-
Execution Mode: TRUE_INDEPENDENT_AGENT
|
|
50
|
-
Independent LLM Execution: PROVEN
|
|
51
|
-
Native Subagent Invocation: AVAILABLE
|
|
52
|
-
Review Method: True Independent Agent
|
|
53
|
-
```
|
|
54
|
-
|
|
55
|
-
When no subagent ran (tool AVAILABLE: mode adds `(reason: <why>)`):
|
|
56
|
-
|
|
57
|
-
```
|
|
58
|
-
Execution Mode: CONTEXT_ISOLATION_ONLY
|
|
59
|
-
Independent LLM Execution: NOT PROVEN
|
|
60
|
-
Native Subagent Invocation: UNAVAILABLE
|
|
61
|
-
Review Method: Clean-Slate Artifact Isolation Barrier
|
|
62
|
-
```
|
|
@@ -1,24 +0,0 @@
|
|
|
1
|
-
# Loop commands and Studio
|
|
2
|
-
|
|
3
|
-
- `init` / `status` / `refresh` / `sync-hosts`: run `npx ai-engineering-loop <command>` in the repo. `sync-hosts` installs the core pack into hosts that already exist; `--pack backend|design` opts in, and user-edited files are backed up first. Do not commit unless asked.
|
|
4
|
-
- `onboard`: load skill `project-onboarding` to fill `.ai-engineering-loop/architecture.md` and `conventions.md` from the code with evidence. Never automatic.
|
|
5
|
-
- `generate-adapter`: load skill `generate-adapter` if present. Grill Q1-Q5, then write `.ai-engineering-loop/adapter.md`. Do not start Maker.
|
|
6
|
-
- `generate-workflow`: load skill `generate-workflow` if present. Grill Q1-Q6. Q6 Maker intern: list numbered options from the host model catalog (see Host rules) plus `none`; if there is no catalog, offer only `none`. Do not type a model name. Write `.ai-engineering-loop/workflow.md` and an empty `lessons.md` if missing. Do not start Maker. Missing `maker_intern` means INVOCATION_UNAVAILABLE.
|
|
7
|
-
|
|
8
|
-
- Never run `update apply|auto|rollback|policy` unless the user asks; the CLI applies updates itself under the user's policy (`docs runtime-safety`).
|
|
9
|
-
|
|
10
|
-
## Personal workflow
|
|
11
|
-
|
|
12
|
-
No task (`ael`, "hi", "what can you do"): offer, numbered, 1) build my workflow, 2) start a task, 3) show status. Do not create a Run or edit files. For 1: `workflow interview --json`, show the pre-filled answers with their evidence, let the user confirm or change them, write the answers to a temp file, then `workflow propose --answers <file> --json` and show the diff. Install only after the user says yes: `workflow accept --proposal <id> --by <name>`. At a no-task start or at Deliver, show at most one pending `workflow suggest` proposal. Never accept for the user. The safety backbone cannot be removed (`docs personal-workflow`).
|
|
13
|
-
|
|
14
|
-
## Studio
|
|
15
|
-
|
|
16
|
-
Stage commands (`run`, `goal`, `gate`, `verify`, `review-pack`, `deliver`, `node start|activity|complete`) stream into an open Studio; `status --json` reports `studioUrl`. Emit `npx ai-engineering-loop activity heartbeat --run <runId> --phase <phase> --message <short factual summary>` only during long manual work, never before every stage. Before asking the human, persist the question with `npx ai-engineering-loop interaction question --run <runId> --id <id> --message <text>` so it appears once in Studio.
|
|
17
|
-
|
|
18
|
-
## Budget
|
|
19
|
-
|
|
20
|
-
`run --json` already reports the budget; run `budget status --run <runId>` only before each new iteration. After each child, `budget record --input <n> --output <n> --model <id> --run <runId>` from provider usage. No usage shown: `budget record --unavailable --run <runId>` once; ASSISTED continues and discloses it at delivery (do not ask the human); UNATTENDED fails that command, so stop and escalate. `budget pause` is the kill switch. The ledger mode is immutable. UNATTENDED or budget errors: `docs runtime-safety`.
|
|
21
|
-
|
|
22
|
-
## Resuming
|
|
23
|
-
|
|
24
|
-
`state --json` gives the current runId only when resuming a run. If stopping mid-loop, write `.ai-engineering-loop/tasks/handoff.md` (`docs handoff-policy`).
|
|
@@ -1,10 +0,0 @@
|
|
|
1
|
-
# Stage 8: Delivery
|
|
2
|
-
|
|
3
|
-
- After Judge PASS, run the `after_pass` hook, then the Stage 8 adapter from `.ai-engineering-loop/adapter.md`.
|
|
4
|
-
- Before any push, run `npx ai-engineering-loop doctor`: `✗ adapter-*` (unknown `adapter_type`, missing spec) must be fixed; `! adapter-*` (gh/glab not logged in, configured type differs from the detected one) needs a human look. `deliver` repeats this check: UNATTENDED stops before writing, ASSISTED only warns.
|
|
5
|
-
- The PR/MR body includes `Steps to Reproduce & Testing (QA)`; bugfix placeholders must not stay empty. Disclose any `budget record --unavailable`.
|
|
6
|
-
- Preview remote payloads; never include context packs, usage ledgers, raw logs, or credentials.
|
|
7
|
-
- ASSISTED: wait for explicit human approval and never infer it. Then one call: `npx ai-engineering-loop deliver --run <runId> --destination <where> --summary <text> --approve --by <name>` (approves READY approval nodes, writes `RUN_DIR/delivery.json` with `humanApproved: true`, runs `gate delivery`). Without `--approve` it refuses in ASSISTED.
|
|
8
|
-
- Long form: `node status --run <runId>`, `node approve delivery-approval --yes --by <name> --run <runId>` for each READY approval node, write `RUN_DIR/delivery.json`, then `gate delivery`. If the gate says a node is not READY, follow its prerequisite hint; never bypass approval.
|
|
9
|
-
- Commit before `deliver` (its receipt binds `HEAD`; screenshots: `--evidence AC-N=<https-url>`). Paste `RUN_DIR/receipt.md` into the PR/MR Receipt section unchanged; ❌ stays ❌ (`docs pr-receipt`).
|
|
10
|
-
- Only the delivery gate completes the run. Then run `learn` so the next Run's packs carry its lessons.
|
|
@@ -1,11 +0,0 @@
|
|
|
1
|
-
# Stage 1: Goal Contract
|
|
2
|
-
|
|
3
|
-
- If the user asks for ideas, list a short menu and wait; do not implement.
|
|
4
|
-
- Ambiguous task the user can answer: grill first (`docs grill-policy`): design tree, recommended answers, never ask look-up facts. T2 adds `loop-risky`.
|
|
5
|
-
- If the user prompt has no numbered AC, draft the contract (`docs goal-contract` if needed), list it, and wait. Chat agreement is not freeze.
|
|
6
|
-
- AC is a failure table: each row has a statement, required evidence, and failure cases. Do not freeze sunny-path-only. T0 may use 1-3 rows that still list failure cases.
|
|
7
|
-
- Emit `npx ai-engineering-loop activity goal-drafting --run <runId> --message <summary>`, write the contract JSON to a repository-local temporary file, then `npx ai-engineering-loop goal draft --run <runId> --file <file> --revision <currentRevision>` so Studio shows the exact draft.
|
|
8
|
-
- Wait for the explicit human freeze, then `npx ai-engineering-loop goal freeze --latest --run <runId> --by human` (or `--revision <r> --hash <h>`). T0 may write `RUN_DIR/goal-contract.json` and run `gate goal` directly.
|
|
9
|
-
- The freeze writes a DRAFT blast-radius map: `impact show --run <runId>`. ASSISTED: the human confirms or edits it (`impact confirm --by <name> [--allow <glob>] [--remove <path>]`); copy/CSS/comment-only goals: `impact skip --by <name> --reason <text>` (`docs blast-radius-map`).
|
|
10
|
-
- Do not edit production code until the Goal gate passes.
|
|
11
|
-
- After the freeze, work from the frozen contract (`goal show --run <runId>`), not the drafting chat; compact the conversation there if the host supports it.
|
|
@@ -1,48 +0,0 @@
|
|
|
1
|
-
# Host rules: subagent tools per host
|
|
2
|
-
|
|
3
|
-
Read only your host's section, before the first Devil's Advocate (DA) or Judge spawn. Every host shares the loop, budgets, and gates; only the spawn mechanics differ. REPORT_ONLY (`audit`) uses the same spawn tool for one `devil-advocate` report review (`loop-maker`); never report CONTEXT_ISOLATION_ONLY next to an AVAILABLE subagent tool without a reason. Modes: `TRUE_INDEPENDENT_AGENT`, `ISOLATED_AGENT_INSTANCE`, `FRESH_PROCESS_AGENT`, `CONTEXT_ISOLATION_ONLY`, `UNAVAILABLE`.
|
|
4
|
-
|
|
5
|
-
## Certification tiers
|
|
6
|
-
|
|
7
|
-
`hosts list` and `hosts doctor` show each host's tier (`lib/hosts/registry.js`). **full**: a real `default` recipe run with reviewer subagents and every gate is recorded (`certifiedBy`: recipe, AEL version, date). **experimental**: reviewer subagents install, no recorded run; follow your section below and report the mode you actually got. **instruction-only**: no subagents; run DA and Judge in-session as `CONTEXT_ISOLATION_ONLY`. The compact rules for these hosts: `npx ai-engineering-loop docs AGENTS` (≤2 KB). No host is `full` until such a run is recorded.
|
|
8
|
-
|
|
9
|
-
## Claude Code (and Kiro-backed strict proxies)
|
|
10
|
-
|
|
11
|
-
Strict proxies (including Kiro) return HTTP 400 `REQUEST_BODY_INVALID` on unknown keys:
|
|
12
|
-
1. Use only tools that exist in this session. Spawn subagents with **Task** (or **Agent** if that is the only one), passing only `subagent_type`, `description`, `prompt`, and `run_in_background: false` only if the schema has it. Never invent other keys.
|
|
13
|
-
2. `subagent_type: devil-advocate` / `judge`; `general-purpose` only if rejected. No Task/Agent tool: review in this session as `CONTEXT_ISOLATION_ONLY`.
|
|
14
|
-
3. Bash or Write says "cannot determine the safety" or 400: stop that tool, do not retry, use Read/Grep/Glob, and tell the user to leave auto permission mode or add a permissions.allow rule, then start a new session.
|
|
15
|
-
4. Models: `/models` when it exists; never type a model name.
|
|
16
|
-
|
|
17
|
-
## Grok CLI
|
|
18
|
-
|
|
19
|
-
1. `spawn_subagent` present and `GROK_SUBAGENTS` not `0`: review is **INVOCATION_AVAILABLE**; **PROVEN** only after a child returns its own `subagent_id`. Otherwise use `CONTEXT_ISOLATION_ONLY`, disclosed; never call it a subagent review.
|
|
20
|
-
2. Siblings only (depth limit 1): `capability_mode: "execute"`, `background: false`, `isolation: none`, no `resume_from`. Forbidden `subagent_type` for DA/Judge: `caveman:cavecrew-reviewer`, `caveman:cavecrew-builder`, `caveman:cavecrew-investigator`, `explore`, `plan`. Unregistered: `general-purpose`, agent spec prepended, `description` prefixed `[devil-advocate]`/`[judge]`.
|
|
21
|
-
3. Models: `grok models` (drop grok-imagine-* and video); never type a model name. Headless `grok -p` is `FRESH_PROCESS_AGENT` only once it prints a model response.
|
|
22
|
-
4. Alias: `NATIVE_SUBAGENT` → `TRUE_INDEPENDENT_AGENT`.
|
|
23
|
-
|
|
24
|
-
## Antigravity (IDE, 2.0, `agy` CLI)
|
|
25
|
-
|
|
26
|
-
1. If `invoke_subagent` (or Task) exists, spawn `devil-advocate` then `judge` (custom agents with `subagent: true`) as siblings, wait for each, never in the background; `general-purpose` only if the named type is rejected. Do not use `browser_subagent` (or the `browser` subagent).
|
|
27
|
-
2. No subagent tool: run the same budgets in this session as `CONTEXT_ISOLATION_ONLY`; do not claim independent agent execution.
|
|
28
|
-
3. Models: the host catalog (`/models` when it exists); never type a model name.
|
|
29
|
-
|
|
30
|
-
## Gemini CLI
|
|
31
|
-
|
|
32
|
-
1. Subagents `devil-advocate` and `judge` live in `~/.gemini/agents/` after `sync-hosts`; delegate to them by name when the session exposes them, one at a time, and wait.
|
|
33
|
-
2. Otherwise `CONTEXT_ISOLATION_ONLY`. Models: `/model`; never type a model name.
|
|
34
|
-
|
|
35
|
-
## Codex CLI
|
|
36
|
-
|
|
37
|
-
1. Custom agents `devil-advocate` and `judge` live in `~/.codex/agents/*.toml` after `sync-hosts`; spawn them as sibling agents when the session has a spawn tool, and wait for each result.
|
|
38
|
-
2. Otherwise `CONTEXT_ISOLATION_ONLY`. Models: the host catalog; never type a model name.
|
|
39
|
-
|
|
40
|
-
## Cursor, GitHub Copilot, OpenCode, Factory Droid, Augment, Qwen Code, Kiro, Junie
|
|
41
|
-
|
|
42
|
-
1. `sync-hosts` installs `devil-advocate` and `judge` in the host's own agent format. Delegate with the host's subagent tool by that name (Cursor subagents, Copilot custom agents, OpenCode `@devil-advocate`, Droid Task `subagent_type`, Auggie subagents, Qwen `/agents`, Kiro custom agents, Junie subagents), one at a time, and wait.
|
|
43
|
-
2. No subagent tool, or the agent is missing: `CONTEXT_ISOLATION_ONLY`.
|
|
44
|
-
|
|
45
|
-
## Other hosts (Windsurf/Devin, Amp, Zed, Goose, Cline, Roo, unknown)
|
|
46
|
-
|
|
47
|
-
1. Use a native subagent only if it can run the DA or Judge prompt with a fresh context and return its own result; read-only research subagents qualify only for DA.
|
|
48
|
-
2. Otherwise run DA and Judge in this session as `CONTEXT_ISOLATION_ONLY`, disclosed, with the same budgets.
|
|
@@ -1,14 +0,0 @@
|
|
|
1
|
-
# Stages 2-4: Maker
|
|
2
|
-
|
|
3
|
-
- T1/T2: read `docs tdd-policy` before Maker. Use `npx ai-engineering-loop context query <term>` and `context related <file>` before opening broad source files.
|
|
4
|
-
- Branch on mode. REPORT_ONLY: never edit repository files; write `RUN_DIR/report.json` with summary and recommendations, then the report review below, run `gate report`, and stop. ASSISTED: the parent (or intern) is Maker; delivery later needs human approval. UNATTENDED: `sandbox create --run <runId>`, Maker works only in the returned worktreePath, never the parent checkout, then `sandbox capture --run <runId>`.
|
|
5
|
-
- Maker intern: read `maker_intern` from workflow.md (missing or `none` = parent is Maker). Confirm it through the host model catalog; otherwise the parent is Maker and you report INVOCATION_UNAVAILABLE. The intern cannot skip later gates or spawn DA/Judge.
|
|
6
|
-
- Guardrails: Claude Code enforces them after `hooks install`. Elsewhere, before an out-of-scope edit or a destructive command (`rm -rf`, `DROP TABLE`, `git push --force`, `git reset --hard`, `git clean -fd`) run `guard check --tool edit --path <file>` or `--tool bash --command "<cmd>"`: `warn` = ask the human, `block` = do not run it.
|
|
7
|
-
- Bugs: red repro first. Features: one red test per AC row, then green.
|
|
8
|
-
- After package and manifest edits are stable, run `npx ai-engineering-loop refresh` once (drift during red-green is expected; do not refresh per test cycle).
|
|
9
|
-
- ASSISTED: `npx ai-engineering-loop gate maker --from-git` writes the exact working-tree diff (tracked and new files, excluding `.ai-engineering-loop/`) to `RUN_DIR/diff.patch` and gates it; or write that file yourself and run `gate maker`. UNATTENDED: `sandbox capture` writes it, then `gate maker`. The gate can raise the tier from the diff.
|
|
10
|
-
|
|
11
|
-
## REPORT_ONLY report review (recipe `audit`)
|
|
12
|
-
|
|
13
|
-
- Host has a subagent tool (`loop-hosts`): spawn ONE fresh `devil-advocate` sibling with report.json and the evidence paths it cites; it challenges unsupported or wrong findings with the usual DA budget. No Judge, no iteration loop: fold accepted findings once, drop rejected ones with evidence. Record `"review": {"executionMode": "TRUE_INDEPENDENT_AGENT", "nativeSubagent": "AVAILABLE", "reviewer": "devil-advocate", "childId": "<its own id>"}`.
|
|
14
|
-
- No subagent tool, or the spawn failed: do the same challenge in this session and record `"executionMode": "CONTEXT_ISOLATION_ONLY"` with `"reason"` (required by `gate report` when `nativeSubagent` is `AVAILABLE`). The header shows `Execution Mode: CONTEXT_ISOLATION_ONLY (reason: <why>)`.
|
|
@@ -1,20 +0,0 @@
|
|
|
1
|
-
# Stages 6-7: Devil's Advocate and Judge
|
|
2
|
-
|
|
3
|
-
REPORT_ONLY runs skip these stages; their single report review is in `loop-maker`.
|
|
4
|
-
|
|
5
|
-
## Devil's Advocate (T1, T2)
|
|
6
|
-
|
|
7
|
-
- `npx ai-engineering-loop review-pack --run <runId> --json` returns the DA pack path, fast-path, escalation floor, and tier. Keep the lean path when eligible; add `context devil-advocate <files...>` only for files whose hunks are insufficient. The DA reads that pack or `RUN_DIR/diff.patch` (do not also write `tasks/current.diff`).
|
|
8
|
-
- Use the runtime policy `reviewProfile` (default `lean`); upgrade to `standard` or `thorough` only when the human asks or the budget gate requires it.
|
|
9
|
-
- Spawn a new DA as a sibling (Host rules) with the pack path, the changed paths as a short list, and claimed-vs-reality.md. Do not paste Maker rationale. DA prompt includes "at most 8 tool calls; read the diff file; skip css and generated files".
|
|
10
|
-
- Iteration 2+: give unresolved findings and new hunks, not the whole diff again.
|
|
11
|
-
- Wait, `budget record` its usage (or `--unavailable`), normalize its ledger into `RUN_DIR/findings.json` with runId and diffHash, then `npx ai-engineering-loop gate review --json`. Report Spec and Standards separately.
|
|
12
|
-
|
|
13
|
-
## Judge
|
|
14
|
-
|
|
15
|
-
- T0, or T1 when `gate review --json` reports `judgeRequired: false`: run `gate judge`; the CLI writes the deterministic verdict.
|
|
16
|
-
- Otherwise run `npx ai-engineering-loop escalation --json` and resolve the required tier through the host model catalog; if unavailable, escalate to the user. T2 needs STRONG_MODEL.
|
|
17
|
-
- Judge context: only run-summary.md, verification-summary.json (or verification.json), open-findings.json/findings.json, and the Goal hash; it reads the full diff only if those contradict each other. Judge prompt includes "at most 4 tool calls; ledger and contract only; skip css; do not re-review the whole diff".
|
|
18
|
-
- Spawn a fresh sibling Judge, wait, `budget record`, write `RUN_DIR/verdict.json` with `modelTier`, then `gate judge`. A gate failure overrides optimistic prose.
|
|
19
|
-
- Acting on findings (ITERATE or human MR comments): verify each one before changing code; fix valid ones test-first, decline invalid ones with evidence (skill `ael-receiving-code-review` if installed).
|
|
20
|
-
- ITERATE while iteration < 3: fix in the parent, re-verify, spawn a **new** DA (never resume the previous child). At the iteration ceiling (3) ESCALATE to the human instead.
|
|
@@ -1,9 +0,0 @@
|
|
|
1
|
-
# T2 risky tier
|
|
2
|
-
|
|
3
|
-
Applies to HIGH_RISK_PATH changes (auth, payments, migrations, secrets, infra), DOT business logic, more than 10 files, or a manual `--tier T2`.
|
|
4
|
-
|
|
5
|
-
- Grill before the Goal (`docs grill-policy`): design tree, recommended answers, no look-up questions.
|
|
6
|
-
- Business-logic changes need a blast radius: lifecycle sketch of what reads and writes the changed state; on `adapter_type: dot` load `task-impact-inquiry`. Skip it for docs, config, or UI-copy changes.
|
|
7
|
-
- Full DA (not the T1 lean shortcut) and Judge on STRONG_MODEL resolved through the host model catalog; if unavailable, escalate to the user. Never run the deterministic Judge for T2.
|
|
8
|
-
- UNATTENDED: sandbox worktree only, and `budget pause` is the kill switch (`docs runtime-safety`).
|
|
9
|
-
- The tier never falls back once raised.
|