# Tech Log Tree Contract

`tech-log-tree.json` is the explicit boundary between deep project analysis and Tech Log
record generation. **It is the decomposition contract and the index at once, and it is the
source of truth.** There is one file, so nothing can disagree with it.

A finished `tech-log-studio/` holds `tech-log-tree.json` and the record folders. Nothing
else.

A project whose index predates this contract fails verification with one error until it is
migrated. The per-field checks stay off for such a project — "not written yet" must not read
as "written wrong" — but non-adoption itself is counted, because a warning lets an old index
avoid every check indefinitely.

## Required top level

- `schemaVersion`
- `project`
- `ssot` and `ssotSha256` — the hash prevents treating a tree derived from old material
  as current
- `sourceRevision`
- `generatedAt`
- `sourceRepository` — `path`, `revision`, and `verified`: which checkout the analysis read,
  which commit the document describes, and how that was confirmed. Leave `revision` null rather
  than inventing one; the verifier warns instead of accepting a made-up label. When the work
  is spread over branches rather than one line of commits, use `revisions` — a label to commit
  map — and pin every tip the document describes
- `candidateScope` — which part of the SSOT candidates may come from
- `contract` — the decomposition rules, `readinessValues`, `dispositionValues`
- `topics`, `candidates`, `counts`, `unlisted`

## Candidate scope

A folded `final/document.md` carries the integrated analysis, the module analyses, and the
analysis material in one file. Only the first is candidate material.

```json
"candidateScope": {
  "document": "final/document.md",
  "sections": ["§3", "§4", "§5", "§6", "§7", "§8", "§9", "§10", "§11"],
  "excluded": ["제2부 — 모듈 분석 전문", "제3부 — 분석 재료"]
}
```

`document` names the SSOT and must match `ssot`. `sections` names the candidate scope, and
`excluded` names the parts that are evidence rather than candidates. A node may cite an
anchor from an excluded part in `source`; it may not exist because of one.

## Topics

Each Topic has `topic` (its key), `title`, **`readerQuestion`**, and `kinds` with the five
record kinds.

```json
"oauth-oidc-auth-boundary": {
  "topic": "oauth-oidc-auth-boundary",
  "title": "OAuth 자격증명과 세션의 보관 경계",
  "readerQuestion": "자격증명과 세션을 누가 보관하고, 누가 API 요청을 만들며, 보호 자원은 무엇을 신뢰하는가?",
  "kinds": { "case": [], "concept": [], "reference": [], "question": [], "decision": [] }
}
```

Every node in the Topic must help answer the reader question. Two Topics do not share a
question; one Topic does not need two. Empty kinds are allowed — do not manufacture nodes
to fill all five.

## Candidates

Everything the analysis found lives in `candidates` with its disposition —
`.agents/skills/deriving-tech-log-root-tree/references/candidate-disposition.md`. Only
`PROMOTE` candidates become nodes under `topics`, and the relation runs both ways: a
`PROMOTE` candidate whose target is not a node, and a node no `PROMOTE` candidate points
at, are both contract errors.

`dispositionReview` records whether a person re-read the candidate under the independence
test. `PENDING` means it reached the tree by recall alone, and a `PENDING` candidate is an
error, not a warning — a record written over an unreviewed tree inherits the
over-classification the disposition step exists to catch. Write records only for nodes
whose candidate is `PROMOTE` and `CONFIRMED`.

## Written by hand, refreshed by script

`readiness` · `source` · `code` · `evidence` · `classification` · `relations` and the rest
of each kind's fields are written by a person. `build-tech-log-tree.py` never touches them.
It refreshes only what it can read from the record files — `file`, `publication`, `status`,
`studioId`, `assets`, `evidenceFiles` — and lists records that have no node in `unlisted`.

### Case

`slug` · `readiness` · `source` · `classification` · `missing-verification` · `relations`,
plus `code`/`evidence` when the conclusion depends on them.

One problem, an observation or reproduction, a diagnosis, a conclusion that closes. Several
observations that answer the same question with the same conclusion are one Case with a
table or sub-sections, not several partial Cases.

### Concept

`slug` · `readiness` · `source` · `basis-version` · `classification` · `relations`.

`basis-version` names what the explanation was written against — `Keycloak 26.7.0 identity
brokering`, `Spring Boot 3.3 auto-configuration`. A Concept without it cannot be known to
be stale.

A Concept exists because a Case, Decision, or Question needs it to be understood. Absence,
call-counts, unwired subsystems, analysis scope, and coverage ledgers are not Concepts.

### Reference

`slug` · `readiness` · `source` · `classification` · `scope` · `exceptions` · `relations`.

A Reference must be useful beyond retelling one Case. If removing the originating
project's names leaves no rule, it is still a Case.

### Open Question

`slug` · `readiness: OPEN` · `source` · `known` · `unknown` · `next-verification` ·
`decision-criterion` · `relations`.

Do not create a Question when the analysis already contains a verified answer. Move the
material to Case/Reference/Decision and update the tree first.

### Decision

`slug` · `readiness` · `decision-status` · `source` · `decision-evidence` · `grounds` ·
`classification` · `relations`.

`decision-status` is `PROPOSED`, `ADOPTED`, `SUPERSEDED`, or `NOT_DECIDED`. A
`NOT_DECIDED` candidate uses `NEEDS_DECISION` and is not written as a Decision.

## Readiness semantics

**`readiness` is about evidence, not about publication.** Whether a record has been
written, and whether it has been saved into Studio, are separate facts that the generated
index carries as `file` and `publication`. A published record with thin evidence is still
`NEEDS_EVIDENCE`.

| readiness | meaning | generation |
|---|---|---|
| `READY` | grounded enough for the kind | allowed |
| `OPEN` | legitimate unresolved Question | allowed as Open Question |
| `NEEDS_EVIDENCE` | material assertion still lacks verification | blocked |
| `NEEDS_DECISION` | direction sounds plausible but the project has not decided | blocked |
| `BLOCKED` | sources are incomplete or contradictory | blocked |

`REJECTED` is not a readiness. Whether a candidate becomes a record at all is a
disposition, and it lives in `candidates`, not on the node.

## Derivation rules

1. Discover candidates from `final/document.md` only. It is the whole analysis, folded in —
   there is no `analysis/` folder to search in a finished project.
2. Give every candidate a disposition before writing any node. `KEEP_IN_SSOT` is a normal
   outcome, and a decomposition that excludes nothing has not selected anything.
3. Apply the independence test: if folding the record into a related Case or Concept as
   one section changes nothing, it is not an independent record.
4. Take Cases, References, Decisions, and Questions first; add Concepts backwards from
   what those four require.
5. Prefer several narrowly grounded Cases over one broad Case combining unrelated
   incidents — but merge observations that share a question and a conclusion.
6. Extract Decisions only from explicit choice evidence: ADR, commit/history, configuration
   plus recorded rationale, issue/PR decision, or a user-supplied decision record.
7. A node may relate to several siblings, but each record has one primary purpose.
8. If new runtime evidence changes the answer, update the analysis and revise the tree
   before editing downstream records.

## Generation and verification

```bash
python3 scripts/build-tech-log-tree.py <project>    # 파생 칸을 다시 채운다
python3 scripts/verify-tech-log-tree.py <project>   # error 0 이어야 한다
```