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/lib/guard.js
ADDED
|
@@ -0,0 +1,336 @@
|
|
|
1
|
+
'use strict';
|
|
2
|
+
|
|
3
|
+
// Runtime guardrails (#59). `guard check` decides allow | warn | block for one
|
|
4
|
+
// tool call before it runs: Edit/Write outside the Run's scope, and Bash
|
|
5
|
+
// commands that destroy files, history, or data. ASSISTED warns (the host
|
|
6
|
+
// asks the human), UNATTENDED and REPORT_ONLY block. Every warn/block is
|
|
7
|
+
// appended to the Run as evidence.
|
|
8
|
+
|
|
9
|
+
const fs = require('fs');
|
|
10
|
+
const path = require('path');
|
|
11
|
+
const { RUN_MODES, TERMINAL_STATES, atomicWriteJson, getCurrentRun, loadRun, runsDir } = require('./run-state.js');
|
|
12
|
+
const { loadPolicy } = require('./runtime-policy.js');
|
|
13
|
+
const { redactHomePaths, redactSecrets } = require('./safe-context.js');
|
|
14
|
+
const { impactScope, loadImpactMap, matchesAnyGlob } = require('./impact-map.js');
|
|
15
|
+
|
|
16
|
+
const GUARD_EVENTS_FILE = 'guard-events.json';
|
|
17
|
+
const MAX_EVENTS = 500;
|
|
18
|
+
const MAX_TARGET_CHARS = 300;
|
|
19
|
+
const DECISIONS = Object.freeze(['allow', 'warn', 'block']);
|
|
20
|
+
const EDIT_TOOLS = new Set(['edit', 'write', 'multiedit', 'notebookedit']);
|
|
21
|
+
const BASH_TOOLS = new Set(['bash', 'shell']);
|
|
22
|
+
|
|
23
|
+
function guardError(message, code = 'INVALID_USAGE') {
|
|
24
|
+
const error = new Error(message);
|
|
25
|
+
error.code = code;
|
|
26
|
+
return error;
|
|
27
|
+
}
|
|
28
|
+
|
|
29
|
+
function normalizeTool(tool) {
|
|
30
|
+
const value = String(tool || '').trim().toLowerCase();
|
|
31
|
+
if (EDIT_TOOLS.has(value)) return 'edit';
|
|
32
|
+
if (BASH_TOOLS.has(value)) return 'bash';
|
|
33
|
+
return value ? 'other' : null;
|
|
34
|
+
}
|
|
35
|
+
|
|
36
|
+
// Accepts a Claude Code PreToolUse payload ({ tool_name, tool_input }) or a
|
|
37
|
+
// plain { path } / { command } object.
|
|
38
|
+
function parseGuardInput(input, tool) {
|
|
39
|
+
const value = input && typeof input === 'object' ? input : {};
|
|
40
|
+
const toolInput = value.tool_input && typeof value.tool_input === 'object' ? value.tool_input : value;
|
|
41
|
+
const kind = normalizeTool(tool || value.tool_name);
|
|
42
|
+
if (!kind) throw guardError('guard check needs --tool edit|bash or a payload with tool_name');
|
|
43
|
+
return {
|
|
44
|
+
tool: kind,
|
|
45
|
+
toolName: value.tool_name || tool,
|
|
46
|
+
path: toolInput.file_path || toolInput.notebook_path || toolInput.path || null,
|
|
47
|
+
command: typeof toolInput.command === 'string' ? toolInput.command : null
|
|
48
|
+
};
|
|
49
|
+
}
|
|
50
|
+
|
|
51
|
+
// Shell segments split on ; && || | and newlines; quotes are kept simple on
|
|
52
|
+
// purpose: a quoted "rm -rf" still warns, which errs on the safe side.
|
|
53
|
+
function segments(command) {
|
|
54
|
+
return String(command || '')
|
|
55
|
+
.split(/\n|;|&&|\|\||\|/)
|
|
56
|
+
.map((part) => part.trim().split(/\s+/).filter(Boolean).map((token) => token.replace(/^['"]|['"]$/g, '')))
|
|
57
|
+
.filter((tokens) => tokens.length);
|
|
58
|
+
}
|
|
59
|
+
|
|
60
|
+
function shortFlags(tokens) {
|
|
61
|
+
return tokens.filter((token) => /^-[A-Za-z]+$/.test(token)).join('').replace(/-/g, '');
|
|
62
|
+
}
|
|
63
|
+
|
|
64
|
+
function commandIndex(tokens, name) {
|
|
65
|
+
return tokens.findIndex((token) => token === name || token.endsWith(`/${name}`));
|
|
66
|
+
}
|
|
67
|
+
|
|
68
|
+
function gitSubcommand(tokens) {
|
|
69
|
+
const start = commandIndex(tokens, 'git');
|
|
70
|
+
if (start === -1) return null;
|
|
71
|
+
for (let index = start + 1; index < tokens.length; index += 1) {
|
|
72
|
+
const token = tokens[index];
|
|
73
|
+
if (token === '-C' || token === '-c') {
|
|
74
|
+
index += 1;
|
|
75
|
+
continue;
|
|
76
|
+
}
|
|
77
|
+
if (token.startsWith('-')) continue;
|
|
78
|
+
return { name: token, args: tokens.slice(index + 1) };
|
|
79
|
+
}
|
|
80
|
+
return null;
|
|
81
|
+
}
|
|
82
|
+
|
|
83
|
+
const DESTRUCTIVE_RULES = Object.freeze([
|
|
84
|
+
{
|
|
85
|
+
id: 'rm-recursive-force',
|
|
86
|
+
reason: 'rm with recursive and force flags deletes files without confirmation',
|
|
87
|
+
test: (tokens) => {
|
|
88
|
+
const start = commandIndex(tokens, 'rm');
|
|
89
|
+
if (start === -1) return false;
|
|
90
|
+
const args = tokens.slice(start + 1);
|
|
91
|
+
const flags = shortFlags(args);
|
|
92
|
+
const recursive = /[rR]/.test(flags) || args.includes('--recursive');
|
|
93
|
+
const force = flags.includes('f') || args.includes('--force');
|
|
94
|
+
return recursive && force;
|
|
95
|
+
}
|
|
96
|
+
},
|
|
97
|
+
{
|
|
98
|
+
id: 'git-push-force',
|
|
99
|
+
reason: 'git push --force rewrites remote history',
|
|
100
|
+
test: (tokens) => {
|
|
101
|
+
const git = gitSubcommand(tokens);
|
|
102
|
+
if (git?.name !== 'push') return false;
|
|
103
|
+
return git.args.some((arg) => arg === '--force' || arg.startsWith('--force-with-lease') ||
|
|
104
|
+
arg === '--force-if-includes' || (/^-[A-Za-z]+$/.test(arg) && arg.includes('f')) ||
|
|
105
|
+
(/^\+[^\s]/.test(arg)));
|
|
106
|
+
}
|
|
107
|
+
},
|
|
108
|
+
{
|
|
109
|
+
id: 'git-reset-hard',
|
|
110
|
+
reason: 'git reset --hard discards uncommitted work',
|
|
111
|
+
test: (tokens) => {
|
|
112
|
+
const git = gitSubcommand(tokens);
|
|
113
|
+
return git?.name === 'reset' && git.args.includes('--hard');
|
|
114
|
+
}
|
|
115
|
+
},
|
|
116
|
+
{
|
|
117
|
+
id: 'git-clean-force',
|
|
118
|
+
reason: 'git clean -fd deletes untracked files and directories',
|
|
119
|
+
test: (tokens) => {
|
|
120
|
+
const git = gitSubcommand(tokens);
|
|
121
|
+
if (git?.name !== 'clean') return false;
|
|
122
|
+
const flags = shortFlags(git.args);
|
|
123
|
+
const force = flags.includes('f') || git.args.includes('--force');
|
|
124
|
+
const dirs = flags.includes('d');
|
|
125
|
+
return force && dirs;
|
|
126
|
+
}
|
|
127
|
+
}
|
|
128
|
+
]);
|
|
129
|
+
|
|
130
|
+
const SQL_RULES = Object.freeze([
|
|
131
|
+
{ id: 'sql-drop', reason: 'DROP TABLE/DATABASE/SCHEMA destroys data', pattern: /\bdrop\s+(?:table|database|schema)\b/i },
|
|
132
|
+
{ id: 'sql-truncate', reason: 'TRUNCATE deletes every row of a table', pattern: /\btruncate\s+(?:table\s+)?[`"'[]?[A-Za-z_]/i }
|
|
133
|
+
]);
|
|
134
|
+
|
|
135
|
+
function destructiveFindings(command) {
|
|
136
|
+
const findings = new Map();
|
|
137
|
+
for (const tokens of segments(command)) {
|
|
138
|
+
for (const rule of DESTRUCTIVE_RULES) {
|
|
139
|
+
if (rule.test(tokens)) findings.set(rule.id, rule.reason);
|
|
140
|
+
}
|
|
141
|
+
}
|
|
142
|
+
for (const rule of SQL_RULES) {
|
|
143
|
+
if (rule.pattern.test(String(command || ''))) findings.set(rule.id, rule.reason);
|
|
144
|
+
}
|
|
145
|
+
return [...findings].map(([id, reason]) => ({ id, reason }));
|
|
146
|
+
}
|
|
147
|
+
|
|
148
|
+
function activeRun(rootDir, runId) {
|
|
149
|
+
if (runId) return loadRun(rootDir, runId);
|
|
150
|
+
const current = getCurrentRun(rootDir);
|
|
151
|
+
return current && !TERMINAL_STATES.has(current.state) ? current : null;
|
|
152
|
+
}
|
|
153
|
+
|
|
154
|
+
function readFrozenGoal(rootDir, run) {
|
|
155
|
+
const filePath = path.join(runsDir(rootDir), run.runId, 'goal-contract.json');
|
|
156
|
+
if (!fs.existsSync(filePath)) return null;
|
|
157
|
+
try {
|
|
158
|
+
return JSON.parse(fs.readFileSync(filePath, 'utf8'));
|
|
159
|
+
} catch {
|
|
160
|
+
return null;
|
|
161
|
+
}
|
|
162
|
+
}
|
|
163
|
+
|
|
164
|
+
// Allowed = the frozen Goal's scope.allowedPaths plus the confirmed impact
|
|
165
|
+
// map (#71); denied = the Goal's scope.deniedPaths. No allowed list means no
|
|
166
|
+
// path enforcement, but denied paths always apply.
|
|
167
|
+
function runScope(rootDir, run) {
|
|
168
|
+
if (!run) return { allowedPaths: null, deniedPaths: [], sources: [] };
|
|
169
|
+
const goal = readFrozenGoal(rootDir, run);
|
|
170
|
+
const mapScope = impactScope(loadImpactMap(rootDir, run.runId));
|
|
171
|
+
const sources = [];
|
|
172
|
+
let allowed = null;
|
|
173
|
+
if (Array.isArray(goal?.scope?.allowedPaths)) {
|
|
174
|
+
allowed = [...goal.scope.allowedPaths];
|
|
175
|
+
sources.push('goal');
|
|
176
|
+
}
|
|
177
|
+
if (mapScope) {
|
|
178
|
+
allowed = [...(allowed || []), ...mapScope.allowedPaths];
|
|
179
|
+
sources.push('impact-map');
|
|
180
|
+
}
|
|
181
|
+
return {
|
|
182
|
+
allowedPaths: allowed ? [...new Set(allowed)].sort() : null,
|
|
183
|
+
deniedPaths: Array.isArray(goal?.scope?.deniedPaths) ? [...goal.scope.deniedPaths] : [],
|
|
184
|
+
sources
|
|
185
|
+
};
|
|
186
|
+
}
|
|
187
|
+
|
|
188
|
+
// Real path of a file that may not exist yet: resolve the nearest existing
|
|
189
|
+
// ancestor (macOS /var -> /private/var, symlinked checkouts) and re-append.
|
|
190
|
+
function realish(target) {
|
|
191
|
+
let current = path.resolve(target);
|
|
192
|
+
const rest = [];
|
|
193
|
+
for (;;) {
|
|
194
|
+
try {
|
|
195
|
+
return path.join(fs.realpathSync(current), ...rest);
|
|
196
|
+
} catch {
|
|
197
|
+
const parent = path.dirname(current);
|
|
198
|
+
if (parent === current) return path.resolve(target);
|
|
199
|
+
rest.unshift(path.basename(current));
|
|
200
|
+
current = parent;
|
|
201
|
+
}
|
|
202
|
+
}
|
|
203
|
+
}
|
|
204
|
+
|
|
205
|
+
function repoRelative(rootDir, filePath) {
|
|
206
|
+
const absolute = path.resolve(rootDir, String(filePath));
|
|
207
|
+
const pairs = [[path.resolve(rootDir), absolute], [realish(rootDir), realish(absolute)]];
|
|
208
|
+
for (const [root, target] of pairs) {
|
|
209
|
+
const rel = path.relative(root, target);
|
|
210
|
+
if (rel !== '..' && !rel.startsWith(`..${path.sep}`) && !path.isAbsolute(rel)) return rel.split(path.sep).join('/');
|
|
211
|
+
}
|
|
212
|
+
return null;
|
|
213
|
+
}
|
|
214
|
+
|
|
215
|
+
function scopeFindings(rootDir, filePath, scope) {
|
|
216
|
+
if (!filePath) return [];
|
|
217
|
+
const relative = repoRelative(rootDir, filePath);
|
|
218
|
+
if (relative != null && (relative === '.ai-engineering-loop' || relative.startsWith('.ai-engineering-loop/'))) return [];
|
|
219
|
+
if (relative == null) {
|
|
220
|
+
return scope.allowedPaths ? [{ id: 'outside-repository', reason: 'edit target is outside the repository and the Run scope' }] : [];
|
|
221
|
+
}
|
|
222
|
+
if (matchesAnyGlob(relative, scope.deniedPaths)) {
|
|
223
|
+
return [{ id: 'scope-denied', reason: `${relative} matches scope.deniedPaths` }];
|
|
224
|
+
}
|
|
225
|
+
if (scope.allowedPaths && !matchesAnyGlob(relative, scope.allowedPaths)) {
|
|
226
|
+
return [{ id: 'scope-outside', reason: `${relative} is outside the Run scope (${scope.sources.join(' + ')})` }];
|
|
227
|
+
}
|
|
228
|
+
return [];
|
|
229
|
+
}
|
|
230
|
+
|
|
231
|
+
function decisionFor(mode, findings) {
|
|
232
|
+
if (!findings.length) return 'allow';
|
|
233
|
+
return mode === RUN_MODES.ASSISTED ? 'warn' : 'block';
|
|
234
|
+
}
|
|
235
|
+
|
|
236
|
+
function safeTarget(parsed, rootDir) {
|
|
237
|
+
const raw = parsed.tool === 'bash' ? parsed.command : (repoRelative(rootDir, parsed.path || '') ?? parsed.path);
|
|
238
|
+
return redactHomePaths(redactSecrets(String(raw || '')).text).slice(0, MAX_TARGET_CHARS);
|
|
239
|
+
}
|
|
240
|
+
|
|
241
|
+
function recordGuardEvent(rootDir, runId, event) {
|
|
242
|
+
const filePath = path.join(runsDir(rootDir), runId, GUARD_EVENTS_FILE);
|
|
243
|
+
let events = [];
|
|
244
|
+
if (fs.existsSync(filePath)) {
|
|
245
|
+
try {
|
|
246
|
+
const parsed = JSON.parse(fs.readFileSync(filePath, 'utf8'));
|
|
247
|
+
if (Array.isArray(parsed.events)) events = parsed.events;
|
|
248
|
+
} catch {
|
|
249
|
+
events = [];
|
|
250
|
+
}
|
|
251
|
+
}
|
|
252
|
+
events.push(event);
|
|
253
|
+
atomicWriteJson(filePath, { schemaVersion: 1, runId, events: events.slice(-MAX_EVENTS) });
|
|
254
|
+
}
|
|
255
|
+
|
|
256
|
+
function checkGuard(rootDir, { tool, input, runId, now = new Date() } = {}) {
|
|
257
|
+
const parsed = parseGuardInput(input, tool);
|
|
258
|
+
const run = activeRun(rootDir, runId);
|
|
259
|
+
const mode = run?.mode || loadPolicy(rootDir).defaultMode;
|
|
260
|
+
let findings = [];
|
|
261
|
+
if (parsed.tool === 'edit') {
|
|
262
|
+
if (run && mode === RUN_MODES.REPORT_ONLY) {
|
|
263
|
+
findings.push({ id: 'report-only-mutation', reason: 'REPORT_ONLY runs must not edit the repository' });
|
|
264
|
+
}
|
|
265
|
+
findings.push(...scopeFindings(rootDir, parsed.path, runScope(rootDir, run)));
|
|
266
|
+
} else if (parsed.tool === 'bash') {
|
|
267
|
+
findings = destructiveFindings(parsed.command);
|
|
268
|
+
}
|
|
269
|
+
const decision = decisionFor(mode, findings);
|
|
270
|
+
const result = {
|
|
271
|
+
decision,
|
|
272
|
+
tool: parsed.tool,
|
|
273
|
+
mode,
|
|
274
|
+
runId: run?.runId || null,
|
|
275
|
+
rules: findings.map((item) => item.id),
|
|
276
|
+
reasons: findings.map((item) => item.reason)
|
|
277
|
+
};
|
|
278
|
+
if (run && decision !== 'allow') {
|
|
279
|
+
recordGuardEvent(rootDir, run.runId, {
|
|
280
|
+
at: now.toISOString(),
|
|
281
|
+
tool: parsed.toolName || parsed.tool,
|
|
282
|
+
decision,
|
|
283
|
+
mode,
|
|
284
|
+
rules: result.rules,
|
|
285
|
+
reasons: result.reasons,
|
|
286
|
+
target: safeTarget(parsed, rootDir)
|
|
287
|
+
});
|
|
288
|
+
}
|
|
289
|
+
return result;
|
|
290
|
+
}
|
|
291
|
+
|
|
292
|
+
function loadGuardEvents(rootDir, runId) {
|
|
293
|
+
const filePath = path.join(runsDir(rootDir), runId, GUARD_EVENTS_FILE);
|
|
294
|
+
if (!fs.existsSync(filePath)) return [];
|
|
295
|
+
try {
|
|
296
|
+
const parsed = JSON.parse(fs.readFileSync(filePath, 'utf8'));
|
|
297
|
+
return Array.isArray(parsed.events) ? parsed.events : [];
|
|
298
|
+
} catch {
|
|
299
|
+
return [];
|
|
300
|
+
}
|
|
301
|
+
}
|
|
302
|
+
|
|
303
|
+
function guardSummary(rootDir, runId) {
|
|
304
|
+
const events = loadGuardEvents(rootDir, runId);
|
|
305
|
+
return {
|
|
306
|
+
warn: events.filter((event) => event.decision === 'warn').length,
|
|
307
|
+
block: events.filter((event) => event.decision === 'block').length,
|
|
308
|
+
rules: [...new Set(events.flatMap((event) => event.rules || []))].sort()
|
|
309
|
+
};
|
|
310
|
+
}
|
|
311
|
+
|
|
312
|
+
// Claude Code PreToolUse output: deny blocks the call, ask hands it to the
|
|
313
|
+
// human, and allow prints nothing so the normal permission flow continues.
|
|
314
|
+
function claudeHookOutput(result) {
|
|
315
|
+
if (result.decision === 'allow') return null;
|
|
316
|
+
return {
|
|
317
|
+
hookSpecificOutput: {
|
|
318
|
+
hookEventName: 'PreToolUse',
|
|
319
|
+
permissionDecision: result.decision === 'block' ? 'deny' : 'ask',
|
|
320
|
+
permissionDecisionReason: `ai-engineering-loop guard (${result.mode}): ${result.reasons.join('; ')}`
|
|
321
|
+
}
|
|
322
|
+
};
|
|
323
|
+
}
|
|
324
|
+
|
|
325
|
+
module.exports = {
|
|
326
|
+
DECISIONS,
|
|
327
|
+
GUARD_EVENTS_FILE,
|
|
328
|
+
DESTRUCTIVE_RULES,
|
|
329
|
+
parseGuardInput,
|
|
330
|
+
destructiveFindings,
|
|
331
|
+
runScope,
|
|
332
|
+
checkGuard,
|
|
333
|
+
loadGuardEvents,
|
|
334
|
+
guardSummary,
|
|
335
|
+
claudeHookOutput
|
|
336
|
+
};
|
package/lib/host-skill-build.js
CHANGED
|
@@ -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,
|
package/lib/hosts/commands.js
CHANGED
|
@@ -5,7 +5,7 @@
|
|
|
5
5
|
// then runs the normal sync (manifest-based copy and cleanup).
|
|
6
6
|
|
|
7
7
|
const path = require('path');
|
|
8
|
-
const { HOSTS, HOST_IDS, OUT_OF_SCOPE, SHARED_SKILLS_DIR, getHost, usesSharedSkills } = require('./registry.js');
|
|
8
|
+
const { HOSTS, HOST_IDS, OUT_OF_SCOPE, SHARED_SKILLS_DIR, getHost, guardrailSupport, usesSharedSkills } = require('./registry.js');
|
|
9
9
|
const { detectHosts } = require('./detect.js');
|
|
10
10
|
const { readUserConfig, writeUserConfig } = require('../user-state.js');
|
|
11
11
|
|
|
@@ -34,7 +34,8 @@ function listHosts({ home, env = process.env, selection }) {
|
|
|
34
34
|
return {
|
|
35
35
|
id: host.id,
|
|
36
36
|
name: host.name,
|
|
37
|
-
|
|
37
|
+
certification: host.certification,
|
|
38
|
+
guardrails: guardrailSupport(host),
|
|
38
39
|
detected: d.detected,
|
|
39
40
|
via: [...d.dirs.map((dir) => `~/${dir}`), ...d.bins.map((bin) => `PATH:${path.basename(bin)}`)],
|
|
40
41
|
enabled: selection.enabled.has(host.id),
|
|
@@ -47,10 +48,10 @@ function listHosts({ home, env = process.env, selection }) {
|
|
|
47
48
|
|
|
48
49
|
function formatHostsList(rows, selection) {
|
|
49
50
|
const lines = [`Hosts (${selection.source === 'config' ? `saved selection, mode ${selection.mode}` : 'no setup yet: hosts with a config folder are synced'})`];
|
|
50
|
-
lines.push(` ${'id'.padEnd(16)} ${'enabled'.padEnd(8)} ${'detected'.padEnd(28)} skills`);
|
|
51
|
+
lines.push(` ${'id'.padEnd(16)} ${'enabled'.padEnd(8)} ${'certification'.padEnd(17)} ${'guardrails'.padEnd(10)} ${'detected'.padEnd(28)} skills`);
|
|
51
52
|
for (const row of rows) {
|
|
52
53
|
const state = row.enabled ? 'yes' : row.disabled ? 'off' : '-';
|
|
53
|
-
lines.push(` ${row.id.padEnd(16)} ${state.padEnd(8)} ${(row.detected ? row.via.join(',') : '-').slice(0, 28).padEnd(28)} ${row.skills}`);
|
|
54
|
+
lines.push(` ${row.id.padEnd(16)} ${state.padEnd(8)} ${row.certification.padEnd(17)} ${row.guardrails.padEnd(10)} ${(row.detected ? row.via.join(',') : '-').slice(0, 28).padEnd(28)} ${row.skills}`);
|
|
54
55
|
}
|
|
55
56
|
lines.push(`Out of scope (no native skills): ${OUT_OF_SCOPE.map((h) => h.name).join(', ')}.`);
|
|
56
57
|
return lines.join('\n');
|
package/lib/hosts/doctor.js
CHANGED
|
@@ -7,7 +7,8 @@
|
|
|
7
7
|
const crypto = require('crypto');
|
|
8
8
|
const fs = require('fs');
|
|
9
9
|
const path = require('path');
|
|
10
|
-
const { HOSTS, usesSharedSkills } = require('./registry.js');
|
|
10
|
+
const { HOSTS, guardrailSupport, 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, guardrails: guardrailSupport(host), 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)}, guardrails ${row.guardrails}] ${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`);
|
package/lib/hosts/registry.js
CHANGED
|
@@ -13,26 +13,39 @@
|
|
|
13
13
|
// used by `hosts doctor` and the one-copy-per-host test.
|
|
14
14
|
// - `agents`: reviewer subagent format and directory, or null when the host
|
|
15
15
|
// has no file-based custom subagents.
|
|
16
|
-
// - `docs` / `verified`: sources checked, and when.
|
|
16
|
+
// - `docs` / `verified`: sources checked, and when (docs only, not a run).
|
|
17
|
+
// - `certification` (#60): 'full' = a real recipes/default.json run completed
|
|
18
|
+
// on this host with reviewer subagents and every gate, recorded in
|
|
19
|
+
// `certifiedBy: { recipe, aelVersion, date }`; 'experimental' = reviewer
|
|
20
|
+
// subagents are installed but no such run is recorded; 'instruction-only' =
|
|
21
|
+
// no file-based subagents, the loop runs CONTEXT_ISOLATION_ONLY. Promote a
|
|
22
|
+
// host to 'full' only with a run record.
|
|
23
|
+
// - `hooks` (#59): native pre-tool hook API that `ael hooks install` writes
|
|
24
|
+
// to, or absent. A host with hooks gets **enforced** runtime guardrails;
|
|
25
|
+
// every other host is **advisory** (the loop instructions only).
|
|
17
26
|
|
|
18
27
|
const SHARED_SKILLS_DIR = '.agents/skills';
|
|
28
|
+
const CERTIFICATIONS = Object.freeze(['full', 'experimental', 'instruction-only']);
|
|
19
29
|
|
|
20
30
|
const HOSTS = Object.freeze([
|
|
21
31
|
{
|
|
22
32
|
id: 'claude',
|
|
23
33
|
name: 'Claude Code',
|
|
24
|
-
|
|
34
|
+
certification: 'experimental',
|
|
35
|
+
certifiedBy: null,
|
|
25
36
|
detect: { dirs: ['.claude'], bins: ['claude'] },
|
|
26
37
|
skills: { dir: '.claude/skills' },
|
|
27
38
|
reads: ['.claude/skills'],
|
|
28
39
|
agents: { format: 'claude-md', dir: '.claude/agents' },
|
|
29
|
-
|
|
40
|
+
hooks: { format: 'claude-pretooluse', settings: '.claude/settings.json' },
|
|
41
|
+
docs: ['https://code.claude.com/docs/en/skills', 'https://code.claude.com/docs/en/sub-agents', 'https://code.claude.com/docs/en/hooks'],
|
|
30
42
|
verified: '2026-10-11'
|
|
31
43
|
},
|
|
32
44
|
{
|
|
33
45
|
id: 'codex',
|
|
34
46
|
name: 'Codex CLI',
|
|
35
|
-
|
|
47
|
+
certification: 'experimental',
|
|
48
|
+
certifiedBy: null,
|
|
36
49
|
detect: { dirs: ['.codex'], bins: ['codex'] },
|
|
37
50
|
skills: 'shared',
|
|
38
51
|
reads: ['.agents/skills'],
|
|
@@ -43,7 +56,8 @@ const HOSTS = Object.freeze([
|
|
|
43
56
|
{
|
|
44
57
|
id: 'gemini',
|
|
45
58
|
name: 'Gemini CLI',
|
|
46
|
-
|
|
59
|
+
certification: 'experimental',
|
|
60
|
+
certifiedBy: null,
|
|
47
61
|
detect: { dirs: ['.gemini'], bins: ['gemini'] },
|
|
48
62
|
skills: 'shared',
|
|
49
63
|
reads: ['.gemini/skills', '.agents/skills'],
|
|
@@ -54,7 +68,8 @@ const HOSTS = Object.freeze([
|
|
|
54
68
|
{
|
|
55
69
|
id: 'antigravity',
|
|
56
70
|
name: 'Antigravity (IDE / 2.0)',
|
|
57
|
-
|
|
71
|
+
certification: 'experimental',
|
|
72
|
+
certifiedBy: null,
|
|
58
73
|
detect: { dirs: ['.gemini/antigravity'], bins: ['antigravity'] },
|
|
59
74
|
skills: { dir: '.gemini/config/skills' },
|
|
60
75
|
reads: ['.gemini/config/skills'],
|
|
@@ -65,7 +80,8 @@ const HOSTS = Object.freeze([
|
|
|
65
80
|
{
|
|
66
81
|
id: 'antigravity-cli',
|
|
67
82
|
name: 'Antigravity CLI (agy)',
|
|
68
|
-
|
|
83
|
+
certification: 'experimental',
|
|
84
|
+
certifiedBy: null,
|
|
69
85
|
detect: { dirs: ['.gemini/antigravity-cli'], bins: ['agy'] },
|
|
70
86
|
skills: { dir: '.gemini/antigravity-cli/skills' },
|
|
71
87
|
reads: ['.gemini/antigravity-cli/skills'],
|
|
@@ -76,7 +92,8 @@ const HOSTS = Object.freeze([
|
|
|
76
92
|
{
|
|
77
93
|
id: 'grok',
|
|
78
94
|
name: 'Grok CLI',
|
|
79
|
-
|
|
95
|
+
certification: 'experimental',
|
|
96
|
+
certifiedBy: null,
|
|
80
97
|
detect: { dirs: ['.grok'], bins: ['grok'] },
|
|
81
98
|
skills: 'shared',
|
|
82
99
|
reads: ['.grok/skills', '.claude/skills', '.agents/skills'],
|
|
@@ -87,7 +104,8 @@ const HOSTS = Object.freeze([
|
|
|
87
104
|
{
|
|
88
105
|
id: 'cursor',
|
|
89
106
|
name: 'Cursor (editor + CLI)',
|
|
90
|
-
|
|
107
|
+
certification: 'experimental',
|
|
108
|
+
certifiedBy: null,
|
|
91
109
|
// The CLI installs `agent` plus a legacy `cursor-agent` link; `agent` is too
|
|
92
110
|
// generic to count as evidence on its own.
|
|
93
111
|
detect: { dirs: ['.cursor'], bins: ['cursor-agent', 'cursor'] },
|
|
@@ -100,7 +118,8 @@ const HOSTS = Object.freeze([
|
|
|
100
118
|
{
|
|
101
119
|
id: 'copilot',
|
|
102
120
|
name: 'GitHub Copilot (CLI / VS Code)',
|
|
103
|
-
|
|
121
|
+
certification: 'experimental',
|
|
122
|
+
certifiedBy: null,
|
|
104
123
|
detect: { dirs: ['.copilot'], bins: ['copilot'] },
|
|
105
124
|
skills: 'shared',
|
|
106
125
|
reads: ['.copilot/skills', '.agents/skills'],
|
|
@@ -112,7 +131,8 @@ const HOSTS = Object.freeze([
|
|
|
112
131
|
{
|
|
113
132
|
id: 'opencode',
|
|
114
133
|
name: 'OpenCode',
|
|
115
|
-
|
|
134
|
+
certification: 'experimental',
|
|
135
|
+
certifiedBy: null,
|
|
116
136
|
detect: { dirs: ['.config/opencode'], bins: ['opencode'] },
|
|
117
137
|
skills: 'shared',
|
|
118
138
|
reads: ['.config/opencode/skills', '.claude/skills', '.agents/skills'],
|
|
@@ -123,7 +143,8 @@ const HOSTS = Object.freeze([
|
|
|
123
143
|
{
|
|
124
144
|
id: 'windsurf',
|
|
125
145
|
name: 'Windsurf / Devin Desktop',
|
|
126
|
-
|
|
146
|
+
certification: 'instruction-only',
|
|
147
|
+
certifiedBy: null,
|
|
127
148
|
// No CLI binary is documented; detect by config folder only.
|
|
128
149
|
detect: { dirs: ['.codeium/windsurf', '.config/devin'], bins: [] },
|
|
129
150
|
skills: 'shared',
|
|
@@ -135,7 +156,8 @@ const HOSTS = Object.freeze([
|
|
|
135
156
|
{
|
|
136
157
|
id: 'amp',
|
|
137
158
|
name: 'Amp',
|
|
138
|
-
|
|
159
|
+
certification: 'instruction-only',
|
|
160
|
+
certifiedBy: null,
|
|
139
161
|
detect: { dirs: ['.config/amp'], bins: ['amp'] },
|
|
140
162
|
skills: 'shared',
|
|
141
163
|
reads: ['.config/agents/skills', '.agents/skills', '.config/amp/skills', '.claude/skills'],
|
|
@@ -147,7 +169,8 @@ const HOSTS = Object.freeze([
|
|
|
147
169
|
{
|
|
148
170
|
id: 'factory',
|
|
149
171
|
name: 'Factory Droid',
|
|
150
|
-
|
|
172
|
+
certification: 'experimental',
|
|
173
|
+
certifiedBy: null,
|
|
151
174
|
detect: { dirs: ['.factory'], bins: ['droid'] },
|
|
152
175
|
skills: 'shared',
|
|
153
176
|
reads: ['.factory/skills', '.agents/skills'],
|
|
@@ -158,7 +181,8 @@ const HOSTS = Object.freeze([
|
|
|
158
181
|
{
|
|
159
182
|
id: 'augment',
|
|
160
183
|
name: 'Augment (Auggie)',
|
|
161
|
-
|
|
184
|
+
certification: 'experimental',
|
|
185
|
+
certifiedBy: null,
|
|
162
186
|
detect: { dirs: ['.augment'], bins: ['auggie'] },
|
|
163
187
|
skills: 'shared',
|
|
164
188
|
reads: ['.augment/skills', '.claude/skills', '.agents/skills'],
|
|
@@ -169,7 +193,8 @@ const HOSTS = Object.freeze([
|
|
|
169
193
|
{
|
|
170
194
|
id: 'zed',
|
|
171
195
|
name: 'Zed',
|
|
172
|
-
|
|
196
|
+
certification: 'instruction-only',
|
|
197
|
+
certifiedBy: null,
|
|
173
198
|
detect: { dirs: ['.config/zed', 'Library/Application Support/Zed'], bins: ['zed'] },
|
|
174
199
|
skills: 'shared',
|
|
175
200
|
reads: ['.agents/skills'],
|
|
@@ -180,7 +205,8 @@ const HOSTS = Object.freeze([
|
|
|
180
205
|
{
|
|
181
206
|
id: 'goose',
|
|
182
207
|
name: 'Goose',
|
|
183
|
-
|
|
208
|
+
certification: 'instruction-only',
|
|
209
|
+
certifiedBy: null,
|
|
184
210
|
detect: { dirs: ['.config/goose'], bins: ['goose'] },
|
|
185
211
|
skills: 'shared',
|
|
186
212
|
reads: ['.agents/skills', '.config/goose/skills', '.config/agents/skills', '.claude/skills'],
|
|
@@ -194,7 +220,8 @@ const HOSTS = Object.freeze([
|
|
|
194
220
|
{
|
|
195
221
|
id: 'cline',
|
|
196
222
|
name: 'Cline',
|
|
197
|
-
|
|
223
|
+
certification: 'instruction-only',
|
|
224
|
+
certifiedBy: null,
|
|
198
225
|
detect: { dirs: ['.cline'], bins: ['cline'] },
|
|
199
226
|
skills: { dir: '.cline/skills' },
|
|
200
227
|
reads: ['.cline/skills'],
|
|
@@ -206,7 +233,8 @@ const HOSTS = Object.freeze([
|
|
|
206
233
|
{
|
|
207
234
|
id: 'roo',
|
|
208
235
|
name: 'Roo Code',
|
|
209
|
-
|
|
236
|
+
certification: 'instruction-only',
|
|
237
|
+
certifiedBy: null,
|
|
210
238
|
detect: { dirs: ['.roo'], bins: [] },
|
|
211
239
|
skills: 'shared',
|
|
212
240
|
reads: ['.roo/skills', '.agents/skills'],
|
|
@@ -218,7 +246,8 @@ const HOSTS = Object.freeze([
|
|
|
218
246
|
{
|
|
219
247
|
id: 'kiro',
|
|
220
248
|
name: 'Kiro (IDE + CLI)',
|
|
221
|
-
|
|
249
|
+
certification: 'experimental',
|
|
250
|
+
certifiedBy: null,
|
|
222
251
|
detect: { dirs: ['.kiro'], bins: ['kiro-cli', 'kiro'] },
|
|
223
252
|
skills: { dir: '.kiro/skills' },
|
|
224
253
|
reads: ['.kiro/skills'],
|
|
@@ -229,7 +258,8 @@ const HOSTS = Object.freeze([
|
|
|
229
258
|
{
|
|
230
259
|
id: 'qwen',
|
|
231
260
|
name: 'Qwen Code',
|
|
232
|
-
|
|
261
|
+
certification: 'experimental',
|
|
262
|
+
certifiedBy: null,
|
|
233
263
|
detect: { dirs: ['.qwen'], bins: ['qwen'] },
|
|
234
264
|
skills: { dir: '.qwen/skills' },
|
|
235
265
|
reads: ['.qwen/skills'],
|
|
@@ -242,7 +272,8 @@ const HOSTS = Object.freeze([
|
|
|
242
272
|
{
|
|
243
273
|
id: 'junie',
|
|
244
274
|
name: 'JetBrains Junie',
|
|
245
|
-
|
|
275
|
+
certification: 'experimental',
|
|
276
|
+
certifiedBy: null,
|
|
246
277
|
detect: { dirs: ['.junie'], bins: ['junie'] },
|
|
247
278
|
skills: 'shared',
|
|
248
279
|
reads: ['.junie/skills', '.agents/skills'],
|
|
@@ -268,4 +299,19 @@ function usesSharedSkills(host) {
|
|
|
268
299
|
return host.skills === 'shared';
|
|
269
300
|
}
|
|
270
301
|
|
|
271
|
-
|
|
302
|
+
// 'enforced' = native hooks block or ask before a tool runs; 'advisory' = the
|
|
303
|
+
// guardrail lives in the loop instructions only.
|
|
304
|
+
function guardrailSupport(host) {
|
|
305
|
+
return host?.hooks ? 'enforced' : 'advisory';
|
|
306
|
+
}
|
|
307
|
+
|
|
308
|
+
module.exports = {
|
|
309
|
+
CERTIFICATIONS,
|
|
310
|
+
HOSTS,
|
|
311
|
+
HOST_IDS,
|
|
312
|
+
OUT_OF_SCOPE,
|
|
313
|
+
SHARED_SKILLS_DIR,
|
|
314
|
+
getHost,
|
|
315
|
+
guardrailSupport,
|
|
316
|
+
usesSharedSkills
|
|
317
|
+
};
|