ai-engineering-loop 2.12.0 → 2.14.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 (46) hide show
  1. package/.agents/skills/ael/SKILL.md +3 -19
  2. package/.agents/skills/ael/references/loop-commands.md +5 -3
  3. package/.agents/skills/ael/references/loop-deliver.md +20 -0
  4. package/.agents/skills/ael/references/loop-goal.md +3 -2
  5. package/.agents/skills/ael/references/loop-hosts.md +10 -0
  6. package/.agents/skills/ael/references/loop-judge.md +9 -0
  7. package/.agents/skills/ael/references/loop-maker.md +1 -2
  8. package/.agents/skills/ael/references/loop-modes.md +6 -0
  9. package/.agents/skills/ael/references/loop-review.md +2 -6
  10. package/CHANGELOG.md +35 -0
  11. package/README.md +9 -1
  12. package/agents/instruction-only/AGENTS.md +1 -1
  13. package/bin/ai-engineering-loop.js +398 -41
  14. package/core/dig-first.md +46 -0
  15. package/core/goal-contract.md +40 -0
  16. package/core/run-isolation.md +24 -0
  17. package/core/verification-loop.md +27 -0
  18. package/lib/adapter-check.js +3 -2
  19. package/lib/agent-artifacts.js +28 -0
  20. package/lib/budget.js +1 -1
  21. package/lib/clean-state.js +20 -0
  22. package/lib/cli-args.js +5 -2
  23. package/lib/docs.js +2 -1
  24. package/lib/doctor.js +26 -0
  25. package/lib/driver-scaffold.js +289 -0
  26. package/lib/gates.js +3 -1
  27. package/lib/gh.js +27 -0
  28. package/lib/git-readiness.js +36 -0
  29. package/lib/harness-audit.js +11 -0
  30. package/lib/pr-status.js +83 -0
  31. package/lib/provenance.js +111 -0
  32. package/lib/quick.js +11 -0
  33. package/lib/recap-html.js +3 -2
  34. package/lib/recap.js +9 -0
  35. package/lib/receipt.js +3 -1
  36. package/lib/review-ingest.js +6 -1
  37. package/lib/rules.js +4 -2
  38. package/lib/run-isolation.js +117 -27
  39. package/lib/sources.js +166 -0
  40. package/lib/stats.js +9 -0
  41. package/lib/ste.js +69 -0
  42. package/lib/sync-hosts.js +2 -0
  43. package/lib/transcript-lessons.js +232 -0
  44. package/lib/workflow-runtime.js +8 -2
  45. package/package.json +2 -2
  46. package/schemas/goal-contract.schema.json +14 -0
package/lib/gh.js ADDED
@@ -0,0 +1,27 @@
1
+ 'use strict';
2
+
3
+ const { spawnSync } = require('child_process');
4
+
5
+ function ghCommand() {
6
+ const custom = process.env.AEL_GH_BIN;
7
+ if (custom && /\.(c|m)?js$/.test(custom)) return [process.execPath, [custom]];
8
+ return [custom || 'gh', []];
9
+ }
10
+
11
+ function ghJson(args, { cwd, timeoutMs = 20000 } = {}) {
12
+ const [bin, prefix] = ghCommand();
13
+ const result = spawnSync(bin, [...prefix, ...args], { cwd, encoding: 'utf8', timeout: timeoutMs });
14
+ if (result.error?.code === 'ENOENT') return { ok: false, reason: 'missing', message: 'GitHub CLI (gh) is not installed' };
15
+ if (result.status !== 0) {
16
+ const text = `${result.stderr || ''}${result.stdout || ''}`.trim();
17
+ const reason = /auth login|not logged|authentication/i.test(text) ? 'auth' : /no pull requests? found|could not resolve/i.test(text) ? 'not-found' : 'failed';
18
+ return { ok: false, reason, message: text.split('\n')[0] || `gh exited ${result.status}` };
19
+ }
20
+ try {
21
+ return { ok: true, value: JSON.parse(result.stdout || 'null') };
22
+ } catch {
23
+ return { ok: false, reason: 'failed', message: 'gh returned output that is not JSON' };
24
+ }
25
+ }
26
+
27
+ module.exports = { ghJson };
@@ -0,0 +1,36 @@
1
+ 'use strict';
2
+
3
+ const { spawnSync } = require('child_process');
4
+
5
+ function git(rootDir, args) {
6
+ const result = spawnSync('git', args, { cwd: rootDir, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] });
7
+ return { missing: Boolean(result.error && result.error.code === 'ENOENT'), ok: result.status === 0, out: String(result.stdout || '').trim() };
8
+ }
9
+
10
+ const INSTALL = process.platform === 'darwin' ? '`xcode-select --install` (or `brew install git`)' : process.platform === 'win32' ? '`winget install Git.Git`' : '`sudo apt-get install -y git` (or your package manager)';
11
+
12
+ function gitReadiness(rootDir) {
13
+ const version = git(rootDir, ['--version']);
14
+ if (version.missing || !version.ok) {
15
+ return { ok: false, code: 'GIT_MISSING', message: 'git is not installed', why: 'AEL binds every Run to a git commit: the Maker diff, impact map, receipts and worktrees all come from git.', fix: `Install git: ${INSTALL}, then rerun this command.`, warnings: [] };
16
+ }
17
+ if (git(rootDir, ['rev-parse', '--is-inside-work-tree']).out !== 'true') {
18
+ return { ok: false, code: 'GIT_NOT_A_REPO', message: 'this folder is not a git repository', why: 'AEL reads the change from git, so the project must be a git repository.', fix: '`git init && git add -A && git commit -m "init"`, then rerun this command.', warnings: [] };
19
+ }
20
+ if (!git(rootDir, ['rev-parse', '--verify', '-q', 'HEAD']).ok) {
21
+ return { ok: false, code: 'GIT_NO_COMMIT', message: 'the repository has no commit yet', why: 'A Run starts from the current commit; without one there is nothing to diff against.', fix: '`git add -A && git commit -m "init"`, then rerun this command.', warnings: [] };
22
+ }
23
+ const warnings = [];
24
+ if (!git(rootDir, ['config', 'user.email']).out || !git(rootDir, ['config', 'user.name']).out) {
25
+ warnings.push('git user.name / user.email are not set, so you cannot commit before `deliver`. FIX: `git config --global user.name "<name>" && git config --global user.email "<email>"`.');
26
+ }
27
+ return { ok: true, code: 'GIT_READY', message: 'git ready', warnings };
28
+ }
29
+
30
+ function assertGitReady(rootDir) {
31
+ const result = gitReadiness(rootDir);
32
+ if (!result.ok) throw Object.assign(new Error(`Git is not ready: ${result.message}.`), { code: result.code, why: result.why, fix: result.fix });
33
+ return result;
34
+ }
35
+
36
+ module.exports = { assertGitReady, gitReadiness };
@@ -146,11 +146,22 @@ function auditFeatureMapDrift(rootDir) {
146
146
  return items;
147
147
  }
148
148
 
149
+ function auditDrivers(rootDir) {
150
+ const items = require('./driver-scaffold.js').driverProblems(rootDir).map((item) => ({ id: 'feature-driver', level: 'warn', detail: `Feature "${item.feature}": ${item.problem}. FIX: \`driver scaffold --feature ${item.feature}\`, or fix the Driver column.` }));
151
+ const lanes = require('./verification-lanes.js').verificationCommands(rootDir);
152
+ if (lanes.e2e || lanes.smoke) {
153
+ const missing = require('./feature-map.js').loadFeatureMap(rootDir).filter((entry) => !entry.driver).map((entry) => entry.id);
154
+ if (missing.length) items.push({ id: 'feature-driver', level: 'info', detail: `${missing.length} feature(s) have no driver, so L3 checks get rewritten each Run: ${missing.slice(0, 5).join(', ')}. FIX: \`driver scaffold\`.` });
155
+ }
156
+ return items;
157
+ }
158
+
149
159
  function auditHarness(rootDir, { budget = true } = {}) {
150
160
  const items = [
151
161
  ...auditEntryFile(rootDir),
152
162
  ...auditFeatureMap(rootDir),
153
163
  ...auditFeatureMapDrift(rootDir),
164
+ ...auditDrivers(rootDir),
154
165
  ...auditLearnings(rootDir),
155
166
  ...auditRules(rootDir),
156
167
  ...(budget ? auditBudget(rootDir) : [])
@@ -0,0 +1,83 @@
1
+ 'use strict';
2
+
3
+ const fs = require('fs');
4
+ const path = require('path');
5
+ const { ghJson } = require('./gh.js');
6
+
7
+ const FIELDS = 'number,url,state,isDraft,mergeable,mergeStateStatus,reviewDecision,statusCheckRollup,mergedAt,mergeCommit,headRefName';
8
+ const FAILED = new Set(['FAILURE', 'CANCELLED', 'TIMED_OUT', 'ACTION_REQUIRED', 'STARTUP_FAILURE', 'ERROR']);
9
+ const PENDING = new Set(['QUEUED', 'IN_PROGRESS', 'PENDING', 'WAITING', 'REQUESTED', 'EXPECTED']);
10
+
11
+ const fail = (message, code, fix) => Object.assign(new Error(message), { code, fix });
12
+ const runDir = (rootDir, runId) => path.join(rootDir, '.ai-engineering-loop', 'runs', runId);
13
+
14
+ function readJson(file) {
15
+ try {
16
+ return JSON.parse(fs.readFileSync(file, 'utf8'));
17
+ } catch {
18
+ return null;
19
+ }
20
+ }
21
+
22
+ function branchForRun(rootDir, runId) {
23
+ const registry = readJson(path.join(rootDir, '.ai-engineering-loop', 'worktrees.json'));
24
+ const entry = (registry?.worktrees || []).find((item) => item.runId === runId);
25
+ if (entry?.branch) return entry.branch;
26
+ const destination = readJson(path.join(runDir(rootDir, runId), 'delivery.json'))?.destination;
27
+ if (destination && !/^https?:\/\//.test(destination) && !/\s/.test(destination)) return destination;
28
+ return null;
29
+ }
30
+
31
+ function checkName(check) {
32
+ return check.name || check.context || check.workflowName || 'check';
33
+ }
34
+
35
+ function verdictOf(pr) {
36
+ if (pr.state === 'MERGED') return { verdict: 'merged', blockers: [] };
37
+ if (pr.state === 'CLOSED') return { verdict: 'closed', blockers: [] };
38
+ const checks = Array.isArray(pr.statusCheckRollup) ? pr.statusCheckRollup : [];
39
+ const failing = checks.filter((check) => FAILED.has(String(check.conclusion || check.state || '').toUpperCase())).map(checkName);
40
+ const pending = checks.filter((check) => PENDING.has(String(check.status || check.state || '').toUpperCase()) && !check.conclusion).map(checkName);
41
+ const blockers = [];
42
+ if (pr.isDraft) blockers.push('draft');
43
+ if (pr.mergeable === 'CONFLICTING' || pr.mergeStateStatus === 'DIRTY') blockers.push('merge-conflicts');
44
+ if (failing.length) blockers.push(`failing-checks: ${[...new Set(failing)].join(', ')}`);
45
+ if (pr.reviewDecision === 'CHANGES_REQUESTED') blockers.push('changes-requested');
46
+ if (blockers.length) return { verdict: 'blocker', blockers };
47
+ if (pending.length || pr.mergeable === 'UNKNOWN') return { verdict: 'waiting', blockers: [], waitingOn: [...new Set(pending)] };
48
+ if (pr.reviewDecision === 'REVIEW_REQUIRED') return { verdict: 'waiting', blockers: [], waitingOn: ['review'] };
49
+ return { verdict: 'ready', blockers: [] };
50
+ }
51
+
52
+ function recordMerge(rootDir, runId, pr) {
53
+ if (!runId || !fs.existsSync(runDir(rootDir, runId))) return false;
54
+ const file = path.join(runDir(rootDir, runId), 'merge.json');
55
+ if (fs.existsSync(file)) return false;
56
+ const value = { schemaVersion: 1, runId, pr: pr.number, url: pr.url, mergedAt: pr.mergedAt || null, mergeCommit: pr.mergeCommit?.oid || null, branch: pr.headRefName || null };
57
+ fs.writeFileSync(file, `${JSON.stringify(value, null, 2)}\n`, { mode: 0o600 });
58
+ return true;
59
+ }
60
+
61
+ function loadMerge(rootDir, runId) {
62
+ return runId ? readJson(path.join(runDir(rootDir, runId), 'merge.json')) : null;
63
+ }
64
+
65
+ function prStatus(rootDir, { runId = null, branch = null, pr = null } = {}) {
66
+ const target = pr ? String(pr).replace(/^#/, '') : branch || (runId ? branchForRun(rootDir, runId) : null);
67
+ if (!target) {
68
+ throw fail('No PR to check: pass --pr <number>, --branch <name>, or a --run whose delivery or worktree names a branch', 'INVALID_USAGE', 'ai-engineering-loop pr status --pr <number>');
69
+ }
70
+ const result = ghJson(['pr', 'view', target, '--json', FIELDS], { cwd: rootDir });
71
+ if (!result.ok) {
72
+ if (result.reason === 'missing') throw fail('GitHub CLI (gh) is not installed, so the PR state cannot be read', 'GH_UNAVAILABLE', 'Install gh (https://cli.github.com), run `gh auth login`, then retry');
73
+ if (result.reason === 'auth') throw fail('gh is not signed in, so the PR state cannot be read', 'GH_UNAVAILABLE', 'Run `gh auth login`, then retry');
74
+ if (result.reason === 'not-found') throw fail(`No pull request found for ${target}`, 'PR_NOT_FOUND', 'Open the PR first, or pass --pr <number>');
75
+ throw fail(`gh could not read the PR: ${result.message}`, 'GH_FAILED', 'Run the same `gh pr view` by hand to see why');
76
+ }
77
+ const value = result.value;
78
+ const outcome = verdictOf(value);
79
+ const recorded = outcome.verdict === 'merged' ? recordMerge(rootDir, runId, value) : false;
80
+ return { pr: value.number, url: value.url, branch: value.headRefName || null, ...outcome, ...(runId ? { runId, mergeRecorded: recorded } : {}) };
81
+ }
82
+
83
+ module.exports = { branchForRun, loadMerge, prStatus, recordMerge, verdictOf };
@@ -0,0 +1,111 @@
1
+ 'use strict';
2
+
3
+ const fs = require('fs');
4
+ const path = require('path');
5
+ const { spawnSync } = require('child_process');
6
+ const { loadGathered } = require('./sources.js');
7
+
8
+ const KINDS = ['fact', 'decision', 'assumption'];
9
+
10
+ function validateStatements(statements) {
11
+ if (statements === undefined) return [];
12
+ if (!Array.isArray(statements)) return ['statements must be an array of { text, kind, source?, by? }'];
13
+ const errors = [];
14
+ statements.forEach((item, index) => {
15
+ if (!item || typeof item !== 'object' || !String(item.text || '').trim()) errors.push(`statements[${index}].text is required`);
16
+ else if (!KINDS.includes(item.kind)) errors.push(`statements[${index}].kind must be ${KINDS.join(', ')}`);
17
+ });
18
+ return errors;
19
+ }
20
+
21
+ function checkFileLine(rootDir, ref) {
22
+ const match = String(ref).match(/^(.+?):(\d+)(?:-\d+)?$/);
23
+ if (!match) return null;
24
+ const file = path.resolve(rootDir, match[1]);
25
+ const relative = path.relative(rootDir, file);
26
+ if (relative.startsWith('..') || path.isAbsolute(relative)) return 'path is outside the repository';
27
+ let lines;
28
+ try {
29
+ lines = fs.readFileSync(file, 'utf8').split('\n').length;
30
+ } catch {
31
+ return `${match[1]} does not exist`;
32
+ }
33
+ return Number(match[2]) >= 1 && Number(match[2]) <= lines ? true : `${match[1]} has ${lines} line(s), not ${match[2]}`;
34
+ }
35
+
36
+ function checkCommit(rootDir, ref) {
37
+ if (!/^[0-9a-f]{7,40}$/i.test(String(ref))) return null;
38
+ const result = spawnSync('git', ['cat-file', '-e', `${ref}^{commit}`], { cwd: rootDir, stdio: 'ignore' });
39
+ return result.status === 0 ? true : `commit ${ref} does not exist`;
40
+ }
41
+
42
+ function checkGathered(gathered, ref) {
43
+ if (/^S-\d+$/.test(String(ref))) return gathered.some((entry) => entry.id === ref) ? true : `${ref} is not in sources.json`;
44
+ if (/^https?:\/\//i.test(String(ref))) return gathered.some((entry) => entry.ref === ref) ? true : 'URL was not recorded with `sources record`';
45
+ return null;
46
+ }
47
+
48
+ function verifySource(rootDir, gathered, ref) {
49
+ if (!String(ref || '').trim()) return 'no source';
50
+ for (const check of [checkGathered(gathered, ref), checkCommit(rootDir, ref), checkFileLine(rootDir, ref)]) {
51
+ if (check !== null) return check;
52
+ }
53
+ return 'source must be path:line, a commit SHA, a recorded URL or S-n';
54
+ }
55
+
56
+ function checkProvenance(rootDir, runId, contract) {
57
+ const gathered = loadGathered(rootDir, runId);
58
+ const statements = (Array.isArray(contract?.statements) ? contract.statements : []).map((item) => {
59
+ const declared = item.kind;
60
+ let kind = declared;
61
+ let reason = null;
62
+ if (declared === 'fact') {
63
+ const result = verifySource(rootDir, gathered, item.source);
64
+ if (result !== true) {
65
+ kind = 'assumption';
66
+ reason = `fact downgraded: ${result}`;
67
+ }
68
+ } else if (declared === 'decision' && !String(item.by || '').trim()) {
69
+ const result = item.source ? verifySource(rootDir, gathered, item.source) : 'no --by and no source';
70
+ if (result !== true) {
71
+ kind = 'assumption';
72
+ reason = `decision downgraded: ${result}`;
73
+ }
74
+ }
75
+ return { text: String(item.text).trim(), declared, kind, ...(item.source ? { source: item.source } : {}), ...(item.by ? { by: item.by } : {}), ...(reason ? { reason } : {}) };
76
+ });
77
+ const assumptions = statements.filter((item) => item.kind === 'assumption');
78
+ return {
79
+ schemaVersion: 1,
80
+ runId,
81
+ counts: Object.fromEntries(KINDS.map((kind) => [kind, statements.filter((item) => item.kind === kind).length])),
82
+ downgraded: statements.filter((item) => item.reason).length,
83
+ statements,
84
+ unconfirmed: assumptions.map((item) => item.reason ? `${item.text} (${item.reason})` : item.text)
85
+ };
86
+ }
87
+
88
+ function provenancePath(rootDir, runId) {
89
+ return path.join(rootDir, '.ai-engineering-loop', 'runs', runId, 'provenance.json');
90
+ }
91
+
92
+ function writeProvenance(rootDir, runId, contract) {
93
+ const result = checkProvenance(rootDir, runId, contract);
94
+ fs.writeFileSync(provenancePath(rootDir, runId), `${JSON.stringify(result, null, 2)}\n`, { mode: 0o600 });
95
+ return result;
96
+ }
97
+
98
+ function loadProvenance(rootDir, runId) {
99
+ try {
100
+ return JSON.parse(fs.readFileSync(provenancePath(rootDir, runId), 'utf8'));
101
+ } catch {
102
+ return null;
103
+ }
104
+ }
105
+
106
+ function renderUnconfirmed(provenance, heading = '### Unconfirmed assumptions') {
107
+ if (!provenance || !provenance.unconfirmed.length) return [];
108
+ return [heading, '', ...provenance.unconfirmed.map((text) => `- ${text}`), ''];
109
+ }
110
+
111
+ module.exports = { KINDS, checkProvenance, loadProvenance, renderUnconfirmed, validateStatements, writeProvenance };
package/lib/quick.js CHANGED
@@ -63,6 +63,17 @@ function quickGoal(runId, task) {
63
63
 
64
64
  function startQuick(rootDir, { task, mode = null } = {}) {
65
65
  if (!String(task || '').trim()) throw quickError('quick start needs a task: quick start "<task>"', 'INVALID_USAGE');
66
+ const ready = require('./git-readiness.js').gitReadiness(rootDir);
67
+ if (!ready.ok) throw Object.assign(quickError(`Cannot start a Run: ${ready.message}.`, ready.code), { why: ready.why, fix: ready.fix });
68
+ const { getCurrentRun } = require('./run-state.js');
69
+ let current = null;
70
+ try {
71
+ current = getCurrentRun(rootDir);
72
+ } catch {
73
+ current = null;
74
+ }
75
+ const conflict = require('./run-isolation.js').runConflict(rootDir, current, task);
76
+ if (conflict) throw Object.assign(quickError(`Run ${conflict.runId} (${conflict.state}) is unfinished and works on a different task. Ask the human which option to take; do not pick one yourself.`, 'RUN_CONFLICT'), { conflict, fix: conflict.options.map((option) => `${option.label}: ${option.command}`).join(' | ') });
66
77
  const run = invoke(rootDir, ['run', '--new', ...(mode ? ['--mode', mode] : []), task]);
67
78
  if (run.tier !== 'T0') {
68
79
  return {
package/lib/recap-html.js CHANGED
@@ -170,7 +170,8 @@ function featureCard(run) {
170
170
  n ? `<span class="pill ${n > 1 ? 'warn' : 'ok'}">${n} iteration${n > 1 ? 's' : ''}</span>` : '',
171
171
  run.commands.length ? `<span class="pill ${green === run.commands.length ? 'ok' : 'bad'}">${green}/${run.commands.length} checks green</span>` : '',
172
172
  run.outOfMap.length ? `<span class="pill warn">${run.outOfMap.length} outside impact map</span>` : '',
173
- run.openFindings ? `<span class="pill warn">${run.openFindings} open findings</span>` : ''
173
+ run.openFindings ? `<span class="pill warn">${run.openFindings} open findings</span>` : '',
174
+ run.merge ? `<span class="pill ok">merged${run.merge.lagMs != null ? ` ${fmtDur(run.merge.lagMs)} after delivery` : ''}</span>` : (run.delivered ? '<span class="pill muted">not merged yet</span>' : '')
174
175
  ].join('');
175
176
  const meta = [esc(run.project), esc(fmtDate(run.date)), run.branch ? `<code>${esc(run.branch)}</code>` : '', run.approvedBy ? `approved by ${esc(run.approvedBy)}` : ''].filter(Boolean);
176
177
  return `<article class="feature"><header><div><h3 style="max-width:60ch">${esc(run.title)}</h3><p>${meta.join(' · ')}</p></div><div class="tags">${tags}</div></header>${evidence(run)}</article>`;
@@ -199,7 +200,7 @@ function renderRecap(data, { audience = 'me', now = new Date(), lang = null } =
199
200
  <div class="panel"><h2>Activity per day</h2>${heatmap(data)}</div>
200
201
  <div class="panel"><h2>Where the time went</h2>${stageBars(runs)}</div>
201
202
  <div class="panel"><h2>Why runs had to iterate</h2>${causes(metrics)}</div>` : `<div class="panel">${empty}</div>`;
202
- const lead = runs.length ? `<div class="metrics">${metric('Delivered', metrics.delivered, prev?.delivered)}${metric('Passed on the first try', metrics.firstPassRate, prev?.firstPassRate, { kind: 'pct' })}${metric('Median cycle time', metrics.medianCycleMs, prev?.medianCycleMs, { kind: 'dur', lowerIsBetter: true })}${metric('High-risk (T2) runs', metrics.t2, prev?.t2, { lowerIsBetter: true })}${metric('Times a human stepped in, per run', metrics.interventionsPerRun, prev?.interventionsPerRun, { lowerIsBetter: true })}</div>${technical.length ? `<div class="panel"><h2>Before you share the client tab</h2><p>${technical.length} delivered run${technical.length === 1 ? ' has' : 's have'} no <code>plainSummary</code>, so the client tab shows the technical objective: ${technical.map((run) => `<b>${esc(run.title)}</b>`).join(', ')}. Add a one-sentence <code>plainSummary</code> to the Goal and rerun the recap.</p></div>` : ''}<h2>Work and its evidence</h2><div${contentLang}>${runs.slice().reverse().map(featureCard).join('')}</div>` : `<div class="panel">${empty}</div>`;
203
+ const lead = runs.length ? `<div class="metrics">${metric('Delivered', metrics.delivered, prev?.delivered)}${metric('Passed on the first try', metrics.firstPassRate, prev?.firstPassRate, { kind: 'pct' })}${metric('Median cycle time', metrics.medianCycleMs, prev?.medianCycleMs, { kind: 'dur', lowerIsBetter: true })}${metric('High-risk (T2) runs', metrics.t2, prev?.t2, { lowerIsBetter: true })}${metric('Merged into main', metrics.merged, prev?.merged)}${metric('Times a human stepped in, per run', metrics.interventionsPerRun, prev?.interventionsPerRun, { lowerIsBetter: true })}</div>${technical.length ? `<div class="panel"><h2>Before you share the client tab</h2><p>${technical.length} delivered run${technical.length === 1 ? ' has' : 's have'} no <code>plainSummary</code>, so the client tab shows the technical objective: ${technical.map((run) => `<b>${esc(run.title)}</b>`).join(', ')}. Add a one-sentence <code>plainSummary</code> to the Goal and rerun the recap.</p></div>` : ''}<h2>Work and its evidence</h2><div${contentLang}>${runs.slice().reverse().map(featureCard).join('')}</div>` : `<div class="panel">${empty}</div>`;
203
204
  const tab = (view, text) => `<button type="button" aria-controls="${view}" data-view="${view}" aria-pressed="${view === audience}">${text}</button>`;
204
205
  const section = (view, html) => `<section class="view${view === audience ? ' on' : ''}" id="${view}" aria-label="${esc({ me: 'For me', lead: 'For the lead', client: 'For the client' }[view])}">${html}</section>`;
205
206
  const range = `${fmtDate(data.window.from)} – ${fmtDate(new Date(data.window.to.getTime() - 1))}`;
package/lib/recap.js CHANGED
@@ -111,6 +111,13 @@ function loadRun(projectPath, runId) {
111
111
  openFindings: Array.isArray(summary.openFindings) ? summary.openFindings.length : 0,
112
112
  stages: stageDurations(history),
113
113
  interventions: require('./interventions.js').runInterventions(dir),
114
+ merge: (() => {
115
+ const merge = require('./pr-status.js').loadMerge(projectPath, runId);
116
+ const delivered = history.filter((entry) => entry.to === 'DELIVERED').pop();
117
+ if (!merge) return null;
118
+ const lagMs = merge.mergedAt && delivered ? Math.max(0, Date.parse(merge.mergedAt) - Date.parse(delivered.at)) : null;
119
+ return { pr: merge.pr, url: merge.url, mergedAt: merge.mergedAt, lagMs };
120
+ })(),
114
121
  files
115
122
  };
116
123
  }
@@ -147,6 +154,8 @@ function metricsOf(runs) {
147
154
  firstPassRate: judged.length ? Math.round((judged.filter((run) => run.iterations[0].verdict === 'PASS').length / judged.length) * 100) : null,
148
155
  medianCycleMs: median(runs.filter((run) => run.delivered).map(cycle).filter(Boolean)),
149
156
  t2: runs.filter((run) => run.tier === 'T2').length,
157
+ merged: runs.filter((run) => run.merge).length,
158
+ medianMergeLagMs: median(runs.map((run) => run.merge?.lagMs).filter((value) => value != null)),
150
159
  interventionsPerRun: require('./interventions.js').summarizeInterventions(runs.map((run) => run.interventions)).perRun,
151
160
  causes
152
161
  };
package/lib/receipt.js CHANGED
@@ -256,7 +256,8 @@ function buildReceipt(rootDir, { runId, host, model, head, evidenceLinks = [], a
256
256
  warn: guardEvents.filter((event) => event.decision === 'warn').length,
257
257
  block: guardEvents.filter((event) => event.decision === 'block').length
258
258
  },
259
- artifacts
259
+ artifacts,
260
+ unconfirmed: (require('./provenance.js').loadProvenance(rootDir, runId) || { unconfirmed: [] }).unconfirmed
260
261
  };
261
262
  receipt.digest = receiptDigest(receipt);
262
263
  return receipt;
@@ -299,6 +300,7 @@ function renderReceiptMarkdown(receipt) {
299
300
  lines.push(`- ${criterion.status === 'PASS' ? '✅' : '❌'} **${criterion.id}** ${markdownCell(criterion.statement)}${parts.length ? ` — ${parts.join(', ')}` : ''}${missing}`);
300
301
  }
301
302
  const { findings, verdict } = receipt.review;
303
+ if (receipt.unconfirmed && receipt.unconfirmed.length) lines.push('', '### Unconfirmed assumptions', '', ...receipt.unconfirmed.map((text) => `- ${markdownCell(text)}`));
302
304
  lines.push('');
303
305
  lines.push(`Judge: **${verdict.verdict}**${verdict.modelTier ? ` (${verdict.modelTier})` : ''} · Findings: ${findings.total} (${findings.valid} valid, ${findings.blocking} blocking)` +
304
306
  `${receipt.impact ? ` · Impact map: ${receipt.impact.mapStatus}, ${receipt.impact.outOfMap.length} file(s) outside` : ''}` +
@@ -110,7 +110,12 @@ function ingestReview(rootDir, { runId, childId, file } = {}) {
110
110
  if (stat.size > MAX_RAW_BYTES) throw ingestError(`--file is larger than ${MAX_RAW_BYTES} bytes`, 'INVALID_FILE');
111
111
  const raw = fs.readFileSync(source);
112
112
  const ledger = extractLedger(raw.toString('utf8'));
113
- if (!ledger) throw ingestError('No JSON ledger with a findings array in the reviewer output', 'NO_LEDGER_IN_OUTPUT');
113
+ if (!ledger) {
114
+ throw Object.assign(ingestError('No JSON ledger with a findings array in the reviewer output', 'NO_LEDGER_IN_OUTPUT'), {
115
+ why: 'The gate reads findings from a JSON ledger in the reviewer output; prose alone cannot be checked.',
116
+ fix: 'Ask the reviewer to end with a JSON block, e.g. {"findings":[]} when clean, or {"findings":[{"id":"DA-01","severity":"high","location":"src/a.js:12","claim":"...","evidence":"..."}]}; see `docs finding-policy`. Then rerun `review ingest`.'
117
+ });
118
+ }
114
119
  const runDir = path.join(runsDir(rootDir), run.runId);
115
120
  fs.writeFileSync(path.join(runDir, RAW_FILE), raw, { mode: 0o600 });
116
121
  const document = {
package/lib/rules.js CHANGED
@@ -27,11 +27,13 @@ function loadRules(rootDir) {
27
27
  }
28
28
 
29
29
  function loadLearningEntries(rootDir) {
30
+ let entries = [];
30
31
  try {
31
- return JSON.parse(fs.readFileSync(path.join(rootDir, '.ai-engineering-loop', 'learnings.json'), 'utf8')).entries || [];
32
+ entries = JSON.parse(fs.readFileSync(path.join(rootDir, '.ai-engineering-loop', 'learnings.json'), 'utf8')).entries || [];
32
33
  } catch {
33
- return [];
34
+ entries = [];
34
35
  }
36
+ return [...entries, ...require('./transcript-lessons.js').loadTranscriptLessons(rootDir)];
35
37
  }
36
38
 
37
39
  const SCOPES = Object.freeze(['repo', 'diff']);
@@ -132,9 +132,17 @@ function registerWorktree(mainRoot, entry) {
132
132
  saveRegistry(mainRoot, registry);
133
133
  }
134
134
 
135
- function isDirty(worktreePath) {
135
+ function dirtyKind(worktreePath) {
136
136
  const out = git(worktreePath, ['status', '--porcelain', '--', '.', ':(exclude).ai-engineering-loop'], { allowFail: true });
137
- return out == null ? true : out.split('\n').filter(Boolean).length > 0;
137
+ if (out == null) return { kind: 'wip', tracked: 0, untracked: 0 };
138
+ const lines = out.split('\n').filter(Boolean);
139
+ const untracked = lines.filter((line) => line.startsWith('??')).length;
140
+ const tracked = lines.length - untracked;
141
+ return { kind: tracked ? 'wip' : untracked ? 'scratch' : 'clean', tracked, untracked };
142
+ }
143
+
144
+ function isDirty(worktreePath) {
145
+ return dirtyKind(worktreePath).kind !== 'clean';
138
146
  }
139
147
 
140
148
  function copyEvidence(worktreePath, mainRoot, runId) {
@@ -182,19 +190,67 @@ function defaultBranch(mainRoot) {
182
190
  return null;
183
191
  }
184
192
 
185
- function isMerged(mainRoot, branch) {
193
+ function isMerged(mainRoot, branch, runId = null) {
194
+ if (require('./pr-status.js').loadMerge(mainRoot, runId)) return { merged: true, source: 'merge.json' };
186
195
  if (!git(mainRoot, ['rev-parse', '--verify', '--quiet', branch], { allowFail: true })) return { merged: false, gone: true };
187
196
  const target = defaultBranch(mainRoot);
188
- if (target && spawnSync('git', ['merge-base', '--is-ancestor', branch, target], { cwd: mainRoot }).status === 0) return { merged: true };
189
- const gh = spawnSync('gh', ['pr', 'list', '--head', branch.replace(/^origin\//, ''), '--state', 'merged', '--json', 'number'], { cwd: mainRoot, encoding: 'utf8', timeout: 15000 });
190
- if (gh.status === 0) {
197
+ if (target && spawnSync('git', ['merge-base', '--is-ancestor', branch, target], { cwd: mainRoot }).status === 0) return { merged: true, source: 'ancestor' };
198
+ const gh = require('./gh.js').ghJson(['pr', 'list', '--head', branch.replace(/^origin\//, ''), '--state', 'merged', '--json', 'number'], { cwd: mainRoot, timeoutMs: 15000 });
199
+ if (gh.ok && Array.isArray(gh.value) && gh.value.length) return { merged: true, source: 'gh' };
200
+ return { merged: false };
201
+ }
202
+
203
+ function hasOpenPr(mainRoot, branch) {
204
+ if (!branch) return false;
205
+ const gh = require('./gh.js').ghJson(['pr', 'list', '--head', branch, '--state', 'open', '--json', 'number'], { cwd: mainRoot, timeoutMs: 15000 });
206
+ return gh.ok && Array.isArray(gh.value) && gh.value.length > 0;
207
+ }
208
+
209
+ function sizeOf(dir) {
210
+ let total = 0;
211
+ const stack = [dir];
212
+ while (stack.length) {
213
+ const current = stack.pop();
214
+ let entries = [];
191
215
  try {
192
- if (JSON.parse(gh.stdout || '[]').length) return { merged: true };
216
+ entries = fs.readdirSync(current, { withFileTypes: true });
193
217
  } catch {
194
- return { merged: false };
218
+ continue;
219
+ }
220
+ for (const entry of entries) {
221
+ if (entry.name === '.git') continue;
222
+ const full = path.join(current, entry.name);
223
+ if (entry.isDirectory()) stack.push(full);
224
+ else if (entry.isFile()) {
225
+ try {
226
+ total += fs.statSync(full).size;
227
+ } catch {
228
+ total += 0;
229
+ }
230
+ }
195
231
  }
196
232
  }
197
- return { merged: false };
233
+ return total;
234
+ }
235
+
236
+ function ageDays(worktreePath, now) {
237
+ const stamp = Number(git(worktreePath, ['log', '-1', '--format=%ct'], { allowFail: true }));
238
+ return Number.isFinite(stamp) && stamp > 0 ? Math.floor((now.getTime() - stamp * 1000) / 86400000) : null;
239
+ }
240
+
241
+ function gitWorktrees(mainRoot) {
242
+ const out = git(mainRoot, ['worktree', 'list', '--porcelain'], { allowFail: true }) || '';
243
+ const items = [];
244
+ let current = null;
245
+ for (const line of out.split('\n')) {
246
+ if (line.startsWith('worktree ')) {
247
+ current = { path: path.resolve(line.slice(9)), branch: null };
248
+ items.push(current);
249
+ } else if (current && line.startsWith('branch ')) {
250
+ current.branch = line.slice(7).replace(/^refs\/heads\//, '');
251
+ }
252
+ }
253
+ return items.filter((item) => realpath(item.path) !== realpath(mainRoot));
198
254
  }
199
255
 
200
256
  function runStateOf(entry, mainRoot) {
@@ -205,48 +261,81 @@ function runStateOf(entry, mainRoot) {
205
261
  return null;
206
262
  }
207
263
 
208
- function planPrune(rootDir, { now = new Date(), checkMerged = true } = {}) {
264
+ function planPrune(rootDir, { now = new Date(), checkMerged = true, checkPrs = true, includeScratch = false, audit = false, sizes = false } = {}) {
209
265
  const mainRoot = mainCheckout(rootDir) || rootDir;
210
266
  const registry = loadRegistry(mainRoot);
211
267
  const plan = [];
268
+ const registered = new Set(registry.worktrees.map((entry) => realpath(entry.path)));
212
269
  for (const entry of registry.worktrees) {
213
270
  if (entry.branchDeleted) continue;
214
271
  const exists = fs.existsSync(entry.path);
215
272
  const run = runStateOf(entry, mainRoot);
216
273
  const state = run?.state || null;
217
- const row = { path: entry.path, branch: entry.branch, runId: entry.runId || null, runState: state, actions: [], notes: [] };
218
- if (!exists && entry.state !== 'removed') {
219
- row.actions.push('forget-missing-folder');
220
- } else if (exists) {
221
- if (state === 'DELIVERED' || state === 'CANCELLED' || state === 'ESCALATED') {
222
- if (isDirty(entry.path)) row.notes.push('kept: uncommitted or untracked changes');
223
- else row.actions.push('remove-worktree');
224
- } else if (run) {
225
- const activity = runActivity(entry.path, run, { now });
226
- if (activity.idleMinutes != null && activity.idleMinutes >= IDLE_DAYS * 1440) row.notes.push(`run ${run.runId} idle ${Math.floor(activity.idleMinutes / 1440)} days: abandon it there if it is dead`);
274
+ const row = { path: entry.path, branch: entry.branch, runId: entry.runId || null, runState: state, registered: true, bucket: 'review', actions: [], notes: [] };
275
+ if (!exists) {
276
+ if (entry.state !== 'removed') {
277
+ row.bucket = 'safe';
278
+ row.actions.push('forget-missing-folder');
279
+ }
280
+ } else {
281
+ const dirty = dirtyKind(entry.path);
282
+ row.dirty = dirty;
283
+ if (sizes) row.sizeBytes = sizeOf(entry.path);
284
+ row.ageDays = ageDays(entry.path, now);
285
+ const finished = TERMINAL.has(state);
286
+ const activity = run && !finished ? runActivity(entry.path, run, { now }) : null;
287
+ if (dirty.kind === 'wip') {
288
+ row.bucket = 'hold-wip';
289
+ row.notes.push(`kept: ${dirty.tracked} changed tracked file(s)`);
290
+ } else if (activity?.live) {
291
+ row.bucket = 'hold-live-run';
292
+ row.notes.push(`kept: run ${run.runId} active ${activity.idleMinutes} minute(s) ago`);
293
+ } else if (checkPrs && hasOpenPr(mainRoot, entry.branch)) {
294
+ row.bucket = 'hold-open-pr';
295
+ row.notes.push('kept: the branch has an open pull request');
296
+ } else if (!finished) {
297
+ row.bucket = 'review';
298
+ if (activity?.idleMinutes != null && activity.idleMinutes >= IDLE_DAYS * 1440) row.notes.push(`run ${run.runId} idle ${Math.floor(activity.idleMinutes / 1440)} days: abandon it there if it is dead`);
299
+ } else if (dirty.kind === 'scratch') {
300
+ row.bucket = 'scratch';
301
+ if (includeScratch) row.actions.push('remove-worktree');
302
+ else row.notes.push(`kept: ${dirty.untracked} untracked file(s); add --include-scratch to remove them with the worktree`);
303
+ } else {
304
+ row.bucket = 'safe';
305
+ row.actions.push('remove-worktree');
227
306
  }
228
307
  }
229
308
  if (checkMerged && entry.branch && (state === 'DELIVERED' || entry.state === 'removed' || entry.state === 'delivered')) {
230
- const merged = isMerged(mainRoot, entry.branch);
309
+ const merged = isMerged(mainRoot, entry.branch, entry.runId);
231
310
  if (merged.merged) {
232
- if (exists && !row.actions.includes('remove-worktree')) row.notes.push('branch merged but worktree kept until it is clean');
311
+ if (exists && !row.actions.includes('remove-worktree')) row.notes.push('branch merged but worktree kept');
233
312
  else row.actions.push('delete-branch');
234
313
  }
235
314
  }
236
- if (row.actions.length || row.notes.length) plan.push(row);
315
+ if (audit || row.actions.length || row.notes.length) plan.push(row);
316
+ }
317
+ if (audit) {
318
+ for (const item of gitWorktrees(mainRoot)) {
319
+ if (registered.has(realpath(item.path))) continue;
320
+ const dirty = dirtyKind(item.path);
321
+ plan.push({ path: item.path, branch: item.branch, runId: null, runState: null, registered: false, bucket: 'foreign', dirty, ...(sizes ? { sizeBytes: sizeOf(item.path) } : {}), ageDays: ageDays(item.path, now), actions: [], notes: ['not created by AEL: never removed by prune'] });
322
+ }
237
323
  }
324
+ if (sizes) plan.sort((a, b) => (b.sizeBytes || 0) - (a.sizeBytes || 0));
238
325
  return { mainRoot, plan };
239
326
  }
240
327
 
241
- function applyPrune(rootDir, { now = new Date() } = {}) {
242
- const { mainRoot, plan } = planPrune(rootDir, { now });
328
+ function applyPrune(rootDir, { now = new Date(), includeScratch = false } = {}) {
329
+ const { mainRoot, plan } = planPrune(rootDir, { now, includeScratch });
243
330
  const registry = loadRegistry(mainRoot);
244
331
  const done = [];
245
332
  for (const row of plan) {
246
333
  const entry = registry.worktrees.find((item) => item.path === row.path);
334
+ if (!entry) continue;
247
335
  for (const action of row.actions) {
248
336
  if (action === 'remove-worktree') {
249
- if (isDirty(row.path)) continue;
337
+ const dirty = dirtyKind(row.path);
338
+ if (dirty.kind === 'wip' || (dirty.kind === 'scratch' && !includeScratch)) continue;
250
339
  copyEvidence(row.path, mainRoot, row.runId);
251
340
  removeWorktree(mainRoot, row.path);
252
341
  entry.state = 'removed';
@@ -269,7 +358,7 @@ function applyPrune(rootDir, { now = new Date() } = {}) {
269
358
 
270
359
  function pruneHint(rootDir) {
271
360
  try {
272
- const { plan } = planPrune(rootDir, { checkMerged: false });
361
+ const { plan } = planPrune(rootDir, { checkMerged: false, checkPrs: false });
273
362
  const ready = plan.filter((row) => row.actions.length).length;
274
363
  return ready ? `${ready} AEL worktree(s) can be cleaned up: ai-engineering-loop worktree prune` : null;
275
364
  } catch {
@@ -283,6 +372,7 @@ module.exports = {
283
372
  applyPrune,
284
373
  cleanupAfterDeliver,
285
374
  createWorktree,
375
+ dirtyKind,
286
376
  loadRegistry,
287
377
  mainCheckout,
288
378
  planPrune,