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.
Files changed (133) hide show
  1. package/.agents/skills/ai-engineering-loop/SKILL.md +4 -4
  2. package/.agents/skills/ai-engineering-loop/references/loop-deliver.md +2 -2
  3. package/.agents/skills/ai-engineering-loop/references/loop-goal.md +3 -3
  4. package/.agents/skills/ai-engineering-loop/references/loop-maker.md +1 -0
  5. package/.agents/skills/ai-engineering-loop/references/loop-review.md +3 -4
  6. package/.agents/skills/ai-engineering-loop/references/loop-risky.md +1 -0
  7. package/.agents/skills/ai-engineering-loop/references/loop-verify.md +3 -3
  8. package/.claude/agents/judge.md +5 -2
  9. package/.grok/agents/judge.md +5 -2
  10. package/CHANGELOG.md +60 -0
  11. package/README.md +1 -0
  12. package/THIRD_PARTY_NOTICES.md +11 -0
  13. package/adapters/spec/LICENSE +202 -0
  14. package/adapters/spec/NOTICE-AEL.md +26 -0
  15. package/adapters/spec/agents/ael-spec-codebase-details.md +71 -0
  16. package/adapters/spec/agents/ael-spec-comprehension.md +71 -0
  17. package/adapters/spec/agents/ael-spec-design.md +65 -0
  18. package/adapters/spec/agents/ael-spec-implementation-readiness.md +64 -0
  19. package/adapters/spec/agents/ael-spec-structural.md +67 -0
  20. package/adapters/spec/agents/ael-spec-style.md +68 -0
  21. package/adapters/spec/agents/ael-spec-synthesizer.md +73 -0
  22. package/adapters/spec/agents/ael-spec-zoom-out.md +76 -0
  23. package/adapters/spec/skills/ael-spec-brainstorm/SKILL.md +265 -0
  24. package/adapters/spec/skills/ael-spec-draft/SKILL.md +315 -0
  25. package/adapters/spec/skills/ael-spec-draft/references/design_doc.md +179 -0
  26. package/adapters/spec/skills/ael-spec-drift/SKILL.md +68 -0
  27. package/adapters/spec/skills/ael-spec-resolve/SKILL.md +188 -0
  28. package/adapters/spec/skills/ael-spec-review/SKILL.md +403 -0
  29. package/adapters/spec/skills/ael-spec-review-loop/SKILL.md +191 -0
  30. package/adapters/spec/standards/ael-spec-execution-instructions.md +36 -0
  31. package/adapters/spec/standards/ael-spec-feature-spec-standard.md +38 -0
  32. package/adapters/spec/standards/ael-spec-heilmeier-standard.md +32 -0
  33. package/adapters/spec/standards/ael-spec-implementation-readiness-standard.md +36 -0
  34. package/adapters/spec/standards/ael-spec-re-implementation-standard.md +39 -0
  35. package/adapters/spec/standards/ael-spec-zoom-out-standard.md +62 -0
  36. package/agents/maker.md +1 -1
  37. package/agents/shared/judge.body.md +5 -2
  38. package/bin/ai-engineering-loop.js +344 -78
  39. package/core/definition-of-done.md +2 -2
  40. package/core/escalation-policy.md +1 -1
  41. package/core/goal-contract.md +1 -1
  42. package/core/iteration-policy.md +2 -1
  43. package/core/judge-policy.md +10 -4
  44. package/core/orchestration-model.md +8 -7
  45. package/core/repo-config-schema.md +2 -2
  46. package/core/runtime-safety.md +3 -3
  47. package/core/spec-pack.md +47 -0
  48. package/lib/auto-update.js +8 -14
  49. package/lib/claimed-vs-reality.js +2 -2
  50. package/lib/cli-args.js +3 -1
  51. package/lib/design-ref.js +178 -0
  52. package/lib/docs.js +1 -1
  53. package/lib/doctor.js +0 -6
  54. package/lib/escalation.js +1 -1
  55. package/lib/fsutil.js +88 -0
  56. package/lib/gates.js +70 -27
  57. package/lib/generate-workflow.js +0 -29
  58. package/lib/goal-runtime.js +8 -2
  59. package/lib/guard-hooks.js +26 -7
  60. package/lib/guard.js +100 -10
  61. package/lib/hosts/doctor.js +17 -7
  62. package/lib/impact-map.js +31 -8
  63. package/lib/jsonl-ledger.js +104 -0
  64. package/lib/learn.js +4 -9
  65. package/lib/loop-groups.js +0 -25
  66. package/lib/migrations.js +1 -5
  67. package/lib/no-progress.js +119 -0
  68. package/lib/node-evidence.js +1 -5
  69. package/lib/orchestration.js +5 -361
  70. package/lib/personal-workflow.js +1 -1
  71. package/lib/quick.js +152 -0
  72. package/lib/receipt.js +13 -6
  73. package/lib/recipe-builder.js +3 -35
  74. package/lib/recipe-graph.js +2 -63
  75. package/lib/recipe.js +2 -4
  76. package/lib/review-ingest.js +116 -0
  77. package/lib/run-abandon.js +2 -1
  78. package/lib/run-compaction.js +4 -12
  79. package/lib/run-interactions.js +16 -71
  80. package/lib/run-lifecycle.js +25 -77
  81. package/lib/run-state.js +68 -17
  82. package/lib/run-watcher.js +11 -14
  83. package/lib/runtime-files.js +45 -1
  84. package/lib/safe-context.js +17 -6
  85. package/lib/sandbox.js +2 -1
  86. package/lib/smart-context.js +13 -14
  87. package/lib/spawn-command.js +94 -0
  88. package/lib/studio-layout.js +2 -8
  89. package/lib/studio-runtime.js +2 -1
  90. package/lib/studio-server.js +25 -5
  91. package/lib/sync-hosts.js +25 -2
  92. package/lib/tier.js +36 -10
  93. package/lib/user-state.js +2 -17
  94. package/lib/verification-lanes.js +115 -0
  95. package/lib/verification-recorder.js +110 -22
  96. package/lib/workflow-runtime.js +7 -4
  97. package/package.json +1 -2
  98. package/policies/review-budget.md +1 -1
  99. package/schemas/goal-contract.schema.json +87 -11
  100. package/.claude/skills/ai-engineering-loop/SKILL.md +0 -62
  101. package/.claude/skills/ai-engineering-loop/references/loop-commands.md +0 -24
  102. package/.claude/skills/ai-engineering-loop/references/loop-deliver.md +0 -10
  103. package/.claude/skills/ai-engineering-loop/references/loop-goal.md +0 -11
  104. package/.claude/skills/ai-engineering-loop/references/loop-hosts.md +0 -48
  105. package/.claude/skills/ai-engineering-loop/references/loop-maker.md +0 -14
  106. package/.claude/skills/ai-engineering-loop/references/loop-review.md +0 -20
  107. package/.claude/skills/ai-engineering-loop/references/loop-risky.md +0 -9
  108. package/.claude/skills/ai-engineering-loop/references/loop-verify.md +0 -20
  109. package/.claude/skills/animate/RECIPES.md +0 -324
  110. package/.claude/skills/animate/SKILL.md +0 -207
  111. package/.claude/skills/animate-expo/RECIPES.md +0 -385
  112. package/.claude/skills/animate-expo/SKILL.md +0 -263
  113. package/.claude/skills/animation-vocabulary/SKILL.md +0 -181
  114. package/.claude/skills/apple-design/SKILL.md +0 -290
  115. package/.claude/skills/ask-sonner/API.md +0 -64
  116. package/.claude/skills/ask-sonner/SKILL.md +0 -88
  117. package/.claude/skills/backend-development/SKILL.md +0 -272
  118. package/.claude/skills/backend-development/references/api-design-guidelines.md +0 -95
  119. package/.claude/skills/backend-development/references/query-and-database-best-practices.md +0 -53
  120. package/.claude/skills/backend-development/references/security-checklist.md +0 -60
  121. package/.claude/skills/emil-design-eng/SKILL.md +0 -674
  122. package/.claude/skills/find-animation-opportunities/SKILL.md +0 -140
  123. package/.claude/skills/improve-animations/AUDIT.md +0 -115
  124. package/.claude/skills/improve-animations/PLAN-TEMPLATE.md +0 -73
  125. package/.claude/skills/improve-animations/SKILL.md +0 -109
  126. package/.claude/skills/mobile-native/SKILL.md +0 -311
  127. package/.claude/skills/pick-ui-library/SKILL.md +0 -85
  128. package/.claude/skills/prototype/PICKER.md +0 -197
  129. package/.claude/skills/prototype/SKILL.md +0 -98
  130. package/.claude/skills/review-animations/SKILL.md +0 -120
  131. package/.claude/skills/review-animations/STANDARDS.md +0 -187
  132. package/.claude/skills/write-swift/SKILL.md +0 -396
  133. package/lib/intern-catalog.js +0 -53
@@ -46,7 +46,7 @@ flowchart LR
46
46
 
47
47
  ### Pillar 4: Adversarial Consensus
48
48
  - Independent [Devil's Advocate Review](../agents/devil-advocate.md) has been executed across all 6 core review domains.
49
- - **Zero Unresolved Blocking Findings**: No open `SEV-1 (Critical)` or `SEV-2 (High)` findings.
49
+ - **Zero Unresolved Blocking Findings**: No open VALID `BLOCKER` or `HIGH` findings (older docs call these SEV-1 and SEV-2).
50
50
  - **Evidence-Based Triage**: Every raised finding has been formally triaged with reproducible evidence as `VALID` (and resolved in code) or `INVALID` (with technical proof of why it is a false positive).
51
51
 
52
52
  ### Pillar 5: Judge Certified PASS
@@ -78,4 +78,4 @@ An engineering run MUST be rejected and flagged as `FAIL` or `BLOCKED` if any of
78
78
  1. **Unverified Claims**: The agent states that a test passed or feature works without providing command outputs or test code.
79
79
  2. **Post-Hoc Goal Shifting**: Modifying Acceptance Criteria to match buggy behavior instead of fixing the bug.
80
80
  3. **Suppressed Errors**: Adding `@ts-ignore`, `eslint-disable`, empty catch blocks, or skipping tests to force a green build.
81
- 4. **Unresolved Critical Findings**: Attempting to declare completion while a `SEV-1` or `SEV-2` finding from the Devil's Advocate remains open.
81
+ 4. **Unresolved Critical Findings**: Attempting to declare completion while a VALID `BLOCKER` or `HIGH` finding from the Devil's Advocate remains open.
@@ -27,7 +27,7 @@ flowchart TD
27
27
  ```
28
28
 
29
29
  ### Trigger 1: Maximum Iterations Reached
30
- - **Condition**: The system has completed `MAX_ITERATIONS` (default: 3) and unresolved blocking findings (`SEV-1` or `SEV-2`) still persist.
30
+ - **Condition**: The system has completed `MAX_ITERATIONS` (default: 3) and unresolved blocking findings (VALID `BLOCKER` or `HIGH`) still persist, or the loop stopped making progress (`NO_PROGRESS`: the same Maker diff or the same blocking findings as the previous iteration).
31
31
  - **Rationale**: Prolonged retries indicate either an incorrect fundamental strategy or a hidden architectural obstacle.
32
32
 
33
33
  ### Trigger 2: No-Progress / Stagnation Detected
@@ -66,7 +66,7 @@ Each AC is one row that can **fail**. Happy path alone is not a contract (`polic
66
66
  ## 9. Definition of Done (DoD)
67
67
  - [ ] All Acceptance Criteria (AC-1 through AC-N) verified with automated tests.
68
68
  - [ ] 100% pass on all deterministic verification commands (0 errors, 0 warnings where enforced).
69
- - [ ] Independent Devil's Advocate review completed with 0 unresolved blocking findings (SEV-1 / SEV-2).
69
+ - [ ] Independent Devil's Advocate review completed with 0 unresolved blocking findings (VALID BLOCKER / HIGH).
70
70
  - [ ] All review findings triaged with evidence (VALID, INVALID, UNCERTAIN).
71
71
  - [ ] Judge Agent issues a formal PASS verdict.
72
72
  ```
@@ -17,7 +17,8 @@ MAX_ALLOWED_CEILING = 5
17
17
  ```
18
18
 
19
19
  - **Default Cap**: An engineering run is allotted a maximum of **3 iterations** by default.
20
- - **Configurability**: Projects or workflows may configure `MAX_ITERATIONS` between 1 and 5 in their runtime configuration or Goal Contract.
20
+ - **Configurability**: A recipe sets the cap with `maxIterations` on the loop group whose decision node is the Judge (`recipes/default.json`). Gates clamp it to 1..5; runs without a recipe use 3.
21
+ - **No progress**: an ITERATE that repeats the previous iteration's Maker diff or its blocking findings becomes ESCALATE (`NO_PROGRESS`), recorded in `RUN_DIR/iterations.jsonl`.
21
22
  - **Hard Ceiling**: Under no circumstances may an agent loop beyond 5 iterations without human re-authorization.
22
23
 
23
24
  ---
@@ -37,8 +37,8 @@ The Judge renders decisions based strictly on **Validity + Severity**, then **re
37
37
  | **`VALID`** | **`BLOCKER`** | Any | **UPHELD (Blocking)** if `axis` is `spec` (or omitted), or `standards` with `hardConvention: true` | **`ITERATE`** — Maker must apply alternative diff & tests. |
38
38
  | **`VALID`** | **`HIGH`** | Any | **UPHELD (Blocking)** under the same axis rule | **`ITERATE`** — Maker must apply alternative diff & tests. |
39
39
  | **`VALID`** | **`BLOCKER` / `HIGH`** | Any | **TRADEOFF** if `axis` is `standards` and `hardConvention` is not true | **`PASS`** (if ACs met) — smell/convention judgement, not an AC breach. |
40
- | **`VALID`** | **`MEDIUM`** | `ACCEPTABLE` | **UPHELD (Tradeoff)** | **`PASS`** (if ACs met) — Logged as known tradeoff in MR. |
41
- | **`VALID`** | **`LOW`** | `ACCEPTABLE` | **UPHELD (Tradeoff)** | **`PASS`** (if ACs met) — Logged as known tradeoff in MR. |
40
+ | **`VALID`** | **`MEDIUM`** | Any | **UPHELD (Tradeoff)** | **`PASS`** (if ACs met) — Logged as known tradeoff in MR. |
41
+ | **`VALID`** | **`LOW`** | Any | **UPHELD (Tradeoff)** | **`PASS`** (if ACs met) — Logged as known tradeoff in MR. |
42
42
  | **`INVALID`** | Any | `WEAK` | **DISMISSED (Hallucination)** | **`PASS`** (if ACs met) — Discarded with evidence proof. |
43
43
 
44
44
  ---
@@ -69,9 +69,15 @@ The Judge renders decisions based strictly on **Validity + Severity**, then **re
69
69
 
70
70
  ---
71
71
 
72
+ ### Judge-added findings
73
+
74
+ The gate recomputes the verdict from the Finding Ledger plus `judgeFindings` in `verdict.json`. A Judge that blocks for a reason the ledger lacks (rows 3-5 above) adds that reason as a `judgeFindings` entry in the Finding Ledger shape (VALID BLOCKER/HIGH with evidence and `concreteAlternativeDiff`). The Judge cannot PASS what the ledger blocks, and the gate rejects a blocking verdict with no supporting finding.
75
+
76
+ ---
77
+
72
78
  ### Verdict 3: `ESCALATE`
73
79
  - **Conditions**:
74
- 1. Active iteration count $\ge \text{MAX\_ITERATIONS}$ (3).
75
- 2. Stagnation detected (identical finding signatures repeated across 2 iterations).
80
+ 1. Active iteration count $\ge \text{MAX\_ITERATIONS}$ (recipe `maxIterations`, default 3, at most 5).
81
+ 2. Stagnation detected (`NO_PROGRESS`): the same blocking finding signatures or the same Maker diff as the previous iteration. The gate enforces this.
76
82
  3. Contradictory architectural invariants that cannot be resolved within task scope.
77
83
  - **Action**: Halt the loop immediately and generate an actionable Human Escalation Report.
@@ -22,7 +22,7 @@ The architecture explicitly distinguishes three separate stages:
22
22
 
23
23
  > [!IMPORTANT]
24
24
  > **Semantic Invariant**:
25
- > If `CONFIGURATION_SUPPORTED = true`, `INVOCATION_AVAILABLE = false`, and `EXECUTION_PROVEN = false`, the engine **must select `CONTEXT_ISOLATION_ONLY`**.
25
+ > If `CONFIGURATION_SUPPORTED = true`, `INVOCATION_AVAILABLE = false`, and `EXECUTION_PROVEN = false`, the review **must report `CONTEXT_ISOLATION_ONLY`**.
26
26
  > Configuration discovery is **never** conflated with execution capability.
27
27
 
28
28
  ---
@@ -62,7 +62,7 @@ The system categorically rejects the following as proof of independent LLM execu
62
62
  | **External Agent CLI** | `/Users/.../.local/bin/claude -p` | `UNAVAILABLE` | Unauthenticated: `Not logged in · Please run /login`. |
63
63
  | **Antigravity `new-conversation`** | `agentapi new-conversation` | `UNAVAILABLE` | Blocked by Language Server `project_id` authorization. |
64
64
  | **Antigravity `send-message`** | `agentapi send-message` | `IPC_MESSAGE_DISPATCH` | Succeeded (IPC message dispatch works, but is not an agent). |
65
- | **Artifact Barrier** | `buildReviewContextBarrier()` | `CONTEXT_ISOLATION_ONLY` | **Available & Verified**: 0% prompt bleed on disk. |
65
+ | **Artifact Barrier** | Clean-slate review artifacts | `CONTEXT_ISOLATION_ONLY` | **Available**: review reads only on-disk artifacts. |
66
66
 
67
67
  ### Architectural Conclusion:
68
68
  > *"Antigravity custom subagent configuration is supported/discoverable, but native subagent invocation is not exposed or executable from the current standalone agent runtime."*
@@ -80,7 +80,7 @@ The system categorically rejects the following as proof of independent LLM execu
80
80
  | **Headless process** | `grok -p` | `FRESH_PROCESS_AGENT` | Only after the process prints a model response. |
81
81
  | **Cavecrew reviewer** | `caveman:cavecrew-reviewer` | `GROK_COMPRESSED_REVIEW_PRESET` | **Rejected** as Devil's Advocate / Judge (wrong output schema). |
82
82
  | **Maker resume** | `spawn_subagent(resume_from=maker)` | tainted history | **Rejected**. DA and Judge must spawn fresh. |
83
- | **Artifact barrier** | `buildReviewContextBarrier()` | `CONTEXT_ISOLATION_ONLY` | Fallback when spawn is disabled. |
83
+ | **Artifact barrier** | Clean-slate review artifacts | `CONTEXT_ISOLATION_ONLY` | Fallback when spawn is disabled. |
84
84
 
85
85
  ### Architectural Conclusion:
86
86
  > *"Grok CLI spawn_subagent is a true independent child session. Select TRUE_INDEPENDENT_AGENT only after a child id and model response are captured without resume_from. Binary presence and agent markdown are never sufficient."*
@@ -91,7 +91,7 @@ See [docs/grok-cli-feasibility.md](../docs/grok-cli-feasibility.md).
91
91
 
92
92
  ## 5. Truthful Reporting Output
93
93
 
94
- When `CONTEXT_ISOLATION_ONLY` is selected, the report generator strictly produces:
94
+ When `CONTEXT_ISOLATION_ONLY` applies, the review report header is:
95
95
 
96
96
  ```text
97
97
  Execution Mode: CONTEXT_ISOLATION_ONLY
@@ -111,8 +111,9 @@ Review Method: Clean-Slate Artifact Isolation Barrier
111
111
 
112
112
  REPORT_ONLY (recipe `audit`) policy: when the host can invoke a native subagent, one fresh `devil-advocate` sibling reviews `report.json` before `gate report` (no Judge, no iteration loop); otherwise the same check runs in-session with a reason. `report.json` may carry a `review` block, which `gate report` validates.
113
113
 
114
- ### Strictly Forbidden Phrases during `CONTEXT_ISOLATION_ONLY`:
114
+ ### Strictly Forbidden Claims during `CONTEXT_ISOLATION_ONLY`:
115
+ Outside the fixed header lines above (which name `Native Subagent Invocation` as a capability), never claim that a separate agent reviewed the work:
115
116
  - *"independent agent review"*
116
- - *"subagent"*
117
+ - *"reviewed by a subagent"* (or any wording that says a subagent ran)
117
118
  - *"multi-agent review"*
118
- - *"independent reviewer"*
119
+ - *"independent reviewer"
@@ -18,7 +18,7 @@ The `.ai-engineering-loop/` directory serves as the **Living Project Context** f
18
18
  ├── lessons.md # Optional confirmed process lessons (not a chat log)
19
19
  ├── adrs/ # Architecture Decision Records from Stage 1 grill
20
20
  │ └── README.md
21
- └── tasks/ # Ephemeral: current.diff, handoff.md, verification logs
21
+ └── tasks/ # Ephemeral: handoff.md, verification logs
22
22
  ```
23
23
 
24
24
  ---
@@ -79,7 +79,7 @@ Maintains lightweight state for instant drift detection:
79
79
  - Durable why for load-bearing choices settled in grill. `refresh` does not overwrite existing ADRs.
80
80
 
81
81
  ### 9. `tasks/` — Run artifacts (optional)
82
- - `current.diff`, verification logs, `handoff.md`, `claimed-vs-reality.md`, `maker-brief.md`. Not required for `init` validity.
82
+ - Verification logs, `handoff.md`, `claimed-vs-reality.md`, `maker-brief.md`. Not required for `init` validity.
83
83
 
84
84
  ### 10. `workflow.md` — Loop overlay (optional)
85
85
  - Hooks around the 8-stage OS: `before_grill`, `after_freeze`, `after_pass`.
@@ -32,12 +32,12 @@ npx ai-engineering-loop hooks status | uninstall
32
32
 
33
33
  | Check | Rule |
34
34
  |---|---|
35
- | Edit / Write / MultiEdit / NotebookEdit | Blocked or warned when the file is outside the Run scope or matches `scope.deniedPaths`. `.ai-engineering-loop/` (Run artifacts) is always writable. A `REPORT_ONLY` Run may not edit at all. |
36
- | Bash | `rm` with recursive + force flags, `DROP TABLE/DATABASE/SCHEMA`, `TRUNCATE`, `git push --force` / `-f` / `--force-with-lease` / `+refspec`, `git reset --hard`, `git clean` with `-f` and `-d`. |
35
+ | Edit / Write / MultiEdit / NotebookEdit | Blocked or warned when the file is outside the Run scope or matches `scope.deniedPaths`. `.ai-engineering-loop/` (Run artifacts) is writable, except CLI-owned Run evidence (`runs/current.json` and, per Run, `state.json`, `plan.json`, `workflow-state.json`, `events.jsonl`, `lifecycle.jsonl`, `interactions.jsonl`, `verification*`, `sandbox-evidence.json`, `impact-map.json`, `impact-drift.json`, `guard-events.json`, `receipt.*`, `CANCELLED`): rule `run-evidence`. A `REPORT_ONLY` Run may not edit at all. |
36
+ | Bash | `rm` with recursive + force flags (also `\rm` and `"rm"`), `find -delete` / `find -exec rm`, `DROP TABLE/DATABASE/SCHEMA`, `TRUNCATE`, `git push --force` / `-f` / `--force-with-lease` / `+refspec`, `git reset --hard`, `git clean` with `-f` and `-d`, `git checkout -- <paths>` / `git checkout .` / `-f`, `git restore` (except `--staged` only), `git branch -D`. |
37
37
 
38
38
  **Scope** = the frozen Goal's optional `scope.allowedPaths` plus the confirmed blast-radius map (`impact confirm`, see `docs blast-radius-map`). `scope.deniedPaths` always applies. A Goal without `scope` and without a confirmed map has no path enforcement (backward compatible). Globs: `**` crosses directories, `*` and `?` stay inside one segment, a trailing `/` is a directory prefix; paths are repository-relative.
39
39
 
40
- **Decision** by Run mode: `ASSISTED` → `warn` (the Claude hook answers `ask`, so the human decides); `UNATTENDED` and `REPORT_ONLY` → `block` (`deny`; CLI exit code 2). With no active Run the policy `defaultMode` applies and nothing is recorded.
40
+ **Decision** by Run mode: `ASSISTED` → `warn` (the Claude hook answers `ask`, so the human decides); `UNATTENDED` and `REPORT_ONLY` → `block` (`deny`; CLI exit code 2). If `guard check --hook` itself fails (bad input, unreadable Run), it exits 2 so the host blocks the call, except in `ASSISTED` where it exits 1 and the human still approves. `hooks install` pins the hook to the installed version (`npx --yes ai-engineering-loop@<version>`) and re-pins hooks from older installs. With no active Run the policy `defaultMode` applies and nothing is recorded.
41
41
 
42
42
  **Evidence:** every warn and block is appended to `RUN_DIR/guard-events.json` (tool, rule ids, reasons, mode, redacted repository-relative target). `gate <name>` prints the counts and `--json` returns `guard: { warn, block, rules }`.
43
43
 
@@ -0,0 +1,47 @@
1
+ # Spec pack: design before code
2
+
3
+ The optional `spec` host pack adds design-document skills derived from Google's
4
+ [Elephant-Goldfish Model](https://github.com/google/elephant-goldfish-model) (EGM,
5
+ Apache-2.0) through the fork [egagofur/elephant-goldfish-model](https://github.com/egagofur/elephant-goldfish-model).
6
+ The Elephant (your session) drafts; fresh Goldfish reviewers read only the document and
7
+ the code it cites; you decide the trade-offs.
8
+
9
+ ## When to use it
10
+
11
+ - Use it for a new feature, an architecture change, an API or integration design, or a
12
+ data-model change: work that needs decisions before code. A new T2 Run suggests it.
13
+ - Do not use it for a bug fix, typo, small refactor, or any T0/T1 task. Use the normal loop.
14
+
15
+ ## Flow
16
+
17
+ 1. `ael-spec-brainstorm <idea>`: clarifying questions, then six review lenses; writes `concepts_brief.md`.
18
+ 2. `ael-spec-draft`: section-by-section `design_draft.md`, saved under `docs/designs/<name>.md`.
19
+ 3. `ael-spec-review docs/designs/<name>.md`: staged Goldfish review (zoom out, comprehension,
20
+ critique, readiness). Expect many findings; take what is relevant.
21
+ 4. `ael-spec-resolve`: each finding is PROPOSE FIX, CONTEST, ESCALATE or DECLINE; you choose.
22
+ 5. You approve and commit the design. Agreement in chat is not approval.
23
+ 6. `npx ai-engineering-loop goal draft --run <id> --from-design docs/designs/<name>.md --revision <r>`:
24
+ prefilled acceptance rows with `<fill: …>` placeholders, `outOfScope`, and `designRef`.
25
+ Fill the placeholders; `goal freeze` refuses them. Then run the loop as usual.
26
+ 7. Verify and review report design drift (planned files untouched, changed files outside
27
+ the plan). Later, `ael-spec-drift docs/designs/` compares all designs with the code.
28
+
29
+ Personas and standards: `npx ai-engineering-loop docs ael-spec-zoom-out`,
30
+ `docs ael-spec-implementation-readiness-standard`, and so on.
31
+
32
+ ## Hosts
33
+
34
+ `npx ai-engineering-loop sync-hosts --pack spec` installs the six `ael-spec-*` skills on
35
+ every enabled host. Reviewers spawn as fresh sibling subagents per `docs loop-hosts`. A host
36
+ without a subagent tool runs the reviewers one at a time in-session and labels the reports
37
+ `CONTEXT_ISOLATION_ONLY`; that is weaker than a Goldfish review and is disclosed.
38
+ `hosts doctor` shows, per host, whether the pack is installed and which mode it gets.
39
+
40
+ ## Updating from upstream
41
+
42
+ 1. `gh repo sync egagofur/elephant-goldfish-model` (pulls google/main into the fork).
43
+ 2. In this repository: `node scripts/sync-spec-pack.js --pull [ref]`, then `npm test`.
44
+ 3. Open a PR. Users get it through the normal CLI update.
45
+
46
+ The pinned commit is in `vendor/egm/UPSTREAM.json`; every generated file names it.
47
+ Attribution and the list of modifications: `THIRD_PARTY_NOTICES.md` and `adapters/spec/NOTICE-AEL.md`.
@@ -14,7 +14,14 @@
14
14
 
15
15
  const fs = require('fs');
16
16
  const path = require('path');
17
- const { execFileSync, spawn } = require('child_process');
17
+ const { execFileSync: rawExecFileSync, spawn } = require('child_process');
18
+ const { resolveSpawn } = require('./spawn-command.js');
19
+
20
+ // npm and the global ai-engineering-loop bin are .cmd shims on Windows.
21
+ function execFileSync(cmd, args, options) {
22
+ const target = resolveSpawn(cmd, args);
23
+ return rawExecFileSync(target.command, target.args, { ...options, ...target.options });
24
+ }
18
25
  const { homeDir, userStatePath, readJsonFile, writeJsonFile, readUserConfig, writeUserConfig } = require('./user-state.js');
19
26
  const { compareVersions, parseVersion } = require('./update-manager.js');
20
27
 
@@ -161,18 +168,6 @@ function decideUpdate({ current, distTags, policy, channel = 'latest', pin = nul
161
168
  return { action: 'apply', reason: `POLICY_${policy.toUpperCase()}`, target, bump };
162
169
  }
163
170
 
164
- function noticeText(current, decision) {
165
- const why = {
166
- MAJOR_NOTICE_ONLY: 'major release: read the changelog/migration notes, then run `ai-engineering-loop update apply --yes`',
167
- PINNED: 'outside your pin (`update policy --pin`)',
168
- PRERELEASE: 'prerelease; policy `all` is needed to apply it',
169
- POLICY_NOTIFY: 'run `ai-engineering-loop update apply --yes`, or choose `update policy minor`',
170
- POLICY_PATCH_ONLY: 'policy `patch` applies patch releases only',
171
- PROJECT_SCOPE_NOTIFY_ONLY: 'project install: update package.json yourself (`npm install ai-engineering-loop@latest --save-dev`)'
172
- }[decision.reason] || decision.reason;
173
- return `ai-engineering-loop ${decision.target} is available (current ${current}, ${decision.bump}): ${why}.`;
174
- }
175
-
176
171
  // ---- lock ----------------------------------------------------------------
177
172
 
178
173
  function acquireLock(home = homeDir(), { now = Date.now() } = {}) {
@@ -476,7 +471,6 @@ module.exports = {
476
471
  bumpType,
477
472
  matchesPin,
478
473
  decideUpdate,
479
- noticeText,
480
474
  acquireLock,
481
475
  readState,
482
476
  applyUpdate,
@@ -1,8 +1,8 @@
1
1
  'use strict';
2
2
 
3
- const crypto = require('crypto');
4
3
  const fs = require('fs');
5
4
  const path = require('path');
5
+ const { sha256 } = require('./fsutil.js');
6
6
  const { getCurrentRun, loadRun } = require('./run-state.js');
7
7
 
8
8
  function claimedVsRealityError(message, code = 'CLAIMED_VS_REALITY_FAILED') {
@@ -35,7 +35,7 @@ function frozenGoal(rootDir, run) {
35
35
  throw claimedVsRealityError('Frozen Goal Contract must be a regular file.', 'UNSAFE_GOAL_PATH');
36
36
  }
37
37
  const content = fs.readFileSync(goalPath);
38
- const hash = crypto.createHash('sha256').update(content).digest('hex');
38
+ const hash = sha256(content);
39
39
  if (hash !== artifact.sha256) {
40
40
  throw claimedVsRealityError('Frozen Goal Contract changed after its gate.', 'STALE_GOAL');
41
41
  }
package/lib/cli-args.js CHANGED
@@ -25,7 +25,9 @@ const WRITER_COMMANDS = Object.freeze({
25
25
  positionals: []
26
26
  },
27
27
  migrate: { flags: ['--json', '--dry-run'], valued: ['--from'], positionals: [] },
28
- verify: { flags: ['--json', '--serial', '--shell'], valued: ['--run', '--cmd', '--timeout-ms'], positionals: [] },
28
+ verify: { flags: ['--json', '--serial', '--shell', '--related', '--final', '--fresh'], valued: ['--run', '--cmd', '--timeout-ms'], positionals: [] },
29
+ quick: { flags: ['--json', '--serial', '--shell'], valued: ['--run', '--cmd', '--timeout-ms', '--mode'], positionals: null },
30
+ review: { flags: ['--json'], valued: ['--run', '--child-id', '--file'], positionals: ['ingest'] },
29
31
  learn: { flags: ['--json', '--dry-run', '--prune'], valued: ['--max-age-runs'], positionals: [] },
30
32
  guard: { flags: ['--json'], valued: ['--run', '--tool', '--input', '--path', '--command', '--hook'], positionals: ['check'] },
31
33
  hooks: { flags: ['--json'], valued: ['--host'], positionals: ['install', 'uninstall', 'status'] },
@@ -0,0 +1,178 @@
1
+ 'use strict';
2
+
3
+ // Design documents as Goal input (#97). `goal draft --from-design <doc.md>`
4
+ // turns a reviewed design (for example from the `spec` pack, #96) into a
5
+ // Goal draft with placeholder rows, and records `designRef` so later stages
6
+ // can tell which design a Run implements and whether it changed.
7
+
8
+ const fs = require('fs');
9
+ const path = require('path');
10
+ const { sha256 } = require('./fsutil.js');
11
+
12
+ const MAX_BYTES = 256 * 1024;
13
+ const PLACEHOLDER = '<fill:';
14
+
15
+ function designError(message, code) {
16
+ return Object.assign(new Error(message), { code });
17
+ }
18
+
19
+ function toPosix(file) {
20
+ return file.split(path.sep).join('/');
21
+ }
22
+
23
+ // Bounded, repository-local Markdown file. Returns { path, sha256, text }.
24
+ function readDesignDoc(rootDir, fileName) {
25
+ if (!fileName) throw designError('--from-design requires a Markdown file path', 'INVALID_USAGE');
26
+ const file = path.resolve(rootDir, fileName);
27
+ const relative = path.relative(rootDir, file);
28
+ if (!relative || relative.startsWith('..') || path.isAbsolute(relative)) {
29
+ throw designError('Design document must stay inside the repository', 'UNSAFE_DESIGN_PATH');
30
+ }
31
+ if (!/\.(md|markdown)$/i.test(file)) throw designError('Design document must be a .md file', 'INVALID_DESIGN_DOC');
32
+ let stat;
33
+ try {
34
+ stat = fs.lstatSync(file);
35
+ } catch {
36
+ throw designError(`Design document not found: ${toPosix(relative)}`, 'DESIGN_DOC_MISSING');
37
+ }
38
+ if (stat.isSymbolicLink() || !stat.isFile() || stat.size > MAX_BYTES) {
39
+ throw designError('Design document must be a regular file of at most 256 KB', 'INVALID_DESIGN_DOC');
40
+ }
41
+ const buf = fs.readFileSync(file);
42
+ return { path: toPosix(relative), sha256: sha256(buf), text: buf.toString('utf8').replace(/\r\n?/g, '\n') };
43
+ }
44
+
45
+ const SECTION_KINDS = [
46
+ ['nonGoals', /\b(non[- ]?goals?|out of scope|anti[- ]?goals?)\b/],
47
+ ['goals', /^(\d+[.)]\s*)?(goals?|objectives?)\b/],
48
+ ['targetFiles', /\b(target scope|affected files|files? (to )?(change|changed|touch|touched|modify)|file changes|file plan)\b/],
49
+ ['testCases', /\b(test plan|testing|test cases|verification plan)\b/]
50
+ ];
51
+
52
+ function sectionKind(heading) {
53
+ const text = heading.toLowerCase().replace(/[*_`]/g, '').trim();
54
+ const hit = SECTION_KINDS.find(([, pattern]) => pattern.test(text));
55
+ return hit ? hit[0] : null;
56
+ }
57
+
58
+ function cleanItem(line) {
59
+ return line.replace(/^\s*(?:[-*+]|\d+[.)])\s+(\[[ xX]\]\s+)?/, '').replace(/\*\*/g, '').trim();
60
+ }
61
+
62
+ // Lenient: any heading level; top-level bullets (indent <= 1) are items.
63
+ function parseDesignDoc(text) {
64
+ const parsed = { title: null, goals: [], nonGoals: [], targetFiles: [], testCases: [], warnings: [] };
65
+ let kind = null;
66
+ let kindLevel = 0;
67
+ let inFence = false;
68
+ const files = new Set();
69
+ for (const line of String(text).split('\n')) {
70
+ if (/^\s*(```|~~~)/.test(line)) {
71
+ inFence = !inFence;
72
+ continue;
73
+ }
74
+ if (inFence) continue;
75
+ const heading = line.match(/^(#{1,6})\s+(.*)$/);
76
+ if (heading) {
77
+ const level = heading[1].length;
78
+ if (!parsed.title && level === 1) parsed.title = heading[2].replace(/[*_`]/g, '').trim();
79
+ const next = sectionKind(heading[2]);
80
+ if (next) {
81
+ kind = next;
82
+ kindLevel = level;
83
+ } else if (kind && level <= kindLevel) {
84
+ kind = null;
85
+ }
86
+ continue;
87
+ }
88
+ if (!kind) continue;
89
+ if (kind === 'targetFiles') {
90
+ for (const match of line.matchAll(/`([^`\s]+)`/g)) {
91
+ const candidate = match[1].replace(/^\.\//, '');
92
+ if (/[/.]/.test(candidate) && !candidate.startsWith('/') && !candidate.split('/').includes('..') && !/[()=:]/.test(candidate)) files.add(candidate);
93
+ }
94
+ continue;
95
+ }
96
+ if (/^\s{0,1}(?:[-*+]|\d+[.)])\s+\S/.test(line)) {
97
+ const item = cleanItem(line);
98
+ if (item) parsed[kind].push(item);
99
+ }
100
+ }
101
+ parsed.targetFiles = [...files];
102
+ if (!parsed.testCases.length) parsed.warnings.push('No Test Plan section with bullet items: acceptance rows come from Goals or are placeholders.');
103
+ if (!parsed.targetFiles.length) parsed.warnings.push('No Target Scope section with `file` paths: designRef.targetFiles is empty, so design drift cannot be checked.');
104
+ return parsed;
105
+ }
106
+
107
+ function placeholderRow(index, statement) {
108
+ return {
109
+ id: `AC-${index + 1}`,
110
+ statement,
111
+ evidenceRequired: `${PLACEHOLDER} test file and command that prove this>`,
112
+ failureCases: [`${PLACEHOLDER} what would still look green if this broke>`]
113
+ };
114
+ }
115
+
116
+ function designRefFrom(doc, parsed) {
117
+ return { path: doc.path, sha256: doc.sha256, targetFiles: parsed.targetFiles };
118
+ }
119
+
120
+ // A draft contract built from the document. Never frozen here.
121
+ function draftFromDesign(doc, parsed) {
122
+ const rows = parsed.testCases.length ? parsed.testCases : parsed.goals;
123
+ const objective = parsed.goals[0] || parsed.title || `Implement ${doc.path}`;
124
+ return {
125
+ objective: parsed.title && parsed.goals[0] ? `${parsed.title}: ${parsed.goals[0]}` : objective,
126
+ acceptanceCriteria: rows.length
127
+ ? rows.map((row, index) => placeholderRow(index, row))
128
+ : [placeholderRow(0, `${PLACEHOLDER} acceptance criterion from ${doc.path}>`)],
129
+ ...(parsed.nonGoals.length ? { outOfScope: parsed.nonGoals } : {}),
130
+ designRef: designRefFrom(doc, parsed)
131
+ };
132
+ }
133
+
134
+ function validateDesignRef(ref) {
135
+ if (ref === undefined) return [];
136
+ if (!ref || typeof ref !== 'object' || Array.isArray(ref)) return ['designRef must be an object'];
137
+ const errors = [];
138
+ if (typeof ref.path !== 'string' || !ref.path || ref.path.startsWith('/') || ref.path.split('/').includes('..')) {
139
+ errors.push('designRef.path must be a repository-relative path');
140
+ }
141
+ if (!/^[a-f0-9]{64}$/.test(String(ref.sha256 || ''))) errors.push('designRef.sha256 must be a sha256 hex digest');
142
+ if (ref.targetFiles !== undefined && (!Array.isArray(ref.targetFiles) || ref.targetFiles.some((item) => typeof item !== 'string' || !item))) {
143
+ errors.push('designRef.targetFiles must be an array of paths');
144
+ }
145
+ return errors;
146
+ }
147
+
148
+ // AC ids that still hold `<fill:` placeholders; freeze refuses them.
149
+ function placeholderRows(contract) {
150
+ return (contract?.acceptanceCriteria || [])
151
+ .filter((row) => [row.statement, row.evidenceRequired, ...(row.failureCases || [])].some((value) => String(value || '').includes(PLACEHOLDER)))
152
+ .map((row) => row.id);
153
+ }
154
+
155
+ // Whether the referenced design still matches the hash recorded in the contract.
156
+ function designStatus(rootDir, ref) {
157
+ if (!ref) return null;
158
+ const file = path.resolve(rootDir, ref.path);
159
+ let current = null;
160
+ try {
161
+ const stat = fs.lstatSync(file);
162
+ if (stat.isFile() && !stat.isSymbolicLink()) current = sha256(fs.readFileSync(file));
163
+ } catch {
164
+ current = null;
165
+ }
166
+ return { path: ref.path, missing: current === null, designChanged: current !== ref.sha256 };
167
+ }
168
+
169
+ module.exports = {
170
+ PLACEHOLDER,
171
+ readDesignDoc,
172
+ parseDesignDoc,
173
+ draftFromDesign,
174
+ designRefFrom,
175
+ validateDesignRef,
176
+ placeholderRows,
177
+ designStatus
178
+ };
package/lib/docs.js CHANGED
@@ -8,7 +8,7 @@ const fs = require('fs');
8
8
  const path = require('path');
9
9
 
10
10
  // Loop stage references are generated host-neutral copies (issue #35).
11
- const DOC_ROOTS = Object.freeze(['core', 'policies', 'profiles', 'agents', 'adapters', '.claude/skills/ai-engineering-loop/references']);
11
+ const DOC_ROOTS = Object.freeze(['core', 'policies', 'profiles', 'agents', 'adapters', '.agents/skills/ai-engineering-loop/references']);
12
12
 
13
13
  function packageRoot() {
14
14
  return path.join(__dirname, '..');
package/lib/doctor.js CHANGED
@@ -9,15 +9,9 @@ const { listRecipes, loadRecipe, validateRecipe } = require('./recipe.js');
9
9
  const { checkAdapter } = require('./adapter-check.js');
10
10
 
11
11
  const REQUIRED_HOST_ASSETS = [
12
- '.claude/skills/ai-engineering-loop/SKILL.md',
13
12
  'adapters/project-onboarding/SKILL.md',
14
13
  'adapters/quality/skills/ael-code-simplifier/SKILL.md',
15
14
  'adapters/quality/skills/ael-receiving-code-review/SKILL.md',
16
- '.claude/skills/ai-engineering-loop/references/loop-review.md',
17
- '.claude/skills/backend-development/SKILL.md',
18
- '.claude/skills/emil-design-eng/SKILL.md',
19
- '.claude/skills/animate/SKILL.md',
20
- '.claude/skills/review-animations/SKILL.md',
21
15
  '.claude/agents/devil-advocate.md',
22
16
  '.claude/agents/judge.md',
23
17
  '.grok/agents/devil-advocate.md',
package/lib/escalation.js CHANGED
@@ -145,7 +145,7 @@ function assessRunEscalation(rootDir, { runId } = {}) {
145
145
  const assessment = assessEscalation({
146
146
  changedPaths: extractChangedPaths(diff),
147
147
  iteration: run.iteration,
148
- maxIterations: signals.maxIterations || 3,
148
+ maxIterations: signals.maxIterations || require('./no-progress.js').runMaxIterations(rootDir, run),
149
149
  schemaFailures: signals.schemaFailures || 0,
150
150
  hallucinatedCitations: signals.hallucinatedCitations || 0,
151
151
  reviewerJudgeDisagreement: signals.reviewerJudgeDisagreement === true,
package/lib/fsutil.js ADDED
@@ -0,0 +1,88 @@
1
+ 'use strict';
2
+
3
+ // Small file helpers shared across lib/: one atomic write, one sha256, one
4
+ // optional JSON read, one actor-id rule.
5
+
6
+ const crypto = require('crypto');
7
+ const fs = require('fs');
8
+ const path = require('path');
9
+
10
+ // Who asked, answered, approved, or acted: a short handle or an email.
11
+ const ACTOR_ID = /^[A-Za-z0-9@._-]{1,64}$/;
12
+
13
+ function sha256(content) {
14
+ return crypto.createHash('sha256').update(content).digest('hex');
15
+ }
16
+
17
+ // Missing or unparsable file -> fallback.
18
+ function readJsonOptional(filePath, fallback = null) {
19
+ try {
20
+ return JSON.parse(fs.readFileSync(filePath, 'utf8'));
21
+ } catch {
22
+ return fallback;
23
+ }
24
+ }
25
+
26
+ const RENAME_RETRY_CODES = new Set(['EPERM', 'EACCES', 'EBUSY']);
27
+ const RENAME_ATTEMPTS = 10;
28
+
29
+ function sleepSync(ms) {
30
+ Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
31
+ }
32
+
33
+ // Windows reports EPERM/EBUSY while an antivirus scanner, indexer, or a
34
+ // concurrent reader briefly holds the destination open. Retry with backoff.
35
+ function renameWithRetry(from, to) {
36
+ for (let attempt = 1; ; attempt += 1) {
37
+ try {
38
+ fs.renameSync(from, to);
39
+ return;
40
+ } catch (error) {
41
+ if (!RENAME_RETRY_CODES.has(error.code) || attempt >= RENAME_ATTEMPTS) throw error;
42
+ sleepSync(Math.min(20 * attempt, 200));
43
+ }
44
+ }
45
+ }
46
+
47
+ function jsonText(value) {
48
+ return `${JSON.stringify(value, null, 2)}\n`;
49
+ }
50
+
51
+ // Write to a temporary sibling, then rename, so readers never see a partial
52
+ // file. `mode` (e.g. 0o600) is enforced on the result; without it the file
53
+ // gets the process default permissions.
54
+ function atomicWrite(filePath, content, { mode, dirMode } = {}) {
55
+ fs.mkdirSync(path.dirname(filePath), dirMode ? { recursive: true, mode: dirMode } : { recursive: true });
56
+ const temporary = `${filePath}.${process.pid}.${crypto.randomBytes(4).toString('hex')}.tmp`;
57
+ try {
58
+ fs.writeFileSync(temporary, content, mode ? { mode } : undefined);
59
+ renameWithRetry(temporary, filePath);
60
+ if (mode) fs.chmodSync(filePath, mode);
61
+ } finally {
62
+ try {
63
+ fs.unlinkSync(temporary);
64
+ } catch {
65
+ // Rename succeeded or no temporary file was written.
66
+ }
67
+ }
68
+ }
69
+
70
+ function writePrivateFile(filePath, content, options = {}) {
71
+ atomicWrite(filePath, content, { ...options, mode: 0o600 });
72
+ }
73
+
74
+ function writePrivateJson(filePath, value, options = {}) {
75
+ writePrivateFile(filePath, jsonText(value), options);
76
+ }
77
+
78
+ module.exports = {
79
+ ACTOR_ID,
80
+ renameWithRetry,
81
+ sleepSync,
82
+ sha256,
83
+ readJsonOptional,
84
+ jsonText,
85
+ atomicWrite,
86
+ writePrivateFile,
87
+ writePrivateJson
88
+ };