@agentsfleet/orly 0.5.3 → 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.
 
@@ -241,9 +241,9 @@ 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.

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,7 +1,7 @@
 <!-- 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.

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.
 

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/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.3",
+  "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/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",