@agentsfleet/orly 0.5.3 → 0.6.0

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
 
@@ -110,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/20 | 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/278** | |
+| **corpus** | | | | **26/280** | |
 
 ## 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/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.3",
+  "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/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();
+  });
+});