kg-extractlisted

# Codebase Extract — Systematic Architecture Mapping ## Purpose Extract builds a two-tier navigation index in the project graph. The goal is precise: **let future sessions answer "should I read this file?" without opening it.** Filenames and directory listings tell you what exists. The KG tells you what each piece *handles* and — equally important — what it *doesn't*, so skip decisions are reliable. ## Two Tiers ### Tier 1 — Subsystem nodes (5–10 per project) Directory-scale orientation. Answers: "which part of the codebase?" ``` kg_put_node(level="project", id="auth-subsystem", gist="JWT issue/verify + refresh flow. No user lookup, no permissions — those are in user-subsystem.", touches=["src/auth/"]) ``` ### Tier 2 — Component nodes (built lazily, 15–40 total when mature) File-cluster-scale. Answers: "which file within that area?" One node covers 1–5 tightly related files that always change together. ``` kg_put_node(level="project", id="auth-token-signing", gist="Signs/verifies JWTs only. Key rotation logic here, not in middleware.", touches=["src/auth/jwt.ts", "src/auth/keys.ts"]) ``` Component nodes are **never created upfront in bulk** — only when you actually explore that area during a task. They accumulate naturally as the codebase is worked on. ## Node Types | Type | Tier | What it represents | |------|------|--------------------| | `subsystem` | 1 | Major bounded area (auth, payments, ingestion pipeline) | | `component` | 2 | Specific file cluster