@holmes-lab/holmes-kit 0.7.1 → 0.9.0

package/dist/holmes/review/test-outcomes.js

@@ -0,0 +1,108 @@
+"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.OUTCOMES_FILE = void 0;
+exports.appendOutcomes = appendOutcomes;
+exports.readOutcomes = readOutcomes;
+exports.buildOutcomeRecords = buildOutcomeRecords;
+exports.groupOutcomesByAspec = groupOutcomesByAspec;
+// @implements A-SPEC-534.3
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+exports.OUTCOMES_FILE = path.join('.ax', 'ledger', 'test-outcomes.jsonl');
+/** Append outcome records as JSONL lines. Fail-open (recording must never break a run). */
+function appendOutcomes(root, records) {
+    try {
+        const file = path.join(root, exports.OUTCOMES_FILE);
+        fs.mkdirSync(path.dirname(file), { recursive: true });
+        fs.appendFileSync(file, records.map((r) => `${JSON.stringify(r)}\n`).join(''));
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Read every outcome record; missing file → [], broken lines skipped (same convention as the other ledgers). */
+function readOutcomes(root) {
+    let text;
+    try {
+        text = fs.readFileSync(path.join(root, exports.OUTCOMES_FILE), 'utf8');
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const line of text.split('\n')) {
+        const s = line.trim();
+        if (!s)
+            continue;
+        try {
+            const r = JSON.parse(s);
+            if (r && typeof r === 'object' && typeof r.aspec === 'string' && typeof r.outcome === 'string'
+                && typeof r.ts === 'string' && typeof r.head === 'string') {
+                out.push(r);
+            }
+        }
+        catch { /* skip a corrupt line rather than fail the whole read */ }
+    }
+    return out;
+}
+/**
+ * @implements A-SPEC-534.5
+ * Expand per-file outcomes into per-A-SPEC records via the anchor map, stamping each with the run's
+ * head and ts. A file with no anchor (or an empty anchor list) contributes nothing — an outcome that
+ * cannot be attributed to an A-SPEC is not evidence about one. Pure.
+ */
+function buildOutcomeRecords(outcomeByFile, anchors, head, ts) {
+    const out = [];
+    for (const [file, outcome] of Object.entries(outcomeByFile)) {
+        for (const aspec of anchors[file] ?? [])
+            out.push({ aspec, outcome, ts, head });
+    }
+    return out;
+}
+/**
+ * Group outcomes by A-SPEC, keeping only records stamped with the given baseline `head` — a stale
+ * record from another commit cannot vouch for the current work (the isFresh discipline). Pure.
+ */
+function groupOutcomesByAspec(records, head) {
+    const out = {};
+    for (const r of records) {
+        if (r.head !== head)
+            continue;
+        (out[r.aspec] ??= []).push({ outcome: r.outcome, ts: r.ts });
+    }
+    return out;
+}

package/dist/holmes/review/test-runner.d.ts

@@ -32,6 +32,12 @@ export interface TestRunResult {
     unsupported?: string[];
     /** Which adapters actually ran, for evidence provenance. */
     ranWith?: string[];
+    /**
+     * @implements A-SPEC-534.5
+     * Per-file RED-first outcome (jest only). red-assertion | red-error | green, for the outcome ledger
+     * ART-8 reads. Other ecosystems do not classify outcomes yet, so they contribute nothing here.
+     */
+    outcomeByFile?: Record<string, TestOutcome>;
 }
 export type Ecosystem = 'jest' | 'pytest' | 'go' | 'rust' | 'java' | 'dotnet';
 /** Ecosystem of a test file, by extension/convention. `null` when no runner adapter exists for it. */
@@ -51,6 +57,24 @@ export declare function parseGoTestJson(out: string): Record<string, number>;
  * fabrications cannot produce evidence. Returns {} for unparseable output (caller falls back).
  */
 export declare function parseExecutedCounts(stdout: string, cwd: string): Record<string, number>;
+/**
+ * Per-file test outcome for RED-first evidence (REQ-534). `red-assertion` is a REAL red — a case ran
+ * and its assertion failed; `red-error` is a file that could not run its cases (load/collection/import
+ * error), which ART-8 (534.2) must NOT accept as a valid RED; `green` ran and all assertions passed.
+ */
+export type TestOutcome = 'red-assertion' | 'red-error' | 'green';
+/**
+ * @implements A-SPEC-534.1
+ * Classify each jest-executed file into red-assertion | red-error | green from `jest --json` stdout.
+ * Pure; unparseable/empty input → {} (same fail-soft convention as parseExecutedCounts).
+ *
+ * A failed assertion anywhere in a file wins (`red-assertion`) — that is a real red. A file that ran
+ * NO assertions but errored (testExecError, or status 'failed' with an empty assertion list — a
+ * load/collection/import failure) is `red-error`, which ART-8 must not accept as a valid RED. A file
+ * that executed ≥1 assertion with none failing is `green`. A file that only pended/skipped carries no
+ * evidence and is omitted entirely.
+ */
+export declare function classifyJestOutcomes(stdout: string, cwd: string): Record<string, TestOutcome>;
 /**
  * Parse pytest's built-in JUnit XML into per-file EXECUTED case counts — the pytest analogue of
  * parseExecutedCounts. `--junit-xml` ships with pytest core, so this needs no plugin, and it is the
@@ -75,6 +99,12 @@ export declare function parseJUnitXmlCounts(xml: string, ext?: string): Record<s
  * there), and a repo with no local jest could never yield meaningful suite evidence anyway.
  */
 export declare function jestEntry(cwd: string): string | null;
+/**
+ * @implements A-SPEC-534.8
+ * Run specific jest files and return only their RED-first outcomes — the runner `test_run --mutate`
+ * injects into runKillsOnFile. Scoped, jest only (the classifier is jest-only), fail-soft to {}.
+ */
+export declare function runJestOutcomes(files: string[], cwd: string): Record<string, TestOutcome>;
 /** Run the pytest half of a plan, taking execution evidence from pytest's built-in JUnit XML. */
 export declare function runPytest(files: string[], mode: TestRunPlan['mode'], cwd: string): {
     passed: boolean;

package/dist/holmes/review/test-runner.js

@@ -37,8 +37,10 @@ exports.planTestRun = planTestRun;
 exports.ecosystemOf = ecosystemOf;
 exports.parseGoTestJson = parseGoTestJson;
 exports.parseExecutedCounts = parseExecutedCounts;
+exports.classifyJestOutcomes = classifyJestOutcomes;
 exports.parseJUnitXmlCounts = parseJUnitXmlCounts;
 exports.jestEntry = jestEntry;
+exports.runJestOutcomes = runJestOutcomes;
 exports.runPytest = runPytest;
 exports.parseCargoTest = parseCargoTest;
 exports.runCargo = runCargo;
@@ -153,9 +155,57 @@ function parseExecutedCounts(stdout, cwd) {
         const abs = tr.name ?? tr.testFilePath ?? '';
         if (!abs)
             continue;
-        const rel = abs.startsWith(cwd) ? abs.slice(cwd.length).replace(/^[/\\]/, '') : abs;
         const ran = (tr.assertionResults ?? []).filter((a) => a.status === 'passed' || a.status === 'failed').length;
-        out[rel.split('\\').join('/')] = ran;
+        out[relTestPath(abs, cwd)] = ran;
+    }
+    return out;
+}
+/** Repo-relative, forward-slashed key for a jest test-file path — shared by the parsers below. */
+function relTestPath(abs, cwd) {
+    const rel = abs.startsWith(cwd) ? abs.slice(cwd.length).replace(/^[/\\]/, '') : abs;
+    return rel.split('\\').join('/');
+}
+/**
+ * @implements A-SPEC-534.1
+ * Classify each jest-executed file into red-assertion | red-error | green from `jest --json` stdout.
+ * Pure; unparseable/empty input → {} (same fail-soft convention as parseExecutedCounts).
+ *
+ * A failed assertion anywhere in a file wins (`red-assertion`) — that is a real red. A file that ran
+ * NO assertions but errored (testExecError, or status 'failed' with an empty assertion list — a
+ * load/collection/import failure) is `red-error`, which ART-8 must not accept as a valid RED. A file
+ * that executed ≥1 assertion with none failing is `green`. A file that only pended/skipped carries no
+ * evidence and is omitted entirely.
+ */
+function classifyJestOutcomes(stdout, cwd) {
+    const start = stdout.indexOf('{');
+    if (start < 0)
+        return {};
+    let data;
+    try {
+        data = JSON.parse(stdout.slice(start));
+    }
+    catch {
+        return {};
+    }
+    const out = {};
+    for (const tr of data?.testResults ?? []) {
+        const abs = tr.name ?? tr.testFilePath ?? '';
+        if (!abs)
+            continue;
+        const rel = relTestPath(abs, cwd);
+        const assertions = tr.assertionResults ?? [];
+        if (assertions.some((a) => a.status === 'failed')) {
+            out[rel] = 'red-assertion';
+            continue;
+        }
+        const executed = assertions.filter((a) => a.status === 'passed' || a.status === 'failed').length;
+        const errored = !!tr.testExecError || tr.status === 'failed';
+        if (executed === 0) {
+            if (errored)
+                out[rel] = 'red-error'; // ran nothing AND failed → could not execute its cases
+            continue; // otherwise all pending/skipped → no evidence, omit
+        }
+        out[rel] = errored ? 'red-error' : 'green';
     }
     return out;
 }
@@ -248,14 +298,25 @@ function runJest(files, mode, cwd) {
         // @implements A-SPEC-515.1 — the green path says what happened instead of handing back the
         // whole `--json` document. `tailOf` wraps the result too, so an unexpectedly long summary is
         // still bounded: a cap that any one path can escape is not a cap.
-        return { passed: true, tail: tailOf(summarizeJestJson(out) ?? out), executed: parseExecutedCounts(out, cwd) };
+        return { passed: true, tail: tailOf(summarizeJestJson(out) ?? out), executed: parseExecutedCounts(out, cwd), outcomes: classifyJestOutcomes(out, cwd) };
     }
     catch (e) {
         const err = e;
-        // A failing suite still emits --json on stdout, so execution evidence survives a red run.
-        return { passed: false, tail: tailOf(`${err.stdout ?? ''}\n${err.stderr ?? err.message ?? ''}`), executed: parseExecutedCounts(err.stdout ?? '', cwd) };
+        // A failing suite still emits --json on stdout, so execution evidence — and the red/green outcome
+        // classification (A-SPEC-534.1) — survives a red run.
+        return { passed: false, tail: tailOf(`${err.stdout ?? ''}\n${err.stderr ?? err.message ?? ''}`), executed: parseExecutedCounts(err.stdout ?? '', cwd), outcomes: classifyJestOutcomes(err.stdout ?? '', cwd) };
     }
 }
+/**
+ * @implements A-SPEC-534.8
+ * Run specific jest files and return only their RED-first outcomes — the runner `test_run --mutate`
+ * injects into runKillsOnFile. Scoped, jest only (the classifier is jest-only), fail-soft to {}.
+ */
+function runJestOutcomes(files, cwd) {
+    if (files.length === 0)
+        return {};
+    return runJest(files, 'scoped', cwd).outcomes;
+}
 /** Run the pytest half of a plan, taking execution evidence from pytest's built-in JUnit XML. */
 // @implements A-SPEC-502.1 — exported for the wiring test (a fake venv python capturing argv).
 function runPytest(files, mode, cwd) {
@@ -592,12 +653,16 @@ function runTestScope(scope, cwd) {
         let passed = true;
         const tails = [];
         const executedByFile = {};
+        const outcomeByFile = {}; // @implements A-SPEC-534.5 — jest only
         for (const eco of [...groups.keys()].sort()) {
             const r = runners[eco](groups.get(eco), plan.mode, cwd);
             ran.push(eco);
             passed = passed && r.passed;
             tails.push(`[${eco}] ${r.tail}`);
             Object.assign(executedByFile, r.executed);
+            const adapterOutcomes = r.outcomes;
+            if (adapterOutcomes)
+                Object.assign(outcomeByFile, adapterOutcomes);
             // @implements A-SPEC-137.1 — an adapter whose toolchain is absent reports its files as
             // unsupported; merge them so a scope that could not run them never reads as fully covered.
             const adapterUnsupported = r.unsupported;
@@ -613,6 +678,7 @@ function runTestScope(scope, cwd) {
         return {
             tier: scope.tier, mode: plan.mode, ranFiles: plan.testFiles, passed, skipped: false,
             tail: tails.join('\n'), executedByFile, ranWith: ran,
+            ...(Object.keys(outcomeByFile).length ? { outcomeByFile } : {}),
             ...(unsupported.length ? { unsupported } : {}),
         };
     }

package/dist/holmes/spec/kills.d.ts

@@ -0,0 +1,14 @@
+/**
+ * A discriminating-power mutation (REQ-534 C-layer): a named change to production source that a
+ * covering test SHOULD turn red. Minimal DSL — a literal `where` replaced by `mutate`. `test_run
+ * --mutate` applies each and confirms the covering cases go red-assertion; a mutation that kills
+ * nothing is a coverage gap. Deliberately small; widen the DSL only when a real case needs it.
+ */
+export interface Mutation {
+    where: string;
+    mutate: string;
+}
+/** Extract well-formed {where,mutate} entries from `kills`. Lenient: anything else yields []. Pure. */
+export declare function parseKills(frontmatter: Record<string, unknown>): Mutation[];
+/** Replace the FIRST occurrence of `where` with `mutate`. null when `where` is empty or absent. Pure. */
+export declare function applyMutation(source: string, m: Mutation): string | null;

package/dist/holmes/spec/kills.js

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseKills = parseKills;
+exports.applyMutation = applyMutation;
+/** Extract well-formed {where,mutate} entries from `kills`. Lenient: anything else yields []. Pure. */
+function parseKills(frontmatter) {
+    const raw = frontmatter.kills;
+    if (!Array.isArray(raw))
+        return [];
+    const out = [];
+    for (const item of raw) {
+        if (item && typeof item === 'object'
+            && typeof item.where === 'string'
+            && typeof item.mutate === 'string') {
+            out.push({ where: item.where, mutate: item.mutate });
+        }
+    }
+    return out;
+}
+/** Replace the FIRST occurrence of `where` with `mutate`. null when `where` is empty or absent. Pure. */
+function applyMutation(source, m) {
+    if (!m.where)
+        return null;
+    const i = source.indexOf(m.where);
+    if (i < 0)
+        return null;
+    return source.slice(0, i) + m.mutate + source.slice(i + m.where.length);
+}

package/dist/holmes/spec/spec-store.d.ts

@@ -59,6 +59,15 @@ export interface SpecStore {
  * exist" while looking straight at the file. The verdict stays; the silence does not.
  */
 export declare function unreadableSpecFiles(specsDir: string): string[];
+/**
+ * @implements A-SPEC-536.1
+ * The "not found" reason, enriched when the store is silently dropping unparseable files. BUG-1's
+ * silent-loss bit at the tool surface: a spec whose YAML frontmatter is broken is dropped by list()/
+ * read() and every handler answered a bare "spec <id> not found", hiding that the file EXISTS but
+ * cannot be parsed. When `unreadable` is empty the string is byte-identical to the legacy message
+ * (no regression); otherwise it names the skipped files and the usual cause.
+ */
+export declare function notFoundReason(id: string, unreadable: readonly string[]): string;
 export declare class LocalMarkdownRepository implements SpecStore {
     private readonly root;
     constructor(root: string);

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

@@ -35,6 +35,7 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.MemorySpecStore = exports.LocalMarkdownRepository = exports.TargetPathOccupiedError = exports.SpecVersionConflictError = void 0;
 exports.unreadableSpecFiles = unreadableSpecFiles;
+exports.notFoundReason = notFoundReason;
 const node_crypto_1 = require("node:crypto");
 const fs = __importStar(require("node:fs"));
 const path = __importStar(require("node:path"));
@@ -118,6 +119,22 @@ function unreadableSpecFiles(specsDir) {
     walk(specsDir);
     return out.sort();
 }
+/**
+ * @implements A-SPEC-536.1
+ * The "not found" reason, enriched when the store is silently dropping unparseable files. BUG-1's
+ * silent-loss bit at the tool surface: a spec whose YAML frontmatter is broken is dropped by list()/
+ * read() and every handler answered a bare "spec <id> not found", hiding that the file EXISTS but
+ * cannot be parsed. When `unreadable` is empty the string is byte-identical to the legacy message
+ * (no regression); otherwise it names the skipped files and the usual cause.
+ */
+function notFoundReason(id, unreadable) {
+    const base = `spec ${id} not found`;
+    if (unreadable.length === 0)
+        return base;
+    return `${base} — but ${unreadable.length} spec file(s) failed to parse and were skipped `
+        + `(a malformed one may be this spec): ${unreadable.join(', ')}. `
+        + `Check the YAML frontmatter (an unquoted ':' in a value is the usual cause).`;
+}
 class LocalMarkdownRepository {
     root;
     constructor(root) {

package/dist/holmes/spec/validator.js

@@ -257,6 +257,24 @@ function validateSpec(spec, resolve) {
         if (!def.parents.includes(parent.type))
             err('wrong-parent-type', `parent ${pid} is ${parent.type}, expected ${def.parents.join('|')}`);
     }
+    // @implements A-SPEC-534.7 — optional `kills` (discriminating-power mutations). Absent → no check
+    // (every existing T-SPEC is unaffected); present → it must be an array of {string where, string
+    // mutate}. A malformed shape is always an error, independent of status.
+    if (spec.type === 'T-SPEC' && spec.frontmatter.kills != null) {
+        const raw = spec.frontmatter.kills;
+        if (!Array.isArray(raw)) {
+            err('kills-shape', 'kills must be an array of {where, mutate}');
+        }
+        else {
+            raw.forEach((item, i) => {
+                const ok = !!item && typeof item === 'object'
+                    && typeof item.where === 'string'
+                    && typeof item.mutate === 'string';
+                if (!ok)
+                    err('kills-shape', `kills[${i}] must be {where: string, mutate: string}`);
+            });
+        }
+    }
     // gate: T-SPEC 4-quadrant coverage on approve attempt
     if (spec.type === 'T-SPEC' && spec.status === 'approved') {
         const cov = (spec.frontmatter.coverage ?? {});

package/dist/holmes/update/update-notice.d.ts

@@ -0,0 +1,28 @@
+export declare const NPM_URL = "https://www.npmjs.com/package/@holmes-lab/holmes-kit";
+/** How this install was wired — decides how (or whether) to phrase the update command. */
+export type InstallMode = 'global-npx' | 'local-dep' | 'source';
+export interface UpdateCache {
+    latest: string;
+    checkedAt: number;
+}
+export interface BannerInput {
+    current: string;
+    cached: UpdateCache | null;
+    mode: InstallMode;
+    npmUrl: string;
+}
+/** -1 if a<b, 0 if equal, 1 if a>b — NUMERIC per field, so 0.9.0 < 0.10.0 (a string compare fails). */
+export declare function compareSemver(a: string, b: string): -1 | 0 | 1;
+/** The cache file, read only — no network, no write. Anything unreadable/malformed/mis-shaped → null. */
+export declare function readCache(home: string, readFile: (p: string) => string): UpdateCache | null;
+/** The one-line update guidance, branched by install mode. `source` returns null (git updates it). */
+export declare function installModeGuide(mode: InstallMode, latest: string, current: string): string | null;
+/**
+ * The banner: always an English intro line (version + governance rule + npm page). If the cache
+ * knows a newer version AND the install mode has an update path, a second guidance line follows.
+ */
+export declare function composeBanner(input: BannerInput): string;
+/** Whether a network refresh is allowed at all. Opt-out via HOLMES_NO_UPDATE_CHECK or CI. */
+export declare function shouldQuery(env: NodeJS.ProcessEnv): boolean;
+/** Whether the cache is old enough to refresh. A missing cache is stale. */
+export declare function cacheIsStale(cached: UpdateCache | null, now: number, ttlMs?: number): boolean;

package/dist/holmes/update/update-notice.js

@@ -0,0 +1,131 @@
+"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.NPM_URL = void 0;
+exports.compareSemver = compareSemver;
+exports.readCache = readCache;
+exports.installModeGuide = installModeGuide;
+exports.composeBanner = composeBanner;
+exports.shouldQuery = shouldQuery;
+exports.cacheIsStale = cacheIsStale;
+// @implements A-SPEC-531.1
+// The session banner and update notice, as a PURE core. Every side channel — the filesystem, the
+// clock, the environment — is a parameter, so the whole module verifies offline. The delivery
+// points (SessionStart hook, MCP instructions, init wiring) consume this in A-SPEC-531.2.
+//
+// No new dependency: semver comparison is a three-integer compare (our versions are plain
+// major.minor.patch — a full semver library would carry prerelease/build code this never runs), and
+// the registry query (A-SPEC-531.2) uses Node's built-in https.
+const path = __importStar(require("node:path"));
+exports.NPM_URL = 'https://www.npmjs.com/package/@holmes-lab/holmes-kit';
+const DEFAULT_TTL_MS = 24 * 3600_000;
+/** Parse `major.minor.patch` to a 3-tuple; a non-numeric field becomes 0 (never throws). */
+function triple(v) {
+    const parts = String(v).split('.');
+    const n = (i) => { const x = Number.parseInt(parts[i] ?? '', 10); return Number.isFinite(x) ? x : 0; };
+    return [n(0), n(1), n(2)];
+}
+/** -1 if a<b, 0 if equal, 1 if a>b — NUMERIC per field, so 0.9.0 < 0.10.0 (a string compare fails). */
+function compareSemver(a, b) {
+    const x = triple(a);
+    const y = triple(b);
+    for (let i = 0; i < 3; i++) {
+        if (x[i] < y[i])
+            return -1;
+        if (x[i] > y[i])
+            return 1;
+    }
+    return 0;
+}
+/** The cache file, read only — no network, no write. Anything unreadable/malformed/mis-shaped → null. */
+function readCache(home, readFile) {
+    let raw;
+    try {
+        raw = readFile(path.join(home, '.holmes', 'update-check.json'));
+    }
+    catch {
+        return null;
+    }
+    if (!raw)
+        return null;
+    try {
+        const v = JSON.parse(raw);
+        if (v && typeof v === 'object'
+            && typeof v.latest === 'string'
+            && typeof v.checkedAt === 'number') {
+            return { latest: v.latest, checkedAt: v.checkedAt };
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+/** The one-line update guidance, branched by install mode. `source` returns null (git updates it). */
+function installModeGuide(mode, latest, current) {
+    const head = `[Holmes-Kit] Update available: ${latest} (current ${current}).`;
+    switch (mode) {
+        case 'global-npx':
+            return `${head} Run: npm i -g @holmes-lab/holmes-kit@latest, then holmes-kit init --force (re-pins wiring; requires HOLMES_APPROVAL).`;
+        case 'local-dep':
+            return `${head} Run: npm i -D @holmes-lab/holmes-kit@latest`;
+        case 'source':
+            return null;
+    }
+}
+/**
+ * The banner: always an English intro line (version + governance rule + npm page). If the cache
+ * knows a newer version AND the install mode has an update path, a second guidance line follows.
+ */
+function composeBanner(input) {
+    const intro = `[Holmes-Kit] This session is governed by Holmes-Kit v${input.current} (No Spec, No Code) — ${input.npmUrl}`;
+    const latest = input.cached?.latest;
+    if (latest && compareSemver(latest, input.current) > 0) {
+        const guide = installModeGuide(input.mode, latest, input.current);
+        if (guide)
+            return `${intro}\n${guide}`;
+    }
+    return intro;
+}
+/** Whether a network refresh is allowed at all. Opt-out via HOLMES_NO_UPDATE_CHECK or CI. */
+function shouldQuery(env) {
+    return !env.HOLMES_NO_UPDATE_CHECK && !env.CI;
+}
+/** Whether the cache is old enough to refresh. A missing cache is stale. */
+function cacheIsStale(cached, now, ttlMs = DEFAULT_TTL_MS) {
+    if (!cached)
+        return true;
+    return now - cached.checkedAt > ttlMs;
+}

package/package.json

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

package/playbooks/tdd-slice/PLAYBOOK.md

@@ -0,0 +1,82 @@
+---
+name: holmes-tdd-slice
+description: >-
+  Use when writing or changing code under a Holmes-Kit gate — the built-in TDD discipline. Reach for
+  it when the gate says "Approved specification required before code modification", or when the Stop
+  hook prints an "ART-8 RED-first" observation. Restates the Iron Law and Red-Green-Refactor in holmes
+  terms and tags each rule with the article that enforces it (ART-1 no-spec-no-code, ART-4 coverage
+  honesty, ART-8 RED-first evidence), so you know which rules the gate checks and which are
+  honor-system. Key trap: a RED must be a red-assertion, not a red-error.
+---
+
+# tdd-slice
+
+테스트를 먼저 쓰고, **실패를 눈으로 본 뒤**, 통과시키는 최소 코드를 쓴다. 이것은 권고가 아니다 —
+holmes-kit은 이 규율의 상당 부분을 **헌법 조항으로 집행**한다. 그래서 이 스킬의 각 규칙 옆에는
+그것을 강제하는 조항이 붙어 있다: `[ART-N]`은 게이트가 막는 것, `[명예제]`는 네 판단에 맡기는 것.
+합리화로 빠져나갈 수 있는 규칙과 없는 규칙을 구별하라 — 없는 것은 정말 없다.
+
+## Iron Law
+
+**승인된 T-SPEC이 코드보다 먼저 있어야 하고, 그 커버 테스트가 코드 전에 RED로 관측돼야 한다.**
+
+- `[ART-1]` No Spec, No Code — 소스는 승인된 A-SPEC(+그것을 depends_on 하는 승인된 T-SPEC) 아래서만
+  바뀐다. 게이트가 코드 쓰기를 막는다. `promote-slice`가 그 승격을 다룬다.
+- `[ART-8]` 테스트-우선은 가정이 아니라 **관측**된다 — 소스가 바뀐 A-SPEC은 원장에
+  `red-assertion`(코드 전) → `green`(코드 후) 시퀀스를 남겨야 한다. 코드 뒤에 써서 즉시 통과한
+  테스트는 실패를 관측한 적이 없으니 아무것도 증명하지 못한다. 기본은 `track`(관측), 오너가
+  실측 후 `strict`(차단)로 올린다(config `redFirstEvidence`).
+
+## Red-Green-Refactor (holmes 판)
+
+1. **RED** — 커버 케이스를 `test_run`으로 돌려 **실패를 본다**. 이 실패는 `red-assertion`(케이스가
+   실행되고 어서션이 실패)이어야 한다.
+2. **GREEN** — 통과시키는 **최소** 코드를 쓴다. `test_run`이 `green`을 기록한다.
+3. **REFACTOR** — green을 유지한 채 정리한다. 원장은 그대로다.
+
+`test_run`이 매 실행마다 커버 파일별 outcome을 분류(`red-assertion`/`red-error`/`green`)해 원장에
+남긴다 — 이것이 ART-8이 읽는 증거다.
+
+## RED은 red-assertion 이어야 한다 (가장 흔한 함정)
+
+`[ART-8]` **`red-error`는 유효 RED가 아니다.** 심볼 부재로 인한 컴파일 실패, 임포트 오류,
+수집(collection) 실패는 케이스가 **실행조차 못 된** 상태다 — 그것은 "실패를 올바른 이유로
+관측했다"가 아니다. 함수가 아직 없어 컴파일이 깨지면, **틀린 값을 반환하는 스텁**을 먼저 넣어
+어서션이 붉어지게(=`red-assertion`) 만든 뒤 구현하라. superpowers가 "fails *correctly*"라 부른 것을
+holmes는 기계적으로 판별한다: `red-error`로는 red→green 시퀀스가 성립하지 않는다.
+
+## 좋은 테스트의 규칙
+
+- `[ART-4]` 선언한 커버리지는 **실제 앵커된 테스트 케이스**로 뒷받침돼야 한다 — 산문이 아니다.
+  T-SPEC이 커버를 선언하면 그 A-SPEC을 `@implements`로 앵커한 테스트 파일에 실제 케이스가 있고
+  실행돼야 한다. 없으면 게이트가 막는다.
+- `[ART-4]` 앵커는 **파일당 첫 줄**에 둔다 — 스캐너가 파일당 첫 `@implements`만 잡는다. 기존
+  파일의 비-첫줄에 새 A-SPEC 앵커를 넣으면 ART-4에 안 보인다. 새 테스트는 새 파일로.
+- `[명예제]` mock이 아니라 **실제 동작**을 단언하라. mock의 호출 여부를 재는 테스트는 제품이 아니라
+  네 mock을 시험한다. holmes의 T-SPEC 4분면(normal/negative/corner/boundary)은 관측 가능한 동작을
+  요구한다.
+- `[명예제]` 테스트를 쓰기 전에 **그 테스트를 실패시킬 프로덕션 변경을 한 문장으로 말하라**. 말할
+  수 없다면 그 테스트는 무엇도 지키지 못한다. (C층 `kills:`가 이를 스펙 필드로 승격한다.)
+
+## 집행 요약
+
+| 규칙 | 집행 |
+|---|---|
+| 스펙 없이 코드 없음 | `[ART-1]` PreToolUse 게이트 |
+| 커버 테스트가 실재·실행 | `[ART-4]` Stop 헌법 |
+| 코드 전 red-assertion→green | `[ART-8]` Stop 헌법(track/strict) |
+| mock 아닌 실동작·판별력 | `[명예제]` (C층 `kills:`로 선택 검증) |
+
+## 절차
+
+1. `promote-slice`로 대상 A-SPEC과 그 T-SPEC을 승인한다(`[ART-1]` 게이트를 연다).
+2. 커버 테스트를 **먼저** 쓴다. 심볼이 없어 컴파일이 깨지면 틀린-값 스텁을 넣는다.
+3. `test_run` — **red-assertion**을 본다. `red-error`면 그건 아직 RED가 아니다; 스텁으로 고쳐라.
+4. 통과시키는 최소 코드를 쓴다.
+5. `test_run` — `green`. 원장에 red→green이 남는다(`[ART-8]` 증거).
+6. green 유지하며 refactor.
+
+## 검증
+
+`src/holmes/playbooks/tdd-slice.test.ts` — 이 스킬이 집행 태그(ART-1/4/8)와 red-assertion/red-error
+구별을 담고, 설치기가 이를 발견함을 고정한다. 상시 스위트 포함.