@agentsfleet/orly 0.5.2 → 0.5.4

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` (Orly's working notes) is inlined as the final section; re-read it when padding or burying the answer.
+**Start:** `SOUL.md` (Tyto'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 **Orly**. **Name collision:** lowercase `orly` is always the CLI (`orly gate`, the `Orly-Override` trailer it writes); capitalised **Orly** is always you.
+**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).
 
-**Address tags.** Kishore: **🤠 Indy**; agent: **🦉 Orly** (`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: **🦉 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`.
 
 MacBook. Languages: Python, Go, Rust, TypeScript, Zig. Tooling: `mise` first, `brew` fallback. Forges: `gh`/`glab`. Commit identity from `git config`, never here.
 
@@ -75,7 +75,7 @@ Auto-memory is **disabled** (`autoMemoryEnabled: false` + `CLAUDE_CODE_DISABLE_A
 ### Operational defaults
 
 - Workspace `~/Projects`. `gh`/`glab` not browsers. `trash` not `rm`. Conventional Commits. Process decisions → repo docs, not chat. "Make a note" → update `AGENTS.md`/repo docs.
-- **Symlinked dotfiles edits.** File `readlink`-resolving under `~/Projects/dotfiles/` is a dotfiles edit. Detect via `readlink` BEFORE editing. After: `cd ~/Projects/dotfiles && git add <files> && git commit && git push origin master`. Never leave uncommitted.
+- **Symlinked edits land in the repository that owns the file.** A file whose `readlink` resolves outside this checkout — into a dotfiles or config repository — is an edit to *that* repository, not this one. Detect via `readlink` BEFORE editing. After: `cd` to the resolved repository, `git add <files> && git commit && git push` on its default branch. Never leave uncommitted.
 - **Docs-repo edits on own branch.** `~/Projects/docs/` is shared across milestones: check `git status` first; from `main` (checkout or worktree off `main`) commit on `chore/m{N}-{slug}-changelog`; recovery = stash, re-apply on a fresh branch.
 - Other dotfiles (`.zshrc`/`.gitconfig`/etc.): timestamped backup; minimal edits.
 - Before commit/push: `gitleaks` must pass.
@@ -241,14 +241,14 @@ Required when spec involved — after last COMMIT, before PR. Also runs when par
 
 ---
 
-# SOUL.md — Orly's working notes
+# SOUL.md — Tyto's working notes
 
-> First-person: Orly to future Orly. `AGENTS.md` carries the rules; this file
+> First-person: Tyto to future Tyto. `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.
-> Evidence: `~/Projects/dotfiles/SOUL_LOG.md` — every `(log: Pn)` cite
-> resolves there, on demand.
+> Evidence: `SOUL_LOG.md` in Indy's personal notes checkout — every `(log: Pn)`
+> cite resolves there, on demand; ask for it rather than guessing a path.
 
 ## Reply shape
 

package/README.md

@@ -39,20 +39,6 @@ Works with Claude Code, Codex, OpenCode, and Amp.
 | 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 |
 
-### gstack
-
-[gstack](https://github.com/garrytan/gstack) is **optional**. orly does not
-require it to install or run.
-
-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.
-
-**Bottom line:** orly works without gstack. Installing
-[gstack](https://github.com/garrytan/gstack) gives you the automated `/review`
-step.
-
 ```bash
 bunx @agentsfleet/orly init
 ```
@@ -71,6 +57,36 @@ orly init
 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.
 
+## gstack (optional)
+
+[gstack](https://github.com/garrytan/gstack) is **optional**. orly does not
+require it to install or run.
+
+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.
+
+**Bottom line:** orly works without gstack. Installing
+[gstack](https://github.com/garrytan/gstack) gives you the automated `/review`
+step.
+
+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.
+
+```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`.
+
 ## What happens when you use it
 
 `orly init` is the setup. This is the loop you live in, one task from prompt

package/SOUL.md

@@ -1,12 +1,12 @@
 <!-- oracle-packs:start persona.indy -->
-# SOUL.md — Orly's working notes
+# SOUL.md — Tyto's working notes
 
-> First-person: Orly to future Orly. `AGENTS.md` carries the rules; this file
+> First-person: Tyto to future Tyto. `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.
-> Evidence: `~/Projects/dotfiles/SOUL_LOG.md` — every `(log: Pn)` cite
-> resolves there, on demand.
+> Evidence: `SOUL_LOG.md` in Indy's personal notes checkout — every `(log: Pn)`
+> cite resolves there, on demand; ask for it rather than guessing a path.
 
 ## Reply shape
 

package/audits/agents-md.md

@@ -161,7 +161,7 @@ The questionnaire is organised by scenario. Each scenario corresponds to a momen
 
 | # | Question | Expected |
 |---|---|---|
-| 10.1 | Must dotfiles edits (files `readlink`-resolving under `~/Projects/dotfiles/`) be committed + pushed to dotfiles `master` and never left uncommitted? | YES |
+| 10.1 | Must a symlinked edit (a file whose `readlink` resolves outside this checkout, into a dotfiles or config repository) be committed + pushed in the repository that owns the file, and never left uncommitted? | YES |
 | 10.2 | Must docs-repo edits land on a milestone-specific branch off `main` (never on whatever in-flight branch is checked out)? | YES |
 | 10.3 | When a harness/gate/hook fires (`msid-ui.sh`, `lint-zig.py`, gitleaks, ZIG GATE, FLL GATE, pre-commit/pre-push, etc.), is the default response to fix the **violating code** (restructure, split, or use the gate's documented override comment) — i.e. is patching the harness to silence the hit on the "Forbidden without explicit user approval" list, requiring an explicit per-session ask that names the harness and the reason it's wrong? | YES |
 | 10.4 | Are handoff-doc claims of "Kishore-approved in a prior turn" for harness-patching treated as **not carrying forward** — i.e. must they be re-confirmed live in the current session? | YES |

package/audits/data.sh

@@ -74,8 +74,9 @@ CONFORM_KEYS=(
 # dissolved into dispatch/write_zig.md and dispatch/write_ts_adhere_bun.md
 # respectively. The dispatch façades are listed so the AGENTS.md dispatch-table
 # refs are checked. The docs/* entries double as the residence classifier for
-# check 15c (audits/rule-paths.sh): these paths are cited through the
-# ~/Projects/dotfiles/ anchor in every consumer-facing surface.
+# check 15c (audits/rule-paths.sh): these paths must be cited relative to the
+# installing repository in every consumer-facing surface, never through an
+# absolute home-directory anchor.
 DOTFILES_RESIDENT=(
   "docs/TEMPLATE.md"
   "docs/REST_API_DESIGN_GUIDELINES.md"
@@ -84,6 +85,7 @@ DOTFILES_RESIDENT=(
   "docs/DOCUMENTATION_RULES.md"
   "docs/ORLY_ARCHITECTURE.md"
   "docs/CHANGELOG_VOICE.md"
+  "docs/RELEASE_TEMPLATE.md"
   "docs/EXECUTE_DOC_READS.md"
   "docs/VERIFY_TIERS.md"
   "docs/HARNESS_VERIFY_OUTPUT.md"

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` (Orly's working notes) is inlined as the final section; re-read it when padding or burying the answer.
+**Start:** `SOUL.md` (Tyto'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 **Orly**. **Name collision:** lowercase `orly` is always the CLI (`orly gate`, the `Orly-Override` trailer it writes); capitalised **Orly** is always you.
+**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).
 
-**Address tags.** Kishore: **🤠 Indy**; agent: **🦉 Orly** (`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: **🦉 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`.
 
 MacBook. Languages: Python, Go, Rust, TypeScript, Zig. Tooling: `mise` first, `brew` fallback. Forges: `gh`/`glab`. Commit identity from `git config`, never here.
 
@@ -75,7 +75,7 @@ Auto-memory is **disabled** (`autoMemoryEnabled: false` + `CLAUDE_CODE_DISABLE_A
 ### Operational defaults
 
 - Workspace `~/Projects`. `gh`/`glab` not browsers. `trash` not `rm`. Conventional Commits. Process decisions → repo docs, not chat. "Make a note" → update `AGENTS.md`/repo docs.
-- **Symlinked dotfiles edits.** File `readlink`-resolving under `~/Projects/dotfiles/` is a dotfiles edit. Detect via `readlink` BEFORE editing. After: `cd ~/Projects/dotfiles && git add <files> && git commit && git push origin master`. Never leave uncommitted. <!-- oracle-packs:persona.indy -->
+- **Symlinked edits land in the repository that owns the file.** A file whose `readlink` resolves outside this checkout — into a dotfiles or config repository — is an edit to *that* repository, not this one. Detect via `readlink` BEFORE editing. After: `cd` to the resolved repository, `git add <files> && git commit && git push` on its default branch. Never leave uncommitted. <!-- oracle-packs:persona.indy -->
 - **Docs-repo edits on own branch.** `~/Projects/docs/` is shared across milestones: check `git status` first; from `main` (checkout or worktree off `main`) commit on `chore/m{N}-{slug}-changelog`; recovery = stash, re-apply on a fresh branch.
 - Other dotfiles (`.zshrc`/`.gitconfig`/etc.): timestamped backup; minimal edits. <!-- oracle-packs:persona.indy -->
 - Before commit/push: `gitleaks` must pass.

package/dispatch/edit_rules.md

@@ -4,7 +4,7 @@ Read this file before editing Oracle's operating model, rule registry, packs,
 generated instructions, dispatch pages, audits, or governance hooks.
 
 The canonical propagation design lives in
-`~/Projects/dotfiles/docs/ORLY_ARCHITECTURE.md`.
+[`docs/ORLY_ARCHITECTURE.md`](../docs/ORLY_ARCHITECTURE.md).
 The deterministic checker is `make audit`. The comprehension questionnaire is
 [`audits/agents-md.md`](../audits/agents-md.md).
 

package/dispatch/lifecycle.md

@@ -35,22 +35,25 @@ into the tree; on 🟠 run `provision-env-1password`, re-link. Post-merge:
 
 **agentsfleet CHORE(close) paths:** the `<Update>` lands in
 `~/Projects/docs/changelog.mdx` (template + version-bump matrix:
-`skills/release-template.md` in the governance checkout — re-source each
-release, never paraphrase). Version sync: `VERSION` touched → `make
+`docs/RELEASE_TEMPLATE.md` in this repository — re-source each release, never
+paraphrase). Version sync: `VERSION` touched → `make
 sync-version`; commit propagated `build.zig.zon` / `agentsfleet/package.json` /
 `agentsfleet/src/cli.js`; `make check-version` passes.
 
-**dotfiles takes NO worktree — feature branches in the main checkout.** Every
-agent-home symlink and every consumer's `ORLY_ROOT` resolves to
-`~/Projects/dotfiles`; a linked worktree's `.git` is a *file*, and the audit
-chain the hooks run spawns git against other directories. Under a hook that
-combination corrupted the real index and flipped `core.bare` (Aug 16, 2026).
-So: `git checkout -b feat/mNN-name` in `~/Projects/dotfiles` itself, and
-`orly update` always renders the one true root. One stream at a time —
-a second concurrent agent coordinates in-session rather than forking a tree.
-This is the dotfiles exception; product repos keep the worktree recipe above.
 <!-- oracle-packs:end -->
 
+**A governance/rules repository takes NO linked worktree — cut feature branches
+in its main checkout.** This applies to whichever repository owns the rules you
+are editing (the orly pack source, a dotfiles checkout, any repo whose own hooks
+run the governance audit chain). A linked worktree's `.git` is a *file*, and that
+audit chain spawns git against other directories; under a hook the combination
+corrupted the real index and flipped `core.bare` (Aug 16, 2026). So:
+`git checkout -b feat/mNN-name` in the rules repository's main checkout, and let
+`orly update` re-materialise consumers from there. One stream at a time — a
+second concurrent agent coordinates in-session rather than forking a tree.
+This is the governance-repo exception; product repos still create the worktree
+at CHORE(open).
+
 **Mid-stream spec → ask before hydrating (default: same tree).** A spec created
 inside an active worktree → ask the user before spinning up a second one. Lean
 same tree: a second tree fragments the outcome and adds a PR to babysit.

package/dispatch/write_changelog.md

@@ -58,7 +58,7 @@ If the change is internal-only, emit instead:
 ## Family
 
 - `docs/CHANGELOG_VOICE.md` — the canonical Mintlify-style voice rules (deep reference).
-- `skills/release-template.md` — release template + version-bump matrix; re-source
+- `docs/RELEASE_TEMPLATE.md` — release template + version-bump matrix; re-source
   each release, never paraphrase.
 - `verify` — runs before CHORE(close); a changelog claim must be backed by the
   verification that dispatch reports.

package/docs/DOCUMENTATION_RULES.md

@@ -4,14 +4,16 @@
 > any narrower guide such as `CHANGELOG_VOICE.md` or before editing documentation
 > about the dispatch model.
 
-These rules govern customer-facing `agentsfleet` documentation. They keep pages
+These rules govern any documentation orly writes or renders. They keep pages
 short, accurate, and usable by a first-day reader. Compliance is binary. A
 rejection cites the Documentation (DOC) rule identifier that failed.
 
 ## Scope and precedence
 
-- **DOC-S1 — Published pages.** A standalone Markdown JSX (MDX) file listed in
-  `docs.json` follows every applicable rule in this document.
+- **DOC-S1 — Any page orly writes.** Every Markdown or Markdown JSX (MDX) file
+  orly writes, renders, or materialises follows every applicable rule in this
+  document. A published page listed in `docs.json`, a rule page installed into
+  a repository, a skill page, and a `README.md` are all in scope.
 - **DOC-S2 — Generated API pages.** OpenAPI source follows the reference-page
   intent through summaries, descriptions, parameters, examples, responses, and
   stable errors. Generated pages do not need MDX front matter.
@@ -26,6 +28,9 @@ rejection cites the Documentation (DOC) rule identifier that failed.
 - **DOC-S6 — Source wins.** Runtime code is the source of truth. OpenAPI and the
   command-line interface follow runtime behavior. Published pages follow all
   three.
+- **DOC-S7 — Records stay as written.** A historical record keeps its original
+  wording. Spec records under `docs/v1/` and closed changelog entries are read,
+  never rewritten to a later rule.
 
 ## Required front matter
 

package/docs/LOGGING_STANDARD.md

@@ -15,7 +15,7 @@ Triggers on every `Edit`/`Write` that adds, removes, or changes a log emit:
 Out of scope (explicitly):
 
 - Test-only diagnostic prints inside `*_test.zig`, `*.test.ts`, `*.spec.ts`. Tests render to humans, not collectors; gates ignore.
-- Build/release scripts in `~/Projects/dotfiles/`, `audits/release-*` — toolchain output, not application logs.
+- Build/release scripts — the harness's own `audits/*`, `audits/release-*`, and any governance-repo tooling — toolchain output, not application logs.
 - Generated framework noise (Next.js startup banners, Bun runtime warnings) — out of our control.
 
 The **LOGGING GATE** (`dispatch/write_any.md`, Logging Gate) sits on top of this file — it fires in addition to the language-level rules in `dispatch/write_zig.md` and `dispatch/write_ts_adhere_bun.md`, not instead of them.

package/docs/ORLY_ARCHITECTURE.md

@@ -48,8 +48,8 @@ scripts resolved live from this checkout via `$ORLY_ROOT`.
 
 That traded the storage cost for a distribution cost undiscovered until a
 second engineer tried to install the harness without this checkout present —
-the symlink and `$ORLY_ROOT` both require a copy of `~/Projects/dotfiles` at a
-known path, which is exactly what a fresh machine, a Continuous Integration
+the symlink and `$ORLY_ROOT` both require a copy of the governance checkout at
+a known absolute path, which is exactly what a fresh machine, a Continuous Integration
 (CI) runner, or a remote fleet container does not have. `orly init` (M03)
 restores storage, but not the failure mode that got it removed: `orly update`
 turns a rule change into one command per repository instead of the manual

package/docs/RELEASE_TEMPLATE.md

@@ -0,0 +1,46 @@
+# Release doc template — `changelog.mdx` `<Update>` block
+
+Source of truth: `~/Projects/docs/changelog.mdx`. New `<Update>` blocks go at the top, after the leading `<Tip>`/`<Note>`. Labels are date-only — never a semver prefix. `VERSION` is the single source of truth for binary version (binaries via `make sync-version` propagate to `build.zig.zon`, `agentsfleet/package.json`, `agentsfleet/src/cli.js`); changelog stays chronological. Decoupled by design — avoids parallel-branch collisions.
+
+## Block template
+
+```mdx
+<Update label="MMM DD, YYYY" tags={["What's new" | "Breaking" | "Bug fixes", "API" | "CLI" | "UI" | "Security" | "Performance" | "Integrations" | "Observability" | "Internal", ...]}>
+  ## {Short user-facing feature title — no milestone IDs, no codenames}
+
+  {One paragraph from the user's perspective. No workstream numbers, branch names, RULE references.}
+
+  ## Upgrading
+  {Breaking changes only. ALWAYS first when present. Each break: explicit migration step + whether CLI+server must upgrade together.}
+
+  ## What's new
+  {New capabilities — what a user/operator can now do.}
+
+  ## API reference
+  {New/changed endpoints, shapes, error codes. Include JSON/route examples. Omit if no API change.}
+
+  ## Bug fixes
+  {User-visible bugs fixed — observed behavior before/after. Omit if none.}
+
+  ## CLI
+  {`agentsfleet` additions or shape changes. Omit if none.}
+</Update>
+```
+
+## Hard rules
+
+- Label is `MMM DD, YYYY` exactly — no `vX.Y.Z —` prefix, no release name. Two releases on the same date → one merged `<Update>` block OR a disambiguator inside the title (`## Morning release — …`, `## Follow-up — …`); the label stays the date.
+- Section order is fixed: Upgrading → What's new → API reference → Bug fixes → CLI. Omit empty sections; never leave empty headings.
+- No milestone/workstream IDs, branch names, spec filenames, or `RULE XXX` references in the body.
+- User-centric verbs ("we added", "X now does Y"), not implementation prose.
+- Every breaking change appears under `Upgrading` with a migration step, even if also mentioned elsewhere.
+- Body copy may reference a past entry by date (`"…that shipped on Apr 22, 2026"`); do not reference past releases by semver (`"shipped in v0.27.0"`) — that drags the two timelines back together.
+
+## Version bumps (`VERSION`, not the changelog label)
+
+- Feature milestone → minor (`0.7.0` → `0.8.0`).
+- Bug fix → patch.
+- Pre-v1.0 breaking → minor (semver 0.x carve-out); call out under Upgrading.
+- Post-v1.0 breaking → major.
+- Internal-only refactor: terse `<Update>` with `tags={["Internal", ...]}`, one-paragraph summary, skip section structure. Prefer folding into the next user-visible release.
+- Parallel branches bumping `VERSION` do not coordinate through the changelog — whichever lands second rebases `VERSION` and re-runs `make sync-version`.

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/20 | latent |
+| `docs/DOCUMENTATION_RULES.md` | — | 0 | 0 | 0/21 | 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/278** | |
+| **corpus** | | | | **26/279** | |
 
 ## How to read this
 

package/fixtures/doc-slop.md

@@ -0,0 +1,29 @@
+# Slop fixture
+
+This page is the fail fixture for the documentation-language check. Every
+violation below is deliberate, and the test asserts the check finds each one.
+
+We leverage a robust and seamless pipeline to execute the request, and the
+result is a powerful experience that lets you delve into a realm of insight
+without ever once thinking about the mechanics of the thing you are using.
+This sentence exists to be long. This one too. And a fourth, to break DOC-03.
+
+An em dash — in short copy — is over budget by itself.
+
+### Skipped level
+
+The heading above jumps from H1 to H3.
+
+# Second level-one heading
+
+`make harness-verify` and `provision-env-1password` are command names, not
+banned words. The check must leave both alone.
+
+| leverage | robust | seamless |
+|---|---|---|
+| a table cell is exempt | so is this | and this |
+
+```bash
+# a fenced block is exempt: execute the robust and seamless pipeline
+orly gate verify
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentsfleet/orly",
-  "version": "0.5.2",
+  "version": "0.5.4",
   "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",

package/registry.json

@@ -228,6 +228,10 @@
         {
           "source": "docs/CHANGELOG_VOICE.md",
           "target": "docs/CHANGELOG_VOICE.md"
+        },
+        {
+          "source": "docs/RELEASE_TEMPLATE.md",
+          "target": "docs/RELEASE_TEMPLATE.md"
         }
       ]
     },

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

@@ -32,7 +32,6 @@ Before doing anything else in a polling cycle, read the triage helper:
 
 ```bash
 GREPTILE_TRIAGE="$HOME/.local/share/gstack/review/greptile-triage.md"
-[ -r "$GREPTILE_TRIAGE" ] || GREPTILE_TRIAGE="$HOME/Projects/dotfiles/.unified-skills/review/greptile-triage.md"
 [ -r "$GREPTILE_TRIAGE" ] || { echo "BABYSIT: greptile-triage.md missing — abort cycle"; exit 1; }
 ```
 
@@ -312,15 +311,14 @@ BABYSIT REPORT — <PR|MR> #<n> @ <SHA>
 ## References
 
 - `~/.local/share/gstack/review/greptile-triage.md` — fetch / classify /
-  reply / suppressions / history-write mechanics. Also at
-  `~/Projects/dotfiles/.unified-skills/review/greptile-triage.md`.
+  reply / suppressions / history-write mechanics (installed by gstack).
 - `$HOME/.gstack/projects/<slug>/greptile-history.md` — per-project
   history; drives Suppressions Check.
 - `$HOME/.gstack/greptile-history.md` — global aggregate.
 - `docs/greptile-learnings/RULES.md` — project-level named rules
   (durable principles). New rule added here only when the finding
   generalizes; per-incident rows go to greptile-history.md.
-- `~/Projects/dotfiles/AGENTS.md` — CHORE(close) skill chain step 4
-  cites this skill.
+- this repository's `AGENTS.md` / `AGENTS.orly.md` — CHORE(close) skill
+  chain step 4 cites this skill.
 - `gh api` docs: https://cli.github.com/manual/gh_api
 - `glab api` docs: https://gitlab.com/gitlab-org/cli (`glab api --help`)

package/src/criteria.ts

@@ -8,6 +8,7 @@ import {
   openQuestions, productClarity, specBaseline, specDeferrals, specDimensions,
   specGate, specMoved, specOrdering,
 } from "./criteria_spec";
+import { documentationSurfaces, scanSurfaces } from "./doc_rules";
 import { isObject, JsonObject, objectValue, OrlyError, RulesModel } from "./model";
 import { readConfigSync, RepoConfig } from "./config";
 import { classifyBranch, SurfaceReport } from "./surfaces";
@@ -30,6 +31,10 @@ const GIT_TREE = "git.tree";
 const GIT_PUSHED = "git.pushed";
 const REPO_CONFIG = "repo.config";
 const DOCS_UPDATED = "docs.updated";
+const DOCS_LANGUAGE = "docs.language";
+// How many findings a report names before it stops listing them. A criterion
+// line is a summary, not a linter dump.
+const NAMED_FINDINGS = 3;
 
 const FAST_TIER = "fast";
 const SLOW_TIER = "slow";
@@ -44,7 +49,7 @@ const SLOW_COMMANDS = ["verify.integration", "verify.memory"];
 // pr = can this ship (whole-branch checks + the slow suites).
 export function criteriaFor(gate: string, context: CriterionContext): Criterion[] {
   if (gate === "work") return [gitBranch(), gitTree(), repositoryConfig()];
-  if (gate === "verify") return [specDimensions(), ...commandCriteria(context, FAST_TIER)];
+  if (gate === "verify") return [specDimensions(), docsLanguage(), ...commandCriteria(context, FAST_TIER)];
   if (gate === "pr") {
     return [
       gitTree(), gitPushed(), specGate(), openQuestions(), productClarity(), specDimensions(),
@@ -139,6 +144,34 @@ function docsUpdated(): Criterion {
   });
 }
 
+// docs/DOCUMENTATION_RULES.md, read back against the pages orly renders here.
+// The scope rule is the document's own: any documentation orly writes or
+// renders, README.md included.
+//
+// REPORTING ONLY, and deliberately so. The rule document landed against a
+// corpus that predates it, and the corpus does not obey it yet: this
+// repository alone carries hundreds of pre-existing findings. A red gate on
+// day one would be switched off by the end of the week, and grandfathering
+// them into a baseline file would be a list of chores wearing a gate's badge.
+// So the check reports what it found and leaves the verdict green until a
+// human has decided how the debt gets paid. Partial mechanization stated
+// honestly beats a red that means nothing (the same call audits/doc-read.sh
+// makes when its record is missing). Flipping this to a gate is a one-line
+// change: return ok on `findings.length === 0`.
+function docsLanguage(): Criterion {
+  return criterion(DOCS_LANGUAGE, (context) => {
+    const surfaces = documentationSurfaces(context.root);
+    if (surfaces.length === 0) return { ok: true, detail: "no documentation surface here" };
+    const findings = scanSurfaces(context.root, surfaces);
+    if (findings.length === 0) return { ok: true, detail: `${surfaces.length} page(s) clean` };
+    const named = findings.slice(0, NAMED_FINDINGS).map((finding) => `${finding.file}:${finding.line} ${finding.code}`);
+    return {
+      ok: true,
+      detail: `${findings.length} finding(s) across ${surfaces.length} page(s), reporting only: ${named.join(", ")}`,
+    };
+  });
+}
+
 // The branch is classified once per inspection and cached on the context.
 function report(context: CriterionContext, surfaces: JsonObject | undefined): SurfaceReport {
   context.surfaces ??= classifyBranch(context.root, surfaces);

package/src/doc_rules.test.ts

@@ -0,0 +1,101 @@
+import { describe, expect, test } from "bun:test";
+import { readFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+
+import { DOC_DASH, DOC_HEADING, DOC_PARAGRAPH, DOC_SENTENCE, DOC_WORD, documentationSurfaces, scanDocument } from "./doc_rules";
+
+const ROOT = resolve(import.meta.dir, "..");
+const SLOP_FIXTURE = "fixtures/doc-slop.md";
+const PAGE = "page.md";
+
+// The pass fixture: one clean page written to the rules it is checked against.
+// Every line here is prose the check must leave alone, so a false positive
+// anywhere in the reader turns this test red.
+const CLEAN = `# A clean page
+
+orly writes this page. The check reads it and finds nothing.
+
+## What it leaves alone
+
+Command names keep their banned word: run \`make harness-verify\` first.
+A link keeps its text and drops its [target](https://example.com/execute).
+
+| leverage | robust |
+|---|---|
+| a table cell is exempt | so is this |
+
+\`\`\`bash
+# fenced code is exempt: execute the robust pipeline
+orly gate verify
+\`\`\`
+
+The EXECUTE stage is a name, not a verb. A rule may quote “leverage” to ban it.
+
+<!-- lint-ignore: DOCWORD — this paragraph names the banned words to ban them -->
+Also banned: delve, foster, elevate, harness, tapestry, realm.
+`;
+
+function codes(text: string): string[] {
+  return scanDocument(PAGE, text).map((finding) => finding.code);
+}
+
+describe("scanDocument", () => {
+  test("passes a clean page", () => {
+    expect(scanDocument(PAGE, CLEAN)).toEqual([]);
+  });
+
+  test("fails the slop fixture on every mechanical rule", () => {
+    const found = codes(readFileSync(join(ROOT, SLOP_FIXTURE), "utf8"));
+
+    expect(found).toContain(DOC_WORD);
+    expect(found).toContain(DOC_DASH);
+    expect(found).toContain(DOC_SENTENCE);
+    expect(found).toContain(DOC_PARAGRAPH);
+    expect(found).toContain(DOC_HEADING);
+  });
+
+  test("names the banned word it found", () => {
+    const findings = scanDocument(PAGE, "# Page\n\nWe leverage it.\n");
+
+    expect(findings).toHaveLength(1);
+    expect(findings[0]?.message).toContain("leverage");
+    expect(findings[0]?.line).toBe(3);
+  });
+
+  test("counts an over-budget page by its overage", () => {
+    const findings = scanDocument(PAGE, "# Page\n\nOne — two — three.\n").filter((finding) => finding.code === DOC_DASH);
+
+    expect(findings[0]?.weight).toBe(2);
+  });
+
+  test("reads a lowercase product name as a sentence start", () => {
+    const paragraph = "# Page\n\nOne here. orly two. bun three. git four.\n";
+
+    expect(codes(paragraph)).toEqual([DOC_PARAGRAPH]);
+  });
+
+  test("leaves a hyphenated command name alone", () => {
+    expect(codes("# Page\n\nRun provision-env-1password before the hook.\n")).toEqual([]);
+  });
+
+  test("counts a code span as one word, not as a hole", () => {
+    const findings = scanDocument(PAGE, "# Page\n\nThe hooks run on every commit and push. `orly gate pr` then refuses it.\n");
+
+    expect(findings).toEqual([]);
+  });
+
+  test("requires exactly one level-one heading", () => {
+    expect(codes("## Only a level two\n\nProse.\n")).toContain(DOC_HEADING);
+    expect(codes("# One\n\nProse.\n\n# Two\n\nMore prose.\n")).toContain(DOC_HEADING);
+  });
+});
+
+describe("documentationSurfaces", () => {
+  test("covers the readme and the pages orly renders", () => {
+    const surfaces = documentationSurfaces(ROOT);
+
+    expect(surfaces).toContain("README.md");
+    expect(surfaces).toContain("docs/DOCUMENTATION_RULES.md");
+    expect(surfaces.every((relative) => relative.endsWith(".md"))).toBeTrue();
+  });
+});

package/src/doc_rules.ts

@@ -0,0 +1,358 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+// Mechanical enforcement of docs/DOCUMENTATION_RULES.md over the markdown orly
+// writes and renders.
+//
+// It lives in the CLI, not in this repository's audits/, because the gap it
+// closes is in what orly RENDERS. A shell script here would only ever guard
+// this checkout; a criterion in the engine travels with every install and
+// reads the pages wherever they land.
+//
+// What it enforces, mechanically and without judgment:
+//   DOCWORD  DOC-05 + DOC-07 + DOC-14b banned vocabulary, exact forms only.
+//   DOCDASH  DOC-14b em-dash budget: none in short copy, two per long page.
+//   DOCSENT  DOC-02 prose sentences carry at most 25 words.
+//   DOCPARA  DOC-03 paragraphs carry at most three sentences.
+//   DOCHEAD  DOC-25 one level-one heading, and no skipped heading level.
+//
+// What it deliberately leaves alone: DOC-06 (meaning survives the shorter
+// form), DOC-12 (pronoun referents), DOC-34 (review checks), and the
+// reading-joy set DOC-36..DOC-42. Each needs a reader who understands the
+// page. DOC-33 and DOC-34 already split the rules that way, and faking the
+// judgment half would report confidence nobody has.
+
+export const DOC_WORD = "DOCWORD";
+export const DOC_DASH = "DOCDASH";
+export const DOC_SENTENCE = "DOCSENT";
+export const DOC_PARAGRAPH = "DOCPARA";
+export const DOC_HEADING = "DOCHEAD";
+
+export type DocFinding = { file: string; line: number; code: string; message: string; weight: number };
+
+const MAX_SENTENCE_WORDS = 25;
+const MAX_PARAGRAPH_SENTENCES = 3;
+// "Short copy" and "long page" need a bound to be mechanical. A page under
+// this many words of prose is short copy and gets no em dash at all.
+const SHORT_COPY_WORDS = 300;
+const LONG_PAGE_DASHES = 2;
+const EM_DASH = "—";
+const README = "README.md";
+const CONFIG_RELATIVE_PATH = ".oracle/orly.json";
+const REGISTRY_FILE = "registry.json";
+const CODE_PLACEHOLDER = "Code";
+const EMPTY = "";
+const CLOSERS = "]\")'";
+const ENDERS = ".!?";
+const SPACE = " ";
+const UTF8 = "utf8";
+const FRONT_MATTER_FENCE = "---";
+// The first capture group, kept when a markdown span is unwrapped.
+const FIRST_GROUP = "$1";
+
+// Enumerated, never stemmed: a stemmer that turns "execute" into "executable"
+// bans a correct English word, and one false positive is what gets a check
+// switched off. The inflections that carry the same slop are listed by hand.
+const BANNED_WORDS = new Set([
+  "utilise", "utilises", "utilised", "utilising", "utilisation",
+  "utilize", "utilizes", "utilized", "utilizing", "utilization",
+  "facilitate", "facilitates", "facilitated", "facilitating",
+  "leverage", "leverages", "leveraged", "leveraging",
+  "orchestrate", "orchestrates", "orchestrated", "orchestrating", "orchestration",
+  "instantiate", "instantiates", "instantiated", "instantiating", "instantiation",
+  "terminate", "terminates", "terminated", "terminating", "termination",
+  "provision", "provisions", "provisioned", "provisioning",
+  "execute", "executes", "executed", "executing", "execution", "executions",
+  "persist", "persists", "persisted", "persisting", "persistence",
+  "hydrate", "hydrates", "hydrated", "hydrating", "hydration",
+  "artifact", "artifacts",
+  "powerful", "revolutionary", "enterprise-grade", "seamless", "seamlessly",
+  "cutting-edge", "robust", "next-generation", "world-class", "intelligent",
+  "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",
+]);
+
+const BANNED_PHRASES = ["paradigm shift", "game changer", "game-changer"];
+
+// Forms that end in a period without ending a sentence.
+const ABBREVIATIONS = new Set(["e.g.", "i.e.", "etc.", "vs.", "cf.", "no.", "fig.", "approx."]);
+// Product names are written lowercase and open sentences all over these pages.
+// Without this list "…host. orly neither…" reads as one sentence and both
+// length rules quietly under-report. The list is closed on purpose: guessing
+// at lowercase sentence starts in general would split mid-sentence and invent
+// violations.
+const LOWERCASE_OPENERS = new Set(["orly", "gstack", "agentsfleet", "bun", "bunx", "git", "npm"]);
+
+// Which DOC identifiers each code stands for, so a `lint-ignore` may name
+// either the code or the rule it enforces.
+const RULE_NAMES: Record<string, string> = {
+  [DOC_WORD]: "DOC-05 DOC-07 DOC-14b",
+  [DOC_DASH]: "DOC-14b",
+  [DOC_SENTENCE]: "DOC-02",
+  [DOC_PARAGRAPH]: "DOC-03",
+  [DOC_HEADING]: "DOC-25",
+};
+
+// The pages orly renders into a repository, plus its readme. The materialised
+// set is authoritative and it is recorded, not guessed: `.oracle/orly.json`
+// names every file orly wrote here. In the engine's own checkout the registry
+// names the sources those files are rendered from, which is the same set one
+// step earlier. README.md joins either list by the scope rule in
+// docs/DOCUMENTATION_RULES.md — the rules cover any documentation orly writes.
+export function documentationSurfaces(root: string): string[] {
+  const found = new Set<string>();
+  for (const path of [join(root, REGISTRY_FILE), join(root, CONFIG_RELATIVE_PATH)]) {
+    if (!existsSync(path)) continue;
+    for (const match of readFileSync(path, UTF8).matchAll(/"([^"\n]+\.md)"/g)) {
+      const relative = match[1] ?? EMPTY;
+      if (!relative.startsWith("/") && !relative.includes("..")) found.add(relative);
+    }
+  }
+  found.add(README);
+  return [...found].filter((relative) => existsSync(join(root, relative))).sort();
+}
+
+export function scanSurfaces(root: string, surfaces: string[]): DocFinding[] {
+  return surfaces.flatMap((relative) => scanDocument(relative, readFileSync(join(root, relative), UTF8)));
+}
+
+export function scanDocument(file: string, text: string): DocFinding[] {
+  return new Reader(file, text).run();
+}
+
+type Paragraph = { text: string; line: number; ignore: string };
+
+class Reader {
+  private readonly findings: DocFinding[] = [];
+  private paragraph: Paragraph = { text: EMPTY, line: 0, ignore: EMPTY };
+  // A pragma introduces the paragraph under it, so it outlives its own line
+  // and dies with the paragraph it was written for.
+  private pendingIgnore = EMPTY;
+  private readonly declared = new Set<string>();
+  private proseWords = 0;
+  private dashes = 0;
+  private headingLevels: number[] = [];
+  private inComment = false;
+  private inFence = false;
+  private inFrontMatter = false;
+
+  constructor(private readonly file: string, private readonly text: string) {}
+
+  run(): DocFinding[] {
+    const lines = this.text.split(/\r?\n/);
+    for (const [index, raw] of lines.entries()) this.read(raw, index + 1);
+    this.flush();
+    this.reportHeadings();
+    this.reportDashes();
+    return this.findings;
+  }
+
+  private read(raw: string, lineNumber: number): void {
+    if (lineNumber === 1 && raw === FRONT_MATTER_FENCE) {
+      this.inFrontMatter = true;
+      return;
+    }
+    if (this.inFrontMatter) {
+      if (raw === FRONT_MATTER_FENCE) this.inFrontMatter = false;
+      return;
+    }
+    if (/^[ \t]*(```|~~~)/.test(raw)) {
+      this.inFence = !this.inFence;
+      this.flush();
+      return;
+    }
+    if (this.inFence) return;
+    if (this.inComment) {
+      if (raw.includes("-->")) this.inComment = false;
+      return;
+    }
+    // A comment that opens and closes on one line is cut out of the line, not
+    // used to drop it: a prose line ending in a pack marker is still prose.
+    // One comment is read rather than dropped, `lint-ignore: <CODE> — reason`,
+    // the spelling DOC-35 already gives an exception. It clears that code for
+    // the paragraph it introduces, and it is how a page that must NAME a
+    // banned word says so out loud instead of silently.
+    const ignore = /lint-ignore:[ \t]*(DOC[A-Z0-9-]*)/.exec(raw)?.[1] ?? EMPTY;
+    if (ignore) {
+      this.declared.add(ignore);
+      this.pendingIgnore = ignore;
+    }
+    const active = this.pendingIgnore;
+    const line = raw.replace(/<!--.*?-->/g, SPACE);
+    if (line.includes("<!--")) {
+      this.inComment = true;
+      return;
+    }
+    // Tables are exempt by DOC-13, and a cell is not a sentence.
+    if (/^[ \t]*\|/.test(line)) {
+      this.flush();
+      return;
+    }
+    const heading = /^(#{1,6})[ \t]+(.*)$/.exec(line);
+    if (heading) {
+      this.flush();
+      this.readHeading(heading[1]?.length ?? 0, clean(heading[2] ?? EMPTY), lineNumber, active);
+      return;
+    }
+    if (/^[ \t]*$/.test(line)) {
+      // Unless the line went blank because it held nothing but a lint-ignore:
+      // a pragma on its own line introduces the paragraph under it.
+      if (!ignore) this.flush();
+      return;
+    }
+    if (/^[ \t]*([-*+]|[0-9]+[.)])[ \t]/.test(line)) this.flush();
+    const prose = clean(line.replace(/^[ \t]*>[ \t]?/, EMPTY).replace(/^[ \t]*([-*+]|[0-9]+[.)])[ \t]+/, EMPTY));
+    if (/^[ \t]*$/.test(prose)) return;
+    this.scanWords(prose, lineNumber, active);
+    this.countDashes(prose);
+    if (!this.paragraph.text) this.paragraph = { text: prose, line: lineNumber, ignore: active };
+    else this.paragraph.text += `${SPACE}${prose}`;
+  }
+
+  private readHeading(level: number, title: string, lineNumber: number, ignore: string): void {
+    this.scanWords(title, lineNumber, ignore);
+    this.countDashes(title);
+    const previous = this.headingLevels[this.headingLevels.length - 1];
+    if (previous === undefined) {
+      if (level !== 1) this.report(lineNumber, DOC_HEADING, `first heading is H${level}, not H1`, 1, ignore);
+    } else if (level > previous + 1) {
+      this.report(lineNumber, DOC_HEADING, `heading level jumps H${previous} to H${level}`, 1, ignore);
+    }
+    this.headingLevels.push(level);
+  }
+
+  private scanWords(prose: string, lineNumber: number, ignore: string): void {
+    this.proseWords += words(prose).length;
+    const spoken = unquote(prose);
+    for (const token of words(spoken)) {
+      // An all-caps token is a name, not vocabulary: EXECUTE is a lifecycle
+      // stage, CONFORM is a gate, DOC-05 is a rule identifier. DOC-09 asks for
+      // one canonical name per concept, and this is how those names are written.
+      if (/^[A-Z0-9_.-]+$/.test(token) && /[A-Z]/.test(token)) continue;
+      const word = token.toLowerCase().replace(/^[./-]+/, EMPTY).replace(/[.,;:!?)/-]+$/, EMPTY);
+      if (BANNED_WORDS.has(word)) {
+        this.report(lineNumber, DOC_WORD, `banned word "${token}" (DOC-05/DOC-07/DOC-14b)`, 1, ignore);
+      }
+    }
+    const lowered = spoken.toLowerCase();
+    for (const phrase of BANNED_PHRASES) {
+      if (lowered.includes(phrase)) this.report(lineNumber, DOC_WORD, `banned phrase "${phrase}" (DOC-14b)`, 1, ignore);
+    }
+  }
+
+  private countDashes(prose: string): void {
+    this.dashes += prose.split(EM_DASH).length - 1;
+  }
+
+  private flush(): void {
+    const { text, line, ignore } = this.paragraph;
+    this.paragraph = { text: EMPTY, line: 0, ignore: EMPTY };
+    if (!text) return;
+    this.pendingIgnore = EMPTY;
+    const parts = sentences(text);
+    if (parts.length > MAX_PARAGRAPH_SENTENCES) {
+      this.report(line, DOC_PARAGRAPH, `${parts.length} sentences in one paragraph, DOC-03 allows ${MAX_PARAGRAPH_SENTENCES}`, 1, ignore);
+    }
+    for (const sentence of parts) {
+      const count = words(sentence).length;
+      if (count > MAX_SENTENCE_WORDS) {
+        this.report(line, DOC_SENTENCE, `${count} words in one sentence, DOC-02 allows ${MAX_SENTENCE_WORDS}: "${excerpt(sentence)}"`, 1, ignore);
+      }
+    }
+  }
+
+  private reportHeadings(): void {
+    const first = this.headingLevels.filter((level) => level === 1).length;
+    if (first === 0) this.reportPage(DOC_HEADING, "no level-one heading", 1);
+    if (first > 1) this.reportPage(DOC_HEADING, `${first} level-one headings, DOC-25 allows one`, first - 1);
+  }
+
+  private reportDashes(): void {
+    const short = this.proseWords < SHORT_COPY_WORDS;
+    const budget = short ? 0 : LONG_PAGE_DASHES;
+    if (this.dashes <= budget) return;
+    const where = short ? `short copy (${this.proseWords} prose words), budget 0` : `a long page, budget ${budget}`;
+    this.reportPage(DOC_DASH, `${this.dashes} em dashes in ${where}`, this.dashes - budget);
+  }
+
+  // `weight` is how much debt a finding carries: one for a line-level
+  // violation, the overage for a page-level budget. A page five dashes over
+  // and a page one dash over are not the same finding.
+  private report(line: number, code: string, message: string, weight: number, ignore: string): void {
+    if (ignore && allows(ignore, code)) return;
+    this.findings.push({ file: this.file, line, code, message, weight });
+  }
+
+  private reportPage(code: string, message: string, weight: number): void {
+    for (const declared of this.declared) if (allows(declared, code)) return;
+    this.findings.push({ file: this.file, line: 0, code, message, weight });
+  }
+}
+
+function allows(ignore: string, code: string): boolean {
+  return ignore === code || (RULE_NAMES[code] ?? EMPTY).includes(ignore);
+}
+
+function words(prose: string): string[] {
+  return prose.replace(/[^A-Za-z0-9_/.-]+/g, SPACE).split(/[ \t]+/).filter(Boolean);
+}
+
+// Everything the rules exempt comes out before any rule reads the text. An
+// inline code span becomes a placeholder word rather than a hole: a hole loses
+// the capital that starts the next sentence, and the splitter then welds two
+// sentences into one long false positive. A link keeps its text and drops its
+// target, because the text is prose and the target is a path no rule governs.
+function clean(line: string): string {
+  return line
+    .replace(/!\[[^\]]*\]\([^)]*\)/g, SPACE)
+    .replace(/`[^`]*`/g, CODE_PLACEHOLDER)
+    .replace(/\[([^\]]*)\]\([^)]*\)/g, FIRST_GROUP)
+    .replace(/\[([^\]]*)\]\[[^\]]*\]/g, FIRST_GROUP)
+    .replace(/https?:\/\/[^\s)>]+/g, SPACE)
+    .replace(/<[^>]*>/g, SPACE);
+}
+
+// Use versus mention: a word inside quotation marks is being named, not used.
+// A rule that bans a word has to print it to ban it, and a page quoting a
+// caller is reporting speech rather than writing it.
+function unquote(prose: string): string {
+  return prose.replace(/“[^”]*”/g, SPACE).replace(/"[^"]*"/g, SPACE);
+}
+
+function excerpt(sentence: string): string {
+  const limit = 57;
+  return sentence.length > limit + 3 ? `${sentence.slice(0, limit)}...` : sentence;
+}
+
+// A period, question mark, or exclamation mark, then optional closing brackets
+// or quotes, then a space, then the next sentence. What follows the space
+// decides: a lowercase letter, a digit, or more punctuation continues the
+// sentence, unless the word is one of the lowercase product names.
+function sentences(paragraph: string): string[] {
+  const parts: string[] = [];
+  let current = EMPTY;
+  for (let index = 0; index < paragraph.length; index += 1) {
+    const character = paragraph[index] ?? EMPTY;
+    current += character;
+    if (!ENDERS.includes(character)) continue;
+    while (CLOSERS.includes(paragraph[index + 1] ?? EMPTY) && index + 1 < paragraph.length) {
+      index += 1;
+      current += paragraph[index];
+    }
+    const gap = paragraph[index + 1] ?? EMPTY;
+    if (gap !== SPACE && gap !== "\t" && gap !== EMPTY) continue;
+    const rest = paragraph.slice(index + 2);
+    if (gap !== EMPTY && /^[a-z0-9,;:]/.test(rest) && !LOWERCASE_OPENERS.has(/^[A-Za-z0-9_-]+/.exec(rest)?.[0] ?? EMPTY)) continue;
+    const previous = current.split(/[ \t]/).pop() ?? EMPTY;
+    if (ABBREVIATIONS.has(previous.toLowerCase()) || /^[A-Za-z]\.$/.test(previous)) continue;
+    parts.push(current.trim());
+    current = EMPTY;
+  }
+  if (current.trim()) parts.push(current.trim());
+  return parts;
+}

package/src/gates.test.ts

@@ -30,7 +30,7 @@ describe("gate groups", () => {
     const model = await modelFor(project);
 
     expect(names(runGate(model, project, "work"))).toEqual(["git.branch", "git.tree", "repo.config"]);
-    expect(names(runGate(model, project, "verify"))).toEqual(["cmd.conform", "cmd.verify.unit", "spec.dimensions"]);
+    expect(names(runGate(model, project, "verify"))).toEqual(["cmd.conform", "cmd.verify.unit", "docs.language", "spec.dimensions"]);
     expect(names(runGate(model, project, "pr"))).toEqual([
       "docs.updated", "git.pushed", "git.tree", "spec.baseline", "spec.deferrals", "spec.dimensions", "spec.gate",
       "spec.moved", "spec.open-questions", "spec.ordering", "spec.product-clarity",

package/src/install_packs.test.ts

@@ -7,7 +7,10 @@ import { install } from "./install";
 import { RulesModel } from "./model";
 
 const SOURCE_EXTENSIONS = ["rs", "ts", "tsx", "js", "jsx", "py", "sh", "sql", "zig", "mdx"];
-const ENGINE_VERSION = "0.5.2";
+// Read from package.json rather than restated here: a hand-synced copy goes
+// stale at the next release and the test then proves an install at a version
+// that no longer ships.
+const ENGINE_VERSION = (await Bun.file(join(ROOT, "package.json")).json()).version;
 
 afterEach(cleanupTemporaryDirectories);