@holmes-lab/holmes-kit 0.17.0 → 0.19.0

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

@@ -37,7 +37,9 @@ exports.parseDependsOn = parseDependsOn;
 exports.parseSpec = parseSpec;
 exports.serializeSpec = serializeSpec;
 const yaml = __importStar(require("js-yaml"));
-const legacy_format_1 = require("./legacy-format");
+// @implements A-SPEC-574.3 — from the shared module, not from `legacy-format`, which imports
+// this file's `Spec` type. That pair was a cycle over one string constant.
+const legacy_fields_1 = require("./legacy-fields");
 /**
  * Read `depends_on` in every spelling the corpus contains, keeping what cannot be represented.
  *
@@ -121,8 +123,8 @@ function parseSpec(input) {
     const deps = parseDependsOn(fm.depends_on);
     // @implements A-SPEC-221 — never overwrite an existing preservation: a second round trip must not
     // chew up what the first one saved, the same rule `legacy_status` follows.
-    if (deps.legacy !== null && fm[legacy_format_1.LEGACY_DEPENDS_FIELD] === undefined) {
-        fm[legacy_format_1.LEGACY_DEPENDS_FIELD] = deps.legacy;
+    if (deps.legacy !== null && fm[legacy_fields_1.LEGACY_DEPENDS_FIELD] === undefined) {
+        fm[legacy_fields_1.LEGACY_DEPENDS_FIELD] = deps.legacy;
     }
     return {
         id: String(fm.id ?? ''),

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.19.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
@@ -117,3 +136,17 @@ T-SPEC 필수 섹션은 4분면 그대로다: **Normal · Corner · Negative ·
 번호가 A-SPEC과 T-SPEC에 한정되는 것, 그리고 스펙 폴더 밑 `.ts`가 author 게이트로 강등되지 않는다는 사실. 번호
 상속 관습은 엔진이 강제하지 않으므로 테스트도 고정하지 않는다 — 관습은 관습이라 말한다. 변이
 검사로 판별력을 증명한 뒤 신뢰한다.
+
+### 순환 의존을 만들지 않는다
+
+두 모듈이 서로를 import 하면 순환이다. **설계 단계에서 피하는 것이 유일하게 값싼 시점이다** ——
+코드가 쓰인 뒤에는 공유 타입 추출이나 지연 `require()` 워크어라운드로만 풀 수 있고, 후자는
+순환을 숨길 뿐 없애지 않는다.
+
+- **공유 타입은 별도 모듈로 뺀다.** A 와 B 가 같은 타입을 필요로 하면 그 타입은 A 도 B 도 아닌
+  세 번째 모듈에 있어야 한다.
+- **타입만 필요하면 `import type` 을 쓴다.** TypeScript 가 방출에서 지우므로 런타임 순환이 되지
+  않는다. 값 import 로 두면 타입만 쓰면서도 순환을 만든다.
+- **지연 `require()` 로 순환을 우회하지 않는다.** 그것은 수리가 아니라 청구서 이연이다.
+
+이 저장소는 **스펙 그래프의 무순환을 ART-2 로 집행**한다. 코드 그래프도 같은 기준을 향한다.

package/playbooks/publish/PLAYBOOK.md

@@ -96,6 +96,38 @@ npm publish --access public
 
 ---
 
+### 6단계: 외부 문서 표면 (External Docs Reach) — 발행이 닿는 곳까지 정직하게
+
+npm 만 갱신하고 끝나면, 사람들이 실제로 읽는 문서는 낡은 채로 남는다. **사고 이력**: 이 저장소에는
+GitHub 리모트가 없어(origin 이 로컬 gitea) 0.16.0·0.17.0·0.18.0 **세 릴리스 동안** GitHub README 가
+한 번도 갱신되지 않았고, `package.json` 의 `homepage` 가 바로 그 문서를 가리킨다.
+
+**발행이 성공한 뒤에만** 실행한다 — 실패한 릴리스의 문서를 최신이라고 주장하지 않는다.
+
+1. **대상 파생 (하드코딩 금지)**: `package.json` 의 `repository` 에서 `<owner>/<repo>` 를 얻는다
+   (`repoTargetFrom`). 이 플레이북은 **소비 프로젝트에도 설치**되므로 특정 저장소를 박아 두면 남의
+   릴리스가 그 저장소를 덮어쓴다. 파생 실패 → **SKIP(사유: `repository` 필드 없음/비-GitHub)**.
+2. **덮어쓸 것을 먼저 본다**: `gh api repos/<owner>/<repo>/contents/README.md` 로 원격을 읽어
+   로컬과의 차이를 **보고**한다. 원격이 분기했다면 동기화는 남의 편집을 지우는 행위다 — 사람이
+   알고 결정해야 한다.
+3. **동기화**: 로컬 `README.md` 를 `gh api --method PUT` 으로 올린다(`sha` 는 2 에서 읽은 값).
+4. **재조회 검증**: 다시 읽어 로컬과 일치하는지 확인한다. **쓴 것과 남은 것은 다를 수 있다** —
+   검증 없는 "갱신했다"는 주장이지 사실이 아니다.
+5. **profile README drift 감지 (자동 수정 금지)**: `<owner>/.github` 의 `profile/README.md` 를 읽어
+   `profileDriftFindings` 로 주장-현실 불일치를 **보고만** 한다. 포지셔닝 문안은 오너 결정이며
+   릴리스 절차가 정할 것이 아니다.
+6. **SKIP 은 값이지 침묵이 아니다**: `gh` 미설치 / 미인증(`gh auth status` 실패) / 권한 없음 /
+   `repository` 부재 — 각각 **무엇을 하지 않았는지 명시**하고 다음으로 간다. 소비 프로젝트의 발행을
+   우리 편의로 막지 않는다. 다만 **조용한 성공은 금지** — 아무 말 없이 넘어가면 그것은 3단계
+   전부를 한 것처럼 읽힌다.
+
+> [!CAUTION]
+> 2.5단계가 로컬 문서에 적용하는 규율("drift 도 누락도 거짓 주장이다")은 **외부 표면에도** 적용된다.
+> 다른 점은 하나뿐이다: repo README 는 로컬의 사본이라 **동기화**하고, profile README 는 독립
+> 문서라 **감지·보고**한다. 무엇이 정본인가가 처방을 정한다.
+
+---
+
 ## 플레이북 트리거 조건
 - "npm publish"
 - "release to npm"

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가 아니다; 스텁으로 고쳐라.
@@ -80,3 +85,17 @@ holmes는 기계적으로 판별한다: `red-error`로는 red→green 시퀀스
 
 `src/holmes/playbooks/tdd-slice.test.ts` — 이 스킬이 집행 태그(ART-1/4/8)와 red-assertion/red-error
 구별을 담고, 설치기가 이를 발견함을 고정한다. 상시 스위트 포함.
+
+### 순환 의존을 만들지 않는다
+
+두 모듈이 서로를 import 하면 순환이다. **설계 단계에서 피하는 것이 유일하게 값싼 시점이다** ——
+코드가 쓰인 뒤에는 공유 타입 추출이나 지연 `require()` 워크어라운드로만 풀 수 있고, 후자는
+순환을 숨길 뿐 없애지 않는다.
+
+- **공유 타입은 별도 모듈로 뺀다.** A 와 B 가 같은 타입을 필요로 하면 그 타입은 A 도 B 도 아닌
+  세 번째 모듈에 있어야 한다.
+- **타입만 필요하면 `import type` 을 쓴다.** TypeScript 가 방출에서 지우므로 런타임 순환이 되지
+  않는다. 값 import 로 두면 타입만 쓰면서도 순환을 만든다.
+- **지연 `require()` 로 순환을 우회하지 않는다.** 그것은 수리가 아니라 청구서 이연이다.
+
+이 저장소는 **스펙 그래프의 무순환을 ART-2 로 집행**한다. 코드 그래프도 같은 기준을 향한다.