ai-engineering-loop 2.14.1 → 2.15.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.agents/skills/ael/SKILL.md +4 -4
- package/.agents/skills/ael/references/loop-commands.md +6 -3
- package/.agents/skills/ael/references/loop-deliver.md +1 -0
- package/.agents/skills/ael/references/loop-goal.md +7 -4
- package/.agents/skills/ael/references/loop-hosts.md +1 -0
- package/.agents/skills/ael/references/loop-modes.md +1 -0
- package/CHANGELOG.md +23 -1
- package/README.md +1 -0
- package/adapters/project-onboarding/SKILL.md +2 -0
- package/agents/instruction-only/AGENTS.md +1 -1
- package/bin/ai-engineering-loop.js +446 -39
- package/core/coordinator.md +33 -0
- package/core/garden.md +18 -0
- package/core/goal-contract.md +23 -1
- package/core/overnight-contract.md +62 -0
- package/core/prototype-spike.md +28 -0
- package/core/root-cause-analysis.md +27 -0
- package/core/run-isolation.md +19 -0
- package/core/verification-loop.md +2 -0
- package/core/verification-one-pager.md +34 -0
- package/core/weekly-process-sampling.md +32 -0
- package/lib/agent-artifacts.js +6 -0
- package/lib/cli-args.js +5 -3
- package/lib/design-ref.js +15 -0
- package/lib/driver-scaffold.js +1 -1
- package/lib/feature-map.js +427 -1
- package/lib/features.js +20 -1
- package/lib/garden.js +171 -0
- package/lib/gates.js +18 -0
- package/lib/git-readiness.js +6 -1
- package/lib/goal-runtime.js +31 -1
- package/lib/harness-audit.js +1 -1
- package/lib/issue-repro.js +460 -0
- package/lib/learn.js +34 -0
- package/lib/overnight.js +179 -0
- package/lib/pr-babysit.js +277 -0
- package/lib/run-isolation.js +25 -4
- package/lib/spike.js +104 -0
- package/lib/ste.js +15 -0
- package/package.json +1 -1
- package/schemas/goal-contract.schema.json +13 -0
package/lib/feature-map.js
CHANGED
|
@@ -11,6 +11,8 @@
|
|
|
11
11
|
//
|
|
12
12
|
// `Paths` are globs (comma separated) used to pick the entries a diff
|
|
13
13
|
// touches; `Driver` is an optional reusable command that runs the flow.
|
|
14
|
+
// `ael feature-map scaffold` drafts the table from routes, OpenAPI, pages,
|
|
15
|
+
// or README headings and never overwrites an edited map.
|
|
14
16
|
|
|
15
17
|
const fs = require('fs');
|
|
16
18
|
const path = require('path');
|
|
@@ -54,4 +56,428 @@ function renderForPack(entries) {
|
|
|
54
56
|
...entries.map((entry) => `- ${entry.id}: ${entry.where}. Reach: ${entry.how}.${entry.driver ? ` Driver: \`${entry.driver}\`` : ''}`)].join('\n');
|
|
55
57
|
}
|
|
56
58
|
|
|
57
|
-
|
|
59
|
+
// Same route declarations the impact map reads (lib/impact-map.js ROUTE_PATTERNS).
|
|
60
|
+
const ROUTE_PATTERNS = [
|
|
61
|
+
/\b(?:app|router|server|route|api)\.(get|post|put|patch|delete)\(\s*['"`]([^'"`]+)['"`]/gi,
|
|
62
|
+
/@(Get|Post|Put|Patch|Delete)\(\s*['"`]([^'"`]*)['"`]/g
|
|
63
|
+
];
|
|
64
|
+
const NEXT_HANDLER = /\bexport\s+(?:async\s+)?(?:function|const)\s+(GET|POST|PUT|PATCH|DELETE)\b/g;
|
|
65
|
+
const SKIP_DIRS = new Set(['node_modules', '.git', '.hg', '.svn', 'vendor', 'dist', 'build', 'coverage', '.next', '.ai-engineering-loop', 'target', '__pycache__', '.venv', 'venv', 'out', '.cache', '.turbo']);
|
|
66
|
+
const CODE_EXT = new Set(['.js', '.jsx', '.mjs', '.cjs', '.ts', '.tsx', '.py', '.go', '.rb', '.java', '.kt', '.php']);
|
|
67
|
+
const OPENAPI_NAME = /^(openapi|swagger)\.(json|ya?ml)$/i;
|
|
68
|
+
const README_SKIP = new Set(['table of contents', 'contents', 'toc', 'installation', 'install', 'getting started', 'quick start', 'contributing', 'contribute', 'license', 'licence', 'changelog', 'prerequisites', 'requirements', 'development', 'developing', 'testing', 'tests', 'build', 'setup', 'configuration', 'config', 'acknowledgements', 'acknowledgments', 'credits', 'authors', 'support', 'faq', 'roadmap', 'status', 'overview', 'introduction', 'about', 'documentation', 'docs', 'deploy', 'deployment', 'scripts', 'commands', 'api']);
|
|
69
|
+
const CONTAINER_HEADINGS = new Set(['features', 'feature', 'usage', 'functionality']);
|
|
70
|
+
const SCRIPT_SKIP = new Set(['test', 'lint', 'build', 'start', 'prepare', 'prepublish', 'prepublishonly', 'postinstall', 'preinstall', 'install']);
|
|
71
|
+
const SRC_SKIP = new Set(['test', 'tests', '__tests__', 'lib', 'utils', 'util', 'common', 'shared', 'types', 'assets', 'styles']);
|
|
72
|
+
const MAX_FILES = 2000;
|
|
73
|
+
const MAX_BYTES = 256 * 1024;
|
|
74
|
+
const MAX_ROWS = 40;
|
|
75
|
+
const HEADER = '| Feature | Where (UI or endpoint) | Paths | How to reach | Driver |\n|---|---|---|---|---|';
|
|
76
|
+
|
|
77
|
+
const cell = (value) => String(value || '').replace(/\|/g, '/').replace(/\s+/g, ' ').trim();
|
|
78
|
+
|
|
79
|
+
function slug(text) {
|
|
80
|
+
const id = String(text || '').toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 48);
|
|
81
|
+
return id || 'feature';
|
|
82
|
+
}
|
|
83
|
+
|
|
84
|
+
function normRoute(route) {
|
|
85
|
+
let value = String(route || '/').trim().replace(/\{([^}]+)\}/g, ':$1');
|
|
86
|
+
if (!value.startsWith('/')) value = `/${value}`;
|
|
87
|
+
value = value.replace(/\/{2,}/g, '/');
|
|
88
|
+
if (value.length > 1) value = value.replace(/\/+$/, '');
|
|
89
|
+
return value || '/';
|
|
90
|
+
}
|
|
91
|
+
|
|
92
|
+
function dynamicSeg(segment) {
|
|
93
|
+
return segment.replace(/^\[\[\.\.\.(.+?)\]\]$/, ':$1').replace(/^\[\.\.\.(.+?)\]$/, ':$1').replace(/^\[(.+?)\]$/, ':$1');
|
|
94
|
+
}
|
|
95
|
+
|
|
96
|
+
function urlFromSegments(body) {
|
|
97
|
+
const parts = String(body || '').split('/').filter((segment) => segment && !/^\(.+\)$/.test(segment)).map(dynamicSeg);
|
|
98
|
+
const url = `/${parts.join('/')}`.replace(/\/+/g, '/');
|
|
99
|
+
return url === '/' ? '/' : url.replace(/\/$/, '') || '/';
|
|
100
|
+
}
|
|
101
|
+
|
|
102
|
+
function isTestPath(rel) {
|
|
103
|
+
return /(^|\/)(tests?|__tests__|spec|specs)\//.test(rel) || /\.(test|spec)\.[a-z0-9]+$/i.test(rel);
|
|
104
|
+
}
|
|
105
|
+
|
|
106
|
+
function walkFiles(rootDir) {
|
|
107
|
+
const files = [];
|
|
108
|
+
const stack = [rootDir];
|
|
109
|
+
while (stack.length && files.length < MAX_FILES) {
|
|
110
|
+
const dir = stack.pop();
|
|
111
|
+
let entries = [];
|
|
112
|
+
try {
|
|
113
|
+
entries = fs.readdirSync(dir, { withFileTypes: true });
|
|
114
|
+
} catch {
|
|
115
|
+
continue;
|
|
116
|
+
}
|
|
117
|
+
for (const entry of entries) {
|
|
118
|
+
if (files.length >= MAX_FILES) break;
|
|
119
|
+
if (entry.isSymbolicLink()) continue;
|
|
120
|
+
const abs = path.join(dir, entry.name);
|
|
121
|
+
if (entry.isDirectory()) {
|
|
122
|
+
if (!SKIP_DIRS.has(entry.name)) stack.push(abs);
|
|
123
|
+
} else if (entry.isFile()) files.push(abs);
|
|
124
|
+
}
|
|
125
|
+
}
|
|
126
|
+
return files;
|
|
127
|
+
}
|
|
128
|
+
|
|
129
|
+
function readBounded(abs) {
|
|
130
|
+
try {
|
|
131
|
+
const stat = fs.statSync(abs);
|
|
132
|
+
if (!stat.isFile() || stat.size === 0 || stat.size > MAX_BYTES) return '';
|
|
133
|
+
return fs.readFileSync(abs, 'utf8');
|
|
134
|
+
} catch {
|
|
135
|
+
return '';
|
|
136
|
+
}
|
|
137
|
+
}
|
|
138
|
+
|
|
139
|
+
function routesIn(text, rel) {
|
|
140
|
+
if (!text) return [];
|
|
141
|
+
const found = [];
|
|
142
|
+
for (const pattern of ROUTE_PATTERNS) {
|
|
143
|
+
for (const match of text.matchAll(new RegExp(pattern.source, pattern.flags))) {
|
|
144
|
+
const route = match[2] || '/';
|
|
145
|
+
if (route !== '' && route !== '*' && !String(route).startsWith('/')) continue;
|
|
146
|
+
found.push({ method: match[1].toUpperCase(), route: normRoute(route || '/'), file: rel, summary: '' });
|
|
147
|
+
}
|
|
148
|
+
}
|
|
149
|
+
if (/^(src\/)?app\/.*\/route\.(jsx?|tsx?)$/.test(rel)) {
|
|
150
|
+
const route = urlFromSegments(rel.replace(/^src\//, '').replace(/^app\//, '').replace(/\/route\.(jsx?|tsx?)$/, ''));
|
|
151
|
+
for (const match of text.matchAll(new RegExp(NEXT_HANDLER.source, NEXT_HANDLER.flags))) {
|
|
152
|
+
found.push({ method: match[1].toUpperCase(), route, file: rel, summary: '' });
|
|
153
|
+
}
|
|
154
|
+
}
|
|
155
|
+
if (!found.length && /^(src\/)?pages\/api\/.+\.(jsx?|tsx?)$/.test(rel) && !path.posix.basename(rel).startsWith('_')) {
|
|
156
|
+
const route = urlFromSegments(rel.replace(/^src\//, '').replace(/^pages\//, '').replace(/\.(jsx?|tsx?)$/, ''));
|
|
157
|
+
found.push({ method: 'GET', route, file: rel, summary: '' });
|
|
158
|
+
}
|
|
159
|
+
return found;
|
|
160
|
+
}
|
|
161
|
+
|
|
162
|
+
function pageOf(rel) {
|
|
163
|
+
if (/(^|\/)(?:pages|app)\/api\//.test(rel)) return null;
|
|
164
|
+
const file = rel.split('/').pop();
|
|
165
|
+
if (/^_(app|document|error)\./.test(file)) return null;
|
|
166
|
+
let body = null;
|
|
167
|
+
if (/^(src\/)?app\/(?:.*\/)?page\.(jsx?|tsx?)$/.test(rel)) body = rel.replace(/^src\//, '').replace(/^app\//, '').replace(/\/page\.(jsx?|tsx?)$/, '');
|
|
168
|
+
else if (/^(src\/)?pages\/.+\.(jsx?|tsx?|vue|svelte)$/.test(rel)) body = rel.replace(/^src\//, '').replace(/^pages\//, '').replace(/\.(jsx?|tsx?|vue|svelte)$/, '').replace(/\/index$/, '').replace(/^index$/, '');
|
|
169
|
+
else if (/^(src\/)?routes\/(?:.*\/)?\+page\.(svelte|js|ts)$/.test(rel)) body = rel.replace(/^src\//, '').replace(/^routes\//, '').replace(/\/\+page\.(svelte|js|ts)$/, '');
|
|
170
|
+
if (body == null) return null;
|
|
171
|
+
return { method: 'PAGE', route: urlFromSegments(body), file: rel, summary: '' };
|
|
172
|
+
}
|
|
173
|
+
|
|
174
|
+
function operationsFromOpenApi(doc, rel) {
|
|
175
|
+
const paths = doc && doc.paths;
|
|
176
|
+
if (!paths || typeof paths !== 'object') return [];
|
|
177
|
+
const found = [];
|
|
178
|
+
for (const route of Object.keys(paths).sort()) {
|
|
179
|
+
const item = paths[route];
|
|
180
|
+
if (!item || typeof item !== 'object') continue;
|
|
181
|
+
for (const method of ['get', 'post', 'put', 'patch', 'delete']) {
|
|
182
|
+
const operation = item[method];
|
|
183
|
+
if (!operation || typeof operation !== 'object') continue;
|
|
184
|
+
found.push({
|
|
185
|
+
method: method.toUpperCase(),
|
|
186
|
+
route: normRoute(route),
|
|
187
|
+
file: rel,
|
|
188
|
+
summary: cell(operation.summary || operation.operationId || '')
|
|
189
|
+
});
|
|
190
|
+
}
|
|
191
|
+
}
|
|
192
|
+
return found;
|
|
193
|
+
}
|
|
194
|
+
|
|
195
|
+
function operationsFromOpenApiYaml(text, rel) {
|
|
196
|
+
const lines = String(text || '').split('\n');
|
|
197
|
+
const start = lines.findIndex((line) => /^paths:\s*(?:#.*)?$/.test(line));
|
|
198
|
+
if (start === -1) return [];
|
|
199
|
+
const found = [];
|
|
200
|
+
let route = null;
|
|
201
|
+
let method = null;
|
|
202
|
+
let summary = '';
|
|
203
|
+
const flush = () => {
|
|
204
|
+
if (route && method) found.push({ method, route: normRoute(route), file: rel, summary: cell(summary) });
|
|
205
|
+
};
|
|
206
|
+
for (let index = start + 1; index < lines.length; index += 1) {
|
|
207
|
+
const line = lines[index];
|
|
208
|
+
if (/^\S/.test(line) && line.trim() && !line.trim().startsWith('#')) break;
|
|
209
|
+
const pathMatch = line.match(/^ {2}(\/[^:#\s]+):\s*(?:#.*)?$/);
|
|
210
|
+
if (pathMatch) {
|
|
211
|
+
flush();
|
|
212
|
+
route = pathMatch[1];
|
|
213
|
+
method = null;
|
|
214
|
+
summary = '';
|
|
215
|
+
continue;
|
|
216
|
+
}
|
|
217
|
+
const methodMatch = line.match(/^ {4}(get|post|put|patch|delete):\s*(?:#.*)?$/i);
|
|
218
|
+
if (methodMatch && route) {
|
|
219
|
+
flush();
|
|
220
|
+
method = methodMatch[1].toUpperCase();
|
|
221
|
+
summary = '';
|
|
222
|
+
continue;
|
|
223
|
+
}
|
|
224
|
+
const summaryMatch = line.match(/^ {6}(?:summary|operationId):\s*(.+?)\s*(?:#.*)?$/);
|
|
225
|
+
if (summaryMatch && method && !summary) summary = summaryMatch[1].replace(/^['"]|['"]$/g, '');
|
|
226
|
+
}
|
|
227
|
+
flush();
|
|
228
|
+
return found;
|
|
229
|
+
}
|
|
230
|
+
|
|
231
|
+
function readOpenApi(abs, rel) {
|
|
232
|
+
const text = readBounded(abs);
|
|
233
|
+
if (!text) return [];
|
|
234
|
+
if (rel.endsWith('.json')) {
|
|
235
|
+
try {
|
|
236
|
+
return operationsFromOpenApi(JSON.parse(text), rel);
|
|
237
|
+
} catch {
|
|
238
|
+
return [];
|
|
239
|
+
}
|
|
240
|
+
}
|
|
241
|
+
return operationsFromOpenApiYaml(text, rel);
|
|
242
|
+
}
|
|
243
|
+
|
|
244
|
+
function cleanTitle(text) {
|
|
245
|
+
return String(text || '').replace(/\[([^\]]+)\]\([^)]*\)/g, '$1').replace(/[`*_]/g, '').trim();
|
|
246
|
+
}
|
|
247
|
+
|
|
248
|
+
function docRow(title, rel) {
|
|
249
|
+
return { method: 'DOC', route: title, file: rel, summary: title };
|
|
250
|
+
}
|
|
251
|
+
|
|
252
|
+
function readmeRows(abs, rel) {
|
|
253
|
+
const found = [];
|
|
254
|
+
let container = false;
|
|
255
|
+
for (const line of readBounded(abs).split('\n')) {
|
|
256
|
+
const heading = line.match(/^(#{1,3})[ \t]+(.+?)\s*$/);
|
|
257
|
+
if (heading) {
|
|
258
|
+
const level = heading[1].length;
|
|
259
|
+
const title = cleanTitle(heading[2]);
|
|
260
|
+
const key = title.toLowerCase().replace(/[:.!?]+$/g, '');
|
|
261
|
+
if (level <= 2 && CONTAINER_HEADINGS.has(key)) {
|
|
262
|
+
container = true;
|
|
263
|
+
continue;
|
|
264
|
+
}
|
|
265
|
+
if (container && level === 3 && title.length >= 3 && !README_SKIP.has(key)) {
|
|
266
|
+
found.push(docRow(title, rel));
|
|
267
|
+
continue;
|
|
268
|
+
}
|
|
269
|
+
container = false;
|
|
270
|
+
if (level < 2 || title.length < 3 || README_SKIP.has(key)) continue;
|
|
271
|
+
found.push(docRow(title, rel));
|
|
272
|
+
continue;
|
|
273
|
+
}
|
|
274
|
+
if (!container) continue;
|
|
275
|
+
const bullet = line.match(/^\s*[-*+]\s+(.+?)\s*$/);
|
|
276
|
+
if (!bullet) continue;
|
|
277
|
+
const title = cleanTitle(bullet[1]).replace(/[:.]+$/, '');
|
|
278
|
+
if (title.length < 3 || title.length > 80) continue;
|
|
279
|
+
found.push(docRow(title, rel));
|
|
280
|
+
}
|
|
281
|
+
return found;
|
|
282
|
+
}
|
|
283
|
+
|
|
284
|
+
function packageRows(rootDir) {
|
|
285
|
+
let pkg;
|
|
286
|
+
try {
|
|
287
|
+
pkg = JSON.parse(fs.readFileSync(path.join(rootDir, 'package.json'), 'utf8'));
|
|
288
|
+
} catch {
|
|
289
|
+
return [];
|
|
290
|
+
}
|
|
291
|
+
const rows = [];
|
|
292
|
+
const bin = pkg.bin;
|
|
293
|
+
if (typeof bin === 'string') rows.push({ method: 'CLI', route: pkg.name || 'cli', file: bin, summary: pkg.name || 'cli' });
|
|
294
|
+
else if (bin && typeof bin === 'object') {
|
|
295
|
+
for (const [name, file] of Object.entries(bin)) rows.push({ method: 'CLI', route: name, file: String(file), summary: name });
|
|
296
|
+
}
|
|
297
|
+
for (const [name, command] of Object.entries(pkg.scripts || {})) {
|
|
298
|
+
if (SCRIPT_SKIP.has(name.toLowerCase()) || /^(pre|post)/.test(name)) continue;
|
|
299
|
+
rows.push({ method: 'SCRIPT', route: name, file: 'package.json', summary: String(command).slice(0, 80) });
|
|
300
|
+
}
|
|
301
|
+
return rows;
|
|
302
|
+
}
|
|
303
|
+
|
|
304
|
+
function srcDirRows(rootDir) {
|
|
305
|
+
let entries = [];
|
|
306
|
+
try {
|
|
307
|
+
entries = fs.readdirSync(path.join(rootDir, 'src'), { withFileTypes: true });
|
|
308
|
+
} catch {
|
|
309
|
+
return [];
|
|
310
|
+
}
|
|
311
|
+
return entries
|
|
312
|
+
.filter((entry) => entry.isDirectory() && !entry.isSymbolicLink() && !SRC_SKIP.has(entry.name))
|
|
313
|
+
.map((entry) => ({ method: 'DIR', route: entry.name, file: `src/${entry.name}/**`, summary: entry.name }));
|
|
314
|
+
}
|
|
315
|
+
|
|
316
|
+
function withSourcePaths(readme, dirs) {
|
|
317
|
+
const used = new Set();
|
|
318
|
+
const docs = readme.map((row) => {
|
|
319
|
+
const words = row.summary.toLowerCase().split(/[^a-z0-9]+/).filter(Boolean);
|
|
320
|
+
const match = dirs.find((dir) => words.includes(dir.route.toLowerCase()) || slug(row.summary) === slug(dir.route));
|
|
321
|
+
if (!match) return row;
|
|
322
|
+
used.add(match.route);
|
|
323
|
+
return { ...row, file: match.file };
|
|
324
|
+
});
|
|
325
|
+
return { docs, dirs: dirs.filter((dir) => !used.has(dir.route)) };
|
|
326
|
+
}
|
|
327
|
+
|
|
328
|
+
function mergeSignals(openapi, routes, pages) {
|
|
329
|
+
const byKey = new Map();
|
|
330
|
+
const add = (row, signal) => {
|
|
331
|
+
const key = `${row.method} ${normRoute(row.route)}`;
|
|
332
|
+
const prev = byKey.get(key);
|
|
333
|
+
if (!prev) byKey.set(key, { ...row, route: normRoute(row.route), signal });
|
|
334
|
+
else {
|
|
335
|
+
if (!prev.summary && row.summary) prev.summary = row.summary;
|
|
336
|
+
if (signal === 'routes' && prev.signal === 'openapi') prev.file = row.file;
|
|
337
|
+
}
|
|
338
|
+
};
|
|
339
|
+
for (const row of openapi) add(row, 'openapi');
|
|
340
|
+
for (const row of routes) add(row, 'routes');
|
|
341
|
+
for (const row of pages) add(row, 'pages');
|
|
342
|
+
return [...byKey.values()].sort((a, b) => a.file.localeCompare(b.file) || a.route.localeCompare(b.route) || a.method.localeCompare(b.method));
|
|
343
|
+
}
|
|
344
|
+
|
|
345
|
+
function baseId(row) {
|
|
346
|
+
if (row.method === 'DOC') return slug(row.summary);
|
|
347
|
+
if (row.method === 'CLI' || row.method === 'SCRIPT' || row.method === 'DIR') return slug(row.route);
|
|
348
|
+
const parts = normRoute(row.route).split('/').filter(Boolean).map((segment) => segment.replace(/^:/, ''));
|
|
349
|
+
return slug(parts.join('-') || 'home');
|
|
350
|
+
}
|
|
351
|
+
|
|
352
|
+
function assignIds(rows) {
|
|
353
|
+
const used = new Set();
|
|
354
|
+
return rows.map((row) => {
|
|
355
|
+
let id = baseId(row);
|
|
356
|
+
if (used.has(id)) id = `${id}-${row.method.toLowerCase()}`;
|
|
357
|
+
let next = id;
|
|
358
|
+
let n = 2;
|
|
359
|
+
while (used.has(next)) {
|
|
360
|
+
next = `${id}-${n}`;
|
|
361
|
+
n += 1;
|
|
362
|
+
}
|
|
363
|
+
used.add(next);
|
|
364
|
+
return { ...row, id: next };
|
|
365
|
+
});
|
|
366
|
+
}
|
|
367
|
+
|
|
368
|
+
function whereOf(row) {
|
|
369
|
+
if (row.method === 'PAGE') return `page ${row.route}`;
|
|
370
|
+
if (row.method === 'DOC') return row.summary;
|
|
371
|
+
if (row.method === 'CLI') return `command ${row.route}`;
|
|
372
|
+
if (row.method === 'SCRIPT') return `npm script ${row.route}`;
|
|
373
|
+
if (row.method === 'DIR') return `src/${row.route}`;
|
|
374
|
+
const endpoint = `${row.method} ${row.route}`;
|
|
375
|
+
return row.summary ? `${endpoint} — ${row.summary}` : endpoint;
|
|
376
|
+
}
|
|
377
|
+
|
|
378
|
+
function howOf(row) {
|
|
379
|
+
if (row.method === 'PAGE') return `open ${row.route}`;
|
|
380
|
+
if (row.method === 'DOC') return `read the README section "${row.summary}"`;
|
|
381
|
+
if (row.method === 'CLI') return `run ${row.route}`;
|
|
382
|
+
if (row.method === 'SCRIPT') return `npm run ${row.route}`;
|
|
383
|
+
if (row.method === 'DIR') return `open src/${row.route}`;
|
|
384
|
+
return `call ${row.method} ${row.route}`;
|
|
385
|
+
}
|
|
386
|
+
|
|
387
|
+
function renderTable(signals, rows, total) {
|
|
388
|
+
const from = signals.join(', ');
|
|
389
|
+
const note = total > rows.length ? ` Showing the first ${rows.length} of ${total}.` : '';
|
|
390
|
+
const body = rows.map((row) => `| ${cell(row.id)} | ${cell(whereOf(row))} | ${cell(row.file)} | ${cell(howOf(row))} | |`);
|
|
391
|
+
return [
|
|
392
|
+
'# Feature map',
|
|
393
|
+
'',
|
|
394
|
+
`Drafted by \`ael feature-map scaffold\` from ${from}.${note} Each row is a user-facing feature: where it lives, the file that implements it, and how a user reaches it. Edit the rows, then run \`ael driver scaffold\` to add a driver per feature. Re-running scaffold leaves this file alone and writes \`feature-map.md.ael-new\` when the draft differs.`,
|
|
395
|
+
'',
|
|
396
|
+
HEADER,
|
|
397
|
+
...body,
|
|
398
|
+
''
|
|
399
|
+
].join('\n');
|
|
400
|
+
}
|
|
401
|
+
|
|
402
|
+
const STUB = `# Feature map
|
|
403
|
+
|
|
404
|
+
\`ael feature-map scaffold\` found no routes, OpenAPI document, pages, or README feature headings.
|
|
405
|
+
Next: add a \`## Features\` list (one bullet per feature), a package.json \`bin\`, or a \`src/<feature>/\` directory, then rerun \`ael feature-map scaffold\`. Or fill one row below. \`review-pack\` and \`doctor --harness\` read this table; \`driver scaffold\` needs at least one row.
|
|
406
|
+
|
|
407
|
+
${HEADER}
|
|
408
|
+
|
|
409
|
+
Example (the leading \`>\` keeps it out of the table until you delete it and add a real row):
|
|
410
|
+
|
|
411
|
+
> | export-csv | Reports > Export | src/reports/** | open Reports, click Export | |
|
|
412
|
+
`;
|
|
413
|
+
|
|
414
|
+
function draftFeatureMap(rootDir) {
|
|
415
|
+
const openapi = [];
|
|
416
|
+
const routes = [];
|
|
417
|
+
const pages = [];
|
|
418
|
+
let readme = null;
|
|
419
|
+
for (const abs of walkFiles(rootDir).sort()) {
|
|
420
|
+
const rel = path.relative(rootDir, abs).split(path.sep).join('/');
|
|
421
|
+
if (isTestPath(rel)) continue;
|
|
422
|
+
const base = path.posix.basename(rel);
|
|
423
|
+
if (/^readme\.md$/i.test(base) && !rel.includes('/')) readme = { abs, rel };
|
|
424
|
+
if (OPENAPI_NAME.test(base)) {
|
|
425
|
+
openapi.push(...readOpenApi(abs, rel));
|
|
426
|
+
continue;
|
|
427
|
+
}
|
|
428
|
+
const page = pageOf(rel);
|
|
429
|
+
if (page) pages.push(page);
|
|
430
|
+
if (!CODE_EXT.has(path.extname(rel).toLowerCase())) continue;
|
|
431
|
+
routes.push(...routesIn(readBounded(abs), rel));
|
|
432
|
+
}
|
|
433
|
+
const signals = [];
|
|
434
|
+
if (openapi.length) signals.push('openapi');
|
|
435
|
+
if (routes.length) signals.push('routes');
|
|
436
|
+
if (pages.length) signals.push('pages');
|
|
437
|
+
let rows = mergeSignals(openapi, routes, pages);
|
|
438
|
+
if (!rows.length) {
|
|
439
|
+
const packages = packageRows(rootDir);
|
|
440
|
+
const dirs = srcDirRows(rootDir);
|
|
441
|
+
const readmeFound = readme ? readmeRows(readme.abs, readme.rel) : [];
|
|
442
|
+
const attached = withSourcePaths(readmeFound, dirs);
|
|
443
|
+
if (packages.length) signals.push('package');
|
|
444
|
+
if (attached.dirs.length) signals.push('src');
|
|
445
|
+
if (attached.docs.length) signals.push('readme');
|
|
446
|
+
rows = [...packages, ...attached.dirs, ...attached.docs];
|
|
447
|
+
}
|
|
448
|
+
if (!rows.length) return { content: STUB, signals: [], rows: [] };
|
|
449
|
+
const total = rows.length;
|
|
450
|
+
const kept = assignIds(rows.slice(0, MAX_ROWS));
|
|
451
|
+
return { content: renderTable(signals, kept, total), signals, rows: kept };
|
|
452
|
+
}
|
|
453
|
+
|
|
454
|
+
// Same safe write as driver scaffold: an edited map stays put and the new
|
|
455
|
+
// draft lands beside it as feature-map.md.ael-new.
|
|
456
|
+
function scaffoldFeatureMap(rootDir) {
|
|
457
|
+
const draft = draftFeatureMap(rootDir);
|
|
458
|
+
const content = draft.content.endsWith('\n') ? draft.content : `${draft.content}\n`;
|
|
459
|
+
const relative = FEATURE_MAP_FILE.split(path.sep).join('/');
|
|
460
|
+
const file = path.join(rootDir, FEATURE_MAP_FILE);
|
|
461
|
+
fs.mkdirSync(path.dirname(file), { recursive: true });
|
|
462
|
+
let written = relative;
|
|
463
|
+
let preserved = false;
|
|
464
|
+
if (fs.existsSync(file) && fs.readFileSync(file, 'utf8') !== content) {
|
|
465
|
+
written = `${relative}.ael-new`;
|
|
466
|
+
fs.writeFileSync(path.join(rootDir, written), content);
|
|
467
|
+
preserved = true;
|
|
468
|
+
} else if (!fs.existsSync(file)) {
|
|
469
|
+
fs.writeFileSync(file, content);
|
|
470
|
+
} else {
|
|
471
|
+
written = null;
|
|
472
|
+
}
|
|
473
|
+
return {
|
|
474
|
+
file: relative,
|
|
475
|
+
written,
|
|
476
|
+
preserved,
|
|
477
|
+
source: draft.signals.length > 1 ? 'mixed' : (draft.signals[0] || 'stub'),
|
|
478
|
+
signals: draft.signals,
|
|
479
|
+
rows: draft.rows.length
|
|
480
|
+
};
|
|
481
|
+
}
|
|
482
|
+
|
|
483
|
+
module.exports = { FEATURE_MAP_FILE, featuresForFiles, loadFeatureMap, parseFeatureMap, renderForPack, scaffoldFeatureMap };
|
package/lib/features.js
CHANGED
|
@@ -13,6 +13,25 @@ const { atomicWriteJson, loadRun } = require('./run-state.js');
|
|
|
13
13
|
|
|
14
14
|
const FEATURES_FILE = path.join('.ai-engineering-loop', 'features.json');
|
|
15
15
|
const STATUSES = Object.freeze(['not_started', 'active', 'blocked', 'passing']);
|
|
16
|
+
const FEATURES_EXAMPLE = '{"schemaVersion":1,"features":[{"id":"export-csv","title":"Export CSV","behavior":"The user can export the filtered rows.","verify":"npm test","status":"not_started","priority":1,"dependsOn":[]}]}';
|
|
17
|
+
|
|
18
|
+
function featuresFromMap(rootDir) {
|
|
19
|
+
const entries = require('./feature-map.js').loadFeatureMap(rootDir);
|
|
20
|
+
if (!entries.length) return null;
|
|
21
|
+
return {
|
|
22
|
+
schemaVersion: 1,
|
|
23
|
+
source: 'feature-map.md',
|
|
24
|
+
features: entries.map((entry, index) => ({
|
|
25
|
+
id: entry.id,
|
|
26
|
+
title: entry.where || entry.id,
|
|
27
|
+
behavior: entry.how || entry.where || entry.id,
|
|
28
|
+
verify: entry.driver || '',
|
|
29
|
+
status: 'not_started',
|
|
30
|
+
priority: index + 1,
|
|
31
|
+
dependsOn: []
|
|
32
|
+
}))
|
|
33
|
+
};
|
|
34
|
+
}
|
|
16
35
|
|
|
17
36
|
function featuresPath(rootDir) {
|
|
18
37
|
return path.join(rootDir, FEATURES_FILE);
|
|
@@ -92,4 +111,4 @@ function auditFeatures(rootDir, document = loadFeatures(rootDir)) {
|
|
|
92
111
|
return problems;
|
|
93
112
|
}
|
|
94
113
|
|
|
95
|
-
module.exports = { FEATURES_FILE, STATUSES, auditFeatures, loadFeatures, nextFeature, onDelivered, onGoalFrozen, vcr };
|
|
114
|
+
module.exports = { FEATURES_EXAMPLE, FEATURES_FILE, STATUSES, auditFeatures, featuresFromMap, loadFeatures, nextFeature, onDelivered, onGoalFrozen, vcr };
|
package/lib/garden.js
ADDED
|
@@ -0,0 +1,171 @@
|
|
|
1
|
+
'use strict';
|
|
2
|
+
|
|
3
|
+
// `refresh --garden`: report stale project knowledge. Dry-run unless --yes.
|
|
4
|
+
// Runs are never deleted. Feature-map edits move fully dead rows aside and
|
|
5
|
+
// keep a backup of the file.
|
|
6
|
+
|
|
7
|
+
const fs = require('fs');
|
|
8
|
+
const path = require('path');
|
|
9
|
+
const { execFileSync } = require('child_process');
|
|
10
|
+
const { pruneStored, DEFAULT_MAX_AGE_RUNS } = require('./learn.js');
|
|
11
|
+
const { FEATURE_MAP_FILE, parseFeatureMap } = require('./feature-map.js');
|
|
12
|
+
const { matchesGlob } = require('./impact-map.js');
|
|
13
|
+
|
|
14
|
+
const REVIEW_DAYS = 7;
|
|
15
|
+
const KEEP_DAYS = 30;
|
|
16
|
+
const TERMINAL = new Set(['REPORTED', 'DELIVERED', 'ESCALATED', 'CANCELLED']);
|
|
17
|
+
const STALE_HEADING = '## Stale (garden)';
|
|
18
|
+
const MAP_HEADER = '| Feature | Where (UI or endpoint) | Paths | How to reach | Driver |\n|---|---|---|---|---|';
|
|
19
|
+
|
|
20
|
+
function trackedFiles(rootDir) {
|
|
21
|
+
try {
|
|
22
|
+
return execFileSync('git', ['ls-files'], {
|
|
23
|
+
cwd: rootDir,
|
|
24
|
+
encoding: 'utf8',
|
|
25
|
+
stdio: ['ignore', 'pipe', 'pipe'],
|
|
26
|
+
maxBuffer: 64 * 1024 * 1024
|
|
27
|
+
}).split('\n').filter(Boolean);
|
|
28
|
+
} catch {
|
|
29
|
+
return null;
|
|
30
|
+
}
|
|
31
|
+
}
|
|
32
|
+
|
|
33
|
+
function rowId(line) {
|
|
34
|
+
const trimmed = String(line || '').trim();
|
|
35
|
+
if (!trimmed.startsWith('|') || /^\|\s*-/.test(trimmed)) return null;
|
|
36
|
+
const cells = trimmed.split('|').slice(1, -1).map((cell) => cell.trim());
|
|
37
|
+
if (cells.length < 4 || /^feature$/i.test(cells[0])) return null;
|
|
38
|
+
return cells[0];
|
|
39
|
+
}
|
|
40
|
+
|
|
41
|
+
function readMap(rootDir) {
|
|
42
|
+
try {
|
|
43
|
+
return fs.readFileSync(path.join(rootDir, FEATURE_MAP_FILE), 'utf8');
|
|
44
|
+
} catch {
|
|
45
|
+
return null;
|
|
46
|
+
}
|
|
47
|
+
}
|
|
48
|
+
|
|
49
|
+
function planFeatureMap(rootDir) {
|
|
50
|
+
const files = trackedFiles(rootDir);
|
|
51
|
+
const text = readMap(rootDir);
|
|
52
|
+
if (text == null) return { skipped: files ? null : 'not a git repository', rows: [] };
|
|
53
|
+
if (!files) return { skipped: 'not a git repository', rows: [] };
|
|
54
|
+
const head = text.split(/^## Stale \(garden\)/m)[0];
|
|
55
|
+
const rows = [];
|
|
56
|
+
for (const entry of parseFeatureMap(head)) {
|
|
57
|
+
if (!entry.paths.length) {
|
|
58
|
+
rows.push({ id: entry.id, paths: [], action: 'skip', reason: 'no paths' });
|
|
59
|
+
continue;
|
|
60
|
+
}
|
|
61
|
+
const dead = entry.paths.filter((glob) => !files.some((file) => matchesGlob(file, glob)));
|
|
62
|
+
if (dead.length === entry.paths.length) rows.push({ id: entry.id, paths: dead, action: 'move-to-stale' });
|
|
63
|
+
else if (dead.length) rows.push({ id: entry.id, paths: dead, action: 'report', reason: 'some paths still match' });
|
|
64
|
+
}
|
|
65
|
+
return { skipped: null, rows };
|
|
66
|
+
}
|
|
67
|
+
|
|
68
|
+
function planRuns(rootDir, now) {
|
|
69
|
+
const dir = path.join(rootDir, '.ai-engineering-loop', 'runs');
|
|
70
|
+
if (!fs.existsSync(dir)) return [];
|
|
71
|
+
const rows = [];
|
|
72
|
+
for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
|
|
73
|
+
if (!entry.isDirectory()) continue;
|
|
74
|
+
let state;
|
|
75
|
+
try {
|
|
76
|
+
state = JSON.parse(fs.readFileSync(path.join(dir, entry.name, 'state.json'), 'utf8'));
|
|
77
|
+
} catch {
|
|
78
|
+
continue;
|
|
79
|
+
}
|
|
80
|
+
if (!state?.runId || !state.state) continue;
|
|
81
|
+
const at = Date.parse(state.updatedAt || state.createdAt || '');
|
|
82
|
+
if (!Number.isFinite(at)) continue;
|
|
83
|
+
const ageDays = Math.floor((now.getTime() - at) / 86400000);
|
|
84
|
+
if (!TERMINAL.has(state.state) && ageDays >= REVIEW_DAYS) {
|
|
85
|
+
rows.push({
|
|
86
|
+
runId: state.runId,
|
|
87
|
+
state: state.state,
|
|
88
|
+
ageDays,
|
|
89
|
+
action: 'review',
|
|
90
|
+
note: `idle ${ageDays}d. A human can abandon it: ael run --abandon --run ${state.runId} --reason "<why>" --by <name>`
|
|
91
|
+
});
|
|
92
|
+
} else if (TERMINAL.has(state.state) && ageDays >= KEEP_DAYS) {
|
|
93
|
+
rows.push({
|
|
94
|
+
runId: state.runId,
|
|
95
|
+
state: state.state,
|
|
96
|
+
ageDays,
|
|
97
|
+
action: 'keep',
|
|
98
|
+
note: 'left on disk; garden does not delete Run evidence'
|
|
99
|
+
});
|
|
100
|
+
}
|
|
101
|
+
}
|
|
102
|
+
rows.sort((left, right) => right.ageDays - left.ageDays || left.runId.localeCompare(right.runId));
|
|
103
|
+
return rows;
|
|
104
|
+
}
|
|
105
|
+
|
|
106
|
+
function planGarden(rootDir, { maxAgeRuns = DEFAULT_MAX_AGE_RUNS, now = new Date() } = {}) {
|
|
107
|
+
const learned = pruneStored(rootDir, { dryRun: true, maxAgeRuns });
|
|
108
|
+
const features = planFeatureMap(rootDir);
|
|
109
|
+
const runs = planRuns(rootDir, now);
|
|
110
|
+
const writes = [];
|
|
111
|
+
if (learned.pruned.length) {
|
|
112
|
+
writes.push('.ai-engineering-loop/learnings.json', '.ai-engineering-loop/learnings.md');
|
|
113
|
+
}
|
|
114
|
+
if (features.rows.some((row) => row.action === 'move-to-stale')) {
|
|
115
|
+
writes.push('.ai-engineering-loop/feature-map.md', '.ai-engineering-loop/feature-map.md.ael-backup');
|
|
116
|
+
}
|
|
117
|
+
return {
|
|
118
|
+
dryRun: true,
|
|
119
|
+
applied: false,
|
|
120
|
+
learnings: learned.pruned.map((item) => ({ id: item.id, reason: item.reason, action: 'prune' })),
|
|
121
|
+
featureMap: features.rows,
|
|
122
|
+
featureMapSkipped: features.skipped,
|
|
123
|
+
runs,
|
|
124
|
+
writes
|
|
125
|
+
};
|
|
126
|
+
}
|
|
127
|
+
|
|
128
|
+
function moveDeadRows(rootDir, deadIds) {
|
|
129
|
+
if (!deadIds.size) return false;
|
|
130
|
+
const text = readMap(rootDir);
|
|
131
|
+
if (text == null) return false;
|
|
132
|
+
const parts = text.split(/^## Stale \(garden\)/m);
|
|
133
|
+
const moved = [];
|
|
134
|
+
const kept = [];
|
|
135
|
+
for (const line of parts[0].replace(/\s*$/, '').split('\n')) {
|
|
136
|
+
const id = rowId(line);
|
|
137
|
+
if (id && deadIds.has(id)) moved.push(line);
|
|
138
|
+
else kept.push(line);
|
|
139
|
+
}
|
|
140
|
+
if (!moved.length) return false;
|
|
141
|
+
const file = path.join(rootDir, FEATURE_MAP_FILE);
|
|
142
|
+
const backup = `${file}.ael-backup`;
|
|
143
|
+
if (!fs.existsSync(backup)) fs.copyFileSync(file, backup);
|
|
144
|
+
const stale = parts.length > 1
|
|
145
|
+
? `${STALE_HEADING}${parts.slice(1).join(STALE_HEADING)}`.replace(/\s*$/, '')
|
|
146
|
+
: `${STALE_HEADING}\n\nRows whose paths match no tracked file. Move a row back into the table above when the feature returns.\n\n${MAP_HEADER}`;
|
|
147
|
+
const next = `${kept.join('\n').replace(/\s*$/, '')}\n\n${stale}\n${moved.join('\n')}\n`;
|
|
148
|
+
fs.writeFileSync(file, next);
|
|
149
|
+
return true;
|
|
150
|
+
}
|
|
151
|
+
|
|
152
|
+
function applyGarden(rootDir, options = {}) {
|
|
153
|
+
const plan = planGarden(rootDir, options);
|
|
154
|
+
const written = [];
|
|
155
|
+
if (plan.learnings.length) {
|
|
156
|
+
pruneStored(rootDir, { dryRun: false, maxAgeRuns: options.maxAgeRuns || DEFAULT_MAX_AGE_RUNS });
|
|
157
|
+
written.push('.ai-engineering-loop/learnings.json', '.ai-engineering-loop/learnings.md');
|
|
158
|
+
}
|
|
159
|
+
const deadIds = new Set(plan.featureMap.filter((row) => row.action === 'move-to-stale').map((row) => row.id));
|
|
160
|
+
if (moveDeadRows(rootDir, deadIds)) {
|
|
161
|
+
written.push('.ai-engineering-loop/feature-map.md', '.ai-engineering-loop/feature-map.md.ael-backup');
|
|
162
|
+
}
|
|
163
|
+
return { ...plan, dryRun: false, applied: true, written };
|
|
164
|
+
}
|
|
165
|
+
|
|
166
|
+
module.exports = {
|
|
167
|
+
KEEP_DAYS,
|
|
168
|
+
REVIEW_DAYS,
|
|
169
|
+
applyGarden,
|
|
170
|
+
planGarden
|
|
171
|
+
};
|
package/lib/gates.js
CHANGED
|
@@ -173,6 +173,23 @@ function validateGoalContract(contract) {
|
|
|
173
173
|
return { valid: errors.length === 0, errors };
|
|
174
174
|
}
|
|
175
175
|
|
|
176
|
+
// goal draft only. The frozen-contract gate stays compatible with Goals
|
|
177
|
+
// written before this field existed. A missing restatement would let a human
|
|
178
|
+
// freeze the method they suggested instead of the problem the agent understood.
|
|
179
|
+
const RESTATEMENT_KEYS = ['problem', 'doneWhen', 'failIf', 'unknowns'];
|
|
180
|
+
|
|
181
|
+
function restatementProblems(contract) {
|
|
182
|
+
const value = contract?.restatement;
|
|
183
|
+
if (!value || typeof value !== 'object' || Array.isArray(value)) {
|
|
184
|
+
return ['restatement is required: problem, doneWhen, failIf, unknowns'];
|
|
185
|
+
}
|
|
186
|
+
const errors = [];
|
|
187
|
+
for (const key of RESTATEMENT_KEYS) {
|
|
188
|
+
if (typeof value[key] !== 'string' || !value[key].trim()) errors.push(`restatement.${key} is required`);
|
|
189
|
+
}
|
|
190
|
+
return errors;
|
|
191
|
+
}
|
|
192
|
+
|
|
176
193
|
// Optional Goal scope (#59): absent = no path enforcement.
|
|
177
194
|
function validateGoalScope(scope) {
|
|
178
195
|
if (scope === undefined) return [];
|
|
@@ -844,6 +861,7 @@ module.exports = {
|
|
|
844
861
|
hashFile,
|
|
845
862
|
assertArtifactCurrent,
|
|
846
863
|
validateGoalContract,
|
|
864
|
+
restatementProblems,
|
|
847
865
|
validateVerificationBundle,
|
|
848
866
|
validateVerdictDocument,
|
|
849
867
|
judgeRequirement,
|
package/lib/git-readiness.js
CHANGED
|
@@ -33,4 +33,9 @@ function assertGitReady(rootDir) {
|
|
|
33
33
|
return result;
|
|
34
34
|
}
|
|
35
35
|
|
|
36
|
-
|
|
36
|
+
function gitTopLevel(rootDir) {
|
|
37
|
+
const result = git(rootDir, ['rev-parse', '--show-toplevel']);
|
|
38
|
+
return result.ok && result.out ? result.out : null;
|
|
39
|
+
}
|
|
40
|
+
|
|
41
|
+
module.exports = { assertGitReady, gitReadiness, gitTopLevel };
|