document-haness/.agents/skills/writing-tech-log-records/references/tech-log-tree-contract.md

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.

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

"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

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