@holmes-lab/holmes-kit 0.1.0

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

@@ -0,0 +1,331 @@
+"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.MemorySpecStore = exports.LocalMarkdownRepository = exports.TargetPathOccupiedError = exports.SpecVersionConflictError = void 0;
+exports.unreadableSpecFiles = unreadableSpecFiles;
+const node_crypto_1 = require("node:crypto");
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const spec_parser_1 = require("./spec-parser");
+const spec_types_1 = require("./spec-types");
+// @implements A-SPEC-100.1
+/**
+ * Thrown when `expectedVersion` no longer matches what the store holds.
+ *
+ * @implements A-SPEC-151
+ * Optimistic concurrency, which REQ-018's deprecation note named as the surviving fragment of that
+ * requirement: "스펙 수준 낙관적 동시성은 ports SpecStore expectedVersion(ADR-001)으로 생존".
+ */
+class SpecVersionConflictError extends Error {
+}
+exports.SpecVersionConflictError = SpecVersionConflictError;
+/**
+ * @implements A-SPEC-188
+ * A write would land on a path occupied by a file that is NOT this spec's own current file —
+ * typically an unparseable human note or broken document that list()/read() cannot see. Thrown
+ * before any mutation; the occupant is a human's to look at, never the store's to replace.
+ */
+class TargetPathOccupiedError extends Error {
+    occupiedPath;
+    constructor(message, occupiedPath) {
+        super(message);
+        this.occupiedPath = occupiedPath;
+    }
+}
+exports.TargetPathOccupiedError = TargetPathOccupiedError;
+// Rejects values that are empty or would escape a single path segment (contains a path
+// separator or resolves to something other than itself via path.basename, which also
+// catches '..' and '.'). Throws rather than silently coercing so callers (e.g. spec_create)
+// surface a clean error instead of writing outside the store root.
+function assertSafePathSegment(value, label) {
+    if (!value || path.basename(value) !== value) {
+        throw new Error(`Invalid ${label}: "${value}" is not a safe path segment`);
+    }
+}
+/**
+ * @implements A-SPEC-176
+ * Markdown files under the spec tree that the parser cannot turn into a spec.
+ *
+ * `list()` drops these via `if (spec.id)`, which is the right call for a gate — an unparseable file
+ * cannot be treated as approved. But dropping them silently means a user reads "that spec does not
+ * exist" while looking straight at the file. The verdict stays; the silence does not.
+ */
+function unreadableSpecFiles(specsDir) {
+    const out = [];
+    const walk = (d) => {
+        let entries;
+        try {
+            entries = fs.readdirSync(d, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const e of entries) {
+            const p = path.join(d, e.name);
+            if (e.isDirectory()) {
+                walk(p);
+                continue;
+            }
+            if (!e.name.endsWith('.md'))
+                continue;
+            let ok = false;
+            try {
+                ok = (0, spec_parser_1.parseSpec)(fs.readFileSync(p, 'utf8')).id !== '';
+            }
+            catch {
+                ok = false;
+            }
+            if (!ok)
+                out.push(path.relative(specsDir, p).split(path.sep).join('/'));
+        }
+    };
+    walk(specsDir);
+    return out.sort();
+}
+class LocalMarkdownRepository {
+    root;
+    constructor(root) {
+        this.root = root;
+    }
+    /**
+     * @implements A-SPEC-169
+     * Where this store writes. Exposed so a handler can tell that the `root` it was given names a
+     * DIFFERENT project — measured 2026-08-08, a call with a temp root wrote into this repository
+     * instead, because the store is bound at start-up and the argument governed only the ledger.
+     */
+    get specsRoot() { return this.root; }
+    dirFor(spec) {
+        const base = path.join(this.root, spec_types_1.SPEC_TYPES[spec.type].folder);
+        if (spec.type !== 'H-SPEC')
+            return base;
+        // @implements A-SPEC-174
+        // A placeholder is not a classification. `req_type` is required, so `spec_create` stubs it, and
+        // using that stub as a path segment put a literal `02_h-spec/TODO/` directory in the user's
+        // repository (measured 2026-08-12). Unclassified H-SPECs sit directly under the type folder — a
+        // layout the repository already contains — and the relocation on a later `req_type` edit is the
+        // same one that already handles a change of classification.
+        const raw = spec.frontmatter.req_type;
+        if (raw == null || String(raw) === spec_types_1.FIELD_PLACEHOLDER)
+            return base;
+        const reqType = String(raw);
+        assertSafePathSegment(reqType, 'req_type');
+        return path.join(base, reqType);
+    }
+    /** Version of the STORED representation — the serialized document, so a status flip changes it. */
+    versionOf(text) {
+        return `sha256:${(0, node_crypto_1.createHash)('sha256').update(text, 'utf8').digest('hex')}`;
+    }
+    /**
+     * @implements A-SPEC-188
+     * The exact path a write of this spec would land on — PUBLIC so create-only callers can refuse
+     * when something already sits there. `list()` cannot answer that question: it drops files it
+     * cannot parse, and an unparseable document at the target path is precisely the one a create
+     * must not destroy (probed: a prose file at 01_req/REQ-777.md was silently overwritten by a
+     * guard that consulted list() alone — and the overwrite also emptied unreadableSpecFiles, so
+     * the doctor warning that would have surfaced the loss died with the document).
+     */
+    targetPathFor(spec) {
+        assertSafePathSegment(spec.id, 'spec id');
+        return path.join(this.dirFor(spec), `${spec.id}.md`);
+    }
+    /**
+     * @implements A-SPEC-188
+     * Writes are SERIALIZED per store instance. The expectedVersion check and the file write are
+     * separated by an `await this.list()` (the orphan sweep), so two concurrent write() calls could
+     * both pass the check before either wrote — a check-then-act hole round-3 review demonstrated.
+     * The server is single-process; a promise chain closes the in-process window. Cross-process
+     * concurrency remains the caller's problem, as it was.
+     */
+    writeChain = Promise.resolve();
+    async write(spec, opts) {
+        const run = () => this.writeSerialized(spec, opts);
+        const p = this.writeChain.then(run, run);
+        this.writeChain = p.catch(() => undefined);
+        return p;
+    }
+    async writeSerialized(spec, opts) {
+        const newPath = this.targetPathFor(spec);
+        // @implements A-SPEC-151
+        // Checked BEFORE any filesystem change. A refusal that half-wrote would be the worst outcome:
+        // the caller is told it failed while the store has already moved.
+        if (opts?.expectedVersion !== undefined) {
+            const current = await this.read(spec.id);
+            if (current === null || current.version !== opts.expectedVersion) {
+                throw new SpecVersionConflictError(`spec ${spec.id} changed since it was read (expected ${opts.expectedVersion}, found ${current?.version ?? 'nothing'})`);
+            }
+        }
+        // @implements A-SPEC-188
+        // A write that RELOCATES (legacy filename → canonical on upgrade, base folder → req_type
+        // subfolder on approve after classification) must not land on a file that is not this spec's
+        // own. list()/read() skip unparseable files, so an occupied destination is invisible to every
+        // version check — round-3 review probed spec_upgrade and spec_approve silently replacing a
+        // human note at the destination, with the doctor's unreadable-file warning dying alongside it.
+        // Same-path overwrite (currentPath === newPath) is the normal update and stays allowed.
+        const currentPath = await this.findFilePath(spec.id);
+        if (currentPath !== newPath && fs.existsSync(newPath)) {
+            throw new TargetPathOccupiedError(`spec ${spec.id}: destination ${newPath} is occupied by a file the store cannot read as this spec — a human must move or fix it first`, newPath);
+        }
+        // Remove orphaned files with same id from different paths (e.g., after req_type change)
+        const allSpecs = await this.list();
+        for (const existing of allSpecs) {
+            if (existing.id === spec.id) {
+                // Find the actual file path by walking the tree
+                const existingPath = await this.findFilePath(existing.id);
+                if (existingPath && existingPath !== newPath) {
+                    fs.unlinkSync(existingPath);
+                }
+            }
+        }
+        const dir = this.dirFor(spec);
+        fs.mkdirSync(dir, { recursive: true });
+        const text = (0, spec_parser_1.serializeSpec)(spec);
+        fs.writeFileSync(newPath, text);
+        return { version: this.versionOf(text) };
+    }
+    async findFilePath(id) {
+        let result = null;
+        const walk = (d) => {
+            if (!fs.existsSync(d))
+                return;
+            for (const e of fs.readdirSync(d, { withFileTypes: true })) {
+                const p = path.join(d, e.name);
+                if (e.isDirectory()) {
+                    walk(p);
+                }
+                else if (e.name.endsWith('.md')) {
+                    try {
+                        const spec = (0, spec_parser_1.parseSpec)(fs.readFileSync(p, 'utf8'));
+                        if (spec.id === id) {
+                            result = p;
+                        }
+                    }
+                    catch {
+                        // Skip unparseable files
+                    }
+                }
+            }
+        };
+        walk(this.root);
+        return result;
+    }
+    async list() {
+        const out = [];
+        const walk = (d) => {
+            if (!fs.existsSync(d))
+                return;
+            for (const e of fs.readdirSync(d, { withFileTypes: true })) {
+                const p = path.join(d, e.name);
+                if (e.isDirectory())
+                    walk(p);
+                else if (e.name.endsWith('.md')) {
+                    try {
+                        const spec = (0, spec_parser_1.parseSpec)(fs.readFileSync(p, 'utf8'));
+                        // Only include valid specs with non-empty id
+                        if (spec.id) {
+                            out.push(spec);
+                        }
+                    }
+                    catch {
+                        // Skip files that cannot be parsed (e.g., legacy/malformed markdown)
+                    }
+                }
+            }
+        };
+        walk(this.root);
+        return out;
+    }
+    async read(id) {
+        const file = await this.findFilePath(id);
+        if (file === null)
+            return null;
+        let text;
+        try {
+            text = fs.readFileSync(file, 'utf8');
+        }
+        catch {
+            return null;
+        }
+        let spec;
+        try {
+            spec = (0, spec_parser_1.parseSpec)(text);
+        }
+        catch {
+            return null;
+        } // unparseable is "not readable", as list() treats it
+        return { spec, version: this.versionOf(text) };
+    }
+}
+exports.LocalMarkdownRepository = LocalMarkdownRepository;
+/**
+ * The second adapter — the instrument that makes the contract testable.
+ *
+ * @implements A-SPEC-151
+ * Uses NO filesystem, deliberately: an in-memory store backed by a temp directory would be the file
+ * adapter in disguise and would prove nothing about coupling. The version is derived the same way in
+ * spirit — from the stored representation — but the representation here is an object, so it is
+ * hashed from a canonical serialization of the whole spec INCLUDING status, which is the property
+ * the conformance suite pins.
+ */
+class MemorySpecStore {
+    items = new Map();
+    versionOf(spec) {
+        const canonical = JSON.stringify({
+            id: spec.id, type: spec.type, title: spec.title, status: spec.status,
+            dependsOn: [...spec.dependsOn].sort(),
+            sections: Object.keys(spec.sections).sort().map((k) => [k, spec.sections[k]]),
+            frontmatter: Object.keys(spec.frontmatter).sort().map((k) => [k, spec.frontmatter[k]]),
+        });
+        return `sha256:${(0, node_crypto_1.createHash)('sha256').update(canonical, 'utf8').digest('hex')}`;
+    }
+    async read(id) {
+        const spec = this.items.get(id);
+        return spec ? { spec, version: this.versionOf(spec) } : null;
+    }
+    async write(spec, opts) {
+        if (opts?.expectedVersion !== undefined) {
+            const current = this.items.get(spec.id);
+            const version = current ? this.versionOf(current) : null;
+            if (version !== opts.expectedVersion) {
+                throw new SpecVersionConflictError(`spec ${spec.id} changed since it was read (expected ${opts.expectedVersion}, found ${version ?? 'nothing'})`);
+            }
+        }
+        this.items.set(spec.id, spec);
+        return { version: this.versionOf(spec) };
+    }
+    async list() {
+        return [...this.items.values()].sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+    }
+}
+exports.MemorySpecStore = MemorySpecStore;

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

@@ -0,0 +1,177 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FIELD_PLACEHOLDER = exports.SPEC_TYPES = exports.CITATION_PLACEHOLDER = exports.MUTABLE_CITATION_KINDS = exports.CITATION_KINDS = exports.SPEC_ORDER = exports.SPEC_STATUSES = void 0;
+exports.specTypeDef = specTypeDef;
+exports.isGoverned = isGoverned;
+exports.filterGoverned = filterGoverned;
+exports.specTypeOfId = specTypeOfId;
+exports.parentRuleText = parentRuleText;
+// @implements A-SPEC-192
+// The RUNTIME list is the single truth; the type derives from it (the same rule A-SPEC-189 set for
+// phase ACTIONS). Review round 1 measured THREE hand-copies of this union — handlers' legacy set,
+// its test's CANON, and the type itself — so adding a status compiled clean while spec_list kept
+// flagging it legacy.
+exports.SPEC_STATUSES = ['draft', 'review', 'approved', 'outdated'];
+exports.SPEC_ORDER = ['REQ', 'H-SPEC', 'A-SPEC', 'C-SPEC', 'T-SPEC'];
+/**
+ * Where a requirement came from.
+ *
+ * A REQ is the one artefact whose content cannot be recovered from the codebase — intent lives in
+ * people, tickets, incidents and decisions. That makes its provenance the weakest link in the whole
+ * chain: everything downstream is traceable to the REQ, and the REQ was traceable to a sentence of
+ * free text. Structuring it is what lets a future RequirementSourceAdapter / KnowledgeBaseAdapter
+ * (ports-and-adapters-design §2.1) fill this field mechanically instead of a human paraphrasing a
+ * wiki page, and what lets a changed upstream source mark its derived specs outdated.
+ *
+ * DELIBERATELY SHAPE-ONLY. The deterministic layer can check that a citation exists, names a kind it
+ * understands, points somewhere, and pins either a revision or a read date. It cannot check that the
+ * cited document says what the REQ claims — that stays a human review judgement, exactly as with the
+ * prose sections a reverse-engineered spec leaves as TODO.
+ */
+exports.CITATION_KINDS = [
+    'user-request', // stated directly by the requester
+    'conversation', // a decision reached in discussion
+    'plan', // a planning document
+    'adr', // an architecture decision record
+    'architecture', // a design/architecture document
+    'analysis', // competitive/market/technical analysis
+    'issue', // tracker item (JIRA, GitHub, internal)
+    'wiki', // knowledge base page, runbook
+    'incident', // production incident or postmortem
+    'code-review', // a review comment or finding
+    'regulation', // a compliance obligation (HIPAA/SOC2/GDPR/…)
+    'other',
+];
+/**
+ * Kinds whose content can change after it was cited, and which therefore REQUIRE `rev`.
+ *
+ * The split is mutable vs immutable, not "has a version number". A wiki page, a ticket, an ADR or a
+ * plan file all keep changing under you, so a citation without a version pin cannot detect drift and
+ * the citation stops meaning anything. A conversation, a direct request, or an incident is fixed the
+ * moment it happened — `ref` plus `retrieved` already pins it completely, and demanding a `rev` there
+ * would only push an author to invent one, which is the fabrication this whole schema exists to stop.
+ */
+exports.MUTABLE_CITATION_KINDS = [
+    'plan', 'adr', 'architecture', 'analysis', 'issue', 'wiki', 'code-review', 'regulation', 'other',
+];
+/** Placeholder a freshly created spec carries until its author supplies a real citation. */
+exports.CITATION_PLACEHOLDER = 'TODO';
+exports.SPEC_TYPES = {
+    'REQ': {
+        type: 'REQ', idRegex: /^REQ-\d{3,}$/, example: 'REQ-001', folder: '01_req', parents: [],
+        requiredFields: ['source', 'created'],
+        requiredSections: ['Problem / Need', 'Desired Outcome', 'Constraints', 'Success Criteria', 'Out of Scope'],
+    },
+    'H-SPEC': {
+        type: 'H-SPEC', idRegex: /^H-SPEC-\d{3,}$/, example: 'H-SPEC-001', folder: '02_h-spec', parents: ['REQ'],
+        requiredFields: ['req_type', 'owner'],
+        requiredSections: ['Intent', 'Scope (In / Out)', 'Design Overview', 'Interfaces / Contracts', 'Acceptance Criteria', 'Non-Functional', 'Assumptions', 'Open Questions'],
+    },
+    'A-SPEC': {
+        type: 'A-SPEC', idRegex: /^A-SPEC-\d{3,}(\.\d+)?$/, example: 'A-SPEC-001', folder: '03_a-spec', parents: ['H-SPEC'],
+        requiredFields: ['slice', 'priority', 'independent_test'],
+        // @implements A-SPEC-146
+        // Scaffolded by `spec_create`, NOT required by `validateSpec`. Measured: putting
+        // `breaking_change` in `requiredFields` produced 38 ART-3 violations and a Stop hook that
+        // 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'],
+        requiredSections: ['Objective', 'Inputs / Outputs', 'Behavior', 'Test Points', 'Files to Touch', 'Done When'],
+    },
+    'C-SPEC': {
+        type: 'C-SPEC', idRegex: /^C-SPEC-\d{3,}$/, example: 'C-SPEC-001', folder: '04_cpg', parents: ['A-SPEC'],
+        requiredFields: [],
+        requiredSections: ['Allowed Dependencies', 'Forbidden Edges', 'Affected Symbols', 'Layer Rules'],
+    },
+    'T-SPEC': {
+        // @implements A-SPEC-186
+        // Mirrors A-SPEC's shape so a T-SPEC can carry its parent's number VERBATIM — `A-SPEC-100.1`
+        // is tested by `T-SPEC-100.1`, and a reader needs no arithmetic. The old habit appended a
+        // sequence digit (`A-SPEC-129` → `T-SPEC-1291`), which measured 0 uses across 76 A-SPECs — not
+        // one of them has a second T-SPEC — while producing a number that reads as a quantity and
+        // cannot be split back into parent and sequence.
+        //
+        // This WIDENS the accepted set; the 76 existing ids all still pass. Narrowing would have made
+        // every one of them a violation at once, which is the accident A-SPEC-146 recorded.
+        // The mirror is a CONVENTION, not a rule the validator enforces: `T-SPEC-1291` under
+        // `A-SPEC-129` stays valid, because renaming sealed documents is not on the table.
+        type: 'T-SPEC', idRegex: /^T-SPEC-\d{3,}(\.\d+)?$/, example: 'T-SPEC-001', folder: '05_t-spec', parents: ['A-SPEC'],
+        requiredFields: ['coverage'],
+        requiredSections: ['Normal Cases', 'Corner Cases', 'Negative Cases', 'Boundary Cases'],
+    },
+};
+// @implements A-SPEC-100.1
+/**
+ * The GOVERNED set is defined by the modern spec format: a spec is governed
+ * iff it carries a `type` field naming a known SpecType. This deliberately
+ * excludes (a) pre-`type` legacy specs retained only as archived history, and
+ * (b) the `06_job/JOB-*` runtime ledger, which is not a governed spec type.
+ * Validation and RTM integrity checks operate on the governed set — validating
+ * archived legacy or runtime-ledger entries is a category error (audit C1).
+ * Generic over `{ type?: SpecType }` to stay free of an import cycle with the
+ * parser (which imports SpecType from here).
+ */
+/**
+ * Own-property lookup into SPEC_TYPES. A bare `SPEC_TYPES[type]` inherits
+ * Object.prototype, so a spec with `type: constructor` / `__proto__` / etc.
+ * (raw unvalidated YAML frontmatter) would resolve to a prototype member and
+ * masquerade as a known type — then crash downstream on `def.idRegex`. This
+ * guard returns undefined for any non-own key.
+ */
+function specTypeDef(type) {
+    if (type == null)
+        return undefined;
+    return Object.prototype.hasOwnProperty.call(exports.SPEC_TYPES, type)
+        ? exports.SPEC_TYPES[type]
+        : undefined;
+}
+function isGoverned(spec) {
+    return specTypeDef(spec.type) !== undefined;
+}
+function filterGoverned(specs) {
+    return specs.filter(isGoverned);
+}
+/**
+ * @implements A-SPEC-174
+ * The value `spec_create` writes into a required field it cannot answer.
+ *
+ * Named because two places must agree on it: the handler that writes it, and the store that must NOT
+ * treat it as a directory name. Measured 2026-08-12 — a stubbed `req_type` produced a literal
+ * `.ax/specs/02_h-spec/TODO/` in the user's repository.
+ */
+exports.FIELD_PLACEHOLDER = 'TODO';
+/**
+ * @implements A-SPEC-174
+ * Which spec type an id belongs to, or null if no type claims it.
+ *
+ * Judged by the same `idRegex` the approval-time validator uses, not by a prefix comparison. A second
+ * statement of the rule drifts, and the failure it produces is either "created but never approvable"
+ * (which is the defect this closes) or the worse inverse — refused at creation, accepted at approval.
+ *
+ * This is what lets a parent be checked WITHOUT resolving it: a parent that does not exist yet is a
+ * legitimate state an author reaches by creating the child first, while a parent of the wrong type is
+ * wrong forever.
+ */
+function specTypeOfId(id) {
+    for (const def of Object.values(exports.SPEC_TYPES))
+        if (def.idRegex.test(id))
+            return def.type;
+    return null;
+}
+/**
+ * @implements A-SPEC-174
+ * The parent-kind rule as prose, GENERATED from the relation itself.
+ *
+ * Written by hand this drifted the moment a clause was edited, and prose assertions could not tell
+ * the difference — a test looking for "H-SPEC ... REQ" still matched a sentence that had lost the
+ * H-SPEC rule entirely. Generating it removes the second copy instead of testing around it.
+ */
+function parentRuleText() {
+    return exports.SPEC_ORDER
+        .map((t) => {
+        const p = exports.SPEC_TYPES[t].parents;
+        return p.length === 0 ? `${t} has no parent` : `${t} depends on ${p.join(' or ')}`;
+    })
+        .join('; ');
+}