ai-engineering-loop 2.14.0 → 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 +31 -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 +447 -40
- 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/lib/verification-lanes.js +1 -2
- package/package.json +1 -1
- package/schemas/goal-contract.schema.json +13 -0
- package/README.npm.md +0 -104
- package/docs/images/ael-hero.svg +0 -19
- package/docs/images/engineering-loop-overview.svg +0 -114
- package/docs/images/social-preview.png +0 -0
- package/docs/images/studio-hero-orange.svg +0 -136
- package/docs/images/studio-hero.svg +0 -136
|
@@ -0,0 +1,33 @@
|
|
|
1
|
+
# Coordinating agents
|
|
2
|
+
|
|
3
|
+
AEL does not start agents, rank them, or pass work between them. The human starts each agent in the host they already use. Every host runs the same commands.
|
|
4
|
+
|
|
5
|
+
## One checkout, one unfinished Run
|
|
6
|
+
|
|
7
|
+
A second task in the same checkout returns `RUN_CONFLICT` (exit 3). The human chooses a worktree, resume, or abandon. The agent does not choose. See `docs run-isolation`.
|
|
8
|
+
|
|
9
|
+
## More than one agent
|
|
10
|
+
|
|
11
|
+
Each extra task gets its own worktree:
|
|
12
|
+
|
|
13
|
+
```bash
|
|
14
|
+
npx ai-engineering-loop run --worktree "<task>"
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
Work only in the printed path. Do not edit another agent's worktree. Do not merge another agent's branch.
|
|
18
|
+
|
|
19
|
+
## Stacked pull requests
|
|
20
|
+
|
|
21
|
+
The human names the branch the next task sits on. That branch is a commit already in this repository. AEL does not fetch.
|
|
22
|
+
|
|
23
|
+
```bash
|
|
24
|
+
npx ai-engineering-loop run --worktree --base <branch> "<task>"
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
This creates `ael/<slug>-<id>` from `<branch>` and records `baseRef` on the worktree. `--base` without `--worktree` is refused, because switching the current checkout would mix Runs.
|
|
28
|
+
|
|
29
|
+
The human orders the stack and merges it. An agent does not merge.
|
|
30
|
+
|
|
31
|
+
## What this is not
|
|
32
|
+
|
|
33
|
+
No coordinator process. No host-specific queue. No second model and no arena. The same commands work in every host.
|
package/core/garden.md
ADDED
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
# Garden
|
|
2
|
+
|
|
3
|
+
`refresh --garden` reports stale project knowledge. It writes nothing unless you pass `--yes`. It never deletes a Run.
|
|
4
|
+
|
|
5
|
+
```bash
|
|
6
|
+
npx ai-engineering-loop refresh --garden
|
|
7
|
+
npx ai-engineering-loop refresh --garden --yes
|
|
8
|
+
```
|
|
9
|
+
|
|
10
|
+
## What it looks at
|
|
11
|
+
|
|
12
|
+
| Knowledge | Stale when | `--yes` does |
|
|
13
|
+
|---|---|---|
|
|
14
|
+
| `.ai-engineering-loop/learnings.json` | Every listed file is gone, or the lesson has not been seen in the last 20 Runs | Removes those entries and records them under `suppressed`. Other lessons stay. Ledgers are not re-mined. |
|
|
15
|
+
| `.ai-engineering-loop/feature-map.md` | Every path on a row matches no tracked file | Moves that row under `## Stale (garden)`. A row that still has a live path is only reported. The previous file is kept as `feature-map.md.ael-backup` the first time. |
|
|
16
|
+
| `runs/<id>/` | Unfinished and idle 7 days or more, or finished and 30 days or older | Nothing. Unfinished Runs are listed so a human can abandon one. Finished Runs stay on disk. |
|
|
17
|
+
|
|
18
|
+
`--garden` does not reconcile context. That remains `refresh` and `refresh --non-destructive`. Passing `--garden` together with `--non-destructive` is refused.
|
package/core/goal-contract.md
CHANGED
|
@@ -86,6 +86,9 @@ Each AC is one row that can **fail**. Happy path alone is not a contract (`polic
|
|
|
86
86
|
4. **Chat is not the contract**:
|
|
87
87
|
- Parent-transcript `setuju` does not freeze AC.
|
|
88
88
|
- Every user-visible grill decision (order of pages, enable flags, layout) MUST appear as AC-1..N in the contract file before Maker starts.
|
|
89
|
+
- `goal freeze --by <name>` records the person who agreed. It refuses an empty name, `agent`, `ael-agent`, and a model id (`deepseek-flash`). `studio-user` is a human click in Studio and still counts.
|
|
90
|
+
- A cancelled or unanswered question is not agreement. Stop and wait. Do not freeze.
|
|
91
|
+
- `goal draft` returns `repoRoot`, the git toplevel. Draft only when that path is the project the human named.
|
|
89
92
|
|
|
90
93
|
---
|
|
91
94
|
|
|
@@ -208,6 +211,19 @@ Then ask the human: freeze, another view, or turn `?` cells, hotspots and side e
|
|
|
208
211
|
|
|
209
212
|
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
213
|
|
|
214
|
+
## Restate
|
|
215
|
+
|
|
216
|
+
Before acceptance criteria, write the problem in your own words. `goal draft` refuses a Goal whose `restatement` is missing or blank, so a freeze cannot lock the method a human suggested.
|
|
217
|
+
|
|
218
|
+
| Field | What to write | Leave out |
|
|
219
|
+
|---|---|---|
|
|
220
|
+
| `problem` | What is wrong or missing, as you understand it | Steps, files, libraries, the human's how |
|
|
221
|
+
| `doneWhen` | The outcome that means this is done | The implementation |
|
|
222
|
+
| `failIf` | What is still wrong when that outcome is missed | A procedure |
|
|
223
|
+
| `unknowns` | What you cannot tell yet, or `None.` | Guesses stated as facts |
|
|
224
|
+
|
|
225
|
+
`goal.md` prints this block first, under Restate.
|
|
226
|
+
|
|
211
227
|
## JSON example for `goal draft` (C-50)
|
|
212
228
|
|
|
213
229
|
`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.
|
|
@@ -217,6 +233,12 @@ The receipt lists `--evidence AC-N=<https-url>` links first, typed as video, scr
|
|
|
217
233
|
"schemaVersion": 1,
|
|
218
234
|
"runId": "<runId>",
|
|
219
235
|
"objective": "Users can export the filtered report as CSV",
|
|
236
|
+
"restatement": {
|
|
237
|
+
"problem": "People cannot take the filtered rows out of the report.",
|
|
238
|
+
"doneWhen": "Export saves a CSV of only the filtered rows.",
|
|
239
|
+
"failIf": "The CSV still contains rows the filter hid.",
|
|
240
|
+
"unknowns": "None."
|
|
241
|
+
},
|
|
220
242
|
"acceptanceCriteria": [
|
|
221
243
|
{
|
|
222
244
|
"id": "AC-1",
|
|
@@ -246,5 +268,5 @@ The Goal JSON is for the tools; people read `RUN_DIR/goal.md` (`goal show --huma
|
|
|
246
268
|
|
|
247
269
|
`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
270
|
|
|
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.
|
|
271
|
+
`goal.md` has these sections: Restate (Problem, Done when, Fail if, Unknowns), 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
272
|
|
|
@@ -0,0 +1,62 @@
|
|
|
1
|
+
# Overnight contract
|
|
2
|
+
|
|
3
|
+
An overnight run is an `UNATTENDED` Run the human started and then left. The agent may keep working only inside this contract. `overnight check` recomputes the result from Run files. A note the agent wrote about itself does not count.
|
|
4
|
+
|
|
5
|
+
This is not a new mode. Enable unattended the same way as today (`docs runtime-safety`):
|
|
6
|
+
|
|
7
|
+
```bash
|
|
8
|
+
npx ai-engineering-loop policy set --allow-unattended true
|
|
9
|
+
npx ai-engineering-loop run --mode unattended "<task>"
|
|
10
|
+
```
|
|
11
|
+
|
|
12
|
+
The Goal is still frozen by the human before the agent is left alone. Delivery still waits for that person.
|
|
13
|
+
|
|
14
|
+
## What the agent may do
|
|
15
|
+
|
|
16
|
+
- Continue a Goal the human already froze.
|
|
17
|
+
- Edit only inside that frozen scope, in the sandbox worktree (`sandbox create`).
|
|
18
|
+
- Run verify, Devil's Advocate, and Judge, inside the recipe's iteration cap and the token budget.
|
|
19
|
+
- Record evidence under `runs/<id>/`.
|
|
20
|
+
|
|
21
|
+
## What the agent must not do
|
|
22
|
+
|
|
23
|
+
- Freeze, unfreeze, or edit the Goal.
|
|
24
|
+
- Deliver, approve, or merge.
|
|
25
|
+
- Force-push, `git reset --hard`, or `git clean -fd`.
|
|
26
|
+
- Widen scope, change verification config, or add a dependency.
|
|
27
|
+
- Guess a product decision, or pick a `RUN_CONFLICT` option the human has not answered.
|
|
28
|
+
|
|
29
|
+
## Stop conditions
|
|
30
|
+
|
|
31
|
+
Stop on the first one that is true. Do not start another iteration after it.
|
|
32
|
+
|
|
33
|
+
| Code | Stop when |
|
|
34
|
+
|---|---|
|
|
35
|
+
| `GOAL_NOT_FROZEN` | The Goal is not frozen. Do not invent one. |
|
|
36
|
+
| `NEEDS_HUMAN` | A question is waiting, or the next step is a product decision. |
|
|
37
|
+
| `GUARD_BLOCK` | `guard-events.json` has a `block`. |
|
|
38
|
+
| `BUDGET` | The budget kill switch is on, or `budget record --unavailable` fails. |
|
|
39
|
+
| `VERIFY_STILL_RED` | Verification is still red at the iteration cap. |
|
|
40
|
+
| `JUDGE_ESCALATE` | The Judge escalated. |
|
|
41
|
+
| `JUDGED_PASS` | The Judge passed. Wait. Do not deliver. |
|
|
42
|
+
|
|
43
|
+
## What must be left for the morning
|
|
44
|
+
|
|
45
|
+
A person should be able to review without replaying the session.
|
|
46
|
+
|
|
47
|
+
- The frozen Goal (`goal.frozen` on the Run).
|
|
48
|
+
- `runs/<id>/diff.patch` when the stop is `JUDGED_PASS` or the human has since approved delivery.
|
|
49
|
+
- `runs/<id>/verification.json` (command, exit code, logs) in those same cases.
|
|
50
|
+
- `runs/<id>/verdict.json` for `JUDGED_PASS` and `JUDGE_ESCALATE`.
|
|
51
|
+
- `runs/<id>/findings.json` when a review ran.
|
|
52
|
+
- Unanswered questions in `interactions.jsonl`.
|
|
53
|
+
|
|
54
|
+
`JUDGED_PASS` is a successful stop. The human delivers in the morning with `deliver --approve --by <name>`.
|
|
55
|
+
|
|
56
|
+
## Check
|
|
57
|
+
|
|
58
|
+
```bash
|
|
59
|
+
npx ai-engineering-loop overnight check [--run <id>] [--json]
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
Exit 0 when the contract holds. Exit 1 when an unattended Run was delivered without a person (`humanApproved` not true, or `approvedBy` is an agent name), or a stopped Run is missing the morning files above. Assisted and report-only Runs do not apply; the check says so and exits 0.
|
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
# Prototype, then contract
|
|
2
|
+
|
|
3
|
+
When the design is still a guess, one throwaway spike is allowed before the Goal is frozen. The spike answers one question. You delete it, write the contract from what you learned, and the human freezes. Maker starts from that contract, not from the spike.
|
|
4
|
+
|
|
5
|
+
## Steps
|
|
6
|
+
|
|
7
|
+
1. Start the Run (`ael run "<task>"`). Do not edit product code yet.
|
|
8
|
+
2. Name one question the code can answer. Example: "Does the list helper already paginate?"
|
|
9
|
+
3. Answer it in a scratch branch or an untracked file you will delete. Do not commit that code onto the task branch.
|
|
10
|
+
4. Delete the scratch. Nothing from the spike remains in the tree.
|
|
11
|
+
5. Record the note:
|
|
12
|
+
|
|
13
|
+
```bash
|
|
14
|
+
npx ai-engineering-loop spike record --discarded \
|
|
15
|
+
--question "Does the list helper already paginate?" \
|
|
16
|
+
--learned "slice(0, 10) is fixed. The contract needs a page argument."
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
6. Draft the Goal from `learned`. Leave the spike's structure out of the acceptance criteria.
|
|
20
|
+
7. Show the draft and wait. The human freezes. Then Maker begins.
|
|
21
|
+
|
|
22
|
+
`spike show` reads `runs/<id>/spike.json`. A missing file is fine: a spike is optional. `discarded` must be true.
|
|
23
|
+
|
|
24
|
+
Recording is refused when `--discarded` is missing, or the Goal is already frozen. Re-recording before freeze replaces the note.
|
|
25
|
+
|
|
26
|
+
## Not a tournament
|
|
27
|
+
|
|
28
|
+
One spike, then the contract. Do not run a bake-off, a second model, or `/arena`. The human does not pick a winner among prototypes. There is nothing to pick: the prototype is gone, and the contract is what gets frozen.
|
|
@@ -22,6 +22,33 @@ Use a gated diagnosis loop. Do not skip a gate.
|
|
|
22
22
|
5. **Fix.** Only after one hypothesis is confirmed. The fix is Stage 4, still test-first at the agreed seam (`policies/tdd-policy.md`).
|
|
23
23
|
6. **Regression test.** The red repro becomes a kept test mapped to an AC.
|
|
24
24
|
|
|
25
|
+
## Start from a bug report
|
|
26
|
+
|
|
27
|
+
`ael run --from-issue <url|#n>` reads one issue and drafts the Goal. The Run then stays on the normal loop: the human freezes the Goal, then Maker, verification, Devil's Advocate, Judge, and human-approved delivery. That loop does not change.
|
|
28
|
+
|
|
29
|
+
The reader is read-only. It never comments, creates, closes, or edits the issue.
|
|
30
|
+
|
|
31
|
+
| Host | Command |
|
|
32
|
+
|---|---|
|
|
33
|
+
| GitHub | `gh issue view <url-or-number> --json number,title,body,url,state` |
|
|
34
|
+
| GitLab | `glab issue view <number> --output json` |
|
|
35
|
+
|
|
36
|
+
A `#n` uses the origin host (`gh` on GitHub, `glab` on GitLab). A full issue URL names the host. If `gh` or `glab` is missing or not signed in, paste the report and run `ael outcome repro --file <path>` (`run --from-report <path>` is the same draft).
|
|
37
|
+
|
|
38
|
+
The draft has one acceptance criterion. `failureCases` is the concrete failing behavior. `verify.command` is the command that fails today. The Maker still sees that command red before the fix.
|
|
39
|
+
|
|
40
|
+
When the issue text has neither, put them in the report:
|
|
41
|
+
|
|
42
|
+
```markdown
|
|
43
|
+
# Export ignores the active filter
|
|
44
|
+
|
|
45
|
+
Actual: The CSV contains rows the filter hid.
|
|
46
|
+
|
|
47
|
+
Verify: npm test -- export.test.js
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
`Verify:`, `Driver:`, or `Command:` is the command. A `bash` fence, or the first command under a Repro / Steps heading, works too. `Actual:` (or an Actual heading) is the failing behavior. The first of each wins. AEL does not invent a command.
|
|
51
|
+
|
|
25
52
|
## When fixes keep failing
|
|
26
53
|
|
|
27
54
|
- **Trace backward.** Start at the wrong value or symptom and walk up the call chain to where it first became wrong. Fix it there, not where it surfaced.
|
package/core/run-isolation.md
CHANGED
|
@@ -29,6 +29,8 @@ Two agent sessions in one checkout corrupt each other: `gate maker --from-git` c
|
|
|
29
29
|
|
|
30
30
|
Creates `<repo>.ael-worktrees/<slug>-<id>` next to the repository on branch `ael/<slug>-<id>`, from `HEAD` (uncommitted changes of the other Run stay behind), copies the AEL context files (not `runs/`, `recaps/`, `tasks/` or pointers), starts the Run there, and records it in `.ai-engineering-loop/worktrees.json` of the main checkout. `--mode`, `--recipe`, `--tier` and `--tier-reason` pass through. Work only in the printed path for that Run.
|
|
31
31
|
|
|
32
|
+
`--base <branch>` with `--worktree` starts that worktree from the named commit instead of `HEAD` (`docs coordinator`). `--base` on its own is refused.
|
|
33
|
+
|
|
32
34
|
## Stage 9: cleanup after deliver (C-39)
|
|
33
35
|
|
|
34
36
|
When `deliver` completes a Run inside a registered worktree:
|
|
@@ -77,3 +79,20 @@ Uncommitted or unmerged work is never removed. `status` and `run` print one line
|
|
|
77
79
|
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
80
|
|
|
79
81
|
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.
|
|
82
|
+
|
|
83
|
+
## `pr babysit` (after the PR is open)
|
|
84
|
+
|
|
85
|
+
`ai-engineering-loop pr babysit --run <id> [--json]` watches the pull request for that Run. Each look is a `pr status` read (same `gh pr view`, same `GH_UNAVAILABLE` when `gh` is missing or signed out). It polls with backoff while the verdict is `waiting`: 2s, 4s, 8s, 16s, then 30s, and at most 8 times.
|
|
86
|
+
|
|
87
|
+
| What you see | What babysit does |
|
|
88
|
+
|---|---|
|
|
89
|
+
| Failing checks, and the fix classifies as T0 or T1 | Starts a fix Run on that same branch and pushes it (`git push origin <branch>`). T0 and T1 come from the same classifier as `run`: the failing check names are the task text, and a dirty risky path raises the tier. The agent finishes that Run, then runs `pr babysit` again. |
|
|
90
|
+
| Failing checks that classify as T2 | Stops. A human takes a risky fix. |
|
|
91
|
+
| `ready` (ready to merge) | Stops and says so. You merge it. |
|
|
92
|
+
| `changes-requested` | Stops and says so, even when checks are also failing. |
|
|
93
|
+
| `merged`, `closed`, `draft`, or `merge-conflicts` with no failing checks | Stops and names the blocker. |
|
|
94
|
+
| This checkout is on a different branch | Stops and names the PR branch. It does not switch branches. |
|
|
95
|
+
|
|
96
|
+
The fix Run is recorded at `runs/<fix-id>/fix-pass.json` (`parentRunId`, `branch`, `tier`, `checks`). Calling babysit again while that Run is unfinished pushes the same branch and does not start a second Run.
|
|
97
|
+
|
|
98
|
+
Merge stays with the human. This command does not run `gh pr merge` or `git merge`.
|
|
@@ -82,6 +82,8 @@ Enforcement (`lib/claimed-vs-reality.js`, `gate review`):
|
|
|
82
82
|
|
|
83
83
|
**Feature map (C-22).** Optional `.ai-engineering-loop/feature-map.md` is a site map of what users can do, one Markdown table: `| Feature | Where (UI or endpoint) | Paths (globs) | How to reach | Driver |`. `review-pack` appends the entries whose `Paths` the diff touches, so the Devil's Advocate and L3 evidence use the same names ("export-csv", not "the button on the left"). `Driver` is an optional reusable command that runs the flow (cheaper and more repeatable than an agent clicking around). `doctor --harness` warns when `e2e` or `smoke` is configured but the map is empty.
|
|
84
84
|
|
|
85
|
+
`ael feature-map scaffold` drafts that table from routes (the same declarations the impact map reads, plus Next.js route handlers), an OpenAPI or Swagger document, page files, or README headings when nothing else exists. No signal produces a stub table with no rows. An existing `feature-map.md` that differs is left in place and the new draft is written to `feature-map.md.ael-new`. `init` and project onboarding only offer the command; they do not write the map unless you say yes.
|
|
86
|
+
|
|
85
87
|
**L1 at T1/T2.** When `verification.md` configures `typecheck` or `lint`, the verification gate at T1/T2 refuses a full-scope bundle with no L1 record (`L1_MISSING`). The related lane is exempt; `verify --final` runs the full plan.
|
|
86
88
|
|
|
87
89
|
`init` writes only commands the project really has: `typecheck` from a script or a TypeScript setup, `lint` and `build` only from package scripts.
|
|
@@ -0,0 +1,34 @@
|
|
|
1
|
+
# How AEL verifies work
|
|
2
|
+
|
|
3
|
+
A change is verified when the gates below have passed on recorded files. A sentence from the agent is not verification.
|
|
4
|
+
|
|
5
|
+
## Gates, in order
|
|
6
|
+
|
|
7
|
+
1. **Goal.** The human froze a contract that says what fails (`docs goal-contract`). The agent does not freeze it.
|
|
8
|
+
2. **Maker.** `gate maker --from-git` writes `runs/<id>/diff.patch`. That diff is the change.
|
|
9
|
+
3. **Verify.** `ael verify` runs the project's commands and writes `verification.json`: the command, the exit code, and the logs. A non-zero exit blocks the gate.
|
|
10
|
+
4. **Review.** Claimed-vs-reality cites those logs. Devil's Advocate writes `findings.json`. `gate review` checks the ledger against the diff.
|
|
11
|
+
5. **Judge.** PASS, ITERATE, or ESCALATE, from the ledger and the evidence (`docs judge-policy`). PASS with an open BLOCKER or HIGH is refused.
|
|
12
|
+
6. **Deliver.** A person passes `deliver --approve --by <name>`. The receipt is recomputed from the artifacts.
|
|
13
|
+
|
|
14
|
+
## What verify records
|
|
15
|
+
|
|
16
|
+
```bash
|
|
17
|
+
npx ai-engineering-loop verify --run <id>
|
|
18
|
+
```
|
|
19
|
+
|
|
20
|
+
The default plan runs the commands configured in `.ai-engineering-loop/verification.md` (build, typecheck, lint, unit tests), stops at the first failure, and stores each result. `--related` is the fast lane on the files that changed. `--final` is the full run after the Judge passes, before delivery.
|
|
21
|
+
|
|
22
|
+
## Layers
|
|
23
|
+
|
|
24
|
+
| Layer | Proves |
|
|
25
|
+
|---|---|
|
|
26
|
+
| L1 | Static checks: types, lint, build |
|
|
27
|
+
| L2 | Tests and other runtime checks |
|
|
28
|
+
| L3 | A real user flow across components |
|
|
29
|
+
|
|
30
|
+
The long map, including baselines and waivers, is `docs verification-loop`.
|
|
31
|
+
|
|
32
|
+
## Tiers
|
|
33
|
+
|
|
34
|
+
T0 still runs verify and the gates. The CLI writes the empty ledger and the verdict; there is no Devil's Advocate subagent. T1 adds that review. T2 adds a stronger Judge and a safety proof. None of the tiers skip the recorded command.
|
|
@@ -0,0 +1,32 @@
|
|
|
1
|
+
# Weekly process-sampling playbook
|
|
2
|
+
|
|
3
|
+
Once a week, read three recent Runs. If the project has fewer than three, read all of them. You are checking that the loop was followed. You are not re-reviewing the product.
|
|
4
|
+
|
|
5
|
+
## Pick the sample
|
|
6
|
+
|
|
7
|
+
1. List `.ai-engineering-loop/runs/` and take the three newest directories that contain `state.json`.
|
|
8
|
+
2. Skip `CANCELLED` unless you are asking why the work stopped.
|
|
9
|
+
3. Write down the run id, the task, the tier, and the state.
|
|
10
|
+
|
|
11
|
+
`ael recap --days 7` is a map of what shipped. The sample still comes from the Run directories, because the recap does not show a skipped gate.
|
|
12
|
+
|
|
13
|
+
## For each Run, answer from files
|
|
14
|
+
|
|
15
|
+
| Question | Where to look | Followed when |
|
|
16
|
+
|---|---|---|
|
|
17
|
+
| The Goal was frozen before the code changed | `state.json` history, then `diff.patch` | `GOAL_FROZEN` is earlier than the diff |
|
|
18
|
+
| Verification is a command, not a claim | `verification.json` | `commands` has an entry, `exitCode` is 0, and stdout is stored |
|
|
19
|
+
| Review happened when the tier needs it | `findings.json` | T1 and T2 have a ledger. T0 may have the empty ledger the CLI writes |
|
|
20
|
+
| The Judge matches the ledger | `verdict.json` | `PASS` only when no BLOCKER or HIGH is still open. Otherwise `ITERATE` or `ESCALATE` |
|
|
21
|
+
| A person approved delivery | `delivery.json` | `humanApproved` is true and `approvedBy` is that person |
|
|
22
|
+
| The diff stayed inside the Goal | `diff.patch`, the frozen Goal, `impact-map.json` | No surprise files outside the frozen scope |
|
|
23
|
+
|
|
24
|
+
A missing file is "could not tell", not a pass.
|
|
25
|
+
|
|
26
|
+
## Write the note down
|
|
27
|
+
|
|
28
|
+
Three lines per Run: followed, one miss, or "could not tell" plus the missing file. Keep the note in your own weekly log. The loop does not store it.
|
|
29
|
+
|
|
30
|
+
## When a Run skipped a gate
|
|
31
|
+
|
|
32
|
+
Do not patch history. On the next Run, watch that gate. If the same gate is skipped in a second sample, treat it as a loop bug and fix the gate.
|
package/lib/agent-artifacts.js
CHANGED
|
@@ -153,6 +153,12 @@ function scaffoldGoal(rootDir, { runId } = {}) {
|
|
|
153
153
|
schemaVersion: 1,
|
|
154
154
|
runId: run.runId,
|
|
155
155
|
objective: run.task || '<one sentence: what changes for the user>',
|
|
156
|
+
restatement: {
|
|
157
|
+
problem: '<the problem in your own words>',
|
|
158
|
+
doneWhen: '<the outcome that means this is done>',
|
|
159
|
+
failIf: '<what is still wrong if that outcome is missed>',
|
|
160
|
+
unknowns: '<what you cannot tell yet, or None>'
|
|
161
|
+
},
|
|
156
162
|
acceptanceCriteria: [{
|
|
157
163
|
id: 'AC-1',
|
|
158
164
|
statement: '<observable behaviour, e.g. "Export button downloads a CSV of the filtered rows">',
|
package/lib/cli-args.js
CHANGED
|
@@ -11,7 +11,7 @@ const HELP_FLAGS = new Set(['-h', '--help']);
|
|
|
11
11
|
// accepted bare words (null = free text allowed).
|
|
12
12
|
const WRITER_COMMANDS = Object.freeze({
|
|
13
13
|
init: { flags: [], valued: [], positionals: [] },
|
|
14
|
-
refresh: { flags: ['--non-destructive', '--json'], valued: [], positionals: [] },
|
|
14
|
+
refresh: { flags: ['--non-destructive', '--json', '--garden', '--yes'], valued: [], positionals: [] },
|
|
15
15
|
'sync-hosts': { flags: ['--dry-run', '--prune', '--json'], valued: ['--pack'], positionals: [] },
|
|
16
16
|
setup: { flags: ['--yes', '--json'], valued: ['--hosts', '--mode'], positionals: [] },
|
|
17
17
|
hosts: { flags: ['--json'], valued: [], positionals: null },
|
|
@@ -25,19 +25,21 @@ const WRITER_COMMANDS = Object.freeze({
|
|
|
25
25
|
positionals: []
|
|
26
26
|
},
|
|
27
27
|
worktree: { flags: ['--json', '--yes', '--audit', '--include-scratch'], valued: [], positionals: ['prune'] },
|
|
28
|
-
pr: { flags: ['--json'], valued: ['--run', '--branch', '--pr'], positionals: ['status'] },
|
|
28
|
+
pr: { flags: ['--json'], valued: ['--run', '--branch', '--pr'], positionals: ['status', 'babysit'] },
|
|
29
29
|
driver: { flags: ['--json'], valued: ['--feature', '--surface'], positionals: ['scaffold'] },
|
|
30
|
+
'feature-map': { flags: ['--json'], valued: [], positionals: ['scaffold'] },
|
|
30
31
|
safety: { flags: ['--json', '--live'], valued: ['--run', '--fact', '--cmd', '--level'], positionals: ['record'] },
|
|
31
32
|
measurement: { flags: ['--json'], valued: ['--run', '--ac', '--runs', '--spread', '--effect', '--limiter'], positionals: ['record'] },
|
|
32
33
|
recap: { flags: ['--json', '--open'], valued: ['--days', '--for', '--projects', '--out', '--now', '--lang'], positionals: [] },
|
|
33
34
|
migrate: { flags: ['--json', '--dry-run'], valued: ['--from'], positionals: [] },
|
|
34
35
|
debt: { flags: ['--json'], valued: ['--by', '--note', '--file'], positionals: null },
|
|
35
|
-
outcome: { flags: ['--json'], valued: ['--run', '--source', '--location', '--summary', '--evidence', '--by'], positionals: ['record'] },
|
|
36
|
+
outcome: { flags: ['--json'], valued: ['--run', '--source', '--location', '--summary', '--evidence', '--by', '--file'], positionals: ['record', 'repro'] },
|
|
36
37
|
verify: { flags: ['--json', '--serial', '--shell', '--related', '--final', '--fresh', '--baseline'], valued: ['--run', '--cmd', '--timeout-ms'], positionals: [] },
|
|
37
38
|
quick: { flags: ['--json', '--serial', '--shell'], valued: ['--run', '--cmd', '--timeout-ms', '--mode'], positionals: null },
|
|
38
39
|
review: { flags: ['--json'], valued: ['--run', '--child-id', '--file'], positionals: ['ingest'] },
|
|
39
40
|
sources: { flags: ['--json'], valued: ['--run', '--source', '--ref', '--line'], positionals: ['refresh', 'show', 'record', 'hint'] },
|
|
40
41
|
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 },
|
|
42
|
+
spike: { flags: ['--json', '--discarded'], valued: ['--run', '--question', '--learned'], positionals: ['record', 'show'] },
|
|
41
43
|
guard: { flags: ['--json'], valued: ['--run', '--tool', '--input', '--path', '--command', '--hook'], positionals: ['check'] },
|
|
42
44
|
hooks: { flags: ['--json'], valued: ['--host'], positionals: ['install', 'uninstall', 'status'] },
|
|
43
45
|
impact: { flags: ['--json', '--force'], valued: ['--run', '--by', '--reason', '--allow', '--remove', '--limit'], positionals: ['map', 'show', 'confirm', 'skip', 'drift'] },
|
package/lib/design-ref.js
CHANGED
|
@@ -117,12 +117,27 @@ function designRefFrom(doc, parsed) {
|
|
|
117
117
|
return { path: doc.path, sha256: doc.sha256, targetFiles: parsed.targetFiles };
|
|
118
118
|
}
|
|
119
119
|
|
|
120
|
+
// Problem and outcomes only. Target files and the implementation plan stay out,
|
|
121
|
+
// so a prefilled draft does not freeze the design's method.
|
|
122
|
+
function restatementFromDesign(doc, parsed) {
|
|
123
|
+
const problem = [parsed.title, ...parsed.goals].filter(Boolean).join('. ') || `The work described in ${doc.path} is not done.`;
|
|
124
|
+
const outcomes = parsed.testCases.length ? parsed.testCases : parsed.goals;
|
|
125
|
+
const lead = parsed.goals[0] || parsed.title || 'the stated outcome';
|
|
126
|
+
return {
|
|
127
|
+
problem,
|
|
128
|
+
doneWhen: outcomes.length ? outcomes.join('. ') : problem,
|
|
129
|
+
failIf: `${lead} is still missing.`,
|
|
130
|
+
unknowns: parsed.warnings.length ? parsed.warnings.join(' ') : 'None.'
|
|
131
|
+
};
|
|
132
|
+
}
|
|
133
|
+
|
|
120
134
|
// A draft contract built from the document. Never frozen here.
|
|
121
135
|
function draftFromDesign(doc, parsed) {
|
|
122
136
|
const rows = parsed.testCases.length ? parsed.testCases : parsed.goals;
|
|
123
137
|
const objective = parsed.goals[0] || parsed.title || `Implement ${doc.path}`;
|
|
124
138
|
return {
|
|
125
139
|
objective: parsed.title && parsed.goals[0] ? `${parsed.title}: ${parsed.goals[0]}` : objective,
|
|
140
|
+
restatement: restatementFromDesign(doc, parsed),
|
|
126
141
|
acceptanceCriteria: rows.length
|
|
127
142
|
? rows.map((row, index) => placeholderRow(index, row))
|
|
128
143
|
: [placeholderRow(0, `${PLACEHOLDER} acceptance criterion from ${doc.path}>`)],
|
package/lib/driver-scaffold.js
CHANGED
|
@@ -247,7 +247,7 @@ function setDriverCell(rootDir, featureId, command) {
|
|
|
247
247
|
function scaffoldDriver(rootDir, { feature = null, surface = null } = {}) {
|
|
248
248
|
if (surface && !SURFACES.includes(surface)) throw fail(`--surface must be ${SURFACES.join(', ')}`);
|
|
249
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)
|
|
250
|
+
if (!entries.length) throw fail('No feature map yet: run `feature-map scaffold`, or add rows to .ai-engineering-loop/feature-map.md (Feature | Where | Paths | How to reach | Driver)', 'FEATURE_MAP_MISSING');
|
|
251
251
|
const targets = feature ? entries.filter((entry) => entry.id === feature) : entries.filter((entry) => !entry.driver);
|
|
252
252
|
if (feature && !targets.length) throw fail(`No feature "${feature}" in the feature map; known: ${entries.map((entry) => entry.id).join(', ')}`, 'NOT_FOUND');
|
|
253
253
|
const facts = projectFacts(rootDir);
|