ai-engineering-loop 2.6.0 → 2.8.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 +1 -1
- package/.agents/skills/ael/references/loop-commands.md +13 -1
- package/.agents/skills/ael/references/loop-deliver.md +1 -1
- package/.agents/skills/ael/references/loop-goal.md +2 -0
- package/.agents/skills/ael/references/loop-maker.md +1 -6
- package/.agents/skills/ael/references/loop-report.md +8 -0
- package/.agents/skills/ael/references/loop-verify.md +11 -9
- package/.claude/agents/devil-advocate.md +7 -2
- package/.claude/agents/judge.md +3 -1
- package/.grok/agents/devil-advocate.md +7 -2
- package/.grok/agents/judge.md +3 -1
- package/CHANGELOG.md +31 -0
- package/agents/devil-advocate.md +8 -0
- package/agents/judge.md +1 -0
- package/agents/shared/devil-advocate.body.md +7 -2
- package/agents/shared/judge.body.md +3 -1
- package/bin/ai-engineering-loop.js +326 -21
- package/core/bench.md +15 -0
- package/core/formal-statechart.md +49 -0
- package/core/goal-contract.md +53 -0
- package/core/verification-loop.md +106 -1
- package/lib/ablation.js +52 -0
- package/lib/ac-status.js +95 -0
- package/lib/baseline.js +138 -0
- package/lib/bench.js +24 -1
- package/lib/budget.js +9 -1
- package/lib/calibration.js +129 -0
- package/lib/claimed-vs-reality.js +106 -12
- package/lib/clean-state.js +85 -0
- package/lib/cli-args.js +5 -3
- package/lib/comment-findings.js +111 -0
- package/lib/debt.js +110 -0
- package/lib/feature-map.js +57 -0
- package/lib/features.js +95 -0
- package/lib/flow.js +86 -0
- package/lib/gates.js +257 -41
- package/lib/harness-audit.js +141 -0
- package/lib/learn.js +24 -1
- package/lib/no-progress.js +6 -1
- package/lib/receipt.js +33 -2
- package/lib/reverts.js +77 -0
- package/lib/review-ingest.js +54 -2
- package/lib/rule-check.js +90 -0
- package/lib/rules.js +205 -0
- package/lib/stats.js +110 -0
- package/lib/sync-hosts.js +1 -0
- package/lib/verification-integrity.js +164 -0
- package/lib/verification-lanes.js +96 -0
- package/lib/verification-recorder.js +20 -8
- package/package.json +1 -1
- package/schemas/finding-ledger.schema.json +14 -0
- package/schemas/goal-contract.schema.json +50 -0
- package/schemas/verdict.schema.json +2 -1
package/lib/features.js
ADDED
|
@@ -0,0 +1,95 @@
|
|
|
1
|
+
'use strict';
|
|
2
|
+
|
|
3
|
+
// Project feature ledger (C-15, learn-harness-engineering L07/L08): the
|
|
4
|
+
// cross-Run list of what the project must do. Each feature is a triple
|
|
5
|
+
// (behavior, verify, status). Status moves only through Run transitions:
|
|
6
|
+
// a frozen Goal with `featureId` makes it `active`, delivery makes it
|
|
7
|
+
// `passing` with the Run as evidence. `next` picks the next feature and
|
|
8
|
+
// reports VCR = verified / activated.
|
|
9
|
+
|
|
10
|
+
const fs = require('fs');
|
|
11
|
+
const path = require('path');
|
|
12
|
+
const { atomicWriteJson, loadRun } = require('./run-state.js');
|
|
13
|
+
|
|
14
|
+
const FEATURES_FILE = path.join('.ai-engineering-loop', 'features.json');
|
|
15
|
+
const STATUSES = Object.freeze(['not_started', 'active', 'blocked', 'passing']);
|
|
16
|
+
|
|
17
|
+
function featuresPath(rootDir) {
|
|
18
|
+
return path.join(rootDir, FEATURES_FILE);
|
|
19
|
+
}
|
|
20
|
+
|
|
21
|
+
function loadFeatures(rootDir) {
|
|
22
|
+
try {
|
|
23
|
+
const value = JSON.parse(fs.readFileSync(featuresPath(rootDir), 'utf8'));
|
|
24
|
+
return Array.isArray(value.features) ? value : null;
|
|
25
|
+
} catch {
|
|
26
|
+
return null;
|
|
27
|
+
}
|
|
28
|
+
}
|
|
29
|
+
|
|
30
|
+
function save(rootDir, document) {
|
|
31
|
+
atomicWriteJson(featuresPath(rootDir), document);
|
|
32
|
+
}
|
|
33
|
+
|
|
34
|
+
function transition(rootDir, featureId, to, { runId, now = new Date() } = {}) {
|
|
35
|
+
const document = loadFeatures(rootDir);
|
|
36
|
+
const feature = document?.features.find((item) => item.id === featureId);
|
|
37
|
+
if (!feature) return null;
|
|
38
|
+
if (feature.status === 'passing' && to !== 'passing') return feature; // passing is final
|
|
39
|
+
feature.status = to;
|
|
40
|
+
feature.history = [...(feature.history || []), { to, runId, at: now.toISOString() }];
|
|
41
|
+
if (to === 'passing') feature.evidence = { runId, deliveredAt: now.toISOString() };
|
|
42
|
+
save(rootDir, document);
|
|
43
|
+
return feature;
|
|
44
|
+
}
|
|
45
|
+
|
|
46
|
+
// Called by the Goal gate.
|
|
47
|
+
function onGoalFrozen(rootDir, run, goal) {
|
|
48
|
+
if (!goal?.featureId) return null;
|
|
49
|
+
const feature = loadFeatures(rootDir)?.features.find((item) => item.id === goal.featureId);
|
|
50
|
+
if (!feature || feature.status === 'passing') return feature || null;
|
|
51
|
+
return transition(rootDir, goal.featureId, 'active', { runId: run.runId });
|
|
52
|
+
}
|
|
53
|
+
|
|
54
|
+
// Called by the delivery gate.
|
|
55
|
+
function onDelivered(rootDir, run, goal) {
|
|
56
|
+
if (!goal?.featureId) return null;
|
|
57
|
+
return transition(rootDir, goal.featureId, 'passing', { runId: run.runId });
|
|
58
|
+
}
|
|
59
|
+
|
|
60
|
+
function vcr(document) {
|
|
61
|
+
const features = document?.features || [];
|
|
62
|
+
const activated = features.filter((item) => item.status !== 'not_started').length;
|
|
63
|
+
const verified = features.filter((item) => item.status === 'passing').length;
|
|
64
|
+
return { verified, activated, value: activated ? Math.round((verified / activated) * 1000) / 1000 : 1 };
|
|
65
|
+
}
|
|
66
|
+
|
|
67
|
+
function nextFeature(document) {
|
|
68
|
+
const features = document?.features || [];
|
|
69
|
+
const passing = new Set(features.filter((item) => item.status === 'passing').map((item) => item.id));
|
|
70
|
+
return features
|
|
71
|
+
.filter((item) => item.status === 'not_started' && (item.dependsOn || []).every((id) => passing.has(id)))
|
|
72
|
+
.sort((a, b) => (a.priority ?? 999) - (b.priority ?? 999))[0] || null;
|
|
73
|
+
}
|
|
74
|
+
|
|
75
|
+
// A `passing` feature must point at a delivered Run whose Goal names it.
|
|
76
|
+
function auditFeatures(rootDir, document = loadFeatures(rootDir)) {
|
|
77
|
+
const problems = [];
|
|
78
|
+
for (const feature of document?.features || []) {
|
|
79
|
+
if (!STATUSES.includes(feature.status)) problems.push(`${feature.id}: unknown status ${feature.status}`);
|
|
80
|
+
if (feature.status !== 'passing') continue;
|
|
81
|
+
const runId = feature.evidence?.runId;
|
|
82
|
+
let run = null;
|
|
83
|
+
try {
|
|
84
|
+
run = runId ? loadRun(rootDir, runId) : null;
|
|
85
|
+
} catch {
|
|
86
|
+
run = null;
|
|
87
|
+
}
|
|
88
|
+
if (!run || run.state !== 'DELIVERED') {
|
|
89
|
+
problems.push(`${feature.id}: marked passing without a delivered Run as evidence. FIX: set it back to not_started and deliver it through a Run whose Goal has featureId "${feature.id}".`);
|
|
90
|
+
}
|
|
91
|
+
}
|
|
92
|
+
return problems;
|
|
93
|
+
}
|
|
94
|
+
|
|
95
|
+
module.exports = { FEATURES_FILE, STATUSES, auditFeatures, loadFeatures, nextFeature, onDelivered, onGoalFrozen, vcr };
|
package/lib/flow.js
ADDED
|
@@ -0,0 +1,86 @@
|
|
|
1
|
+
'use strict';
|
|
2
|
+
|
|
3
|
+
// Goal `flow` (C-21, "All Code Is Slop (Except Mine)" 12:46): a small state
|
|
4
|
+
// machine from the user's point of view, so a human can check that the agent
|
|
5
|
+
// understood the intent before any code exists, and review it again next to
|
|
6
|
+
// the verification artifacts. Plain Markdown tables (no diagram engine), so
|
|
7
|
+
// it renders on every host and in every PR.
|
|
8
|
+
//
|
|
9
|
+
// "flow": [ { "from": "List", "event": "click Export", "to": "Exporting" }, ... ]
|
|
10
|
+
|
|
11
|
+
function flowProblems(flow) {
|
|
12
|
+
if (flow == null) return [];
|
|
13
|
+
if (!Array.isArray(flow) || !flow.length) return ['flow must be a non-empty array of {from, event, to}'];
|
|
14
|
+
const problems = [];
|
|
15
|
+
flow.forEach((step, index) => {
|
|
16
|
+
for (const field of ['from', 'event', 'to']) {
|
|
17
|
+
if (!String(step?.[field] || '').trim()) problems.push(`flow[${index}].${field} is required`);
|
|
18
|
+
}
|
|
19
|
+
});
|
|
20
|
+
return problems;
|
|
21
|
+
}
|
|
22
|
+
|
|
23
|
+
// Warnings a reviewer should look at: states nothing leads to (besides the
|
|
24
|
+
// first), and states with no way out that are not marked terminal.
|
|
25
|
+
function flowWarnings(flow) {
|
|
26
|
+
if (flowProblems(flow).length || !flow) return [];
|
|
27
|
+
const start = flow[0].from;
|
|
28
|
+
const sources = new Set(flow.map((step) => step.from));
|
|
29
|
+
const targets = new Set(flow.map((step) => step.to));
|
|
30
|
+
const states = [...new Set(flow.flatMap((step) => [step.from, step.to]))];
|
|
31
|
+
const warnings = [];
|
|
32
|
+
for (const state of states) {
|
|
33
|
+
if (state !== start && !targets.has(state)) warnings.push(`"${state}" is never reached from another state`);
|
|
34
|
+
if (!sources.has(state) && !/^(done|end|closed|success|error|failed|cancel(l)?ed)$/i.test(state)) {
|
|
35
|
+
warnings.push(`"${state}" has no way out; mark it terminal (Done/Error) or add the next step`);
|
|
36
|
+
}
|
|
37
|
+
}
|
|
38
|
+
return warnings;
|
|
39
|
+
}
|
|
40
|
+
|
|
41
|
+
const cell = (value) => String(value ?? '').replace(/\r?\n/g, ' ').replace(/\|/g, '\\|');
|
|
42
|
+
|
|
43
|
+
function renderFlow(flow) {
|
|
44
|
+
if (!Array.isArray(flow) || !flow.length) return '';
|
|
45
|
+
return ['| From | Event | To |', '|---|---|---|', ...flow.map((step) => `| ${cell(step.from)} | ${cell(step.event)} | ${cell(step.to)} |`)].join('\n');
|
|
46
|
+
}
|
|
47
|
+
|
|
48
|
+
// C-25: the same flow as a Mermaid stateDiagram-v2 (GitHub renders it in
|
|
49
|
+
// PRs). States get safe ids (s0, s1, ...) with the reader's label attached,
|
|
50
|
+
// so any text in a state name keeps the diagram valid. Visualisation only:
|
|
51
|
+
// model checking stays with the `formal` key (e.g. pstack /statechart).
|
|
52
|
+
const TERMINAL = /^(done|end|closed|success|error|failed|cancel(l)?ed)$/i;
|
|
53
|
+
|
|
54
|
+
function mermaidText(value) {
|
|
55
|
+
return String(value ?? '')
|
|
56
|
+
.replace(/[\r\n]+/g, ' ')
|
|
57
|
+
.replace(/"/g, "'")
|
|
58
|
+
.replace(/;/g, ',')
|
|
59
|
+
.replace(/#/g, 'no. ')
|
|
60
|
+
.replace(/[{}<>]/g, '')
|
|
61
|
+
.trim();
|
|
62
|
+
}
|
|
63
|
+
|
|
64
|
+
function renderMermaid(flow) {
|
|
65
|
+
if (!Array.isArray(flow) || !flow.length || flowProblems(flow).length) return '';
|
|
66
|
+
const ids = new Map();
|
|
67
|
+
const idOf = (state) => {
|
|
68
|
+
if (!ids.has(state)) ids.set(state, `s${ids.size}`);
|
|
69
|
+
return ids.get(state);
|
|
70
|
+
};
|
|
71
|
+
for (const step of flow) {
|
|
72
|
+
idOf(step.from);
|
|
73
|
+
idOf(step.to);
|
|
74
|
+
}
|
|
75
|
+
const sources = new Set(flow.map((step) => step.from));
|
|
76
|
+
const lines = ['stateDiagram-v2'];
|
|
77
|
+
for (const [state, id] of ids) lines.push(` state "${mermaidText(state)}" as ${id}`);
|
|
78
|
+
lines.push(` [*] --> ${idOf(flow[0].from)}`);
|
|
79
|
+
for (const step of flow) lines.push(` ${idOf(step.from)} --> ${idOf(step.to)}: ${mermaidText(step.event)}`);
|
|
80
|
+
for (const [state, id] of ids) {
|
|
81
|
+
if (!sources.has(state) && TERMINAL.test(state)) lines.push(` ${id} --> [*]`);
|
|
82
|
+
}
|
|
83
|
+
return lines.join('\n');
|
|
84
|
+
}
|
|
85
|
+
|
|
86
|
+
module.exports = { flowProblems, flowWarnings, renderFlow, renderMermaid };
|