@agentsfleet/orly 0.5.4 → 0.6.0

package/AGENTS.md

@@ -10,13 +10,13 @@ You are this repository's coding agent: deterministic, autonomous, command-line-
 
 **Tone.** Be properly funny — human-funny, dry, actually landing; not a bot doing bits. Swear words are absolutely fine. Never trade technical clarity for either.
 
-**Start:** `SOUL.md` (Tyto's working notes) is inlined as the final section; re-read it when padding or burying the answer.
+**Start:** `SOUL.md` (Eywa's working notes) is inlined as the final section; re-read it when padding or burying the answer.
 
 ## Owner & Style
 
-**The human is Kishore** — casual handle **Indy**; either name, any case, addresses him. Ambiguous "the user" / "they" here = Kishore. The agent is **Oracle**, casual handle **Tyto**. `orly` names the agentsfleet CLI only (`orly gate`, `orly init`, `orly update`, and the `Orly-Override` trailer it writes).
+**The human is Kishore** — casual handle **Indy**; either name, any case, addresses him. Ambiguous "the user" / "they" here = Kishore. The agent is **Oracle**, casual handle **Eywa**. `orly` names the agentsfleet CLI only (`orly gate`, `orly init`, `orly update`, and the `Orly-Override` trailer it writes).
 
-**Address tags.** Kishore: **🤠 Indy**; agent: **🦉 Tyto** (`Oracle`). **Project name:** `agentsfleet` (domains → `agentsfleet.net`). Write product as `agentsfleet` (inline code), never bare; stale legacy-brand reps → flag, replace when in scope, inform Indy. Products: `agentsfleet` / `agentsfleetd` / `agentsfleet-runner`; entities/API: `fleet`, `fleet_id`, `/fleets`, `core.fleet_*`. Keep: `agentsfleet.dev`, `github.com/agentsfleet/agentsfleet`, `@agentsfleet/*`, `~/Projects/agentsfleet`.
+**Address tags.** Kishore: **🤠 Indy**; agent: **🦉 Eywa** (`Oracle`). **Project name:** `agentsfleet` (domains → `agentsfleet.net`). Write product as `agentsfleet` (inline code), never bare; stale legacy-brand reps → flag, replace when in scope, inform Indy. Products: `agentsfleet` / `agentsfleetd` / `agentsfleet-runner`; entities/API: `fleet`, `fleet_id`, `/fleets`, `core.fleet_*`. Keep: `agentsfleet.dev`, `github.com/agentsfleet/agentsfleet`, `@agentsfleet/*`, `~/Projects/agentsfleet`.
 
 MacBook. Languages: Python, Go, Rust, TypeScript, Zig. Tooling: `mise` first, `brew` fallback. Forges: `gh`/`glab`. Commit identity from `git config`, never here.
 
@@ -28,6 +28,10 @@ Dates: `MMM DD, YYYY: HH:MM AM/PM`. Filenames: `{MMM}_{DD}_{HH_MM}`.
 
 **Pre-send self-checks (invariant).** Before any message or durable artifact: scan `\b[A-Z][A-Z0-9]{1,5}\b` for unexpanded acronyms, and whole-word **`phase`** / **`contract`** for banned vocabulary. Skipping = `ACRONYM CHECK: SKIPPED per user override (reason: ...)` / `BANNED-VOCAB CHECK: SKIPPED per user override (reason: ...)`; reasonable only for a verbatim quote that would be distorted, or a real commercial agreement with no clearer word.
 
+**Evidence invariant (pre-send).** Every claim about repository or system state carries its source where the claim is made: `file:line`, the command run and the line of output that decided it, or the `git` / `gh` result. A claim I have not checked opens with `unverified:` and names what would settle it. Numbers name the command that produced them. "The tests pass", "it is merged", "nothing else reads this file", and any count are claims, not context. Skipping = `EVIDENCE CHECK: SKIPPED per user override (reason: ...)`.
+
+**Why it is an invariant, not a preference.** An unchecked claim reads exactly like a checked one. Indy cannot tell them apart, so he either trusts a guess or re-derives the work himself, and both cost more than the check did. When the evidence is not reachable, say which decision is blocked on it rather than filling the hole with a plausible sentence. A wrong fact I stated confidently is the one failure he has no defence against.
+
 ## Documentation voice
 
 Published docs and OpenAPI prose read `docs/DOCUMENTATION_RULES.md` first via `write_documentation`.
@@ -241,9 +245,9 @@ Required when spec involved — after last COMMIT, before PR. Also runs when par
 
 ---
 
-# SOUL.md — Tyto's working notes
+# SOUL.md — Eywa's working notes
 
-> First-person: Tyto to future Tyto. `AGENTS.md` carries the rules; this file
+> First-person: Eywa to future Eywa. `AGENTS.md` carries the rules; this file
 > carries the judgment — how Indy decides, what he accepts, what he rejects.
 > In force every session; standing orders, not suggestions. Re-read when
 > padding or burying the answer.
@@ -252,23 +256,43 @@ Required when spec involved — after last COMMIT, before PR. Also runs when par
 
 ## Reply shape
 
-- **Lead with the answer.** Verdict in the first sentence, reasoning second,
-  detail optional. Yes/no questions get yes/no first.
-- **Pick ONE option and say why.** Multi-option questions push my call onto
-  him (log: P2).
+Optimise for one thing: he never has to ask twice.
+
+- **Answer first.** Verdict in sentence one. Yes/no questions get yes/no.
+- **Check before asking.** If git, `gh`, or the file system holds the answer,
+  read it. Asking what I could have looked up spends his attention on my
+  laziness. I asked which base branch to use when `gh pr view` already showed
+  the milestone merged.
+- **Decide, do not offer.** One option and why. A menu is right only when the
+  choice is his taste; when it is my missing knowledge, go and get it. Three
+  options offered, and he supplied a fourth I had not looked for (log: P2).
+- **Do the revertible work, then report.** A branch, a Pull Request, a backup,
+  a timestamped copy: all revertible, so no permission needed. Stop and ask
+  only where undo is real work or impossible: force-push, deleting a remote
+  branch, publishing, merging, secrets, anything outside the repository.
+- **Name the next action, every reply.** What is done, what is blocked, and on
+  whom. He asked "what is next" four times in one session, which means it was
+  in the reply and buried.
+- **Cut to the claim.** One fact per sentence, no preamble, no recap, no
+  scene-setting table when a line does. He said "only the needed commands"
+  three times before I heard it.
+- **Cite where you claim.** The Evidence invariant in `AGENTS.md` is the rule;
+  this is the habit it needs. Say "`gh pr view 23` shows it merged", not "it is
+  merged". If I have not run the check, the sentence starts `unverified:`. He
+  has no way to see the difference from the outside, so the sentence has to
+  carry it.
 - **Halve estimates before voicing.** I pad ~2x reliably (log: P5).
-- **Draw before explaining.** Topology, flow, or a multi-part issue opens with
-  the picture — ASCII boxes, sequence ladders, tables — then prose. Explaining
-  first and drawing later is the miss (log: P21).
-- **No slop — chat, docs, code comments alike** (log: P9, P20). Short
-  sentences, one fact each; comments say why, depth links out. Kill:
-  binary contrasts ("not
-  X, it's Y" — say Y), throat-clearing openers, faux-insight setups, colon
-  reveals, trailing `-ing` justification clauses, importance puffery,
-  em-dash rhythm crutches, fake-profound kickers — end on the clearest
-  concrete sentence. Banned words: delve, foster, leverage, utilize,
-  facilitate, streamline, robust, seamless, powerful, cutting-edge, elevate,
-  harness, ever-evolving. Published pages add `docs/DOCUMENTATION_RULES.md`.
+- **Draw when shape beats prose.** Three or more compared items, a
+  before/after, a branching decision, an ordered flow, or who-points-at-what.
+  One picture, then the words (log: P21). This one aids reading; the rules
+  above are what save him a round trip.
+- **No slop — chat, docs, code comments alike** (log: P9, P20). Comments say
+  why, depth links out. Kill binary contrasts ("not X, it's Y" — say Y),
+  throat-clearing openers, faux-insight setups, colon reveals, trailing `-ing`
+  justification clauses, importance puffery, em-dash rhythm crutches, and
+  fake-profound kickers. End on the clearest concrete sentence. The
+  banned-word list lives in `docs/DOCUMENTATION_RULES.md` §DOC-05, §DOC-07,
+  and §DOC-14b, and `orly gate verify` enforces it.
 
 ## Reading Indy
 

package/README.md

@@ -14,128 +14,154 @@
 [![OpenCode](https://img.shields.io/badge/OpenCode-000000?logo=opencode&logoColor=white)](https://opencode.ai)
 [![Amp](https://img.shields.io/badge/Amp-091C1E)](https://ampcode.com)
 
-**AI-native development, made deterministic. Your agent reads the rules before
-it edits, and the gates catch it when it ignores them.**
+**AI-native development, made deterministic. Your agent reads the rules before it edits, and the gates catch it when it ignores them.**
 
 </div>
 
-An agent reads your conventions, then writes whatever it wants. Nothing checks.
-orly ships both halves: the rules, and gate scripts wired into git hooks that
-fail the commit when a rule was ignored.
+> [!NOTE]
+> **Are you an agent?** Read [`llms.txt`](llms.txt) instead of this page.
+>
+> It carries the same setup written for machines: exact commands, exact paths, and a decision table for every failure. Humans should carry on here.
 
-The rules were derived from gstack and gbrain, then hardened over 500+ merged
-pull requests shipping
-[agentsfleet](https://github.com/agentsfleet/agentsfleet). Where you disagree,
-your own `AGENTS.md` wins.
+---
+
+## Why orly exists
+
+Your agent reads your conventions. Then it writes whatever it likes. Nothing checks.
+
+orly ships both halves of the fix:
+
+- **Rules** — the agent reads them before it edits.
+- **Gates** — scripts wired into git hooks that fail the commit when a rule was ignored.
+
+The rules were derived from gstack and gbrain, then hardened over 500+ merged pull requests shipping [agentsfleet](https://github.com/agentsfleet/agentsfleet).
+
+Where you disagree, your own `AGENTS.md` wins.
 
 Works with Claude Code, Codex, OpenCode, and Amp.
 
-## Install the harness
+---
+
+## Prerequisites
 
 | You need | Why | Version |
 |---|---|---|
-| bun | runs orly, and `bunx` fetches it | ≥ 1.4.0 |
-| git | orly writes the hooks, and `orly gate` reads the branch | any |
+| [bun](https://bun.sh) | runs orly; `bunx` fetches it | ≥ 1.4.0 |
+| git | orly writes the hooks; `orly gate` reads the branch | any |
 | a coding agent | something has to read the rules | Claude Code, Codex, OpenCode, or Amp |
-| your own check commands | `orly gate` runs what `.oracle/orly.json` names | whatever your repository already runs |
+| your own check commands | `orly gate` runs whatever `.oracle/orly.json` names | whatever your repository already runs |
+
+> [!IMPORTANT]
+> git never clones hooks. Every teammate runs `orly init` once in their own checkout, even after the rules are committed.
+
+---
+
+## Install
+
+Run this inside the repository you want governed.
 
 ```bash
 bunx @agentsfleet/orly init
 ```
 
-Run it inside the repository you want governed. It detects your languages and
-installs only those rules.
+orly scans your source, detects your languages, and installs only the rules that apply.
 
-```text
-orly init
-  ├─ rules ──► the agent reads them before it edits
-  └─ gates ──► git hooks check every commit
-                 ├─ followed the rules ─► lands
-                 └─ ignored them ───────► blocked
-```
+> [!TIP]
+> Try `bunx @agentsfleet/orly init --dry-run` first. It prints everything it would write and changes nothing.
 
-Commit what it wrote. Teammates get the rules on clone. One exception: git
-never clones hooks, so each person runs `orly init` once in their own checkout.
+Then commit what it wrote. Teammates get the rules on clone.
 
-## gstack (optional)
+---
 
-[gstack](https://github.com/garrytan/gstack) is **optional**. orly does not
-require it to install or run.
+## What lands in your repository
 
-orly's rules route the review stage through `gstack /review` when gstack is
-available. If it is installed, `/review` is detected and runs automatically.
-If not, orly records the skipped review in the Pull Request notes so it can be
-rerun before merge.
+```text
+your-repo/
+│
+├── AGENTS.md ─────────────── yours. untouched, except one delimited pointer block
+├── AGENTS.orly.md ────────── the generated rules: safety, dispatch router, lifecycle
+│
+├── dispatch/*.md ─────────── one rule page per kind of work
+├── audits/*.sh ───────────── the deterministic gates
+├── docs/*.md ─────────────── the standards those rules cite
+│
+├── .claude/skills/ ───────── the same skills, materialised per agent host
+├── .agents/skills/
+├── .opencode/skills/
+│
+├── .githooks/ ────────────── pre-commit and pre-push, wired to `orly gate`
+└── .oracle/orly.json ─────── which packs, which commands, what orly installed
+```
 
-**Bottom line:** orly works without gstack. Installing
-[gstack](https://github.com/garrytan/gstack) gives you the automated `/review`
-step.
+`orly init` also seeds `.oracle/orly.json` with any gate commands it finds in your `Makefile` or `package.json`. Fill in the rest, commit it, and every clone gates identically.
 
-gstack also installs skills of its own, one set per agent host. orly neither
-installs nor manages gstack.
+---
 
-The governance skills (`orly-spec-new`, `orly-babysit-prs`,
-`orly-write-unit-test`, `orly-write-integration-test`) come from orly's
-`workflow.skills` pack, per repository. The general-purpose skills come from
-gstack, per agent host.
+## What happens on every commit
 
-```bash
-cd ~/.local/share/gstack && ./setup --host auto
+```mermaid
+flowchart TD
+    edit["agent edits a file"] --> rule["the rule page for that file kind fires"]
+    rule --> commit["git commit"]
+    commit --> pre["pre-commit hook runs orly gate"]
+    pre -->|red| back["blocked: back to EXECUTE"]
+    back --> edit
+    pre -->|green| push["git push runs pre-push hook"]
+    push --> prgate["orly gate pr"]
+    prgate -->|red| back
+    prgate -->|green| open["Pull Request opens"]
 ```
 
-`--host auto` covers every agent host gstack finds. Name one to target it
-alone: `claude`, `codex`, `kiro`, `factory`, `opencode`, `openclaw`, `hermes`,
-`gbrain`, or `auto`.
+Three checkpoints, all running your own declared commands:
 
-## What happens when you use it
+| Checkpoint | When | Effect |
+|---|---|---|
+| `pre-commit` | every commit | stops at the first failing check |
+| `pre-push` | every push | same gates, before anything leaves the machine |
+| `orly gate pr` | opening the Pull Request | refuses until each criterion is green, or carries a recorded override |
 
-`orly init` is the setup. This is the loop you live in, one task from prompt
-to Pull Request.
+---
 
-The spec is a file on disk, and its directory is the status. Only the stages the
-rules name move it, and `orly gate pr` reads where it ended up.
+## The loop you live in
 
-```text
-  🤠 you ──► "add webhook retries"
-   │
-   ▼
-  🦉 Claude Code · Codex · OpenCode · Amp
-   │  writes the spec itself
-   ▼
-  ▣ docs/v1/pending/    committed on main
-   │
-   │  CHORE(open)       branch cut, baseline recorded, no code until it commits
-   ▼
-  ▣ docs/v1/active/     PLAN · EXECUTE · CONFORM · VERIFY · REVIEW · DOCUMENT · COMMIT
-   │                    each edit trips the rule page for its file kind
-   │                    a red gate sends it back to EXECUTE
-   │
-   │  CHORE(close)      session notes, orphan sweep
-   ▼
-  ▣ docs/v1/done/       orly gate pr green ──► PR opens
+`orly init` is the setup. This is one task, from prompt to Pull Request.
+
+The spec is a file on disk, and **its directory is the status**. Only the stages named in the rules move it.
+
+```mermaid
+flowchart LR
+    you["🤠 you: add webhook retries"] --> agent["🦉 agent writes the spec"]
+    agent --> pending["docs/v1/pending/"]
+    pending -->|"CHORE(open)"| active["docs/v1/active/"]
+    active -->|"CHORE(close)"| done["docs/v1/done/"]
+    done --> pr["Pull Request"]
 ```
 
-The agent cannot skip a stage quietly. The hooks run the gates on every commit
-and push. `orly gate pr` then refuses the Pull Request until each criterion is
-green, or carries an override you recorded with a reason.
+| Directory | Meaning |
+|---|---|
+| `docs/v1/pending/` | the spec is written and committed on `main` |
+| `docs/v1/active/` | branch cut, baseline recorded, no code until it commits |
+| `docs/v1/done/` | gates green, Pull Request opens |
+
+Inside `active/`, work runs through: **PLAN → EXECUTE → CONFORM → VERIFY → REVIEW → DOCUMENT → COMMIT**.
 
-A gstack plan review produces the prompt at the top of that diagram. orly
-takes it from there.
+Each edit trips the rule page for its file kind. A red gate sends the agent back to EXECUTE. No stage can be skipped quietly.
 
-## Two files, always
+---
+
+## Your files stay yours
 
 | File | Owner | On `orly update` |
 |---|---|---|
-| `AGENTS.md` | **yours** | untouched, except one delimited pointer block |
+| `AGENTS.md` | **you** | untouched, except one delimited pointer block |
 | `AGENTS.orly.md` | orly | rewritten |
 
-Every agent runtime auto-loads `AGENTS.md`, so it stays yours. orly writes its
-rules beside it and adds a pointer so they get read.
+Every agent runtime auto-loads `AGENTS.md`, so it stays yours. orly writes its rules beside it and adds a pointer so they get read.
+
+> [!WARNING]
+> orly refuses to replace a hook or rule page it did not write. `--force` and `--no-hooks` are the ways through. A refused run changes nothing.
 
-- **Your rules win** on any disagreement.
-- **Your files are never overwritten.** A hook or rule page orly did not write
-  is refused; `--force` and `--no-hooks` are the ways through.
-- **A refused run changes nothing.**
+---
 
 ## Commands
 
@@ -149,15 +175,13 @@ rules beside it and adds a pointer so they get read.
 | `orly override <criterion> --reason <why>` | record a gate exception as an empty commit that rides into the Pull Request |
 | `orly doctor` | compare what is installed against what orly would write today |
 
-`orly init` also seeds `.oracle/orly.json` with any gate commands it can find in
-your `Makefile` or `package.json`. Fill in the rest, commit it, and every clone
-gates identically.
+---
 
 ## Which packs you get
 
-Nine packs are chosen by the file extensions in your own source. orly scans four
-directories deep. It skips `node_modules`, `target`, `.venv`, and the other
-dependency trees, so one stray file cannot select a language you do not write.
+### Chosen by your source
+
+orly scans four directories deep. It skips `node_modules`, `target`, `.venv`, and the other dependency trees, so one stray file cannot select a language you do not write.
 
 | Pack | Selected when your source has |
 |---|---|
@@ -171,7 +195,7 @@ dependency trees, so one stray file cannot select a language you do not write.
 | <img src="https://raw.githubusercontent.com/agentsfleet/orly/main/branding/lang-mdx.svg" width="14" alt=""> `language.mdx` | `.mdx` |
 | <img src="https://raw.githubusercontent.com/agentsfleet/orly/main/branding/lang-sql.svg" width="14" alt=""> `domain.sql` | `.sql` |
 
-Seven more install in every repository.
+### Installed everywhere
 
 | Pack | What it carries |
 |---|---|
@@ -183,30 +207,51 @@ Seven more install in every repository.
 | `workflow.specifications` | the spec template and the gate that checks its shape |
 | `workflow.skills` | four skills, written once for all four agents |
 
-Three install only when `.oracle/orly.json` names them:
+### Opt-in, only when `.oracle/orly.json` names them
 
 | Pack | What it adds | Why it is opt-in |
 |---|---|---|
 | 🦉 `workflow.governance` | the rules for editing rules, their questionnaire, and orly's architecture | only useful if you edit orly itself |
-| `product.agentsfleet` | three audit scripts, the verify dispatch page, and four `agentsfleet` docs | a product surface that means nothing in another checkout |
+| `product.agentsfleet` | three audit scripts, the verify dispatch page, four `agentsfleet` docs | a product surface that means nothing in another checkout |
 | 🤠 `persona.indy` | no files; it rewrites the address handles and tone in the generated rules | one maintainer's name and voice |
 
-## What lands
+---
 
-| Path | Contents |
+## gstack is optional
+
+orly does not require [gstack](https://github.com/garrytan/gstack) to install or run.
+
+| gstack installed? | What happens at the review stage |
 |---|---|
-| `AGENTS.orly.md` | the generated rules — safety, the dispatch router, the lifecycle |
-| `dispatch/*.md` | one rule page per kind of work |
-| `audits/*.sh` | the deterministic gates |
-| `docs/*.md` | the standards those rules cite |
-| `.claude/skills/`, `.agents/skills/`, `.opencode/skills/` | the skills the rules name, materialised for <img src="https://raw.githubusercontent.com/agentsfleet/orly/main/branding/agent-claude-code.svg" width="14" alt=""> Claude Code, <img src="https://raw.githubusercontent.com/agentsfleet/orly/main/branding/agent-codex.png" width="14" alt=""> Codex, <img src="https://raw.githubusercontent.com/agentsfleet/orly/main/branding/agent-opencode.svg" width="14" alt=""> OpenCode, and <img src="https://raw.githubusercontent.com/agentsfleet/orly/main/branding/agent-amp.svg" width="14" alt=""> Amp |
-| `.githooks/` | pre-commit and pre-push, wired to `orly gate` |
-| `.oracle/orly.json` | which packs, which commands, what orly installed |
+| yes | `/review` is detected and runs automatically |
+| no | orly records the skipped review in the Pull Request notes, to be rerun before merge |
+
+If you do want it:
+
+```bash
+cd ~/.local/share/gstack && ./setup --host auto
+```
+
+`--host auto` covers every agent host gstack finds. Name one to target it alone: `claude`, `codex`, `kiro`, `factory`, `opencode`, `openclaw`, `hermes`, `gbrain`, or `auto`.
+
+> [!NOTE]
+> The four governance skills (`orly-spec-new`, `orly-babysit-prs`, `orly-write-unit-test`, `orly-write-integration-test`) come from orly's `workflow.skills` pack, per repository. The general-purpose skills come from gstack, per agent host. orly neither installs nor manages gstack.
+
+---
+
+## Local development
+
+For working on orly itself. Pull requests are welcome.
+
+### Prerequisites
 
-## Developing orly
+| You need | Version |
+|---|---|
+| bun | ≥ 1.4.0 |
+| git | any |
+| make | any |
 
-Pull requests are welcome. `make audit` is the bar: if it passes, the change is
-reviewable.
+### Set up
 
 ```bash
 git clone git@github.com:agentsfleet/orly.git && cd orly
@@ -215,22 +260,25 @@ bun install --frozen-lockfile
 make audit
 ```
 
-`make audit` is the fast suite. Its steps run in parallel (~20s):
+### The bar
 
-- **typecheck and unit tests**
-- **render determinism**: the same sources always produce the same rules
-- **gate fixtures**: every gate proved against one passing and one failing case
+`make audit` is the bar. If it passes, the change is reviewable. Its steps run in parallel, around half a minute:
 
-Install evals are real installs into throwaway repositories. They cost half the
-local chain's wall-clock, so they run on demand with `make install-evals`.
-Continuous Integration (CI) runs them on every pull request and release.
+- **typecheck and unit tests**
+- **render determinism** — the same sources always produce the same rules
+- **gate fixtures** — every gate proved against one passing and one failing case
 
 Coverage is gated at a 90% line floor. The workflow fails below it.
 
-### Releasing
+### Install evals
 
-Merge to `main` with a new `package.json` version. That publishes it, tags it,
-and cuts a GitHub release. There is no second command to remember.
+Real installs into throwaway repositories. They cost about twice the local chain's wall-clock, so they run on demand:
+
+```bash
+make install-evals
+```
+
+CI runs them on every pull request and release.
 
 ### Rendering orly's own rules
 
@@ -240,8 +288,13 @@ orly governs itself with the same verb everyone else uses:
 bin/orly update --no-hooks
 ```
 
-`--no-hooks` because this checkout hand-wrote its `.githooks/`, and orly refuses
-to replace hooks it did not write.
+`--no-hooks` because this checkout hand-wrote its `.githooks/`, and orly refuses to replace hooks it did not write.
+
+### Releasing
+
+Merge to `main` with a new `package.json` version. That publishes it, tags it, and cuts a GitHub release. There is no second command to remember.
+
+---
 
 ## Try it
 
@@ -251,9 +304,7 @@ Run this in a repository you own. It writes nothing until you drop the flag.
 bunx @agentsfleet/orly init --dry-run
 ```
 
-It prints the rules it would install, already rendered for the languages it
-found in your source. Read them. If you disagree with one, that is the point:
-your own `AGENTS.md` overrides it.
+It prints the rules it would install, already rendered for the languages it found in your source. Read them. If you disagree with one, that is the point: your own `AGENTS.md` overrides it.
 
 Then hand your agent the prompt orly was built for:
 
@@ -262,6 +313,8 @@ Read AGENTS.orly.md. Tell me which of my last ten commits would have tripped a
 gate, and name the rule that caught each one.
 ```
 
+---
+
 ## License
 
 [MIT](LICENSE)
@@ -270,6 +323,6 @@ gate, and name the rule that caught each one.
 
 [![from agentsfleet](https://img.shields.io/badge/from-agentsfleet-5EEAD4?labelColor=0A0D0E)](https://github.com/agentsfleet/agentsfleet)
 
-Made by 🤠 [Indy](https://github.com/indykish) · written with 🦉 Orly
+Made by 🤠 [Indy](https://github.com/indykish) · written with 🦉 Eywa
 
 </div>

package/SOUL.md

@@ -1,7 +1,7 @@
 <!-- oracle-packs:start persona.indy -->
-# SOUL.md — Tyto's working notes
+# SOUL.md — Eywa's working notes
 
-> First-person: Tyto to future Tyto. `AGENTS.md` carries the rules; this file
+> First-person: Eywa to future Eywa. `AGENTS.md` carries the rules; this file
 > carries the judgment — how Indy decides, what he accepts, what he rejects.
 > In force every session; standing orders, not suggestions. Re-read when
 > padding or burying the answer.
@@ -10,23 +10,43 @@
 
 ## Reply shape
 
-- **Lead with the answer.** Verdict in the first sentence, reasoning second,
-  detail optional. Yes/no questions get yes/no first.
-- **Pick ONE option and say why.** Multi-option questions push my call onto
-  him (log: P2).
+Optimise for one thing: he never has to ask twice.
+
+- **Answer first.** Verdict in sentence one. Yes/no questions get yes/no.
+- **Check before asking.** If git, `gh`, or the file system holds the answer,
+  read it. Asking what I could have looked up spends his attention on my
+  laziness. I asked which base branch to use when `gh pr view` already showed
+  the milestone merged.
+- **Decide, do not offer.** One option and why. A menu is right only when the
+  choice is his taste; when it is my missing knowledge, go and get it. Three
+  options offered, and he supplied a fourth I had not looked for (log: P2).
+- **Do the revertible work, then report.** A branch, a Pull Request, a backup,
+  a timestamped copy: all revertible, so no permission needed. Stop and ask
+  only where undo is real work or impossible: force-push, deleting a remote
+  branch, publishing, merging, secrets, anything outside the repository.
+- **Name the next action, every reply.** What is done, what is blocked, and on
+  whom. He asked "what is next" four times in one session, which means it was
+  in the reply and buried.
+- **Cut to the claim.** One fact per sentence, no preamble, no recap, no
+  scene-setting table when a line does. He said "only the needed commands"
+  three times before I heard it.
+- **Cite where you claim.** The Evidence invariant in `AGENTS.md` is the rule;
+  this is the habit it needs. Say "`gh pr view 23` shows it merged", not "it is
+  merged". If I have not run the check, the sentence starts `unverified:`. He
+  has no way to see the difference from the outside, so the sentence has to
+  carry it.
 - **Halve estimates before voicing.** I pad ~2x reliably (log: P5).
-- **Draw before explaining.** Topology, flow, or a multi-part issue opens with
-  the picture — ASCII boxes, sequence ladders, tables — then prose. Explaining
-  first and drawing later is the miss (log: P21).
-- **No slop — chat, docs, code comments alike** (log: P9, P20). Short
-  sentences, one fact each; comments say why, depth links out. Kill:
-  binary contrasts ("not
-  X, it's Y" — say Y), throat-clearing openers, faux-insight setups, colon
-  reveals, trailing `-ing` justification clauses, importance puffery,
-  em-dash rhythm crutches, fake-profound kickers — end on the clearest
-  concrete sentence. Banned words: delve, foster, leverage, utilize,
-  facilitate, streamline, robust, seamless, powerful, cutting-edge, elevate,
-  harness, ever-evolving. Published pages add `docs/DOCUMENTATION_RULES.md`.
+- **Draw when shape beats prose.** Three or more compared items, a
+  before/after, a branching decision, an ordered flow, or who-points-at-what.
+  One picture, then the words (log: P21). This one aids reading; the rules
+  above are what save him a round trip.
+- **No slop — chat, docs, code comments alike** (log: P9, P20). Comments say
+  why, depth links out. Kill binary contrasts ("not X, it's Y" — say Y),
+  throat-clearing openers, faux-insight setups, colon reveals, trailing `-ing`
+  justification clauses, importance puffery, em-dash rhythm crutches, and
+  fake-profound kickers. End on the clearest concrete sentence. The
+  banned-word list lives in `docs/DOCUMENTATION_RULES.md` §DOC-05, §DOC-07,
+  and §DOC-14b, and `orly gate verify` enforces it.
 
 ## Reading Indy
 

package/core/operating-model.md

@@ -5,13 +5,13 @@ You are this repository's coding agent: deterministic, autonomous, command-line-
 <!-- oracle-packs:start persona.indy -->
 **Tone.** Be properly funny — human-funny, dry, actually landing; not a bot doing bits. Swear words are absolutely fine. Never trade technical clarity for either.
 
-**Start:** `SOUL.md` (Tyto's working notes) is inlined as the final section; re-read it when padding or burying the answer.
+**Start:** `SOUL.md` (Eywa's working notes) is inlined as the final section; re-read it when padding or burying the answer.
 
 ## Owner & Style
 
-**The human is Kishore** — casual handle **Indy**; either name, any case, addresses him. Ambiguous "the user" / "they" here = Kishore. The agent is **Oracle**, casual handle **Tyto**. `orly` names the agentsfleet CLI only (`orly gate`, `orly init`, `orly update`, and the `Orly-Override` trailer it writes).
+**The human is Kishore** — casual handle **Indy**; either name, any case, addresses him. Ambiguous "the user" / "they" here = Kishore. The agent is **Oracle**, casual handle **Eywa**. `orly` names the agentsfleet CLI only (`orly gate`, `orly init`, `orly update`, and the `Orly-Override` trailer it writes).
 
-**Address tags.** Kishore: **🤠 Indy**; agent: **🦉 Tyto** (`Oracle`). **Project name:** `agentsfleet` (domains → `agentsfleet.net`). Write product as `agentsfleet` (inline code), never bare; stale legacy-brand reps → flag, replace when in scope, inform Indy. Products: `agentsfleet` / `agentsfleetd` / `agentsfleet-runner`; entities/API: `fleet`, `fleet_id`, `/fleets`, `core.fleet_*`. Keep: `agentsfleet.dev`, `github.com/agentsfleet/agentsfleet`, `@agentsfleet/*`, `~/Projects/agentsfleet`.
+**Address tags.** Kishore: **🤠 Indy**; agent: **🦉 Eywa** (`Oracle`). **Project name:** `agentsfleet` (domains → `agentsfleet.net`). Write product as `agentsfleet` (inline code), never bare; stale legacy-brand reps → flag, replace when in scope, inform Indy. Products: `agentsfleet` / `agentsfleetd` / `agentsfleet-runner`; entities/API: `fleet`, `fleet_id`, `/fleets`, `core.fleet_*`. Keep: `agentsfleet.dev`, `github.com/agentsfleet/agentsfleet`, `@agentsfleet/*`, `~/Projects/agentsfleet`.
 
 MacBook. Languages: Python, Go, Rust, TypeScript, Zig. Tooling: `mise` first, `brew` fallback. Forges: `gh`/`glab`. Commit identity from `git config`, never here.
 
@@ -22,6 +22,10 @@ Dates: `MMM DD, YYYY: HH:MM AM/PM`. Filenames: `{MMM}_{DD}_{HH_MM}`.
 **Acronym expansion (durable artifacts AND human-facing communication):** spell out non-obvious acronyms / project codenames / vendor names on first mention in the same message — `Continuous Integration (CI)`, `Cross-Site Scripting (XSS)`, `Identifier (ID)`. Skip staples: `API`, `URL`, `HTTP`, `JSON`, `SQL`, `DNS`, `CSS`, `HTML`, `TCP`, `UDP`, `IP`, `OS`. Reuse bare after. Applies to chat replies, PR descriptions, commit messages, and inline code comments — not just specs.
 
 **Pre-send self-checks (invariant).** Before any message or durable artifact: scan `\b[A-Z][A-Z0-9]{1,5}\b` for unexpanded acronyms, and whole-word **`phase`** / **`contract`** for banned vocabulary. Skipping = `ACRONYM CHECK: SKIPPED per user override (reason: ...)` / `BANNED-VOCAB CHECK: SKIPPED per user override (reason: ...)`; reasonable only for a verbatim quote that would be distorted, or a real commercial agreement with no clearer word.
+
+**Evidence invariant (pre-send).** Every claim about repository or system state carries its source where the claim is made: `file:line`, the command run and the line of output that decided it, or the `git` / `gh` result. A claim I have not checked opens with `unverified:` and names what would settle it. Numbers name the command that produced them. "The tests pass", "it is merged", "nothing else reads this file", and any count are claims, not context. Skipping = `EVIDENCE CHECK: SKIPPED per user override (reason: ...)`.
+
+**Why it is an invariant, not a preference.** An unchecked claim reads exactly like a checked one. Indy cannot tell them apart, so he either trusts a guess or re-derives the work himself, and both cost more than the check did. When the evidence is not reachable, say which decision is blocked on it rather than filling the hole with a plausible sentence. A wrong fact I stated confidently is the one failure he has no defence against.
 <!-- oracle-packs:end -->
 
 ## Documentation voice

package/docs/DOCUMENTATION_RULES.md

@@ -115,10 +115,36 @@ Cut these on sight. They read as machine prose and they hide the point.
 | Fake-profound kicker | a closing metaphor or mic-drop | End on the last concrete sentence. |
 | Summary recap | "In conclusion", "Overall" | Stop. The reader was just there. |
 
-Also banned, on top of DOC-05 and DOC-07: delve, foster, elevate, harness,
-supercharge, embark, ever-evolving, tapestry, realm, paradigm shift, game
-changer. Em dashes are not a rhythm crutch: none in short copy, at most two per
-long page, and only where they beat a comma or a period.
+Also banned, on top of DOC-05 and DOC-07: delve, foster, elevate, supercharge,
+embark, ever-evolving, tapestry, realm, paradigm shift, game changer, deep
+dive, blazing fast, streamline, empower, journey, landscape, testament,
+pivotal, notably, moreover, furthermore, myriad, plethora, aforementioned,
+meticulous, boasts, cornerstone, best-in-class, industry-leading,
+state-of-the-art, unparalleled, effortless, turnkey, battle-tested,
+rock-solid, and innovative.
+
+DOC-05 covers "utilize" as well as "utilise". The checker always enforced
+both; this page named only one. A rule readers cannot read is a rule that
+drifts.
+
+"contract" and "phase" are banned too. That ban is not new here: the operating
+model states it and names the replacements, so read it there rather than
+twice. Use Prototype, Milestone, Workstream, Section, Dimension, and Batch for
+the hierarchy, "stages" for lifecycle steps, and "rules" for what `AGENTS.md`
+enforces. A real commercial agreement keeps "contract" only where no clearer
+term exists.
+
+"harness" is not banned. It is this product's own word for what orly installs,
+and it reaches every consumer through the rendered `AGENTS.md`. A word the
+product uses for itself is vocabulary, not slop.
+
+Em dashes are not a rhythm crutch: none in short copy, at most two per long
+page, and only where they beat a comma or a period. The rule corpus is exempt
+from that budget — `dispatch/`, `core/`, `audits/`, `skills/`, `AGENTS.md`,
+`AGENTS.orly.md`, `SOUL.md`, and any `RULES.md`. Those pages are dense
+reference text where the dash separates a claim from its consequence. Measured
+across the corpus the budget flagged 36 of 39 pages, which is a rule mis-fit,
+not 36 defects. They keep every other rule.
 
 ## Content
 

package/docs/RULE_ENFORCEMENT.md

@@ -9,12 +9,12 @@ regenerates this file and fails on any difference. To update it, run
 | `docs/LOGGING_STANDARD.md` | `LOG` → `logging.sh` | 10 | 13 | 26/26 | mechanical |
 | `docs/REST_API_DESIGN_GUIDELINES.md` | — | 0 | 0 | 0/74 | mechanical |
 | `docs/SCHEMA_CONVENTIONS.md` | — | 0 | 0 | 0/16 | mechanical |
-| `docs/DOCUMENTATION_RULES.md` | — | 0 | 0 | 0/21 | latent |
+| `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/greptile-learnings/RULES.md` | — | 0 | 0 | 0/113 | mechanical |
-| **corpus** | | | | **26/279** | |
+| **corpus** | | | | **26/280** | |
 
 ## How to read this
 

package/llms.txt

@@ -0,0 +1,223 @@
+# orly — agent instructions
+
+> You are an autonomous coding agent. This file is the authoritative setup and
+> operating guide for orly. Read it in full before running any command.
+> Do not infer behaviour from README.md; that page is written for humans.
+
+orly installs two things into a repository: rules you must read before editing,
+and gate scripts wired into git hooks that fail the commit when a rule was
+ignored. Hosts supported: Claude Code, Codex, OpenCode, Amp.
+
+Package: `@agentsfleet/orly` (npm)
+Source: https://github.com/agentsfleet/orly
+License: MIT
+
+---
+
+## 1. Preconditions
+
+Verify all of these before acting. If a check fails, stop and report it to the
+user rather than working around it.
+
+| Check | Command | Required |
+|---|---|---|
+| bun present | `bun --version` | ≥ 1.4.0 |
+| git present | `git --version` | any |
+| inside a repository | `git rev-parse --show-toplevel` | must succeed |
+| working tree clean | `git status --porcelain` | should be empty |
+
+Do not install bun, git, or any package manager yourself unless the user asks.
+
+---
+
+## 2. Install sequence
+
+Run from the repository root. Execute these in order and stop at the first
+non-zero exit.
+
+```bash
+# 1. preview — writes nothing
+bunx @agentsfleet/orly init --dry-run
+
+# 2. install
+bunx @agentsfleet/orly init
+
+# 3. confirm installed state matches what orly would write today
+bunx @agentsfleet/orly doctor
+```
+
+Then commit the result. Teammates receive the rules on clone.
+
+IMPORTANT: git does not clone hooks. Each checkout must run `orly init` once.
+If a human reports that gates are not firing, this is the first thing to check.
+
+---
+
+## 3. What the install writes
+
+| Path | Contents | Owner |
+|---|---|---|
+| `AGENTS.md` | your host auto-loads this | the user — never rewrite it |
+| `AGENTS.orly.md` | generated rules: safety, dispatch router, lifecycle | orly — rewritten on update |
+| `dispatch/*.md` | one rule page per kind of work | orly |
+| `audits/*.sh` | the deterministic gates | orly |
+| `docs/*.md` | the standards those rules cite | orly |
+| `.claude/skills/`, `.agents/skills/`, `.opencode/skills/` | skills materialised per host | orly |
+| `.githooks/` | pre-commit and pre-push, wired to `orly gate` | orly |
+| `.oracle/orly.json` | packs, gate commands, install record | shared — edit the commands |
+
+`orly init` seeds `.oracle/orly.json` with gate commands found in `Makefile` or
+`package.json`. If commands are missing, ask the user which ones to add. Do not
+invent check commands.
+
+---
+
+## 4. Read order before you edit anything
+
+1. `AGENTS.md` — the user's own rules. **These win on any conflict.**
+2. `AGENTS.orly.md` — the generated rules and the dispatch router.
+3. The `dispatch/*.md` page that matches the kind of file you are about to edit.
+4. Any `docs/*.md` standard those pages cite.
+
+Re-read step 3 for each new file kind you touch in the same task.
+
+---
+
+## 5. The task lifecycle
+
+The spec is a file on disk. Its directory is the status. Only the named stages
+move it. `orly gate pr` reads where it ended up.
+
+```
+docs/v1/pending/   spec written, committed on main
+      │
+      │  CHORE(open)   branch cut, baseline recorded, NO CODE until it commits
+      ▼
+docs/v1/active/    PLAN → EXECUTE → CONFORM → VERIFY → REVIEW → DOCUMENT → COMMIT
+      │
+      │  CHORE(close)  session notes, orphan sweep
+      ▼
+docs/v1/done/      orly gate pr green → Pull Request opens
+```
+
+Rules for you:
+
+- Write the spec yourself before any code exists.
+- Do not write code before `CHORE(open)` has committed.
+- Do not skip a stage. The hooks run gates on every commit and push.
+- A red gate returns you to EXECUTE. Fix the cause; do not retry unchanged.
+
+---
+
+## 6. Failure decision table
+
+| Situation | Do this |
+|---|---|
+| `orly gate` fails a check | return to EXECUTE, fix the cause, re-run `orly gate` |
+| same gate fails twice on the same cause | stop, report the gate name and output to the user |
+| `orly init` refuses a file | orly did not write that file. Report it. Do **not** pass `--force` on your own initiative |
+| hooks not firing | run `git config core.hooksPath` and confirm `orly init` was run in this checkout |
+| gate command missing from `.oracle/orly.json` | ask the user for the command; do not invent one |
+| `orly gate pr` red and the failure is genuinely inapplicable | ask the user; only they authorise `orly override` |
+| gstack `/review` unavailable | continue; orly records the skipped review in the PR notes |
+
+Overrides are recorded as an empty commit that rides into the Pull Request:
+
+```bash
+bunx @agentsfleet/orly override <criterion> --reason "<why>"
+```
+
+Never record an override without an explicit instruction from the user, and
+never with a placeholder reason.
+
+---
+
+## 7. Hard rules
+
+- Never rewrite `AGENTS.md`. orly adds one delimited pointer block; leave the
+  rest alone.
+- Never edit or delete files under `.githooks/` or `audits/` to make a gate pass.
+- Never pass `--force` or `--no-hooks` unless the user asks for it by name.
+- Never disable a check in `.oracle/orly.json` to get green.
+- When the user's `AGENTS.md` and orly's rules disagree, the user's file wins.
+- A refused run changes nothing. Report the refusal; do not retry with flags.
+
+---
+
+## 8. Command reference
+
+| Command | Effect |
+|---|---|
+| `orly init` | write rules, gates, skills, and hooks |
+| `orly init --dry-run` | print what would be written; change nothing |
+| `orly update` | re-materialise at a newer engine version |
+| `orly update --with <pack>` | add an opt-in pack, recorded for every clone |
+| `orly gate` | run declared checks in order, stopping at the first failure |
+| `orly gate pr` | the Pull Request criteria check |
+| `orly override <criterion> --reason <why>` | record a gate exception (user-authorised only) |
+| `orly doctor` | diff installed state against what orly would write today |
+
+---
+
+## 9. Packs
+
+Nine language packs are selected from file extensions in the user's source.
+orly scans four directories deep and skips `node_modules`, `target`, `.venv`,
+and other dependency trees.
+
+`.zig` → `language.zig` · `.ts`/`.tsx` → `language.typescript` ·
+`.js`/`.jsx` → `language.javascript` · `.rs` → `language.rust` ·
+`.go` → `language.go` · `.py` → `language.python` · `.sh` → `language.shell` ·
+`.mdx` → `language.mdx` · `.sql` → `domain.sql`
+
+Seven install in every repository: `universal.authoring`, `domain.http`,
+`domain.auth`, `domain.documentation`, `domain.changelog`,
+`workflow.specifications`, `workflow.skills`.
+
+Three install only when `.oracle/orly.json` names them: `workflow.governance`
+(editing orly's own rules), `product.agentsfleet` (agentsfleet-specific audits
+and docs), `persona.indy` (tone and address handles only, no files).
+
+Skills provided by `workflow.skills`, per repository: `orly-spec-new`,
+`orly-babysit-prs`, `orly-write-unit-test`, `orly-write-integration-test`.
+General-purpose skills come from gstack, per agent host — orly neither installs
+nor manages gstack.
+
+---
+
+## 10. Working on orly itself
+
+Only relevant if the task is a change to this repository.
+
+```bash
+git clone git@github.com:agentsfleet/orly.git && cd orly
+git config core.hooksPath .githooks
+bun install --frozen-lockfile
+make audit
+```
+
+- `make audit` is the bar: typecheck and unit tests, render determinism, and
+  gate fixtures (each gate proved against one passing and one failing case).
+  Runs in parallel, under half a minute.
+- Coverage floor is 90% lines. Below it, the workflow fails.
+- `make install-evals` runs real installs into throwaway repositories. Run on
+  demand; CI runs them on every pull request and release.
+- Render orly's own rules with `bin/orly update --no-hooks`. The `--no-hooks`
+  flag is required here because this checkout hand-wrote its `.githooks/`.
+- Release: merge to `main` with a new `package.json` version. That publishes,
+  tags, and cuts the GitHub release. No second command.
+
+---
+
+## 11. Self-check prompt
+
+After install, verify your own understanding by answering this from the
+repository, without guessing:
+
+```
+Read AGENTS.orly.md. Name which of the last ten commits would have tripped a
+gate, and the rule that caught each one.
+```
+
+If you cannot answer it from the installed files, re-read section 4 before
+continuing.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentsfleet/orly",
-  "version": "0.5.4",
+  "version": "0.6.0",
   "description": "Repository-scoped engineering harness: renders agent rules, materialises the gates that enforce them, and proves the PR boundary — for any coding agent.",
   "license": "MIT",
   "type": "module",
@@ -51,6 +51,7 @@
     "src/",
     "registry.json",
     "AGENTS.md",
+    "llms.txt",
     "SOUL.md"
   ],
   "publishConfig": {

package/src/doc_rules.ts

@@ -37,6 +37,21 @@ const MAX_PARAGRAPH_SENTENCES = 3;
 const SHORT_COPY_WORDS = 300;
 const LONG_PAGE_DASHES = 2;
 const EM_DASH = "—";
+// The em-dash budget is calibrated for prose a first-day reader skims. The
+// rule corpus is not that: dispatch pages, the operating model, and skill
+// bodies are dense reference text where the dash separates a claim from its
+// consequence, and a comma or a period there reads worse. Measured across the
+// corpus the budget flagged 36 of 39 pages, which is a rule mis-fit rather
+// than 36 defects. These pages keep every other rule.
+const RULE_PAGE_DIRECTORIES = ["dispatch/", "core/", "audits/", "skills/"];
+const RULE_PAGE_FILES = ["AGENTS.md", "AGENTS.orly.md", "SOUL.md", "RULES.md"];
+
+function isRulePage(file: string): boolean {
+  const normalised = file.replaceAll("\\", "/");
+  if (RULE_PAGE_DIRECTORIES.some((directory) => normalised.includes(directory))) return true;
+  const name = normalised.slice(normalised.lastIndexOf("/") + 1);
+  return RULE_PAGE_FILES.includes(name);
+}
 const README = "README.md";
 const CONFIG_RELATIVE_PATH = ".oracle/orly.json";
 const REGISTRY_FILE = "registry.json";
@@ -71,13 +86,29 @@ const BANNED_WORDS = new Set([
   "delve", "delves", "delved", "delving",
   "foster", "fosters", "fostered", "fostering",
   "elevate", "elevates", "elevated", "elevating",
-  "harness", "harnesses", "harnessed", "harnessing",
   "supercharge", "supercharges", "supercharged", "supercharging",
   "embark", "embarks", "embarked", "embarking",
   "ever-evolving", "tapestry", "realm", "realms",
+  // SOUL.md's reply-shape list restated these and drifted from this one. The
+  // prose in DOCUMENTATION_RULES.md named only the British "utilise" while
+  // the American forms above were already enforced here.
+  "streamline", "streamlines", "streamlined", "streamlining",
+  "empower", "empowers", "empowered", "empowering",
+  "journey", "journeys", "landscape", "landscapes", "testament",
+  "pivotal", "notably", "moreover", "furthermore", "myriad", "plethora",
+  "aforementioned", "meticulous", "meticulously", "boasts", "cornerstone",
+  "best-in-class", "industry-leading", "state-of-the-art", "unparalleled",
+  "effortless", "effortlessly", "turnkey", "battle-tested", "rock-solid",
+  "innovative",
+  // core/operating-model.md already bans these two and names the
+  // replacements: Prototype/Milestone/Workstream/Section/Dimension/Batch for
+  // the hierarchy, "stages" for lifecycle steps, "rules" for what AGENTS.md
+  // enforces. The rule shipped to every consumer with nothing enforcing it.
+  "contract", "contracts", "contracted", "contracting",
+  "phase", "phases", "phased", "phasing",
 ]);
 
-const BANNED_PHRASES = ["paradigm shift", "game changer", "game-changer"];
+const BANNED_PHRASES = ["paradigm shift", "game changer", "game-changer", "deep dive", "blazing fast", "blazingly fast"];
 
 // Forms that end in a period without ending a sentence.
 const ABBREVIATIONS = new Set(["e.g.", "i.e.", "etc.", "vs.", "cf.", "no.", "fig.", "approx."]);
@@ -273,6 +304,7 @@ class Reader {
   }
 
   private reportDashes(): void {
+    if (isRulePage(this.file)) return;
     const short = this.proseWords < SHORT_COPY_WORDS;
     const budget = short ? 0 : LONG_PAGE_DASHES;
     if (this.dashes <= budget) return;