ai-engineering-loop 1.15.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 (39) hide show
  1. package/.agents/skills/ai-engineering-loop/SKILL.md +1 -1
  2. package/.agents/skills/ai-engineering-loop/references/loop-deliver.md +1 -0
  3. package/.agents/skills/ai-engineering-loop/references/loop-hosts.md +5 -1
  4. package/.agents/skills/ai-engineering-loop/references/loop-maker.md +6 -1
  5. package/.agents/skills/ai-engineering-loop/references/loop-review.md +2 -0
  6. package/.claude/skills/ai-engineering-loop/SKILL.md +1 -1
  7. package/.claude/skills/ai-engineering-loop/references/loop-deliver.md +1 -0
  8. package/.claude/skills/ai-engineering-loop/references/loop-hosts.md +5 -1
  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 +36 -0
  12. package/README.md +24 -22
  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 +24 -23
  23. package/core/grill-policy.md +1 -1
  24. package/core/orchestration-model.md +11 -0
  25. package/lib/adapter-check.js +102 -0
  26. package/lib/adapter-detect.js +125 -0
  27. package/lib/doctor.js +10 -3
  28. package/lib/gates.js +28 -1
  29. package/lib/generate-adapter.js +6 -30
  30. package/lib/host-skill-build.js +10 -0
  31. package/lib/hosts/commands.js +3 -3
  32. package/lib/hosts/doctor.js +3 -2
  33. package/lib/hosts/registry.js +49 -22
  34. package/lib/hosts/table.js +12 -4
  35. package/lib/orchestration.js +39 -6
  36. package/lib/studio-server.js +1 -0
  37. package/lib/sync-hosts.js +2 -1
  38. package/package.json +1 -1
  39. package/schemas/report.schema.json +52 -5
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: task-impact-inquiry
3
- description: Map business blast radius before code. Use for impact, side effects, sibling data, approval, queues, or when a new developer must learn the current flow. Triggers: cek impactnya, blast radius, analisa pengaruh, brainstorming impact. Not a substitute for ai-engineering-loop.
3
+ description: Map business blast radius before code. Use for impact, side effects, sibling data, approval, queues, or when a new developer must learn the current flow. Triggers (EN/ID): check the impact, impact analysis, blast radius, side effects, cek impactnya, analisa pengaruh. Not a substitute for ai-engineering-loop.
4
4
  ---
5
5
 
6
6
  # Task Impact Inquiry
@@ -9,7 +9,9 @@ Map the **current business flow** and the **blast radius** of a change before an
9
9
 
10
10
  This skill fills AI Engineering Loop Stage 1 grill. It is not a parallel engineering OS.
11
11
 
12
- If Stage 1 grill already produced this matrix and the user confirmed it, stop. Do not interview again. On commit-bound work, continue in `ai-engineering-loop` (freeze the Goal Contract, then Maker). Do not start `dot-dev-workflow` Phases 1-6.
12
+ If Stage 1 grill already produced this matrix and the user confirmed it, stop. Do not interview again. On commit-bound work, continue in `ai-engineering-loop` (freeze the Goal Contract, then Maker). Do not start a second engineering loop from your team's own workflow skill.
13
+
14
+ Works on any adapter. On `adapter_type: dot` it is mandatory in Stage 1; the DOT-only rules live in `adapters/dot/README.md`.
13
15
 
14
16
  ## Hard gate
15
17
 
@@ -23,7 +25,8 @@ Green unit tests later are not proof that siblings, approvals, or downstream job
23
25
 
24
26
  ## When to use
25
27
 
26
- - "cek impactnya", "blast radius", "analisa pengaruh", "brainstorming impact"
28
+ - "check the impact", "impact analysis", "blast radius", "side effects"
29
+ - Indonesian: "cek impactnya", "analisa pengaruh", "brainstorming impact"
27
30
  - Bug, edge case, or business-logic change
28
31
  - Shared service, status transition, calculation, validation, authorization, schema
29
32
  - The user is new to the domain and does not know the flow
@@ -47,8 +50,8 @@ Look up facts (files, enums, jobs). Grill only **decisions**.
47
50
  Read in this order. Skip a source if it is missing. Do not invent statuses.
48
51
 
49
52
  1. `.ai-engineering-loop/glossary.md`
50
- 2. Existing FSD if present (`docs/fsd/`, `specs-book/fsd/`, especially `impact-matrix.md`). Read only. Do not generate an FSD.
51
- 3. Status enums, services, validators, listeners, BullMQ / cron / queue processors
53
+ 2. Existing functional spec (FSD/PRD) if present (`docs/fsd/`, `specs-book/fsd/`, especially `impact-matrix.md`). Read only. Do not generate an FSD.
54
+ 3. Status enums, services, validators, listeners, queue / cron / job processors
52
55
  4. Matching FE pages, routes, and permission guards when both FE and BE are in the workspace
53
56
 
54
57
  Cite the path for each claim. If FE or BE is missing, say so.
@@ -76,7 +79,7 @@ If the flow cannot be determined from the repo, say what is missing.
76
79
 
77
80
  **Actor and approval.** Who creates, who may edit, who must re-approve? When is an existing approval void, and when must it be kept?
78
81
 
79
- **Downstream.** BullMQ, cron, listeners, billing, dashboard totals.
82
+ **Downstream.** Queues, cron, listeners, billing, dashboard totals.
80
83
 
81
84
  ### 4. Where it hits (hit map + blast picture)
82
85
 
@@ -152,4 +155,4 @@ Next: freeze Goal Contract | stop (impact-only)
152
155
  - Mermaid or LaTeX
153
156
  - Claiming isolation because unit tests passed
154
157
  - Inventing business rules the repo and the user did not supply
155
- - Generating an FSD or starting `dot-dev-workflow` as a second loop
158
+ - Generating an FSD or starting another workflow skill as a second loop
@@ -0,0 +1,24 @@
1
+ <!-- Generated from skill-src/ by npm run build:skills; do not edit. -->
2
+ # AI Engineering Loop (digest)
3
+
4
+ For hosts with no subagent tool (certification `instruction-only`). Full skill: `~/.agents/skills/ai-engineering-loop/SKILL.md` after `sync-hosts`. Stage details: `npx ai-engineering-loop docs loop-<goal|maker|verify|review|deliver>`.
5
+
6
+ Loop: Specify (0-1), Make (2-4), Review (5-7), Deliver (8). You are Maker. Devil's Advocate (DA) and Judge run in this session as `CONTEXT_ISOLATION_ONLY`, with the same budgets; never claim independent review.
7
+
8
+ 1. `npx ai-engineering-loop run --json` gives runId, tier, budget. Read `.ai-engineering-loop/glossary.md`.
9
+ 2. Goal Contract: AC is a failure table (happy, empty, boundary, error). Only after the human freezes: `goal freeze --latest --run <runId> --by human`. Chat agreement is not freeze.
10
+ 3. Maker: one red test per AC row before the fix, then `gate maker`.
11
+ 4. `verify --cmd <test command>`, then write claimed-vs-reality.md.
12
+ 5. DA: re-read only the diff, Goal, and evidence; log findings; `gate review`. Judge: write the verdict from the evidence, then `gate judge`. ITERATE at most 3 times.
13
+ 6. Deliver per `.ai-engineering-loop/adapter.md`. ASSISTED: `deliver --approve --by <human>` only after the human says so.
14
+
15
+ Never: edit `state.json`/`current.json`, skip a gate, infer approval, invent usage counts, or put secrets in messages. A gate failure overrides prose.
16
+
17
+ Report header:
18
+
19
+ ```
20
+ Execution Mode: CONTEXT_ISOLATION_ONLY
21
+ Independent LLM Execution: NOT PROVEN
22
+ Native Subagent Invocation: UNAVAILABLE
23
+ Review Method: Clean-Slate Artifact Isolation Barrier
24
+ ```
@@ -36,6 +36,8 @@ const {
36
36
  formatGenerateAdapterReport,
37
37
  parseTypeArg
38
38
  } = require('../lib/generate-adapter.js');
39
+ const { detectAdapter } = require('../lib/adapter-detect.js');
40
+ const { checkAdapter } = require('../lib/adapter-check.js');
39
41
  const {
40
42
  writeWorkflowOverlay,
41
43
  formatGenerateWorkflowReport,
@@ -549,26 +551,12 @@ function analyzeRepository(rootDir) {
549
551
  discovery.evidence.push('Manifest: pubspec.yaml');
550
552
  }
551
553
 
552
- // 3. Adapter / CI Detection
553
- if (fs.existsSync(path.join(rootDir, '.github', 'workflows'))) {
554
- discovery.adapter.ciProvider = 'GitHub Actions';
555
- discovery.adapter.type = 'github';
556
- } else if (fs.existsSync(path.join(rootDir, '.gitlab-ci.yml'))) {
557
- discovery.adapter.ciProvider = 'GitLab CI';
558
- discovery.adapter.type = 'gitlab';
559
- }
560
-
561
- // Check git remote if git folder exists
562
- const gitConfigStr = readFileSafe(path.join(rootDir, '.git', 'config'));
563
- if (gitConfigStr) {
564
- const urlMatch = gitConfigStr.match(/url\s*=\s*(.*)/);
565
- if (urlMatch) {
566
- discovery.adapter.repoSlug = urlMatch[1].trim();
567
- if (discovery.adapter.repoSlug.includes('gitlab.dot.co.id')) {
568
- discovery.adapter.type = 'dot';
569
- }
570
- }
571
- }
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})`);
572
560
 
573
561
  return discovery;
574
562
  }
@@ -1472,7 +1460,8 @@ function handleRun() {
1472
1460
  console.log('1. Grill if needed (docs grill-policy), then freeze a failure-table Goal Contract');
1473
1461
  if (runResult.run.mode === RUN_MODES.REPORT_ONLY) {
1474
1462
  console.log('2. Analyze evidence without changing repository files');
1475
- 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`');
1476
1465
  } else {
1477
1466
  console.log('2. Root Cause Analysis (docs root-cause-analysis) & Plan');
1478
1467
  console.log('3. Maker TDD at named seams (docs tdd-policy)');
@@ -2257,12 +2246,12 @@ function handleState() {
2257
2246
 
2258
2247
  function handleDoctor() {
2259
2248
  const json = process.argv.includes('--json');
2260
- const result = runDoctor(path.join(__dirname, '..'));
2249
+ const result = runDoctor(path.join(__dirname, '..'), { projectDir: CWD });
2261
2250
  if (json) console.log(JSON.stringify(result));
2262
2251
  else {
2263
2252
  console.log(`AI Engineering Loop doctor: ${result.ok ? 'READY' : 'NOT READY'}`);
2264
2253
  for (const check of result.checks) {
2265
- console.log(`${check.passed ? '✓' : '✗'} ${check.id}: ${check.detail}`);
2254
+ console.log(`${check.passed ? '✓' : check.level === 'warn' ? '!' : '✗'} ${check.id}: ${check.detail}`);
2266
2255
  }
2267
2256
  }
2268
2257
  if (!result.ok) process.exit(1);
@@ -3227,6 +3216,18 @@ function handleDeliver() {
3227
3216
  if (approve && !by) {
3228
3217
  throw Object.assign(new Error('--approve requires --by <name> (the approving human).'), { code: 'INVALID_USAGE' });
3229
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}`);
3230
3231
  const approved = [];
3231
3232
  if (approve && run.workflow) {
3232
3233
  const workflow = workflowStatus(CWD, { runId });
@@ -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/`, `~/.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.
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"*
@@ -0,0 +1,102 @@
1
+ 'use strict';
2
+
3
+ // Adapter checks shared by `doctor` and the `deliver` preflight (#63).
4
+ // Each check: { id, passed, detail, level: 'error' | 'warn' }.
5
+ // `error` = Stage 8 cannot follow this adapter; `warn` = it may fail late.
6
+
7
+ const fs = require('fs');
8
+ const path = require('path');
9
+ const { spawnSync } = require('child_process');
10
+ const { SHIPPED_TYPES, detectAdapterHints } = require('./generate-adapter.js');
11
+ const { DOT_GITLAB_HOST } = require('./adapter-detect.js');
12
+
13
+ const KNOWN_TYPES = [...SHIPPED_TYPES, 'custom'];
14
+ const CUSTOM_SPEC = '.ai-engineering-loop/adapter/delivery.md';
15
+
16
+ function editDistance(a, b) {
17
+ const row = Array.from({ length: b.length + 1 }, (_, i) => i);
18
+ for (let i = 1; i <= a.length; i += 1) {
19
+ let prev = row[0];
20
+ row[0] = i;
21
+ for (let j = 1; j <= b.length; j += 1) {
22
+ const next = row[j];
23
+ row[j] = Math.min(row[j] + 1, row[j - 1] + 1, prev + (a[i - 1] === b[j - 1] ? 0 : 1));
24
+ prev = next;
25
+ }
26
+ }
27
+ return row[b.length];
28
+ }
29
+
30
+ function nearestType(value) {
31
+ const ranked = KNOWN_TYPES
32
+ .map((type) => ({ type, distance: editDistance(String(value || '').toLowerCase(), type) }))
33
+ .sort((a, b) => a.distance - b.distance);
34
+ return ranked[0].distance <= 2 ? ranked[0].type : null;
35
+ }
36
+
37
+ // Which CLI must be logged in for a type, or null.
38
+ function toolFor(type) {
39
+ if (type === 'github') return { bin: 'gh', args: ['auth', 'status'], label: 'gh auth status' };
40
+ if (type === 'gitlab') return { bin: 'glab', args: ['auth', 'status'], label: 'glab auth status' };
41
+ if (type === 'dot') {
42
+ return { bin: 'glab', args: ['auth', 'status', '--hostname', DOT_GITLAB_HOST], label: `glab auth status --hostname ${DOT_GITLAB_HOST}` };
43
+ }
44
+ return null;
45
+ }
46
+
47
+ function defaultRun(bin, args) {
48
+ return spawnSync(bin, args, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], timeout: 15000 });
49
+ }
50
+
51
+ function check(id, passed, detail, level = 'error') {
52
+ return { id, passed: Boolean(passed), detail, level };
53
+ }
54
+
55
+ // projectDir: the repo being delivered. packageRoot: where adapters/ ships.
56
+ function checkAdapter(projectDir, { packageRoot = path.join(__dirname, '..'), run = defaultRun } = {}) {
57
+ const checks = [];
58
+ const adapterFile = path.join(projectDir, '.ai-engineering-loop', 'adapter.md');
59
+ if (!fs.existsSync(adapterFile)) {
60
+ checks.push(check('adapter-config', false, 'no .ai-engineering-loop/adapter.md; run init or generate-adapter', 'warn'));
61
+ return checks;
62
+ }
63
+ const hints = detectAdapterHints(projectDir);
64
+ const type = hints.existingType;
65
+ if (!KNOWN_TYPES.includes(type)) {
66
+ const near = nearestType(type);
67
+ checks.push(check(
68
+ 'adapter-type',
69
+ false,
70
+ `unknown adapter_type "${type || '(empty)'}"; known: ${KNOWN_TYPES.join(' | ')}${near ? `; did you mean "${near}"?` : ''}`
71
+ ));
72
+ return checks;
73
+ }
74
+ checks.push(check('adapter-type', true, `adapter_type "${type}"`));
75
+
76
+ const spec = type === 'custom' ? path.join(projectDir, CUSTOM_SPEC) : path.join(packageRoot, 'adapters', type, 'README.md');
77
+ const specLabel = type === 'custom' ? CUSTOM_SPEC : `adapters/${type}/README.md`;
78
+ checks.push(check('adapter-spec', fs.existsSync(spec), fs.existsSync(spec) ? `${specLabel} present` : `missing ${specLabel}`));
79
+
80
+ const tool = toolFor(type);
81
+ if (tool) {
82
+ const result = run(tool.bin, tool.args);
83
+ let detail;
84
+ if (result.error && result.error.code === 'ENOENT') detail = `${tool.bin} not installed (needed by adapter "${type}")`;
85
+ else if (result.error) detail = `${tool.label} failed: ${result.error.message}`;
86
+ else if (result.status !== 0) detail = `${tool.bin} not logged in: \`${tool.label}\` exited ${result.status}`;
87
+ else detail = `${tool.label} ok`;
88
+ checks.push(check('adapter-auth', !result.error && result.status === 0, detail, 'warn'));
89
+ }
90
+
91
+ if (hints.recommended !== type && type !== 'custom') {
92
+ checks.push(check(
93
+ 'adapter-detected',
94
+ false,
95
+ `configured "${type}" but the repo looks like "${hints.recommended}" (${hints.reason}); rerun generate-adapter if that is wrong`,
96
+ 'warn'
97
+ ));
98
+ }
99
+ return checks;
100
+ }
101
+
102
+ module.exports = { KNOWN_TYPES, CUSTOM_SPEC, checkAdapter, nearestType, toolFor };
@@ -0,0 +1,125 @@
1
+ 'use strict';
2
+
3
+ // One adapter detector for `init`, `generate-adapter` and Studio (#62).
4
+ // Priority: origin remote host -> CI files -> standard.
5
+
6
+ const fs = require('fs');
7
+ const path = require('path');
8
+
9
+ const DOT_GITLAB_HOST = 'gitlab.dot.co.id';
10
+
11
+ function readFileSafe(file) {
12
+ try {
13
+ return fs.readFileSync(file, 'utf8');
14
+ } catch {
15
+ return '';
16
+ }
17
+ }
18
+
19
+ // Returns the git config text for rootDir. Follows a `.git` file
20
+ // (`gitdir: ...`) and its `commondir`, so linked worktrees work.
21
+ function readGitConfig(rootDir) {
22
+ const dotGit = path.join(rootDir, '.git');
23
+ let stat;
24
+ try {
25
+ stat = fs.statSync(dotGit);
26
+ } catch {
27
+ return '';
28
+ }
29
+ if (stat.isDirectory()) return readFileSafe(path.join(dotGit, 'config'));
30
+ const match = readFileSafe(dotGit).match(/^gitdir:\s*(.+)$/m);
31
+ if (!match) return '';
32
+ const gitDir = path.resolve(rootDir, match[1].trim());
33
+ const common = readFileSafe(path.join(gitDir, 'commondir')).trim();
34
+ const configDir = common ? path.resolve(gitDir, common) : gitDir;
35
+ return readFileSafe(path.join(configDir, 'config'));
36
+ }
37
+
38
+ // Remote URLs in config order: [{ name, url }].
39
+ function parseRemotes(configText) {
40
+ const remotes = [];
41
+ let current = null;
42
+ for (const raw of String(configText || '').split(/\r?\n/)) {
43
+ const line = raw.trim();
44
+ const section = line.match(/^\[\s*([^\s\]"]+)(?:\s+"([^"]*)")?\s*\]$/);
45
+ if (section) {
46
+ current = section[1].toLowerCase() === 'remote' ? section[2] : null;
47
+ continue;
48
+ }
49
+ if (current === null || current === undefined) continue;
50
+ const kv = line.match(/^url\s*=\s*(.+)$/i);
51
+ if (kv && !remotes.some((remote) => remote.name === current)) {
52
+ remotes.push({ name: current, url: kv[1].trim() });
53
+ }
54
+ }
55
+ return remotes;
56
+ }
57
+
58
+ // `origin` first, otherwise the first remote.
59
+ function readGitRemote(rootDir) {
60
+ const remotes = parseRemotes(readGitConfig(rootDir));
61
+ const origin = remotes.find((remote) => remote.name === 'origin');
62
+ const chosen = origin || remotes[0];
63
+ return chosen ? { name: chosen.name, url: chosen.url } : { name: '', url: '' };
64
+ }
65
+
66
+ function remoteHost(url) {
67
+ const value = String(url || '').trim();
68
+ if (!value) return '';
69
+ const withScheme = value.match(/^[a-z][a-z0-9+.-]*:\/\/(?:[^@/]*@)?([^/:]+)/i);
70
+ if (withScheme) return withScheme[1].toLowerCase();
71
+ const scp = value.match(/^(?:[^@/]+@)?([^/:]+):/);
72
+ return scp ? scp[1].toLowerCase() : '';
73
+ }
74
+
75
+ // Adapter type for a remote URL, or null when the host says nothing.
76
+ function typeFromRemote(url) {
77
+ const host = remoteHost(url);
78
+ if (!host) return null;
79
+ if (host === DOT_GITLAB_HOST) return 'dot';
80
+ if (host === 'github.com') return 'github';
81
+ if (host.includes('gitlab')) return 'gitlab';
82
+ return null;
83
+ }
84
+
85
+ function detectCi(rootDir) {
86
+ if (fs.existsSync(path.join(rootDir, '.github', 'workflows'))) return 'GitHub Actions';
87
+ if (fs.existsSync(path.join(rootDir, '.gitlab-ci.yml'))) return 'GitLab CI';
88
+ return 'none';
89
+ }
90
+
91
+ const CI_TYPES = { 'GitHub Actions': 'github', 'GitLab CI': 'gitlab' };
92
+
93
+ function detectAdapter(rootDir) {
94
+ const remote = readGitRemote(rootDir);
95
+ const ciProvider = detectCi(rootDir);
96
+ const fromRemote = typeFromRemote(remote.url);
97
+ if (fromRemote) {
98
+ return {
99
+ type: fromRemote,
100
+ reason: `remote ${remote.name} host ${remoteHost(remote.url)}`,
101
+ remote: remote.url,
102
+ ciProvider
103
+ };
104
+ }
105
+ if (CI_TYPES[ciProvider]) {
106
+ return { type: CI_TYPES[ciProvider], reason: `CI: ${ciProvider}`, remote: remote.url, ciProvider };
107
+ }
108
+ return {
109
+ type: 'standard',
110
+ reason: remote.url ? `remote host ${remoteHost(remote.url) || '(unknown)'} not recognized; no CI files` : 'no remote; no CI files',
111
+ remote: remote.url,
112
+ ciProvider
113
+ };
114
+ }
115
+
116
+ module.exports = {
117
+ DOT_GITLAB_HOST,
118
+ detectAdapter,
119
+ detectCi,
120
+ parseRemotes,
121
+ readGitConfig,
122
+ readGitRemote,
123
+ remoteHost,
124
+ typeFromRemote
125
+ };
package/lib/doctor.js CHANGED
@@ -5,6 +5,7 @@ const path = require('path');
5
5
  const { loadEvaluationCases } = require('./evaluation.js');
6
6
  const { auditPackage } = require('./package-audit.js');
7
7
  const { listRecipes, loadRecipe, validateRecipe } = require('./recipe.js');
8
+ const { checkAdapter } = require('./adapter-check.js');
8
9
 
9
10
  const REQUIRED_HOST_ASSETS = [
10
11
  '.claude/skills/ai-engineering-loop/SKILL.md',
@@ -27,7 +28,8 @@ const REQUIRED_HOST_ASSETS = [
27
28
  '.agents/skills/animate/SKILL.md',
28
29
  '.agents/skills/review-animations/SKILL.md',
29
30
  'agents/shared/devil-advocate.body.md',
30
- 'agents/shared/judge.body.md'
31
+ 'agents/shared/judge.body.md',
32
+ 'agents/instruction-only/AGENTS.md'
31
33
  ];
32
34
 
33
35
  const REQUIRED_SCHEMAS = [
@@ -49,7 +51,7 @@ function check(id, passed, detail) {
49
51
  return { id, passed: Boolean(passed), detail };
50
52
  }
51
53
 
52
- function runDoctor(rootDir = path.join(__dirname, '..')) {
54
+ function runDoctor(rootDir = path.join(__dirname, '..'), { projectDir = null, run } = {}) {
53
55
  const checks = [];
54
56
  const nodeMajor = Number(process.versions.node.split('.')[0]);
55
57
  checks.push(check('node-version', nodeMajor >= 18, `Node ${process.versions.node}; required >=18`));
@@ -133,8 +135,13 @@ function runDoctor(rootDir = path.join(__dirname, '..')) {
133
135
  (process.platform === 'win32' || (fs.statSync(binPath).mode & 0o111) !== 0);
134
136
  checks.push(check('cli-executable', executable, executable ? 'CLI is executable' : 'CLI executable bit is missing'));
135
137
 
138
+ // Project adapter (#63): only where a project has been initialized.
139
+ if (projectDir && fs.existsSync(path.join(projectDir, '.ai-engineering-loop'))) {
140
+ checks.push(...checkAdapter(projectDir, { packageRoot: rootDir, ...(run ? { run } : {}) }));
141
+ }
142
+
136
143
  return {
137
- ok: checks.every((item) => item.passed),
144
+ ok: checks.every((item) => item.passed || item.level === 'warn'),
138
145
  checks
139
146
  };
140
147
  }
package/lib/gates.js CHANGED
@@ -6,8 +6,33 @@ const path = require('path');
6
6
  const {
7
7
  validateVerificationEvidence,
8
8
  validateFindingLedger,
9
- computeJudgeVerdict
9
+ computeJudgeVerdict,
10
+ EXECUTION_MODES,
11
+ resolveExecutionModeId
10
12
  } = require('./orchestration.js');
13
+
14
+ // Optional `review` block in REPORT_ONLY report.json (#57). Absent = legacy
15
+ // report, accepted. Present = must be truthful and non-contradictory.
16
+ function validateReportReview(review) {
17
+ const errors = [];
18
+ if (review === undefined) return errors;
19
+ if (!review || typeof review !== 'object' || Array.isArray(review)) return ['review must be an object'];
20
+ const modeId = resolveExecutionModeId(review.executionMode);
21
+ const mode = EXECUTION_MODES[modeId];
22
+ if (!review.executionMode || !mode) {
23
+ errors.push(`review.executionMode must be one of ${Object.keys(EXECUTION_MODES).join(', ')}`);
24
+ return errors;
25
+ }
26
+ const native = String(review.nativeSubagent || '').toUpperCase();
27
+ if (native && !['AVAILABLE', 'UNAVAILABLE'].includes(native)) errors.push('review.nativeSubagent must be AVAILABLE or UNAVAILABLE');
28
+ if (mode.isIndependentExecutionProven) {
29
+ if (review.reviewer !== 'devil-advocate') errors.push('review.reviewer must be devil-advocate for an independent report review');
30
+ if (!String(review.childId || '').trim()) errors.push(`review.childId (the reviewer's own subagent/result id) is required for ${modeId}`);
31
+ } else if (native === 'AVAILABLE' && !String(review.reason || '').trim()) {
32
+ errors.push(`review.reason is required: ${modeId} was used although native subagent invocation is AVAILABLE`);
33
+ }
34
+ return errors;
35
+ }
11
36
  const {
12
37
  RUN_STATES,
13
38
  RUN_MODES,
@@ -317,6 +342,7 @@ function applyGate(rootDir, gate, { runId, transitionOptions = {} } = {}) {
317
342
  else if (value.recommendations.some((item) => !String(item || '').trim())) {
318
343
  reportErrors.push('recommendations must contain non-empty strings');
319
344
  }
345
+ reportErrors.push(...validateReportReview(value.review));
320
346
  if (reportErrors.length) throw gateError('Report gate failed', reportErrors);
321
347
  return transitionRun(rootDir, run.runId, RUN_STATES.REPORTED, {
322
348
  gate,
@@ -471,6 +497,7 @@ function applyGate(rootDir, gate, { runId, transitionOptions = {} } = {}) {
471
497
 
472
498
  module.exports = {
473
499
  GATE_FILES,
500
+ validateReportReview,
474
501
  artifactPath,
475
502
  hashContent,
476
503
  hashFile,
@@ -2,41 +2,17 @@
2
2
 
3
3
  const fs = require('fs');
4
4
  const path = require('path');
5
+ const { detectAdapter, typeFromRemote } = require('./adapter-detect.js');
5
6
 
6
7
  const SHIPPED_TYPES = ['standard', 'github', 'gitlab', 'dot'];
7
8
 
8
- function readGitRemote(rootDir) {
9
- const gitConfig = path.join(rootDir, '.git', 'config');
10
- try {
11
- const text = fs.readFileSync(gitConfig, 'utf8');
12
- const match = text.match(/url\s*=\s*(.*)/);
13
- return match ? match[1].trim() : '';
14
- } catch {
15
- return '';
16
- }
17
- }
18
-
19
- function detectCi(rootDir) {
20
- if (fs.existsSync(path.join(rootDir, '.github', 'workflows'))) {
21
- return 'GitHub Actions';
22
- }
23
- if (fs.existsSync(path.join(rootDir, '.gitlab-ci.yml'))) {
24
- return 'GitLab CI';
25
- }
26
- return 'none';
27
- }
28
-
9
+ // Kept for callers that only have a URL. Same rules as the shared detector.
29
10
  function recommendType(remote) {
30
- const url = (remote || '').toLowerCase();
31
- if (url.includes('github.com')) return 'github';
32
- if (url.includes('gitlab')) return 'gitlab';
33
- return 'standard';
11
+ return typeFromRemote(remote) || 'standard';
34
12
  }
35
13
 
36
14
  function detectAdapterHints(rootDir) {
37
- const remote = readGitRemote(rootDir);
38
- const ciProvider = detectCi(rootDir);
39
- const recommended = recommendType(remote);
15
+ const { type: recommended, reason, remote, ciProvider } = detectAdapter(rootDir);
40
16
  let existingType = '';
41
17
  const adapterPath = path.join(rootDir, '.ai-engineering-loop', 'adapter.md');
42
18
  try {
@@ -46,7 +22,7 @@ function detectAdapterHints(rootDir) {
46
22
  } catch {
47
23
  /* missing */
48
24
  }
49
- return { remote, ciProvider, recommended, existingType };
25
+ return { remote, ciProvider, recommended, reason, existingType };
50
26
  }
51
27
 
52
28
  function adapterMarkdown({ type, remote, ciProvider, defaultBranch = 'main' }) {
@@ -91,7 +67,7 @@ function formatGenerateAdapterReport(hints, { version, wrote } = {}) {
91
67
  'Detected',
92
68
  `- remote: ${hints.remote || '(none)'}`,
93
69
  `- ci: ${hints.ciProvider}`,
94
- `- recommended: ${hints.recommended}`,
70
+ `- recommended: ${hints.recommended}${hints.reason ? ` (${hints.reason})` : ''}`,
95
71
  `- existing: ${hints.existingType || '(none)'}`,
96
72
  `Shipped: ${SHIPPED_TYPES.join(' | ')}`,
97
73
  'Next: load skill generate-adapter. Ask Q1-Q5. Wait.',
@@ -13,6 +13,10 @@ const path = require('path');
13
13
 
14
14
  const SOURCE_DIR = 'skill-src/ai-engineering-loop';
15
15
  const SKILL_CHAR_LIMIT = 4000;
16
+ // Compact digest for instruction-only hosts (#60), served by `docs AGENTS`.
17
+ const DIGEST_SOURCE = 'digest.md';
18
+ const DIGEST_PATH = 'agents/instruction-only/AGENTS.md';
19
+ const DIGEST_BYTE_LIMIT = 2048;
16
20
  const GENERATED_NOTE = '<!-- Generated from skill-src/ by npm run build:skills; do not edit. -->';
17
21
 
18
22
  function readText(file) {
@@ -74,6 +78,10 @@ function buildHostSkills(root = path.join(__dirname, '..')) {
74
78
  outputs.push({ path: path.posix.join(dir, 'references', ref.name), content: ref.content, kind: 'reference' });
75
79
  }
76
80
  }
81
+ const digest = `${GENERATED_NOTE}\n${readText(path.join(src, DIGEST_SOURCE)).replace(/\s*$/, '\n')}`;
82
+ const bytes = Buffer.byteLength(digest, 'utf8');
83
+ if (bytes > DIGEST_BYTE_LIMIT) throw new Error(`${DIGEST_PATH}: ${bytes} bytes > ${DIGEST_BYTE_LIMIT}`);
84
+ outputs.push({ path: DIGEST_PATH, content: digest, kind: 'digest' });
77
85
  return outputs;
78
86
  }
79
87
 
@@ -113,6 +121,8 @@ function writeHostSkills(root = path.join(__dirname, '..')) {
113
121
  module.exports = {
114
122
  SOURCE_DIR,
115
123
  SKILL_CHAR_LIMIT,
124
+ DIGEST_PATH,
125
+ DIGEST_BYTE_LIMIT,
116
126
  GENERATED_NOTE,
117
127
  parseOverlay,
118
128
  buildHostSkills,
@@ -34,7 +34,7 @@ function listHosts({ home, env = process.env, selection }) {
34
34
  return {
35
35
  id: host.id,
36
36
  name: host.name,
37
- tier: host.tier,
37
+ certification: host.certification,
38
38
  detected: d.detected,
39
39
  via: [...d.dirs.map((dir) => `~/${dir}`), ...d.bins.map((bin) => `PATH:${path.basename(bin)}`)],
40
40
  enabled: selection.enabled.has(host.id),
@@ -47,10 +47,10 @@ function listHosts({ home, env = process.env, selection }) {
47
47
 
48
48
  function formatHostsList(rows, selection) {
49
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`);
50
+ lines.push(` ${'id'.padEnd(16)} ${'enabled'.padEnd(8)} ${'certification'.padEnd(17)} ${'detected'.padEnd(28)} skills`);
51
51
  for (const row of rows) {
52
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}`);
53
+ lines.push(` ${row.id.padEnd(16)} ${state.padEnd(8)} ${row.certification.padEnd(17)} ${(row.detected ? row.via.join(',') : '-').slice(0, 28).padEnd(28)} ${row.skills}`);
54
54
  }
55
55
  lines.push(`Out of scope (no native skills): ${OUT_OF_SCOPE.map((h) => h.name).join(', ')}.`);
56
56
  return lines.join('\n');
@@ -8,6 +8,7 @@ const crypto = require('crypto');
8
8
  const fs = require('fs');
9
9
  const path = require('path');
10
10
  const { HOSTS, usesSharedSkills } = require('./registry.js');
11
+ const { certificationLabel } = require('./table.js');
11
12
 
12
13
  const CORE_SKILL = 'ai-engineering-loop';
13
14
 
@@ -54,7 +55,7 @@ function hostsDoctor({ home, selection, plan }) {
54
55
  if (!copies.length) problems.push('core skill not installed');
55
56
  if (hashes.size > 1) problems.push(`${copies.length} copies with different content`);
56
57
  if (resync.length) problems.push(`${resync.length} file(s) need sync`);
57
- rows.push({ id: host.id, name: host.name, copies, identical: hashes.size <= 1, resync, ok: problems.length === 0, problems });
58
+ rows.push({ id: host.id, name: host.name, certification: host.certification, certifiedBy: host.certifiedBy || null, copies, identical: hashes.size <= 1, resync, ok: problems.length === 0, problems });
58
59
  }
59
60
  return { ok: rows.every((row) => row.ok), hosts: rows };
60
61
  }
@@ -64,7 +65,7 @@ function formatHostsDoctor(report) {
64
65
  const lines = ['hosts doctor (core skill copies each host can see):'];
65
66
  for (const row of report.hosts) {
66
67
  const where = row.copies.map((c) => c.path).join(', ') || '-';
67
- lines.push(` ${row.ok ? '✓' : '✗'} ${row.id.padEnd(16)} ${row.copies.length} cop${row.copies.length === 1 ? 'y' : 'ies'}${row.copies.length > 1 ? (row.identical ? ' (identical)' : ' (DIFFERENT)') : ''}: ${where}`);
68
+ lines.push(` ${row.ok ? '✓' : '✗'} ${row.id.padEnd(16)} [${certificationLabel(row)}] ${row.copies.length} cop${row.copies.length === 1 ? 'y' : 'ies'}${row.copies.length > 1 ? (row.identical ? ' (identical)' : ' (DIFFERENT)') : ''}: ${where}`);
68
69
  for (const problem of row.problems) lines.push(` ${problem}`);
69
70
  for (const file of row.resync.slice(0, 5)) lines.push(` needs sync: ${file}`);
70
71
  if (row.resync.length > 5) lines.push(` ... and ${row.resync.length - 5} more`);