Run Milestone

---
name: run-milestone
description: Run a sealed milestone's remaining tasks in one main session, sidelining blocked tasks and batching decisions.
argument-hint: "<milestone-id> [--handoff]"
disable-model-invocation: true
allowed-tools: Read Glob Grep Write Edit Bash Skill Agent
---

너는 마일스톤 연속 실행의 **운전자**다. 절차는 하위 skill 4종(`/implement-`·`/validate-`·`/repair-`·`/finalize-workitem`)이 소유한다. 너는 다음 단계를 파일로 판정·실행·확인하고, 진행 불가 task는 빼두고 끝에 모아 보고한다. **커밋하지 않는다**(task 커밋은 finalize 단독). auto 권한 모드 전제. 정책: [ADR-076](../../../docs/90-decisions/boilerplate/ADR-076-run-milestone-orchestration.md).

## 핵심 루프 (컴팩션 뒤에도 이 절부터)
1. §2로 다음 단계를 판정한다(매 task 전, 기억 대신 파일로).
2. §3대로 하위 절차를 실행하고 산출물로 확인한다.
3. 진행 불가면 §4로 그 task만 빼고 1로.
4. 더 돌릴 task가 없거나 §4-4 종료·전체 멈춤이면 §6.
- **하위 skill 호출**: 처음 쓸 때와 컴팩션 뒤 처음 쓸 때만 Skill 도구로 부르고, 그 사이에는 컨텍스트의 본문을 따른다(절차 생략 금지). 단계 시작 때 `▶ /<skill> T-NNN <인자>`를 출력하고, 재사용 본문의 치환된 인자 대신 이 줄의 값을 쓴다.
- **컴팩션 직후**(대화가 요약으로 시작): 이 파일·인계 파일 2개·`## 운영 함정` 재독 → §1-3 → §2 재판정 → 진행 중이던 하위 절차를 재진입 지점부터.
- 실행 중 해결 알림은 현재 하위 절차 뒤 §4-5로.

## 0. 입력·승인 범위
- `$ARGUMENTS`: `M[0-9]+` 정확히 1개 + 선택 `--handoff`. 그 밖이면 안내 후 종료.
- 이 호출 = 이 M의 task 사이클 연속 진행 + finalize 로컬 커밋 승인. push·배포·제품 결정·새 실행 권한은 불포함 — 따로 받은 권한(대화·인계 `## 1`)만 그 범위에서 쓰고, 거부된 명령은 우회·재시도하지 않는다.
- 특정 task를 지목한 실행 증거 면제 사유는 그 task implement에만 문구 그대로 `--waiver "<문구>"`.
- `--handoff`·대화로 인계·중단 요청: 진행 중 하위 절차가 끝난 지점에서(없으면 §1 없이 바로) §5 인계를 쓰고 종료.
- «상태» = `git -c core.quotePath=false status --porcelain -uall`.

## 1. 시작 (1회)
1. `docs/30-workitems/handoffs/M<N>.md`·`_common.md`, `docs/00-meta/STACK_SETUP_PLAN.md`의 `## 운영 함정`을 읽는다. `## 1`은 복구·질문보다 먼저 첫 출력에 `이어받는 지시·권한 N건: …`으로 인용 그대로.
2. milestone `## 10` `- 봉인일:`이 비면 `/seal-milestone M<N>` 안내 후 종료.
3. **마감 중단 복구**: 트리의 task 문서만 `done`이면(HEAD는 아님) — staged이고 staged diff에 마지막 `- closure`가 있으면(`Needs Commit` 잔존) 그대로 finalize(§3-5 표), 아니면 status를 `in-progress`로, HEAD에 없는 마지막 `- closure` 줄은 지운다(`- ac-pending`은 둔다).
4. **막힌 목록** = `git stash list --format='%gd %H %s'`에서 이름이 `run-milestone M<N> T-NNN:`인 항목(`## 4`에 `적용 완료 <hash>`면 제외) + 인계 `## 4`의 `- T-NNN —` 줄. 트리 status가 `done`인 task는 제외. stash 목록에 없는 hash의 `적용 완료` 줄과 `done` task의 `- T-NNN —` 줄은 지운다.
5. 산하 task(`## 7` Milestone 링크가 이 M)가 전부 `done`이고 막힌 목록이 비었으면 `/stabilize-milestone M<N>` 안내 후 종료.
6. «상태»의 변경이 진행 중 task 것이 아니면 사용자 변경 — 건드리지 않고 멈춰 보고.
7. **시작 점검**: 트리가 깨끗하고 통합 명령이 있으면 1회 실행 — 실패(기준선 깨짐)나 «상태» 변경(통합 명령 부작용)이면 **전체 멈춤** + 안내(부작용 경로는 `.gitignore` 또는 명령이 원복).
8. **시작 질문**(해당할 때만, 첫 task 전 한 메시지): 막힌 목록·필요한 행동 → 해결된 task / `## 1`의 push·배포·외부 write·운영 환경 접근 권한 → 한 줄씩 재확인 / 남은 task에 `## 2` `(a) 영속 저장소 쓰기`가 있고 `## 로컬 환경 동기화`의 DB 초기화가 `허용`이 아님 → 이번 실행 동안 필요할 때마다 자동 초기화 허용(명령을 보이고 답에 명령 포함 — 행이 없으면 명령도. 인계 안 함). 고른 task는 §4-5로 되살린다. 재확인 못 받은 권한은 쓰지 않고 인계에서 빼고, 나머지는 승계.

## 2. 다음 task·단계 판정 (HTML 주석 밖 줄만)
- 후보: `## 9`의 `T-<번호>:AC-<번호>` 토큰 전부가 선행이다(`:AC-` 없는 ID는 의존 아님). 선행이 모두 `done`이고 막힌 목록에 없는 task를 번호순으로 — 단 트리에 변경이 남은 `in-progress` task(막힌 목록 밖)가 있으면 그것부터. **막힌 목록의 task는 `ready`로 보여도 미완**이며 직·간접 후행도 후보가 아니다. 트리에 막힌 task의 변경이 남아 있으면(재개방 done task) 후보를 고르지 않고 **전체 멈춤**. `blocked`·`deprecated` task는 건너뛰고 §6에.

| 상태 | 다음 |
|---|---|
| `ready` | `/implement-workitem T-NNN --run-milestone` |
| `in-progress` + 구현 완료 미충족 | 같은 implement (재개 — task당 이번 실행 2회, 넘으면 §4) |
| `in-progress` + 구현 완료 + report 신선하지 않음 | `/validate-workitem T-NNN` |
| report 신선 | §3-3 |

- **구현 완료** = ① 기계 AC(`## 6-1`의 `[자동 테스트]`·`[산출물 검사]`·표기 없음)가 있으면 `## 4-1`이 비어 있지 않고 그 AC마다 `## 8` `- verify-power`, 없으면 관측 AC마다 `- ac-pending` ② `## 2` `- 외부 경계:` 종류마다 `- exec-evidence`(마지막 줄이 `미확보`가 아님) ③ `## 3`에 `[미실측]` 없음 ④ 정지 신호(3-1)가 없거나 해소됨 — 다음 implement·repair가 신호 없이 끝나거나 사용자가 해결을 알림(뒤 단계 Pass는 해소 아님).
- **신선** = 이 컨텍스트에서 그 task의 validate가 쓴 report이고 그 뒤 편집이 없다(새 세션·컴팩션 직후 report는 아님).

## 3. 한 task 사이클
결과는 하위 skill의 말 대신 산출물(report `- 판정:`·task 문서·git)로. implement 직전 이 task의 이월(인계 `## 3`·세션 메모)·관련 함정·사용자의 해석 답(말 그대로)을 대화에 적는다.

**3-1 정지 신호 (implement·repair 출력만)** — `Needs SSOT Amendment`·`Fact Resolution`·`Execution Evidence`·`Install`·`MCP Access`·`Dependency Tool Decision`·미해소 `Research`·잠정 금지 범주의 해석 보고·repair `Needs Follow-up`, 또는 사용자만 할 수 있는 행동(자격증명·원격 실행·권한 거부)이 필요하면 §4. implement 3-R (1)(선행 done task 산출 누락)이면 트리를 비운 뒤(§4-1) 선행 task를 §5 done task 수리로 고치고 재시도. `Needs Stack Guard`·마일스톤 게이트 거부(같은 M `draft` task·미해결 plan-review)는 **전체 멈춤**. 아래 표에 없는 결과도 §4.

**3-2 validate 직전 대조 (매번)** — «상태» 중 `## 4-1`에 없는 경로(finalize 자동 add·제외 대상 빼고)가 있으면 §4(되돌리지 않음). 이 «상태»를 기억한다.

**3-3 validate 뒤** — «상태»에 3-2 때 없던 경로가 생기면 §1-7의 부작용: **전체 멈춤** + 안내.

| report | 행동 |
|---|---|
| `Needs Fix` + `P0 [Spec-gap]`·상위 결정 필요 | §4 |
| `Needs Fix`, 실패가 전부 `감사 미완` | validate 1회 재실행, 또 그러면 §4 |
| 그 외 `Needs Fix` | `/repair-workitem T-NNN` → validate |
| `Pass`·`Pending Acceptance` + 이번 라운드 코드가 만든 계약 P1 | `/repair-workitem T-NNN "<요약>"` (task당 1라운드) → validate |
| 그 외 `Pass`·`Pending Acceptance` | 3-5 |

- 계약 P1 = 라벨 `[Arch-iface-*]`·`[Design-*]`·`[Seam]`이거나 승인 프로토타입 `PX-`·닫힌 결정 `D-NNN`을 인용하는 P1. 위치 파일이 `## 4-1`에 있으면 이번 라운드 것. P2 제외(일반 repair는 전 severity). `Reject-*`로 기각되면 다시 부르지 않는다. 다른 task 소유면 §5.

**3-4 루프 상한** — 일반 repair 3라운드. 먼저 끊는다: (a) repair가 기각한 P0가 같은 라벨·같은 파일(AC 지적은 같은 AC — repair 줄 위치 칸, 줄 번호 무시)로 재등장(§6 교차 검증 권장) (b) 한 라운드 뒤 같은 테스트가 같은 이유로 실패. 둘 다 §4.

**3-5 finalize** — validate 뒤에는 task 문서·작업 트리를 고치지 않는다(고칠 것이 생기면 고친 뒤 validate부터). `/finalize-workitem T-NNN`:

| 관측 | 행동 |
|---|---|
| HEAD 커밋에 T-NNN 문서(status=`done`·마지막 `- closure`=T-NNN) + `## 4-1` 파일 잔존 없음 | 성공 |
| `Needs Commit` | finalize 1회 재실행(1-G가 커밋만 재시도), 또 그러면 **전체 멈춤** + 원인 |
| `Needs Fix` | repair → validate → finalize (3-4 상한) |
| `Needs Review`·`Needs Validation` | 이 task 변경의 `## 4-1` 누락이면 추가 후 validate부터 1회 재시도, 그 밖이거나 또 그러면 §4 |
| 다른 task가 커밋·변경됨 | **전체 멈춤**·보고(되돌리지 않음) |

## 4. 빼두기 (전체를 멈추지 않는다)
1. 트리에 그 task 변경이 있으면(task 문서 상태 줄뿐이어도) `git stash push -u -m "run-milestone M<N> T-NNN: <사유 1줄>"`. task status는 쓰지 않는다. **done·재개방 task면 stash하지 않고 전체 멈춤.**
2. 곧바로 인계 `## 4`에 `- T-NNN — <사유> / 필요한 것: <행동·결정> / stash: <hash>|없음`(없으면 §5 양식으로). 필요한 것을 한 줄로 요청하고 **기다리지 않고** 계속한다.
3. **환경 동기화**(stash를 만들거나 되살렸을 때) — 그 변경에 의존성 목록·lockfile이 있으면 `STACK_SETUP_PLAN.md` `## 로컬 환경 동기화`의 의존성 명령(없으면 `## Dependency Tools`의 lockfile 고정 설치), DB 마이그레이션·스키마가 있거나 그 task `## 2`에 `(a) 영속 저장소 쓰기`가 있으면 DB 명령(`(예:` 행 무시). 명령이 거부·실패하거나, DB 명령이 없거나 `확인 필요`인데 §1-8 허용이 없으면 **전체 멈춤**.
4. 같은 원인(같은 `Needs *` 대상·실패 명령)으로 **연속 2건**이면 그 원인에 걸릴 남은 task를 문서로 가린다(같은 `- 외부 경계:` 종류·대상, `## 3`의 같은 설치·MCP 항목). 가려지면 시도 없이 2의 줄(`같은 원인: T-NNN`, stash 없음)로 빼두고 계속, 가릴 수 없으면 §6.
5. **재개**: 트리가 깨끗할 때 그 hash의 `stash@{k}`를 `git stash pop`(한 번에 하나, finalize 뒤 다음). 충돌 없으면 `## 4` 줄 삭제 → 3 → §2. 충돌이면 확신이 있을 때만 풀고 `git reset -q` → `## 4` 줄을 `- 적용 완료 <hash> (T-NNN)`로 → 3 → implement 재개(**stash 항목은 지우지 않는다**). 확신이 없거나 부분 실패면 그 상태로 **전체 멈춤**(충돌 파일·hash·되돌리는 법 안내). stash 없는 task는 `## 4` 줄 삭제 → §2.
6. done task(task 층) 수리는 현재 task를 finalize하거나 빼둬 트리를 비운 직후, 다음 후보보다 먼저.
- **즉시 전체 멈춤**: 굵게 적은 «전체 멈춤» 전부 + 되돌릴 수 없는 외부 운영 환경 작업 + stash 명령(push·pop) 거부·실패. 멈춘 task는 `## 4` 줄을 남긴다(있으면 유지, 없으면 2의 줄을 실제 stash hash나 `없음`으로).

## 5. 이월·함정·인계
- **이월**: 같은 M 뒤 task 소유 → 그 task implement 때 대화로(세션을 넘기면 인계 `## 3`). done task(task 층) 소유 P0/P1 → §4-6 뒤 `/repair-workitem T-OLD "<요약>"` → validate(전부 기각 시 생략) → finalize. 그 밖(P2·마일스톤 층·cross-cutting·다음 M)은 report에(stabilize 회수).
- 운전자가 쓰는 커밋 대상은 현재 task `## 4-1`(3-5 `Needs Review` 해소)과 §1-3 복구뿐(§6 승격 제외). 반복 함정은 `_common.md`에 `- <규칙 1줄> — 근거: <T-NNN 사건>` 추가.
- **인계**(멈출 때만): §1-1의 인계 파일을 읽고 해소 안 된 `## 4` 줄은 유지한 채 새로 쓴다. `## 1`은 사용자 말 그대로 + 날짜·적용 범위(task·명령). 파일로 알 수 있는 것은 쓰지 않는다. 양식: `# M<N> 인계` / `- 기록: <YYYY-MM-DD> / HEAD <sha>` / `## 1. 사용자 지시·권한` / `## 2. 외부 상태 (확인 시점)` / `## 3. 이월` / `## 4. 막힌 task`.

## 6. 종료 — 배치 보고
한 메시지로 보고하고 §5 인계를 쓴다.
- 막힌 task와 필요한 행동 → 해결 후 재실행
- 잠정 해석 목록(M 전체의 `해석 확정:` 없는 `해석 잠정:` AC) — **묻지 않는다**(stabilize·repair-milestone이 확인)
- 교차 검증 권장(보안·인증·권한·데이터 무결성 경계를 건드렸고 oracle gap 보안 항목이 `not covered`/`partial`인 task·3-4 (a) task) → stabilize 뒤 `/validate-milestone --reviewer-tag`
- 정리할 stash: `## 4`의 `적용 완료` hash — 사용자가 지운다
- (전 task done·막힌 목록 빔일 때만) `_common.md`의 오래갈 함정을 `STACK_SETUP_PLAN.md ## 운영 함정`으로 승격 제안 — 승인분만 옮기고 `_common.md`에서 지운다. 커밋은 사용자. 인계 잔여 항목은 목적지 제안·확인 후 삭제. 다음 `/stabilize-milestone M<N>`.