parents

A commit-pinned, distilled, LLM-consumable reference on the upstream projects clawdie descends from — FreeBSD, NomadBSD, OpenZFS, and the handful of others whose behavior our own code must stay consistent with.

It exists so an agent (Claude, pi, Hermes) or a human can answer "how does the upstream actually do X" against a stable, cite-able ground truth that cannot drift overnight — without a live network fetch, without burning API credits, and without trusting a mirror's moving HEAD.

Where this sits

mother births and coordinates the hive at runtime. parents are who our source descends from. Same family metaphor, different axis — one is runtime kin, the other is genealogical lineage. They do not overlap.

What it is / is not

It is:

• Small, sliced snapshots of upstream source, committed at a pinned SHA — the cite target. Not the whole tree; only the subsystems we actually touch.
• Distilled notes ("the why/how") that cite into those snapshots by file :: symbol at the pinned SHA.

It is not:

• A full mirror of FreeBSD/OpenZFS (that buys nothing and rots).
• A live tool. For fast exploration of upstream current state, use the zread MCP (reads GitHub HEAD, no at-SHA pin) — then land the durable, pinned version here. The two are complementary: zread explores, parents pins.

Why not the built-in wiki

This is wiki-shaped content, but the built-in wiki is a separate .wiki.git with web-only edits and no CI — which would split every note from the source snapshot it cites, skip PR review, and skip the drift-lint. So notes live in the repo tree (rendered and cross-linked like a wiki via INDEX.md), matching the colibri docs/wiki/ precedent. Same reasoning: lint-gated, reviewed, one history.

Invariants (the whole discipline)

1. Everything cites a pin. Every note records the upstream repo@SHA it was distilled from. No pin, no note.
2. Snapshots are committed, never submodules. A submodule points at a ref that can move and agents trip over it. A committed slice-at-SHA is in our git history — it cannot drift and needs no network to prove what was cited.
3. Drift-lint is file-granular, and it only prompts — never auto-fixes. git log <pinnedSHA>..<upstreamHEAD> -- <file> tells you a cited file has moved since your pin, i.e. "re-read this." It does not keep the note correct for you.
4. Notes cite snapshots, not the live web. A file :: symbol reference resolves inside snapshots/<upstream>/ at that upstream's PIN.
5. Kill-criterion. This is a discipline problem, not a tooling one. If no entry is re-read during real work within ~4-6 weeks, we stop filling it. Success is not "we built it" — it's "an agent re-read an entry during a live task."

Layout

parents/
  README.md                  # this file
  CONVENTIONS.md             # provenance-header spec + cite format + lint contract
  INDEX.md                   # roadmap table + one line per note (the landing page)
  lint/
    drift-check.sh           # per-note: git log pin..HEAD -- <cited files>
  notes/                     # topic-organized, distilled; a note may cite >1 upstream
    zfs-label-flush.md
  snapshots/                 # upstream-organized source slices (backfilled on demand)
    freebsd-src/
      PIN                    # <branch> @ <full-SHA> (<read-date>)
      LICENSE / COPYRIGHT    # preserved verbatim once source lands
    openzfs/
      PIN

Notes are topic-first (they cross upstreams). Snapshots are upstream-first (they are source trees). A note's file :: symbol cite resolves into snapshots/<upstream>/… at that upstream's PIN.

Notes-first, snapshots on demand

The repo starts notes-first: a note records its PIN and cites file :: symbol against it, but the sliced source is backfilled only when a topic earns re-reads (the kill-criterion). Until backfilled, a cite resolves via zread or upstream at the pinned SHA. This keeps the repo small and honest about which subsystems actually pay for their MB.

Provenance header (every note carries one)

---
title: <what this note answers>
read_date: <dd.mmm.yy>
parents:
  - repo: freebsd/freebsd-src # <branch> @ <full-SHA> (<date>)
    cites:
      - "sys/dev/md/md.c :: mdstart_vnode"
local_anchor: "<the clawdie code this is about — repo :: symbol (~Lnnn)>"
---

Cite by file :: symbol, not file:line — lines shift on every edit; symbols + a pinned SHA are the stable pair. Full spec in CONVENTIONS.md.

License hygiene (when source lands in snapshots/)

All current parents are permissively licensed, so vendoring sliced source is fine — provided the upstream license travels with it:

Upstream	License	Requirement in snapshots/<upstream>/
FreeBSD src	BSD-2-Clause	keep COPYRIGHT + per-file headers verbatim
OpenZFS	CDDL-1.0	keep LICENSE + per-file CDDL headers verbatim
NomadBSD	BSD-2-Clause	keep COPYRIGHT/license verbatim

Never strip a source header to "clean up" a slice. The header is the license.

Conventions inherited from the clawdie repos

• Dates are dd.mmm.yy (e.g. 06.jul.26).
• Markdown passes the format gate before push (ported from clawdie-iso's check-format.sh). CI runs it (.forgejo/workflows/format.yml, blocking) plus lint/drift-check.sh (drift.yml, advisory + weekly).
• Origin is Forgejo code.smilepowered.org:clawdie/parents; contribute by PR.

How it gets used

• Agents grep notes/ for the topic, read the verdict, and when they need ground truth follow the file :: symbol cite into snapshots/. No fetch.
• Contributors add an entry by: recording the PIN, writing the note with the provenance header, adding one line to INDEX.md, and (when the topic earns it) committing the source slice. lint/drift-check.sh surfaces stale pins at PR time.

Start at INDEX.md.