ai-engineering-loop 1.2.1 → 1.5.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/README.md CHANGED
@@ -1,12 +1,11 @@
1
- # AI Engineering Loop
2
-
3
1
  <div align="center">
2
+ <h1>AI Engineering Loop</h1>
4
3
 
5
4
  [![NPM Version](https://img.shields.io/npm/v/ai-engineering-loop.svg?color=cb3837)](https://www.npmjs.com/package/ai-engineering-loop)
6
5
  [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
7
6
  [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](https://github.com/egagofur/ai-engineering-loop/pulls)
8
7
  [![AI Engineering](https://img.shields.io/badge/AI-Engineering%20Loop-orange.svg)](https://github.com/egagofur/ai-engineering-loop)
9
- [![Release](https://img.shields.io/badge/release-v1.2.1-purple.svg)](https://github.com/egagofur/ai-engineering-loop/releases)
8
+ [![Release](https://img.shields.io/badge/release-v1.5.0-purple.svg)](https://github.com/egagofur/ai-engineering-loop/releases)
10
9
 
11
10
  **A Reusable, Framework-Agnostic AI Engineering Operating System for Autonomous Coding Agents**
12
11
 
@@ -183,6 +182,7 @@ npx ai-engineering-loop refresh
183
182
  # Start or resume a stateful engineering run
184
183
  npx ai-engineering-loop run
185
184
  npx ai-engineering-loop run --mode report-only "audit this repository"
185
+ npx ai-engineering-loop run --recipe bugfix --mode assisted "repair retry race"
186
186
 
187
187
  # Inspect the run ledger
188
188
  npx ai-engineering-loop state --json
@@ -196,6 +196,8 @@ npx ai-engineering-loop budget resume
196
196
 
197
197
  # Record actual provider-reported usage after each model response
198
198
  npx ai-engineering-loop budget record --input 1200 --output 300 --model provider/model-id
199
+ npx ai-engineering-loop budget status --node root-cause --estimate 4000
200
+ npx ai-engineering-loop budget record --node root-cause --input 3000 --output 700 --model provider/model-id
199
201
 
200
202
  # Isolate unattended Maker, then capture only its diff
201
203
  npx ai-engineering-loop sandbox create
@@ -219,6 +221,25 @@ npx ai-engineering-loop context judge <files...>
219
221
  npx ai-engineering-loop doctor
220
222
  npx ai-engineering-loop eval
221
223
 
224
+ # Inspect declarative workflow recipes without executing nodes
225
+ npx ai-engineering-loop recipe list
226
+ npx ai-engineering-loop recipe validate default --mode assisted
227
+ npx ai-engineering-loop recipe explain default --mode assisted
228
+ npx ai-engineering-loop recipe graph default --mode assisted
229
+ npx ai-engineering-loop recipe simulate default --mode assisted
230
+ npx ai-engineering-loop recipe catalog --json
231
+ npx ai-engineering-loop recipe create api-bugfix --from bugfix
232
+ npx ai-engineering-loop recipe inspect api-bugfix --json
233
+ npx ai-engineering-loop recipe diff bugfix api-bugfix
234
+ npx ai-engineering-loop recipe install candidate.json
235
+ npx ai-engineering-loop recipe install candidate-v2.json --replace
236
+
237
+ # Operate a custom node in an immutable recipe-bound run
238
+ npx ai-engineering-loop node status
239
+ npx ai-engineering-loop node start root-cause
240
+ npx ai-engineering-loop node complete root-cause --artifact .ai-engineering-loop/runs/<run-id>/root-cause.json
241
+ npx ai-engineering-loop node approve delivery-approval --yes
242
+
222
243
  # Copy package skills/agents/commands into ~/.claude ~/.grok ~/.gemini ~/.agents
223
244
  npx ai-engineering-loop sync-hosts
224
245
 
@@ -233,6 +254,10 @@ npx ai-engineering-loop generate-workflow --write
233
254
 
234
255
  Every full run stores private local artifacts under `.ai-engineering-loop/runs/<run-id>/`. Usage, worktrees, locks, context packs, and logs are Git-ignored. Markdown remains the human contract; JSON sidecars follow the shipped `schemas/` and make stage claims deterministic. `ASSISTED` is the default and requires explicit human delivery approval. `UNATTENDED` is disabled until a human enables it. See [`core/runtime-safety.md`](core/runtime-safety.md), [`core/artifact-gates.md`](core/artifact-gates.md), [`SECURITY.md`](SECURITY.md), and [`SUPPORT.md`](SUPPORT.md).
235
256
 
257
+ Declarative recipes let an AI or future visual editor author a workflow graph without weakening the safety gates. Built-in presets and project recipes can be validated, explained, graphed, and simulated deterministically. `run --recipe` opts into an immutable, resumable DAG scheduler; legacy runs remain unchanged. See [`core/workflow-recipes.md`](core/workflow-recipes.md) and [`core/controlled-workflow-runtime.md`](core/controlled-workflow-runtime.md).
258
+
259
+ The deterministic recipe builder scaffolds from safe presets, validates candidates before atomic installation, preserves replaced versions locally, and exposes catalog/inspect/diff JSON for AI agents and a future UI. The host-neutral agent protocol is in [`agents/recipe-builder.md`](agents/recipe-builder.md).
260
+
236
261
  Shipped adapters (Stage 8 only, after Judge PASS): `standard`, `github`, `gitlab`, `dot`. Catalog: `adapters/README.md`. Each team generates its own; do not copy a neighbour's pipeline.
237
262
 
238
263
  `sync-hosts` updates only hosts that already exist on the machine. DOT skills (`dot-dev-skill-router`, `dot-dev-workflow`) are updated only if they are already installed. `task-impact-inquiry`, `generate-adapter`, and `generate-workflow` are upserted onto Claude, Grok, and Gemini. After a copy, start a new session so the host reloads skill text. `/ai-engineering-loop` Stage 0 and `run` call `sync-hosts` so a published package bump reaches global host files without a manual copy.
@@ -321,7 +346,13 @@ ai-engineering-loop/
321
346
  │ └── ai-engineering-loop.js # npx executable CLI (init, status, refresh, run, sync-hosts)
322
347
  │
323
348
  ├── lib/ # Core orchestration & decision engine
324
- │ └── orchestration.js # 3-stage capability registry, barrier builder, Judge engine
349
+ │ ├── orchestration.js # 3-stage capability registry, barrier builder, Judge engine
350
+ │ ├── recipe.js # Declarative graph validator and deterministic compiler
351
+ │ └── workflow-runtime.js # Resumable scheduler and hash-chained event ledger
352
+ │
353
+ ├── recipes/ # Built-in workflow presets; target repos may add their own
354
+ │ ├── default.json # Current production loop represented as a graph
355
+ │ └── audit.json # Read-only report workflow
325
356
  │
326
357
  ├── tests/ # Deterministic test suites
327
358
  │ ├── capability-selection.test.js # Unit tests for capability lifecycle & truthful selection
@@ -360,6 +391,8 @@ ai-engineering-loop/
360
391
  │ ├── escalation-policy.md # Deterministic human escalation triggers
361
392
  │ ├── judge-policy.md # Evaluation rules, triage audit, & verdicts
362
393
  │ ├── configuration-precedence.md # 5-layer precedence & conflict resolution
394
+ │ ├── controlled-workflow-runtime.md # Immutable plan, scheduler, events, and recovery
395
+ │ ├── workflow-recipes.md # Recipe safety backbone and AI authoring protocol
363
396
  │ └── repo-config-schema.md # Schema for target repo .ai-engineering-loop/
364
397
  │
365
398
  ├── profiles/ # Project archetype profiles
@@ -0,0 +1,28 @@
1
+ # Recipe Builder Agent
2
+
3
+ You author workflow proposals; you do not bypass the recipe compiler or execute a proposed workflow.
4
+
5
+ ## Interview
6
+
7
+ Ask only unanswered questions:
8
+
9
+ 1. What outcome should the workflow produce?
10
+ 2. Which modes are allowed: `REPORT_ONLY`, `ASSISTED`, or `UNATTENDED`?
11
+ 3. May it mutate the repository?
12
+ 4. What analysis is required before Maker?
13
+ 5. Where is explicit human approval required?
14
+ 6. What are the maximum files and tokens for each agent node?
15
+ 7. Is delivery risk low, medium, or high?
16
+
17
+ ## Authoring protocol
18
+
19
+ 1. Run `ai-engineering-loop recipe catalog --json`.
20
+ 2. Select the closest built-in preset.
21
+ 3. Run `recipe create <id> --from <preset>`; never start from an unconstrained blank graph.
22
+ 4. Make the smallest meaningful edits to the project recipe.
23
+ 5. Run `recipe validate`, `recipe inspect`, `recipe diff <preset> <id>`, `recipe explain`, `recipe graph`, and `recipe simulate`.
24
+ 6. Present validation, diff, graph hash, model calls, token ceiling, mutations, side effects, and approvals.
25
+ 7. Ask for explicit human approval.
26
+ 8. For a separately prepared candidate, use `recipe install <path>` only after approval. Existing recipes require `--replace` and a higher version.
27
+
28
+ Never add executable code, shell text, remote schema URLs, conditional mandatory safety gates, or mutation to `REPORT_ONLY`. Never claim validation or simulation executed a workflow.
@@ -38,7 +38,8 @@ const {
38
38
  TERMINAL_STATES,
39
39
  createOrResumeRun,
40
40
  getCurrentRun,
41
- loadRun
41
+ loadRun,
42
+ newRunId
42
43
  } = require('../lib/run-state.js');
43
44
  const {
44
45
  DEFAULT_POLICY,
@@ -82,8 +83,34 @@ const {
82
83
  createSandbox,
83
84
  sandboxStatus
84
85
  } = require('../lib/sandbox.js');
85
-
86
- const VERSION = '1.2.1';
86
+ const {
87
+ compileRecipe,
88
+ explainPlan,
89
+ listRecipes,
90
+ loadRecipe,
91
+ mermaidPlan,
92
+ simulatePlan,
93
+ validateRecipe
94
+ } = require('../lib/recipe.js');
95
+ const {
96
+ applyWorkflowGate,
97
+ approveWorkflowNode,
98
+ completeWorkflowNode,
99
+ createWorkflowBundle,
100
+ failWorkflowNode,
101
+ retryWorkflowNode,
102
+ startWorkflowNode,
103
+ workflowStatus
104
+ } = require('../lib/workflow-runtime.js');
105
+ const {
106
+ cloneRecipe,
107
+ diffRecipes,
108
+ inspectRecipe,
109
+ installRecipe,
110
+ recipeCatalog
111
+ } = require('../lib/recipe-builder.js');
112
+
113
+ const VERSION = '1.5.0';
87
114
  const CWD = process.cwd();
88
115
  const CONTEXT_DIR = path.join(CWD, '.ai-engineering-loop');
89
116
 
@@ -337,7 +364,7 @@ function generateContextFiles(rootDir, discovery, trigger = 'init', impact = 'IN
337
364
 
338
365
  // 0. metadata.json (Baseline)
339
366
  const metadataJson = {
340
- contextVersion: '1.2.1',
367
+ contextVersion: '1.5.0',
341
368
  generatedAt: new Date().toISOString(),
342
369
  repositoryRevision: currentRevision,
343
370
  projectProfile: discovery.profile,
@@ -787,6 +814,7 @@ function handleRun() {
787
814
  const runArgs = process.argv.slice(3);
788
815
  const forceNew = runArgs.includes('--new');
789
816
  const modeArg = argValue('--mode');
817
+ const recipeArg = argValue('--recipe');
790
818
  const taskParts = [];
791
819
  for (let index = 0; index < runArgs.length; index++) {
792
820
  if (runArgs[index] === '--new') continue;
@@ -794,6 +822,10 @@ function handleRun() {
794
822
  index += 1;
795
823
  continue;
796
824
  }
825
+ if (runArgs[index] === '--recipe') {
826
+ index += 1;
827
+ continue;
828
+ }
797
829
  taskParts.push(runArgs[index]);
798
830
  }
799
831
  const task = taskParts.join(' ').trim();
@@ -802,9 +834,42 @@ function handleRun() {
802
834
  const current = getCurrentRun(CWD);
803
835
  const policy = loadPolicy(CWD);
804
836
  const startsNewRun = forceNew || !current || TERMINAL_STATES.has(current.state);
805
- const mode = modeArg ? normalizeMode(modeArg) : (startsNewRun ? policy.defaultMode : null);
837
+ let mode = modeArg ? normalizeMode(modeArg) : (startsNewRun ? policy.defaultMode : null);
838
+ let workflow = null;
839
+ let requestedRunId = null;
840
+ if (recipeArg) {
841
+ const { recipe } = loadRecipe(CWD, recipeArg);
842
+ if (!mode && current) mode = current.mode;
843
+ if (startsNewRun && !modeArg && !recipe.compatibleModes.includes(mode)) {
844
+ if (recipe.compatibleModes.length !== 1) {
845
+ throw new Error(`Recipe ${recipe.id} requires an explicit compatible --mode.`);
846
+ }
847
+ mode = recipe.compatibleModes[0];
848
+ }
849
+ const plan = compileRecipe(recipe, { mode });
850
+ if (startsNewRun) {
851
+ requestedRunId = newRunId();
852
+ workflow = createWorkflowBundle(plan, requestedRunId, {
853
+ run: {
854
+ runId: requestedRunId,
855
+ mode,
856
+ state: 'STARTED',
857
+ iteration: 1,
858
+ task
859
+ }
860
+ });
861
+ } else {
862
+ workflow = { plan };
863
+ }
864
+ }
806
865
  if (mode) assertModeAllowed(CWD, mode);
807
- runResult = createOrResumeRun(CWD, { task, forceNew, mode });
866
+ runResult = createOrResumeRun(CWD, {
867
+ task,
868
+ forceNew,
869
+ mode,
870
+ workflow,
871
+ ...(requestedRunId ? { runId: requestedRunId } : {})
872
+ });
808
873
  assertBudgetAvailable(CWD, { runId: runResult.run.runId });
809
874
  } catch (err) {
810
875
  log.error(err.message);
@@ -813,6 +878,14 @@ function handleRun() {
813
878
  console.log(`- Run: ${runResult.run.runId} (${runResult.resumed ? 'resumed' : 'created'})`);
814
879
  console.log(`- State: ${runResult.run.state}, iteration ${runResult.run.iteration}`);
815
880
  console.log(`- Mode: ${runResult.run.mode || RUN_MODES.ASSISTED}`);
881
+ if (runResult.run.workflow) {
882
+ const runtime = workflowStatus(CWD, { runId: runResult.run.runId });
883
+ const ready = runtime.plan.nodes
884
+ .filter((node) => runtime.state.nodes[node.id].status === 'READY')
885
+ .map((node) => node.id);
886
+ console.log(`- Recipe: ${runResult.run.workflow.recipeId} (${runResult.run.workflow.graphHash})`);
887
+ console.log(`- Ready nodes: ${ready.join(', ') || 'none'}`);
888
+ }
816
889
 
817
890
  const grok = detectGrokHost();
818
891
 
@@ -964,13 +1037,21 @@ function handleBudget() {
964
1037
  const action = process.argv[3] || 'status';
965
1038
  const json = process.argv.includes('--json');
966
1039
  const runId = argValue('--run');
1040
+ const nodeId = argValue('--node');
967
1041
  try {
968
1042
  let result;
969
1043
  if (action === 'status') {
970
- result = budgetStatus(CWD, { runId });
1044
+ result = budgetStatus(CWD, {
1045
+ runId,
1046
+ nodeId,
1047
+ estimatedTokens: argValue('--estimate') == null
1048
+ ? 0
1049
+ : parseNonNegativeIntegerArg('--estimate', argValue('--estimate'))
1050
+ });
971
1051
  } else if (action === 'record') {
972
1052
  result = recordTokenUsage(CWD, {
973
1053
  runId,
1054
+ nodeId,
974
1055
  inputTokens: parseNonNegativeIntegerArg('--input', argValue('--input')),
975
1056
  outputTokens: parseNonNegativeIntegerArg('--output', argValue('--output')),
976
1057
  model: argValue('--model')
@@ -1020,7 +1101,11 @@ function handleGate() {
1020
1101
  const runId = argValue('--run');
1021
1102
  const json = process.argv.includes('--json');
1022
1103
  try {
1023
- const run = applyGate(CWD, gate, { runId });
1104
+ const target = runId ? loadRun(CWD, runId) : getCurrentRun(CWD);
1105
+ if (!target) throw new Error('No current run. Start one with `ai-engineering-loop run`.');
1106
+ const run = target.workflow
1107
+ ? applyWorkflowGate(CWD, gate, { runId: target.runId }).run
1108
+ : applyGate(CWD, gate, { runId: target.runId });
1024
1109
  if (json) {
1025
1110
  console.log(JSON.stringify({
1026
1111
  ok: true,
@@ -1050,6 +1135,78 @@ function handleGate() {
1050
1135
  }
1051
1136
  }
1052
1137
 
1138
+ function handleNode() {
1139
+ const action = process.argv[3] || 'status';
1140
+ const nodeId = process.argv[4];
1141
+ const runId = argValue('--run');
1142
+ const json = process.argv.includes('--json');
1143
+ try {
1144
+ if (action === 'status') {
1145
+ const workflow = workflowStatus(CWD, { runId });
1146
+ const result = {
1147
+ ok: true,
1148
+ runId: workflow.run.runId,
1149
+ recipe: workflow.plan.recipe,
1150
+ graphHash: workflow.plan.graphHash,
1151
+ nodes: workflow.plan.nodes.map((node) => ({
1152
+ id: node.id,
1153
+ type: node.type,
1154
+ order: node.order,
1155
+ ...workflow.state.nodes[node.id]
1156
+ }))
1157
+ };
1158
+ if (json) console.log(JSON.stringify(result));
1159
+ else {
1160
+ console.log(`Workflow: ${workflow.plan.recipe.id} (${workflow.plan.graphHash})`);
1161
+ for (const node of result.nodes) {
1162
+ console.log(`${String(node.order).padStart(2)} ${node.id}: ${node.status}`);
1163
+ }
1164
+ }
1165
+ return;
1166
+ }
1167
+ if (!nodeId || nodeId.startsWith('-')) throw new Error(`node ${action} requires a node id`);
1168
+ let workflow;
1169
+ if (action === 'start') {
1170
+ workflow = startWorkflowNode(CWD, nodeId, { runId });
1171
+ } else if (action === 'complete') {
1172
+ workflow = completeWorkflowNode(CWD, nodeId, { runId, artifact: argValue('--artifact') });
1173
+ } else if (action === 'fail') {
1174
+ workflow = failWorkflowNode(CWD, nodeId, {
1175
+ runId,
1176
+ reason: argValue('--reason') || 'node execution failed'
1177
+ });
1178
+ } else if (action === 'retry') {
1179
+ workflow = retryWorkflowNode(CWD, nodeId, { runId });
1180
+ } else if (action === 'approve') {
1181
+ if (!process.argv.includes('--yes')) {
1182
+ throw new Error('Approval requires explicit --yes confirmation');
1183
+ }
1184
+ workflow = approveWorkflowNode(CWD, nodeId, {
1185
+ runId,
1186
+ approvedBy: argValue('--by') || 'human'
1187
+ });
1188
+ } else {
1189
+ throw new Error(`Unknown node action: ${action}`);
1190
+ }
1191
+ const node = workflow.state.nodes[nodeId];
1192
+ if (json) console.log(JSON.stringify({ ok: true, nodeId, ...node }));
1193
+ else log.success(`✓ Node ${nodeId}: ${node.status}`);
1194
+ } catch (err) {
1195
+ if (json) {
1196
+ console.log(JSON.stringify({
1197
+ ok: false,
1198
+ code: err.code || 'NODE_FAILED',
1199
+ error: err.message,
1200
+ details: err.details || []
1201
+ }));
1202
+ } else {
1203
+ log.error(err.message);
1204
+ for (const detail of err.details || []) console.error(`- ${detail}`);
1205
+ }
1206
+ process.exit(1);
1207
+ }
1208
+ }
1209
+
1053
1210
  function commandFiles(startIndex, optionsWithValues = []) {
1054
1211
  const files = [];
1055
1212
  for (let index = startIndex; index < process.argv.length; index++) {
@@ -1180,6 +1337,119 @@ function handleDoctor() {
1180
1337
  if (!result.ok) process.exit(1);
1181
1338
  }
1182
1339
 
1340
+ function handleRecipe() {
1341
+ const action = process.argv[3] || 'list';
1342
+ const id = process.argv[4];
1343
+ const mode = argValue('--mode');
1344
+ const json = process.argv.includes('--json');
1345
+ try {
1346
+ if (action === 'catalog') {
1347
+ const result = { ok: true, nodeTypes: recipeCatalog() };
1348
+ console.log(JSON.stringify(result, null, json ? 0 : 2));
1349
+ return;
1350
+ }
1351
+ if (action === 'clone' || action === 'create') {
1352
+ const sourceId = action === 'clone' ? id : (argValue('--from') || 'default');
1353
+ const targetId = action === 'clone' ? process.argv[5] : id;
1354
+ if (!sourceId || !targetId || targetId.startsWith('-')) {
1355
+ throw new Error(`recipe ${action} requires ${action === 'clone' ? '<source> <target>' : '<id> [--from <preset>]'}`);
1356
+ }
1357
+ const result = cloneRecipe(CWD, sourceId, targetId, { description: argValue('--description') });
1358
+ const relativePath = path.relative(CWD, result.path).split(path.sep).join('/');
1359
+ console.log(json ? JSON.stringify({ ok: true, ...result, path: relativePath }) :
1360
+ `Created ${targetId} from ${sourceId} at ${relativePath}\nSource hash: ${result.sourceHash}`);
1361
+ return;
1362
+ }
1363
+ if (action === 'install') {
1364
+ if (!id || id.startsWith('-')) throw new Error('recipe install requires a candidate path');
1365
+ const result = installRecipe(CWD, id, { replace: process.argv.includes('--replace') });
1366
+ const relativePath = path.relative(CWD, result.path).split(path.sep).join('/');
1367
+ console.log(json ? JSON.stringify({ ok: true, ...result, path: relativePath }) :
1368
+ `Installed ${result.recipe.id} v${result.recipe.version}\nSource hash: ${result.sourceHash}`);
1369
+ return;
1370
+ }
1371
+ if (action === 'diff') {
1372
+ const rightId = process.argv[5];
1373
+ if (!id || !rightId) throw new Error('recipe diff requires <left> <right>');
1374
+ const result = diffRecipes(CWD, id, rightId);
1375
+ console.log(JSON.stringify({ ok: true, ...result }, null, json ? 0 : 2));
1376
+ return;
1377
+ }
1378
+ if (action === 'inspect') {
1379
+ if (!id || id.startsWith('-')) throw new Error('recipe inspect requires an id');
1380
+ console.log(JSON.stringify({ ok: true, ...inspectRecipe(CWD, id) }, null, json ? 0 : 2));
1381
+ return;
1382
+ }
1383
+ if (action === 'list') {
1384
+ const recipes = listRecipes(CWD).map((entry) => {
1385
+ const { recipe } = loadRecipe(CWD, entry.id);
1386
+ return {
1387
+ ...entry,
1388
+ description: recipe.description,
1389
+ compatibleModes: recipe.compatibleModes
1390
+ };
1391
+ });
1392
+ if (json) console.log(JSON.stringify({ ok: true, recipes }));
1393
+ else {
1394
+ console.log('Workflow recipes:');
1395
+ for (const recipe of recipes) {
1396
+ console.log(`- ${recipe.id} [${recipe.source}] ${recipe.compatibleModes.join(', ')}`);
1397
+ console.log(` ${recipe.description}`);
1398
+ }
1399
+ }
1400
+ return;
1401
+ }
1402
+
1403
+ if (!['show', 'validate', 'explain', 'graph', 'simulate'].includes(action)) {
1404
+ throw Object.assign(new Error(`Unknown recipe action: ${action}`), { code: 'UNKNOWN_RECIPE_ACTION' });
1405
+ }
1406
+ if (!id || id.startsWith('-')) {
1407
+ throw Object.assign(new Error(`recipe ${action} requires an id`), { code: 'RECIPE_ID_REQUIRED' });
1408
+ }
1409
+ const loaded = loadRecipe(CWD, id);
1410
+ if (action === 'show') {
1411
+ console.log(JSON.stringify(loaded.recipe, null, json ? 0 : 2));
1412
+ return;
1413
+ }
1414
+ if (action === 'validate') {
1415
+ const validation = validateRecipe(loaded.recipe, mode ? { mode } : {});
1416
+ const result = { ok: validation.valid, id, source: loaded.source, ...validation };
1417
+ if (json) console.log(JSON.stringify(result));
1418
+ else {
1419
+ console.log(`Recipe ${id}: ${validation.valid ? 'VALID' : 'INVALID'}`);
1420
+ for (const warning of validation.warnings) console.log(`! ${warning}`);
1421
+ for (const error of validation.errors) console.log(`✗ ${error}`);
1422
+ }
1423
+ if (!validation.valid) process.exit(1);
1424
+ return;
1425
+ }
1426
+
1427
+ const plan = compileRecipe(loaded.recipe, mode ? { mode } : {});
1428
+ if (action === 'explain') {
1429
+ console.log(json ? JSON.stringify({ ok: true, source: loaded.source, plan }) : explainPlan(plan));
1430
+ } else if (action === 'graph') {
1431
+ const mermaid = mermaidPlan(plan);
1432
+ console.log(json ? JSON.stringify({ ok: true, graphHash: plan.graphHash, mermaid }) : mermaid);
1433
+ } else {
1434
+ const simulation = simulatePlan(plan);
1435
+ console.log(JSON.stringify({ ok: true, ...simulation }, null, json ? 0 : 2));
1436
+ }
1437
+ } catch (err) {
1438
+ if (json) {
1439
+ console.log(JSON.stringify({
1440
+ ok: false,
1441
+ code: err.code || 'RECIPE_FAILED',
1442
+ error: err.message,
1443
+ details: err.details || []
1444
+ }));
1445
+ } else {
1446
+ log.error(err.message);
1447
+ for (const detail of err.details || []) console.error(`- ${detail}`);
1448
+ }
1449
+ process.exit(1);
1450
+ }
1451
+ }
1452
+
1183
1453
  // Help Menu
1184
1454
  function printHelp() {
1185
1455
  console.log(`
@@ -1196,6 +1466,7 @@ Commands:
1196
1466
  run [task] Start or resume a stateful engineering run, sync hosts, and instruct the agent
1197
1467
  --new start a new run even when another run is active
1198
1468
  --mode report-only|assisted|unattended
1469
+ --recipe <id> bind an immutable compiled workflow plan
1199
1470
  state Inspect the current run ledger
1200
1471
  --run <id> target a non-current run
1201
1472
  --json print the complete machine-readable ledger
@@ -1203,14 +1474,21 @@ Commands:
1203
1474
  goal | report | maker | verification | review | judge | delivery
1204
1475
  --run <id> target a non-current run
1205
1476
  --json print machine-readable gate output
1477
+ node Operate custom nodes in a recipe-bound run
1478
+ status [--run <id>] [--json]
1479
+ start <id> [--run <id>] [--json]
1480
+ complete <id> [--artifact <repository-relative-path>] [--json]
1481
+ fail <id> [--reason <text>] [--json]
1482
+ retry <id> [--json]
1483
+ approve <id> --yes [--by <name>] [--json]
1206
1484
  policy Inspect or update fail-closed runtime controls
1207
1485
  show [--json]
1208
1486
  set [--default-mode <mode>] [--allow-unattended true|false]
1209
1487
  [--require-sandbox true|false]
1210
1488
  [--per-run-token-limit <n>] [--daily-token-limit <n>]
1211
1489
  budget Enforce actual provider-reported token usage and emergency pause
1212
- status [--run <id>] [--json]
1213
- record --input <n> --output <n> --model <id> [--run <id>]
1490
+ status [--run <id>] [--node <id>] [--estimate <n>] [--json]
1491
+ record --input <n> --output <n> --model <id> [--run <id>] [--node <id>]
1214
1492
  pause | resume
1215
1493
  sandbox Isolate Maker changes in a locked disposable Git worktree
1216
1494
  create | capture | abort | status [--run <id>] [--json]
@@ -1227,6 +1505,17 @@ Commands:
1227
1505
  --json print machine-readable reasons
1228
1506
  doctor Check runtime, schemas, host assets, package contents, and eval catalog
1229
1507
  --json print machine-readable diagnostics
1508
+ recipe Inspect and compile declarative workflow recipes (does not execute nodes)
1509
+ list [--json]
1510
+ catalog [--json]
1511
+ create <id> [--from <preset>] [--description <text>] [--json]
1512
+ clone <source> <target> [--description <text>] [--json]
1513
+ install <path> [--replace] [--json]
1514
+ inspect <id> [--json]
1515
+ diff <left> <right> [--json]
1516
+ show <id> [--json]
1517
+ validate <id> [--mode <mode>] [--json]
1518
+ explain | graph | simulate <id> [--mode <mode>] [--json]
1230
1519
  sync-hosts Copy package skills/agents/commands into ~/.claude ~/.grok ~/.gemini ~/.agents
1231
1520
  (only hosts that already exist; DOT skills only if already installed)
1232
1521
  --dry-run print the plan without writing
@@ -1267,6 +1556,9 @@ switch (command) {
1267
1556
  case 'gate':
1268
1557
  handleGate();
1269
1558
  break;
1559
+ case 'node':
1560
+ handleNode();
1561
+ break;
1270
1562
  case 'policy':
1271
1563
  handlePolicy();
1272
1564
  break;
@@ -1288,6 +1580,9 @@ switch (command) {
1288
1580
  case 'doctor':
1289
1581
  handleDoctor();
1290
1582
  break;
1583
+ case 'recipe':
1584
+ handleRecipe();
1585
+ break;
1291
1586
  case 'sync-hosts':
1292
1587
  handleSyncHosts();
1293
1588
  break;
@@ -0,0 +1,77 @@
1
+ # Controlled Workflow Runtime
2
+
3
+ The controlled runtime binds a validated recipe to one run without replacing the existing artifact gates. It is opt-in through `run --recipe`; runs started without that option retain the legacy behavior.
4
+
5
+ ## Immutable run binding
6
+
7
+ At run creation the CLI compiles the selected recipe and writes private runtime files under `.ai-engineering-loop/runs/<run-id>/`:
8
+
9
+ - `plan.json`: canonical compiled DAG with source and graph hashes
10
+ - `workflow-state.json`: reconstructable scheduler cache
11
+ - `events.jsonl`: append-only, hash-chained transition log
12
+
13
+ The run ledger stores the recipe ID, recipe version, source hash, and graph hash. Resume rejects a different graph. Every load recalculates the plan hash and verifies the full event chain. The state cache is reconstructed from events, so a stale or edited cache cannot grant a node permission to run.
14
+
15
+ ## Scheduler rules
16
+
17
+ Node states are:
18
+
19
+ `PENDING → READY → RUNNING → PASSED`
20
+
21
+ Additional outcomes are `FAILED`, `SKIPPED`, and `BLOCKED`.
22
+
23
+ - A node becomes `READY` only after every dependency is `PASSED` or conditionally `SKIPPED`.
24
+ - A failed dependency makes descendants `BLOCKED`.
25
+ - `retry` returns a failed or interrupted custom node to `READY` and recalculates descendants.
26
+ - Structured conditions read only allowlisted run metadata.
27
+ - Legacy gates execute atomically under the workflow lock and mark their corresponding node passed only after existing artifact validation succeeds.
28
+ - Judge `ITERATE` resets Maker and its descendants while preserving upstream analysis.
29
+ - Judge `ESCALATE` blocks unfinished nodes.
30
+
31
+ ## Commands
32
+
33
+ ```bash
34
+ # Create an immutable recipe-bound run
35
+ ai-engineering-loop run --recipe bugfix --mode assisted "repair retry race"
36
+
37
+ # Inspect scheduler state
38
+ ai-engineering-loop node status --json
39
+
40
+ # Custom agent lifecycle
41
+ ai-engineering-loop node start root-cause
42
+ ai-engineering-loop budget status --node root-cause --estimate 4000
43
+ ai-engineering-loop budget record --node root-cause \
44
+ --input 3000 --output 700 --model provider/model-id
45
+ ai-engineering-loop node complete root-cause \
46
+ --artifact .ai-engineering-loop/runs/<run-id>/root-cause.json
47
+
48
+ # Failure and crash recovery
49
+ ai-engineering-loop node fail root-cause --reason provider-timeout
50
+ ai-engineering-loop node retry root-cause
51
+
52
+ # Explicit human checkpoint
53
+ ai-engineering-loop node approve delivery-approval --yes --by account-id
54
+ ```
55
+
56
+ Existing gate commands remain authoritative for built-in stages:
57
+
58
+ ```bash
59
+ ai-engineering-loop gate goal
60
+ ai-engineering-loop gate maker
61
+ ai-engineering-loop gate verification
62
+ ai-engineering-loop gate review
63
+ ai-engineering-loop gate judge
64
+ ai-engineering-loop gate delivery
65
+ ```
66
+
67
+ ## Artifact and token boundaries
68
+
69
+ Agent completion requires a regular JSON file inside the repository, rejects symlink escape, binds `runId`, validates the declared repository-relative schema, and records the artifact hash. Artifact content is never copied into the event log.
70
+
71
+ Provider-reported usage can be attributed to a node. `budget status --node --estimate` must be called before a model request; it combines kill switch, daily, run, node-state, and node token limits. `budget record --node` records actual provider usage after the response.
72
+
73
+ ## Intentionally disabled
74
+
75
+ The runtime does not execute `command` nodes. Command nodes are conservatively classified as repository mutation, rejected in `REPORT_ONLY`, and fail with `COMMAND_EXECUTION_DISABLED`. Enabling them later requires a separate sandboxed executor with executable allowlists, environment filtering, bounded output, cancellation, and auditable process isolation.
76
+
77
+ The CLI also does not invoke a model itself. Host agents perform model work, record real token usage, and submit structured artifacts through the runtime boundary.