ai-engineering-loop 1.14.0 → 1.16.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 (112) hide show
  1. package/.agents/{workflows/ai-engineering-loop.md → skills/ai-engineering-loop/SKILL.md} +9 -7
  2. package/{.gemini → .agents}/skills/ai-engineering-loop/references/loop-deliver.md +1 -0
  3. package/.agents/skills/ai-engineering-loop/references/loop-hosts.md +48 -0
  4. package/.agents/skills/ai-engineering-loop/references/loop-maker.md +13 -0
  5. package/{.gemini → .agents}/skills/ai-engineering-loop/references/loop-review.md +2 -0
  6. package/.claude/skills/ai-engineering-loop/SKILL.md +10 -11
  7. package/.claude/skills/ai-engineering-loop/references/loop-deliver.md +1 -0
  8. package/.claude/skills/ai-engineering-loop/references/loop-hosts.md +48 -0
  9. package/.claude/skills/ai-engineering-loop/references/loop-maker.md +6 -1
  10. package/.claude/skills/ai-engineering-loop/references/loop-review.md +2 -0
  11. package/CHANGELOG.md +83 -0
  12. package/README.md +54 -6
  13. package/adapters/README.md +22 -0
  14. package/adapters/dot/README.md +19 -9
  15. package/adapters/dot/gitlab.md +49 -0
  16. package/adapters/dot/mattermost.md +10 -0
  17. package/adapters/dot/skills/dot-dev-workflow/SKILL.md +27 -5
  18. package/adapters/dot/sonar.md +90 -0
  19. package/adapters/generate-adapter/SKILL.md +6 -5
  20. package/adapters/{dot → quality}/skills/task-impact-inquiry/SKILL.md +10 -7
  21. package/agents/instruction-only/AGENTS.md +24 -0
  22. package/bin/ai-engineering-loop.js +320 -34
  23. package/core/grill-policy.md +1 -1
  24. package/core/orchestration-model.md +11 -0
  25. package/core/runtime-safety.md +2 -1
  26. package/lib/adapter-check.js +102 -0
  27. package/lib/adapter-detect.js +125 -0
  28. package/lib/auto-update.js +3 -1
  29. package/lib/cli-args.js +11 -0
  30. package/lib/doctor.js +13 -17
  31. package/lib/gates.js +28 -1
  32. package/lib/generate-adapter.js +6 -30
  33. package/lib/host-skill-build.js +25 -15
  34. package/lib/hosts/agent-formats.js +135 -0
  35. package/lib/hosts/commands.js +126 -0
  36. package/lib/hosts/detect.js +56 -0
  37. package/lib/hosts/doctor.js +77 -0
  38. package/lib/hosts/redetect.js +60 -0
  39. package/lib/hosts/registry.js +298 -0
  40. package/lib/hosts/table.js +43 -0
  41. package/lib/orchestration.js +39 -6
  42. package/lib/run-abandon.js +116 -0
  43. package/lib/studio-server.js +1 -0
  44. package/lib/sync-hosts.js +156 -112
  45. package/package.json +2 -3
  46. package/schemas/report.schema.json +52 -5
  47. package/.agents/devil-advocate.md +0 -79
  48. package/.agents/judge.md +0 -58
  49. package/.claude/commands/ai-engineering-loop.md +0 -11
  50. package/.gemini/skills/ai-engineering-loop/SKILL.md +0 -61
  51. package/.gemini/skills/ai-engineering-loop/references/loop-maker.md +0 -8
  52. package/.gemini/skills/animate/RECIPES.md +0 -324
  53. package/.gemini/skills/animate/SKILL.md +0 -207
  54. package/.gemini/skills/animate-expo/RECIPES.md +0 -385
  55. package/.gemini/skills/animate-expo/SKILL.md +0 -263
  56. package/.gemini/skills/animation-vocabulary/SKILL.md +0 -181
  57. package/.gemini/skills/apple-design/SKILL.md +0 -290
  58. package/.gemini/skills/ask-sonner/API.md +0 -64
  59. package/.gemini/skills/ask-sonner/SKILL.md +0 -88
  60. package/.gemini/skills/backend-development/SKILL.md +0 -272
  61. package/.gemini/skills/backend-development/references/api-design-guidelines.md +0 -95
  62. package/.gemini/skills/backend-development/references/query-and-database-best-practices.md +0 -53
  63. package/.gemini/skills/backend-development/references/security-checklist.md +0 -60
  64. package/.gemini/skills/emil-design-eng/SKILL.md +0 -674
  65. package/.gemini/skills/find-animation-opportunities/SKILL.md +0 -140
  66. package/.gemini/skills/improve-animations/AUDIT.md +0 -115
  67. package/.gemini/skills/improve-animations/PLAN-TEMPLATE.md +0 -73
  68. package/.gemini/skills/improve-animations/SKILL.md +0 -109
  69. package/.gemini/skills/mobile-native/SKILL.md +0 -311
  70. package/.gemini/skills/pick-ui-library/SKILL.md +0 -85
  71. package/.gemini/skills/prototype/PICKER.md +0 -197
  72. package/.gemini/skills/prototype/SKILL.md +0 -98
  73. package/.gemini/skills/review-animations/SKILL.md +0 -120
  74. package/.gemini/skills/review-animations/STANDARDS.md +0 -187
  75. package/.gemini/skills/write-swift/SKILL.md +0 -396
  76. package/.grok/commands/ai-engineering-loop.md +0 -11
  77. package/.grok/skills/ai-engineering-loop/SKILL.md +0 -62
  78. package/.grok/skills/ai-engineering-loop/references/loop-commands.md +0 -20
  79. package/.grok/skills/ai-engineering-loop/references/loop-deliver.md +0 -8
  80. package/.grok/skills/ai-engineering-loop/references/loop-goal.md +0 -10
  81. package/.grok/skills/ai-engineering-loop/references/loop-maker.md +0 -8
  82. package/.grok/skills/ai-engineering-loop/references/loop-review.md +0 -18
  83. package/.grok/skills/ai-engineering-loop/references/loop-risky.md +0 -9
  84. package/.grok/skills/ai-engineering-loop/references/loop-verify.md +0 -20
  85. package/.grok/skills/animate/RECIPES.md +0 -324
  86. package/.grok/skills/animate/SKILL.md +0 -207
  87. package/.grok/skills/animate-expo/RECIPES.md +0 -385
  88. package/.grok/skills/animate-expo/SKILL.md +0 -263
  89. package/.grok/skills/animation-vocabulary/SKILL.md +0 -181
  90. package/.grok/skills/apple-design/SKILL.md +0 -290
  91. package/.grok/skills/ask-sonner/API.md +0 -64
  92. package/.grok/skills/ask-sonner/SKILL.md +0 -88
  93. package/.grok/skills/backend-development/SKILL.md +0 -272
  94. package/.grok/skills/backend-development/references/api-design-guidelines.md +0 -95
  95. package/.grok/skills/backend-development/references/query-and-database-best-practices.md +0 -53
  96. package/.grok/skills/backend-development/references/security-checklist.md +0 -60
  97. package/.grok/skills/emil-design-eng/SKILL.md +0 -674
  98. package/.grok/skills/find-animation-opportunities/SKILL.md +0 -140
  99. package/.grok/skills/improve-animations/AUDIT.md +0 -115
  100. package/.grok/skills/improve-animations/PLAN-TEMPLATE.md +0 -73
  101. package/.grok/skills/improve-animations/SKILL.md +0 -109
  102. package/.grok/skills/mobile-native/SKILL.md +0 -311
  103. package/.grok/skills/pick-ui-library/SKILL.md +0 -85
  104. package/.grok/skills/prototype/PICKER.md +0 -197
  105. package/.grok/skills/prototype/SKILL.md +0 -98
  106. package/.grok/skills/review-animations/SKILL.md +0 -120
  107. package/.grok/skills/review-animations/STANDARDS.md +0 -187
  108. package/.grok/skills/write-swift/SKILL.md +0 -396
  109. /package/{.gemini → .agents}/skills/ai-engineering-loop/references/loop-commands.md +0 -0
  110. /package/{.gemini → .agents}/skills/ai-engineering-loop/references/loop-goal.md +0 -0
  111. /package/{.gemini → .agents}/skills/ai-engineering-loop/references/loop-risky.md +0 -0
  112. /package/{.gemini → .agents}/skills/ai-engineering-loop/references/loop-verify.md +0 -0
@@ -18,12 +18,16 @@ const {
18
18
  homeDir,
19
19
  applyHostSync,
20
20
  hostSkillStatus,
21
+ resolveHostSelection,
22
+ planHostSync,
21
23
  formatHostSyncReport
22
24
  } = require('../lib/sync-hosts.js');
25
+ const hostCommands = require('../lib/hosts/commands.js');
23
26
  const { listDocs, readDoc } = require('../lib/docs.js');
24
27
  const {
25
28
  wantsCommandHelp,
26
29
  unknownWriterArgs,
30
+ effectiveCommand,
27
31
  commandHelp
28
32
  } = require('../lib/cli-args.js');
29
33
  const {
@@ -32,6 +36,8 @@ const {
32
36
  formatGenerateAdapterReport,
33
37
  parseTypeArg
34
38
  } = require('../lib/generate-adapter.js');
39
+ const { detectAdapter } = require('../lib/adapter-detect.js');
40
+ const { checkAdapter } = require('../lib/adapter-check.js');
35
41
  const {
36
42
  writeWorkflowOverlay,
37
43
  formatGenerateWorkflowReport,
@@ -545,26 +551,12 @@ function analyzeRepository(rootDir) {
545
551
  discovery.evidence.push('Manifest: pubspec.yaml');
546
552
  }
547
553
 
548
- // 3. Adapter / CI Detection
549
- if (fs.existsSync(path.join(rootDir, '.github', 'workflows'))) {
550
- discovery.adapter.ciProvider = 'GitHub Actions';
551
- discovery.adapter.type = 'github';
552
- } else if (fs.existsSync(path.join(rootDir, '.gitlab-ci.yml'))) {
553
- discovery.adapter.ciProvider = 'GitLab CI';
554
- discovery.adapter.type = 'gitlab';
555
- }
556
-
557
- // Check git remote if git folder exists
558
- const gitConfigStr = readFileSafe(path.join(rootDir, '.git', 'config'));
559
- if (gitConfigStr) {
560
- const urlMatch = gitConfigStr.match(/url\s*=\s*(.*)/);
561
- if (urlMatch) {
562
- discovery.adapter.repoSlug = urlMatch[1].trim();
563
- if (discovery.adapter.repoSlug.includes('gitlab.dot.co.id')) {
564
- discovery.adapter.type = 'dot';
565
- }
566
- }
567
- }
554
+ // 3. Adapter / CI Detection (shared with generate-adapter and Studio, #62)
555
+ const detected = detectAdapter(rootDir);
556
+ discovery.adapter.type = detected.type;
557
+ discovery.adapter.ciProvider = detected.ciProvider;
558
+ discovery.adapter.repoSlug = detected.remote || null;
559
+ discovery.evidence.push(`Adapter: ${detected.type} (${detected.reason})`);
568
560
 
569
561
  return discovery;
570
562
  }
@@ -909,6 +901,12 @@ function statusJson() {
909
901
  result.contextVersion = metadata.contextVersion || null;
910
902
  result.projectProfile = metadata.projectProfile || null;
911
903
  result.freshness = { status: drift.status, reason: drift.reason, level: drift.level || null };
904
+ const activeRun = currentRunSafe(CWD);
905
+ if (activeRun && !TERMINAL_STATES.has(activeRun.state)) {
906
+ const info = require('../lib/run-abandon.js').staleRunInfo(activeRun);
907
+ result.activeRun = { runId: activeRun.runId, state: activeRun.state, updatedAt: activeRun.updatedAt || null, stale: info.stale, idleDays: info.idleDays };
908
+ if (info.stale) result.activeRun.hint = require('../lib/run-abandon.js').abandonCommand(activeRun.runId);
909
+ }
912
910
  }
913
911
  }
914
912
  return result;
@@ -950,6 +948,13 @@ function handleStatus() {
950
948
  console.log(`- Living Freshness: \x1b[32m${drift.status}\x1b[0m (${drift.reason})`);
951
949
  console.log(`- Context Files: ${REQUIRED_FILES.length}/${REQUIRED_FILES.length} verified (including metadata.json, glossary.md, adrs/)`);
952
950
 
951
+ const activeRun = currentRunSafe(CWD);
952
+ if (activeRun && !TERMINAL_STATES.has(activeRun.state)) {
953
+ console.log(`- Active run: ${activeRun.runId} (${activeRun.state})`);
954
+ const hint = staleRunHint(activeRun);
955
+ if (hint) log.warn(` ${hint}`);
956
+ }
957
+
953
958
  const hosts = hostSkillStatus({ home: homeDir(), version: VERSION });
954
959
  if (hosts.stale) {
955
960
  log.warn(`- Host skills: STALE (${hosts.staleFiles} file(s) behind package v${VERSION}${hosts.installedVersion ? `, installed v${hosts.installedVersion}` : ''})`);
@@ -1030,6 +1035,168 @@ function handleSyncHosts() {
1030
1035
  console.log(formatHostSyncReport(results, { version: VERSION, dryRun }));
1031
1036
  }
1032
1037
 
1038
+ function hostSyncOrExit(selection, { dryRun = false } = {}) {
1039
+ try {
1040
+ return applyHostSync({ home: homeDir(), hosts: selection, dryRun, version: VERSION });
1041
+ } catch (err) {
1042
+ log.error(`${err.code || 'SYNC_FAILED'}: ${err.message}`);
1043
+ process.exit(2);
1044
+ }
1045
+ }
1046
+
1047
+ function readTtyLine(question, fallback) {
1048
+ process.stdout.write(question);
1049
+ try {
1050
+ const buffer = Buffer.alloc(64);
1051
+ const bytes = fs.readSync(0, buffer, 0, buffer.length, null);
1052
+ return buffer.toString('utf8', 0, bytes).trim().toLowerCase() || fallback;
1053
+ } catch {
1054
+ return fallback;
1055
+ }
1056
+ }
1057
+
1058
+ // `hosts list|doctor|enable|disable` (issues #49, #52).
1059
+ function handleHosts() {
1060
+ const rest = process.argv.slice(3).filter((arg) => !arg.startsWith('-'));
1061
+ const sub = rest[0] || 'list';
1062
+ const json = process.argv.includes('--json');
1063
+ const home = homeDir();
1064
+ const selection = resolveHostSelection(home);
1065
+ if (sub === 'list') {
1066
+ const rows = hostCommands.listHosts({ home, selection });
1067
+ if (json) {
1068
+ console.log(JSON.stringify({ ok: true, source: selection.source, mode: selection.mode, hosts: rows }, null, 2));
1069
+ return;
1070
+ }
1071
+ console.log(hostCommands.formatHostsList(rows, selection));
1072
+ if (selection.source !== 'config') console.log('Run "ai-engineering-loop setup" to choose hosts explicitly.');
1073
+ return;
1074
+ }
1075
+ if (sub === 'doctor') {
1076
+ const { hostsDoctor, formatHostsDoctor } = require('../lib/hosts/doctor.js');
1077
+ const report = hostsDoctor({ home, selection, plan: planHostSync({ home, hosts: selection }) });
1078
+ console.log(json ? JSON.stringify(report, null, 2) : formatHostsDoctor(report));
1079
+ if (!report.ok) process.exitCode = 1;
1080
+ return;
1081
+ }
1082
+ if (sub !== 'enable' && sub !== 'disable') {
1083
+ log.error(`Unknown hosts subcommand "${sub}". Use: list, doctor, enable <id...>, disable <id...>. Nothing was written.`);
1084
+ process.exit(2);
1085
+ }
1086
+ let ids;
1087
+ try {
1088
+ ids = hostCommands.parseHostIds(rest.slice(1));
1089
+ } catch (err) {
1090
+ log.error(`${err.code}: ${err.message}. Nothing was written.`);
1091
+ process.exit(2);
1092
+ }
1093
+ if (!ids.length) {
1094
+ log.error(`hosts ${sub} needs at least one host id. Nothing was written.`);
1095
+ process.exit(2);
1096
+ }
1097
+ const next = hostCommands.changeHosts({ home, selection, [sub]: ids });
1098
+ const results = hostSyncOrExit(next);
1099
+ if (json) {
1100
+ console.log(JSON.stringify({ ok: true, [sub === 'enable' ? 'enabled' : 'disabled']: ids, hosts: [...next.enabled], files: results.map(({ content, ...item }) => item) }, null, 2));
1101
+ return;
1102
+ }
1103
+ log.info(`AI Engineering Loop — hosts ${sub} ${ids.join(', ')}`);
1104
+ console.log(formatHostSyncReport(results, { version: VERSION }));
1105
+ }
1106
+
1107
+ // `setup` (issue #49): the one-time, explicit replacement for a postinstall
1108
+ // hook. Detects agents (config folder or PATH binary, never executed), asks,
1109
+ // then syncs. Without a TTY it only prints the plan unless --yes is given.
1110
+ function handleSetup() {
1111
+ const home = homeDir();
1112
+ const json = process.argv.includes('--json');
1113
+ const yes = process.argv.includes('--yes');
1114
+ const hostsArg = argValue('--hosts');
1115
+ const modeArg = argValue('--mode');
1116
+ if (modeArg && !['auto', 'manual'].includes(modeArg)) {
1117
+ log.error('--mode must be auto or manual. Nothing was written.');
1118
+ process.exit(2);
1119
+ }
1120
+ const selection = resolveHostSelection(home);
1121
+ const rows = hostCommands.listHosts({ home, selection });
1122
+ let ids;
1123
+ try {
1124
+ ids = hostsArg ? hostCommands.parseHostIds(hostsArg) : rows.filter((row) => row.detected).map((row) => row.id);
1125
+ } catch (err) {
1126
+ log.error(`${err.code}: ${err.message}. Nothing was written.`);
1127
+ process.exit(2);
1128
+ }
1129
+ const interactive = process.stdin.isTTY && process.stdout.isTTY && !json && autoUpdate.autoUpdateAllowedHere();
1130
+ if (!yes && !interactive) {
1131
+ const plan = { ok: true, wrote: false, detected: rows.filter((row) => row.detected).map((row) => row.id), wouldEnable: ids };
1132
+ if (json) console.log(JSON.stringify(plan, null, 2));
1133
+ else {
1134
+ console.log(hostCommands.formatHostsList(rows, selection));
1135
+ console.log(`Would enable: ${ids.join(', ') || '(none detected)'}`);
1136
+ console.log('Nothing was written. Run "ai-engineering-loop setup --yes" (optionally --hosts a,b --mode auto|manual) to install.');
1137
+ }
1138
+ return;
1139
+ }
1140
+ let mode = hostCommands.setupMode({ modeArg, interactive: false });
1141
+ if (!yes) {
1142
+ console.log(hostCommands.formatHostsList(rows, selection));
1143
+ if (!ids.length) {
1144
+ console.log('No AI agent detected. Install one, or pick hosts with "setup --hosts <id,...>".');
1145
+ return;
1146
+ }
1147
+ const ok = readTtyLine(`Install the loop for ${ids.join(', ')}? [Y/n] `, 'y');
1148
+ if (!['y', 'yes'].includes(ok)) {
1149
+ console.log('Nothing was written.');
1150
+ return;
1151
+ }
1152
+ if (!modeArg) {
1153
+ mode = hostCommands.setupMode({ interactive: true, answer: readTtyLine(hostCommands.SETUP_MODE_QUESTION, '') });
1154
+ }
1155
+ }
1156
+ const next = hostCommands.applySetup({ home, ids, mode });
1157
+ const results = hostSyncOrExit(next);
1158
+ if (json) {
1159
+ console.log(JSON.stringify({ ok: true, wrote: true, enabled: [...next.enabled], mode: next.mode, files: results.map(({ content, ...item }) => item) }, null, 2));
1160
+ return;
1161
+ }
1162
+ log.info(`AI Engineering Loop — setup (${next.enabled.size} host${next.enabled.size === 1 ? '' : 's'}, mode ${next.mode})`);
1163
+ console.log(formatHostSyncReport(results, { version: VERSION }));
1164
+ }
1165
+
1166
+ // First-run hint (issue #49): no postinstall writes to HOME, so the first
1167
+ // interactive CLI use suggests `setup` once a day until hosts are chosen.
1168
+ function maybeSetupHint() {
1169
+ try {
1170
+ if (process.env.AEL_NO_SETUP_HINT === '1' || process.argv.includes('--json')) return;
1171
+ if (!process.stderr.isTTY || !autoUpdate.autoUpdateAllowedHere()) return;
1172
+ const home = homeDir();
1173
+ if (hostCommands.savedHosts(home)) return;
1174
+ const userState = require('../lib/user-state.js');
1175
+ const stampFile = userState.userStatePath('setup-hint.json', home);
1176
+ const last = userState.readJsonFile(stampFile, {});
1177
+ if (last.at && Date.now() - Date.parse(last.at) < 24 * 60 * 60 * 1000) return;
1178
+ const rows = hostCommands.listHosts({ home, selection: resolveHostSelection(home) });
1179
+ const detected = rows.filter((row) => row.detected).map((row) => row.id);
1180
+ if (!detected.length) return;
1181
+ userState.writeJsonFile(stampFile, { at: new Date().toISOString() });
1182
+ process.stderr.write(`ai-engineering-loop: detected ${detected.join(', ')}. Run "ai-engineering-loop setup" once to install the loop for them (silence: AEL_NO_SETUP_HINT=1).\n`);
1183
+ } catch {
1184
+ // A hint never breaks a command.
1185
+ }
1186
+ }
1187
+
1188
+ // New agents after setup (issue #52): `status` prints a short, rate-limited
1189
+ // notice in manual mode; auto mode is handled by the background `update auto`.
1190
+ function maybeNewHostsNotice() {
1191
+ try {
1192
+ if (process.argv.includes('--json') || !process.stderr.isTTY || !autoUpdate.autoUpdateAllowedHere()) return;
1193
+ const message = require('../lib/hosts/redetect.js').newHostsNotice({ home: homeDir() });
1194
+ if (message) process.stderr.write(`${message}\n`);
1195
+ } catch {
1196
+ // A notice never breaks a command.
1197
+ }
1198
+ }
1199
+
1033
1200
  function handleGenerateAdapter() {
1034
1201
  log.info('AI Engineering Loop — Generate delivery adapter (generate-adapter)');
1035
1202
  const hints = detectAdapterHints(CWD);
@@ -1085,7 +1252,72 @@ function workingTreePaths(rootDir) {
1085
1252
  }
1086
1253
 
1087
1254
  // Command: run
1255
+ // `run --abandon [--run <id>] --reason <text> --by <name> [--yes] [--json]`
1256
+ // (issue #46). ASSISTED asks for confirmation (or --yes); UNATTENDED runs are
1257
+ // refused unless a human passes --yes. Terminal runs exit 2.
1258
+ function handleRunAbandon() {
1259
+ const json = process.argv.includes('--json');
1260
+ const yes = process.argv.includes('--yes');
1261
+ const runAbandon = require('../lib/run-abandon.js');
1262
+ const fail = (err) => {
1263
+ if (json) console.log(JSON.stringify({ ok: false, code: err.code || 'ABANDON_FAILED', error: err.message }));
1264
+ else log.error(err.message);
1265
+ process.exit(err.exitCode || 1);
1266
+ };
1267
+ try {
1268
+ const plan = runAbandon.planAbandon(CWD, { runId: argValue('--run'), reason: argValue('--reason'), by: argValue('--by') });
1269
+ const { run } = plan;
1270
+ if (run.mode === 'UNATTENDED' && !yes) {
1271
+ throw Object.assign(new Error(`Run ${run.runId} is UNATTENDED. Agents must not abandon it; a human can re-run with --yes.`), { code: 'UNATTENDED_REQUIRES_HUMAN', exitCode: 2 });
1272
+ }
1273
+ if (!yes) {
1274
+ if (json || !process.stdin.isTTY || !process.stdout.isTTY) {
1275
+ throw Object.assign(new Error(`Confirm abandoning run ${run.runId} (${run.state}) by re-running with --yes.`), { code: 'CONFIRMATION_REQUIRED' });
1276
+ }
1277
+ process.stdout.write(`Abandon run ${run.runId} (${run.state}, ${run.task ? `"${String(run.task).slice(0, 60)}"` : 'no task'})? Run data is kept. [y/N] `);
1278
+ const buffer = Buffer.alloc(16);
1279
+ let answer = '';
1280
+ try {
1281
+ answer = buffer.toString('utf8', 0, fs.readSync(0, buffer, 0, buffer.length, null)).trim().toLowerCase();
1282
+ } catch {
1283
+ answer = '';
1284
+ }
1285
+ if (!['y', 'yes'].includes(answer)) {
1286
+ console.log('Not abandoned.');
1287
+ process.exit(1);
1288
+ }
1289
+ }
1290
+ const result = runAbandon.abandonRun(CWD, { runId: run.runId, reason: plan.reason, by: plan.actor });
1291
+ if (json) console.log(JSON.stringify({ ok: true, ...result }));
1292
+ else {
1293
+ log.success(`✓ Run ${result.runId} abandoned (${result.from} -> CANCELLED) by ${result.by}: ${result.reason}`);
1294
+ console.log(result.released
1295
+ ? '- current.json released; refresh and auto-update will process this project again.'
1296
+ : `- current run unchanged${result.current ? ` (${result.current})` : ''}.`);
1297
+ }
1298
+ } catch (err) {
1299
+ fail(err);
1300
+ }
1301
+ }
1302
+
1303
+ // One-line hint for an active run that has not moved for STALE_RUN_DAYS.
1304
+ function staleRunHint(run) {
1305
+ const runAbandon = require('../lib/run-abandon.js');
1306
+ const info = runAbandon.staleRunInfo(run);
1307
+ if (!info.stale) return null;
1308
+ return `Run ${run.runId} has been ${run.state} for ${info.idleDays} day(s). If it is abandoned: ${runAbandon.abandonCommand(run.runId)}`;
1309
+ }
1310
+
1311
+ function currentRunSafe(dir) {
1312
+ try {
1313
+ return getCurrentRun(dir);
1314
+ } catch {
1315
+ return null;
1316
+ }
1317
+ }
1318
+
1088
1319
  function handleRun() {
1320
+ if (process.argv.includes('--abandon')) return handleRunAbandon();
1089
1321
  const runJson = process.argv.includes('--json');
1090
1322
  const realLog = console.log;
1091
1323
  if (runJson) console.log = () => {};
@@ -1228,7 +1460,8 @@ function handleRun() {
1228
1460
  console.log('1. Grill if needed (docs grill-policy), then freeze a failure-table Goal Contract');
1229
1461
  if (runResult.run.mode === RUN_MODES.REPORT_ONLY) {
1230
1462
  console.log('2. Analyze evidence without changing repository files');
1231
- console.log('3. Write report.json and finish with `ai-engineering-loop gate report`');
1463
+ console.log('3. Write report.json; if the host has a subagent tool, have ONE fresh devil-advocate challenge it (no Judge), and record `review` in report.json (loop-maker)');
1464
+ console.log('4. Finish with `ai-engineering-loop gate report`');
1232
1465
  } else {
1233
1466
  console.log('2. Root Cause Analysis (docs root-cause-analysis) & Plan');
1234
1467
  console.log('3. Maker TDD at named seams (docs tdd-policy)');
@@ -1264,7 +1497,7 @@ function handleRun() {
1264
1497
  } else {
1265
1498
  console.log(`- Fallback: CONTEXT_ISOLATION_ONLY (${grok.reason})`);
1266
1499
  }
1267
- console.log('- Skill: .grok/skills/ai-engineering-loop/SKILL.md');
1500
+ console.log('- Skill: .agents/skills/ai-engineering-loop/SKILL.md (spawn rules: references/loop-hosts.md, Grok CLI section)');
1268
1501
  }
1269
1502
 
1270
1503
  const claudeSkill = path.join(CWD, '.claude', 'skills', 'ai-engineering-loop', 'SKILL.md');
@@ -1279,14 +1512,14 @@ function handleRun() {
1279
1512
  console.log('- Skill: .claude/skills/ai-engineering-loop/SKILL.md');
1280
1513
  }
1281
1514
 
1282
- const agAgent = path.join(CWD, '.agents', 'judge.md');
1283
- if (fs.existsSync(agAgent)) {
1515
+ const sharedSkill = path.join(CWD, '.agents', 'skills', 'ai-engineering-loop', 'SKILL.md');
1516
+ if (fs.existsSync(sharedSkill)) {
1284
1517
  console.log('------------------------------------------------------------');
1285
- log.bold('Antigravity host:');
1286
- console.log('- Subagent: invoke_subagent or Task; wait; never browser_subagent');
1518
+ log.bold('Shared .agents/skills hosts (Codex, Gemini CLI, Antigravity, Cursor, Copilot, ...):');
1519
+ console.log('- Same skill on every host; spawn rules per host: references/loop-hosts.md');
1287
1520
  console.log('- Devil\'s Advocate: 8 tool calls, diff file, skip css');
1288
1521
  console.log('- Judge: 4 tool calls, ledger + contract only');
1289
- console.log('- Workflow: .agents/workflows/ai-engineering-loop.md');
1522
+ console.log('- Skill: .agents/skills/ai-engineering-loop/SKILL.md');
1290
1523
  }
1291
1524
  console.log('------------------------------------------------------------\n');
1292
1525
  }
@@ -2001,6 +2234,8 @@ function handleState() {
2001
2234
  console.log(`State: ${run.state}`);
2002
2235
  console.log(`Iteration: ${run.iteration}`);
2003
2236
  console.log(`Artifacts: ${Object.keys(run.artifacts).join(', ') || 'none'}`);
2237
+ const hint = staleRunHint(run);
2238
+ if (hint) log.warn(hint);
2004
2239
  }
2005
2240
  } catch (err) {
2006
2241
  if (json) console.log(JSON.stringify({ ok: false, code: err.code || 'STATE_FAILED', error: err.message }));
@@ -2011,12 +2246,12 @@ function handleState() {
2011
2246
 
2012
2247
  function handleDoctor() {
2013
2248
  const json = process.argv.includes('--json');
2014
- const result = runDoctor(path.join(__dirname, '..'));
2249
+ const result = runDoctor(path.join(__dirname, '..'), { projectDir: CWD });
2015
2250
  if (json) console.log(JSON.stringify(result));
2016
2251
  else {
2017
2252
  console.log(`AI Engineering Loop doctor: ${result.ok ? 'READY' : 'NOT READY'}`);
2018
2253
  for (const check of result.checks) {
2019
- console.log(`${check.passed ? '✓' : '✗'} ${check.id}: ${check.detail}`);
2254
+ console.log(`${check.passed ? '✓' : check.level === 'warn' ? '!' : '✗'} ${check.id}: ${check.detail}`);
2020
2255
  }
2021
2256
  }
2022
2257
  if (!result.ok) process.exit(1);
@@ -2044,6 +2279,7 @@ function handleSafeRefresh() {
2044
2279
  const current = getCurrentRun(CWD);
2045
2280
  if (current && !TERMINAL_STATES.has(current.state)) {
2046
2281
  log.warn(`Run ${current.runId} is active (${current.state}); skipping refresh until it finishes.`);
2282
+ log.dim(`If that run is abandoned, close it first: ${require('../lib/run-abandon.js').abandonCommand(current.runId)}`);
2047
2283
  process.exit(3);
2048
2284
  }
2049
2285
  const legacy = !fs.existsSync(path.join(CONTEXT_DIR, GENERATED_HASHES_FILE));
@@ -2190,6 +2426,17 @@ function handleUpdateAuto() {
2190
2426
  // Best effort.
2191
2427
  }
2192
2428
  const decision = autoUpdate.decideUpdate({ current: VERSION, distTags: cache.distTags, ...policy });
2429
+ // Agents installed after setup (#52): auto mode enables and syncs them here.
2430
+ let hostsResult = { added: [] };
2431
+ try {
2432
+ hostsResult = require('../lib/hosts/redetect.js').autoEnableNewHosts({ home: homeDir(), scope });
2433
+ if (hostsResult.added.length && decision.action !== 'apply') {
2434
+ const synced = applyHostSync({ home: homeDir(), hosts: resolveHostSelection(homeDir()), version: VERSION });
2435
+ hostsResult = { ...hostsResult, synced: synced.filter((item) => item.action === 'copy').length };
2436
+ }
2437
+ } catch (err) {
2438
+ hostsResult = { added: [], error: err.message };
2439
+ }
2193
2440
  const projects = projectRegistry.listProjects().projects;
2194
2441
  let result = null;
2195
2442
  if (decision.action === 'apply') {
@@ -2205,7 +2452,10 @@ function handleUpdateAuto() {
2205
2452
  } else {
2206
2453
  result = autoUpdate.processPending({ projects, readCurrentRun: readCurrentRunFor });
2207
2454
  }
2208
- out({ ok: true, policy: policy.policy, policySource: policy.source, scope, offline: cache.error || null, decision, result });
2455
+ const held = result && Array.isArray(result.pending) && result.pending.length
2456
+ ? { pendingHint: `Projects skipped because a run is active. If a run is abandoned, run in that project: ${require('../lib/run-abandon.js').abandonCommand()}` }
2457
+ : {};
2458
+ out({ ok: true, policy: policy.policy, policySource: policy.source, scope, offline: cache.error || null, decision, result, hosts: hostsResult, ...held });
2209
2459
  cacheUpdateHighlights({ ...cache, scope }, decision, packageName).catch(() => {});
2210
2460
  }
2211
2461
 
@@ -2258,7 +2508,12 @@ function handleProjects() {
2258
2508
  if (json) console.log(JSON.stringify({ ok: true, action, ...result }));
2259
2509
  else if (action === 'list') {
2260
2510
  if (!result.projects.length) console.log('No registered projects. They are added by init/run/status/refresh, or `projects add|scan`.');
2261
- for (const p of result.projects) console.log(`- ${p.path} (context ${p.contextVersion || '?'}, seen ${p.lastSeen})`);
2511
+ for (const p of result.projects) {
2512
+ const held = currentRunSafe(p.path);
2513
+ const info = held ? require('../lib/run-abandon.js').staleRunInfo(held) : { stale: false };
2514
+ const tag = info.stale ? `; held by stale run ${held.runId} (${held.state}, ${info.idleDays}d): run --abandon there` : '';
2515
+ console.log(`- ${p.path} (context ${p.contextVersion || '?'}, seen ${p.lastSeen}${tag})`);
2516
+ }
2262
2517
  } else console.log(JSON.stringify(result, null, 2));
2263
2518
  } catch (err) {
2264
2519
  if (json) console.log(JSON.stringify({ ok: false, code: err.code || 'PROJECTS_FAILED', error: err.message }));
@@ -2961,6 +3216,18 @@ function handleDeliver() {
2961
3216
  if (approve && !by) {
2962
3217
  throw Object.assign(new Error('--approve requires --by <name> (the approving human).'), { code: 'INVALID_USAGE' });
2963
3218
  }
3219
+ // Adapter preflight (#63): UNATTENDED stops before anything is written;
3220
+ // ASSISTED only warns, because a human is approving this delivery.
3221
+ // A configured-vs-detected mismatch can be deliberate, so it never blocks.
3222
+ const adapterProblems = checkAdapter(CWD).filter((item) => !item.passed);
3223
+ const blocking = adapterProblems.filter((item) => item.id !== 'adapter-detected');
3224
+ if (mode === RUN_MODES.UNATTENDED && blocking.length) {
3225
+ throw Object.assign(
3226
+ new Error(`Adapter preflight failed; nothing was written. ${blocking.map((item) => `${item.id}: ${item.detail}`).join('; ')}`),
3227
+ { code: 'ADAPTER_PREFLIGHT_FAILED' }
3228
+ );
3229
+ }
3230
+ for (const item of adapterProblems) console.error(`! ${item.id}: ${item.detail}`);
2964
3231
  const approved = [];
2965
3232
  if (approve && run.workflow) {
2966
3233
  const workflow = workflowStatus(CWD, { runId });
@@ -3046,6 +3313,9 @@ Commands:
3046
3313
  --recipe <id> bind an immutable compiled workflow plan
3047
3314
  --tier T0|T1|T2 --tier-reason <text> override the automatic tier (recorded)
3048
3315
  --json print runId, tier, tier reasons, and subagent count only
3316
+ --abandon [--run <id>] --reason <text> --by <name> [--yes] [--json]
3317
+ close a stale run as CANCELLED (kept on disk) and release current.json;
3318
+ ASSISTED asks to confirm, UNATTENDED needs --yes from a human
3049
3319
  state Inspect the current run ledger
3050
3320
  --run <id> target a non-current run
3051
3321
  --json print the complete machine-readable ledger
@@ -3162,7 +3432,13 @@ Commands:
3162
3432
  create [--run <id>] [--audience developer|agent|auditor]
3163
3433
  [--output <repository-relative-file>|-] [--json]
3164
3434
  inspect | brief <repository-relative-file> [--json]
3165
- sync-hosts Copy package skills/agents/commands into ~/.claude ~/.grok ~/.gemini ~/.agents
3435
+ setup One-time: detect AI agents (config folder or PATH binary, never run) and install for them
3436
+ --yes skip the prompt --hosts <id,...> pick hosts --json
3437
+ --mode auto|manual (prompt suggests auto; --yes / no TTY default to manual)
3438
+ Without a TTY and without --yes it only prints the plan
3439
+ hosts Show or change which AI agent hosts get the loop
3440
+ list [--json] | doctor [--json] | enable <id...> | disable <id...> (removes unedited AEL files)
3441
+ sync-hosts Install the loop skill and reviewer agents into every detected AI agent host
3166
3442
  (only hosts that already exist; DOT skills only if already installed)
3167
3443
  --dry-run print the plan without writing
3168
3444
  --pack <list> core (always), backend, design, quality; saved for later syncs
@@ -3194,14 +3470,15 @@ const command = args[0] || 'init';
3194
3470
  // Side-effect guard (issue #25): help never executes a command, and writer
3195
3471
  // commands reject unknown flags before touching any file.
3196
3472
  if (!['-h', '--help', '-v', '--version'].includes(command)) {
3197
- if (wantsCommandHelp(command, args.slice(1))) {
3473
+ const checked = effectiveCommand(command, args.slice(1));
3474
+ if (wantsCommandHelp(checked, args.slice(1))) {
3198
3475
  const block = commandHelp(helpText(), command);
3199
3476
  console.log(block
3200
3477
  ? `Usage: npx ai-engineering-loop ${block.trim()}`
3201
3478
  : helpText());
3202
3479
  process.exit(0);
3203
3480
  }
3204
- const unknown = unknownWriterArgs(command, args.slice(1));
3481
+ const unknown = unknownWriterArgs(checked, args.slice(1));
3205
3482
  if (unknown.length > 0) {
3206
3483
  log.error(`Unknown argument(s) for "${command}": ${unknown.join(' ')}. Nothing was written.`);
3207
3484
  console.log(`Run "npx ai-engineering-loop ${command} --help" for usage.`);
@@ -3217,6 +3494,9 @@ if (['init', 'run', 'status', 'refresh'].includes(command)) {
3217
3494
  maybeAutoUpdate();
3218
3495
  }
3219
3496
 
3497
+ if (!['setup', 'hosts', 'sync-hosts', '-h', '--help', '-v', '--version'].includes(command)) maybeSetupHint();
3498
+ if (command === 'status') maybeNewHostsNotice();
3499
+
3220
3500
  switch (command) {
3221
3501
  case 'init':
3222
3502
  handleInit();
@@ -3311,6 +3591,12 @@ switch (command) {
3311
3591
  case 'sync-hosts':
3312
3592
  handleSyncHosts();
3313
3593
  break;
3594
+ case 'hosts':
3595
+ handleHosts();
3596
+ break;
3597
+ case 'setup':
3598
+ handleSetup();
3599
+ break;
3314
3600
  case 'generate-adapter':
3315
3601
  handleGenerateAdapter();
3316
3602
  break;
@@ -64,7 +64,7 @@ When the change can touch state, siblings, actors/approvals, or downstream work,
64
64
 
65
65
  On `adapter_type: dot`, this is mandatory. On other adapters, skip only when the change cannot touch those four (copy, CSS, comment).
66
66
 
67
- Canonical skill: `adapters/dot/skills/task-impact-inquiry/SKILL.md`. Host copies via `sync-hosts`: `~/.claude/skills/task-impact-inquiry/`, `~/.grok/skills/task-impact-inquiry/`, `~/.gemini/config/skills/task-impact-inquiry/`. Load that skill if present. If it is missing, still run this section. Do not claim the skill ran.
67
+ Canonical skill (adapter-neutral): `adapters/quality/skills/task-impact-inquiry/SKILL.md`. Host copies via `sync-hosts`: `~/.claude/skills/task-impact-inquiry/`, `~/.agents/skills/task-impact-inquiry/` (Codex, Gemini CLI, Grok, Cursor, Copilot, and other shared-folder hosts), `~/.gemini/config/skills/task-impact-inquiry/` (Antigravity). Load that skill if present. If it is missing, still run this section. Do not claim the skill ran.
68
68
 
69
69
  If Stage 1 grill already produced the matrix and the user confirmed it, do not run a second interview.
70
70
 
@@ -100,6 +100,17 @@ Native Subagent Invocation: UNAVAILABLE
100
100
  Review Method: Clean-Slate Artifact Isolation Barrier
101
101
  ```
102
102
 
103
+ If native subagent invocation is AVAILABLE but no reviewer subagent returned its own result, the mode line carries the reason, so the header is never contradictory (#57):
104
+
105
+ ```text
106
+ Execution Mode: CONTEXT_ISOLATION_ONLY (reason: <why>)
107
+ Independent LLM Execution: NOT PROVEN
108
+ Native Subagent Invocation: AVAILABLE
109
+ Review Method: Clean-Slate Artifact Isolation Barrier
110
+ ```
111
+
112
+ REPORT_ONLY (recipe `audit`) policy: when the host can invoke a native subagent, one fresh `devil-advocate` sibling reviews `report.json` before `gate report` (no Judge, no iteration loop); otherwise the same check runs in-session with a reason. `report.json` may carry a `review` block, which `gate report` validates.
113
+
103
114
  ### Strictly Forbidden Phrases during `CONTEXT_ISOLATION_ONLY`:
104
115
  - *"independent agent review"*
105
116
  - *"subagent"*
@@ -97,8 +97,9 @@ The CLI may update itself, but only under the policy the user chose (`~/.ai-engi
97
97
 
98
98
  - **Check:** `run`, `status`, `init`, and `refresh` start `update auto --background` detached at most once every 24 hours (`npm view <pkg> dist-tags`, 3 s timeout). The command itself never waits. Offline or failed checks keep the cached tags and stay silent.
99
99
  - **Opt-out:** `AEL_NO_AUTO_UPDATE=1`, `CI=true`, or `update policy off`.
100
- - **Apply (global installs only):** acquire `~/.ai-engineering-loop/update.lock`, verify the release (registry `repository.url` must match this package, and `dist.integrity` must exist), `npm install -g <pkg>@<target>`, `sync-hosts`, then `refresh --non-destructive` in every project in `~/.ai-engineering-loop/projects.json`. User-edited context files are kept and new templates are written as `*.ael-new`. Projects with an active run are skipped and retried later. Updates are deferred entirely while any UNATTENDED run is active.
100
+ - **Apply (global installs only):** acquire `~/.ai-engineering-loop/update.lock`, verify the release (registry `repository.url` must match this package, and `dist.integrity` must exist), `npm install -g <pkg>@<target>`, `sync-hosts`, then `refresh --non-destructive` in every project in `~/.ai-engineering-loop/projects.json`. User-edited context files are kept and new templates are written as `*.ael-new`. Projects with an active run are skipped and retried later; a human closes a stale run with `run --abandon --reason <text> --by <name>` (agents never abandon a run on their own). Updates are deferred entirely while any UNATTENDED run is active.
101
101
  - **Project installs (devDependency or npx):** notify only. `package.json` and lockfiles are never changed automatically. The notice shows current -> latest, 2-4 CHANGELOG highlights, one update command for the detected package manager (npm/pnpm/yarn/bun), and how to silence it (`AEL_NO_UPDATE_NOTICE=1` or `update policy off`). It appears at most once per 24 h per project, on an interactive stderr only, never in CI or `--json` output. Global `notify` and major notices use the same format.
102
+ - **Host setup (no install hooks):** the package defines no `preinstall`/`install`/`postinstall` script, so installing never writes to `$HOME`. `ai-engineering-loop setup` (interactive, or `--yes`) detects agents by config folder or by an executable on `PATH` (stat only, never executed) and saves the selection in `~/.ai-engineering-loop/config.json` (`hosts.enabled`, `hosts.disabled`, `hosts.mode`). `hosts enable|disable <id...>` change it; disabling removes only manifest-tracked, unedited AEL files. Before `setup`, sync writes only to hosts whose config folder exists. Agents never run `setup` or `hosts enable|disable` on their own initiative. Agents installed later are re-detected (stat only): with `hosts.mode: auto` the background `update auto` of a global install enables and syncs them (never a host the user disabled); with `manual` `status` shows one rate-limited notice. Neither writes or prints in CI, in `--json` output, or with `AEL_NO_AUTO_UPDATE`. `hosts doctor` is read-only.
102
103
  - **Legacy projects (no `.ael-generated.json` yet):** the first `refresh --non-destructive` overwrites AEL-managed context files directly and deletes obsolete AEL-managed files instead of writing `*.ael-new`. Old copies go to `.ai-engineering-loop/.ael-backup/<timestamp>/` first, and hashes are recorded so later updates use the normal flow. Append-only files (lessons, glossary) and all other user files are never touched. `sync-hosts` likewise removes host files it recorded in its manifest that the package no longer ships (unless edited).
103
104
  - **Majors:** `update apply --yes` runs `ai-engineering-loop migrate --from <old>` right after the install. `migrations/<major>.js` steps are idempotent and recorded in `~/.ai-engineering-loop/migrations.json`.
104
105
  - **Rollback:** `update rollback --yes` reinstalls the previous version, re-syncs host skills, and restores any legacy-update snapshot taken by that update.