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
@@ -1,9 +1,22 @@
 # <project>

- codebase: `/shared/codebase/<project>`
- analysis owner: `/shared/document-detail/<project>`
- Tech Log output: `/shared/Tech-Log-Document/<project>`
+- 분석 대상 코드베이스: `<경로 또는 URL>`
+- 이 폴더: SSOT(`final/document.md`)와 Studio 에 올릴 글(`tech-log-studio/`)의 정본

-## Current analysis scope
+## 끝난 프로젝트의 폴더

-`state.json`을 정본으로 사용한다. 대형 코드베이스에서는 한 실행에 한 module/subsystem을 우선한다.
+| 폴더 | 무엇 |
+|---|---|
+| `final/` | SSOT — 이 프로젝트에 대해 아는 것 전부 |
+| `tech-log-studio/` | SSOT 에서 뽑아 쓴 글. 정본은 `tech-log-tree.json` |
+
+## 분석·반입하는 동안에만 있는 것
+
+`state.json` · `source-index.md` · `analysis/` · `notes/` · `checkpoints/` · `source/`
+
+**작업 재료다.** 코드베이스를 직접 읽으면 앞의 다섯을 쌓고, 밖에서 문서를 가져오면
+`source/` 를 쌓는다. 끝나면 그 내용을 `final/document.md` 로 합친 뒤 지운다. 남아 있으면
+합치는 일이 끝나지 않은 것이다.
+
+지금 어디까지 봤는지는 `state.json` 이 정본이다. 큰 저장소에서는 한 번에 한
+모듈·서브시스템만 본다.
@@ -1,25 +0,0 @@
-# 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 |
-|---|---|---|---|
-
-## 아직 단정하지 않는 것
@@ -1,60 +0,0 @@
-# <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,2 @@
+그림의 정본 — <이름>/{context.json, spec.json, prompt.md}.
+technical-visualizer 스킬이 만든다. 손으로 SVG 를 그리지 않는다.
@@ -0,0 +1,2 @@
+그림. 그림 하나가 폴더 하나다 — <이름>/<이름>.svg 와 편집 형식들.
+Studio 에 올릴 표현물은 tech-log-studio/ 아래에 flat SVG 로 둔다.
@@ -0,0 +1,2 @@
+Studio 에 올릴 표현물. 기록 frontmatter 의 `assets: file:` 이 가리키는 자리다.
+그림의 정본은 ../<이름>/ 과 ../../.techviz/<이름>/ 에 있다.
@@ -0,0 +1 @@
+Playwright MCP 로 찍은 브라우저 캡처. 무엇을 찍었는지 한 줄을 적는다.
@@ -0,0 +1 @@
+그 실행의 command·cwd·executedAt·exitCode·revision. 형식은 evidence.json.
@@ -7,7 +7,7 @@
  "cwd": "<working directory or null>",
  "exitCode": null,
  "rawPath": "evidence/raw/<file>",
-  "presentationPath": "evidence/terminal|browser|svg/<file>",
+  "presentationPath": "evidence/rendered|browser/<file>",
  "proves": "<bounded claim>",
  "doesNotProve": "<important limitation>"
 }
@@ -0,0 +1,2 @@
+명령 출력·csv·덤프 원문. 여기가 정본이다.
+하위 폴더를 자유롭게 둔다(explain/, guards/). 폴더마다 무엇을 담았는지 한 줄을 README.txt 에 적는다.
@@ -0,0 +1,2 @@
+raw 에서 만든 터미널 SVG. 표현물이지 정본이 아니다.
+scripts/terminal-evidence/render_terminal.py 로 만든다.
@@ -1,85 +0,0 @@
---
-schemaVersion: 1
-project: <project>
-sourceDocument: final/document.md
-sourceDocumentSha256: <sha256>
-sourceRevision: <git-revision-or-snapshot>
-generatedAt: <ISO-8601>
---
-
-# Root Tree
-
-PROJECT
-<project>
-
-TOPIC
-<Topic title>
-<topic-slug>
-
-├── CASE
-│   └── <Case title>
-├── REFERENCE
-│   └── <Reference title>
-├── OPEN QUESTION
-│   └── <Open Question title>
-└── DECISION
-    └── <Decision title>
-
-# Node Specifications
-
-## CASE — <Case title>
-
- slug: `<slug>`
- readiness: `READY | NEEDS_EVIDENCE | BLOCKED | REJECTED`
- source:
-  - `final/document.md#<anchor>`
- code:
-  - `/shared/codebase/<project>/<path>:<line-or-symbol>`
- evidence:
-  - `evidence/raw/<file>`
- classification: `<specific incident/experiment/diagnosis that makes this a Case>`
- missing-verification: `<none or concrete missing check>`
- relations:
-  - `<kind>:<slug> — <reason>`
-
-## REFERENCE — <Reference title>
-
- slug: `<slug>`
- readiness: `READY | NEEDS_EVIDENCE | BLOCKED | REJECTED`
- source:
-  - `final/document.md#<anchor>`
- classification: `<reusable criterion rather than a retelling of one Case>`
- scope: `<where the rule applies>`
- exceptions: `<known exceptions or none>`
- relations:
-  - `<kind>:<slug> — <reason>`
-
-## OPEN QUESTION — <Open Question title>
-
- slug: `<slug>`
- readiness: `OPEN | BLOCKED | REJECTED`
- source:
-  - `final/document.md#<anchor>`
- known:
-  - `<grounded fact>`
- unknown:
-  - `<unresolved fact>`
- next-verification: `<what would reduce the uncertainty>`
- decision-criterion: `<what would allow this question to close>`
- relations:
-  - `<kind>:<slug> — <reason>`
-
-## DECISION — <Decision title>
-
- slug: `<slug>`
- readiness: `READY | NEEDS_DECISION | BLOCKED | REJECTED`
- decision-status: `PROPOSED | ADOPTED | SUPERSEDED | NOT_DECIDED`
- source:
-  - `final/document.md#<anchor>`
- decision-evidence:
-  - `<commit/ADR/config/history/user-provided decision record>`
- grounds:
-  - `<case/reference relation>`
- classification: `<why this is an actual project decision, not advice>`
- relations:
-  - `<kind>:<slug> — <reason>`
@@ -1,7 +0,0 @@
-# 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>` |
@@ -1,30 +0,0 @@
-{
-  "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
-  },
-  "rootTree": {
-    "path": "root-tree.md",
-    "status": "NOT_STARTED",
-    "sourceDocumentHash": null
-  },
-  "evidenceTasks": [],
-  "lastRunAt": null
-}
@@ -0,0 +1,94 @@
+{
+  "schemaVersion": 4,
+  "project": "<project>",
+  "ssot": "final/document.md",
+  "sourceRepository": {
+    "path": "<분석한 저장소의 체크아웃 경로 또는 URL>",
+    "revision": "<문서가 서술한 상태의 커밋. 모르면 null 로 두고 지어내지 않는다>",
+    "revisions": {"<갈래가 여럿이면 이름>": "<커밋>"},
+    "verified": "<이 값이 맞다고 판단한 근거 — 무엇을 어디서 대조했는지>"
+  },
+  "ssotSha256": "<sha256>",
+  "sourceRevision": "<git-revision-or-snapshot>",
+  "generatedAt": "<YYYY-MM-DD>",
+  "candidateScope": {
+    "document": "final/document.md",
+    "sections": ["§3", "§4", "§5", "§6", "§7", "§8", "§9", "§10", "§11"],
+    "excluded": ["제2부 — 모듈 분석 전문", "제3부 — 분석 재료"],
+    "note": "후보를 찾는 범위다. 제2부·제3부는 근거이지 후보 자리가 아니다. excludedAnchorPattern 을 적으면 그 정규식에 걸리는 앵커에서만 나온 글감을 검사기가 error 로 센다"
+  },
+  "note": "이 프로젝트의 글감 전부다. 분해 계약이자 색인이고, 이 파일이 정본이다. 노드의 칸(readiness·source·classification·relations…)은 사람이 적고, file·publication·status 는 기록 파일에서 읽어 채운다 — python3 scripts/build-tech-log-tree.py <프로젝트>",
+  "contract": {
+    "decomposition": [
+      "글감을 찾는 입력은 final/document.md 하나다. 거기에 없는 근거는 먼저 SSOT 에 넣는다.",
+      "후보 전부는 candidates 에 처분과 함께 남고 PROMOTE 만 topics 로 올라간다.",
+      "없애고 관련 Case 나 Concept 의 한 절로 넣어도 이해·결정·재사용성이 그대로라면 독립 기록으로 만들지 않는다.",
+      "Topic 은 독자 질문 하나다. 그 물음에 답하지 않는 글감은 다른 Topic 으로 옮긴다.",
+      "Concept 은 Case·Decision·Question 을 먼저 고른 뒤 그것을 이해하는 데 필요한 것만 거꾸로 더한다."
+    ],
+    "readinessValues": ["READY", "OPEN", "NEEDS_EVIDENCE", "NEEDS_DECISION", "BLOCKED"],
+    "dispositionValues": {
+      "PROMOTE": "독립 Tech Log 로 쓴다",
+      "MERGE_INTO": "다른 기록의 한 절로 흡수한다",
+      "KEEP_IN_SSOT": "분석에는 남기고 독립 기록으로 만들지 않는다 — 정상적인 성공 결과다",
+      "NEEDS_EVIDENCE": "주장에 아직 검증이 없다",
+      "NEEDS_DECISION": "방향이 그럴듯하지만 프로젝트가 정하지 않았다",
+      "BLOCKED": "원본이 불완전하거나 서로 어긋난다"
+    }
+  },
+  "counts": { "topics": 1, "nodes": 2, "written": 0, "unwritten": 2, "unlisted": 0, "candidates": 1 },
+  "topics": {
+    "<topic-slug>": {
+      "topic": "<topic-slug>",
+      "title": "<Topic 제목>",
+      "readerQuestion": "<이 Topic 의 기록들이 함께 답하는 물음 하나?>",
+      "kinds": {
+        "case": [
+          {
+            "title": "<Case 제목>",
+            "kind": "case",
+            "slug": "<slug>",
+            "readiness": "READY",
+            "source": ["final/document.md#<anchor>"],
+            "code": ["<path>:<line-or-symbol>"],
+            "evidence": ["evidence/raw/<file>"],
+            "classification": "<재현·진단·결론이 닫히는 하나의 사건. 정적 카운트나 문구 수정이 아니다>",
+            "missing-verification": "<없음 또는 하지 못한 확인>",
+            "relations": ["concept:<slug>"],
+            "publication": "미작성"
+          }
+        ],
+        "concept": [
+          {
+            "title": "<Concept 제목>",
+            "kind": "concept",
+            "slug": "<slug>",
+            "readiness": "READY",
+            "source": ["final/document.md#<anchor>"],
+            "basis-version": "<무엇을 보고 썼는지 — 예: Keycloak 26.7.0 identity brokering>",
+            "classification": "<이 구조를 처음부터 설명해야 어떤 Case 를 이해할 수 있는지>",
+            "relations": ["case:<slug>"],
+            "publication": "미작성"
+          }
+        ],
+        "reference": [],
+        "question": [],
+        "decision": []
+      }
+    }
+  },
+  "candidates": [
+    {
+      "id": "<A05-F012>",
+      "kindCandidate": "CASE",
+      "sourceRefs": ["final/document.md#<anchor>"],
+      "summary": "<한 줄>",
+      "disposition": "KEEP_IN_SSOT",
+      "dispositionReview": "CONFIRMED",
+      "target": null,
+      "reason": "<왜 독립 기록으로 만들지 않았는지>"
+    }
+  ],
+  "unlisted": [],
+  "history": {}
+}
				`@@ -0,0 +1 @@`
				`Playwright MCP 로 찍은 브라우저 캡처. 무엇을 찍었는지 한 줄을 적는다.`
				`@@ -0,0 +1 @@`
				`그 실행의 command·cwd·executedAt·exitCode·revision. 형식은 evidence.json.`