@holmes-lab/holmes-kit 0.12.2 → 0.14.0

package/dist/holmes/hooks/stop.js

@@ -36,6 +36,9 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.MAX_CONSECUTIVE_BLOCKS = void 0;
 exports.changedAnchoredAspecs = changedAnchoredAspecs;
 exports.unanchoredChangedSources = unanchoredChangedSources;
+exports.dependencyReappraisals = dependencyReappraisals;
+exports.reappraisalWarningLine = reappraisalWarningLine;
+exports.escalateReappraisals = escalateReappraisals;
 exports.unrecordedApprovals = unrecordedApprovals;
 exports.rolledBackLedgers = rolledBackLedgers;
 exports.governanceLostPreflight = governanceLostPreflight;
@@ -50,6 +53,9 @@ exports.readGuardCount = readGuardCount;
 exports.writeGuardCount = writeGuardCount;
 const fs = __importStar(require("node:fs"));
 const npx_bin_1 = require("../project/npx-bin");
+const approval_queue_1 = require("../governance/approval-queue");
+const dependency_delta_1 = require("../guardrail/dependency-delta");
+const autonomy_1 = require("../governance/autonomy");
 const risk_gate_1 = require("../guardrail/risk-gate");
 const json_state_1 = require("../project/json-state");
 const node_child_process_1 = require("node:child_process");
@@ -74,7 +80,9 @@ function changedAnchoredAspecs(root) {
     const VENDORED = /^(?:reference|node_modules|dist|build|vendor|third_party)\//;
     let raw;
     try {
-        raw = (0, node_child_process_1.execFileSync)('git', ['status', '--porcelain', '-uall'], {
+        // @implements A-SPEC-560.3 — quotepath OFF, or a non-ASCII-named source arrives octal-escaped
+        // and its ART-8 evidence silently vanishes (shared defect with the reappraisal detector).
+        raw = (0, node_child_process_1.execFileSync)('git', ['-c', 'core.quotepath=false', 'status', '--porcelain', '-uall'], {
             cwd: root, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], env: (0, root_1.cleanSubprocessEnv)(),
         });
     }
@@ -120,7 +128,8 @@ function unanchoredChangedSources(root) {
     try {
         // `-uall`: without it git folds a wholly-untracked directory into one `?? src/` line and the
         // files inside it are never seen — which is precisely where a bypassed write lands.
-        raw = (0, node_child_process_1.execFileSync)('git', ['status', '--porcelain', '-uall'], {
+        // @implements A-SPEC-560.3 — quotepath OFF (same octal-escape blindness as the siblings).
+        raw = (0, node_child_process_1.execFileSync)('git', ['-c', 'core.quotepath=false', 'status', '--porcelain', '-uall'], {
             cwd: root, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], env: (0, root_1.cleanSubprocessEnv)(),
         });
     }
@@ -148,6 +157,141 @@ function unanchoredChangedSources(root) {
     }
     return out;
 }
+const REAPPRAISAL_VENDORED = /^(?:reference|node_modules|dist|build|vendor|third_party)\//;
+function depLangOf(rel) {
+    if (/\.(?:ts|tsx|mts|cts|js|jsx|mjs|cjs)$/.test(rel))
+        return 'ts';
+    if (/\.py$/.test(rel))
+        return 'py';
+    return undefined;
+}
+function dependencyReappraisals(root, isApproved, io = {}) {
+    // @implements A-SPEC-560.3 — quotepath OFF: with the default core.quotepath, a Korean- (or any
+    // non-ASCII/quote-) named file arrives octal-escaped, the read then ENOENTs, and the signal is
+    // silently lost. Measured: 2 of 4 drifting files detected before this flag.
+    const status = io.status ?? (() => {
+        try {
+            return (0, node_child_process_1.execFileSync)('git', ['-c', 'core.quotepath=false', 'status', '--porcelain', '-uall'], { cwd: root, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], env: (0, root_1.cleanSubprocessEnv)() });
+        }
+        catch {
+            return undefined;
+        }
+    });
+    const show = io.show ?? ((rel) => {
+        try {
+            return (0, node_child_process_1.execFileSync)('git', ['-c', 'core.quotepath=false', 'show', `HEAD:${rel}`], { cwd: root, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], env: (0, root_1.cleanSubprocessEnv)() });
+        }
+        catch {
+            return undefined;
+        }
+    });
+    const read = io.read ?? ((rel) => {
+        try {
+            return fs.readFileSync(path.join(root, rel), 'utf8');
+        }
+        catch {
+            return undefined;
+        }
+    });
+    let raw;
+    try {
+        raw = status();
+    }
+    catch {
+        raw = undefined;
+    }
+    if (raw === undefined)
+        return [];
+    const out = [];
+    for (const line of raw.split('\n')) {
+        if (line.trim() === '')
+            continue;
+        let rel = line.slice(3).trim().replace(/^"|"$/g, '');
+        if (rel.includes(' -> '))
+            rel = rel.split(' -> ')[1]; // renames name the destination
+        const lang = depLangOf(rel);
+        if (lang === undefined || REAPPRAISAL_VENDORED.test(rel))
+            continue;
+        let after;
+        try {
+            after = read(rel);
+        }
+        catch {
+            after = undefined;
+        }
+        if (after === undefined)
+            continue; // deleted / unreadable
+        const aspecs = [...new Set([...after.matchAll(/@implements\s+(A-SPEC-\d+(?:\.\d+)?)/g)].map((m) => m[1]))].filter(isApproved).sort();
+        if (aspecs.length === 0)
+            continue; // not inside an APPROVED A-SPEC scope
+        let before;
+        try {
+            before = show(rel);
+        }
+        catch {
+            before = undefined;
+        }
+        if (before === undefined)
+            continue; // no HEAD version = a new file, not in-scope drift
+        let packages = [];
+        try {
+            packages = (0, dependency_delta_1.dependencyDelta)(before, after, lang);
+        }
+        catch {
+            packages = [];
+        }
+        if (packages.length > 0)
+            out.push({ file: rel, aspecs, packages });
+    }
+    return out;
+}
+function reappraisalWarningLine(reaps) {
+    if (reaps.length === 0)
+        return null;
+    return reaps.map((r) => `[Holmes-Kit] spec-reappraisal: ${r.file} introduces external dependency ${r.packages.join(', ')} inside approved ${r.aspecs.join(', ')} scope — this looks like an architecture change; update the spec or open a sub-slice.`).join('\n');
+}
+// @implements A-SPEC-560.3 — decision-respecting escalation: a reappraisal the owner already decided
+// (granted/denied in the queue ledger) must not re-pend every turn while the tree stays dirty, and an
+// already-pending one needs no duplicate append. A reader failure fails OPEN (the signal survives).
+function escalateReappraisals(root, reaps, opts) {
+    if (!opts.autonomous)
+        return 0;
+    const readLines = opts.readQueueLines ?? ((r) => fs.readFileSync(path.join(r, approval_queue_1.QUEUE_RELPATH), 'utf8').split('\n'));
+    let lines;
+    try {
+        lines = readLines(root);
+    }
+    catch {
+        lines = [];
+    } // a broken reader fails OPEN — the signal survives
+    let n = 0;
+    for (const r of reaps) {
+        try {
+            const id = (0, approval_queue_1.approvalRequestId)('spec-reappraisal', r.file);
+            let decided = false;
+            let lastEvent;
+            for (const raw of lines) {
+                if (raw.trim() === '')
+                    continue;
+                try {
+                    const e = JSON.parse(raw);
+                    if (e.id !== id)
+                        continue;
+                    lastEvent = String(e.event);
+                    if (lastEvent === 'granted' || lastEvent === 'denied')
+                        decided = true;
+                }
+                catch { /* a corrupt line is not this id's history */ }
+            }
+            if (decided || lastEvent === 'requested')
+                continue; // decided, or already pending — no re-append
+            if (opts.enqueue(root, { kind: 'spec-reappraisal', target: r.file, why: `new external dependency ${r.packages.join(', ')} inside approved ${r.aspecs.join(', ')} — spec update or sub-slice needed` }))
+                n += 1;
+        }
+        catch { /* enqueue failure is best-effort; the warning still surfaced */ }
+    }
+    return n;
+}
 /**
  * @implements A-SPEC-453
  * ART-5 evidence: approvals that happened without the approving act.
@@ -318,27 +462,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 +584,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 +667,7 @@ function findProjectRoot(specsDir) {
             if (r.marker !== 'given')
                 return r.root;
         }
-        catch { /* 표지가 없으면 짓지 않는다 */ }
+        catch { /* if there is no marker, build nothing */ }
         return null;
     }
     return null;
@@ -769,6 +913,24 @@ if (require.main === module) {
             let out = evaluateStop(specs, { testCasesByAspec, provenance, executedByAspec, findings, findingsUnreadable, unanchoredChangedSources: unanchored, unrecordedApprovals: unrecorded, rolledBackLedgers: rolledBack, redFirstMode, changedAspecs, outcomesByAspec });
             // @implements A-SPEC-534.4 — track mode records ART-8 findings without blocking: surface them so
             // the operator observes RED-first gaps before an owner promotes the posture to strict.
+            // @implements A-SPEC-559.2 — spec-evolution trigger (observe-first, NEVER blocks): a dirty
+            // in-scope source that newly introduces an external dependency is an architecture-drift signal.
+            // Manual mode warns; autonomy mode also enqueues it so the owner sees the drift async. Fail-open.
+            // @implements A-SPEC-560.3 — placed BEFORE the guard decisions and their early returns, so a
+            // degraded-yield turn (guard state unwritable) still surfaces the drift; stderr-only, so no
+            // verdict path is affected.
+            try {
+                const approvedIds = new Set(specs.filter((s) => s.type === 'A-SPEC' && s.status === 'approved').map((s) => s.id));
+                const reaps = dependencyReappraisals(stopProjectRoot(), (id) => approvedIds.has(id));
+                const line = reappraisalWarningLine(reaps);
+                if (line)
+                    process.stderr.write(`${line}\n`);
+                const nowIso = new Date().toISOString();
+                if (line && (0, autonomy_1.autonomousApprovalEnabled)(process.env, stopProjectRoot(), nowIso)) {
+                    escalateReappraisals(stopProjectRoot(), reaps, { autonomous: true, enqueue: approval_queue_1.enqueueApprovalRequest });
+                }
+            }
+            catch { /* the reappraisal signal is advisory; a failure never affects the stop verdict */ }
             if (out.tracked && out.tracked.length > 0) {
                 process.stderr.write(`[Holmes-Kit] ART-8 RED-first (track): ${out.tracked.map((t) => t.detail).join(' | ')}\n`);
             }
@@ -814,7 +976,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 +988,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/project/root.js

@@ -77,7 +77,15 @@ function cleanSubprocessEnv(env = process.env) {
  * evidence run would disarm every test that verifies a gate, and that contamination masks red as
  * green — the worse direction of the two.
  */
-const TEST_SCRUB_KEYS = new Set(['HOLMES_SPECS', 'HOLMES_GATE_BYPASS', 'HOLMES_MCP_AUTORELOAD', 'HOLMES_MCP_PROFILE']);
+// @implements A-SPEC-561.1
+// `HOLMES_AUTONOMOUS_APPROVAL` joins the list for the SAME reason, pointing the same way as the
+// HOLMES_SPECS incident above: measured 2026-09-06, a project that opted into autonomy
+// (`init --autonomy` persists the switch into .mcp.json) starts its MCP server with that env, the
+// server's `test_run` handed it to the jest children, and REQ-551's autonomy branch then skipped the
+// elicitation path — 9 elicitation tests red on a tree whose full suite was green, twice, and
+// identically on the previous commit. A posture is an approval channel, never a property of the code
+// under test; an evidence run must judge the same in an autonomous workspace and a human-gated one.
+const TEST_SCRUB_KEYS = new Set(['HOLMES_SPECS', 'HOLMES_GATE_BYPASS', 'HOLMES_MCP_AUTORELOAD', 'HOLMES_MCP_PROFILE', 'HOLMES_AUTONOMOUS_APPROVAL']);
 function cleanTestEnv(env = process.env) {
     const cleaned = cleanSubprocessEnv(env);
     for (const k of Object.keys(cleaned)) {

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/package.json

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