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.
- package/.agents/workflows/ai-engineering-loop.md +5 -5
- package/.claude/skills/ai-engineering-loop/SKILL.md +7 -5
- package/.gemini/skills/ai-engineering-loop/SKILL.md +7 -5
- package/.grok/skills/ai-engineering-loop/SKILL.md +7 -5
- package/README.md +56 -6
- package/README.npm.md +9 -1
- package/SECURITY.md +8 -2
- package/agents/judge.md +5 -5
- package/agents/maker.md +6 -6
- package/agents/recipe-builder.md +28 -0
- package/bin/ai-engineering-loop.js +521 -16
- package/core/configuration-precedence.md +4 -4
- package/core/context-impact-assessment.md +1 -1
- package/core/controlled-workflow-runtime.md +77 -0
- package/core/definition-of-done.md +3 -3
- package/core/escalation-policy.md +2 -2
- package/core/goal-contract.md +2 -2
- package/core/iteration-policy.md +4 -4
- package/core/project-initialization.md +2 -2
- package/core/runtime-safety.md +75 -0
- package/core/verification-loop.md +1 -1
- package/core/workflow-recipes.md +140 -0
- package/lib/budget.js +258 -0
- package/lib/doctor.js +38 -2
- package/lib/gates.js +55 -1
- package/lib/node-registry.js +155 -0
- package/lib/package-audit.js +78 -0
- package/lib/recipe-builder.js +200 -0
- package/lib/recipe.js +495 -0
- package/lib/run-state.js +94 -8
- package/lib/runtime-files.js +54 -0
- package/lib/runtime-policy.js +118 -0
- package/lib/safe-context.js +3 -0
- package/lib/sandbox.js +305 -0
- package/lib/workflow-runtime.js +692 -0
- package/package.json +7 -3
- package/policies/finding-policy.md +2 -2
- package/policies/no-progress-policy.md +2 -2
- package/profiles/README.md +5 -5
- package/profiles/backend-api.md +1 -1
- package/profiles/library.md +1 -1
- package/profiles/mobile-app.md +1 -1
- package/profiles/monorepo.md +1 -1
- package/profiles/web-app.md +1 -1
- package/recipes/audit.json +32 -0
- package/recipes/bugfix.json +63 -0
- package/recipes/default.json +49 -0
- package/recipes/docs-light.json +63 -0
- package/recipes/high-risk.json +69 -0
- package/recipes/refactor.json +63 -0
- package/schemas/compiled-plan.schema.json +19 -0
- package/schemas/delivery.schema.json +2 -1
- package/schemas/node-definition.schema.json +33 -0
- package/schemas/recipe.schema.json +26 -0
- package/schemas/report.schema.json +17 -0
- package/schemas/workflow-event.schema.json +28 -0
- 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
|
-
|
|
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.
|
|
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
|
-
|
|
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
|
|
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
|
-
|
|
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
|
-
|
|
777
|
-
|
|
778
|
-
|
|
779
|
-
|
|
780
|
-
|
|
781
|
-
|
|
782
|
-
|
|
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
|
|
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](
|
|
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](
|
|
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](
|
|
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](
|
|
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](
|
|
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
|
|