[ancsingabor]

Your instinct was right, and it found the sharpest thing in this whole review.

The example was the counter-example

Both READMEs used Summa I q.2 a.3 as the specimen of a verifiable citation. An article is a chunk, not a unit (ADR-002 § Amendment) — and q.2 a.3 is the worst possible choice, because it asks whether God exists, so its objections argue that he does not. lib/corpus/chunk.ts spells the failure out:

An objection states a position Aquinas is about to reject, often in crisp, quotable, highly retrievable prose. Retrieved without its role, "videtur quod Deus non sit" is a chunk that resolves to a real locator, quotes byte-exactly, passes the citation gate, and cites Thomas Aquinas for the non-existence of God.

So the headline example of the project's central guarantee was an address that cannot deliver that guarantee.

It survived four earlier passes because each grepped summa:I.q2.a3 — the locator form. These two were written as prose, *Summa* I q.2 a.3, so no search for the locator ever touched them.

• 30-second pitch → uses only Catechism §1730.
• 2-minute pitch → uses q.2 a.3 deliberately, as the worked example of why units are leaf-level.
• Top-level README.md → I q.2 a.3 *co.*

"chunk" was introduced as the enemy, then used as ours

The page says other systems' "citations are therefore chunk IDs, which mean nothing outside the system" — and then, nine lines later, "chunking follows each source's own structure", with nothing in between saying these are two different objects. A reader meets the distinction for the first time in chapter 02. It is now stated where both words are first used: a unit is what we cite, a chunk is what we embed, plus chunk.ts's real payoff — re-tuning the chunker cannot invalidate a stored citation, which is what makes chunking a variable the harness can move rather than a decision that must be right first time.

An internal contradiction, two bullets apart

	said
ingestion bullet	"writes the result to Postgres with pgvector. That half is built"
query-path bullet	"waits on one open decision: which embedding model to use"

Both cannot be true. Nothing is embedded — embed is deliberately unimplemented until ADR-008 is decided. Now stated once, naming why the two halves share one blocker: a query and the corpus compare only if the same model embedded both.

Two smaller ones, same family:

• "Query path — it retrieves units." It retrieves chunks and cites the units inside them (guide 06's own diagram: chunks → units (context)). That flattening is the exact vagueness this PR is about.
• Conventions defined a locator as source:address without saying it names a unit — the omission that let the Summa example through. Fixed.

1,187 words (was 917), under the budget. docs:lint green.

🤖 Generated with Claude Code