ai-engineering-loop 1.1.0 → 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.
Files changed (57) hide show
  1. package/.agents/workflows/ai-engineering-loop.md +5 -5
  2. package/.claude/skills/ai-engineering-loop/SKILL.md +7 -5
  3. package/.gemini/skills/ai-engineering-loop/SKILL.md +7 -5
  4. package/.grok/skills/ai-engineering-loop/SKILL.md +7 -5
  5. package/README.md +56 -6
  6. package/README.npm.md +9 -1
  7. package/SECURITY.md +8 -2
  8. package/agents/judge.md +5 -5
  9. package/agents/maker.md +6 -6
  10. package/agents/recipe-builder.md +28 -0
  11. package/bin/ai-engineering-loop.js +521 -16
  12. package/core/configuration-precedence.md +4 -4
  13. package/core/context-impact-assessment.md +1 -1
  14. package/core/controlled-workflow-runtime.md +77 -0
  15. package/core/definition-of-done.md +3 -3
  16. package/core/escalation-policy.md +2 -2
  17. package/core/goal-contract.md +2 -2
  18. package/core/iteration-policy.md +4 -4
  19. package/core/project-initialization.md +2 -2
  20. package/core/runtime-safety.md +75 -0
  21. package/core/verification-loop.md +1 -1
  22. package/core/workflow-recipes.md +140 -0
  23. package/lib/budget.js +258 -0
  24. package/lib/doctor.js +38 -2
  25. package/lib/gates.js +55 -1
  26. package/lib/node-registry.js +155 -0
  27. package/lib/package-audit.js +78 -0
  28. package/lib/recipe-builder.js +200 -0
  29. package/lib/recipe.js +495 -0
  30. package/lib/run-state.js +94 -8
  31. package/lib/runtime-files.js +54 -0
  32. package/lib/runtime-policy.js +118 -0
  33. package/lib/safe-context.js +3 -0
  34. package/lib/sandbox.js +305 -0
  35. package/lib/workflow-runtime.js +692 -0
  36. package/package.json +7 -3
  37. package/policies/finding-policy.md +2 -2
  38. package/policies/no-progress-policy.md +2 -2
  39. package/profiles/README.md +5 -5
  40. package/profiles/backend-api.md +1 -1
  41. package/profiles/library.md +1 -1
  42. package/profiles/mobile-app.md +1 -1
  43. package/profiles/monorepo.md +1 -1
  44. package/profiles/web-app.md +1 -1
  45. package/recipes/audit.json +32 -0
  46. package/recipes/bugfix.json +63 -0
  47. package/recipes/default.json +49 -0
  48. package/recipes/docs-light.json +63 -0
  49. package/recipes/high-risk.json +69 -0
  50. package/recipes/refactor.json +63 -0
  51. package/schemas/compiled-plan.schema.json +19 -0
  52. package/schemas/delivery.schema.json +2 -1
  53. package/schemas/node-definition.schema.json +33 -0
  54. package/schemas/recipe.schema.json +26 -0
  55. package/schemas/report.schema.json +17 -0
  56. package/schemas/workflow-event.schema.json +28 -0
  57. package/schemas/workflow-state.schema.json +29 -0
@@ -34,10 +34,20 @@ const {
34
34
  lessonsMarkdown
35
35
  } = require('../lib/generate-workflow.js');
36
36
  const {
37
+ RUN_MODES,
38
+ TERMINAL_STATES,
37
39
  createOrResumeRun,
38
40
  getCurrentRun,
39
- loadRun
41
+ loadRun,
42
+ newRunId
40
43
  } = require('../lib/run-state.js');
44
+ const {
45
+ DEFAULT_POLICY,
46
+ assertModeAllowed,
47
+ loadPolicy,
48
+ normalizeMode,
49
+ updatePolicy
50
+ } = require('../lib/runtime-policy.js');
41
51
  const {
42
52
  applyGate
43
53
  } = require('../lib/gates.js');
@@ -58,8 +68,49 @@ const {
58
68
  const {
59
69
  runDoctor
60
70
  } = require('../lib/doctor.js');
61
-
62
- const VERSION = '1.1.0';
71
+ const {
72
+ assertBudgetAvailable,
73
+ budgetStatus,
74
+ recordTokenUsage,
75
+ setKillSwitch
76
+ } = require('../lib/budget.js');
77
+ const {
78
+ PRIVATE_RUNTIME_GITIGNORE
79
+ } = require('../lib/runtime-files.js');
80
+ const {
81
+ abortSandbox,
82
+ captureSandbox,
83
+ createSandbox,
84
+ sandboxStatus
85
+ } = require('../lib/sandbox.js');
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';
63
114
  const CWD = process.cwd();
64
115
  const CONTEXT_DIR = path.join(CWD, '.ai-engineering-loop');
65
116
 
@@ -313,7 +364,7 @@ function generateContextFiles(rootDir, discovery, trigger = 'init', impact = 'IN
313
364
 
314
365
  // 0. metadata.json (Baseline)
315
366
  const metadataJson = {
316
- contextVersion: '1.1.0',
367
+ contextVersion: '1.5.0',
317
368
  generatedAt: new Date().toISOString(),
318
369
  repositoryRevision: currentRevision,
319
370
  projectProfile: discovery.profile,
@@ -453,9 +504,14 @@ What becomes easier, harder, or forbidden.
453
504
 
454
505
  writeContextFile(path.join(targetDir, 'workflow.md'), workflowMarkdown(), { overwrite: false });
455
506
  writeContextFile(path.join(targetDir, 'lessons.md'), lessonsMarkdown(), { overwrite: false });
507
+ writeContextFile(
508
+ path.join(targetDir, 'runtime-policy.json'),
509
+ `${JSON.stringify(DEFAULT_POLICY, null, 2)}\n`,
510
+ { overwrite: false }
511
+ );
456
512
  writeContextFile(
457
513
  path.join(targetDir, '.gitignore'),
458
- '# Runtime artifacts may contain source excerpts and verification logs.\nruns/\ntasks/current.diff\ntasks/*.log\n',
514
+ PRIVATE_RUNTIME_GITIGNORE,
459
515
  { overwrite: false }
460
516
  );
461
517
  }
@@ -757,29 +813,100 @@ function handleRun() {
757
813
 
758
814
  const runArgs = process.argv.slice(3);
759
815
  const forceNew = runArgs.includes('--new');
760
- const task = runArgs.filter((arg) => arg !== '--new').join(' ').trim();
816
+ const modeArg = argValue('--mode');
817
+ const recipeArg = argValue('--recipe');
818
+ const taskParts = [];
819
+ for (let index = 0; index < runArgs.length; index++) {
820
+ if (runArgs[index] === '--new') continue;
821
+ if (runArgs[index] === '--mode') {
822
+ index += 1;
823
+ continue;
824
+ }
825
+ if (runArgs[index] === '--recipe') {
826
+ index += 1;
827
+ continue;
828
+ }
829
+ taskParts.push(runArgs[index]);
830
+ }
831
+ const task = taskParts.join(' ').trim();
761
832
  let runResult;
762
833
  try {
763
- runResult = createOrResumeRun(CWD, { task, forceNew });
834
+ const current = getCurrentRun(CWD);
835
+ const policy = loadPolicy(CWD);
836
+ const startsNewRun = forceNew || !current || TERMINAL_STATES.has(current.state);
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
+ }
865
+ if (mode) assertModeAllowed(CWD, mode);
866
+ runResult = createOrResumeRun(CWD, {
867
+ task,
868
+ forceNew,
869
+ mode,
870
+ workflow,
871
+ ...(requestedRunId ? { runId: requestedRunId } : {})
872
+ });
873
+ assertBudgetAvailable(CWD, { runId: runResult.run.runId });
764
874
  } catch (err) {
765
875
  log.error(err.message);
766
876
  process.exit(1);
767
877
  }
768
878
  console.log(`- Run: ${runResult.run.runId} (${runResult.resumed ? 'resumed' : 'created'})`);
769
879
  console.log(`- State: ${runResult.run.state}, iteration ${runResult.run.iteration}`);
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
+ }
770
889
 
771
890
  const grok = detectGrokHost();
772
891
 
773
892
  console.log('\n------------------------------------------------------------');
774
893
  log.bold('AI Agent Ready:');
775
894
  console.log('1. Grill if needed, then freeze Goal Contract (core/grill-policy.md, core/goal-contract.md)');
776
- console.log('2. Root Cause Analysis (core/root-cause-analysis.md) & Plan');
777
- console.log('3. Maker TDD at named seams (policies/tdd-policy.md)');
778
- console.log('4. Run Deterministic Verification');
779
- console.log('5. Execute Devil\'s Advocate Adversarial Review');
780
- console.log('6. Judge Agent evaluates DoD and issues PASS verdict');
781
- console.log('7. Context Impact Assessment (NONE / TARGETED / MAJOR)');
782
- console.log('8. Delivery Adapter creates MR/PR');
895
+ if (runResult.run.mode === RUN_MODES.REPORT_ONLY) {
896
+ console.log('2. Analyze evidence without changing repository files');
897
+ console.log('3. Write report.json and finish with `ai-engineering-loop gate report`');
898
+ } else {
899
+ console.log('2. Root Cause Analysis (core/root-cause-analysis.md) & Plan');
900
+ console.log('3. Maker TDD at named seams (policies/tdd-policy.md)');
901
+ console.log('4. Run Deterministic Verification');
902
+ console.log('5. Execute Devil\'s Advocate Adversarial Review');
903
+ console.log('6. Judge Agent evaluates DoD and issues PASS verdict');
904
+ console.log('7. Context Impact Assessment (NONE / TARGETED / MAJOR)');
905
+ console.log('8. Delivery Adapter creates MR/PR');
906
+ if (runResult.run.mode === RUN_MODES.ASSISTED) {
907
+ console.log('9. Human approval is required before the delivery gate');
908
+ }
909
+ }
783
910
 
784
911
  if (grok && grok.host === 'grok-cli') {
785
912
  console.log('------------------------------------------------------------');
@@ -826,12 +953,159 @@ function argValue(name) {
826
953
  return index === -1 ? null : process.argv[index + 1] || null;
827
954
  }
828
955
 
956
+ function parseBooleanArg(name, value) {
957
+ if (!['true', 'false'].includes(String(value))) {
958
+ const err = new Error(`${name} must be true or false`);
959
+ err.code = 'INVALID_POLICY_VALUE';
960
+ throw err;
961
+ }
962
+ return value === 'true';
963
+ }
964
+
965
+ function parsePositiveIntegerArg(name, value) {
966
+ const parsed = Number(value);
967
+ if (!Number.isSafeInteger(parsed) || parsed <= 0) {
968
+ const err = new Error(`${name} must be a positive integer`);
969
+ err.code = 'INVALID_POLICY_VALUE';
970
+ throw err;
971
+ }
972
+ return parsed;
973
+ }
974
+
975
+ function parseNonNegativeIntegerArg(name, value) {
976
+ if (value == null) {
977
+ const err = new Error(`${name} is required`);
978
+ err.code = 'INVALID_USAGE';
979
+ throw err;
980
+ }
981
+ const parsed = Number(value);
982
+ if (!Number.isSafeInteger(parsed) || parsed < 0) {
983
+ const err = new Error(`${name} must be a non-negative integer`);
984
+ err.code = 'INVALID_USAGE';
985
+ throw err;
986
+ }
987
+ return parsed;
988
+ }
989
+
990
+ function handlePolicy() {
991
+ const action = process.argv[3] || 'show';
992
+ const json = process.argv.includes('--json');
993
+ try {
994
+ let policy;
995
+ if (action === 'show') {
996
+ policy = loadPolicy(CWD);
997
+ } else if (action === 'set') {
998
+ const changes = {};
999
+ const mode = argValue('--default-mode');
1000
+ const allowUnattended = argValue('--allow-unattended');
1001
+ const requireSandbox = argValue('--require-sandbox');
1002
+ const perRunLimit = argValue('--per-run-token-limit');
1003
+ const dailyLimit = argValue('--daily-token-limit');
1004
+ if (mode != null) changes.defaultMode = normalizeMode(mode);
1005
+ if (allowUnattended != null) {
1006
+ changes.allowUnattended = parseBooleanArg('--allow-unattended', allowUnattended);
1007
+ }
1008
+ if (requireSandbox != null) {
1009
+ changes.requireSandboxForUnattended = parseBooleanArg('--require-sandbox', requireSandbox);
1010
+ }
1011
+ if (perRunLimit != null) {
1012
+ changes.perRunTokenLimit = parsePositiveIntegerArg('--per-run-token-limit', perRunLimit);
1013
+ }
1014
+ if (dailyLimit != null) {
1015
+ changes.dailyTokenLimit = parsePositiveIntegerArg('--daily-token-limit', dailyLimit);
1016
+ }
1017
+ if (Object.keys(changes).length === 0) {
1018
+ throw new Error('No policy changes provided');
1019
+ }
1020
+ policy = updatePolicy(CWD, changes);
1021
+ } else {
1022
+ throw new Error('Unknown policy action. Use show|set');
1023
+ }
1024
+ if (json) console.log(JSON.stringify(policy));
1025
+ else {
1026
+ log.success(action === 'set' ? '✓ Runtime policy updated' : 'Runtime policy');
1027
+ console.log(JSON.stringify(policy, null, 2));
1028
+ }
1029
+ } catch (err) {
1030
+ if (json) console.log(JSON.stringify({ ok: false, code: err.code || 'POLICY_ERROR', error: err.message }));
1031
+ else log.error(err.message);
1032
+ process.exit(1);
1033
+ }
1034
+ }
1035
+
1036
+ function handleBudget() {
1037
+ const action = process.argv[3] || 'status';
1038
+ const json = process.argv.includes('--json');
1039
+ const runId = argValue('--run');
1040
+ const nodeId = argValue('--node');
1041
+ try {
1042
+ let result;
1043
+ if (action === 'status') {
1044
+ result = budgetStatus(CWD, {
1045
+ runId,
1046
+ nodeId,
1047
+ estimatedTokens: argValue('--estimate') == null
1048
+ ? 0
1049
+ : parseNonNegativeIntegerArg('--estimate', argValue('--estimate'))
1050
+ });
1051
+ } else if (action === 'record') {
1052
+ result = recordTokenUsage(CWD, {
1053
+ runId,
1054
+ nodeId,
1055
+ inputTokens: parseNonNegativeIntegerArg('--input', argValue('--input')),
1056
+ outputTokens: parseNonNegativeIntegerArg('--output', argValue('--output')),
1057
+ model: argValue('--model')
1058
+ });
1059
+ } else if (action === 'pause' || action === 'resume') {
1060
+ result = setKillSwitch(CWD, action === 'pause');
1061
+ } else {
1062
+ throw new Error('Unknown budget action. Use status|record|pause|resume');
1063
+ }
1064
+ if (json) console.log(JSON.stringify(result));
1065
+ else {
1066
+ log.success(action === 'record' ? '✓ Token usage recorded' : `Token budget: ${action}`);
1067
+ console.log(JSON.stringify(result, null, 2));
1068
+ }
1069
+ } catch (err) {
1070
+ if (json) console.log(JSON.stringify({ ok: false, code: err.code || 'BUDGET_ERROR', error: err.message }));
1071
+ else log.error(err.message);
1072
+ process.exit(1);
1073
+ }
1074
+ }
1075
+
1076
+ function handleSandbox() {
1077
+ const action = process.argv[3] || 'status';
1078
+ const json = process.argv.includes('--json');
1079
+ const runId = argValue('--run');
1080
+ try {
1081
+ let result;
1082
+ if (action === 'create') result = createSandbox(CWD, { runId });
1083
+ else if (action === 'capture') result = captureSandbox(CWD, { runId });
1084
+ else if (action === 'abort') result = abortSandbox(CWD, { runId });
1085
+ else if (action === 'status') result = sandboxStatus(CWD, { runId });
1086
+ else throw new Error('Unknown sandbox action. Use create|capture|abort|status');
1087
+ if (json) console.log(JSON.stringify(result));
1088
+ else {
1089
+ log.success(`✓ Sandbox ${action}`);
1090
+ console.log(JSON.stringify(result, null, 2));
1091
+ }
1092
+ } catch (err) {
1093
+ if (json) console.log(JSON.stringify({ ok: false, code: err.code || 'SANDBOX_ERROR', error: err.message }));
1094
+ else log.error(err.message);
1095
+ process.exit(1);
1096
+ }
1097
+ }
1098
+
829
1099
  function handleGate() {
830
1100
  const gate = process.argv[3];
831
1101
  const runId = argValue('--run');
832
1102
  const json = process.argv.includes('--json');
833
1103
  try {
834
- 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 });
835
1109
  if (json) {
836
1110
  console.log(JSON.stringify({
837
1111
  ok: true,
@@ -861,6 +1135,78 @@ function handleGate() {
861
1135
  }
862
1136
  }
863
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
+
864
1210
  function commandFiles(startIndex, optionsWithValues = []) {
865
1211
  const files = [];
866
1212
  for (let index = startIndex; index < process.argv.length; index++) {
@@ -991,6 +1337,119 @@ function handleDoctor() {
991
1337
  if (!result.ok) process.exit(1);
992
1338
  }
993
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
+
994
1453
  // Help Menu
995
1454
  function printHelp() {
996
1455
  console.log(`
@@ -1006,13 +1465,33 @@ Commands:
1006
1465
  refresh Reconcile drifted context against repository non-destructively
1007
1466
  run [task] Start or resume a stateful engineering run, sync hosts, and instruct the agent
1008
1467
  --new start a new run even when another run is active
1468
+ --mode report-only|assisted|unattended
1469
+ --recipe <id> bind an immutable compiled workflow plan
1009
1470
  state Inspect the current run ledger
1010
1471
  --run <id> target a non-current run
1011
1472
  --json print the complete machine-readable ledger
1012
1473
  gate <name> Validate an artifact and advance the current run
1013
- goal | maker | verification | review | judge | delivery
1474
+ goal | report | maker | verification | review | judge | delivery
1014
1475
  --run <id> target a non-current run
1015
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]
1484
+ policy Inspect or update fail-closed runtime controls
1485
+ show [--json]
1486
+ set [--default-mode <mode>] [--allow-unattended true|false]
1487
+ [--require-sandbox true|false]
1488
+ [--per-run-token-limit <n>] [--daily-token-limit <n>]
1489
+ budget Enforce actual provider-reported token usage and emergency pause
1490
+ status [--run <id>] [--node <id>] [--estimate <n>] [--json]
1491
+ record --input <n> --output <n> --model <id> [--run <id>] [--node <id>]
1492
+ pause | resume
1493
+ sandbox Isolate Maker changes in a locked disposable Git worktree
1494
+ create | capture | abort | status [--run <id>] [--json]
1016
1495
  context <stage> <files...>
1017
1496
  Build a bounded, redacted context pack for maker, devil-advocate, or judge
1018
1497
  --run <id> target a non-current run
@@ -1026,6 +1505,17 @@ Commands:
1026
1505
  --json print machine-readable reasons
1027
1506
  doctor Check runtime, schemas, host assets, package contents, and eval catalog
1028
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]
1029
1519
  sync-hosts Copy package skills/agents/commands into ~/.claude ~/.grok ~/.gemini ~/.agents
1030
1520
  (only hosts that already exist; DOT skills only if already installed)
1031
1521
  --dry-run print the plan without writing
@@ -1066,6 +1556,18 @@ switch (command) {
1066
1556
  case 'gate':
1067
1557
  handleGate();
1068
1558
  break;
1559
+ case 'node':
1560
+ handleNode();
1561
+ break;
1562
+ case 'policy':
1563
+ handlePolicy();
1564
+ break;
1565
+ case 'budget':
1566
+ handleBudget();
1567
+ break;
1568
+ case 'sandbox':
1569
+ handleSandbox();
1570
+ break;
1069
1571
  case 'context':
1070
1572
  handleContext();
1071
1573
  break;
@@ -1078,6 +1580,9 @@ switch (command) {
1078
1580
  case 'doctor':
1079
1581
  handleDoctor();
1080
1582
  break;
1583
+ case 'recipe':
1584
+ handleRecipe();
1585
+ break;
1081
1586
  case 'sync-hosts':
1082
1587
  handleSyncHosts();
1083
1588
  break;
@@ -35,10 +35,10 @@ flowchart TD
35
35
  ### Layer 2: Engineering Core (`core/`)
36
36
  - **Authority**: AI Engineering Operating System specification.
37
37
  - **Scope**: Mandatory engineering invariants:
38
- - No code changes without a formalized [Goal Contract](file:///Users/egagofur/Development/work/ai-engineering-loop/core/goal-contract.md).
38
+ - No code changes without a formalized [Goal Contract](./goal-contract.md).
39
39
  - Deterministic checks must pass 100% before adversarial review.
40
40
  - Review findings require reproducible evidence (Level 1–3) to be valid.
41
- - Only the [Judge Agent](file:///Users/egagofur/Development/work/ai-engineering-loop/agents/judge.md) can issue a `PASS` verdict.
41
+ - Only the [Judge Agent](../agents/judge.md) can issue a `PASS` verdict.
42
42
  - **Overridability**: Invariant. Downstream layers cannot skip verification or eliminate agent roles.
43
43
 
44
44
  ### Layer 3: Project Type Profile (`profiles/`)
@@ -55,7 +55,7 @@ flowchart TD
55
55
  - Layer definitions in `architecture.md`.
56
56
  - Architectural constraints and forbidden patterns in `conventions.md`.
57
57
  - Configured delivery adapter (DOT, GitHub, GitLab) in `adapter.md`.
58
- - **Auto-Discovery**: Automatically generated if missing via [Project Initialization](file:///Users/egagofur/Development/work/ai-engineering-loop/core/project-initialization.md).
58
+ - **Auto-Discovery**: Automatically generated if missing via [Project Initialization](./project-initialization.md).
59
59
  - **Overridability**: Overrides Layer 3 defaults for this specific codebase.
60
60
 
61
61
  ### Layer 5: Task Contract
@@ -99,4 +99,4 @@ def resolve_config_key(key: str, context: ExecutionContext) -> Any:
99
99
  - *Refinement (Allowed)*: Profile says "Run unit tests"; Repo config specifies `pnpm run test:unit`. $\rightarrow$ Valid refinement.
100
100
  - *Contradiction (Escalate)*: Core requires deterministic verification; Task contract requests skipping tests to merge faster. $\rightarrow$ **Forbidden**. The engine rejects the override and flags a policy violation.
101
101
  2. **Unresolvable Contradictions**:
102
- - If repository configuration directly contradicts an established platform invariant (e.g. a command requires root sudo or drops protected tables), the system halts and triggers [Human Escalation](file:///Users/egagofur/Development/work/ai-engineering-loop/core/escalation-policy.md).
102
+ - If repository configuration directly contradicts an established platform invariant (e.g. a command requires root sudo or drops protected tables), the system halts and triggers [Human Escalation](./escalation-policy.md).
@@ -92,7 +92,7 @@ flowchart TD
92
92
 
93
93
  ## 4. Devil's Advocate & Judge Drift Interaction
94
94
 
95
- During task review, the [Devil's Advocate](file:///Users/egagofur/Development/work/ai-engineering-loop/agents/devil-advocate.md) may discover that the codebase has drifted from the documented architecture:
95
+ During task review, the [Devil's Advocate](../agents/devil-advocate.md) may discover that the codebase has drifted from the documented architecture:
96
96
 
97
97
  > *Example Review Finding*: "The implementation assumes `user-service` connects directly to Postgres, but the codebase has migrated to an asynchronous event queue in `src/events/`."
98
98