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.
Files changed (46) hide show
  1. package/.agents/skills/ael/SKILL.md +3 -19
  2. package/.agents/skills/ael/references/loop-commands.md +5 -3
  3. package/.agents/skills/ael/references/loop-deliver.md +20 -0
  4. package/.agents/skills/ael/references/loop-goal.md +3 -2
  5. package/.agents/skills/ael/references/loop-hosts.md +10 -0
  6. package/.agents/skills/ael/references/loop-judge.md +9 -0
  7. package/.agents/skills/ael/references/loop-maker.md +1 -2
  8. package/.agents/skills/ael/references/loop-modes.md +6 -0
  9. package/.agents/skills/ael/references/loop-review.md +2 -6
  10. package/CHANGELOG.md +35 -0
  11. package/README.md +9 -1
  12. package/agents/instruction-only/AGENTS.md +1 -1
  13. package/bin/ai-engineering-loop.js +398 -41
  14. package/core/dig-first.md +46 -0
  15. package/core/goal-contract.md +40 -0
  16. package/core/run-isolation.md +24 -0
  17. package/core/verification-loop.md +27 -0
  18. package/lib/adapter-check.js +3 -2
  19. package/lib/agent-artifacts.js +28 -0
  20. package/lib/budget.js +1 -1
  21. package/lib/clean-state.js +20 -0
  22. package/lib/cli-args.js +5 -2
  23. package/lib/docs.js +2 -1
  24. package/lib/doctor.js +26 -0
  25. package/lib/driver-scaffold.js +289 -0
  26. package/lib/gates.js +3 -1
  27. package/lib/gh.js +27 -0
  28. package/lib/git-readiness.js +36 -0
  29. package/lib/harness-audit.js +11 -0
  30. package/lib/pr-status.js +83 -0
  31. package/lib/provenance.js +111 -0
  32. package/lib/quick.js +11 -0
  33. package/lib/recap-html.js +3 -2
  34. package/lib/recap.js +9 -0
  35. package/lib/receipt.js +3 -1
  36. package/lib/review-ingest.js +6 -1
  37. package/lib/rules.js +4 -2
  38. package/lib/run-isolation.js +117 -27
  39. package/lib/sources.js +166 -0
  40. package/lib/stats.js +9 -0
  41. package/lib/ste.js +69 -0
  42. package/lib/sync-hosts.js +2 -0
  43. package/lib/transcript-lessons.js +232 -0
  44. package/lib/workflow-runtime.js +8 -2
  45. package/package.json +2 -2
  46. package/schemas/goal-contract.schema.json +14 -0
@@ -25,7 +25,7 @@ Same skill on every host. Before the first DA or Judge spawn, read your host's s
25
25
  Map (not a second OS) of the 8-stage loop: Specify (stages 0-1), Make (stages 2-4), Review (stages 5-7), Deliver (stage 8). Parent = Maker + orchestrator; Devil's Advocate (DA) and Judge are fresh **siblings**, never nested or resumed. Gate failures override prose. Never edit `state.json`/`current.json`.
26
26
 
27
27
  Tier (from `run --json`; it only rises). Do not skip Goal Contract, verification, Devil's Advocate, or Judge gates; the tier only decides who fills them.
28
- - **T0** trivial (docs, typo, lint): `quick start "<task>"` (run + `gate goal`), edit, `quick finish`; no subagents.
28
+ - **T0** trivial (docs/typo/lint): `quick start "<task>"` (run + `gate goal`), edit, `quick finish`; no subagents.
29
29
  - **T1** normal: frozen Goal, red test, `verify --related`, lean DA, `review ingest`; Judge only on `judgeRequired`.
30
30
  - **T2** risky (HIGH_RISK_PATH, DOT business logic, >10 files): add `loop-risky` (blast radius, Judge on STRONG_MODEL). Unseen risk: `run --new --tier T2 --tier-reason <why>`.
31
31
 
@@ -37,26 +37,10 @@ Invariants (every tier):
37
37
  - One red test per AC row (bugs: red repro) before the fix.
38
38
  - Write claimed-vs-reality.md after `gate verification` passes. Do not spawn Devil's Advocate if the file is missing or any Claimed row lacks Reality.
39
39
  - ITERATE to iteration 3 (or the recipe cap), each with a **new** DA.
40
- - Never infer human approval.
40
+ - Never infer human approval; ask with host buttons (`loop-hosts`).
41
41
  - After each child `budget record` real usage or `--unavailable`; never invent counts.
42
42
  - No secrets or hidden reasoning in activity messages.
43
43
 
44
44
  ## Report header
45
45
 
46
- When a subagent returned its own result (Grok: its own `subagent_id`):
47
-
48
- ```
49
- Execution Mode: TRUE_INDEPENDENT_AGENT
50
- Independent LLM Execution: PROVEN
51
- Native Subagent Invocation: AVAILABLE
52
- Review Method: True Independent Agent
53
- ```
54
-
55
- When no subagent ran (tool AVAILABLE: mode adds `(reason: <why>)`):
56
-
57
- ```
58
- Execution Mode: CONTEXT_ISOLATION_ONLY
59
- Independent LLM Execution: NOT PROVEN
60
- Native Subagent Invocation: UNAVAILABLE
61
- Review Method: Clean-Slate Artifact Isolation Barrier
62
- ```
46
+ The final report starts with the execution-mode block in `loop-deliver` (TRUE_INDEPENDENT_AGENT or CONTEXT_ISOLATION_ONLY); never claim independent execution without a subagent result. Tool AVAILABLE but unused: add `(reason: <why>)`.
@@ -11,14 +11,16 @@
11
11
 
12
12
  Run these when the user asks how the loop is doing, before planning work, or when a gate points at them. All read local Run files; none starts a Run.
13
13
  - `stats [--last <n>] [--json]`: failure causes by harness layer (`task_spec`, `context`, `environment`, `verification`, `state`, `model`), false-victory rate per tier, iterations to PASS, revert rate of delivered Runs (from git) and the verification share of tokens. Fix the bottleneck layer first.
14
+ - `learn --transcripts [--since 30d]`: corrections you repeated across agent chats become candidate lessons (local, redacted; `docs verification-loop` 12).
14
15
  - `learn promote ... --prove <commit>`: the check must fail on the commit that introduced the mistake. `measurement record --ac <id> --runs <n> --spread <pct> --effect <pct> --limiter <text>` for `measure: true` ACs (`docs verification-loop` 3e).
15
- - `run --worktree "<task>"` starts a task in its own git worktree when another Run is unfinished; `worktree prune [--yes]` removes finished, clean worktrees and merged branches (`docs run-isolation`).
16
+ - `run --worktree "<task>"` starts a task in its own git worktree when another Run is unfinished; `worktree prune [--audit] [--include-scratch] [--yes]` removes finished, clean worktrees and merged branches; `pr status --run <id>` reads the PR once and records `merge.json` when merged (`docs run-isolation`).
16
17
  - `recap [--days N] [--for me|lead|client] [--projects <p,...>|all]`: one HTML page of what shipped, with evidence (`docs recap`). Client recaps take one project.
17
18
  - `outcome record --run <id> --source mr-comment|revert|bug|incident --location <file[:line]> --summary <text> --by <name>`: a problem people found after delivery. Only record what the human reported; never invent one. Then `calibrate` lists DA misses and wrong dismissals per reviewer prompt version.
18
19
  - `debt [--file <path>]` lists trade-offs the Judge accepted and L3 waivers; `debt close <id> --by <name>` only on the human's word.
19
20
  - `next`: the next unblocked feature in `.ai-engineering-loop/features.json` and VCR (verified/activated). Finish the active feature before starting another.
20
21
  - `learn` lists lessons seen in 3+ Runs; a human promotes one with `learn promote <id> --check "<cmd>" --fix "<instruction>" --by <name>`. Default `verify` then runs it as an L1 rule. On a codebase that already has old violations use `--scope diff`: the check reads only added lines from `$AEL_ADDED_LINES_FILE`, so new ones fail and the old ones become a backlog (`doctor --harness`). Common cases need no script: `--forbid-import "src/renderer/** -> src/main/**"` or `--forbid-api "\buseEffect\(" --except "src/framework/**"`.
21
- - `.ai-engineering-loop/feature-map.md` (Feature | Where | Paths | How to reach | Driver): `review-pack` adds the features a diff touches; use those names and drivers for L3 evidence.
22
+ - `.ai-engineering-loop/feature-map.md` (Feature | Where | Paths | How to reach | Driver): `review-pack` adds the features a diff touches; use those names and drivers for L3 evidence. `driver scaffold [--feature <id>]` writes a reusable driver (launch, drive, observe) per row and fills the Driver column; fill in its `EXPECT` and steps once, then reuse it every Run.
23
+ - Dig before asking (`docs dig-first`): `.ai-engineering-loop/sources.md` lists readable sources (read-only); `sources hint` suggests queries, `sources record` caches one line each (budget T0 0, T1 4, T2 8). Goal `statements` label fact/decision/assumption; a fact needs `path:line`, a commit or a recorded `S-n`. Assumptions are shown, never blocking.
22
24
  - `doctor --harness`: harness debt (entry-file size and structure, stale learnings, rule provenance, skill budget). Report findings; do not mass-delete.
23
25
  - `bench --without <integrity|l3|l1|smoke|rules>` measures whether a gate component still earns its cost (`docs bench`). Never use it on a real task.
24
26
 
@@ -32,7 +34,7 @@ Stage commands (`run`, `goal`, `gate`, `verify`, `review-pack`, `deliver`, `node
32
34
 
33
35
  ## Budget
34
36
 
35
- `run --json` already reports the budget; run `budget status --run <runId>` only before each new iteration. After each child, `budget record --input <n> --output <n> --model <id> --role maker|reviewer|judge|verification --run <runId>` from provider usage. No usage shown: `budget record --unavailable --run <runId>` once; ASSISTED continues and discloses it at delivery (do not ask the human); UNATTENDED fails that command, so stop and escalate. `budget pause` is the kill switch. The ledger mode is immutable. UNATTENDED or budget errors: `docs runtime-safety`.
37
+ `run --json` already reports the budget; run `budget status --run <runId>` only before each new iteration. After each child, `budget record --input <n> --output <n> --model <id> --role maker|reviewer|judge|verification|gather --run <runId>` from provider usage. No usage shown: `budget record --unavailable --run <runId>` once; ASSISTED continues and discloses it at delivery (do not ask the human); UNATTENDED fails that command, so stop and escalate. `budget pause` is the kill switch. The ledger mode is immutable. UNATTENDED or budget errors: `docs runtime-safety`.
36
38
 
37
39
  ## Resuming
38
40
 
@@ -9,3 +9,23 @@
9
9
  - Commit before `deliver` (its receipt binds `HEAD`; videos/screenshots: `--evidence AC-N=<https-url>`, required for `crossComponent` and rubric ACs). Paste `RUN_DIR/receipt.md` into the PR/MR Receipt section unchanged; ❌ stays ❌ (`docs pr-receipt`).
10
10
  - Only the delivery gate completes the run. It also mines lessons for the next Run.
11
11
  - Worktree Run: after `deliver`, continue in `cleanup.mainCheckout` (Stage 9).
12
+
13
+ ## Report header (execution mode)
14
+
15
+ When a subagent returned its own result (Grok: its own `subagent_id`):
16
+
17
+ ```
18
+ Execution Mode: TRUE_INDEPENDENT_AGENT
19
+ Independent LLM Execution: PROVEN
20
+ Native Subagent Invocation: AVAILABLE
21
+ Review Method: True Independent Agent
22
+ ```
23
+
24
+ When no subagent ran (tool AVAILABLE: mode adds `(reason: <why>)`):
25
+
26
+ ```
27
+ Execution Mode: CONTEXT_ISOLATION_ONLY
28
+ Independent LLM Execution: NOT PROVEN
29
+ Native Subagent Invocation: UNAVAILABLE
30
+ Review Method: Clean-Slate Artifact Isolation Barrier
31
+ ```
@@ -7,9 +7,10 @@
7
7
  - AC is a failure table: each row has a statement, required evidence, and failure cases. Do not freeze sunny-path-only. T0 may use 1-3 rows that still list failure cases.
8
8
  - Boundary-crossing AC (UI-API, service-DB, queue, IPC): `crossComponent: true`; needs L3.
9
9
  - Optional per AC: `verify.command` (Judge PASS needs it green), `rubric` for subjective ACs; Goal `featureId` links `features.json`; Goal `flow` (from/event/to) for UI work: show its table with the draft (`docs goal-contract`).
10
- - Write the contract JSON to a repository-local file, then `npx ai-engineering-loop goal draft --run <runId> --file <file> --revision <currentRevision>` (publishes the draft and the freeze question to Studio). Show the human the draft and its `impactPreview` in one message.
10
+ - Write the contract JSON to `.ai-engineering-loop/drafts/goal.json`, then `npx ai-engineering-loop goal draft --json --run <runId> --file <file> --revision <currentRevision>` (publishes the draft and the freeze question to Studio). Show the human `goal show --run <runId> --human` (plain Markdown) and the `impactPreview` in one message.
11
+ - Write `objective`, AC `statement` and `failureCases` in STE style (`docs goal-contract`, STE): one fact or action per sentence, active voice, at most 20-25 words, words a test can check. Fix `readability` warnings from `goal draft` before asking for the freeze.
11
12
  - If `goal draft` returns `diagramOptions`, offer the recommended view or freeze; render only the pick (`goal diagram --view <v>`), then ask: freeze, another view, or add AC for `?`/side effects.
12
- - Wait for the explicit human freeze, then `npx ai-engineering-loop goal freeze --latest --run <runId> --by <name>` (or `--revision <r> --hash <h>`). Add `--confirm-impact` when that answer also accepts the blast radius. T0: `quick start`.
13
+ - Wait for the explicit human freeze, then `npx ai-engineering-loop goal freeze --json --latest --run <runId> --by <name>` (or `--revision <r> --hash <h>`). Add `--confirm-impact` when that answer also accepts the blast radius. T0: `quick start`.
13
14
  - Otherwise the freeze writes a DRAFT blast-radius map: `impact show --run <runId>`. ASSISTED: the human confirms or edits it (`impact confirm --by <name> [--allow <glob>] [--remove <path>]`); copy/CSS/comment-only goals: `impact skip --by <name> --reason <text>` (`docs blast-radius-map`).
14
15
  - Do not edit production code until the Goal gate passes.
15
16
  - After the freeze, work from the frozen contract (`goal show --run <runId>`), not the drafting chat; compact the conversation there if the host supports it.
@@ -46,3 +46,13 @@ Strict proxies (including Kiro) return HTTP 400 `REQUEST_BODY_INVALID` on unknow
46
46
 
47
47
  1. Use a native subagent only if it can run the DA or Judge prompt with a fresh context and return its own result; read-only research subagents qualify only for DA.
48
48
  2. Otherwise run DA and Judge in this session as `CONTEXT_ISOLATION_ONLY`, disclosed, with the same budgets.
49
+
50
+ ## Asking the human
51
+
52
+ Every decision that is the human's (freeze the Goal, a diagram view, RUN_CONFLICT worktree/resume/abandon, fix DA findings or deliver as-is, approve delivery, a tier change) goes through the host's structured question tool when it has one, so the human clicks instead of typing:
53
+
54
+ - Claude Code: `AskUserQuestion`. Antigravity, Cursor, Codex, Gemini and others: their native ask/options UI when the session offers one.
55
+ - One question per decision; 2-4 options; your recommendation first with "(Recommended)"; each option a short label plus one line on what happens next.
56
+ - CLI JSON that already lists choices (`conflict.options`, `diagramOptions`) maps one option per entry; keep the command each option runs.
57
+ - No such tool: a numbered list with the exact words to reply, recommendation first.
58
+ - Only the human's own answer counts. No answer, a timeout or a changed subject is not approval.
@@ -0,0 +1,9 @@
1
+ # Stage 7: Judge and ITERATE
2
+
3
+ Read when `gate review` says `judgeRequired`, on T2, or when acting on findings.
4
+
5
+ - Otherwise run `npx ai-engineering-loop escalation --json` and resolve the required tier through the host model catalog; if unavailable, escalate to the user. T2 needs STRONG_MODEL.
6
+ - Judge context: only run-summary.md, verification-summary.json (or verification.json), open-findings.json/findings.json, and the Goal hash; it reads the full diff only if those contradict each other. Judge prompt includes "at most 4 tool calls; ledger and contract only; skip css; do not re-review the whole diff".
7
+ - Spawn a fresh sibling Judge, wait, `budget record`, write `RUN_DIR/verdict.json` with `modelTier` and any `judgeFindings`, then `gate judge`. A gate failure overrides optimistic prose.
8
+ - Acting on findings (ITERATE or human MR comments): verify each one before changing code; fix valid ones test-first, decline invalid ones with evidence (skill `ael-receiving-code-review` if installed).
9
+ - ITERATE under the recipe cap: fix in the parent, re-verify, spawn a **new** DA (never resume the previous child). At the cap or NO_PROGRESS, ESCALATE to the human.
@@ -1,8 +1,7 @@
1
1
  # Stages 2-4: Maker
2
2
 
3
3
  - T1/T2: read `docs tdd-policy` before Maker. Use `npx ai-engineering-loop context query <term>` and `context related <file>` before opening broad source files.
4
- - Branch on mode. REPORT_ONLY: never edit repository files; write `RUN_DIR/report.json` with summary and recommendations, then the report review (`loop-report`), run `gate report`, and stop. ASSISTED: the parent (or intern) is Maker; delivery later needs human approval. UNATTENDED: `sandbox create --run <runId>`, Maker works only in the returned worktreePath, never the parent checkout, then `sandbox capture --run <runId>`.
5
- - Maker intern: read `maker_intern` from workflow.md (missing or `none` = parent is Maker). Confirm it through the host model catalog; otherwise the parent is Maker and you report INVOCATION_UNAVAILABLE. The intern cannot skip later gates or spawn DA/Judge.
4
+ - ASSISTED (default): the parent (or intern) is Maker; delivery needs human approval. REPORT_ONLY, UNATTENDED, `maker_intern`: `loop-modes`.
6
5
  - Guardrails: Claude Code enforces them after `hooks install`. Elsewhere, before an out-of-scope edit or a destructive command (`rm -rf`, `DROP TABLE`, `git push --force`, `git reset --hard`, `git clean -fd`) run `guard check --tool edit --path <file>` or `--tool bash --command "<cmd>"`: `warn` = ask the human, `block` = do not run it.
7
6
  - No code comments in product code (C-26): put intent in names, types, tests; rationale in the commit.
8
7
  - Bugs: red repro first. Features: one red test per AC row, then green.
@@ -0,0 +1,6 @@
1
+ # Run modes and the Maker intern
2
+
3
+ Read when the Run is REPORT_ONLY or UNATTENDED, or `workflow.md` names a `maker_intern`.
4
+
5
+ - Branch on mode. REPORT_ONLY: never edit repository files; write `RUN_DIR/report.json` with summary and recommendations, then the report review (`loop-report`), run `gate report`, and stop. ASSISTED: the parent (or intern) is Maker; delivery later needs human approval. UNATTENDED: `sandbox create --run <runId>`, Maker works only in the returned worktreePath, never the parent checkout, then `sandbox capture --run <runId>`.
6
+ - Maker intern: read `maker_intern` from workflow.md (missing or `none` = parent is Maker). Confirm it through the host model catalog; otherwise the parent is Maker and you report INVOCATION_UNAVAILABLE. The intern cannot skip later gates or spawn DA/Judge.
@@ -10,10 +10,6 @@ REPORT_ONLY runs skip these stages; their single report review is in `loop-maker
10
10
  - Iteration 2+: give unresolved findings and new hunks, not the whole diff again.
11
11
  - Wait, `budget record` its usage (or `--unavailable`), save its output to a file, then `review ingest --run <runId> --child-id <id> --file <output> --json` (binds the ledger, runs `gate review`, and `gate judge` when not required). Never drop a finding; dismiss or downgrade only with `dismissal: {by, evidence}`. Report Spec and Standards separately.
12
12
 
13
- ## Judge
13
+ ## Judge and iterate
14
14
 
15
- - Otherwise run `npx ai-engineering-loop escalation --json` and resolve the required tier through the host model catalog; if unavailable, escalate to the user. T2 needs STRONG_MODEL.
16
- - Judge context: only run-summary.md, verification-summary.json (or verification.json), open-findings.json/findings.json, and the Goal hash; it reads the full diff only if those contradict each other. Judge prompt includes "at most 4 tool calls; ledger and contract only; skip css; do not re-review the whole diff".
17
- - Spawn a fresh sibling Judge, wait, `budget record`, write `RUN_DIR/verdict.json` with `modelTier` and any `judgeFindings`, then `gate judge`. A gate failure overrides optimistic prose.
18
- - Acting on findings (ITERATE or human MR comments): verify each one before changing code; fix valid ones test-first, decline invalid ones with evidence (skill `ael-receiving-code-review` if installed).
19
- - ITERATE under the recipe cap: fix in the parent, re-verify, spawn a **new** DA (never resume the previous child). At the cap or NO_PROGRESS, ESCALATE to the human.
15
+ - Judge only when `gate review` says `judgeRequired` or T2, or on ITERATE: `loop-judge`.
package/CHANGELOG.md CHANGED
@@ -6,6 +6,41 @@ All notable changes to this project are documented here. Versions follow [Semant
6
6
 
7
7
  _No changes yet._
8
8
 
9
+ ## 2.14.0 - 2026-11-21
10
+
11
+ Readable Goals for people (ASD-STE100 style) and skill headroom.
12
+
13
+ - **Changed:** `goal draft` and `goal freeze` print the readable Goal (`goal.md`) and the next step by default, everywhere. Agents and scripts pass `--json` for the full JSON (the skill does). Scripts that parsed the old default output must add `--json`.
14
+ - **Added:** a Goal for people. Every `goal draft` writes `RUN_DIR/goal.md` (What changes, Done when with proof and "Fail if" lines, Not in this change, Not confirmed yet), and `goal show --human` prints it. `goal draft` returns `readability` warnings in the style of ASD-STE100 Simplified Technical English (long or passive sentences, vague words, several actions in one sentence); they never block. The JSON for agents is unchanged (`docs goal-contract`, "Writing for people").
15
+ - **Changed:** skill headroom. The Judge and ITERATE steps moved to `loop-judge` (read only when `judgeRequired`, on T2 or on ITERATE), REPORT_ONLY / UNATTENDED / Maker intern to `loop-modes`, and the report header block to `loop-deliver`. SKILL.md 4000 -> 3757 of 4000 chars; T1 context 17853 -> 16626 of 17859. No rule was dropped.
16
+
17
+ ## 2.13.0 - 2026-11-21
18
+
19
+ Newcomer UX from a clean Docker sandbox (cards C-47..C-56 in `docs/cards/novice-ux-2026-11-21.md`; rerun with `scripts/sandbox-e2e.sh`) and "dig first" (C-45, C-46 in `docs/cards/dig-first-2026-11-21.md`).
20
+
21
+ - **Changed:** `deliver` refuses while the reviewed change is not committed, and names the files and the `git add … && git commit` to run (C-47). Commit before `deliver`, as Stage 8 already said.
22
+ - **Changed:** `run` and `quick start` check git first (installed, inside a repo, at least one commit) and stop with WHY/FIX before creating a Run; `status` shows `Git: NOT READY` instead of claiming the context is current, and warns when git identity is missing (C-48).
23
+ - **Changed:** `quick start` on a different task while a Run is unfinished returns `RUN_CONFLICT` (exit 3) with the same options as `run` (C-54).
24
+ - **Added:** README Get Started is three commands (`npm i -g`, `ael setup`, `ael init`); `init`, `status` and `run` say `NOT INSTALLED` and point at `ael setup` when no agent has the skill (C-49).
25
+ - **Added:** `scaffold goal` writes a Goal Contract JSON template to `.ai-engineering-loop/drafts/goal.json`; `goal draft` refuses an unfilled template, explains itself when `--file` is missing, and warns when the draft lives outside `.ai-engineering-loop/`. `docs <name> --section` lists the sections when the name is wrong (C-50, C-55).
26
+ - **Changed:** `doctor` checks your machine (Node, git, git identity, agent skill, adapter CLI and login), and every problem names its FIX; warnings alone print `READY (warnings)`. The release checks moved to `doctor --package` (`npm run doctor`) (C-51).
27
+ - **Changed:** CLI basics (C-52): an unknown command exits 2 with "Did you mean …?" instead of the full help; `ael help [command]` and a short `--help` (`help --all` for everything); bare `ael` in a new folder shows a three-option menu and writes nothing (in an initialised project it shows `status`); `run` with no task and no Run, and `gate` with no name, explain themselves.
28
+ - **Changed:** review handoff (C-53): stage-order errors (`Node X is PENDING, not READY`) carry WHY/FIX naming the next ready stage; `gate judge` after a pass is a no-op that names the next command; `review ingest` on prose shows the minimal ledger.
29
+ - **Changed:** `init` no longer pretends an empty folder is a backend API, warns on an old Node, and tells you to commit the `.gitignore` it created; an untracked `.gitignore` that only ignores AEL stays out of the Maker diff. No colour codes when output is not a terminal or `NO_COLOR` is set; `goal draft`/`goal freeze` print a short summary in a terminal (JSON otherwise, or with `--json`) (C-55, C-56).
30
+ - **Changed:** the skill asks every human decision (freeze, RUN_CONFLICT, fix findings or deliver, approval) through the host's option buttons when it has them (Claude Code `AskUserQuestion`, Antigravity and others' native options), with a numbered fallback (`loop-hosts`, "Asking the human").
31
+ - **Added:** `.ai-engineering-loop/sources.md` (from `init`, `refresh`, `sources refresh`) lists the read-only sources on this machine (code, gh, glab, a Mattermost MCP, AEL history) and keeps your Scope section. `sources hint` / `sources record` with a per-tier gather budget (T0 0, T1 4, T2 8) cached in `runs/<id>/sources.json`; `budget record --role gather` (C-45).
32
+ - **Added:** Goal `statements` labelled fact / decision / assumption. The goal gate checks each fact's source (`path:line`, commit, recorded URL or `S-n`) and downgrades the rest to assumptions, which `status`, the receipt and the review pack show without blocking (C-46).
33
+
34
+ From poteto's live with Matt Pocock (cards C-43 and C-44 in `docs/cards/poteto-live-2026-11-21.md`).
35
+
36
+ - **Added:** `learn --transcripts` (C-44): reads local Claude Code, Cursor and Codex transcripts for this repository, finds corrections the human repeated across sessions, and saves them as candidate lessons (`L-T…`, redacted example only) with a suggested fix level and, for code tokens, a ready `learn promote --forbid-api … --prove <commit>`. `stats` lists the top repeated corrections.
37
+ - **Added:** `driver scaffold [--feature <id>] [--surface web|api|cli|launch]` (C-43): writes `.ai-engineering-loop/drivers/<feature>.mjs` (launch the app, drive the user steps, save evidence under `runs/<id>/evidence/`; exit 0 only when `EXPECT` matches) plus a README naming any gap, and fills the feature map's Driver column. It reuses the project's Playwright or plain `fetch`, adds no dependency, and never overwrites an edited driver (`.ael-new`). `doctor --harness` warns when a Driver command's file is missing and lists features with no driver when an e2e or smoke lane is set.
38
+
39
+ From pstack's scripts (cards C-41, C-42 in `docs/cards/pstack-scripts-2026-11-21.md`).
40
+
41
+ - **Added:** `worktree prune` buckets (C-41): `hold-wip`, `hold-live-run`, `hold-open-pr`, `review`, `scratch`, `safe`, plus size and age per worktree, biggest first. Worktrees with only untracked files are `scratch` and removed only with `--include-scratch`; an open PR holds a worktree; `--audit` lists every git worktree (others as `foreign`, never removed).
42
+ - **Added:** `pr status [--run|--branch|--pr] [--json]` (C-42): one `gh` snapshot with verdict `merged|closed|blocker|waiting|ready` and named blockers; a merged PR writes `runs/<id>/merge.json` once. `worktree prune` uses it to delete squash-merged branches without `gh`; `stats` and `recap` report merged Runs and delivery-to-merge time.
43
+
9
44
  ## 2.12.0 - 2026-11-21
10
45
 
11
46
  Run isolation (cards C-37..C-40 in `docs/cards/run-isolation-2026-11-21.md`, issue #130; `docs run-isolation`).
package/README.md CHANGED
@@ -29,7 +29,15 @@ AI Engineering Loop puts every task on one gated path and keeps the receipts. Yo
29
29
 
30
30
  ## Get started in a minute
31
31
 
32
- Run the command above in any project. Then tell your coding agent:
32
+ In any project:
33
+
34
+ ```bash
35
+ npm i -g ai-engineering-loop # Node 18+ and git required
36
+ ael setup # installs the ael skill into your coding agents
37
+ ael init # writes .ai-engineering-loop/ for this project
38
+ ```
39
+
40
+ Then start a new agent session and tell it:
33
41
 
34
42
  > Use AI Engineering Loop to build this feature: **your idea here**
35
43
 
@@ -6,7 +6,7 @@ For hosts with no subagent tool (certification `instruction-only`). Full skill:
6
6
  Loop: Specify (0-1), Make (2-4), Review (5-7), Deliver (8). You are Maker. Devil's Advocate (DA) and Judge run in this session as `CONTEXT_ISOLATION_ONLY`, with the same budgets; never claim independent review.
7
7
 
8
8
  1. `npx ai-engineering-loop run --json` gives runId, tier, budget. Read `.ai-engineering-loop/glossary.md`.
9
- 2. Goal Contract: AC is a failure table (happy, empty, boundary, error). Only after the human freezes: `goal freeze --latest --run <runId> --by human`. Chat agreement is not freeze.
9
+ 2. Goal Contract: AC is a failure table (happy, empty, boundary, error). Only after the human freezes: `goal freeze --json --latest --run <runId> --by human`. Chat agreement is not freeze.
10
10
  3. Maker: one red test per AC row before the fix, then `gate maker`.
11
11
  4. `verify --cmd <test command>`, then write claimed-vs-reality.md.
12
12
  5. DA: re-read only the diff, Goal, and evidence; log findings; `gate review`. Judge: write the verdict from the evidence, then `gate judge`. ITERATE at most 3 times.