ai-engineering-loop 1.15.0 → 1.17.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 (61) hide show
  1. package/.agents/skills/ai-engineering-loop/SKILL.md +1 -1
  2. package/.agents/skills/ai-engineering-loop/references/loop-deliver.md +3 -1
  3. package/.agents/skills/ai-engineering-loop/references/loop-goal.md +1 -0
  4. package/.agents/skills/ai-engineering-loop/references/loop-hosts.md +5 -1
  5. package/.agents/skills/ai-engineering-loop/references/loop-maker.md +7 -1
  6. package/.agents/skills/ai-engineering-loop/references/loop-review.md +2 -0
  7. package/.claude/skills/ai-engineering-loop/SKILL.md +1 -1
  8. package/.claude/skills/ai-engineering-loop/references/loop-deliver.md +3 -1
  9. package/.claude/skills/ai-engineering-loop/references/loop-goal.md +1 -0
  10. package/.claude/skills/ai-engineering-loop/references/loop-hosts.md +5 -1
  11. package/.claude/skills/ai-engineering-loop/references/loop-maker.md +7 -1
  12. package/.claude/skills/ai-engineering-loop/references/loop-review.md +2 -0
  13. package/CHANGELOG.md +68 -0
  14. package/README.md +26 -22
  15. package/adapters/README.md +22 -0
  16. package/adapters/dot/README.md +19 -9
  17. package/adapters/dot/gitlab.md +55 -0
  18. package/adapters/dot/mattermost.md +10 -0
  19. package/adapters/dot/skills/dot-dev-workflow/SKILL.md +27 -5
  20. package/adapters/dot/sonar.md +90 -0
  21. package/adapters/generate-adapter/SKILL.md +6 -5
  22. package/adapters/github/pull-request.md +5 -0
  23. package/adapters/gitlab/merge-request.md +5 -0
  24. package/adapters/{dot → quality}/skills/task-impact-inquiry/SKILL.md +12 -7
  25. package/agents/instruction-only/AGENTS.md +24 -0
  26. package/bin/ai-engineering-loop.js +318 -27
  27. package/core/blast-radius-map.md +37 -0
  28. package/core/grill-policy.md +1 -1
  29. package/core/learnings.md +24 -0
  30. package/core/orchestration-model.md +11 -0
  31. package/core/pr-receipt.md +35 -0
  32. package/core/runtime-safety.md +24 -0
  33. package/lib/adapter-check.js +102 -0
  34. package/lib/adapter-detect.js +125 -0
  35. package/lib/cli-args.js +5 -1
  36. package/lib/doctor.js +14 -4
  37. package/lib/gates.js +67 -1
  38. package/lib/generate-adapter.js +6 -30
  39. package/lib/guard-hooks.js +115 -0
  40. package/lib/guard.js +336 -0
  41. package/lib/host-skill-build.js +10 -0
  42. package/lib/hosts/commands.js +5 -4
  43. package/lib/hosts/doctor.js +4 -3
  44. package/lib/hosts/registry.js +69 -23
  45. package/lib/hosts/table.js +15 -5
  46. package/lib/impact-map.js +501 -0
  47. package/lib/learn.js +303 -0
  48. package/lib/orchestration.js +39 -6
  49. package/lib/receipt.js +362 -0
  50. package/lib/safe-context.js +14 -0
  51. package/lib/smart-context.js +21 -0
  52. package/lib/studio-server.js +1 -0
  53. package/lib/sync-hosts.js +2 -1
  54. package/package.json +1 -1
  55. package/schemas/delivery.schema.json +11 -1
  56. package/schemas/finding-ledger.schema.json +2 -1
  57. package/schemas/goal-contract.schema.json +9 -0
  58. package/schemas/impact-map.schema.json +78 -0
  59. package/schemas/learnings.schema.json +47 -0
  60. package/schemas/receipt.schema.json +102 -0
  61. package/schemas/report.schema.json +52 -5
@@ -19,6 +19,30 @@ npx ai-engineering-loop run --mode unattended "task"
19
19
 
20
20
  The repository policy lives at `.ai-engineering-loop/runtime-policy.json`. Invalid policy fails closed. Do not change a policy merely because an agent asks to bypass a gate.
21
21
 
22
+ ## Runtime guardrails (scope freeze and destructive commands)
23
+
24
+ Gates check artifacts after a stage. The guard checks each tool call **before** it runs:
25
+
26
+ ```bash
27
+ npx ai-engineering-loop guard check --tool edit --path src/list.js
28
+ npx ai-engineering-loop guard check --tool bash --command "git push --force"
29
+ npx ai-engineering-loop hooks install # Claude Code: .claude/settings.json PreToolUse hook
30
+ npx ai-engineering-loop hooks status | uninstall
31
+ ```
32
+
33
+ | Check | Rule |
34
+ |---|---|
35
+ | Edit / Write / MultiEdit / NotebookEdit | Blocked or warned when the file is outside the Run scope or matches `scope.deniedPaths`. `.ai-engineering-loop/` (Run artifacts) is always writable. A `REPORT_ONLY` Run may not edit at all. |
36
+ | Bash | `rm` with recursive + force flags, `DROP TABLE/DATABASE/SCHEMA`, `TRUNCATE`, `git push --force` / `-f` / `--force-with-lease` / `+refspec`, `git reset --hard`, `git clean` with `-f` and `-d`. |
37
+
38
+ **Scope** = the frozen Goal's optional `scope.allowedPaths` plus the confirmed blast-radius map (`impact confirm`, see `docs blast-radius-map`). `scope.deniedPaths` always applies. A Goal without `scope` and without a confirmed map has no path enforcement (backward compatible). Globs: `**` crosses directories, `*` and `?` stay inside one segment, a trailing `/` is a directory prefix; paths are repository-relative.
39
+
40
+ **Decision** by Run mode: `ASSISTED` → `warn` (the Claude hook answers `ask`, so the human decides); `UNATTENDED` and `REPORT_ONLY` → `block` (`deny`; CLI exit code 2). With no active Run the policy `defaultMode` applies and nothing is recorded.
41
+
42
+ **Evidence:** every warn and block is appended to `RUN_DIR/guard-events.json` (tool, rule ids, reasons, mode, redacted repository-relative target). `gate <name>` prints the counts and `--json` returns `guard: { warn, block, rules }`.
43
+
44
+ **Enforced vs advisory:** only hosts with a native pre-tool hook API are **enforced** (Claude Code today, `hooks` in `lib/hosts/registry.js`). Every other host is **advisory**: the loop instructions ask the agent to run `guard check` itself, and nothing stops a call it skips. `hosts list`, `hosts doctor`, and the README host table show the column. The guard is not a sandbox: it does not isolate the OS or the network; UNATTENDED still uses the disposable worktree.
45
+
22
46
  ## Token budget and emergency stop
23
47
 
24
48
  Check the budget once after `run` and again before each new iteration, and record provider-reported usage whenever the host returns it:
@@ -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/cli-args.js CHANGED
@@ -21,8 +21,12 @@ const WRITER_COMMANDS = Object.freeze({
21
21
  'run:abandon': { flags: ['--abandon', '--yes', '--json'], valued: ['--run', '--reason', '--by'], positionals: [] },
22
22
  migrate: { flags: ['--json', '--dry-run'], valued: ['--from'], positionals: [] },
23
23
  verify: { flags: ['--json', '--serial', '--shell'], valued: ['--run', '--cmd', '--timeout-ms'], positionals: [] },
24
+ learn: { flags: ['--json', '--dry-run', '--prune'], valued: ['--max-age-runs'], positionals: [] },
25
+ guard: { flags: ['--json'], valued: ['--run', '--tool', '--input', '--path', '--command', '--hook'], positionals: ['check'] },
26
+ hooks: { flags: ['--json'], valued: ['--host'], positionals: ['install', 'uninstall', 'status'] },
27
+ impact: { flags: ['--json', '--force'], valued: ['--run', '--by', '--reason', '--allow', '--remove', '--limit'], positionals: ['map', 'show', 'confirm', 'skip', 'drift'] },
24
28
  'review-pack': { flags: ['--json'], valued: ['--run', '--base', '--profile'], positionals: [] },
25
- deliver: { flags: ['--json', '--approve'], valued: ['--run', '--destination', '--summary', '--by'], positionals: [] },
29
+ deliver: { flags: ['--json', '--approve'], valued: ['--run', '--destination', '--summary', '--by', '--host', '--model', '--head', '--evidence'], positionals: [] },
26
30
  'generate-adapter': { flags: [], valued: ['--type'], positionals: [] },
27
31
  'generate-workflow': { flags: ['--write'], valued: [], positionals: [] }
28
32
  });
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 = [
@@ -42,14 +44,17 @@ const REQUIRED_SCHEMAS = [
42
44
  'compiled-plan.schema.json',
43
45
  'workflow-state.schema.json',
44
46
  'workflow-event.schema.json',
45
- 'handoff.schema.json'
47
+ 'handoff.schema.json',
48
+ 'impact-map.schema.json',
49
+ 'receipt.schema.json',
50
+ 'learnings.schema.json'
46
51
  ];
47
52
 
48
53
  function check(id, passed, detail) {
49
54
  return { id, passed: Boolean(passed), detail };
50
55
  }
51
56
 
52
- function runDoctor(rootDir = path.join(__dirname, '..')) {
57
+ function runDoctor(rootDir = path.join(__dirname, '..'), { projectDir = null, run } = {}) {
53
58
  const checks = [];
54
59
  const nodeMajor = Number(process.versions.node.split('.')[0]);
55
60
  checks.push(check('node-version', nodeMajor >= 18, `Node ${process.versions.node}; required >=18`));
@@ -133,8 +138,13 @@ function runDoctor(rootDir = path.join(__dirname, '..')) {
133
138
  (process.platform === 'win32' || (fs.statSync(binPath).mode & 0o111) !== 0);
134
139
  checks.push(check('cli-executable', executable, executable ? 'CLI is executable' : 'CLI executable bit is missing'));
135
140
 
141
+ // Project adapter (#63): only where a project has been initialized.
142
+ if (projectDir && fs.existsSync(path.join(projectDir, '.ai-engineering-loop'))) {
143
+ checks.push(...checkAdapter(projectDir, { packageRoot: rootDir, ...(run ? { run } : {}) }));
144
+ }
145
+
136
146
  return {
137
- ok: checks.every((item) => item.passed),
147
+ ok: checks.every((item) => item.passed || item.level === 'warn'),
138
148
  checks
139
149
  };
140
150
  }
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,
@@ -132,9 +157,29 @@ function validateGoalContract(contract) {
132
157
  }
133
158
  });
134
159
  }
160
+ errors.push(...validateGoalScope(contract.scope));
135
161
  return { valid: errors.length === 0, errors };
136
162
  }
137
163
 
164
+ // Optional Goal scope (#59): absent = no path enforcement.
165
+ function validateGoalScope(scope) {
166
+ if (scope === undefined) return [];
167
+ if (!scope || typeof scope !== 'object' || Array.isArray(scope)) return ['scope must be an object'];
168
+ const errors = [];
169
+ for (const key of Object.keys(scope)) {
170
+ if (!['allowedPaths', 'deniedPaths'].includes(key)) errors.push(`scope.${key} is not supported (use allowedPaths, deniedPaths)`);
171
+ }
172
+ for (const key of ['allowedPaths', 'deniedPaths']) {
173
+ if (scope[key] === undefined) continue;
174
+ if (!Array.isArray(scope[key]) || scope[key].some((item) => typeof item !== 'string' || !item.trim())) {
175
+ errors.push(`scope.${key} must be an array of non-empty glob strings`);
176
+ } else if (scope[key].some((item) => item.startsWith('/') || item.split('/').includes('..'))) {
177
+ errors.push(`scope.${key} globs must be repository-relative`);
178
+ }
179
+ }
180
+ return errors;
181
+ }
182
+
138
183
  function validateVerificationBundle(bundle, run, diffHash, currentRevision) {
139
184
  const errors = [];
140
185
  requireRunMetadata(bundle, run, 'verification');
@@ -285,6 +330,24 @@ function writeDeterministicVerdictIfEligible(rootDir, run) {
285
330
  return true;
286
331
  }
287
332
 
333
+ // Out-of-map changes recorded by verify (#71) become LOW ledger warnings,
334
+ // so they reach the Judge and the receipt without blocking delivery.
335
+ function mergeImpactDrift(rootDir, run) {
336
+ const { loadImpactDrift, mergeDriftIntoLedger } = require('./impact-map.js');
337
+ const drift = loadImpactDrift(rootDir, run.runId);
338
+ const filePath = artifactPath(rootDir, run.runId, GATE_FILES.review);
339
+ if (!drift?.outOfMap?.length || !fs.existsSync(filePath)) return 0;
340
+ let ledger;
341
+ try {
342
+ ledger = JSON.parse(fs.readFileSync(filePath, 'utf8'));
343
+ } catch {
344
+ return 0;
345
+ }
346
+ const merged = mergeDriftIntoLedger(ledger, drift);
347
+ if (merged.added) fs.writeFileSync(filePath, `${JSON.stringify(merged.ledger, null, 2)}\n`, { mode: 0o600 });
348
+ return merged.added;
349
+ }
350
+
288
351
  function applyGate(rootDir, gate, { runId, transitionOptions = {} } = {}) {
289
352
  if (!Object.hasOwn(GATE_FILES, gate)) {
290
353
  throw gateError(`Unknown gate: ${gate}. Use ${Object.keys(GATE_FILES).join('|')}`);
@@ -317,6 +380,7 @@ function applyGate(rootDir, gate, { runId, transitionOptions = {} } = {}) {
317
380
  else if (value.recommendations.some((item) => !String(item || '').trim())) {
318
381
  reportErrors.push('recommendations must contain non-empty strings');
319
382
  }
383
+ reportErrors.push(...validateReportReview(value.review));
320
384
  if (reportErrors.length) throw gateError('Report gate failed', reportErrors);
321
385
  return transitionRun(rootDir, run.runId, RUN_STATES.REPORTED, {
322
386
  gate,
@@ -386,6 +450,7 @@ function applyGate(rootDir, gate, { runId, transitionOptions = {} } = {}) {
386
450
  assertArtifactCurrent(rootDir, run, 'diff');
387
451
  assertArtifactCurrent(rootDir, run, 'verification');
388
452
  if (tierOf(run) === 'T0') writeT0FindingLedger(rootDir, run);
453
+ mergeImpactDrift(rootDir, run);
389
454
  const { filePath, value } = readJsonArtifact(rootDir, run.runId, GATE_FILES.review);
390
455
  requireRunMetadata(value, run, 'Finding Ledger');
391
456
  if (value.diffHash !== run.artifacts.diff?.sha256) {
@@ -471,6 +536,7 @@ function applyGate(rootDir, gate, { runId, transitionOptions = {} } = {}) {
471
536
 
472
537
  module.exports = {
473
538
  GATE_FILES,
539
+ validateReportReview,
474
540
  artifactPath,
475
541
  hashContent,
476
542
  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.',
@@ -0,0 +1,115 @@
1
+ 'use strict';
2
+
3
+ // `hooks install | uninstall | status` (#59): native pre-tool hooks that call
4
+ // `guard check`. Claude Code first; hosts without a hook API stay advisory.
5
+ // Project-level settings, because the guard reads this repository's Run.
6
+
7
+ const fs = require('fs');
8
+ const path = require('path');
9
+ const { HOSTS, getHost, guardrailSupport } = require('./hosts/registry.js');
10
+
11
+ const HOOK_MARKER = 'ai-engineering-loop guard check';
12
+ const CLAUDE_MATCHER = 'Edit|Write|MultiEdit|NotebookEdit|Bash';
13
+ const CLAUDE_COMMAND = 'npx --yes ai-engineering-loop guard check --hook claude';
14
+
15
+ function hooksError(message, code = 'INVALID_USAGE') {
16
+ const error = new Error(message);
17
+ error.code = code;
18
+ return error;
19
+ }
20
+
21
+ function hookHost(hostId = 'claude') {
22
+ const host = getHost(hostId);
23
+ if (!host) throw hooksError(`Unknown host: ${hostId}`);
24
+ if (guardrailSupport(host) !== 'enforced') {
25
+ const enforced = HOSTS.filter((item) => guardrailSupport(item) === 'enforced').map((item) => item.id);
26
+ throw hooksError(`${host.name} has no hook API; its guardrails are advisory. Hosts with hooks: ${enforced.join(', ')}`, 'HOOKS_UNSUPPORTED');
27
+ }
28
+ return host;
29
+ }
30
+
31
+ function settingsPath(rootDir, host) {
32
+ return path.join(rootDir, host.hooks.settings);
33
+ }
34
+
35
+ function readSettings(filePath) {
36
+ if (!fs.existsSync(filePath)) return {};
37
+ const stat = fs.lstatSync(filePath);
38
+ if (stat.isSymbolicLink() || !stat.isFile()) throw hooksError(`${filePath} must be a regular file`, 'UNSAFE_HOOKS_PATH');
39
+ try {
40
+ const value = JSON.parse(fs.readFileSync(filePath, 'utf8'));
41
+ if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error('not an object');
42
+ return value;
43
+ } catch (cause) {
44
+ throw hooksError(`Cannot update ${path.basename(filePath)}: ${cause.message}. Nothing was written.`, 'INVALID_HOOKS_SETTINGS');
45
+ }
46
+ }
47
+
48
+ function writeSettings(filePath, value) {
49
+ fs.mkdirSync(path.dirname(filePath), { recursive: true });
50
+ const temporary = `${filePath}.${process.pid}.tmp`;
51
+ fs.writeFileSync(temporary, `${JSON.stringify(value, null, 2)}\n`);
52
+ fs.renameSync(temporary, filePath);
53
+ }
54
+
55
+ function isOurHook(hook) {
56
+ return typeof hook?.command === 'string' && hook.command.includes(HOOK_MARKER);
57
+ }
58
+
59
+ function ourEntries(settings) {
60
+ return (settings.hooks?.PreToolUse || []).filter((entry) => (entry.hooks || []).some(isOurHook));
61
+ }
62
+
63
+ function hooksStatus(rootDir, { host: hostId = 'claude' } = {}) {
64
+ const host = hookHost(hostId);
65
+ const filePath = settingsPath(rootDir, host);
66
+ const settings = readSettings(filePath);
67
+ return {
68
+ host: host.id,
69
+ guardrails: guardrailSupport(host),
70
+ settings: host.hooks.settings,
71
+ installed: ourEntries(settings).length > 0
72
+ };
73
+ }
74
+
75
+ function installHooks(rootDir, { host: hostId = 'claude' } = {}) {
76
+ const host = hookHost(hostId);
77
+ const filePath = settingsPath(rootDir, host);
78
+ const settings = readSettings(filePath);
79
+ if (ourEntries(settings).length) return { ...hooksStatus(rootDir, { host: host.id }), changed: false };
80
+ const hooks = settings.hooks && typeof settings.hooks === 'object' ? settings.hooks : {};
81
+ const preToolUse = Array.isArray(hooks.PreToolUse) ? hooks.PreToolUse : [];
82
+ writeSettings(filePath, {
83
+ ...settings,
84
+ hooks: {
85
+ ...hooks,
86
+ PreToolUse: [...preToolUse, { matcher: CLAUDE_MATCHER, hooks: [{ type: 'command', command: CLAUDE_COMMAND }] }]
87
+ }
88
+ });
89
+ return { ...hooksStatus(rootDir, { host: host.id }), changed: true };
90
+ }
91
+
92
+ function uninstallHooks(rootDir, { host: hostId = 'claude' } = {}) {
93
+ const host = hookHost(hostId);
94
+ const filePath = settingsPath(rootDir, host);
95
+ if (!fs.existsSync(filePath)) return { ...hooksStatus(rootDir, { host: host.id }), changed: false };
96
+ const settings = readSettings(filePath);
97
+ if (!ourEntries(settings).length) return { ...hooksStatus(rootDir, { host: host.id }), changed: false };
98
+ const preToolUse = settings.hooks.PreToolUse
99
+ .map((entry) => ({ ...entry, hooks: (entry.hooks || []).filter((hook) => !isOurHook(hook)) }))
100
+ .filter((entry) => entry.hooks.length);
101
+ const { PreToolUse: _removed, ...otherHooks } = settings.hooks;
102
+ const hooks = preToolUse.length ? { ...otherHooks, PreToolUse: preToolUse } : otherHooks;
103
+ const { hooks: _old, ...rest } = settings;
104
+ writeSettings(filePath, Object.keys(hooks).length ? { ...rest, hooks } : rest);
105
+ return { ...hooksStatus(rootDir, { host: host.id }), changed: true };
106
+ }
107
+
108
+ module.exports = {
109
+ HOOK_MARKER,
110
+ CLAUDE_COMMAND,
111
+ CLAUDE_MATCHER,
112
+ hooksStatus,
113
+ installHooks,
114
+ uninstallHooks
115
+ };