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.
- package/.agents/skills/ai-engineering-loop/SKILL.md +1 -1
- package/.agents/skills/ai-engineering-loop/references/loop-deliver.md +3 -1
- package/.agents/skills/ai-engineering-loop/references/loop-goal.md +1 -0
- package/.agents/skills/ai-engineering-loop/references/loop-hosts.md +5 -1
- package/.agents/skills/ai-engineering-loop/references/loop-maker.md +7 -1
- package/.agents/skills/ai-engineering-loop/references/loop-review.md +2 -0
- package/.claude/skills/ai-engineering-loop/SKILL.md +1 -1
- package/.claude/skills/ai-engineering-loop/references/loop-deliver.md +3 -1
- package/.claude/skills/ai-engineering-loop/references/loop-goal.md +1 -0
- package/.claude/skills/ai-engineering-loop/references/loop-hosts.md +5 -1
- package/.claude/skills/ai-engineering-loop/references/loop-maker.md +7 -1
- package/.claude/skills/ai-engineering-loop/references/loop-review.md +2 -0
- package/CHANGELOG.md +68 -0
- package/README.md +26 -22
- package/adapters/README.md +22 -0
- package/adapters/dot/README.md +19 -9
- package/adapters/dot/gitlab.md +55 -0
- package/adapters/dot/mattermost.md +10 -0
- package/adapters/dot/skills/dot-dev-workflow/SKILL.md +27 -5
- package/adapters/dot/sonar.md +90 -0
- package/adapters/generate-adapter/SKILL.md +6 -5
- package/adapters/github/pull-request.md +5 -0
- package/adapters/gitlab/merge-request.md +5 -0
- package/adapters/{dot → quality}/skills/task-impact-inquiry/SKILL.md +12 -7
- package/agents/instruction-only/AGENTS.md +24 -0
- package/bin/ai-engineering-loop.js +318 -27
- package/core/blast-radius-map.md +37 -0
- package/core/grill-policy.md +1 -1
- package/core/learnings.md +24 -0
- package/core/orchestration-model.md +11 -0
- package/core/pr-receipt.md +35 -0
- package/core/runtime-safety.md +24 -0
- package/lib/adapter-check.js +102 -0
- package/lib/adapter-detect.js +125 -0
- package/lib/cli-args.js +5 -1
- package/lib/doctor.js +14 -4
- package/lib/gates.js +67 -1
- package/lib/generate-adapter.js +6 -30
- package/lib/guard-hooks.js +115 -0
- package/lib/guard.js +336 -0
- package/lib/host-skill-build.js +10 -0
- package/lib/hosts/commands.js +5 -4
- package/lib/hosts/doctor.js +4 -3
- package/lib/hosts/registry.js +69 -23
- package/lib/hosts/table.js +15 -5
- package/lib/impact-map.js +501 -0
- package/lib/learn.js +303 -0
- package/lib/orchestration.js +39 -6
- package/lib/receipt.js +362 -0
- package/lib/safe-context.js +14 -0
- package/lib/smart-context.js +21 -0
- package/lib/studio-server.js +1 -0
- package/lib/sync-hosts.js +2 -1
- package/package.json +1 -1
- package/schemas/delivery.schema.json +11 -1
- package/schemas/finding-ledger.schema.json +2 -1
- package/schemas/goal-contract.schema.json +9 -0
- package/schemas/impact-map.schema.json +78 -0
- package/schemas/learnings.schema.json +47 -0
- package/schemas/receipt.schema.json +102 -0
- package/schemas/report.schema.json +52 -5
package/core/runtime-safety.md
CHANGED
|
@@ -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,
|
package/lib/generate-adapter.js
CHANGED
|
@@ -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
|
-
|
|
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
|
-
|
|
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 =
|
|
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
|
+
};
|