@agentsfleet/orly 0.7.1 → 0.9.0

package/dispatch/write_go.md

@@ -22,5 +22,13 @@ a working value.
 Table-driven tests are the default shape. Concurrency work needs a `-race` run,
 and a deterministic contention test rather than a sleep.
 
+A string literal repeated in one file becomes a named constant — `audits/ufs.sh`
+reads `*.go` and enforces it. Two Go shapes are held out, because no rename can
+fix them: members of a `const ( … )` group, which state the binding keyword once
+on the opening line rather than per member, and backtick struct tags, whose
+quoted halves (`json:"id"`) are addressed by reflection and cannot hold a const.
+Both are carve-outs for what the *language* makes unfixable, not permission —
+a flag name or a label spelled inline twice is still the rule.
+
 The repository owns formatting, vet, lint, build, and test commands — it
 declares them in `.oracle/orly.json`.

package/dispatch/write_rust.md

@@ -33,6 +33,172 @@ Local convention wins on conflict, but the divergence is named in the review
 output. Refresh the copy when the user asks or a cited rule looks stale
 (re-run the fetch; upstream updates continuously).
 
+## Error discipline (RULE ERR-RS)
+
+> [DETERMINISTIC → ERR-RS]
+
+Two of the clauses below are decided by `audits/rust-error.sh`, which
+`dispatch/write_rust.sh` runs over staged Rust: an error type with no `Result`
+alias in its crate, and a `map_err` that stringifies its own cause. The other
+two — whether a `source()` implementation returns its own kind, and whether a
+context addition is warranted — need the call site read beside the diff and stay
+the agent's call at write time.
+
+One error type per crate, and a `Result` alias beside it:
+
+    pub type Result<T, E = Error> = core::result::Result<T, E>;
+
+Every fallible function in the crate returns `Result<T>`. The default type
+parameter is what lets the few functions answering with a foreign error keep
+the same spelling — `Result<T, VerifyError>` — instead of reaching for
+`std::result::Result`. A reader must never have to check WHICH error a
+signature returns to know it is this crate's.
+
+**Compose with `From`; `?` does the lifting.** This is `M-FROM-ERROR` and is
+read there, carve-out included; what the guideline leaves open is how the
+variant is spelled, which locally is `#[from]`:
+
+    #[derive(Debug, thiserror::Error)]
+    pub enum BootFailure {
+        #[error(transparent)]
+        Environment(#[from] Refusal),
+        #[error("cannot boot: the database would not answer")]
+        Database(#[from] db::Error),
+    }
+
+**`map_err` only to ADD context the call site alone knows** — a role tag, a
+budget, an operation name; the same carve-out `M-FROM-ERROR` names. And never
+this, which no guideline covers:
+
+    // WRONG: a lossy conversion wearing a conversion's clothes.
+    .map_err(|error| Mine::Database(error.to_string()))?
+
+`to_string()` on the way INTO an error type destroys the `source()` chain. It
+compiles, it reads fine, and it silently defeats every chain walker downstream.
+
+**`source()` returns what caused you, never yourself.** An error whose
+`Display` already renders its kind must not also return that kind as its
+source, or a chain walker prints the same sentence twice before reaching
+anything new:
+
+    // WRONG — Display is "[code] {kind}", so the kind is already printed.
+    fn source(&self) -> Option<&(dyn Error + 'static)> { Some(&self.kind) }
+
+    // RIGHT — skip ourselves, hand back what the kind wraps.
+    fn source(&self) -> Option<&(dyn Error + 'static)> {
+        std::error::Error::source(&self.kind)
+    }
+
+**Not every error has a cause, and that is not a defect.** A variant holding
+another error has one; a variant holding only data (`MissingUrl { knob }`) does
+not — nothing *caused* an unset variable. A test asserting `source().is_some()`
+for every variant is WRONG and forces authors to invent causes. Assert the real
+invariant: where there IS a source, it is not a repeat of our own message.
+
+**Divergence from the reference guideline, named as that section requires.**
+`M-ERRORS-CANONICAL-STRUCTS` prescribes a situation-specific `struct` carrying
+a `Backtrace` and lets a complex crate expose several error types;
+`M-APP-ERROR` further lets an application crate skip its own type for
+`anyhow`/`eyre`/`ohno::AppError`. This rule diverges on all three for one
+reason: a `#[from]`-composed enum behind a single per-crate alias is what lets
+`?` lift across a crate boundary with no call-site conversion, and an
+application-level catch-all erases the variant the caller would have matched
+on. A `Backtrace` inside a variant is welcome. A crate with two genuinely
+unrelated fallible surfaces may carry a second type — with its own alias, under
+these same rules. Cite this divergence in review rather than re-deriving it.
+
+Prior art, not invention: `core_api` (multi-crate workspace, per-crate
+`error.rs` with `pub type Result<T>` + flat `Error`, in production for years),
+bun (`thiserror`, `#[from]`, `pub type Result<T, E = Error>`), habitat (one
+payload-carrying `enum Error`, one alias).
+
+## Functional design (RULE FN-RS)
+
+Design the fallible path as a Result PIPELINE, never as a control-flow tree.
+
+**Fallibility lives in the type, never in a sentinel.** A function that can
+fail returns `Result<T>`; a value that can be absent returns `Option<T>`.
+Never a bool-plus-out-parameter, never a magic value (-1, empty string, null
+UUID), never a logged-and-swallowed error. If the caller cannot see the
+failure in the signature, the design is wrong before the body is written.
+
+**Compose with combinators; spend `match` only where arms genuinely differ.**
+`?`, `map`, `and_then`, `ok_or_else`, `unwrap_or_else` say "transform on
+success, pass failure through" in one line, where a nested match spends five
+and gives every arm a chance to swallow the `Err`:
+
+    // WRONG: the failure path is hand-plumbed, twice.
+    let config = match load(path) {
+        Ok(raw) => match parse(&raw) {
+            Ok(c) => c,
+            Err(e) => return Err(e.into()),
+        },
+        Err(e) => return Err(e.into()),
+    };
+
+    // RIGHT: one pipeline; `?` and `From` (RULE ERR-RS) do the lifting.
+    let config = parse(&load(path)?)?;
+
+A `match` earns its place when the arms carry different LOGIC — not when one
+arm is a hand-written `?`.
+
+**Make illegal states unrepresentable; parse, don't validate.** Convert raw
+input into a type that can only hold valid states ONCE, at the boundary, and
+pass that type inward. Two `Option` fields where exactly one is ever set is an
+enum. A `state: String` compared against literals is an enum. A checked-then-
+used raw value is a newtype whose constructor returns `Result` — that
+constructor is `M-STRONG-TYPES-GUARD`, and picking the type family is
+`M-STRONG-TYPES`. What those do not say is the consequence: interior code that
+trusts its types needs no defensive re-checks — delete them.
+
+**Expression-orientation: bind once.** `let x = if ... { a } else { b };` and
+`let x = match ...` — never a mutable default that later branches overwrite.
+A `mut` that exists only to simulate an expression is a bug surface with no
+compensating power.
+
+**`unwrap()` / `expect()` are for tests and for invariants already proved.**
+`M-PANIC-ON-BUG` settles when a panic is right and `M-PANIC-MESSAGE` that it
+must be helpful; the addition here is WHAT the message carries — the proof
+("mutex never poisoned: no thread panics while holding it"). In production
+code, an `unwrap()` without a written invariant is a `Result` that was never
+designed.
+
+Prior art, not invention: `core_api` — a multi-crate production workspace
+where every crate with a fallible surface carries its own `error.rs` +
+`Result` alias, and the fallible path is written as pipelines throughout
+(573 `.map`, 463 `.and_then`, 164 `.ok_or_else` across the workspace). It has
+run in production for years; its author attributes the absence of error-path
+defects to exactly this design, and the maintenance record bears that out.
+
+## Constant discipline (RULE UFS)
+
+`audits/ufs.sh` reads `*.rs`. It did not until this pack said so, and the cost
+was concrete: a crate spelled a wire verb inline twice — `pong == "PONG" ||
+pong.contains("PONG")` — while `write_any.sh` printed a green UFS row over the
+file, because the façade had always declared `*.rs` and the leaf had never read
+it. Bind the repeated literal to a `const` or `static` and use the name.
+
+Four Rust shapes are held out of the count, because no rename can fix them:
+
+- **`#[cfg(test)]` and `#[test]` blocks.** Rust keeps unit tests inside the file
+  they cover, so fixture keys would otherwise read as that file's worst debt.
+- **Feature-gated test seams** — `#[cfg(feature = "test-util")]`. A helper that
+  hands a sibling integration test one of each error kind has to compile into
+  the crate, which is the only reason it is not behind `cfg(test)`; its contents
+  are fixture data all the same. The match is narrow on purpose: `test` as a
+  whole word or a `-`/`_` segment, so `#[cfg(feature = "redis")]` still counts.
+- **Attribute literals** — `#[serde(rename = "…")]`, `#[cfg(feature = "…")]`,
+  `#[doc = "…"]`. An attribute takes a literal token by language rule; a const
+  is not accepted in that position.
+- **`tests/` and `benches/`** at the crate root, which are fixture trees.
+
+Everything else counts, including `examples/` — not because it compiles, but
+because what repeats there is coupling, not demonstration. A cache namespace
+declared at the top of a walkthrough and matched ninety lines below it, or a
+fixture id that is both the fake store's match arm and the key five call sites
+pass, breaks silently when one end moves. That is the drift RULE UFS exists to
+catch, and example code is where a reader copies it from.
+
 ## Evolution
 
 This pack is young next to the Zig façade and grows the same way: a Rust

package/dispatch/write_rust.sh

@@ -0,0 +1,38 @@
+#!/usr/bin/env bash
+# dispatch/write_rust.sh — the Rust dispatch, DETERMINISTIC façade.
+#
+# Pairs with dispatch/write_rust.md (the LATENT façade — prose the agent reads).
+# This .sh runs the mechanically-checkable subset of the Rust discipline and
+# emits ONE verdict block. The latent trigger ("about to write a *.rs file")
+# dispatches here; everything below is deterministic and re-runnable.
+#
+#   dispatch/write_rust.sh <src/file.rs> [...]   # explicit targets (EXECUTE)
+#   dispatch/write_rust.sh --staged              # staged *.rs (CONFORM, pre-commit)
+#
+# Layering:  AGENTS.md → write_rust.md (latent) → write_rust.sh (this) → audits/*.sh
+# Signals:   🟢 pass · 🔴 fail (blocks) · 🤔 DECIDE (judgment; blocks the TURN, not the script) · 🟣 delegated
+# Exit:      0 = mechanical gates pass · 1 = ≥1 failed · 2 = usage error.
+#
+# Note: Rust had no deterministic façade at all until this file, which is why
+# the error standard the operating model calls mandatory was enforced by review
+# alone. ERR-RS carries the two clauses a machine can decide from the text — a
+# map_err that stringifies its own cause, and an error type with no Result alias
+# beside it. The rest of write_rust.md stays judgment on purpose: ownership,
+# justified `unsafe`, feature combinations, and whether a source() implementation
+# returns its own kind all need a call site read beside the diff, and a gate that
+# guesses at those is a gate people learn to ignore.
+#
+# UFS over *.rs is NOT re-run here. It is wired once in its home façade
+# (write_any), and the universal-code carve-out makes that row satisfy the tag
+# wherever it appears — running it twice would report one violation as two.
+
+source "$(dirname "${BASH_SOURCE[0]}")/lib.sh"
+
+dispatch_init "RUST" '*.rs'
+dispatch_resolve_files "$@"
+dispatch_header
+
+# ── deterministic gates ────────────────────────────────────────────
+dispatch_run_helper "ERR-RS" rust-error.sh --staged
+
+dispatch_verdict

package/docs/EXECUTE_DOC_READS.md

@@ -15,7 +15,7 @@ Every triggered document requires one `📖 DOC READ: <path>` proof-line **per t
 | `*.zig` | `dispatch/write_zig.md`. ZIG GATE per edit. |
 | `*.ts`/`*.tsx`/`*.js`/`*.jsx` | `dispatch/write_ts_adhere_bun.md` — TS FILE SHAPE DECISION (§1) at PLAN, const/import/Bun-primitive discipline, anti-patterns. |
 | `*.rs` | `dispatch/write_rust.md` — ownership, error variants, feature combinations, and contention tests. | <!-- oracle-packs:language.rust -->
-| Rust error type, `Result` alias, or any fallible signature | `dispatch/write_rust.md` §Error discipline — one error per crate, one `Result` alias, `#[from]` composition, `source()` never returns self. | <!-- oracle-packs:language.rust -->
+| Rust error type, `Result` alias, or any fallible signature | `dispatch/write_rust.md` §Error discipline — one error per crate, one `Result` alias, `#[from]` composition, `source()` never returns self. ERR-RS fires per edit: `audits/rust-error.sh` (via `dispatch/write_rust.sh`) blocks a `map_err` that stringifies its own cause and an error type with no alias in its crate; the remaining clauses stay judgment. | <!-- oracle-packs:language.rust -->
 | Designing a Rust function, type, or module; writing `match` on a `Result`/`Option`; any production `unwrap()` | `dispatch/write_rust.md` §Functional design — Result pipelines over control-flow trees, illegal states unrepresentable, bind once, `unwrap` needs a proved invariant. | <!-- oracle-packs:language.rust -->
 | `*.py` | `dispatch/write_python.md` — parsing boundaries, resource ownership, and specific exceptions. |
 | `*.sh` | `dispatch/write_shell.md` — quoting, array arguments, cleanup, input safety, and shell compatibility. |

package/docs/RULE_ENFORCEMENT.md

@@ -12,9 +12,9 @@ regenerates this file and fails on any difference. To update it, run
 | `docs/DOCUMENTATION_RULES.md` | — | 0 | 0 | 0/22 | latent |
 | `docs/LIFECYCLE_PATTERNS.md` | — | 0 | 0 | 0/22 | mechanical |
 | `docs/CHANGELOG_VOICE.md` | — | 0 | 0 | 0/3 | latent |
-| `docs/VERIFY_TIERS.md` | — | 0 | 0 | 0/4 | uncited |
+| `docs/VERIFY_TIERS.md` | — | 0 | 0 | 0/7 | uncited |
 | `docs/greptile-learnings/RULES.md` | — | 0 | 0 | 0/114 | mechanical |
-| **corpus** | | | | **30/285** | |
+| **corpus** | | | | **30/288** | |
 
 ## How to read this
 

package/docs/VERIFY_TIERS.md

@@ -8,16 +8,33 @@ page carries only what is specific to this repository.
 
 | Tier | Command | When |
 |---|---|---|
-| conform | `make harness-verify` | Always, after EXECUTE and before the rest. Any 🔴 returns to EXECUTE. |
-| lint | `make lint-all` | Always. Rust rides `lint-rustd` (rustfmt + Clippy, warnings are errors); script self-tests ride `lint-scripts`. |
-| unit | `make test-unit-all` | Always. The cargo workspace plus every TypeScript package coverage gate. |
-| version | `make check-version` | Always. `VERSION` against `build.zig.zon`, `cli/package.json` and both `rustd/Cargo.toml` sites. |
-
-These four are exactly what `.oracle/orly.json` declares and exactly what
-`orly gate` runs, so the rubric and the mechanical gate grade one boundary.
-
-There is no slow tier. The Zig integration and memory-leak lanes retired with the
-rest of the Zig gating, so no lane a developer runs needs live Postgres or Redis.
+| conform | `make harness-verify` | Section lane and boundary, after EXECUTE and before the rest. Any 🔴 returns to EXECUTE. |
+| lint | `make lint-all` | Boundary. Rust rides `lint-rustd` (rustfmt + Clippy, warnings are errors); script self-tests ride `lint-scripts`. |
+| unit | `make test-unit-all` | Boundary. The cargo workspace plus every TypeScript package coverage gate. |
+| version | `make check-version` | Boundary. `VERSION` against `build.zig.zon`, `cli/package.json` and both `rustd/Cargo.toml` sites. |
+| integration | `make test-integration-rustd` | Boundary. Live Postgres and Redis via docker compose, schemas reset per run. `orly gate pr` skips it on a branch carrying no code. |
+
+These five are exactly what `.oracle/orly.json` declares and exactly what
+`orly gate pr` runs, so the rubric and the mechanical gate grade one boundary.
+
+**Two cadences.** A Section closing is not a milestone closing. Inside a
+Section, run `make harness-verify` plus the lane covering the surface the
+Section touched (`make test-unit-rustd`, `make test-unit-app`, …) — enough to
+prove the Section, never a repository claim. The full table above runs ONCE, at
+CHORE(close).
+
+**Which gate runs which row.** `orly gate work` runs the `conform` row alone and
+is what the pre-commit hook fires, so it costs seconds. `orly gate verify` runs
+the lint, unit, and version rows and is what pre-push fires. `orly gate pr` runs
+the integration row plus the whole-branch and spec criteria, and is what
+CHORE(close) fires — it skips the fast rows because `git.pushed` proves HEAD is
+the commit pre-push already graded.
+
+One lane needs live datastores, and only one. `make/test-infra.mk` brings up
+docker compose Postgres and Redis for `test-integration-rustd`; `make
+test-unit-all` stays datastore-free, because every Rust test needing one is
+`#[ignore]`d and runs only in that lane. `KEEP_TEST_STATE=1` skips the reset for
+the inner loop; Continuous Integration (CI) never sets it.
 
 ## Test Baseline
 
@@ -61,7 +78,14 @@ Paste the deciding line, not the exit code. A gate that reports a number — a s
 against a cap, a count against a budget — is owed that number in the done message.
 
 ```
-✅ Verified: 🧪 lint-all ✓ · 🧪 test-unit-all ✓ <N>p/<M>s · 🔆 harness-verify ✓ · 🔆 check-version ✓
+✅ Verified: 🧪 lint-all ✓ · 🧪 test-unit-all ✓ <N>p/<M>s · 🧩 test-integration-rustd ✓ · 🔆 harness-verify ✓ · 🔆 check-version ✓
+```
+
+A Section lane reports what it ran and says so, never borrowing the repository's
+verdict:
+
+```
+✅ Section verified: 🔆 harness-verify ✓ · 🧪 test-unit-<surface> ✓ <N>p/<M>s
 ```
 
 A skipped target is surfaced as 🟠 with its reason, never dressed as a pass.

package/docs/greptile-learnings/RULES.md

@@ -51,6 +51,7 @@ every code a dispatch `.sh` emits resolves to exactly one row here.
 | LOG | LOGging discipline (scoped event, error_code, severity, redaction) |
 | MSID | Milestone-ID ban in source (M{N}_{NNN} / §x.y / T{N} / dim) |
 | ERR | ERror Registry (UZ-XXX-NNN declared + referenced) |
+| ERR-RS | Rust ERror discipline (one type per crate, Result alias, no stringified cause) |
 | GRP | GREptile rule audit (diff vs greptile-learnings/RULES.md codes) |
 | LDC | Legacy-Design Consult (A remove / B patch / C keep) |
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentsfleet/orly",
-  "version": "0.7.1",
+  "version": "0.9.0",
   "description": "Repository-scoped engineering harness: renders agent rules, materialises the gates that enforce them, and proves the PR boundary \u2014 for any coding agent.",
   "license": "MIT",
   "type": "module",

package/packs/language/rust/rules.md

@@ -35,6 +35,15 @@ output. Refresh the copy when the user asks or a cited rule looks stale
 
 ## Error discipline (RULE ERR-RS)
 
+> [DETERMINISTIC → ERR-RS]
+
+Two of the clauses below are decided by `audits/rust-error.sh`, which
+`dispatch/write_rust.sh` runs over staged Rust: an error type with no `Result`
+alias in its crate, and a `map_err` that stringifies its own cause. The other
+two — whether a `source()` implementation returns its own kind, and whether a
+context addition is warranted — need the call site read beside the diff and stay
+the agent's call at write time.
+
 One error type per crate, and a `Result` alias beside it:
 
     pub type Result<T, E = Error> = core::result::Result<T, E>;

package/registry.json

@@ -36,6 +36,14 @@
           "source": "dispatch/write_pr_description.md",
           "target": "dispatch/write_pr_description.md"
         },
+        {
+          "source": "audits/doc-read.sh",
+          "target": "audits/doc-read.sh"
+        },
+        {
+          "source": "audits/rule-ledger-lib.sh",
+          "target": "audits/rule-ledger-lib.sh"
+        },
         {
           "source": "audits/ufs.sh",
           "target": "audits/ufs.sh"
@@ -118,6 +126,14 @@
         ".rs"
       ],
       "managed_files": [
+        {
+          "source": "dispatch/write_rust.sh",
+          "target": "dispatch/write_rust.sh"
+        },
+        {
+          "source": "audits/rust-error.sh",
+          "target": "audits/rust-error.sh"
+        },
         {
           "source": "packs/language/rust/rules.md",
           "target": "dispatch/write_rust.md"

package/skills/orly-babysit-prs/SKILL.md

@@ -1,14 +1,10 @@
 ---
 name: orly-babysit-prs
 description: |
-  Post-push follow-up for PRs/MRs: backoff-cadence polls over CI check runs
-  (fix every failure your diff caused), every greptile inline thread, and the
-  PR-level summary; classifies via gstack greptile-triage, suppresses via
-  greptile-history, stops after two consecutive empty polls with CI green.
-  Forge-aware (gh PR / glab MR). Use after `gh pr create` / `glab mr create`,
-  after every push to a branch with an open PR/MR, or on "babysit", "watch
-  greptile", "poll the PR/MR", "watch reviews", "follow up on review
-  feedback". Cross-agent: Claude, Codex, OpenCode, Amp.
+  Post-push follow-up for a Pull Request or Merge Request: poll Continuous
+  Integration (CI) checks, greptile threads, and the summary; fix what your diff
+  broke; stop after two empty polls with CI green. Forge-aware (gh, glab). Use
+  after creating or pushing to a PR/MR, or on "babysit", "watch reviews".
 ---
 
 # orly-babysit-prs

package/skills/orly-spec-new/SKILL.md

@@ -1,12 +1,10 @@
 ---
 name: orly-spec-new
 description: |
-  Author a milestone/workstream spec the executing agent (Orly) ships into a
-  deterministic, review-clean, reported Pull Request — intent capture and
-  review-readiness first, file mechanics last. Use on "create a spec", "new
-  milestone", "start M{N}_{NNN}", "spec out X", or any TODO.md attempt
-  (forbidden — every non-trivial intent becomes a spec). Cross-agent,
-  self-contained markdown.
+  Author a milestone or workstream spec that ships as a deterministic,
+  review-clean Pull Request — intent capture first, file mechanics last. Use on
+  "create a spec", "new milestone", "spec out X", "start M{N}_{NNN}", or any
+  TODO.md attempt (forbidden — every non-trivial intent becomes a spec).
 ---
 
 # orly-spec-new

package/skills/orly-write-integration-test/SKILL.md

@@ -1,12 +1,10 @@
 ---
 name: orly-write-integration-test
 description: >
-  Service-layer integration tests against real dependencies (Postgres, Redis,
-  full HTTP router + middleware) with deterministic failure injection,
-  per-test isolation, drain + leak audits, and 100-or-more-connection parallelism
-  proofs. Sister of orly-write-unit-test. Use for handlers, repos, services, or
-  any real-I/O module-boundary crossing. Not for browser E2E (gstack /qa) or
-  pure logic (orly-write-unit-test).
+  Service-layer integration tests against real dependencies — Postgres, Redis,
+  full HTTP router and middleware — with failure injection, per-test isolation,
+  and leak audits. Use for handlers, repositories, services, or any real
+  input/output module boundary; not for browser end-to-end or pure logic.
 ---
 
 # Write Integration Test

package/skills/orly-write-unit-test/SKILL.md

@@ -1,12 +1,10 @@
 ---
 name: orly-write-unit-test
 description: >
-  Risk-weighted, failure-injecting test generation across 8 stacks (Python,
-  Python SDK, OpenAPI, JS/TS CLI, React/TS, Zig, Rust, Shell) enforcing behaviour +
-  failure + invariant + integration + regression coverage with a
-  Definition-of-Done gate; deterministic production-safety proofs (Zig
-  zero-leak, 100-or-more-connection concurrency, complexity/latency budgets) live
-  in the skill body. Use during implementation, not after.
+  Risk-weighted, failure-injecting unit tests across Python, TypeScript, React,
+  Zig, Rust, and shell: behaviour, failure, invariant, and regression coverage
+  behind a Definition-of-Done gate. Production-safety proofs live in the body.
+  Use during implementation, not after.
 ---
 
 # Write Unit Test

package/src/cli.ts

@@ -293,6 +293,12 @@ function printHelp(): void {
 Gates (read-only; no PR without every criterion green or a recorded override):
   orly gate [--accept-dirty]        run work → verify → pr; stop at first red
   orly gate <work|verify|pr>        run one gate
+      work    does this commit conform? the declared conform command; no git
+              state, so a commit hook's own dirty tree never blocks it
+      verify  does the work hold up? spec dimensions, docs language, and the
+              fast verify.* set
+      pr      can this ship? branch, tree, pushed, every spec criterion, and
+              the slow verify.* suites
   orly override <CRITERION> --reason <REASON>
                                     empty commit with an Orly-Override trailer
 
@@ -302,7 +308,11 @@ Install (the repository is the unit — no checkout of this package required):
                                     seeded .oracle/orly.json. A repository that
                                     already has an AGENTS.md keeps it: orly's
                                     rules land as AGENTS.orly.md, reached by a
-                                    pointer block in the file you own.
+                                    pointer block in the file you own. One
+                                    import line lands per runtime that needs
+                                    one (CLAUDE.md, opencode.json), so the
+                                    rules load rather than wait to be noticed;
+                                    a loader you wrote yourself is left alone.
   orly update [--force] [--with <PACK>] [--dry-run] [--json]
                                     re-materialise at the installed engine version
 

package/src/criteria.test.ts

@@ -24,9 +24,12 @@ describe("criteriaFor", () => {
     return criteriaFor(gate, context).map((criterion) => criterion.name).sort();
   }
 
-  test("work evaluates the branch, the tree and the profile", async () => {
+  // work is the commit-time gate, and a commit hook's tree is dirty by
+  // construction. It asks the repository's own conform command and nothing
+  // about git state.
+  test("work evaluates the profile and the conform tier", async () => {
     const project = newSpecRepository();
-    expect(named(WORK, await contextFor(project))).toEqual(["git.branch", "git.tree", REPO_CONFIG]);
+    expect(named(WORK, await contextFor(project))).toEqual(["cmd.conform", REPO_CONFIG]);
   });
 
   test("verify pairs the spec dimensions with the fast command tier only", async () => {
@@ -34,7 +37,9 @@ describe("criteriaFor", () => {
     const names = named(VERIFY, await contextFor(project));
 
     expect(names).toContain("spec.dimensions");
-    expect(names).toContain("cmd.conform");
+    expect(names).toContain("cmd.verify.unit");
+    // conform is the work gate's tier now, so the chain runs it once.
+    expect(names).not.toContain("cmd.conform");
     // The slow tier belongs to the pr gate; leaking it here would make every
     // verify run pay for integration and memory suites.
     expect(names).not.toContain("cmd.verify.integration");
@@ -47,9 +52,15 @@ describe("criteriaFor", () => {
     for (const required of ["spec.moved", "spec.baseline", "spec.ordering", "spec.deferrals", "docs.updated"]) {
       expect(names).toContain(required);
     }
-    // git.branch is a work-gate concern: by pr time the branch is established,
-    // and re-asserting it would make an already-merged branch un-gateable.
-    expect(names).not.toContain("git.branch");
+    // git.branch belongs here and only here. It was a work-gate criterion until
+    // the generated pre-commit hook was found refusing every commit made on the
+    // default branch — including the commit that installs orly, and the
+    // spec-on-main commit the operating model itself prescribes. The question
+    // "is this the default branch" is only ever decisive where a Pull Request
+    // would open from it, so it is asked there. Running `orly gate pr` on a
+    // merged branch reds, which is the honest answer: no PR opens from main.
+    expect(names).toContain("git.branch");
+    expect(names).toContain("git.tree");
   });
 
   test("an unknown gate name yields no criteria rather than throwing", async () => {

package/src/criteria.ts

@@ -36,6 +36,12 @@ const DOCS_LANGUAGE = "docs.language";
 // line is a summary, not a linter dump.
 const NAMED_FINDINGS = 3;
 
+// CONFORM is its own lifecycle stage — EXECUTE → CONFORM → VERIFY — and it is
+// its own tier here for the same reason. Lumped into verify, the deterministic
+// rule audit could only run beside the lint and unit suites, so a repository
+// paid minutes to learn something its seconds-long conform command already
+// knew, and `orly gate` ran it twice on the way to `pr`.
+const CONFORM_TIER = "conform";
 const FAST_TIER = "fast";
 const SLOW_TIER = "slow";
 // The slow tier is a fixed name set, not a prefix rule: lint and version
@@ -45,14 +51,31 @@ const SLOW_COMMANDS = ["verify.integration", "verify.memory"];
 // Every criterion is mechanical: it reads an exit code or a file, never a
 // judgment. The anchor invariant promises the machine can PROVE the PR
 // boundary, so anything unprovable stays prose and never lands here.
-// work = is this branch workable · verify = does the work hold up ·
-// pr = can this ship (whole-branch checks + the slow suites).
+//
+// One gate per cadence, and each question asked at the only moment it can be
+// answered honestly:
+//
+//   work   — does this commit conform? Config plus the declared `conform`
+//            command. Nothing about branch or tree: inside a commit hook the
+//            tree is dirty BY CONSTRUCTION (that is what is being committed),
+//            and the operating model itself says a new spec is committed on the
+//            default branch. Judging either here made the generated pre-commit
+//            hook refuse every commit — including the one installing orly —
+//            with `--no-verify`, which Hard Safety forbids, as the only way out.
+//   verify — does the work hold up? Spec dimensions, documentation language,
+//            and the fast `verify.*` set. Runs before the work leaves the
+//            machine, not after every edit.
+//   pr     — can this ship? The whole-branch facts (branch shape, clean tree,
+//            pushed) plus every spec criterion and the slow suites. A tree is
+//            only required clean where a reviewer is about to read it, and a
+//            branch is only wrong for being `main` where a PR would open from
+//            it.
 export function criteriaFor(gate: string, context: CriterionContext): Criterion[] {
-  if (gate === "work") return [gitBranch(), gitTree(), repositoryConfig()];
+  if (gate === "work") return [repositoryConfig(), ...commandCriteria(context, CONFORM_TIER)];
   if (gate === "verify") return [specDimensions(), docsLanguage(), ...commandCriteria(context, FAST_TIER)];
   if (gate === "pr") {
     return [
-      gitTree(), gitPushed(), specGate(), openQuestions(), productClarity(), specDimensions(),
+      gitBranch(), gitTree(), gitPushed(), specGate(), openQuestions(), productClarity(), specDimensions(),
       specMoved(), specBaseline(), specOrdering(), specDeferrals(),
       docsUpdated(), ...commandCriteria(context, SLOW_TIER),
     ];
@@ -107,10 +130,11 @@ function repositoryConfig(): Criterion {
 }
 
 // Model C: the repository's declared command surface. Orly owns policy and
-// invokes these; the repository owns what they actually do. Fast tier =
-// conform + verify.unit. Slow tier = every other verify.* (integration,
-// memleak); those auto-pass with a printed skip when the branch carries no
-// code, so a prose-only branch never pays for the slow suites.
+// invokes these; the repository owns what they actually do. Conform tier = the
+// `conform` command alone. Fast tier = every verify.* that is not slow. Slow
+// tier = verify.integration and verify.memory; those auto-pass with a printed
+// skip when the branch carries no code, so a prose-only branch never pays for
+// the slow suites.
 function commandCriteria(context: CriterionContext, tier: string): Criterion[] {
   const config = resolvedConfig(context);
   if (!config) return tier === FAST_TIER ? [criterion(REPO_CONFIG, () => ({ ok: false, detail: UNINSTALLED }))] : [];
@@ -125,8 +149,9 @@ function commandCriteria(context: CriterionContext, tier: string): Criterion[] {
 }
 
 function tierOf(key: string): string {
+  if (key === CONFORM_COMMAND) return CONFORM_TIER;
   if (SLOW_COMMANDS.includes(key)) return SLOW_TIER;
-  if (key === CONFORM_COMMAND || key.startsWith(VERIFY_PREFIX)) return FAST_TIER;
+  if (key.startsWith(VERIFY_PREFIX)) return FAST_TIER;
   return "";
 }