enola-guides 0.8.0 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3784520433166796cdd4b84e8991d25877fc6c1c97dcd5af9e04b5d8dcf12985
-  data.tar.gz: a6e317df671ddcbc2cc90f3077eff8db4ec03e6762cd5c5e3ea8e439d27d3555
+  metadata.gz: 8d1b81f179855dbd64a4feb84618651f3b3805d7410dd82f09238fb9a3896f00
+  data.tar.gz: 46ec48df52057f409f66e0a60ee1c32224cdfc84f06da9474c85561923a677b5
 SHA512:
-  metadata.gz: 7b7987e38206a19d0bddbfa955b77158df65da89b794398ad510c1b63b482f4d28466cba970f1ccf58cf42592e533a2fffa072bd9a89533b60f83852c10b3188
-  data.tar.gz: 3a488496fb470ab2eb67183cc0e38bfa6f177892a74437cc808e345b85421ef0683bc6061231a9c6bfe38e3b362c9f597672cc274bbe415140767da699c1bccd
+  metadata.gz: d6c33d263d7d51ad7b16dc436ddf1412f441309dbbb05f8534fd4efda42c97b8ba2489d02ef9fc04f887ab226261db0f0edab3168dad1c4bf5b2426e899415b8
+  data.tar.gz: 99318280749a1987d2a1197f29ca3fe8850a78df1a5fdd13cc3d743d2e24ce14918b79b8b6ccabd1cb492174db69cec19f5f456a2e57283a31d1f13b8ea43c01

data/CHANGELOG.md

@@ -1,5 +1,63 @@
 # Changelog
 
+## 0.9.0 (2026-10-26)
+
+Checked against enola v0.4.35, and read again as someone who has never
+heard of enola: a developer landing on the README, one following guide 01
+literally on a Python service, and a tech lead deciding whether to adopt
+it. What they tripped on is fixed, and every command it changed was run
+against v0.4.35.
+
+- The README says what enola is and how to install it before anything
+  else, and groups the guides into tracks: new to enola, your stack, laws
+  and CI, agents, deeper, and an optional knowledge-base track.
+- Three new guides. [00, what enola is](guides/00-concepts.md): the
+  pieces, a glossary, who makes what, and enola beside linters and
+  dependency-rule tools. [19, rolling out](guides/19-rolling-out.md):
+  measured costs (Mastodon and a 20,000-file Rails monolith), one recipe
+  instead of five, report then enforce, owners, what to commit, turning
+  it off. [20, reading a verdict](guides/20-reading-a-verdict.md): every
+  section and exit code, partial and declined, the surprises.
+- Guide 01: install pinned through `pipx`, the npm `enola` warning, the
+  MCP server registered with `alwaysLoad`, `doctor` before a restart, a
+  first law in YAML that fires on any layout with the output it gives,
+  and why a first `.rb` law in a repository with no Ruby makes the verdict
+  partial and grades an old breach as new.
+- Guide 04: modes as a table with the confidence each reports at; fix,
+  exempt, suppress or leave in the baseline, with the syntax in Ruby and
+  YAML; a recipes section; `check` needs a pinned baseline.
+- Guide 05: the action pinned with `version:`, Rubydex installed pinned;
+  the template's variables, requirements, exit codes and comment.
+- Guide 06: registering the MCP server per agent, what the agent does
+  differently, v0.4.35's narrower search refusal and folder-of-repositories
+  install, what to commit (the hooks carry an absolute path) and how to
+  turn each piece off.
+- `templates/enola-check.sh`: a regression under enforcement is a verdict
+  with a comment, not "did not run"; the confidence floor stays at 1.00 so
+  advisory laws never fail; a shallow clone fails on CI instead of passing
+  quietly; the comment is edited by its numeric id; without Ruby the
+  comment is enola's own summary; `.enola-version` pins the release.
+  `script/test-check-template` covers each.
+- The knowledge-base hooks leave a repository with no decision records
+  alone (`ENOLA_DECISION_DIRS`) and are wired from `.claude/hooks/`, where
+  `enola-guides copy` writes them. The five knowledge-base skills call a
+  wrapper that now ships, `templates/kb/kb`, tested by `script/test-kb`.
+  `examples/knowledge-base`'s cluster config parses on v0.4.35.
+- Fixed: the `enola --generate . && enola check .` line in guide 02, the
+  skills and the twenty-six law READMEs fails with no pinned baseline;
+  `constraints init` binds a recipe only when every role has a directory;
+  a Ruby `via:` keyword on a sentence is dropped (write `via :imports` in
+  the law); `enola gc` trims the local history; the Ember recipe is copied
+  with `enola-guides copy`, not `gem contents`; undefined names (munola,
+  the brain) are gone; `list recipes` no longer lists the recipes README.
+- What v0.4.35 still reads less than the code, each re-checked: an
+  Express `router.post("/")` under a mount, an inline Axum `.nest`, a
+  bare Cargo version read as pinned, an inline TypeScript handler,
+  `layered`'s `depends_on` rules on Python, TypeScript, Go and Rust, and a
+  Ruby `where:` value that is not a string.
+- tabula and taha are marked as a preview: neither is public yet.
+- `script/check-links` checks `#anchors` too.
+
 ## 0.8.0 (2026-10-25)
 
 One command, `enola-guides`, in every ecosystem: RubyGems, npm, PyPI,

data/README.md

@@ -1,19 +1,137 @@
 # enola-guides
 
-How to use [enola](https://github.com/enola-labs/enola), the tool that
-grades what a change did to a codebase's architecture, checked against
-v0.4.34: laws written as sentences in Ruby or YAML, recipes a team
-reviews, providers that run beside enola's own extractors, the check in
-CI, the hooks and MCP tools an agent uses during a session, and the
-knowledge base built on top of it with [tabula](guides/13-tabula.md) and
-[taha](guides/14-taha.md). Guides for Rails, Ember, Python, TypeScript,
-Go and Rust, worked examples that CI snapshots and grades on every change,
-skills and templates, packaged so a team can pin the guidance it adopted.
+[enola](https://github.com/enola-labs/enola) snapshots a codebase's
+architecture (modules, calls, routes, tables, dependencies) and grades
+each change against a pinned baseline. It catches what file-by-file
+linters cannot: a new cycle across four files, a job that starts calling
+a controller, a second part writing a table that was one part's own. And
+it reports only what the change added, not the hundreds of findings the
+repository already had.
 
-## Install
+These are guides to using it: a first graded change in ten minutes, laws
+your team states as sentences, the check on every pull request, and the
+hooks and tools a coding agent uses during a session, for Rails, Ember,
+Python, TypeScript, Go and Rust. Every command, flag and output in them
+was run against **enola v0.4.35**, and CI snapshots and grades the worked
+examples on every change. The guides are by Muhamed Isabegovic and are
+not part of enola-labs.
 
-One command, `enola-guides`, with the same items and the same output from
-every package. Take it from the ecosystem you already use:
+## Install enola
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/enola-labs/enola/main/install.sh | sh
+enola --version
+```
+
+or `pipx install enola-cli` (the PyPI name; the command is `enola`).
+[Start here](guides/01-start-here.md) has the rest, including how to pin
+a version. enola is not on npm: the npm package `enola` is something
+else.
+
+## Read in this order
+
+**New to enola**
+
+- [What enola is, and the words these guides use](guides/00-concepts.md):
+  the pieces, a glossary, and how it sits beside the tools you already
+  run. Five minutes.
+- [Start here](guides/01-start-here.md): install, snapshot, baseline, a
+  graded change, the agent hooks, a first law. Ten minutes.
+
+**Your stack**: what enola measures in each, the recipe that names its
+parts, and where it reads less than the code says.
+
+- [Rails](guides/02-rails.md) · [Ember](guides/03-ember.md) ·
+  [Python](guides/15-python.md) · [TypeScript and JavaScript](guides/16-typescript.md) ·
+  [Go](guides/17-go.md) · [Rust](guides/18-rust.md)
+
+**Laws and CI**
+
+- [Writing laws](guides/04-writing-laws.md): parts, the sentences, modes,
+  dates, exemptions and suppressions, what a refusal means.
+- [Constraints in CI](guides/05-constraints-in-ci.md): the check on every
+  pull request, on GitHub or any other CI.
+- [Rolling out](guides/19-rolling-out.md): adopting it on a repository
+  with years of history, what to commit, what it costs, how to turn each
+  piece off.
+- [Reading a verdict](guides/20-reading-a-verdict.md): every section of
+  `enola check`'s output, every exit code, and the surprises.
+
+**Agents**
+
+- [Hooks and agents](guides/06-hooks-and-agents.md): registering the MCP
+  server, the session hooks, what the agent does differently, the tools
+  it reaches for.
+
+**Deeper**
+
+- [Providers](guides/07-providers.md): the Ruby pair, the census, the
+  runtime capture, writing one.
+- [Beyond one repository](guides/08-beyond-one-repo.md): the cluster, the
+  seams between repositories, the laws across them, the history.
+
+**Optional: a knowledge base of decisions.** For teams that keep
+decision records beside their code and want each page anchored to the
+code it governs. Nothing above needs it.
+
+- [A knowledge base with enola](guides/09-a-knowledge-base-with-enola.md):
+  pages that compile into the graph, receipts, a finding ledger.
+- [Knowledge-base hooks](guides/10-hooks.md): the intent-first gate, the
+  turn record, the stop-time debt, the session refresh.
+- [The knowledge-base skills, as they run](guides/11-the-skills-as-they-run.md):
+  deepdive, claim check, drift, citation hygiene, zoom-out.
+- [The wrapper](guides/12-the-wrapper.md): the command those skills call,
+  shipped as a template.
+- *Preview:* [tabula](guides/13-tabula.md) and [taha](guides/14-taha.md),
+  the same practice as one program and agents run on it. Neither is
+  public yet.
+
+## Worked examples
+
+- [`examples/python-service`](examples/python-service),
+  [`typescript-service`](examples/typescript-service),
+  [`go-service`](examples/go-service) and
+  [`rust-service`](examples/rust-service): the same four-layer service in
+  each language, with its source, breaking the laws it states on purpose
+  so you can watch each one fire.
+- [`examples/rails-shop`](examples/rails-shop): thirteen laws in the Ruby
+  DSL, one file each, from "jobs never invoke controller code" to
+  "billing keeps to its own tables", with the Prism and Rubydex
+  providers configured.
+- [`examples/ember-app`](examples/ember-app): an Ember application bound
+  to the conventions recipe in one block.
+- [`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.
+- [`examples/knowledge-base`](examples/knowledge-base/README.md): two
+  pages anchored to code, a cluster config, receipts and a finding
+  ledger, for the optional track.
+
+## Skills, hooks, templates and recipes
+
+- [`templates/skills/`](templates/skills): skills for a coding agent.
+  Four for any repository: `enola` (ask the graph before searching, grade
+  after changing), `enola-laws` (write a law with a reason, lint it, read
+  its verdict), `enola-grade-before-push` (a declined grade is not a
+  pass) and `enola-intent-first` (read the governing decision before the
+  file moves). Five more belong to the knowledge-base track and call its
+  [wrapper](guides/12-the-wrapper.md) (`enola-guides copy templates/kb`):
+  `enola-deepdive`, `enola-ingest-check`, `enola-drift`,
+  `enola-citation-hygiene`, `enola-zoom-out`.
+- [`templates/hooks/`](templates/hooks): the knowledge-base hooks of
+  [guide 10](guides/10-hooks.md).
+- [`templates/`](templates): the CI check script and its comment
+  renderer, a cluster configuration, and a starter of four Rails laws.
+- [`recipes/`](recipes/README.md): recipes to copy into your own
+  `enola/recipes/` and bind in one block, each with the count its laws
+  held at on a real repository; starting points a team reviews, never
+  defaults the tool applies.
+
+## These guides as a command
+
+Everything above is also one command, `enola-guides`, with the same items
+and the same output from every package. Take it from the ecosystem you
+already use:
 
 ```bash
 gem install enola-guides                                         # RubyGems
@@ -32,94 +150,14 @@ enola-guides list                    # every item; list guides, list laws, list
 enola-guides show guides/01-start-here
 enola-guides copy laws/foreign-keys  # writes enola/constraints/foreign-keys.yaml
 enola-guides copy skills/enola       # writes .claude/skills/enola/SKILL.md
+enola-guides copy hooks/stop-debt    # writes .claude/hooks/stop-debt.sh
+enola-guides copy examples/python-service   # a project to try the guides on
 ```
 
 `copy` writes an item's files under a directory each kind has a default
-for (`enola/constraints` for a law, `.claude/skills` for a skill,
-`enola/recipes` for a recipe) or the one you name, and never overwrites:
-it names the first file that exists and writes nothing. The gem also
-carries the tree itself, so `gem contents enola-guides` lists every file
-and a team can pin the guidance it adopted in its `Gemfile`.
-
-## Start with an example
-
-[`examples/rails-shop`](examples/rails-shop): a Rails application declaring
-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/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/python-service`](examples/python-service),
-[`examples/typescript-service`](examples/typescript-service),
-[`examples/go-service`](examples/go-service) and
-[`examples/rust-service`](examples/rust-service): the same four-layer
-service in each language, with its source, breaking the laws it states on
-purpose so you can watch each one fire. [`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.
-
-## Guides
-
-1. [Start here](guides/01-start-here.md): install, snapshot, baseline, a
-   graded change, the hooks, a first law. Ten minutes.
-2. [A Rails application](guides/02-rails.md): what enola measures, the
-   Prism and Rubydex providers, the recipe, the laws a Rails team writes.
-3. [An Ember application](guides/03-ember.md): the Ember facts, the
-   conventions as a recipe, an app inside a larger repository.
-4. [Writing laws](guides/04-writing-laws.md): parts, the twenty-one
-   sentences, modes, dates, exemptions, what a refusal means.
-5. [Constraints in CI](guides/05-constraints-in-ci.md): the check step.
-6. [Hooks and agents](guides/06-hooks-and-agents.md): the session hooks,
-   the MCP tools, the skills.
-7. [Providers](guides/07-providers.md): the seam, the Ruby pair, the
-   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.
-13. [tabula](guides/13-tabula.md): the knowledge base kept by a tool that
-    carries cardo, its laws compiled into `enola/constraints/`, PRDs
-    graded with `enola check`, and which hand-built piece each verb
-    replaces.
-14. [taha](guides/14-taha.md): agents run on a tabula project under a
-    mandate, gated by tabula's verdicts, asking before anything is
-    published.
-15. [A Python service](guides/15-python.md),
-16. [a TypeScript or JavaScript service](guides/16-typescript.md),
-17. [a Go service](guides/17-go.md), and
-18. [a Rust service](guides/18-rust.md): what enola measures in each
-    language, the `layered` recipe bound to a service, the law over
-    `imports` its domain rules need, dependencies, and where v0.4.34 reads
-    less than the code says.
-
-## Skills
-
-The skills under [`templates/skills/`](templates/skills) are the ones used
-day to day with enola's MCP in an agent session: `enola` (ask the graph
-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), 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
-
-[`templates/`](templates): the CI check script and its comment renderer,
-a cluster configuration, a constraints starter. [`recipes/`](recipes/README.md) (the catalogue munola binds, each recipe with the number its laws held at):
-recipes a repository copies into its own `enola/recipes/` and binds in one
-line, starting with the Ember conventions and a house-recipe template;
-starting points the team reviews, never defaults the tool applies.
+for (`enola/constraints` for a law, `enola/recipes` for a recipe,
+`.claude/skills` for a skill, `.claude/hooks` for a hook) or the one you
+name, and never overwrites: it names the first file that exists and
+writes nothing. The gem also carries the tree itself, so
+`gem contents enola-guides` lists every file and a team can pin the
+guidance it adopted in its `Gemfile`.