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
|
@@ -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
|
|
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 `
|
|
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 (`
|
|
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
|
package/core/goal-contract.md
CHANGED
|
@@ -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 (
|
|
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
|
```
|
package/core/iteration-policy.md
CHANGED
|
@@ -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**:
|
|
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
|
---
|
package/core/judge-policy.md
CHANGED
|
@@ -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`** |
|
|
41
|
-
| **`VALID`** | **`LOW`** |
|
|
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 (
|
|
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
|
|
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** |
|
|
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** |
|
|
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`
|
|
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
|
|
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:
|
|
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
|
-
-
|
|
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`.
|
package/core/runtime-safety.md
CHANGED
|
@@ -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
|
|
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`.
|
package/lib/auto-update.js
CHANGED
|
@@ -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 =
|
|
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', '.
|
|
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 ||
|
|
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
|
+
};
|