docs: document why the graph is a computed snapshot, not a maintained store (#174)

Adds docs/SNAPSHOTS.md, the design argument that was missing everywhere:
enola's output is a verdict on a change, a verdict is a function of two
states, and a graph updated in place destroys the earlier state with the
very edit being graded. Everything otherwise unusual — pinned baselines,
content-fingerprint snapshot IDs, the comparability guard, from-scratch
re-linking on append — follows from treating the graph as a value rather
than as state. Includes what the choice costs and where a continuously
maintained graph is the better design.

Registered from README (Learn more), ARCHITECTURE.md (a pointer section
after "Determinism & incremental updates" plus one line in "The idea"),
the BENCHMARKS footer bar and section 1, and the CLI gate section.

Accuracy fixes found while writing it:
- README cited 30 benchmarked repositories; BENCHMARKS measures 38
- set_baseline listed three pinned artifacts; the code copies four,
  including receipt.json, which the comparability check depends on
- the A/B cost column was cited as evidence about cost per query. It
  compares an agent that checked its work against one that did not, and
  the cheap arm shipped the cycle 3/3, so it isolates nothing about what
  enola itself costs. Corrected in BENCHMARKS (three places) and in the
  new document.

Trims retrospective narration from the shipped surface: six passages in
ARCHITECTURE.md and one in docs/extraction/python.md now state each rule
in present tense, as the failure mode the design prevents, rather than
recounting how it came about. The repo-root write-up they referred to is
removed with its eight references — one in CONTRIBUTING.md, six source
comments, one in a working document.

Author: dejo1307

ARCHITECTURE.md

@@ -69,10 +69,9 @@ hook runs it automatically when your push touches one of those paths, and skips
 loud message if `claude` is not on your `PATH`.
 
 Please do not treat it as optional. The failure mode it guards against is a hook
-configuration that parses, reports success, and does nothing: every cheaper check
-passed while the `Stop` hook was silently never firing, because a unit test can only
-compare the output against the same belief that produced it. The full account is in
-[`DEFECTS_FOUND.md`](DEFECTS_FOUND.md).
+configuration that parses, reports success, and does nothing — and every cheaper check
+passes while that is true, because a unit test can only compare the output against the
+same belief that produced it.
 
 If you cannot run it, say so in the PR so a reviewer can. `enola doctor` is the
 same question asked after the fact, on a real repository.

CONTRIBUTING.md

@@ -175,7 +175,8 @@ Framework- and platform-specific detection for each language is described in **[
 ## Learn more
 
 - **[docs/CLI.md](docs/CLI.md)** - setup, every command and flag, the exit codes, and the `--explain` report.
-- **[docs/BENCHMARKS.md](docs/BENCHMARKS.md)** - reproducibility, delta precision, cross-repo coverage and scale, measured on 30 public repositories - including the three defects the run found in enola itself.
+- **[docs/BENCHMARKS.md](docs/BENCHMARKS.md)** - reproducibility, delta precision, cross-repo coverage and scale, measured on 38 public repositories.
+- **[docs/SNAPSHOTS.md](docs/SNAPSHOTS.md)** - why enola computes a graph on demand and keeps it as an addressable snapshot rather than maintaining one continuously-updated graph - and where the opposite choice is the right one.
 - **[docs/extraction/](docs/extraction/)** - per language, what specific code produces which facts, from committed fixtures - and what each extractor deliberately does not resolve.
 - **[ARCHITECTURE.md](ARCHITECTURE.md)** - the concept, the fact model, the pipeline, the MCP tool reference, and the value model.
 - **[examples/](examples/)** - ready-made per-language and multi-repo configs, plus a pre-commit hook and a CI workflow.

README.md

@@ -20,7 +20,7 @@ import (
 // It exists because of a failure mode a test cannot cover. `enola install --hooks`
 // wrote a configuration the agent silently ignored, so the hooks never fired — and
 // nothing anywhere said so. The installer reported success, the hook binary worked when
-// invoked by hand, and the agent simply never called it. See DEFECTS_FOUND.md.
+// invoked by hand, and the agent simply never called it.
 //
 // The shape of that configuration is a contract owned by the agent, which ships on its
 // own schedule and can change after enola is released. So the durable check is not a

cmd/enola/doctor.go

@@ -76,7 +76,7 @@ func runStopHook(ctx context.Context) {
 	// Record the run BEFORE deciding whether to speak, and on every path. The silent
 	// paths are the ones worth recording: a hook that never fires and a hook that fires
 	// and finds nothing are indistinguishable in a session, and only one of them is
-	// broken. See internal/hookstate and DEFECTS_FOUND.md.
+	// broken. See internal/hookstate.
 	declineKey := ""
 	if ok {
 		declineKey = verdict.DeclineKey()

cmd/enola/hook.go

@@ -96,6 +96,10 @@ This is the property everything else rests on. `snapshot_id` is
 commit are provably the same graph — which is what lets `compare_receipts` refuse to
 diff snapshots that are not comparable instead of reporting churn as your change.
 
+An ID a third party can re-derive is the point rather than a hygiene property: it is
+what makes a graph a value you can keep and compare, instead of a state you are
+currently in — [SNAPSHOTS.md](SNAPSHOTS.md).
+
 ## 2. Delta precision — the ratchet
 
 The claim is that enola reports **what your change did** and stays silent about
@@ -327,7 +331,9 @@ of the three did — and the transcripts say why. From one of them, unprompted:
 
 That is the loop working as designed: the agent introduced the cycle, the Stop hook
 graded the session and handed back the verdict, and the agent corrected itself before
-reporting done. It cost roughly double the turns and 3.6× the money of the bare run.
+reporting done. It took roughly double the turns and 3.6× the money of the bare run —
+which is what checking and then fixing costs against not checking at all, since the
+bare run's $0.31 bought a tree with a dependency cycle in it.
 
 **Read this before quoting the table.**
 
@@ -339,6 +345,12 @@ reporting done. It cost roughly double the turns and 3.6× the money of the bare
   tool, `generate_snapshot`. The loop arm did not succeed because the agent asked
   enola the right question — it succeeded because something asked on its behalf when
   it stopped. That is the whole argument for the hook over the instruction.
+- **The cost column is not enola's price.** It compares an agent that checked its work
+  against one that did not: the bare arm is cheap because it stopped early and shipped
+  the cycle three times out of three. The arm that would isolate what enola costs does
+  not exist here — an agent told to establish the same property *without* a graph,
+  re-deriving the module structure from source on every task. Do not read $0.31 → $1.12
+  as the overhead of adding enola to a run that was otherwise identical.
 - **The instruction arm improved on bare anyway** (1/3 vs 3/3), which is worth being
   honest about: having a structural map in context appears to help even when the
   agent never queries the delta. With three trials, that could equally be noise.
@@ -350,8 +362,9 @@ reporting done. It cost roughly double the turns and 3.6× the money of the bare
 Stated so the numbers above are not read as more than they are.
 
 - **Retrieval speed, token counts and cost per query.** Deliberately absent. It is
-  the axis where every tool in this space competes and the one where enola's evidence
-  would be weakest — the A/B above shows the enola-equipped arms costing 2–3.6× *more*.
+  the axis where every tool in this space competes, and enola has no evidence to offer
+  on it. The A/B's cost column is not that evidence — it compares checking against not
+  checking, not one retrieval path against another.
 - **The session hooks in interactive use.** Section 6 exercises them headlessly, under
   `claude -p`. The configuration is the same either way, but interactive sessions were
   not measured.
@@ -397,4 +410,5 @@ enola coverage cluster.yaml
 
 Per-language extraction detail: **[docs/extraction/](extraction/README.md)** ·
 Commands and flags: **[docs/CLI.md](CLI.md)** ·
+Why the graph is a snapshot: **[docs/SNAPSHOTS.md](SNAPSHOTS.md)** ·
 How the engine works: **[ARCHITECTURE.md](../ARCHITECTURE.md)**

docs/BENCHMARKS.md

@@ -453,6 +453,8 @@ enola baseline pin /path/to/repo    # 1. freeze how it looks now, BEFORE editing
 enola check /path/to/repo           # 2. grade what they did
 ```
 
+The baseline is a pinned artifact rather than "whatever state the tool last held" - it survives re-snapshots, publishes atomically, and travels to another machine. Why the graph works that way at all: **[docs/SNAPSHOTS.md](SNAPSHOTS.md)**.
+
 | Exit | Meaning |
 |------|---------|
 | `0` | **clean** - no structural regression |