@holmes-lab/holmes-kit 0.12.2 → 0.13.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "//": "@implements A-SPEC-209",
   "name": "@holmes-lab/holmes-kit",
-  "version": "0.12.2",
+  "version": "0.13.0",
   "description": "Holmes-Kit — deterministic Agentic Software Engineering (ASE) harness with causal traceability (spec chain + D-CPG + RTM + phase guardrail)",
   "main": "dist/holmes/mcp/server.js",
   "types": "dist/holmes/mcp/server.d.ts",
@@ -42,7 +42,7 @@
     "mcp",
     "guardrail"
   ],
-  "author": "SungNam Park <snpark.phd@gmail.com>",
+  "author": "SungNam Park <sungnam.park.korea@gmail.com>",
   "license": "MIT",
   "devDependencies": {
     "@types/better-sqlite3": "^7.6.13",

package/playbooks/publish/PLAYBOOK.md

@@ -2,72 +2,85 @@
 name: holmes-publish
 description: >-
   Use when asked to publish holmes-kit to NPM registry or run release workflow governed by
-  "HOLMES_APPROVAL", "hard-hitl", or "A-SPEC-133" with mandatory Human-In-The-Loop (HITL)
-  authorization by 박성남 그룹장님.
+  "HOLMES_APPROVAL", "hard-hitl", or "A-SPEC-133" — the repository owner authorizes an
+  irreversible / high-risk release Human-In-The-Loop, while a low-risk release may self-publish
+  under autonomous mode.
 ---
 
-# holmes-publish — NPM 서버 배포 및 HITL 승인 절차
+# holmes-publish — NPM 배포 및 릴리스 자율/HITL 절차
 
-이 플레이북은 `@holmes-lab/holmes-kit` 패키지를 NPM Registry에 안전하게 배포하기 위한 **5단계 규정 절차**를 정의합니다.
-배포 직전에는 반드시 **박성남 그룹장님**의 명시적 대역외 승인(HITL — Human-In-The-Loop)을 거쳐야만 실제 배포 명령어가 실행됩니다.
+이 플레이북은 `@holmes-lab/holmes-kit` 를 NPM Registry에 안전하게 배포하는 **규정 절차**를 정의합니다.
+npm publish 는 **비가역·외부노출**이라 기본은 HITL(사람 승인)이지만, **저위험 릴리스**(문서·테스트·양성
+내부 변경의 patch/minor)는 **자율 모드에서 자율 처리**할 수 있고, **비가역/high-risk**(게이트·보안·아키텍처
+변경, major 범프, 상위 스펙)는 반드시 **오너의 대역외 HITL 승인**을 거칩니다. 판정은 결정론적 분류기
+`releaseAutonomy`(A-SPEC-555.1, `governance/autonomy.ts`)가 담당합니다.
 
 ---
 
-## 배포 5단계 절차 (5-Step Release Workflow)
+## 배포 절차 (Release Workflow)
 
 ### 1단계: 사전 품질 감사 (Pre-flight Quality Audit)
-배포를 시작하기 전 코드베이스의 무결성과 타입 안전성을 검증합니다:
-1. `npm run typecheck` 실행 (타입 오류 0건 검증)
-2. `npm test` 실행 (전체 145+ 테스트 수트 100% PASS 검증)
-3. `npm run build` 실행 (`dist/` 최신 빌드 및 `.build-id` 생성)
+1. `npm run typecheck` (타입 오류 0건)
+2. 전체 스위트 green — `mcp__holmes-kit__test_run`(HEAD~1..HEAD) 또는 `npx jest`. 부하가 높으면 대시보드
+   canary(A-SPEC-435)가 타임아웃할 수 있으니 부하를 낮춘 뒤 재실행한다(코드가 아니라 부하 문제).
+3. `npm run build` (`dist/` 최신 + `.build-id`).
 
 > [!IMPORTANT]
-> 단 하나의 테스트라도 실패하거나 타입 오류가 발생하면 즉시 배포 절차를 중단(Abort)합니다.
+> 타입 오류나 실제(부하-무관) 테스트 실패가 하나라도 있으면 즉시 배포 중단(Abort).
 
 ---
 
 ### 2단계: 패키지 타르볼 시뮬레이션 및 검수 (Tarball Inspection)
-NPM에 게시될 패키지 구성 요소를 사전 시뮬레이션하여 검수합니다:
-- `npm publish --dry-run` 실행
-- 출력된 타르볼 패키지 목록 검수:
-  - `package.json` (`@holmes-lab/holmes-kit` 명칭 및 버전 확인)
-  - `bin/` (`holmes-kit.js`, `holmes-mcp.js`, `holmes-hook-antigravity.js` 등)
-  - `dist/` (전체 컴파일 산출물)
-  - `playbooks/` (`adopt`, `author-slice`, `promote-slice`, `publish`)
-  - `CHANGELOG.md`, `README.md`
+- `npm publish --dry-run`
+- 타르볼 구성 검수: `package.json`(명칭·버전), `bin/`, `dist/`, `playbooks/`, `CHANGELOG.md`, `README.md`.
 
 ---
 
-### 3단계: 필수 사람 승인 (Mandatory HITL Approval) — 보안 게이트
-**가장 중요한 보안 지점입니다.** AI Agent는 독단적으로 `npm publish`를 실행할 수 없으며, 반드시 **박성남 그룹장님**께 배포 요약을 보고하고 명시적 승인을 받아야 합니다.
+### 2.5단계: 문서 정합성 게이트 (Docs Currency Gate) — 배포는 정직한 고지다
+타르볼에 문서가 **포함**됐는지가 아니라 **최신인지**를 diff로 검사한다(이 단계 없이 폐기된 동작이 README에
+현재형으로 남는 사고가 실제로 있었다):
+1. 직전 릴리스 태그 이후 승인된 스펙 열거: `git log <last-tag>..HEAD --name-only -- .ax/specs/03_a-spec/`.
+2. 각 A-SPEC 중 **사용자-대면**(CLI 명령/플래그, 동작 변경, env 스위치, 게이트 행동)인 것마다:
+   - `CHANGELOG.md` 의 이번 버전 항목이 그 변화를 기술하는가.
+   - `README.md` 의 기능 목록/CLI 치트시트가 새 명령·플래그를 담고, **폐기된 동작을 현재형으로 서술하지
+     않는가**(바뀐 동작의 옛 문구를 `grep` 으로 점검).
+> [!CAUTION]
+> 사용자-대면 변화가 CHANGELOG/README 에 반영되지 않았으면 배포 중단 — 문서 drift 는 거짓 주장이다.
+
+---
+
+### 3단계: 릴리스 자율 판정 (Release Autonomy) — auto 또는 HITL
+`releaseAutonomy(specsSinceTag, versionBump, process.env, root, now)` 로 이번 릴리스를 분류한다
+(`versionBumpKind(현재버전, 대상버전)` 으로 범프 종류 산출):
+- **`'auto'`** (자율 ON + 모든 스펙 auto 등급 + patch/minor): 사람 없이 4단계로 진행하되, 원장에 배포
+  근거를 남긴다(무엇을·왜·어느 버전). 저위험 릴리스의 자율 처리.
+- **`'hitl'`** (자율 OFF · major 범프 · 게이트/보안/아키텍처 스펙 · 상위 REQ/H/C · 비가역 breaking_change):
+  **오너에게 배포 요약을 보고하고 명시적 대역외 승인**을 받은 뒤에만 진행한다. AI Agent 는 독단적으로
+  `npm publish` 하지 않는다. 승인은 채팅의 명시적 확인 또는 `HOLMES_APPROVAL` 로 전달된다.
 
-**[보고 양식]**:
-- **배포 패키지**: `@holmes-lab/holmes-kit`
-- **대상 버전**: `vX.Y.Z`
-- **테스트 결과**: PASS (100%)
-- **타르볼 파일 수 및 용량**: N개 / XXX kB
+**[HITL 보고 양식]**: 패키지 `@holmes-lab/holmes-kit` · 대상 `vX.Y.Z`(범프: major/minor/patch) ·
+테스트 PASS · 타르볼 N개/XXX kB · 분류 사유(어느 스펙이 hitl 인지).
 
 > [!CAUTION]
-> **박성남 그룹장님**께서 승인을 내리지 않거나 거부 의사를 밝힌 경우, 즉시 배포 동작을 중단합니다.
-> 승인은 채팅을 통한 명시적 확인 또는 `HOLMES_APPROVAL` 환경변수를 통해 전달됩니다.
+> hitl 판정에서 오너 승인이 없으면 즉시 중단. 자율(auto) 판정이라도 2.5단계 문서 게이트를 통과해야 한다.
 
 ---
 
 ### 4단계: NPM 게시 실행 (NPM Publishing Execution)
-승인이 완료된 경우에만 실제 게시 명령을 수행합니다:
 ```bash
 npm publish --access public
 ```
-- 2FA / Web OTP 인증이 필요한 경우 터미널 인증 URL을 사용자에게 제공하고 대기합니다.
+- 2FA / Web OTP 가 필요하면 인증 URL 을 사용자에게 제공하고 대기.
+- verify-release 가 전체 `npm test` 를 돌려 플레이크할 수 있으므로, 1단계를 이미 green 으로 통과했다면
+  `npm publish --ignore-scripts` + 수동 무결성 확인(트리 클린·build-id==HEAD·CHANGELOG 항목)로 우회할 수 있다.
 
 ---
 
 ### 5단계: 배포 후 검증 및 Git 태깅 (Post-Release Verification)
-게시가 완료된 후 등록 상태를 최종 검증합니다:
-1. `npm view @holmes-lab/holmes-kit version` 실행하여 NPM Registry에 반영되었는지 확인
-2. Git 커밋 및 태그 생성:
+1. NPM 반영 확인: `npm view @holmes-lab/holmes-kit version` (레지스트리 read-cache 지연 시 레지스트리 JSON 직접 조회).
+2. 커밋 및 태그:
    ```bash
-   git add package.json
+   git add package.json CHANGELOG.md README.md
    git commit -m "chore: release vX.Y.Z"
    git tag -a vX.Y.Z -m "vX.Y.Z Release"
    ```
@@ -75,7 +88,6 @@ npm publish --access public
 ---
 
 ## 플레이북 트리거 조건
-다음 요청 시 자동 트리거됩니다:
 - "npm publish"
 - "release to npm"
 - "HOLMES_APPROVAL"

package/playbooks/remediation/PLAYBOOK.md

@@ -1,7 +1,7 @@
 ---
 name: holmes-remediation
 description: >-
-  Automatically triggered when Holmes-Kit pre-tool-use hook gate denies a tool call with "구현 대상 A-SPEC(...)이 approved가 아닙니다" or missing code anchor. Guides the agent to execute 1-call spec_remediate or 3-step recovery workflow.
+  Automatically triggered when Holmes-Kit pre-tool-use hook gate denies a tool call with "Target specification (...) is not approved" or missing code anchor. Guides the agent to execute 1-call spec_remediate or 3-step recovery workflow.
 ---
 
 # Holmes-Kit Remediation Playbook (Self-Healing Recovery)