refactor: 분리되어 관리하고 있던 문서 시스템을 하나로 통일

2026-09-04 18:56:01 +09:00
parent 4b9e7148b5
commit 43bccd08a8
121 changed files with 2861 additions and 534 deletions
@@ -0,0 +1,119 @@
+# Root Tree Contract
+
+The root tree is the explicit boundary between deep project analysis and Tech Log record generation.
+
+## Required document header
+
+A root tree records:
+
+- `schemaVersion`
+- `project`
+- `sourceDocument`
+- `sourceDocumentSha256`
+- `sourceRevision`
+- `generatedAt`
+
+The hash/revision prevents a scheduled generator from treating a tree derived from old code as current.
+
+## Required human-readable tree
+
+Each Topic has a title, slug, and four branches:
+
+```text
+PROJECT
+<project>
+
+TOPIC
+<Topic title>
+<topic-slug>
+
+├── CASE
+├── REFERENCE
+├── OPEN QUESTION
+└── DECISION
+```
+
+Empty branches are allowed. Do not manufacture nodes to fill all four kinds.
+
+## Node source contract
+
+Every candidate includes a specification after the human-readable tree.
+
+### Case
+
+Required:
+
+- `slug`
+- `readiness`
+- one or more `source` anchors
+- `classification` explaining the concrete incident/experiment/diagnosis
+- relevant code/evidence when the conclusion depends on them
+- `missing-verification`
+- `relations`
+
+A Case with `NEEDS_EVIDENCE`, `BLOCKED`, or `REJECTED` is not generated.
+
+### Reference
+
+Required:
+
+- `slug`
+- `readiness`
+- `source`
+- `classification` explaining the reusable criterion
+- `scope`
+- `exceptions`
+- `relations`
+
+A Reference must be useful beyond retelling one Case. If removing the originating project's names leaves no rule, it is probably still a Case.
+
+### Open Question
+
+Required:
+
+- `slug`
+- `readiness: OPEN`
+- `source`
+- `known`
+- `unknown`
+- `next-verification`
+- `decision-criterion`
+- `relations`
+
+Do not generate a Question when the detailed analysis already contains a verified answer. Move the material to Case/Reference/Decision as appropriate and update the tree first.
+
+### Decision
+
+Required:
+
+- `slug`
+- `readiness`
+- `decision-status`
+- `source`
+- `decision-evidence`
+- `grounds`
+- `classification`
+- `relations`
+
+`decision-status` is one of `PROPOSED`, `ADOPTED`, `SUPERSEDED`, `NOT_DECIDED`. A `NOT_DECIDED` candidate uses `NEEDS_DECISION` and is not generated as a Decision.
+
+## Readiness semantics
+
+| readiness | meaning | generation |
+|---|---|---|
+| `READY` | grounded enough for the kind | allowed |
+| `NEEDS_EVIDENCE` | material assertion still lacks verification | blocked |
+| `NEEDS_DECISION` | direction sounds plausible but project has not decided | blocked |
+| `OPEN` | legitimate unresolved Question | allowed as Open Question |
+| `BLOCKED` | sources are incomplete or contradictory | blocked |
+| `REJECTED` | should not become a record | blocked |
+
+## Derivation rules
+
+1. Start from sections and evidence already present in detailed analysis; do not begin by brainstorming titles.
+2. Prefer several narrowly grounded Cases over one broad Case that combines unrelated incidents.
+3. Extract References only after identifying the invariant/selection criterion that survives outside the incident.
+4. Extract Questions from explicit uncertainty, missing verification, operational unknowns, or conflicting constraints.
+5. Extract Decisions only from explicit project choice evidence: ADR, commit/history, configuration plus recorded rationale, issue/PR decision, or user-supplied decision record.
+6. A node may relate to several siblings, but each record has one primary purpose.
+7. If new runtime evidence changes the answer, update detailed analysis and regenerate/review the tree before editing downstream records.