ai-engineering-loop 1.13.0 → 1.15.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 (117) hide show
  1. package/.agents/skills/ai-engineering-loop/SKILL.md +62 -0
  2. package/.agents/skills/ai-engineering-loop/references/loop-commands.md +20 -0
  3. package/.agents/skills/ai-engineering-loop/references/loop-deliver.md +8 -0
  4. package/.agents/skills/ai-engineering-loop/references/loop-goal.md +10 -0
  5. package/.agents/skills/ai-engineering-loop/references/loop-hosts.md +44 -0
  6. package/.agents/skills/ai-engineering-loop/references/loop-maker.md +8 -0
  7. package/.agents/skills/ai-engineering-loop/references/loop-review.md +18 -0
  8. package/.agents/skills/ai-engineering-loop/references/loop-risky.md +9 -0
  9. package/.agents/skills/ai-engineering-loop/references/loop-verify.md +20 -0
  10. package/.claude/skills/ai-engineering-loop/SKILL.md +28 -47
  11. package/.claude/skills/ai-engineering-loop/references/loop-commands.md +20 -0
  12. package/.claude/skills/ai-engineering-loop/references/loop-deliver.md +8 -0
  13. package/.claude/skills/ai-engineering-loop/references/loop-goal.md +10 -0
  14. package/.claude/skills/ai-engineering-loop/references/loop-hosts.md +44 -0
  15. package/.claude/skills/ai-engineering-loop/references/loop-maker.md +8 -0
  16. package/.claude/skills/ai-engineering-loop/references/loop-review.md +18 -0
  17. package/.claude/skills/ai-engineering-loop/references/loop-risky.md +9 -0
  18. package/.claude/skills/ai-engineering-loop/references/loop-verify.md +20 -0
  19. package/CHANGELOG.md +116 -0
  20. package/README.md +90 -5
  21. package/README.npm.md +6 -2
  22. package/THIRD_PARTY_NOTICES.md +29 -0
  23. package/adapters/dot/README.md +1 -1
  24. package/adapters/dot/skills/dot-dev-skill-router/SKILL.md +24 -16
  25. package/adapters/project-onboarding/SKILL.md +27 -0
  26. package/adapters/project-onboarding/references/output.md +29 -0
  27. package/adapters/quality/skills/ael-code-simplifier/SKILL.md +43 -0
  28. package/adapters/quality/skills/ael-receiving-code-review/SKILL.md +37 -0
  29. package/bin/ai-engineering-loop.js +1270 -75
  30. package/core/grill-policy.md +1 -1
  31. package/core/root-cause-analysis.md +6 -0
  32. package/core/runtime-safety.md +31 -3
  33. package/evals/cases/21-tier-t0-docs.json +34 -0
  34. package/evals/cases/22-tier-t1-small-pass.json +30 -0
  35. package/evals/cases/23-tier-t1-blocker.json +26 -0
  36. package/evals/cases/24-tier-t1-auth-escalates.json +30 -0
  37. package/lib/auto-update.js +488 -0
  38. package/lib/budget.js +31 -1
  39. package/lib/cli-args.js +95 -0
  40. package/lib/docs.js +91 -0
  41. package/lib/doctor.js +9 -14
  42. package/lib/gates.js +114 -1
  43. package/lib/host-skill-build.js +121 -0
  44. package/lib/hosts/agent-formats.js +135 -0
  45. package/lib/hosts/commands.js +126 -0
  46. package/lib/hosts/detect.js +56 -0
  47. package/lib/hosts/doctor.js +76 -0
  48. package/lib/hosts/redetect.js +60 -0
  49. package/lib/hosts/registry.js +271 -0
  50. package/lib/hosts/table.js +35 -0
  51. package/lib/migrations.js +84 -0
  52. package/lib/project-registry.js +148 -0
  53. package/lib/run-abandon.js +116 -0
  54. package/lib/run-state.js +6 -3
  55. package/lib/sync-hosts.js +456 -130
  56. package/lib/tier.js +134 -0
  57. package/lib/update-manager.js +17 -1
  58. package/lib/update-notice.js +192 -0
  59. package/lib/user-state.js +80 -0
  60. package/lib/verification-recorder.js +44 -0
  61. package/migrations/README.md +21 -0
  62. package/package.json +8 -4
  63. package/.agents/devil-advocate.md +0 -79
  64. package/.agents/judge.md +0 -58
  65. package/.agents/workflows/ai-engineering-loop.md +0 -24
  66. package/.claude/commands/ai-engineering-loop.md +0 -11
  67. package/.gemini/skills/ai-engineering-loop/SKILL.md +0 -74
  68. package/.gemini/skills/animate/RECIPES.md +0 -324
  69. package/.gemini/skills/animate/SKILL.md +0 -207
  70. package/.gemini/skills/animate-expo/RECIPES.md +0 -385
  71. package/.gemini/skills/animate-expo/SKILL.md +0 -263
  72. package/.gemini/skills/animation-vocabulary/SKILL.md +0 -181
  73. package/.gemini/skills/apple-design/SKILL.md +0 -290
  74. package/.gemini/skills/ask-sonner/API.md +0 -64
  75. package/.gemini/skills/ask-sonner/SKILL.md +0 -88
  76. package/.gemini/skills/backend-development/SKILL.md +0 -272
  77. package/.gemini/skills/backend-development/references/api-design-guidelines.md +0 -95
  78. package/.gemini/skills/backend-development/references/query-and-database-best-practices.md +0 -53
  79. package/.gemini/skills/backend-development/references/security-checklist.md +0 -60
  80. package/.gemini/skills/emil-design-eng/SKILL.md +0 -674
  81. package/.gemini/skills/find-animation-opportunities/SKILL.md +0 -140
  82. package/.gemini/skills/improve-animations/AUDIT.md +0 -115
  83. package/.gemini/skills/improve-animations/PLAN-TEMPLATE.md +0 -73
  84. package/.gemini/skills/improve-animations/SKILL.md +0 -109
  85. package/.gemini/skills/mobile-native/SKILL.md +0 -311
  86. package/.gemini/skills/pick-ui-library/SKILL.md +0 -85
  87. package/.gemini/skills/prototype/PICKER.md +0 -197
  88. package/.gemini/skills/prototype/SKILL.md +0 -98
  89. package/.gemini/skills/review-animations/SKILL.md +0 -120
  90. package/.gemini/skills/review-animations/STANDARDS.md +0 -187
  91. package/.gemini/skills/write-swift/SKILL.md +0 -396
  92. package/.grok/commands/ai-engineering-loop.md +0 -11
  93. package/.grok/skills/ai-engineering-loop/SKILL.md +0 -94
  94. package/.grok/skills/animate/RECIPES.md +0 -324
  95. package/.grok/skills/animate/SKILL.md +0 -207
  96. package/.grok/skills/animate-expo/RECIPES.md +0 -385
  97. package/.grok/skills/animate-expo/SKILL.md +0 -263
  98. package/.grok/skills/animation-vocabulary/SKILL.md +0 -181
  99. package/.grok/skills/apple-design/SKILL.md +0 -290
  100. package/.grok/skills/ask-sonner/API.md +0 -64
  101. package/.grok/skills/ask-sonner/SKILL.md +0 -88
  102. package/.grok/skills/backend-development/SKILL.md +0 -272
  103. package/.grok/skills/backend-development/references/api-design-guidelines.md +0 -95
  104. package/.grok/skills/backend-development/references/query-and-database-best-practices.md +0 -53
  105. package/.grok/skills/backend-development/references/security-checklist.md +0 -60
  106. package/.grok/skills/emil-design-eng/SKILL.md +0 -674
  107. package/.grok/skills/find-animation-opportunities/SKILL.md +0 -140
  108. package/.grok/skills/improve-animations/AUDIT.md +0 -115
  109. package/.grok/skills/improve-animations/PLAN-TEMPLATE.md +0 -73
  110. package/.grok/skills/improve-animations/SKILL.md +0 -109
  111. package/.grok/skills/mobile-native/SKILL.md +0 -311
  112. package/.grok/skills/pick-ui-library/SKILL.md +0 -85
  113. package/.grok/skills/prototype/PICKER.md +0 -197
  114. package/.grok/skills/prototype/SKILL.md +0 -98
  115. package/.grok/skills/review-animations/SKILL.md +0 -120
  116. package/.grok/skills/review-animations/STANDARDS.md +0 -187
  117. package/.grok/skills/write-swift/SKILL.md +0 -396
package/lib/docs.js ADDED
@@ -0,0 +1,91 @@
1
+ 'use strict';
2
+
3
+ // Read-only access to packaged specs. Host skills cite `ai-engineering-loop docs <name>`
4
+ // instead of repository-relative paths such as `core/grill-policy.md`, because
5
+ // target repositories never contain the package's core/ or policies/ (issue #27).
6
+
7
+ const fs = require('fs');
8
+ const path = require('path');
9
+
10
+ // Loop stage references are generated host-neutral copies (issue #35).
11
+ const DOC_ROOTS = Object.freeze(['core', 'policies', 'profiles', 'agents', 'adapters', '.claude/skills/ai-engineering-loop/references']);
12
+
13
+ function packageRoot() {
14
+ return path.join(__dirname, '..');
15
+ }
16
+
17
+ function walk(dir, out) {
18
+ let entries;
19
+ try {
20
+ entries = fs.readdirSync(dir, { withFileTypes: true });
21
+ } catch {
22
+ return;
23
+ }
24
+ for (const entry of entries) {
25
+ const abs = path.join(dir, entry.name);
26
+ if (entry.isDirectory()) walk(abs, out);
27
+ else if (entry.isFile() && entry.name.endsWith('.md')) out.push(abs);
28
+ }
29
+ }
30
+
31
+ function listDocs(root = packageRoot()) {
32
+ const files = [];
33
+ for (const dir of DOC_ROOTS) walk(path.join(root, dir), files);
34
+ const counts = new Map();
35
+ const docs = files.map((abs) => {
36
+ const rel = path.relative(root, abs).split(path.sep).join('/');
37
+ const base = path.basename(rel, '.md');
38
+ counts.set(base, (counts.get(base) || 0) + 1);
39
+ return { rel, base, bytes: fs.statSync(abs).size };
40
+ });
41
+ return docs
42
+ .map((doc) => ({ ...doc, name: counts.get(doc.base) === 1 && doc.base !== 'SKILL' ? doc.base : doc.rel.replace(/\.md$/, '') }))
43
+ .sort((a, b) => a.name.localeCompare(b.name));
44
+ }
45
+
46
+ function resolveDoc(name, root = packageRoot()) {
47
+ const wanted = String(name || '').replace(/\.md$/, '').replace(/\\/g, '/');
48
+ if (!wanted || wanted.includes('..')) return null;
49
+ return listDocs(root).find((doc) => doc.name === wanted || doc.rel.replace(/\.md$/, '') === wanted) || null;
50
+ }
51
+
52
+ function extractSection(markdown, heading) {
53
+ const lines = String(markdown).split('\n');
54
+ const needle = String(heading).trim().toLowerCase();
55
+ const start = lines.findIndex((line) => /^#{1,6}\s/.test(line) && line.replace(/^#{1,6}\s+/, '').trim().toLowerCase().includes(needle));
56
+ if (start === -1) return null;
57
+ const level = lines[start].match(/^#+/)[0].length;
58
+ const out = [lines[start]];
59
+ for (let index = start + 1; index < lines.length; index += 1) {
60
+ const match = lines[index].match(/^(#{1,6})\s/);
61
+ if (match && match[1].length <= level) break;
62
+ out.push(lines[index]);
63
+ }
64
+ return out.join('\n').replace(/\s+$/, '');
65
+ }
66
+
67
+ function readDoc(name, { section = null, root = packageRoot() } = {}) {
68
+ const doc = resolveDoc(name, root);
69
+ if (!doc) {
70
+ const err = new Error(`Unknown doc "${name}". Run "ai-engineering-loop docs list".`);
71
+ err.code = 'UNKNOWN_DOC';
72
+ throw err;
73
+ }
74
+ const text = fs.readFileSync(path.join(root, doc.rel), 'utf8').replace(/\r\n?/g, '\n');
75
+ if (!section) return { ...doc, text };
76
+ const part = extractSection(text, section);
77
+ if (part == null) {
78
+ const err = new Error(`Section "${section}" not found in ${doc.rel}`);
79
+ err.code = 'UNKNOWN_SECTION';
80
+ throw err;
81
+ }
82
+ return { ...doc, section, text: part };
83
+ }
84
+
85
+ module.exports = {
86
+ DOC_ROOTS,
87
+ listDocs,
88
+ resolveDoc,
89
+ readDoc,
90
+ extractSection
91
+ };
package/lib/doctor.js CHANGED
@@ -8,31 +8,26 @@ const { listRecipes, loadRecipe, validateRecipe } = require('./recipe.js');
8
8
 
9
9
  const REQUIRED_HOST_ASSETS = [
10
10
  '.claude/skills/ai-engineering-loop/SKILL.md',
11
+ 'adapters/project-onboarding/SKILL.md',
12
+ 'adapters/quality/skills/ael-code-simplifier/SKILL.md',
13
+ 'adapters/quality/skills/ael-receiving-code-review/SKILL.md',
14
+ '.claude/skills/ai-engineering-loop/references/loop-review.md',
11
15
  '.claude/skills/backend-development/SKILL.md',
12
16
  '.claude/skills/emil-design-eng/SKILL.md',
13
17
  '.claude/skills/animate/SKILL.md',
14
18
  '.claude/skills/review-animations/SKILL.md',
15
19
  '.claude/agents/devil-advocate.md',
16
20
  '.claude/agents/judge.md',
17
- '.grok/skills/ai-engineering-loop/SKILL.md',
18
- '.grok/skills/backend-development/SKILL.md',
19
- '.grok/skills/emil-design-eng/SKILL.md',
20
- '.grok/skills/animate/SKILL.md',
21
- '.grok/skills/review-animations/SKILL.md',
22
21
  '.grok/agents/devil-advocate.md',
23
22
  '.grok/agents/judge.md',
24
- '.gemini/skills/ai-engineering-loop/SKILL.md',
25
- '.gemini/skills/backend-development/SKILL.md',
26
- '.gemini/skills/emil-design-eng/SKILL.md',
27
- '.gemini/skills/animate/SKILL.md',
28
- '.gemini/skills/review-animations/SKILL.md',
29
- '.agents/workflows/ai-engineering-loop.md',
23
+ '.agents/skills/ai-engineering-loop/SKILL.md',
24
+ '.agents/skills/ai-engineering-loop/references/loop-hosts.md',
30
25
  '.agents/skills/backend-development/SKILL.md',
31
26
  '.agents/skills/emil-design-eng/SKILL.md',
32
27
  '.agents/skills/animate/SKILL.md',
33
28
  '.agents/skills/review-animations/SKILL.md',
34
- '.agents/devil-advocate.md',
35
- '.agents/judge.md'
29
+ 'agents/shared/devil-advocate.body.md',
30
+ 'agents/shared/judge.body.md'
36
31
  ];
37
32
 
38
33
  const REQUIRED_SCHEMAS = [
@@ -108,7 +103,7 @@ function runDoctor(rootDir = path.join(__dirname, '..')) {
108
103
 
109
104
  try {
110
105
  const fixtures = loadEvaluationCases(path.join(rootDir, 'evals', 'cases'));
111
- checks.push(check('evaluation-catalog', fixtures.length === 20, `${fixtures.length} valid cases; required 20`));
106
+ checks.push(check('evaluation-catalog', fixtures.length === 24, `${fixtures.length} valid cases; required 24`));
112
107
  } catch (cause) {
113
108
  checks.push(check('evaluation-catalog', false, cause.message));
114
109
  }
package/lib/gates.js CHANGED
@@ -21,8 +21,14 @@ const {
21
21
  assertModeAllowed
22
22
  } = require('./runtime-policy.js');
23
23
  const {
24
+ MODEL_TIERS,
25
+ assessRunEscalation,
24
26
  enforceVerdictTier
25
27
  } = require('./escalation.js');
28
+ const { raiseTierFromDiff } = require('./tier.js');
29
+ const { readyForDa } = require('./claimed-vs-reality.js');
30
+
31
+ const CLAIMED_VS_REALITY_PATH = '.ai-engineering-loop/tasks/claimed-vs-reality.md';
26
32
 
27
33
  const GATE_FILES = Object.freeze({
28
34
  goal: 'goal-contract.json',
@@ -181,6 +187,104 @@ function resolveRun(rootDir, runId) {
181
187
  return current;
182
188
  }
183
189
 
190
+ function tierOf(run) {
191
+ return run?.tier?.current || null;
192
+ }
193
+
194
+ function claimedVsRealityReady(rootDir) {
195
+ try {
196
+ return readyForDa(fs.readFileSync(path.join(rootDir, CLAIMED_VS_REALITY_PATH), 'utf8'));
197
+ } catch {
198
+ return false;
199
+ }
200
+ }
201
+
202
+ // T0 has no Devil's Advocate. The CLI writes an explicit empty, diff-bound
203
+ // ledger so the review and Judge gates stay in place, but only after
204
+ // claimed-vs-reality has a Reality cell for every Claimed row.
205
+ function writeT0FindingLedger(rootDir, run) {
206
+ const filePath = artifactPath(rootDir, run.runId, GATE_FILES.review);
207
+ if (fs.existsSync(filePath)) return false;
208
+ if (!claimedVsRealityReady(rootDir)) {
209
+ throw gateError('T0 review needs a completed claimed-vs-reality file', [
210
+ `Fill every Claimed and Reality cell in ${CLAIMED_VS_REALITY_PATH} (scaffold: context claimed-vs-reality)`
211
+ ]);
212
+ }
213
+ fs.writeFileSync(filePath, `${JSON.stringify({
214
+ schemaVersion: 1,
215
+ runId: run.runId,
216
+ diffHash: run.artifacts.diff.sha256,
217
+ reviewer: 'none (tier T0: no Devil\'s Advocate)',
218
+ tier: 'T0',
219
+ findings: []
220
+ }, null, 2)}\n`, { mode: 0o600 });
221
+ return true;
222
+ }
223
+
224
+ // Whether the Judge subagent can be replaced by the deterministic verdict.
225
+ // Never for T2 or tierless (legacy) runs. T0/T1 qualify only with zero
226
+ // BLOCKER/HIGH findings of any validity, a clean escalation assessment,
227
+ // green diff-bound verification, a ready claimed-vs-reality file, and an
228
+ // iteration under the cap.
229
+ function judgeRequirement(rootDir, run) {
230
+ const tier = tierOf(run);
231
+ const reasons = [];
232
+ if (!tier) return { required: true, tier: null, reasons: ['NO_TIER (legacy run): use the Judge subagent'] };
233
+ if (tier === 'T2') return { required: true, tier, reasons: ['TIER_T2: Judge on STRONG_MODEL is mandatory'] };
234
+ let findings = [];
235
+ try {
236
+ findings = readJsonArtifact(rootDir, run.runId, GATE_FILES.review).value.findings || [];
237
+ } catch {
238
+ reasons.push('FINDINGS_MISSING');
239
+ }
240
+ const serious = findings.filter((f) => f && (f.severity === 'BLOCKER' || f.severity === 'HIGH'));
241
+ if (serious.length) reasons.push(`BLOCKER_OR_HIGH_FINDINGS: ${serious.map((f) => f.id).join(', ')}`);
242
+ if (run.iteration >= 3) reasons.push('ITERATION_CEILING');
243
+ let escalation = null;
244
+ try {
245
+ escalation = assessRunEscalation(rootDir, { runId: run.runId });
246
+ if (escalation.requiredTier !== MODEL_TIERS.CHEAP_MODEL) {
247
+ reasons.push(`ESCALATION_${escalation.requiredTier}: ${escalation.reasons.map((r) => r.code).join(', ')}`);
248
+ }
249
+ } catch (cause) {
250
+ reasons.push(`ESCALATION_UNAVAILABLE: ${cause.message}`);
251
+ }
252
+ if (!claimedVsRealityReady(rootDir)) reasons.push('CLAIMED_VS_REALITY_INCOMPLETE');
253
+ return { required: reasons.length > 0, tier, reasons };
254
+ }
255
+
256
+ function writeDeterministicVerdictIfEligible(rootDir, run) {
257
+ const filePath = artifactPath(rootDir, run.runId, GATE_FILES.judge);
258
+ if (fs.existsSync(filePath)) return false;
259
+ const tier = tierOf(run);
260
+ if (!tier) return false;
261
+ const requirement = judgeRequirement(rootDir, run);
262
+ if (requirement.required) {
263
+ throw gateError(`Judge subagent required for tier ${tier}; write ${GATE_FILES.judge} from its verdict`, requirement.reasons);
264
+ }
265
+ const verification = readJsonArtifact(rootDir, run.runId, GATE_FILES.verification).value;
266
+ const findings = readJsonArtifact(rootDir, run.runId, GATE_FILES.review).value;
267
+ const goalContract = readJsonArtifact(rootDir, run.runId, GATE_FILES.goal).value;
268
+ const expected = computeJudgeVerdict({
269
+ goalContract,
270
+ verificationEvidence: verificationForJudge(verification),
271
+ findingLedger: findings,
272
+ activeIteration: run.iteration,
273
+ maxIterations: 3
274
+ });
275
+ fs.writeFileSync(filePath, `${JSON.stringify({
276
+ schemaVersion: 1,
277
+ runId: run.runId,
278
+ verdict: expected.verdict,
279
+ reason: expected.reason,
280
+ action: expected.action,
281
+ modelTier: MODEL_TIERS.CHEAP_MODEL,
282
+ decidedBy: 'deterministic-gate',
283
+ tier
284
+ }, null, 2)}\n`, { mode: 0o600 });
285
+ return true;
286
+ }
287
+
184
288
  function applyGate(rootDir, gate, { runId, transitionOptions = {} } = {}) {
185
289
  if (!Object.hasOwn(GATE_FILES, gate)) {
186
290
  throw gateError(`Unknown gate: ${gate}. Use ${Object.keys(GATE_FILES).join('|')}`);
@@ -254,9 +358,11 @@ function applyGate(rootDir, gate, { runId, transitionOptions = {} } = {}) {
254
358
  if (sandboxErrors.length) throw gateError('Unattended Maker sandbox evidence failed', sandboxErrors);
255
359
  artifacts.sandboxEvidence = descriptor(rootDir, sandboxFile);
256
360
  }
361
+ const raisedTier = raiseTierFromDiff(run.tier, { task: run.task, diff });
257
362
  return transitionRun(rootDir, run.runId, RUN_STATES.MAKER_COMPLETE, {
258
363
  gate,
259
- artifacts
364
+ artifacts,
365
+ ...(raisedTier ? { statePatch: { tier: raisedTier }, historyMetadata: { tier: raisedTier.current } } : {})
260
366
  });
261
367
  }
262
368
 
@@ -279,6 +385,7 @@ function applyGate(rootDir, gate, { runId, transitionOptions = {} } = {}) {
279
385
  assertArtifactCurrent(rootDir, run, 'goalContract');
280
386
  assertArtifactCurrent(rootDir, run, 'diff');
281
387
  assertArtifactCurrent(rootDir, run, 'verification');
388
+ if (tierOf(run) === 'T0') writeT0FindingLedger(rootDir, run);
282
389
  const { filePath, value } = readJsonArtifact(rootDir, run.runId, GATE_FILES.review);
283
390
  requireRunMetadata(value, run, 'Finding Ledger');
284
391
  if (value.diffHash !== run.artifacts.diff?.sha256) {
@@ -297,9 +404,14 @@ function applyGate(rootDir, gate, { runId, transitionOptions = {} } = {}) {
297
404
  assertArtifactCurrent(rootDir, run, 'diff');
298
405
  assertArtifactCurrent(rootDir, run, 'verification');
299
406
  assertArtifactCurrent(rootDir, run, 'findings');
407
+ writeDeterministicVerdictIfEligible(rootDir, run);
300
408
  const { filePath, value } = readJsonArtifact(rootDir, run.runId, GATE_FILES.judge);
301
409
  const verdictCheck = validateVerdictDocument(value, run);
302
410
  if (!verdictCheck.valid) throw gateError('Judge gate failed', verdictCheck.errors);
411
+ if (tierOf(run) === 'T2' && value.verdict === 'PASS'
412
+ && ![MODEL_TIERS.STRONG_MODEL, MODEL_TIERS.HUMAN].includes(value.modelTier)) {
413
+ throw gateError('T2 Judge PASS requires modelTier STRONG_MODEL or HUMAN', ['TIER_T2_STRONG_JUDGE']);
414
+ }
303
415
  try {
304
416
  enforceVerdictTier(rootDir, run, value);
305
417
  } catch (cause) {
@@ -366,5 +478,6 @@ module.exports = {
366
478
  validateGoalContract,
367
479
  validateVerificationBundle,
368
480
  validateVerdictDocument,
481
+ judgeRequirement,
369
482
  applyGate
370
483
  };
@@ -0,0 +1,121 @@
1
+ 'use strict';
2
+
3
+ // Host skill build (issues #35, #48). One template plus one overlay produces a
4
+ // single host-neutral ai-engineering-loop skill and its references/. The same
5
+ // bytes are written to every output directory, so a host that reads several
6
+ // skill folders (Grok, Cursor, OpenCode, Amp, Augment) only ever sees identical
7
+ // copies. Host-specific spawn rules live in references/loop-hosts.md. The
8
+ // generated files are committed (they ship in the npm package); a drift test
9
+ // fails when a generated file is edited by hand instead of skill-src/.
10
+
11
+ const fs = require('fs');
12
+ const path = require('path');
13
+
14
+ const SOURCE_DIR = 'skill-src/ai-engineering-loop';
15
+ const SKILL_CHAR_LIMIT = 4000;
16
+ const GENERATED_NOTE = '<!-- Generated from skill-src/ by npm run build:skills; do not edit. -->';
17
+
18
+ function readText(file) {
19
+ return fs.readFileSync(file, 'utf8').replace(/\r\n?/g, '\n');
20
+ }
21
+
22
+ // Overlay format: `@@ key: value` (one line) or `@@ key` followed by a block
23
+ // that runs until the next `@@` line.
24
+ function parseOverlay(text) {
25
+ const values = {};
26
+ let current = null;
27
+ for (const line of text.split('\n')) {
28
+ const header = line.match(/^@@ ([a-zA-Z]+)(?::\s?(.*))?$/);
29
+ if (header) {
30
+ current = null;
31
+ if (header[2] !== undefined) values[header[1]] = header[2];
32
+ else {
33
+ current = header[1];
34
+ values[current] = [];
35
+ }
36
+ continue;
37
+ }
38
+ if (current) values[current].push(line);
39
+ }
40
+ for (const [key, value] of Object.entries(values)) {
41
+ if (Array.isArray(value)) values[key] = value.join('\n').replace(/\s+$/, '');
42
+ }
43
+ return values;
44
+ }
45
+
46
+ function render(template, values, label) {
47
+ return template.replace(/\{\{([a-zA-Z]+)\}\}/g, (_, key) => {
48
+ if (!Object.hasOwn(values, key)) throw new Error(`${label}: missing overlay value "${key}"`);
49
+ return values[key];
50
+ });
51
+ }
52
+
53
+ function insertNote(content) {
54
+ const match = content.match(/^---\n[\s\S]*?\n---\n/);
55
+ if (!match) return `${GENERATED_NOTE}\n${content}`;
56
+ return `${match[0]}${GENERATED_NOTE}\n${content.slice(match[0].length)}`;
57
+ }
58
+
59
+ // Returns [{ path, content }] relative to the package root.
60
+ function buildHostSkills(root = path.join(__dirname, '..')) {
61
+ const src = path.join(root, SOURCE_DIR);
62
+ const template = readText(path.join(src, 'SKILL.template.md'));
63
+ const refDir = path.join(src, 'references');
64
+ const references = fs.readdirSync(refDir).filter((f) => f.endsWith('.md')).sort()
65
+ .map((name) => ({ name, content: readText(path.join(refDir, name)) }));
66
+ const overlay = parseOverlay(readText(path.join(src, 'overlay.md')));
67
+ const dirs = String(overlay.outputs || '').split(',').map((d) => d.trim()).filter(Boolean);
68
+ if (!dirs.length) throw new Error('overlay needs "@@ outputs: <dir>[, <dir>]"');
69
+ const body = insertNote(render(template, overlay, 'overlay').replace(/\n{3,}/g, '\n\n').replace(/\s*$/, '\n'));
70
+ const outputs = [];
71
+ for (const dir of dirs) {
72
+ outputs.push({ path: path.posix.join(dir, 'SKILL.md'), content: body, kind: 'skill' });
73
+ for (const ref of references) {
74
+ outputs.push({ path: path.posix.join(dir, 'references', ref.name), content: ref.content, kind: 'reference' });
75
+ }
76
+ }
77
+ return outputs;
78
+ }
79
+
80
+ function checkHostSkills(root = path.join(__dirname, '..')) {
81
+ const drift = [];
82
+ for (const out of buildHostSkills(root)) {
83
+ let actual = null;
84
+ try {
85
+ actual = readText(path.join(root, out.path));
86
+ } catch {
87
+ // Missing file counts as drift.
88
+ }
89
+ if (actual !== out.content) drift.push(out.path);
90
+ }
91
+ return drift;
92
+ }
93
+
94
+ function writeHostSkills(root = path.join(__dirname, '..')) {
95
+ const written = [];
96
+ for (const out of buildHostSkills(root)) {
97
+ const abs = path.join(root, out.path);
98
+ fs.mkdirSync(path.dirname(abs), { recursive: true });
99
+ let actual = null;
100
+ try {
101
+ actual = readText(abs);
102
+ } catch {
103
+ // New file.
104
+ }
105
+ if (actual !== out.content) {
106
+ fs.writeFileSync(abs, out.content);
107
+ written.push(out.path);
108
+ }
109
+ }
110
+ return written;
111
+ }
112
+
113
+ module.exports = {
114
+ SOURCE_DIR,
115
+ SKILL_CHAR_LIMIT,
116
+ GENERATED_NOTE,
117
+ parseOverlay,
118
+ buildHostSkills,
119
+ checkHostSkills,
120
+ writeHostSkills
121
+ };
@@ -0,0 +1,135 @@
1
+ 'use strict';
2
+
3
+ // Reviewer subagents (devil-advocate, judge) rendered per host format (#48+).
4
+ // One body (agents/shared/<name>.body.md) and one description per agent; each
5
+ // formatter only adds the host's frontmatter or wrapper, so the reviewer
6
+ // contract stays identical everywhere.
7
+
8
+ const fs = require('fs');
9
+ const path = require('path');
10
+
11
+ const AGENTS = Object.freeze(['devil-advocate', 'judge']);
12
+
13
+ function readText(file) {
14
+ return fs.readFileSync(file, 'utf8').replace(/\r\n?/g, '\n');
15
+ }
16
+
17
+ // Description comes from the canonical Claude agent file so it is written once.
18
+ function agentSpec(root, name) {
19
+ if (!AGENTS.includes(name)) throw new Error(`Unknown reviewer agent "${name}"`);
20
+ const body = readText(path.join(root, 'agents', 'shared', `${name}.body.md`)).replace(/\s+$/, '\n');
21
+ const claude = readText(path.join(root, '.claude', 'agents', `${name}.md`));
22
+ const line = claude.split('\n').find((l) => l.startsWith('description:'));
23
+ if (!line) throw new Error(`.claude/agents/${name}.md has no description`);
24
+ return { name, description: line.slice('description:'.length).trim(), body };
25
+ }
26
+
27
+ function frontmatter(fields) {
28
+ const lines = Object.entries(fields).map(([key, value]) => {
29
+ if (Array.isArray(value)) return `${key}:\n${value.map((v) => ` - ${v}`).join('\n')}`;
30
+ return `${key}: ${value}`;
31
+ });
32
+ return `---\n${lines.join('\n')}\n---\n\n`;
33
+ }
34
+
35
+ // TOML multi-line literal string: no escapes, so the body must not contain '''.
36
+ function tomlLiteral(text) {
37
+ if (text.includes("'''")) throw new Error("agent body must not contain ''' for codex-toml");
38
+ return `'''\n${text}'''`;
39
+ }
40
+
41
+ function tomlString(text) {
42
+ return JSON.stringify(text);
43
+ }
44
+
45
+ const FORMATS = Object.freeze({
46
+ // Canonical files committed in the repo (their frontmatter is host-tuned).
47
+ // https://code.claude.com/docs/en/sub-agents
48
+ 'claude-md': { file: (name) => `${name}.md`, src: (name) => `.claude/agents/${name}.md` },
49
+ // https://docs.x.ai/build/features/subagents
50
+ 'grok-md': { file: (name) => `${name}.md`, src: (name) => `.grok/agents/${name}.md` },
51
+ // https://developers.openai.com/codex/subagents: name, description,
52
+ // developer_instructions required; reviewers run read-only.
53
+ 'codex-toml': {
54
+ file: (name) => `${name}.toml`,
55
+ render: (spec) => [
56
+ `name = ${tomlString(spec.name)}`,
57
+ `description = ${tomlString(spec.description)}`,
58
+ 'sandbox_mode = "read-only"',
59
+ `developer_instructions = ${tomlLiteral(spec.body)}`,
60
+ ''
61
+ ].join('\n')
62
+ },
63
+ // https://geminicli.com/docs/core/subagents/: tools omitted = inherit.
64
+ 'gemini-md': {
65
+ file: (name) => `${name}.md`,
66
+ render: (spec) => frontmatter({ name: spec.name, description: spec.description, kind: 'local' }) + spec.body
67
+ },
68
+ // https://cursor.com/docs/subagents
69
+ 'cursor-md': {
70
+ file: (name) => `${name}.md`,
71
+ render: (spec) => frontmatter({ name: spec.name, description: spec.description, model: 'inherit', readonly: true }) + spec.body
72
+ },
73
+ // https://opencode.ai/docs/agents/: file name is the agent name; reviewers never edit.
74
+ 'opencode-md': {
75
+ file: (name) => `${name}.md`,
76
+ render: (spec) => `---\ndescription: ${spec.description}\nmode: subagent\npermission:\n edit: deny\n---\n\n${spec.body}`
77
+ },
78
+ // https://docs.factory.ai/harness/subagents: Task subagent_type targets.
79
+ 'factory-md': {
80
+ file: (name) => `${name}.md`,
81
+ render: (spec) => frontmatter({ name: spec.name, description: spec.description, model: 'inherit', tools: 'read-only' }) + spec.body
82
+ },
83
+ // https://docs.augmentcode.com/cli/subagents: tools omitted = all tools.
84
+ 'augment-md': {
85
+ file: (name) => `${name}.md`,
86
+ render: (spec) => frontmatter({ name: spec.name, description: spec.description }) + spec.body
87
+ },
88
+ // Qwen Code docs (qwenlm.github.io/qwen-code-docs, Features > Subagents): approvalMode plan = no edits.
89
+ 'qwen-md': {
90
+ file: (name) => `${name}.md`,
91
+ render: (spec) => frontmatter({ name: spec.name, description: spec.description, model: 'inherit', approvalMode: 'plan' }) + spec.body
92
+ },
93
+ // https://kiro.dev/docs/cli/custom-agents/configuration-reference/ (Markdown agents, CLI V3 / IDE 1.0).
94
+ 'kiro-md': {
95
+ file: (name) => `${name}.md`,
96
+ render: (spec) => frontmatter({ name: spec.name, description: spec.description, tools: ['read'] }) + spec.body
97
+ },
98
+ // https://junie.jetbrains.com/docs/junie-cli-subagents.html (tool names from the documented examples).
99
+ 'junie-md': {
100
+ file: (name) => `${name}.md`,
101
+ render: (spec) => frontmatter({ name: spec.name, description: spec.description, tools: ['Read', 'Grep'] }) + spec.body
102
+ },
103
+ // https://docs.github.com/en/copilot/reference/custom-agents-configuration
104
+ 'copilot-agent-md': {
105
+ file: (name) => `${name}.agent.md`,
106
+ render: (spec) => frontmatter({ name: spec.name, description: spec.description }) + spec.body
107
+ },
108
+ // https://antigravity.google/docs/subagents (tool names from the documented example only:
109
+ // an unknown tool name can hang the subagent).
110
+ 'antigravity-md': {
111
+ file: (name) => `${name}.md`,
112
+ render: (spec) => frontmatter({
113
+ name: spec.name,
114
+ description: spec.description,
115
+ tools: ['view_file', 'grep_search', 'run_command'],
116
+ subagent: true,
117
+ mainAgent: false
118
+ }) + spec.body
119
+ }
120
+ });
121
+
122
+ function renderAgent(root, format, name) {
123
+ const fmt = FORMATS[format];
124
+ if (!fmt) throw new Error(`Unknown agent format "${format}"`);
125
+ if (fmt.src) return readText(path.join(root, fmt.src(name)));
126
+ return fmt.render(agentSpec(root, name));
127
+ }
128
+
129
+ function agentFileName(format, name) {
130
+ const fmt = FORMATS[format];
131
+ if (!fmt) throw new Error(`Unknown agent format "${format}"`);
132
+ return fmt.file(name);
133
+ }
134
+
135
+ module.exports = { AGENTS, FORMATS, agentSpec, renderAgent, agentFileName };
@@ -0,0 +1,126 @@
1
+ 'use strict';
2
+
3
+ // `setup` and `hosts list|enable|disable` (#49). Pure helpers: they compute and
4
+ // persist the host selection in ~/.ai-engineering-loop/config.json; the CLI
5
+ // then runs the normal sync (manifest-based copy and cleanup).
6
+
7
+ const path = require('path');
8
+ const { HOSTS, HOST_IDS, OUT_OF_SCOPE, SHARED_SKILLS_DIR, getHost, usesSharedSkills } = require('./registry.js');
9
+ const { detectHosts } = require('./detect.js');
10
+ const { readUserConfig, writeUserConfig } = require('../user-state.js');
11
+
12
+ function parseHostIds(raw) {
13
+ const values = (Array.isArray(raw) ? raw : String(raw || '').split(','))
14
+ .flatMap((value) => String(value).split(','))
15
+ .map((value) => value.trim().toLowerCase())
16
+ .filter(Boolean);
17
+ const unknown = values.filter((id) => !HOST_IDS.includes(id));
18
+ if (unknown.length) {
19
+ const err = new Error(`Unknown host(s): ${unknown.join(', ')}. Known: ${HOST_IDS.join(', ')}`);
20
+ err.code = 'UNKNOWN_HOST';
21
+ throw err;
22
+ }
23
+ return [...new Set(values)];
24
+ }
25
+
26
+ function skillLocation(host) {
27
+ return usesSharedSkills(host) ? `~/${SHARED_SKILLS_DIR} (shared)` : `~/${host.skills.dir}`;
28
+ }
29
+
30
+ function listHosts({ home, env = process.env, selection }) {
31
+ const detected = new Map(detectHosts({ home, env }).map((d) => [d.id, d]));
32
+ return HOSTS.map((host) => {
33
+ const d = detected.get(host.id);
34
+ return {
35
+ id: host.id,
36
+ name: host.name,
37
+ tier: host.tier,
38
+ detected: d.detected,
39
+ via: [...d.dirs.map((dir) => `~/${dir}`), ...d.bins.map((bin) => `PATH:${path.basename(bin)}`)],
40
+ enabled: selection.enabled.has(host.id),
41
+ disabled: selection.disabled.has(host.id),
42
+ skills: skillLocation(host),
43
+ agents: host.agents ? `~/${host.agents.dir}` : null
44
+ };
45
+ });
46
+ }
47
+
48
+ function formatHostsList(rows, selection) {
49
+ const lines = [`Hosts (${selection.source === 'config' ? `saved selection, mode ${selection.mode}` : 'no setup yet: hosts with a config folder are synced'})`];
50
+ lines.push(` ${'id'.padEnd(16)} ${'enabled'.padEnd(8)} ${'detected'.padEnd(28)} skills`);
51
+ for (const row of rows) {
52
+ const state = row.enabled ? 'yes' : row.disabled ? 'off' : '-';
53
+ lines.push(` ${row.id.padEnd(16)} ${state.padEnd(8)} ${(row.detected ? row.via.join(',') : '-').slice(0, 28).padEnd(28)} ${row.skills}`);
54
+ }
55
+ lines.push(`Out of scope (no native skills): ${OUT_OF_SCOPE.map((h) => h.name).join(', ')}.`);
56
+ return lines.join('\n');
57
+ }
58
+
59
+ function savedHosts(home) {
60
+ const config = readUserConfig(home);
61
+ return config.hosts && typeof config.hosts === 'object' && Array.isArray(config.hosts.enabled) ? config.hosts : null;
62
+ }
63
+
64
+ function writeHosts(home, { enabled, disabled, mode, extra = {} }) {
65
+ const next = {
66
+ ...(savedHosts(home) || {}),
67
+ ...extra,
68
+ enabled: HOST_IDS.filter((id) => enabled.has(id)),
69
+ disabled: HOST_IDS.filter((id) => disabled.has(id) && !enabled.has(id)),
70
+ mode: mode === 'auto' ? 'auto' : 'manual',
71
+ updatedAt: new Date().toISOString()
72
+ };
73
+ writeUserConfig({ hosts: next }, home);
74
+ return { enabled: new Set(next.enabled), disabled: new Set(next.disabled), source: 'config', mode: next.mode };
75
+ }
76
+
77
+ // Starting point for enable/disable before any setup: whatever is synced today.
78
+ function changeHosts({ home, selection, enable = [], disable = [] }) {
79
+ const enabled = new Set(selection.enabled);
80
+ const disabled = new Set(selection.disabled);
81
+ for (const id of enable) {
82
+ enabled.add(id);
83
+ disabled.delete(id);
84
+ }
85
+ for (const id of disable) {
86
+ enabled.delete(id);
87
+ disabled.add(id);
88
+ }
89
+ return writeHosts(home, { enabled, disabled, mode: selection.mode || 'manual' });
90
+ }
91
+
92
+ // Detection mode for agents installed later (decision 4 on #54): the
93
+ // interactive prompt suggests `auto` (Enter = auto); every non-interactive path
94
+ // (--yes, CI, scripts) stays `manual` unless --mode says otherwise.
95
+ const SETUP_MODE_DEFAULTS = Object.freeze({ interactive: 'auto', nonInteractive: 'manual' });
96
+ const SETUP_MODE_QUESTION = 'Sync agents you install later automatically? [Y/n] (recommended: Y = auto) ';
97
+
98
+ function setupMode({ modeArg = null, interactive = false, answer = '' } = {}) {
99
+ if (modeArg) return modeArg;
100
+ if (!interactive) return SETUP_MODE_DEFAULTS.nonInteractive;
101
+ const value = String(answer || '').trim().toLowerCase();
102
+ if (!value) return SETUP_MODE_DEFAULTS.interactive;
103
+ return ['y', 'yes', 'auto'].includes(value) ? 'auto' : 'manual';
104
+ }
105
+
106
+ function applySetup({ home, ids, mode }) {
107
+ return writeHosts(home, {
108
+ enabled: new Set(ids),
109
+ disabled: new Set(),
110
+ mode,
111
+ extra: { setupAt: new Date().toISOString() }
112
+ });
113
+ }
114
+
115
+ module.exports = {
116
+ parseHostIds,
117
+ listHosts,
118
+ formatHostsList,
119
+ savedHosts,
120
+ changeHosts,
121
+ applySetup,
122
+ setupMode,
123
+ SETUP_MODE_DEFAULTS,
124
+ SETUP_MODE_QUESTION,
125
+ getHost
126
+ };