ai-engineering-loop 2.2.0 → 2.3.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 (103) 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-verify.md +3 -3
  7. package/.claude/agents/judge.md +5 -2
  8. package/.grok/agents/judge.md +5 -2
  9. package/CHANGELOG.md +35 -0
  10. package/agents/maker.md +1 -1
  11. package/agents/shared/judge.body.md +5 -2
  12. package/bin/ai-engineering-loop.js +303 -77
  13. package/core/definition-of-done.md +2 -2
  14. package/core/escalation-policy.md +1 -1
  15. package/core/goal-contract.md +1 -1
  16. package/core/iteration-policy.md +2 -1
  17. package/core/judge-policy.md +10 -4
  18. package/core/orchestration-model.md +8 -7
  19. package/core/repo-config-schema.md +2 -2
  20. package/core/runtime-safety.md +3 -3
  21. package/lib/auto-update.js +8 -14
  22. package/lib/claimed-vs-reality.js +2 -2
  23. package/lib/cli-args.js +3 -1
  24. package/lib/docs.js +1 -1
  25. package/lib/doctor.js +0 -6
  26. package/lib/escalation.js +1 -1
  27. package/lib/fsutil.js +88 -0
  28. package/lib/gates.js +69 -27
  29. package/lib/generate-workflow.js +0 -29
  30. package/lib/goal-runtime.js +3 -2
  31. package/lib/guard-hooks.js +26 -7
  32. package/lib/guard.js +100 -10
  33. package/lib/hosts/doctor.js +1 -5
  34. package/lib/impact-map.js +4 -9
  35. package/lib/jsonl-ledger.js +104 -0
  36. package/lib/learn.js +4 -9
  37. package/lib/loop-groups.js +0 -25
  38. package/lib/migrations.js +1 -5
  39. package/lib/no-progress.js +119 -0
  40. package/lib/node-evidence.js +1 -5
  41. package/lib/orchestration.js +5 -361
  42. package/lib/personal-workflow.js +1 -1
  43. package/lib/quick.js +152 -0
  44. package/lib/receipt.js +1 -5
  45. package/lib/recipe-builder.js +3 -35
  46. package/lib/recipe-graph.js +2 -63
  47. package/lib/recipe.js +2 -4
  48. package/lib/review-ingest.js +116 -0
  49. package/lib/run-abandon.js +2 -1
  50. package/lib/run-compaction.js +4 -12
  51. package/lib/run-interactions.js +16 -71
  52. package/lib/run-lifecycle.js +25 -77
  53. package/lib/run-state.js +68 -17
  54. package/lib/run-watcher.js +11 -14
  55. package/lib/runtime-files.js +45 -1
  56. package/lib/safe-context.js +17 -6
  57. package/lib/sandbox.js +2 -1
  58. package/lib/smart-context.js +3 -13
  59. package/lib/spawn-command.js +94 -0
  60. package/lib/studio-layout.js +2 -8
  61. package/lib/studio-runtime.js +2 -1
  62. package/lib/studio-server.js +25 -5
  63. package/lib/tier.js +36 -10
  64. package/lib/user-state.js +2 -17
  65. package/lib/verification-lanes.js +115 -0
  66. package/lib/verification-recorder.js +110 -22
  67. package/lib/workflow-runtime.js +7 -4
  68. package/package.json +1 -2
  69. package/policies/review-budget.md +1 -1
  70. package/.claude/skills/ai-engineering-loop/SKILL.md +0 -62
  71. package/.claude/skills/ai-engineering-loop/references/loop-commands.md +0 -24
  72. package/.claude/skills/ai-engineering-loop/references/loop-deliver.md +0 -10
  73. package/.claude/skills/ai-engineering-loop/references/loop-goal.md +0 -11
  74. package/.claude/skills/ai-engineering-loop/references/loop-hosts.md +0 -48
  75. package/.claude/skills/ai-engineering-loop/references/loop-maker.md +0 -14
  76. package/.claude/skills/ai-engineering-loop/references/loop-review.md +0 -20
  77. package/.claude/skills/ai-engineering-loop/references/loop-risky.md +0 -9
  78. package/.claude/skills/ai-engineering-loop/references/loop-verify.md +0 -20
  79. package/.claude/skills/animate/RECIPES.md +0 -324
  80. package/.claude/skills/animate/SKILL.md +0 -207
  81. package/.claude/skills/animate-expo/RECIPES.md +0 -385
  82. package/.claude/skills/animate-expo/SKILL.md +0 -263
  83. package/.claude/skills/animation-vocabulary/SKILL.md +0 -181
  84. package/.claude/skills/apple-design/SKILL.md +0 -290
  85. package/.claude/skills/ask-sonner/API.md +0 -64
  86. package/.claude/skills/ask-sonner/SKILL.md +0 -88
  87. package/.claude/skills/backend-development/SKILL.md +0 -272
  88. package/.claude/skills/backend-development/references/api-design-guidelines.md +0 -95
  89. package/.claude/skills/backend-development/references/query-and-database-best-practices.md +0 -53
  90. package/.claude/skills/backend-development/references/security-checklist.md +0 -60
  91. package/.claude/skills/emil-design-eng/SKILL.md +0 -674
  92. package/.claude/skills/find-animation-opportunities/SKILL.md +0 -140
  93. package/.claude/skills/improve-animations/AUDIT.md +0 -115
  94. package/.claude/skills/improve-animations/PLAN-TEMPLATE.md +0 -73
  95. package/.claude/skills/improve-animations/SKILL.md +0 -109
  96. package/.claude/skills/mobile-native/SKILL.md +0 -311
  97. package/.claude/skills/pick-ui-library/SKILL.md +0 -85
  98. package/.claude/skills/prototype/PICKER.md +0 -197
  99. package/.claude/skills/prototype/SKILL.md +0 -98
  100. package/.claude/skills/review-animations/SKILL.md +0 -120
  101. package/.claude/skills/review-animations/STANDARDS.md +0 -187
  102. package/.claude/skills/write-swift/SKILL.md +0 -396
  103. 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
 
@@ -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'] },
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
+ };
package/lib/gates.js CHANGED
@@ -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: hashContent } = require('./fsutil.js');
6
6
  const {
7
7
  validateVerificationEvidence,
8
8
  validateFindingLedger,
@@ -52,6 +52,9 @@ const {
52
52
  } = require('./escalation.js');
53
53
  const { raiseTierFromDiff } = require('./tier.js');
54
54
  const { readyForDa } = require('./claimed-vs-reality.js');
55
+ const { runMaxIterations, detectNoProgress, recordIteration } = require('./no-progress.js');
56
+ const { finalVerificationStatus } = require('./verification-lanes.js');
57
+ const { checkLedgerBinding } = require('./review-ingest.js');
55
58
 
56
59
  const CLAIMED_VS_REALITY_PATH = '.ai-engineering-loop/tasks/claimed-vs-reality.md';
57
60
 
@@ -87,10 +90,6 @@ function readJsonArtifact(rootDir, runId, fileName) {
87
90
  return { filePath, value };
88
91
  }
89
92
 
90
- function hashContent(content) {
91
- return crypto.createHash('sha256').update(content).digest('hex');
92
- }
93
-
94
93
  function hashFile(filePath) {
95
94
  try {
96
95
  return hashContent(fs.readFileSync(filePath));
@@ -284,7 +283,7 @@ function judgeRequirement(rootDir, run) {
284
283
  }
285
284
  const serious = findings.filter((f) => f && (f.severity === 'BLOCKER' || f.severity === 'HIGH'));
286
285
  if (serious.length) reasons.push(`BLOCKER_OR_HIGH_FINDINGS: ${serious.map((f) => f.id).join(', ')}`);
287
- if (run.iteration >= 3) reasons.push('ITERATION_CEILING');
286
+ if (run.iteration >= runMaxIterations(rootDir, run)) reasons.push('ITERATION_CEILING');
288
287
  let escalation = null;
289
288
  try {
290
289
  escalation = assessRunEscalation(rootDir, { runId: run.runId });
@@ -298,6 +297,49 @@ function judgeRequirement(rootDir, run) {
298
297
  return { required: reasons.length > 0, tier, reasons };
299
298
  }
300
299
 
300
+ // The verdict the evidence supports. The Judge may add evidence-backed
301
+ // blocking findings (judgeFindings) that the Maker's ledger lacks; it can
302
+ // never PASS what the deterministic rules block. An ITERATE that repeats the
303
+ // previous iteration (same diff or same blocking findings) escalates.
304
+ function expectedJudgeVerdict(rootDir, run, { judgeFindings = [] } = {}) {
305
+ const verification = readJsonArtifact(rootDir, run.runId, GATE_FILES.verification).value;
306
+ const findings = readJsonArtifact(rootDir, run.runId, GATE_FILES.review).value;
307
+ const goalContract = readJsonArtifact(rootDir, run.runId, GATE_FILES.goal).value;
308
+ const ledger = judgeFindings.length
309
+ ? { ...findings, findings: [...(findings.findings || []), ...judgeFindings] }
310
+ : findings;
311
+ const expected = computeJudgeVerdict({
312
+ goalContract,
313
+ verificationEvidence: verificationForJudge(verification),
314
+ findingLedger: ledger,
315
+ activeIteration: run.iteration,
316
+ maxIterations: runMaxIterations(rootDir, run)
317
+ });
318
+ if (expected.verdict === 'ITERATE') {
319
+ const noProgress = detectNoProgress(rootDir, run, {
320
+ diffHash: run.artifacts?.diff?.sha256,
321
+ blockingFindings: expected.blockingFindings || []
322
+ });
323
+ if (noProgress) {
324
+ return {
325
+ ...expected,
326
+ verdict: 'ESCALATE',
327
+ reason: noProgress,
328
+ action: 'Human escalation: the loop stopped making progress.'
329
+ };
330
+ }
331
+ }
332
+ return expected;
333
+ }
334
+
335
+ function validateJudgeFindings(value) {
336
+ if (value == null) return [];
337
+ if (!Array.isArray(value)) throw gateError('Judge gate failed', ['judgeFindings must be an array']);
338
+ const check = validateFindingLedger({ findings: value });
339
+ if (!check.valid) throw gateError('Judge gate failed', [`judgeFindings: ${check.reason}`]);
340
+ return value.map((finding) => ({ ...finding, source: 'judge' }));
341
+ }
342
+
301
343
  function writeDeterministicVerdictIfEligible(rootDir, run) {
302
344
  const filePath = artifactPath(rootDir, run.runId, GATE_FILES.judge);
303
345
  if (fs.existsSync(filePath)) return false;
@@ -307,16 +349,7 @@ function writeDeterministicVerdictIfEligible(rootDir, run) {
307
349
  if (requirement.required) {
308
350
  throw gateError(`Judge subagent required for tier ${tier}; write ${GATE_FILES.judge} from its verdict`, requirement.reasons);
309
351
  }
310
- const verification = readJsonArtifact(rootDir, run.runId, GATE_FILES.verification).value;
311
- const findings = readJsonArtifact(rootDir, run.runId, GATE_FILES.review).value;
312
- const goalContract = readJsonArtifact(rootDir, run.runId, GATE_FILES.goal).value;
313
- const expected = computeJudgeVerdict({
314
- goalContract,
315
- verificationEvidence: verificationForJudge(verification),
316
- findingLedger: findings,
317
- activeIteration: run.iteration,
318
- maxIterations: 3
319
- });
352
+ const expected = expectedJudgeVerdict(rootDir, run);
320
353
  fs.writeFileSync(filePath, `${JSON.stringify({
321
354
  schemaVersion: 1,
322
355
  runId: run.runId,
@@ -458,6 +491,15 @@ function applyGate(rootDir, gate, { runId, transitionOptions = {} } = {}) {
458
491
  }
459
492
  const check = validateFindingLedger(value);
460
493
  if (!check.valid) throw gateError('Review gate failed', [check.reason]);
494
+ const binding = checkLedgerBinding(rootDir, run, value);
495
+ if (binding.errors.length) {
496
+ throw gateError('Finding Ledger does not match the reviewer output (LEDGER_TAMPERED)', binding.errors);
497
+ }
498
+ if (binding.binding === 'UNBOUND' && mode === RUN_MODES.UNATTENDED) {
499
+ throw gateError('UNATTENDED review needs a ledger bound to the reviewer output', [
500
+ 'Run `review ingest --run <id> --child-id <id> --file <child-output>` instead of writing findings.json'
501
+ ]);
502
+ }
461
503
  return transitionRun(rootDir, run.runId, RUN_STATES.REVIEWED, {
462
504
  gate,
463
505
  artifacts: { findings: descriptor(rootDir, filePath) }
@@ -482,19 +524,16 @@ function applyGate(rootDir, gate, { runId, transitionOptions = {} } = {}) {
482
524
  } catch (cause) {
483
525
  throw gateError(cause.message, [cause.code]);
484
526
  }
485
- const verification = readJsonArtifact(rootDir, run.runId, GATE_FILES.verification).value;
486
- const findings = readJsonArtifact(rootDir, run.runId, GATE_FILES.review).value;
487
- const goalContract = readJsonArtifact(rootDir, run.runId, GATE_FILES.goal).value;
488
- const expected = computeJudgeVerdict({
489
- goalContract,
490
- verificationEvidence: verificationForJudge(verification),
491
- findingLedger: findings,
492
- activeIteration: run.iteration,
493
- maxIterations: 3
494
- });
527
+ const judgeFindings = validateJudgeFindings(value.judgeFindings);
528
+ const expected = expectedJudgeVerdict(rootDir, run, { judgeFindings });
495
529
  if (value.verdict !== expected.verdict) {
496
- throw gateError(`Judge verdict is unsupported: expected ${expected.verdict}, received ${value.verdict}`);
530
+ throw gateError(`Judge verdict is unsupported: expected ${expected.verdict}, received ${value.verdict}`, [expected.reason]);
497
531
  }
532
+ recordIteration(rootDir, run, {
533
+ verdict: expected.verdict,
534
+ diffHash: run.artifacts?.diff?.sha256,
535
+ blockingFindings: expected.blockingFindings || []
536
+ });
498
537
  const artifacts = { verdict: descriptor(rootDir, filePath) };
499
538
  if (expected.verdict === 'PASS') {
500
539
  return transitionRun(rootDir, run.runId, RUN_STATES.JUDGED_PASS, { gate, artifacts });
@@ -527,6 +566,8 @@ function applyGate(rootDir, gate, { runId, transitionOptions = {} } = {}) {
527
566
  if (mode === RUN_MODES.ASSISTED && value.humanApproved !== true) {
528
567
  deliveryErrors.push('humanApproved must be true for ASSISTED delivery');
529
568
  }
569
+ const finalCheck = finalVerificationStatus(rootDir, run);
570
+ if (!finalCheck.satisfied) deliveryErrors.push(`Full verification required before delivery: ${finalCheck.reason}`);
530
571
  if (deliveryErrors.length) throw gateError('Delivery gate failed', deliveryErrors);
531
572
  return transitionRun(rootDir, run.runId, RUN_STATES.DELIVERED, {
532
573
  gate,
@@ -545,5 +586,6 @@ module.exports = {
545
586
  validateVerificationBundle,
546
587
  validateVerdictDocument,
547
588
  judgeRequirement,
589
+ expectedJudgeVerdict,
548
590
  applyGate
549
591
  };
@@ -41,17 +41,6 @@ function assertNoRequiredSkip(skips) {
41
41
  }
42
42
  }
43
43
 
44
- function routeDurableNote(kind) {
45
- const map = {
46
- term: 'glossary.md',
47
- process: 'lessons.md',
48
- lesson: 'lessons.md',
49
- convention: 'conventions.md',
50
- adr: 'adrs/'
51
- };
52
- return map[kind] || 'lessons.md';
53
- }
54
-
55
44
  function normalizeMakerIntern(raw) {
56
45
  const s = String(raw || '').trim();
57
46
  if (!s || /^none$/i.test(s)) return DEFAULT_MAKER_INTERN;
@@ -143,22 +132,6 @@ function parseWorkflowMarkdown(text) {
143
132
  };
144
133
  }
145
134
 
146
- function parseWorkflowFile(rootDir) {
147
- const dest = path.join(rootDir, '.ai-engineering-loop', 'workflow.md');
148
- try {
149
- const text = fs.readFileSync(dest, 'utf8');
150
- return parseWorkflowMarkdown(text);
151
- } catch {
152
- return {
153
- missing: true,
154
- required: REQUIRED_STAGES.slice(),
155
- hooks: { ...DEFAULT_HOOKS },
156
- makerIntern: DEFAULT_MAKER_INTERN,
157
- optionalSkips: []
158
- };
159
- }
160
- }
161
-
162
135
  function lessonsAreFilled(text) {
163
136
  if (!text || !text.trim()) return false;
164
137
  return /\| 20\d{2}-/.test(text);
@@ -223,11 +196,9 @@ module.exports = {
223
196
  DEFAULT_MAKER_INTERN,
224
197
  assertNoRequiredSkip,
225
198
  normalizeMakerIntern,
226
- routeDurableNote,
227
199
  workflowMarkdown,
228
200
  lessonsMarkdown,
229
201
  parseWorkflowMarkdown,
230
- parseWorkflowFile,
231
202
  writeWorkflowOverlay,
232
203
  formatGenerateWorkflowReport,
233
204
  parseWriteArg
@@ -2,6 +2,7 @@
2
2
 
3
3
  const fs = require('fs');
4
4
  const path = require('path');
5
+ const { ACTOR_ID } = require('./fsutil.js');
5
6
  const { validateGoalContract, hashFile } = require('./gates.js');
6
7
  const { sha256 } = require('./recipe.js');
7
8
  const {
@@ -22,7 +23,7 @@ function goalError(message, code, details = []) {
22
23
 
23
24
  function actorId(actor) {
24
25
  const value = String(actor || '').trim();
25
- if (!/^[A-Za-z0-9@._-]{1,64}$/.test(value)) {
26
+ if (!ACTOR_ID.test(value)) {
26
27
  throw goalError('Goal actor must be a short account identifier', 'INVALID_GOAL_ACTOR');
27
28
  }
28
29
  return value;
@@ -59,7 +60,7 @@ function normalizeDraft(value, runId) {
59
60
  contract.runId !== runId ||
60
61
  !Number.isSafeInteger(revision) ||
61
62
  revision < 1 ||
62
- !/^[A-Za-z0-9@._-]{1,64}$/.test(String(metadata.actor || '')) ||
63
+ !ACTOR_ID.test(String(metadata.actor || '')) ||
63
64
  !metadata.updatedAt ||
64
65
  !Number.isFinite(Date.parse(metadata.updatedAt)) ||
65
66
  metadata.contentHash !== contentHash