Schema — thin local state

Thin local state. Every record (task · lane · lesson · investigation · artifact) is a thin local entity. No global container; no embedded duplicates; cross-references go by id.

🌳 evergreen tended 2026-05-08 schema contracts thin-state

flowchart LR
  record[record: thin local] --> id[(id)]
  id --> ref1[other refs by id]
  record --> field[fields: typed]
  record -.never embeds.-> other[other records]

Read next

• TODO — the human-readable index
• Frontier — investigation records
• Rating & priority — the priority field
• Patterns — where conventions live

Authoritative types in tasks/schema.py. Thin records compose; dense aggregates drown.

Every state record (task, lane, lesson, investigation, artifact) is a thin local entity. No global container; no embedded duplicates of other records. Cross-references go by id.

Authoritative types: tasks/schema.py.

Why thin

Dense aggregate files (e.g. a 97k-token NEXT.md) drown both humans and models in context they didn't ask for. Thin records, addressed by id and rendered on demand, let the reader expand only what they need.

The five entities

classDiagram
  class Task {
    +id: str
    +title: str
    +rating: Rating
    +status: TaskStatus
    +created: date
    +due: date?
    +parents: str[]
    +children: str[]
    +artifacts: Artifact[]
    +refs: str[]
  }
  class Artifact {
    +kind: input|build|result|diff
    +ref: str
    +when: date
    +note: str
  }
  class Investigation {
    +id: str
    +title: str
    +rating: Rating
    +levels: L0|L1|L2|...
    +refs: str[]
    +inspiration: str[]
    +mermaid: str?
    +open_questions: str[]
  }
  class Lane {
    +id: str
    +session: str
    +domain: str
    +intent: str
    +expect: str
    +artifacts: Artifact[]
  }
  class Lesson {
    +id: str
    +title: str
    +session: str
    +domain: str
    +rating: Rating
    +external_ref: str?
  }
  Task "1" o-- "*" Artifact
  Investigation ..> Task : refs
  Lane ..> Task : refs
  Lesson ..> Lane : produced by

Field discipline

• id is monotonic and never reused.
• rating ∈ {bad, medium, good}. Drives ordering. See RATING-AND-PRIORITY.
• status ∈ {open, in-progress, blocked, done, abandoned}. Closed states (done, abandoned) freeze the record; new info goes to a successor task.
• created / due / when are ISO dates. No relative phrasing ("next week").
• artifacts.kind ∈ {input, build, result, diff}. Track all four — the diff (expect vs actual) is the learning signal.
• refs are id-strings or stable URLs. Never paste foreign content into a record; link.

Validation

python3 -c "from tasks.schema import Task, Rating, TaskStatus; print('ok')"

A future tools/validate_tasks.py will round-trip every record in tasks/TODO.md through schema.py and fail loudly on shape drift. Tracked as task T-006.

Rendering rule

Markdown tables in tasks/TODO.md are the human view; schema.py is the contract. If the markdown drifts from the schema, the schema wins.