The `lineage` annotation (a reusable critical-path standard)

The lineage annotation (a reusable critical-path standard)

A lineage block is a small HTML comment embedded near the top of any markdown artifact. It is invisible when rendered, but it declares the artifact’s place in the dependency graph so a change to a canonical decision can be swept down every path it must reach. Think slime mold: the blocks are the tubes; critpath is the pulse.

Format

Fields

Field	Meaning
role	source-of-truth · amendment (feeds a source) · fallback · derived · index. Cosmetic + helps reading.
conforms_to	the source(s) this artifact must not contradict (usually CANON.md). An edge → source.
depends_on	sibling artifacts this one builds on. Edges → those files.
defines	the canonical terms/decisions this artifact OWNS. A term should have exactly one real owner (the source).
consumes	the canonical terms this artifact USES. This is what makes a term-sweep precise.

Paths are repo-relative. Term tokens are free-form but must match across docs (use the spelling the owner defines).

How critpath uses it

• graph — builds the DAG from conforms_to/depends_on, ranks the trunk by downstream flux (how many artifacts a change here reaches), prints the critical path (longest conformance chain), and lists untracked (.md with no lineage — invisible to sweeps) and dangling edges.
• sweep <term> — finds the term’s owner, then classifies every artifact:
  • SOURCE — owns the term.
  • REVIEW — declares consumes: <term> and literally contains it → confirm it’s the new sense.
  • HIDDEN-DEP — contains the term but its lineage doesn’t declare it → the tube is missing; add it.
  • UNTRACKED — contains the term but has no lineage at all → starved node; annotate it.
• lint — artifacts missing a lineage block.

Why a term needs a single defines owner

The owner is the nutrient source. When you change a term’s meaning, you change it once at the owner, then run sweep <term> to drive the update to every consumes node. UNTRACKED/HIDDEN-DEP results are the slime mold telling you a path exists in reality (the literal token) that the network hasn’t reinforced yet — wire it up.

Adoption

Reusable for any doc package: drop a lineage block in each file, give your canonical doc role: source-of-truth with a full defines: list, and run critpath graph.