enola-guides 0.3.1 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f8f7f20100ffdeea1ae928ad9e76186848aeba81caed9491993e09cfc5bc7461
-  data.tar.gz: dcbacd0bba3cf8ee9883b1590a8cd969d1c01150d4549789c1869920dad8de9e
+  metadata.gz: 8d1b81f179855dbd64a4feb84618651f3b3805d7410dd82f09238fb9a3896f00
+  data.tar.gz: 46ec48df52057f409f66e0a60ee1c32224cdfc84f06da9474c85561923a677b5
 SHA512:
-  metadata.gz: f3de1b04dfb1ec8c76f2686d4730052a0f38175721ea288294a09e1f4c2be4fa154d9622748405204b086857bdc5de3969675b49f729b0a5f229f5b8dc5ebebb
-  data.tar.gz: 49e2f753fa478c657683dbe69b729774dc94129a8ba8bf3c6614469b7576e0752857daa266f993006098e8a3e36eeeada89377412548d122c83f9d4fa41d1a01
+  metadata.gz: d6c33d263d7d51ad7b16dc436ddf1412f441309dbbb05f8534fd4efda42c97b8ba2489d02ef9fc04f887ab226261db0f0edab3168dad1c4bf5b2426e899415b8
+  data.tar.gz: 99318280749a1987d2a1197f29ca3fe8850a78df1a5fdd13cc3d743d2e24ce14918b79b8b6ccabd1cb492174db69cec19f5f456a2e57283a31d1f13b8ea43c01

data/CHANGELOG.md

@@ -1,5 +1,173 @@
 # 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,
+crates.io, Go and Homebrew, and binaries for Linux, macOS and Windows on
+the GitHub release. `list`, `show` and `copy` read one catalogue,
+`bundle/bundle.json`, generated from the tree by `script/bundle`: 74 items
+across guides, examples, laws, skills, hooks, recipes and templates. The
+five implementations (Go, Rust, Node, Python, Ruby) are held to the same
+22 cases, byte for byte, by `script/test-clis`, and CI runs them against
+each package as installed from the artifact a release would publish, and
+installs the Homebrew formula from a local tap. `VERSION` is the one
+version; a tag `vX.Y.Z` publishes everywhere through trusted publishing
+(`RELEASING.md`). A `NOTICE` names enola. `CONTRIBUTING.md`, `SECURITY.md`,
+a code of conduct, issue and pull-request templates and Dependabot for the
+actions and the crate; `script/test` runs every check CI runs that needs
+no registry.
+
+## 0.7.0 (2026-10-25)
+
+Python, TypeScript, Go and Rust. Guides 15 to 18 and a worked example in
+each language: the same four-layer service with its source, binding the
+`layered` and `supply-chain` recipes and breaking its laws on purpose.
+`script/test-examples` snapshots every example with the pinned enola and
+fails when the laws reporting a breach are not exactly the ones its
+`EXPECTED` file lists. What the examples showed on v0.4.34, each said
+where it bites:
+
+- `layered`'s two domain rules read `depends_on`, which none of the four
+  extractors writes, so each example states the domain's law over
+  `imports`.
+- A TypeScript handler written inline puts its calls on the file, where
+  the edge rules do not walk; a named handler is walked.
+- An Express `router.post("/")` under a mount produces no route.
+- An Axum router nested inline keeps its bare paths.
+- A Cargo version with no operator counts as pinned.
+
+Guide 01 states its first law in YAML as well as Ruby, and the README
+no longer reads as Rubyists first.
+
+## 0.6.0 (2026-10-25)
+
+tabula and taha. Guide 13 is tabula for an enola user: a release that
+carries cardo inside the binary and finds it last, after `engine.binary`
+and any `enola` on PATH; the tour; laws said on an architecture page and
+compiled into plain enola YAML that upstream v0.4.34 lints clean; a PRD
+bullet graded with `grade: enola check clean`; its hooks beside enola's;
+and which hand-built piece of guides 09 to 12 each verb replaces. Guide
+14 is taha: installing from a clone (the npm name `taha` is another
+package's), a run under a mandate, adopting a repository enola already
+measures, and the `cardo` it calls by name. Guides 09 to 12 keep the
+hand-built path and say where tabula takes it over.
+
+## 0.5.0 (2026-10-25)
+
+What enola shipped between v0.4.4 and v0.4.34, each command and key run
+against v0.4.34 before it was written down:
+
+- Guide 05: enola-action@v2, with the install step that gives it the
+  Rubydex library it does not fetch itself, its outputs, and `-format`
+  `sarif`, `annotations` and `summary`; `-reviewers`. A CI job runs the
+  workflow the guide prints.
+- Guide 06: the opencode and Pi install targets, the Claude Code plugin
+  and what it leaves out, all twenty-two MCP tools, and the questions the
+  CLI answers without an agent (`impact`, `endpoint`, `plan`, `flows`,
+  `constraints ledger`, `dashboard`).
+- Guide 07: the rbs and zeitwerk providers, provider reuse, and pinning a
+  provider of your own.
+- Guide 08: `cluster init` and folders indexed as clusters, why the
+  output directory needs its own name (it is resolved inside each
+  member), `matched_routes`, `caller`, `unreached_by_clients`, `coverage
+  --unresolved`, declaring an in-house HTTP client, and sharing the
+  history.
+- Guide 04: laws over dependencies and the `supply-chain` recipe, the
+  ledger, `no_frame_in_members`, and how `since` falls back to git.
+  In v0.4.34 a Ruby `where:` drops a value that is not a string or a
+  symbol, so the guide quotes booleans and numbers.
+- Guide 02: the `packwerk` explainer and the `package_paths` it needs
+  when packs live outside `packages/`, and the `ruby-conventions` recipe.
+
+## 0.4.0 (2026-10-25)
+
+Checked against enola v0.4.34. enola skips a provider whose
+`expected_version` disagrees with what it answers, and the guides pinned
+Prism at `0.1.0` (the script answers `0.2.0` since v0.4.5) and Rubydex at
+`0.4.0` (the binary carries `0.4.1` since v0.4.33), so their Ruby
+configurations produced no provider facts. Every configuration now names
+the built-in `rubydex` and `prism` providers with no pin; neither needs
+Ruby. Also fixed, each wrong before this release too:
+
+- The configuration file is `mcp-arch.yaml`; enola never read
+  `enola.yaml`, so `examples/rails-shop` now ships `mcp-arch.yaml`.
+- `templates/enola-check.sh` defaults to v0.4.34 (it named `0.5.0`, which
+  does not exist), installs the binary under the name the release archive
+  gives it, configures the built-in providers in a tree with a `Gemfile`,
+  and grades with the configuration it generated with; grading the bare
+  path read no providers and reported every Ruby run as a partial verdict.
+- `templates/enola-findings.rb` renders a partial verdict and names each
+  producer it left ungraded.
+- `constraints init` writes `enola/constraints/recipes.yaml`.
+- A provider that ran on one side only gives a partial verdict, not a
+  decline; the session-start hook pins a baseline, and in Claude Code a
+  `PreToolUse` hook refuses the first two file searches.
+- `doctor` reports the hooks and the baseline, not the Rubydex library.
+- The recipes README lists `ruby-conventions` and `supply-chain` among
+  upstream's built-ins.
+
+A CI workflow lints every example against the pinned enola release, runs
+the check template end to end on a Rails fixture, and checks every
+relative link.
+
 ## 0.3.1 (2026-08-23)
 
 The recipes README says where the catalogue ships: built into munola,

data/LICENSE

@@ -187,7 +187,7 @@ APPENDIX: How to apply the Apache License to your work.
   same "printed page" as the copyright notice for easier
   identification within third-party archives.
 
-Copyright (c) 2026 Dejan Menges
+Copyright (c) 2026 Muhamed Isabegovic
 
 Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.

data/NOTICE

@@ -0,0 +1,7 @@
+enola-guides
+Copyright (c) 2026 Muhamed Isabegovic
+
+Guides, worked examples, skills and templates for enola
+(https://github.com/enola-labs/enola), by Dejan Menges, licensed under the
+Apache License, Version 2.0. enola, tabula, taha and cardo are separate
+projects; no part of their code is included here.

data/README.md

@@ -1,80 +1,163 @@
 # enola-guides
 
-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
-a session. Guides, worked examples, skills and templates, packaged as a
-gem so a team can pin the guidance it adopted. Rubyists first; consumed by
-[enola-rb](https://github.com/misabegovic/enola-rb), the gem that runs
-enola. Expanding as the practice does.
+[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.
+
+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.
+
+## 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
+npm install -g enola-guides                                      # npm
+pipx install enola-guides                                        # PyPI (or uv tool install)
+cargo install enola-guides                                       # crates.io
+go install github.com/misabegovic/enola-guides/cmd/enola-guides@latest
+brew install misabegovic/tap/enola-guides                        # Homebrew
+```
+
+or a binary for Linux, macOS or Windows from the
+[releases](https://github.com/misabegovic/enola-guides/releases). Then:
 
 ```bash
-gem install enola-guides
-gem contents enola-guides
+enola-guides list                    # every item; list guides, list laws, list skills, ...
+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
 ```
 
-## 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/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.
-
-## 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.
+`copy` writes an item's files under a directory each kind has a default
+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`.