pipeline: make tech-log-tree.json the one decomposition contract and enforce it

리뷰 두 건을 반영했다. 계약 - tech-log-tree.json 하나가 분해 계약이자 색인이다. 사람이 읽는 트리·Node Specification· 후보 대장은 없어졌고, 문서에 남아 있던 그 개념을 걷어냈다 - candidateScope — 후보를 찾는 SSOT 범위. 접어 넣은 제2부·제3부는 근거이지 후보가 아니다 - sourceRepository — 분석한 저장소의 경로·리비전·판단 근거. 리비전을 모르면 null 로 두고 지어내지 않는다. 갈래가 여럿이면 revisions - 검사기: 계약 미채택·PENDING·PROMOTE↔글감 양방향·candidateScope·sourceRepository 를 error/warn 으로 센다. 옛 스키마도 검사를 피하지 못한다. 테스트 22 → 31 기록 쓰기 - 템플릿 5종에 source·sourceRevision·topicName, Question 에 닫는 조건, 본문 없는 종류에서 assets 제거. 고정 절 개수 삭제 - check_evidence.mjs — 인용한 코드가 SSOT 에 있는지, 앵커가 SSOT 를 가리키는지, 제목이 계약과 같은지, 리비전이 저장소에 있는지. 게시된 기록에서 SSOT 와 다른 URL 을 잡았다 문체 - 문체 규칙의 정본을 ai-tells.md 로. explaining.md 의 질문체 제목·절 끝 대조 반복·그림 예고 규칙을 삭제해 충돌을 없앴다. 첫 절 「설명 뒤에 평가를 붙이지 않는다」에 지우는 사례 네 유형 - voice 스킬의 「독자 쪽을 본다」를 자료에 오독 기록이 있을 때로 좁히고, 평가만 더한 예시를 교체 - check_prose: 안내 문장을 요구하던 경고 제거, 문장이 끝나지 않은 채 문단이 끝나는 조각 검사 추가 Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
2026-09-07 12:39:20 +09:00
parent 73026cada6
commit 9d2a3725c5
54 changed files with 3583 additions and 871 deletions
@@ -15,12 +15,31 @@ Produce a highly detailed, source-traceable engineering analysis. This stage dis
 2. If an `IN_PROGRESS` project exists, analyze only that project. If none exists, activate the first `PENDING` project in queue order. Never preempt an active project because a new project appeared.
 3. For the selected `<분석 대상 저장소>`, check the nearest `AGENTS.md` or equivalent repository instructions.
 4. Record Git revision and `git status` when Git is available. Never modify or reset user source as part of analysis.
-5. Read `docs/<프로젝트>/state.json` if it exists; otherwise initialize from `docs/_templates`.
+5. Read `docs/<프로젝트>/state.json` if it exists; otherwise initialize the working material from `templates/` in this skill. The project folder template (`docs/_templates/`) holds only the finished shape and does not carry it.
 6. Map repository/build/module boundaries before choosing a scope.
 7. If the repository is large, select one bounded unanalysed module/subsystem and analyze it completely. Do not skim the whole repository and call that detailed analysis.
 8. Update `source-index.md`, the bounded analysis file, coverage ledger, evidence, and `state.json`.
 9. Capture runtime evidence only where it resolves a material uncertainty or verifies a significant claim.
-10. Continue the same project across runs until all intended scopes are complete. Then synthesize `final/document.md` without dropping provenance or limitations, mark its queue entry `COMPLETE`, and clear `activeProject`. Do not start the next project before this completion transition.
+10. Continue the same project across runs until all intended scopes are complete.
+11. **Fold the analysis into `final/document.md`.** Not a summary of it — the material
+    itself, with provenance and limitations intact. The test is that every claim a Tech Log
+    record will cite can be anchored in `final/document.md` alone. Anything that survives
+    only in `analysis/**` has not been folded in.
+12. **Remove the working material.** `analysis/`, `notes/`, `checkpoints/`, `state.json`,
+    and `source-index.md` exist only while the analysis runs. A finished project folder
+    holds `final/` and `tech-log-studio/` (and `source/` when the material came from
+    outside). Then mark the queue entry `COMPLETE` and clear `activeProject`. Do not start
+    the next project before this completion transition.
+
+`python3 scripts/fold-analysis-into-final.py <project>` performs steps 11 and 12: it moves
+the module analyses into part 2 of `final/document.md`, the source index, scope coverage and
+process notes into part 3, rewrites every `analysis/NN` anchor to `final/document.md#aNN`,
+and removes the working material.
+
+`analysisStatus: COMPLETE` while the working material is still on disk means step 11 was
+skipped — the analysis was summarized rather than folded in, and downstream records will
+anchor on `analysis/**` instead of the SSOT. `scripts/verify-project-layout.py` and
+`scripts/verify-tech-log-tree.py` count that state.

 Read `references/queue-contract.md`, `references/analysis-contract.md`, `references/deep-analysis-standard.md`, and `references/evidence-contract.md` before analysis.

@@ -60,7 +60,7 @@ When reanalysis finishes:
 - mark the queue entry `COMPLETE`;
 - clear `activeProject`.

-The 10:00 root-tree stage will see the changed final document and may then update decomposition/readiness. The 11:00 generation stage remains grounded in that updated tree.
+The 10:00 decomposition stage will see the changed final document and may then update decomposition/readiness. The 11:00 generation stage remains grounded in that updated tree.

 ## New projects and ordering

@@ -0,0 +1,11 @@
+분석하는 동안에만 있는 작업 재료의 틀이다.
+
+    docs/<프로젝트>/state.json        분석 상태 — 어디까지 봤나, 어느 리비전을 봤나
+    docs/<프로젝트>/source-index.md   분석한 코드의 목록
+    docs/<프로젝트>/analysis/         모듈·서브시스템 단위 분석
+    docs/<프로젝트>/notes/            분석 중에 남긴 메모
+    docs/<프로젝트>/checkpoints/      중간 저장
+
+프로젝트 폴더 틀(docs/_templates/)에는 이것들이 없다. 분석이 끝나면 내용을
+final/document.md 로 옮기고 폴더에서 지우기 때문이다. 끝난 프로젝트의 폴더는
+final/ 과 tech-log-studio/ 둘이다.
@@ -0,0 +1,25 @@
+# Project Overview
+
+## 분석 기준 revision
+
+- repository: `/shared/codebase/<project>`
+- revision: `<git revision or non-git snapshot note>`
+
+## Build and module map
+
+## Dependency direction
+
+## Runtime entry points
+
+## Persistence / messaging / external systems
+
+## Test topology
+
+## Configuration and operational surfaces
+
+## 분석할 bounded scopes
+
+| scope | why separate | status | analysis file |
+|---|---|---|---|
+
+## 아직 단정하지 않는 것
@@ -0,0 +1,60 @@
+# <module/subsystem> 완전 해부
+
+> 상태: IN_PROGRESS | COMPLETE  
+> 기준 revision: <git-sha>  
+> 분석 범위: <path/module>
+
+## 0. 커버리지와 숫자 지도
+
+- production files:
+- production LOC:
+- packages/directories:
+- tests by lane:
+- migrations/config/build files:
+- runtime membership:
+
+### Coverage ledger
+
+| scope/file group | count | disposition | reason |
+|---|---:|---|---|
+| | | FULL_READ / STRUCTURAL_ONLY / EXCLUDED | |
+
+## 1. 모듈의 정체와 경계
+
+## 2. 의존성과 런타임 배선
+
+## 3. 패키지/컴포넌트 지도
+
+## 4. 계약·불변식·상태 모델
+
+## 5. 주요 실행 경로
+
+## 6. 실패 경로와 복구/번역
+
+## 7. 트랜잭션·동시성·수명주기
+
+## 8. 설정·기능 플래그·환경 차이
+
+## 9. 퍼시스턴스/외부 시스템 세부
+
+## 10. 테스트 레인과 실제 증명 범위
+
+## 11. 빌드/ArchUnit/CI 강제 지점
+
+## 12. 실제 사용 여부와 dead/unwired/duplicate 경로
+
+## 13. Git/설계 문서에서 확인한 변화와 실패 기록
+
+## 14. 런타임·터미널·브라우저 Evidence
+
+## 15. 명시적 설계 이유와 추론을 구분한 정리
+
+## 16. 확인한 것 / 확인하지 못한 것
+
+## 17. 손볼 것
+
+각 항목: 우선순위 → 사실 → 근거 → 왜 문제인가 → 확인 방법 → 후보/다음 단계.
+
+## Source anchors
+
+모든 핵심 주장에 source-index의 파일/심볼/테스트/evidence anchor를 연결한다.
@@ -0,0 +1,7 @@
+# Source Index
+
+상세 문서의 주장과 근거를 다시 찾을 수 있게 code/config/test/git/runtime source를 색인한다.
+
+| id | kind | path / command / URL | revision or time | what it proves | limitations |
+|---|---|---|---|---|---|
+| SRC-001 | code | `<path>` | `<revision>` | `<grounded fact>` | `<limit>` |
@@ -0,0 +1,30 @@
+{
+  "schemaVersion": 2,
+  "project": "<project>",
+  "codebasePath": "/shared/codebase/<project>",
+  "gitRevision": null,
+  "analysisStatus": "NOT_STARTED",
+  "analysisCycle": 1,
+  "scopes": [],
+  "reanalysis": {
+    "baselineRevision": null,
+    "targetRevision": null,
+    "mode": null,
+    "changedPaths": [],
+    "impactedScopes": [],
+    "requestedAt": null,
+    "completedAt": null
+  },
+  "finalDocument": {
+    "path": "final/document.md",
+    "status": "NOT_STARTED",
+    "sourceRevision": null
+  },
+  "evidenceTasks": [],
+  "lastRunAt": null,
+  "techLogTree": {
+    "path": "tech-log-studio/tech-log-tree.json",
+    "status": "NOT_STARTED",
+    "sourceDocumentHash": null
+  }
+}