KichmaDocs
Sign in

The entity and edge model

Kichma is a typed graph, not a folder of documents. Documents are a view of it — editable, but never a second source of truth. This page is the model the code enforces: the tables below are generated from the same constants the database constraints and the authoring validator read.

Entities

7 node types in 4 zones, each owned by a document stage. The definitions are deliberately crisp and non-overlapping — the failure mode of every traceability graph is fuzzy adjacent rungs.

TypeDefinition
IdeaI-The raw thesis. One per project.
Market RequirementMR-A validated market/user problem. Why anyone cares.
RequirementR-A committed product behavior. What we promise to build.
Design InputDI-A measurable, testable engineering input refining a Product Requirement. What the design must provably do.
ComponentC-A durable architectural part. What the system is made of.
TaskT-A transient unit of work. What someone does this week.
MilestoneM-A dated grouping/checkpoint. Orthogonal — groups Tasks.

Identity — the graph never forgets

Every node carries two identities. An opaque canonical id that all edges bind to, and the friendly display key you actually see — R-7, T-42. Both are immutable, and neither is ever reused.

Never-reuse is the load-bearing half. Display keys end up in branch names and pull request titles, so a branch cut six months ago must still resolve to the same task — and must never resolve to a different one. Deleting R-7 retires the number 7 permanently.

A deletion is a tombstone, not a removal: the node keeps its id and its edges, marked dead, so nothing dangles and a revert is one click. Rewording a node keeps its id and appends a version; a split or merge mints new ids and records split-into / merged-from edges rather than silently retargeting an existing key. Every version carries who wrote it and why, and because the history is append-only, an attribution can never be erased.

Edges

11 edge types in four categories. The category is what decides whether an edge is on the trace path, feeds the forecast, or is simply history.

Spine

The load-bearing Why trace. Four hops, and it never passes through an overlay — so traceability survives a project that skips the design stage entirely.

  • traces-toMarket Requirement → Ideadrives rollups
  • derives-fromRequirement → Market Requirementdrives rollups
  • implementsTask → Requirementdrives rollups

Overlays

Where the work lives and when it lands. These enrich the record when a team does that work; absent, they never break the trace.

  • refinesDesign Input → Requirementdrives rollups
  • realizesComponent → Requirement
  • satisfiesComponent → Design Input
  • touchesTask → Component
  • belongs-toTask → Milestonedrives rollups

Sequencing

Ordering between units of work — the structure the forecast is computed from.

  • depends-onTask / Component → Task / Component

Provenance

Split and merge history. A key is never silently retargeted, so a retired one keeps a forwarding address.

  • split-intoany node → any node
  • merged-fromany node → any node

The seam law

Every derivation seam in the graph obeys the same four rules, so one mental model spans the whole chain:

  1. 1Many-to-many. It is a graph, not a tree.
  2. 2One primary edge per child drives the rollups and the forecast. Extra “also-serves” edges are traceability only and never double-count.
  3. 3Must trace up — enforced. Every child needs at least one parent. An orphan is build-with-no-why, so the engine surfaces it by key rather than tolerating it.
  4. 4May be childless — allowed. A parent with no children is the honest backlog: validated, not yet built.

Net effect: solution-space is strictly bounded by problem-space, while problem-space is free to run ahead. The seams the law applies to:

  • Requirement (R-) derives-from Market Requirement (MR-) — every requirement needs at least one market requirement; a market requirement may have none.
  • Design Input (DI-) refines Requirement (R-) — every design input needs at least one requirement; a requirement may have none.
  • Task (T-) implements Requirement (R-) — every task needs at least one requirement; a requirement may have none.

Three axes

A task sits at the intersection of three independent questions, and only the first is load-bearing:

  • Why — what promise does this serve? Task → Requirement → Market Requirement → Idea. Drives the forecast and answers “is R-7 done?”
  • Where — what part of the system? An overlay onto components, from the design stage.
  • When — what checkpoint? An overlay onto milestones.

Components are deliberately off the spine. If the trace had to pass through them, a team that defers its design document would have no traceability and no forecast — breaking the promise for exactly the lightweight teams the product lands on first.

What flows along the spine

A static graph is a prettier document generator. What moves when something changes is the part that matters, and it moves in two directions.

Up — completion. Truth is set only at the task, from an objective git signal: a merged pull request. Everything above is derived, never authored. A requirement is satisfied only when all of its primary tasks are done — you never get to say yes until it is truly yes — while progress is a separate, duration-weighted percentage for the forecast bar, because nine trivial tasks and one enormous one are not 90% of the time. A requirement with no tasks reads 0% and “unbuilt”, never “done”.

Down — staleness. Changing a node's content flags what sits downstream of it as may be stale, and never rewrites it. The flag carries its reasoning — which change, and why it might matter here — and a human either clears it or opens the edit. An automatic rewrite would be a source-of-truth product quietly editing the record, which is the one thing it must not do.