@holmes-lab/holmes-kit 0.1.15 → 0.1.16

package/CHANGELOG.md

@@ -4,6 +4,28 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+<!-- @implements A-SPEC-209 -->
+## [0.1.16] - 2026-08-23
+
+Predictable spec numbering — enforced at the door, and the corpus cleaned to match.
+
+### Added
+- **spec_create refuses a wild id (REQ-252)**: a new id whose base number leaps past
+  `max(base) + 1` is refused, naming the next available number. `spec_slice_init` assigns
+  `max + 1`, which is only predictable while numbering stays sequential — a single hand-picked
+  id (REQ-1403) once dragged the max to 1403 and every slice after jumped to 1404. The guard
+  closes the one door that let a manual id in, so `max + 1` can never be poisoned again.
+  Gap-fills, chain completion (base == max), and sub-slices (250.1) still pass; slice_init is
+  unaffected. Pure `sequentialIdVerdict`, injected id list — no filesystem.
+
+### Changed
+- **Spec numbering restructured for readability**: the MCP drift fix shipped in 0.1.15 as two
+  top-level REQs (1404/1405) that were really one problem. Refiled under this repo's own
+  sub-slice convention as REQ-251 with A-SPEC-251.1 (npx wiring) and A-SPEC-251.2 (doctor
+  drift). The out-of-sequence REQ-1403 was renumbered to its rightful 250. Code `@implements`
+  anchors moved with them. No runtime behavior change — ids and anchors only; the 0.1.15
+  features are byte-identical.
+
 <!-- @implements A-SPEC-209 -->
 ## [0.1.15] - 2026-08-23
 

package/dist/.build-id

@@ -1 +1 @@
-d6b14ca-mt5ea641
+3c84046-mt5fni4h

package/dist/holmes/cli/agents.js

@@ -70,7 +70,7 @@ exports.HARNESS_ENFORCES = {
     codex: false,
 };
 const q = (p) => p;
-// @implements A-SPEC-1404 — same launch contract as the Claude wiring: npx-pin for installed
+// @implements A-SPEC-251.1 — same launch contract as the Claude wiring: npx-pin for installed
 // packageRoots, node for source checkouts. Shared via mcpEntryForInstall so all three harnesses
 // move together.
 const mcpConfig = (packageRoot, specsDir, launcher) => {

package/dist/holmes/cli/doctor.js

@@ -456,7 +456,7 @@ async function runDoctor(packageRoot, target, opts, extraChecks) {
         else {
             add('approval channel', 'WARN', '이 프로세스에는 HOLMES_APPROVAL이 있으나 .mcp.json의 서버 환경에는 없습니다 — spec_approve는 서버 환경을 읽습니다', 'settings.local.json의 env가 MCP 서버까지 전달된다는 보장은 없습니다. 그 변수를 설정한 셸에서 Claude Code를 띄우면 자식 서버가 상속합니다.');
         }
-        // @implements A-SPEC-1405 — the version this project's MCP server will ACTUALLY launch, vs this
+        // @implements A-SPEC-251.2 — the version this project's MCP server will ACTUALLY launch, vs this
         // CLI. The stale-global trap (measured 2026-08-23: .mcp.json pinned a 0.1.9 global while the user
         // believed they had upgraded) was invisible because nothing compared them. Offline: the launch
         // version comes from the wiring string, or a node wiring's LOCAL package.json — never the registry.

package/dist/holmes/cli/index.js

@@ -429,7 +429,7 @@ async function main(argv) {
     }
     if (cmd === 'init') {
         const mode = (typeof flags.mode === 'string' ? flags.mode : 'guardrail');
-        // @implements A-SPEC-1404 — an unknown launch mode is refused, not defaulted: substituting a
+        // @implements A-SPEC-251.1 — an unknown launch mode is refused, not defaulted: substituting a
         // default acts where the operator did not point (REQ-144). Only npx|node are wiring modes.
         let mcpLauncher;
         if (typeof flags['mcp-launcher'] === 'string') {

package/dist/holmes/cli/init.js

@@ -310,7 +310,7 @@ function runInit(opts) {
             const kept = Object.keys(prevEnv).filter((k) => !settings_merge_2.HOLMES_OWNED_MCP_ENV.includes(k));
             if (kept.length > 0)
                 messages.push(`Preserved your MCP server env: ${kept.join(', ')}`);
-            // @implements A-SPEC-1404 — compute the launch entry once (npx-pin for installs, node for source),
+            // @implements A-SPEC-251.1 — compute the launch entry once (npx-pin for installs, node for source),
             // then merge; env preservation is unchanged.
             const mcpEntry = (0, mcp_launcher_1.mcpEntryForInstall)({ packageRoot: opts.packageRoot, mcpBinPath: mcpBin, flag: opts.mcpLauncher });
             changes.push({ path: mcpPath, before: m.raw, after: JSON.stringify((0, settings_merge_1.mergeMcpServers)(m.value, exports.SERVER_NAME, mcpEntry, opts.specsDir), null, 2) + '\n' });

package/dist/holmes/cli/mcp-launcher.d.ts

@@ -3,7 +3,7 @@
  *
  * 왜 한 곳인가: `.mcp.json`(Claude)·`.agents/mcp_config.json`(antigravity)·`.codex/mcp_config.json`
  * 세 배선이 같은 서버를 띄운다. 셋이 각자 command/args 를 지으면 하나가 npx 로 옮겨갈 때 나머지가
- * 절대경로에 남아 어긋난다 — 그 드리프트가 REQ-1404 자체의 출발점이었다.
+ * 절대경로에 남아 어긋난다 — 그 드리프트가 REQ-251 자체의 출발점이었다.
  *
  * 왜 두 모드인가: 최종 사용자는 npm 설치본에서 init 하므로 `npx ...@<정확한버전> holmes-mcp` 가
  * 옳다 — 전역 설치도 `-g` 도 필요 없고(Windows EPERM 회피), 절대경로 고착이 없다. 그러나 개발
@@ -45,7 +45,7 @@ export declare function readPackageVersion(packageRoot: string): string | undefi
  * 세 배선(Claude/antigravity/codex)이 공유하는 조립: 모드 판별 → 버전 읽기 → entry.
  *
  * npx 로 판별됐어도 버전을 못 읽으면 node 로 물러난다 — 빈 핀(`@holmes-lab/holmes-kit@`)을 박느니
- * 로컬 bin 을 부르는 편이 유효하다(A-SPEC-1404 경계). `readVersion` 은 주입 가능해 시험이 fs 없이 돈다.
+ * 로컬 bin 을 부르는 편이 유효하다(A-SPEC-251.1 경계). `readVersion` 은 주입 가능해 시험이 fs 없이 돈다.
  */
 export declare function mcpEntryForInstall(opts: {
     packageRoot: string;

package/dist/holmes/cli/mcp-launcher.js

@@ -38,7 +38,7 @@ exports.mcpServerEntry = mcpServerEntry;
 exports.resolveLauncherMode = resolveLauncherMode;
 exports.readPackageVersion = readPackageVersion;
 exports.mcpEntryForInstall = mcpEntryForInstall;
-// @implements A-SPEC-1404
+// @implements A-SPEC-251.1
 const fs = __importStar(require("node:fs"));
 const path = __importStar(require("node:path"));
 /** npm 상의 정식 패키지 이름. 핀은 이 이름에 정확한 버전을 붙인다. */
@@ -83,7 +83,7 @@ function readPackageVersion(packageRoot) {
  * 세 배선(Claude/antigravity/codex)이 공유하는 조립: 모드 판별 → 버전 읽기 → entry.
  *
  * npx 로 판별됐어도 버전을 못 읽으면 node 로 물러난다 — 빈 핀(`@holmes-lab/holmes-kit@`)을 박느니
- * 로컬 bin 을 부르는 편이 유효하다(A-SPEC-1404 경계). `readVersion` 은 주입 가능해 시험이 fs 없이 돈다.
+ * 로컬 bin 을 부르는 편이 유효하다(A-SPEC-251.1 경계). `readVersion` 은 주입 가능해 시험이 fs 없이 돈다.
  */
 function mcpEntryForInstall(opts) {
     const mode = resolveLauncherMode({ flag: opts.flag, packageRoot: opts.packageRoot });

package/dist/holmes/cli/mcp-version.d.ts

@@ -1,7 +1,7 @@
 /**
  * `.mcp.json` 배선이 **실제로 띄울** holmes-kit 버전을, 네트워크 없이 로컬로 뽑는다.
  *
- * 이 판정이 없어서 사용자의 전역 0.1.9 정체를 아무 진단도 보지 못했다(REQ-1405). 레지스트리를
+ * 이 판정이 없어서 사용자의 전역 0.1.9 정체를 아무 진단도 보지 못했다(REQ-251). 레지스트리를
  * 묻지 않는다 — 배선 문자열과, node 배선인 경우 주입된 로컬 reader 만 본다. reader 를 안 주면 node
  * 경로는 판정 불능(null)이지 실제 fs 를 더듬지 않는다: 순수성이 [offline] 을 시험 가능하게 한다.
  */

package/dist/holmes/cli/mcp-version.js

@@ -35,7 +35,7 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.mcpLaunchVersion = mcpLaunchVersion;
 exports.versionDriftVerdict = versionDriftVerdict;
-// @implements A-SPEC-1405
+// @implements A-SPEC-251.2
 const path = __importStar(require("node:path"));
 /** npx 인자에서 핀 버전을 뽑는 정규식: `@holmes-lab/holmes-kit@<X>` 의 X. `@` 없는 스펙은 안 잡힌다. */
 const NPX_PIN = /^@holmes-lab\/holmes-kit@(.+)$/;

package/dist/holmes/cli/settings-merge.js

@@ -90,7 +90,7 @@ function disableMcpServer(existing, name) {
  * put it there.
  */
 exports.HOLMES_OWNED_MCP_ENV = ['HOLMES_SPECS'];
-// @implements A-SPEC-1404
+// @implements A-SPEC-251.1
 // The server entry (command/args) is COMPUTED by the caller (mcp-launcher: npx-pin for installs,
 // node for source checkouts) rather than assembled here, so all three harness wirings share one
 // launch contract. This merge owns only env preservation, not how the server is launched.

package/dist/holmes/mcp/handlers.js

@@ -138,6 +138,7 @@ const ignore_1 = require("../project/ignore");
 // @implements A-SPEC-126
 const scan_1 = require("../reverse/scan");
 const draft_1 = require("../reverse/draft");
+const spec_id_guard_1 = require("./spec-id-guard");
 const anchor_1 = require("../reverse/anchor");
 // @implements A-SPEC-128
 // Where a project begins, for tools that only walk the tree.
@@ -593,6 +594,16 @@ function makeRawHandlers(store) {
                     return { ok: false, reason: `depends_on "${String(pid)}"는 ${ptype}입니다 — ${def.type}의 부모는 ${def.parents.join('|') || '없음(빈 depends_on)'}이어야 합니다.` };
                 }
             }
+            // @implements A-SPEC-252
+            // A new id may not LEAP past the sequence. spec_slice_init assigns nextId = max(base)+1, which
+            // is only predictable while numbering stays sequential; a hand-picked wild id (REQ-1403) once
+            // dragged max to 1403 and every slice after jumped to 1404. Refused here, at the one door that
+            // lets a manual id in — so max+1 can never be poisoned again. After the shape check on purpose:
+            // an id whose base cannot be read is the shape check's to name, not this guard's.
+            const corpus = await store.list();
+            const seq = (0, spec_id_guard_1.sequentialIdVerdict)(String(id), corpus.map((s) => s.id));
+            if (!seq.ok)
+                return { ok: false, reason: seq.reason };
             // @implements A-SPEC-188
             // Creation creates. Probed before this check existed: spec_create over an approved+sealed
             // REQ returned {"created"} while the disk went draft / seal gone / prose gone — the sanctioned
@@ -600,7 +611,7 @@ function makeRawHandlers(store) {
             // refusals on purpose: a malformed id must keep its own message (order is pinned by test).
             // Legacy (typeless) documents count as existing too — overwriting one makes the store's
             // orphan removal delete the differently-named original file along with its history.
-            const existing = (await store.list()).find((s) => s.id === id);
+            const existing = corpus.find((s) => s.id === id);
             if (existing) {
                 const sealed = existing.status === 'approved' || Boolean(existing.frontmatter?.approved_digest);
                 const kind = existing.type ? `${existing.type} (status: ${existing.status})` : `옛 형식 문서 (status: ${existing.status})`;

package/dist/holmes/mcp/spec-id-guard.d.ts

@@ -0,0 +1,26 @@
+/**
+ * 넘버링 오염을 생성 시점에 막는 순수 가드.
+ *
+ * spec_slice_init 의 `nextId = max(base) + 1` 은 번호가 항상 순차 배정될 때만 예측 가능하다. 그런데
+ * spec_create 는 id 형태만 보고 순번은 보지 않아, 손으로 심은 wild id(REQ-1403) 하나가 max 를 끌어올려
+ * 이후 모든 슬라이스를 오염시켰다(실측: 249→1404). 이 가드는 그 하나의 구멍을 막는다 — 새 base 는
+ * 현재 max 를 한 칸 넘게 뛸 수 없다. 막으면 max+1 은 다시 오염되지 않고 넘버링이 영구히 예측 가능하다.
+ */
+/** id 의 base 숫자. "REQ-1403"→1403, "A-SPEC-250.1"→250(서브번호 무시), 레거시 "H-SPEC-050"→50. 못 뽑으면 null. */
+export declare function specIdBase(id: string): number | null;
+export type IdVerdict = {
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+    nextAvailable: number;
+};
+/**
+ * 새 id 의 base 가 코퍼스 max base 를 한 칸 넘게 뛰면 거부한다.
+ *
+ * - 빈 코퍼스, 또는 base 를 못 뽑는 id → 통과(비교 대상이 없거나, 형태 검증은 별도 소관이라 한 결함에
+ *   두 이름을 주지 않는다).
+ * - base ≤ maxBase(갭 메우기·체인 완성) 또는 base == maxBase+1(새 체인) → 통과.
+ * - base > maxBase+1(leap) → 거부, 다음 가용 번호를 문면과 필드에 댄다.
+ */
+export declare function sequentialIdVerdict(newId: string, existingIds: string[]): IdVerdict;

package/dist/holmes/mcp/spec-id-guard.js

@@ -0,0 +1,50 @@
+"use strict";
+// @implements A-SPEC-252
+/**
+ * 넘버링 오염을 생성 시점에 막는 순수 가드.
+ *
+ * spec_slice_init 의 `nextId = max(base) + 1` 은 번호가 항상 순차 배정될 때만 예측 가능하다. 그런데
+ * spec_create 는 id 형태만 보고 순번은 보지 않아, 손으로 심은 wild id(REQ-1403) 하나가 max 를 끌어올려
+ * 이후 모든 슬라이스를 오염시켰다(실측: 249→1404). 이 가드는 그 하나의 구멍을 막는다 — 새 base 는
+ * 현재 max 를 한 칸 넘게 뛸 수 없다. 막으면 max+1 은 다시 오염되지 않고 넘버링이 영구히 예측 가능하다.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.specIdBase = specIdBase;
+exports.sequentialIdVerdict = sequentialIdVerdict;
+/** id 의 base 숫자. "REQ-1403"→1403, "A-SPEC-250.1"→250(서브번호 무시), 레거시 "H-SPEC-050"→50. 못 뽑으면 null. */
+function specIdBase(id) {
+    if (typeof id !== 'string')
+        return null;
+    // 마지막 하이픈 뒤의 숫자 토막(점 앞)을 base 로 본다.
+    const m = /-(\d+)(?:\.\d+)?\s*$/.exec(id.trim());
+    if (!m)
+        return null;
+    const n = parseInt(m[1], 10);
+    return Number.isNaN(n) ? null : n;
+}
+/**
+ * 새 id 의 base 가 코퍼스 max base 를 한 칸 넘게 뛰면 거부한다.
+ *
+ * - 빈 코퍼스, 또는 base 를 못 뽑는 id → 통과(비교 대상이 없거나, 형태 검증은 별도 소관이라 한 결함에
+ *   두 이름을 주지 않는다).
+ * - base ≤ maxBase(갭 메우기·체인 완성) 또는 base == maxBase+1(새 체인) → 통과.
+ * - base > maxBase+1(leap) → 거부, 다음 가용 번호를 문면과 필드에 댄다.
+ */
+function sequentialIdVerdict(newId, existingIds) {
+    const base = specIdBase(newId);
+    if (base === null)
+        return { ok: true };
+    const bases = (existingIds ?? []).map(specIdBase).filter((n) => n !== null);
+    if (bases.length === 0)
+        return { ok: true };
+    const maxBase = Math.max(...bases);
+    if (base > maxBase + 1) {
+        const nextAvailable = maxBase + 1;
+        return {
+            ok: false,
+            reason: `${newId} 는 순번을 벗어납니다 — 현재 최대 번호는 ${maxBase}, 다음 가용 번호는 ${nextAvailable} 입니다. 순차 번호나 기존 base 의 서브슬라이스만 만들 수 있습니다(넘버링 오염 방지).`,
+            nextAvailable,
+        };
+    }
+    return { ok: true };
+}

package/package.json

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