enola-labs
diff --git a/‎.gitignore‎
Lines changed: 5 additions & 0 deletions b/‎.gitignore‎
Lines changed: 5 additions & 0 deletions
diff --git a/‎ARCHITECTURE.md‎
Lines changed: 40 additions & 1 deletion b/‎ARCHITECTURE.md‎
Lines changed: 40 additions & 1 deletion
diff --git a/‎README.md‎
Lines changed: 81 additions & 2 deletions b/‎README.md‎
Lines changed: 81 additions & 2 deletions
@@ -8,6 +8,11 @@
 *.so
 *.dylib
 
+# The binary produced by `go build -o enola ./cmd/enola` (the command CONTRIBUTING.md
+# gives). Leading slash on purpose: an unanchored `enola` would also match the
+# cmd/enola/ DIRECTORY, silently hiding every new source file added there.
+/enola
+
 # Test binary, built with `go test -c`
 *.test
 
 
@@ -223,6 +223,8 @@ The shared module-graph construction and statistical-outlier helpers used by sev
 
 `--help`, `--list` and `--status` are served from two public packages, for the same reason as `pkg/explain`: a wrapper binary must be able to print *its* version of each without restating the shared text. Both extension points are plain data, so nothing a wrapper adds is known here.
 
+**Subcommands vs. flags.** `check`, `baseline` and `upgrade` are dispatched in [`cmd/enola/main.go`](cmd/enola/main.go) *before* the flag loop, and each owns a `flag.FlagSet`. The loop itself is an exact-match switch over `os.Args` and cannot parse `--flag=value`, so anything taking its own flags has to be a subcommand. The loop's `default:` case **validates** rather than absorbs: a directory is a repository, an existing file is a config, and anything else is rejected. It used to pass every unrecognized token through as a config path, and because an unreadable config is only a *warning* inside `config.Load` — by design, so a missing `mcp-arch.yaml` falls back to defaults — every typo inherited that leniency and became a silent wrong action (`enola chekc .` started an MCP server; `enola --generate /does/not/exist.yaml` snapshotted the working directory). The default-path fallback is unchanged; only an *explicitly named* path that does not exist is now fatal.
+
 **[`pkg/cli`](pkg/cli)** renders what a binary prints about itself.
 
 - `OSSTools()` is the `--list` catalogue: name plus a one-line summary. It is hand-written on purpose — the descriptions registered with `mcp.AddTool` are multi-paragraph agent prompts, unusable in a terminal. `TestE2E_ToolCatalogueMatchesRegisteredTools` ([`internal/server/e2e_test.go`](internal/server/e2e_test.go)) asserts set equality against the tools the running server actually registers, so the two cannot drift. `RenderToolList(ToolListSpec)` renders it; a wrapper passes its own tools in `Extra` (or an unlock note via `ExtraLocked`/`LockedNote`), and with a zero spec the output never mentions that a wrapper exists.
@@ -557,6 +559,8 @@ Per-service edge-coverage report, so you can tell a genuinely isolated service f
 
 Pins the current snapshot as a diff baseline by copying the snapshot artifacts (`facts.jsonl`, `insights.json`, `snapshot.meta.json`) into `.enola/baseline/`. Call it once at the start of a task, after the first `generate_snapshot`. The pinned baseline **survives subsequent `generate_snapshot` runs**, so it stays valid across several rounds of edits — unlike the auto-rotated `.enola/previous/`, which only ever holds the immediately-preceding run. Takes no parameters.
 
+> The CLI equivalent, `enola baseline pin [repo|config]`, **snapshots first and then pins** — there is no separate `--generate` step. The MCP tool cannot do that (the agent has just generated, and re-generating inside the tool would be surprising), but from a shell "pin a baseline of this repo" is one intent, and pinning whatever happened to be on disk risks freezing a days-old snapshot as "the state before my change" — precisely the staleness the diff then warns about.
+
 ### `diff_snapshot` — "what did my change actually do?"
 
 Computes the architectural **delta** between a baseline snapshot and the current one. This is the verification counterpart to `impact_analysis`: where impact analysis *plans* a change, diff_snapshot *confirms* it, replacing "re-read the files to check what got built" with a deterministic answer.
@@ -583,7 +587,42 @@ The typical loop is `generate_snapshot → set_baseline → edit → generate_sn
 | `output_mode` | `summary` (default — headline regressions/improvements + structural tally) → `compact` (adds finding descriptions, evidence, and the changed edges/facts) → `full` (complete JSON). |
 | `max_tokens` | Optional hard cap on output size. |
 
-The engine lives in [`internal/diff`](internal/diff/diff.go) (pure `Compute` + deterministic renderers) and is re-exported for out-of-module use via [`pkg/diff`](pkg/diff/diff.go); baseline persistence and the on-disk loader live in [`internal/engine/baseline.go`](internal/engine/baseline.go). `diff_snapshot` also runs the **comparability guard** (`diff.CompareMeta`): it reads the receipt fields on both snapshots' metadata and warns, above the delta, when they were not generated over equivalent inputs.
+The engine lives in [`internal/diff`](internal/diff/diff.go) (pure `Compute` + deterministic renderers) and is re-exported for out-of-module use via [`pkg/diff`](pkg/diff/diff.go); baseline persistence, the on-disk loader and the shared selector resolution (`ResolveBaselineDir`) live in [`internal/engine/baseline.go`](internal/engine/baseline.go). `diff_snapshot` also runs the **comparability guard** (`diff.CompareMeta`): it reads the receipt fields on both snapshots' metadata and warns, above the delta, when they were not generated over equivalent inputs.
+
+#### Comparability is a spectrum, not a boolean
+
+`Comparability` carries `Comparable bool` (invariant: `Comparable == (len(Warnings) == 0)`), free-text `Warnings`, and a **set of `Kinds`** categorizing them. The kinds exist because the boolean spans everything from *"these are different repositories, the delta is meaningless"* to *"the baseline is four days old, the delta is real but also contains the repo's own drift"*. A human reader can weigh that from the prose; a **gate cannot** — and consuming `Comparable` would turn every stale baseline into a hard refusal, contradicting the deliberate design of `staleBaselineDays`.
+
+| Kind | Raised when | Treated as |
+|------|-------------|-----------|
+| `different_repo` | the two snapshots are of different repositories | blocking |
+| `version_mismatch` | different enola versions (extractor changes read as churn) | blocking |
+| `extractor_set` | a language present on one side only | blocking |
+| `ignore_globs` | the set of files parsed changed | blocking |
+| `unclassified` | contributed via `AddWarning` by a caller that knows something this package cannot (notably `engine.Drift`) | blocking — a gate must **fail closed** on a caveat it cannot categorize |
+| `inverted_pair` | the baseline is *newer* than the current snapshot | usage error (concrete remedy: re-generate) |
+| `stale_baseline` | the baseline is ≥ 3 days older | **advisory** — warn and still grade |
+| `pre_receipt` | the baseline predates snapshot receipts | advisory |
+
+`Kinds` is a **set**, not a per-message list, so `Warnings` keeps its type and JSON shape for every existing consumer (the dashboard, `output_mode='full'`, and out-of-module readers via `pkg/diff`). Callers that know their category should use `AddWarningKind` rather than `AddWarning`.
+
+> Note on timestamps: `GeneratedAt` is RFC3339, i.e. **second** resolution, so a baseline pinned and then diffed inside the same second yields a zero gap. Zero is *simultaneous*, not inverted — `inverted_pair` requires a strictly negative gap. Treating zero as inverted made a no-op check on an untouched repository report "the current snapshot does not contain your change".
+
+---
+
+### The gate (`pkg/check`) — `diff_snapshot` as an exit code
+
+[`pkg/check`](pkg/check/check.go) is a thin, **pure** policy layer over `internal/diff`: `Compute` decides *what changed*, `Evaluate(*diff.SnapshotDiff, Policy) Verdict` decides whether that is allowed to break a build. Same delta plus same policy always yields the same verdict, so a gate is as reproducible as the snapshot underneath it. It backs the `enola check` CLI, and exists as a public package so a wrapper can build a graded verdict on top of it rather than re-deriving one.
+
+`Status.ExitCode()` is the contract with CI: `0` clean · `1` regression · `2` usage error · `3` incomparable. Precedence is **blocking → usage error → regression**; blocking comes first because when the snapshots were built over different inputs, the inverted-pair remedy ("re-generate") would send the caller down the wrong path. Nothing is hidden by the ordering — every warning is reported regardless of which decided the status.
+
+**Why the policy keys on the explainer rather than on confidence.** The obvious design is "fail at confidence `1.0`, because [Insights](#insights-explainers) says `1.0` is a structural fact and anything below is a flagged heuristic". That does not survive contact with the explainers: `godclass` computes confidence from a fan-in ratio and **clamps it to `1.0`**, so a statistical outlier at twice the threshold presents as a certainty; and `layers` emits an informational `Architecture pattern: <name>` finding whose confidence is the share of the codebase matching the pattern, which can also reach `1.0`. A gate keyed on the number alone would fail builds for a new statistical outlier and for a re-detected pattern after a reorganization.
+
+So the **explainer is the primary filter** (`DefaultFailExplainers = ["cycles"]`) and confidence is a floor applied within it (`DefaultMinConfidence = 1.0`). The floor still does real work: `cycles` emits both a true cycle at `1.0` and a "highly coupled module cluster" at `0.4` whose own description calls it "a coupling-density signal, not a defect to break".
+
+> The confidence-invariant violation above is a **real inconsistency between the docs and the explainers**, worked around here rather than fixed. Capping `god-class` below `1.0` and reclassifying the `layers` pattern finding as informational would let the gate key on confidence directly — but it changes insight output, so it needs golden regeneration.
+
+**New coupling is reported, never failed.** `diff.Edge` is name-level, so `EdgesAdded` is populated by virtually any change — adding a function that calls another adds edges. A gate firing on that would be switched off within a day. Only module-level and cross-repo coupling deltas are worth escalating, and that needs an edge filter that does not exist yet.
 
 ---
 
 
@@ -342,6 +342,15 @@ If the diff shows a regression, hand it straight back:
 
 Two prompts, no file re-reading, no review meeting. Repeat until the diff is boring.
 
+**The same loop without an agent.** Everything above is also a shell command, so the check can run in a git hook or CI instead of depending on the agent remembering to ask:
+
+```bash
+enola baseline pin      # before editing
+enola check             # after - exits 1 on a structural regression
+```
+
+See [The gate - `enola check`](#the-gate---enola-check).
+
 #### 5. Go multi-repo
 
 Generate the first repo, then add the rest with append mode - enola links them into one cross-repo graph:
@@ -608,17 +617,87 @@ For interactive per-module blast-radius queries with configurable depth, see the
 
 Run `enola --help` for the full text. With no flags, enola starts the MCP server on stdio.
 
+Every path argument follows the same rule: **a directory is a repository, a file is a config.** Anything that is neither is rejected rather than silently ignored.
+
+| Command | What it does |
+|------|--------------|
+| `baseline pin\|show\|clear [repo\|config]` | Manage the diff baseline - the "before" a change is graded against. `pin` snapshots the repository and freezes it (no separate `--generate` needed); `show` reports what the current baseline describes; `clear` removes it. Stored per repository, in that repo's `.enola/baseline`, so several repos each keep their own. |
+| `check [flags] [repo\|config]` | **Grade what a change did to the architecture**, and exit with a code CI can act on. Read-only: writes nothing and leaves the baseline in place, so it can be run repeatedly. See [The gate](#the-gate---enola-check). |
+| `upgrade` | Download and install the latest release over the running binary. |
+
 | Flag | What it does |
 |------|--------------|
-| `--generate [config_path]` | Generate a snapshot and exit - no MCP server. Artifacts go to `output.dir` (default `.enola/`). With `repos:` in the config, indexes the whole cluster in one run. |
+| `--generate [repo_path\|config_path]` | Generate a snapshot and exit - no MCP server. Artifacts go to `output.dir` (default `.enola/`). With `repos:` in the config, indexes the whole cluster in one run. |
 | `--explain [repo_path\|config_path]` | Print the statistics report above and exit. Read-only: nothing is written to `.enola/`. A directory is a repository; a file is a config, so a `repos:` config reports over the whole cluster. |
 | `--list` | List the MCP tools this build serves, with one-line summaries. |
 | `--status` | List every enola server running right now - PID, repos, uptime, calls, dashboard URL - plus per-tool call counts and an estimate of the reconstruction those calls saved, in time and tokens. |
 | `--status --all` | The same usage, broken down per repository. |
 | `--no-dashboard` | Start the MCP server without the localhost dashboard. |
 | `--version` | Print the build version. |
 | `--help`, `-h` | Show usage. |
-| `upgrade` | Download and install the latest release over the running binary. |
+
+### The gate - `enola check`
+
+`diff_snapshot` answers "what did my change actually do?" for an agent. `enola check` asks the same question from a shell, and turns the answer into an **exit code** - so the same delta can gate a commit or a CI job with no agent in the loop.
+
+```bash
+enola baseline pin /path/to/repo    # 1. freeze how it looks now, BEFORE editing
+#   …make your changes…
+enola check /path/to/repo           # 2. grade what they did
+```
+
+| Exit | Meaning |
+|------|---------|
+| `0` | **clean** - no structural regression |
+| `1` | **regression** - the policy was violated |
+| `2` | **error** - the gate could not run (no baseline pinned, bad argument, inverted snapshot pair) |
+| `3` | **declined** - the baseline is not comparable, so it refused to grade |
+
+`3` is deliberately not `1`. When the two snapshots were built over different inputs - a different enola version, a different extractor set, changed ignore globs - the delta describes *how they were produced*, not what you edited. Reporting that as a failing change would be a lie, so the gate says it declined and why.
+
+**A stale baseline warns; it never blocks.** Past three days it tells you exactly how stale and what that means (the delta now also contains whatever the repo itself changed in between) - then grades anyway, because a long-lived baseline is a legitimate way to measure a multi-day refactor and only you know which you meant.
+
+**What fails by default is narrow: a newly introduced dependency cycle, and nothing else.** Everything below that is reported, not failed - so a red gate is always real. Widen it per repo:
+
+```bash
+enola check --fail-on=cycles,layers --min-confidence=0.8   # also fail on new layer violations
+enola check --warn-only                                    # report everything, never fail
+enola check --json                                         # machine-readable verdict
+enola check --detail                                       # full delta under the verdict
+enola check --baseline=previous                            # compare against the preceding snapshot
+enola check --focus=internal/auth                          # narrow the delta to what you touched
+enola check --write                                        # also persist the snapshot (default: read-only)
+```
+
+The output names what moved rather than counting it - the added symbols with their `file:line`, the new coupling with its relation kinds, and any finding whose content shifted:
+
+```
+FAIL — 1 structural regression introduced.
+
+Regressions (fail):
+  - [cycles] 1.00 — Cyclic dependency detected (2 modules)
+      module "pkga" is part of the cycle
+
+What changed
+  symbols      +2
+  dependencies +1
+  edges        +4  (imports +1, calls +1, declares +2)
+
+Added (3):
+  symbol     pkga.AlphaViaB                    pkga/a.go:7
+  symbol     pkgb.Helper                       pkgb/b.go:7
+  dependency pkga -> example.com/gate/pkgb     pkga/a.go:3
+
+New coupling (4):
+  pkga                --imports--> pkgb
+  pkga.AlphaViaB      --calls--> pkgb.Helper
+  pkga.AlphaViaB      --declares--> pkga
+  pkgb.Helper         --declares--> pkgb
+```
+
+Lists cap at 12 entries with a `--detail` pointer, and `declares` edges - the mechanical one-per-new-symbol link to their module - always sort last, since they say nothing about what got coupled.
+
+Ready-made wiring: [`examples/hooks/pre-commit`](examples/hooks/pre-commit) (blocks only on exit `1`; a missing or incomparable baseline skips the gate rather than blocking someone over setup they haven't done) and [`examples/ci/architecture-gate.yml`](examples/ci/architecture-gate.yml) (a GitHub Action that pins a baseline from the PR's merge base).
 
 ### What it saved you - `--status`