loop

Files (10)

• SKILL.md
• cycle.md · references/
• design.md · references/
• init-flow.md · references/
• safety.md · references/
• scoring.md · references/
• stop.md · references/
• driver.js.tmpl · templates/
• loop.json.tmpl · templates/
• scorecard.md.tmpl · templates/

SKILL.md (first lines)

# /caseworker:loop — 완성도 루프 (단일 진입점)

> *"Build the loop, stay the engineer."* — Addy Osmani
> 임의의 코드 프로젝트를 *계산 가능한 완성도 점수*로 측정→triage→fix→verify→re-score 하는 루프.
> 엔진·절차는 이 스킬과 `references/`, 프로젝트별 rubric·probe·env 는 `<project>/.loop/` 에 산다.
>
> **이 스킬은 *디스패처*다.** 절차 본문은 `references/*.md` 에, 데이터(rubric/weights/evidence/env)는
> `<project>/.loop/loop.json` + `scorecard.md` 에, **장부와 판정**은 `scripts/loop.mjs` 에 있다 —
> 중복 정의 금지. 각 모드는 해당 reference 만 펼쳐 읽고 위임한다(통독 금지 — §2 컨텍스트 규율).

`<P>` = 플러그인 루트 절대 경로. 이 스킬이 로드될 때 표시되는 `Base directory for this skill` 의
**두 단계 위**다(`skills/loop` 의 부모의 부모). 아래 모든 명령의 `<P>` 를 그 경로로 치환하고,
프로젝트 루트(또는 그 worktree)에서 실행한다.

---

## 0. 정수 — 5 invariants (모든 모드가 지킨다)

루프가 의미를 가지려면 이 5개가 깨지면 안 된다. 어떤 모드든 출력 전에 이 5개로 자기점검한다.

1. **"잘됨"을 숫자로** — 성공을 계산 가능한 0~100 score 로. 막연한 "make it better"·"production-ready 인 것 같다" 금지.
2. **숫자를 올린다** — score → triage(최약 고리) → fix → verify → rescore 사이클로만 전진.
3. **숫자를 못 속인다 (anti-gaming)** — 모든 점수 상승은 **실환경 신호**(DB 불변식·200+실데이터·비-권한 403·벤치)에 결박. 테스트 *개수* 증가·정적 grep "0건"·"코드가 존재함"을 PASS 로 세지 않는다. (자세히 → [references/scoring.md](references/scoring.md))
4. **결정론적 종료** — STOP / ESCALATE / CONTINUE 는 **`loop.mjs record` 가 계산한다.** 스킬이 직접 세지 않는다. (자세히 → [references/stop.md](references/stop.md))
5. **사람이 루프 안에 (stay the engineer)** — 브랜치만, **auto-merge 금지**, 게이트. fix·probe 는 **local 범위만**(prod/remote/자격증명/force push 금지). (자세히 → [references/safety.md](references/safety.md))

> **판정은 스크립트가 한다.** 이 스킬의 산문은 STOP·ESCALATE 규칙을 *설명*할 뿐이고,
> 실제 판정은 `node "<P>/scripts/loop.mjs" record …` 의 출력(`verdict`)을 따른다.
> 모델이 "연속 2회 달성했으니 STOP" 이라고 손으로 세면 상한·브레이커·no-progress 축과 어긋난다.

---

## ⛔ Guard — 스킬 시작 즉시 (가장 먼저 실행)

```bash
node "<P>/scripts/loop.mjs" check --json
```

| 결과 | 뜻 | 다음 |
|------|----|------|
| exit 2 · `.loop/loop.json 이 없다` | 셋업 전 | → **무조건 init 모드** (다른 의도여도 먼저 셋업해야 측정 가능) |
| exit 2 · `errors[]` | 설정 무효(Σweight≠1 · caps 없음 · auto_merge≠false) | → 그 항목만 고치고 재-check. 고치기 전 다른 모드 진입 금지 |
| exit 0 | 정상 | → 사용자 발화로 의도 분류 → score / run / status |

`.loop/` 가 없는데 "재채점/루프 돌려"를 요청받았다면 측정할 rubric 자체가 없는 것이다 →
"아직 루프가 셋업되지 않았습니다. `loop init` 을 먼저 돌려 `.loop/` 를 만들까요?" 로 안내하고 init 으로 진입.

---

## 1. 모드 분기표 (의도 추론 — 플래그 explosion 없음)

| 모드 | 트리거(자연어) | 무엇을 하나 | 위임 reference | 정지 |
|------|---------------|------------|----------------|------|
| **init** | `.loop/` 없음 · "루프 셋업/시작/init" | 코드베이스 스캔 → 풀 인터뷰 → `loop.mjs init` + `.loop/`(scorecard.md·driver.js) 생성 | [references/init-flow.md](references/init-flow.md) | 생성 후 baseline score 제안 |
| **score** | "재채점/완성도 몇 점/re-score/full re-audit" | rubric+probe 로 측정 → `loop.mjs record` 로 기록·판정 | [references/scoring.md](references/scoring.md) | record 의 verdict |
| **run [N]** | "루프 N라운드 돌려/N바퀴/loop engineering N" | **N=1**: attended 1바퀴+게이트 / **N≥2**: 무인 드라이버 2방식 중 하나 | [references/cycle.md](references/cycle.md)(+[stop.md](references/stop.md)) | verdict / caps / 브레이커 |
| **status** | "루프 현황/다음 뭐/지금 몇 점" | `loop.mjs status` 요약(측정 안 함) | — (스크립트만 호출) | 즉시 |

> **N 단일 다이얼**: "루프 10" = 10 라운드(직관 일치). N 만으로 attended↔무인 자동 전환 —
> **N=1 게이트**(첫 바퀴는 항상 보여주고 검증), **N≥2 무인 드라이버**(나머지는 맡긴다). 별도 플래그 없음.
> N 미지정 "루프 돌려"는 **N=1 로 해석**(보수적 — 한 바퀴 보여주고 사람이 이어가게).

각 모드는 **그 모드의 reference 만** 펼쳐 읽는다. 4개를 한꺼번에 읽지 않는다(컨텍스트 규율).

---

## 2. 컨텍스트 규율 — "메모리는 컨텍스트가 아니라 디스크에"

이 스킬은 메인 세션에서 돈다. 통독·전수 inline 채점·멀티라운드 인라인은 컨텍스트를 폭발시킨다.
어느 모드든 다음 4규율을 지킨다:

- **선택적 읽기**: `scorecard.md`(산문 rubric, 클 수 있음)·reference 를 통독하지 말 것. 필요한 절(per-round 면 해당 dimension 의 §정의 + `scorecard.md` 마지막 점수이력 행만 / full 이면 §헤더 점수 + weights 만)만 offset/Grep 으로 읽는다. evidence anchor 는 필요할 때 그 `file:line` 만.
- **heavy work 는 sub-agent 위임, compact 만 회수**: dimension probe(HTTP/DB/테스트 묶음)·maker(구현)·verifier(실 probe)·코드리뷰는 sub-agent 가 자기 컨텍스트에서 실행하고 **{대상, 점수/verdict, 핵심증거 3~5줄}만** 반환. full 모드 = dimension 별 sub-agent fan-out(병렬), 메인은 compact 결과만 합산. probe 출력 raw·파일 전체내용을 메인이 들고 있지 말 것 = **컨텍스트 방화벽** + 진짜 maker≠verifier.
- **상태는 디스크에**: 결과는 컨텍스트가 아니라 `loop.mjs record` 가 쓰는 `.loop/scorecard.json` + `.loop/checkpoint.json` + `scorecard.md §점수이력` 으로 영속. 다음 라운드/세션(fresh 여도)은 `loop.mjs status` 만 읽고 재진입 — 컨텍스트 의존 0.
- **멀티라운드는 인라인 금지**: `run N≥2` 는 인라인 "계속"이 아니라 §4 의 두 무인 방식 중 하나. 스크립트/훅이 compact 상태만 들고 라운드를 sub-agent 로 반복하므로 메인 컨텍스트가 폭발하지 않는다.

---

## 3. `.loop/` 레이아웃 (init 이 생성, 다른 모드가 읽음)

```
<project>/.loop/
├── loop.json          # 기계 설정: dimensions·weights·evidence·probe·env·stop·caps·breaker·triage_order·safety
│                      #   (스키마 정본 = <P>/schemas/loop.schema.json · 검증 = loop.mjs check)
├── scorecard.md       # 산문 SSoT: 각 dimension FULL/PARTIAL/CONFLICT/MISSING 정의 + §점수이력(append-only)
├── scorecard.json     # 런타임 점수 (loop.mjs record 가 씀 — round·mode·active_total·domains·blocked)
├── checkpoint.json    # 런타임 상태 (loop.mjs record 가 씀 — rounds[]·verdict·no_progress·연속·브레이커 카운터)
├── session.local.json # Stop 훅 루프 활성 표식 (loop.mjs session start 가 씀 · gitignore)
└── driver.js          # (선택) Workflow 무인 드라이버 — templates/driver.js.tmpl 을 채운 것
```

**보편(이 스킬·references·templates·scripts) = 엔진·절차·장부. 프로젝트별(`.loop/`) = rubric·probe·env.**
`.loop/loop.json` 스키마는 `<P>/schemas/loop.schema.json` 이 정본이고 `loop.mjs check` 가 강제한다 —
**설정은 JSON 이다. YAML 형식은 이 프레임워크에 없다.**

---

## 4. 모드별 진입 (요지 + 위임)

> 각 항목은 *언제 무엇을 위임하나*만 적는다. 절차 본문은 reference 가 SSoT.

### init — 스캔 + 풀 인터뷰 → `.loop/` 생성
`.loop/` 가 없거나 사용자가 셋업을 원할 때. **여기가 "기획" 엔진** — 스캔이 초안을 제안하고 인터뷰가 확정한다.

```
A 스캔(read-only)  언어/프레임워크(package.json·build.gradle·go.mod·pyproject…)·테스트/기동/DB/인증·
                   도메인/모듈 경계(→ dimension 후보)·CI 스크립트(→ probe 후보) 자동 탐지
B 인터뷰(풀)        스캔 결과를 보여주고 사람이 확정/보정: ①목표 한 줄 ②dimensions+weights(Σ=1.0)
                   ③각 축 probe="코드 존재 아닌 실동작" 신호(+held_out 여부) ④env ⑤stop.target
                   ⑥★caps(상한) — max_rounds|max_cost_usd|max_minutes 중 최소 1개
C 생성             loop.mjs init 으로 골격 → 인터뷰 결과로 loop.json 편집 → loop.mjs check → scorecard.md(+driver.js)
D baseline         "지금 baseline 잴까요?" → score(full) 1회 → record --mode full 로 R0 기록
```

> ★ **caps 없이는 `loop init` 이 거부된다** — `loop.mjs init` 은 `--max-rounds` / `--max-cost-usd` /
> `--max-minutes` 중 하나도 없으면 exit 2 로 멈춘다("상한 없는 루프는 시작할 수 없다").
> 서킷브레이커(`breaker.no_change_rounds` 연속 파일 변경 0 · `same_error_rounds` 같은 에러 반복)도
> 같은 자리에서 확정한다 — 둘 다 열리면 verdict 는 ESCALATE 다.

From bigbulgogiburger/caseworker, MIT.

More from bigbulgogiburger/caseworker