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.
- package/.agents/skills/ael/SKILL.md +3 -19
- package/.agents/skills/ael/references/loop-commands.md +5 -3
- package/.agents/skills/ael/references/loop-deliver.md +20 -0
- package/.agents/skills/ael/references/loop-goal.md +3 -2
- package/.agents/skills/ael/references/loop-hosts.md +10 -0
- package/.agents/skills/ael/references/loop-judge.md +9 -0
- package/.agents/skills/ael/references/loop-maker.md +1 -2
- package/.agents/skills/ael/references/loop-modes.md +6 -0
- package/.agents/skills/ael/references/loop-review.md +2 -6
- package/CHANGELOG.md +35 -0
- package/README.md +9 -1
- package/agents/instruction-only/AGENTS.md +1 -1
- package/bin/ai-engineering-loop.js +398 -41
- package/core/dig-first.md +46 -0
- package/core/goal-contract.md +40 -0
- package/core/run-isolation.md +24 -0
- package/core/verification-loop.md +27 -0
- package/lib/adapter-check.js +3 -2
- package/lib/agent-artifacts.js +28 -0
- package/lib/budget.js +1 -1
- package/lib/clean-state.js +20 -0
- package/lib/cli-args.js +5 -2
- package/lib/docs.js +2 -1
- package/lib/doctor.js +26 -0
- package/lib/driver-scaffold.js +289 -0
- package/lib/gates.js +3 -1
- package/lib/gh.js +27 -0
- package/lib/git-readiness.js +36 -0
- package/lib/harness-audit.js +11 -0
- package/lib/pr-status.js +83 -0
- package/lib/provenance.js +111 -0
- package/lib/quick.js +11 -0
- package/lib/recap-html.js +3 -2
- package/lib/recap.js +9 -0
- package/lib/receipt.js +3 -1
- package/lib/review-ingest.js +6 -1
- package/lib/rules.js +4 -2
- package/lib/run-isolation.js +117 -27
- package/lib/sources.js +166 -0
- package/lib/stats.js +9 -0
- package/lib/ste.js +69 -0
- package/lib/sync-hosts.js +2 -0
- package/lib/transcript-lessons.js +232 -0
- package/lib/workflow-runtime.js +8 -2
- package/package.json +2 -2
- package/schemas/goal-contract.schema.json +14 -0
package/lib/sources.js
ADDED
|
@@ -0,0 +1,166 @@
|
|
|
1
|
+
'use strict';
|
|
2
|
+
|
|
3
|
+
const fs = require('fs');
|
|
4
|
+
const os = require('os');
|
|
5
|
+
const path = require('path');
|
|
6
|
+
const { spawnSync } = require('child_process');
|
|
7
|
+
const { redactHomePaths, redactSecrets } = require('./safe-context.js');
|
|
8
|
+
const { gitReadiness } = require('./git-readiness.js');
|
|
9
|
+
|
|
10
|
+
const SOURCES_FILE = path.join('.ai-engineering-loop', 'sources.md');
|
|
11
|
+
const GATHER_BUDGET = Object.freeze({ T0: 0, T1: 4, T2: 8 });
|
|
12
|
+
const SCOPE_HEADING = '## Scope (edit me)';
|
|
13
|
+
const MAX_LINE = 200;
|
|
14
|
+
|
|
15
|
+
const home = () => process.env.HOME || process.env.USERPROFILE || os.homedir();
|
|
16
|
+
const fail = (message, code, extra = {}) => Object.assign(new Error(message), { code, ...extra });
|
|
17
|
+
|
|
18
|
+
function runTool(bin, args, cwd) {
|
|
19
|
+
const command = bin.endsWith('.js') ? process.execPath : bin;
|
|
20
|
+
const argv = bin.endsWith('.js') ? [bin, ...args] : args;
|
|
21
|
+
const result = spawnSync(command, argv, { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], timeout: 10000 });
|
|
22
|
+
return { installed: !(result.error && result.error.code === 'ENOENT'), ok: result.status === 0, out: `${result.stdout || ''}` };
|
|
23
|
+
}
|
|
24
|
+
|
|
25
|
+
function readText(file) {
|
|
26
|
+
try {
|
|
27
|
+
return fs.readFileSync(file, 'utf8');
|
|
28
|
+
} catch {
|
|
29
|
+
return '';
|
|
30
|
+
}
|
|
31
|
+
}
|
|
32
|
+
|
|
33
|
+
function remotes(rootDir) {
|
|
34
|
+
return runTool('git', ['remote', '-v'], rootDir).out;
|
|
35
|
+
}
|
|
36
|
+
|
|
37
|
+
function mattermostConfigs(rootDir, base) {
|
|
38
|
+
const candidates = [
|
|
39
|
+
path.join(base, '.claude.json'),
|
|
40
|
+
path.join(base, '.claude', 'settings.json'),
|
|
41
|
+
path.join(base, '.cursor', 'mcp.json'),
|
|
42
|
+
path.join(base, '.codex', 'config.toml'),
|
|
43
|
+
path.join(base, '.gemini', 'settings.json'),
|
|
44
|
+
path.join(base, '.gemini', 'antigravity', 'mcp_config.json'),
|
|
45
|
+
path.join(rootDir, '.mcp.json'),
|
|
46
|
+
path.join(rootDir, '.cursor', 'mcp.json')
|
|
47
|
+
];
|
|
48
|
+
return candidates.filter((file) => /mattermost/i.test(readText(file))).map((file) => redactHomePaths(file));
|
|
49
|
+
}
|
|
50
|
+
|
|
51
|
+
function aelHistory(rootDir) {
|
|
52
|
+
const dir = path.join(rootDir, '.ai-engineering-loop');
|
|
53
|
+
let runs = 0;
|
|
54
|
+
try {
|
|
55
|
+
runs = fs.readdirSync(path.join(dir, 'runs')).filter((name) => name !== 'current.json').length;
|
|
56
|
+
} catch {
|
|
57
|
+
runs = 0;
|
|
58
|
+
}
|
|
59
|
+
const parts = [];
|
|
60
|
+
if (runs) parts.push(`${runs} past Run(s)`);
|
|
61
|
+
for (const name of ['lessons.md', 'debt.json', 'feature-map.md', 'transcript-lessons.json']) {
|
|
62
|
+
if (fs.existsSync(path.join(dir, name))) parts.push(name);
|
|
63
|
+
}
|
|
64
|
+
return parts;
|
|
65
|
+
}
|
|
66
|
+
|
|
67
|
+
function detectSources(rootDir, { homeDir = home() } = {}) {
|
|
68
|
+
const git = gitReadiness(rootDir);
|
|
69
|
+
const remoteText = git.ok ? remotes(rootDir) : '';
|
|
70
|
+
const gh = runTool(process.env.AEL_GH_BIN || 'gh', ['auth', 'status'], rootDir);
|
|
71
|
+
const glab = runTool(process.env.AEL_GLAB_BIN || 'glab', ['auth', 'status'], rootDir);
|
|
72
|
+
const mattermost = mattermostConfigs(rootDir, homeDir);
|
|
73
|
+
const history = aelHistory(rootDir);
|
|
74
|
+
const status = (tool) => (!tool.installed ? 'not installed' : tool.ok ? 'logged in' : 'installed, not logged in');
|
|
75
|
+
return [
|
|
76
|
+
{ id: 'code', label: 'Code and git history', available: git.ok, detail: git.ok ? 'git log, git blame, rg' : git.message, try: 'rg -n "<term>"; git log -S "<term>" --oneline -n 5' },
|
|
77
|
+
{ id: 'github', label: 'GitHub issues and PRs', available: gh.ok, detail: `gh ${status(gh)}${/github\.com/.test(remoteText) ? ', GitHub remote' : ''}`, try: 'gh issue list --search "<term>" -L 5; gh pr list --search "<term>" --state all -L 5' },
|
|
78
|
+
{ id: 'gitlab', label: 'GitLab issues and MRs', available: glab.ok, detail: `glab ${status(glab)}${/gitlab/.test(remoteText) ? ', GitLab remote' : ''}`, try: 'glab issue list --search "<term>"; glab mr list --search "<term>"' },
|
|
79
|
+
{ id: 'mattermost', label: 'Mattermost (read-only MCP)', available: mattermost.length > 0, detail: mattermost.length ? `MCP configured in ${mattermost.join(', ')}` : 'no Mattermost MCP found in host configs', try: 'Mattermost-Agent MCP read/search tools only, within the channels listed under Scope; never post' },
|
|
80
|
+
{ id: 'ael', label: 'AEL history', available: history.length > 0, detail: history.length ? history.join(', ') : 'nothing yet', try: 'ai-engineering-loop learn; ai-engineering-loop debt list' }
|
|
81
|
+
];
|
|
82
|
+
}
|
|
83
|
+
|
|
84
|
+
function existingScope(text) {
|
|
85
|
+
const start = text.indexOf(SCOPE_HEADING);
|
|
86
|
+
return start === -1 ? null : text.slice(start).trimEnd();
|
|
87
|
+
}
|
|
88
|
+
|
|
89
|
+
function renderSources(sources, scope) {
|
|
90
|
+
const rows = sources.map((item) => `| ${item.id} | ${item.available ? 'yes' : 'no'} | ${item.label} | ${item.detail} | \`${item.try}\` |`);
|
|
91
|
+
return [
|
|
92
|
+
'# Sources the agent may read before asking you',
|
|
93
|
+
'',
|
|
94
|
+
'Generated by `ai-engineering-loop init`, `refresh` and `sources refresh`. The table is rewritten; the Scope section below is yours and is kept.',
|
|
95
|
+
'',
|
|
96
|
+
'Rules: read-only. Dig in these sources before asking the human. Per-Run budget: T0 0, T1 4, T2 8 gather queries (`sources record`). A Goal Contract fact must cite a source the CLI can check (`path:line`, commit, or a recorded `S-n`).',
|
|
97
|
+
'',
|
|
98
|
+
'| Source | Available | What | Detail | Try |',
|
|
99
|
+
'|---|---|---|---|---|',
|
|
100
|
+
...rows,
|
|
101
|
+
'',
|
|
102
|
+
scope || `${SCOPE_HEADING}\n\n- Mattermost channels: <none yet; list channel names the agent may read>\n- Issue labels or projects: <optional>\n- Never read: <optional>`,
|
|
103
|
+
''
|
|
104
|
+
].join('\n');
|
|
105
|
+
}
|
|
106
|
+
|
|
107
|
+
function writeSourcesFile(rootDir, options = {}) {
|
|
108
|
+
const file = path.join(rootDir, SOURCES_FILE);
|
|
109
|
+
const sources = detectSources(rootDir, options);
|
|
110
|
+
fs.mkdirSync(path.dirname(file), { recursive: true });
|
|
111
|
+
fs.writeFileSync(file, renderSources(sources, existingScope(readText(file))));
|
|
112
|
+
return { path: SOURCES_FILE.split(path.sep).join('/'), sources };
|
|
113
|
+
}
|
|
114
|
+
|
|
115
|
+
function sourcesPath(rootDir, runId) {
|
|
116
|
+
return path.join(rootDir, '.ai-engineering-loop', 'runs', runId, 'sources.json');
|
|
117
|
+
}
|
|
118
|
+
|
|
119
|
+
function loadGathered(rootDir, runId) {
|
|
120
|
+
try {
|
|
121
|
+
const value = JSON.parse(fs.readFileSync(sourcesPath(rootDir, runId), 'utf8'));
|
|
122
|
+
return Array.isArray(value.entries) ? value.entries : [];
|
|
123
|
+
} catch {
|
|
124
|
+
return [];
|
|
125
|
+
}
|
|
126
|
+
}
|
|
127
|
+
|
|
128
|
+
const clean = (text) => {
|
|
129
|
+
const value = redactHomePaths(redactSecrets(String(text || '')).text).replace(/\s+/g, ' ').trim();
|
|
130
|
+
return value.length > MAX_LINE ? `${value.slice(0, MAX_LINE - 1)}…` : value;
|
|
131
|
+
};
|
|
132
|
+
|
|
133
|
+
function recordGather(rootDir, run, { source, ref, line }) {
|
|
134
|
+
if (!String(source || '').trim() || !String(ref || '').trim() || !String(line || '').trim()) {
|
|
135
|
+
throw fail('sources record needs --source, --ref and --line', 'INVALID_USAGE', { why: 'Each gathered fact keeps where it came from and one line of what it says.', fix: '`sources record --run <id> --source github --ref https://github.com/o/r/issues/12 --line "Export must respect filters"`' });
|
|
136
|
+
}
|
|
137
|
+
const tier = run.tier?.current || 'T1';
|
|
138
|
+
const budget = GATHER_BUDGET[tier] ?? GATHER_BUDGET.T1;
|
|
139
|
+
const entries = loadGathered(rootDir, run.runId);
|
|
140
|
+
if (entries.length >= budget) {
|
|
141
|
+
throw fail(`Gather budget for ${tier} is ${budget} quer${budget === 1 ? 'y' : 'ies'}; ${entries.length} already recorded`, 'GATHER_BUDGET', {
|
|
142
|
+
why: 'Digging without a limit burns tokens; past the budget, asking the human one question is cheaper.',
|
|
143
|
+
fix: tier === 'T2' ? 'Stop gathering; mark the remaining statements as assumptions or ask the human one question.' : 'Stop gathering; mark the rest as assumptions, ask the human, or re-tier with `run --tier T2 --tier-reason "<why>"` if the task is bigger.'
|
|
144
|
+
});
|
|
145
|
+
}
|
|
146
|
+
const entry = { id: `S-${entries.length + 1}`, source: clean(source), ref: clean(ref), line: clean(line), at: new Date().toISOString() };
|
|
147
|
+
const next = [...entries, entry];
|
|
148
|
+
fs.writeFileSync(sourcesPath(rootDir, run.runId), `${JSON.stringify({ schemaVersion: 1, runId: run.runId, budget, entries: next }, null, 2)}\n`, { mode: 0o600 });
|
|
149
|
+
return { entry, used: next.length, budget };
|
|
150
|
+
}
|
|
151
|
+
|
|
152
|
+
function gatherHints(rootDir, run) {
|
|
153
|
+
const tier = run?.tier?.current || 'T1';
|
|
154
|
+
const terms = [...new Set(String(run?.task || '').toLowerCase().split(/[^a-z0-9_-]+/).filter((word) => word.length >= 4))].slice(0, 3);
|
|
155
|
+
const term = terms[0] || '<term>';
|
|
156
|
+
const sources = detectSources(rootDir).filter((item) => item.available);
|
|
157
|
+
return {
|
|
158
|
+
tier,
|
|
159
|
+
budget: GATHER_BUDGET[tier] ?? GATHER_BUDGET.T1,
|
|
160
|
+
used: run ? loadGathered(rootDir, run.runId).length : 0,
|
|
161
|
+
terms,
|
|
162
|
+
hints: sources.map((item) => ({ source: item.id, try: item.try.replace(/<term>/g, term) }))
|
|
163
|
+
};
|
|
164
|
+
}
|
|
165
|
+
|
|
166
|
+
module.exports = { GATHER_BUDGET, SOURCES_FILE, detectSources, gatherHints, loadGathered, recordGather, renderSources, writeSourcesFile };
|
package/lib/stats.js
CHANGED
|
@@ -75,7 +75,11 @@ function computeStats(rootDir, { last = null } = {}) {
|
|
|
75
75
|
const checking = ['reviewer', 'judge', 'verification'].reduce((sum, role) => sum + (tokensByRole[role] || 0), 0);
|
|
76
76
|
const { runInterventions, summarizeInterventions } = require('./interventions.js');
|
|
77
77
|
const interventions = summarizeInterventions(runs.map((runId) => runInterventions(path.join(runsDir(rootDir), runId))));
|
|
78
|
+
const repeatedCorrections = require('./transcript-lessons.js').loadTranscriptLessons(rootDir).slice(0, 3).map((entry) => ({ id: entry.id, sessions: entry.sessions, lesson: entry.lesson }));
|
|
79
|
+
const merged = runs.filter((runId) => require('./pr-status.js').loadMerge(rootDir, runId)).length;
|
|
78
80
|
return {
|
|
81
|
+
repeatedCorrections,
|
|
82
|
+
merged,
|
|
79
83
|
interventions,
|
|
80
84
|
revertRate: reverts.rate,
|
|
81
85
|
reverted: reverts.reverted,
|
|
@@ -101,6 +105,7 @@ function formatStats(stats) {
|
|
|
101
105
|
`Iterations to PASS (avg): ${stats.iterationsToPass ?? 'n/a'}`,
|
|
102
106
|
`Failure causes: ${Object.entries(stats.causes).map(([cause, count]) => `${cause} ${count}`).join(', ') || 'none'}`
|
|
103
107
|
];
|
|
108
|
+
if (stats.merged) lines.push(`Merged after delivery: ${stats.merged}/${stats.delivered} delivered Run(s) confirmed merged (pr status)`);
|
|
104
109
|
lines.push(`Revert rate: ${stats.reverted.length}/${stats.delivered} delivered Run(s) (${Math.round(stats.revertRate * 1000) / 10}%)${stats.reverted.length ? `: ${stats.reverted.map((item) => item.runId).join(', ')}` : ''}`);
|
|
105
110
|
if (stats.verificationTokenShare != null) lines.push(`Verification token share: ${Math.round(stats.verificationTokenShare * 100)}% (reviewer + judge + verification of role-labelled usage)`);
|
|
106
111
|
if (stats.interventions?.runs) {
|
|
@@ -109,6 +114,10 @@ function formatStats(stats) {
|
|
|
109
114
|
const ran = i.proofs.reproduced + i.proofs.not_reproduced;
|
|
110
115
|
if (ran) lines.push(`Finding proofs: ${i.proofs.reproduced}/${ran} reproduced (${Math.round(i.reproducedRate * 100)}%); ${i.proofs.not_reproduced} blocking finding(s) did not reproduce and stopped blocking`);
|
|
111
116
|
}
|
|
117
|
+
if (stats.repeatedCorrections?.length) {
|
|
118
|
+
lines.push('Corrections you keep repeating (learn --transcripts):');
|
|
119
|
+
for (const item of stats.repeatedCorrections) lines.push(`- ${item.id} ×${item.sessions} sessions: ${item.lesson}`);
|
|
120
|
+
}
|
|
112
121
|
if (stats.bottleneck) lines.push(`Bottleneck: ${stats.bottleneck}. Fix that harness layer first.`);
|
|
113
122
|
for (const [tier, bucket] of Object.entries(stats.tiers)) {
|
|
114
123
|
lines.push(`- ${tier}: ${bucket.runs} run(s), false-victory rate ${Math.round(bucket.falseVictoryRate * 100)}%`);
|
package/lib/ste.js
ADDED
|
@@ -0,0 +1,69 @@
|
|
|
1
|
+
'use strict';
|
|
2
|
+
|
|
3
|
+
const MAX_WORDS = { instruction: 20, description: 25 };
|
|
4
|
+
const VAGUE = ['should', 'might', 'could', 'would', 'may', 'maybe', 'probably', 'possibly', 'some', 'various', 'etc', 'and/or', 'appropriate', 'properly', 'correctly', 'as needed', 'if necessary', 'user-friendly', 'robust', 'seamless', 'fast', 'easy'];
|
|
5
|
+
const PASSIVE = /\b(is|are|was|were|be|been|being|gets|got)\s+(\w+ly\s+)?(\w+ed|built|done|made|shown|sent|set|written|given|taken|seen|known|found|kept|held|read|run|left|put|shut|split|spent|chosen|broken)\b/i;
|
|
6
|
+
const IMPERATIVE_HINT = /^(add|remove|show|hide|send|save|open|close|keep|use|return|reject|accept|write|read|run|stop|start|set|make|create|delete|update|move|check|display|export|import|log|block|allow)\b/i;
|
|
7
|
+
|
|
8
|
+
const words = (sentence) => sentence.split(/\s+/).filter((word) => /[A-Za-z0-9]/.test(word));
|
|
9
|
+
|
|
10
|
+
function sentences(text) {
|
|
11
|
+
return String(text || '')
|
|
12
|
+
.replace(/`[^`]*`/g, 'CODE')
|
|
13
|
+
.split(/(?<=[.!?;])\s+|\n+/)
|
|
14
|
+
.map((part) => part.trim())
|
|
15
|
+
.filter(Boolean);
|
|
16
|
+
}
|
|
17
|
+
|
|
18
|
+
function steFindings(text, { kind = 'description' } = {}) {
|
|
19
|
+
const findings = [];
|
|
20
|
+
const limit = MAX_WORDS[kind] || MAX_WORDS.description;
|
|
21
|
+
for (const sentence of sentences(text)) {
|
|
22
|
+
const count = words(sentence).length;
|
|
23
|
+
if (count > limit) findings.push({ rule: 'length', detail: `${count} words; keep ${kind} sentences at ${limit} or fewer` });
|
|
24
|
+
if (PASSIVE.test(sentence)) findings.push({ rule: 'active-voice', detail: `passive "${sentence.match(PASSIVE)[0]}"; say who does what` });
|
|
25
|
+
const lower = ` ${sentence.toLowerCase().replace(/[^a-z/\s-]/g, ' ')} `;
|
|
26
|
+
const vague = VAGUE.filter((word) => lower.includes(` ${word} `));
|
|
27
|
+
if (vague.length) findings.push({ rule: 'precise-words', detail: `vague: ${vague.join(', ')}; use a word a test can check` });
|
|
28
|
+
if (kind === 'instruction' && (sentence.match(/\b(and then|then|and also)\b/gi) || []).length) findings.push({ rule: 'one-instruction', detail: 'more than one action; write one sentence per action' });
|
|
29
|
+
if (/^\w+ing\b/.test(sentence) && !IMPERATIVE_HINT.test(sentence)) findings.push({ rule: 'no-ing-start', detail: 'starts with an -ing word; start with the subject or the verb' });
|
|
30
|
+
}
|
|
31
|
+
return findings;
|
|
32
|
+
}
|
|
33
|
+
|
|
34
|
+
function goalReadability(goal) {
|
|
35
|
+
const out = [];
|
|
36
|
+
const add = (field, text, kind) => {
|
|
37
|
+
for (const finding of steFindings(text, { kind })) out.push({ field, ...finding });
|
|
38
|
+
};
|
|
39
|
+
add('objective', goal?.objective, 'description');
|
|
40
|
+
if (goal?.plainSummary) add('plainSummary', goal.plainSummary, 'description');
|
|
41
|
+
for (const criterion of goal?.acceptanceCriteria || []) {
|
|
42
|
+
add(`${criterion.id}.statement`, criterion.statement, 'description');
|
|
43
|
+
(criterion.failureCases || []).forEach((item, index) => add(`${criterion.id}.failureCases[${index}]`, item, 'description'));
|
|
44
|
+
}
|
|
45
|
+
return out;
|
|
46
|
+
}
|
|
47
|
+
|
|
48
|
+
const line = (text) => String(text || '').replace(/\s+/g, ' ').trim();
|
|
49
|
+
|
|
50
|
+
function renderHumanGoal(goal, { runId = goal?.runId, revision = null } = {}) {
|
|
51
|
+
const parts = [`# Goal${runId ? ` for Run ${runId}` : ''}${revision != null ? ` (revision ${revision})` : ''}`, ''];
|
|
52
|
+
parts.push('## What changes', '', line(goal?.plainSummary || goal?.objective), '');
|
|
53
|
+
parts.push('## Done when', '');
|
|
54
|
+
for (const criterion of goal?.acceptanceCriteria || []) {
|
|
55
|
+
parts.push(`${criterion.id}. ${line(criterion.statement)}`);
|
|
56
|
+
parts.push(` - Proof: ${line(criterion.evidenceRequired)}.`.replace(/\.\.$/, '.'));
|
|
57
|
+
for (const failure of criterion.failureCases || []) parts.push(` - Fail if: ${line(failure)}`);
|
|
58
|
+
}
|
|
59
|
+
parts.push('');
|
|
60
|
+
if ((goal?.outOfScope || []).length) parts.push('## Not in this change', '', ...goal.outOfScope.map((item) => `- ${line(item)}`), '');
|
|
61
|
+
const statements = goal?.statements || [];
|
|
62
|
+
const unconfirmed = statements.filter((item) => item.kind === 'assumption');
|
|
63
|
+
if (unconfirmed.length) parts.push('## Not confirmed yet', '', ...unconfirmed.map((item) => `- ${line(item.text)}`), '');
|
|
64
|
+
const findings = goalReadability(goal);
|
|
65
|
+
if (findings.length) parts.push('## Writing checks (STE style, not blocking)', '', ...findings.map((item) => `- ${item.field}: ${item.detail}`), '');
|
|
66
|
+
return `${parts.join('\n').trimEnd()}\n`;
|
|
67
|
+
}
|
|
68
|
+
|
|
69
|
+
module.exports = { MAX_WORDS, goalReadability, renderHumanGoal, steFindings };
|
package/lib/sync-hosts.js
CHANGED
|
@@ -0,0 +1,232 @@
|
|
|
1
|
+
'use strict';
|
|
2
|
+
|
|
3
|
+
const fs = require('fs');
|
|
4
|
+
const os = require('os');
|
|
5
|
+
const path = require('path');
|
|
6
|
+
const { execFileSync } = require('child_process');
|
|
7
|
+
const { redactHomePaths, redactSecrets } = require('./safe-context.js');
|
|
8
|
+
|
|
9
|
+
const FILE = path.join('.ai-engineering-loop', 'transcript-lessons.json');
|
|
10
|
+
const HOSTS = ['claude', 'cursor', 'codex'];
|
|
11
|
+
const MAX_EXAMPLE = 200;
|
|
12
|
+
const MAX_TURN = 600;
|
|
13
|
+
const THRESHOLD = 0.6;
|
|
14
|
+
const DAY = 86400000;
|
|
15
|
+
const CORRECTION = /\b(don'?t|do not|never|stop doing|(same|still|keeps?|why)\b.{0,30}\bagain|already (said|told)|i (said|told) you|wrong|not what i|instead of|revert|undo|why did you|jangan|kok\b|(masih|kenapa)\b.{0,30}\blagi|sudah (di|aku |ku)?bilang|udah (di|aku |ku)?bilang|salah|kenapa (kamu|malah)|bukan (itu|begitu|gitu)|harusnya|seharusnya|malah)\b/i;
|
|
16
|
+
const STOPWORDS = new Set([
|
|
17
|
+
'the', 'and', 'for', 'with', 'that', 'this', 'from', 'into', 'you', 'your', 'please', 'again', 'don', 'not', 'dont', 'never', 'stop', 'already', 'said', 'told', 'wrong', 'why', 'did',
|
|
18
|
+
'yang', 'dan', 'untuk', 'dengan', 'dari', 'pada', 'tidak', 'akan', 'bisa', 'atau', 'ini', 'itu', 'jangan', 'kok', 'lagi', 'sudah', 'udah', 'bilang', 'salah', 'kenapa', 'kamu', 'malah', 'bukan', 'harusnya', 'seharusnya', 'aku', 'tolong', 'pakai', 'pake', 'use', 'using'
|
|
19
|
+
]);
|
|
20
|
+
|
|
21
|
+
const home = () => process.env.HOME || process.env.USERPROFILE || os.homedir();
|
|
22
|
+
const fail = (message, code = 'INVALID_USAGE') => Object.assign(new Error(message), { code });
|
|
23
|
+
|
|
24
|
+
function readLines(file) {
|
|
25
|
+
try {
|
|
26
|
+
return fs.readFileSync(file, 'utf8').split('\n').filter(Boolean).flatMap((line) => {
|
|
27
|
+
try {
|
|
28
|
+
return [JSON.parse(line)];
|
|
29
|
+
} catch {
|
|
30
|
+
return [];
|
|
31
|
+
}
|
|
32
|
+
});
|
|
33
|
+
} catch {
|
|
34
|
+
return [];
|
|
35
|
+
}
|
|
36
|
+
}
|
|
37
|
+
|
|
38
|
+
function listFiles(dir, match, depth = 4) {
|
|
39
|
+
const out = [];
|
|
40
|
+
const walk = (current, level) => {
|
|
41
|
+
let entries = [];
|
|
42
|
+
try {
|
|
43
|
+
entries = fs.readdirSync(current, { withFileTypes: true });
|
|
44
|
+
} catch {
|
|
45
|
+
return;
|
|
46
|
+
}
|
|
47
|
+
for (const entry of entries) {
|
|
48
|
+
const full = path.join(current, entry.name);
|
|
49
|
+
if (entry.isDirectory() && level < depth) walk(full, level + 1);
|
|
50
|
+
else if (entry.isFile() && match(entry.name)) out.push(full);
|
|
51
|
+
}
|
|
52
|
+
};
|
|
53
|
+
walk(dir, 0);
|
|
54
|
+
return out;
|
|
55
|
+
}
|
|
56
|
+
|
|
57
|
+
const textOf = (content) => (typeof content === 'string'
|
|
58
|
+
? content
|
|
59
|
+
: Array.isArray(content) ? content.filter((part) => part && ['text', 'input_text'].includes(part.type)).map((part) => part.text).join('\n') : '');
|
|
60
|
+
|
|
61
|
+
const humanText = (text) => {
|
|
62
|
+
const value = String(text || '').trim();
|
|
63
|
+
return value && !value.startsWith('<') && !/^caveat:/i.test(value) ? value : '';
|
|
64
|
+
};
|
|
65
|
+
|
|
66
|
+
function claudeSessions(repo) {
|
|
67
|
+
const slug = repo.replace(/[\\/:.]/g, '-');
|
|
68
|
+
const base = path.join(home(), '.claude', 'projects');
|
|
69
|
+
let dirs = [];
|
|
70
|
+
try {
|
|
71
|
+
dirs = fs.readdirSync(base).filter((name) => name === slug || name.startsWith(`${slug}--`));
|
|
72
|
+
} catch {
|
|
73
|
+
return { found: false, sessions: [] };
|
|
74
|
+
}
|
|
75
|
+
const sessions = [];
|
|
76
|
+
for (const dir of dirs) {
|
|
77
|
+
for (const file of listFiles(path.join(base, dir), (name) => name.endsWith('.jsonl'), 0)) {
|
|
78
|
+
const turns = readLines(file)
|
|
79
|
+
.filter((line) => line.type === 'user' && line.message && !line.isMeta && !line.isSidechain)
|
|
80
|
+
.map((line) => ({ text: humanText(textOf(line.message.content)), at: Date.parse(line.timestamp) || null }))
|
|
81
|
+
.filter((turn) => turn.text);
|
|
82
|
+
sessions.push({ host: 'claude', id: path.basename(file, '.jsonl'), turns });
|
|
83
|
+
}
|
|
84
|
+
}
|
|
85
|
+
return { found: dirs.length > 0, sessions };
|
|
86
|
+
}
|
|
87
|
+
|
|
88
|
+
function cursorSessions(repo) {
|
|
89
|
+
const slug = repo.replace(/^[\\/]+/, '').replace(/[\\/:.]/g, '-');
|
|
90
|
+
const dir = path.join(home(), '.cursor', 'projects', slug, 'agent-transcripts');
|
|
91
|
+
if (!fs.existsSync(dir)) return { found: false, sessions: [] };
|
|
92
|
+
const sessions = listFiles(dir, (name) => name.endsWith('.jsonl'), 2).map((file) => {
|
|
93
|
+
const at = fs.statSync(file).mtimeMs;
|
|
94
|
+
const turns = readLines(file)
|
|
95
|
+
.filter((line) => line.role === 'user')
|
|
96
|
+
.map((line) => ({ text: humanText(textOf(line.message?.content)), at }))
|
|
97
|
+
.filter((turn) => turn.text);
|
|
98
|
+
return { host: 'cursor', id: path.basename(file, '.jsonl'), turns };
|
|
99
|
+
});
|
|
100
|
+
return { found: true, sessions };
|
|
101
|
+
}
|
|
102
|
+
|
|
103
|
+
function codexSessions(repo) {
|
|
104
|
+
const dir = path.join(home(), '.codex', 'sessions');
|
|
105
|
+
if (!fs.existsSync(dir)) return { found: false, sessions: [] };
|
|
106
|
+
const target = path.resolve(repo);
|
|
107
|
+
const sessions = [];
|
|
108
|
+
for (const file of listFiles(dir, (name) => name.endsWith('.jsonl'), 4)) {
|
|
109
|
+
const lines = readLines(file);
|
|
110
|
+
const cwd = lines.find((line) => line.type === 'session_meta')?.payload?.cwd;
|
|
111
|
+
if (!cwd || (path.resolve(cwd) !== target && !path.resolve(cwd).startsWith(`${target}${path.sep}`))) continue;
|
|
112
|
+
const turns = lines
|
|
113
|
+
.filter((line) => line.type === 'response_item' && line.payload?.type === 'message' && line.payload.role === 'user')
|
|
114
|
+
.map((line) => ({ text: humanText(textOf(line.payload.content)), at: Date.parse(line.timestamp) || null }))
|
|
115
|
+
.filter((turn) => turn.text);
|
|
116
|
+
sessions.push({ host: 'codex', id: path.basename(file, '.jsonl'), turns });
|
|
117
|
+
}
|
|
118
|
+
return { found: true, sessions };
|
|
119
|
+
}
|
|
120
|
+
|
|
121
|
+
const READERS = { claude: claudeSessions, cursor: cursorSessions, codex: codexSessions };
|
|
122
|
+
|
|
123
|
+
function words(text) {
|
|
124
|
+
return [...new Set(String(text).toLowerCase().replace(/[`'"]/g, '').split(/[^a-z0-9_]+/)
|
|
125
|
+
.filter((word) => word.length >= 3 && !STOPWORDS.has(word) && !/^\d+$/.test(word)))].sort();
|
|
126
|
+
}
|
|
127
|
+
|
|
128
|
+
function similarity(left, right) {
|
|
129
|
+
if (!left.length || !right.length) return 0;
|
|
130
|
+
const set = new Set(left);
|
|
131
|
+
const shared = right.filter((word) => set.has(word)).length;
|
|
132
|
+
return shared >= 3 ? shared / Math.min(left.length, right.length) : 0;
|
|
133
|
+
}
|
|
134
|
+
|
|
135
|
+
const redact = (text) => {
|
|
136
|
+
const clean = redactHomePaths(redactSecrets(String(text)).text).replace(/\s+/g, ' ').trim();
|
|
137
|
+
return clean.length > MAX_EXAMPLE ? `${clean.slice(0, MAX_EXAMPLE - 1)}…` : clean;
|
|
138
|
+
};
|
|
139
|
+
|
|
140
|
+
function codeToken(text) {
|
|
141
|
+
const tick = String(text).match(/`([^`]{2,60})`/);
|
|
142
|
+
if (tick) return tick[1].trim();
|
|
143
|
+
const call = String(text).match(/\b([A-Za-z_$][\w$]*(?:\.[A-Za-z_$][\w$]*)+)\s*\(?/);
|
|
144
|
+
return call ? call[1] : null;
|
|
145
|
+
}
|
|
146
|
+
|
|
147
|
+
function provingCommit(repo, token) {
|
|
148
|
+
if (!token) return null;
|
|
149
|
+
try {
|
|
150
|
+
return execFileSync('git', ['log', '-S', token, '-n', '1', '--format=%H', '--', '.', ':(exclude).ai-engineering-loop'], { cwd: repo, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim() || null;
|
|
151
|
+
} catch {
|
|
152
|
+
return null;
|
|
153
|
+
}
|
|
154
|
+
}
|
|
155
|
+
|
|
156
|
+
function suggestedFix(repo, id, text) {
|
|
157
|
+
const token = codeToken(text);
|
|
158
|
+
if (token) {
|
|
159
|
+
const pattern = token.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
|
|
160
|
+
const commit = provingCommit(repo, token);
|
|
161
|
+
return {
|
|
162
|
+
level: 'lint',
|
|
163
|
+
why: `names code (${token}); a rule can block new uses`,
|
|
164
|
+
command: `ai-engineering-loop learn promote ${id} --forbid-api "${pattern}" --fix "<what to use instead>" --by <name>${commit ? ` --prove ${commit.slice(0, 12)}` : ''}`
|
|
165
|
+
};
|
|
166
|
+
}
|
|
167
|
+
if (/\btest|tes\b/i.test(text)) return { level: 'test', why: 'about tests; a test that fails on the mistake enforces it' };
|
|
168
|
+
return { level: 'docs', why: 'a judgment call; record it in lessons.md or a skill until it can be enforced' };
|
|
169
|
+
}
|
|
170
|
+
|
|
171
|
+
function mineTranscripts(repo, { hosts = HOSTS, since = 30, minSessions = 2, now = new Date() } = {}) {
|
|
172
|
+
const unknown = hosts.filter((host) => !HOSTS.includes(host));
|
|
173
|
+
if (unknown.length) throw fail(`--host must be ${HOSTS.join(', ')} or all (got ${unknown.join(', ')})`);
|
|
174
|
+
if (!Number.isInteger(since) || since < 1) throw fail('--since must be a number of days, such as 30 or 30d');
|
|
175
|
+
const cutoff = now.getTime() - since * DAY;
|
|
176
|
+
const scanned = {};
|
|
177
|
+
const corrections = [];
|
|
178
|
+
for (const host of hosts) {
|
|
179
|
+
const { found, sessions } = READERS[host](repo);
|
|
180
|
+
scanned[host] = found ? sessions.length : 'not found';
|
|
181
|
+
for (const session of sessions) {
|
|
182
|
+
session.turns.slice(1).forEach((turn) => {
|
|
183
|
+
if (turn.at && turn.at < cutoff) return;
|
|
184
|
+
if (turn.text.length > MAX_TURN || !CORRECTION.test(turn.text)) return;
|
|
185
|
+
const key = words(turn.text);
|
|
186
|
+
if (key.length >= 3) corrections.push({ host, session: `${host}:${session.id}`, text: turn.text, key, at: turn.at });
|
|
187
|
+
});
|
|
188
|
+
}
|
|
189
|
+
}
|
|
190
|
+
const groups = [];
|
|
191
|
+
for (const item of corrections) {
|
|
192
|
+
const group = groups.find((entry) => similarity(entry.key, item.key) >= THRESHOLD);
|
|
193
|
+
if (group) group.items.push(item);
|
|
194
|
+
else groups.push({ key: item.key, items: [item] });
|
|
195
|
+
}
|
|
196
|
+
const entries = groups
|
|
197
|
+
.map((group) => ({ group, sessions: new Set(group.items.map((item) => item.session)) }))
|
|
198
|
+
.filter(({ sessions }) => sessions.size >= minSessions)
|
|
199
|
+
.map(({ group, sessions }) => {
|
|
200
|
+
const id = `L-T${require('crypto').createHash('sha256').update(group.key.join(' ')).digest('hex').slice(0, 8)}`;
|
|
201
|
+
const latest = [...group.items].sort((a, b) => (b.at || 0) - (a.at || 0))[0];
|
|
202
|
+
return {
|
|
203
|
+
id,
|
|
204
|
+
source: 'transcripts',
|
|
205
|
+
lesson: redact(latest.text),
|
|
206
|
+
sessions: sessions.size,
|
|
207
|
+
occurrences: group.items.length,
|
|
208
|
+
hosts: [...new Set(group.items.map((item) => item.host))].sort(),
|
|
209
|
+
lastSeenAt: latest.at ? new Date(latest.at).toISOString() : null,
|
|
210
|
+
suggestedFix: suggestedFix(repo, id, latest.text)
|
|
211
|
+
};
|
|
212
|
+
})
|
|
213
|
+
.sort((a, b) => b.sessions - a.sessions || b.occurrences - a.occurrences);
|
|
214
|
+
return { scanned, corrections: corrections.length, entries };
|
|
215
|
+
}
|
|
216
|
+
|
|
217
|
+
function writeTranscriptLessons(repo, result, { since, now = new Date() }) {
|
|
218
|
+
const file = path.join(repo, FILE);
|
|
219
|
+
fs.mkdirSync(path.dirname(file), { recursive: true });
|
|
220
|
+
fs.writeFileSync(file, `${JSON.stringify({ schemaVersion: 1, generatedAt: now.toISOString(), sinceDays: since, scanned: result.scanned, entries: result.entries }, null, 2)}\n`, { mode: 0o600 });
|
|
221
|
+
return FILE;
|
|
222
|
+
}
|
|
223
|
+
|
|
224
|
+
function loadTranscriptLessons(repo) {
|
|
225
|
+
try {
|
|
226
|
+
return JSON.parse(fs.readFileSync(path.join(repo, FILE), 'utf8')).entries || [];
|
|
227
|
+
} catch {
|
|
228
|
+
return [];
|
|
229
|
+
}
|
|
230
|
+
}
|
|
231
|
+
|
|
232
|
+
module.exports = { FILE, HOSTS, loadTranscriptLessons, mineTranscripts, writeTranscriptLessons };
|
package/lib/workflow-runtime.js
CHANGED
|
@@ -465,11 +465,17 @@ function assertReady(workflow, nodeId) {
|
|
|
465
465
|
} else if (runtimeNode.reason) {
|
|
466
466
|
details.push(`Reason: ${runtimeNode.reason}.`);
|
|
467
467
|
}
|
|
468
|
-
|
|
468
|
+
const NEXT = { goal: 'goal draft, then `goal freeze`', maker: '`gate maker --from-git`', verification: '`verify`', review: '`review ingest` or `gate review`', judge: '`gate judge`', 'delivery-approval': '`deliver --approve --by <name>`', delivery: '`deliver --approve --by <name>`' };
|
|
469
|
+
const blocker = (workflow.plan.nodes.find((candidate) => workflow.state.nodes[candidate.id]?.status === NODE_STATES.READY) || dependencies[0]?.node)?.id;
|
|
470
|
+
const passed = SUCCESS_STATES.has(runtimeNode.status);
|
|
471
|
+
throw Object.assign(runtimeError(
|
|
469
472
|
`Node ${nodeId} is ${runtimeNode.status}, not READY`,
|
|
470
473
|
'NODE_NOT_READY',
|
|
471
474
|
details
|
|
472
|
-
)
|
|
475
|
+
), {
|
|
476
|
+
why: passed ? `Node ${nodeId} already finished; it does not run twice.` : 'Stages run in order; this one waits for the stage before it.',
|
|
477
|
+
fix: passed ? 'Move on to the next stage (`status` shows it).' : blocker ? `Next ready stage is '${blocker}': ${NEXT[blocker] || `\`node status --run ${workflow.run.runId}\``}.` : `Check \`node status --run ${workflow.run.runId}\` for what is pending.`
|
|
478
|
+
});
|
|
473
479
|
}
|
|
474
480
|
return node;
|
|
475
481
|
}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "ai-engineering-loop",
|
|
3
|
-
"version": "2.
|
|
3
|
+
"version": "2.14.0",
|
|
4
4
|
"description": "A visual workspace that helps AI coding agents plan, build, review, and ship reliable software.",
|
|
5
5
|
"main": "bin/ai-engineering-loop.js",
|
|
6
6
|
"bin": {
|
|
@@ -34,7 +34,7 @@
|
|
|
34
34
|
"scripts": {
|
|
35
35
|
"init": "node bin/ai-engineering-loop.js",
|
|
36
36
|
"test": "node --test",
|
|
37
|
-
"doctor": "node bin/ai-engineering-loop.js doctor",
|
|
37
|
+
"doctor": "node bin/ai-engineering-loop.js doctor --package",
|
|
38
38
|
"eval": "node bin/ai-engineering-loop.js eval",
|
|
39
39
|
"audit:package": "node scripts/audit-package.js",
|
|
40
40
|
"verify:release": "node scripts/verify-release.js",
|
|
@@ -198,6 +198,20 @@
|
|
|
198
198
|
"type": "string",
|
|
199
199
|
"minLength": 1
|
|
200
200
|
},
|
|
201
|
+
"statements": {
|
|
202
|
+
"description": "Optional (C-46): what the Goal rests on, labelled. A fact needs a source the CLI can check (path:line, commit SHA, a URL or S-n recorded with `sources record`); otherwise the goal gate downgrades it to assumption. Assumptions are shown, never blocking.",
|
|
203
|
+
"type": "array",
|
|
204
|
+
"items": {
|
|
205
|
+
"type": "object",
|
|
206
|
+
"required": ["text", "kind"],
|
|
207
|
+
"properties": {
|
|
208
|
+
"text": { "type": "string", "minLength": 1 },
|
|
209
|
+
"kind": { "enum": ["fact", "decision", "assumption"] },
|
|
210
|
+
"source": { "type": "string" },
|
|
211
|
+
"by": { "type": "string" }
|
|
212
|
+
}
|
|
213
|
+
}
|
|
214
|
+
},
|
|
201
215
|
"outOfScope": {
|
|
202
216
|
"description": "Optional list of things this Goal must not change.",
|
|
203
217
|
"type": "array",
|