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
|
@@ -36,6 +36,8 @@ const {
|
|
|
36
36
|
formatGenerateAdapterReport,
|
|
37
37
|
parseTypeArg
|
|
38
38
|
} = require('../lib/generate-adapter.js');
|
|
39
|
+
const { detectAdapter } = require('../lib/adapter-detect.js');
|
|
40
|
+
const { checkAdapter } = require('../lib/adapter-check.js');
|
|
39
41
|
const {
|
|
40
42
|
writeWorkflowOverlay,
|
|
41
43
|
formatGenerateWorkflowReport,
|
|
@@ -65,6 +67,11 @@ const {
|
|
|
65
67
|
judgeRequirement
|
|
66
68
|
} = require('../lib/gates.js');
|
|
67
69
|
const { initialTierState } = require('../lib/tier.js');
|
|
70
|
+
const impactMap = require('../lib/impact-map.js');
|
|
71
|
+
const guard = require('../lib/guard.js');
|
|
72
|
+
const guardHooks = require('../lib/guard-hooks.js');
|
|
73
|
+
const receipts = require('../lib/receipt.js');
|
|
74
|
+
const { learn } = require('../lib/learn.js');
|
|
68
75
|
const {
|
|
69
76
|
createContextPack,
|
|
70
77
|
contextPackSummary
|
|
@@ -549,26 +556,12 @@ function analyzeRepository(rootDir) {
|
|
|
549
556
|
discovery.evidence.push('Manifest: pubspec.yaml');
|
|
550
557
|
}
|
|
551
558
|
|
|
552
|
-
// 3. Adapter / CI Detection
|
|
553
|
-
|
|
554
|
-
|
|
555
|
-
|
|
556
|
-
|
|
557
|
-
|
|
558
|
-
discovery.adapter.type = 'gitlab';
|
|
559
|
-
}
|
|
560
|
-
|
|
561
|
-
// Check git remote if git folder exists
|
|
562
|
-
const gitConfigStr = readFileSafe(path.join(rootDir, '.git', 'config'));
|
|
563
|
-
if (gitConfigStr) {
|
|
564
|
-
const urlMatch = gitConfigStr.match(/url\s*=\s*(.*)/);
|
|
565
|
-
if (urlMatch) {
|
|
566
|
-
discovery.adapter.repoSlug = urlMatch[1].trim();
|
|
567
|
-
if (discovery.adapter.repoSlug.includes('gitlab.dot.co.id')) {
|
|
568
|
-
discovery.adapter.type = 'dot';
|
|
569
|
-
}
|
|
570
|
-
}
|
|
571
|
-
}
|
|
559
|
+
// 3. Adapter / CI Detection (shared with generate-adapter and Studio, #62)
|
|
560
|
+
const detected = detectAdapter(rootDir);
|
|
561
|
+
discovery.adapter.type = detected.type;
|
|
562
|
+
discovery.adapter.ciProvider = detected.ciProvider;
|
|
563
|
+
discovery.adapter.repoSlug = detected.remote || null;
|
|
564
|
+
discovery.evidence.push(`Adapter: ${detected.type} (${detected.reason})`);
|
|
572
565
|
|
|
573
566
|
return discovery;
|
|
574
567
|
}
|
|
@@ -1472,7 +1465,8 @@ function handleRun() {
|
|
|
1472
1465
|
console.log('1. Grill if needed (docs grill-policy), then freeze a failure-table Goal Contract');
|
|
1473
1466
|
if (runResult.run.mode === RUN_MODES.REPORT_ONLY) {
|
|
1474
1467
|
console.log('2. Analyze evidence without changing repository files');
|
|
1475
|
-
console.log('3. Write report.json
|
|
1468
|
+
console.log('3. Write report.json; if the host has a subagent tool, have ONE fresh devil-advocate challenge it (no Judge), and record `review` in report.json (loop-maker)');
|
|
1469
|
+
console.log('4. Finish with `ai-engineering-loop gate report`');
|
|
1476
1470
|
} else {
|
|
1477
1471
|
console.log('2. Root Cause Analysis (docs root-cause-analysis) & Plan');
|
|
1478
1472
|
console.log('3. Maker TDD at named seams (docs tdd-policy)');
|
|
@@ -1833,9 +1827,12 @@ function executeGate(gate, runId) {
|
|
|
1833
1827
|
});
|
|
1834
1828
|
}
|
|
1835
1829
|
}
|
|
1830
|
+
if (gate === 'maker') ensureImpactMap(target.runId);
|
|
1836
1831
|
const run = target.workflow
|
|
1837
1832
|
? applyWorkflowGate(CWD, gate, { runId: target.runId }).run
|
|
1838
1833
|
: applyGate(CWD, gate, { runId: target.runId });
|
|
1834
|
+
if (gate === 'goal') ensureImpactMap(target.runId);
|
|
1835
|
+
if (gate === 'verification') recordImpactDrift(target.runId);
|
|
1839
1836
|
const runCompleted = run.state === 'DELIVERED' || run.state === 'REPORTED';
|
|
1840
1837
|
appendRunLifecycle(CWD, target.runId, {
|
|
1841
1838
|
type: runCompleted
|
|
@@ -1850,6 +1847,31 @@ function executeGate(gate, runId) {
|
|
|
1850
1847
|
return run;
|
|
1851
1848
|
}
|
|
1852
1849
|
|
|
1850
|
+
// Blast-radius map (#71): written into the Run once the Goal is frozen, so it
|
|
1851
|
+
// exists before Stage 3. Best effort: a scan failure never blocks a gate.
|
|
1852
|
+
function ensureImpactMap(runId) {
|
|
1853
|
+
try {
|
|
1854
|
+
if (impactMap.loadImpactMap(CWD, runId)) return null;
|
|
1855
|
+
const result = impactMap.generateImpactMap(CWD, { runId });
|
|
1856
|
+
console.error(`- Impact map: ${result.path} (DRAFT; review it with \`impact show\`, then \`impact confirm --by <name>\` or \`impact skip --reason <text>\`)`);
|
|
1857
|
+
return result;
|
|
1858
|
+
} catch (err) {
|
|
1859
|
+
console.error(`! impact map not written: ${err.message}`);
|
|
1860
|
+
return null;
|
|
1861
|
+
}
|
|
1862
|
+
}
|
|
1863
|
+
|
|
1864
|
+
// Drift of the gated Maker diff against the map, recorded with verification;
|
|
1865
|
+
// the review gate turns out-of-map files into LOW ledger findings.
|
|
1866
|
+
function recordImpactDrift(runId) {
|
|
1867
|
+
try {
|
|
1868
|
+
return impactMap.detectImpactDrift(CWD, { runId }).drift;
|
|
1869
|
+
} catch (err) {
|
|
1870
|
+
console.error(`! impact drift not checked: ${err.message}`);
|
|
1871
|
+
return null;
|
|
1872
|
+
}
|
|
1873
|
+
}
|
|
1874
|
+
|
|
1853
1875
|
// `gate maker --from-git` (issue #35): write the working-tree diff (tracked and
|
|
1854
1876
|
// untracked files, excluding .ai-engineering-loop/) to RUN_DIR/diff.patch so the
|
|
1855
1877
|
// agent does not need a separate write step. ASSISTED/REPORT_ONLY only;
|
|
@@ -1890,6 +1912,7 @@ function handleGate() {
|
|
|
1890
1912
|
}
|
|
1891
1913
|
const run = executeGate(gate, target.runId);
|
|
1892
1914
|
const judge = gate === 'review' && run.tier ? judgeRequirement(CWD, run) : null;
|
|
1915
|
+
const guardEvents = guard.guardSummary(CWD, run.runId);
|
|
1893
1916
|
if (json) {
|
|
1894
1917
|
console.log(JSON.stringify({
|
|
1895
1918
|
ok: true,
|
|
@@ -1898,13 +1921,17 @@ function handleGate() {
|
|
|
1898
1921
|
iteration: run.iteration,
|
|
1899
1922
|
gate,
|
|
1900
1923
|
...(run.tier ? { tier: run.tier.current } : {}),
|
|
1901
|
-
...(judge ? { judgeRequired: judge.required, judgeReasons: judge.reasons } : {})
|
|
1924
|
+
...(judge ? { judgeRequired: judge.required, judgeReasons: judge.reasons } : {}),
|
|
1925
|
+
guard: guardEvents
|
|
1902
1926
|
}));
|
|
1903
1927
|
} else {
|
|
1904
1928
|
log.success(`✓ ${gate} gate passed`);
|
|
1905
1929
|
console.log(`- Run: ${run.runId}`);
|
|
1906
1930
|
console.log(`- State: ${run.state}, iteration ${run.iteration}`);
|
|
1907
1931
|
if (run.tier) console.log(`- Tier: ${run.tier.current}`);
|
|
1932
|
+
if (guardEvents.warn || guardEvents.block) {
|
|
1933
|
+
console.log(`- Guard: ${guardEvents.block} blocked, ${guardEvents.warn} warned (${guardEvents.rules.join(', ')}); see guard-events.json`);
|
|
1934
|
+
}
|
|
1908
1935
|
if (judge) {
|
|
1909
1936
|
console.log(judge.required
|
|
1910
1937
|
? `- Judge: REQUIRED (${judge.reasons.join('; ')}). Spawn the Judge subagent, write verdict.json, then gate judge.`
|
|
@@ -2257,12 +2284,12 @@ function handleState() {
|
|
|
2257
2284
|
|
|
2258
2285
|
function handleDoctor() {
|
|
2259
2286
|
const json = process.argv.includes('--json');
|
|
2260
|
-
const result = runDoctor(path.join(__dirname, '..'));
|
|
2287
|
+
const result = runDoctor(path.join(__dirname, '..'), { projectDir: CWD });
|
|
2261
2288
|
if (json) console.log(JSON.stringify(result));
|
|
2262
2289
|
else {
|
|
2263
2290
|
console.log(`AI Engineering Loop doctor: ${result.ok ? 'READY' : 'NOT READY'}`);
|
|
2264
2291
|
for (const check of result.checks) {
|
|
2265
|
-
console.log(`${check.passed ? '✓' : '✗'} ${check.id}: ${check.detail}`);
|
|
2292
|
+
console.log(`${check.passed ? '✓' : check.level === 'warn' ? '!' : '✗'} ${check.id}: ${check.detail}`);
|
|
2266
2293
|
}
|
|
2267
2294
|
}
|
|
2268
2295
|
if (!result.ok) process.exit(1);
|
|
@@ -2929,6 +2956,7 @@ function handleGoal() {
|
|
|
2929
2956
|
actor: argValue('--by') || 'human',
|
|
2930
2957
|
message: 'Goal Contract frozen'
|
|
2931
2958
|
});
|
|
2959
|
+
ensureImpactMap(runId);
|
|
2932
2960
|
} else {
|
|
2933
2961
|
const error = new Error('goal must be show, draft, or freeze');
|
|
2934
2962
|
error.code = 'INVALID_USAGE';
|
|
@@ -3136,6 +3164,7 @@ async function handleVerify() {
|
|
|
3136
3164
|
return;
|
|
3137
3165
|
}
|
|
3138
3166
|
const run = executeGate('verification', runId);
|
|
3167
|
+
const drift = impactMap.loadImpactDrift(CWD, runId) || { mapStatus: 'MISSING', outOfMap: [] };
|
|
3139
3168
|
const compact = compactRun(CWD, { runId });
|
|
3140
3169
|
let claimed = { path: '.ai-engineering-loop/tasks/claimed-vs-reality.md', created: false };
|
|
3141
3170
|
try {
|
|
@@ -3150,6 +3179,7 @@ async function handleVerify() {
|
|
|
3150
3179
|
tier: run.tier ? run.tier.current : null,
|
|
3151
3180
|
commands,
|
|
3152
3181
|
testCounts: recorded.summary.testCounts,
|
|
3182
|
+
impactDrift: { mapStatus: drift.mapStatus, outOfMap: drift.outOfMap },
|
|
3153
3183
|
compact: compact.paths,
|
|
3154
3184
|
claimedVsReality: claimed,
|
|
3155
3185
|
next: run.tier && run.tier.current === 'T0'
|
|
@@ -3161,6 +3191,11 @@ async function handleVerify() {
|
|
|
3161
3191
|
log.success('✓ verification recorded and gated');
|
|
3162
3192
|
for (const c of commands) console.log(`- ${c.command}: exit ${c.exitCode}`);
|
|
3163
3193
|
console.log(`- State: ${run.state}`);
|
|
3194
|
+
if (drift.outOfMap.length) {
|
|
3195
|
+
console.log(`! ${drift.outOfMap.length} file(s) changed outside the ${drift.mapStatus} impact map (LOW finding at review): ${drift.outOfMap.join(', ')}`);
|
|
3196
|
+
} else if (drift.mapStatus === 'MISSING') {
|
|
3197
|
+
console.log('! No impact map for this Run; drift was not checked');
|
|
3198
|
+
}
|
|
3164
3199
|
console.log(`- Claimed-vs-reality: ${claimed.path}${claimed.created ? ' (scaffolded; fill it from the command output)' : ''}`);
|
|
3165
3200
|
console.log(`- Next: ${result.next}`);
|
|
3166
3201
|
}
|
|
@@ -3169,6 +3204,137 @@ async function handleVerify() {
|
|
|
3169
3204
|
}
|
|
3170
3205
|
}
|
|
3171
3206
|
|
|
3207
|
+
function readGuardInput() {
|
|
3208
|
+
const source = argValue('--input') || (process.argv.includes('--hook') ? '-' : null);
|
|
3209
|
+
if (source == null) {
|
|
3210
|
+
const target = argValue('--path');
|
|
3211
|
+
const commandText = argValue('--command');
|
|
3212
|
+
if (target == null && commandText == null) {
|
|
3213
|
+
throw Object.assign(new Error('guard check needs --input -|<file>, --path <file>, or --command <text>'), { code: 'INVALID_USAGE' });
|
|
3214
|
+
}
|
|
3215
|
+
return target != null ? { path: target } : { command: commandText };
|
|
3216
|
+
}
|
|
3217
|
+
const text = source === '-' ? fs.readFileSync(0, 'utf8') : fs.readFileSync(path.resolve(CWD, source), 'utf8');
|
|
3218
|
+
try {
|
|
3219
|
+
return JSON.parse(text);
|
|
3220
|
+
} catch (cause) {
|
|
3221
|
+
throw Object.assign(new Error(`guard input is not JSON: ${cause.message}`), { code: 'INVALID_USAGE' });
|
|
3222
|
+
}
|
|
3223
|
+
}
|
|
3224
|
+
|
|
3225
|
+
function handleGuard() {
|
|
3226
|
+
const action = args[1] && !args[1].startsWith('--') ? args[1] : 'check';
|
|
3227
|
+
const json = process.argv.includes('--json');
|
|
3228
|
+
const hook = argValue('--hook');
|
|
3229
|
+
try {
|
|
3230
|
+
if (action !== 'check') throw Object.assign(new Error('guard supports: check'), { code: 'INVALID_USAGE' });
|
|
3231
|
+
if (hook != null && hook !== 'claude') throw Object.assign(new Error('--hook supports: claude'), { code: 'INVALID_USAGE' });
|
|
3232
|
+
const result = guard.checkGuard(CWD, { tool: argValue('--tool'), input: readGuardInput(), runId: argValue('--run') });
|
|
3233
|
+
if (hook === 'claude') {
|
|
3234
|
+
const output = guard.claudeHookOutput(result);
|
|
3235
|
+
if (output) console.log(JSON.stringify(output));
|
|
3236
|
+
return;
|
|
3237
|
+
}
|
|
3238
|
+
if (json) console.log(JSON.stringify({ ok: true, ...result }));
|
|
3239
|
+
else {
|
|
3240
|
+
const mark = { allow: '✓', warn: '!', block: '✗' }[result.decision];
|
|
3241
|
+
console.log(`${mark} ${result.decision} (${result.tool}, ${result.mode}${result.runId ? `, run ${result.runId}` : ', no active run'})`);
|
|
3242
|
+
for (const reason of result.reasons) console.log(`- ${reason}`);
|
|
3243
|
+
}
|
|
3244
|
+
if (result.decision === 'block') process.exitCode = 2;
|
|
3245
|
+
} catch (err) {
|
|
3246
|
+
if (hook) {
|
|
3247
|
+
console.error(`ai-engineering-loop guard: ${err.message}`);
|
|
3248
|
+
process.exitCode = 1;
|
|
3249
|
+
return;
|
|
3250
|
+
}
|
|
3251
|
+
stageJsonError(err, json, 'GUARD_FAILED');
|
|
3252
|
+
}
|
|
3253
|
+
}
|
|
3254
|
+
|
|
3255
|
+
function handleHooks() {
|
|
3256
|
+
const action = args[1] && !args[1].startsWith('--') ? args[1] : 'status';
|
|
3257
|
+
const json = process.argv.includes('--json');
|
|
3258
|
+
try {
|
|
3259
|
+
const options = { host: argValue('--host') || 'claude' };
|
|
3260
|
+
let result;
|
|
3261
|
+
if (action === 'install') result = guardHooks.installHooks(CWD, options);
|
|
3262
|
+
else if (action === 'uninstall') result = guardHooks.uninstallHooks(CWD, options);
|
|
3263
|
+
else if (action === 'status') result = guardHooks.hooksStatus(CWD, options);
|
|
3264
|
+
else throw Object.assign(new Error('hooks must be install, uninstall, or status'), { code: 'INVALID_USAGE' });
|
|
3265
|
+
if (json) console.log(JSON.stringify({ ok: true, action, ...result }));
|
|
3266
|
+
else {
|
|
3267
|
+
const verb = action === 'status' ? '' : (result.changed ? ' (updated)' : ' (already up to date)');
|
|
3268
|
+
log.success(`✓ ${result.host} guard hooks ${result.installed ? 'installed' : 'not installed'} in ${result.settings}${verb}`);
|
|
3269
|
+
if (result.installed) console.log('- Edit/Write outside the Run scope and destructive Bash commands: ASSISTED asks, UNATTENDED blocks.');
|
|
3270
|
+
}
|
|
3271
|
+
} catch (err) {
|
|
3272
|
+
stageJsonError(err, json, 'HOOKS_FAILED');
|
|
3273
|
+
}
|
|
3274
|
+
}
|
|
3275
|
+
|
|
3276
|
+
function handleImpact() {
|
|
3277
|
+
const action = args[1] && !args[1].startsWith('--') ? args[1] : 'show';
|
|
3278
|
+
const json = process.argv.includes('--json');
|
|
3279
|
+
try {
|
|
3280
|
+
const runId = requiredRunId('impact');
|
|
3281
|
+
let result;
|
|
3282
|
+
if (action === 'map') {
|
|
3283
|
+
const limit = argValue('--limit');
|
|
3284
|
+
result = impactMap.generateImpactMap(CWD, {
|
|
3285
|
+
runId,
|
|
3286
|
+
force: process.argv.includes('--force'),
|
|
3287
|
+
...(limit == null ? {} : { limit: parsePositiveIntegerArg('--limit', limit) })
|
|
3288
|
+
});
|
|
3289
|
+
} else if (action === 'confirm') {
|
|
3290
|
+
result = impactMap.confirmImpactMap(CWD, {
|
|
3291
|
+
runId,
|
|
3292
|
+
by: argValue('--by'),
|
|
3293
|
+
allow: repeatedArg('--allow'),
|
|
3294
|
+
remove: repeatedArg('--remove')
|
|
3295
|
+
});
|
|
3296
|
+
} else if (action === 'skip') {
|
|
3297
|
+
result = impactMap.skipImpactMap(CWD, { runId, by: argValue('--by'), reason: argValue('--reason') });
|
|
3298
|
+
} else if (action === 'show') {
|
|
3299
|
+
const map = impactMap.loadImpactMap(CWD, runId);
|
|
3300
|
+
if (!map) throw Object.assign(new Error('No impact map yet. Run `impact map` first.'), { code: 'IMPACT_MAP_MISSING' });
|
|
3301
|
+
result = { map, path: `.ai-engineering-loop/runs/${runId}/${impactMap.IMPACT_MAP_FILE}` };
|
|
3302
|
+
} else if (action === 'drift') {
|
|
3303
|
+
const drift = impactMap.detectImpactDrift(CWD, { runId });
|
|
3304
|
+
result = { map: null, drift: drift.drift, path: drift.path };
|
|
3305
|
+
} else {
|
|
3306
|
+
throw Object.assign(new Error('impact must be map, show, confirm, skip, or drift'), { code: 'INVALID_USAGE' });
|
|
3307
|
+
}
|
|
3308
|
+
if (json) {
|
|
3309
|
+
console.log(JSON.stringify({ ok: true, runId, action, path: result.path, ...(result.map ? { map: result.map } : {}), ...(result.drift ? { drift: result.drift } : {}) }, null, 2));
|
|
3310
|
+
return;
|
|
3311
|
+
}
|
|
3312
|
+
if (result.drift) {
|
|
3313
|
+
log.success(`✓ impact drift checked (${result.drift.mapStatus})`);
|
|
3314
|
+
console.log(`- Changed: ${result.drift.changedFiles.length}, outside the map: ${result.drift.outOfMap.length}`);
|
|
3315
|
+
for (const file of result.drift.outOfMap) console.log(` ! ${file}`);
|
|
3316
|
+
return;
|
|
3317
|
+
}
|
|
3318
|
+
const { map } = result;
|
|
3319
|
+
log.success(`✓ impact map ${map.status} (${result.path})`);
|
|
3320
|
+
if (map.status === 'SKIPPED') {
|
|
3321
|
+
console.log(`- Skipped: ${map.skipReason}`);
|
|
3322
|
+
return;
|
|
3323
|
+
}
|
|
3324
|
+
for (const key of ['files', 'modules', 'endpoints', 'dbTables', 'tests']) {
|
|
3325
|
+
console.log(`- ${key}: ${map[key].length}`);
|
|
3326
|
+
for (const entry of map[key].slice(0, 10)) {
|
|
3327
|
+
const label = entry.route ? `${entry.method} ${entry.route} (${entry.path})` : (entry.path && key !== 'dbTables' ? entry.path : entry.name);
|
|
3328
|
+
console.log(` ${label} [${entry.confidence}] ${entry.reason}`);
|
|
3329
|
+
}
|
|
3330
|
+
}
|
|
3331
|
+
if (map.status === 'CONFIRMED') console.log(`- Allowed scope: ${map.scope.allowedPaths.length} path(s), confirmed by ${map.confirmedBy}`);
|
|
3332
|
+
else console.log('- Next: confirm with `impact confirm --by <name> [--allow <glob>]... [--remove <path>]...` or skip a trivial goal with `impact skip --by <name> --reason <text>`');
|
|
3333
|
+
} catch (err) {
|
|
3334
|
+
stageJsonError(err, json, 'IMPACT_FAILED');
|
|
3335
|
+
}
|
|
3336
|
+
}
|
|
3337
|
+
|
|
3172
3338
|
function handleReviewPack() {
|
|
3173
3339
|
const json = process.argv.includes('--json');
|
|
3174
3340
|
try {
|
|
@@ -3194,6 +3360,7 @@ function handleReviewPack() {
|
|
|
3194
3360
|
estimatedTokens: pack.estimatedTokens,
|
|
3195
3361
|
truncated: pack.truncated,
|
|
3196
3362
|
unresolvedFindings: pack.unresolvedFindings,
|
|
3363
|
+
impactDrift: pack.impactDrift,
|
|
3197
3364
|
fastPath: { eligible: fastPath.eligible, reasons: fastPath.reasons },
|
|
3198
3365
|
escalation: { requiredTier: escalation.requiredTier, reasons: escalation.reasons.map((r) => r.code) }
|
|
3199
3366
|
};
|
|
@@ -3203,6 +3370,9 @@ function handleReviewPack() {
|
|
|
3203
3370
|
console.log(`- Pack: ${result.packPath} (${result.reviewProfile}, ~${result.estimatedTokens} tokens)`);
|
|
3204
3371
|
console.log(`- Tier: ${tier || 'none'}; Devil's Advocate ${result.devilAdvocateRequired ? 'required' : 'not used (T0)'}`);
|
|
3205
3372
|
console.log(`- Judge tier floor: ${result.escalation.requiredTier}${result.escalation.reasons.length ? ` (${result.escalation.reasons.join(', ')})` : ''}`);
|
|
3373
|
+
if (result.impactDrift?.outOfMap.length) {
|
|
3374
|
+
console.log(`- Outside the impact map: ${result.impactDrift.outOfMap.join(', ')} (check their side effects)`);
|
|
3375
|
+
}
|
|
3206
3376
|
}
|
|
3207
3377
|
} catch (err) {
|
|
3208
3378
|
stageJsonError(err, json, 'REVIEW_PACK_FAILED');
|
|
@@ -3227,6 +3397,18 @@ function handleDeliver() {
|
|
|
3227
3397
|
if (approve && !by) {
|
|
3228
3398
|
throw Object.assign(new Error('--approve requires --by <name> (the approving human).'), { code: 'INVALID_USAGE' });
|
|
3229
3399
|
}
|
|
3400
|
+
// Adapter preflight (#63): UNATTENDED stops before anything is written;
|
|
3401
|
+
// ASSISTED only warns, because a human is approving this delivery.
|
|
3402
|
+
// A configured-vs-detected mismatch can be deliberate, so it never blocks.
|
|
3403
|
+
const adapterProblems = checkAdapter(CWD).filter((item) => !item.passed);
|
|
3404
|
+
const blocking = adapterProblems.filter((item) => item.id !== 'adapter-detected');
|
|
3405
|
+
if (mode === RUN_MODES.UNATTENDED && blocking.length) {
|
|
3406
|
+
throw Object.assign(
|
|
3407
|
+
new Error(`Adapter preflight failed; nothing was written. ${blocking.map((item) => `${item.id}: ${item.detail}`).join('; ')}`),
|
|
3408
|
+
{ code: 'ADAPTER_PREFLIGHT_FAILED' }
|
|
3409
|
+
);
|
|
3410
|
+
}
|
|
3411
|
+
for (const item of adapterProblems) console.error(`! ${item.id}: ${item.detail}`);
|
|
3230
3412
|
const approved = [];
|
|
3231
3413
|
if (approve && run.workflow) {
|
|
3232
3414
|
const workflow = workflowStatus(CWD, { runId });
|
|
@@ -3247,28 +3429,99 @@ function handleDeliver() {
|
|
|
3247
3429
|
if (!delivery && !(destination && summary)) {
|
|
3248
3430
|
throw Object.assign(new Error('Pass --destination <where> and --summary <text>, or write delivery.json first.'), { code: 'INVALID_USAGE' });
|
|
3249
3431
|
}
|
|
3432
|
+
// Proof-carrying receipt (#70): the final deliver step, after approval.
|
|
3433
|
+
// Missing gate artifacts leave no receipt; the delivery gate then reports them.
|
|
3434
|
+
let receipt = null;
|
|
3435
|
+
try {
|
|
3436
|
+
receipt = receipts.writeReceipt(CWD, {
|
|
3437
|
+
runId,
|
|
3438
|
+
host: argValue('--host'),
|
|
3439
|
+
model: argValue('--model'),
|
|
3440
|
+
head: argValue('--head'),
|
|
3441
|
+
evidenceLinks: repeatedArg('--evidence'),
|
|
3442
|
+
aelVersion: VERSION
|
|
3443
|
+
});
|
|
3444
|
+
} catch (err) {
|
|
3445
|
+
if (err.code !== 'RECEIPT_INPUT_MISSING') throw err;
|
|
3446
|
+
}
|
|
3250
3447
|
delivery = {
|
|
3251
3448
|
...(delivery || {}),
|
|
3252
3449
|
schemaVersion: 1,
|
|
3253
3450
|
runId,
|
|
3254
3451
|
...(destination ? { destination } : {}),
|
|
3255
3452
|
...(summary ? { summary } : {}),
|
|
3256
|
-
...(approve ? { humanApproved: true, approvedBy: by } : {})
|
|
3453
|
+
...(approve ? { humanApproved: true, approvedBy: by } : {}),
|
|
3454
|
+
...(receipt ? { receipt: { path: receipt.path, digest: receipt.receipt.digest } } : {})
|
|
3257
3455
|
};
|
|
3258
3456
|
fs.writeFileSync(deliveryPath, `${JSON.stringify(delivery, null, 2)}\n`, { mode: 0o600 });
|
|
3259
3457
|
const next = executeGate('delivery', runId);
|
|
3260
|
-
const result = {
|
|
3458
|
+
const result = {
|
|
3459
|
+
ok: true,
|
|
3460
|
+
runId,
|
|
3461
|
+
state: next.state,
|
|
3462
|
+
approvedNodes: approved,
|
|
3463
|
+
humanApproved: delivery.humanApproved === true,
|
|
3464
|
+
receipt: receipt && { path: receipt.path, markdown: receipt.markdownPath, digest: receipt.receipt.digest, missingEvidence: receipt.missing }
|
|
3465
|
+
};
|
|
3261
3466
|
if (json) console.log(JSON.stringify(result));
|
|
3262
3467
|
else {
|
|
3263
3468
|
log.success('✓ delivery gate passed');
|
|
3264
3469
|
console.log(`- State: ${next.state}`);
|
|
3265
3470
|
if (approved.length) console.log(`- Approved: ${approved.join(', ')} by ${by}`);
|
|
3471
|
+
if (receipt) console.log(`- Receipt: ${receipt.path} (digest ${receipt.receipt.digest.slice(0, 12)}); paste ${receipt.markdownPath} into the PR/MR body`);
|
|
3472
|
+
if (receipt?.missing.length) console.log(`! Missing AC evidence (❌ in the receipt): ${receipt.missing.join(', ')}`);
|
|
3266
3473
|
}
|
|
3267
3474
|
} catch (err) {
|
|
3268
3475
|
stageJsonError(err, json, 'DELIVER_FAILED');
|
|
3269
3476
|
}
|
|
3270
3477
|
}
|
|
3271
3478
|
|
|
3479
|
+
function handleVerifyReceipt() {
|
|
3480
|
+
const json = process.argv.includes('--json');
|
|
3481
|
+
try {
|
|
3482
|
+
const positional = args.slice(1).find((arg, index, list) => !arg.startsWith('--') && !['--run', '--head'].includes(list[index - 1]));
|
|
3483
|
+
const result = receipts.verifyReceipt(CWD, {
|
|
3484
|
+
runId: argValue('--run'),
|
|
3485
|
+
receiptPath: positional,
|
|
3486
|
+
head: argValue('--head')
|
|
3487
|
+
});
|
|
3488
|
+
if (json) console.log(JSON.stringify(result));
|
|
3489
|
+
else if (result.ok) {
|
|
3490
|
+
log.success(`✓ receipt verified (${result.path}, digest ${result.digest.slice(0, 12)})`);
|
|
3491
|
+
} else {
|
|
3492
|
+
log.error(`Receipt check failed (${result.path})`);
|
|
3493
|
+
for (const problem of result.problems) console.error(`- ${problem.code}: ${problem.detail}`);
|
|
3494
|
+
}
|
|
3495
|
+
if (!result.ok) process.exitCode = 1;
|
|
3496
|
+
} catch (err) {
|
|
3497
|
+
stageJsonError(err, json, 'VERIFY_RECEIPT_FAILED');
|
|
3498
|
+
}
|
|
3499
|
+
}
|
|
3500
|
+
|
|
3501
|
+
function handleLearn() {
|
|
3502
|
+
const json = process.argv.includes('--json');
|
|
3503
|
+
try {
|
|
3504
|
+
const maxAge = argValue('--max-age-runs');
|
|
3505
|
+
const result = learn(CWD, {
|
|
3506
|
+
dryRun: process.argv.includes('--dry-run'),
|
|
3507
|
+
prune: process.argv.includes('--prune'),
|
|
3508
|
+
...(maxAge == null ? {} : { maxAgeRuns: parsePositiveIntegerArg('--max-age-runs', maxAge) })
|
|
3509
|
+
});
|
|
3510
|
+
const { document } = result;
|
|
3511
|
+
if (json) {
|
|
3512
|
+
console.log(JSON.stringify({ ok: true, written: result.written, path: result.path, pruned: result.pruned, learnings: document }));
|
|
3513
|
+
return;
|
|
3514
|
+
}
|
|
3515
|
+
log.success(`✓ ${document.entries.length} learning(s) from ${document.sourceRuns} Run(s)${result.written ? ` → ${result.path}` : ' (dry run, nothing written)'}`);
|
|
3516
|
+
for (const entry of document.entries.slice(0, 10)) {
|
|
3517
|
+
console.log(`- ${entry.id} [${entry.axis}, ${entry.severity}, ×${entry.occurrences}] ${entry.lesson}`);
|
|
3518
|
+
}
|
|
3519
|
+
for (const item of result.pruned) console.log(` pruned ${item.id} (${item.reason})`);
|
|
3520
|
+
} catch (err) {
|
|
3521
|
+
stageJsonError(err, json, 'LEARN_FAILED');
|
|
3522
|
+
}
|
|
3523
|
+
}
|
|
3524
|
+
|
|
3272
3525
|
// Command: docs (read-only packaged specs)
|
|
3273
3526
|
function handleDocs() {
|
|
3274
3527
|
const json = process.argv.includes('--json');
|
|
@@ -3393,11 +3646,34 @@ Commands:
|
|
|
3393
3646
|
verify Record verification commands, gate them, compact, and scaffold claimed-vs-reality
|
|
3394
3647
|
[--run <id>] [--cmd "<command>"]... [--shell] [--serial] [--timeout-ms <n>] [--json]
|
|
3395
3648
|
default command: test_unit from .ai-engineering-loop/verification.md; commands run in parallel
|
|
3649
|
+
impact Blast-radius map of the frozen Goal before Stage 3 (written to the Run on Goal freeze)
|
|
3650
|
+
map [--run <id>] [--limit <n>] [--force] [--json] files, modules, endpoints, DB tables, tests
|
|
3651
|
+
show [--run <id>] [--json]
|
|
3652
|
+
confirm --by <name> [--allow <glob>]... [--remove <path>]... [--run <id>] [--json]
|
|
3653
|
+
confirmed paths become the Run's allowed scope; verify reports changes outside it
|
|
3654
|
+
skip --by <name> --reason <text> [--run <id>] trivial goals (copy, CSS, comments)
|
|
3655
|
+
drift [--run <id>] [--json] compare the gated Maker diff with the map
|
|
3656
|
+
guard Runtime guardrail for one tool call: allow | warn | block (warn/block recorded in the Run)
|
|
3657
|
+
check --tool edit|bash (--input -|<file> | --path <file> | --command <text>) [--run <id>] [--json]
|
|
3658
|
+
check --hook claude read a Claude Code PreToolUse payload on stdin and answer deny/ask
|
|
3659
|
+
edit: outside Goal scope.allowedPaths + confirmed impact map, or in scope.deniedPaths
|
|
3660
|
+
bash: rm -rf, DROP TABLE/TRUNCATE, git push --force, git reset --hard, git clean -fd
|
|
3661
|
+
ASSISTED warns (the host asks), UNATTENDED and REPORT_ONLY block (exit 2)
|
|
3662
|
+
hooks Install native pre-tool hooks that call guard check (enforced hosts: Claude Code)
|
|
3663
|
+
install | uninstall | status [--host claude] [--json] writes .claude/settings.json
|
|
3396
3664
|
review-pack Build the Devil's Advocate pack: fast-path, diff hunks, escalation floor, tier
|
|
3397
3665
|
[--run <id>] [--base <git-ref>] [--profile lean|standard|thorough] [--json]
|
|
3398
3666
|
deliver Approve READY approval nodes, write delivery.json, and pass the delivery gate
|
|
3399
3667
|
[--run <id>] [--destination <where> --summary <text>] [--approve --by <name>] [--json]
|
|
3400
3668
|
ASSISTED requires --approve --by <name>, given only after explicit human approval
|
|
3669
|
+
[--host <id>] [--model <id>] [--head <sha>] [--evidence AC-N=<https-url>]...
|
|
3670
|
+
writes RUN_DIR/receipt.json + receipt.md (paste into the PR/MR body); digest stored in delivery.json
|
|
3671
|
+
verify-receipt Re-check a delivery receipt: artifact hashes, frozen Goal, AC evidence, verdict, head SHA
|
|
3672
|
+
[--run <id> | <repository-relative-receipt.json>] [--head <sha>] [--json] exit 1 on mismatch (CI)
|
|
3673
|
+
learn Mine past Runs' VALID findings into .ai-engineering-loop/learnings.json (+ .md) for context packs
|
|
3674
|
+
[--dry-run] [--prune] [--max-age-runs <n>] [--json]
|
|
3675
|
+
deterministic and deduped with runId provenance; --prune drops lessons whose files are gone
|
|
3676
|
+
or not seen in the last <n> Runs (default 20); maker / devil-advocate packs get the top entries
|
|
3401
3677
|
docs Print a packaged spec without needing the package source tree
|
|
3402
3678
|
list [--json]
|
|
3403
3679
|
<name> [--section <heading>] [--json] e.g. docs grill-policy --section "When to grill"
|
|
@@ -3493,7 +3769,7 @@ if (['init', 'run', 'status', 'refresh'].includes(command)) {
|
|
|
3493
3769
|
maybeAutoUpdate();
|
|
3494
3770
|
}
|
|
3495
3771
|
|
|
3496
|
-
if (!['setup', 'hosts', 'sync-hosts', '-h', '--help', '-v', '--version'].includes(command)) maybeSetupHint();
|
|
3772
|
+
if (!['setup', 'hosts', 'sync-hosts', 'guard', '-h', '--help', '-v', '--version'].includes(command)) maybeSetupHint();
|
|
3497
3773
|
if (command === 'status') maybeNewHostsNotice();
|
|
3498
3774
|
|
|
3499
3775
|
switch (command) {
|
|
@@ -3563,9 +3839,24 @@ switch (command) {
|
|
|
3563
3839
|
case 'verify':
|
|
3564
3840
|
handleVerify();
|
|
3565
3841
|
break;
|
|
3842
|
+
case 'guard':
|
|
3843
|
+
handleGuard();
|
|
3844
|
+
break;
|
|
3845
|
+
case 'hooks':
|
|
3846
|
+
handleHooks();
|
|
3847
|
+
break;
|
|
3848
|
+
case 'impact':
|
|
3849
|
+
handleImpact();
|
|
3850
|
+
break;
|
|
3566
3851
|
case 'review-pack':
|
|
3567
3852
|
handleReviewPack();
|
|
3568
3853
|
break;
|
|
3854
|
+
case 'learn':
|
|
3855
|
+
handleLearn();
|
|
3856
|
+
break;
|
|
3857
|
+
case 'verify-receipt':
|
|
3858
|
+
handleVerifyReceipt();
|
|
3859
|
+
break;
|
|
3569
3860
|
case 'deliver':
|
|
3570
3861
|
handleDeliver();
|
|
3571
3862
|
break;
|
|
@@ -0,0 +1,37 @@
|
|
|
1
|
+
# Blast-Radius Impact Map
|
|
2
|
+
|
|
3
|
+
Scope is decided before code, not discovered after it. Once the Goal Contract is frozen, the CLI writes a heuristic **impact map** into the Run: `.ai-engineering-loop/runs/<runId>/impact-map.json` (schema: `schemas/impact-map.schema.json`). It works on every adapter and in any language the repository uses; it does not depend on DOT or on Indonesian prompts.
|
|
4
|
+
|
|
5
|
+
## What it lists
|
|
6
|
+
|
|
7
|
+
Each entry has a `confidence` (0–1) and a `reason`.
|
|
8
|
+
|
|
9
|
+
| Section | Source |
|
|
10
|
+
|---|---|
|
|
11
|
+
| `files` | Indexed source files whose path or exported symbols match keywords from the Goal objective, AC statements, and failure cases (English and Indonesian filler words are dropped) |
|
|
12
|
+
| `modules` | The top two directory levels of the matched files |
|
|
13
|
+
| `endpoints` | Route declarations in matched files (`router.post('/x')`, `app.get(...)`, `@Get('/x')`) |
|
|
14
|
+
| `dbTables` | Matching migrations/`.sql` files and `CREATE`/`ALTER`/`DROP TABLE` names found in them |
|
|
15
|
+
| `tests` | Matching test files and tests named after a matched source file |
|
|
16
|
+
|
|
17
|
+
The scan is deterministic (`generator: heuristic-v1`): no model call and no call graph. Treat it as a starting point for the human, not as proof.
|
|
18
|
+
|
|
19
|
+
## Lifecycle
|
|
20
|
+
|
|
21
|
+
```bash
|
|
22
|
+
npx ai-engineering-loop goal freeze --latest --run <id> --by human # writes impact-map.json (DRAFT)
|
|
23
|
+
npx ai-engineering-loop impact show --run <id>
|
|
24
|
+
npx ai-engineering-loop impact confirm --run <id> --by <name> [--allow 'docs/**'] [--remove src/x.js]
|
|
25
|
+
# or, for copy / CSS / comment-only goals:
|
|
26
|
+
npx ai-engineering-loop impact skip --run <id> --by <name> --reason "copy-only change"
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
- **DRAFT**: written on Goal freeze (and before `gate maker` if it is still missing). `impact map --force` regenerates it.
|
|
30
|
+
- **CONFIRMED**: the human accepted or edited it. Its `scope.allowedPaths` (mapped files, tests and migrations, plus `--allow` globs, minus `--remove`) is the Run's allowed scope, which the runtime guardrail enforces. A confirmed map is locked; `impact map --force` resets it to DRAFT.
|
|
31
|
+
- **SKIPPED**: trivial goal; `skipReason` is required and kept in the Run.
|
|
32
|
+
|
|
33
|
+
In ASSISTED mode, show the map to the human and confirm or edit it before Stage 3. On `adapter_type: dot` the `task-impact-inquiry` grill stays mandatory; the map records its outcome.
|
|
34
|
+
|
|
35
|
+
## Drift at verify
|
|
36
|
+
|
|
37
|
+
When the verification gate passes, the CLI compares the gated Maker diff with the map and writes `impact-drift.json` (`mapStatus`, `changedFiles`, `outOfMap`). `verify` prints any out-of-map file, `review-pack` lists them for the Devil's Advocate (`impactDrift` in the pack), and the review gate adds one `LOW` / `VALID` / `ACCEPTABLE` finding per file to `findings.json` with `source: "impact-map"`. Drift is a warning: it reaches the Judge and the delivery evidence but never blocks on its own. A DRAFT map is compared against its mapped paths (the finding says "unconfirmed"); a SKIPPED or missing map records no drift.
|
package/core/grill-policy.md
CHANGED
|
@@ -64,7 +64,7 @@ When the change can touch state, siblings, actors/approvals, or downstream work,
|
|
|
64
64
|
|
|
65
65
|
On `adapter_type: dot`, this is mandatory. On other adapters, skip only when the change cannot touch those four (copy, CSS, comment).
|
|
66
66
|
|
|
67
|
-
Canonical skill: `adapters/
|
|
67
|
+
Canonical skill (adapter-neutral): `adapters/quality/skills/task-impact-inquiry/SKILL.md`. Host copies via `sync-hosts`: `~/.claude/skills/task-impact-inquiry/`, `~/.agents/skills/task-impact-inquiry/` (Codex, Gemini CLI, Grok, Cursor, Copilot, and other shared-folder hosts), `~/.gemini/config/skills/task-impact-inquiry/` (Antigravity). Load that skill if present. If it is missing, still run this section. Do not claim the skill ran.
|
|
68
68
|
|
|
69
69
|
If Stage 1 grill already produced the matrix and the user confirmed it, do not run a second interview.
|
|
70
70
|
|
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
# Project Learnings (`ael learn`)
|
|
2
|
+
|
|
3
|
+
The same Devil's Advocate objections should not be raised Run after Run. `learn` mines the finding ledgers of past Runs (`RUN_DIR/findings.json`) into project learnings that the next Maker and Devil's Advocate packs carry.
|
|
4
|
+
|
|
5
|
+
```bash
|
|
6
|
+
npx ai-engineering-loop learn # write .ai-engineering-loop/learnings.json + learnings.md
|
|
7
|
+
npx ai-engineering-loop learn --dry-run --json
|
|
8
|
+
npx ai-engineering-loop learn --prune [--max-age-runs 20]
|
|
9
|
+
```
|
|
10
|
+
|
|
11
|
+
## What becomes a learning
|
|
12
|
+
|
|
13
|
+
- Only findings with `validity: VALID`. `INVALID` findings and findings whose `status`/`resolution`/`decision` is `REJECTED`, `DISMISSED`, `WONT_FIX` or `INVALID` are excluded. Blast-radius drift findings (`source: impact-map`) describe one Run and are skipped.
|
|
14
|
+
- Findings are clustered per review axis (`spec` / `standards`) by word overlap of their `failureScenario` (Jaccard ≥ 0.6) and deduped. Each entry keeps the highest severity, the latest wording, the file locations, the occurrence count and the `runIds` it came from.
|
|
15
|
+
- Deterministic: no model call, no timestamps of its own; the same Runs always produce the same bytes. Runs are mined oldest first, so entry ids (`L-<hash>`) stay stable.
|
|
16
|
+
- Text passes the `safe-context` secret and home-path redaction before it is written. `learnings.json` follows `schemas/learnings.schema.json`.
|
|
17
|
+
|
|
18
|
+
## Pruning
|
|
19
|
+
|
|
20
|
+
`--prune` moves entries to `suppressed` when every file they point at is gone (`files-removed`) or their last occurrence is older than the newest `--max-age-runs` Runs (`stale`). To retire a lesson by hand, set `"supersededBy": "<where the rule now lives>"` on its entry; the next `learn` suppresses it. A suppressed lesson comes back only if it recurs in a newer Run.
|
|
21
|
+
|
|
22
|
+
## In context packs
|
|
23
|
+
|
|
24
|
+
`context maker|devil-advocate` packs and the `review-pack` diff-hunk pack add up to 5 `learnings`: entries whose locations match the pack's files first (same file, then same directory), then lessons seen in 2+ Runs. They use at most 10% of the stage's token budget and never push the pack past it (`learningTokens` is counted in `estimatedTokens`). Judge packs get none.
|
|
@@ -100,6 +100,17 @@ Native Subagent Invocation: UNAVAILABLE
|
|
|
100
100
|
Review Method: Clean-Slate Artifact Isolation Barrier
|
|
101
101
|
```
|
|
102
102
|
|
|
103
|
+
If native subagent invocation is AVAILABLE but no reviewer subagent returned its own result, the mode line carries the reason, so the header is never contradictory (#57):
|
|
104
|
+
|
|
105
|
+
```text
|
|
106
|
+
Execution Mode: CONTEXT_ISOLATION_ONLY (reason: <why>)
|
|
107
|
+
Independent LLM Execution: NOT PROVEN
|
|
108
|
+
Native Subagent Invocation: AVAILABLE
|
|
109
|
+
Review Method: Clean-Slate Artifact Isolation Barrier
|
|
110
|
+
```
|
|
111
|
+
|
|
112
|
+
REPORT_ONLY (recipe `audit`) policy: when the host can invoke a native subagent, one fresh `devil-advocate` sibling reviews `report.json` before `gate report` (no Judge, no iteration loop); otherwise the same check runs in-session with a reason. `report.json` may carry a `review` block, which `gate report` validates.
|
|
113
|
+
|
|
103
114
|
### Strictly Forbidden Phrases during `CONTEXT_ISOLATION_ONLY`:
|
|
104
115
|
- *"independent agent review"*
|
|
105
116
|
- *"subagent"*
|
|
@@ -0,0 +1,35 @@
|
|
|
1
|
+
# Proof-Carrying PR Receipt
|
|
2
|
+
|
|
3
|
+
A PR/MR from the loop carries a **receipt**: a checkable summary of what was proven, not free-text claims. `deliver` writes it as the last step after approval:
|
|
4
|
+
|
|
5
|
+
- `RUN_DIR/receipt.json` (schema: `schemas/receipt.schema.json`)
|
|
6
|
+
- `RUN_DIR/receipt.md`, the "Receipt" section for the PR/MR body (GitHub, GitLab and DOT templates)
|
|
7
|
+
- `delivery.json` → `receipt: { path, digest }`
|
|
8
|
+
|
|
9
|
+
```bash
|
|
10
|
+
git commit ... # commit first: the receipt binds HEAD (or pass --head <sha>)
|
|
11
|
+
npx ai-engineering-loop deliver --run <id> --destination pr --summary "<text>" --approve --by <name> \
|
|
12
|
+
[--host claude] [--model <id>] [--evidence AC-1=https://ci.example/run/42/shot.png]
|
|
13
|
+
npx ai-engineering-loop verify-receipt --run <id> --head <pr-head-sha> # or: verify-receipt <path/to/receipt.json>
|
|
14
|
+
```
|
|
15
|
+
|
|
16
|
+
## Contents
|
|
17
|
+
|
|
18
|
+
| Field | Source |
|
|
19
|
+
|---|---|
|
|
20
|
+
| `goal` | frozen `goal-contract.json`: repo-relative path, file sha256, content hash, version, objective |
|
|
21
|
+
| `acceptanceCriteria[]` | every AC from the frozen Goal, `PASS` or `MISSING` with `missing` reasons. Evidence: the claimed-vs-reality row, every verification command (exit code, timeout status, sha256 of its output), and hosted links from `--evidence` |
|
|
22
|
+
| `verification` | diff hash, git revision, commands, optional numeric `coverage` from `verification.json` |
|
|
23
|
+
| `review` | finding-ledger summary (total, valid, blocking, by severity) and the Judge verdict (verdict, model tier, decided by) |
|
|
24
|
+
| `impact`, `guard` | blast-radius drift (#71) and guardrail warn/block counts (#59) when present |
|
|
25
|
+
| `base`, `head`, `host` | Run start revision, `HEAD` (or `--head`), host id and model |
|
|
26
|
+
| `artifacts[]` | sha256 of the Goal, diff, verification, findings, verdict, impact map/drift, guard events and claimed-vs-reality |
|
|
27
|
+
| `digest` | sha256 of the canonical receipt body |
|
|
28
|
+
|
|
29
|
+
An AC is `PASS` only when it has a filled claimed-vs-reality row and every recorded verification command passed. Missing evidence is an explicit ❌; it is never dropped. `deliver` still finishes (the human approved it) but prints the missing AC ids.
|
|
30
|
+
|
|
31
|
+
No secrets and no local absolute paths: text is redacted, artifact paths are repository-relative, and screenshots are only accepted as `http(s)` links without credentials.
|
|
32
|
+
|
|
33
|
+
## `verify-receipt`
|
|
34
|
+
|
|
35
|
+
Exit 1 (usable in CI) when any of these fail: `RECEIPT_DIGEST_MISMATCH` (receipt edited), `ARTIFACT_MISSING` / `ARTIFACT_TAMPERED` (an artifact's sha256 changed), `GOAL_CHANGED`, `AC_NOT_IN_RECEIPT`, `AC_EVIDENCE_MISSING`, `VERDICT_NOT_PASS`, `BLOCKING_FINDINGS`, `HEAD_MISMATCH` (receipt head ≠ `--head`, default the checkout's `HEAD`). It reads the Run directory, so it runs where the Run lives (the developer machine, or CI with the Run attached). Signing the digest is not implemented yet; the schema reserves `signature`.
|