@holmes-lab/holmes-kit 0.1.8 → 0.1.10

package/dist/holmes/testing/effects.js

@@ -0,0 +1,107 @@
+"use strict";
+// @implements A-SPEC-238
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.observeEffects = observeEffects;
+exports.expectPure = expectPure;
+/**
+ * Every filesystem READ surface, found by prefix rather than listed by name.
+ *
+ * Enumerating method names would let a new one through, and a pass reads as "no access". Judging the
+ * surface whole is the direction this repository has already taken three times: tool names in
+ * `write-target.ts`, shell verbs in `risk-classifier.ts`, and dependency declaration surfaces in
+ * `project/dependencies.ts`. Prefix matching also means a future Node release's new read method is
+ * covered the day it appears.
+ */
+const READ_PREFIXES = /^(read|stat|lstat|fstat|exists|open|access|opendir|realpath|watch|glob)/;
+/**
+ * The CommonJS `fs` module object, NOT an `import * as fs` namespace.
+ *
+ * The namespace an ES import produces exposes getter-only properties: assigning to one throws
+ * `TypeError: Cannot set property access of #<Object> which has only a getter`. Measured while
+ * writing this — the standalone probe worked because it used `require`, and the first version of
+ * this module did not, so every case failed at the first patch. The module object is what the code
+ * under test actually calls through.
+ */
+const fsModule = () => 
+// eslint-disable-next-line @typescript-eslint/no-var-requires
+require('node:fs');
+/**
+ * Run `fn` and report what it touched.
+ *
+ * @implements A-SPEC-238
+ * The body's exception is RETURNED in `threw`, not re-thrown. "Why did it fail" and "what did it
+ * touch" are different pieces of information and a caller usually needs both; re-throwing would
+ * restore the globals but discard the observation.
+ *
+ * WHAT THIS DOES NOT SEE. Network calls and child processes — no claim in this repository's
+ * `## Non-Functional` sections mentions them, and offering coverage would recreate the
+ * "documented but unenforced" state. Asynchronous work that lands after `fn` returns: every function
+ * making a purity claim here is synchronous. Reads through a handle obtained before observation
+ * began. And a grammar loaded once per process — measured 2026-08-23, `extractSymbols` performs 26
+ * filesystem calls on the FIRST call in a process and zero on every call after, including the first
+ * call for a different language. That is one-time lazy loading, not per-call I/O, and this tool
+ * cannot tell them apart: warm the callee first.
+ */
+function observeEffects(fn) {
+    const target = fsModule();
+    const surface = Object.keys(target).filter((k) => READ_PREFIXES.test(k) && typeof target[k] === 'function');
+    const originals = {};
+    const unwatched = [];
+    const calls = [];
+    for (const name of surface) {
+        const original = target[name];
+        try {
+            target[name] = function (...args) {
+                calls.push(name);
+                return original.apply(target, args);
+            };
+            // Assignment can silently no-op on a non-writable property, which would look like a wrapped
+            // method that never fires. Confirm it took.
+            if (target[name] === original) {
+                unwatched.push(name);
+                continue;
+            }
+            originals[name] = original;
+        }
+        catch {
+            unwatched.push(name);
+        }
+    }
+    const realNow = Date.now;
+    const realRandom = Math.random;
+    let clock = 0;
+    let random = 0;
+    Date.now = function () { clock++; return realNow.call(Date); };
+    Math.random = function () { random++; return realRandom.call(Math); };
+    let threw;
+    let didThrow = false;
+    try {
+        fn();
+    }
+    catch (e) {
+        threw = e;
+        didThrow = true;
+    }
+    finally {
+        // Restoration is in `finally` because a tool that patches globals and fails to put them back
+        // poisons every test that runs afterwards — and that poisoning surfaces far from its cause.
+        for (const name of Object.keys(originals))
+            target[name] = originals[name];
+        Date.now = realNow;
+        Math.random = realRandom;
+    }
+    const out = { fs: calls, clock, random, unwatched };
+    return didThrow ? { ...out, threw } : out;
+}
+/** Assert that `fn` touched nothing, naming what it touched when it did. */
+function expectPure(fn) {
+    const e = observeEffects(fn);
+    const touched = [
+        ...e.fs.map((m) => `fs.${m}`),
+        ...(e.clock ? [`Date.now ×${e.clock}`] : []),
+        ...(e.random ? [`Math.random ×${e.random}`] : []),
+    ];
+    if (touched.length > 0) {
+        throw new Error(`expected no effects, observed: ${[...new Set(touched)].join(', ')}`);
+    }
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "//": "@implements A-SPEC-209",
   "name": "@holmes-lab/holmes-kit",
-  "version": "0.1.8",
+  "version": "0.1.10",
   "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",
@@ -23,7 +23,8 @@
     "test": "npm run typecheck && jest",
     "mcp": "node bin/holmes-mcp.js",
     "release": "npm run build && node scripts/make-release.js",
-    "typecheck": "tsc --noEmit -p tsconfig.test.json"
+    "typecheck": "tsc --noEmit -p tsconfig.test.json",
+    "prepublishOnly": "node scripts/verify-release.js"
   },
   "keywords": [
     "ase",

package/playbooks/promote-slice/PLAYBOOK.md

@@ -107,6 +107,25 @@ depends_on:
 승인 후에 발견된 것은 **새 리비전**이지 승인 취소가 아니다. 되돌리는 비용이 승인을 미루게 만들면,
 게이트는 품질 장치가 아니라 지연 장치가 된다.
 
+## 문서를 물리는 법 — `spec_retire`
+
+승인이 권한을 주는 행위라면 폐기는 거두는 행위다. 그래서 기본 문턱이 낮다 — 잘못 만든 초안을
+치우는 데 대역외 열쇠를 요구하면 일상 작업이 막힌다. **다만 문턱은 행위의 이름이 아니라 결과의
+위험을 따른다.** 두 경우는 폐기가 곧 게이트 열기다:
+
+- **봉인된 문서.** 코드 게이트는 "대상 A-SPEC을 `depends_on`에 담은 approved T-SPEC"을 요구한다.
+  그 T-SPEC을 폐기하면 요구가 사라진다. 그래서 `approved_digest`를 가진 문서의 폐기는
+  `spec_approve`와 **같은** `HOLMES_APPROVAL`을 요구하며 fail-closed다.
+- **활성 문서가 의존하는 문서.** `approved` 자식이 하나라도 있으면 거부하고, 문면이 그 자식을
+  id로 지목한다. 그 사슬은 지금 무언가를 지탱하고 있다.
+
+사유는 `retired_reason`에 남는다 — 비어 있으면 적지 않고, `superseded_by`가 이미 답이면 묻지
+않는다. 멱등이다: 이미 `outdated`인 문서를 다시 폐기하면 아무것도 쓰지 않는다. 두 번째 호출이
+첫 번째의 사유를 덮어쓰면 기록이 아니라 낙서다.
+
+> `outdated`는 `SPEC_STATUSES`에 처음부터 있었지만 이를 쓰는 코드가 0곳, 그 상태인 문서도
+> 0건이었다(실측 2026-08-21). 도달할 수 없는 상태는 선언이 아니라 장식이다.
+
 ## 흔한 오해
 
 | 오해 | 사실 |
@@ -116,6 +135,7 @@ depends_on:
 | "A-SPEC을 승인했으니 코드를 쓸 수 있다" | 테스트는 그렇다. 코드는 T-SPEC이 남았다 |
 | "T-SPEC 승인했는데 막힌다 = 게이트 버그" | `depends_on` 누락. 메시지가 동일해서 구별되지 않는다 |
 | "일단 승인하고 검증은 나중에" | 통과한 채 깨진 그래프가 남는다. 4단계 참조 |
+| "폐기는 `status: outdated`로 손편집한다" | `spec_retire(id, reason)`이 유일한 경로다. 봉인된 문서는 승인 열쇠를 요구하고, approved 의존자가 있으면 거부한다 |
 | "`missing`이 'approved A-SPEC'이니 A-SPEC을 승인하면 된다" | `AUTHOR_TSPEC`이면 아무거나 하나, `WRITE_TEST`면 대상 그것. 같은 문자열이 두 가지를 뜻한다 |
 
 ## 검증