@holmes-lab/holmes-kit 0.17.0 → 0.18.0

package/CHANGELOG.md

@@ -5,6 +5,64 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 <!-- @implements A-SPEC-209 -->
+## [0.18.0] - 2026-09-08
+
+Decisions become governed. A consuming project's operational decisions had been leaking into agent
+memory outside the gate — because Holmes-Kit accepted functional contracts (REQ→H→A→T) but had no
+slot for a **decision**. Now it does, and it reuses machinery already present rather than inventing
+a channel.
+
+### Added
+- **ADR as a first-class governed spec type (REQ-571)** — `spec_create(type: "ADR")` (refused as
+  "unknown spec type" through 0.17.0) now scaffolds a root decision document under `06_adr`
+  (sections Context / Decision / Consequences / Alternatives; fields `decided` / `decider`) and
+  inherits the store's full authoring governance: validate → `spec_approve` seal
+  (`approved_digest` + ledger) → post-seal tamper-block. Three deliberate boundaries: an ADR
+  carries **no** T-SPEC / `@implements` / Files-to-Touch duty (a decision is not a functional
+  contract — a separate axis from No-Spec-No-Code); it lives in its **own number space** (a
+  consuming project's existing `ADR-0001` neither blocks nor is blocked by the functional chain's
+  max); and its seal is **hitl-only** (autonomy never self-approves a decision, like an upstream
+  REQ/H-SPEC/C-SPEC).
+- **Store ADRs join the existing decision surface with zero new edge kinds (REQ-571)** — a store
+  ADR merges into the `collectDecisions` population (store wins on id collision with a legacy
+  `.ax/decisions/` entry, which coexists for back-compat), so `ADR-XXXX` citations in specs and
+  source become `constrained_by` edges, `supersedes` chains link, and the DECISION node appears —
+  all through machinery that already shipped. The graph's `SPEC:ADR` node carries the Decision
+  line as its intent summary (intent-layer parity), and the citation system recognizes `ADR-\d+`
+  (recognition only — the lexical match-scoring population stays A-SPEC-limited, so an ADR never
+  admits or reorders a file). A migration guide for consuming projects ships at
+  `docs/adr-migration.md`.
+
+- **The graph advisory now arrives at DESIGN time (REQ-572)** — measured on our own work: the
+  sealing advisory for a slice named `validator.ts` / `legacy-format.ts` / `rtm-check.ts` /
+  `constitution.ts`, three regressions landed in exactly that cluster, and the agent read none of
+  it until the suite went red. The calculation was never the gap; the **delivery time** was. So the
+  read-only `approval_status` — already the "what is blocking this right now" tool — also answers
+  `graphPreview`: `impact` (files calling INTO your declared Files-to-Touch from outside, each
+  anchor carrying its spec's intent sentence) and `density` (anchor-dense files inside the scope),
+  computed by the **same functions `spec_approve` calls**, so a preview can never disagree with the
+  seal. Read-only stays read-only: no scan, no build, and **no ledger append** (a query must not
+  pollute the observation denominator); every failure degrades to an absent field. Both authoring
+  playbooks now carry the step — read the impact before freezing Files-to-Touch, then either widen
+  the declaration, narrow the design, or leave it knowingly — pinned by test so the instruction
+  cannot evaporate. It stays a **discipline, not a gate** (hard-gate promotion waits on the
+  observation ledger's false-positive rate).
+- **Root-cause analysis carries the decision context (REQ-572)** — `maintenance_analyze` candidates
+  now ride with `decisionContext`: the ADRs constraining that file (directly, or through the specs
+  it anchors) and each decision's own sentence. That is the order a person diagnoses in — what
+  broke, then why it was left this way — and it needs no new mechanism: ADRs entered the graph with
+  REQ-571 and `constrained_by` has been built from citations since A-SPEC-293. Information only,
+  capped, never an input to the ranking.
+
+### Notes
+- Version bump is **minor** carrying one `gate-behavior` change (the new ADR type is accepted where
+  it was refused); the release classifier routes this to HITL by design. The four existing spec
+  types are unchanged — verdicts pinned across the suite.
+- REQ-572's own last slice was authored **through** the new design-time read: the preview reported
+  `maintenance-analyze.ts` at 35 anchors and `handlers.ts` at 83 (p90 = 7), so the decision-context
+  logic went into a new pure module instead of thickening either file. First recorded case of the
+  advisory changing a design before the code was written.
+
 ## [0.17.0] - 2026-09-07
 
 An adversarial review of 0.16.0's own new surfaces, run against the shipped tarball the day it

package/README.md

@@ -16,6 +16,9 @@
 
 ### 🛡️ Currently Supported Features (Production Features)
 
+- 🧭 **The graph speaks BEFORE you commit to a scope** *(new in 0.18.0)*: the read-only `approval_status` now also answers `graphPreview` — `impact` (files that call INTO your declared Files-to-Touch from outside it, each anchor carrying its spec's intent sentence) and `density` (anchor-dense files inside the scope) — computed by the **same functions the sealing advisory uses**, so the preview can never disagree with the seal. Read the impact, then widen the declaration, narrow the design, or leave it knowingly; the authoring playbooks carry the step (pinned by test) and it stays a discipline, not a gate. Root-cause work gets the other half: `maintenance_analyze` candidates ride with `decisionContext` — the ADRs constraining that file and each decision's own sentence — which is the order a person diagnoses in (what broke, then why it was left this way). Both are information only: value tests pin that no ranking, score or gate reads them.
+- 📜 **ADR as a first-class governed document** *(new in 0.18.0)*: decisions stop leaking into agent memory outside the gate (a measured incident on a consuming project drove this). `spec_create(type: "ADR")` scaffolds a root decision document (Context / Decision / Consequences / Alternatives, `decided`/`decider`) under the store's full authoring governance — validate, `spec_approve` seal, ledger, tamper-block — with its **own number space** (your existing `ADR-0001` just works) and a **hitl-only seal** (autonomy never self-approves a decision). Store ADRs join the existing decision surface with zero new edge kinds: `ADR-XXXX` citations in specs/code become `constrained_by` edges, `supersedes` chains link, the graph's SPEC:ADR node carries the Decision line as its intent summary, and legacy `.ax/decisions/` entries coexist (store wins on id collision). A migration guide ships at `docs/adr-migration.md`.
+
 - 📣 **Impact Advisory at sealing time** *(new in 0.16.0)*: approving an A-SPEC now returns what your Files-to-Touch declaration *missed* — files whose symbols **call into** the declared scope from outside it (1-hop, capped, repo-relative allow-list), computed from the persisted RTM graph at the moment of sealing. Advisory, never verdict: it rides the response *after* the seal commits, degrades to absence on any failure, and every emission lands in an observation ledger so its false-positive rate is **measured before** anyone proposes a hard gate. The graph keeps itself fresh — `rtm_impact` rebuilds on basis drift and the Stop hook spawns a TTL-gated detached reindex (staleness was measured as the advisory's quality factor: 7 findings on an 8-day-old graph, 17 after a fresh one). *(0.17.0 hardening)*: the advisory/impact graph is **approved-only** (a draft needs no approval to exist, so it can no longer reach these agent-visible channels), summary prose can't forge graph rows (structural characters fold at both the extraction and storage boundaries), and annotations are capped with explicit omission counts (a hub-grade response shrank 104.7KB → 18.7KB, −82%). Sealing also gains an **anchor-density advisory** (observation-only): an A-SPEC whose Files-to-Touch contains an anchor-dense file (live anchors ≥ max(8, p90)) is annotated with `anchorDensity: [{path, anchors, p90}]` and ledgered — grounded in the measured precision tax of anchor accumulation; a count *gate* was considered and refused.
 - 🗣️ **The graph speaks intent** *(new in 0.16.0)*: every SPEC node stores a one-sentence intent summary (`"<title> — <first sentence of its intent section>"`, schema `rtm-graph/3`, old stores rebuild automatically) — extracted deterministically, **never generated** (same store, byte-identical graph; measured cost +6.4% build time / +4.2% file size). Advisory anchors arrive as `{id, summary}` and `rtm_impact` adds `impactedSummaries`, so the reader sees *which intent* is at risk without a spec-store round trip. Information only: value tests pin that no verdict, ranking or gate reads the prose.
 - 📇 **Session-context observability** *(new in 0.16.0)*: the ledger records which agent/model drove a session and what the governance overhead cost, per replica (`session-context.<replica>.jsonl`), grounding field reports in machine attribution instead of guesswork.

package/dist/.build-id

@@ -1 +1 @@
-20f5f64-mtrggtxw
+cc24589-mtrjegw0

package/dist/holmes/governance/autonomy.js

@@ -133,6 +133,7 @@ function specApprovalAutonomy(spec, _resolveParent) {
         case 'REQ':
         case 'H-SPEC':
         case 'C-SPEC':
+        case 'ADR': // @implements A-SPEC-571.1 — a decision is the human's to seal
             return 'hitl'; // wide blast radius / structural constraint
         case 'A-SPEC': {
             const grade = breakingGrade(spec);

package/dist/holmes/mcp/handlers.d.ts

@@ -1,6 +1,9 @@
 import { SpecStore } from '../spec/spec-store';
+import { Spec } from '../spec/spec-parser';
 import { MaintenanceGroundTruth, MaintenanceAnalysis } from './maintenance-analyze';
 import { Action } from '../guardrail/phase';
+import { ScannedFile } from '../cpg/cpg-scanner';
+import { type DecisionRecord, type DecisionCitation } from '../rtm/rtm-builder';
 import { Basis } from './basis';
 import { Finding } from '../review/findings';
 import { Approval, Enforcement } from '../guardrail/risk-gate';
@@ -53,6 +56,16 @@ export declare function makeHandlers(store: SpecStore, opts?: ElicitOpts): RawHa
     }>;
 };
 type RawHandlers = ReturnType<typeof makeRawHandlers>;
+/**
+ * @implements A-SPEC-293
+ * Read `.ax/decisions/*.md` and find who cites them. Citation is the link, chosen by measurement:
+ * `governs` resolves 9 of 65 names to symbols while 37 source files and 71 spec files cite an ADR.
+ * Failure here is never fatal — a project with no decisions directory simply has no decisions.
+ */
+export declare function collectDecisions(root: string, scanned: readonly ScannedFile[], specs: readonly Spec[]): {
+    decisions: DecisionRecord[];
+    citations: DecisionCitation[];
+};
 declare function makeRawHandlers(store: SpecStore, opts?: ElicitOpts): {
     spec_create(a: any): Promise<{
         ok: boolean;
@@ -207,6 +220,11 @@ declare function makeRawHandlers(store: SpecStore, opts?: ElicitOpts): {
         ok: boolean;
         reason: string;
     } | {
+        graphPreview?: {
+            impact?: import("../rtm/impact-advisory").ImpactAdvisory;
+            density?: import("../rtm/anchor-density").AnchorDensityFinding[];
+            graphAsOf?: string;
+        } | undefined;
         id: string;
         type?: string;
         status: string;

package/dist/holmes/mcp/handlers.js

@@ -37,6 +37,7 @@ exports.HandlerRefusal = void 0;
 exports.isHandlerRefusal = isHandlerRefusal;
 exports.unreadableAmong = unreadableAmong;
 exports.makeHandlers = makeHandlers;
+exports.collectDecisions = collectDecisions;
 // @implements A-SPEC-293
 // @implements A-SPEC-292
 // @implements A-SPEC-290
@@ -699,8 +700,24 @@ function collectDecisions(root, scanned, specs) {
             });
         }
     }
-    catch {
-        return { decisions: [], citations: [] };
+    catch { /* @implements A-SPEC-571.2 — no legacy .ax/decisions dir is not "no decisions": store
+      ADRs below are still a source. An unreadable dir degrades to the empty legacy set, not an early
+      return that would skip the store population. */
+    }
+    // @implements A-SPEC-571.2 — store ADRs JOIN the decisions population, so the existing consumers
+    // (DECISION nodes, constrained_by citations, supersedes) light up with no new edge kind. A store
+    // ADR is the canon: same id in legacy .ax/decisions is replaced (store wins).
+    for (const spec of specs) {
+        if (spec.type !== 'ADR')
+            continue;
+        const sup = spec.frontmatter?.supersedes;
+        const supersedes = typeof sup === 'string' && sup.trim() && sup.trim() !== 'null' ? sup.trim() : null;
+        const idx = decisions.findIndex((d) => d.id === spec.id);
+        const rec = { id: spec.id, title: spec.title, status: spec.status, supersedes };
+        if (idx >= 0)
+            decisions[idx] = rec;
+        else
+            decisions.push(rec);
     }
     const ids = new Set(decisions.map((d) => d.id));
     // @implements A-SPEC-546.1 — recognise ADR-\d{3,} (4-digit ADRs no longer invisible), via a pure fn.
@@ -1330,7 +1347,58 @@ function makeRawHandlers(store, opts) {
                 const unreadable = typeof dir === 'string' ? (0, spec_store_1.unreadableSpecFiles)(dir) : [];
                 return { ok: false, reason: (0, spec_store_1.notFoundReason)(a.id, unreadable) };
             }
-            return { ok: true, ...(0, approval_status_1.describeApproval)(cur.spec, resolver(all)) };
+            // @implements A-SPEC-572.1
+            // The graph advisory, delivered at DESIGN time. Measured on our own work: A-SPEC-571.1's
+            // sealing advisory named the exact cluster three regressions then landed in — and by then
+            // the design was done. The calculation was never the gap; the delivery time was. So the
+            // read-only "what is blocking this right now" tool also answers "what will this scope leak,
+            // and where is it dense" — using the SAME functions spec_approve calls, so the preview can
+            // never disagree with the seal. Read-only stays read-only: no scan, no build, no ledger
+            // append (a query must not pollute the observation denominator), and every failure degrades
+            // to an absent field on an otherwise identical response.
+            let graphPreview;
+            try {
+                if (cur.spec.type === 'A-SPEC' && a.root) {
+                    const dbPath = path.join(a.root, '.ax', 'rtm.sqlite');
+                    if (fs.existsSync(dbPath)) {
+                        const { declaredImpactGap } = require('../rtm/impact-advisory');
+                        const { anchorDensityFindings } = require('../rtm/anchor-density');
+                        const { filesToTouch } = require('../spec/compat-impact');
+                        const { RtmGraph } = require('../rtm/rtm-graph');
+                        const graph = new RtmGraph(dbPath);
+                        try {
+                            const ftt = filesToTouch(cur.spec);
+                            const impact = declaredImpactGap(ftt, graph, (rel) => { try {
+                                return fs.readFileSync(path.join(a.root, rel), 'utf8');
+                            }
+                            catch {
+                                return null;
+                            } });
+                            const density = anchorDensityFindings(ftt, graph.implementsAnchorCounts());
+                            if (impact || density.length > 0) {
+                                const graphAsOf = (() => { try {
+                                    return fs.statSync(dbPath).mtime.toISOString();
+                                }
+                                catch {
+                                    return undefined;
+                                } })();
+                                graphPreview = {
+                                    ...(impact ? { impact } : {}),
+                                    ...(density.length > 0 ? { density } : {}),
+                                    ...(graphAsOf ? { graphAsOf } : {}),
+                                };
+                            }
+                        }
+                        finally {
+                            graph.close();
+                        }
+                    }
+                }
+            }
+            catch {
+                graphPreview = undefined;
+            }
+            return { ok: true, ...(0, approval_status_1.describeApproval)(cur.spec, resolver(all)), ...(graphPreview ? { graphPreview } : {}) };
         },
         /**
          * @implements A-SPEC-538.3

package/dist/holmes/mcp/maintenance-analyze.d.ts

@@ -3,6 +3,7 @@ import type { Spec } from '../spec/spec-parser';
 import type { RtmGraph } from '../rtm/rtm-graph';
 import type { ContextBundle } from '../context/bundler';
 import { type TestScope } from '../rtm/test-scope';
+import { type DecisionContextEntry } from '../rtm/decision-context';
 import type { ResolutionReport } from '../rtm/rtm-builder';
 import { type TestEvidence } from '../review/test-evidence';
 import { type LanguageGap } from '../cpg/language-capability';
@@ -212,6 +213,8 @@ export interface MaintenanceAnalysis {
         score: number;
         symbols: string[];
         evidence: string[];
+        /** @implements A-SPEC-572.3 — decisions constraining this candidate; information only. */
+        decisionContext?: DecisionContextEntry[];
     }>;
     /**
      * @implements A-SPEC-494 — the semantic ALTERNATES: top-3 cached-vector cosines among files

package/dist/holmes/mcp/maintenance-analyze.js

@@ -26,6 +26,11 @@ const scope_1 = require("../review/scope");
 // the measured numbers transfer to the shipped surface.
 const assoc_arm_1 = require("../assoc/assoc-arm");
 const acceptance_quality_1 = require("../spec/acceptance-quality");
+// @implements A-SPEC-572.3 — the decision lookup lives in its own pure module: this file
+// already carries 35 anchors (p90 is 7), and the design-time density advisory said so BEFORE
+// this slice fixed its Files-to-Touch. Adding logic here would have made the file denser; the
+// call site is one line, the logic is next door.
+const decision_context_1 = require("../rtm/decision-context");
 const taint_1 = require("../rtm/taint");
 const test_evidence_1 = require("../review/test-evidence");
 const language_capability_1 = require("../cpg/language-capability");
@@ -377,6 +382,21 @@ function analyzeMaintenance(input) {
         symbols: sortedUnique(hit.matchedSymbols),
         evidence: [...hit.why],
     }));
+    // @implements A-SPEC-572.3
+    // "What broke" then "why is it this way" — the order a person diagnoses in. The decisions are
+    // already in the graph (REQ-571 put store ADRs there; A-SPEC-293 builds `constrained_by` from
+    // citations), so this is a lookup, not a new mechanism. Information only: it rides beside a
+    // candidate and never enters the score or the ordering above.
+    {
+        const anchorsOf = new Map(scanned.map((f) => [f.sourcePath, f.implementsSpecs ?? []]));
+        const ctx = (0, decision_context_1.decisionContextFor)(candidates.map((c) => c.file), (file) => anchorsOf.get(file) ?? [], input.graph);
+        for (const candidate of candidates) {
+            const entries = ctx.get(candidate.file);
+            if (entries && entries.length > 0) {
+                candidate.decisionContext = entries;
+            }
+        }
+    }
     // @implements A-SPEC-478 — the uncited semantic head rerank, exactly the arm S-495 measured:
     // same math (cosine over cached doc vectors, pool FIXED), same gate (the request cited no
     // spec). The gate is load-bearing both ways — uncited corpora gained +26%/+93% at the head,

package/dist/holmes/mcp/spec-id-guard.d.ts

@@ -15,12 +15,4 @@ export type IdVerdict = {
     reason: string;
     nextAvailable: number;
 };
-/**
- * 새 id 의 base 가 코퍼스 max base 를 한 칸 넘게 뛰면 거부한다.
- *
- * - 빈 코퍼스, 또는 base 를 못 뽑는 id → 통과(비교 대상이 없거나, 형태 검증은 별도 소관이라 한 결함에
- *   두 이름을 주지 않는다).
- * - base ≤ maxBase(갭 메우기·체인 완성) 또는 base == maxBase+1(새 체인) → 통과.
- * - base > maxBase+1(leap) → 거부, 다음 가용 번호를 문면과 필드에 댄다.
- */
 export declare function sequentialIdVerdict(newId: string, existingIds: string[]): IdVerdict;

package/dist/holmes/mcp/spec-id-guard.js

@@ -30,11 +30,20 @@ function specIdBase(id) {
  * - base ≤ maxBase(갭 메우기·체인 완성) 또는 base == maxBase+1(새 체인) → 통과.
  * - base > maxBase+1(leap) → 거부, 다음 가용 번호를 문면과 필드에 댄다.
  */
+/** The id's number SPACE. @implements A-SPEC-571.1 — ADR keeps its own sequence so a decision
+ * (jarvis's ADR-0001) neither blocks nor is blocked by the functional chain's max. Everything
+ * else shares one space, exactly as before. */
+function idSpaceOf(id) {
+    return /^ADR-/.test(id.trim()) ? 'ADR' : 'functional';
+}
 function sequentialIdVerdict(newId, existingIds) {
     const base = specIdBase(newId);
     if (base === null)
         return { ok: true };
-    const bases = (existingIds ?? []).map(specIdBase).filter((n) => n !== null);
+    // @implements A-SPEC-571.1 — compare only within the same number space.
+    const space = idSpaceOf(newId);
+    const bases = (existingIds ?? []).filter((id) => idSpaceOf(id) === space)
+        .map(specIdBase).filter((n) => n !== null);
     if (bases.length === 0)
         return { ok: true };
     const maxBase = Math.max(...bases);

package/dist/holmes/rtm/decision-context.d.ts

@@ -0,0 +1,23 @@
+/**
+ * The DECISION context of a candidate — "why is this the way it is?".
+ *
+ * A person diagnosing a defect asks two questions in order: what broke (the candidates), and then
+ * why this code was left this way (the decision). The graph already answers the second — REQ-571
+ * put store ADRs into the decision population and A-SPEC-293 already builds `constrained_by` from
+ * citations — so this is a lookup, not a new mechanism: no new edge kind, no new tool.
+ *
+ * OBSERVATION ONLY. The context rides beside a candidate; nothing here enters the ranking, the
+ * score, or any gate (the c6 rule — prose informs, it never adjudicates).
+ */
+export interface DecisionContextEntry {
+    adr: string;
+    /** The decision's own sentence, or null when the store carries no summary for it (id stays). */
+    decision: string | null;
+}
+export interface DecisionGraphLike {
+    decisionsConstraining(nodeIds: readonly string[]): string[];
+    summaryOf(id: string): string | null;
+}
+/** How many decisions ride beside one candidate. A prose constant — never a verdict input. */
+export declare const MAX_DECISIONS = 3;
+export declare function decisionContextFor(files: readonly string[], specIdsOf: (file: string) => readonly string[], graph: DecisionGraphLike): Map<string, DecisionContextEntry[]>;

package/dist/holmes/rtm/decision-context.js

@@ -0,0 +1,47 @@
+"use strict";
+// @implements A-SPEC-572.3
+/**
+ * The DECISION context of a candidate — "why is this the way it is?".
+ *
+ * A person diagnosing a defect asks two questions in order: what broke (the candidates), and then
+ * why this code was left this way (the decision). The graph already answers the second — REQ-571
+ * put store ADRs into the decision population and A-SPEC-293 already builds `constrained_by` from
+ * citations — so this is a lookup, not a new mechanism: no new edge kind, no new tool.
+ *
+ * OBSERVATION ONLY. The context rides beside a candidate; nothing here enters the ranking, the
+ * score, or any gate (the c6 rule — prose informs, it never adjudicates).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_DECISIONS = void 0;
+exports.decisionContextFor = decisionContextFor;
+/** How many decisions ride beside one candidate. A prose constant — never a verdict input. */
+exports.MAX_DECISIONS = 3;
+function decisionContextFor(files, specIdsOf, graph) {
+    const out = new Map();
+    for (const file of files) {
+        let adrs = [];
+        try {
+            // The file itself AND the specs it anchors: a person chasing "why" follows both, and the
+            // constraint is often recorded one level up, on the spec rather than on the file.
+            adrs = graph.decisionsConstraining([
+                `FILE:${file}`,
+                ...specIdsOf(file).map((id) => `SPEC:${id}`),
+            ]);
+        }
+        catch {
+            continue;
+        } // an unreadable graph yields no context, never a throw
+        const shown = [...new Set(adrs)].sort().slice(0, exports.MAX_DECISIONS);
+        if (shown.length === 0)
+            continue; // no entry rather than an invented empty list
+        out.set(file, shown.map((adr) => {
+            let decision = null;
+            try {
+                decision = graph.summaryOf(`SPEC:${adr}`);
+            }
+            catch { /* id stays, prose does not */ }
+            return { adr, decision };
+        }));
+    }
+    return out;
+}

package/dist/holmes/rtm/localize.js

@@ -10,8 +10,10 @@ exports.localizeIssue = localizeIssue;
  * repository's `S-<n>` slice shorthand (which names the whole REQ->T-SPEC chain at that number).
  * The prefix is REQUIRED — a bare `262` in "262 files were rewritten" is a number, not a citation.
  */
-const CITATION = /\b(?:(A-SPEC|H-SPEC|T-SPEC|C-SPEC|REQ)-(\d+(?:\.\d+)?)|S-(\d+(?:\.\d+)?))\b/gi;
-const CITABLE_KINDS = ['REQ', 'H-SPEC', 'A-SPEC', 'T-SPEC', 'C-SPEC'];
+// @implements A-SPEC-571.2 — ADR is citable like any governed id (recognition only; the match
+// SCORING population stays A-SPEC-limited below, so an ADR never admits or reorders a file).
+const CITATION = /\b(?:(A-SPEC|H-SPEC|T-SPEC|C-SPEC|ADR|REQ)-(\d+(?:\.\d+)?)|S-(\d+(?:\.\d+)?))\b/gi;
+const CITABLE_KINDS = ['REQ', 'H-SPEC', 'A-SPEC', 'T-SPEC', 'C-SPEC', 'ADR'];
 /**
  * @implements A-SPEC-273
  * How much a citation is worth, normalized by the file's anchor count exactly as the lexical spec

package/dist/holmes/rtm/rtm-builder.js

@@ -73,6 +73,8 @@ const INTENT_SECTION = {
     'REQ': 'Problem / Need',
     'H-SPEC': 'Intent',
     'A-SPEC': 'Objective',
+    // @implements A-SPEC-571.2 — a decision's intent IS its Decision line.
+    'ADR': 'Decision',
 };
 /** Longest intent sentence carried into the graph — a bound, applied deterministically. */
 const SUMMARY_SENTENCE_CAP = 200;

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

@@ -1,4 +1,4 @@
-export type SpecType = 'REQ' | 'H-SPEC' | 'A-SPEC' | 'C-SPEC' | 'T-SPEC';
+export type SpecType = 'REQ' | 'H-SPEC' | 'A-SPEC' | 'C-SPEC' | 'T-SPEC' | 'ADR';
 export declare const SPEC_STATUSES: readonly ["draft", "review", "approved", "outdated"];
 export type SpecStatus = (typeof SPEC_STATUSES)[number];
 export interface SpecTypeDef {

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

@@ -12,7 +12,9 @@ exports.parentRuleText = parentRuleText;
 // 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'];
+// @implements A-SPEC-571.1 — ADR trails the functional chain: spec_next serves the REQ→…→T-SPEC
+// order first, and a decision is off that critical path.
+exports.SPEC_ORDER = ['REQ', 'H-SPEC', 'A-SPEC', 'C-SPEC', 'T-SPEC', 'ADR'];
 /**
  * Where a requirement came from.
  *
@@ -102,6 +104,17 @@ exports.SPEC_TYPES = {
         requiredFields: ['coverage'],
         requiredSections: ['Normal Cases', 'Corner Cases', 'Negative Cases', 'Boundary Cases'],
     },
+    // @implements A-SPEC-571.1
+    // A DECISION, not a functional contract: a root type (no parent, like REQ) that records why a
+    // choice was made and inherits the store's authoring governance (stub → validate → seal → ledger
+    // → tamper-block). It carries NO T-SPEC/anchor/FtT duty — that is the No-Spec-No-Code chain, a
+    // separate axis. Its number space is its own (see spec-id-guard), so jarvis's ADR-0001 does not
+    // collide with the functional chain's max. 4-digit zero-padded ids are accepted (ADR-0001).
+    'ADR': {
+        type: 'ADR', idRegex: /^ADR-\d{3,}$/, example: 'ADR-0001', folder: '06_adr', parents: [],
+        requiredFields: ['decided', 'decider'],
+        requiredSections: ['Context', 'Decision', 'Consequences', 'Alternatives'],
+    },
 };
 // @implements A-SPEC-100.1
 /**

package/package.json

@@ -1,7 +1,7 @@
 {
   "//": "@implements A-SPEC-209",
   "name": "@holmes-lab/holmes-kit",
-  "version": "0.17.0",
+  "version": "0.18.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/author-slice/PLAYBOOK.md

@@ -82,6 +82,25 @@ Criteria · Non-Functional · Assumptions · Open Questions.** 필수 필드: `r
 부모 REQ의 Success Criteria가 이 설계로 어떻게 달성되는지가 본문이다. Open Questions는 비워두는
 칸이 아니다 — 아직 결정하지 않은 것을 결정하지 않았다고 적는 곳이고, 닫을 때는 근거와 함께 닫는다.
 
+## Files to Touch를 확정하기 전에 — 설계-시점 영향 범위 읽기
+
+A-SPEC의 Files to Touch는 **스코프 선언**이고, 그래프는 그 선언이 무엇을 빠뜨리는지 이미 안다.
+`approval_status(id)`를 부르면 `graphPreview`가 온다:
+
+- `impact` — 선언한 FtT **밖**에서 그 안으로 호출해 들어오는 파일들(1-hop). 각 파일의 앵커 옆에
+  그 스펙의 **의도 문장**이 붙으므로, "무슨 의도가 걸려 있는지"를 스토어를 열지 않고 읽는다.
+- `density` — FtT 안의 **앵커-과밀** 파일(live 앵커가 분포 상위이며 절대치도 큰 것). 새 로직을
+  거기 더할지, 새 파일로 뺄지 판단하는 근거다.
+
+읽고 나서 셋 중 하나를 **선택**한다: ①지목된 밖-파일을 FtT에 넣는다 ②스코프를 좁혀 그 파급이
+생기지 않게 설계를 바꾼다 ③근거를 갖고 그대로 둔다. 어느 쪽이든 선언은 이제 **알고 한 선언**이다.
+
+> [!NOTE]
+> **게이트는 이것을 막지 않는다** — 규율이지 차단이 아니다(하드 게이트 승격은 관측 원장이
+> 오탐률을 답한 뒤의 별도 결정). 다만 읽지 않고 확정하면, 같은 소견이 봉인 뒤에 같은 말을
+> 반복한다 — 실사고 기록: 봉인 소견이 지목한 파일 클러스터에서 회귀 3건이 났고, 그 소견은
+> 설계가 끝난 뒤에야 읽혔다.
+
 ## A-SPEC / T-SPEC에 쓰는 것
 
 A-SPEC 필수 섹션: **Objective · Inputs / Outputs · Behavior · Test Points · Files to Touch · Done

package/playbooks/tdd-slice/PLAYBOOK.md

@@ -69,6 +69,11 @@ holmes는 기계적으로 판별한다: `red-error`로는 red→green 시퀀스
 
 ## 절차
 
+0. **FtT 확정 전** `approval_status(<A-SPEC id>)`의 `graphPreview`로 영향 범위를 읽는다 —
+   `impact`(선언 밖에서 들어오는 1-hop 호출자, 의도 문장 병기)와 `density`(앵커-과밀 파일). 지목된
+   것을 FtT에 넣을지, 스코프를 좁힐지, 근거를 갖고 둘지 **정하고 나서** 아래로 간다. 게이트가
+   **게이트는 이것을 막지 않는다** — 규율이지 차단이 아니다. 다만 읽지 않으면
+   같은 소견을 봉인 뒤에 다시 듣는다(실사고 기록).
 1. `promote-slice`로 대상 A-SPEC과 그 T-SPEC을 승인한다(`[ART-1]` 게이트를 연다).
 2. 커버 테스트를 **먼저** 쓴다. 심볼이 없어 컴파일이 깨지면 틀린-값 스텁을 넣는다.
 3. `test_run` — **red-assertion**을 본다. `red-error`면 그건 아직 RED가 아니다; 스텁으로 고쳐라.