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/receipt.js
ADDED
|
@@ -0,0 +1,362 @@
|
|
|
1
|
+
'use strict';
|
|
2
|
+
|
|
3
|
+
// Proof-carrying PR receipt (#70). `deliver` writes RUN_DIR/receipt.json:
|
|
4
|
+
// the frozen Goal and its hash, per-AC evidence, the DA/Judge result, base and
|
|
5
|
+
// head SHA, the sha256 of every referenced artifact, and an overall digest.
|
|
6
|
+
// `verify-receipt` re-checks all of it, so a reviewer (or CI) can trust the
|
|
7
|
+
// PR body without re-reading the Run.
|
|
8
|
+
|
|
9
|
+
const crypto = require('crypto');
|
|
10
|
+
const fs = require('fs');
|
|
11
|
+
const path = require('path');
|
|
12
|
+
const { execFileSync } = require('child_process');
|
|
13
|
+
const { getCurrentRun, loadRun, runsDir } = require('./run-state.js');
|
|
14
|
+
const { canonicalJson, sha256 } = require('./recipe.js');
|
|
15
|
+
const { parseClaimedVsReality } = require('./claimed-vs-reality.js');
|
|
16
|
+
const { redactHomePaths, redactSecrets } = require('./safe-context.js');
|
|
17
|
+
const { isBlockingFinding } = require('./orchestration.js');
|
|
18
|
+
|
|
19
|
+
const RECEIPT_FILE = 'receipt.json';
|
|
20
|
+
const RECEIPT_MARKDOWN_FILE = 'receipt.md';
|
|
21
|
+
const CLAIMED_VS_REALITY = '.ai-engineering-loop/tasks/claimed-vs-reality.md';
|
|
22
|
+
const RUN_ARTIFACTS = Object.freeze([
|
|
23
|
+
['goalContract', 'goal-contract.json', true],
|
|
24
|
+
['diff', 'diff.patch', true],
|
|
25
|
+
['verification', 'verification.json', true],
|
|
26
|
+
['findings', 'findings.json', true],
|
|
27
|
+
['verdict', 'verdict.json', true],
|
|
28
|
+
['impactMap', 'impact-map.json', false],
|
|
29
|
+
['impactDrift', 'impact-drift.json', false],
|
|
30
|
+
['guardEvents', 'guard-events.json', false]
|
|
31
|
+
]);
|
|
32
|
+
const MAX_TEXT = 500;
|
|
33
|
+
|
|
34
|
+
function receiptError(message, code = 'RECEIPT_FAILED', details = []) {
|
|
35
|
+
const error = new Error(message);
|
|
36
|
+
error.code = code;
|
|
37
|
+
error.details = details;
|
|
38
|
+
return error;
|
|
39
|
+
}
|
|
40
|
+
|
|
41
|
+
function resolveRun(rootDir, runId) {
|
|
42
|
+
if (runId) return loadRun(rootDir, runId);
|
|
43
|
+
const current = getCurrentRun(rootDir);
|
|
44
|
+
if (!current) throw receiptError('No current Run. Pass --run <id>.', 'NO_CURRENT_RUN');
|
|
45
|
+
return current;
|
|
46
|
+
}
|
|
47
|
+
|
|
48
|
+
function hashBytes(buffer) {
|
|
49
|
+
return crypto.createHash('sha256').update(buffer).digest('hex');
|
|
50
|
+
}
|
|
51
|
+
|
|
52
|
+
function repoRelative(rootDir, filePath) {
|
|
53
|
+
return path.relative(rootDir, filePath).split(path.sep).join('/');
|
|
54
|
+
}
|
|
55
|
+
|
|
56
|
+
// Receipts leave the machine: no secrets and no local absolute paths.
|
|
57
|
+
function safeText(value) {
|
|
58
|
+
return redactHomePaths(redactSecrets(String(value ?? '')).text)
|
|
59
|
+
.replace(/(?:^|\s)\/(?:tmp|var|private|Users|home)\/\S*/g, ' [REDACTED PATH]')
|
|
60
|
+
.trim()
|
|
61
|
+
.slice(0, MAX_TEXT);
|
|
62
|
+
}
|
|
63
|
+
|
|
64
|
+
function readJson(filePath, label) {
|
|
65
|
+
try {
|
|
66
|
+
return JSON.parse(fs.readFileSync(filePath, 'utf8'));
|
|
67
|
+
} catch (cause) {
|
|
68
|
+
throw receiptError(`${label} is missing or invalid: ${cause.message}`, 'RECEIPT_INPUT_MISSING');
|
|
69
|
+
}
|
|
70
|
+
}
|
|
71
|
+
|
|
72
|
+
function gitHead(rootDir) {
|
|
73
|
+
try {
|
|
74
|
+
return execFileSync('git', ['rev-parse', 'HEAD'], { cwd: rootDir, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
|
|
75
|
+
} catch {
|
|
76
|
+
return null;
|
|
77
|
+
}
|
|
78
|
+
}
|
|
79
|
+
|
|
80
|
+
function validateLink(url) {
|
|
81
|
+
let parsed;
|
|
82
|
+
try {
|
|
83
|
+
parsed = new URL(String(url));
|
|
84
|
+
} catch {
|
|
85
|
+
parsed = null;
|
|
86
|
+
}
|
|
87
|
+
if (!parsed || !['https:', 'http:'].includes(parsed.protocol) || parsed.username || parsed.password) {
|
|
88
|
+
throw receiptError(`Evidence links must be hosted http(s) URLs without credentials: ${safeText(url)}`, 'INVALID_EVIDENCE_LINK');
|
|
89
|
+
}
|
|
90
|
+
return parsed.toString();
|
|
91
|
+
}
|
|
92
|
+
|
|
93
|
+
// `--evidence AC-1=https://ci.example/run/1` (repeatable).
|
|
94
|
+
function parseEvidenceLinks(values = []) {
|
|
95
|
+
const links = {};
|
|
96
|
+
for (const value of values) {
|
|
97
|
+
const match = String(value).match(/^(AC-\d+)=(.+)$/);
|
|
98
|
+
if (!match) throw receiptError(`--evidence must be AC-N=<https-url>, received ${safeText(value)}`, 'INVALID_EVIDENCE_LINK');
|
|
99
|
+
(links[match[1]] ||= []).push(validateLink(match[2]));
|
|
100
|
+
}
|
|
101
|
+
return links;
|
|
102
|
+
}
|
|
103
|
+
|
|
104
|
+
function artifactEntries(rootDir, run) {
|
|
105
|
+
const directory = path.join(runsDir(rootDir), run.runId);
|
|
106
|
+
const entries = [];
|
|
107
|
+
for (const [name, file, required] of RUN_ARTIFACTS) {
|
|
108
|
+
const filePath = path.join(directory, file);
|
|
109
|
+
if (!fs.existsSync(filePath)) {
|
|
110
|
+
if (required) throw receiptError(`Receipt needs ${file}; finish the gates first`, 'RECEIPT_INPUT_MISSING');
|
|
111
|
+
continue;
|
|
112
|
+
}
|
|
113
|
+
entries.push({ name, path: repoRelative(rootDir, filePath), sha256: hashBytes(fs.readFileSync(filePath)) });
|
|
114
|
+
}
|
|
115
|
+
const claimed = path.join(rootDir, CLAIMED_VS_REALITY);
|
|
116
|
+
if (fs.existsSync(claimed)) {
|
|
117
|
+
entries.push({ name: 'claimedVsReality', path: CLAIMED_VS_REALITY, sha256: hashBytes(fs.readFileSync(claimed)) });
|
|
118
|
+
}
|
|
119
|
+
return entries;
|
|
120
|
+
}
|
|
121
|
+
|
|
122
|
+
function commandEvidence(command) {
|
|
123
|
+
return {
|
|
124
|
+
type: 'command',
|
|
125
|
+
command: safeText(command.command),
|
|
126
|
+
exitCode: command.exitCode,
|
|
127
|
+
timeoutStatus: command.timeoutStatus,
|
|
128
|
+
outputSha256: sha256(`${command.stdout || ''}\n${command.stderr || ''}`),
|
|
129
|
+
passed: command.exitCode === 0 && command.timeoutStatus === 'COMPLETED'
|
|
130
|
+
};
|
|
131
|
+
}
|
|
132
|
+
|
|
133
|
+
// Optional coverage numbers from verification.json (e.g. { lines: 91.2,
|
|
134
|
+
// linesDelta: 0.4 }); only finite numbers are kept, never paths or text.
|
|
135
|
+
function coverageSummary(coverage) {
|
|
136
|
+
if (!coverage || typeof coverage !== 'object' || Array.isArray(coverage)) return null;
|
|
137
|
+
const numbers = Object.entries(coverage).filter(([key, value]) => /^[A-Za-z0-9_-]{1,40}$/.test(key) && Number.isFinite(value));
|
|
138
|
+
return numbers.length ? Object.fromEntries(numbers.sort(([a], [b]) => a.localeCompare(b))) : null;
|
|
139
|
+
}
|
|
140
|
+
|
|
141
|
+
function criterionEntry(criterion, { commands, claims, links }) {
|
|
142
|
+
const claim = claims.find((row) => row.ac === criterion.id);
|
|
143
|
+
const evidence = [];
|
|
144
|
+
const missing = [];
|
|
145
|
+
if (claim && String(claim.reality || '').trim()) {
|
|
146
|
+
evidence.push({ type: 'claim', claimed: safeText(claim.claimed), reality: safeText(claim.reality) });
|
|
147
|
+
} else {
|
|
148
|
+
missing.push('no claimed-vs-reality row with a Reality cell');
|
|
149
|
+
}
|
|
150
|
+
if (!commands.length) missing.push('no recorded verification command');
|
|
151
|
+
else if (commands.some((item) => !item.passed)) missing.push('a verification command did not pass');
|
|
152
|
+
evidence.push(...commands);
|
|
153
|
+
for (const url of links[criterion.id] || []) evidence.push({ type: 'link', url });
|
|
154
|
+
return {
|
|
155
|
+
id: criterion.id,
|
|
156
|
+
statement: safeText(criterion.statement),
|
|
157
|
+
evidenceRequired: safeText(criterion.evidenceRequired),
|
|
158
|
+
status: missing.length ? 'MISSING' : 'PASS',
|
|
159
|
+
...(missing.length ? { missing } : {}),
|
|
160
|
+
evidence
|
|
161
|
+
};
|
|
162
|
+
}
|
|
163
|
+
|
|
164
|
+
function receiptDigest(receipt) {
|
|
165
|
+
const { digest: _digest, ...body } = receipt;
|
|
166
|
+
return sha256(canonicalJson(body));
|
|
167
|
+
}
|
|
168
|
+
|
|
169
|
+
function buildReceipt(rootDir, { runId, host, model, head, evidenceLinks = [], aelVersion, now = new Date() } = {}) {
|
|
170
|
+
const run = resolveRun(rootDir, runId);
|
|
171
|
+
const directory = path.join(runsDir(rootDir), run.runId);
|
|
172
|
+
const artifacts = artifactEntries(rootDir, run);
|
|
173
|
+
const goalFile = path.join(directory, 'goal-contract.json');
|
|
174
|
+
const goal = readJson(goalFile, 'goal-contract.json');
|
|
175
|
+
const verification = readJson(path.join(directory, 'verification.json'), 'verification.json');
|
|
176
|
+
const findings = readJson(path.join(directory, 'findings.json'), 'findings.json');
|
|
177
|
+
const verdict = readJson(path.join(directory, 'verdict.json'), 'verdict.json');
|
|
178
|
+
const claimedFile = path.join(rootDir, CLAIMED_VS_REALITY);
|
|
179
|
+
const claims = fs.existsSync(claimedFile) ? parseClaimedVsReality(fs.readFileSync(claimedFile, 'utf8')).rows : [];
|
|
180
|
+
const commands = (verification.commands || []).map(commandEvidence);
|
|
181
|
+
const links = parseEvidenceLinks(evidenceLinks);
|
|
182
|
+
const unknownLinks = Object.keys(links).filter((id) => !(goal.acceptanceCriteria || []).some((item) => item.id === id));
|
|
183
|
+
if (unknownLinks.length) throw receiptError(`--evidence names unknown AC: ${unknownLinks.join(', ')}`, 'INVALID_EVIDENCE_LINK');
|
|
184
|
+
const ledger = Array.isArray(findings.findings) ? findings.findings : [];
|
|
185
|
+
const drift = artifacts.some((item) => item.name === 'impactDrift')
|
|
186
|
+
? readJson(path.join(directory, 'impact-drift.json'), 'impact-drift.json')
|
|
187
|
+
: null;
|
|
188
|
+
const guardEvents = artifacts.some((item) => item.name === 'guardEvents')
|
|
189
|
+
? (readJson(path.join(directory, 'guard-events.json'), 'guard-events.json').events || [])
|
|
190
|
+
: [];
|
|
191
|
+
const bySeverity = {};
|
|
192
|
+
for (const finding of ledger) bySeverity[finding.severity] = (bySeverity[finding.severity] || 0) + 1;
|
|
193
|
+
const receipt = {
|
|
194
|
+
schemaVersion: 1,
|
|
195
|
+
runId: run.runId,
|
|
196
|
+
generatedAt: now.toISOString(),
|
|
197
|
+
aelVersion: aelVersion || null,
|
|
198
|
+
host: { id: safeText(host || 'unspecified'), model: model ? safeText(model) : (verdict.model ? safeText(verdict.model) : null) },
|
|
199
|
+
base: { sha: run.startedRevision || null },
|
|
200
|
+
head: { sha: head || gitHead(rootDir) },
|
|
201
|
+
goal: {
|
|
202
|
+
path: repoRelative(rootDir, goalFile),
|
|
203
|
+
sha256: hashBytes(fs.readFileSync(goalFile)),
|
|
204
|
+
contentHash: sha256(goal),
|
|
205
|
+
version: run.goal?.version || 1,
|
|
206
|
+
objective: safeText(goal.objective)
|
|
207
|
+
},
|
|
208
|
+
acceptanceCriteria: (goal.acceptanceCriteria || []).map((criterion) => criterionEntry(criterion, { commands, claims, links })),
|
|
209
|
+
verification: {
|
|
210
|
+
diffHash: verification.diffHash,
|
|
211
|
+
gitRevision: verification.gitRevision,
|
|
212
|
+
commands,
|
|
213
|
+
coverage: coverageSummary(verification.coverage)
|
|
214
|
+
},
|
|
215
|
+
review: {
|
|
216
|
+
findings: {
|
|
217
|
+
total: ledger.length,
|
|
218
|
+
valid: ledger.filter((item) => item.validity === 'VALID').length,
|
|
219
|
+
blocking: ledger.filter(isBlockingFinding).length,
|
|
220
|
+
bySeverity
|
|
221
|
+
},
|
|
222
|
+
verdict: {
|
|
223
|
+
verdict: verdict.verdict,
|
|
224
|
+
modelTier: verdict.modelTier || null,
|
|
225
|
+
decidedBy: safeText(verdict.decidedBy || 'judge'),
|
|
226
|
+
reason: safeText(verdict.reason)
|
|
227
|
+
}
|
|
228
|
+
},
|
|
229
|
+
impact: drift ? { mapStatus: drift.mapStatus, outOfMap: (drift.outOfMap || []).map(safeText) } : null,
|
|
230
|
+
guard: {
|
|
231
|
+
warn: guardEvents.filter((event) => event.decision === 'warn').length,
|
|
232
|
+
block: guardEvents.filter((event) => event.decision === 'block').length
|
|
233
|
+
},
|
|
234
|
+
artifacts
|
|
235
|
+
};
|
|
236
|
+
receipt.digest = receiptDigest(receipt);
|
|
237
|
+
return receipt;
|
|
238
|
+
}
|
|
239
|
+
|
|
240
|
+
function markdownCell(value) {
|
|
241
|
+
return String(value ?? '').replace(/\r?\n/g, ' ').replace(/\|/g, '\\|');
|
|
242
|
+
}
|
|
243
|
+
|
|
244
|
+
function short(sha, length = 12) {
|
|
245
|
+
return sha ? String(sha).slice(0, length) : 'unknown';
|
|
246
|
+
}
|
|
247
|
+
|
|
248
|
+
function renderReceiptMarkdown(receipt) {
|
|
249
|
+
const lines = [
|
|
250
|
+
'## Receipt',
|
|
251
|
+
'',
|
|
252
|
+
`Run \`${receipt.runId}\` · Goal v${receipt.goal.version} \`${short(receipt.goal.contentHash)}\` · base \`${short(receipt.base.sha, 7)}\` → head \`${short(receipt.head.sha, 7)}\` · digest \`${short(receipt.digest)}\``,
|
|
253
|
+
''
|
|
254
|
+
];
|
|
255
|
+
for (const criterion of receipt.acceptanceCriteria) {
|
|
256
|
+
const parts = [];
|
|
257
|
+
for (const item of criterion.evidence) {
|
|
258
|
+
if (item.type === 'command') parts.push(`\`${markdownCell(item.command)}\` exit ${item.exitCode}`);
|
|
259
|
+
if (item.type === 'claim') parts.push(`reality: ${markdownCell(item.reality)}`);
|
|
260
|
+
if (item.type === 'link') parts.push(`[evidence](${item.url})`);
|
|
261
|
+
}
|
|
262
|
+
const missing = criterion.missing ? ` — **missing:** ${criterion.missing.join('; ')}` : '';
|
|
263
|
+
lines.push(`- ${criterion.status === 'PASS' ? '✅' : '❌'} **${criterion.id}** ${markdownCell(criterion.statement)}${parts.length ? ` — ${parts.join(', ')}` : ''}${missing}`);
|
|
264
|
+
}
|
|
265
|
+
const { findings, verdict } = receipt.review;
|
|
266
|
+
lines.push('');
|
|
267
|
+
lines.push(`Judge: **${verdict.verdict}**${verdict.modelTier ? ` (${verdict.modelTier})` : ''} · Findings: ${findings.total} (${findings.valid} valid, ${findings.blocking} blocking)` +
|
|
268
|
+
`${receipt.impact ? ` · Impact map: ${receipt.impact.mapStatus}, ${receipt.impact.outOfMap.length} file(s) outside` : ''}` +
|
|
269
|
+
` · Guard: ${receipt.guard.block} blocked, ${receipt.guard.warn} warned`);
|
|
270
|
+
lines.push('');
|
|
271
|
+
lines.push(`Check: \`npx ai-engineering-loop verify-receipt --run ${receipt.runId} --head ${short(receipt.head.sha, 40)}\``);
|
|
272
|
+
return `${lines.join('\n')}\n`;
|
|
273
|
+
}
|
|
274
|
+
|
|
275
|
+
function writeReceipt(rootDir, options = {}) {
|
|
276
|
+
const receipt = buildReceipt(rootDir, options);
|
|
277
|
+
const directory = path.join(runsDir(rootDir), receipt.runId);
|
|
278
|
+
const jsonPath = path.join(directory, RECEIPT_FILE);
|
|
279
|
+
const markdownPath = path.join(directory, RECEIPT_MARKDOWN_FILE);
|
|
280
|
+
fs.writeFileSync(jsonPath, `${JSON.stringify(receipt, null, 2)}\n`, { mode: 0o600 });
|
|
281
|
+
fs.writeFileSync(markdownPath, renderReceiptMarkdown(receipt), { mode: 0o600 });
|
|
282
|
+
return {
|
|
283
|
+
receipt,
|
|
284
|
+
path: repoRelative(rootDir, jsonPath),
|
|
285
|
+
markdownPath: repoRelative(rootDir, markdownPath),
|
|
286
|
+
missing: receipt.acceptanceCriteria.filter((item) => item.status !== 'PASS').map((item) => item.id)
|
|
287
|
+
};
|
|
288
|
+
}
|
|
289
|
+
|
|
290
|
+
function insideRepo(rootDir, relativePath) {
|
|
291
|
+
const absolute = path.resolve(rootDir, relativePath);
|
|
292
|
+
const relative = path.relative(rootDir, absolute);
|
|
293
|
+
if (!relativePath || path.isAbsolute(relativePath) || relative === '..' || relative.startsWith(`..${path.sep}`)) return null;
|
|
294
|
+
return absolute;
|
|
295
|
+
}
|
|
296
|
+
|
|
297
|
+
function verifyReceipt(rootDir, { runId, receiptPath, head } = {}) {
|
|
298
|
+
let file;
|
|
299
|
+
if (receiptPath) {
|
|
300
|
+
file = insideRepo(rootDir, receiptPath);
|
|
301
|
+
if (!file) throw receiptError('Receipt path must be repository-relative', 'UNSAFE_RECEIPT_PATH');
|
|
302
|
+
} else {
|
|
303
|
+
file = path.join(runsDir(rootDir), resolveRun(rootDir, runId).runId, RECEIPT_FILE);
|
|
304
|
+
}
|
|
305
|
+
const receipt = readJson(file, 'receipt.json');
|
|
306
|
+
const problems = [];
|
|
307
|
+
const fail = (code, detail) => problems.push({ code, detail });
|
|
308
|
+
if (receipt.schemaVersion !== 1 || !receipt.runId) fail('RECEIPT_INVALID', 'schemaVersion 1 and runId are required');
|
|
309
|
+
if (receiptDigest(receipt) !== receipt.digest) fail('RECEIPT_DIGEST_MISMATCH', 'receipt content does not match its digest');
|
|
310
|
+
|
|
311
|
+
for (const artifact of receipt.artifacts || []) {
|
|
312
|
+
const absolute = insideRepo(rootDir, artifact.path);
|
|
313
|
+
if (!absolute || !fs.existsSync(absolute)) {
|
|
314
|
+
fail('ARTIFACT_MISSING', `${artifact.path} is missing`);
|
|
315
|
+
} else if (hashBytes(fs.readFileSync(absolute)) !== artifact.sha256) {
|
|
316
|
+
fail('ARTIFACT_TAMPERED', `${artifact.path} changed after the receipt`);
|
|
317
|
+
}
|
|
318
|
+
}
|
|
319
|
+
|
|
320
|
+
const goalFile = receipt.goal?.path && insideRepo(rootDir, receipt.goal.path);
|
|
321
|
+
let goal = null;
|
|
322
|
+
if (!goalFile || !fs.existsSync(goalFile)) {
|
|
323
|
+
fail('GOAL_CHANGED', 'the frozen Goal is missing');
|
|
324
|
+
} else {
|
|
325
|
+
goal = JSON.parse(fs.readFileSync(goalFile, 'utf8'));
|
|
326
|
+
if (hashBytes(fs.readFileSync(goalFile)) !== receipt.goal.sha256 || sha256(goal) !== receipt.goal.contentHash) {
|
|
327
|
+
fail('GOAL_CHANGED', 'the frozen Goal differs from the one in the receipt');
|
|
328
|
+
}
|
|
329
|
+
}
|
|
330
|
+
const listed = new Map((receipt.acceptanceCriteria || []).map((item) => [item.id, item]));
|
|
331
|
+
for (const criterion of goal?.acceptanceCriteria || []) {
|
|
332
|
+
const entry = listed.get(criterion.id);
|
|
333
|
+
if (!entry) fail('AC_NOT_IN_RECEIPT', `${criterion.id} is not in the receipt`);
|
|
334
|
+
else if (entry.status !== 'PASS' || !(entry.evidence || []).length) {
|
|
335
|
+
fail('AC_EVIDENCE_MISSING', `${criterion.id}: ${(entry.missing || ['no evidence']).join('; ')}`);
|
|
336
|
+
}
|
|
337
|
+
}
|
|
338
|
+
if (receipt.review?.verdict?.verdict !== 'PASS') fail('VERDICT_NOT_PASS', `Judge verdict is ${receipt.review?.verdict?.verdict || 'missing'}`);
|
|
339
|
+
if (receipt.review?.findings?.blocking) fail('BLOCKING_FINDINGS', `${receipt.review.findings.blocking} blocking finding(s)`);
|
|
340
|
+
const expectedHead = head || gitHead(rootDir);
|
|
341
|
+
if (!receipt.head?.sha || !expectedHead || receipt.head.sha !== expectedHead) {
|
|
342
|
+
fail('HEAD_MISMATCH', `receipt head ${short(receipt.head?.sha, 7)} vs ${head ? '--head' : 'HEAD'} ${short(expectedHead, 7)}`);
|
|
343
|
+
}
|
|
344
|
+
return {
|
|
345
|
+
ok: problems.length === 0,
|
|
346
|
+
runId: receipt.runId,
|
|
347
|
+
digest: receipt.digest,
|
|
348
|
+
path: repoRelative(rootDir, file),
|
|
349
|
+
problems
|
|
350
|
+
};
|
|
351
|
+
}
|
|
352
|
+
|
|
353
|
+
module.exports = {
|
|
354
|
+
RECEIPT_FILE,
|
|
355
|
+
RECEIPT_MARKDOWN_FILE,
|
|
356
|
+
buildReceipt,
|
|
357
|
+
writeReceipt,
|
|
358
|
+
verifyReceipt,
|
|
359
|
+
renderReceiptMarkdown,
|
|
360
|
+
receiptDigest,
|
|
361
|
+
parseEvidenceLinks
|
|
362
|
+
};
|
package/lib/safe-context.js
CHANGED
|
@@ -237,6 +237,17 @@ function createContextPack(rootDir, { runId, stage, files, profile } = {}) {
|
|
|
237
237
|
content: redacted.text
|
|
238
238
|
});
|
|
239
239
|
}
|
|
240
|
+
// Project learnings (#61) for Maker and DA, inside this stage's budget.
|
|
241
|
+
const learned = stage === 'judge'
|
|
242
|
+
? { learnings: [], estimatedTokens: 0 }
|
|
243
|
+
: require('./learn.js').selectLearnings(rootDir, {
|
|
244
|
+
files: entries.map((entry) => entry.path),
|
|
245
|
+
budgetTokens: Math.min(
|
|
246
|
+
limits.maxEstimatedTokens * require('./learn.js').LEARNINGS_BUDGET_SHARE,
|
|
247
|
+
limits.maxEstimatedTokens - estimatedTokens
|
|
248
|
+
)
|
|
249
|
+
});
|
|
250
|
+
estimatedTokens += learned.estimatedTokens;
|
|
240
251
|
assertBudgetAvailable(rootDir, { runId: run.runId, estimatedTokens });
|
|
241
252
|
|
|
242
253
|
const pack = {
|
|
@@ -249,6 +260,8 @@ function createContextPack(rootDir, { runId, stage, files, profile } = {}) {
|
|
|
249
260
|
limits,
|
|
250
261
|
totalBytes,
|
|
251
262
|
estimatedTokens,
|
|
263
|
+
learningTokens: learned.estimatedTokens,
|
|
264
|
+
learnings: learned.learnings,
|
|
252
265
|
entries
|
|
253
266
|
};
|
|
254
267
|
const packPath = path.join(runsDir(rootDir), run.runId, 'context', `${stage}.json`);
|
|
@@ -269,6 +282,7 @@ function contextPackSummary(result) {
|
|
|
269
282
|
files: result.pack.entries.length,
|
|
270
283
|
totalBytes: result.pack.totalBytes,
|
|
271
284
|
estimatedTokens: result.pack.estimatedTokens,
|
|
285
|
+
learnings: (result.pack.learnings || []).length,
|
|
272
286
|
redactions: result.pack.entries.reduce((sum, entry) => sum + entry.redactions.length, 0),
|
|
273
287
|
truncatedFiles: result.pack.entries.filter((entry) => entry.truncated).length
|
|
274
288
|
};
|
package/lib/smart-context.js
CHANGED
|
@@ -473,6 +473,14 @@ function boundedHunks(file, limits, remainingBytes) {
|
|
|
473
473
|
return { hunks, includedBytes, truncated };
|
|
474
474
|
}
|
|
475
475
|
|
|
476
|
+
// Blast-radius drift from verify (#71): the Devil's Advocate sees which
|
|
477
|
+
// changed files were outside the impact map.
|
|
478
|
+
function impactDriftSummary(rootDir, runId) {
|
|
479
|
+
const drift = require('./impact-map.js').loadImpactDrift(rootDir, runId);
|
|
480
|
+
if (!drift) return null;
|
|
481
|
+
return { mapStatus: drift.mapStatus, outOfMap: (drift.outOfMap || []).slice(0, 50) };
|
|
482
|
+
}
|
|
483
|
+
|
|
476
484
|
function createDiffHunkPack(rootDir, { runId, base = 'HEAD', profile, includeIgnored = false } = {}) {
|
|
477
485
|
const run = resolveRun(rootDir, runId);
|
|
478
486
|
const policy = loadPolicy(rootDir);
|
|
@@ -514,6 +522,16 @@ function createDiffHunkPack(rootDir, { runId, base = 'HEAD', profile, includeIgn
|
|
|
514
522
|
if (estimatedTokens > contextLimits.maxEstimatedTokens) {
|
|
515
523
|
throw smartContextError(`${reviewProfile} diff hunk pack exceeds devil-advocate token budget`, 'DIFF_PACK_TOKEN_LIMIT');
|
|
516
524
|
}
|
|
525
|
+
// Project learnings (#61) the Devil's Advocate should not have to rediscover.
|
|
526
|
+
const { LEARNINGS_BUDGET_SHARE, selectLearnings } = require('./learn.js');
|
|
527
|
+
const learned = selectLearnings(rootDir, {
|
|
528
|
+
files: changedPaths,
|
|
529
|
+
budgetTokens: Math.min(
|
|
530
|
+
contextLimits.maxEstimatedTokens * LEARNINGS_BUDGET_SHARE,
|
|
531
|
+
contextLimits.maxEstimatedTokens - estimatedTokens
|
|
532
|
+
)
|
|
533
|
+
});
|
|
534
|
+
estimatedTokens += learned.estimatedTokens;
|
|
517
535
|
assertBudgetAvailable(rootDir, { runId: run.runId, estimatedTokens });
|
|
518
536
|
const pack = {
|
|
519
537
|
schemaVersion: 1,
|
|
@@ -536,6 +554,8 @@ function createDiffHunkPack(rootDir, { runId, base = 'HEAD', profile, includeIgn
|
|
|
536
554
|
focusPaths
|
|
537
555
|
},
|
|
538
556
|
unresolvedFindings: unresolved,
|
|
557
|
+
impactDrift: impactDriftSummary(rootDir, run.runId),
|
|
558
|
+
learnings: learned.learnings,
|
|
539
559
|
files
|
|
540
560
|
};
|
|
541
561
|
const packPath = path.join(runsDir(rootDir), run.runId, 'context', 'diff-hunks.json');
|
|
@@ -617,6 +637,7 @@ function smartContextSummary(result) {
|
|
|
617
637
|
truncated: result.pack.truncated,
|
|
618
638
|
unresolvedFindings: result.pack.unresolvedFindings.length,
|
|
619
639
|
ignoredPaths: result.pack.reviewDelta?.ignoredPaths?.length || 0,
|
|
640
|
+
impactDrift: result.pack.impactDrift || null,
|
|
620
641
|
reviewBudget: result.pack.reviewBudget
|
|
621
642
|
};
|
|
622
643
|
}
|
package/lib/studio-server.js
CHANGED
|
@@ -162,6 +162,7 @@ function bootstrap(rootDir) {
|
|
|
162
162
|
types: SHIPPED_TYPES,
|
|
163
163
|
current: adapterHints.existingType || null,
|
|
164
164
|
recommended: adapterHints.recommended,
|
|
165
|
+
reason: adapterHints.reason,
|
|
165
166
|
ciProvider: adapterHints.ciProvider
|
|
166
167
|
},
|
|
167
168
|
live: liveSnapshot(rootDir)
|
package/lib/sync-hosts.js
CHANGED
|
@@ -131,7 +131,8 @@ function skillFolderFiles(skillsDir) {
|
|
|
131
131
|
...loopReferenceFiles(CORE_SKILL_SRC, path.join(skillsDir, 'ai-engineering-loop')),
|
|
132
132
|
...backendSkillFiles('.agents/skills/backend-development', path.join(skillsDir, 'backend-development')),
|
|
133
133
|
...emilKowalskiSkillFiles('.agents/skills', skillsDir),
|
|
134
|
-
|
|
134
|
+
// Adapter-neutral (#64): installed by default, not part of the opt-in quality pack.
|
|
135
|
+
{ src: 'adapters/quality/skills/task-impact-inquiry/SKILL.md', dest: path.join(skillsDir, 'task-impact-inquiry/SKILL.md'), mode: 'upsert' },
|
|
135
136
|
{ src: 'adapters/generate-adapter/SKILL.md', dest: path.join(skillsDir, 'generate-adapter/SKILL.md'), mode: 'upsert' },
|
|
136
137
|
{ src: 'adapters/generate-workflow/SKILL.md', dest: path.join(skillsDir, 'generate-workflow/SKILL.md'), mode: 'upsert' },
|
|
137
138
|
...adoptedSkillFiles(skillsDir)
|
package/package.json
CHANGED
|
@@ -9,7 +9,17 @@
|
|
|
9
9
|
"runId": { "type": "string", "minLength": 1 },
|
|
10
10
|
"destination": { "type": "string", "minLength": 1 },
|
|
11
11
|
"summary": { "type": "string", "minLength": 1 },
|
|
12
|
-
"humanApproved": { "type": "boolean" }
|
|
12
|
+
"humanApproved": { "type": "boolean" },
|
|
13
|
+
"approvedBy": { "type": "string" },
|
|
14
|
+
"receipt": {
|
|
15
|
+
"description": "Proof-carrying PR receipt written by deliver (#70)",
|
|
16
|
+
"type": "object",
|
|
17
|
+
"required": ["path", "digest"],
|
|
18
|
+
"properties": {
|
|
19
|
+
"path": { "type": "string", "minLength": 1 },
|
|
20
|
+
"digest": { "type": "string", "pattern": "^[a-f0-9]{64}$" }
|
|
21
|
+
}
|
|
22
|
+
}
|
|
13
23
|
},
|
|
14
24
|
"additionalProperties": true
|
|
15
25
|
}
|
|
@@ -17,7 +17,8 @@
|
|
|
17
17
|
"axis": { "enum": ["spec", "standards"] },
|
|
18
18
|
"severity": { "enum": ["BLOCKER", "HIGH", "MEDIUM", "LOW"] },
|
|
19
19
|
"validity": { "enum": ["VALID", "INVALID"] },
|
|
20
|
-
"disposition": { "enum": ["STRONG", "ACCEPTABLE", "WEAK"] }
|
|
20
|
+
"disposition": { "enum": ["STRONG", "ACCEPTABLE", "WEAK"] },
|
|
21
|
+
"source": { "description": "Producer of a CLI-generated finding, e.g. impact-map for blast-radius drift", "type": "string" }
|
|
21
22
|
},
|
|
22
23
|
"additionalProperties": true
|
|
23
24
|
}
|
|
@@ -26,6 +26,15 @@
|
|
|
26
26
|
},
|
|
27
27
|
"additionalProperties": true
|
|
28
28
|
}
|
|
29
|
+
},
|
|
30
|
+
"scope": {
|
|
31
|
+
"description": "Optional file scope frozen with the Goal (#59). Absent = no path enforcement. Globs: ** crosses directories, * stays in one segment, a trailing / is a directory prefix.",
|
|
32
|
+
"type": "object",
|
|
33
|
+
"properties": {
|
|
34
|
+
"allowedPaths": { "type": "array", "items": { "type": "string", "minLength": 1 } },
|
|
35
|
+
"deniedPaths": { "type": "array", "items": { "type": "string", "minLength": 1 } }
|
|
36
|
+
},
|
|
37
|
+
"additionalProperties": false
|
|
29
38
|
}
|
|
30
39
|
},
|
|
31
40
|
"additionalProperties": true
|
|
@@ -0,0 +1,78 @@
|
|
|
1
|
+
{
|
|
2
|
+
"$schema": "https://json-schema.org/draft/2020-12/schema",
|
|
3
|
+
"$id": "https://github.com/egagofur/ai-engineering-loop/schemas/impact-map.schema.json",
|
|
4
|
+
"title": "AI Engineering Loop Blast-Radius Impact Map",
|
|
5
|
+
"type": "object",
|
|
6
|
+
"required": ["schemaVersion", "runId", "goalHash", "status", "files", "modules", "endpoints", "dbTables", "tests"],
|
|
7
|
+
"properties": {
|
|
8
|
+
"schemaVersion": { "const": 1 },
|
|
9
|
+
"runId": { "type": "string", "minLength": 1 },
|
|
10
|
+
"goalHash": { "type": "string", "pattern": "^[a-f0-9]{64}$" },
|
|
11
|
+
"status": { "enum": ["DRAFT", "CONFIRMED", "SKIPPED"] },
|
|
12
|
+
"generator": { "type": "string" },
|
|
13
|
+
"generatedAt": { "type": "string" },
|
|
14
|
+
"keywords": { "type": "array", "items": { "type": "string" } },
|
|
15
|
+
"files": { "type": "array", "items": { "$ref": "#/$defs/pathEntry" } },
|
|
16
|
+
"modules": { "type": "array", "items": { "$ref": "#/$defs/namedEntry" } },
|
|
17
|
+
"endpoints": {
|
|
18
|
+
"type": "array",
|
|
19
|
+
"items": {
|
|
20
|
+
"allOf": [{ "$ref": "#/$defs/pathEntry" }],
|
|
21
|
+
"required": ["method", "route"],
|
|
22
|
+
"properties": {
|
|
23
|
+
"method": { "type": "string" },
|
|
24
|
+
"route": { "type": "string" }
|
|
25
|
+
}
|
|
26
|
+
}
|
|
27
|
+
},
|
|
28
|
+
"dbTables": {
|
|
29
|
+
"type": "array",
|
|
30
|
+
"items": {
|
|
31
|
+
"allOf": [{ "$ref": "#/$defs/namedEntry" }],
|
|
32
|
+
"required": ["kind"],
|
|
33
|
+
"properties": { "kind": { "enum": ["table", "migration"] }, "path": { "type": "string" } }
|
|
34
|
+
}
|
|
35
|
+
},
|
|
36
|
+
"tests": { "type": "array", "items": { "$ref": "#/$defs/pathEntry" } },
|
|
37
|
+
"scope": {
|
|
38
|
+
"oneOf": [
|
|
39
|
+
{ "type": "null" },
|
|
40
|
+
{
|
|
41
|
+
"type": "object",
|
|
42
|
+
"required": ["allowedPaths"],
|
|
43
|
+
"properties": { "allowedPaths": { "type": "array", "items": { "type": "string", "minLength": 1 } } }
|
|
44
|
+
}
|
|
45
|
+
]
|
|
46
|
+
},
|
|
47
|
+
"confirmedBy": { "type": "string" },
|
|
48
|
+
"confirmedAt": { "type": "string" },
|
|
49
|
+
"skipReason": { "type": "string", "minLength": 1, "maxLength": 500 },
|
|
50
|
+
"skippedBy": { "type": "string" },
|
|
51
|
+
"skippedAt": { "type": "string" }
|
|
52
|
+
},
|
|
53
|
+
"allOf": [
|
|
54
|
+
{ "if": { "properties": { "status": { "const": "SKIPPED" } } }, "then": { "required": ["skipReason"] } },
|
|
55
|
+
{ "if": { "properties": { "status": { "const": "CONFIRMED" } } }, "then": { "required": ["scope", "confirmedBy"] } }
|
|
56
|
+
],
|
|
57
|
+
"$defs": {
|
|
58
|
+
"pathEntry": {
|
|
59
|
+
"type": "object",
|
|
60
|
+
"required": ["path", "confidence", "reason"],
|
|
61
|
+
"properties": {
|
|
62
|
+
"path": { "type": "string", "minLength": 1 },
|
|
63
|
+
"confidence": { "type": "number", "minimum": 0, "maximum": 1 },
|
|
64
|
+
"reason": { "type": "string", "minLength": 1 }
|
|
65
|
+
}
|
|
66
|
+
},
|
|
67
|
+
"namedEntry": {
|
|
68
|
+
"type": "object",
|
|
69
|
+
"required": ["name", "confidence", "reason"],
|
|
70
|
+
"properties": {
|
|
71
|
+
"name": { "type": "string", "minLength": 1 },
|
|
72
|
+
"confidence": { "type": "number", "minimum": 0, "maximum": 1 },
|
|
73
|
+
"reason": { "type": "string", "minLength": 1 }
|
|
74
|
+
}
|
|
75
|
+
}
|
|
76
|
+
},
|
|
77
|
+
"additionalProperties": true
|
|
78
|
+
}
|
|
@@ -0,0 +1,47 @@
|
|
|
1
|
+
{
|
|
2
|
+
"$schema": "https://json-schema.org/draft/2020-12/schema",
|
|
3
|
+
"$id": "https://github.com/egagofur/ai-engineering-loop/schemas/learnings.schema.json",
|
|
4
|
+
"title": "AI Engineering Loop Project Learnings",
|
|
5
|
+
"type": "object",
|
|
6
|
+
"required": ["schemaVersion", "generator", "sourceRuns", "entries", "suppressed"],
|
|
7
|
+
"properties": {
|
|
8
|
+
"schemaVersion": { "const": 1 },
|
|
9
|
+
"generator": { "type": "string" },
|
|
10
|
+
"sourceRuns": { "type": "integer", "minimum": 0 },
|
|
11
|
+
"latestRunId": { "type": ["string", "null"] },
|
|
12
|
+
"entries": {
|
|
13
|
+
"type": "array",
|
|
14
|
+
"items": {
|
|
15
|
+
"type": "object",
|
|
16
|
+
"required": ["id", "axis", "severity", "lesson", "locations", "occurrences", "runIds", "firstRunId", "lastRunId"],
|
|
17
|
+
"properties": {
|
|
18
|
+
"id": { "type": "string", "pattern": "^L-[a-f0-9]{10}$" },
|
|
19
|
+
"axis": { "enum": ["spec", "standards"] },
|
|
20
|
+
"severity": { "enum": ["BLOCKER", "HIGH", "MEDIUM", "LOW"] },
|
|
21
|
+
"lesson": { "type": "string", "minLength": 1, "maxLength": 300 },
|
|
22
|
+
"locations": { "type": "array", "items": { "type": "string" } },
|
|
23
|
+
"occurrences": { "type": "integer", "minimum": 1 },
|
|
24
|
+
"runIds": { "type": "array", "minItems": 1, "items": { "type": "string" } },
|
|
25
|
+
"firstRunId": { "type": "string" },
|
|
26
|
+
"lastRunId": { "type": "string" },
|
|
27
|
+
"lastSeenAt": { "type": "string" },
|
|
28
|
+
"supersededBy": { "description": "Set by a human; the next learn run suppresses the entry", "type": "string" }
|
|
29
|
+
}
|
|
30
|
+
}
|
|
31
|
+
},
|
|
32
|
+
"suppressed": {
|
|
33
|
+
"type": "array",
|
|
34
|
+
"items": {
|
|
35
|
+
"type": "object",
|
|
36
|
+
"required": ["id", "reason"],
|
|
37
|
+
"properties": {
|
|
38
|
+
"id": { "type": "string" },
|
|
39
|
+
"reason": { "enum": ["files-removed", "stale", "superseded"] },
|
|
40
|
+
"supersededBy": { "type": "string" },
|
|
41
|
+
"lastRunId": { "type": ["string", "null"] }
|
|
42
|
+
}
|
|
43
|
+
}
|
|
44
|
+
}
|
|
45
|
+
},
|
|
46
|
+
"additionalProperties": true
|
|
47
|
+
}
|