@holmes-lab/holmes-kit 0.1.0

package/playbooks/promote-slice/PLAYBOOK.md

@@ -0,0 +1,134 @@
+---
+name: holmes-promote-slice
+description: >-
+  Use when a Holmes-Kit gate denies with "approved H-SPEC이 없습니다", "approved A-SPEC이 없습니다",
+  "구현 대상 A-SPEC(...)이 approved가 아닙니다", or "…를 depends_on에 담은 T-SPEC이 없습니다(테스트 먼저)" —
+  the spec already exists but its status still blocks the next action, or an approved T-SPEC leaves
+  the code gate shut.
+---
+
+# promote-slice
+
+승인은 **내용을 봉인하는 행위**다. `spec_approve`가 그 행위를 수행한다 — 검증 → 본문 다이제스트
+계산 → `status: approved` + `approved_digest` + 부모 봉인 스냅샷 기록 → 원장 append를 한 번에.
+손으로 `status:`만 바꾸는 것으로는 부족하다: 봉인 없이 approved가 된 스펙은 `unsealed-approval`로
+검증에 걸리고, 봉인 후 본문을 고치면 `post-approval-edit`으로, 부모가 움직이면 `stale-parent`로
+걸린다(REQ-132). `spec_approve`는 **서버 환경의** 유효한 `HOLMES_APPROVAL`을 요구한다(fail-closed) —
+요청 인자로는 대체되지 않는다.
+
+이 플레이북은 그 승인을 **언제·무엇에·어떤 근거로** 하는지를 다룬다. 문서를 새로 쓰는 일이라면
+이것이 아니라 `author-slice`다 — 판별은 3단계에 있다.
+
+## 게이트가 실제로 요구하는 것
+
+`phaseCheck`의 조건은 동작마다 다르고, 그 차이가 이 플레이북의 전부다.
+
+| 하려는 동작 | 요구 조건 | 비직관적인 점 |
+|---|---|---|
+| H-SPEC 작성 | REQ가 **존재**만 하면 됨 | `draft` REQ로 충분하다. 승인이 불필요한 유일한 칸 |
+| A-SPEC 작성 | approved H-SPEC **아무거나 하나** | 지금 쓰는 A-SPEC의 부모일 필요가 없다 |
+| C-SPEC / T-SPEC 작성 | approved A-SPEC **아무거나 하나** | 대상 A-SPEC이 draft여도 T-SPEC은 쓸 수 있다 |
+| 테스트 작성 | **대상** A-SPEC이 approved | 여기서 "아무거나"가 "바로 그것"으로 바뀐다 |
+| 코드 작성 | 대상 A-SPEC approved **＋** 그것을 `depends_on` 하는 approved T-SPEC | 유일한 2조건 게이트 |
+
+위 세 줄은 **파이프라인이 열렸는가**를 묻는다 — 아무 승인 하나가 그 칸을 연다. 아래 두 줄은
+**이 슬라이스가 준비됐는가**를 묻는다 — 대상으로 지정된 바로 그 문서여야 한다. 승인 하나로 여러
+칸이 동시에 열리는 것은 위쪽에서만 일어나는 일이다.
+
+## 절차
+
+1. **무엇이 막혔는지 deny에서 읽는다.** `phase` 필드는 지금 있는 곳이 아니라 **되돌아가야 할 곳**을
+   가리킨다(`WRITE_CODE` 거부 → `TEST-SPEC`). `missing`은 결핍의 *종류*까지만 말하고 그 이상은
+   말하지 않는다 — 두 개의 서로 다른 실패가 같은 `missing`을 낸다. 「T-SPEC 거부는 상태를 구별해 말한다」를 함께 읽는다.
+2. **대상을 특정한다.** `구현 대상 A-SPEC(미지정)` 이 나왔다면 스펙이 아니라 호출이 문제다 —
+   `targetAspecId`를 넘기지 않은 것이고, 승인할 것은 없다.
+3. **그 스펙이 존재하는가.** `spec_list`로 확인한다. 없으면 이것은 승격이 아니라 저작이다 →
+   `author-slice`. 있으면 계속한다.
+4. **검증을 확인한다 — 부르는 게 아니라 받는 것이다.** `spec_validate`는 기본 프로파일에서
+   **광고되지 않는다**. `phase_check` · `risk_check` · `rtm_check`와 함께 훅이 push로 강제하는
+   집합(`HOOK_ENFORCED_TOOLS`)이라 도구 목록에서 빠져 있고, 이름으로는 여전히 호출 가능하지만
+   스키마가 없어 실질적으로 부를 수 없다. 명시적 호출이 필요하면 `HOLMES_MCP_PROFILE=full`이다.
+   보통은 Stop 훅이 dangling parent와 결측 필드를 잡아 주므로, 확인할 것은 **직전 턴이 조용했는가**다.
+   깨진 채로 승인하면 게이트는 통과하고 그래프만 깨진 상태로 남는다.
+5. **승인 바(bar)를 대고 판단한다.** 아래 「승인의 기준」. 못 넘으면 먼저 문서를 보완한다 — 보완
+   후 6으로 돌아온다.
+6. **`spec_approve(id)`로 봉인-승인한다.** 이 도구가 검증·다이제스트·status 전이·원장 기록을
+   한 행위로 묶는다. **`root`는 생략해도 된다**(REQ-188) — 원장 위치는 서버가 바인딩된 스토어에서
+   파생되며, 명시하면 같은 프로젝트인지 확인되고 다르면 봉인 전에 거부된다. 과거에는 root를
+   빼면 봉인만 서고 원장 기록이 누락됐는데(REQ-182 체인 4건이 실제로 겪음), 이제 그 경로는
+   구조적으로 없다: 원장 목적지를 확정할 수 없으면 봉인도 서지 않는다. 승인 진행 중 문서가
+   바뀌면 편집이 이기고 승인이 거부된다 — 다시 읽고 다시 승인하면 된다. 부모부터 승인한다 —
+   봉인 안 된 approved 부모가 있으면 도구가 그 부모를 지목하며 거부한다. `status:`만 손으로
+   바꾸면 봉인이 없어 `unsealed-approval`로 되돌아온다.
+
+   승인이 거부하는 것(REQ-182 이후 게이트도 같은 사실을 미리 말한다):
+   - 부모가 draft이거나, 승인됐지만 봉인이 없다
+   - `breaking_change`가 없거나 등급이 허용값 밖이다(A-SPEC)
+   - **절이 생성기 자리표시자 그대로다** — `spec_create`의 맨 `TODO`이든 `reverse_draft`의
+     `TODO — …` + inferred 주석이든. 거부 문면이 어느 절인지 지목하므로 그 절만 채우면 된다.
+7. **같은 동작을 다시 시도한다.** 여전히 막히면 거부 문면을 그대로 읽는다 — 어느 상황인지 게이트가 말한다.
+
+## T-SPEC 거부는 상태를 구별해 말한다
+
+`WRITE_CODE`가 T-SPEC 때문에 막히면 문면이 **어느 상황인지** 알려준다. 두 갈래이고 조치가 다르다.
+
+| 문면이 이렇게 시작하면 | 상황 | 할 일 |
+|---|---|---|
+| `A-SPEC …를 depends_on에 담은 T-SPEC이 없습니다(테스트 먼저).` | 간선이 없다 — 아직 안 썼거나, 썼는데 안 걸었다 | 문면이 두 조치를 모두 말한다: 작성·승인하거나, 기존 T-SPEC의 `depends_on`에 추가 |
+| `T-SPEC …가 A-SPEC …를 시험한다고 선언했으나 approved가 아닙니다.` | 간선은 있고 승인이 없다 | 그 T-SPEC을 승인. 문면에 **왜 승인이 안 되는지**가 함께 온다 |
+
+게이트는 "아직 안 썼다"와 "썼는데 간선이 없다"를 **구별할 수 없다** — 그건 저자만 아는 사실이다.
+그래서 한 문면이 두 조치를 모두 제시한다. 다만 **A-SPEC 간선이 하나도 없는 T-SPEC**이 있으면
+그것만은 이름과 현재 `depends_on`으로 지목한다. 정상 저장소에 그런 문서는 없으므로(실측 73개 중 0),
+있다는 것은 방금 쓴 그 문서라는 뜻이다.
+
+```yaml
+# A-SPEC-129를 대상으로 코드를 쓰려면
+depends_on:
+  - A-SPEC-129        # 이 줄이 없으면 approved여도 게이트는 닫힌 채다
+```
+
+이전에는 세 상황이 글자 하나 다르지 않은 한 문장을 냈고, 이 절이 그 구별을 사람에게 대신
+설명했다. 이제 게이트가 말하므로 문서가 대신할 일이 없다(REQ-183).
+
+## 승인의 기준
+
+승인은 완벽함이 아니라 **다음 층이 이 문서를 근거로 삼을 수 있는가**다.
+
+- **REQ** — Problem / Desired Outcome / Constraints / Success Criteria / Out of Scope가 채워지고,
+  `source:`가 실재하는 것을 가리킨다. 대화에서 나온 지시는 `kind: conversation`으로, 문서가 없으면
+  없다고 적는다.
+- **H-SPEC** — 부모 REQ의 Success Criteria가 이 설계로 어떻게 달성되는지가 추적된다.
+- **A-SPEC** — Test Points가 검증 가능한 문장이고, Files to Touch가 실제 경로이며, Done When이
+  관측 가능하다. "잘 동작한다"는 Test Point가 아니다.
+- **T-SPEC** — 4분면(normal / negative / corner / boundary)이 모두 있고, `depends_on`이 대상
+  A-SPEC을 가리킨다.
+
+승인 후에 발견된 것은 **새 리비전**이지 승인 취소가 아니다. 되돌리는 비용이 승인을 미루게 만들면,
+게이트는 품질 장치가 아니라 지연 장치가 된다.
+
+## 흔한 오해
+
+| 오해 | 사실 |
+|---|---|
+| "`status:`만 손으로 바꾸면 된다" | 봉인이 없어 `unsealed-approval`로 걸린다. `spec_approve`가 봉인한다 |
+| "REQ를 승인해야 H-SPEC을 쓴다" | 아니다. REQ는 존재만 하면 된다 |
+| "A-SPEC을 승인했으니 코드를 쓸 수 있다" | 테스트는 그렇다. 코드는 T-SPEC이 남았다 |
+| "T-SPEC 승인했는데 막힌다 = 게이트 버그" | `depends_on` 누락. 메시지가 동일해서 구별되지 않는다 |
+| "일단 승인하고 검증은 나중에" | 통과한 채 깨진 그래프가 남는다. 4단계 참조 |
+| "`missing`이 'approved A-SPEC'이니 A-SPEC을 승인하면 된다" | `AUTHOR_TSPEC`이면 아무거나 하나, `WRITE_TEST`면 대상 그것. 같은 문자열이 두 가지를 뜻한다 |
+
+## 검증
+
+`src/holmes/playbooks/promote-slice.test.ts` — 20개 단언, 상시 스위트에 포함. 고정하는 것:
+
+- 위 조건표의 다섯 칸 전부를, **양방향으로**. 게이트를 여는 상태와 열지 못하는 상태를 함께 단언한다.
+- 이 문서가 인용한 모든 deny 문자열을 **완전 일치**로. 부분 일치는 문자열이 사라진 것을 숨긴다.
+- `depends_on` 누락과 T-SPEC 부재가 `message` · `missing` · `phase` 셋 다 같다는 사실을, 두 결과의
+  동일성으로. 주장이 "구별되지 않는다"이므로 고정하는 것도 구별되지 않음 자체다.
+- `spec_approve`가 표면에 존재하며 봉인을 설명한다는 것과 `spec_validate`가 광고 집합 밖이라는
+  것을, 전사(轉寫)가 아니라 `TOOL_SCHEMAS` · `HOOK_ENFORCED_TOOLS`를 직접 읽어서.
+
+**변이 검사로 판별력을 확인했다**(2026-08-05): `phase.ts`의 거부 문자열 하나를 바꾸자 3개 단언이
+red로 떨어졌고, 원복 후 파일은 HEAD와 바이트 동일했다. 현재 상태를 그대로 베끼기만 하는 공허한
+테스트가 아니라는 증명이다.