ai-engineering-loop 1.11.0 → 1.12.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 (114) hide show
  1. package/.agents/skills/animate/RECIPES.md +324 -0
  2. package/.agents/skills/animate/SKILL.md +207 -0
  3. package/.agents/skills/animate-expo/RECIPES.md +385 -0
  4. package/.agents/skills/animate-expo/SKILL.md +263 -0
  5. package/.agents/skills/animation-vocabulary/SKILL.md +181 -0
  6. package/.agents/skills/apple-design/SKILL.md +290 -0
  7. package/.agents/skills/ask-sonner/API.md +64 -0
  8. package/.agents/skills/ask-sonner/SKILL.md +88 -0
  9. package/.agents/skills/backend-development/SKILL.md +272 -0
  10. package/.agents/skills/backend-development/references/api-design-guidelines.md +95 -0
  11. package/.agents/skills/backend-development/references/query-and-database-best-practices.md +53 -0
  12. package/.agents/skills/backend-development/references/security-checklist.md +60 -0
  13. package/.agents/skills/emil-design-eng/SKILL.md +674 -0
  14. package/.agents/skills/find-animation-opportunities/SKILL.md +140 -0
  15. package/.agents/skills/improve-animations/AUDIT.md +115 -0
  16. package/.agents/skills/improve-animations/PLAN-TEMPLATE.md +73 -0
  17. package/.agents/skills/improve-animations/SKILL.md +109 -0
  18. package/.agents/skills/mobile-native/SKILL.md +311 -0
  19. package/.agents/skills/pick-ui-library/SKILL.md +85 -0
  20. package/.agents/skills/prototype/PICKER.md +197 -0
  21. package/.agents/skills/prototype/SKILL.md +98 -0
  22. package/.agents/skills/review-animations/SKILL.md +120 -0
  23. package/.agents/skills/review-animations/STANDARDS.md +187 -0
  24. package/.agents/skills/write-swift/SKILL.md +396 -0
  25. package/.agents/workflows/ai-engineering-loop.md +4 -4
  26. package/.claude/skills/ai-engineering-loop/SKILL.md +4 -4
  27. package/.claude/skills/animate/RECIPES.md +324 -0
  28. package/.claude/skills/animate/SKILL.md +207 -0
  29. package/.claude/skills/animate-expo/RECIPES.md +385 -0
  30. package/.claude/skills/animate-expo/SKILL.md +263 -0
  31. package/.claude/skills/animation-vocabulary/SKILL.md +181 -0
  32. package/.claude/skills/apple-design/SKILL.md +290 -0
  33. package/.claude/skills/ask-sonner/API.md +64 -0
  34. package/.claude/skills/ask-sonner/SKILL.md +88 -0
  35. package/.claude/skills/backend-development/SKILL.md +272 -0
  36. package/.claude/skills/backend-development/references/api-design-guidelines.md +95 -0
  37. package/.claude/skills/backend-development/references/query-and-database-best-practices.md +53 -0
  38. package/.claude/skills/backend-development/references/security-checklist.md +60 -0
  39. package/.claude/skills/emil-design-eng/SKILL.md +674 -0
  40. package/.claude/skills/find-animation-opportunities/SKILL.md +140 -0
  41. package/.claude/skills/improve-animations/AUDIT.md +115 -0
  42. package/.claude/skills/improve-animations/PLAN-TEMPLATE.md +73 -0
  43. package/.claude/skills/improve-animations/SKILL.md +109 -0
  44. package/.claude/skills/mobile-native/SKILL.md +311 -0
  45. package/.claude/skills/pick-ui-library/SKILL.md +85 -0
  46. package/.claude/skills/prototype/PICKER.md +197 -0
  47. package/.claude/skills/prototype/SKILL.md +98 -0
  48. package/.claude/skills/review-animations/SKILL.md +120 -0
  49. package/.claude/skills/review-animations/STANDARDS.md +187 -0
  50. package/.claude/skills/write-swift/SKILL.md +396 -0
  51. package/.gemini/skills/ai-engineering-loop/SKILL.md +4 -4
  52. package/.gemini/skills/animate/RECIPES.md +324 -0
  53. package/.gemini/skills/animate/SKILL.md +207 -0
  54. package/.gemini/skills/animate-expo/RECIPES.md +385 -0
  55. package/.gemini/skills/animate-expo/SKILL.md +263 -0
  56. package/.gemini/skills/animation-vocabulary/SKILL.md +181 -0
  57. package/.gemini/skills/apple-design/SKILL.md +290 -0
  58. package/.gemini/skills/ask-sonner/API.md +64 -0
  59. package/.gemini/skills/ask-sonner/SKILL.md +88 -0
  60. package/.gemini/skills/backend-development/SKILL.md +272 -0
  61. package/.gemini/skills/backend-development/references/api-design-guidelines.md +95 -0
  62. package/.gemini/skills/backend-development/references/query-and-database-best-practices.md +53 -0
  63. package/.gemini/skills/backend-development/references/security-checklist.md +60 -0
  64. package/.gemini/skills/emil-design-eng/SKILL.md +674 -0
  65. package/.gemini/skills/find-animation-opportunities/SKILL.md +140 -0
  66. package/.gemini/skills/improve-animations/AUDIT.md +115 -0
  67. package/.gemini/skills/improve-animations/PLAN-TEMPLATE.md +73 -0
  68. package/.gemini/skills/improve-animations/SKILL.md +109 -0
  69. package/.gemini/skills/mobile-native/SKILL.md +311 -0
  70. package/.gemini/skills/pick-ui-library/SKILL.md +85 -0
  71. package/.gemini/skills/prototype/PICKER.md +197 -0
  72. package/.gemini/skills/prototype/SKILL.md +98 -0
  73. package/.gemini/skills/review-animations/SKILL.md +120 -0
  74. package/.gemini/skills/review-animations/STANDARDS.md +187 -0
  75. package/.gemini/skills/write-swift/SKILL.md +396 -0
  76. package/.grok/skills/ai-engineering-loop/SKILL.md +4 -4
  77. package/.grok/skills/animate/RECIPES.md +324 -0
  78. package/.grok/skills/animate/SKILL.md +207 -0
  79. package/.grok/skills/animate-expo/RECIPES.md +385 -0
  80. package/.grok/skills/animate-expo/SKILL.md +263 -0
  81. package/.grok/skills/animation-vocabulary/SKILL.md +181 -0
  82. package/.grok/skills/apple-design/SKILL.md +290 -0
  83. package/.grok/skills/ask-sonner/API.md +64 -0
  84. package/.grok/skills/ask-sonner/SKILL.md +88 -0
  85. package/.grok/skills/backend-development/SKILL.md +272 -0
  86. package/.grok/skills/backend-development/references/api-design-guidelines.md +95 -0
  87. package/.grok/skills/backend-development/references/query-and-database-best-practices.md +53 -0
  88. package/.grok/skills/backend-development/references/security-checklist.md +60 -0
  89. package/.grok/skills/emil-design-eng/SKILL.md +674 -0
  90. package/.grok/skills/find-animation-opportunities/SKILL.md +140 -0
  91. package/.grok/skills/improve-animations/AUDIT.md +115 -0
  92. package/.grok/skills/improve-animations/PLAN-TEMPLATE.md +73 -0
  93. package/.grok/skills/improve-animations/SKILL.md +109 -0
  94. package/.grok/skills/mobile-native/SKILL.md +311 -0
  95. package/.grok/skills/pick-ui-library/SKILL.md +85 -0
  96. package/.grok/skills/prototype/PICKER.md +197 -0
  97. package/.grok/skills/prototype/SKILL.md +98 -0
  98. package/.grok/skills/review-animations/SKILL.md +120 -0
  99. package/.grok/skills/review-animations/STANDARDS.md +187 -0
  100. package/.grok/skills/write-swift/SKILL.md +396 -0
  101. package/README.md +11 -1
  102. package/README.npm.md +5 -0
  103. package/THIRD_PARTY_NOTICES.md +10 -0
  104. package/agents/third-party/emilkowalski-skills/LICENSE +21 -0
  105. package/bin/ai-engineering-loop.js +129 -3
  106. package/core/runtime-safety.md +18 -1
  107. package/lib/doctor.js +16 -0
  108. package/lib/run-compaction.js +170 -0
  109. package/lib/smart-context.js +267 -8
  110. package/lib/studio-server.js +19 -2
  111. package/lib/sync-hosts.js +69 -0
  112. package/lib/update-manager.js +147 -0
  113. package/package.json +2 -1
  114. package/studio/app.js +5 -2
@@ -57,10 +57,16 @@ const {
57
57
  contextPackSummary
58
58
  } = require('../lib/safe-context.js');
59
59
  const {
60
+ assessSmallTaskFastPath,
60
61
  buildContextIndex,
61
62
  createDiffHunkPack,
63
+ queryContextIndex,
64
+ relatedContextIndex,
62
65
  smartContextSummary
63
66
  } = require('../lib/smart-context.js');
67
+ const {
68
+ compactRun
69
+ } = require('../lib/run-compaction.js');
64
70
  const {
65
71
  defaultCasesDir,
66
72
  loadEvaluationCases,
@@ -77,6 +83,10 @@ const {
77
83
  const {
78
84
  runDoctor
79
85
  } = require('../lib/doctor.js');
86
+ const {
87
+ checkForUpdate,
88
+ executeUpdatePlan
89
+ } = require('../lib/update-manager.js');
80
90
  const {
81
91
  assertBudgetAvailable,
82
92
  budgetStatus,
@@ -1371,11 +1381,14 @@ function handleContext() {
1371
1381
  const runId = argValue('--run');
1372
1382
  const profile = argValue('--profile');
1373
1383
  const base = argValue('--base') || 'HEAD';
1384
+ const query = argValue('--query');
1385
+ const limit = Number(argValue('--limit') || 10);
1374
1386
  const json = process.argv.includes('--json');
1375
- const files = commandFiles(4, ['--run', '--profile', '--base']);
1387
+ const includeIgnored = process.argv.includes('--include-ignored');
1388
+ const files = commandFiles(4, ['--run', '--profile', '--base', '--query', '--limit']);
1376
1389
  try {
1377
1390
  if (stage === 'index') {
1378
- const result = buildContextIndex(CWD, { files });
1391
+ const result = buildContextIndex(CWD, { files, includeIgnored });
1379
1392
  const summary = smartContextSummary(result);
1380
1393
  if (json) {
1381
1394
  console.log(JSON.stringify({ ok: true, ...summary }));
@@ -1386,8 +1399,54 @@ function handleContext() {
1386
1399
  }
1387
1400
  return;
1388
1401
  }
1402
+ if (stage === 'query') {
1403
+ const result = queryContextIndex(CWD, { query: query || files.join(' '), limit });
1404
+ if (json) {
1405
+ console.log(JSON.stringify({ ok: true, ...result }));
1406
+ } else {
1407
+ log.success('✓ context index query complete');
1408
+ console.log(`- Matches: ${result.matches.length}`);
1409
+ for (const match of result.matches) console.log(` - ${match.path}${match.symbols.length ? ` (${match.symbols.join(', ')})` : ''}`);
1410
+ }
1411
+ return;
1412
+ }
1413
+ if (stage === 'related') {
1414
+ const result = relatedContextIndex(CWD, { file: files[0], limit });
1415
+ if (json) {
1416
+ console.log(JSON.stringify({ ok: true, ...result }));
1417
+ } else {
1418
+ log.success('✓ related context query complete');
1419
+ console.log(`- File: ${result.file}`);
1420
+ for (const match of result.matches) console.log(` - ${match.path}`);
1421
+ }
1422
+ return;
1423
+ }
1424
+ if (stage === 'fast-path') {
1425
+ const result = assessSmallTaskFastPath(CWD, { base, includeIgnored });
1426
+ if (json) {
1427
+ console.log(JSON.stringify({ ok: true, ...result }));
1428
+ } else {
1429
+ log.success(result.eligible ? '✓ small-task fast path eligible' : 'Small-task fast path not eligible');
1430
+ console.log(`- Profile: ${result.recommendedProfile}`);
1431
+ console.log(`- Files: ${result.changedPaths.length}, changed lines: ${result.changedLines}`);
1432
+ if (result.reasons.length) console.log(`- Reasons: ${result.reasons.join(', ')}`);
1433
+ }
1434
+ return;
1435
+ }
1436
+ if (stage === 'compact') {
1437
+ const result = compactRun(CWD, { runId });
1438
+ if (json) {
1439
+ console.log(JSON.stringify({ ok: true, runId: result.summary.runId, paths: result.paths, openFindings: result.summary.openFindings.length }));
1440
+ } else {
1441
+ log.success('✓ run context compacted');
1442
+ console.log(`- Summary: ${result.paths.markdown}`);
1443
+ console.log(`- Machine summary: ${result.paths.summary}`);
1444
+ console.log(`- Open findings: ${result.paths.openFindings}`);
1445
+ }
1446
+ return;
1447
+ }
1389
1448
  if (stage === 'diff-hunks' || stage === 'diff-pack') {
1390
- const result = createDiffHunkPack(CWD, { runId, base, profile });
1449
+ const result = createDiffHunkPack(CWD, { runId, base, profile, includeIgnored });
1391
1450
  const summary = smartContextSummary(result);
1392
1451
  if (json) {
1393
1452
  console.log(JSON.stringify({ ok: true, ...summary }));
@@ -1397,6 +1456,7 @@ function handleContext() {
1397
1456
  console.log(`- Review profile: ${summary.reviewProfile}`);
1398
1457
  console.log(`- Files: ${summary.files}, estimated tokens: ${summary.estimatedTokens}`);
1399
1458
  console.log(`- Unresolved findings: ${summary.unresolvedFindings}, truncated: ${summary.truncated}`);
1459
+ if (summary.ignoredPaths) console.log(`- Ignored by context policy: ${summary.ignoredPaths}`);
1400
1460
  }
1401
1461
  return;
1402
1462
  }
@@ -1512,6 +1572,59 @@ function handleDoctor() {
1512
1572
  if (!result.ok) process.exit(1);
1513
1573
  }
1514
1574
 
1575
+ function printUpdatePlan(plan) {
1576
+ console.log(`Current: ${plan.currentVersion}`);
1577
+ console.log(`Latest: ${plan.latestVersion}`);
1578
+ console.log(`Install: ${plan.installScope}`);
1579
+ if (plan.updateAvailable) {
1580
+ console.log('\nUpdate available. Recommended commands:');
1581
+ } else {
1582
+ console.log('\nai-engineering-loop is up to date. Sync commands remain safe to run:');
1583
+ }
1584
+ for (const item of plan.commands) console.log(item.display);
1585
+ }
1586
+
1587
+ function handleUpdate() {
1588
+ const action = process.argv[3] || 'check';
1589
+ const json = process.argv.includes('--json');
1590
+ const yes = process.argv.includes('--yes');
1591
+ try {
1592
+ const plan = checkForUpdate(path.join(__dirname, '..'));
1593
+ if (action === 'check' || action === 'plan') {
1594
+ if (json) console.log(JSON.stringify({ ok: true, action, ...plan }));
1595
+ else printUpdatePlan(plan);
1596
+ return;
1597
+ }
1598
+ if (action === 'apply') {
1599
+ if (json && !yes) {
1600
+ throw new Error('update apply requires --yes; use update plan for a dry run');
1601
+ }
1602
+ if (!yes) {
1603
+ printUpdatePlan(plan);
1604
+ throw new Error('Refusing to update without explicit confirmation. Re-run with: ai-engineering-loop update apply --yes');
1605
+ }
1606
+ if (!plan.updateAvailable) {
1607
+ if (json) console.log(JSON.stringify({ ok: true, action, skipped: true, reason: 'UP_TO_DATE', ...plan }));
1608
+ else {
1609
+ console.log('ai-engineering-loop is already up to date.');
1610
+ printUpdatePlan(plan);
1611
+ }
1612
+ return;
1613
+ }
1614
+ if (!json) printUpdatePlan(plan);
1615
+ executeUpdatePlan(plan);
1616
+ if (json) console.log(JSON.stringify({ ok: true, action, applied: true, ...plan }));
1617
+ else log.success('✓ ai-engineering-loop updated and post-update sync completed');
1618
+ return;
1619
+ }
1620
+ throw new Error(`Unknown update action: ${action}`);
1621
+ } catch (err) {
1622
+ if (json) console.log(JSON.stringify({ ok: false, code: err.code || 'UPDATE_FAILED', error: err.message }));
1623
+ else log.error(err.message);
1624
+ process.exit(1);
1625
+ }
1626
+ }
1627
+
1515
1628
  function handleRecipe() {
1516
1629
  const action = process.argv[3] || 'list';
1517
1630
  const id = process.argv[4];
@@ -2007,10 +2120,17 @@ Commands:
2007
2120
  context <stage> <files...>
2008
2121
  Build a bounded, redacted context pack for maker, devil-advocate, or judge
2009
2122
  index [files...] build a private source summary index without file bodies
2123
+ query <term> search index paths and exported symbols without source bodies
2124
+ related <file> list nearby indexed files without reading source bodies
2010
2125
  diff-hunks build a hunk-only review pack with unresolved findings
2126
+ fast-path assess whether a small task can stay on lean review
2127
+ compact write run-summary.md/json and open-findings.json
2011
2128
  --run <id> target a non-current run
2012
2129
  --profile lean|standard|thorough override runtime policy for one pack
2013
2130
  --base <git-ref> base ref for diff-hunks; default HEAD
2131
+ --query <term> query term for context query
2132
+ --limit <n> bound query/related result count
2133
+ --include-ignored include CSS, generated, lockfile, and .aelcontextignore paths
2014
2134
  --json print only pack metadata; never print packed content
2015
2135
  eval Validate the 20-case production evaluation catalog
2016
2136
  --results <dir> score host-generated JSON results
@@ -2021,6 +2141,9 @@ Commands:
2021
2141
  --json print machine-readable reasons
2022
2142
  doctor Check runtime, schemas, host assets, package contents, and eval catalog
2023
2143
  --json print machine-readable diagnostics
2144
+ update Check or apply the package update workflow
2145
+ check|plan [--json]
2146
+ apply --yes
2024
2147
  recipe Inspect and compile declarative workflow recipes (does not execute nodes)
2025
2148
  list [--json]
2026
2149
  catalog [--json]
@@ -2114,6 +2237,9 @@ switch (command) {
2114
2237
  case 'doctor':
2115
2238
  handleDoctor();
2116
2239
  break;
2240
+ case 'update':
2241
+ handleUpdate();
2242
+ break;
2117
2243
  case 'recipe':
2118
2244
  handleRecipe();
2119
2245
  break;
@@ -64,11 +64,28 @@ Prefer smart context before opening whole files:
64
64
 
65
65
  ```bash
66
66
  npx ai-engineering-loop context index
67
+ npx ai-engineering-loop context query createStudioRun
68
+ npx ai-engineering-loop context related lib/studio-server.js
69
+ npx ai-engineering-loop context fast-path --json
67
70
  npx ai-engineering-loop context diff-hunks --run <run-id>
71
+ npx ai-engineering-loop context diff-hunks --run <run-id> --include-ignored
68
72
  npx ai-engineering-loop verification summarize --run <run-id>
73
+ npx ai-engineering-loop context compact --run <run-id>
69
74
  ```
70
75
 
71
- The index stores file summaries and hashes, never file bodies, and reuses per-hash summaries when files are unchanged. The diff-hunk pack stores bounded changed hunks, file summaries, token estimates, and unresolved blocking findings from the previous ledger. The verification summary stores command outcomes, counts, and short failure excerpts without raw stdout. Iteration 2+ reviewers should start from these compact artifacts and request full source or logs only when the hunk or summary cannot prove or disprove a finding.
76
+ The index stores file summaries and hashes, never file bodies, and reuses per-hash summaries when files are unchanged. `query` and `related` return metadata only so agents can choose the right files before reading source. `fast-path` keeps low-risk small diffs on lean review and names the reason when a task must use the standard path. The diff-hunk pack stores bounded changed hunks, file summaries, token estimates, unresolved blocking findings from the previous ledger, and a count of paths skipped by context policy. Smart context skips CSS, generated bundles, lockfiles, build output, and `.aelcontextignore` matches by default; pass `--include-ignored` only when those files are the task. The verification summary stores command outcomes, counts, and short failure excerpts without raw stdout. `context compact` writes `run-summary.md`, `run-summary.json`, and `open-findings.json` so iteration 2+ reviewers and Judge start from compact artifacts and request full source or logs only when the hunk or summary cannot prove or disprove a finding.
77
+
78
+ ## Package update workflow
79
+
80
+ Agents may check for package updates, but must not update the user's global or project installation without explicit instruction. Use:
81
+
82
+ ```bash
83
+ ai-engineering-loop update check
84
+ ai-engineering-loop update plan
85
+ ai-engineering-loop update apply --yes
86
+ ```
87
+
88
+ `update plan` prints the exact install, `sync-hosts`, `refresh`, and `doctor` commands for the detected install scope. `update apply --yes` runs those commands explicitly; the separate `--yes` flag is the confirmation boundary.
72
89
 
73
90
  ## Unattended Maker isolation
74
91
 
package/lib/doctor.js CHANGED
@@ -8,13 +8,29 @@ const { listRecipes, loadRecipe, validateRecipe } = require('./recipe.js');
8
8
 
9
9
  const REQUIRED_HOST_ASSETS = [
10
10
  '.claude/skills/ai-engineering-loop/SKILL.md',
11
+ '.claude/skills/backend-development/SKILL.md',
12
+ '.claude/skills/emil-design-eng/SKILL.md',
13
+ '.claude/skills/animate/SKILL.md',
14
+ '.claude/skills/review-animations/SKILL.md',
11
15
  '.claude/agents/devil-advocate.md',
12
16
  '.claude/agents/judge.md',
13
17
  '.grok/skills/ai-engineering-loop/SKILL.md',
18
+ '.grok/skills/backend-development/SKILL.md',
19
+ '.grok/skills/emil-design-eng/SKILL.md',
20
+ '.grok/skills/animate/SKILL.md',
21
+ '.grok/skills/review-animations/SKILL.md',
14
22
  '.grok/agents/devil-advocate.md',
15
23
  '.grok/agents/judge.md',
16
24
  '.gemini/skills/ai-engineering-loop/SKILL.md',
25
+ '.gemini/skills/backend-development/SKILL.md',
26
+ '.gemini/skills/emil-design-eng/SKILL.md',
27
+ '.gemini/skills/animate/SKILL.md',
28
+ '.gemini/skills/review-animations/SKILL.md',
17
29
  '.agents/workflows/ai-engineering-loop.md',
30
+ '.agents/skills/backend-development/SKILL.md',
31
+ '.agents/skills/emil-design-eng/SKILL.md',
32
+ '.agents/skills/animate/SKILL.md',
33
+ '.agents/skills/review-animations/SKILL.md',
18
34
  '.agents/devil-advocate.md',
19
35
  '.agents/judge.md'
20
36
  ];
@@ -0,0 +1,170 @@
1
+ 'use strict';
2
+
3
+ const fs = require('fs');
4
+ const path = require('path');
5
+ const { atomicWriteJson, atomicWritePrivateFile, getCurrentRun, loadRun, runsDir } = require('./run-state.js');
6
+ const { writeVerificationSummary } = require('./verification-summary.js');
7
+ const { loadPolicy } = require('./runtime-policy.js');
8
+
9
+ function compactionError(message, code = 'RUN_COMPACTION_ERROR') {
10
+ const err = new Error(message);
11
+ err.code = code;
12
+ return err;
13
+ }
14
+
15
+ function resolveRun(rootDir, runId) {
16
+ if (runId) return loadRun(rootDir, runId);
17
+ const current = getCurrentRun(rootDir);
18
+ if (!current) throw compactionError('No current run. Pass --run <id>.', 'NO_CURRENT_RUN');
19
+ return current;
20
+ }
21
+
22
+ function readOptionalJson(filePath) {
23
+ if (!fs.existsSync(filePath)) return null;
24
+ try {
25
+ return JSON.parse(fs.readFileSync(filePath, 'utf8'));
26
+ } catch {
27
+ return null;
28
+ }
29
+ }
30
+
31
+ function firstPresent(...values) {
32
+ return values.find((value) => value != null && value !== '') ?? null;
33
+ }
34
+
35
+ function compactGoal(goal) {
36
+ if (!goal) return null;
37
+ const criteria = goal.acceptanceCriteria || goal.criteria || [];
38
+ return {
39
+ objective: firstPresent(goal.objective, goal.goal, goal.summary),
40
+ revision: goal.revision || goal.draftRevision || null,
41
+ hash: goal.hash || goal.sha256 || null,
42
+ acceptanceCriteria: criteria.map((criterion) => ({
43
+ id: criterion.id,
44
+ statement: criterion.statement || criterion.description || '',
45
+ failureCases: (criterion.failureCases || []).slice(0, 3)
46
+ }))
47
+ };
48
+ }
49
+
50
+ function compactFindings(findingsDocument) {
51
+ const findings = findingsDocument?.findings || [];
52
+ return findings
53
+ .filter((finding) => finding.validity === 'VALID')
54
+ .filter((finding) => !['ACCEPTABLE', 'DISMISSED', 'FIXED', 'RESOLVED'].includes(String(finding.disposition || '').toUpperCase()))
55
+ .map((finding) => ({
56
+ id: finding.id,
57
+ axis: finding.axis,
58
+ severity: finding.severity,
59
+ disposition: finding.disposition,
60
+ location: finding.location,
61
+ title: finding.title || finding.topic || null
62
+ }));
63
+ }
64
+
65
+ function markdownSummary(document) {
66
+ const goalLines = document.goal
67
+ ? [
68
+ `- Objective: ${document.goal.objective || 'Not recorded'}`,
69
+ `- Acceptance criteria: ${document.goal.acceptanceCriteria.length}`,
70
+ `- Goal revision: ${document.goal.revision || 'n/a'}`,
71
+ `- Goal hash: ${document.goal.hash || 'n/a'}`
72
+ ]
73
+ : ['- Goal: not recorded'];
74
+ const verification = document.verification
75
+ ? [
76
+ `- Passed: ${document.verification.passed}`,
77
+ `- Exit code: ${document.verification.exitCode}`,
78
+ `- Commands: ${document.verification.commandCount}`,
79
+ `- Tests: ${JSON.stringify(document.verification.testCounts)}`
80
+ ]
81
+ : ['- Verification: not summarized'];
82
+ const findings = document.openFindings.length
83
+ ? document.openFindings.map((finding) => `- ${finding.id} ${finding.severity || ''} ${finding.axis || ''}: ${finding.title || finding.location || 'open'}`)
84
+ : ['- No open VALID non-accepted findings recorded'];
85
+ return [
86
+ `# Run Summary: ${document.runId}`,
87
+ '',
88
+ `Generated: ${document.generatedAt}`,
89
+ '',
90
+ '## State',
91
+ '',
92
+ `- State: ${document.state}`,
93
+ `- Mode: ${document.mode || 'n/a'}`,
94
+ `- Iteration: ${document.iteration}`,
95
+ `- Review profile: ${document.reviewProfile || 'n/a'}`,
96
+ '',
97
+ '## Goal',
98
+ '',
99
+ ...goalLines,
100
+ '',
101
+ '## Verification',
102
+ '',
103
+ ...verification,
104
+ '',
105
+ '## Open findings',
106
+ '',
107
+ ...findings,
108
+ '',
109
+ '## Reviewer read order',
110
+ '',
111
+ '1. This summary',
112
+ '2. verification-summary.json',
113
+ '3. open-findings.json',
114
+ '4. context/diff-hunks.json',
115
+ '5. Full artifacts only when the summaries contradict each other'
116
+ ].join('\n');
117
+ }
118
+
119
+ function compactRun(rootDir, { runId } = {}) {
120
+ const run = resolveRun(rootDir, runId);
121
+ const runDir = path.join(runsDir(rootDir), run.runId);
122
+ const goal = readOptionalJson(path.join(runDir, 'goal-contract.json'));
123
+ let verification = readOptionalJson(path.join(runDir, 'verification-summary.json'));
124
+ if (!verification && fs.existsSync(path.join(runDir, 'verification.json'))) {
125
+ verification = writeVerificationSummary(rootDir, { runId: run.runId }).summary;
126
+ }
127
+ const findingsDocument = readOptionalJson(path.join(runDir, 'findings.json'));
128
+ const openFindings = compactFindings(findingsDocument);
129
+ const summary = {
130
+ schemaVersion: 1,
131
+ runId: run.runId,
132
+ generatedAt: new Date().toISOString(),
133
+ state: run.state,
134
+ mode: run.mode || null,
135
+ iteration: run.iteration || 1,
136
+ reviewProfile: loadPolicy(rootDir).reviewProfile,
137
+ goal: compactGoal(goal),
138
+ verification: verification ? {
139
+ passed: verification.passed,
140
+ exitCode: verification.exitCode,
141
+ commandCount: verification.commandCount,
142
+ testCounts: verification.testCounts,
143
+ diffHash: verification.diffHash || null
144
+ } : null,
145
+ openFindings
146
+ };
147
+ const summaryPath = path.join(runDir, 'run-summary.json');
148
+ const markdownPath = path.join(runDir, 'run-summary.md');
149
+ const findingsPath = path.join(runDir, 'open-findings.json');
150
+ atomicWriteJson(summaryPath, summary);
151
+ atomicWritePrivateFile(markdownPath, `${markdownSummary(summary)}\n`);
152
+ atomicWriteJson(findingsPath, {
153
+ schemaVersion: 1,
154
+ runId: run.runId,
155
+ generatedAt: summary.generatedAt,
156
+ findings: openFindings
157
+ });
158
+ return {
159
+ summary,
160
+ paths: {
161
+ summary: path.relative(rootDir, summaryPath).split(path.sep).join('/'),
162
+ markdown: path.relative(rootDir, markdownPath).split(path.sep).join('/'),
163
+ openFindings: path.relative(rootDir, findingsPath).split(path.sep).join('/')
164
+ }
165
+ };
166
+ }
167
+
168
+ module.exports = {
169
+ compactRun
170
+ };