ai-engineering-loop 2.2.0 → 2.4.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/ai-engineering-loop/SKILL.md +4 -4
- package/.agents/skills/ai-engineering-loop/references/loop-deliver.md +2 -2
- package/.agents/skills/ai-engineering-loop/references/loop-goal.md +3 -3
- package/.agents/skills/ai-engineering-loop/references/loop-maker.md +1 -0
- package/.agents/skills/ai-engineering-loop/references/loop-review.md +3 -4
- package/.agents/skills/ai-engineering-loop/references/loop-risky.md +1 -0
- package/.agents/skills/ai-engineering-loop/references/loop-verify.md +3 -3
- package/.claude/agents/judge.md +5 -2
- package/.grok/agents/judge.md +5 -2
- package/CHANGELOG.md +60 -0
- package/README.md +1 -0
- package/THIRD_PARTY_NOTICES.md +11 -0
- package/adapters/spec/LICENSE +202 -0
- package/adapters/spec/NOTICE-AEL.md +26 -0
- package/adapters/spec/agents/ael-spec-codebase-details.md +71 -0
- package/adapters/spec/agents/ael-spec-comprehension.md +71 -0
- package/adapters/spec/agents/ael-spec-design.md +65 -0
- package/adapters/spec/agents/ael-spec-implementation-readiness.md +64 -0
- package/adapters/spec/agents/ael-spec-structural.md +67 -0
- package/adapters/spec/agents/ael-spec-style.md +68 -0
- package/adapters/spec/agents/ael-spec-synthesizer.md +73 -0
- package/adapters/spec/agents/ael-spec-zoom-out.md +76 -0
- package/adapters/spec/skills/ael-spec-brainstorm/SKILL.md +265 -0
- package/adapters/spec/skills/ael-spec-draft/SKILL.md +315 -0
- package/adapters/spec/skills/ael-spec-draft/references/design_doc.md +179 -0
- package/adapters/spec/skills/ael-spec-drift/SKILL.md +68 -0
- package/adapters/spec/skills/ael-spec-resolve/SKILL.md +188 -0
- package/adapters/spec/skills/ael-spec-review/SKILL.md +403 -0
- package/adapters/spec/skills/ael-spec-review-loop/SKILL.md +191 -0
- package/adapters/spec/standards/ael-spec-execution-instructions.md +36 -0
- package/adapters/spec/standards/ael-spec-feature-spec-standard.md +38 -0
- package/adapters/spec/standards/ael-spec-heilmeier-standard.md +32 -0
- package/adapters/spec/standards/ael-spec-implementation-readiness-standard.md +36 -0
- package/adapters/spec/standards/ael-spec-re-implementation-standard.md +39 -0
- package/adapters/spec/standards/ael-spec-zoom-out-standard.md +62 -0
- package/agents/maker.md +1 -1
- package/agents/shared/judge.body.md +5 -2
- package/bin/ai-engineering-loop.js +344 -78
- package/core/definition-of-done.md +2 -2
- package/core/escalation-policy.md +1 -1
- package/core/goal-contract.md +1 -1
- package/core/iteration-policy.md +2 -1
- package/core/judge-policy.md +10 -4
- package/core/orchestration-model.md +8 -7
- package/core/repo-config-schema.md +2 -2
- package/core/runtime-safety.md +3 -3
- package/core/spec-pack.md +47 -0
- package/lib/auto-update.js +8 -14
- package/lib/claimed-vs-reality.js +2 -2
- package/lib/cli-args.js +3 -1
- package/lib/design-ref.js +178 -0
- package/lib/docs.js +1 -1
- package/lib/doctor.js +0 -6
- package/lib/escalation.js +1 -1
- package/lib/fsutil.js +88 -0
- package/lib/gates.js +70 -27
- package/lib/generate-workflow.js +0 -29
- package/lib/goal-runtime.js +8 -2
- package/lib/guard-hooks.js +26 -7
- package/lib/guard.js +100 -10
- package/lib/hosts/doctor.js +17 -7
- package/lib/impact-map.js +31 -8
- package/lib/jsonl-ledger.js +104 -0
- package/lib/learn.js +4 -9
- package/lib/loop-groups.js +0 -25
- package/lib/migrations.js +1 -5
- package/lib/no-progress.js +119 -0
- package/lib/node-evidence.js +1 -5
- package/lib/orchestration.js +5 -361
- package/lib/personal-workflow.js +1 -1
- package/lib/quick.js +152 -0
- package/lib/receipt.js +13 -6
- package/lib/recipe-builder.js +3 -35
- package/lib/recipe-graph.js +2 -63
- package/lib/recipe.js +2 -4
- package/lib/review-ingest.js +116 -0
- package/lib/run-abandon.js +2 -1
- package/lib/run-compaction.js +4 -12
- package/lib/run-interactions.js +16 -71
- package/lib/run-lifecycle.js +25 -77
- package/lib/run-state.js +68 -17
- package/lib/run-watcher.js +11 -14
- package/lib/runtime-files.js +45 -1
- package/lib/safe-context.js +17 -6
- package/lib/sandbox.js +2 -1
- package/lib/smart-context.js +13 -14
- package/lib/spawn-command.js +94 -0
- package/lib/studio-layout.js +2 -8
- package/lib/studio-runtime.js +2 -1
- package/lib/studio-server.js +25 -5
- package/lib/sync-hosts.js +25 -2
- package/lib/tier.js +36 -10
- package/lib/user-state.js +2 -17
- package/lib/verification-lanes.js +115 -0
- package/lib/verification-recorder.js +110 -22
- package/lib/workflow-runtime.js +7 -4
- package/package.json +1 -2
- package/policies/review-budget.md +1 -1
- package/schemas/goal-contract.schema.json +87 -11
- package/.claude/skills/ai-engineering-loop/SKILL.md +0 -62
- package/.claude/skills/ai-engineering-loop/references/loop-commands.md +0 -24
- package/.claude/skills/ai-engineering-loop/references/loop-deliver.md +0 -10
- package/.claude/skills/ai-engineering-loop/references/loop-goal.md +0 -11
- package/.claude/skills/ai-engineering-loop/references/loop-hosts.md +0 -48
- package/.claude/skills/ai-engineering-loop/references/loop-maker.md +0 -14
- package/.claude/skills/ai-engineering-loop/references/loop-review.md +0 -20
- package/.claude/skills/ai-engineering-loop/references/loop-risky.md +0 -9
- package/.claude/skills/ai-engineering-loop/references/loop-verify.md +0 -20
- package/.claude/skills/animate/RECIPES.md +0 -324
- package/.claude/skills/animate/SKILL.md +0 -207
- package/.claude/skills/animate-expo/RECIPES.md +0 -385
- package/.claude/skills/animate-expo/SKILL.md +0 -263
- package/.claude/skills/animation-vocabulary/SKILL.md +0 -181
- package/.claude/skills/apple-design/SKILL.md +0 -290
- package/.claude/skills/ask-sonner/API.md +0 -64
- package/.claude/skills/ask-sonner/SKILL.md +0 -88
- package/.claude/skills/backend-development/SKILL.md +0 -272
- package/.claude/skills/backend-development/references/api-design-guidelines.md +0 -95
- package/.claude/skills/backend-development/references/query-and-database-best-practices.md +0 -53
- package/.claude/skills/backend-development/references/security-checklist.md +0 -60
- package/.claude/skills/emil-design-eng/SKILL.md +0 -674
- package/.claude/skills/find-animation-opportunities/SKILL.md +0 -140
- package/.claude/skills/improve-animations/AUDIT.md +0 -115
- package/.claude/skills/improve-animations/PLAN-TEMPLATE.md +0 -73
- package/.claude/skills/improve-animations/SKILL.md +0 -109
- package/.claude/skills/mobile-native/SKILL.md +0 -311
- package/.claude/skills/pick-ui-library/SKILL.md +0 -85
- package/.claude/skills/prototype/PICKER.md +0 -197
- package/.claude/skills/prototype/SKILL.md +0 -98
- package/.claude/skills/review-animations/SKILL.md +0 -120
- package/.claude/skills/review-animations/STANDARDS.md +0 -187
- package/.claude/skills/write-swift/SKILL.md +0 -396
- package/lib/intern-catalog.js +0 -53
|
@@ -25,18 +25,18 @@ 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): `
|
|
29
|
-
- **T1** normal: frozen Goal, red test, `verify`, lean DA, `
|
|
28
|
+
- **T0** trivial (docs, typo, lint): `quick start "<task>"` (run + `gate goal`), edit, `quick finish`; no subagents.
|
|
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
|
|
|
32
|
-
0. `run --json [--mode report-only|assisted|unattended]` (`RUN_DIR` = `.ai-engineering-loop/runs/<runId>/`). Do not run `sync-hosts` per run; if `hostSkills.stale`, ask the user. Read `.ai-engineering-loop/glossary.md`, plus `lessons.md`/`workflow.md` if present
|
|
32
|
+
0. `run --json [--mode report-only|assisted|unattended]` (`RUN_DIR` = `.ai-engineering-loop/runs/<runId>/`). Do not run `sync-hosts` per run; if `hostSkills.stale`, ask the user. Read `.ai-engineering-loop/glossary.md`, plus `lessons.md`/`workflow.md` if present; heed `learnings`.
|
|
33
33
|
1. Goal Contract: `loop-goal`. 2-4. Maker: `loop-maker`, then `gate maker`. 5. Verify: `loop-verify`. 6-7. DA and Judge: `loop-review`. 8. Deliver: `loop-deliver`.
|
|
34
34
|
|
|
35
35
|
Invariants (every tier):
|
|
36
36
|
- AC is a failure table. Do not freeze sunny-path-only. Chat agreement is not freeze.
|
|
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
|
-
- ITERATE
|
|
39
|
+
- ITERATE to iteration 3 (or the recipe cap), each with a **new** DA.
|
|
40
40
|
- Never infer human approval.
|
|
41
41
|
- After each child `budget record` real usage or `--unavailable`; never invent counts.
|
|
42
42
|
- No secrets or hidden reasoning in activity messages.
|
|
@@ -1,10 +1,10 @@
|
|
|
1
1
|
# Stage 8: Delivery
|
|
2
2
|
|
|
3
|
-
- After Judge PASS, run the `after_pass` hook, then the Stage 8 adapter from `.ai-engineering-loop/adapter.md`.
|
|
3
|
+
- After Judge PASS (and `verify --final` if verification was `--related`), run the `after_pass` hook, then the Stage 8 adapter from `.ai-engineering-loop/adapter.md`.
|
|
4
4
|
- Before any push, run `npx ai-engineering-loop doctor`: `✗ adapter-*` (unknown `adapter_type`, missing spec) must be fixed; `! adapter-*` (gh/glab not logged in, configured type differs from the detected one) needs a human look. `deliver` repeats this check: UNATTENDED stops before writing, ASSISTED only warns.
|
|
5
5
|
- The PR/MR body includes `Steps to Reproduce & Testing (QA)`; bugfix placeholders must not stay empty. Disclose any `budget record --unavailable`.
|
|
6
6
|
- Preview remote payloads; never include context packs, usage ledgers, raw logs, or credentials.
|
|
7
7
|
- ASSISTED: wait for explicit human approval and never infer it. Then one call: `npx ai-engineering-loop deliver --run <runId> --destination <where> --summary <text> --approve --by <name>` (approves READY approval nodes, writes `RUN_DIR/delivery.json` with `humanApproved: true`, runs `gate delivery`). Without `--approve` it refuses in ASSISTED.
|
|
8
8
|
- Long form: `node status --run <runId>`, `node approve delivery-approval --yes --by <name> --run <runId>` for each READY approval node, write `RUN_DIR/delivery.json`, then `gate delivery`. If the gate says a node is not READY, follow its prerequisite hint; never bypass approval.
|
|
9
9
|
- Commit before `deliver` (its receipt binds `HEAD`; screenshots: `--evidence AC-N=<https-url>`). Paste `RUN_DIR/receipt.md` into the PR/MR Receipt section unchanged; ❌ stays ❌ (`docs pr-receipt`).
|
|
10
|
-
- Only the delivery gate completes the run.
|
|
10
|
+
- Only the delivery gate completes the run. It also mines lessons for the next Run.
|
|
@@ -4,8 +4,8 @@
|
|
|
4
4
|
- Ambiguous task the user can answer: grill first (`docs grill-policy`): design tree, recommended answers, never ask look-up facts. T2 adds `loop-risky`.
|
|
5
5
|
- If the user prompt has no numbered AC, draft the contract (`docs goal-contract` if needed), list it, and wait. Chat agreement is not freeze.
|
|
6
6
|
- 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.
|
|
7
|
-
-
|
|
8
|
-
- Wait for the explicit human freeze, then `npx ai-engineering-loop goal freeze --latest --run <runId> --by
|
|
9
|
-
-
|
|
7
|
+
- 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.
|
|
8
|
+
- 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`.
|
|
9
|
+
- 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`).
|
|
10
10
|
- Do not edit production code until the Goal gate passes.
|
|
11
11
|
- 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.
|
|
@@ -6,6 +6,7 @@
|
|
|
6
6
|
- 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
7
|
- Bugs: red repro first. Features: one red test per AC row, then green.
|
|
8
8
|
- After package and manifest edits are stable, run `npx ai-engineering-loop refresh` once (drift during red-green is expected; do not refresh per test cycle).
|
|
9
|
+
- `eslint --fix` and other auto-fixers run before `gate maker`, never after.
|
|
9
10
|
- ASSISTED: `npx ai-engineering-loop gate maker --from-git` writes the exact working-tree diff (tracked and new files, excluding `.ai-engineering-loop/`) to `RUN_DIR/diff.patch` and gates it; or write that file yourself and run `gate maker`. UNATTENDED: `sandbox capture` writes it, then `gate maker`. The gate can raise the tier from the diff.
|
|
10
11
|
|
|
11
12
|
## REPORT_ONLY report review (recipe `audit`)
|
|
@@ -8,13 +8,12 @@ REPORT_ONLY runs skip these stages; their single report review is in `loop-maker
|
|
|
8
8
|
- Use the runtime policy `reviewProfile` (default `lean`); upgrade to `standard` or `thorough` only when the human asks or the budget gate requires it.
|
|
9
9
|
- Spawn a new DA as a sibling (Host rules) with the pack path, the changed paths as a short list, and claimed-vs-reality.md. Do not paste Maker rationale. DA prompt includes "at most 8 tool calls; read the diff file; skip css and generated files".
|
|
10
10
|
- Iteration 2+: give unresolved findings and new hunks, not the whole diff again.
|
|
11
|
-
- Wait, `budget record` its usage (or `--unavailable`),
|
|
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
13
|
## Judge
|
|
14
14
|
|
|
15
|
-
- T0, or T1 when `gate review --json` reports `judgeRequired: false`: run `gate judge`; the CLI writes the deterministic verdict.
|
|
16
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.
|
|
17
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".
|
|
18
|
-
- Spawn a fresh sibling Judge, wait, `budget record`, write `RUN_DIR/verdict.json` with `modelTier`, then `gate judge`. A gate failure overrides optimistic prose.
|
|
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.
|
|
19
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).
|
|
20
|
-
- ITERATE
|
|
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.
|
|
@@ -7,3 +7,4 @@ Applies to HIGH_RISK_PATH changes (auth, payments, migrations, secrets, infra),
|
|
|
7
7
|
- Full DA (not the T1 lean shortcut) and Judge on STRONG_MODEL resolved through the host model catalog; if unavailable, escalate to the user. Never run the deterministic Judge for T2.
|
|
8
8
|
- UNATTENDED: sandbox worktree only, and `budget pause` is the kill switch (`docs runtime-safety`).
|
|
9
9
|
- The tier never falls back once raised.
|
|
10
|
+
- New feature or architecture: suggest a reviewed design first (`docs spec-pack`), then `goal draft --from-design <doc>`.
|
|
@@ -1,10 +1,10 @@
|
|
|
1
1
|
# Stage 5: Verification
|
|
2
2
|
|
|
3
|
-
-
|
|
4
|
-
-
|
|
3
|
+
- `npx ai-engineering-loop verify --run <runId> [--cmd "<command>"]...` (default `test_unit` from verification.md) records commands in parallel (`--serial`, `--shell`), binds redacted evidence to the gated diff, and only when all pass gates verification, compacts, and scaffolds claimed-vs-reality.
|
|
4
|
+
- Iterating (T1/T2): `verify --related` runs `test_related` on the diff's changed files. After Judge PASS, `verify --final` runs the full suite once; delivery requires it after related-only runs. Unchanged diff: passes are reused (`--fresh` re-runs).
|
|
5
5
|
- A failed command is recorded honestly and returns non-zero; it cannot pass the gate. Vague "seems green" is invalid.
|
|
6
6
|
- Fill `.ai-engineering-loop/tasks/claimed-vs-reality.md`: Claimed from the actual change, Reality from command output. Do not spawn DA while the file is missing or any Claimed row lacks Reality.
|
|
7
|
-
- Hand-authored artifacts: `scaffold verification|findings|delivery --run <runId
|
|
7
|
+
- Hand-authored artifacts: `scaffold verification|findings|delivery --run <runId>`, fill it, remove `_templateOnly`, then `validate <file>`. Templates are never evidence.
|
|
8
8
|
- Pass run-summary.md and verification-summary.json to reviewers instead of raw logs.
|
|
9
9
|
|
|
10
10
|
## No claim without fresh evidence
|
package/.claude/agents/judge.md
CHANGED
|
@@ -21,11 +21,13 @@ AC source is the Goal Contract **file** only. Chat `setuju` and the parent trans
|
|
|
21
21
|
|
|
22
22
|
ITERATE if verification is missing, vague, non-zero, proves a different artifact than the AC names, is only a source grep, or is happy-path-only while the Goal Contract lists empty, boundary, sibling, or error rows. ITERATE if claimed-vs-reality.md is missing or a Claimed row has empty Reality.
|
|
23
23
|
|
|
24
|
+
The gate recomputes the verdict from the ledger. To block on a problem the ledger lacks (wrong-artifact or happy-path-only evidence, an AC the tests do not prove), add it to `judgeFindings` in the Finding Ledger shape: VALID, BLOCKER or HIGH, with `location`, `failureScenario`, `evidence`, and `concreteAlternativeDiff`. A verdict that blocks without such a finding is rejected. You cannot PASS what the ledger blocks.
|
|
25
|
+
|
|
24
26
|
## Axes
|
|
25
27
|
|
|
26
28
|
Do not merge Spec and Standards into one ranking.
|
|
27
29
|
|
|
28
|
-
- Spec VALID BLOCKER or HIGH (or missing axis, treated as spec): ITERATE (ESCALATE
|
|
30
|
+
- Spec VALID BLOCKER or HIGH (or missing axis, treated as spec): ITERATE (ESCALATE at the recipe's iteration cap, default 3)
|
|
29
31
|
- Standards VALID BLOCKER or HIGH: ITERATE only when hardConvention is true
|
|
30
32
|
- Other Standards findings: ACCEPT as tradeoff; may still PASS
|
|
31
33
|
- INVALID findings: DISMISS, cannot block delivery
|
|
@@ -44,7 +46,8 @@ Return a fenced JSON block:
|
|
|
44
46
|
"action": "Proceed to context impact assessment and delivery adapter",
|
|
45
47
|
"blockingFindings": [],
|
|
46
48
|
"acceptableTradeoffs": [],
|
|
47
|
-
"dismissedFindings": []
|
|
49
|
+
"dismissedFindings": [],
|
|
50
|
+
"judgeFindings": []
|
|
48
51
|
}
|
|
49
52
|
```
|
|
50
53
|
|
package/.grok/agents/judge.md
CHANGED
|
@@ -22,11 +22,13 @@ AC source is the Goal Contract **file** only. Chat `setuju` and the parent trans
|
|
|
22
22
|
|
|
23
23
|
ITERATE if verification is missing, vague, non-zero, proves a different artifact than the AC names, is only a source grep, or is happy-path-only while the Goal Contract lists empty, boundary, sibling, or error rows. ITERATE if claimed-vs-reality.md is missing or a Claimed row has empty Reality.
|
|
24
24
|
|
|
25
|
+
The gate recomputes the verdict from the ledger. To block on a problem the ledger lacks (wrong-artifact or happy-path-only evidence, an AC the tests do not prove), add it to `judgeFindings` in the Finding Ledger shape: VALID, BLOCKER or HIGH, with `location`, `failureScenario`, `evidence`, and `concreteAlternativeDiff`. A verdict that blocks without such a finding is rejected. You cannot PASS what the ledger blocks.
|
|
26
|
+
|
|
25
27
|
## Axes
|
|
26
28
|
|
|
27
29
|
Do not merge Spec and Standards into one ranking.
|
|
28
30
|
|
|
29
|
-
- Spec VALID BLOCKER or HIGH (or missing axis, treated as spec): ITERATE (ESCALATE
|
|
31
|
+
- Spec VALID BLOCKER or HIGH (or missing axis, treated as spec): ITERATE (ESCALATE at the recipe's iteration cap, default 3)
|
|
30
32
|
- Standards VALID BLOCKER or HIGH: ITERATE only when hardConvention is true
|
|
31
33
|
- Other Standards findings: ACCEPT as tradeoff; may still PASS
|
|
32
34
|
- INVALID findings: DISMISS, cannot block delivery
|
|
@@ -45,7 +47,8 @@ Return a fenced JSON block:
|
|
|
45
47
|
"action": "Proceed to context impact assessment and delivery adapter",
|
|
46
48
|
"blockingFindings": [],
|
|
47
49
|
"acceptableTradeoffs": [],
|
|
48
|
-
"dismissedFindings": []
|
|
50
|
+
"dismissedFindings": [],
|
|
51
|
+
"judgeFindings": []
|
|
49
52
|
}
|
|
50
53
|
```
|
|
51
54
|
|
package/CHANGELOG.md
CHANGED
|
@@ -6,6 +6,66 @@ All notable changes to this project are documented here. Versions follow [Semant
|
|
|
6
6
|
|
|
7
7
|
_No changes yet._
|
|
8
8
|
|
|
9
|
+
## 2.4.0 - 2026-11-02
|
|
10
|
+
|
|
11
|
+
### Spec pack: design before code (EGM fork)
|
|
12
|
+
|
|
13
|
+
- **Added:** opt-in `spec` host pack (`sync-hosts --pack spec`, #96): six host-neutral skills, `ael-spec-brainstorm`, `ael-spec-draft`, `ael-spec-review`, `ael-spec-review-loop`, `ael-spec-resolve` and `ael-spec-drift`, derived from Google's Elephant-Goldfish Model through the fork [egagofur/elephant-goldfish-model](https://github.com/egagofur/elephant-goldfish-model) (Apache-2.0). Reviewer personas and document standards are `ael-spec-*` docs (`docs ael-spec-zoom-out`). On a host without a subagent tool the reviews run one at a time in-session, labelled `CONTEXT_ISOLATION_ONLY`, instead of stopping. Core and T0/T1 runs are unchanged.
|
|
14
|
+
- **Internal:** `vendor/egm/` holds the pinned fork files (not shipped); `scripts/sync-spec-pack.js` regenerates `adapters/spec/`, `--check` fails on stale output, and `--pull [ref]` refreshes the vendor copy.
|
|
15
|
+
|
|
16
|
+
### Design documents as Goal input
|
|
17
|
+
|
|
18
|
+
- **Added:** `goal draft --from-design <doc.md>` (#97) prefills a Goal draft from a design document: objective from the title and first goal, one acceptance row per Test Plan item (or per goal), `outOfScope` from Non-Goals, and `designRef { path, sha256, targetFiles }` from the Target Scope file paths. With `--file`, the given contract keeps its rows and only gains `designRef`. Missing, outside-the-repo, symlinked, non-Markdown or >256 KB documents are refused.
|
|
19
|
+
- **Added:** `goal freeze` refuses rows that still contain `<fill: …>` placeholders (`GOAL_PLACEHOLDERS`); `goal show` reports `design.designChanged` when the document changed after drafting. Goals without `designRef` behave as before.
|
|
20
|
+
|
|
21
|
+
### Design drift
|
|
22
|
+
|
|
23
|
+
- **Added:** when the frozen Goal has `designRef` (#98), `impact drift` (run with `verify`) also records `design { path, docChanged, planned, unplanned[], untouched[] }` in `impact-drift.json`: changed files outside the design's plan and planned files nobody touched. The review pack shows it as two short lines for the Devil's Advocate and `receipt.json` carries the counts under `impact.design`. It is informational: no ledger finding, no gate failure. Runs without `designRef` are unchanged.
|
|
24
|
+
|
|
25
|
+
### Spec pack hint and doctor status
|
|
26
|
+
|
|
27
|
+
- **Added:** a new T2 Run prints one `specHint` (`run --json`) suggesting `ael-spec-brainstorm -> ael-spec-draft -> ael-spec-review` and `goal draft --from-design` (#99), plus the install command when the `spec` pack is missing. T0/T1 and resumed Runs print nothing new.
|
|
28
|
+
- **Added:** `hosts doctor` rows carry `spec { installed, reviewMode }` (`FRESH_SUBAGENT`, or `CONTEXT_ISOLATION_ONLY` on instruction-only hosts) and the text report names the install command when no host has the pack. It never changes `ok`.
|
|
29
|
+
|
|
30
|
+
### Spec pack guide
|
|
31
|
+
|
|
32
|
+
- **Docs:** `npx ai-engineering-loop docs spec-pack` (#100): when to use the `spec` pack and when not, the flow from `ael-spec-brainstorm` to `goal draft --from-design` and `ael-spec-drift`, the host fallback, and how to pull upstream EGM updates. README and the T2 reference (`loop-risky`) point at it; `THIRD_PARTY_NOTICES.md` lists every shipped EGM-derived file.
|
|
33
|
+
|
|
34
|
+
## 2.3.0 - 2026-10-21
|
|
35
|
+
|
|
36
|
+
### Security
|
|
37
|
+
|
|
38
|
+
- Studio: mutating requests now need the `x-ael-studio-token` header or an exact same-origin `Origin`, plus `content-type: application/json`. The SameSite cookie alone no longer authorizes a POST from another localhost port.
|
|
39
|
+
- Secret redaction covers JSON keys (`{"password":"…"}`), key names embedded in identifiers (`AWS_SECRET_ACCESS_KEY=`, `_password`, `clientSecret`), npm `npm_` tokens, Stripe `sk_live_`/`rk_live_` keys, Slack `xox*` tokens, JWTs, and credentials in URLs (`postgres://user:pass@host`).
|
|
40
|
+
- Guard: agent edits to CLI-owned Run evidence (`verification.json`, `state.json`, event ledgers, and others) are denied; `\rm -rf`, `find -delete`, `git checkout -- .`, `git restore`, and `git branch -D` are detected; a failing hook exits 2 (fail closed) outside ASSISTED; `hooks install` pins the hook command to the installed version.
|
|
41
|
+
|
|
42
|
+
### Fixed
|
|
43
|
+
|
|
44
|
+
- `verification record` timeouts stop the whole process tree (process group on POSIX, `taskkill /T` on Windows) and no longer hang on a grandchild that holds the output pipes.
|
|
45
|
+
- Concurrent `verification record` calls and Run state updates no longer lose each other's writes: both re-read under a lock before writing.
|
|
46
|
+
- An unterminated last line in `events.jsonl`, `lifecycle.jsonl`, or `interactions.jsonl` (crash mid-append) no longer bricks the Run; the next append quarantines it to `<ledger>.torn-*`.
|
|
47
|
+
- Windows: `npm` and other `.cmd` shims are resolved for `verification record` and auto-update; atomic writes retry a transient `EPERM`/`EBUSY` rename.
|
|
48
|
+
- Studio live snapshots show the newest 100 lifecycle events, and the watcher seeds its cursor from the latest event, so long Runs no longer replay stale events.
|
|
49
|
+
|
|
50
|
+
### Lighter package and faster hook calls
|
|
51
|
+
|
|
52
|
+
- **Changed:** the npm package ships one copy of the host skills (`.agents/skills`, which `sync-hosts` already installs from) instead of two identical trees: 247 files, 1.79 MB unpacked (was 279 files, 2.11 MB). `docs` and `doctor` read `.agents/skills`.
|
|
53
|
+
- **Changed:** the CLI loads command modules on first use. `guard check --hook` now loads 15 modules instead of 61.
|
|
54
|
+
- **Removed:** internal helpers that only tests called (capability selection and report formatting in `lib/orchestration.js`, `lib/intern-catalog.js`, recipe import plan/apply, loop-group create/remove, and a few single-use exports). CLI behaviour is unchanged.
|
|
55
|
+
- **Internal:** one atomic writer, sha256 helper, optional JSON reader and actor-id rule (`lib/fsutil.js`), and one hash-chained JSONL ledger for run interactions and lifecycle (`lib/jsonl-ledger.js`).
|
|
56
|
+
|
|
57
|
+
### Lower ceremony, faster verification, tamper-resistant review
|
|
58
|
+
|
|
59
|
+
- **Added:** `verify --related` runs the project's `test_related` command (`{files}` = changed files of the gated diff; `init` writes it for Jest and Vitest), tagged `scope: related`. When verification was related-only, `gate delivery` needs `verify --final`, a single full run bound to the same diff. Re-running `verify` on an unchanged diff reuses passing commands (`--fresh` re-runs them); a superseded failure stays in `verification.json` under `superseded`.
|
|
60
|
+
- **Added:** `quick start "<task>"` / `quick finish` take a T0 task through the same gates in two calls: a Goal derived from the task, verify, claimed-vs-reality from the recorded output, review, and the deterministic Judge. T0 parent calls in `npm run measure`: 15 → 6.
|
|
61
|
+
- **Added:** `review ingest --child-id <id> --file <output>` binds `findings.json` to the Devil's Advocate output (`reviewer.rawSha256`, `review-raw.txt`), gates review, and gates the Judge when not required. The review gate rejects a dropped finding, or one downgraded without `dismissal.evidence` (`LEDGER_TAMPERED`). UNATTENDED refuses unbound ledgers; ASSISTED reports `ledgerBinding: UNBOUND`.
|
|
62
|
+
- **Added:** `verdict.json` may carry `judgeFindings`, so the Judge can block with evidence the ledger lacks. It still cannot PASS what the ledger blocks.
|
|
63
|
+
- **Added:** `goal draft` returns an `impactPreview` and persists the freeze question; `goal freeze --confirm-impact` accepts the blast radius in the same human stop and closes the question.
|
|
64
|
+
- **Changed:** the iteration cap comes from the recipe's Judge loop group (`maxIterations`, clamped to 1-5; default 3). An ITERATE that repeats the previous Maker diff or blocking findings escalates as `NO_PROGRESS` (`RUN_DIR/iterations.jsonl`).
|
|
65
|
+
- **Changed:** runs that end DELIVERED or ESCALATED mine learnings automatically (`AEL_NO_AUTO_LEARN=1` opts out); `run --json` reports the top `learnings`.
|
|
66
|
+
- **Changed:** tier classification is path-first. Docs-only paths stay T0 even when the task names a risky topic; prose under a risky directory is not a risky path; dependency manifests and lockfiles are never T0; trivial-plus-risky text without paths starts at T1.
|
|
67
|
+
- **Fixed:** spec contradictions: no `tasks/current.diff`, one severity vocabulary (BLOCKER/HIGH, formerly SEV-1/SEV-2), auto-fixing linters before `gate maker`, the CONTEXT_ISOLATION_ONLY header no longer contains a forbidden word, and the Judge matrix covers every MEDIUM/LOW disposition.
|
|
68
|
+
|
|
9
69
|
## 2.2.0 - 2026-10-18
|
|
10
70
|
|
|
11
71
|
### Studio: richer node detail, Live tab, times, and trackpad gestures (#91)
|
package/README.md
CHANGED
|
@@ -206,6 +206,7 @@ Agents you install later are noticed by `status` and the background `update auto
|
|
|
206
206
|
npx ai-engineering-loop sync-hosts --pack backend # framework-agnostic backend best practices
|
|
207
207
|
npx ai-engineering-loop sync-hosts --pack backend,design # plus Emil Kowalski's MIT-licensed design/animation skills
|
|
208
208
|
npx ai-engineering-loop sync-hosts --pack quality # ael-code-simplifier + ael-receiving-code-review (opt-in)
|
|
209
|
+
npx ai-engineering-loop sync-hosts --pack spec # ael-spec-* design-doc skills from the EGM fork (docs spec-pack)
|
|
209
210
|
npx ai-engineering-loop sync-hosts --pack core --prune # drop unmodified optional-pack files again
|
|
210
211
|
```
|
|
211
212
|
|
package/THIRD_PARTY_NOTICES.md
CHANGED
|
@@ -9,6 +9,17 @@ AEL vendors design and animation skills from `emilkowalski/skills` so `ai-engine
|
|
|
9
9
|
|
|
10
10
|
The vendored skill text remains authored by the original project. See the upstream repository for updates and full project context.
|
|
11
11
|
|
|
12
|
+
## google/elephant-goldfish-model (Elephant-Goldfish Model, EGM)
|
|
13
|
+
|
|
14
|
+
AEL ships a modified derivative of EGM as the opt-in `spec` host pack (`sync-hosts --pack spec`, issue #96).
|
|
15
|
+
|
|
16
|
+
- Upstream: https://github.com/google/elephant-goldfish-model (Copyright Google LLC; not an officially supported Google product)
|
|
17
|
+
- Fork vendored: https://github.com/egagofur/elephant-goldfish-model at the commit in `vendor/egm/UPSTREAM.json`
|
|
18
|
+
- License: Apache License 2.0, shipped as `adapters/spec/LICENSE`; modifications listed in `adapters/spec/NOTICE-AEL.md`
|
|
19
|
+
- Modifications: skills and personas renamed `egm-*` to `ael-spec-*` (`egm-drift-report` to `ael-spec-drift`), plugin-root and harness-specific references replaced with `ai-engineering-loop docs` lookups and AEL host rules, and a disclosed same-session fallback (`CONTEXT_ISOLATION_ONLY`) where a host has no subagent tool. `egm-bootstrap`, plugin manifests, tests and icons are not shipped.
|
|
20
|
+
- AEL files shipped: `adapters/spec/skills/ael-spec-{brainstorm,draft,review,review-loop,resolve,drift}/SKILL.md`, `adapters/spec/skills/ael-spec-draft/references/design_doc.md`, `adapters/spec/agents/ael-spec-*.md` (8 reviewer personas), `adapters/spec/standards/ael-spec-*.md` (5 document standards and the execution instructions), `adapters/spec/LICENSE` and `adapters/spec/NOTICE-AEL.md`. They are generated by `scripts/sync-spec-pack.js`; every file names the source commit and the skills keep `license: Apache-2.0`.
|
|
21
|
+
- Original AEL text (not derived from EGM): `core/spec-pack.md`, `lib/design-ref.js` (`goal draft --from-design`), design drift in `lib/impact-map.js`, and the spec status in `hosts doctor`.
|
|
22
|
+
|
|
12
23
|
## Adopted skill ideas (issue #36)
|
|
13
24
|
|
|
14
25
|
The following AEL files were written fresh for AEL. No upstream text was copied. They adapt ideas from the projects below, which are credited here.
|
|
@@ -0,0 +1,202 @@
|
|
|
1
|
+
|
|
2
|
+
Apache License
|
|
3
|
+
Version 2.0, January 2004
|
|
4
|
+
http://www.apache.org/licenses/
|
|
5
|
+
|
|
6
|
+
TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
|
|
7
|
+
|
|
8
|
+
1. Definitions.
|
|
9
|
+
|
|
10
|
+
"License" shall mean the terms and conditions for use, reproduction,
|
|
11
|
+
and distribution as defined by Sections 1 through 9 of this document.
|
|
12
|
+
|
|
13
|
+
"Licensor" shall mean the copyright owner or entity authorized by
|
|
14
|
+
the copyright owner that is granting the License.
|
|
15
|
+
|
|
16
|
+
"Legal Entity" shall mean the union of the acting entity and all
|
|
17
|
+
other entities that control, are controlled by, or are under common
|
|
18
|
+
control with that entity. For the purposes of this definition,
|
|
19
|
+
"control" means (i) the power, direct or indirect, to cause the
|
|
20
|
+
direction or management of such entity, whether by contract or
|
|
21
|
+
otherwise, or (ii) ownership of fifty percent (50%) or more of the
|
|
22
|
+
outstanding shares, or (iii) beneficial ownership of such entity.
|
|
23
|
+
|
|
24
|
+
"You" (or "Your") shall mean an individual or Legal Entity
|
|
25
|
+
exercising permissions granted by this License.
|
|
26
|
+
|
|
27
|
+
"Source" form shall mean the preferred form for making modifications,
|
|
28
|
+
including but not limited to software source code, documentation
|
|
29
|
+
source, and configuration files.
|
|
30
|
+
|
|
31
|
+
"Object" form shall mean any form resulting from mechanical
|
|
32
|
+
transformation or translation of a Source form, including but
|
|
33
|
+
not limited to compiled object code, generated documentation,
|
|
34
|
+
and conversions to other media types.
|
|
35
|
+
|
|
36
|
+
"Work" shall mean the work of authorship, whether in Source or
|
|
37
|
+
Object form, made available under the License, as indicated by a
|
|
38
|
+
copyright notice that is included in or attached to the work
|
|
39
|
+
(an example is provided in the Appendix below).
|
|
40
|
+
|
|
41
|
+
"Derivative Works" shall mean any work, whether in Source or Object
|
|
42
|
+
form, that is based on (or derived from) the Work and for which the
|
|
43
|
+
editorial revisions, annotations, elaborations, or other modifications
|
|
44
|
+
represent, as a whole, an original work of authorship. For the purposes
|
|
45
|
+
of this License, Derivative Works shall not include works that remain
|
|
46
|
+
separable from, or merely link (or bind by name) to the interfaces of,
|
|
47
|
+
the Work and Derivative Works thereof.
|
|
48
|
+
|
|
49
|
+
"Contribution" shall mean any work of authorship, including
|
|
50
|
+
the original version of the Work and any modifications or additions
|
|
51
|
+
to that Work or Derivative Works thereof, that is intentionally
|
|
52
|
+
submitted to Licensor for inclusion in the Work by the copyright owner
|
|
53
|
+
or by an individual or Legal Entity authorized to submit on behalf of
|
|
54
|
+
the copyright owner. For the purposes of this definition, "submitted"
|
|
55
|
+
means any form of electronic, verbal, or written communication sent
|
|
56
|
+
to the Licensor or its representatives, including but not limited to
|
|
57
|
+
communication on electronic mailing lists, source code control systems,
|
|
58
|
+
and issue tracking systems that are managed by, or on behalf of, the
|
|
59
|
+
Licensor for the purpose of discussing and improving the Work, but
|
|
60
|
+
excluding communication that is conspicuously marked or otherwise
|
|
61
|
+
designated in writing by the copyright owner as "Not a Contribution."
|
|
62
|
+
|
|
63
|
+
"Contributor" shall mean Licensor and any individual or Legal Entity
|
|
64
|
+
on behalf of whom a Contribution has been received by Licensor and
|
|
65
|
+
subsequently incorporated within the Work.
|
|
66
|
+
|
|
67
|
+
2. Grant of Copyright License. Subject to the terms and conditions of
|
|
68
|
+
this License, each Contributor hereby grants to You a perpetual,
|
|
69
|
+
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
|
|
70
|
+
copyright license to reproduce, prepare Derivative Works of,
|
|
71
|
+
publicly display, publicly perform, sublicense, and distribute the
|
|
72
|
+
Work and such Derivative Works in Source or Object form.
|
|
73
|
+
|
|
74
|
+
3. Grant of Patent License. Subject to the terms and conditions of
|
|
75
|
+
this License, each Contributor hereby grants to You a perpetual,
|
|
76
|
+
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
|
|
77
|
+
(except as stated in this section) patent license to make, have made,
|
|
78
|
+
use, offer to sell, sell, import, and otherwise transfer the Work,
|
|
79
|
+
where such license applies only to those patent claims licensable
|
|
80
|
+
by such Contributor that are necessarily infringed by their
|
|
81
|
+
Contribution(s) alone or by combination of their Contribution(s)
|
|
82
|
+
with the Work to which such Contribution(s) was submitted. If You
|
|
83
|
+
institute patent litigation against any entity (including a
|
|
84
|
+
cross-claim or counterclaim in a lawsuit) alleging that the Work
|
|
85
|
+
or a Contribution incorporated within the Work constitutes direct
|
|
86
|
+
or contributory patent infringement, then any patent licenses
|
|
87
|
+
granted to You under this License for that Work shall terminate
|
|
88
|
+
as of the date such litigation is filed.
|
|
89
|
+
|
|
90
|
+
4. Redistribution. You may reproduce and distribute copies of the
|
|
91
|
+
Work or Derivative Works thereof in any medium, with or without
|
|
92
|
+
modifications, and in Source or Object form, provided that You
|
|
93
|
+
meet the following conditions:
|
|
94
|
+
|
|
95
|
+
(a) You must give any other recipients of the Work or
|
|
96
|
+
Derivative Works a copy of this License; and
|
|
97
|
+
|
|
98
|
+
(b) You must cause any modified files to carry prominent notices
|
|
99
|
+
stating that You changed the files; and
|
|
100
|
+
|
|
101
|
+
(c) You must retain, in the Source form of any Derivative Works
|
|
102
|
+
that You distribute, all copyright, patent, trademark, and
|
|
103
|
+
attribution notices from the Source form of the Work,
|
|
104
|
+
excluding those notices that do not pertain to any part of
|
|
105
|
+
the Derivative Works; and
|
|
106
|
+
|
|
107
|
+
(d) If the Work includes a "NOTICE" text file as part of its
|
|
108
|
+
distribution, then any Derivative Works that You distribute must
|
|
109
|
+
include a readable copy of the attribution notices contained
|
|
110
|
+
within such NOTICE file, excluding those notices that do not
|
|
111
|
+
pertain to any part of the Derivative Works, in at least one
|
|
112
|
+
of the following places: within a NOTICE text file distributed
|
|
113
|
+
as part of the Derivative Works; within the Source form or
|
|
114
|
+
documentation, if provided along with the Derivative Works; or,
|
|
115
|
+
within a display generated by the Derivative Works, if and
|
|
116
|
+
wherever such third-party notices normally appear. The contents
|
|
117
|
+
of the NOTICE file are for informational purposes only and
|
|
118
|
+
do not modify the License. You may add Your own attribution
|
|
119
|
+
notices within Derivative Works that You distribute, alongside
|
|
120
|
+
or as an addendum to the NOTICE text from the Work, provided
|
|
121
|
+
that such additional attribution notices cannot be construed
|
|
122
|
+
as modifying the License.
|
|
123
|
+
|
|
124
|
+
You may add Your own copyright statement to Your modifications and
|
|
125
|
+
may provide additional or different license terms and conditions
|
|
126
|
+
for use, reproduction, or distribution of Your modifications, or
|
|
127
|
+
for any such Derivative Works as a whole, provided Your use,
|
|
128
|
+
reproduction, and distribution of the Work otherwise complies with
|
|
129
|
+
the conditions stated in this License.
|
|
130
|
+
|
|
131
|
+
5. Submission of Contributions. Unless You explicitly state otherwise,
|
|
132
|
+
any Contribution intentionally submitted for inclusion in the Work
|
|
133
|
+
by You to the Licensor shall be under the terms and conditions of
|
|
134
|
+
this License, without any additional terms or conditions.
|
|
135
|
+
Notwithstanding the above, nothing herein shall supersede or modify
|
|
136
|
+
the terms of any separate license agreement you may have executed
|
|
137
|
+
with Licensor regarding such Contributions.
|
|
138
|
+
|
|
139
|
+
6. Trademarks. This License does not grant permission to use the trade
|
|
140
|
+
names, trademarks, service marks, or product names of the Licensor,
|
|
141
|
+
except as required for reasonable and customary use in describing the
|
|
142
|
+
origin of the Work and reproducing the content of the NOTICE file.
|
|
143
|
+
|
|
144
|
+
7. Disclaimer of Warranty. Unless required by applicable law or
|
|
145
|
+
agreed to in writing, Licensor provides the Work (and each
|
|
146
|
+
Contributor provides its Contributions) on an "AS IS" BASIS,
|
|
147
|
+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
|
|
148
|
+
implied, including, without limitation, any warranties or conditions
|
|
149
|
+
of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
|
|
150
|
+
PARTICULAR PURPOSE. You are solely responsible for determining the
|
|
151
|
+
appropriateness of using or redistributing the Work and assume any
|
|
152
|
+
risks associated with Your exercise of permissions under this License.
|
|
153
|
+
|
|
154
|
+
8. Limitation of Liability. In no event and under no legal theory,
|
|
155
|
+
whether in tort (including negligence), contract, or otherwise,
|
|
156
|
+
unless required by applicable law (such as deliberate and grossly
|
|
157
|
+
negligent acts) or agreed to in writing, shall any Contributor be
|
|
158
|
+
liable to You for damages, including any direct, indirect, special,
|
|
159
|
+
incidental, or consequential damages of any character arising as a
|
|
160
|
+
result of this License or out of the use or inability to use the
|
|
161
|
+
Work (including but not limited to damages for loss of goodwill,
|
|
162
|
+
work stoppage, computer failure or malfunction, or any and all
|
|
163
|
+
other commercial damages or losses), even if such Contributor
|
|
164
|
+
has been advised of the possibility of such damages.
|
|
165
|
+
|
|
166
|
+
9. Accepting Warranty or Additional Liability. While redistributing
|
|
167
|
+
the Work or Derivative Works thereof, You may choose to offer,
|
|
168
|
+
and charge a fee for, acceptance of support, warranty, indemnity,
|
|
169
|
+
or other liability obligations and/or rights consistent with this
|
|
170
|
+
License. However, in accepting such obligations, You may act only
|
|
171
|
+
on Your own behalf and on Your sole responsibility, not on behalf
|
|
172
|
+
of any other Contributor, and only if You agree to indemnify,
|
|
173
|
+
defend, and hold each Contributor harmless for any liability
|
|
174
|
+
incurred by, or claims asserted against, such Contributor by reason
|
|
175
|
+
of your accepting any such warranty or additional liability.
|
|
176
|
+
|
|
177
|
+
END OF TERMS AND CONDITIONS
|
|
178
|
+
|
|
179
|
+
APPENDIX: How to apply the Apache License to your work.
|
|
180
|
+
|
|
181
|
+
To apply the Apache License to your work, attach the following
|
|
182
|
+
boilerplate notice, with the fields enclosed by brackets "[]"
|
|
183
|
+
replaced with your own identifying information. (Don't include
|
|
184
|
+
the brackets!) The text should be enclosed in the appropriate
|
|
185
|
+
comment syntax for the file format. We also recommend that a
|
|
186
|
+
file or class name and description of purpose be included on the
|
|
187
|
+
same "printed page" as the copyright notice for easier
|
|
188
|
+
identification within third-party archives.
|
|
189
|
+
|
|
190
|
+
Copyright [yyyy] [name of copyright owner]
|
|
191
|
+
|
|
192
|
+
Licensed under the Apache License, Version 2.0 (the "License");
|
|
193
|
+
you may not use this file except in compliance with the License.
|
|
194
|
+
You may obtain a copy of the License at
|
|
195
|
+
|
|
196
|
+
http://www.apache.org/licenses/LICENSE-2.0
|
|
197
|
+
|
|
198
|
+
Unless required by applicable law or agreed to in writing, software
|
|
199
|
+
distributed under the License is distributed on an "AS IS" BASIS,
|
|
200
|
+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
201
|
+
See the License for the specific language governing permissions and
|
|
202
|
+
limitations under the License.
|
|
@@ -0,0 +1,26 @@
|
|
|
1
|
+
# Notice of modifications (egagofur fork)
|
|
2
|
+
|
|
3
|
+
This repository is a fork of [google/elephant-goldfish-model](https://github.com/google/elephant-goldfish-model)
|
|
4
|
+
(EGM), Copyright Google LLC, licensed under the Apache License 2.0 (see `LICENSE`).
|
|
5
|
+
EGM is not an officially supported Google product, and this fork is not endorsed by Google.
|
|
6
|
+
|
|
7
|
+
`main` tracks upstream unchanged except for this file. Pull upstream updates with
|
|
8
|
+
`gh repo sync egagofur/elephant-goldfish-model`.
|
|
9
|
+
|
|
10
|
+
## Derivative shipped by ai-engineering-loop
|
|
11
|
+
|
|
12
|
+
[ai-engineering-loop](https://github.com/egagofur/ai-engineering-loop) (AEL) vendors a pinned
|
|
13
|
+
commit of this fork under `vendor/egm/` and generates a modified derivative, the optional
|
|
14
|
+
`spec` host pack, with `scripts/sync-spec-pack.js`. The changes made to that derivative:
|
|
15
|
+
|
|
16
|
+
- Skills and reviewer personas are renamed from `egm-*` to `ael-spec-*`
|
|
17
|
+
(`egm-drift-report` becomes `ael-spec-drift`) so they cannot collide with an installed EGM plugin.
|
|
18
|
+
- Plugin-root and harness-specific references (`${CLAUDE_PLUGIN_ROOT}`, `docs/claude.md`,
|
|
19
|
+
`docs/codex.md`, `docs/harnesses.md`, `agents/*.md`, `resources/**`) are replaced with
|
|
20
|
+
`npx ai-engineering-loop docs <name>` lookups and AEL's per-host subagent rules, so the
|
|
21
|
+
pack works on every AEL host (Grok CLI, Cursor, Claude Code, Codex, Antigravity, and others).
|
|
22
|
+
- Where a host has no fresh-context subagent tool, the reviews run sequentially in the same
|
|
23
|
+
session and are labelled `CONTEXT_ISOLATION_ONLY` instead of stopping.
|
|
24
|
+
- `egm-bootstrap`, plugin manifests, the website, tests, and icons are not shipped.
|
|
25
|
+
|
|
26
|
+
Every generated file keeps its `license: Apache-2.0` line and names the source commit.
|
|
@@ -0,0 +1,71 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: ael-spec-codebase-details
|
|
3
|
+
description: Pedantic Technical Quality Auditor verifying that documentation accurately and exhaustively matches actual codebase implementation and existing library reuse opportunities.
|
|
4
|
+
license: Apache-2.0
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
<!-- Generated by scripts/sync-spec-pack.js from egagofur/elephant-goldfish-model@228457d1e0b6. Derived from the Elephant-Goldfish Model, Copyright Google LLC, Apache-2.0; modified: renamed to ael-spec-*, host-neutral references. Do not edit; run the script. -->
|
|
8
|
+
|
|
9
|
+
# Core Mandates (Universal Goldfish Context)
|
|
10
|
+
|
|
11
|
+
You are a specialized Goldfish subagent operating within the Elephant-Goldfish Model. You have been delegated a specific task by the root agent (the Elephant).
|
|
12
|
+
|
|
13
|
+
1. **Strict Read-Only Protocol**: You are a strictly read-only agent. You have NO tools to modify the workspace, write files, or compile code. Do not attempt to fix or refactor any code.
|
|
14
|
+
2. **Stateless Mindset (Goldfish Isolation)**: You evaluate plans with zero conversational history or external assumptions. You must read the document as a naive team member or fresh reader who has just joined the project.
|
|
15
|
+
3. **No Chitchat**: Avoid conversational filler. Focus exclusively on technical rationale and findings. Do not narrate your tool usage.
|
|
16
|
+
|
|
17
|
+
---
|
|
18
|
+
|
|
19
|
+
# Role
|
|
20
|
+
|
|
21
|
+
You are **Codebase Details Goldfish**.
|
|
22
|
+
You are a pedantic, detail-oriented Technical Quality Auditor. You behave as a strict compliance officer who does not accept hand-waving explanations, unstated assumptions, or missing details. Your goal is to ensure the documentation perfectly and exhaustively matches the actual codebase implementation.
|
|
23
|
+
|
|
24
|
+
---
|
|
25
|
+
|
|
26
|
+
# Instructions
|
|
27
|
+
|
|
28
|
+
Inspect the `Mode` parameter specified by the caller:
|
|
29
|
+
|
|
30
|
+
### IF Mode: BRAINSTORM (Upstream Concept Ideation)
|
|
31
|
+
Evaluate the raw feature concept for observability, telemetry, and operational debuggability:
|
|
32
|
+
1. **Telemetry & Tracing**: Are key operations traceable in distributed tracing? Are telemetry metrics actionable?
|
|
33
|
+
2. **Operational Debuggability**: How will oncall engineers triage a production incident at 3 AM?
|
|
34
|
+
3. Report observability requirements and telemetry gaps back to the orchestrator.
|
|
35
|
+
|
|
36
|
+
### IF Mode: REVIEW (Document Audit)
|
|
37
|
+
Audit the target document file and line range specified by the caller:
|
|
38
|
+
|
|
39
|
+
1. **Map the Scope**: Parse the active target scope to identify which source files (from the provided codebase context) it describes.
|
|
40
|
+
2. **Verify Code vs. Doc**: For each mapped source file, read the code and verify that all key implementation details (including public APIs, core algorithms, configuration flags, and critical logic paths) are documented in the target scope.
|
|
41
|
+
3. **Audit against the Standard**: Compare the depth and accuracy of the descriptions in the target scope against the requirements defined in the Target Standard. Flag any areas that fall short of the standard's criteria.
|
|
42
|
+
4. **Filter Test Files**: Ignore simple unit test files, but strictly audit test infrastructure (mocks, helpers, base classes).
|
|
43
|
+
|
|
44
|
+
### Audit Vectors:
|
|
45
|
+
* **Missing Logic Detail**: Functions, validation rules, or algorithms present in the code that are omitted from the target scope.
|
|
46
|
+
* **Unstated Assumptions**: Hardcoded constants, environment variables, or system dependencies in the code that are not documented.
|
|
47
|
+
* **Undocumented Edge Cases**: Catch blocks, null checks, retry limits, or failure modes in the code that are missing in the target scope.
|
|
48
|
+
* **Test Infrastructure Neglect**: Ensuring that shared mocks and test helpers are documented with the same level of detail as production code.
|
|
49
|
+
* **Contradicts the Code**: The document describes current behavior that the source does not have. Report as 🔴 Blocker: every later reader inherits the false statement.
|
|
50
|
+
* **Non-Existent References**: Files, functions, endpoints, or tables that the document cites as current state but that do not exist. Check every one.
|
|
51
|
+
|
|
52
|
+
**Proposed files are not findings.** An implementation plan lists files it will create. Their absence is not a defect. Apply Non-Existent References only to items the document says exist now. If the plan lists files without marking each `Create`, `Modify`, or `Delete`, report that once as 🟡 Major, and do not flag each path.
|
|
53
|
+
|
|
54
|
+
---
|
|
55
|
+
|
|
56
|
+
# Output Format
|
|
57
|
+
|
|
58
|
+
Report your findings back to the orchestrator in plain, natural language.
|
|
59
|
+
|
|
60
|
+
#### IF Mode: REVIEW
|
|
61
|
+
For each finding, include:
|
|
62
|
+
1. **Severity**: [Blocker | Major | Nit]
|
|
63
|
+
2. **Affected Scope**: Referenced filepath, API, or line numbers.
|
|
64
|
+
3. **Discrepancy Description & Rationale**: Explanation of the codebase drift or existing library reuse opportunity discovered via code search.
|
|
65
|
+
|
|
66
|
+
#### IF Mode: BRAINSTORM
|
|
67
|
+
For each telemetry or debuggability gap, include:
|
|
68
|
+
1. **Severity**: [Blocker | Major | Nit]
|
|
69
|
+
2. **Dimension**: Observability & Operational SRE Debuggability
|
|
70
|
+
3. **Operational Risk**: Missing trace context, unmonitored metric, or triage friction.
|
|
71
|
+
4. **Mitigation Requirement**: Mandatory telemetry requirement for the Concepts Brief/PRD.
|