Extraction and the gate

Discovery decides which units exist. Extraction decides which files feed each unit's doc, and the gate decides whether the resulting doc is trustworthy.

Rule packs and the extraction surface

Which files feed a unit's doc is a judgment, so it lives in YAML rule packs per unit kind, not in code. Each rule pairs file globs (executed by the CLI) with an extraction prompt (executed by the agent reading the bundle).

The concept that matters most is the extraction surface: the union of a rule pack's globs is the unit's declared input set, and it becomes the unit of everything downstream. A doc derives only from its declared inputs, which is what makes drift precise - a one-character fix in an internal file the doc never read marks nothing (see Provenance and drift). The bundle is traceable the same way: every included file maps back to a rule-pack line.

Native docs, under a trust rule

Good repos self-document - contractual READMEs, generated event catalogs. Alloy distills what a repo asserts about itself rather than re-deriving it, but under a pinned trust rule baked into every bundle:

• Any fact derivable from code must be extracted from the code inputs.
• Native docs contribute only what code cannot assert - purpose, rationale, narrative.
• Where a native doc contradicts code, code wins.

So a stale README can color the story but can never corrupt the factual surface.

Coverage: the complement of a whitelist

A whitelist has a known failure mode: what it does not name is silently invisible. Coverage accounting is the complement that closes it. Every source element of an opted-in source lands in exactly one of three states:

• EXTRACTED - a rule covers it.
• EXCLUDED - a recorded decision with a mandatory written rationale.
• UNKNOWN - a surfaced gap demanding one of the other two.

UNKNOWN is remaining work, not an omission. This is covered in depth on Views and coverage; the point here is that extraction and coverage are two halves of one honest picture - what a rule reaches, and what no rule reaches.

The gate: eight validators

Before any doc can merge, alloy validate runs eight validators over it. Only errors block; a crash in one validator reports as a failure rather than aborting the run. The eight:

1. Frontmatter schema - the doc's metadata is well-formed.
2. Per-kind required sections - a doc of a kind has the sections its kind requires.
3. Imports - code fences follow the fence convention (real import statements are typescript; inline fragments are ts).
4. Type signatures - documented signatures are structurally sound.
5. Negative-knowledge minimums - When NOT to Use and Anti-Patterns meet minimum entry counts, because negative knowledge is what agents most lack.
6. Gap-marker surfacing - ⚠️ GAP markers are found and aggregated, turning unknowns into a tracked queue.
7. Lifecycle integrity - supersession edges resolve; a dangling tombstone is a merge-blocking error.
8. Curated governance - a hand-written doc carries its owner and freshness mechanism.

What the gate cannot check

The honest residual, named out loud: the gate checks a doc's shape, not its truth. generate then stamp with no real authoring in between still passes every validator. No check anywhere reads a source file and confirms that a sentence an author wrote is true of it.

That guarantee belongs to two things the gate cannot replace: an author who wrote or re-verified the doc against its actual source files, and a human who spot-reads against source at merge. The gate makes structure reliable so that human attention can go where only human attention works - to whether the prose is true.