@holmes-lab/holmes-kit 0.13.0 → 0.15.0

package/dist/holmes/spec/compat-impact.js

@@ -0,0 +1,140 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CELL_VERDICTS = exports.OS_CELLS = exports.HARNESS_CELLS = void 0;
+exports.checkCompatDeclared = checkCompatDeclared;
+/**
+ * REQ-565's enforcement device: the obligation to declare HARNESS (claude/codex/agy) and OS
+ * (windows/mac/linux) impact lives on the ACT of approval — the exact shape ADR-013 gave
+ * `breaking_change`, and for the same measured reason (a static `requiredFields` predicate turned
+ * 38 already-approved specs into ART-3 violations and bricked the harness; act-time converges
+ * instead: any spec that changes re-approves and acquires the fields, a spec that never changes
+ * can introduce no new incompatibility).
+ *
+ * WHY a gate and not a habit, measured twice in one day: an observability design came out
+ * Claude-biased (Stop hook + transcript_path is a Claude-only channel — the owner caught it), and
+ * the Stop hook's own header records that voluntarily-invoked discipline fired 0/143 times. Memory
+ * is rationale storage; control is a gate.
+ *
+ * WHAT THIS DOES NOT DO: verify the declarations are TRUE. Truth belongs to the layers that measure
+ * it — adapter parity (A-SPEC-336~338), doctor's wiring checks, on-device E2E. This gate makes
+ * skipping the thought impossible and makes a false declaration an auditable record.
+ */
+exports.HARNESS_CELLS = ['claude', 'codex', 'agy'];
+exports.OS_CELLS = ['windows', 'mac', 'linux'];
+exports.CELL_VERDICTS = ['supported', 'unavailable', 'n-a'];
+/** Directory-or-file prefixes that ARE the harness surface. A trailing '/' is a directory boundary;
+ * without it the rule names a file stem (`cli/init` catches `cli/init.ts`), and the boundary test
+ * below keeps `hooks-util.ts` from matching `hooks/`. */
+const HARNESS_SURFACES = [
+    'src/holmes/hooks/',
+    'src/holmes/cli/init',
+    'src/holmes/cli/agents',
+    'src/holmes/cli/interactive-prompt',
+    'src/holmes/mcp/server',
+];
+/** Conservative OS-sensitivity signals — content properties, not directories. Grown by measurement,
+ * never by guess (the goal records this as an explicitly open list). */
+const OS_SIGNALS = ['process.platform', "'win32'", '"win32"', 'spawn(', 'spawnSync(', 'execFileSync(', '.ps1'];
+const FORMAT_HINT = (field, cells) => `${field} 형식: 'none: <실이유>' 또는 3셀 매핑 { ${cells.map((c) => `${c}: '<supported|unavailable|n-a>: <근거>'`).join(', ')} }`;
+/** A reason that says nothing is not a reason: empty, or still carrying the scaffold's TODO/TBD. */
+const emptyReason = (reason) => reason.trim() === '' || /\bTODO\b|\bTBD\b/i.test(reason);
+/**
+ * Validate one axis' declaration. Returns the refusal (naming the field) or the parsed shape:
+ * `none` (an irrelevance claim — cross-checkable) or `cells` (the axis was faced — exempt).
+ */
+function parseAxis(field, raw, cells) {
+    const err = (why) => ({ kind: 'error', message: `${field} ${why} — ${FORMAT_HINT(field, cells)}` });
+    if (raw === undefined || raw === null)
+        return err('선언이 없습니다 (REQ-565: 호환 고려는 봉인 의무)');
+    if (typeof raw === 'string') {
+        const i = raw.indexOf(':');
+        const grade = (i === -1 ? raw : raw.slice(0, i)).trim();
+        const reason = i === -1 ? '' : raw.slice(i + 1).trim();
+        if (grade !== 'none')
+            return err(`알 수 없는 문자열 선언 '${grade}'`);
+        if (emptyReason(reason))
+            return err('의 none 사유가 비었거나 placeholder(TODO/TBD)입니다');
+        return { kind: 'none' };
+    }
+    if (typeof raw === 'object' && !Array.isArray(raw)) {
+        const m = raw;
+        const keys = Object.keys(m);
+        for (const c of cells)
+            if (!(c in m))
+                return err(`매핑에 '${c}' 셀이 없습니다 (3셀 전부 필수)`);
+        for (const k of keys)
+            if (!cells.includes(k))
+                return err(`매핑에 알 수 없는 셀 '${k}'`);
+        for (const c of cells) {
+            const v = m[c];
+            if (typeof v !== 'string')
+                return err(`의 '${c}' 셀이 문자열이 아닙니다`);
+            const i = v.indexOf(':');
+            const verdict = (i === -1 ? v : v.slice(0, i)).trim();
+            const reason = i === -1 ? '' : v.slice(i + 1).trim();
+            if (!exports.CELL_VERDICTS.includes(verdict)) {
+                return err(`의 '${c}' 셀 어휘 '${verdict}' 는 supported|unavailable|n-a 가 아닙니다`);
+            }
+            if (emptyReason(reason))
+                return err(`의 '${c}' 셀 근거가 비었거나 placeholder 입니다`);
+        }
+        return { kind: 'cells' };
+    }
+    return err('의 형태가 문자열도 매핑도 아닙니다');
+}
+/** `src/…` path tokens out of the Files to Touch section — backticks, bullets and commas tolerated.
+ * Backslashes normalize to `/` FIRST (adversarial round-1): a Windows author legitimately writes
+ * `src\holmes\hooks\stop.ts`, and un-normalized it walked straight past the surface prefixes —
+ * an OS-compat gate defeated by an OS path convention would be its own counterexample. */
+function filesToTouch(spec) {
+    const body = (spec.sections?.['Files to Touch'] ?? '')
+        .replace(/\\/g, '/')
+        .replace(/\/{2,}/g, '/'); // round-2: `src\\holmes` normalized to `src//holmes` and slid past the prefix
+    const out = [];
+    for (const m of body.matchAll(/src\/[\w./-]+/g))
+        out.push(m[0]);
+    return [...new Set(out)];
+}
+function checkCompatDeclared(spec, opts) {
+    if (spec.type !== 'A-SPEC')
+        return null;
+    const fm = (spec.frontmatter ?? {});
+    const harness = parseAxis('harness_impact', fm.harness_impact, exports.HARNESS_CELLS);
+    if (harness.kind === 'error')
+        return harness.message;
+    const os = parseAxis('os_impact', fm.os_impact, exports.OS_CELLS);
+    if (os.kind === 'error')
+        return os.message;
+    // Cross-checks apply ONLY to `none` — a 3-cell mapping already faced the axis, and re-litigating
+    // it here would punish exactly the declaration this gate exists to elicit (C1's lesson is that a
+    // DECLARATION must not be the only wall; an irrelevance CLAIM is what the machine can contradict).
+    const ftt = filesToTouch(spec);
+    if (harness.kind === 'none') {
+        for (const p of ftt) {
+            const hit = HARNESS_SURFACES.find((s) => (s.endsWith('/') ? p.startsWith(s) : p === s || p.startsWith(`${s}.`) || p.startsWith(`${s}/`)));
+            if (hit) {
+                return `harness_impact 는 none 인데 Files to Touch 의 '${p}' 는 하네스 표면(${hit})입니다 — 모순. 3셀 매핑으로 각 하네스의 영향을 기술하십시오.`;
+            }
+        }
+    }
+    if (os.kind === 'none' && opts?.readFile) {
+        for (const p of ftt) {
+            // round-2: an injected reader that THROWS (permissions, FIFO, anything) must degrade to
+            // "unreadable = skip", never crash the approval act — this check is a gate, not a hostage.
+            let text;
+            try {
+                text = opts.readFile(p);
+            }
+            catch {
+                text = null;
+            }
+            if (text === null || text === undefined)
+                continue; // a file that does not exist yet has no character
+            const sig = OS_SIGNALS.find((s) => text.includes(s));
+            if (sig) {
+                return `os_impact 는 none 인데 '${p}' 의 내용이 OS 신호 '${sig}' 를 담고 있습니다 — 모순. 3셀 매핑으로 각 OS 의 영향을 기술하십시오.`;
+            }
+        }
+    }
+    return null;
+}

package/dist/holmes/spec/spec-types.js

@@ -76,7 +76,9 @@ exports.SPEC_TYPES = {
         // blocked every turn, because all 38 governed A-SPECs are already approved. The duty belongs to
         // the ACT of approval (see spec/breaking-change.ts); this line exists so the field is visible
         // where someone looks up "what fields does an A-SPEC have", instead of hiding in a check.
-        stubOnlyFields: ['breaking_change'],
+        // @implements A-SPEC-565.1 — same shape, same reason: the compat duty (REQ-565) lives on the
+        // act of approval (spec/compat-impact.ts), and these lines exist for the reader, not the check.
+        stubOnlyFields: ['breaking_change', 'harness_impact', 'os_impact'],
         requiredSections: ['Objective', 'Inputs / Outputs', 'Behavior', 'Test Points', 'Files to Touch', 'Done When'],
     },
     'C-SPEC': {

package/package.json

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