enola-guides 0.0.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 76f0a1325c41c7ff90c0e6a2b2952cd597ed7496103df0e6756ad197855da705
-  data.tar.gz: 2bb8581b18beb14dec24dc2b61df053768ee8dea9378bf7d10fa43e5b74000c8
+  metadata.gz: 103217d2be760b0b582027a9119e6acc6fae874ffc1171f8e59df35ac5ffb09b
+  data.tar.gz: 65f13f8cd1c54cafec16aca3f50a80710dcc77df8f6e66077c54fb346afeaf3a
 SHA512:
-  metadata.gz: 845c312c4126618fa265248d19b3a515c47d854c830616d03d1254c9f42df4a6ce1b263fa77b431b1eaa6d64a58e8a7684dbc98d79a8fe590c5c3d20bde366d2
-  data.tar.gz: 6de47b842e40351d514f84b3af1d4b2bd4e5e2145f1f9c329521e251bc9a36842cdde9f41b1c1edbff306b231777b91c5d189ea5b79098453a45de0dde1c639e
+  metadata.gz: 9cac7aed45a1041aeaeb66c46040f165dfa4156b05d5c2c088890dd18912930b6924059b5f0b1bcc00c4379b7574e524ab8794a43c936a5e5915a4afccf7572c
+  data.tar.gz: fe230a7e9daac6c8c88662bdcce76f1be1ff8019992c48f57a95afb469fc4bad58bd02e6171d62603e796b80cd31938826d59a5c8010adada9fa116d5a16e13d

data/CHANGELOG.md

@@ -0,0 +1,25 @@
+# Changelog
+
+## 0.1.1 (2026-08-22)
+
+The laws catalogue: `examples/laws/`, twenty-six complete declarations one
+directory each, nineteen proven by enola's benchmark suite and seven
+generalised from daily use (foreign keys, maintenance tasks, a public tool
+prefix, one door to a schema, readers that read the store only, cluster
+laws), each with a README and verified with `constraints lint`.
+
+## 0.1.0 (2026-08-22)
+
+First content. Eight guides (start here, a Rails application, an Ember
+application, writing laws, constraints in CI, hooks and agents,
+providers, beyond one repository), two worked examples (a Rails shop in
+the Ruby DSL with Prism and Rubydex as providers; an Ember app bound to
+the conventions recipe), four agent skills (enola, enola-laws,
+enola-grade-before-push, enola-intent-first), the CI check template with
+its renderer, a cluster configuration, a constraints starter, and two
+recipes. Written against the release of enola that carries the
+constraints vocabulary (enola-labs/enola#247).
+
+## 0.0.0
+
+Placeholder to claim the name.

data/README.md

@@ -1,12 +1,63 @@
 # enola-guides
 
-Guides, presets and onboarding material for
-[enola](https://github.com/enola-labs/enola), the architecture-graph tool,
-written for Ruby and Rails developers first.
+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
+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.
 
-Ready-to-use templates, presets, skills and instructions: how to use enola on
-a Rails app, on Ember, as a constraints gate in CI, and through hooks and
-agent skills. Consumed by [enola-rb](https://github.com/misabegovic/enola-rb),
-the gem that runs enola.
+```bash
+gem install enola-guides
+gem contents enola-guides
+```
 
-Placeholder release. No content yet.
+## 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
+"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):
+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.
+
+## 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). Copy a directory into your agent's skills folder.
+
+## Templates and recipes
+
+[`templates/`](templates): the CI check script and its comment renderer,
+a cluster configuration, a constraints starter. [`recipes/`](recipes/README.md):
+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.

data/examples/ember-app/enola/constraints/ember.yaml

@@ -0,0 +1,10 @@
+# The Ember conventions bound in one block. The recipe is copied from
+# enola-guides' recipes/ into this repository's enola/recipes/, where the
+# team reviews it; the two optional roles are bound to this app's helpers.
+use_recipe:
+  - recipe: ember-conventions
+    as: app
+    mode: ratchet
+    bind:
+      task-factories: { match: ["app/utils/**"], name_pattern: "*.trackedFunction" }
+      fixture-setup: { match: ["tests/helpers/**"] }

data/examples/ember-app/enola/recipes/ember-conventions.yaml

@@ -0,0 +1,83 @@
+recipe: ember-conventions
+roles:
+  - name: components
+    match: ["app/components/**"]
+  - name: integration-tests
+    kind: test_ref
+    match: ["tests/integration/**"]
+  - name: actions
+    kind: symbol
+    where: { decorators: action }
+  - name: framework-controllers
+    kind: symbol
+    where: { superclass_module: "@ember/controller" }
+  - name: constructors
+    match: ["app/**"]
+    name_pattern: "*.constructor"
+  - name: fetchers
+    match: ["app/services/**"]
+  - name: legacy-accessor
+    match: ["app/utils/**"]
+    name_pattern: "*.get"
+  - name: argument-mutators
+    kind: symbol
+    where: { fields_written: args }
+  - name: element-modifiers
+    kind: symbol
+    match: ["app/components/**", "app/modifiers/**"]
+  - name: state-writing-members
+    kind: symbol
+    where: { fields_written: "<any>" }
+  - name: task-factories
+    optional: true
+  - name: fixture-setup
+    optional: true
+rules:
+  - id: no-action-decorator
+    forbid_fact: actions
+    because: "An arrow function binds lexically and needs no decorator; the decorator predates it and the convention says to stop writing it."
+
+  - id: no-framework-controllers
+    forbid_fact: framework-controllers
+    because: "A route component replaces the controller and its template. Controllers are quirky and carry surprising singleton state, and the convention is to stop adding them."
+
+  - id: components-import-no-render-modifiers
+    forbid: components
+    to_name: ["@ember/render-modifiers*", "ember-render-helpers*"]
+    via: imports
+    because: "The render-helper form fires on a lifecycle rather than attaching to the element it acts on, and it has been discouraged for years. A named modifier attaches to the element and says what it acts on."
+
+  - id: constructors-do-not-fetch
+    forbid: constructors
+    to: fetchers
+    via: calls
+    because: "Rendering pulls data in as it is needed. A constructor that fetches is eager, runs before anything asks, and cannot be re-run when the arguments change."
+
+  - id: no-legacy-property-accessor
+    forbid: components
+    to: legacy-accessor
+    via: calls
+    because: "The proxy accessor reads through a layer that no longer exists on a resolved value, and it defeats type checking. Reach for the property."
+
+  - id: arguments-are-not-mutated
+    forbid_fact: argument-mutators
+    because: "Data flows down and actions flow up. A component that writes through its own arguments changes state it does not own, and the owner never learns of it. Pass a callback and let the owner make the change."
+
+  - id: a-modifier-takes-its-element
+    require: element-modifiers
+    when_edge_to: ["*.modifier"]
+    via: calls
+    must_prop_contain: { prop: takes_parameters, value: "yes" }
+    because: "A modifier is handed the element it is attached to. One that declares no parameter is not modifying anything; it is a side effect fired by render, and a getter or a tracked task says that honestly."
+
+  - id: derivations-do-not-write
+    forbid: state-writing-members
+    to: task-factories
+    via: calls
+    because: "A task is derived state and runs inside the render cycle. Writing the component's own state from one schedules another render off the render it is running in. Return the data and read it through the task's value instead."
+
+  - id: component-tests-carry-no-fixtures
+    forbid: integration-tests
+    to: fixture-setup
+    via: calls
+    because: "A fixture library sets up back-end state and has no place in a component test: if the component makes no request, build a front-end record, and if it does, let the acceptance layer answer it."

data/examples/laws/README.md

@@ -0,0 +1,32 @@
+# Laws, one directory each
+
+Every directory holds a complete declaration you can copy into a repository's
+`enola/` and run. Most are proven by enola's own benchmark suite; the rest are
+generalised from laws in daily use on a multi-repository estate.
+
+- [`governed-code`](governed-code/README.md): The knowledge pages compile into the graph as anchors, and a law demands that every file of a part has one.
+- [`rails-forbidden-names`](rails-forbidden-names/README.md): A naming convention phrased as a prohibition.
+- [`rails-mutations-are-authorized`](rails-mutations-are-authorized/README.md): The code behind a mutating route is selected by the route's method through the handled_by edge the Rails binder draws, and must reach a policy.
+- [`rails-request-boundaries`](rails-request-boundaries/README.md): The Rails laws a team actually writes.
+- [`rails-strict-arrangement`](rails-strict-arrangement/README.md): The strict Rails arrangement: the Rails laws, no circle among the parts, and concerns that stay independent of their includers.
+- [`clean-rings`](clean-rings/README.md): Four rings.
+- [`cqrs-queries-never-write`](cqrs-queries-never-write/README.md): A command-query split.
+- [`instantiation`](instantiation/README.md): What Ruby code constructs, as a fact.
+- [`mixins-stay-independent`](mixins-stay-independent/README.md): A module never reaches the classes that include it.
+- [`naming-conventions`](naming-conventions/README.md): Ruby naming conventions: no get_, set_ or is_ prefixes; a predicate ends in a question mark and has_ is fine.
+- [`one-owner-per-table`](one-owner-per-table/README.md): unique_across compares the members of different repositories; with the storage facts of one repository there is nobody to share a table with, so the rule refuses by name rather than reporting every table as unique.
+- [`paired-names`](paired-names/README.md): A naming pair: every with_ method has a without_ twin.
+- [`parts-never-cycle`](parts-never-cycle/README.md): Parts that may not depend on each other in a circle.
+- [`protocol-any-of`](protocol-any-of/README.md): A protocol satisfied by one of several methods.
+- [`public-surface`](public-surface/README.md): A path-defined public surface.
+- [`receiverless-request-api`](receiverless-request-api/README.md): A literal far end narrowed to receiver-less calls.
+- [`resolved-ancestry`](resolved-ancestry/README.md): Ancestry a provider resolved, and a component selected by it.
+- [`routes-have-consumers`](routes-have-consumers/README.md): A law across repositories refuses by name inside one.
+- [`storage-stays-home`](storage-stays-home/README.md): A part keeps to the tables it owns.
+- [`vanilla-rails-stays-empty`](vanilla-rails-stays-empty/README.md): Plain Rails: the extra directories must stay empty, each with a stated reason.
+- [`foreign-keys`](foreign-keys/README.md): A foreign-key law reads the storage facts the schema yields: every table carrying a tenant column must declare the foreign key to the tenant table.
+- [`maintenance-tasks`](maintenance-tasks/README.md): Two laws for a maintenance-tasks directory: a naming convention the runner depends on, and a boundary against controller code that has no request to read.
+- [`public-tool-prefix`](public-tool-prefix/README.md): A naming law on an externally exposed surface: every class in the public tools directory carries the prefix, so the surface stays greppable and a public class can never shadow an internal one.
+- [`one-door`](one-door/README.md): A boundary with one sanctioned crossing: controllers may not reach the GraphQL schema, except the single execute action, named as an exemption with its owner and reason so the carve-out is a decision and not a hole.
+- [`readers-read-the-store-only`](readers-read-the-store-only/README.md): The allow form: a part's calls may land only in the named parts.
+- [`cluster-laws`](cluster-laws/README.md): Laws that only a cluster snapshot can answer: a table owned by two repositories, mutating actions selected through the routes they handle, and routes no loaded client calls.

data/examples/laws/clean-rings/README.md

@@ -0,0 +1,10 @@
+# clean rings
+
+Four rings. An entity that calls a use case and a use case that calls an
+adapter both point outward; the controller calling inward is the direction the
+arrangement allows. The shipped clean recipe names the two outward reaches.
+
+Declaration: `enola/constraints/clean.yaml`.
+
+Verify it on your own tree: copy `enola/` into the repository, run
+`enola constraints lint .`, then `enola --generate . && enola check .`.

data/examples/laws/clean-rings/enola/constraints/clean.yaml

@@ -0,0 +1,8 @@
+use_recipe:
+  - recipe: clean
+    as: clean
+    bind:
+      frameworks: { match: ["app/controllers/**"] }
+      interface-adapters: { match: ["app/adapters/**"] }
+      use-cases: { match: ["app/use_cases/**"] }
+      entities: { match: ["app/entities/**"] }

data/examples/laws/cluster-laws/README.md

@@ -0,0 +1,9 @@
+# cluster laws
+
+Laws that only a cluster snapshot can answer: a table owned by two
+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 .`,
+then `enola --generate . && enola check .`.

data/examples/laws/cluster-laws/enola/constraints/cluster.rb

@@ -0,0 +1,24 @@
+Enola.architecture "platform" do
+  part :tables, files: "app/models/**", kind: :storage
+  part :mutating_actions, service: :backend, files: "app/controllers/**", handles: [:post, :put, :patch, :delete]
+  part :policies, service: :backend, files: "app/policies/**"
+  part :api, service: :backend, files: "config/**", kind: :route
+
+  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
+
+  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
+
+  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/cqrs-queries-never-write/README.md

@@ -0,0 +1,11 @@
+# cqrs queries never write
+
+A command-query split. A query that calls update_all writes; a read model that
+issues a command is a feedback loop; a query that only counts is clean. The
+shipped cqrs recipe names the two breaches by the mutating method and the
+command reached.
+
+Declaration: `enola/constraints/cqrs.yaml`.
+
+Verify it on your own tree: copy `enola/` into the repository, run
+`enola constraints lint .`, then `enola --generate . && enola check .`.

data/examples/laws/cqrs-queries-never-write/enola/constraints/cqrs.yaml

@@ -0,0 +1,7 @@
+use_recipe:
+  - recipe: cqrs
+    as: cqrs
+    bind:
+      commands: { match: ["app/commands/**"] }
+      queries: { match: ["app/queries/**"] }
+      read-models: { match: ["app/read_models/**"] }

data/examples/laws/foreign-keys/README.md

@@ -0,0 +1,10 @@
+# foreign keys
+
+A foreign-key law reads the storage facts the schema yields: every table
+carrying a tenant column must declare the foreign key to the tenant table. The
+require form verdicts what a member fact carries, with a when antecedent
+narrowing to the tables the law is about, so a table without the column is
+never asked.
+
+Declaration under `enola/constraints/`. Copy it, run `enola constraints lint .`,
+then `enola --generate . && enola check .`.

data/examples/laws/foreign-keys/enola/constraints/foreign-keys.yaml

@@ -0,0 +1,12 @@
+components:
+  - name: tables
+    match: ["db/structure.sql", "db/schema.rb", "app/models/**"]
+    kind: storage
+
+rules:
+  - id: account-fk
+    require: tables
+    when_prop_contains: { prop: columns, value: account_id }
+    must_prop_contain: { prop: fk_constraints, value: "account_id->accounts" }
+    mode: advisory
+    because: "A table carrying account_id references an account, so the database should say so with a foreign key. Advisory while a backfill path that ships the column before the constraint is reconciled with the rule; the verdict names every table that carries the column without the key."

data/examples/laws/governed-code/README.md

@@ -0,0 +1,11 @@
+# governed code
+
+The knowledge pages compile into the graph as anchors, and a law demands that
+every file of a part has one. The charge service is anchored by the decision
+page; the refund service is not, and is named. Without any compiled page the
+rule would refuse rather than call everything ungoverned.
+
+Declaration: `enola/constraints/governance.rb`.
+
+Verify it on your own tree: copy `enola/` into the repository, run
+`enola constraints lint .`, then `enola --generate . && enola check .`.

data/examples/laws/governed-code/enola/constraints/governance.rb

@@ -0,0 +1,8 @@
+Enola.architecture "shop" do
+  part :billing, files: "app/billing/**"
+
+  law "billing is governed" do
+    billing.must_be_governed
+    why "code under a decision needs the page that decided it"
+  end
+end

data/examples/laws/instantiation/README.md

@@ -0,0 +1,14 @@
+# instantiation
+
+What Ruby code constructs, as a fact. `new` on a literal constant is an
+instantiates relation from the calling member to the class, which is the one
+call whose result has a knowable type; `new` on a variable receiver names no
+class and records nothing. A construction whose result is immediately sent a
+message is the one-shot ceremony, named on the calling member as Class.method,
+so a component can select the members that perform it and a rule can forbid
+it. A construction bound to a local first is not the ceremony.
+
+Declaration: `enola/constraints/ceremony.yaml`.
+
+Verify it on your own tree: copy `enola/` into the repository, run
+`enola constraints lint .`, then `enola --generate . && enola check .`.

data/examples/laws/instantiation/enola/constraints/ceremony.yaml

@@ -0,0 +1,11 @@
+components:
+  - name: one-shot-builders
+    kind: symbol
+    match: ["app/services/**"]
+    where:
+      one_shot_call: "Payments::Charge.call"
+
+rules:
+  - id: no-one-shot-charge
+    forbid_fact: one-shot-builders
+    because: "a charge is built and called in one breath, so nobody can hold it to test it"

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

@@ -0,0 +1,9 @@
+# maintenance tasks
+
+Two laws for a maintenance-tasks directory: a naming convention the runner
+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 .`,
+then `enola --generate . && enola check .`.

data/examples/laws/maintenance-tasks/enola/constraints/maintenance-tasks.rb

@@ -0,0 +1,15 @@
+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/laws/mixins-stay-independent/README.md

@@ -0,0 +1,11 @@
+# mixins stay independent
+
+A module never reaches the classes that include it. Taggable calls Post, which
+includes it; Auditable calls Ledger, which does not. Who includes whom comes
+from the resolved ancestry the rubydex provider emits, so the rule refuses
+with a named cause on a snapshot without it and names Taggable on one with it.
+
+Declaration: `enola/constraints/concerns.yaml`.
+
+Verify it on your own tree: copy `enola/` into the repository, run
+`enola constraints lint .`, then `enola --generate . && enola check .`.

data/examples/laws/mixins-stay-independent/enola/constraints/concerns.yaml

@@ -0,0 +1,9 @@
+components:
+  - name: concerns
+    match: ["app/models/concerns/**"]
+    kind: symbol
+    where: { symbol_kind: interface }
+rules:
+  - id: mixins-stay-independent
+    independent: concerns
+    because: "a mixin that knows its includer is half a class in hiding"

data/examples/laws/naming-conventions/README.md

@@ -0,0 +1,10 @@
+# naming conventions
+
+Ruby naming conventions: no get_, set_ or is_ prefixes; a predicate ends in a
+question mark and has_ is fine. Three offenders and two clean names in one
+class.
+
+Declaration: `enola/constraints/naming.yaml`.
+
+Verify it on your own tree: copy `enola/` into the repository, run
+`enola constraints lint .`, then `enola --generate . && enola check .`.

data/examples/laws/naming-conventions/enola/constraints/naming.yaml

@@ -0,0 +1,5 @@
+use_recipe:
+  - recipe: ruby-conventions
+    as: ruby
+    bind:
+      code: { match: ["app/**"], kind: symbol, where: { symbol_kind: method } }

data/examples/laws/one-door/README.md

@@ -0,0 +1,8 @@
+# one door
+
+A boundary with one sanctioned crossing: controllers may not reach the GraphQL
+schema, except the single execute action, named as an exemption with its owner
+and reason so the carve-out is a decision and not a hole.
+
+Declaration under `enola/constraints/`. Copy it, run `enola constraints lint .`,
+then `enola --generate . && enola check .`.

data/examples/laws/one-door/enola/constraints/one-door.yaml

@@ -0,0 +1,18 @@
+components:
+  - name: controllers
+    match: ["app/controllers/**"]
+  - name: schema
+    match: ["app/graphql/**"]
+
+rules:
+  - id: controllers-reach-the-schema-through-one-door
+    forbid: controllers
+    to: schema
+    via: calls
+    mode: advisory
+    exempt:
+      - witness: "Api::GraphqlController#execute -> AppSchema.execute via calls"
+        owner: platform
+        since: "2026-08-22"
+        because: "the one sanctioned entry point"
+    because: "Controllers reach the schema through exactly one door, the execute action; every other controller stays out of it. A second door is a second place to forget authentication."

data/examples/laws/one-owner-per-table/README.md

@@ -0,0 +1,12 @@
+# one owner per table
+
+unique_across compares the members of different repositories; with the storage
+facts of one repository there is nobody to share a table with, so the rule
+refuses by name rather than reporting every table as unique. The verdict that
+names two owners needs the cluster, which the harness measures per repository
+by design.
+
+Declaration: `enola/constraints/tables.rb`.
+
+Verify it on your own tree: copy `enola/` into the repository, run
+`enola constraints lint .`, then `enola --generate . && enola check .`.

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

@@ -0,0 +1,8 @@
+Enola.architecture "shop" do
+  part :tables, files: "app/models/**", kind: :storage
+
+  law "one owner per table" do
+    tables.must_be_unique_across by: :table
+    why "two writers to one table disagree in the end"
+  end
+end

data/examples/laws/paired-names/README.md

@@ -0,0 +1,9 @@
+# paired names
+
+A naming pair: every with_ method has a without_ twin. with_history has its
+twin, with_guests does not, archive is outside the pattern and never asked.
+
+Declaration: `enola/constraints/pairs.yaml`.
+
+Verify it on your own tree: copy `enola/` into the repository, run
+`enola constraints lint .`, then `enola --generate . && enola check .`.

data/examples/laws/paired-names/enola/constraints/pairs.yaml

@@ -0,0 +1,11 @@
+components:
+  - name: chat
+    match: ["app/chat/**"]
+    kind: symbol
+    where: { symbol_kind: method }
+rules:
+  - id: paired-scopes
+    require_name: chat
+    pattern: "with_*"
+    requires: "without_*"
+    because: "a reader who finds with_ expects without_ beside it"

data/examples/laws/parts-never-cycle/README.md

@@ -0,0 +1,12 @@
+# parts never cycle
+
+Parts that may not depend on each other in a circle. Jobs reach models and
+models reach jobs, so the two form a cycle at the part level; mailers sit
+downstream of models only. The rule contracts the module graph to one node per
+declared part, admits the symbol-rollup edges Ruby has, and names the circle;
+the downstream part is not in it.
+
+Declaration: `enola/constraints/cycles.yaml`.
+
+Verify it on your own tree: copy `enola/` into the repository, run
+`enola constraints lint .`, then `enola --generate . && enola check .`.

data/examples/laws/parts-never-cycle/enola/constraints/cycles.yaml

@@ -0,0 +1,12 @@
+components:
+  - name: jobs
+    match: ["app/jobs/**"]
+  - name: models
+    match: ["app/models/**"]
+  - name: mailers
+    match: ["app/mailers/**"]
+rules:
+  - id: parts-never-cycle
+    forbid_cycles: jobs
+    among: [models, mailers]
+    because: "parts that reach each other in a circle cannot be taken apart"

data/examples/laws/protocol-any-of/README.md

@@ -0,0 +1,10 @@
+# protocol any of
+
+A protocol satisfied by one of several methods. Charge defines call, Refund
+defines run, Reconcile defines neither; any_of accepts either door and names
+the class with none, listing what would have satisfied it.
+
+Declaration: `enola/constraints/entry.yaml`.
+
+Verify it on your own tree: copy `enola/` into the repository, run
+`enola constraints lint .`, then `enola --generate . && enola check .`.

data/examples/laws/protocol-any-of/enola/constraints/entry.yaml

@@ -0,0 +1,8 @@
+components:
+  - name: services
+    match: ["app/services/**"]
+rules:
+  - id: entry-point
+    require_defines: services
+    any_of: [call, run]
+    because: "a service answers to one of two doors; a class with neither is one nobody can invoke"

data/examples/laws/public-surface/README.md

@@ -0,0 +1,11 @@
+# public surface
+
+A path-defined public surface. Ruby has no visibility keyword the extractor
+can read at the file level, so a component names the files that are its public
+surface; reaching a public file from outside is fine and reaching an internal
+one is the breach.
+
+Declaration: `enola/constraints/surface.yaml`.
+
+Verify it on your own tree: copy `enola/` into the repository, run
+`enola constraints lint .`, then `enola --generate . && enola check .`.

data/examples/laws/public-surface/enola/constraints/surface.yaml

@@ -0,0 +1,10 @@
+components:
+  - name: billing
+    match: ["app/billing/**"]
+    public: ["app/billing/public/**"]
+  - name: orders
+    match: ["app/orders/**"]
+rules:
+  - id: billing-surface
+    private: billing
+    because: "billing is reached through its public files; the rest is implementation"

data/examples/laws/public-tool-prefix/README.md

@@ -0,0 +1,8 @@
+# public tool prefix
+
+A naming law on an externally exposed surface: every class in the public tools
+directory carries the prefix, so the surface stays greppable and a public
+class can never shadow an internal one.
+
+Declaration under `enola/constraints/`. Copy it, run `enola constraints lint .`,
+then `enola --generate . && enola check .`.

data/examples/laws/public-tool-prefix/enola/constraints/public-tools.rb

@@ -0,0 +1,8 @@
+Enola.architecture "app" do
+  part :public_tools, files: "app/public_tools/**", kind: :symbol, where: { symbol_kind: "class" }
+
+  law "public tools carry the Public prefix" do
+    public_tools.names_must_match "Public*"
+    why "an externally exposed tool class is greppable by its prefix and cannot shadow an internal one"
+  end
+end