ai-engineering-loop 1.16.0 → 1.17.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (38) hide show
  1. package/.agents/skills/ai-engineering-loop/references/loop-deliver.md +2 -1
  2. package/.agents/skills/ai-engineering-loop/references/loop-goal.md +1 -0
  3. package/.agents/skills/ai-engineering-loop/references/loop-maker.md +1 -0
  4. package/.claude/skills/ai-engineering-loop/references/loop-deliver.md +2 -1
  5. package/.claude/skills/ai-engineering-loop/references/loop-goal.md +1 -0
  6. package/.claude/skills/ai-engineering-loop/references/loop-maker.md +1 -0
  7. package/CHANGELOG.md +32 -0
  8. package/README.md +24 -22
  9. package/adapters/dot/gitlab.md +6 -0
  10. package/adapters/github/pull-request.md +5 -0
  11. package/adapters/gitlab/merge-request.md +5 -0
  12. package/adapters/quality/skills/task-impact-inquiry/SKILL.md +2 -0
  13. package/bin/ai-engineering-loop.js +294 -4
  14. package/core/blast-radius-map.md +37 -0
  15. package/core/learnings.md +24 -0
  16. package/core/pr-receipt.md +35 -0
  17. package/core/runtime-safety.md +24 -0
  18. package/lib/cli-args.js +5 -1
  19. package/lib/doctor.js +4 -1
  20. package/lib/gates.js +39 -0
  21. package/lib/guard-hooks.js +115 -0
  22. package/lib/guard.js +336 -0
  23. package/lib/hosts/commands.js +4 -3
  24. package/lib/hosts/doctor.js +3 -3
  25. package/lib/hosts/registry.js +21 -2
  26. package/lib/hosts/table.js +6 -4
  27. package/lib/impact-map.js +501 -0
  28. package/lib/learn.js +303 -0
  29. package/lib/receipt.js +362 -0
  30. package/lib/safe-context.js +14 -0
  31. package/lib/smart-context.js +21 -0
  32. package/package.json +1 -1
  33. package/schemas/delivery.schema.json +11 -1
  34. package/schemas/finding-ledger.schema.json +2 -1
  35. package/schemas/goal-contract.schema.json +9 -0
  36. package/schemas/impact-map.schema.json +78 -0
  37. package/schemas/learnings.schema.json +47 -0
  38. package/schemas/receipt.schema.json +102 -0
@@ -67,6 +67,11 @@ const {
67
67
  judgeRequirement
68
68
  } = require('../lib/gates.js');
69
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');
70
75
  const {
71
76
  createContextPack,
72
77
  contextPackSummary
@@ -1822,9 +1827,12 @@ function executeGate(gate, runId) {
1822
1827
  });
1823
1828
  }
1824
1829
  }
1830
+ if (gate === 'maker') ensureImpactMap(target.runId);
1825
1831
  const run = target.workflow
1826
1832
  ? applyWorkflowGate(CWD, gate, { runId: target.runId }).run
1827
1833
  : applyGate(CWD, gate, { runId: target.runId });
1834
+ if (gate === 'goal') ensureImpactMap(target.runId);
1835
+ if (gate === 'verification') recordImpactDrift(target.runId);
1828
1836
  const runCompleted = run.state === 'DELIVERED' || run.state === 'REPORTED';
1829
1837
  appendRunLifecycle(CWD, target.runId, {
1830
1838
  type: runCompleted
@@ -1839,6 +1847,31 @@ function executeGate(gate, runId) {
1839
1847
  return run;
1840
1848
  }
1841
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
+
1842
1875
  // `gate maker --from-git` (issue #35): write the working-tree diff (tracked and
1843
1876
  // untracked files, excluding .ai-engineering-loop/) to RUN_DIR/diff.patch so the
1844
1877
  // agent does not need a separate write step. ASSISTED/REPORT_ONLY only;
@@ -1879,6 +1912,7 @@ function handleGate() {
1879
1912
  }
1880
1913
  const run = executeGate(gate, target.runId);
1881
1914
  const judge = gate === 'review' && run.tier ? judgeRequirement(CWD, run) : null;
1915
+ const guardEvents = guard.guardSummary(CWD, run.runId);
1882
1916
  if (json) {
1883
1917
  console.log(JSON.stringify({
1884
1918
  ok: true,
@@ -1887,13 +1921,17 @@ function handleGate() {
1887
1921
  iteration: run.iteration,
1888
1922
  gate,
1889
1923
  ...(run.tier ? { tier: run.tier.current } : {}),
1890
- ...(judge ? { judgeRequired: judge.required, judgeReasons: judge.reasons } : {})
1924
+ ...(judge ? { judgeRequired: judge.required, judgeReasons: judge.reasons } : {}),
1925
+ guard: guardEvents
1891
1926
  }));
1892
1927
  } else {
1893
1928
  log.success(`✓ ${gate} gate passed`);
1894
1929
  console.log(`- Run: ${run.runId}`);
1895
1930
  console.log(`- State: ${run.state}, iteration ${run.iteration}`);
1896
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
+ }
1897
1935
  if (judge) {
1898
1936
  console.log(judge.required
1899
1937
  ? `- Judge: REQUIRED (${judge.reasons.join('; ')}). Spawn the Judge subagent, write verdict.json, then gate judge.`
@@ -2918,6 +2956,7 @@ function handleGoal() {
2918
2956
  actor: argValue('--by') || 'human',
2919
2957
  message: 'Goal Contract frozen'
2920
2958
  });
2959
+ ensureImpactMap(runId);
2921
2960
  } else {
2922
2961
  const error = new Error('goal must be show, draft, or freeze');
2923
2962
  error.code = 'INVALID_USAGE';
@@ -3125,6 +3164,7 @@ async function handleVerify() {
3125
3164
  return;
3126
3165
  }
3127
3166
  const run = executeGate('verification', runId);
3167
+ const drift = impactMap.loadImpactDrift(CWD, runId) || { mapStatus: 'MISSING', outOfMap: [] };
3128
3168
  const compact = compactRun(CWD, { runId });
3129
3169
  let claimed = { path: '.ai-engineering-loop/tasks/claimed-vs-reality.md', created: false };
3130
3170
  try {
@@ -3139,6 +3179,7 @@ async function handleVerify() {
3139
3179
  tier: run.tier ? run.tier.current : null,
3140
3180
  commands,
3141
3181
  testCounts: recorded.summary.testCounts,
3182
+ impactDrift: { mapStatus: drift.mapStatus, outOfMap: drift.outOfMap },
3142
3183
  compact: compact.paths,
3143
3184
  claimedVsReality: claimed,
3144
3185
  next: run.tier && run.tier.current === 'T0'
@@ -3150,6 +3191,11 @@ async function handleVerify() {
3150
3191
  log.success('✓ verification recorded and gated');
3151
3192
  for (const c of commands) console.log(`- ${c.command}: exit ${c.exitCode}`);
3152
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
+ }
3153
3199
  console.log(`- Claimed-vs-reality: ${claimed.path}${claimed.created ? ' (scaffolded; fill it from the command output)' : ''}`);
3154
3200
  console.log(`- Next: ${result.next}`);
3155
3201
  }
@@ -3158,6 +3204,137 @@ async function handleVerify() {
3158
3204
  }
3159
3205
  }
3160
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
+
3161
3338
  function handleReviewPack() {
3162
3339
  const json = process.argv.includes('--json');
3163
3340
  try {
@@ -3183,6 +3360,7 @@ function handleReviewPack() {
3183
3360
  estimatedTokens: pack.estimatedTokens,
3184
3361
  truncated: pack.truncated,
3185
3362
  unresolvedFindings: pack.unresolvedFindings,
3363
+ impactDrift: pack.impactDrift,
3186
3364
  fastPath: { eligible: fastPath.eligible, reasons: fastPath.reasons },
3187
3365
  escalation: { requiredTier: escalation.requiredTier, reasons: escalation.reasons.map((r) => r.code) }
3188
3366
  };
@@ -3192,6 +3370,9 @@ function handleReviewPack() {
3192
3370
  console.log(`- Pack: ${result.packPath} (${result.reviewProfile}, ~${result.estimatedTokens} tokens)`);
3193
3371
  console.log(`- Tier: ${tier || 'none'}; Devil's Advocate ${result.devilAdvocateRequired ? 'required' : 'not used (T0)'}`);
3194
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
+ }
3195
3376
  }
3196
3377
  } catch (err) {
3197
3378
  stageJsonError(err, json, 'REVIEW_PACK_FAILED');
@@ -3248,28 +3429,99 @@ function handleDeliver() {
3248
3429
  if (!delivery && !(destination && summary)) {
3249
3430
  throw Object.assign(new Error('Pass --destination <where> and --summary <text>, or write delivery.json first.'), { code: 'INVALID_USAGE' });
3250
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
+ }
3251
3447
  delivery = {
3252
3448
  ...(delivery || {}),
3253
3449
  schemaVersion: 1,
3254
3450
  runId,
3255
3451
  ...(destination ? { destination } : {}),
3256
3452
  ...(summary ? { summary } : {}),
3257
- ...(approve ? { humanApproved: true, approvedBy: by } : {})
3453
+ ...(approve ? { humanApproved: true, approvedBy: by } : {}),
3454
+ ...(receipt ? { receipt: { path: receipt.path, digest: receipt.receipt.digest } } : {})
3258
3455
  };
3259
3456
  fs.writeFileSync(deliveryPath, `${JSON.stringify(delivery, null, 2)}\n`, { mode: 0o600 });
3260
3457
  const next = executeGate('delivery', runId);
3261
- const result = { ok: true, runId, state: next.state, approvedNodes: approved, humanApproved: delivery.humanApproved === true };
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
+ };
3262
3466
  if (json) console.log(JSON.stringify(result));
3263
3467
  else {
3264
3468
  log.success('✓ delivery gate passed');
3265
3469
  console.log(`- State: ${next.state}`);
3266
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(', ')}`);
3267
3473
  }
3268
3474
  } catch (err) {
3269
3475
  stageJsonError(err, json, 'DELIVER_FAILED');
3270
3476
  }
3271
3477
  }
3272
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
+
3273
3525
  // Command: docs (read-only packaged specs)
3274
3526
  function handleDocs() {
3275
3527
  const json = process.argv.includes('--json');
@@ -3394,11 +3646,34 @@ Commands:
3394
3646
  verify Record verification commands, gate them, compact, and scaffold claimed-vs-reality
3395
3647
  [--run <id>] [--cmd "<command>"]... [--shell] [--serial] [--timeout-ms <n>] [--json]
3396
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
3397
3664
  review-pack Build the Devil's Advocate pack: fast-path, diff hunks, escalation floor, tier
3398
3665
  [--run <id>] [--base <git-ref>] [--profile lean|standard|thorough] [--json]
3399
3666
  deliver Approve READY approval nodes, write delivery.json, and pass the delivery gate
3400
3667
  [--run <id>] [--destination <where> --summary <text>] [--approve --by <name>] [--json]
3401
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
3402
3677
  docs Print a packaged spec without needing the package source tree
3403
3678
  list [--json]
3404
3679
  <name> [--section <heading>] [--json] e.g. docs grill-policy --section "When to grill"
@@ -3494,7 +3769,7 @@ if (['init', 'run', 'status', 'refresh'].includes(command)) {
3494
3769
  maybeAutoUpdate();
3495
3770
  }
3496
3771
 
3497
- 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();
3498
3773
  if (command === 'status') maybeNewHostsNotice();
3499
3774
 
3500
3775
  switch (command) {
@@ -3564,9 +3839,24 @@ switch (command) {
3564
3839
  case 'verify':
3565
3840
  handleVerify();
3566
3841
  break;
3842
+ case 'guard':
3843
+ handleGuard();
3844
+ break;
3845
+ case 'hooks':
3846
+ handleHooks();
3847
+ break;
3848
+ case 'impact':
3849
+ handleImpact();
3850
+ break;
3567
3851
  case 'review-pack':
3568
3852
  handleReviewPack();
3569
3853
  break;
3854
+ case 'learn':
3855
+ handleLearn();
3856
+ break;
3857
+ case 'verify-receipt':
3858
+ handleVerifyReceipt();
3859
+ break;
3570
3860
  case 'deliver':
3571
3861
  handleDeliver();
3572
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.
@@ -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.
@@ -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`.
@@ -19,6 +19,30 @@ npx ai-engineering-loop run --mode unattended "task"
19
19
 
20
20
  The repository policy lives at `.ai-engineering-loop/runtime-policy.json`. Invalid policy fails closed. Do not change a policy merely because an agent asks to bypass a gate.
21
21
 
22
+ ## Runtime guardrails (scope freeze and destructive commands)
23
+
24
+ Gates check artifacts after a stage. The guard checks each tool call **before** it runs:
25
+
26
+ ```bash
27
+ npx ai-engineering-loop guard check --tool edit --path src/list.js
28
+ npx ai-engineering-loop guard check --tool bash --command "git push --force"
29
+ npx ai-engineering-loop hooks install # Claude Code: .claude/settings.json PreToolUse hook
30
+ npx ai-engineering-loop hooks status | uninstall
31
+ ```
32
+
33
+ | Check | Rule |
34
+ |---|---|
35
+ | Edit / Write / MultiEdit / NotebookEdit | Blocked or warned when the file is outside the Run scope or matches `scope.deniedPaths`. `.ai-engineering-loop/` (Run artifacts) is always writable. A `REPORT_ONLY` Run may not edit at all. |
36
+ | Bash | `rm` with recursive + force flags, `DROP TABLE/DATABASE/SCHEMA`, `TRUNCATE`, `git push --force` / `-f` / `--force-with-lease` / `+refspec`, `git reset --hard`, `git clean` with `-f` and `-d`. |
37
+
38
+ **Scope** = the frozen Goal's optional `scope.allowedPaths` plus the confirmed blast-radius map (`impact confirm`, see `docs blast-radius-map`). `scope.deniedPaths` always applies. A Goal without `scope` and without a confirmed map has no path enforcement (backward compatible). Globs: `**` crosses directories, `*` and `?` stay inside one segment, a trailing `/` is a directory prefix; paths are repository-relative.
39
+
40
+ **Decision** by Run mode: `ASSISTED` → `warn` (the Claude hook answers `ask`, so the human decides); `UNATTENDED` and `REPORT_ONLY` → `block` (`deny`; CLI exit code 2). With no active Run the policy `defaultMode` applies and nothing is recorded.
41
+
42
+ **Evidence:** every warn and block is appended to `RUN_DIR/guard-events.json` (tool, rule ids, reasons, mode, redacted repository-relative target). `gate <name>` prints the counts and `--json` returns `guard: { warn, block, rules }`.
43
+
44
+ **Enforced vs advisory:** only hosts with a native pre-tool hook API are **enforced** (Claude Code today, `hooks` in `lib/hosts/registry.js`). Every other host is **advisory**: the loop instructions ask the agent to run `guard check` itself, and nothing stops a call it skips. `hosts list`, `hosts doctor`, and the README host table show the column. The guard is not a sandbox: it does not isolate the OS or the network; UNATTENDED still uses the disposable worktree.
45
+
22
46
  ## Token budget and emergency stop
23
47
 
24
48
  Check the budget once after `run` and again before each new iteration, and record provider-reported usage whenever the host returns it:
package/lib/cli-args.js CHANGED
@@ -21,8 +21,12 @@ const WRITER_COMMANDS = Object.freeze({
21
21
  'run:abandon': { flags: ['--abandon', '--yes', '--json'], valued: ['--run', '--reason', '--by'], positionals: [] },
22
22
  migrate: { flags: ['--json', '--dry-run'], valued: ['--from'], positionals: [] },
23
23
  verify: { flags: ['--json', '--serial', '--shell'], valued: ['--run', '--cmd', '--timeout-ms'], positionals: [] },
24
+ learn: { flags: ['--json', '--dry-run', '--prune'], valued: ['--max-age-runs'], positionals: [] },
25
+ guard: { flags: ['--json'], valued: ['--run', '--tool', '--input', '--path', '--command', '--hook'], positionals: ['check'] },
26
+ hooks: { flags: ['--json'], valued: ['--host'], positionals: ['install', 'uninstall', 'status'] },
27
+ impact: { flags: ['--json', '--force'], valued: ['--run', '--by', '--reason', '--allow', '--remove', '--limit'], positionals: ['map', 'show', 'confirm', 'skip', 'drift'] },
24
28
  'review-pack': { flags: ['--json'], valued: ['--run', '--base', '--profile'], positionals: [] },
25
- deliver: { flags: ['--json', '--approve'], valued: ['--run', '--destination', '--summary', '--by'], positionals: [] },
29
+ deliver: { flags: ['--json', '--approve'], valued: ['--run', '--destination', '--summary', '--by', '--host', '--model', '--head', '--evidence'], positionals: [] },
26
30
  'generate-adapter': { flags: [], valued: ['--type'], positionals: [] },
27
31
  'generate-workflow': { flags: ['--write'], valued: [], positionals: [] }
28
32
  });
package/lib/doctor.js CHANGED
@@ -44,7 +44,10 @@ const REQUIRED_SCHEMAS = [
44
44
  'compiled-plan.schema.json',
45
45
  'workflow-state.schema.json',
46
46
  'workflow-event.schema.json',
47
- 'handoff.schema.json'
47
+ 'handoff.schema.json',
48
+ 'impact-map.schema.json',
49
+ 'receipt.schema.json',
50
+ 'learnings.schema.json'
48
51
  ];
49
52
 
50
53
  function check(id, passed, detail) {