enola-guides 0.1.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 103217d2be760b0b582027a9119e6acc6fae874ffc1171f8e59df35ac5ffb09b
-  data.tar.gz: 65f13f8cd1c54cafec16aca3f50a80710dcc77df8f6e66077c54fb346afeaf3a
+  metadata.gz: a8d331c92a1d9c3343d76d079967a3d6c96ec41227c35ca99c2977c8980764b6
+  data.tar.gz: 578aebe657940e45dcab775af903b1e8f6ddd4eb47ab4880d77b81a8ae67fcf1
 SHA512:
-  metadata.gz: 9cac7aed45a1041aeaeb66c46040f165dfa4156b05d5c2c088890dd18912930b6924059b5f0b1bcc00c4379b7574e524ab8794a43c936a5e5915a4afccf7572c
-  data.tar.gz: fe230a7e9daac6c8c88662bdcce76f1be1ff8019992c48f57a95afb469fc4bad58bd02e6171d62603e796b80cd31938826d59a5c8010adada9fa116d5a16e13d
+  metadata.gz: 57c7b7963c5d75e2750338d4f287c8be1115a808d28004f3cefae76b2823de297b3b44e94a2150638b499bb32994f4df32449494b0f2a5daa7cee5e80d3072d6
+  data.tar.gz: 7571fc1b51b77801f6d8f0c032b59f1c550a442ac1e73fb686ba5aded8efc000b2ba4c6c83aa1579c587b8b073abb095fc035c89bb88fc367d7eedaf8e4e8b65

data/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## 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
+and the starter each put every law in a file of its own that declares the parts it
+speaks about, so a reader finds a law by its name and a reviewer sees one
+law per diff.
+
 ## 0.1.1 (2026-08-22)
 
 The laws catalogue: `examples/laws/`, twenty-six complete declarations one

data/README.md

@@ -18,11 +18,13 @@ gem contents enola-guides
 ## Start with an example
 
 [`examples/rails-shop`](examples/rails-shop): a Rails application declaring
-thirteen laws in the Ruby DSL, from "jobs never invoke controller code" to
+thirteen laws in the Ruby DSL, one file each, from "jobs never invoke controller code" to
 "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/examples/laws/cluster-laws/README.md

@@ -5,5 +5,5 @@ repositories, mutating actions selected through the routes they handle, and
 routes no loaded client calls. Each refuses by name in a single-repository
 snapshot rather than reporting silence as compliance.
 
-Declaration under `enola/constraints/`. Copy it, run `enola constraints lint .`,
+One file per law under `enola/constraints/`, each file declaring the parts it speaks about. Copy it, run `enola constraints lint .`,
 then `enola --generate . && enola check .`.

data/examples/laws/cluster-laws/enola/constraints/a-mutating-action-is-authorized.rb

@@ -0,0 +1,10 @@
+Enola.architecture "platform" do
+  part :mutating_actions, service: :backend, files: "app/controllers/**", handles: [:post, :put, :patch, :delete]
+  part :policies, service: :backend, files: "app/policies/**"
+
+  law "a mutating action is authorized" do
+    mutating_actions.must_reach :policies
+    why "an action behind a POST, PUT, PATCH or DELETE route changes state, and the policy call is the one place the change is authorized"
+    mode :advisory
+  end
+end

data/examples/laws/cluster-laws/enola/constraints/every-api-route-has-a-consumer.rb

@@ -0,0 +1,9 @@
+Enola.architecture "platform" do
+  part :api, service: :backend, files: "config/**", kind: :route
+
+  law "every api route has a consumer" do
+    api.must_have_consumer
+    why "a route nobody calls is a surface nobody maintains"
+    mode :advisory
+  end
+end

data/examples/laws/cluster-laws/enola/constraints/one-owner-per-table.rb

@@ -0,0 +1,9 @@
+Enola.architecture "platform" do
+  part :tables, files: "app/models/**", kind: :storage
+
+  law "one owner per table" do
+    tables.must_be_unique_across by: :table
+    why "a table two repositories both model is written by two codebases that never see each other's validations or callbacks"
+    mode :advisory
+  end
+end

data/examples/laws/maintenance-tasks/README.md

@@ -5,5 +5,5 @@ depends on, and a boundary against controller code that has no request to
 read. Both were mined from a codebase where they already held, which is the
 right moment to declare a law.
 
-Declaration under `enola/constraints/`. Copy it, run `enola constraints lint .`,
+One file per law under `enola/constraints/`, each file declaring the parts it speaks about. Copy it, run `enola constraints lint .`,
 then `enola --generate . && enola check .`.

data/examples/laws/maintenance-tasks/enola/constraints/a-maintenance-task-never-invokes-controller-code.rb

@@ -0,0 +1,9 @@
+Enola.architecture "app" do
+  part :tasks, files: "app/tasks/**"
+  part :controllers, files: "app/controllers/**"
+
+  law "a maintenance task never invokes controller code" do
+    tasks.must_not_call controllers
+    why "a task runs from the runner or the console with no request around it, so controller code reached from one has nothing to read"
+  end
+end

data/examples/laws/maintenance-tasks/enola/constraints/{maintenance-tasks.rb → every-maintenance-task-lives-in-the-maintenance-namespace.rb}

@@ -1,15 +1,8 @@
 Enola.architecture "app" do
   part :maintenance_tasks, files: "app/tasks/**", kind: :symbol, where: { symbol_kind: "class" }
-  part :tasks, files: "app/tasks/**"
-  part :controllers, files: "app/controllers/**"
 
   law "every maintenance task lives in the Maintenance namespace" do
     maintenance_tasks.names_must_match "Maintenance::*"
     why "the task runner resolves task constants from that namespace, so a task declared outside it never appears in the runner and cannot be run by anyone"
   end
-
-  law "a maintenance task never invokes controller code" do
-    tasks.must_not_call controllers
-    why "a task runs from the runner or the console with no request around it, so controller code reached from one has nothing to read"
-  end
 end

data/examples/rails-shop/enola/constraints/a-concern-never-reaches-the-class-that-includes-it.rb

@@ -0,0 +1,9 @@
+Enola.architecture "shop" do
+  rails
+
+  law "a concern never reaches the class that includes it" do
+    concerns.must_not_reach_includers
+    why "a mixin that knows its includer is half a class in hiding"
+    mode :ratchet
+  end
+end

data/examples/rails-shop/enola/constraints/a-mutating-action-is-authorized.rb

@@ -0,0 +1,10 @@
+Enola.architecture "shop" do
+  rails
+  part :mutating_actions, files: "app/controllers/**", handles: [:post, :put, :patch, :delete]
+
+  law "a mutating action is authorized" do
+    mutating_actions.must_reach :policies
+    why "every write passes a policy before it touches a record"
+    mode :ratchet
+  end
+end

data/examples/rails-shop/enola/constraints/a-service-answers-to-call.rb

@@ -0,0 +1,9 @@
+Enola.architecture "shop" do
+  part :service_objects, files: "app/services/**", kind: :symbol, where: { symbol_kind: "class" }, owns: :methods
+
+  law "a service answers to call" do
+    service_objects.must_define :call
+    why "one door per service, so a caller never reads it to find the verb"
+    mode :ratchet
+  end
+end

data/examples/rails-shop/enola/constraints/background-jobs-never-invoke-controller-code.rb

@@ -0,0 +1,9 @@
+Enola.architecture "shop" do
+  rails
+
+  law "background jobs never invoke controller code" do
+    jobs.must_not_call controllers
+    why "rendering from a job goes through ApplicationController.renderer"
+    mode :ratchet
+  end
+end

data/examples/rails-shop/enola/constraints/billing-is-documented.rb

@@ -0,0 +1,10 @@
+Enola.architecture "shop" do
+  part :billing, files: ["app/billing/**", "app/models/invoice.rb"]
+
+  law "billing is documented" do
+    billing.must_be_governed
+    since "2026-09-01"
+    why "code under a decision needs the page that decided it"
+    mode :ratchet
+  end
+end

data/examples/rails-shop/enola/constraints/billing-keeps-to-its-own-tables.rb

@@ -0,0 +1,9 @@
+Enola.architecture "shop" do
+  part :billing, files: ["app/billing/**", "app/models/invoice.rb"]
+
+  law "billing keeps to its own tables" do
+    billing.storage_must_stay_home
+    why "a part that writes another part's table owns a bug it cannot see"
+    mode :ratchet
+  end
+end

data/examples/rails-shop/enola/constraints/frames-keep-their-query-budget.rb

@@ -0,0 +1,9 @@
+Enola.architecture "shop" do
+  rails
+
+  law "frames keep their query budget" do
+    controllers.must_keep_budget metric: :queries, max: 20
+    why "a frame past twenty queries is a page that will not scale; refused by name until a capture exists"
+    mode :advisory
+  end
+end

data/examples/rails-shop/enola/constraints/jobs-models-and-mailers-never-depend-on-each-other-in-a-circle.rb

@@ -0,0 +1,9 @@
+Enola.architecture "shop" do
+  rails
+
+  law "jobs, models and mailers never depend on each other in a circle" do
+    jobs.must_not_cycle_with :models, :mailers
+    why "parts that reach each other in a circle cannot be taken apart"
+    mode :advisory
+  end
+end

data/examples/rails-shop/enola/constraints/orders-are-reached-through-their-public-surface.rb

@@ -0,0 +1,9 @@
+Enola.architecture "shop" do
+  part :orders, files: ["app/orders/**", "app/models/order.rb"], public: ["app/orders/public/**"]
+
+  law "orders are reached through their public surface" do
+    orders.stays_inside
+    why "the public directory is the contract; everything else may change"
+    mode :ratchet
+  end
+end

data/examples/rails-shop/enola/constraints/reach-for-an-existing-service.rb

@@ -0,0 +1,8 @@
+Enola.architecture "shop" do
+  part :service_objects, files: "app/services/**", kind: :symbol, where: { symbol_kind: "class" }, owns: :methods
+
+  law "reach for an existing service" do
+    service_objects.advises "look in app/services before writing a new one"
+    why "duplication is a judgement no fact answers; advice where the edit happens is what can be offered honestly"
+  end
+end

data/examples/rails-shop/enola/constraints/scopes-come-in-pairs.rb

@@ -0,0 +1,9 @@
+Enola.architecture "shop" do
+  part :records, ancestor: "ApplicationRecord"
+
+  law "scopes come in pairs" do
+    records.names_must_match "with_*", requires: "without_*"
+    why "every with_ scope has a without_ sibling, or the query reads half a thought"
+    mode :advisory
+  end
+end

data/examples/rails-shop/enola/constraints/the-public-api-stays-small.rb

@@ -0,0 +1,10 @@
+Enola.architecture "shop" do
+  part :api, files: "config/**", kind: :route
+
+  law "the public api stays small" do
+    api.at_most 120
+    growth 5
+    why "a route is a promise; the count may grow, but only on purpose"
+    mode :ratchet
+  end
+end

data/examples/rails-shop/enola/constraints/the-request-api-stays-in-controllers.rb

@@ -0,0 +1,9 @@
+Enola.architecture "shop" do
+  rails
+
+  law "the request api stays in controllers" do
+    models.must_not_call "params", receiver: :none
+    why "params without a receiver is the controller's; a model reading it only works inside a request"
+    mode :ratchet
+  end
+end

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.