enola-guides 0.1.2 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: df9b7b5b2b3fc6589f9353c4f2198b08283fe80fafd2dacda91dea2d66c5a2fb
-  data.tar.gz: 20172bf3167db5fb3d690d401f3313d38861d10f86f7010607c4ccae98353b68
+  metadata.gz: 8b0ff999485e94088e964c4dd465bb5c1a26fea1a6dece3ed79b301e644786a8
+  data.tar.gz: 2c015c5cb721592b33c66e274108ead2f537a50e706d0a18d7a97880e9f78664
 SHA512:
-  metadata.gz: f705dc88218a61a94d6261b624e6744d8fd14212e6524b062f2f9f9520751013968f4a208382861516265ac4ca41db11ca483e09acf52792120aa704f01251a0
-  data.tar.gz: 65b0c4c5cd94ca30b85d3528737489c83c0ff73b8a7b3402dd2d39c45742af8ca679cfaef2ec04ea8837e3ac5d92a1881960b2a7429df198e758ef7b7d8c8435
+  metadata.gz: 581a958308b2e03bd6014a30f73007e7b9e6f70cfc5d97dad82d5e733f520c87b557983d3da041ee4234c7d392d510c67ddcf31a145d166909ad791e95ca187c
+  data.tar.gz: b2b684408b5ec182a1edb87f36483f5159af9520e60c144062b1d9e28f550c4a4176f2c3b256e73a8681b1c776a89aab5999b9816c310692331685e44b14e604

data/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## 0.2.1 (2026-08-23)
+
+enola v0.4.4 released the constraints program the guides describe
+(enola-labs/enola#247 merged); the README says released rather than landing,
+and the install guide names v0.4.4 as the minimum.
+
+## 0.2.0 (2026-08-22)
+
+What a knowledge base gets. Four guides (a knowledge base with enola,
+hooks, the skills as they run, the wrapper), four hook templates
+(intent-first gate, turn record, stop-time debt, session refresh), five
+skills as a knowledge base runs them (deepdive, ingest check, drift,
+citation hygiene, zoom out) and a worked example knowledge base with two
+anchored pages, receipts and a finding ledger.
+
 ## 0.1.2 (2026-08-22)
 
 One law per file: the Rails shop, the cluster laws, the maintenance-task laws

data/README.md

@@ -1,7 +1,7 @@
 # enola-guides
 
-How to use what is landing in [enola](https://github.com/enola-labs/enola)
-([enola-labs/enola#247](https://github.com/enola-labs/enola/pull/247)): a
+How to use what [enola](https://github.com/enola-labs/enola) ships since
+v0.4.4 ([enola-labs/enola#247](https://github.com/enola-labs/enola/pull/247)): a
 Ruby DSL for writing architecture constraints, Prism and Rubydex as
 providers that run together with enola's own extractors, recipes a team
 reviews, laws that read the whole graph, and an MCP your agent uses during
@@ -22,7 +22,9 @@ thirteen laws in the Ruby DSL, one file each, from "jobs never invoke controller
 "billing keeps to its own tables" and "a mutating action is authorized",
 with Prism and Rubydex configured as providers beside the extractors.
 [`examples/ember-app`](examples/ember-app): an Ember application bound to
-the conventions recipe in one block. [`examples/laws`](examples/laws/README.md):
+the conventions recipe in one block. [`examples/knowledge-base`](examples/knowledge-base/README.md):
+two pages anchored to code, a cluster config, receipts and a finding ledger,
+the smallest knowledge base the skills and hooks run against. [`examples/laws`](examples/laws/README.md):
 twenty-six laws, one directory each, from foreign keys on a tenant column
 to parts that may not cycle, each a complete declaration you copy and run.
 
@@ -43,6 +45,16 @@ to parts that may not cycle, each a complete declaration you copy and run.
    census, the runtime capture.
 8. [Beyond one repository](guides/08-beyond-one-repo.md): the cluster, the
    seams, the laws across them, the history.
+9. [A knowledge base with enola](guides/09-a-knowledge-base-with-enola.md):
+   what a wiki of decisions gets when its pages anchor to code and every
+   number it states was read from a receipt.
+10. [Hooks](guides/10-hooks.md): the four agent hooks a knowledge base runs
+    (intent-first gate, turn record, stop-time debt, session refresh).
+11. [The skills, as they run](guides/11-the-skills-as-they-run.md): deepdive
+    before shaping, claim check while ingesting, drift on a schedule,
+    citation hygiene, the blast radius.
+12. [The wrapper](guides/12-the-wrapper.md): the thin command the skills
+    call, the named skip, the receipts and the ledger.
 
 ## Skills
 
@@ -52,7 +64,12 @@ before grepping, grade after changing), `enola-laws` (write a law as a
 sentence with a reason, lint it, read what it verdicts),
 `enola-grade-before-push` (the delta is the deliverable, a declined grade
 is not a pass), `enola-intent-first` (read the governing decision before
-the file moves). Copy a directory into your agent's skills folder.
+the file moves), and the five a knowledge base runs: `enola-deepdive`,
+`enola-ingest-check`, `enola-drift`, `enola-citation-hygiene`,
+`enola-zoom-out`, each described as it runs in
+[guide 11](guides/11-the-skills-as-they-run.md). Copy a directory into
+your agent's skills folder; the hooks they pair with are under
+[`templates/hooks/`](templates/hooks).
 
 ## Templates and recipes
 

data/examples/knowledge-base/README.md

@@ -0,0 +1,20 @@
+# A knowledge base with enola, minimal
+
+The smallest knowledge base that gets what [guide 09](../../guides/09-a-knowledge-base-with-enola.md) describes:
+two pages anchored to code with `enola_intent`, a cluster config, the
+committed receipts, and the finding ledger. The skills under
+[`templates/skills`](../../templates/skills) and the hooks under
+[`templates/hooks`](../../templates/hooks) run against exactly these
+files.
+
+- `enola-cluster.yaml`: the members, with `knowledge` pointing at the wiki.
+- `wiki/shop/permanent/architecture.md`: a page whose `enola_intent`
+  anchors it to `app/jobs/**` and `app/models/**`, with one receipt
+  citation.
+- `wiki/shop/permanent/public-surface.md`: a page anchored to the
+  controllers it describes.
+- `wiki/_state/enola/receipts.json`: what `kb enola generate` recorded.
+- `wiki/_state/enola/findings.json`: the ledger, one judged finding.
+
+`governing_intent app/jobs/order_mailer_job.rb` returns the first page;
+`kb enola citations` verifies its citation against the receipts file.

data/examples/knowledge-base/enola-cluster.yaml

@@ -0,0 +1,7 @@
+cluster: shop
+knowledge: wiki
+repos:
+  - path: ../rails-shop
+    label: shop
+  - path: ../ember-app
+    label: shop-ui

data/examples/knowledge-base/wiki/_state/enola/findings.json

@@ -0,0 +1,10 @@
+{
+  "findings": {
+    "cycles|app/jobs -> app/models -> app/jobs": {
+      "verdict": "accepted",
+      "at": "2026-08-22",
+      "reason": "real; the mailer path",
+      "landed": "wiki/shop/permanent/architecture.md"
+    }
+  }
+}

data/examples/knowledge-base/wiki/_state/enola/receipts.json

@@ -0,0 +1,16 @@
+{
+  "repos": {
+    "shop": {
+      "fingerprint": "8d1e5a7b93c2f0e4d6a18b7c3e9f0a2d4c6b8e1f3a5c7d9e0b2f4a6c8e0d2c40a",
+      "git_commit": "3f2a9c1d4e5b6a7c8d9e0f1a2b3c4d5e6f7a8b9c",
+      "enola_version": "0.1.22",
+      "providers": ["prism", "rubydex"]
+    },
+    "shop-ui": {
+      "fingerprint": "2c7e9b1d4f6a8c0e2b4d6f8a0c2e4b6d8f0a2c4e6b8d0f2a4c6e8b0d2f4a6c8e",
+      "git_commit": "9b8c7d6e5f4a3b2c1d0e9f8a7b6c5d4e3f2a1b0c",
+      "enola_version": "0.1.22",
+      "providers": []
+    }
+  }
+}

data/examples/knowledge-base/wiki/shop/permanent/architecture.md

@@ -0,0 +1,19 @@
+---
+title: Shop architecture
+enola_intent:
+  governs:
+    - app/jobs/**
+    - app/models/**
+  decisions:
+    - jobs enqueue, models decide; a job never calls back into a job
+---
+
+# Shop architecture
+
+Orders are written by `OrderService` only; the two other writers the
+graph reported in 2026-08 were folded into it. `Order` has 41 dependents
+(receipt shop@3f2a9c1, fingerprint 8d1e…c40a).
+
+The cycle `app/jobs -> app/models -> app/jobs` through the mailer path is
+real and accepted in the ledger; it is cut when the mailer moves under
+`app/services`.

data/examples/knowledge-base/wiki/shop/permanent/public-surface.md

@@ -0,0 +1,14 @@
+---
+title: Public surface
+enola_intent:
+  governs:
+    - app/controllers/api/**
+  decisions:
+    - every route under /api has at least one consumer in shop-ui
+---
+
+# Public surface
+
+Fourteen routes under `/api`, all matched by a consumer in `shop-ui`
+(coverage report, receipt shop@3f2a9c1). A route that stops matching is
+a finding of `unused-routes`, judged in the ledger before any removal.

data/guides/01-start-here.md

@@ -10,9 +10,9 @@ invisible to tools that look at one file at a time, and they are what enola
 reports.
 
 This guide takes you from nothing to a graded change. Everything here is
-written for the release that carries the constraints vocabulary (the one
-this repository's recipes and templates target); if your `enola --version`
-is older, upgrade first.
+written for enola v0.4.4 or later, the release that carries the constraints
+vocabulary this repository's recipes and templates target; if your
+`enola --version` is older, upgrade first.
 
 ## 1. Install
 

data/guides/09-a-knowledge-base-with-enola.md

@@ -0,0 +1,148 @@
+# A knowledge base with enola
+
+A team that keeps decisions beside its code (a wiki, ADRs, a design log)
+can compile them into the graph. Then a file answers which decision
+governs it, a decision answers which code it covers, a structural claim
+in prose can be re-checked mechanically, and a finding judged once stays
+judged. This guide is that practice, as it runs day to day on a
+twenty-repository knowledge base.
+
+## Pages compile into the graph
+
+A markdown page carrying an `enola_intent:` block is an intent fact when
+the snapshot is taken, and every anchor on it is an edge to a file:
+
+```yaml
+---
+title: Charges run through one service
+enola_intent:
+  page:
+    type: decision
+    status: accepted
+    scope:
+      - shop
+    relations:
+      - rel: supersedes
+        to: wiki/adrs/charges-in-controllers.md
+    anchors:
+      - repo: shop
+        path: app/billing/charge.rb
+      - repo: shop
+        path: app/billing/refund.rb
+---
+```
+
+Derive the block rather than hand-maintain it: if your pages already cite
+the code they describe (`sources:` lines naming repository paths), the
+anchors are those citations, and a small script stamps the block from
+them and checks the derivation in CI. enola validates the block; keeping
+it truthful to your conventions is yours.
+
+Index the knowledge base as a member of the cluster, last, so its pages
+compile over the code they anchor:
+
+```yaml
+repos:
+  - ../shop
+  - ../mobile
+  - .
+```
+
+## Ask the graph what governs a file
+
+```bash
+enola plan -paths app/billing/charge.rb .
+```
+
+and over MCP, `governing_intent` for a file or a symbol: the pages whose
+anchors cover it, with their relation trails (what supersedes what, what
+depends on what), and for a page, which code its anchors cover. A file no
+page governs is an answer too, and the difference between "no page
+governs this" and "the graph was not asked" must stay visible: a missing
+snapshot is a named skip, never silence.
+
+This is the call behind the [intent-first gate](10-hooks.md): before an
+agent's first edit into a repository, the governing pages are read.
+
+## Laws over the pages
+
+Because anchors are facts, laws can read them (see [writing
+laws](04-writing-laws.md)):
+
+```ruby
+part :billing, files: "app/billing/**"
+part :old_way, governed_by: "wiki/adrs/*.md status:superseded"
+part :new_way, governed_by: "wiki/adrs/charges-in-one-service.md"
+
+law "billing is documented" do
+  billing.must_be_governed
+  why "code under a decision needs the page that decided it"
+end
+
+law "the new way never reaches the old" do
+  new_way.must_not_call :old_way
+  why "a superseded decision's code is on its way out, not a dependency"
+end
+```
+
+## Receipts are the committed state
+
+Graph artifacts (`.enola/`, the cluster's output directory) are
+machine-local and ignored. What enters version control is the receipt:
+one entry per repository with the snapshot's fingerprint, the commit it
+was taken at, the enola version and the providers that ran. Keep them in
+one file the knowledge base owns:
+
+```json
+{"repos": {"shop": {"git_commit": "…", "content_digest": "sha256:…", "enola_version": "0.5.0"}}}
+```
+
+Two rules follow. **Regenerate the whole cluster, never one member**: a
+snapshot scoped to one repository replaces the union rather than
+updating its slice, and everything that reads the union then answers
+from a narrower world without saying so. **Not comparable is not a
+pass**: when a member's snapshot changed enola version or provider set,
+the grade declines; re-pin and regenerate rather than reading silence as
+clean.
+
+## Citations with a grammar
+
+A structural claim in prose ("`internal/facts` has 157 dependents")
+cites the receipt it was read from, in one fixed shape, so a script can
+re-check it against the committed receipts and flag the ones whose
+digest moved. The shape is yours to choose; what matters is that there
+is one, that one extractor parses it, and that a periodic sweep lists
+every citation with a verdict (verified, stale, malformed). A claim
+nobody can re-check is a sentence, not a fact.
+
+## Findings are judged once
+
+The explainers report candidates, not verdicts: a cycle at 0.7
+confidence, a god class, an unused route. Before a finding grounds a
+page, confirm it against the code and record the judgment in a ledger
+beside the receipts, one entry per finding signature: accepted (and
+where it landed), rejected, or permanent noise. The next session reads
+the ledger instead of re-deciding, and the periodic sweep reports a
+ledger entry whose finding no longer exists, which is the code moving
+past a recorded judgment.
+
+## Pulled, with one push
+
+Skills fetch the graph while already reasoning about something: a
+deepdive asks `impact_analysis` and `governing_intent`, an ingest checks
+a claim with `query_facts` while the source is open, a drift sweep
+regenerates and diffs receipts. Nothing lands on a board because the
+graph said so. The one exception is the session-end hook, which speaks
+only when the session's change introduced a structural regression, or
+when it could not grade at all; a gate nobody remembers to run is no gate.
+
+## The wrapper
+
+Every skill calls a thin command the knowledge base owns rather than
+the binary: `kb enola generate | receipt | diff | findings | judge | impact
+| govern | citations | baseline | check | coverage | doctor`. It resolves
+the binary, the cluster config and the receipts file, and when any is
+absent it prints one line saying so and exits 0. That is what keeps a
+skill from failing on a machine without enola, and what keeps "the graph
+was not asked" distinguishable from "the graph agreed". The [wrapper
+guide](12-the-wrapper.md) has its shape.

data/guides/10-hooks.md

@@ -0,0 +1,101 @@
+# Hooks: the graph at the moments that matter
+
+A hook fires at a moment nobody has to remember: a session starting, the
+first edit into a repository, a turn ending, a push. Each one here reads
+the graph at that moment, blocks at most once, and forces a reading,
+never a verdict. The scripts are in [`templates/hooks/`](../templates/hooks);
+they are written for Claude Code's hook protocol (JSON on stdin, exit 2
+to block with the message on stderr) and translate to any agent with
+hooks.
+
+## enola's own pair
+
+```bash
+enola install --hooks
+```
+
+wires two: **session start** restores the snapshot and serves it over
+MCP; **stop** grades the session's delta against the pinned baseline and
+speaks only when the change introduced a regression or could not be
+compared. `enola doctor` reports when each last fired and what it
+concluded; a hook that never fires is the failure to look for.
+
+## The intent-first gate (PreToolUse on Edit and Write)
+
+The first write into each repository per piece of work is blocked once.
+The block carries two things: the pages that govern the file
+(`governing_intent`, or `enola plan -paths <file>` when the MCP is not
+in reach) and the pre-edit contract (the declared laws binding the path
+and the blast radius over the current snapshot). The agent reads, then
+retries, and the retry proceeds. The gate re-arms on every user message,
+so each ask gets its own forced stop and no piece of work gets two.
+
+What it refuses to do: decide. If the governing page contradicts the
+intended change, the contract says amend the page first; the hook only
+makes the page impossible to miss. When no page governs the file, it
+says so and asks whether the work should be shaped. When the graph is
+absent, it says so and lets the write through; a missing graph is a
+named skip, never a wall.
+
+`templates/hooks/intent-first-gate.sh` gates Edit and Write. The brain's
+own gate also classifies shell commands as writes (a `sed -i`, a
+redirect, a `cp` into the repository); the template marks where that
+classifier goes and leaves it out, because the rules for what counts as a
+write depend on your tree.
+
+## The stop-time debt (Stop)
+
+When the turn ends, two debts can block it once each:
+
+- **Code moved, no spec moved.** Files changed in a governed repository
+  this turn and no governing page did. The block asks for either the
+  amendment or an explicit sentence, in the reply, saying why the pages
+  as written already cover the change.
+- **A push went out with no grade.** A `git push` to a repository
+  happened this turn and no `enola check` ran. The block asks for the
+  grade, read, before finishing.
+
+Both read a small per-session record the PostToolUse hook writes
+(`templates/hooks/record.sh`): which files moved, whether a push
+happened, whether a check ran. The debt hook is the mechanical half of
+two rules a team can otherwise only ask people to remember.
+
+## The union refresh (SessionStart)
+
+When the session starts, compare the paired repository's HEAD with the
+commit the committed receipt records. When they differ, regenerate that
+member's slice of the union in the background and say so in one line;
+when they agree, say that. The agent's first structural question then
+reads a graph that matches the checkout it is about to edit.
+
+## Wiring
+
+Claude Code, in `.claude/settings.json`:
+
+```json
+{
+  "hooks": {
+    "SessionStart": [{"matcher": "startup|resume", "hooks": [
+      {"type": "command", "command": "enola hook session-start"},
+      {"type": "command", "command": "\"${CLAUDE_PROJECT_DIR:-.}/hooks/session-refresh.sh\""}]}],
+    "PreToolUse": [{"matcher": "Edit|Write|MultiEdit", "hooks": [
+      {"type": "command", "command": "\"${CLAUDE_PROJECT_DIR:-.}/hooks/intent-first-gate.sh\""}]}],
+    "PostToolUse": [{"matcher": "Edit|Write|MultiEdit|Bash", "hooks": [
+      {"type": "command", "command": "\"${CLAUDE_PROJECT_DIR:-.}/hooks/record.sh\""}]}],
+    "UserPromptSubmit": [{"hooks": [
+      {"type": "command", "command": "\"${CLAUDE_PROJECT_DIR:-.}/hooks/record.sh\" reset"}]}],
+    "Stop": [{"hooks": [
+      {"type": "command", "command": "enola hook stop"},
+      {"type": "command", "command": "\"${CLAUDE_PROJECT_DIR:-.}/hooks/stop-debt.sh\""}]}]
+  }
+}
+```
+
+## What it feels like
+
+An agent asked to change a billing service edits nothing until it has
+read the decision that put charges through one service; it grades the
+change before the push and writes the grade into the pull request; and
+when it ends the turn having changed code under a decision without
+touching the decision, it is asked to account for that once. None of
+this needs the agent to know enola exists.

data/guides/11-the-skills-as-they-run.md

@@ -0,0 +1,81 @@
+# The skills, as they run
+
+A skill is a named piece of practice an agent follows. Each of these asks
+the graph one specific question at one specific moment; the value is the
+moment, not the prompt. They are described here as they run on a
+twenty-repository knowledge base, and shipped under
+[`templates/skills/`](../templates/skills) to copy.
+
+## Before shaping work: the deepdive (`enola-deepdive`)
+
+Shaping a change starts with three graph questions, answered before a
+line of the plan is written:
+
+- `impact_analysis` on every symbol the work would change: fan-in,
+  fan-out, named callers. A symbol with 157 dependents is a different
+  plan from one with 3.
+- `governing_intent` on the paths: which decisions already cover the
+  area, so the plan amends a page rather than contradicting it.
+- `query_insights` for the area: what the explainers already computed (a
+  cycle someone must have introduced, a layer crossed, a dead route), so
+  the plan inherits judged findings instead of rediscovering them.
+
+The plan cites the receipt it read from, so a later reader can re-check
+the numbers.
+
+## Before building: the grade (`enola-grade-before-push`)
+
+`set_baseline` once, early; after the change, `generate_snapshot` and
+`diff_snapshot`; the delta (introduced, resolved, edges added) goes into
+the pull request in one sentence. A declined comparison is not a pass.
+This is also the [stop-time debt](10-hooks.md) hook's demand.
+
+## While ingesting a source: the claim check (`enola-ingest-check`)
+
+A page that states a structural fact (a stack, a public surface, a
+route, a table) checks it while the source is open: `query_facts` for
+the fact, `impact_analysis` for the count. A wrong claim ingested today
+is cited by a page tomorrow and reasoned from by an agent next week, so
+verification is cheapest now. For an incremental ingest, each changed
+path runs through `governing_intent`: the pages whose anchors cover a
+changed file are exactly the synthesis that may have drifted, and a
+changed file no page governs is a gap the ingest may be about to fill.
+
+## The periodic sweep: drift (`enola-drift`)
+
+On a schedule, or before publishing: regenerate the cluster, diff the
+committed receipts (fingerprint and commit per member), and read
+`coverage_report` for which cross-repository edges resolved and which did
+not. Receipts that moved name the members whose pages want a re-read.
+Not a comparison of findings between two runs; that is the grade's job.
+
+## Knowledge hygiene: citations and the ledger (`enola-citation-hygiene`)
+
+Every receipt citation in prose gets a verdict against the committed
+receipts: verified, stale (the digest moved), malformed. Stale ones are
+re-read, not rewritten. The finding ledger is swept the same way: an
+accepted finding whose evidence no longer exists in the graph is the
+code moving past a judgment, and the page that cites it is re-read.
+
+## Stepping back: the blast radius (`enola-zoom-out`)
+
+When deep in a change, one call answers how it sits in the whole:
+`impact_analysis` for the symbols in hand, `find_path` between the
+part being changed and the parts that consume it, `governing_intent`
+for the decisions around it. The answer is one paragraph of technical
+fit the agent can stand on, beside the product fit it reasons out.
+
+## Writing and explaining laws (`enola-laws`)
+
+Covered in [writing laws](04-writing-laws.md): lint before verdict,
+`constraints explain` before arguing with a verdict, ratchet before
+strict.
+
+## What makes these skills and not prompts
+
+Each names the call, the moment, and the refusal: what the agent does
+when the graph is absent (say so, proceed, never pretend), when the
+comparison declines (re-pin, never read as clean), when a finding is a
+candidate (confirm against the code, judge once, record). That is the
+practice the hooks enforce and the skills describe; the two are one
+contract read from two sides.

data/guides/12-the-wrapper.md

@@ -0,0 +1,69 @@
+# The wrapper
+
+Skills call a command the knowledge base owns, not the binary. The
+wrapper is thin: it knows where the binary, the cluster config and the
+receipts file live, it records receipts after a generate, and when
+anything is absent it prints one line saying so and exits 0. That is the
+whole design, and it is what lets every skill run on a machine without
+enola without failing, while keeping "the graph was not asked" a
+different sentence from "the graph agreed".
+
+## The operations
+
+| Op | Answers |
+|---|---|
+| `generate` | snapshot the cluster, then record every member's receipt |
+| `receipt [member]` | what was recorded |
+| `diff` | which members' live receipts drifted from the recorded ones |
+| `findings [--repo] [--all]` | the explainers' findings across the cluster, attributed to the member their evidence names, with judged ones hidden |
+| `judge <signature> accepted\|rejected\|noise` | record a verdict in the ledger |
+| `impact <symbol>` | fan-in, fan-out, named callers, read from the on-disk facts |
+| `govern <path or page>` | the pages governing a file, or the code a page anchors |
+| `citations` | every receipt citation in prose with its verdict |
+| `baseline pin\|show\|clear [member]` | the "before" a change is graded against |
+| `check [member]` | the grade, reported, never gating |
+| `coverage` | which cross-repository edges resolved |
+| `doctor` | whether the hooks fire |
+
+## The shape, in any language
+
+```
+resolve binary   -> absent: print "enola: not installed, the graph was not asked"; exit 0
+resolve config   -> absent: print the path looked for; exit 0
+resolve receipts -> absent on a read op: print; exit 0
+run the op       -> on generate, read each member's .enola/receipt.json
+                    and write fingerprint, commit, version, providers
+                    into the receipts file
+exit codes       -> the binary's, except check: report, exit 0
+```
+
+Three things to keep:
+
+- **Receipts are the only committed state.** `generate` writes them;
+  nothing else does. `diff` compares them to the live ones; it is not a
+  comparison of findings.
+- **Findings read from disk, not the MCP server.** `impact` and
+  `findings` parse the fact and insight files, so scheduled and headless
+  runs keep working when no server is up.
+- **`check` reports; it never gates.** The binary exits 1 on a
+  regression and the wrapper does not propagate it: no graph-dependent
+  step may stop work, so the verdict is surfaced for a person to weigh.
+  Exit 3 from the binary means the snapshots were not comparable; the
+  wrapper prints that as "not asked", never as a pass.
+
+## The ledger beside the receipts
+
+```json
+{"findings": {"cycles|app/jobs -> app/models -> app/jobs": {"verdict": "accepted", "at": "2026-08-22", "reason": "real; the mailer path", "landed": "wiki/shop/permanent/architecture.md"}}}
+```
+
+One entry per finding signature, written on judgment. There is no
+pending state: nothing enumerates unjudged findings as work, because a
+finding nobody bet on is an observation.
+
+## Why not call the binary directly
+
+Every skill would then carry the absent-binary branch, the config
+resolution and the receipt bookkeeping, and they would drift. The
+wrapper is where those live once, which is why the guides say `kb enola
+impact` where the brain that runs this says `brain.py enola impact`.

data/lib/enola-guides.rb

@@ -2,6 +2,6 @@
 
 module Enola
   module Guides
-    VERSION = "0.1.2"
+    VERSION = "0.2.1"
   end
 end

data/templates/hooks/intent-first-gate.sh

@@ -0,0 +1,49 @@
+#!/bin/bash
+# PreToolUse on Edit|Write|MultiEdit: block the first write into each
+# repository per piece of work, once, with the governing pages and the
+# pre-edit contract on stderr. The retry proceeds; the gate forces the
+# reading, never the verdict. Re-armed by record.sh on every user message.
+#
+# Where a shell-command classifier would go: a Bash tool call whose text
+# carries a write shape (sed -i, a redirect, tee, cp or mv into the tree,
+# an interpreter fed a heredoc) is a write too. What counts depends on your
+# tree; gate it the same way once you have decided.
+set -u
+input=$(cat 2>/dev/null || true)
+sid=$(jq -r '.session_id // "nosession"' <<<"$input" 2>/dev/null)
+file=$(jq -r '.tool_input.file_path // empty' <<<"$input" 2>/dev/null)
+[ -n "$file" ] || exit 0
+
+top=$(git -C "$(dirname "$file")" rev-parse --show-toplevel 2>/dev/null) || exit 0
+case "$file" in
+  "$top"/.enola/*|"$top"/wiki/_views/*|"$top"/wiki/_state/*) exit 0 ;;
+esac
+rel="${file#"$top"/}"
+repo=$(basename "$top")
+
+state="${TMPDIR:-/tmp}/intent-first-$(id -u)"
+mkdir -p "$state"
+ack="$state/${sid}-${repo}.ack"
+[ -e "$ack" ] && exit 0
+touch "$ack"
+
+govern=""
+if command -v enola >/dev/null 2>&1; then
+  govern=$(cd "$top" && timeout 30 enola plan -paths "$rel" . 2>/dev/null | sed -n '/^Plan report/,$p' | head -40)
+fi
+[ -n "$govern" ] || govern="(enola plan unavailable: no binary or no snapshot for this checkout; named skip, consult the decision records by hand)"
+
+cat >&2 <<EOF
+intent-first gate (${repo}): first write for this piece of work.
+
+Before ${rel} moves, read what governs it and check the intended change
+against it. If the change deviates from what the governing page records,
+amend the page first; if nothing governs this work, say so and ask
+whether it should be shaped.
+
+${govern}
+
+Retrying proceeds. This gate re-arms on every user message; within one
+piece of work it will not fire again for ${repo}.
+EOF
+exit 2

data/templates/hooks/record.sh

@@ -0,0 +1,37 @@
+#!/bin/bash
+# PostToolUse on Edit|Write|MultiEdit|Bash: record what this turn did, so
+# the stop-time debt hook can account for it. With "reset" as the first
+# argument (UserPromptSubmit): a new user message begins a new piece of
+# work, so clear the record and the gate's acknowledgements.
+set -u
+state="${TMPDIR:-/tmp}/intent-first-$(id -u)"
+mkdir -p "$state"
+input=$(cat 2>/dev/null || true)
+sid=$(jq -r '.session_id // "nosession"' <<<"$input" 2>/dev/null)
+turn="$state/${sid}.turn"
+
+if [ "${1:-}" = "reset" ]; then
+  rm -f "$state/${sid}"-*.ack "$turn" "$state/${sid}.debt-blocked" "$state/${sid}.push-blocked"
+  exit 0
+fi
+
+record() { printf '%s\n' "$1" >> "$turn"; }
+
+tool=$(jq -r '.tool_name // empty' <<<"$input" 2>/dev/null)
+if [ "$tool" = "Bash" ]; then
+  cmd=$(jq -r '.tool_input.command // empty' <<<"$input" 2>/dev/null)
+  [ -n "$cmd" ] || exit 0
+  printf '%s' "$cmd" | grep -qE '(^|[[:space:];&|])git[[:space:]]+push' && record "push"
+  printf '%s' "$cmd" | grep -qE 'enola[[:space:]]+check' && record "check"
+  exit 0
+fi
+
+file=$(jq -r '.tool_input.file_path // .tool_response.filePath // empty' <<<"$input" 2>/dev/null)
+[ -n "$file" ] || exit 0
+top=$(git -C "$(dirname "$file")" rev-parse --show-toplevel 2>/dev/null) || exit 0
+rel="${file#"$top"/}"
+case "$rel" in
+  wiki/*.md|docs/decisions/*.md|docs/adrs/*.md) record "spec	$rel" ;;
+  *) record "code	$rel" ;;
+esac
+exit 0

data/templates/hooks/session-refresh.sh

@@ -0,0 +1,31 @@
+#!/bin/bash
+# SessionStart: when a cluster member's HEAD moved past the commit the
+# committed receipts record, regenerate the cluster in the background and
+# say so in one line; when they agree, say that. The agent's first
+# structural question then reads a graph that matches the checkout.
+#
+# RECEIPTS is the knowledge base's committed receipts file; CLUSTER the
+# cluster config; MEMBER the repository to compare (default: this one).
+set -u
+RECEIPTS="${RECEIPTS:-wiki/_state/enola/receipts.json}"
+CLUSTER="${CLUSTER:-enola-cluster.yaml}"
+MEMBER="${MEMBER:-.}"
+command -v enola >/dev/null 2>&1 || { echo "enola hooks: no binary on PATH; the graph was not asked (named skip)"; exit 0; }
+[ -f "$RECEIPTS" ] || { echo "enola hooks: no receipts at $RECEIPTS; the graph was not asked (named skip)"; exit 0; }
+
+label=$(basename "$(cd "$MEMBER" && pwd -P)")
+head=$(git -C "$MEMBER" rev-parse HEAD 2>/dev/null || true)
+recorded=$(python3 - "$RECEIPTS" "$label" <<'PY' 2>/dev/null
+import json, sys
+r = json.load(open(sys.argv[1]))
+print(((r.get("repos") or r).get(sys.argv[2]) or {}).get("git_commit") or "")
+PY
+)
+if [ -n "$head" ] && [ "$head" != "$recorded" ]; then
+  log="${TMPDIR:-/tmp}/enola-refresh-$(id -u).log"
+  (nohup enola --generate "$CLUSTER" > "$log" 2>&1 &)
+  echo "enola hooks: $label is at ${head:0:11}, the recorded receipt at ${recorded:0:11}; regenerating the cluster in the background (log $log)."
+else
+  echo "enola hooks: the recorded receipt matches $label at ${head:0:11}."
+fi
+exit 0

data/templates/hooks/stop-debt.sh

@@ -0,0 +1,39 @@
+#!/bin/bash
+# Stop: block the end of the turn once when this turn pushed without a
+# grade, and once when code moved under decision records and no record
+# moved. Reads the per-session record written by record.sh.
+set -u
+state="${TMPDIR:-/tmp}/intent-first-$(id -u)"
+input=$(cat 2>/dev/null || true)
+sid=$(jq -r '.session_id // "nosession"' <<<"$input" 2>/dev/null)
+turn="$state/${sid}.turn"
+[ -f "$turn" ] || exit 0
+
+if grep -q '^push$' "$turn" && ! grep -q '^check$' "$turn" && [ ! -e "$state/${sid}.push-blocked" ]; then
+  touch "$state/${sid}.push-blocked"
+  cat >&2 <<'EOF'
+push without a grade: this turn pushed and ran no enola check.
+
+Before finishing: run `enola check <repo>` against the pinned baseline
+and read the grade. A declined grade is not a pass; re-pin and grade
+again. This check blocks once per turn.
+EOF
+  exit 2
+fi
+
+if grep -q '^code' "$turn" && ! grep -q '^spec' "$turn" && [ ! -e "$state/${sid}.debt-blocked" ]; then
+  touch "$state/${sid}.debt-blocked"
+  summary=$(awk -F'\t' '$1 == "code" { print "  " $2 }' "$turn" | sort -u | head -15)
+  cat >&2 <<EOF
+intent debt: code moved this turn, and no decision record did.
+
+Changed without a record moving:
+${summary}
+
+Before finishing: either amend the governing record to match what was
+built, or state explicitly, in your reply, why the records as written
+already cover the change. This check blocks once per turn.
+EOF
+  exit 2
+fi
+exit 0

data/templates/skills/enola-citation-hygiene/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: enola-citation-hygiene
+description: Use during grooming; gives every receipt citation in prose a verdict against the committed receipts and sweeps the finding ledger for judgments the code has moved past
+---
+
+# enola-citation-hygiene: every citation gets a verdict
+
+1. `kb enola citations`: each receipt citation in prose is verified, stale
+   (the digest moved) or malformed.
+2. Stale: re-read the cited page against the current facts and amend the
+   sentence; never update the citation alone, the sentence is what may be
+   wrong.
+3. Malformed: fix the citation to the recorded form.
+4. `kb enola findings --all`: for each accepted finding in the ledger,
+   confirm its evidence still exists in the graph. Evidence gone means
+   the code moved past the judgment; re-read the page that landed it and
+   record the new state.
+5. Rejected and noise verdicts stay; they keep the finding hidden on
+   purpose.
+
+A citation is a promise that a number was read, not remembered; this
+skill keeps the promise current.

data/templates/skills/enola-deepdive/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: enola-deepdive
+description: Use before shaping or planning a change; asks the graph three questions (impact, governing decisions, existing findings) and writes the answers into the plan with the receipt they came from
+---
+
+# enola-deepdive: ask the graph before writing the plan
+
+1. Name the symbols the change would touch. For each:
+   `kb enola impact <Symbol>` (or `impact_analysis` over MCP). Record fan-in,
+   fan-out and the named callers. A symbol with 157 dependents is a
+   different plan from one with 3.
+2. For the paths: `kb enola govern <path>` (`governing_intent`). The pages
+   returned are the decisions already covering the area; the plan amends
+   one of them, it does not contradict it in silence.
+3. For the area: `query_insights` filtered to it. Cycles, layer crossings,
+   dead routes and hotspots are already computed and some are already
+   judged in the ledger; inherit them.
+4. Write the three answers into the plan, each with the receipt
+   (`kb enola receipt <member>`) it was read from.
+5. If the graph is absent or the receipts are stale (`kb enola diff`), say
+   so in the plan and proceed; never fill the numbers from memory.

data/templates/skills/enola-drift/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: enola-drift
+description: Use on a schedule or before publishing; regenerates the cluster, compares committed receipts to live ones, and names the members whose pages want a re-read
+---
+
+# enola-drift: which members moved
+
+1. `kb enola generate` to regenerate the cluster and record receipts.
+2. `kb enola diff`: each member whose fingerprint or commit moved is
+   listed. Those are the members whose pages may describe a structure that
+   no longer exists.
+3. `kb enola coverage` (`coverage_report`): which cross-repository edges
+   resolved and which did not. An edge that stopped resolving is a
+   consumer a page may still claim.
+4. For each moved member: `kb enola govern <member path>` and re-read the
+   pages returned against the new facts. Amend what changed; leave what
+   did not.
+5. Commit the receipts with the page amendments, in one commit.
+
+This is a comparison of receipts, not of findings. Findings between two
+runs are the grade's job (`enola-grade-before-push`).

data/templates/skills/enola-ingest-check/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: enola-ingest-check
+description: Use while ingesting a source into the knowledge base; checks every structural claim against the graph while the source is open, and routes changed paths to the pages that govern them
+---
+
+# enola-ingest-check: verify the claim while the source is open
+
+1. When a page is about to state a structural fact (a stack, a public
+   surface, a route, a table, a count): `query_facts` for the fact,
+   `kb enola impact <Symbol>` for the count. Write what the graph says,
+   and cite the receipt.
+2. For an incremental ingest, for each changed path:
+   `kb enola govern <path>`. The pages returned are the synthesis that may
+   have drifted; re-read them against the change. A changed path no page
+   governs is a gap the ingest is about to fill, so anchor the new page to
+   it with `enola_intent`.
+3. A claim the graph cannot answer (product intent, history, a reason) is
+   stated as the source's claim, not as a fact of the code.
+4. If the graph is absent, the page says the claim is unverified; it does
+   not silently become a fact.
+
+A wrong claim ingested today is cited tomorrow and reasoned from next
+week; verification is cheapest now.

data/templates/skills/enola-zoom-out/SKILL.md

@@ -0,0 +1,16 @@
+---
+name: enola-zoom-out
+description: Use when deep in a change and the question is how it sits in the whole; answers the technical blast radius in one paragraph from the graph, beside the product fit reasoned out
+---
+
+# enola-zoom-out: the blast radius in one paragraph
+
+1. `kb enola impact <Symbol>` for the symbols in hand: fan-in, named callers.
+2. `find_path` from the part being changed to the parts that consume it:
+   the route the change travels.
+3. `kb enola govern <path>`: the decisions around it.
+4. Write one paragraph of technical fit: what depends on this, through
+   what, under which decisions. Put it beside the product fit, which the
+   graph cannot answer.
+5. If the paragraph names a dependent the plan did not, the plan is
+   incomplete; return to `enola-deepdive`.

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: enola-guides
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.2.1
 platform: ruby
 authors:
 - Muhamed Isabegovic
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-08-22 00:00:00.000000000 Z
+date: 2026-08-23 00:00:00.000000000 Z
 dependencies: []
 description: |
   Ready-to-use templates, presets, skills and instructions for adopting
@@ -25,6 +25,12 @@ files:
 - README.md
 - examples/ember-app/enola/constraints/ember.yaml
 - examples/ember-app/enola/recipes/ember-conventions.yaml
+- examples/knowledge-base/README.md
+- examples/knowledge-base/enola-cluster.yaml
+- examples/knowledge-base/wiki/_state/enola/findings.json
+- examples/knowledge-base/wiki/_state/enola/receipts.json
+- examples/knowledge-base/wiki/shop/permanent/architecture.md
+- examples/knowledge-base/wiki/shop/permanent/public-surface.md
 - examples/laws/README.md
 - examples/laws/clean-rings/README.md
 - examples/laws/clean-rings/enola/constraints/clean.yaml
@@ -103,6 +109,10 @@ files:
 - guides/06-hooks-and-agents.md
 - guides/07-providers.md
 - guides/08-beyond-one-repo.md
+- guides/09-a-knowledge-base-with-enola.md
+- guides/10-hooks.md
+- guides/11-the-skills-as-they-run.md
+- guides/12-the-wrapper.md
 - lib/enola-guides.rb
 - recipes/README.md
 - recipes/ember-conventions.yaml
@@ -114,9 +124,18 @@ files:
 - templates/enola-check.sh
 - templates/enola-cluster.yaml
 - templates/enola-findings.rb
+- templates/hooks/intent-first-gate.sh
+- templates/hooks/record.sh
+- templates/hooks/session-refresh.sh
+- templates/hooks/stop-debt.sh
+- templates/skills/enola-citation-hygiene/SKILL.md
+- templates/skills/enola-deepdive/SKILL.md
+- templates/skills/enola-drift/SKILL.md
 - templates/skills/enola-grade-before-push/SKILL.md
+- templates/skills/enola-ingest-check/SKILL.md
 - templates/skills/enola-intent-first/SKILL.md
 - templates/skills/enola-laws/SKILL.md
+- templates/skills/enola-zoom-out/SKILL.md
 - templates/skills/enola/SKILL.md
 homepage: https://github.com/misabegovic/enola-guides
 licenses: