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
|
@@ -0,0 +1,46 @@
|
|
|
1
|
+
# Dig First, Then Ask (C-45, C-46)
|
|
2
|
+
|
|
3
|
+
Agents guess when they cannot see the source, and they ask the human what the repo, the tracker or the chat already answers. AEL gives them a short list of where to look, a budget, and a way to show which Goal statements are backed by a source.
|
|
4
|
+
|
|
5
|
+
## Sources registry
|
|
6
|
+
|
|
7
|
+
`init`, `refresh` and `ai-engineering-loop sources refresh` write `.ai-engineering-loop/sources.md`:
|
|
8
|
+
|
|
9
|
+
| Source | Detected by | Read with |
|
|
10
|
+
|---|---|---|
|
|
11
|
+
| code | git work tree with a commit | `rg`, `git log -S`, `git blame` |
|
|
12
|
+
| github | `gh auth status` | `gh issue list --search`, `gh pr list --search` |
|
|
13
|
+
| gitlab | `glab auth status` | `glab issue list --search`, `glab mr list --search` |
|
|
14
|
+
| mattermost | a Mattermost MCP server in a host config (`~/.claude.json`, `~/.cursor/mcp.json`, `~/.codex/config.toml`, Gemini/Antigravity config, project `.mcp.json`) | the MCP's read and search tools only |
|
|
15
|
+
| ael | past Runs, `lessons.md`, `debt.json`, `feature-map.md` | `learn`, `debt list` |
|
|
16
|
+
|
|
17
|
+
The table is rewritten on every refresh. The `## Scope (edit me)` section is yours (channels, labels, things never to read) and is kept. Tokens are never stored. A missing source is listed as unavailable; nothing fails because of it, and the agent still digs in the code and git.
|
|
18
|
+
|
|
19
|
+
Connectors are triggers, not authorities: they are read-only. The agent never posts, comments or edits through them.
|
|
20
|
+
|
|
21
|
+
## Gather budget
|
|
22
|
+
|
|
23
|
+
| Tier | Gather queries per Run |
|
|
24
|
+
|---|---|
|
|
25
|
+
| T0 | 0 |
|
|
26
|
+
| T1 | 4 |
|
|
27
|
+
| T2 | 8 |
|
|
28
|
+
|
|
29
|
+
Record each useful result: `sources record --run <id> --source github --ref <url|path:line|sha> --line "<one line>"`. It lands in `runs/<id>/sources.json` as `S-n`, redacted, one line each. Past the budget the CLI refuses with `GATHER_BUDGET`: stop, mark the rest as assumptions, or ask the human one question. Stop early once every Goal statement has a source. `sources hint [--run <id>]` prints the commands worth trying for this task. Token use: `budget record --role gather`.
|
|
30
|
+
|
|
31
|
+
## Provenance labels
|
|
32
|
+
|
|
33
|
+
A Goal Contract may carry `statements`:
|
|
34
|
+
|
|
35
|
+
```json
|
|
36
|
+
"statements": [
|
|
37
|
+
{ "text": "Filters live in src/report/filters.js", "kind": "fact", "source": "src/report/filters.js:12" },
|
|
38
|
+
{ "text": "The issue asks for persistence", "kind": "fact", "source": "S-1" },
|
|
39
|
+
{ "text": "CSV, not XLSX", "kind": "decision", "by": "ega" },
|
|
40
|
+
{ "text": "Exports stay under 10k rows", "kind": "assumption" }
|
|
41
|
+
]
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
The goal gate checks every fact: `path:line` must exist, a commit SHA must exist (`git cat-file`), a URL or `S-n` must be recorded in `sources.json`. A fact that fails becomes an assumption with the reason; a decision with no `by` and no valid source does too. The gate never fails on this. Prose cannot turn an assumption into a fact; only a checkable source does.
|
|
45
|
+
|
|
46
|
+
The result is `runs/<id>/provenance.json`. Assumptions are shown, never blocking, on every tier: `status` ("Unconfirmed: n assumption(s)"), the receipt ("Unconfirmed assumptions"), and the review pack, where the Devil's Advocate may raise a finding when the code relies on one.
|
package/core/goal-contract.md
CHANGED
|
@@ -208,3 +208,43 @@ Then ask the human: freeze, another view, or turn `?` cells, hotspots and side e
|
|
|
208
208
|
|
|
209
209
|
The receipt lists `--evidence AC-N=<https-url>` links first, typed as video, screenshot or diagram from the URL. An AC with `crossComponent: true` or a `rubric` is `MISSING` (❌) until it has at least one such link, because a reviewer should be able to look at the behaviour rather than read the diff.
|
|
210
210
|
|
|
211
|
+
## JSON example for `goal draft` (C-50)
|
|
212
|
+
|
|
213
|
+
`goal draft --file` reads JSON, not the Markdown template above. `ai-engineering-loop scaffold goal [--run <id>]` writes this shape to `.ai-engineering-loop/drafts/goal.json` with `_templateOnly: true`; `goal draft` refuses the file until you replace the placeholders and delete `_templateOnly`. Keep drafts under `.ai-engineering-loop/` so they stay out of the Maker diff.
|
|
214
|
+
|
|
215
|
+
```json
|
|
216
|
+
{
|
|
217
|
+
"schemaVersion": 1,
|
|
218
|
+
"runId": "<runId>",
|
|
219
|
+
"objective": "Users can export the filtered report as CSV",
|
|
220
|
+
"acceptanceCriteria": [
|
|
221
|
+
{
|
|
222
|
+
"id": "AC-1",
|
|
223
|
+
"statement": "Export downloads a CSV containing only the filtered rows",
|
|
224
|
+
"evidenceRequired": "unit test output and a CSV sample",
|
|
225
|
+
"failureCases": ["CSV ignores the active filter", "empty report produces an error instead of a header-only file"]
|
|
226
|
+
}
|
|
227
|
+
],
|
|
228
|
+
"outOfScope": ["PDF export"]
|
|
229
|
+
}
|
|
230
|
+
```
|
|
231
|
+
|
|
232
|
+
Then: `goal draft --run <runId> --file .ai-engineering-loop/drafts/goal.json --revision 0`, show the draft to the human, and `goal freeze`.
|
|
233
|
+
|
|
234
|
+
## Writing for people: STE style (ASD-STE100)
|
|
235
|
+
|
|
236
|
+
The Goal JSON is for the tools; people read `RUN_DIR/goal.md` (`goal show --human`), written on every `goal draft`. Write the text fields in the style of ASD-STE100 Simplified Technical English (https://www.asd-ste100.org), so a reviewer, a client or a non-native reader understands each line on the first read:
|
|
237
|
+
|
|
238
|
+
| Rule | Do | Not |
|
|
239
|
+
|---|---|---|
|
|
240
|
+
| One fact or one action per sentence | "Export saves a CSV file." | "Export saves a CSV and then emails it and logs it." |
|
|
241
|
+
| Active voice: say who does what | "The API rejects an empty name." | "An empty name is rejected." |
|
|
242
|
+
| Short sentences | Instructions 20 words or fewer, descriptions 25 or fewer | Long sentences with many clauses |
|
|
243
|
+
| Words a test can check | "The page loads in 2 seconds or less." | "fast", "robust", "properly", "should", "etc." |
|
|
244
|
+
| Same word for the same thing | Use the glossary term every time | Switching between "invoice", "bill" and "receipt" |
|
|
245
|
+
| Start with the subject or the verb | "The filter keeps the last value." | "Keeping the last value, the filter..." |
|
|
246
|
+
|
|
247
|
+
`goal draft` prints `goal.md` and the next step by default; agents and scripts pass `--json` for the full JSON. With `--json` it returns `readability`: warnings for long sentences, passive voice, vague words, several actions in one sentence and sentences that start with an -ing word. They never block the gate; fix them before you ask for the freeze. AEL checks these general writing rules only; it does not ship the ASD-STE100 dictionary.
|
|
248
|
+
|
|
249
|
+
`goal.md` has these sections: What changes, Done when (each AC with its proof and "Fail if" lines), Not in this change, Not confirmed yet (assumptions from `statements`), and the writing checks.
|
|
250
|
+
|
package/core/run-isolation.md
CHANGED
|
@@ -53,3 +53,27 @@ A dirty worktree is kept, with the reason in `cleanup.keptReason`.
|
|
|
53
53
|
| Folder already deleted by hand | `git worktree prune`, entry closed |
|
|
54
54
|
|
|
55
55
|
Uncommitted or unmerged work is never removed. `status` and `run` print one line when something can be cleaned up.
|
|
56
|
+
|
|
57
|
+
### Buckets (C-41, from pstack `worktree-audit`)
|
|
58
|
+
|
|
59
|
+
`worktree prune` prints `SIZE AGE BUCKET RUN WORKTREE`, biggest first:
|
|
60
|
+
|
|
61
|
+
| Bucket | Meaning | Removed? |
|
|
62
|
+
|---|---|---|
|
|
63
|
+
| `hold-wip` | changed or staged tracked files | never, by any flag |
|
|
64
|
+
| `hold-live-run` | its AEL Run was active in the last 15 minutes | no |
|
|
65
|
+
| `hold-open-pr` | the branch has an open pull request (`gh pr list`) | no |
|
|
66
|
+
| `review` | Run still unfinished but quiet | no; idle 7+ days is reported |
|
|
67
|
+
| `scratch` | Run finished, only untracked files left (build output, logs) | with `--include-scratch` |
|
|
68
|
+
| `safe` | Run finished, clean | yes |
|
|
69
|
+
| `foreign` | not created by AEL (`--audit` only) | never |
|
|
70
|
+
|
|
71
|
+
`--audit` adds every other git worktree of the repository as `foreign`, so you can see what fills the disk; prune still only touches registered worktrees.
|
|
72
|
+
|
|
73
|
+
## `pr status` (C-42, from pstack `watch-pr`)
|
|
74
|
+
|
|
75
|
+
`ai-engineering-loop pr status [--run <id> | --branch <name> | --pr <n>] [--json]` reads the pull request once through `gh pr view` (no polling) and returns `merged`, `closed`, `blocker`, `waiting` or `ready`. Blockers are named: `draft`, `merge-conflicts`, `failing-checks: <names>`, `changes-requested`. `waiting` lists pending checks or `review`. With `--run`, the branch comes from the worktree registry or `delivery.json`.
|
|
76
|
+
|
|
77
|
+
When the PR is merged, the Run gets `runs/<id>/merge.json` (PR number, URL, merged at, merge commit), written once. `worktree prune` then deletes a squash-merged branch on that evidence without calling `gh`; `stats` counts merged Runs and `recap` shows "merged N after delivery" per Run and a "Merged into main" metric for the lead.
|
|
78
|
+
|
|
79
|
+
Without `gh`, or with `gh` signed out, the command stops with `GH_UNAVAILABLE` and the command to fix it. Set `AEL_GH_BIN` to use another `gh` binary.
|
|
@@ -244,3 +244,30 @@ Rules live in `.ai-engineering-loop/rules.json` (tracked). Default `verify` runs
|
|
|
244
244
|
|
|
245
245
|
Both are stored with `kind`, always use `scope: "diff"`, and run as `rules check <ruleId>` through the same CLI (so `rules.json` holds no machine-specific path). Violations print as `file:line: <message>` and the rule's FIX.
|
|
246
246
|
|
|
247
|
+
|
|
248
|
+
## 12. Corrections You Keep Repeating (C-44)
|
|
249
|
+
|
|
250
|
+
`learn` mines Run artifacts. The corrections a human types in agent chats ("jangan pakai X", "why did you … again") never reach it, so the same intervention repeats across sessions. `learn --transcripts` reads them:
|
|
251
|
+
|
|
252
|
+
```bash
|
|
253
|
+
npx ai-engineering-loop learn --transcripts [--since 30d] [--host claude|cursor|codex|all] [--min-sessions 2] [--dry-run] [--json]
|
|
254
|
+
```
|
|
255
|
+
|
|
256
|
+
- **Sources (read-only, local):** Claude Code `~/.claude/projects/<repo-slug>*/*.jsonl` (this repo and its Claude worktrees), Cursor `~/.cursor/projects/<slug>/agent-transcripts/`, Codex `~/.codex/sessions/**` whose `session_meta.cwd` is this repo. A missing host is reported as `not found`; it never fails the command.
|
|
257
|
+
- **What counts:** human turns after the first one in a session (the first is the task), not tool results or system text, at most 600 characters, that correct the agent (`don't`, `never`, `wrong`, `revert`, `why did you`, `jangan`, `kok`, `salah`, `harusnya`, `malah`, `masih … lagi`, …) and have at least 3 content words.
|
|
258
|
+
- **Grouping:** corrections sharing at least 3 content words (and 60% of the shorter one) form one group. Groups seen in `--min-sessions` sessions (default 2) become candidates.
|
|
259
|
+
- **Saved:** `.ai-engineering-loop/transcript-lessons.json` (mode 0600) holds per candidate an id `L-T<hash>`, session and occurrence counts, hosts, last seen, one example with secrets and home paths redacted (at most 200 characters), and a suggested fix. No other transcript text is stored anywhere.
|
|
260
|
+
- **Suggested fix:** a correction that names code (a backticked token or `a.b` call) suggests `learn promote <id> --forbid-api "<token>" --fix … --by …`, plus `--prove <commit>` when `git log -S` finds the commit that introduced it; a test-related one suggests a test; anything else is a judgment call for `lessons.md` or a skill.
|
|
261
|
+
- **Promotion** stays human: `learn promote L-T… ...` works like any lesson. `stats` lists the top three repeated corrections.
|
|
262
|
+
|
|
263
|
+
## 13. Reusable Feature Drivers (C-43)
|
|
264
|
+
|
|
265
|
+
L3 evidence used to be a script written during the Run and thrown away. `ael driver scaffold [--feature <id>] [--surface web|api|cli|launch]` builds one per feature-map row instead, once:
|
|
266
|
+
|
|
267
|
+
- File: `.ai-engineering-loop/drivers/<feature>.mjs` plus `<feature>.md` (what to fill in, which gaps remain).
|
|
268
|
+
- Surface: an endpoint row (`POST /api/...`) gets `api`; a repo with Playwright gets `web`; a package with `bin` gets `cli`; otherwise `launch` (start the app and fetch the page, and the README says what runner is missing).
|
|
269
|
+
- Parts: **launch** (start command from `verification.md` `dev`/`start` or `package.json`, skipped when `AEL_BASE_URL` points at a running app), **drive** (the user steps), **observe** (status, body, screenshot or output into `runs/<AEL_RUN_ID>/evidence/`).
|
|
270
|
+
- `EXPECT` starts as `null`, so an unfilled driver always exits non-zero. Exit 0 means the observed result matched.
|
|
271
|
+
- The scaffold fills an empty `Driver` cell with `node .ai-engineering-loop/drivers/<feature>.mjs`; `review-pack` passes it to reviewers.
|
|
272
|
+
- Re-running never overwrites an edited driver: the new template lands next to it as `<file>.ael-new`.
|
|
273
|
+
- `doctor --harness`: warning `feature-driver` when a `node <file>` Driver points at a missing file; info when an e2e or smoke lane exists and some features have no driver.
|
package/lib/adapter-check.js
CHANGED
|
@@ -81,9 +81,10 @@ function checkAdapter(projectDir, { packageRoot = path.join(__dirname, '..'), ru
|
|
|
81
81
|
if (tool) {
|
|
82
82
|
const result = run(tool.bin, tool.args);
|
|
83
83
|
let detail;
|
|
84
|
-
|
|
84
|
+
const install = tool.bin === 'gh' ? 'https://cli.github.com' : tool.bin === 'glab' ? 'https://gitlab.com/gitlab-org/cli#installation' : `your package manager`;
|
|
85
|
+
if (result.error && result.error.code === 'ENOENT') detail = `${tool.bin} not installed (needed by adapter "${type}"). FIX: install it from ${install}, then \`${tool.bin} auth login\`; without it Stage 8 prints a compare URL instead of opening the PR/MR.`;
|
|
85
86
|
else if (result.error) detail = `${tool.label} failed: ${result.error.message}`;
|
|
86
|
-
else if (result.status !== 0) detail = `${tool.bin} not logged in: \`${tool.label}\` exited ${result.status}
|
|
87
|
+
else if (result.status !== 0) detail = `${tool.bin} not logged in: \`${tool.label}\` exited ${result.status}. FIX: \`${tool.bin} auth login\`.`;
|
|
87
88
|
else detail = `${tool.label} ok`;
|
|
88
89
|
checks.push(check('adapter-auth', !result.error && result.status === 0, detail, 'warn'));
|
|
89
90
|
}
|
package/lib/agent-artifacts.js
CHANGED
|
@@ -139,6 +139,32 @@ function scaffoldArtifact(rootDir, { type, runId } = {}) {
|
|
|
139
139
|
};
|
|
140
140
|
}
|
|
141
141
|
|
|
142
|
+
const GOAL_DRAFT = path.join('.ai-engineering-loop', 'drafts', 'goal.json');
|
|
143
|
+
|
|
144
|
+
function scaffoldGoal(rootDir, { runId } = {}) {
|
|
145
|
+
const run = resolveRun(rootDir, runId);
|
|
146
|
+
const filePath = path.join(rootDir, GOAL_DRAFT);
|
|
147
|
+
const relative = GOAL_DRAFT.split(path.sep).join('/');
|
|
148
|
+
if (fs.existsSync(filePath)) throw artifactError(`Template already exists: ${relative}. It was left unchanged.`, 'ARTIFACT_EXISTS');
|
|
149
|
+
fs.mkdirSync(path.dirname(filePath), { recursive: true });
|
|
150
|
+
const template = {
|
|
151
|
+
_templateOnly: true,
|
|
152
|
+
_howTo: 'Replace every <...>, delete _templateOnly and _howTo, then run the goal draft command in nextCommand.',
|
|
153
|
+
schemaVersion: 1,
|
|
154
|
+
runId: run.runId,
|
|
155
|
+
objective: run.task || '<one sentence: what changes for the user>',
|
|
156
|
+
acceptanceCriteria: [{
|
|
157
|
+
id: 'AC-1',
|
|
158
|
+
statement: '<observable behaviour, e.g. "Export button downloads a CSV of the filtered rows">',
|
|
159
|
+
evidenceRequired: '<what proves it, e.g. "unit test output and a CSV sample">',
|
|
160
|
+
failureCases: ['<what a wrong result looks like, e.g. "CSV ignores the active filter">']
|
|
161
|
+
}],
|
|
162
|
+
outOfScope: ['<what this Run must not touch>']
|
|
163
|
+
};
|
|
164
|
+
fs.writeFileSync(filePath, `${JSON.stringify(template, null, 2)}\n`, { mode: 0o600 });
|
|
165
|
+
return { type: 'goal', runId: run.runId, path: relative, nextCommand: `ai-engineering-loop goal draft --run ${run.runId} --file ${relative} --revision 0` };
|
|
166
|
+
}
|
|
167
|
+
|
|
142
168
|
function resolveArtifactFile(rootDir, requestedPath) {
|
|
143
169
|
if (!requestedPath || path.isAbsolute(requestedPath)) {
|
|
144
170
|
throw artifactError('Artifact path must be repository-relative.', 'UNSAFE_ARTIFACT_PATH');
|
|
@@ -244,6 +270,8 @@ function validateArtifactFile(rootDir, { file, type } = {}) {
|
|
|
244
270
|
}
|
|
245
271
|
|
|
246
272
|
module.exports = {
|
|
273
|
+
GOAL_DRAFT,
|
|
274
|
+
scaffoldGoal,
|
|
247
275
|
ARTIFACT_TYPES,
|
|
248
276
|
scaffoldArtifact,
|
|
249
277
|
validateArtifactFile
|
package/lib/budget.js
CHANGED
|
@@ -251,7 +251,7 @@ function appendPrivateLine(rootDir, filePath, line) {
|
|
|
251
251
|
|
|
252
252
|
// C-24: who spent the tokens, so `stats` can show the verification share
|
|
253
253
|
// ("70% of her daily tokens go into verification", talk 11:46).
|
|
254
|
-
const USAGE_ROLES = Object.freeze(['maker', 'reviewer', 'judge', 'verification', 'other']);
|
|
254
|
+
const USAGE_ROLES = Object.freeze(['maker', 'reviewer', 'judge', 'verification', 'gather', 'other']);
|
|
255
255
|
|
|
256
256
|
function recordTokenUsage(
|
|
257
257
|
rootDir,
|
package/lib/clean-state.js
CHANGED
|
@@ -26,6 +26,21 @@ function untrackedFiles(rootDir) {
|
|
|
26
26
|
}
|
|
27
27
|
}
|
|
28
28
|
|
|
29
|
+
function uncommittedChange(rootDir, run, files) {
|
|
30
|
+
const paths = files.map((file) => file.path).filter((file) => !file.startsWith('.ai-engineering-loop/'));
|
|
31
|
+
if (!paths.length) return [];
|
|
32
|
+
let status = '';
|
|
33
|
+
try {
|
|
34
|
+
status = execFileSync('git', ['status', '--porcelain', '-z', '--untracked-files=all', '--', ...paths], {
|
|
35
|
+
cwd: rootDir, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore']
|
|
36
|
+
});
|
|
37
|
+
} catch {
|
|
38
|
+
return [];
|
|
39
|
+
}
|
|
40
|
+
return [...new Set(status.split('\0').filter((entry) => /^.. /.test(entry)).map((entry) => entry.slice(3)))]
|
|
41
|
+
.filter((file) => paths.includes(file));
|
|
42
|
+
}
|
|
43
|
+
|
|
29
44
|
function templateOnlyArtifacts(rootDir, run) {
|
|
30
45
|
const found = [];
|
|
31
46
|
const dirs = [path.join(runsDir(rootDir), run.runId), path.join(rootDir, '.ai-engineering-loop', 'tasks')];
|
|
@@ -73,6 +88,11 @@ function checkCleanState(rootDir, run, { mode = 'ASSISTED' } = {}) {
|
|
|
73
88
|
for (const artifact of templateOnlyArtifacts(rootDir, run)) {
|
|
74
89
|
errors.push(`${artifact}: still a _templateOnly scaffold. FIX: fill it with observed facts and remove _templateOnly, or delete it.`);
|
|
75
90
|
}
|
|
91
|
+
const pending = uncommittedChange(rootDir, run, files);
|
|
92
|
+
if (pending.length) {
|
|
93
|
+
const list = pending.slice(0, 10).join(' ');
|
|
94
|
+
errors.push(`the reviewed change is not committed (${pending.length} file(s): ${pending.slice(0, 10).join(', ')}${pending.length > 10 ? ', ...' : ''}); the receipt would bind a HEAD without it. FIX: \`git add ${list} && git commit -m "<message>"\`, then rerun \`deliver\`.`);
|
|
95
|
+
}
|
|
76
96
|
const inDiff = new Set(files.map((file) => file.path));
|
|
77
97
|
const strays = untrackedFiles(rootDir).filter((file) => !inDiff.has(file));
|
|
78
98
|
if (strays.length) {
|
package/lib/cli-args.js
CHANGED
|
@@ -24,7 +24,9 @@ const WRITER_COMMANDS = Object.freeze({
|
|
|
24
24
|
valued: ['--host', '--model', '--scenario', '--repeat', '--bin', '--mode', '--timeout', '--host-arg', '--without'],
|
|
25
25
|
positionals: []
|
|
26
26
|
},
|
|
27
|
-
worktree: { flags: ['--json', '--yes'], valued: [], positionals: ['prune'] },
|
|
27
|
+
worktree: { flags: ['--json', '--yes', '--audit', '--include-scratch'], valued: [], positionals: ['prune'] },
|
|
28
|
+
pr: { flags: ['--json'], valued: ['--run', '--branch', '--pr'], positionals: ['status'] },
|
|
29
|
+
driver: { flags: ['--json'], valued: ['--feature', '--surface'], positionals: ['scaffold'] },
|
|
28
30
|
safety: { flags: ['--json', '--live'], valued: ['--run', '--fact', '--cmd', '--level'], positionals: ['record'] },
|
|
29
31
|
measurement: { flags: ['--json'], valued: ['--run', '--ac', '--runs', '--spread', '--effect', '--limiter'], positionals: ['record'] },
|
|
30
32
|
recap: { flags: ['--json', '--open'], valued: ['--days', '--for', '--projects', '--out', '--now', '--lang'], positionals: [] },
|
|
@@ -34,7 +36,8 @@ const WRITER_COMMANDS = Object.freeze({
|
|
|
34
36
|
verify: { flags: ['--json', '--serial', '--shell', '--related', '--final', '--fresh', '--baseline'], valued: ['--run', '--cmd', '--timeout-ms'], positionals: [] },
|
|
35
37
|
quick: { flags: ['--json', '--serial', '--shell'], valued: ['--run', '--cmd', '--timeout-ms', '--mode'], positionals: null },
|
|
36
38
|
review: { flags: ['--json'], valued: ['--run', '--child-id', '--file'], positionals: ['ingest'] },
|
|
37
|
-
|
|
39
|
+
sources: { flags: ['--json'], valued: ['--run', '--source', '--ref', '--line'], positionals: ['refresh', 'show', 'record', 'hint'] },
|
|
40
|
+
learn: { flags: ['--json', '--dry-run', '--prune', '--no-shell', '--transcripts'], valued: ['--max-age-runs', '--check', '--fix', '--why', '--by', '--scope', '--forbid-import', '--forbid-api', '--except', '--prove', '--since', '--host', '--min-sessions'], positionals: null },
|
|
38
41
|
guard: { flags: ['--json'], valued: ['--run', '--tool', '--input', '--path', '--command', '--hook'], positionals: ['check'] },
|
|
39
42
|
hooks: { flags: ['--json'], valued: ['--host'], positionals: ['install', 'uninstall', 'status'] },
|
|
40
43
|
impact: { flags: ['--json', '--force'], valued: ['--run', '--by', '--reason', '--allow', '--remove', '--limit'], positionals: ['map', 'show', 'confirm', 'skip', 'drift'] },
|
package/lib/docs.js
CHANGED
|
@@ -75,7 +75,8 @@ function readDoc(name, { section = null, root = packageRoot() } = {}) {
|
|
|
75
75
|
if (!section) return { ...doc, text };
|
|
76
76
|
const part = extractSection(text, section);
|
|
77
77
|
if (part == null) {
|
|
78
|
-
const
|
|
78
|
+
const headings = [...text.matchAll(/^#{2,3}\s+(.+)$/gm)].map((match) => match[1].trim());
|
|
79
|
+
const err = new Error(`Section "${section}" not found in ${doc.rel}. Sections: ${headings.join('; ')}`);
|
|
79
80
|
err.code = 'UNKNOWN_SECTION';
|
|
80
81
|
throw err;
|
|
81
82
|
}
|
package/lib/doctor.js
CHANGED
|
@@ -51,6 +51,31 @@ function check(id, passed, detail) {
|
|
|
51
51
|
return { id, passed: Boolean(passed), detail };
|
|
52
52
|
}
|
|
53
53
|
|
|
54
|
+
function machineChecks(rootDir, { projectDir, hostSkills = null, run } = {}) {
|
|
55
|
+
const checks = [];
|
|
56
|
+
const nodeMajor = Number(process.versions.node.split('.')[0]);
|
|
57
|
+
checks.push(check('node-version', nodeMajor >= 18, nodeMajor >= 18 ? `Node ${process.versions.node}` : `Node ${process.versions.node}; required >=18. FIX: install Node 18 or newer (https://nodejs.org or \`mise use node@20\`).`));
|
|
58
|
+
const { gitReadiness } = require('./git-readiness.js');
|
|
59
|
+
const git = gitReadiness(projectDir || process.cwd());
|
|
60
|
+
if (git.code === 'GIT_MISSING') checks.push(check('git', false, `${git.message}. FIX: ${git.fix}`));
|
|
61
|
+
else if (!git.ok) checks.push({ ...check('git', false, `${git.message}. FIX: ${git.fix}`), level: git.code === 'GIT_NOT_A_REPO' ? 'warn' : undefined });
|
|
62
|
+
else checks.push(check('git', true, 'git installed, repository has a commit'));
|
|
63
|
+
for (const warning of git.warnings || []) checks.push({ ...check('git-identity', false, warning), level: 'warn' });
|
|
64
|
+
if (git.ok && !(git.warnings || []).length) checks.push(check('git-identity', true, 'user.name and user.email set'));
|
|
65
|
+
if (hostSkills) {
|
|
66
|
+
checks.push(hostSkills.installed
|
|
67
|
+
? check('agent-skill', !hostSkills.stale, hostSkills.stale ? `${hostSkills.staleFiles} skill file(s) behind. FIX: \`ael sync-hosts\`, then start a new agent session.` : 'ael skill installed and current')
|
|
68
|
+
: { ...check('agent-skill', false, 'no coding agent on this machine has the ael skill. FIX: `ael setup`, then start a new agent session.'), level: 'warn' });
|
|
69
|
+
if (hostSkills.installed && hostSkills.stale) checks[checks.length - 1].level = 'warn';
|
|
70
|
+
}
|
|
71
|
+
if (projectDir && fs.existsSync(path.join(projectDir, '.ai-engineering-loop'))) {
|
|
72
|
+
checks.push(...checkAdapter(projectDir, { packageRoot: rootDir, ...(run ? { run } : {}) }));
|
|
73
|
+
} else if (projectDir) {
|
|
74
|
+
checks.push({ ...check('project', false, 'no .ai-engineering-loop/ here. FIX: `ael init` in your project.'), level: 'warn' });
|
|
75
|
+
}
|
|
76
|
+
return { ok: checks.every((item) => item.passed || item.level === 'warn'), checks };
|
|
77
|
+
}
|
|
78
|
+
|
|
54
79
|
function runDoctor(rootDir = path.join(__dirname, '..'), { projectDir = null, run } = {}) {
|
|
55
80
|
const checks = [];
|
|
56
81
|
const nodeMajor = Number(process.versions.node.split('.')[0]);
|
|
@@ -161,5 +186,6 @@ function runDoctor(rootDir = path.join(__dirname, '..'), { projectDir = null, ru
|
|
|
161
186
|
module.exports = {
|
|
162
187
|
REQUIRED_HOST_ASSETS,
|
|
163
188
|
REQUIRED_SCHEMAS,
|
|
189
|
+
machineChecks,
|
|
164
190
|
runDoctor
|
|
165
191
|
};
|
|
@@ -0,0 +1,289 @@
|
|
|
1
|
+
'use strict';
|
|
2
|
+
|
|
3
|
+
const fs = require('fs');
|
|
4
|
+
const path = require('path');
|
|
5
|
+
const { FEATURE_MAP_FILE, loadFeatureMap } = require('./feature-map.js');
|
|
6
|
+
|
|
7
|
+
const DRIVER_DIR = path.join('.ai-engineering-loop', 'drivers');
|
|
8
|
+
const SURFACES = ['web', 'api', 'cli', 'launch'];
|
|
9
|
+
|
|
10
|
+
const fail = (message, code = 'INVALID_USAGE') => Object.assign(new Error(message), { code });
|
|
11
|
+
|
|
12
|
+
function readJson(file) {
|
|
13
|
+
try {
|
|
14
|
+
return JSON.parse(fs.readFileSync(file, 'utf8'));
|
|
15
|
+
} catch {
|
|
16
|
+
return null;
|
|
17
|
+
}
|
|
18
|
+
}
|
|
19
|
+
|
|
20
|
+
function projectFacts(rootDir) {
|
|
21
|
+
const pkg = readJson(path.join(rootDir, 'package.json')) || {};
|
|
22
|
+
const deps = { ...(pkg.dependencies || {}), ...(pkg.devDependencies || {}) };
|
|
23
|
+
let verification = '';
|
|
24
|
+
try {
|
|
25
|
+
verification = fs.readFileSync(path.join(rootDir, '.ai-engineering-loop', 'verification.md'), 'utf8');
|
|
26
|
+
} catch {
|
|
27
|
+
verification = '';
|
|
28
|
+
}
|
|
29
|
+
const fromVerification = (key) => (verification.match(new RegExp(`\\*\\*${key}\\*\\*:\\s*\`([^\`]+)\``, 'i')) || [])[1] || null;
|
|
30
|
+
const scripts = pkg.scripts || {};
|
|
31
|
+
const startCommand = fromVerification('dev') || fromVerification('start') || (scripts.dev ? 'npm run dev' : scripts.start ? 'npm start' : null);
|
|
32
|
+
return {
|
|
33
|
+
playwright: Boolean(deps['@playwright/test'] || deps.playwright),
|
|
34
|
+
bin: Boolean(pkg.bin),
|
|
35
|
+
startCommand,
|
|
36
|
+
baseUrl: fromVerification('base_url') || 'http://localhost:3000'
|
|
37
|
+
};
|
|
38
|
+
}
|
|
39
|
+
|
|
40
|
+
function detectSurface(entry, facts) {
|
|
41
|
+
if (/^(GET|POST|PUT|PATCH|DELETE)\s|^\/api\//i.test(entry.where)) return 'api';
|
|
42
|
+
if (facts.playwright) return 'web';
|
|
43
|
+
if (facts.bin) return 'cli';
|
|
44
|
+
return 'launch';
|
|
45
|
+
}
|
|
46
|
+
|
|
47
|
+
const routeOf = (where) => {
|
|
48
|
+
const match = String(where).match(/^(GET|POST|PUT|PATCH|DELETE)\s+(\S+)/i);
|
|
49
|
+
if (match) return { method: match[1].toUpperCase(), path: match[2] };
|
|
50
|
+
const slash = String(where).match(/(\/[\w\-/.:]*)/);
|
|
51
|
+
return { method: 'GET', path: slash ? slash[1] : '/' };
|
|
52
|
+
};
|
|
53
|
+
|
|
54
|
+
function driverSource(entry, surface, facts) {
|
|
55
|
+
const header = `const FEATURE = ${JSON.stringify(entry.id)};
|
|
56
|
+
const WHERE = ${JSON.stringify(entry.where)};
|
|
57
|
+
const HOW = ${JSON.stringify(entry.how)};
|
|
58
|
+
const BASE_URL = process.env.AEL_BASE_URL || ${JSON.stringify(facts.baseUrl)};
|
|
59
|
+
const START = process.env.AEL_START_COMMAND || ${JSON.stringify(facts.startCommand)};
|
|
60
|
+
const EXPECT = null;
|
|
61
|
+
`;
|
|
62
|
+
const common = `import { spawn } from 'node:child_process';
|
|
63
|
+
import fs from 'node:fs';
|
|
64
|
+
import path from 'node:path';
|
|
65
|
+
|
|
66
|
+
${header}
|
|
67
|
+
function evidenceDir() {
|
|
68
|
+
let runId = process.env.AEL_RUN_ID;
|
|
69
|
+
if (!runId) {
|
|
70
|
+
try {
|
|
71
|
+
runId = JSON.parse(fs.readFileSync('.ai-engineering-loop/runs/current.json', 'utf8')).runId;
|
|
72
|
+
} catch {
|
|
73
|
+
runId = 'no-run';
|
|
74
|
+
}
|
|
75
|
+
}
|
|
76
|
+
const dir = path.join('.ai-engineering-loop', 'runs', runId, 'evidence');
|
|
77
|
+
fs.mkdirSync(dir, { recursive: true });
|
|
78
|
+
return dir;
|
|
79
|
+
}
|
|
80
|
+
|
|
81
|
+
async function ready(url, timeoutMs = 60000) {
|
|
82
|
+
const until = Date.now() + timeoutMs;
|
|
83
|
+
while (Date.now() < until) {
|
|
84
|
+
try {
|
|
85
|
+
const response = await fetch(url);
|
|
86
|
+
if (response.status < 500) return true;
|
|
87
|
+
} catch {
|
|
88
|
+
await new Promise((resolve) => setTimeout(resolve, 1000));
|
|
89
|
+
}
|
|
90
|
+
}
|
|
91
|
+
return false;
|
|
92
|
+
}
|
|
93
|
+
|
|
94
|
+
async function launch() {
|
|
95
|
+
if (process.env.AEL_BASE_URL) return null;
|
|
96
|
+
if (!START) throw new Error('No start command: set AEL_START_COMMAND or add - **dev**: \`<command>\` to .ai-engineering-loop/verification.md');
|
|
97
|
+
const child = spawn(START, { shell: true, stdio: 'ignore', detached: process.platform !== 'win32' });
|
|
98
|
+
if (!(await ready(BASE_URL))) {
|
|
99
|
+
child.kill();
|
|
100
|
+
throw new Error(\`App did not answer at \${BASE_URL} within 60s\`);
|
|
101
|
+
}
|
|
102
|
+
return child;
|
|
103
|
+
}
|
|
104
|
+
|
|
105
|
+
function finish(child, ok, message) {
|
|
106
|
+
if (child) {
|
|
107
|
+
try {
|
|
108
|
+
if (process.platform === 'win32') child.kill();
|
|
109
|
+
else process.kill(-child.pid);
|
|
110
|
+
} catch {
|
|
111
|
+
child.kill();
|
|
112
|
+
}
|
|
113
|
+
}
|
|
114
|
+
console.log(\`\${ok ? 'PASS' : 'FAIL'} \${FEATURE}: \${message}\`);
|
|
115
|
+
process.exit(ok ? 0 : 1);
|
|
116
|
+
}
|
|
117
|
+
`;
|
|
118
|
+
if (surface === 'web') {
|
|
119
|
+
return `${common}
|
|
120
|
+
const { chromium } = await import('playwright').catch(() => import('@playwright/test'));
|
|
121
|
+
|
|
122
|
+
const child = await launch().catch((error) => finish(null, false, error.message));
|
|
123
|
+
const browser = await chromium.launch();
|
|
124
|
+
const page = await browser.newPage();
|
|
125
|
+
try {
|
|
126
|
+
await page.goto(new URL(${JSON.stringify(routeOf(entry.where).path)}, BASE_URL).toString());
|
|
127
|
+
await drive(page);
|
|
128
|
+
const shot = path.join(evidenceDir(), \`\${FEATURE}-\${Date.now()}.png\`);
|
|
129
|
+
await page.screenshot({ path: shot, fullPage: true });
|
|
130
|
+
const ok = await observe(page);
|
|
131
|
+
await browser.close();
|
|
132
|
+
finish(child, ok, ok ? \`matches EXPECT; screenshot \${shot}\` : \`EXPECT not met; screenshot \${shot}\`);
|
|
133
|
+
} catch (error) {
|
|
134
|
+
await browser.close();
|
|
135
|
+
finish(child, false, error.message);
|
|
136
|
+
}
|
|
137
|
+
|
|
138
|
+
async function drive(page) {
|
|
139
|
+
throw new Error(\`Write the user steps for "\${HOW}" in drive() of this file\`);
|
|
140
|
+
}
|
|
141
|
+
|
|
142
|
+
async function observe(page) {
|
|
143
|
+
if (EXPECT == null) throw new Error('Set EXPECT (the text or state that proves the feature works) and check it in observe()');
|
|
144
|
+
return (await page.content()).includes(EXPECT);
|
|
145
|
+
}
|
|
146
|
+
`;
|
|
147
|
+
}
|
|
148
|
+
if (surface === 'api') {
|
|
149
|
+
const route = routeOf(entry.where);
|
|
150
|
+
return `${common}
|
|
151
|
+
const child = await launch().catch((error) => finish(null, false, error.message));
|
|
152
|
+
try {
|
|
153
|
+
const response = await fetch(new URL(${JSON.stringify(route.path)}, BASE_URL), { method: ${JSON.stringify(route.method)}, headers: { 'content-type': 'application/json' }, ...request() });
|
|
154
|
+
const body = await response.text();
|
|
155
|
+
const file = path.join(evidenceDir(), \`\${FEATURE}-\${Date.now()}.json\`);
|
|
156
|
+
fs.writeFileSync(file, JSON.stringify({ status: response.status, body }, null, 2));
|
|
157
|
+
const ok = observe(response.status, body);
|
|
158
|
+
finish(child, ok, \`\${response.status}; evidence \${file}\`);
|
|
159
|
+
} catch (error) {
|
|
160
|
+
finish(child, false, error.message);
|
|
161
|
+
}
|
|
162
|
+
|
|
163
|
+
function request() {
|
|
164
|
+
return {};
|
|
165
|
+
}
|
|
166
|
+
|
|
167
|
+
function observe(status, body) {
|
|
168
|
+
if (EXPECT == null) throw new Error('Set EXPECT (status code or a string the body must contain) and check it in observe()');
|
|
169
|
+
return typeof EXPECT === 'number' ? status === EXPECT : body.includes(EXPECT);
|
|
170
|
+
}
|
|
171
|
+
`;
|
|
172
|
+
}
|
|
173
|
+
if (surface === 'cli') {
|
|
174
|
+
return `import { spawnSync } from 'node:child_process';
|
|
175
|
+
import fs from 'node:fs';
|
|
176
|
+
import path from 'node:path';
|
|
177
|
+
|
|
178
|
+
${header}
|
|
179
|
+
const COMMAND = null;
|
|
180
|
+
|
|
181
|
+
if (COMMAND == null || EXPECT == null) {
|
|
182
|
+
console.log(\`FAIL \${FEATURE}: set COMMAND (what the user runs for "\${HOW}") and EXPECT (text the output must contain)\`);
|
|
183
|
+
process.exit(1);
|
|
184
|
+
}
|
|
185
|
+
const result = spawnSync(COMMAND, { shell: true, encoding: 'utf8' });
|
|
186
|
+
const output = \`\${result.stdout || ''}\${result.stderr || ''}\`;
|
|
187
|
+
let runId = process.env.AEL_RUN_ID || 'no-run';
|
|
188
|
+
const dir = path.join('.ai-engineering-loop', 'runs', runId, 'evidence');
|
|
189
|
+
fs.mkdirSync(dir, { recursive: true });
|
|
190
|
+
const file = path.join(dir, \`\${FEATURE}-\${Date.now()}.txt\`);
|
|
191
|
+
fs.writeFileSync(file, \`$ \${COMMAND}\\nexit \${result.status}\\n\${output}\`);
|
|
192
|
+
const ok = result.status === 0 && output.includes(EXPECT);
|
|
193
|
+
console.log(\`\${ok ? 'PASS' : 'FAIL'} \${FEATURE}: exit \${result.status}; evidence \${file}\`);
|
|
194
|
+
process.exit(ok ? 0 : 1);
|
|
195
|
+
`;
|
|
196
|
+
}
|
|
197
|
+
return `${common}
|
|
198
|
+
const child = await launch().catch((error) => finish(null, false, error.message));
|
|
199
|
+
try {
|
|
200
|
+
const response = await fetch(new URL(${JSON.stringify(routeOf(entry.where).path)}, BASE_URL));
|
|
201
|
+
const body = await response.text();
|
|
202
|
+
const file = path.join(evidenceDir(), \`\${FEATURE}-\${Date.now()}.html\`);
|
|
203
|
+
fs.writeFileSync(file, body);
|
|
204
|
+
if (EXPECT == null) finish(child, false, \`app answered \${response.status}; set EXPECT and add a browser or API runner to drive "\${HOW}"\`);
|
|
205
|
+
finish(child, body.includes(EXPECT), \`\${response.status}; evidence \${file}\`);
|
|
206
|
+
} catch (error) {
|
|
207
|
+
finish(child, false, error.message);
|
|
208
|
+
}
|
|
209
|
+
`;
|
|
210
|
+
}
|
|
211
|
+
|
|
212
|
+
function readme(entry, surface, facts, relative) {
|
|
213
|
+
const gaps = [];
|
|
214
|
+
if (!facts.startCommand) gaps.push('No start command found: add `- **dev**: `<command>`` to `.ai-engineering-loop/verification.md`, or set `AEL_START_COMMAND`.');
|
|
215
|
+
if (surface === 'launch') gaps.push('No browser or API runner found: the driver only launches the app and fetches the page. Add Playwright (`npm i -D playwright`) and re-scaffold with `--surface web`, or use `--surface api`.');
|
|
216
|
+
return `# Driver: ${entry.id}
|
|
217
|
+
|
|
218
|
+
Surface: ${surface}. Where: ${entry.where}. How to reach: ${entry.how}.
|
|
219
|
+
|
|
220
|
+
Run: \`node ${relative}\` (exit 0 only when the observed result matches \`EXPECT\`). It starts the app with \`${facts.startCommand || '<none>'}\` unless \`AEL_BASE_URL\` points at a running one, and writes evidence to \`.ai-engineering-loop/runs/<runId>/evidence/\`.
|
|
221
|
+
|
|
222
|
+
Fill in before use:
|
|
223
|
+
- \`EXPECT\`: the text, state or status that proves the feature works.
|
|
224
|
+
- the user steps (${surface === 'web' ? '`drive()`' : surface === 'api' ? '`request()`' : surface === 'cli' ? '`COMMAND`' : 'not available for this surface'}).
|
|
225
|
+
${gaps.length ? `\nGaps:\n${gaps.map((gap) => `- ${gap}`).join('\n')}\n` : ''}`;
|
|
226
|
+
}
|
|
227
|
+
|
|
228
|
+
function setDriverCell(rootDir, featureId, command) {
|
|
229
|
+
const file = path.join(rootDir, FEATURE_MAP_FILE);
|
|
230
|
+
const lines = fs.readFileSync(file, 'utf8').split('\n');
|
|
231
|
+
let changed = false;
|
|
232
|
+
const next = lines.map((raw) => {
|
|
233
|
+
const line = raw.trim();
|
|
234
|
+
if (!line.startsWith('|') || /^\|\s*-/.test(line)) return raw;
|
|
235
|
+
const cells = line.split('|').slice(1, -1).map((cell) => cell.trim());
|
|
236
|
+
if (cells[0] !== featureId) return raw;
|
|
237
|
+
while (cells.length < 5) cells.push('');
|
|
238
|
+
if (cells[4]) return raw;
|
|
239
|
+
cells[4] = `\`${command}\``;
|
|
240
|
+
changed = true;
|
|
241
|
+
return `| ${cells.join(' | ')} |`;
|
|
242
|
+
});
|
|
243
|
+
if (changed) fs.writeFileSync(file, next.join('\n'));
|
|
244
|
+
return changed;
|
|
245
|
+
}
|
|
246
|
+
|
|
247
|
+
function scaffoldDriver(rootDir, { feature = null, surface = null } = {}) {
|
|
248
|
+
if (surface && !SURFACES.includes(surface)) throw fail(`--surface must be ${SURFACES.join(', ')}`);
|
|
249
|
+
const entries = loadFeatureMap(rootDir);
|
|
250
|
+
if (!entries.length) throw fail('No feature map yet: add rows to .ai-engineering-loop/feature-map.md (Feature | Where | Paths | How to reach | Driver) first', 'FEATURE_MAP_MISSING');
|
|
251
|
+
const targets = feature ? entries.filter((entry) => entry.id === feature) : entries.filter((entry) => !entry.driver);
|
|
252
|
+
if (feature && !targets.length) throw fail(`No feature "${feature}" in the feature map; known: ${entries.map((entry) => entry.id).join(', ')}`, 'NOT_FOUND');
|
|
253
|
+
const facts = projectFacts(rootDir);
|
|
254
|
+
const results = [];
|
|
255
|
+
for (const entry of targets) {
|
|
256
|
+
const kind = surface || detectSurface(entry, facts);
|
|
257
|
+
const slug = entry.id.replace(/[^\w.-]+/g, '-');
|
|
258
|
+
const relative = path.posix.join('.ai-engineering-loop', 'drivers', `${slug}.mjs`);
|
|
259
|
+
const file = path.join(rootDir, relative);
|
|
260
|
+
const source = driverSource(entry, kind, facts);
|
|
261
|
+
fs.mkdirSync(path.dirname(file), { recursive: true });
|
|
262
|
+
let written = relative;
|
|
263
|
+
if (fs.existsSync(file) && fs.readFileSync(file, 'utf8') !== source) {
|
|
264
|
+
written = `${relative}.ael-new`;
|
|
265
|
+
fs.writeFileSync(path.join(rootDir, written), source);
|
|
266
|
+
} else if (!fs.existsSync(file)) {
|
|
267
|
+
fs.writeFileSync(file, source);
|
|
268
|
+
fs.writeFileSync(path.join(rootDir, DRIVER_DIR, `${slug}.md`), readme(entry, kind, facts, relative));
|
|
269
|
+
} else {
|
|
270
|
+
written = null;
|
|
271
|
+
}
|
|
272
|
+
const command = `node ${relative}`;
|
|
273
|
+
const mapped = setDriverCell(rootDir, entry.id, command);
|
|
274
|
+
results.push({ feature: entry.id, surface: kind, file: relative, written, featureMapUpdated: mapped, startCommand: facts.startCommand, gaps: [...(facts.startCommand ? [] : ['start command']), ...(kind === 'launch' ? ['browser or API runner'] : [])] });
|
|
275
|
+
}
|
|
276
|
+
return results;
|
|
277
|
+
}
|
|
278
|
+
|
|
279
|
+
function driverProblems(rootDir) {
|
|
280
|
+
const problems = [];
|
|
281
|
+
for (const entry of loadFeatureMap(rootDir)) {
|
|
282
|
+
if (!entry.driver) continue;
|
|
283
|
+
const local = String(entry.driver).match(/^node\s+(\S+)/);
|
|
284
|
+
if (local && !fs.existsSync(path.join(rootDir, local[1]))) problems.push({ feature: entry.id, problem: `driver file ${local[1]} is missing` });
|
|
285
|
+
}
|
|
286
|
+
return problems;
|
|
287
|
+
}
|
|
288
|
+
|
|
289
|
+
module.exports = { SURFACES, driverProblems, scaffoldDriver };
|
package/lib/gates.js
CHANGED
|
@@ -89,7 +89,7 @@ function readJsonArtifact(rootDir, runId, fileName) {
|
|
|
89
89
|
try {
|
|
90
90
|
value = JSON.parse(fs.readFileSync(filePath, 'utf8'));
|
|
91
91
|
} catch (cause) {
|
|
92
|
-
throw gateError(`Missing or invalid ${fileName}: ${cause.message}`, [], { why: 'Every gate reads its artifact from the Run directory; without it there is nothing to check.', fix: `Write ${fileName} in the Run directory
|
|
92
|
+
throw gateError(`Missing or invalid ${fileName}: ${cause.message}`, [], { why: 'Every gate reads its artifact from the Run directory; without it there is nothing to check.', fix: `Write ${fileName} in the Run directory, then retry the gate. Templates: \`scaffold goal\` (then \`goal draft\`), \`scaffold verification|findings|delivery\`.` });
|
|
93
93
|
}
|
|
94
94
|
return { filePath, value };
|
|
95
95
|
}
|
|
@@ -169,6 +169,7 @@ function validateGoalContract(contract) {
|
|
|
169
169
|
}
|
|
170
170
|
errors.push(...validateGoalScope(contract.scope));
|
|
171
171
|
errors.push(...require('./design-ref.js').validateDesignRef(contract.designRef));
|
|
172
|
+
errors.push(...require('./provenance.js').validateStatements(contract.statements));
|
|
172
173
|
return { valid: errors.length === 0, errors };
|
|
173
174
|
}
|
|
174
175
|
|
|
@@ -571,6 +572,7 @@ function applyGate(rootDir, gate, { runId, transitionOptions = {} } = {}) {
|
|
|
571
572
|
requireRunMetadata(value, run, 'goal contract');
|
|
572
573
|
const check = validateGoalContract(value);
|
|
573
574
|
if (!check.valid) throw gateError('Goal Contract gate failed', check.errors, { why: 'Work may not start until acceptance criteria, evidence and failure cases are explicit.', fix: 'Fix the listed Goal Contract fields (every AC needs statement, evidenceRequired, failureCases), then retry `gate goal`.' });
|
|
575
|
+
if (Array.isArray(value.statements)) require('./provenance.js').writeProvenance(rootDir, run.runId, value);
|
|
574
576
|
const frozen = transitionRun(rootDir, run.runId, RUN_STATES.GOAL_FROZEN, {
|
|
575
577
|
gate,
|
|
576
578
|
artifacts: { goalContract: descriptor(rootDir, filePath) },
|