@holmes-lab/holmes-kit 0.1.0

package/dist/holmes/spec/legacy-format.js

@@ -0,0 +1,87 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LEGACY_STATUS_FIELD = void 0;
+exports.formatStateOf = formatStateOf;
+exports.legacyMessage = legacyMessage;
+exports.upgradePlan = upgradePlan;
+exports.upgradedFrontmatter = upgradedFrontmatter;
+const spec_types_1 = require("./spec-types");
+/** Frontmatter key that preserves the pre-upgrade status. Named once so writer and reader agree. */
+exports.LEGACY_STATUS_FIELD = 'legacy_status';
+/**
+ * Classify a document by FORMAT, not by validity.
+ *
+ * A DECLARED type always wins over the id. Inference exists to help a document that never said what
+ * it was — never to overrule a human who did. A declared type that this tool does not have is NOT
+ * `current`: declaring `type: JOB` must not smuggle an unknown kind past the governed boundary.
+ */
+function formatStateOf(spec) {
+    const declared = (0, spec_types_1.specTypeDef)(spec.type);
+    if (declared)
+        return { kind: 'current', type: declared.type };
+    const inferred = (0, spec_types_1.specTypeOfId)(spec.id);
+    return inferred ? { kind: 'legacy', inferred } : { kind: 'unsupported' };
+}
+/**
+ * Why this document cannot be used as a governed spec, and what to do about it — or `null` when the
+ * document is in current format and the caller's existing wording should stand.
+ *
+ * Returning `null` for `current` is what keeps this change from leaking into paths that were already
+ * correct: a parent of the wrong DECLARED kind was always reported accurately, and REQ-184 does not
+ * touch it.
+ *
+ * The two non-null cases must read differently. Telling the holder of a `JOB-001` to upgrade it
+ * would send them after a type that does not exist — the same "points nowhere" failure this REQ
+ * exists to close, merely relocated.
+ */
+function legacyMessage(spec) {
+    const state = formatStateOf(spec);
+    if (state.kind === 'current')
+        return null;
+    if (state.kind === 'unsupported') {
+        return (`${spec.id}은(는) 이 도구가 다루는 스펙 종류가 아닙니다 — id가 현행 종류 규약에 맞지 않습니다. ` +
+            '옛 시스템의 문서라면 그대로 두십시오. 거버넌스 대상이 아니며, 보강해도 쓸 수 있는 종류가 되지 않습니다.');
+    }
+    return (`${spec.id}에 \`type:\` 선언이 없습니다 — 현행보다 이전 양식으로 쓰인 문서입니다. ` +
+        `id로 보면 ${state.inferred}입니다. 이 문서를 거버넌스 아래에서 쓰려면 ` +
+        `\`spec_upgrade\`로 보강하십시오(선언만 더하며 본문과 승인 상태는 건드리지 않습니다).`);
+}
+/**
+ * What an upgrade would change, or `null` when there is nothing to do.
+ *
+ * `null` for BOTH `current` and `unsupported`, for opposite reasons — already declared, or nothing
+ * to declare. The caller distinguishes them; this function only answers "is there a plan".
+ *
+ * The plan carries no status of its own on purpose. Upgrading declares a KIND; it does not decide
+ * whether the document is normative. 37 of this repository's legacy documents say `Approved`, and
+ * carrying that across would mint 37 approvals that never passed through the sealing act — no
+ * `approved_digest`, no `parent_digests`, no ledger entry. The old value is preserved as evidence
+ * and the document restarts at `draft`, from where the normal approval path can seal it properly.
+ */
+function upgradePlan(spec) {
+    const state = formatStateOf(spec);
+    if (state.kind !== 'legacy')
+        return null;
+    // Empty rather than `String(undefined)`. Unreachable through the store — the parser defaults a
+    // missing status to 'draft', and both measured corpora have zero such documents — but a bare
+    // `String()` here would write the literal `undefined` into a governance artefact permanently,
+    // which is the exact defect this REQ exists to remove. The caller omits the field when empty.
+    return { type: state.inferred, legacyStatus: spec.status ? String(spec.status) : '' };
+}
+/**
+ * The frontmatter an upgrade writes: everything that was there, plus the preserved status.
+ *
+ * Lives here rather than inline at the call site so the omission rule is exercisable. The store's
+ * parser defaults a missing status to `draft`, so a document with none cannot arrive through it —
+ * which is exactly why the rule would otherwise go untested and could be deleted unnoticed.
+ *
+ * The spread comes first so a document that somehow already carries `legacy_status` keeps it rather
+ * than having it rewritten from a status that is itself the result of an earlier upgrade.
+ */
+function upgradedFrontmatter(spec, plan) {
+    // Omitted, never written empty: `legacy_status:` with nothing after it asserts evidence that does
+    // not exist, and `String(undefined)` would put the literal `undefined` into a governance artefact.
+    if (!plan.legacyStatus)
+        return { ...spec.frontmatter };
+    return { ...spec.frontmatter, [exports.LEGACY_STATUS_FIELD]: plan.legacyStatus };
+}

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

@@ -0,0 +1,71 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SEAL_FIELDS = void 0;
+exports.specDigest = specDigest;
+exports.sealForTest = sealForTest;
+exports.sealOf = sealOf;
+const node_crypto_1 = require("node:crypto");
+/**
+ * @implements A-SPEC-132
+ * The canonical content digest an approval SEALS. It covers what approving means — the spec's kind,
+ * its title, which parents it claims, and every section body — and deliberately excludes `status`
+ * and the seal fields themselves (a seal must not seal itself, and flipping status must not break
+ * the seal it accompanies). All other frontmatter is excluded too: owner/priority metadata churn is
+ * not a content change someone must re-approve.
+ *
+ * Canonicalization makes the digest platform- and formatting-stable: `dependsOn` is sorted, section
+ * keys are sorted, section bodies are LF-normalized and right-trimmed. Same content, same hex —
+ * reordering YAML keys or a CRLF checkout cannot fake a post-approval edit.
+ */
+function specDigest(spec) {
+    // @implements A-SPEC-146
+    // `breaking_change` is sealed, CONDITIONALLY. Adversarial review found the hole: specDigest hashes
+    // only type/title/dependsOn/sections, so an approved A-SPEC could have its declaration deleted with
+    // the seal still matching — the enforcement could be stripped after the fact, and REQ-146's claim
+    // that "the seal already catches this" was asserted without measuring and was false.
+    //
+    // Conditional, not unconditional: adding the key for every spec would change all 38 existing seals
+    // at once, flooding `post-approval-edit` and blocking the Stop hook every turn — the same bricking
+    // this requirement measured and avoided elsewhere. A spec that never had the field keeps its digest;
+    // one that has it is bound to it, so removal or alteration surfaces as drift.
+    const bc = spec.frontmatter?.breaking_change;
+    const canonical = JSON.stringify({
+        type: spec.type,
+        title: spec.title,
+        dependsOn: [...spec.dependsOn].sort(),
+        sections: Object.keys(spec.sections).sort().map((k) => [k, spec.sections[k].replace(/\r\n/g, '\n').trimEnd()]),
+        ...(spec.type === 'A-SPEC' && typeof bc === 'string' ? { breaking_change: bc } : {}),
+    });
+    return `sha256:${(0, node_crypto_1.createHash)('sha256').update(canonical, 'utf8').digest('hex')}`;
+}
+/** Frontmatter keys written only by an approval act (spec_approve / the one-time backfill). */
+exports.SEAL_FIELDS = ['approved_digest', 'parent_digests'];
+/**
+ * @implements A-SPEC-132
+ * Test-only helper: return a copy of `spec` sealed at its current content, snapshotting each given
+ * parent's own seal. Fixtures that represent an APPROVED spec must now carry a seal to be valid — the
+ * validator enforces it — so tests build approved fixtures through this. Not for production writes:
+ * spec_approve is the only real sealer (it also validates and ledgers).
+ */
+function sealForTest(spec, parents = []) {
+    const parent_digests = {};
+    for (const p of parents) {
+        const d = sealOf(p).approvedDigest;
+        if (d)
+            parent_digests[p.id] = d;
+    }
+    return { ...spec, frontmatter: { ...spec.frontmatter, approved_digest: specDigest(spec), parent_digests } };
+}
+/** The seal a spec carries, if any. */
+function sealOf(spec) {
+    const approvedDigest = typeof spec.frontmatter.approved_digest === 'string' ? spec.frontmatter.approved_digest : undefined;
+    const raw = spec.frontmatter.parent_digests;
+    const parentDigests = {};
+    if (raw && typeof raw === 'object' && !Array.isArray(raw)) {
+        for (const [k, v] of Object.entries(raw)) {
+            if (typeof v === 'string')
+                parentDigests[k] = v;
+        }
+    }
+    return { approvedDigest, parentDigests };
+}

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

@@ -0,0 +1,106 @@
+"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.parseSpec = parseSpec;
+exports.serializeSpec = serializeSpec;
+const yaml = __importStar(require("js-yaml"));
+function splitSections(body) {
+    const out = {};
+    const lines = body.split('\n');
+    let inFence = false;
+    let currentHeading = null;
+    let currentContent = [];
+    const headingRegex = /^##\s+(.+?)\s*$/;
+    for (const line of lines) {
+        // Toggle fence state on lines matching /^\s*```/
+        if (/^\s*```/.test(line)) {
+            inFence = !inFence;
+            if (currentHeading !== null)
+                currentContent.push(line);
+            continue;
+        }
+        // Check for section heading only when not in fence
+        const headingMatch = !inFence ? headingRegex.exec(line) : null;
+        if (headingMatch) {
+            // Save previous section if exists
+            if (currentHeading !== null) {
+                out[currentHeading] = currentContent.join('\n').trim();
+            }
+            // Start new section
+            currentHeading = headingMatch[1].trim();
+            currentContent = [];
+        }
+        else {
+            // Add line to current section
+            if (currentHeading !== null) {
+                currentContent.push(line);
+            }
+        }
+    }
+    // Save final section
+    if (currentHeading !== null) {
+        out[currentHeading] = currentContent.join('\n').trim();
+    }
+    return out;
+}
+function parseSpec(input) {
+    // @implements A-SPEC-176
+    // Fold CRLF at the door, once. Measured 2026-08-12: the delimiter below is LF-only, so a spec saved
+    // by a Windows editor (or cloned with core.autocrlf=true) parsed to `id: ""` WITHOUT throwing, and
+    // `list()` dropped it — the user saw an approved document on disk while the gate said it was not
+    // approved. Fixing only the delimiter would leave a `\r` on every frontmatter value instead, which
+    // poisons ids and titles silently rather than failing.
+    //
+    // Safe for every existing seal: on an LF document this replace is the identity, so the approval
+    // digests of the 400+ specs already in this repository are unchanged (ADR-013 tier ① avoided).
+    const raw = input.replace(/\r\n/g, '\n');
+    const m = /^---\n([\s\S]*?)\n---\n?([\s\S]*)$/.exec(raw);
+    const fm = ((m ? yaml.load(m[1]) : {}) ?? {});
+    const body = m ? m[2] : raw;
+    return {
+        id: String(fm.id ?? ''),
+        type: fm.type,
+        title: String(fm.title ?? ''),
+        status: (fm.status ?? 'draft'),
+        dependsOn: Array.isArray(fm.depends_on) ? fm.depends_on : [],
+        frontmatter: fm,
+        sections: splitSections(body),
+    };
+}
+function serializeSpec(spec) {
+    const fm = { ...spec.frontmatter, id: spec.id, type: spec.type, title: spec.title, status: spec.status, depends_on: spec.dependsOn };
+    const body = Object.entries(spec.sections).map(([h, t]) => `## ${h}\n${t}\n`).join('\n');
+    return `---\n${yaml.dump(fm)}---\n\n${body}`;
+}

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

@@ -0,0 +1,118 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.specStoreConformance = specStoreConformance;
+// @implements A-SPEC-151
+const spec_store_1 = require("./spec-store");
+/**
+ * The ONE conformance suite every `SpecStore` adapter must pass.
+ *
+ * Written entirely against the CONTRACT — no paths, no files, no knowledge of how anything is
+ * stored. ADR-014 recorded the limit measured on the ledger port: a storage-agnostic suite cannot
+ * see storage-specific defects, so each adapter still owes tests about its own medium. What belongs
+ * HERE is only what is meaningful for every adapter.
+ */
+function specStoreConformance(name, make) {
+    const req = (over = {}, fm = {}) => ({
+        id: 'REQ-900', type: 'REQ', title: 't', status: 'draft', dependsOn: [],
+        sections: {
+            'Problem / Need': 'x', 'Desired Outcome': 'y', Constraints: 'c',
+            'Success Criteria': 's', 'Out of Scope': 'o',
+        },
+        frontmatter: {
+            source: [{ kind: 'user-request', ref: 'r', retrieved: '2026-08-07' }],
+            created: '2026-08-07', ...fm,
+        },
+        ...over,
+    });
+    describe(`SpecStore conformance — ${name} (A-SPEC-151)`, () => {
+        it('normal: what is written can be read back', async () => {
+            const s = make();
+            await s.write(req());
+            const got = await s.read('REQ-900');
+            expect(got?.spec.id).toBe('REQ-900');
+            expect(got?.spec.title).toBe('t');
+        });
+        it('normal: read returns a version alongside the spec', async () => {
+            const s = make();
+            await s.write(req());
+            expect(typeof (await s.read('REQ-900'))?.version).toBe('string');
+            expect((await s.read('REQ-900'))?.version).toBeTruthy();
+        });
+        it('boundary: an unknown id reads as null', async () => {
+            expect(await make().read('REQ-999')).toBeNull();
+        });
+        it('boundary: the same content yields the same version — the token must be deterministic', async () => {
+            const s = make();
+            await s.write(req());
+            const first = (await s.read('REQ-900')).version;
+            await s.write(req()); // identical content, written again
+            expect((await s.read('REQ-900')).version).toBe(first);
+        });
+        it('corner: changed CONTENT changes the version', async () => {
+            const s = make();
+            await s.write(req());
+            const before = (await s.read('REQ-900')).version;
+            await s.write(req({ title: 'changed' }));
+            expect((await s.read('REQ-900')).version).not.toBe(before);
+        });
+        it('corner: a change to STATUS ALONE changes the version', async () => {
+            // Why `specDigest` cannot serve as this token: it hashes type/title/dependsOn/sections and
+            // deliberately excludes status, so a draft→approved flip would be invisible to it. The two
+            // digests answer different questions — "is this the content that was approved" versus "has
+            // anyone touched this since I read it" — and collapsing them would weaken both.
+            const s = make();
+            await s.write(req());
+            const before = (await s.read('REQ-900')).version;
+            await s.write(req({ status: 'approved' }));
+            expect((await s.read('REQ-900')).version).not.toBe(before);
+        });
+        it('normal: writing with the CURRENT version succeeds and returns the new one', async () => {
+            const s = make();
+            await s.write(req());
+            const v = (await s.read('REQ-900')).version;
+            const r = await s.write(req({ title: 'next' }), { expectedVersion: v });
+            expect(r.version).toBeTruthy();
+            expect((await s.read('REQ-900')).spec.title).toBe('next');
+        });
+        it('normal: writing with NO expectedVersion still succeeds — existing callers are unaffected', async () => {
+            const s = make();
+            await s.write(req());
+            await expect(s.write(req({ title: 'blind' }))).resolves.toBeTruthy();
+            expect((await s.read('REQ-900')).spec.title).toBe('blind');
+        });
+        it('negative: a STALE expectedVersion is rejected AND leaves the stored spec untouched', async () => {
+            // A refusal that half-wrote would be the worst of both: the caller is told it failed while the
+            // store has already changed.
+            const s = make();
+            await s.write(req());
+            const stale = (await s.read('REQ-900')).version;
+            await s.write(req({ title: 'someone else' })); // concurrent change
+            await expect(s.write(req({ title: 'mine' }), { expectedVersion: stale }))
+                .rejects.toBeInstanceOf(spec_store_1.SpecVersionConflictError);
+            expect((await s.read('REQ-900')).spec.title).toBe('someone else');
+        });
+        it('negative: expectedVersion on a spec that does not exist is a conflict', async () => {
+            // "Is what I read still there" cannot be satisfied by "there is no such thing".
+            await expect(make().write(req(), { expectedVersion: 'whatever' }))
+                .rejects.toBeInstanceOf(spec_store_1.SpecVersionConflictError);
+        });
+        it('normal: externalId round-trips — a mirrored spec keeps its foreign key', async () => {
+            const s = make();
+            await s.write(req({}, { external_id: 'JIRA-1234' }));
+            expect((await s.read('REQ-900')).spec.frontmatter.external_id).toBe('JIRA-1234');
+        });
+        it('boundary: a spec with no externalId reads back without one', async () => {
+            const s = make();
+            await s.write(req());
+            expect((await s.read('REQ-900')).spec.frontmatter.external_id).toBeUndefined();
+        });
+        it('boundary: an empty store lists nothing and does not throw', async () => {
+            expect(await make().list()).toEqual([]);
+        });
+        it('normal: list includes what was written', async () => {
+            const s = make();
+            await s.write(req());
+            expect((await s.list()).map((x) => x.id)).toContain('REQ-900');
+        });
+    });
+}