@holmes-lab/holmes-kit 0.1.6 → 0.1.8

package/dist/holmes/spec/approval-blockers.d.ts

@@ -0,0 +1,62 @@
+import { Spec } from './spec-parser';
+/**
+ * Sections that still hold nothing but a generated placeholder.
+ *
+ * Two generators plant placeholders and both are judged here:
+ *  - `reverse_draft` writes `TODO — <prompt>` plus the INFERRED marker comment. Both are
+ *    required together: 11 of this repository's 257 approved specs use the word "TODO" in
+ *    legitimate prose ("남아 있는 TODO 주석을 제거한다"), and a word search refuses every one.
+ *  - `spec_create` writes the bare literal `TODO` (`FIELD_PLACEHOLDER`) into each required section.
+ *    That one is unambiguous on its own — an entire section equal to the string is never prose.
+ */
+export declare function placeholderSections(spec: Spec): string[];
+/**
+ * Codes that `validateSpec` reports but approval itself supplies, so they are not blockers.
+ * Exported because `spec_approve` filters by the same set — two hand-maintained lists were how the
+ * gate and the act drifted apart in the first place.
+ */
+export declare const SUPPLIED_BY_APPROVAL: Set<string>;
+/**
+ * Parent-chain reasons an approval is refused.
+ *
+ * `validateSpec` deliberately stays silent on both (it `continue`s past a draft or unsealed parent —
+ * "other findings' business"), so nothing else computes these. Shared with `spec_approve` so the
+ * wording cannot drift.
+ */
+/** The one wording for a spec whose prose is still a generator stub. Shared for the same reason. */
+export declare const placeholderMessage: (sections: string[]) => string;
+/** The one wording for an unsealed parent. Shared so a second, degraded copy cannot appear. */
+export declare const unsealedParentMessage: (pid: string) => string;
+export declare function parentBlockers(spec: Spec, resolve: (id: string) => Spec | null): string[];
+/**
+ * Every reason `spec` cannot be approved right now. Empty means nothing is in the way.
+ *
+ * Order matches `spec_approve`'s: parents, then static validity, then the declaration duty, then
+ * placeholders. Pure — it reads the spec objects it is handed and touches no filesystem, because
+ * the gate calls it from a PreToolUse hook on every tool call.
+ */
+export declare function approvalBlockers(spec: Spec, resolve: (id: string) => Spec | null): string[];
+/** The separator between one spec's blockers. Shared so nothing re-splits on a guessed delimiter. */
+export declare const BLOCKER_SEP = "; ";
+/**
+ * One spec's blockers as a labelled clause.
+ *
+ * Exported so a caller that needs to CLAMP the list works on real blocker boundaries. Review found
+ * `tspec-state` re-splitting the joined string on `; ` — a delimiter that also occurs inside
+ * author-controlled text (a `depends_on` entry, a section name), which produced a sliced spec id
+ * with an unterminated quote and a remainder counting fragments rather than blockers.
+ */
+export declare const blockerClause: (label: string, blockers: string[]) => string;
+/**
+ * The blockers as one line for a refusal message, or `null` when nothing blocks.
+ *
+ * `specId` labels the list. A refusal can name several specs at once, and review found the
+ * unlabelled form reintroduced exactly what REQ-155 forbids: the reader saw two reason-lists run
+ * together with no way to tell which spec each belonged to.
+ *
+ * Blockers are separated by `; ` rather than ` / ` because section names legitimately contain a
+ * slash (`Inputs / Outputs`), which made the boundaries unreadable.
+ *
+ * Never throws: a refusal that says less is recoverable, a hook that dies is not.
+ */
+export declare function blockerSummary(spec: Spec | undefined, resolve: (id: string) => Spec | null, specId?: string): string | null;

package/dist/holmes/spec/breaking-change.d.ts

@@ -0,0 +1,42 @@
+import { Spec } from './spec-parser';
+/**
+ * ADR-013's enforcement device: the obligation to declare a breaking change lives on the ACT of
+ * approval, not on the document's static validity.
+ *
+ * WHY here and not in `validateSpec`'s `requiredFields`, measured rather than argued: all 38 governed
+ * A-SPECs in this repository are already approved, so adding the field to the state predicate
+ * produced **38 ART-3 violations and `evaluateStop().block === true`** — the harness would have
+ * blocked every turn, bricked by the very work meant to strengthen its governance.
+ *
+ * The move is not a workaround, it is the correct reading. "Is this change breaking?" is not a static
+ * property a document either has or lacks; it is a question that must be answered at the moment a
+ * change is sealed. Re-sealing means the content changed, which is exactly when the question is due.
+ *
+ * CONVERGENCE: any spec that changes must be re-approved and therefore acquires the field. A spec
+ * that never changes never acquires it — and cannot introduce a breaking change either. That is why
+ * no backfill is needed, and why mechanically filling 38 documents with `none` would be the very
+ * formulaic answer this device exists to discourage.
+ *
+ * REMOVAL AFTER APPROVAL is not defended here on purpose: deleting the field changes the body, the
+ * `approved_digest` stops matching, and the existing seal machinery reports `post-approval-edit`.
+ * Adding a second mechanism for a case the first already covers would be duplication, not depth.
+ */
+/** ADR-013's four tiers, plus `none`. Order is the order the denial message lists them in. */
+export declare const BREAKING_CHANGE_GRADES: readonly ["none", "persisted-artifact", "derived-artifact", "code-interface", "gate-behavior"];
+export type BreakingChangeGrade = (typeof BREAKING_CHANGE_GRADES)[number];
+/**
+ * `null` when the spec satisfies ADR-013's declaration duty, otherwise the reason it does not.
+ *
+ * Only A-SPEC is checked: it is the layer that carries the implementation contract (`Files to
+ * Touch`), so it is the layer where a change becomes breaking. Widening this to every spec type
+ * would collect answers from documents that touch no artefact.
+ */
+export declare function checkBreakingChangeDeclared(spec: Spec): string | null;
+/**
+ * Grade counts across the governed A-SPECs, with `(unset)` for those that have not been re-approved
+ * since ADR-013. A REPORT, never an assertion: "all `none` must fail" would fire falsely during a
+ * period when every change genuinely is non-breaking. ADR-013 recorded formulaic-`none` as a revisit
+ * trigger for a human to judge, and this surfaces the distribution that judgement needs — including
+ * how far the corpus has converged.
+ */
+export declare function breakingChangeDistribution(specs: Spec[]): Record<string, number>;

package/dist/holmes/spec/legacy-format.d.ts

@@ -0,0 +1,93 @@
+import { Spec } from './spec-parser';
+import { SpecType } from './spec-types';
+/**
+ * How a spec document relates to the CURRENT format — the compatibility policy of REQ-184.
+ *
+ * holmes-kit will change its spec format again. This module fixes the answer to "what do we do with
+ * documents written under an older one" so it does not have to be re-argued each time:
+ *
+ *   read but do not enforce  →  a document whose kind is knowable but undeclared
+ *   enforce                  →  a document a human explicitly upgraded
+ *   read and leave alone     →  a kind this tool no longer has
+ *
+ * The line between READING and ENFORCING already exists as `isGoverned`, which keys off a DECLARED
+ * type. This module does not move that line. It teaches the messages to speak about what lies
+ * outside it, and provides the one explicit act that moves a document across.
+ *
+ * Measured 2026-08-18: holmes-kit carries 155 such documents of 483, AX Coder 90 of 90. The id
+ * recovers the kind for 85–88% of them; the remainder are all `JOB-NNN`, a kind that no longer
+ * exists here.
+ */
+export type FormatState = 
+/** `type:` is declared and is a kind this tool has. Governed, and nothing here applies. */
+{
+    kind: 'current';
+    type: SpecType;
+}
+/** No `type:`, but the id says what it is. Upgradable. */
+ | {
+    kind: 'legacy';
+    inferred: SpecType;
+}
+/** No usable kind at all — not something this tool governs. */
+ | {
+    kind: 'unsupported';
+};
+/** Frontmatter key that preserves the pre-upgrade status. Named once so writer and reader agree. */
+export declare const 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.
+ */
+export declare function formatStateOf(spec: {
+    id: string;
+    type?: SpecType;
+}): FormatState;
+/**
+ * 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.
+ */
+export declare function legacyMessage(spec: {
+    id: string;
+    type?: SpecType;
+}): string | null;
+/**
+ * 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.
+ */
+export declare function upgradePlan(spec: Spec): {
+    type: SpecType;
+    legacyStatus: string;
+} | null;
+/**
+ * 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.
+ */
+export declare function upgradedFrontmatter(spec: Spec, plan: {
+    legacyStatus: string;
+}): Record<string, unknown>;

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

@@ -0,0 +1,29 @@
+import { Spec } from './spec-parser';
+/**
+ * @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.
+ */
+export declare function specDigest(spec: Spec): string;
+/** Frontmatter keys written only by an approval act (spec_approve / the one-time backfill). */
+export declare const SEAL_FIELDS: readonly ["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).
+ */
+export declare function sealForTest(spec: Spec, parents?: Spec[]): Spec;
+/** The seal a spec carries, if any. */
+export declare function sealOf(spec: Spec): {
+    approvedDigest?: string;
+    parentDigests: Record<string, string>;
+};

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

@@ -0,0 +1,12 @@
+import { SpecType, SpecStatus } from './spec-types';
+export interface Spec {
+    id: string;
+    type: SpecType;
+    title: string;
+    status: SpecStatus;
+    dependsOn: string[];
+    frontmatter: Record<string, unknown>;
+    sections: Record<string, string>;
+}
+export declare function parseSpec(input: string): Spec;
+export declare function serializeSpec(spec: Spec): string;

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

@@ -0,0 +1,10 @@
+import { SpecStore } from './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.
+ */
+export declare function specStoreConformance(name: string, make: () => SpecStore): void;

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

@@ -0,0 +1,130 @@
+import { Spec } from './spec-parser';
+/**
+ * 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)으로 생존".
+ */
+export declare class SpecVersionConflictError extends Error {
+}
+/**
+ * @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.
+ */
+export declare class TargetPathOccupiedError extends Error {
+    readonly occupiedPath: string;
+    constructor(message: string, occupiedPath: string);
+}
+/**
+ * The spec store as a PORT.
+ *
+ * @implements A-SPEC-151
+ * The version is DERIVED, never stored. A new frontmatter field would be an ADR-013 tier-① format
+ * change, dragging 302 existing specs into a migration and a read-compatibility problem; an opaque
+ * token the store computes at read time costs none of that. It is deliberately NOT `specDigest`,
+ * which excludes `status` and the seal fields — a draft→approved flip would be invisible to it. The
+ * two answer different questions: "is this the content that was approved" versus "has anyone touched
+ * this since I read it".
+ *
+ * DECLARED because they have callers and two adapters can be tested against them: `expectedVersion`
+ * and `external_id` (a spec mirrored from a tracker needs its foreign key).
+ *
+ * NOT DECLARED — locks, events, RBAC — although ADR-001 listed them. ADR-014, decided on the ledger
+ * port's measurement, forbids clauses with no caller that no two adapters can verify, and ADR-001's
+ * own Consequences named speculative port design as its downside. A wrong contract is more expensive
+ * than an absent one, since it is exactly what causes the core-wide rework ADR-001 set out to avoid.
+ * A lock would also duplicate what optimistic concurrency replaces. Widen when a caller appears.
+ */
+export interface SpecStore {
+    read(id: string): Promise<{
+        spec: Spec;
+        version: string;
+    } | null>;
+    write(spec: Spec, opts?: {
+        expectedVersion?: string;
+    }): Promise<{
+        version: string;
+    }>;
+    list(): Promise<Spec[]>;
+}
+/**
+ * @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.
+ */
+export declare function unreadableSpecFiles(specsDir: string): string[];
+export declare class LocalMarkdownRepository implements SpecStore {
+    private readonly root;
+    constructor(root: string);
+    /**
+     * @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(): string;
+    private dirFor;
+    /** Version of the STORED representation — the serialized document, so a status flip changes it. */
+    private versionOf;
+    /**
+     * @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: Spec): string;
+    /**
+     * @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.
+     */
+    private writeChain;
+    write(spec: Spec, opts?: {
+        expectedVersion?: string;
+    }): Promise<{
+        version: string;
+    }>;
+    private writeSerialized;
+    private findFilePath;
+    list(): Promise<Spec[]>;
+    read(id: string): Promise<{
+        spec: Spec;
+        version: string;
+    } | null>;
+}
+/**
+ * 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.
+ */
+export declare class MemorySpecStore implements SpecStore {
+    private readonly items;
+    private versionOf;
+    read(id: string): Promise<{
+        spec: Spec;
+        version: string;
+    } | null>;
+    write(spec: Spec, opts?: {
+        expectedVersion?: string;
+    }): Promise<{
+        version: string;
+    }>;
+    list(): Promise<Spec[]>;
+}

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

@@ -0,0 +1,150 @@
+export type SpecType = 'REQ' | 'H-SPEC' | 'A-SPEC' | 'C-SPEC' | 'T-SPEC';
+export declare const SPEC_STATUSES: readonly ["draft", "review", "approved", "outdated"];
+export type SpecStatus = (typeof SPEC_STATUSES)[number];
+export interface SpecTypeDef {
+    type: SpecType;
+    idRegex: RegExp;
+    /**
+     * @implements A-SPEC-174
+     * A valid id of this type, shown to whoever `spec_create` just refused. Held here rather than
+     * derived from `idRegex`, because generating it would be a second statement of the same rule —
+     * and an example that its own rule rejects sends the reader back into the refusal they came from.
+     */
+    example: string;
+    folder: string;
+    parents: SpecType[];
+    requiredFields: string[];
+    requiredSections: string[];
+    /**
+     * @implements A-SPEC-146
+     * Fields `spec_create` scaffolds but `validateSpec` does NOT require. The gap is deliberate and
+     * measured: a field that is required by the state predicate invalidates every already-approved
+     * spec that predates it — for `breaking_change` that was 38 ART-3 violations and a Stop hook
+     * blocking every turn. Such a duty belongs to the ACT that changes a spec, not to the document's
+     * static validity, while the stub keeps the field visible to whoever writes the next one.
+     */
+    stubOnlyFields?: string[];
+}
+export declare const SPEC_ORDER: SpecType[];
+/**
+ * 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.
+ */
+export declare const CITATION_KINDS: readonly ["user-request", "conversation", "plan", "adr", "architecture", "analysis", "issue", "wiki", "incident", "code-review", "regulation", "other"];
+export type CitationKind = typeof CITATION_KINDS[number];
+/**
+ * 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.
+ */
+export declare const MUTABLE_CITATION_KINDS: readonly CitationKind[];
+export interface Citation {
+    /** What sort of source this is. Drives which adapter can later resolve `ref`. */
+    kind: CitationKind;
+    /** A locator that identifies the source: URL, ticket id, document path, decision id. */
+    ref: string;
+    /**
+     * Pins WHAT was read. REQUIRED for every mutable source kind (see `MUTABLE_CITATION_KINDS`).
+     *
+     * The canonical form is a CONTENT DIGEST of the source as it was read — `sha256:<hex>`. That form
+     * is source-agnostic (any wiki page, ticket payload, or file can be hashed), needs no git, and is
+     * the only form that actually does this field's job: re-fetch, re-hash, compare, and an upstream
+     * edit becomes visible. It is also the idiom this project already uses everywhere else — the
+     * provenance chain's computeHash, the scan cache's hashOf, authorizationRef's token fingerprint.
+     *
+     * A source's own version handle is accepted too when it is content-derived or monotonic: a git
+     * sha, a Confluence page version, a JIRA `updated` timestamp, an HTTP ETag.
+     *
+     * A FRESHLY MINTED UNIQUE TOKEN IS NOT ACCEPTABLE. A random id assigned at citation time
+     * identifies the act of citing, not the state of the content: the wiki page changes and the token
+     * does not, so drift becomes undetectable and the citation quietly starts lying. The value must be
+     * derived FROM the source, never generated ALONGSIDE it.
+     *
+     * The string itself is stored opaquely — nothing parses it — but its provenance value depends
+     * entirely on being derived from content.
+     */
+    rev?: string;
+    /**
+     * ISO date (YYYY-MM-DD) the source was read.
+     *
+     * The universal fallback. Every source can be dated even when it cannot be versioned, so this is
+     * what keeps the schema usable in a non-git environment, against a system with no revision API,
+     * or for a source that only ever existed in a conversation.
+     */
+    retrieved?: string;
+    /** What was actually taken from the source. */
+    note?: string;
+}
+/** Placeholder a freshly created spec carries until its author supplies a real citation. */
+export declare const CITATION_PLACEHOLDER = "TODO";
+export declare const SPEC_TYPES: Record<SpecType, SpecTypeDef>;
+/**
+ * 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.
+ */
+export declare function specTypeDef(type: string | undefined | null): SpecTypeDef | undefined;
+export declare function isGoverned(spec: {
+    type?: SpecType;
+}): boolean;
+export declare function filterGoverned<T extends {
+    type?: SpecType;
+}>(specs: T[]): T[];
+/**
+ * @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.
+ */
+export declare const 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.
+ */
+export declare function specTypeOfId(id: string): SpecType | 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.
+ */
+export declare function parentRuleText(): string;

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

@@ -0,0 +1,65 @@
+import { Spec } from './spec-parser';
+export interface Finding {
+    level: 'error' | 'warn';
+    code: string;
+    message: string;
+}
+export interface ValidationResult {
+    ok: boolean;
+    findings: Finding[];
+}
+/**
+ * The canonical `rev` value for a citation: a content digest of the source as it was read.
+ *
+ * Deliberately computed from bytes with node:crypto and nothing else — no git, no network, no
+ * tracker API. A purely local harness with a wiki page saved to disk, a repository with no VCS, and
+ * an air-gapped machine all produce the same value for the same content, which is what makes this
+ * the one `rev` scheme that is always available. Truncated to 16 hex chars: this detects drift, it
+ * does not resist a motivated forger, and the surrounding provenance chain is what covers that.
+ */
+export declare function citationDigest(content: string | Uint8Array): string;
+export interface PinResult {
+    /** The citation list with newly computed digests filled in. Unchanged entries are preserved. */
+    citations: unknown[];
+    /** `ref`s that gained a digest. */
+    pinned: string[];
+    /** Findings: drift on already-pinned entries, and refs that could not be resolved. */
+    findings: Finding[];
+}
+/**
+ * Fill in `rev` for citations whose `ref` resolves to readable content and that have none yet —
+ * the authoring counterpart of verifyCitationDigests, so nobody has to hash a file by hand.
+ *
+ * NEVER OVERWRITES AN EXISTING rev. That restriction is the whole safety property: re-pinning a
+ * stale citation would silently replace the evidence of drift with a fresh-looking digest, turning
+ * the one mechanism that detects upstream change into the mechanism that hides it. When an existing
+ * digest no longer matches, this reports drift and leaves the stored value alone — resolving it is a
+ * human decision (re-read the source and confirm the requirement still holds), not a rewrite.
+ *
+ * Pinning asserts "this content is what I am citing", so it only ever runs when explicitly invoked.
+ */
+export declare function pinCitations(citations: unknown, read: (ref: string) => string | Uint8Array | null): PinResult;
+/**
+ * Re-derive each citation's digest and report the ones that no longer match — the step that turns a
+ * stored `rev` string from decoration into actual drift detection.
+ *
+ * `read` resolves a `ref` to the source's current bytes, returning null when it cannot be fetched
+ * (an external ticket with no adapter configured, a deleted file). Unfetchable is NOT a failure: the
+ * point is to flag sources that DID change, not to demand that every citation be resolvable in every
+ * environment. Injected rather than importing fs so the rule stays pure and testable.
+ */
+export declare function verifyCitationDigests(citations: unknown, read: (ref: string) => string | Uint8Array | null): Finding[];
+/**
+ * Validate a REQ's `source` as a list of structured citations.
+ *
+ * Two tiers, mirroring how the T-SPEC coverage gate works. SHAPE problems are always errors — a
+ * citation the machine cannot parse is worse than none, because it looks like provenance. COMPLETENESS
+ * problems (a placeholder ref, no revision and no read date) are warnings while the REQ is still being
+ * written and become errors on approval, so a spec can be created and iterated without fighting the
+ * validator, but cannot be APPROVED while its provenance is a stub.
+ *
+ * Exported for direct testing: this is the rule set that decides whether a requirement's origin is
+ * auditable, and it should be pinned independently of the surrounding spec checks.
+ */
+export declare function validateCitations(value: unknown, approved: boolean): Finding[];
+export declare function validateSpec(spec: Spec, resolve: (id: string) => Spec | null): ValidationResult;

package/package.json

@@ -1,9 +1,10 @@
 {
   "//": "@implements A-SPEC-209",
   "name": "@holmes-lab/holmes-kit",
-  "version": "0.1.6",
+  "version": "0.1.8",
   "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",
   "bin": {
     "holmes-kit": "bin/holmes-kit.js",
     "holmes-mcp": "bin/holmes-mcp.js"
@@ -68,11 +69,11 @@
   },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/snpark-io/holmes-kit.git"
+    "url": "git+https://github.com/holmes-kit/holmes-kit.git"
   },
-  "homepage": "https://github.com/snpark-io/holmes-kit#readme",
+  "homepage": "https://github.com/holmes-kit/holmes-kit#readme",
   "bugs": {
-    "url": "https://github.com/snpark-io/holmes-kit/issues"
+    "url": "https://github.com/holmes-kit/holmes-kit/issues"
   },
   "publishConfig": {
     "access": "public"