@graypark/loophaus 3.4.1 → 3.5.1

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 (151) hide show
  1. package/README.ko.md +117 -77
  2. package/README.md +110 -74
  3. package/dist/.claude-plugin/plugin.json +11 -0
  4. package/dist/LICENSE +21 -0
  5. package/dist/README.ko.md +398 -0
  6. package/dist/README.md +318 -0
  7. package/dist/bin/install.d.ts +3 -0
  8. package/dist/bin/install.d.ts.map +1 -0
  9. package/{bin/install.mjs → dist/bin/install.js} +3 -5
  10. package/dist/bin/install.js.map +1 -0
  11. package/dist/bin/loophaus.d.ts +3 -0
  12. package/dist/bin/loophaus.d.ts.map +1 -0
  13. package/dist/bin/loophaus.js +654 -0
  14. package/dist/bin/loophaus.js.map +1 -0
  15. package/dist/bin/uninstall.d.ts +8 -0
  16. package/dist/bin/uninstall.d.ts.map +1 -0
  17. package/dist/bin/uninstall.js +209 -0
  18. package/dist/bin/uninstall.js.map +1 -0
  19. package/dist/codex/commands/cancel-ralph.md +30 -0
  20. package/dist/codex/commands/ralph-loop.md +73 -0
  21. package/dist/commands/cancel-ralph.md +23 -0
  22. package/dist/commands/help.md +96 -0
  23. package/dist/commands/loop-plan.md +257 -0
  24. package/dist/commands/loop-pulse.md +38 -0
  25. package/dist/commands/loop-stop.md +29 -0
  26. package/dist/commands/loop.md +17 -0
  27. package/dist/commands/ralph-loop.md +18 -0
  28. package/dist/core/cost-tracker.d.ts +33 -0
  29. package/dist/core/cost-tracker.d.ts.map +1 -0
  30. package/dist/core/cost-tracker.js +41 -0
  31. package/dist/core/cost-tracker.js.map +1 -0
  32. package/dist/core/engine.d.ts +4 -0
  33. package/dist/core/engine.d.ts.map +1 -0
  34. package/dist/core/engine.js +109 -0
  35. package/dist/core/engine.js.map +1 -0
  36. package/dist/core/event-logger.d.ts +5 -0
  37. package/dist/core/event-logger.d.ts.map +1 -0
  38. package/dist/core/event-logger.js +48 -0
  39. package/dist/core/event-logger.js.map +1 -0
  40. package/dist/core/events.d.ts +34 -0
  41. package/dist/core/events.d.ts.map +1 -0
  42. package/dist/core/events.js +44 -0
  43. package/dist/core/events.js.map +1 -0
  44. package/dist/core/io-helpers.d.ts +3 -0
  45. package/dist/core/io-helpers.d.ts.map +1 -0
  46. package/dist/core/io-helpers.js +65 -0
  47. package/dist/core/io-helpers.js.map +1 -0
  48. package/dist/core/loop-registry.d.ts +10 -0
  49. package/dist/core/loop-registry.d.ts.map +1 -0
  50. package/dist/core/loop-registry.js +37 -0
  51. package/dist/core/loop-registry.js.map +1 -0
  52. package/dist/core/merge-strategy.d.ts +7 -0
  53. package/dist/core/merge-strategy.d.ts.map +1 -0
  54. package/dist/core/merge-strategy.js +82 -0
  55. package/dist/core/merge-strategy.js.map +1 -0
  56. package/dist/core/parallel-runner.d.ts +32 -0
  57. package/dist/core/parallel-runner.d.ts.map +1 -0
  58. package/dist/core/parallel-runner.js +88 -0
  59. package/dist/core/parallel-runner.js.map +1 -0
  60. package/dist/core/policy.d.ts +22 -0
  61. package/dist/core/policy.d.ts.map +1 -0
  62. package/dist/core/policy.js +54 -0
  63. package/dist/core/policy.js.map +1 -0
  64. package/dist/core/quality-scorer.d.ts +40 -0
  65. package/dist/core/quality-scorer.d.ts.map +1 -0
  66. package/dist/core/quality-scorer.js +128 -0
  67. package/dist/core/quality-scorer.js.map +1 -0
  68. package/dist/core/refine-loop.d.ts +16 -0
  69. package/dist/core/refine-loop.d.ts.map +1 -0
  70. package/dist/core/refine-loop.js +26 -0
  71. package/dist/core/refine-loop.js.map +1 -0
  72. package/dist/core/session.d.ts +27 -0
  73. package/dist/core/session.d.ts.map +1 -0
  74. package/dist/core/session.js +67 -0
  75. package/dist/core/session.js.map +1 -0
  76. package/dist/core/trace-analyzer.d.ts +28 -0
  77. package/dist/core/trace-analyzer.d.ts.map +1 -0
  78. package/dist/core/trace-analyzer.js +46 -0
  79. package/dist/core/trace-analyzer.js.map +1 -0
  80. package/dist/core/types.d.ts +99 -0
  81. package/dist/core/types.d.ts.map +1 -0
  82. package/dist/core/types.js +2 -0
  83. package/dist/core/types.js.map +1 -0
  84. package/dist/core/validate.d.ts +7 -0
  85. package/dist/core/validate.d.ts.map +1 -0
  86. package/dist/core/validate.js +55 -0
  87. package/dist/core/validate.js.map +1 -0
  88. package/dist/core/worktree.d.ts +13 -0
  89. package/dist/core/worktree.d.ts.map +1 -0
  90. package/dist/core/worktree.js +108 -0
  91. package/dist/core/worktree.js.map +1 -0
  92. package/dist/hooks/hooks.json +15 -0
  93. package/dist/hooks/stop-hook.mjs +111 -0
  94. package/dist/lib/paths.d.ts +18 -0
  95. package/dist/lib/paths.d.ts.map +1 -0
  96. package/dist/lib/paths.js +74 -0
  97. package/dist/lib/paths.js.map +1 -0
  98. package/dist/lib/stop-hook-core.d.ts +19 -0
  99. package/dist/lib/stop-hook-core.d.ts.map +1 -0
  100. package/dist/lib/stop-hook-core.js +36 -0
  101. package/dist/lib/stop-hook-core.js.map +1 -0
  102. package/dist/package.json +61 -0
  103. package/dist/platforms/claude-code/adapter.mjs +20 -0
  104. package/dist/platforms/claude-code/installer.d.mts +3 -0
  105. package/dist/platforms/claude-code/installer.mjs +173 -0
  106. package/dist/platforms/codex-cli/adapter.mjs +20 -0
  107. package/dist/platforms/codex-cli/installer.d.mts +2 -0
  108. package/dist/platforms/codex-cli/installer.mjs +247 -0
  109. package/dist/platforms/kiro-cli/adapter.mjs +21 -0
  110. package/dist/platforms/kiro-cli/installer.d.mts +3 -0
  111. package/dist/platforms/kiro-cli/installer.mjs +257 -0
  112. package/dist/scripts/setup-ralph-loop.sh +145 -0
  113. package/dist/skills/ralph-claude-cancel/SKILL.md +23 -0
  114. package/dist/skills/ralph-claude-interview/SKILL.md +184 -0
  115. package/dist/skills/ralph-claude-loop/SKILL.md +101 -0
  116. package/dist/skills/ralph-claude-orchestrator/SKILL.md +129 -0
  117. package/dist/skills/ralph-interview/SKILL.md +275 -0
  118. package/dist/skills/ralph-orchestrator/SKILL.md +254 -0
  119. package/dist/store/state-store.d.ts +17 -0
  120. package/dist/store/state-store.d.ts.map +1 -0
  121. package/dist/store/state-store.js +108 -0
  122. package/dist/store/state-store.js.map +1 -0
  123. package/hooks/stop-hook.mjs +6 -6
  124. package/package.json +11 -7
  125. package/platforms/claude-code/installer.d.mts +3 -0
  126. package/platforms/claude-code/installer.mjs +2 -2
  127. package/platforms/codex-cli/installer.d.mts +2 -0
  128. package/platforms/codex-cli/installer.mjs +1 -1
  129. package/platforms/kiro-cli/installer.d.mts +3 -0
  130. package/bin/loophaus.mjs +0 -521
  131. package/bin/uninstall.mjs +0 -255
  132. package/core/cost-tracker.mjs +0 -44
  133. package/core/engine.mjs +0 -123
  134. package/core/event-logger.mjs +0 -37
  135. package/core/events.mjs +0 -48
  136. package/core/io-helpers.mjs +0 -33
  137. package/core/loop-registry.mjs +0 -37
  138. package/core/loop.schema.json +0 -29
  139. package/core/merge-strategy.mjs +0 -72
  140. package/core/parallel-runner.mjs +0 -94
  141. package/core/policy.mjs +0 -58
  142. package/core/quality-scorer.mjs +0 -136
  143. package/core/refine-loop.mjs +0 -29
  144. package/core/session.mjs +0 -66
  145. package/core/state.schema.json +0 -24
  146. package/core/trace-analyzer.mjs +0 -51
  147. package/core/validate.mjs +0 -54
  148. package/core/worktree.mjs +0 -97
  149. package/lib/paths.mjs +0 -99
  150. package/lib/stop-hook-core.mjs +0 -42
  151. package/store/state-store.mjs +0 -106
package/README.ko.md CHANGED
@@ -10,7 +10,7 @@
10
10
  <a href="https://github.com/vcz-Gray/loophaus/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg?style=flat-square" alt="license" /></a>
11
11
  <img src="https://img.shields.io/badge/node-%3E%3D20-brightgreen.svg?style=flat-square" alt="node version" />
12
12
  <img src="https://img.shields.io/badge/platform-Claude%20Code%20%7C%20Codex%20CLI%20%7C%20Kiro%20CLI-purple.svg?style=flat-square" alt="platform" />
13
- <img src="https://img.shields.io/badge/tests-36%20passing-brightgreen.svg?style=flat-square" alt="tests" />
13
+ <img src="https://img.shields.io/badge/tests-296%20passing-brightgreen.svg?style=flat-square" alt="tests" />
14
14
  </p>
15
15
 
16
16
  <p align="center">
@@ -60,8 +60,10 @@ AI 에이전트가 연속 루프에서 태스크를 수행합니다. 매 반복
60
60
  │ 1. prd.json + progress 읽기 │
61
61
  │ 2. 다음 스토리 선택 (passes=false)│
62
62
  │ 3. 구현 + 검증 │
63
- │ 4. 커밋 + progress 업데이트
64
- │ 5. 종료 시도
63
+ │ 4. 품질 측정 (score 0-100)
64
+ │ 5. 개선 루프 (유지/폐기)
65
+ │ 6. 커밋 + progress 업데이트 │
66
+ │ 7. 종료 시도 │
65
67
  │ │ │
66
68
  │ Stop Hook이 가로채기 │
67
69
  │ 프롬프트 재주입 │
@@ -76,9 +78,12 @@ AI 에이전트가 연속 루프에서 태스크를 수행합니다. 매 반복
76
78
  ## 빠른 시작
77
79
 
78
80
  ```bash
79
- npx @graypark/loophaus install
81
+ npm install -g @graypark/loophaus
82
+ loophaus install
80
83
  ```
81
84
 
85
+ > **참고:** `npx @graypark/loophaus install`은 일부 npm 버전에서 bin 해석 캐시 버그로 실패할 수 있습니다. 위의 글로벌 설치 방식을 권장합니다.
86
+
82
87
  이후 AI 코딩 세션에서:
83
88
 
84
89
  ```
@@ -151,26 +156,33 @@ loophaus는 세 개의 주요 코딩 에이전트 플랫폼을 지원합니다:
151
156
  | Stop hook | bash 기반 | Node.js 기반 | bash 기반 |
152
157
  | 루프 실행 | Skill tool | 네이티브 커맨드 | 네이티브 커맨드 |
153
158
  | 멀티 에이전트 | Agent tool | 서브에이전트 | 서브에이전트 |
154
- | 상태 파일 | `.claude/ralph-loop.local.md` | `progress.txt` | `progress.txt` |
159
+ | 상태 파일 | `.loophaus/state.json` | `.loophaus/state.json` | `.loophaus/state.json` |
155
160
 
156
161
  ## 설치
157
162
 
158
- ### 자동 감지 설치 (권장)
163
+ ### 글로벌 설치 (권장)
164
+
165
+ ```bash
166
+ npm install -g @graypark/loophaus
167
+ loophaus install
168
+ ```
159
169
 
160
- 설치된 호스트를 자동으로 감지하여 설치합니다:
170
+ ### npx로 설치
161
171
 
162
172
  ```bash
163
173
  npx @graypark/loophaus install
164
174
  ```
165
175
 
176
+ > `npx`는 일부 npm 버전에서 bin 해석 캐시 버그로 실패할 수 있습니다. 실패 시 위의 글로벌 설치를 사용하세요.
177
+
166
178
  ### 호스트별 설치
167
179
 
168
180
  특정 호스트만 대상으로 설치:
169
181
 
170
182
  ```bash
171
- npx @graypark/loophaus install --claude # Claude Code만
172
- npx @graypark/loophaus install --host codex-cli # Codex CLI만
173
- npx @graypark/loophaus install --kiro # Kiro CLI만
183
+ loophaus install --claude # Claude Code만
184
+ loophaus install --host codex-cli # Codex CLI만
185
+ loophaus install --kiro # Kiro CLI만
174
186
  ```
175
187
 
176
188
  | 플래그 | 설명 |
@@ -201,55 +213,110 @@ npx @graypark/loophaus install --kiro # Kiro CLI만
201
213
  ## CLI
202
214
 
203
215
  ```bash
204
- npx @graypark/loophaus install # 자동 감지 설치
205
- npx @graypark/loophaus status # 설치 상태 확인
206
- npx @graypark/loophaus stats # 루프 실행 통계
207
- npx @graypark/loophaus uninstall # 제거
208
- npx @graypark/loophaus --version # 버전 확인
216
+ loophaus install # 자동 감지 설치
217
+ loophaus status # 설치 상태 확인
218
+ loophaus stats # 루프 실행 통계
219
+ loophaus quality # 품질 점수 측정
220
+ loophaus uninstall # 제거
221
+ loophaus --version # 버전 확인
222
+ ```
223
+
224
+ ## Quality Loop (v3.4.0+)
225
+
226
+ v3.4.0에서 도입된 **Quality Loop** — [karpathy/autoresearch](https://github.com/karpathy/autoresearch)의 실험→측정→유지/폐기 패턴을 코드 품질 개선에 적용.
227
+
228
+ 테스트가 통과하면 "완료"로 처리하던 기존 방식 대신, `/loop-plan`이 이제 **품질을 측정**(0-100)하고 임계값을 충족할 때까지 **반복 개선**합니다.
229
+
230
+ ```
231
+ Phase 4: 구현
232
+
233
+ Phase 5: 측정 (score 0-100)
234
+ ↓ ↑
235
+ Phase 6: 개선 루프
236
+ 점수 향상? → 유지 (commit)
237
+ 점수 하락? → 폐기 (git reset)
238
+ 최대 시도 도달? → 다음으로
239
+
240
+ Phase 7: 보고서 (품질 점수 포함)
241
+ ```
242
+
243
+ | autoresearch | loophaus |
244
+ |-------------|----------|
245
+ | `val_bpb` | quality score (가중치: tests, typecheck, lint, verify, diff, custom) |
246
+ | `results.tsv` | `.loophaus/results.tsv` |
247
+ | keep → advance | 점수 향상 → commit |
248
+ | discard → revert | 점수 하락 → `git reset --hard` |
249
+ | NEVER STOP | 스토리당 최대 3회 시도 (설정 가능) |
250
+
251
+ ### 설정
252
+
253
+ ```json
254
+ {
255
+ "qualityThreshold": 80,
256
+ "maxRefineAttempts": 3,
257
+ "qualityConfig": {
258
+ "weights": { "tests": 30, "typecheck": 25, "lint": 15, "verify": 15, "diff": 10, "custom": 5 }
259
+ }
260
+ }
261
+ ```
262
+
263
+ ### CLI
264
+
265
+ ```bash
266
+ loophaus quality # 전체 스토리 품질 측정
267
+ loophaus quality --story US-001 # 특정 스토리 품질 측정
209
268
  ```
210
269
 
211
270
  ## 아키텍처
212
271
 
213
272
  ```
214
273
  loophaus/
215
- ├── .claude-plugin/plugin.json # Claude Code 마켓플레이스 매니페스트
216
274
  ├── bin/
217
- │ ├── loophaus.mjs # CLI 진입점
218
- │ ├── install.mjs # 크로스 플랫폼 설치기
219
- │ └── uninstall.mjs # 제거기
220
- ├── hooks/
221
- └── stop-hook.mjs # 핵심 루프 엔진 (Node.js)
222
- ├── commands/
223
- │ ├── loop.md # /loop 커맨드
224
- │ ├── loop-plan.md # /loop-plan 커맨드
225
- │ ├── loop-stop.md # /loop-stop 커맨드
226
- │ ├── loop-pulse.md # /loop-pulse 커맨드
227
- └── help.md # /help 커맨드
228
- ├── platforms/ # 호스트별 어댑터
229
- ├── store/ # 상태 저장소
230
- ├── core/ # 핵심 로직
231
- ├── skills/
232
- │ ├── ralph-interview/SKILL.md # Codex: 인터랙티브 커맨드 생성기
233
- │ ├── ralph-orchestrator/SKILL.md # Codex: 멀티 에이전트 패턴
234
- ├── ralph-claude-interview/SKILL.md # Claude: 인터뷰 + Skill tool 호출
235
- ├── ralph-claude-loop/SKILL.md # Claude: PRD 기반 루프
236
- ├── ralph-claude-cancel/SKILL.md # Claude: 루프 취소
237
- │ └── ralph-claude-orchestrator/SKILL.md # Claude: Agent tool 패턴
275
+ │ ├── loophaus.ts # CLI 진입점
276
+ │ ├── install.ts # 크로스 플랫폼 설치기
277
+ │ └── uninstall.ts # 제거기
278
+ ├── core/
279
+ ├── types.ts # 공유 TypeScript 인터페이스
280
+ ├── engine.ts # 핵심 루프 엔진
281
+ │ ├── event-logger.ts # 이벤트 추적
282
+ │ ├── quality-scorer.ts # 품질 측정 (점수, 평가, 로깅)
283
+ │ ├── refine-loop.ts # 유지/폐기 개선 로직
284
+ │ ├── validate.ts # PRD + 상태 스키마 검증
285
+ ├── policy.ts # 루프 정책 평가
286
+ ├── cost-tracker.ts # 토큰 비용 추정
287
+ ├── trace-analyzer.ts # 트레이스 분석 + 비교
288
+ ├── worktree.ts # Git 워크트리 관리
289
+ ├── merge-strategy.ts # 병렬 머지 전략
290
+ │ ├── parallel-runner.ts # 멀티 워크트리 오케스트레이션
291
+ │ ├── session.ts # 체크포인트 / 세션 관리
292
+ └── loop-registry.ts # 멀티 루프 레지스트리
293
+ ├── store/
294
+ └── state-store.ts # 루프 상태 저장소
238
295
  ├── lib/
239
- │ ├── paths.mjs # 크로스 플랫폼 경로
240
- ├── state.mjs # 루프 상태 관리
241
- │ └── stop-hook-core.mjs # 테스트 가능한 hook 로직
242
- └── tests/ # 36개 테스트 케이스 (vitest)
296
+ │ ├── paths.ts # 크로스 플랫폼 경로
297
+ └── stop-hook-core.ts # 테스트 가능한 hook 로직
298
+ ├── platforms/
299
+ │ ├── claude-code/installer.mjs # 플러그인 캐시 설치기
300
+ │ ├── codex-cli/installer.mjs # hooks.json 설치기
301
+ │ └── kiro-cli/installer.mjs # agents/ + steering/ 설치기
302
+ ├── hooks/
303
+ │ └── stop-hook.mjs # 범용 Stop hook (Node.js)
304
+ ├── commands/ # 슬래시 커맨드 정의
305
+ ├── skills/ # 플랫폼별 스킬 정의
306
+ ├── .claude-plugin/
307
+ │ └── plugin.json # Claude Code 마켓플레이스 매니페스트
308
+ ├── dist/ # 컴파일 출력 (tsc)
309
+ └── tests/ # 296개 테스트 케이스 (vitest)
243
310
  ```
244
311
 
245
312
  ## PRD 포맷
246
313
 
247
- loophaus는 **ralph-skills 호환** `prd.json` 포맷을 사용합니다:
314
+ loophaus는 `prd.json` 포맷을 사용합니다:
248
315
 
249
316
  ```json
250
317
  {
251
318
  "project": "MyApp",
252
- "branchName": "ralph/auth-system",
319
+ "branchName": "feature/auth-system",
253
320
  "description": "JWT 인증 시스템과 로그인 UI",
254
321
  "userStories": [
255
322
  {
@@ -271,37 +338,6 @@ loophaus는 **ralph-skills 호환** `prd.json` 포맷을 사용합니다:
271
338
 
272
339
  각 스토리는 **한 번의 반복**(하나의 컨텍스트 윈도우)에서 완료할 수 있는 크기입니다. 의존성은 priority 순으로 정렬됩니다.
273
340
 
274
- ## ralph-codex에서 마이그레이션
275
-
276
- 기존에 `ralph-codex`를 사용하고 있었다면, loophaus가 자동으로 마이그레이션을 처리합니다:
277
-
278
- - **상태 파일 호환** — 기존 `prd.json`과 `progress.txt`를 그대로 사용 가능
279
- - **자동 감지** — 설치 시 기존 ralph-codex 설정을 감지하고 loophaus 포맷으로 업그레이드
280
- - **커맨드 매핑** — 기존 `/ralph-interview` → `/loop-plan`, `/ralph-loop` → `/loop`, `/cancel-ralph` → `/loop-stop`
281
-
282
- 마이그레이션 방법:
283
-
284
- ```bash
285
- # 기존 ralph-codex 제거
286
- npx @graypark/ralph-codex uninstall
287
-
288
- # loophaus 설치 (기존 상태 파일 자동 인식)
289
- npx @graypark/loophaus install
290
- ```
291
-
292
- 기존 PRD 파일은 수정 없이 그대로 동작합니다. `progress.txt`에 축적된 학습 내용도 보존됩니다.
293
-
294
- ## 생태계 호환성
295
-
296
- loophaus는 기존 Ralph 도구들과 호환됩니다:
297
-
298
- | 도구 | 호환성 |
299
- | --- | --- |
300
- | `ralph-skills:prd` | 동일한 `prd.json` 포맷 — 거기서 PRD를 생성하고 여기서 루프 실행 |
301
- | `ralph-skills:ralph` | 동일한 `progress.txt`, `passes` 추적, `COMPLETE` promise |
302
- | 공식 `ralph-loop` 플러그인 | PRD 파일이 양쪽 stop hook에서 동작 |
303
- | `snarktank/ralph` | 호환되는 PRD 구조 및 반복 패턴 |
304
-
305
341
  ## 멀티 에이전트 오케스트레이션
306
342
 
307
343
  여러 서비스에 걸치거나 광범위한 탐색이 필요한 태스크에 사용합니다:
@@ -331,19 +367,23 @@ Phase 2 — 순차 수정 (루프):
331
367
  ## 업데이트
332
368
 
333
369
  ```bash
334
- npx @graypark/loophaus install --force
370
+ npm install -g @graypark/loophaus@latest
371
+ loophaus install --force
335
372
  ```
336
373
 
337
374
  ## 제거
338
375
 
339
376
  ```bash
340
- npx @graypark/loophaus uninstall
377
+ loophaus uninstall
378
+ npm uninstall -g @graypark/loophaus
341
379
  ```
342
380
 
343
381
  ## 개발
344
382
 
345
383
  ```bash
346
- npm install && npm test # 36개 테스트
384
+ npm install && npm test # 296개 테스트
385
+ npm run typecheck # TypeScript strict 모드
386
+ npm run build # dist/로 컴파일
347
387
  npx vitest # watch 모드
348
388
  ```
349
389
 
package/README.md CHANGED
@@ -10,7 +10,7 @@
10
10
  <a href="https://github.com/vcz-Gray/loophaus/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg?style=flat-square" alt="license" /></a>
11
11
  <img src="https://img.shields.io/badge/node-%3E%3D20-brightgreen.svg?style=flat-square" alt="node version" />
12
12
  <img src="https://img.shields.io/badge/platform-Claude%20Code%20%7C%20Codex%20CLI%20%7C%20Kiro%20CLI-purple.svg?style=flat-square" alt="platform" />
13
- <img src="https://img.shields.io/badge/tests-36%20passing-brightgreen.svg?style=flat-square" alt="tests" />
13
+ <img src="https://img.shields.io/badge/tests-296%20passing-brightgreen.svg?style=flat-square" alt="tests" />
14
14
  </p>
15
15
 
16
16
  <h3 align="center">Control plane for coding agents — iterative dev loops across Claude Code, Codex CLI, and Kiro CLI.</h3>
@@ -62,8 +62,10 @@ An AI agent works on a task in a continuous loop. Each iteration starts with fre
62
62
  │ 1. Read prd.json + progress │
63
63
  │ 2. Pick next story (passes=false)│
64
64
  │ 3. Implement + verify │
65
- │ 4. Commit + update progress
66
- │ 5. Exit attempt
65
+ │ 4. Evaluate (score 0-100)
66
+ │ 5. Refine loop (keep/discard)
67
+ │ 6. Commit + update progress │
68
+ │ 7. Exit attempt │
67
69
  │ │ │
68
70
  │ Stop Hook intercepts │
69
71
  │ Re-injects prompt │
@@ -81,9 +83,12 @@ An AI agent works on a task in a continuous loop. Each iteration starts with fre
81
83
  ## Quick Start
82
84
 
83
85
  ```bash
84
- npx @graypark/loophaus install
86
+ npm install -g @graypark/loophaus
87
+ loophaus install
85
88
  ```
86
89
 
90
+ > **Note:** `npx @graypark/loophaus install` may fail on some npm versions due to a bin resolution cache bug. Use the global install above for reliable setup.
91
+
87
92
  The installer auto-detects your host (Claude Code, Codex CLI, or Kiro CLI) and sets up everything — stop hook, commands, and skills.
88
93
 
89
94
  Then in your AI coding session:
@@ -112,22 +117,31 @@ That's it. The interview generates a PRD, activates the loop, and starts impleme
112
117
  | **Commands** | `/reload-plugins` | native | steering manual mode |
113
118
  | **Multi-agent** | Agent tool | subprocesses | steering agents |
114
119
 
115
- All three platforms share the same core engine (`core/engine.mjs`) and state store (`store/state-store.mjs`). Platform-specific adapters handle the differences.
120
+ All three platforms share the same core engine (`core/engine.ts`) and state store (`store/state-store.ts`). Platform-specific adapters handle the differences.
116
121
 
117
122
  ## Installation
118
123
 
119
- ### Auto-detect (recommended)
124
+ ### Global install (recommended)
125
+
126
+ ```bash
127
+ npm install -g @graypark/loophaus
128
+ loophaus install
129
+ ```
130
+
131
+ ### Via npx
120
132
 
121
133
  ```bash
122
134
  npx @graypark/loophaus install
123
135
  ```
124
136
 
137
+ > `npx` may fail on some npm versions due to a bin resolution cache bug. If it does, use the global install above.
138
+
125
139
  ### Specify host
126
140
 
127
141
  ```bash
128
- npx @graypark/loophaus install --host claude-code
129
- npx @graypark/loophaus install --host codex-cli
130
- npx @graypark/loophaus install --host kiro-cli
142
+ loophaus install --host claude-code
143
+ loophaus install --host codex-cli
144
+ loophaus install --host kiro-cli
131
145
  ```
132
146
 
133
147
  ### Flags
@@ -146,16 +160,54 @@ loophaus ships a standalone CLI for management tasks:
146
160
  loophaus install # Install to detected host
147
161
  loophaus status # Show current loop state and active host
148
162
  loophaus stats # Iteration history and completion metrics
163
+ loophaus quality # Run quality scoring on current stories
149
164
  loophaus uninstall # Clean removal from all hosts
150
165
  ```
151
166
 
152
- Or via npx:
167
+ ## Quality Loop (v3.4.0+)
168
+
169
+ loophaus v3.4.0 introduces the **Quality Loop** — inspired by [karpathy/autoresearch](https://github.com/karpathy/autoresearch)'s experiment→measure→keep/discard pattern.
170
+
171
+ Instead of simply marking a story as "done" when tests pass, `/loop-plan` now **measures quality** (0-100) and **iteratively refines** until the score meets the threshold.
172
+
173
+ ```
174
+ Phase 4: Implement
175
+
176
+ Phase 5: Evaluate (score 0-100)
177
+ ↓ ↑
178
+ Phase 6: Refine Loop
179
+ score improved? → keep (commit)
180
+ score declined? → discard (git reset)
181
+ max attempts reached? → move on
182
+
183
+ Phase 7: Report (with quality scores)
184
+ ```
185
+
186
+ | autoresearch | loophaus |
187
+ |-------------|----------|
188
+ | `val_bpb` | quality score (weighted: tests, typecheck, lint, verify, diff, custom) |
189
+ | `results.tsv` | `.loophaus/results.tsv` |
190
+ | keep → advance | score improved → commit |
191
+ | discard → revert | score declined → `git reset --hard` |
192
+ | NEVER STOP | max 3 attempts per story (configurable) |
193
+
194
+ ### Configuration
195
+
196
+ ```json
197
+ {
198
+ "qualityThreshold": 80,
199
+ "maxRefineAttempts": 3,
200
+ "qualityConfig": {
201
+ "weights": { "tests": 30, "typecheck": 25, "lint": 15, "verify": 15, "diff": 10, "custom": 5 }
202
+ }
203
+ }
204
+ ```
205
+
206
+ ### CLI
153
207
 
154
208
  ```bash
155
- npx @graypark/loophaus install
156
- npx @graypark/loophaus status
157
- npx @graypark/loophaus stats
158
- npx @graypark/loophaus uninstall
209
+ loophaus quality # Score all stories
210
+ loophaus quality --story US-001 # Score a specific story
159
211
  ```
160
212
 
161
213
  ## Architecture
@@ -163,58 +215,51 @@ npx @graypark/loophaus uninstall
163
215
  ```
164
216
  loophaus/
165
217
  ├── bin/
166
- │ ├── loophaus.mjs # CLI entry point
167
- │ ├── install.mjs # Cross-platform installer
168
- │ └── uninstall.mjs # Clean uninstaller
218
+ │ ├── loophaus.ts # CLI entry point
219
+ │ ├── install.ts # Cross-platform installer
220
+ │ └── uninstall.ts # Clean uninstaller
169
221
  ├── core/
170
- │ ├── engine.mjs # Core loop engine (shared)
171
- │ ├── event-logger.mjs # Iteration event tracking
172
- └── loop.schema.json # PRD validation schema
222
+ │ ├── types.ts # Shared TypeScript interfaces
223
+ │ ├── engine.ts # Core loop engine (shared)
224
+ ├── event-logger.ts # Iteration event tracking
225
+ │ ├── quality-scorer.ts # Quality scoring (score, evaluate, log)
226
+ │ ├── refine-loop.ts # Keep/discard refinement logic
227
+ │ ├── validate.ts # PRD + state schema validation
228
+ │ ├── policy.ts # Loop policy evaluation
229
+ │ ├── cost-tracker.ts # Token cost estimation
230
+ │ ├── trace-analyzer.ts # Trace analysis + comparison
231
+ │ ├── worktree.ts # Git worktree lifecycle
232
+ │ ├── merge-strategy.ts # Parallel merge strategies
233
+ │ ├── parallel-runner.ts # Multi-worktree orchestration
234
+ │ ├── session.ts # Checkpoint / session management
235
+ │ └── loop-registry.ts # Multi-loop registry
173
236
  ├── store/
174
- │ └── state-store.mjs # Loop state persistence
237
+ │ └── state-store.ts # Loop state persistence
238
+ ├── lib/
239
+ │ ├── paths.ts # Cross-platform path resolution
240
+ │ └── stop-hook-core.ts # Testable hook logic
175
241
  ├── platforms/
176
- │ ├── claude-code/
177
- ├── adapter.mjs # Claude Code platform adapter
178
- └── installer.mjs # Plugin cache installer
179
- │ ├── codex-cli/
180
- │ │ ├── adapter.mjs # Codex CLI platform adapter
181
- │ │ └── installer.mjs # hooks.json installer
182
- │ └── kiro-cli/
183
- │ ├── adapter.mjs # Kiro CLI platform adapter
184
- │ └── installer.mjs # agents/ + steering/ installer
242
+ │ ├── claude-code/installer.mjs # Plugin cache installer
243
+ │ ├── codex-cli/installer.mjs # hooks.json installer
244
+ │ └── kiro-cli/installer.mjs # agents/ + steering/ installer
185
245
  ├── hooks/
186
- ├── stop-hook.mjs # Universal stop hook (Node.js)
187
- │ └── hooks.json # Hook configuration template
188
- ├── commands/
189
- │ ├── loop-plan.md # /loop-plan command definition
190
- │ ├── loop.md # /loop command definition
191
- │ ├── loop-stop.md # /loop-stop command definition
192
- │ ├── loop-pulse.md # /loop-pulse command definition
193
- │ └── help.md # /help command definition
194
- ├── skills/
195
- │ ├── ralph-interview/ # Interactive PRD generator
196
- │ ├── ralph-orchestrator/ # Multi-agent patterns
197
- │ ├── ralph-claude-interview/ # Claude Code interview + Skill tool
198
- │ ├── ralph-claude-loop/ # Claude Code PRD-driven loop
199
- │ ├── ralph-claude-cancel/ # Claude Code cancel
200
- │ └── ralph-claude-orchestrator/# Claude Code Agent tool patterns
201
- ├── lib/
202
- │ ├── paths.mjs # Cross-platform path resolution
203
- │ ├── state.mjs # Legacy state management
204
- │ └── stop-hook-core.mjs # Testable hook logic
246
+ └── stop-hook.mjs # Universal stop hook (Node.js)
247
+ ├── commands/ # Slash command definitions
248
+ ├── skills/ # Platform-specific skill definitions
205
249
  ├── .claude-plugin/
206
250
  │ └── plugin.json # Claude Code marketplace manifest
207
- └── tests/ # 36 test cases (vitest)
251
+ ├── dist/ # Compiled output (tsc)
252
+ └── tests/ # 296 test cases (vitest)
208
253
  ```
209
254
 
210
255
  ## PRD Format
211
256
 
212
- loophaus uses a `prd.json` format compatible with the ralph-skills ecosystem:
257
+ loophaus uses a `prd.json` format:
213
258
 
214
259
  ```json
215
260
  {
216
261
  "project": "MyApp",
217
- "branchName": "loop/auth-system",
262
+ "branchName": "feature/auth-system",
218
263
  "description": "JWT authentication with login UI",
219
264
  "userStories": [
220
265
  {
@@ -236,30 +281,19 @@ loophaus uses a `prd.json` format compatible with the ralph-skills ecosystem:
236
281
 
237
282
  Each story is sized to complete in one iteration (one context window). Dependencies are ordered by priority. The loop engine picks the next story where `passes` is `false` and works on it until verification succeeds.
238
283
 
239
- ## Migrating from ralph-codex
284
+ ## Update
240
285
 
241
- `@graypark/ralph-codex` has been deprecated in favor of `@graypark/loophaus`. The migration is straightforward:
242
-
243
- 1. **Install loophaus** it replaces ralph-codex entirely:
244
- ```bash
245
- npx @graypark/loophaus install --force
246
- ```
247
-
248
- 2. **State files auto-migrate** — Existing `prd.json` and `progress.txt` files are fully compatible. No changes needed.
249
-
250
- 3. **Command mapping:**
286
+ ```bash
287
+ npm install -g @graypark/loophaus@latest
288
+ loophaus install --force
289
+ ```
251
290
 
252
- | ralph-codex | loophaus |
253
- |-------------|----------|
254
- | `/ralph-interview` | `/loop-plan` |
255
- | `/ralph-loop` | `/loop` |
256
- | `/cancel-ralph` | `/loop-stop` |
257
- | (none) | `/loop-pulse` |
291
+ ## Uninstall
258
292
 
259
- 4. **Uninstall the old package** (optional):
260
- ```bash
261
- npx @graypark/ralph-codex uninstall
262
- ```
293
+ ```bash
294
+ loophaus uninstall
295
+ npm uninstall -g @graypark/loophaus
296
+ ```
263
297
 
264
298
  ## Development
265
299
 
@@ -267,7 +301,9 @@ Each story is sized to complete in one iteration (one context window). Dependenc
267
301
  git clone https://github.com/vcz-Gray/loophaus.git
268
302
  cd loophaus
269
303
  npm install
270
- npm test # 36 test cases
304
+ npm test # 296 test cases
305
+ npm run typecheck # TypeScript strict mode
306
+ npm run build # Compile to dist/
271
307
  npx vitest # watch mode
272
308
  ```
273
309
 
@@ -0,0 +1,11 @@
1
+ {
2
+ "name": "loophaus",
3
+ "description": "loophaus — Control plane for coding agents",
4
+ "version": "2.0.1",
5
+ "author": {
6
+ "name": "graypark",
7
+ "email": "vcz.graypark@gmail.com"
8
+ },
9
+ "skills": "./skills/",
10
+ "keywords": ["loophaus", "loop", "control-plane", "agents"]
11
+ }
package/dist/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Viewcommz
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.