@azure-id/orc 2.1.0 → 2.2.0

package/guides/knowledge-reads.md

@@ -0,0 +1,190 @@
+# What ORC knows about your project — the reads
+
+> Every command here is **free**. None of them scans, refreshes, or spends a
+> model token. They tell you what is already on disk.
+
+This is the overflow from the README, so it can be as detailed as it needs to be.
+
+---
+
+## The rule these all live under
+
+> **`--json is not a summary`** — a read's `--json` is the WHOLE computed object.
+> A field the human path prints and the JSON omits is drift, and it is drift no
+> lint can catch, because both halves live in one function.
+
+Before v0.49.1, `orc wiki status --json` emitted five numbers while its own
+terminal output printed the per-doc breakdown, the top five stale docs, and **the
+name of the doc actually pinning the tier**. `orc ui` therefore could not be as
+detailed as the terminal, no matter how well it was written.
+
+Every legacy key kept its name, its position and its meaning — `orc doctor`, the
+Overview tile and the skills' artifact probe all read them — so the change is
+purely additive.
+
+---
+
+## The wiki
+
+### `orc wiki status [--json]`
+
+The tier, and now everything the terminal was already printing:
+
+| field | what it is |
+|---|---|
+| `tier` · `distance` · `anchor` | the wiki's freshness, which is **its worst doc's** |
+| `counts` | how many docs are FRESH / AGING / STALE / unmeasurable |
+| **`worst`** | the doc pinning the tier, **by name**. A hash is not a thing anybody can go and refresh |
+| `per_doc[]` | one row per registered doc: its own tier, its own distance, what it covers, its usage, its tags |
+| **`blind_spot`** | the changed files no doc covers — **the file list**, not the number `2` |
+| `orientation` | present, or missing with the free command that regenerates it |
+| `crosslink` | `PUBLISHED` / `UNPUBLISHED` / `NONE`, and the boundary row count |
+| `free_repairs` | reused verbatim from `orc wiki plan` — **a user must never pay for what a free step fixes** |
+
+**Exit code 0 in every state.** `state` and `tier` are the branch; overloading
+the exit code would collide with the existence probe, where a non-zero result
+reads as "absent" — and `unregistered` means the wiki very much exists.
+
+### `orc wiki docs [--json]`
+
+The doc table. `orc wiki` had six subcommands and **not one of them listed the
+docs** — you could learn the wiki was STALE with 14 docs and 47 commits of drift,
+and could not learn what any of those 14 docs was about.
+
+```
+STALE   orc-feature-billing.md                  47c  used 12/20  4 tags
+        Billing
+        covers: src/billing/
+FRESH   orc-orientation.md                       2c  used 20/20
+```
+
+**Each distance is measured against that doc's OWN covered files.** A doc about
+payments does not age because the README changed forty times.
+
+Exit **0** registered · **1** no wiki · **3** unregistered (and it names
+`orc wiki sync`, which is free and instant).
+
+### `orc wiki show <doc> [--body]`
+
+One doc: its header fields, its coverage list, its crosslink tags, its usage, and
+**the free repairs that apply to it**. `--body` adds the markdown.
+
+`--body` is opt-in on purpose: prose is returned only on an explicit request,
+exactly one artifact at a time.
+
+Exit **0** · **2** unreadable · **3** unknown doc (and it lists the ones that
+exist).
+
+### `orc wiki coverage [--json]`
+
+The number nobody could get before: **what percentage of your tracked files is
+covered by at least one wiki doc.** ORC's own artifacts are excluded, so a
+changed `wiki/` file never reads as a documentation gap.
+
+The uncovered set is collapsed to **directories** and ranked by file count,
+because these are opposite situations and a flat list of 240 paths hides both:
+
+```
+  118  vendor/stripe-sdk       last touched a1b2c3d 2026-02-11
+   22  src/notifications       last touched 9f2c41a 2026-08-08
+```
+
+> **It is a REPORT and never a gate.** There is no threshold, no config key, and
+> nothing in ORC branches on it. A repo that deliberately documents four
+> subsystems out of forty is not broken — and a coverage percentage that starts
+> nagging becomes a number people game.
+
+Exit **0** fully covered · **1** gaps exist. That is a branch, not a failure.
+
+---
+
+## Code patterns
+
+### `orc pattern show <lang> [--body]`
+
+The pattern file is injected **literally** into every executor slice, and nothing
+would show you a line of it. This does:
+
+- when it was codified, from what commit, against which playbook
+- its section headings
+- how many CONVENTIONS and how many INVARIANTS it carries
+- **the conflicts the codifier flagged** — *the project does X, the invariant
+  says Y*. These are the most decision-shaped thing in the file and were
+  invisible outside it
+- `--body` prints the text itself
+
+**It reports what is on disk and invents nothing.** The codifier may not write a
+parseable header today; with none it returns `headered: false`, shows what it
+could parse, and says so in one line. It **never** derives a "codified at" from
+the file's mtime — an mtime is when the file moved, not when the pattern was
+written.
+
+Exit **0** cached · **1** absent · **2** unknown language key. That third one is
+a *caller* bug: keys are FRAMEWORK names (`react`, `nestjs`), never file
+extensions.
+
+---
+
+## Repair memory
+
+### `orc gotcha show <id>`
+
+One entry, **every field** — symptom, fix, why, trigger, first seen. `gotcha
+list` had always emitted these and the panel rendered six columns and discarded
+the rest.
+
+Works on live entries and archived ones alike.
+
+### `orc gotcha list --archived`
+
+The archive. **Eviction is an archive, never a delete**, and ids are monotonic
+and never reused, so an archived gotcha stays traceable forever.
+
+### `orc gotcha prune --dry-run`
+
+Exactly which entries eviction would archive, and **why** — fewest hits first,
+then oldest. It writes nothing.
+
+```
+Would archive 1 gotcha (6 live, gotchas_max=5) — nothing has been written:
+  G-002 · react · repair · hits 0 · 01-01-2026
+      rank 1 of the low-value tail — 0 hit(s), last seen 01-01-2026
+```
+
+This exists because **a count is not consent.** The panel's Apply button stays
+disabled until this has been run, and the preview names every entry.
+
+Exit **0** nothing to prune · **1** it would prune.
+
+---
+
+## The two doctor cautions
+
+`orc doctor` gained exactly two wiki findings, and the restraint is deliberate.
+
+| id | Fires when | Fix |
+|---|---|---|
+| `wiki-unregistered` | the wiki is unregistered, drifted or corrupt | `orc wiki sync` — **free**, instant, and until it is done nothing can read the wiki at all |
+| `wiki-debt` | the tier is **STALE** and `orc wiki plan` has pending rows | `/orc-wiki refresh --top 2` |
+
+**`wiki-debt` never fires on AGING.** Aging is a normal state that every living
+repo passes through, and a doctor that warns about it is a doctor people learn to
+ignore.
+
+**There is no `pattern-missing` finding.** A project with no cached pattern is
+not misconfigured, and warning about it would be ORC nagging you for a paid scan.
+
+Both route to the Knowledge panel, because that is where they can actually be
+cleared — `orc wiki sync` is a button there, and `orc wiki plan` is the card
+above it.
+
+---
+
+## In `orc ui`
+
+All of it renders on **Knowledge**, now five tabs: Wiki · Coverage · Code
+patterns · Memory · Peers.
+
+The panel computes none of it. A free action gets a button, a paid action gets a
+copy-able command, and a value the CLI could not compute renders as an em dash —
+never a guess, and never a zero.

package/guides/model-selection.md

@@ -0,0 +1,186 @@
+# How ORC picks a model (and how to check it)
+
+Short version: **the planner measures the task, arithmetic turns that into a
+score, and the score picks a named agent.** No step of that is a judgement call
+made in prose, which is why you can argue with the result.
+
+---
+
+## 1. The score is computed, not guessed
+
+The planner is the party that read every file, so it reports **facets** per task:
+
+| Facet | What it measures |
+|---|---|
+| `breadth` | how many files the task touches |
+| `novelty` | mechanical · imitate · new-surface |
+| `logic` | none · branching · stateful |
+| `test_surface` | none · update-existing · new-tests |
+| `risk[]` | cited risks: auth, money, migration, … |
+| `uncertainty` | the planner's own confidence |
+
+ORC runs a fixed published formula over those numbers. Two rules ride with it:
+
+- **A cited risk forces a floor of 70.** A small change to payment code is not
+  a small task.
+- **Every fix-cycle dispatch is scored the same way.** A repair is not
+  automatically cheap.
+
+You see the whole table before anything is dispatched.
+
+---
+
+## 2. The score → model table
+
+The default table has 5 bands (`skills/orc/config.md`):
+
+| Score | Model | Effort | Agent |
+|---|---|---|---|
+| `[0,21)` | `claude-sonnet-5-5` | low | `orc-executor-sonnet-5-low` |
+| `[21,31)` | `claude-sonnet-5-5` | medium | `orc-executor-sonnet-5-med` |
+| `[31,41)` | `claude-sonnet-5-5` | high | `orc-executor-sonnet-5-high` |
+| `[41,90)` | `claude-opus-5-5` | low | `orc-executor-opus-5-low` |
+| `[90,100]` | `claude-opus-5-5` | medium | `orc-executor-opus-5-med` |
+
+Every band from score 41 needs an Opus 5.5 main session. Six executors are
+named by no band (`orc-executor-haiku-5-high`,
+`orc-executor-sonnet-4-6-high`, `orc-executor-opus-4-7-med`,
+`orc-executor-opus-4-7-high`, `orc-executor-opus-4-8-high`,
+`orc-executor-opus-5-high`). They still ship. To use one, name it in
+`rubric_bands_override`, `orc diy`'s `fixed_executor` or `extra_fallback_agent`.
+
+`rubric_bands` (2–8) changes **how the report is grouped**, not the table.
+
+### The alternative table: `opus5_only`
+
+Set `opus5_only: true` and **every dispatched role uses Opus 5.5**, with effort as
+the cost dial instead of the model:
+
+| Score | Model | Effort |
+|---|---|---|
+| `[0,90)` | `claude-opus-5-5` | low |
+| `[90,100]` | `claude-opus-5-5` | medium |
+
+This ladder differs from the default table only below score 41.
+
+Eight fixed roles switch to an Opus 5.5 variant too (mini executor, fast
+executor, mini analyst, mini planner, scout, pattern codifier, the light wiki
+scanner, retro miner). The CLAUDE.md writer and the deep wiki scanner are
+already on Opus 5.5 low, so they do not change. Two things are **never** forced:
+the Haiku trace writer (it transcribes a packet somebody else wrote) and
+`/orc-diy` (its executors come from the compiled flow).
+
+While `opus5_only` is on it **outranks** the Fable 5 override and any
+hand-written band table. ORC never hides that: `orc config set` names every key
+it makes inert, and `orc config list` marks them.
+
+**It is inert in `/orc-quick`.** That lane always asks you which agent to use,
+and a forcing mode would silently delete your answer.
+
+### Resolution order
+
+`opus5_only` › a hand-written `rubric_bands_override` › the default 5-band
+table.
+
+---
+
+## 2b. Four lanes have no score, so they have POSITIONS instead
+
+A band answers "which agent for a task that scored 62". `/orc-quick`,
+`/orc-fast`, `/orc-doc` and `/orc-wiki` never produce a score at all — they pin
+one agent to a job. So each of those jobs is a **position** you can point
+somewhere else (`orc extra role`, v0.55.0):
+
+| position | lane | the agent it takes the job from |
+|---|---|---|
+| `quick-executor` | `/orc-quick` | `orc-executor-sonnet-5-med` · `orc-executor-opus-5-low` |
+| `fast-executor` | `/orc-fast` | `orc-executor-sonnet-5-med` |
+| `doc-writer` | `/orc-doc` | `orc-doc-writer-opus-5-med` |
+| `doc-checker` | `/orc-doc` | `orc-doc-checker-opus-5-low` |
+| `wiki-scanner-deep` | `/orc-wiki` | `orc-wiki-scanner-opus-5-low` |
+| `wiki-scanner-light` | `/orc-wiki` | `orc-wiki-scanner-sonnet-5-high` |
+
+A position with no row stays on the agent above, and it **keeps its row** in
+`orc extra role` so "I left the checker on Claude on purpose" and "there is no
+checker" never look the same.
+
+**`/orc-quick`'s recon pair is NOT a position, and that is on purpose (v1.9.0).**
+`orc-recon-sonnet-5-med` and `orc-recon-opus-5-low` read the repository and
+hand back an answer the dispatch gate is expected to trust. Sending that job to
+a third party is a different question from sending a code edit there: a wrong
+edit fails a build, and a wrong answer is believed. So recon and review stay on
+Claude, `quick-executor` remains the lane's only position, and the menu's third
+line is an escape hatch that names a MODEL, never a routed slot.
+
+`/orc-mini` is the one fixed-executor lane that keeps a band, and that is
+deliberate: mini scores its tasks and then pins one executor over them, so
+reading that agent's band is a question about numbers the run really produced.
+
+### The one precedence sentence
+
+> **Extra decides whether a Claude agent runs at all. `opus5_only` and the score
+> tables only decide WHICH Claude agent runs where extra did not take it.**
+
+Under a taken position `opus5_only` is **not consulted** — and it stays fully
+live for every position with no row. `orc config list` names the taken positions
+beside the taken bands, because a partly shadowed setting must not be flattened
+into one word.
+
+---
+
+## 3. The models are pinned, so you can check them
+
+A dispatch names a real agent file in `.claude/agents/`, for example
+`orc-executor-sonnet-5-high`, whose frontmatter carries the model and effort.
+That is why **an agent's model change is always a rename**.
+
+Three ways to confirm what actually ran:
+
+1. Expand the tool call in Claude Code.
+2. Read the behavior trace under `.claude/orc/logs/` — every `RETURN` records
+   the model that really answered.
+3. `orc stats` — it counts dispatches and **downgrades** from those traces.
+
+Every agent return carries `actual_model` and `actual_effort`, quoted rather
+than assumed, so a silent tier downgrade is flagged rather than absorbed.
+
+---
+
+## 4. The tier rule that catches everyone
+
+> **A subagent's model can never be higher than your main session's model.**
+
+Run your main Claude Code session on **Opus 5.5**. Otherwise every Opus-5-pinned
+role (analyst, planner, reviewer, verifier, test author, combiner, ultra
+advisor and judge) plus the top executor band quietly runs on whatever your
+session runs. This is the most common cause of "it used the wrong model".
+
+See `agents/MODEL-MAPPING.md` in your install for the full list.
+
+### The guard `orc init` installs
+
+`orc init` merges two things into `.claude/settings.json`, without replacing
+anything you already have:
+
+- **Effort — a hard block.** `hooks/orc-effort-guard.js` (a `PreToolUse` hook)
+  refuses to start `/orc` below **high** effort. `claude-opus-5-5` and
+  `claude-fable-5` are cleared from **medium** up, because both outrank the
+  Opus 4.8 baseline. This is the half Claude Code lets a hook enforce.
+  The hook runs on two events. `PreToolUse` gates a `/orc` or `/orc-diy` that
+  Claude starts through the Skill tool. `UserPromptExpansion` (v2.1.2) gates a
+  `/orc` or `/orc-diy` that you type. The typed gate reads the effort that the
+  ORC status line wrote for this session. If that reading is not there (no ORC
+  status line, or a headless `claude -p`), the typed command is not stopped.
+  `orc doctor` tells you when the typed gate is not wired; `orc update` adds it.
+- **Model — a warning only.** Claude Code does not expose the model id to a
+  blocking hook, so the tier cannot be hard-stopped. `hooks/orc-statusline.js`
+  carries the verdict in its ICON — `✅` good, `🚀` better, `⛔` ORC will degrade,
+  the last of which always names its reason in brackets — and the orchestrator
+  checks itself at startup. (Before v1.2.1 the verdict was a WORD; the words are
+  now the installed ORC version. Every segment is documented in
+  `.claude/hooks/README.md`.) If you already run a statusline,
+  `orc init` leaves it alone and prints the snippet for you to merge.
+
+The guard matches the **exact** skill name `orc`. `/orc-fast` legitimately runs
+at Sonnet medium — it does no scoring or planning — so it is not in the guard,
+and it never should be.

package/guides/rules.md

@@ -0,0 +1,305 @@
+# Rules — `orc rules` in detail
+
+README overflow. The short version is in the README under *Rules that keep the
+slop out*; this is everything that would have bloated it.
+
+---
+
+## Two halves that never mix
+
+| Half | Who writes it | Where it lives | Changes when |
+|---|---|---|---|
+| **ORC rules** | ORC | `.claude/skills/_shared/rules/` | `orc update` |
+| **Your rules** | the project | `.claude/orc/rules.md` | you type |
+
+The ORC rules are **read-only to you**. A write aimed at them is refused by
+name, with the command that replaces it:
+
+```
+$ orc rules set --pack writing --priority P0 --text "…"
+❌ ORC rules are read-only — they change with `orc update`, never with a command.
+   Write your own instead: orc rules add --priority P0 --text "…" (yours win on any conflict).
+```
+
+`/orc-doc` reads none of this. That lane has its own ledger (`orc doc rules`)
+and its own frozen-per-document mechanic, and the two surfaces are kept apart on
+purpose.
+
+---
+
+## The 65 rules
+
+| Pack | Ids | Rules | Applies to |
+|---|---|---|---|
+| Writing | `OSW-01…23` | 23 | every word an agent writes |
+| Code | `OSC-01…22` | 22 | source an agent writes or edits |
+| Delivery | `OSD-01…10` | 10 | what an agent reports about its own work |
+| UI | `OSU-01…10` | 10 | front-end work only |
+
+`orc rules packs` prints the table. `orc rules show <pack>` prints one pack.
+
+### The three tiers
+
+| Tier | Meaning | On a finding |
+|---|---|---|
+| **HARD** | Absolute. No exception, no purpose that redeems it. | A finding. |
+| **PURPOSE** | The technique is allowed. It needs a written one-line reason. | A missing reason is a finding; the technique is not. |
+| **LOCK** | A consistency requirement. | Reported, never blocking. |
+
+The tier system is Miqdad Badjuber's, from
+[`miqdadbadjuber/anti-slop`](https://github.com/miqdadbadjuber/anti-slop), and it
+exists for a reason worth stating: **a ban list alone leaves a void, and a model
+fills a void with its most generic output.** A purpose gate asks for the reason
+instead, which is the only thing that separates craft from a default.
+
+### The UI pack rides per TASK
+
+`ui` is in no lane's default set. The orchestrator adds it to a single slice
+when that task's declared files are front-end — `.css`, `.scss`, `.html`,
+`.jsx`, `.tsx`, `.vue`, `.svelte`, or a directory the wiki or the cached pattern
+names as the UI layer.
+
+A UI rule in a backend slice is tokens paid on every spawn for a rule that
+cannot apply.
+
+---
+
+## Precedence, and the sentence people get wrong
+
+```
+house rules  >  your rules  >  ORC rules
+```
+
+**The house card is CODE and BEHAVIOUR only.** It governs how a change is made:
+surgical, simple, honest, in-slice. It says nothing about the words an agent
+writes, so it never overrules a writing rule — *it does not speak about prose at
+all.*
+
+**A project rule beats an ORC rule outright.** Not a waiver and not a
+negotiation: the ORC rule is removed from the slice, and the removal is stated
+inside it.
+
+To switch an ORC rule off, name its id in a rule of your own:
+
+```
+$ orc rules add --priority P1 --text "OSW-13: em dashes are our house voice."
+✓ P1 extended — 1 line
+  ORC 65 (W 23 · C 22 · D 10 · U 10) · yours 3 lines (P0 2 · P1 1) · 1 override
+```
+
+### How an override is counted, and why it is counted that way
+
+The CLI counts ORC rule ids you **named**. It says so in the same breath:
+
+> counted from ORC rule ids you NAMED in your own rules. A conflict you did not
+> name is found by the agent at dispatch and returned as `rules_conflicts[]` —
+> the CLI cannot parse intent, so it does not pretend to.
+
+That split is deliberate. A validator that guessed whether one of your sentences
+contradicted a rule would be right often enough to be trusted and wrong often
+enough to matter, and a clean pass would then mean nothing. The agent is the only
+reader that can tell, so the agent is where the answer comes from.
+
+**An override is never silent.** It appears in the preflight line, in the panel,
+and inside every slice.
+
+---
+
+## Your ledger
+
+`.claude/orc/rules.md`. Plain text, three headings, and as much text under each
+as you want.
+
+```markdown
+# ORC · project rules
+#   … anything above the first heading is your own note, never dispatched …
+
+## P0
+
+Never name a customer in a commit message or a PR body. Use the account id.
+Every public function in src/api/ carries a one-line comment naming its caller.
+
+## P1
+
+Prefer Result<T, E> over throwing inside src/core/.
+
+## P2
+
+Say "customer", never "user", in anything a customer reads.
+```
+
+| Priority | Meaning | On conflict |
+|---|---|---|
+| **P0** | Must. A run that breaks it is wrong. | Beats P1, P2 and every ORC rule. |
+| **P1** | Should. Break it only with a reason, and the reason is recorded as a gap. | Beats P2. |
+| **P2** | Prefer. A default when nothing else decides. | Loses to everything above. |
+
+**There is no rule id and no rule count on your side.** The unit is the block,
+and the whole block is handed to every agent verbatim. This is the `orc doc
+rules` design, reused without change, because that argument was already had: a
+standing instruction is prose, not a form, and nobody's real P0 fits on one line.
+
+### The commands
+
+```
+orc rules [--json]                       both halves + the precedence ladder   0 / 1
+orc rules packs [--json]                 the pack table (read-only)            0 / 2
+orc rules show <pack> [--json]           ONE pack, rule by rule                0 / 2
+orc rules user [--json]                  YOUR ledger and where it lives        0 / 1
+orc rules credits [--json]               every source, author and licence      0 / 2
+orc rules slice --lane <lane> [--pack ui]  THE dispatch text                   0 / 2
+
+orc rules set   --priority P0 --text "…"   replace ONE block
+orc rules add   --priority P0 --text "…"   append to a block
+orc rules clear --priority P0              empty ONE block
+orc rules set-all --text "…"               replace the WHOLE file (what `orc ui` writes)
+orc rules --set-file <path>                replace it from a file
+orc rules --reset                          back to the bare template
+```
+
+Exit `1` on a read means **no project rules yet**. That is an answer, and the
+JSON object still comes back with the template in it.
+
+`orc ui` ▸ **Rules** is the same thing with a text box and a Save button.
+Nothing is written until you press Apply, the pending edit is named, and Discard
+appears only while there is something to discard.
+
+---
+
+## The lint
+
+```
+orc rules lint <path…|--staged|--diff> [--pack w,c,d,u] [--json]
+```
+
+Free, deterministic, zero tokens. Exit `0` clean · `1` findings · `2` nothing to
+lint.
+
+It checks **13 of the 65 rules** — the ones a string match can prove:
+
+| Checked | Rules |
+|---|---|
+| Banned lexicon and phrases | `OSW-10` `OSW-11` `OSU-06` |
+| Em dash density | `OSW-13` |
+| Emoji in a heading | `OSW-18` |
+| Comment shapes | `OSC-02` `OSC-03` `OSC-04` `OSC-05` `OSC-06` `OSC-07` |
+| Unrequested artifact files | `OSC-21` |
+| `outline: none` with no replacement | `OSU-03` |
+
+And it prints, in **every** mode, human and JSON:
+
+```
+checked 13 rules of 65 — not checked here: 52 rules. They need a reader, not a matcher.
+```
+
+That line is the point of the command. A lint that implied it had graded all 65
+would let a clean exit stand in for a review that never happened.
+
+**Findings are advisory.** There is no gate. A style preference that fails a
+build gets switched off within a week, and then nothing is enforced at all.
+
+### What it skips, and why it says so
+
+- **The rule packs themselves.** A rule that bans a word has to print that word
+  to define it, so the packs would fail their own lint on every line — and a
+  lint whose loudest findings are its own documentation is a lint people learn
+  to ignore.
+- **`orc-rules-ignore-file`** in a file's head, or **`orc-rules-ignore`** on a
+  line: your own opt-out.
+
+Both are counted in the output. An exemption nobody can see is a file that
+passed without being read.
+
+### Em dash is a DOSE rule, not a ban
+
+`OSW-13` is measured per file, never per occurrence:
+
+- short output (a chat answer, a commit body, a label): none;
+- a long document: at most two per thousand words.
+
+ORC's own documentation uses em dashes, and a rule the shipping project breaks
+on every page is a rule nobody will believe. The lint reports **density**.
+
+---
+
+## In a run
+
+Every lane that writes words or code carries a card in every slice it
+dispatches, assembled by one command (`orc rules slice`) and never by a skill:
+
+```
+1  HOUSE RULES              how a change is made
+2  YOUR PROJECT'S RULES     read first, and they win
+3  ORC RULES                the anti-slop baseline
+4  the task
+```
+
+Preflight prints one line:
+
+```
+rules:    ORC 65 (W 23 · C 22 · D 10 · U 10) · yours 9 lines (P0 4 · P1 2 · P2 3) · 1 override
+rules:    ORC 65 (W 23 · C 22 · D 10 · U 10) · yours none
+```
+
+Both spellings are mandatory in their state. `yours none` says this project has
+not written its own rules — a different fact from the CLI failing to look.
+
+Every return gains three fields:
+
+| Field | What it holds |
+|---|---|
+| `rules_applied[]` | the ids the agent acted on |
+| `rules_conflicts[]` | two rules that disagree. **A gap, never a silent choice** |
+| `rules_overridden[]` | an ORC id a project rule replaced |
+
+### The cost, stated
+
+The card rides on **every spawn**. Measured at v1.7.0: about **3 600 tokens** per
+build-lane slice, **4 300** with the UI pack, **2 200** for a prose-only lane.
+
+It is already the cheap shape — HARD rules carry their body, PURPOSE and LOCK
+rules carry one line each plus the file to open when one applies. If it has to
+come down, the lever is `rulesSlice()` in the CLI, and never a lane trimming its
+own card.
+
+---
+
+## The boundary
+
+Rules govern **what is written and how it reads**, and **what shape of code is
+acceptable**. They can never change how a lane **runs**: the scoring, the wave
+order, the gates, the dispatch contract, the ship rules, or any lane's
+structural and safety rules.
+
+A rule that asks for one of those comes back as `unsupported_request` and is
+relayed as a gap. Never a guessed compromise.
+
+There is no detector for this, and there will not be one. The CLI declares the
+boundary and does not pretend to enforce it — the same decision `orc doc rules`
+made, for the same reason.
+
+---
+
+## Credit
+
+The rules are adapted from other people's work. `orc rules credits` prints the
+whole table; `CREDITS.md` beside the packs is the long form, with the date each
+source was read.
+
+| Source | Author | Licence |
+|---|---|---|
+| [`petergyang/no-ai-slop`](https://github.com/petergyang/no-ai-slop) | Peter G. Yang | MIT |
+| [`miqdadbadjuber/anti-slop`](https://github.com/miqdadbadjuber/anti-slop) | Miqdad Badjuber | MIT |
+| [`ehmo/slopkit`](https://github.com/ehmo/slopkit) | `@ehmo` | see repo |
+| [`BioInfo/slopless`](https://github.com/BioInfo/slopless) | `@BioInfo` | see repo |
+| Karpathy's `CLAUDE.md` | Andrej Karpathy | — |
+| [The Anti-Slop Writing Rules](https://mattycartwright.com/blog/the-anti-slop-writing-rules) | Matty Cartwright | — |
+
+Plus three papers on LLM code smells:
+[2512.18020](https://arxiv.org/html/2512.18020v1) ·
+[2605.02741](https://arxiv.org/html/2605.02741v1) ·
+[2510.03029](https://arxiv.org/pdf/2510.03029).
+
+If you are one of these authors and would prefer different wording, a different
+attribution, or removal, open an issue on
+[`azure-id/orc`](https://github.com/azure-id/orc).