@holmes-lab/holmes-kit 0.1.0

package/dist/holmes/spec/validator.js

@@ -0,0 +1,280 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.citationDigest = citationDigest;
+exports.pinCitations = pinCitations;
+exports.verifyCitationDigests = verifyCitationDigests;
+exports.validateCitations = validateCitations;
+exports.validateSpec = validateSpec;
+const node_crypto_1 = require("node:crypto");
+const spec_types_1 = require("./spec-types");
+const spec_digest_1 = require("./spec-digest");
+const legacy_format_1 = require("./legacy-format");
+const ISO_DATE = /^\d{4}-\d{2}-\d{2}$/;
+/**
+ * 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.
+ */
+function citationDigest(content) {
+    return `sha256:${(0, node_crypto_1.createHash)('sha256').update(content).digest('hex').slice(0, 16)}`;
+}
+/**
+ * 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.
+ */
+function pinCitations(citations, read) {
+    const findings = [];
+    const pinned = [];
+    if (!Array.isArray(citations))
+        return { citations: [], pinned, findings };
+    const out = citations.map((entry, i) => {
+        if (entry === null || typeof entry !== 'object' || Array.isArray(entry))
+            return entry;
+        const c = { ...entry };
+        const ref = c.ref;
+        if (typeof ref !== 'string' || ref.trim() === '' || ref.trim().toUpperCase() === spec_types_1.CITATION_PLACEHOLDER)
+            return entry;
+        let content = null;
+        try {
+            content = read(ref);
+        }
+        catch {
+            content = null;
+        }
+        if (content == null) {
+            // Not an error: an external ticket with no adapter simply cannot be pinned from here.
+            findings.push({ level: 'warn', code: 'citation-unresolvable', message: `source[${i}] "${ref}" could not be read here — pin it where the source is reachable` });
+            return entry;
+        }
+        const digest = citationDigest(content);
+        const existing = c.rev;
+        if (typeof existing === 'string' && existing !== '') {
+            if (existing.startsWith('sha256:') && existing !== digest) {
+                findings.push({ level: 'warn', code: 'citation-drift', message: `source[${i}] "${ref}" changed since it was cited (${existing} -> ${digest}) — re-read it and confirm the requirement still holds; the stored rev was left untouched` });
+            }
+            return entry; // an existing pin is evidence; it is never rewritten
+        }
+        c.rev = digest;
+        pinned.push(ref);
+        return c;
+    });
+    return { citations: out, pinned, findings };
+}
+/**
+ * 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.
+ */
+function verifyCitationDigests(citations, read) {
+    const out = [];
+    if (!Array.isArray(citations))
+        return out;
+    citations.forEach((entry, i) => {
+        if (entry === null || typeof entry !== 'object')
+            return;
+        const c = entry;
+        const { ref, rev } = c;
+        if (typeof ref !== 'string' || typeof rev !== 'string' || !rev.startsWith('sha256:'))
+            return;
+        let current = null;
+        try {
+            current = read(ref);
+        }
+        catch {
+            current = null;
+        }
+        if (current == null)
+            return; // unresolvable here — not evidence of drift
+        const now = citationDigest(current);
+        if (now !== rev) {
+            out.push({
+                level: 'warn',
+                code: 'citation-drift',
+                message: `source[${i}] "${ref}" changed since it was cited (${rev} -> ${now}) — re-read it and confirm the requirement still holds`,
+            });
+        }
+    });
+    return out;
+}
+const isPlaceholder = (s) => s.trim() === '' || s.trim().toUpperCase() === spec_types_1.CITATION_PLACEHOLDER;
+/**
+ * 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.
+ */
+function validateCitations(value, approved) {
+    const f = [];
+    const err = (code, message) => f.push({ level: 'error', code, message });
+    // A completeness gap blocks approval but not authoring.
+    const gap = (code, message) => f.push({ level: approved ? 'error' : 'warn', code, message });
+    if (typeof value === 'string') {
+        err('citation-legacy-string', `source must be a list of citations, not free text. Replace with:\n` +
+            `  source:\n    - kind: <${spec_types_1.CITATION_KINDS.slice(0, 4).join('|')}|…>\n      ref: "<locator>"\n      retrieved: YYYY-MM-DD`);
+        return f;
+    }
+    if (!Array.isArray(value)) {
+        err('citation-not-a-list', 'source must be a list of citations');
+        return f;
+    }
+    if (value.length === 0) {
+        err('citation-empty', 'source must cite at least one origin');
+        return f;
+    }
+    value.forEach((entry, i) => {
+        const at = `source[${i}]`;
+        if (entry === null || typeof entry !== 'object' || Array.isArray(entry)) {
+            err('citation-not-an-object', `${at} must be a mapping with kind/ref`);
+            return;
+        }
+        const c = entry;
+        const kind = c.kind;
+        if (typeof kind !== 'string' || !spec_types_1.CITATION_KINDS.includes(kind)) {
+            err('citation-bad-kind', `${at}.kind "${String(kind)}" is not one of: ${spec_types_1.CITATION_KINDS.join(', ')}`);
+        }
+        const ref = c.ref;
+        if (typeof ref !== 'string')
+            err('citation-missing-ref', `${at}.ref is required and must be a string`);
+        else if (isPlaceholder(ref))
+            gap('citation-placeholder', `${at}.ref is still "${spec_types_1.CITATION_PLACEHOLDER}" — cite the real origin`);
+        // `rev` pins WHAT was read, `retrieved` pins WHEN. A source with neither cannot be re-checked
+        // later, which defeats the point of citing it: an upstream edit becomes undetectable.
+        const rev = c.rev;
+        const retrieved = c.retrieved;
+        if (rev != null && typeof rev !== 'string')
+            err('citation-bad-rev', `${at}.rev must be a string`);
+        if (retrieved != null) {
+            // A YAML date scalar arrives as a Date; accept either that or an ISO string.
+            const asString = retrieved instanceof Date ? retrieved.toISOString().slice(0, 10) : retrieved;
+            if (typeof asString !== 'string' || !ISO_DATE.test(asString)) {
+                err('citation-bad-retrieved', `${at}.retrieved must be an ISO date (YYYY-MM-DD), got "${String(retrieved)}"`);
+            }
+        }
+        const hasRev = typeof rev === 'string' && !isPlaceholder(rev);
+        const hasRetrieved = retrieved != null;
+        const mutable = typeof kind === 'string' && spec_types_1.MUTABLE_CITATION_KINDS.includes(kind);
+        if (mutable && !hasRev) {
+            // A mutable source without a version pin cannot be re-checked: the page is edited, the ticket
+            // is re-scoped, and the citation silently starts describing something that no longer exists.
+            gap('citation-mutable-unpinned', `${at}.kind "${String(kind)}" can change after being cited, so rev is required — use a content digest (sha256:…) of what was read`);
+        }
+        else if (!hasRev && !hasRetrieved) {
+            // Immutable kinds are pinned by ref + when it happened; one of the two must still be present.
+            gap('citation-unpinned', `${at} has neither rev nor retrieved — nothing pins what was read`);
+        }
+        if (c.note != null && typeof c.note !== 'string')
+            err('citation-bad-note', `${at}.note must be a string`);
+    });
+    return f;
+}
+function validateSpec(spec, resolve) {
+    const f = [];
+    const def = (0, spec_types_1.specTypeDef)(spec.type);
+    const err = (code, message) => f.push({ level: 'error', code, message });
+    // @implements A-SPEC-184
+    // Code and level are UNCHANGED — only the sentence improves. Interpolating `spec.type` printed the
+    // literal `undefined` for every pre-format document (155 of 483 here), naming neither the document
+    // nor the reason. `legacyMessage` names both, and distinguishes "older format, upgradable" from
+    // "a kind this tool does not have".
+    if (!def) {
+        err('unknown-type', (0, legacy_format_1.legacyMessage)(spec));
+        return { ok: false, findings: f };
+    }
+    if (!def.idRegex.test(spec.id))
+        err('bad-id', `id "${spec.id}" fails ${def.idRegex}`);
+    for (const field of def.requiredFields)
+        if (spec.frontmatter[field] == null)
+            err('missing-field', `missing frontmatter: ${field}`);
+    for (const sec of def.requiredSections)
+        if (!(sec in spec.sections))
+            err('missing-section', `missing section: ## ${sec}`);
+    // A REQ's origin is the one link in the chain that no downstream artefact can reconstruct, so its
+    // citation is checked for shape here rather than left as free text.
+    if (spec.type === 'REQ' && spec.frontmatter.source != null) {
+        f.push(...validateCitations(spec.frontmatter.source, spec.status === 'approved'));
+    }
+    // @implements A-SPEC-132
+    // Approval seals (REQ-132): an approved governed spec must carry the digest of the content that
+    // was approved, that digest must still match, and its snapshot of each sealed parent must match
+    // the parent's CURRENT seal. Errors (not warns) on approved specs — the constitution's ART-3
+    // blocks the Stop on validation errors, so seals are enforced with no new wiring. Drafts carry no
+    // seal obligations at all: the gap() asymmetry, applied to the graph's internal edges. Measured
+    // origin: an Edit rewriting an approved A-SPEC's body returned `allow` with no approval anywhere.
+    if (spec.status === 'approved') {
+        const seal = (0, spec_digest_1.sealOf)(spec);
+        if (!seal.approvedDigest) {
+            err('unsealed-approval', `approved without approved_digest — approval must seal content (spec_approve)`);
+        }
+        else if (seal.approvedDigest !== (0, spec_digest_1.specDigest)(spec)) {
+            err('post-approval-edit', `content differs from the sealed approved_digest — the approved text was edited after approval; re-approve via spec_approve`);
+        }
+        for (const pid of spec.dependsOn) {
+            const parent = resolve(pid);
+            if (!parent || parent.status !== 'approved')
+                continue; // dangling/draft parents are other findings' business
+            const parentSeal = (0, spec_digest_1.sealOf)(parent).approvedDigest;
+            if (!parentSeal)
+                continue; // an unsealed parent is ITS unsealed-approval, not this child's staleness
+            if (seal.parentDigests[pid] !== parentSeal) {
+                err('stale-parent', `parent ${pid} was re-approved (or never snapshotted) since this spec's seal — re-approve to re-baseline the chain`);
+            }
+        }
+    }
+    // relations
+    if (def.parents.length === 0 && spec.dependsOn.length > 0)
+        err('root-has-parent', `${spec.type} must have empty depends_on`);
+    if (def.parents.length > 0 && spec.dependsOn.length === 0)
+        err('orphan', `${spec.type} requires a parent of type ${def.parents.join('|')}`);
+    for (const pid of spec.dependsOn) {
+        const parent = resolve(pid);
+        if (!parent) {
+            err('dangling-parent', `depends_on "${pid}" not found`);
+            continue;
+        }
+        if (!def.parents.includes(parent.type))
+            err('wrong-parent-type', `parent ${pid} is ${parent.type}, expected ${def.parents.join('|')}`);
+    }
+    // gate: T-SPEC 4-quadrant coverage on approve attempt
+    if (spec.type === 'T-SPEC' && spec.status === 'approved') {
+        const cov = (spec.frontmatter.coverage ?? {});
+        for (const q of ['normal', 'corner', 'negative', 'boundary']) {
+            if (!cov[q]) {
+                err('coverage-gap', `T-SPEC approved requires coverage.${q}=true`);
+                continue;
+            }
+            // BDD 4-quadrant AUTO-verification (diff ②): a declared-covered quadrant must actually carry a
+            // Given/When/Then scenario in its section — not just a true flag over an empty stub. This makes
+            // coverage:{…true} HONEST (the section proves the case exists), enforcing the 4분면 gate.
+            const section = spec.sections[`${q[0].toUpperCase()}${q.slice(1)} Cases`] ?? '';
+            // Require a real Given→When→Then scenario: the three clauses IN ORDER with substantive content
+            // between them (review F5 — the old unordered `given && when && then` passed bare keyword prose
+            // like "given when then"). A trailing given/when clause still needs its consequent `then`.
+            const hasGwt = /\bgiven\b.{2,}?\bwhen\b.{2,}?\bthen\b/is.test(section);
+            if (!hasGwt)
+                err('empty-quadrant', `coverage.${q}=true but '## ${q[0].toUpperCase()}${q.slice(1)} Cases' has no Given/When/Then scenario`);
+        }
+    }
+    return { ok: f.filter((x) => x.level === 'error').length === 0, findings: f };
+}

package/package.json

@@ -0,0 +1,76 @@
+{
+  "name": "@holmes-lab/holmes-kit",
+  "version": "0.1.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",
+  "bin": {
+    "holmes-kit": "bin/holmes-kit.js",
+    "holmes-mcp": "bin/holmes-mcp.js"
+  },
+  "files": [
+    "bin/",
+    "dist/",
+    "playbooks/",
+    "CHANGELOG.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsc && node -e \"const{execSync}=require('child_process'),fs=require('fs');const id=(()=>{try{return execSync('git rev-parse --short HEAD').toString().trim()}catch{return 'nogit'}})();fs.writeFileSync('dist/.build-id',id+'-'+Date.now().toString(36))\"",
+    "test": "npm run typecheck && jest",
+    "mcp": "node bin/holmes-mcp.js",
+    "release": "npm run build && node scripts/make-release.js",
+    "typecheck": "tsc --noEmit -p tsconfig.test.json"
+  },
+  "keywords": [
+    "ase",
+    "agentic",
+    "spec-driven",
+    "rtm",
+    "cpg",
+    "traceability",
+    "mcp",
+    "guardrail"
+  ],
+  "author": "SungNam Park <snpark.phd@gmail.com>",
+  "license": "MIT",
+  "devDependencies": {
+    "@types/better-sqlite3": "^7.6.13",
+    "@types/jest": "^29.5.12",
+    "@types/js-yaml": "^4.0.9",
+    "@types/node": "^20.19.39",
+    "jest": "^29.7.0",
+    "ts-jest": "^29.1.2"
+  },
+  "jest": {
+    "preset": "ts-jest",
+    "testEnvironment": "node",
+    "testMatch": [
+      "**/src/**/*.test.ts"
+    ],
+    "testTimeout": 30000
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "better-sqlite3": "^12.9.0",
+    "js-yaml": "^4.1.1",
+    "tree-sitter": "^0.21.1",
+    "tree-sitter-c-sharp": "^0.21.3",
+    "tree-sitter-cpp": "^0.21.0",
+    "tree-sitter-go": "^0.21.2",
+    "tree-sitter-java": "^0.21.0",
+    "tree-sitter-python": "^0.21.0",
+    "tree-sitter-rust": "^0.21.0",
+    "tree-sitter-typescript": "^0.21.2",
+    "typescript": "^5.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/snpark-io/holmes-kit.git"
+  },
+  "homepage": "https://github.com/snpark-io/holmes-kit#readme",
+  "bugs": {
+    "url": "https://github.com/snpark-io/holmes-kit/issues"
+  }
+}

package/playbooks/adopt/PLAYBOOK.md

@@ -0,0 +1,125 @@
+---
+name: holmes-adopt
+description: >-
+  Use when reverse_draft refuses with "parentReqId is required" or "was not found in the spec store",
+  or when bringing an existing codebase with no specs under Holmes-Kit governance — recovering
+  traceability from legacy code via reverse_scan, reverse_draft, and reverse_anchor.
+---
+
+# adopt
+
+스펙 없이 자란 코드베이스를 거버넌스 아래로 들이는 절차다. 도구는 셋이고 순서가 있다:
+**`reverse_scan`(읽기 전용 조사) → REQ 작성(사람의 일) → `reverse_draft`(초안 생성) →
+검토·승인 → `reverse_anchor`(앵커 삽입).** 이 순서가 강제되는 지점마다 도구가 거부하며,
+그 거부들이 이 플레이북의 트리거다.
+
+## 도구가 대신 써 주지 않는 것
+
+`reverse_draft`는 `parentReqId` 없이 거부한다:
+
+> parentReqId is required. A REQ states business intent, which does not exist in the code and
+> cannot be recovered from it — write the REQ first, then re-run with its id.
+
+이건 미구현이 아니라 설계다. **어떤 코드 경로도 REQ를 만들지 않는다.** 역공학은 코드가 무엇을
+*하는지*를 복원하지, 무엇을 *위한지*는 복원하지 못한다 — 의도는 사람·티켓·사건에 있다. 그래서
+REQ는 사람이 쓴다: 왜 이 코드베이스를 거버넌스 아래 들이는지, 무엇이 성공인지. 쓰는 법은
+`author-slice`다. 그리고 승인까지 기다릴 필요는 없다 — `reverse_draft`의 부모 검사는 존재와
+타입만 보므로 **draft REQ로 충분하다.**
+
+부모 검사의 나머지 두 거부: 스토어에 없는 id는 `parent REQ <id> was not found in the spec store —
+create it first`, REQ가 아닌 스펙을 대면 `<id> is a H-SPEC; drafts must hang off a REQ`.
+
+## 절차
+
+1. **`reverse_scan(root)` — 읽기 전용.** 트리를 바이트 하나 바꾸지 않고 A-SPEC 후보 클러스터,
+   응집도 증거, 커버리지 보고를 돌려준다. git 저장소일 필요도 없다(`isGit:false`로 계속한다).
+   보고에서 볼 것: 클러스터 목록과 각각의 키, **미해석 동적 배선과 미보정 언어** — 지표 0이
+   "깨끗함"이 아니라 "측정 불가"일 수 있음을 보고 자체가 말해 준다.
+2. **부모 REQ를 쓴다.** `author-slice`의 REQ 절 그대로. 역공학 REQ의 요체는 채택의 의도다 —
+   이 코드베이스가 무엇이고, 왜 지금 거버넌스가 필요하고, 어디까지가 이번 채택의 범위인지.
+3. **`reverse_draft(root, parentReqId)` — 기본은 dry-run이다.** `dryRun: false`를 명시해야
+   쓴다. 클러스터마다 H/A/T 3종이 전부 `draft`로, REQ→H→A→T로 연결되어 나온다. 먼저 dry-run
+   결과에서 `drafted` · `skipped` · `refused`를 읽고, 납득한 뒤에 쓰기로 재실행한다.
+4. **특정 클러스터만 초안하려면 `cluster: <키>`.** 키는 scan 보고의 클러스터 키(디렉토리, per-file
+   분할이면 파일 경로)다. **오타 난 키는 조용히 0건이 아니라 거부다** — `availableClusters`
+   목록을 실어 돌려주므로, 목록에서 키를 집어 재시도한다.
+5. **남은 TODO를 채우고 검토한다.** 초안은 **스캔이 판정할 수 있는 것을 이미 적어둔다** — 파일
+   목록·응집도에 더해, `Interfaces / Contracts`에 최상위 심볼 이름(중첩·밑줄 제외)이, `Test
+   Points`에 이 슬라이스에 붙은 기존 테스트가 들어 있다. `Done When`은 구조적 완료 기준으로
+   **완결되어 있어 승인을 막지 않는다.**
+
+   그래도 `Interfaces / Contracts`와 `Test Points`는 **여전히 승인을 막는다.** 심볼 목록은
+   *표면 후보*이지 이 슬라이스가 약속하는 계약이 아니고, 테스트 매칭은 파일 이름의 정확한
+   일치만 인정하므로(실측 재현율 53%) 붙은 목록이 전부라는 보장이 없다. 그래서 사람의 일이
+   **백지 작성에서 초안 편집으로** 바뀔 뿐 사라지지는 않는다 — 공개가 아닌 이름을 지우고,
+   어떤 성질을 고정할지 고른다. Intent·Objective·Behavior·Acceptance Criteria는 코드에서
+   복원되지 않으므로 그대로 사람이 쓴다. 승인은 `promote-slice`로.
+6. **A-SPEC 승인 후 `reverse_anchor(root, mapping)` — 역시 기본 dry-run.** `@implements` 앵커를
+   소스에 삽입한다. **승인되지 않은 A-SPEC으로의 앵커는 거부된다** (`target A-SPEC <id> is not
+   approved`) — 역공학 초안은 코드를 묘사할 뿐이고, 묘사가 승인을 대신하지 않는다.
+   `reverse_draft` 결과의 `anchorPlan`이 파일→A-SPEC 매핑을 그대로 준다.
+
+## 이미 스펙이 있는 저장소 — 옛 양식의 문서
+
+스펙이 아예 없는 저장소만 채택 대상인 것은 아니다. 예전 양식으로 쓰인 문서가 잔뜩 있는
+경우가 오히려 흔하고, 그때 도구는 **세 등급**으로 대한다.
+
+| 등급 | 판정 | 도구의 태도 |
+|---|---|---|
+| **옛 형식** | `type:` 선언이 없으나 id로 종류를 알 수 있다 | 읽되 **강제하지 않는다**. 보강하면 쓸 수 있다 |
+| **현행** | `type:`이 선언돼 있다 | 거버넌스 대상 |
+| **미지원** | id로도 종류를 알 수 없다(예: `JOB-001`) | 읽되 그대로 둔다. 보강 대상이 아니다 |
+
+**기본값은 옛 형식 유지다.** 도구가 저장소를 훑어 일괄 변환하지 않는다 — 어느 문서가 아직
+살아 있는 사양인지는 사람만 안다. 그래서 일괄 실행 경로 자체가 없다.
+
+옛 형식 문서를 부모로 대면 이렇게 말한다:
+
+> `REQ-002에 type: 선언이 없습니다 — 현행보다 이전 양식으로 쓰인 문서입니다. id로 보면
+> REQ입니다. 이 문서를 거버넌스 아래에서 쓰려면 spec_upgrade로 보강하십시오.`
+
+**`spec_upgrade(id)` — 지목한 하나만 올린다.** `type:`을 선언하고, 옛 상태를
+`legacy_status`로 보존하고, `status`를 `draft`로 둔다. 보강 후 남은 검증 소견을 함께
+돌려주므로 다음에 무엇을 채워야 할지 바로 보인다.
+
+**보강은 승인이 아니다.** 옛 문서가 `status: Approved`였더라도 `approved`가 되지 않는다 —
+봉인 행위를 거치지 않은 승인은 승인이 아니기 때문이다. 규범으로 만들려면 정상 승인 경로를
+밟는다.
+
+**파일이 옮겨진다.** 스토어는 `<id>.md`로 쓰고 종류에 맞는 폴더에 둔다. `01_req/`에 몰려
+있던 `A-SPEC-002_x.md`는 `03_a-spec/A-SPEC-002.md`가 된다 — git에서는 rename으로 보인다.
+지목하지 않은 문서는 바이트 하나 바뀌지 않는다.
+
+## 알아둘 동작
+
+- **문서가 어디에 떨어지는가.** 초안은 `root`가 아니라 **서버의 스펙 스토어**(`HOLMES_SPECS`,
+  기본 `.ax/specs`)에 써진다. 서버가 대상 프로젝트 안에서 돌면 둘이 같지만, 다른 저장소를
+  `root`로 가리키면 그 저장소의 슬라이스가 **이쪽** 스토어에 초안된다 — 의도적으로만 할 일이다.
+- **재실행은 안전하다.** 초안된 문서는 `reverse_cluster` 키를 지니고, 같은 키의 클러스터는
+  `skipped: already drafted`로 건너뛴다. 같은 트리에 두 번 돌려도 중복 초안은 없다.
+- **테스트 디렉토리 클러스터는 초안되지 않는다** — "tests implement nothing"으로 거부된다.
+  대신 이름 증거로 프로덕션 슬라이스에 **부착**되어 그 A-SPEC의 테스트 증거가 된다.
+- **id는 전 종류 단일 번호 공간에서 다음 번호를 받는다.** 기존 최대가 `T-SPEC-1291`이면 다음
+  초안은 1292부터다 — 종류별로 번호가 따로 가지 않는다.
+- **초안은 출처를 지닌다.** `reverse_engineered: true`가 문서를 서술적(descriptive)으로 표시한다.
+  검증 전까지 이 문서는 "코드가 이렇다"는 주장이지 "이래야 한다"는 규범이 아니다.
+
+## 흔한 오해
+
+| 오해 | 사실 |
+|---|---|
+| "reverse_draft가 REQ부터 만들어 준다" | 어떤 코드 경로도 REQ를 만들지 않는다. 의도는 코드에 없다 |
+| "부모 REQ도 approved여야 한다" | 존재와 타입만 본다. draft REQ로 충분하다 |
+| "호출하면 바로 써진다" | 기본이 dry-run이다. `dryRun: false`가 명시적 opt-in이다 |
+| "cluster 키 오타면 그냥 0건이겠지" | 거부 + `availableClusters`다. 0건 성공과 구별된다 |
+| "초안 나왔으니 바로 anchor" | 앵커는 approved A-SPEC만 받는다. 승인이 먼저다 |
+| "다른 프로젝트를 root로 주면 거기에 써진다" | 서버의 스토어에 써진다. root는 읽는 곳이다 |
+
+## 검증
+
+`src/holmes/playbooks/adopt.test.ts` — 상시 스위트 포함. 고정하는 것: 부모 검사의 세 거부 문구
+완전 일치, dry-run 기본값, 오타 키의 거부+`availableClusters`, 테스트 클러스터 거부, 초안 3종의
+draft 상태와 REQ→H→A→T 연결과 `reverse_engineered`/`reverse_cluster` 출처, `anchorPlan`의
+파일→A-SPEC 매핑, 미승인 A-SPEC 앵커 거부, 단일 번호 공간. 순수 함수 사실(`draftSpecs` ·
+`planAnchors` · `nextIdBase`)은 픽스처 없이, 핸들러 사실은 tmpdir 스토어로(A-SPEC-129 rev.3).
+변이 검사로 판별력을 증명한 뒤 신뢰한다.

package/playbooks/author-slice/PLAYBOOK.md

@@ -0,0 +1,119 @@
+---
+name: holmes-author-slice
+description: >-
+  Use when a Holmes-Kit gate denies with "선행 REQ가 없습니다", "approved H-SPEC이 없습니다" while
+  no H-SPEC exists yet, or "approved A-SPEC이 없습니다" while no A-SPEC exists yet — the required
+  document has not been written at all. Also use when starting a new slice from scratch and the
+  REQ→H-SPEC→A-SPEC→T-SPEC chain must be authored in order.
+---
+
+# author-slice
+
+거부가 요구하는 문서가 **아직 없을 때** 이 플레이북이다. 문서는 있는데 `status`가 막고 있다면
+`promote-slice`다 — `spec_list`로 먼저 갈라라. `approved H-SPEC이 없습니다` / `approved A-SPEC이
+없습니다`는 "없음"과 "draft로 있음" 두 상황에서 같은 문구로 나오므로 문구가 아니라 스토어 상태가
+판별 기준이고, `선행 REQ가 없습니다`만은 존재 검사라서 언제나 이쪽이다.
+
+## 사슬과 세 거부
+
+파이프라인 입구에는 선행 조건이 없다 — `AUTHOR_REQ`는 빈 스토어에서도 언제나 허용된다. 그 아래로는
+각 단계가 앞 단계를 요구하고, 거부마다 `next_action`이 목적지를 준다. 이 플레이북은 그 목적지에서
+**무엇을 쓰는가**다.
+
+| 거부 | next_action | 이 플레이북에서 볼 곳 |
+|---|---|---|
+| `선행 REQ가 없습니다.` | `spec_create(type='REQ', ...)` | 「REQ에 쓰는 것」 |
+| `approved H-SPEC이 없습니다.` | `H-SPEC 완성 후 spec_validate → approve` | 「H-SPEC에 쓰는 것」 + `promote-slice` |
+| `approved A-SPEC이 없습니다.` | `A-SPEC 먼저 작성·승인` | 「A-SPEC / T-SPEC에 쓰는 것」 + `promote-slice` |
+
+`discipline` 필드는 항상 같은 한 줄이다: **No Spec, No Code — 선행 스펙 승인 전 구현 진입 금지.**
+
+## 절차
+
+1. **`spec_create`로 시작한다 — 빈 파일로 시작하지 않는다.** 생성된 스펙은 `draft`이고, 타입별 필수
+   섹션이 `TODO`로, 필수 frontmatter가 형태 갖춘 스텁으로 채워져 온다. 갓 만든 스펙은 그 자리에서
+   `missing-field` 0건으로 검증을 통과한다 — 손으로 만든 파일은 필드 목록부터 다시 발굴해야 한다.
+2. **id 규칙.** 엔진이 강제하는 것은 형식뿐이다 — `REQ-\d{3,}` 꼴, 그리고 점 하위 번호
+   (`A-SPEC-129.2`, `T-SPEC-129.2`)는 A-SPEC과 T-SPEC이 허용된다. 번호 선택은 관습이다:
+   **체인 전체가 부모 REQ의 번호를 그대로 상속한다.**
+
+   > REQ-129 → H-SPEC-129 → A-SPEC-129 → **T-SPEC-129**
+   > A-SPEC-125.5 → **T-SPEC-125.5**
+
+   T-SPEC도 예외가 아니다 — 부모 A-SPEC의 번호를 **그대로** 쓴다. 읽는 사람이 계산할
+   것이 없어야 한다. 역공학 초안만 전 종류 단일 공간의 다음 번호를 받는다(`adopt`).
+
+   **옛 관습(`A-SPEC-129` → `T-SPEC-1291`)으로 쓰인 76건은 전부 개비했다**(REQ-187).
+   `specDigest`가 id를 해시하지 않아 봉인이 유지되므로 재승인 없이 이름과 `id:` 한 줄만
+   바꿨다. 이제 이 저장소의 T-SPEC은 예외 없이 거울이며, `tspec-mirror.test.ts`가 그 상태를
+   붙잡는다. 옛 id를 남긴 것은 `.ax/ledger`뿐이고, 그것은 그때의 사실이므로 그대로 둔다.
+3. **`TODO`를 실제 내용으로 바꾼다.** 아래 타입별 절. 스텁 `source`(kind `other`, ref `TODO`)의
+   운명은 status가 정한다: **draft에서는 warn, approved에서는 같은 검사가 error로 승격**된다.
+   그래서 초안은 자유롭게 돌고, 승인은 실제 출처 없이는 검증을 통과하지 못한다 — placeholder를
+   교체하는 시점이 승인 전이어야 하는 이유가 문구가 아니라 메커니즘이다.
+4. **승인은 `promote-slice`.** 이 플레이북은 문서를 만들고, 저 플레이북이 올린다. 특히 코드까지
+   가려면 T-SPEC의 `depends_on`이 대상 A-SPEC을 가리켜야 한다는 함정도 저쪽에 있다.
+
+## REQ에 쓰는 것
+
+필수 섹션: **Problem / Need · Desired Outcome · Constraints · Success Criteria · Out of Scope.**
+필수 필드: `source` · `created`.
+
+REQ는 사슬 전체에서 **코드로부터 복원할 수 없는 유일한 문서**다. 의도는 사람·티켓·사건·결정에
+있지 소스에 없다. 그래서 `source`가 가장 중요한 필드다:
+
+- 대화에서 나온 지시는 `kind: user-request` 또는 `conversation` + `retrieved` 날짜. 이 둘은 일어난
+  순간 고정되므로 `rev`가 필요 없다.
+- 문서를 인용하면(`plan` · `adr` · `wiki` · `analysis` 등 변할 수 있는 것) `rev`가 **필수**다 —
+  내용 다이제스트(`sha256:…`)나 원본의 버전 핸들. 인용 시점에 새로 만든 토큰은 출처가 아니라
+  인용 행위를 식별할 뿐이라 거부된다.
+- **존재하지 않는 문서를 인용하지 않는다.** 실측이 대화록에만 있다면 `conversation`으로 적고
+  "no artefact was written"을 note에 남긴다 — `analysis`로 적으면 있지도 않은 파일의 다이제스트를
+  요구받는다.
+
+Success Criteria는 관측 가능한 문장으로 쓴다 — 각 항목이 나중에 테스트나 실측으로 확인 가능한가를
+기준으로. Out of Scope는 빈 절이 아니라 **거절의 기록**이다: 고려했고 안 하기로 한 것과 그 이유.
+
+## H-SPEC에 쓰는 것
+
+필수 섹션: **Intent · Scope (In / Out) · Design Overview · Interfaces / Contracts · Acceptance
+Criteria · Non-Functional · Assumptions · Open Questions.** 필수 필드: `req_type` · `owner`.
+
+부모 REQ의 Success Criteria가 이 설계로 어떻게 달성되는지가 본문이다. Open Questions는 비워두는
+칸이 아니다 — 아직 결정하지 않은 것을 결정하지 않았다고 적는 곳이고, 닫을 때는 근거와 함께 닫는다.
+
+## A-SPEC / T-SPEC에 쓰는 것
+
+A-SPEC 필수 섹션: **Objective · Inputs / Outputs · Behavior · Test Points · Files to Touch · Done
+When.** 필수 필드: `slice` · `priority` · `independent_test`.
+
+- 각 섹션이 넘어야 할 품질 바는 `promote-slice`의 「승인의 기준」이 **소유**한다 — 여기 반복하지
+  않는 것은 두 사본이 어긋나는 것을 막기 위해서다. 쓰는 시점에 그 바를 한 번 읽고 쓰면, 승인
+  시점에 보완할 것이 없다.
+- 하나의 H-SPEC 아래 슬라이스가 여럿이면 점 하위 번호로 나눈다(`A-SPEC-129.2`). 그 슬라이스의
+  T-SPEC은 거울이므로 `T-SPEC-129.2`다 — 점 번호가 A-SPEC과 T-SPEC 둘에만 허용되는 이유다.
+
+T-SPEC 필수 섹션은 4분면 그대로다: **Normal · Corner · Negative · Boundary Cases.** 필수 필드
+`coverage`는 4분면 각각의 boolean 맵이다. 각 케이스는 Given/When/Then으로, **어느 4분면이 왜 그
+케이스인지**가 드러나게 쓴다. 그리고 frontmatter `depends_on: [대상 A-SPEC]` — 이 간선이 없으면
+승인해도 코드 게이트가 열리지 않는다 — 그때 게이트가 `depends_on`을 지목한다(`promote-slice`의 「T-SPEC 거부는 상태를 구별해 말한다」).
+
+## 흔한 오해
+
+| 오해 | 사실 |
+|---|---|
+| "파일을 직접 만들어도 된다" | 된다. 하지만 필수 필드를 손으로 발굴하게 된다. `spec_create`가 스텁을 준다 |
+| "스텁 `source`로 승인까지 간다" | draft에서 warn이던 placeholder 검사가 approved에서 error로 승격된다 |
+| "대화 내용도 `rev`를 지어내야 한다" | 아니다. `conversation`/`user-request`는 불변이라 `rev` 면제다. 지어낸 토큰이야말로 거부 대상 |
+| "REQ-129.1로 REQ를 쪼갠다" | 점 하위 번호는 A-SPEC과 그 거울인 T-SPEC에만 허용된다 |
+| "문서를 썼는데 아직 거부된다" | 작성과 승인은 다른 단계다. `status`는 `promote-slice` 소관 |
+
+## 검증
+
+`src/holmes/playbooks/author-slice.test.ts` — 상시 스위트 포함. 고정하는 것: 세 거부의
+`message` · `next_action` · `discipline` 3필드 완전 일치, `AUTHOR_REQ`의 무조건 허용, 타입별 필수
+섹션/필드 표(전사가 아니라 `SPEC_TYPES`를 직접 읽어서), `spec_create` 스텁의 형태와 caller-wins
+규칙, placeholder 검사의 **draft-warn → approved-error 승격**, `spec_next`의 순서 규칙, 점 하위
+번호가 A-SPEC과 T-SPEC에 한정되는 것, 그리고 스펙 폴더 밑 `.ts`가 author 게이트로 강등되지 않는다는 사실. 번호
+상속 관습은 엔진이 강제하지 않으므로 테스트도 고정하지 않는다 — 관습은 관습이라 말한다. 변이
+검사로 판별력을 증명한 뒤 신뢰한다.