@holmes-lab/holmes-kit 0.12.1 → 0.13.0

package/dist/holmes/hooks/stop.js

@@ -318,27 +318,27 @@ function evaluateStop(specs, evidence) {
     // @implements A-SPEC-191 (§4a) — an existing-but-unreadable findings ledger is not a clean turn:
     // it may hold an open critical, and a "clean" verdict here would also CLEAR standing ART-7 debt.
     if (evidence?.findingsUnreadable) {
-        problems.push('[ART-7] findings 원장을 읽을 수 없습니다 — 열린 치명 발견의 존재를 확인할 수 없는 턴은 깨끗한 턴이 아닙니다 (원장 파일의 권한·형식을 복구하십시오)');
-        structured.push({ article: 'ART-7', detail: 'findings 원장을 읽을 수 없습니다' });
+        problems.push('[ART-7] the findings ledger cannot be read — a turn that cannot confirm whether an open critical exists is not a clean turn (repair the ledger file\'s permissions/format)');
+        structured.push({ article: 'ART-7', detail: 'the findings ledger cannot be read' });
     }
     // @implements A-SPEC-452 — ART-1's second enforcement point. `undefined` is no signal and says
     // nothing; an empty array is measured and clean. A file that claims nothing is a file the write
     // gate never judged, which is exactly what the two-step generator bypass produces.
     for (const file of evidence?.unanchoredChangedSources ?? []) {
-        const detail = `${file}: 변경된 소스에 @implements 앵커가 없습니다 — 이 파일이 무엇을 구현하는지 말하지 않습니다 (승인된 A-SPEC 을 만들고 앵커를 다십시오)`;
+        const detail = `${file}: the changed source has no @implements anchor — it does not say what it implements (create an approved A-SPEC and add the anchor)`;
         problems.push(`[ART-1] ${detail}`);
         structured.push({ article: 'ART-1', detail });
     }
     // @implements A-SPEC-453 — ART-5's second enforcement point. The seal is forgeable; the record
     // of the approving act is not.
     for (const id of evidence?.unrecordedApprovals ?? []) {
-        const detail = `${id}: 승인 상태인데 원장에 승인 행위 기록이 없습니다 — 봉인은 내용 해시라 스스로를 증명하지 못합니다 (spec_approve 로 승인하십시오)`;
+        const detail = `${id}: it is in the approved state but the ledger has no record of the approving act — a seal is a content hash and cannot prove itself (approve with spec_approve)`;
         problems.push(`[ART-5] ${detail}`);
         structured.push({ article: 'ART-5', detail });
     }
     // @implements A-SPEC-455
     for (const file of evidence?.rolledBackLedgers ?? []) {
-        const detail = `${file}: 커밋된 원장 이력이 되돌려졌습니다 — 작업본이 커밋본을 접두로 포함하지 않습니다 (원장은 덧붙이기만 합니다; holmes-kit ledger rechain 으로 확인하십시오)`;
+        const detail = `${file}: the committed ledger history was rolled back — the working copy does not contain the committed copy as a prefix (the ledger is append-only; check with holmes-kit ledger rechain)`;
         problems.push(`[ART-2] ${detail}`);
         structured.push({ article: 'ART-2', detail });
     }
@@ -440,18 +440,18 @@ function acknowledgeStop(violations, pending) {
  */
 function describeTokenHealth(raw) {
     if (raw === undefined || raw === '')
-        return 'HOLMES_APPROVAL 토큰 없음 (읽기 전용 — 승인이 필요한 행위만 막힙니다)';
+        return 'no HOLMES_APPROVAL token (read-only — only actions that need approval are blocked)';
     let parsed;
     try {
         parsed = JSON.parse(raw);
     }
     catch {
-        return 'HOLMES_APPROVAL 무효: JSON 파싱 실패 — 승인이 필요한 행위가 막힙니다';
+        return 'HOLMES_APPROVAL invalid: JSON parse failed — actions that need approval are blocked';
     }
     if (!(0, risk_gate_1.isValidApproval)(parsed)) {
-        return 'HOLMES_APPROVAL 무효: 필수 필드(actor·token·rationale) 누락 — 승인이 필요한 행위가 막힙니다';
+        return 'HOLMES_APPROVAL invalid: missing required field(s) (actor/token/rationale) — actions that need approval are blocked';
     }
-    return 'HOLMES_APPROVAL 유효';
+    return 'HOLMES_APPROVAL valid';
 }
 function decideStopGuard(wantsBlock, priorConsecutiveBlocks, cap = exports.MAX_CONSECUTIVE_BLOCKS) {
     if (!wantsBlock)
@@ -523,7 +523,7 @@ function findProjectRoot(specsDir) {
             if (r.marker !== 'given')
                 return r.root;
         }
-        catch { /* 표지가 없으면 짓지 않는다 */ }
+        catch { /* if there is no marker, build nothing */ }
         return null;
     }
     return null;
@@ -814,7 +814,7 @@ if (require.main === module) {
             else if (ackWaiting.length > 0) {
                 // @implements A-SPEC-247 — acknowledged, not clean: name what is waiting so the user sees
                 // the standing approval debt exactly once, and the agent knows the ball is not in its court.
-                process.stderr.write(`[Holmes-Kit] 승인 대기 중 — 오너 결정을 기다리는 항목: ${ackWaiting.join(', ')}. ${(0, npx_bin_1.npxBin)()} holmes-kit approve 에서 결재하십시오. (이 부채로는 재차단하지 않습니다)\n`);
+                process.stderr.write(`[Holmes-Kit] awaiting approval — items waiting on the owner's decision: ${ackWaiting.join(', ')}. Decide them at ${(0, npx_bin_1.npxBin)()} holmes-kit approve. (This debt does not re-block.)\n`);
             }
             else if (guard.capped) {
                 process.stderr.write(`[Holmes-Kit] governance gate YIELDING after ${exports.MAX_CONSECUTIVE_BLOCKS} consecutive blocks — issues remain UNRESOLVED:\n${out.reason ?? ''}\n`);
@@ -826,7 +826,7 @@ if (require.main === module) {
         }
         catch (err) {
             process.stderr.write(`[Holmes-Kit Stop Hook] Error: ${err instanceof Error ? err.message : String(err)}\n`);
-            process.exitCode = 0; // fail-open — exitCode 로 파이프를 비운 뒤 자연 종료(잘림 방지)
+            process.exitCode = 0; // fail-open — drain the pipe via exitCode, then exit naturally (avoids truncation)
         }
     });
 }

package/dist/holmes/mcp/handlers.js

@@ -1383,10 +1383,23 @@ function makeRawHandlers(store, opts) {
                     // itself. The switch is env-only and an agent cannot set it (pre-tool-use blocks that,
                     // A-SPEC-532.2). Off, or a hitl-classed spec, falls straight through to the elicitor
                     // unchanged — the autonomous-OFF path is byte-identical to before.
-                    if ((0, autonomy_1.autonomousApprovalEnabled)(process.env)
+                    // @implements A-SPEC-553.1 — autonomy is the out-of-band env switch OR a valid, non-expired
+                    // session envelope marker under this project's `.ax/state/` (which an agent cannot write).
+                    const autonomyOn = (0, autonomy_1.autonomousApprovalEnabled)(process.env, a.root, new Date().toISOString());
+                    if (autonomyOn
                         && (0, autonomy_1.specApprovalAutonomy)(target.spec, resolver([target.spec])) === 'auto') {
                         approveResolved = { approval: autonomousApproval(), source: 'autonomous' };
                     }
+                    else if (autonomyOn) {
+                        // @implements A-SPEC-551.1 — hitl-grade spec under autonomy: the in-session elicitation
+                        // dialog is auto-acceptable by an auto-mode client (the protocol cannot tell a human
+                        // from an auto-accept), so a governance-critical spec is never offered it. Do nothing
+                        // here — approveResolved stays undefined and the fail-closed refuse+enqueue path below
+                        // routes the act to the out-of-band human queue (holmes-kit approve). The A-SPEC-532.1
+                        // bound ("governance-critical specs never leave the human channel") thus becomes
+                        // ENFORCED, not aspirational. Autonomy OFF (the else) and the auto-grade branch above
+                        // stay byte-identical to before.
+                    }
                     else {
                         const resealing = typeof target.spec.frontmatter.approved_digest === 'string';
                         // The MODEL text is capped BEFORE the server markers are appended (round-2): a ~185+ char

package/dist/holmes/mcp/server.js

@@ -75,6 +75,25 @@ const SERVER_INSTRUCTIONS = (() => {
     }
 })();
 const server = new index_js_1.Server({ name: 'holmes-kit', version: PKG_VERSION }, { capabilities: { tools: {} }, instructions: SERVER_INSTRUCTIONS });
+// @implements A-SPEC-547.2 — refresh the update cache from the MCP server too, not just Claude's
+// SessionStart hook, so agy/codex (no SessionStart) keep the "new version" notice current. Detached,
+// TTL-gated, fail-soft: any failure leaves the server starting normally.
+(() => {
+    try {
+        const os = require('node:os');
+        const fs = require('node:fs');
+        const cp = require('node:child_process');
+        const { maybeSpawnRefresh } = require('../update/refresh');
+        maybeSpawnRefresh({
+            home: os.homedir(), env: process.env, now: Date.now(),
+            readFile: (p) => fs.readFileSync(p, 'utf8'),
+            execPath: process.execPath,
+            scriptPath: require('node:path').resolve(__dirname, '..', 'hooks', 'session-start.js'),
+            spawn: (cmd, args, o) => cp.spawn(cmd, args, o),
+        });
+    }
+    catch { /* the update check is never a gate */ }
+})();
 const fullProfile = process.env.HOLMES_MCP_PROFILE === 'full';
 // Register each handler as a tool with its real typed inputSchema so MCP
 // clients can marshal complex (array/object) arguments; fall back to a

package/dist/holmes/semantic/credentials.js

@@ -44,7 +44,7 @@ exports.removeSemanticKey = removeSemanticKey;
  * an agent assigning the env names (self-granted egress, the HOLMES_ROLE class); this module owns
  * the storage the human's CLI act writes to. A project-tree file is NEVER a source — a tree file
  * is a commit-accident surface and readable by every in-session tool, which is exactly what the
- * owner's ".env 는 임시 조치" call-out named.
+ * owner's ".env is a stopgap" call-out named.
  *
  * Resolution chain, the order being the contract:
  *   1. HOLMES_SEMANTIC_API_KEY  — dedicated name, CI/headless.

package/dist/holmes/spec/id-collision.js

@@ -49,13 +49,13 @@ function detectIdCollisions(entries) {
                 sealContents.set(en.approvedDigest, new Set([en.contentDigest]));
         }
         const sharedSeals = [...sealContents.entries()].filter(([, cs]) => cs.size > 1).map(([s]) => s).sort();
-        const parts = [...byKey.entries()].sort().map(([k, ens]) => `${k}[seal=${[...new Set(ens.map((en) => en.approvedDigest ?? '없음'))].sort().join('|')}] ← ${ens.map((en) => en.file).sort().join(', ')}`);
+        const parts = [...byKey.entries()].sort().map(([k, ens]) => `${k}[seal=${[...new Set(ens.map((en) => en.approvedDigest ?? 'none'))].sort().join('|')}] ← ${ens.map((en) => en.file).sort().join(', ')}`);
         issues.push({
             kind: 'id-collision',
             id,
             files: group.map((en) => en.file).sort(),
             detail: parts.join(' / ')
-                + (sharedSeals.length > 0 ? ` — 같은 approved_digest 를 서로 다른 내용이 공유(${sharedSeals.join(', ')}): post-approval edit 또는 봉인 복사 의심` : ''),
+                + (sharedSeals.length > 0 ? ` — different contents share the same approved_digest (${sharedSeals.join(', ')}): suspected post-approval edit or seal copy` : ''),
         });
     }
     // --- family-coexistence: a bare A/T-SPEC id alongside its own dot-suffix family ---

package/dist/holmes/update/refresh.d.ts

@@ -0,0 +1,49 @@
+import { UpdateCache } from './update-notice';
+/** The npm registry document for this scoped package — `dist-tags.latest` is the published latest. */
+export declare const REGISTRY_URL = "https://registry.npmjs.org/@holmes-lab%2Fholmes-kit";
+export interface RefreshOpts {
+    home: string;
+    now: number;
+    query: () => Promise<string>;
+    writeFile: (p: string, data: string) => void;
+    mkdir: (dir: string) => void;
+}
+/**
+ * @implements A-SPEC-547.1
+ * Pure: the `dist-tags.latest` string from a registry document body, or null on broken JSON, a missing
+ * field, or a non-string value. Never throws.
+ */
+export declare function parseLatest(body: string): string | null;
+/**
+ * @implements A-SPEC-547.1
+ * Query the registry (injected) and write ~/.holmes/update-check.json with {latest, checkedAt}. A query
+ * failure or an unparseable latest writes nothing and resolves false (fail-open). Staleness is the
+ * caller's decision — this always attempts.
+ */
+export declare function refreshCache(opts: RefreshOpts): Promise<boolean>;
+export interface SpawnRefreshOpts {
+    home: string;
+    env: NodeJS.ProcessEnv;
+    now: number;
+    readFile: (p: string) => string;
+    execPath: string;
+    scriptPath: string;
+    spawn: (cmd: string, args: string[], opts: {
+        detached: boolean;
+        stdio: 'ignore';
+    }) => {
+        unref: () => void;
+    };
+}
+/**
+ * @implements A-SPEC-547.2
+ * Pure: whether a network refresh should fire now — network allowed (not opted out / not CI) AND the
+ * cache is stale (or absent). Composes the two existing decisions so every trigger agrees.
+ */
+export declare function shouldRefreshCache(cached: UpdateCache | null, env: NodeJS.ProcessEnv, now: number): boolean;
+/**
+ * @implements A-SPEC-547.2
+ * Read the cache and, when shouldRefreshCache, spawn the detached `session-start.js --refresh` child so
+ * ANY harness's MCP startup keeps the cache fresh — not just Claude's SessionStart hook. Fail-open.
+ */
+export declare function maybeSpawnRefresh(opts: SpawnRefreshOpts): boolean;

package/dist/holmes/update/refresh.js

@@ -0,0 +1,106 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.REGISTRY_URL = void 0;
+exports.parseLatest = parseLatest;
+exports.refreshCache = refreshCache;
+exports.shouldRefreshCache = shouldRefreshCache;
+exports.maybeSpawnRefresh = maybeSpawnRefresh;
+// @implements A-SPEC-547.1
+const path = __importStar(require("node:path"));
+const update_notice_1 = require("./update-notice");
+/** The npm registry document for this scoped package — `dist-tags.latest` is the published latest. */
+exports.REGISTRY_URL = 'https://registry.npmjs.org/@holmes-lab%2Fholmes-kit';
+/**
+ * @implements A-SPEC-547.1
+ * Pure: the `dist-tags.latest` string from a registry document body, or null on broken JSON, a missing
+ * field, or a non-string value. Never throws.
+ */
+function parseLatest(body) {
+    try {
+        const latest = JSON.parse(body)?.['dist-tags']?.latest;
+        return typeof latest === 'string' ? latest : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * @implements A-SPEC-547.1
+ * Query the registry (injected) and write ~/.holmes/update-check.json with {latest, checkedAt}. A query
+ * failure or an unparseable latest writes nothing and resolves false (fail-open). Staleness is the
+ * caller's decision — this always attempts.
+ */
+async function refreshCache(opts) {
+    let latest = null;
+    try {
+        latest = parseLatest(await opts.query());
+    }
+    catch {
+        return false; // fail-open: a network/query failure writes nothing
+    }
+    if (!latest)
+        return false;
+    const dir = path.join(opts.home, '.holmes');
+    opts.mkdir(dir);
+    opts.writeFile(path.join(dir, 'update-check.json'), JSON.stringify({ latest, checkedAt: opts.now }));
+    return true;
+}
+/**
+ * @implements A-SPEC-547.2
+ * Pure: whether a network refresh should fire now — network allowed (not opted out / not CI) AND the
+ * cache is stale (or absent). Composes the two existing decisions so every trigger agrees.
+ */
+function shouldRefreshCache(cached, env, now) {
+    return (0, update_notice_1.shouldQuery)(env) && (0, update_notice_1.cacheIsStale)(cached, now);
+}
+/**
+ * @implements A-SPEC-547.2
+ * Read the cache and, when shouldRefreshCache, spawn the detached `session-start.js --refresh` child so
+ * ANY harness's MCP startup keeps the cache fresh — not just Claude's SessionStart hook. Fail-open.
+ */
+function maybeSpawnRefresh(opts) {
+    try {
+        const cached = (0, update_notice_1.readCache)(opts.home, opts.readFile);
+        if (!shouldRefreshCache(cached, opts.env, opts.now))
+            return false;
+        const child = opts.spawn(opts.execPath, [opts.scriptPath, '--refresh'], { detached: true, stdio: 'ignore' });
+        child.unref();
+        return true;
+    }
+    catch {
+        return false; // fail-open: a refresh is never a gate
+    }
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "//": "@implements A-SPEC-209",
   "name": "@holmes-lab/holmes-kit",
-  "version": "0.12.1",
+  "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)