ai-engineering-loop 1.0.21 → 1.1.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 (89) hide show
  1. package/.agents/workflows/ai-engineering-loop.md +7 -3
  2. package/.claude/skills/ai-engineering-loop/SKILL.md +13 -7
  3. package/.gemini/skills/ai-engineering-loop/SKILL.md +13 -7
  4. package/.grok/skills/ai-engineering-loop/SKILL.md +13 -7
  5. package/README.md +26 -3
  6. package/SECURITY.md +23 -0
  7. package/SUPPORT.md +28 -0
  8. package/bin/ai-engineering-loop.js +255 -3
  9. package/core/artifact-gates.md +49 -0
  10. package/evals/README.md +35 -0
  11. package/evals/cases/01-stale-verification.json +17 -0
  12. package/evals/cases/02-vague-verification.json +16 -0
  13. package/evals/cases/03-missing-ac-evidence.json +17 -0
  14. package/evals/cases/04-hallucinated-citation.json +17 -0
  15. package/evals/cases/05-prompt-injection.json +17 -0
  16. package/evals/cases/06-source-secret.json +16 -0
  17. package/evals/cases/07-log-secret.json +16 -0
  18. package/evals/cases/08-symlink-escape.json +16 -0
  19. package/evals/cases/09-authorization-bypass.json +16 -0
  20. package/evals/cases/10-payment-idempotency.json +16 -0
  21. package/evals/cases/11-concurrent-update.json +16 -0
  22. package/evals/cases/12-swallowed-error.json +16 -0
  23. package/evals/cases/13-happy-path-only.json +17 -0
  24. package/evals/cases/14-invalid-finding-axis.json +16 -0
  25. package/evals/cases/15-blocker-without-alternative.json +16 -0
  26. package/evals/cases/16-unsupported-pass.json +17 -0
  27. package/evals/cases/17-soft-standard.json +16 -0
  28. package/evals/cases/18-iteration-ceiling.json +17 -0
  29. package/evals/cases/19-safe-documentation-change.json +17 -0
  30. package/evals/cases/20-valid-boundary-feature.json +18 -0
  31. package/lib/doctor.js +98 -0
  32. package/lib/escalation.js +192 -0
  33. package/lib/evaluation.js +137 -0
  34. package/lib/gates.js +315 -0
  35. package/lib/orchestration.js +5 -1
  36. package/lib/run-state.js +221 -0
  37. package/lib/safe-context.js +191 -0
  38. package/lib/sync-hosts.js +6 -5
  39. package/package.json +12 -9
  40. package/policies/model-escalation.md +41 -0
  41. package/schemas/delivery.schema.json +14 -0
  42. package/schemas/finding-ledger.schema.json +27 -0
  43. package/schemas/goal-contract.schema.json +32 -0
  44. package/schemas/verdict.schema.json +17 -0
  45. package/schemas/verification.schema.json +32 -0
  46. package/docs/antigravity-feasibility.md +0 -92
  47. package/docs/claude-code-feasibility.md +0 -80
  48. package/docs/grok-cli-feasibility.md +0 -99
  49. package/docs/migration-plan.md +0 -70
  50. package/examples/backend-api/payment-idempotency/README.md +0 -33
  51. package/examples/backend-api/payment-idempotency/goal-contract.md +0 -33
  52. package/examples/backend-api/payment-idempotency/judge-verdict.md +0 -28
  53. package/examples/backend-api/payment-idempotency/review-findings.md +0 -50
  54. package/examples/dot/status-display/README.md +0 -23
  55. package/examples/dot/status-display/delivery-report.md +0 -41
  56. package/examples/dot/status-display/goal-contract.md +0 -46
  57. package/examples/dot/status-display/judge-verdict.md +0 -44
  58. package/examples/dot/status-display/review-findings.md +0 -63
  59. package/examples/initialization/README.md +0 -19
  60. package/examples/initialization/discovery-trace.md +0 -63
  61. package/examples/initialization/generated-context.md +0 -110
  62. package/examples/mobile-app/offline-sync-queue/README.md +0 -33
  63. package/examples/mobile-app/offline-sync-queue/goal-contract.md +0 -32
  64. package/examples/mobile-app/offline-sync-queue/judge-verdict.md +0 -27
  65. package/examples/mobile-app/offline-sync-queue/review-findings.md +0 -30
  66. package/scripts/init.sh +0 -106
  67. package/templates/repo-config/adapter.md +0 -11
  68. package/templates/repo-config/adr-readme.md +0 -33
  69. package/templates/repo-config/architecture.md +0 -15
  70. package/templates/repo-config/claude-permissions.json +0 -10
  71. package/templates/repo-config/config.md +0 -11
  72. package/templates/repo-config/conventions.md +0 -16
  73. package/templates/repo-config/glossary.md +0 -18
  74. package/templates/repo-config/lessons.md +0 -8
  75. package/templates/repo-config/verification.md +0 -13
  76. package/templates/repo-config/workflow.md +0 -25
  77. package/tests/capability-selection.test.js +0 -207
  78. package/tests/claimed-vs-reality.test.js +0 -27
  79. package/tests/dot-branch-policy.test.js +0 -65
  80. package/tests/generate-adapter.test.js +0 -80
  81. package/tests/generate-workflow.test.js +0 -180
  82. package/tests/grok-runtime.test.js +0 -201
  83. package/tests/intern-catalog.test.js +0 -72
  84. package/tests/living-context.test.js +0 -61
  85. package/tests/no-company-leak.test.js +0 -82
  86. package/tests/orchestration.test.js +0 -368
  87. package/tests/qa-delivery-template.test.js +0 -90
  88. package/tests/skill-host-compat.test.js +0 -406
  89. package/tests/sync-hosts.test.js +0 -168
@@ -0,0 +1,192 @@
1
+ 'use strict';
2
+
3
+ const fs = require('fs');
4
+ const path = require('path');
5
+ const { atomicWriteJson, getCurrentRun, loadRun, runsDir } = require('./run-state.js');
6
+
7
+ const MODEL_TIERS = Object.freeze({
8
+ CHEAP_MODEL: 'CHEAP_MODEL',
9
+ STRONG_MODEL: 'STRONG_MODEL',
10
+ HUMAN: 'HUMAN'
11
+ });
12
+
13
+ const TIER_RANK = Object.freeze({
14
+ CHEAP_MODEL: 0,
15
+ STRONG_MODEL: 1,
16
+ HUMAN: 2
17
+ });
18
+
19
+ const HIGH_RISK_PATHS = [
20
+ /(^|\/)(auth|authorization|permissions?|access-control)(\/|[._-])/i,
21
+ /(^|\/)(payments?|billing|invoices?|ledger)(\/|[._-])/i,
22
+ /(^|\/)(migrations?|schema)(\/|[._-])/i,
23
+ /(^|\/)(infra|terraform|k8s|kubernetes|deploy)(\/|[._-])/i,
24
+ /(^|\/)(crypto|encryption|secrets?)(\/|[._-])/i
25
+ ];
26
+
27
+ function escalationError(message, code = 'ESCALATION_FAILED') {
28
+ const err = new Error(message);
29
+ err.code = code;
30
+ return err;
31
+ }
32
+
33
+ function extractChangedPaths(diff) {
34
+ const paths = [];
35
+ for (const line of String(diff || '').split('\n')) {
36
+ const match = line.match(/^\+\+\+ b\/(.+)$/);
37
+ if (match && match[1] !== '/dev/null' && !paths.includes(match[1])) paths.push(match[1]);
38
+ }
39
+ return paths;
40
+ }
41
+
42
+ function isHighRiskPath(filePath) {
43
+ return HIGH_RISK_PATHS.some((pattern) => pattern.test(String(filePath || '')));
44
+ }
45
+
46
+ function assessEscalation({
47
+ changedPaths = [],
48
+ iteration = 1,
49
+ maxIterations = 3,
50
+ schemaFailures = 0,
51
+ hallucinatedCitations = 0,
52
+ reviewerJudgeDisagreement = false,
53
+ verificationFlaky = false,
54
+ contextTruncated = false,
55
+ criticalUnknowns = 0,
56
+ secretLeakDetected = false
57
+ } = {}) {
58
+ const reasons = [];
59
+ let requiredTier = MODEL_TIERS.CHEAP_MODEL;
60
+ const requireTier = (tier, code, detail) => {
61
+ if (TIER_RANK[tier] > TIER_RANK[requiredTier]) requiredTier = tier;
62
+ if (!reasons.some((reason) => reason.code === code)) reasons.push({ code, detail, requiredTier: tier });
63
+ };
64
+
65
+ const riskyPaths = changedPaths.filter(isHighRiskPath);
66
+ if (riskyPaths.length) {
67
+ requireTier(MODEL_TIERS.STRONG_MODEL, 'HIGH_RISK_PATH', riskyPaths.join(', '));
68
+ }
69
+ if (schemaFailures >= 2) {
70
+ requireTier(MODEL_TIERS.STRONG_MODEL, 'REPEATED_SCHEMA_FAILURE', `${schemaFailures} invalid model artifacts`);
71
+ }
72
+ if (hallucinatedCitations > 0) {
73
+ requireTier(MODEL_TIERS.STRONG_MODEL, 'HALLUCINATED_CITATION', `${hallucinatedCitations} nonexistent citations`);
74
+ }
75
+ if (reviewerJudgeDisagreement) {
76
+ requireTier(MODEL_TIERS.STRONG_MODEL, 'REVIEWER_JUDGE_DISAGREEMENT', 'Judge contradicts deterministic finding disposition');
77
+ }
78
+ if (verificationFlaky) {
79
+ requireTier(MODEL_TIERS.STRONG_MODEL, 'FLAKY_VERIFICATION', 'Repeated verification produced inconsistent results');
80
+ }
81
+ if (contextTruncated) {
82
+ requireTier(MODEL_TIERS.STRONG_MODEL, 'TRUNCATED_CONTEXT', 'A stage context pack omitted source bytes');
83
+ }
84
+ if (criticalUnknowns > 0) {
85
+ requireTier(MODEL_TIERS.STRONG_MODEL, 'CRITICAL_UNKNOWN', `${criticalUnknowns} critical acceptance criteria remain unknown`);
86
+ }
87
+ if (iteration >= maxIterations) {
88
+ requireTier(MODEL_TIERS.HUMAN, 'ITERATION_CEILING', `Iteration ${iteration} reached the ceiling ${maxIterations}`);
89
+ }
90
+ if (secretLeakDetected) {
91
+ requireTier(MODEL_TIERS.HUMAN, 'SECRET_LEAK', 'A secret canary or credential reached model-visible output');
92
+ }
93
+
94
+ return {
95
+ schemaVersion: 1,
96
+ requiredTier,
97
+ escalate: requiredTier !== MODEL_TIERS.CHEAP_MODEL,
98
+ riskyPaths,
99
+ reasons
100
+ };
101
+ }
102
+
103
+ function tierSatisfies(actualTier, requiredTier) {
104
+ return Object.hasOwn(TIER_RANK, actualTier) &&
105
+ Object.hasOwn(TIER_RANK, requiredTier) &&
106
+ TIER_RANK[actualTier] >= TIER_RANK[requiredTier];
107
+ }
108
+
109
+ function readOptionalJson(filePath) {
110
+ if (!fs.existsSync(filePath)) return {};
111
+ try {
112
+ return JSON.parse(fs.readFileSync(filePath, 'utf8'));
113
+ } catch (cause) {
114
+ throw escalationError(`Invalid escalation signals: ${cause.message}`);
115
+ }
116
+ }
117
+
118
+ function contextWasTruncated(rootDir, runId) {
119
+ const contextDir = path.join(runsDir(rootDir), runId, 'context');
120
+ if (!fs.existsSync(contextDir)) return false;
121
+ return fs.readdirSync(contextDir)
122
+ .filter((file) => file.endsWith('.json'))
123
+ .some((file) => {
124
+ const pack = readOptionalJson(path.join(contextDir, file));
125
+ return (pack.entries || []).some((entry) => entry.truncated === true);
126
+ });
127
+ }
128
+
129
+ function resolveRun(rootDir, runId) {
130
+ if (runId) return loadRun(rootDir, runId);
131
+ const current = getCurrentRun(rootDir);
132
+ if (!current) throw escalationError('No current run. Start one before assessing escalation.', 'NO_CURRENT_RUN');
133
+ return current;
134
+ }
135
+
136
+ function assessRunEscalation(rootDir, { runId } = {}) {
137
+ const run = resolveRun(rootDir, runId);
138
+ const runDir = path.join(runsDir(rootDir), run.runId);
139
+ const diffPath = path.join(runDir, 'diff.patch');
140
+ const diff = fs.existsSync(diffPath) ? fs.readFileSync(diffPath, 'utf8') : '';
141
+ const signals = readOptionalJson(path.join(runDir, 'risk.json'));
142
+ if (signals.runId && signals.runId !== run.runId) {
143
+ throw escalationError(`risk.json runId must be ${run.runId}`);
144
+ }
145
+ const assessment = assessEscalation({
146
+ changedPaths: extractChangedPaths(diff),
147
+ iteration: run.iteration,
148
+ maxIterations: signals.maxIterations || 3,
149
+ schemaFailures: signals.schemaFailures || 0,
150
+ hallucinatedCitations: signals.hallucinatedCitations || 0,
151
+ reviewerJudgeDisagreement: signals.reviewerJudgeDisagreement === true,
152
+ verificationFlaky: signals.verificationFlaky === true,
153
+ contextTruncated: contextWasTruncated(rootDir, run.runId),
154
+ criticalUnknowns: signals.criticalUnknowns || 0,
155
+ secretLeakDetected: signals.secretLeakDetected === true
156
+ });
157
+ const document = {
158
+ ...assessment,
159
+ runId: run.runId,
160
+ iteration: run.iteration,
161
+ assessedAt: new Date().toISOString()
162
+ };
163
+ atomicWriteJson(path.join(runDir, 'escalation.json'), document);
164
+ return document;
165
+ }
166
+
167
+ function enforceVerdictTier(rootDir, run, verdict) {
168
+ const assessment = assessRunEscalation(rootDir, { runId: run.runId });
169
+ if (verdict.verdict !== 'PASS') return assessment;
170
+ const actualTier = verdict.modelTier || MODEL_TIERS.CHEAP_MODEL;
171
+ if (!tierSatisfies(actualTier, assessment.requiredTier)) {
172
+ throw escalationError(
173
+ `Escalation required: ${assessment.requiredTier}; verdict used ${actualTier}`,
174
+ 'ESCALATION_REQUIRED'
175
+ );
176
+ }
177
+ if (assessment.requiredTier === MODEL_TIERS.HUMAN && verdict.humanApproved !== true) {
178
+ throw escalationError('Human approval is required for this verdict', 'HUMAN_APPROVAL_REQUIRED');
179
+ }
180
+ return assessment;
181
+ }
182
+
183
+ module.exports = {
184
+ MODEL_TIERS,
185
+ HIGH_RISK_PATHS,
186
+ extractChangedPaths,
187
+ isHighRiskPath,
188
+ assessEscalation,
189
+ tierSatisfies,
190
+ assessRunEscalation,
191
+ enforceVerdictTier
192
+ };
@@ -0,0 +1,137 @@
1
+ 'use strict';
2
+
3
+ const fs = require('fs');
4
+ const path = require('path');
5
+
6
+ const VERDICTS = new Set(['PASS', 'ITERATE', 'ESCALATE']);
7
+
8
+ function evaluationError(message, details = []) {
9
+ const err = new Error(message);
10
+ err.code = 'EVALUATION_FAILED';
11
+ err.details = details;
12
+ return err;
13
+ }
14
+
15
+ function defaultCasesDir() {
16
+ return path.join(__dirname, '..', 'evals', 'cases');
17
+ }
18
+
19
+ function validateCase(fixture) {
20
+ const errors = [];
21
+ if (fixture?.schemaVersion !== 1) errors.push('schemaVersion must be 1');
22
+ if (!/^[a-z0-9][a-z0-9-]+$/.test(String(fixture?.id || ''))) errors.push('id must be kebab-case');
23
+ if (!String(fixture?.title || '').trim()) errors.push('title is required');
24
+ if (!String(fixture?.category || '').trim()) errors.push('category is required');
25
+ if (!['low', 'medium', 'high', 'critical'].includes(fixture?.risk)) errors.push('risk is invalid');
26
+ if (!String(fixture?.task || '').trim()) errors.push('task is required');
27
+ if (!Array.isArray(fixture?.files) || fixture.files.length === 0) errors.push('files must not be empty');
28
+ for (const [index, file] of (fixture?.files || []).entries()) {
29
+ if (!String(file?.path || '').trim()) errors.push(`files[${index}].path is required`);
30
+ if (typeof file?.content !== 'string') errors.push(`files[${index}].content must be a string`);
31
+ }
32
+ if (!VERDICTS.has(fixture?.oracle?.verdict)) errors.push('oracle.verdict is invalid');
33
+ if (!Array.isArray(fixture?.oracle?.requiredSignals)) errors.push('oracle.requiredSignals must be an array');
34
+ if (!Array.isArray(fixture?.oracle?.forbiddenOutput)) errors.push('oracle.forbiddenOutput must be an array');
35
+ return { valid: errors.length === 0, errors };
36
+ }
37
+
38
+ function loadEvaluationCases(casesDir = defaultCasesDir()) {
39
+ const files = fs.readdirSync(casesDir)
40
+ .filter((file) => file.endsWith('.json'))
41
+ .sort();
42
+ const fixtures = [];
43
+ const errors = [];
44
+ const ids = new Set();
45
+ for (const file of files) {
46
+ let fixture;
47
+ try {
48
+ fixture = JSON.parse(fs.readFileSync(path.join(casesDir, file), 'utf8'));
49
+ } catch (cause) {
50
+ errors.push(`${file}: invalid JSON (${cause.message})`);
51
+ continue;
52
+ }
53
+ const check = validateCase(fixture);
54
+ for (const error of check.errors) errors.push(`${file}: ${error}`);
55
+ if (ids.has(fixture.id)) errors.push(`${file}: duplicate id ${fixture.id}`);
56
+ ids.add(fixture.id);
57
+ fixtures.push(fixture);
58
+ }
59
+ if (fixtures.length === 0) errors.push('no evaluation cases found');
60
+ if (errors.length) throw evaluationError('Evaluation catalog is invalid', errors);
61
+ return fixtures;
62
+ }
63
+
64
+ function loadResults(resultsDir) {
65
+ if (!resultsDir) return [];
66
+ return fs.readdirSync(resultsDir)
67
+ .filter((file) => file.endsWith('.json'))
68
+ .sort()
69
+ .map((file) => JSON.parse(fs.readFileSync(path.join(resultsDir, file), 'utf8')));
70
+ }
71
+
72
+ function scoreEvaluationResults(fixtures, results) {
73
+ const resultByCase = new Map((results || []).map((result) => [result.caseId, result]));
74
+ const cases = fixtures.map((fixture) => {
75
+ const result = resultByCase.get(fixture.id);
76
+ if (!result) {
77
+ return {
78
+ caseId: fixture.id,
79
+ expected: fixture.oracle.verdict,
80
+ actual: null,
81
+ passed: false,
82
+ missing: true,
83
+ incorrectPass: false,
84
+ missingSignals: fixture.oracle.requiredSignals,
85
+ leakedCanaries: []
86
+ };
87
+ }
88
+ const output = String(result.output || '');
89
+ const signals = new Set(Array.isArray(result.signals) ? result.signals : []);
90
+ const missingSignals = fixture.oracle.requiredSignals.filter((signal) => !signals.has(signal));
91
+ const leakedCanaries = fixture.oracle.forbiddenOutput.filter((canary) => output.includes(canary));
92
+ const verdictMatches = result.verdict === fixture.oracle.verdict;
93
+ return {
94
+ caseId: fixture.id,
95
+ expected: fixture.oracle.verdict,
96
+ actual: result.verdict || null,
97
+ passed: verdictMatches && missingSignals.length === 0 && leakedCanaries.length === 0,
98
+ missing: false,
99
+ incorrectPass: fixture.oracle.verdict !== 'PASS' && result.verdict === 'PASS',
100
+ missingSignals,
101
+ leakedCanaries
102
+ };
103
+ });
104
+
105
+ const completed = cases.filter((item) => !item.missing).length;
106
+ const passed = cases.filter((item) => item.passed).length;
107
+ return {
108
+ total: fixtures.length,
109
+ completed,
110
+ passed,
111
+ failed: cases.length - passed,
112
+ incorrectPasses: cases.filter((item) => item.incorrectPass).length,
113
+ secretLeaks: cases.reduce((sum, item) => sum + item.leakedCanaries.length, 0),
114
+ passRate: fixtures.length ? passed / fixtures.length : 0,
115
+ cases
116
+ };
117
+ }
118
+
119
+ function catalogSummary(fixtures) {
120
+ const categories = {};
121
+ const verdicts = {};
122
+ for (const fixture of fixtures) {
123
+ categories[fixture.category] = (categories[fixture.category] || 0) + 1;
124
+ verdicts[fixture.oracle.verdict] = (verdicts[fixture.oracle.verdict] || 0) + 1;
125
+ }
126
+ return { total: fixtures.length, categories, verdicts };
127
+ }
128
+
129
+ module.exports = {
130
+ VERDICTS,
131
+ defaultCasesDir,
132
+ validateCase,
133
+ loadEvaluationCases,
134
+ loadResults,
135
+ scoreEvaluationResults,
136
+ catalogSummary
137
+ };
package/lib/gates.js ADDED
@@ -0,0 +1,315 @@
1
+ 'use strict';
2
+
3
+ const crypto = require('crypto');
4
+ const fs = require('fs');
5
+ const path = require('path');
6
+ const {
7
+ validateVerificationEvidence,
8
+ validateFindingLedger,
9
+ computeJudgeVerdict
10
+ } = require('./orchestration.js');
11
+ const {
12
+ RUN_STATES,
13
+ getCurrentRun,
14
+ getGitRevision,
15
+ loadRun,
16
+ runsDir,
17
+ transitionRun
18
+ } = require('./run-state.js');
19
+ const {
20
+ enforceVerdictTier
21
+ } = require('./escalation.js');
22
+
23
+ const GATE_FILES = Object.freeze({
24
+ goal: 'goal-contract.json',
25
+ maker: 'diff.patch',
26
+ verification: 'verification.json',
27
+ review: 'findings.json',
28
+ judge: 'verdict.json',
29
+ delivery: 'delivery.json'
30
+ });
31
+
32
+ function gateError(message, details = []) {
33
+ const err = new Error(message);
34
+ err.code = 'GATE_FAILED';
35
+ err.details = details;
36
+ return err;
37
+ }
38
+
39
+ function artifactPath(rootDir, runId, fileName) {
40
+ return path.join(runsDir(rootDir), runId, fileName);
41
+ }
42
+
43
+ function readJsonArtifact(rootDir, runId, fileName) {
44
+ const filePath = artifactPath(rootDir, runId, fileName);
45
+ let value;
46
+ try {
47
+ value = JSON.parse(fs.readFileSync(filePath, 'utf8'));
48
+ } catch (cause) {
49
+ throw gateError(`Missing or invalid ${fileName}: ${cause.message}`);
50
+ }
51
+ return { filePath, value };
52
+ }
53
+
54
+ function hashContent(content) {
55
+ return crypto.createHash('sha256').update(content).digest('hex');
56
+ }
57
+
58
+ function hashFile(filePath) {
59
+ try {
60
+ return hashContent(fs.readFileSync(filePath));
61
+ } catch (cause) {
62
+ throw gateError(`Unable to hash ${filePath}: ${cause.message}`);
63
+ }
64
+ }
65
+
66
+ function descriptor(rootDir, filePath) {
67
+ return {
68
+ path: path.relative(rootDir, filePath).split(path.sep).join('/'),
69
+ sha256: hashFile(filePath)
70
+ };
71
+ }
72
+
73
+ function assertArtifactCurrent(rootDir, run, name) {
74
+ const artifact = run.artifacts[name];
75
+ if (!artifact?.path || !artifact.sha256) {
76
+ throw gateError(`Required ${name} artifact has not passed its gate`);
77
+ }
78
+ const filePath = path.join(rootDir, artifact.path);
79
+ if (hashFile(filePath) !== artifact.sha256) {
80
+ throw gateError(`${name} artifact changed after its gate; rerun the owning stage`);
81
+ }
82
+ }
83
+
84
+ function requireRunMetadata(document, run, label) {
85
+ const errors = [];
86
+ if (document.schemaVersion !== 1) errors.push('schemaVersion must be 1');
87
+ if (document.runId !== run.runId) errors.push(`runId must be ${run.runId}`);
88
+ if (errors.length) throw gateError(`${label} metadata is invalid`, errors);
89
+ }
90
+
91
+ function validateGoalContract(contract) {
92
+ const errors = [];
93
+ if (!contract || typeof contract !== 'object') return { valid: false, errors: ['contract must be an object'] };
94
+ if (!String(contract.objective || '').trim()) errors.push('objective is required');
95
+ if (!Array.isArray(contract.acceptanceCriteria) || contract.acceptanceCriteria.length === 0) {
96
+ errors.push('acceptanceCriteria must contain at least one item');
97
+ } else {
98
+ const ids = new Set();
99
+ contract.acceptanceCriteria.forEach((criterion, index) => {
100
+ if (!criterion || typeof criterion !== 'object') {
101
+ errors.push(`acceptanceCriteria[${index}] must be an object`);
102
+ return;
103
+ }
104
+ if (!/^AC-\d+$/.test(String(criterion.id || ''))) {
105
+ errors.push(`acceptanceCriteria[${index}].id must match AC-N`);
106
+ } else if (ids.has(criterion.id)) {
107
+ errors.push(`duplicate acceptance criterion: ${criterion.id}`);
108
+ } else {
109
+ ids.add(criterion.id);
110
+ }
111
+ if (!String(criterion.statement || '').trim()) {
112
+ errors.push(`acceptanceCriteria[${index}].statement is required`);
113
+ }
114
+ if (!String(criterion.evidenceRequired || '').trim()) {
115
+ errors.push(`acceptanceCriteria[${index}].evidenceRequired is required`);
116
+ }
117
+ if (!Array.isArray(criterion.failureCases) || criterion.failureCases.length === 0) {
118
+ errors.push(`acceptanceCriteria[${index}].failureCases must not be empty`);
119
+ } else if (criterion.failureCases.some((failureCase) => !String(failureCase || '').trim())) {
120
+ errors.push(`acceptanceCriteria[${index}].failureCases must contain non-empty strings`);
121
+ }
122
+ });
123
+ }
124
+ return { valid: errors.length === 0, errors };
125
+ }
126
+
127
+ function validateVerificationBundle(bundle, run, diffHash, currentRevision) {
128
+ const errors = [];
129
+ requireRunMetadata(bundle, run, 'verification');
130
+ if (bundle.gitRevision !== currentRevision) {
131
+ errors.push(`gitRevision is stale: expected ${currentRevision}, received ${bundle.gitRevision || '(missing)'}`);
132
+ }
133
+ if (bundle.diffHash !== diffHash) {
134
+ errors.push('diffHash does not match the gated Maker diff');
135
+ }
136
+ if (!Array.isArray(bundle.commands) || bundle.commands.length === 0) {
137
+ errors.push('commands must contain at least one verification result');
138
+ } else {
139
+ bundle.commands.forEach((command, index) => {
140
+ const result = validateVerificationEvidence(command);
141
+ if (!result.valid) errors.push(`commands[${index}]: ${result.reason}`);
142
+ });
143
+ }
144
+ return { valid: errors.length === 0, errors };
145
+ }
146
+
147
+ function validateVerdictDocument(verdict, run) {
148
+ const errors = [];
149
+ requireRunMetadata(verdict, run, 'verdict');
150
+ if (!['PASS', 'ITERATE', 'ESCALATE'].includes(verdict.verdict)) {
151
+ errors.push('verdict must be PASS, ITERATE, or ESCALATE');
152
+ }
153
+ if (!String(verdict.reason || '').trim()) errors.push('reason is required');
154
+ if (!String(verdict.action || '').trim()) errors.push('action is required');
155
+ if (verdict.modelTier != null && !['CHEAP_MODEL', 'STRONG_MODEL', 'HUMAN'].includes(verdict.modelTier)) {
156
+ errors.push('modelTier must be CHEAP_MODEL, STRONG_MODEL, or HUMAN');
157
+ }
158
+ if (verdict.humanApproved != null && typeof verdict.humanApproved !== 'boolean') {
159
+ errors.push('humanApproved must be a boolean');
160
+ }
161
+ return { valid: errors.length === 0, errors };
162
+ }
163
+
164
+ function verificationForJudge(bundle) {
165
+ const first = bundle.commands[0];
166
+ return {
167
+ ...first,
168
+ summary: bundle.commands.map((command) => command.summary || command.command).join('; ')
169
+ };
170
+ }
171
+
172
+ function resolveRun(rootDir, runId) {
173
+ if (runId) return loadRun(rootDir, runId);
174
+ const current = getCurrentRun(rootDir);
175
+ if (!current) throw gateError('No current run. Start one with `ai-engineering-loop run <task>`.');
176
+ return current;
177
+ }
178
+
179
+ function applyGate(rootDir, gate, { runId } = {}) {
180
+ if (!Object.hasOwn(GATE_FILES, gate)) {
181
+ throw gateError(`Unknown gate: ${gate}. Use ${Object.keys(GATE_FILES).join('|')}`);
182
+ }
183
+ const run = resolveRun(rootDir, runId);
184
+
185
+ if (gate === 'goal') {
186
+ const { filePath, value } = readJsonArtifact(rootDir, run.runId, GATE_FILES.goal);
187
+ requireRunMetadata(value, run, 'goal contract');
188
+ const check = validateGoalContract(value);
189
+ if (!check.valid) throw gateError('Goal Contract gate failed', check.errors);
190
+ return transitionRun(rootDir, run.runId, RUN_STATES.GOAL_FROZEN, {
191
+ gate,
192
+ artifacts: { goalContract: descriptor(rootDir, filePath) }
193
+ });
194
+ }
195
+
196
+ if (gate === 'maker') {
197
+ const filePath = artifactPath(rootDir, run.runId, GATE_FILES.maker);
198
+ let diff;
199
+ try {
200
+ diff = fs.readFileSync(filePath, 'utf8');
201
+ } catch (cause) {
202
+ throw gateError(`Missing ${GATE_FILES.maker}: ${cause.message}`);
203
+ }
204
+ if (!diff.trim()) throw gateError('Maker gate failed: diff.patch is empty');
205
+ return transitionRun(rootDir, run.runId, RUN_STATES.MAKER_COMPLETE, {
206
+ gate,
207
+ artifacts: { diff: descriptor(rootDir, filePath) }
208
+ });
209
+ }
210
+
211
+ if (gate === 'verification') {
212
+ const diffPath = artifactPath(rootDir, run.runId, GATE_FILES.maker);
213
+ const diffHash = hashFile(diffPath);
214
+ if (run.artifacts.diff?.sha256 !== diffHash) {
215
+ throw gateError('Maker diff changed after its gate; run the Maker gate again');
216
+ }
217
+ const { filePath, value } = readJsonArtifact(rootDir, run.runId, GATE_FILES.verification);
218
+ const check = validateVerificationBundle(value, run, diffHash, getGitRevision(rootDir));
219
+ if (!check.valid) throw gateError('Verification gate failed', check.errors);
220
+ return transitionRun(rootDir, run.runId, RUN_STATES.VERIFIED, {
221
+ gate,
222
+ artifacts: { verification: descriptor(rootDir, filePath) }
223
+ });
224
+ }
225
+
226
+ if (gate === 'review') {
227
+ assertArtifactCurrent(rootDir, run, 'goalContract');
228
+ assertArtifactCurrent(rootDir, run, 'diff');
229
+ assertArtifactCurrent(rootDir, run, 'verification');
230
+ const { filePath, value } = readJsonArtifact(rootDir, run.runId, GATE_FILES.review);
231
+ requireRunMetadata(value, run, 'Finding Ledger');
232
+ if (value.diffHash !== run.artifacts.diff?.sha256) {
233
+ throw gateError('Finding Ledger diffHash does not match the gated Maker diff');
234
+ }
235
+ const check = validateFindingLedger(value);
236
+ if (!check.valid) throw gateError('Review gate failed', [check.reason]);
237
+ return transitionRun(rootDir, run.runId, RUN_STATES.REVIEWED, {
238
+ gate,
239
+ artifacts: { findings: descriptor(rootDir, filePath) }
240
+ });
241
+ }
242
+
243
+ if (gate === 'judge') {
244
+ assertArtifactCurrent(rootDir, run, 'goalContract');
245
+ assertArtifactCurrent(rootDir, run, 'diff');
246
+ assertArtifactCurrent(rootDir, run, 'verification');
247
+ assertArtifactCurrent(rootDir, run, 'findings');
248
+ const { filePath, value } = readJsonArtifact(rootDir, run.runId, GATE_FILES.judge);
249
+ const verdictCheck = validateVerdictDocument(value, run);
250
+ if (!verdictCheck.valid) throw gateError('Judge gate failed', verdictCheck.errors);
251
+ try {
252
+ enforceVerdictTier(rootDir, run, value);
253
+ } catch (cause) {
254
+ throw gateError(cause.message, [cause.code]);
255
+ }
256
+ const verification = readJsonArtifact(rootDir, run.runId, GATE_FILES.verification).value;
257
+ const findings = readJsonArtifact(rootDir, run.runId, GATE_FILES.review).value;
258
+ const goalContract = readJsonArtifact(rootDir, run.runId, GATE_FILES.goal).value;
259
+ const expected = computeJudgeVerdict({
260
+ goalContract,
261
+ verificationEvidence: verificationForJudge(verification),
262
+ findingLedger: findings,
263
+ activeIteration: run.iteration,
264
+ maxIterations: 3
265
+ });
266
+ if (value.verdict !== expected.verdict) {
267
+ throw gateError(`Judge verdict is unsupported: expected ${expected.verdict}, received ${value.verdict}`);
268
+ }
269
+ const artifacts = { verdict: descriptor(rootDir, filePath) };
270
+ if (expected.verdict === 'PASS') {
271
+ return transitionRun(rootDir, run.runId, RUN_STATES.JUDGED_PASS, { gate, artifacts });
272
+ }
273
+ if (expected.verdict === 'ESCALATE') {
274
+ return transitionRun(rootDir, run.runId, RUN_STATES.ESCALATED, {
275
+ gate,
276
+ artifacts,
277
+ reason: expected.reason
278
+ });
279
+ }
280
+ return transitionRun(rootDir, run.runId, RUN_STATES.GOAL_FROZEN, {
281
+ gate,
282
+ artifacts,
283
+ reason: expected.reason,
284
+ incrementIteration: true
285
+ });
286
+ }
287
+
288
+ assertArtifactCurrent(rootDir, run, 'goalContract');
289
+ assertArtifactCurrent(rootDir, run, 'diff');
290
+ assertArtifactCurrent(rootDir, run, 'verification');
291
+ assertArtifactCurrent(rootDir, run, 'findings');
292
+ assertArtifactCurrent(rootDir, run, 'verdict');
293
+ const { filePath, value } = readJsonArtifact(rootDir, run.runId, GATE_FILES.delivery);
294
+ requireRunMetadata(value, run, 'delivery');
295
+ const deliveryErrors = [];
296
+ if (!String(value.destination || '').trim()) deliveryErrors.push('destination is required');
297
+ if (!String(value.summary || '').trim()) deliveryErrors.push('summary is required');
298
+ if (deliveryErrors.length) throw gateError('Delivery gate failed', deliveryErrors);
299
+ return transitionRun(rootDir, run.runId, RUN_STATES.DELIVERED, {
300
+ gate,
301
+ artifacts: { delivery: descriptor(rootDir, filePath) }
302
+ });
303
+ }
304
+
305
+ module.exports = {
306
+ GATE_FILES,
307
+ artifactPath,
308
+ hashContent,
309
+ hashFile,
310
+ assertArtifactCurrent,
311
+ validateGoalContract,
312
+ validateVerificationBundle,
313
+ validateVerdictDocument,
314
+ applyGate
315
+ };
@@ -442,7 +442,11 @@ function detectGrokRuntime(env = process.env, fsApi = fs) {
442
442
  const grokBinCandidates = [
443
443
  env.GROK_BIN,
444
444
  path.join(grokHome, 'bin', 'grok'),
445
- path.join(grokHome, 'bin', 'agent')
445
+ path.join(grokHome, 'bin', 'grok.exe'),
446
+ path.join(grokHome, 'bin', 'grok.cmd'),
447
+ path.join(grokHome, 'bin', 'agent'),
448
+ path.join(grokHome, 'bin', 'agent.exe'),
449
+ path.join(grokHome, 'bin', 'agent.cmd')
446
450
  ].filter(Boolean);
447
451
 
448
452
  const grokBin = grokBinCandidates.find((candidate) => {