# 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.