@azure-id/orc 1.5.0 → 1.7.0

package/mock-run/orc-rules.md

@@ -0,0 +1,254 @@
+# Mock run — `orc rules`
+
+> ORC ships 65 anti-slop rules. Your project writes its own. Yours win.
+
+---
+
+## 1. What it does
+
+ORC writes a lot of prose and a lot of code, and both come out carrying the
+same recognisable defaults: sentences that say nothing in a confident shape,
+and code that is longer, more defensive and more abstract than the task asked
+for. These rules are the filter.
+
+There are two halves, and they never mix.
+
+| Half | Who writes it | Where it lives | Changes when |
+|---|---|---|---|
+| **ORC rules** | ORC | `.claude/skills/_shared/rules/` | you run `orc update` |
+| **Your rules** | you | `.claude/orc/rules.md` | you type |
+
+The ORC rules are **read-only**. They were adapted, with credit, from other
+people's work — `orc rules credits` names every source, its author, its licence
+and what ORC took from it.
+
+`/orc-doc` uses none of this. That lane has its own rules: `orc doc rules`.
+
+---
+
+## 2. Look at what you have
+
+Rina has just installed ORC in the `acme-api` repo.
+
+```
+$ orc rules
+
+orc rules — ORC 65 (W 23 · C 22 · D 10 · U 10) · yours none
+
+  Precedence   the order never changes
+   1. house rules  CODE and agent BEHAVIOUR only
+      _shared/phases/house-rules.md + the project's CLAUDE.md P0
+      beats everything below it, always
+   2. your rules   everything
+      <claude>/orc/rules.md
+      beats the ORC rules OUTRIGHT on any conflict
+   3. ORC rules    everything
+      <claude>/skills/_shared/rules/
+      beats nothing — it is the floor, and yours replaces it
+
+  ORC rules   read-only — `orc update` changes them, nothing else
+   OSW   Writing     23  HARD 14 · PURPOSE 2 · LOCK 7
+   OSC   Code        22  HARD 17 · PURPOSE 4 · LOCK 1
+   OSD   Delivery    10  HARD 7 · PURPOSE 0 · LOCK 3
+   OSU   UI          10  HARD 7 · PURPOSE 1 · LOCK 2
+   /home/rina/acme-api/.claude/skills/_shared/rules
+
+  Your rules   they win on any conflict
+   none yet
+   add one:  orc rules add --priority P0 --text "…"
+   /home/rina/acme-api/.claude/orc/rules.md
+```
+
+**`yours none` is an answer, not a gap.** It says this project has not written
+its own rules yet. That is a different fact from the command failing to look,
+and the line keeps the two apart.
+
+The three tiers mean:
+
+- **HARD** — absolute. No exception.
+- **PURPOSE** — the technique is allowed. It needs a written one-line reason.
+- **LOCK** — a consistency rule. Reported, never blocking.
+
+---
+
+## 3. Read one pack
+
+```
+$ orc rules show writing
+
+Writing (OSW) — 23 rules  read-only
+
+  OSW-01  HARD    Lead with the point
+  OSW-02  HARD    No binary contrast
+  OSW-03  HARD    No faux-insight setup
+  OSW-04  LOCK    No colon reveal
+  OSW-05  HARD    No fake-profound kicker, no summary recap
+  …
+  OSW-22  HARD    A human's paragraph is not yours to restyle
+  OSW-23  HARD    Never invent a specific
+
+  /home/rina/acme-api/.claude/skills/_shared/rules/writing.md
+```
+
+---
+
+## 4. Write your own
+
+Rina's team has two standing rules. She types them the way she would say them.
+
+```
+$ orc rules add --priority P0 --text "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."
+
+✓ P0 extended — 2 lines
+  ORC 65 (W 23 · C 22 · D 10 · U 10) · yours 2 lines (P0 2)
+  /home/rina/acme-api/.claude/orc/rules.md
+```
+
+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 exactly as you typed it. A rule you
+no longer want, you delete.
+
+Three headings, and as much text under each as you want:
+
+- **P0** — must. A run that breaks it is wrong.
+- **P1** — should. Break it only with a reason, and the reason is recorded.
+- **P2** — prefer. A default when nothing else decides.
+
+You can edit the file in your own editor instead. Or open `orc ui` ▸ **Rules**,
+which is one text box and a Save button.
+
+---
+
+## 5. Turn an ORC rule off
+
+ORC caps em dashes (`OSW-13`). Rina's team likes them. She does not argue with
+the tool — she writes her own rule and names the id.
+
+```
+$ orc rules add --priority P1 --text "OSW-13: em dashes are our house voice. Use them where they read best."
+
+✓ P1 extended — 1 line
+  ORC 65 (W 23 · C 22 · D 10 · U 10) · yours 3 lines (P0 2 · P1 1) · 1 override
+```
+
+`1 override`. That count is **never silent**: it prints at preflight, it is
+listed in the panel, and it is stated inside every slice ORC dispatches.
+
+The count comes from ORC rule ids you **named**. A rule of yours that
+contradicts an ORC rule without naming it is found by the agent while it works,
+and comes back as a conflict for you to settle — never a choice it makes
+quietly. The command says so in its own output.
+
+**Trying to edit ORC's own packs is refused by name:**
+
+```
+$ 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).
+```
+
+---
+
+## 6. Check a file, for free
+
+```
+$ orc rules lint src/checkout.js README.md
+
+orc rules lint — 2 files (paths)
+
+  src/checkout.js
+       1  OSC-02 HARD    No decorative separator
+          ==========================
+          → one plain line, or nothing
+       2  OSC-04 HARD    No empty label
+          MAIN LOGIC
+          → the label names a category, not a fact — delete it
+       7  OSC-05 HARD    A TODO names a task
+          TODO: improve this
+          → name the task and enough context to act on it, or delete it
+
+  README.md
+       3  OSW-11 HARD    Banned phrases
+          it's worth noting
+          → delete the clause and keep the point
+
+  off here  your own rules name these ids
+   OSW-13
+
+  checked 12 rules of 65 — not checked here: 53 rules. They need a reader, not a matcher.
+```
+
+That last line is the important one. **The lint only checks what a string match
+can prove** — banned words, banned phrases, comment shapes, emoji in a heading,
+em dash density, a few more. The other 53 rules need a reader.
+
+A clean lint is not a clean review, and the command says so every time, even
+when it finds nothing.
+
+It costs nothing and calls no model. It **reports**; it never fixes.
+
+Two things it skips, and it counts both rather than staying quiet: the rule
+packs themselves (a rule that bans a word has to print that word to define it),
+and any file you mark `orc-rules-ignore-file`. One line you want left alone gets
+`orc-rules-ignore` on it.
+
+---
+
+## 7. What a run does with them
+
+Every lane that writes words or code now carries a card in every slice it
+dispatches, in this order and no other:
+
+```
+1  HOUSE RULES              how a change is made: surgical, simple, honest
+2  YOUR PROJECT'S RULES     read first, and they win
+3  ORC RULES                the anti-slop baseline
+4  the task
+```
+
+The house rules are about **code and behaviour**. They say nothing about the
+words an agent writes, so they never overrule a writing rule.
+
+At preflight you see one line:
+
+```
+rules:    ORC 65 (W 23 · C 22 · D 10 · U 10) · yours 3 lines (P0 2 · P1 1) · 1 override
+```
+
+And every agent reports back what it did with them: which rules it acted on,
+which two rules disagreed, and which ORC rule your own rule replaced. A conflict
+comes back as a gap for you to settle.
+
+---
+
+## 8. Where the rules came from
+
+```
+$ orc rules credits
+```
+
+Every source, with its licence and what was taken:
+
+- **Peter G. Yang** — [`petergyang/no-ai-slop`](https://github.com/petergyang/no-ai-slop) (MIT)
+- **Miqdad Badjuber** — [`miqdadbadjuber/anti-slop`](https://github.com/miqdadbadjuber/anti-slop) (MIT)
+- **`@ehmo`** — [`ehmo/slopkit`](https://github.com/ehmo/slopkit)
+- **`@BioInfo`** — [`BioInfo/slopless`](https://github.com/BioInfo/slopless)
+- **Andrej Karpathy** — his `CLAUDE.md`
+- **Matty Cartwright** — The Anti-Slop Writing Rules
+- Three research papers on LLM code smells
+
+The long form is `CREDITS.md` beside the packs, and the panel renders the same
+table. Credit is a shipped file here, not a line in a commit message.
+
+---
+
+## 9. What it never does
+
+- It never edits ORC's own packs. `orc update` does that, and nothing else.
+- It never resolves a conflict for you. A conflict is a gap you settle.
+- It never blocks a run. The lint reports; there is no gate.
+- It never pretends the lint covered rules it could not check.
+- It never guesses that one of your sentences contradicts a rule. It counts the
+  ids you named and says that is what it counted.
+- It never reaches `/orc-doc`. That lane has `orc doc rules`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@azure-id/orc",
-  "version": "1.5.0",
+  "version": "1.7.0",
   "description": "ORC — an orchestrator skill constellation for Claude Code: intake, planning, scored parallel subagents, code-pattern matching, review, verify, ship, plus a project knowledge-base wiki.",
   "bin": {
     "orc": "bin/cli.js"

package/templates/commands/orc-rules.md

@@ -0,0 +1,66 @@
+---
+description: The anti-slop rules — ORC's shipped packs (read-only) and this project's own, which win on any conflict
+---
+
+Do not use a skill. This command is a **CLI surface**, and the CLI is the only
+thing that reads or writes either half.
+
+## What this is
+
+Two rule sets, and they never mix:
+
+- **ORC rules** — 65 shipped rules in four packs, tagged `ORC RULE`, **read-only**.
+  They change with `orc update` and with nothing else. Adapted, with credit, from
+  `petergyang/no-ai-slop`, `miqdadbadjuber/anti-slop`, `ehmo/slopkit`,
+  `BioInfo/slopless`, Andrej Karpathy's `CLAUDE.md` and Matty Cartwright's
+  anti-slop writing rules. `orc rules credits` names every one.
+- **Your rules** — a plain text file, `.claude/orc/rules.md`, three headings
+  (P0, P1, P2) and as much text under each as you want. **They beat an ORC rule
+  outright** wherever the two disagree.
+
+Above both sits the project's CODE house rules, which govern how a change is
+made and say nothing about the words an agent writes.
+
+```
+house rules  >  your rules  >  ORC rules
+```
+
+`/orc-doc` reads none of this. That lane has its own ledger: `orc doc rules`.
+
+## Run this
+
+```
+orc rules                                   both halves, the ladder, the counts
+orc rules packs                             the four packs (read-only)
+orc rules show writing|code|delivery|ui     one pack, rule by rule
+orc rules credits                           every source, author and licence
+orc rules user                              your own ledger and where it lives
+
+orc rules add   --priority P0 --text "…"    append a rule, as many lines as you like
+orc rules set   --priority P1 --text "…"    replace that whole block
+orc rules clear --priority P2               empty one block
+orc rules --reset                           back to the bare template
+
+orc rules lint <path> | --staged | --diff   the FREE check, zero tokens
+```
+
+`orc ui` ▸ **Rules** is the same thing with a text box and a Save button.
+
+## Then report, in this order
+
+1. `orc rules` — print its output. The precedence ladder is the part people get
+   wrong, so it goes first and is never summarised away.
+2. If the user asked to ADD a rule, run the `add` command with their words
+   **verbatim**. Never re-word a standing instruction into your own phrasing:
+   the whole block is handed to every agent exactly as typed.
+3. If they asked to turn an ORC rule OFF, tell them how: name its id in a rule
+   of their own (`OSW-13: em dashes are our house voice.`). The override is then
+   counted, printed at preflight, and stated inside every slice.
+4. If they asked whether something IS slop, run `orc rules lint` on it and relay
+   the coverage line it prints — the one that says how many rules it did not
+   check. A clean lint is not a clean review, and that line is the difference.
+
+Never edit `.claude/orc/rules.md` with a file tool. `orc rules` is its only
+writer, and the panel goes through the same command.
+
+What about the rules: $ARGUMENTS

package/templates/commands/orc-wiki.md

@@ -33,10 +33,32 @@ linked repo (in-place, user content byte-preserved). Requires a crosslink
 config with ≥1 edge; every step warn-only; never a re-scan. Peer writes are
 FILE writes only — never a commit or push.
 
+**`/orc-wiki update <doc-or-topic>`** → ONE doc, re-scanned. A filename goes
+straight into the targeted refresh. A topic ("the remittance feature") is
+resolved first with `orc wiki resolve` — free, no scan — and an AMBIGUOUS result
+is a question for you, never a guess. Branch detection and area planning are both
+skipped: the doc exists, so its coverage area is already in its own header.
+
+**`/orc-wiki add "<topic>"`** → ONE new doc, in a wiki that already exists, with
+no other area re-planned. It resolves the topic first (if something already
+covers it, that is an `update` and it says so), proposes a coverage scope from
+path names for you to correct, confirms the slug, the covers, the tier and the
+cost in ONE turn, and scans nothing until you say yes. It ends with
+`orc wiki refs`, the derived-reference sweep — adding a doc moves more derived
+surfaces than changing one does: the registration, the orientation page, the
+architecture overview, the CLAUDE.md pointer's doc count, and any crosslink tag
+left anchored to a file that is gone. Only the registration is repaired for you;
+the rest is reported with its command, because a sweep that silently regenerated
+prose would be spending money nobody asked it to spend.
+
 | Argument | Branch |
 |---|---|
 | *(none)* | Phase 0 auto-branch: repair / fresh / resume / refresh (delta default) |
+| `update <doc>` | targeted refresh of ONE doc (skips branch detection + area planning) |
+| `update "<topic>"` | resolve the topic to a doc, then refresh it |
+| `add "<topic>"` | reserve + scan + write ONE new doc, then sweep every derived reference |
 | `crosslink` | Phase 3c legacy backfill (publish tags from existing docs) |
 | `crosslink compile` | one-shot resolve + atlas + CLAUDE.md injection (local + peers) |
 
-Optional focus (or `crosslink` / `crosslink compile`): $ARGUMENTS
+Optional focus (`update <doc>` · `add "<topic>"` · `crosslink` ·
+`crosslink compile`): $ARGUMENTS

package/templates/hooks/README.md

@@ -1,8 +1,11 @@
-# The ORC status line
+# The ORC hooks
 
 > This page is written in Simplified Technical English. Short sentences, one
 > idea each, plain words. See `bin/webui/i18n/TERMS.md` for the term list.
 
+This page covers the two hooks you can see. The STATUS LINE, which shows what
+is happening, and the READ GATE, which can stop an oversized read.
+
 ORC shows two lines at the bottom of your terminal. Claude Code draws them.
 ORC writes them.
 
@@ -258,6 +261,91 @@ it did not see.
 
 ---
 
+## The read gate
+
+This is a different hook. It is off when you install ORC.
+
+ORC has a rule about reading. The main session reads a file to FIND things.
+To UNDERSTAND a file, ORC sends an agent to read it and report back. The agent
+uses its own context, not yours. The rule was written in three guide files and
+nothing checked it. The read gate is the part that can say no.
+
+Turn it on like this:
+
+```
+orc config set read_gate warn     # it tells you, and still reads the file
+orc config set read_gate block    # it stops the read
+orc config set read_gate off      # the default
+```
+
+### What it does
+
+It looks at one thing: a `Read` of a whole file, by the main session, during an
+ORC run, when the file is 1000 lines or more.
+
+In `warn` it shows you a note and reads the file anyway. In `block` it stops the
+read and tells you three other ways to get what you need:
+
+- Read the file with `offset` and `limit`. This is never stopped.
+- Search the file first, then read that part.
+- Send an agent to read it. An agent's reads are never stopped.
+
+**A block always names another way.** A gate that only says no is a gate people
+turn off.
+
+### When it says nothing
+
+This list is the important part. The gate is quiet in all of these states, and
+each one is on purpose:
+
+| State | Why |
+|---|---|
+| An agent is reading | An agent must read a file in full before it edits it. If it could not, it would guess the old text and damage the file. |
+| `read_gate` is `off` | This is the default. With `off`, the hook does nothing at all. |
+| No ORC run is open | The gate is about ORC's own reading. It is not a rule for your session. Outside a run it never stops anything. |
+| You used `offset` or `limit` | This is the behaviour the gate wants. It can never stop it. |
+| The file is under 1000 lines | See the next part. |
+| The file is a build log, a test result, or `.jsonl` | ORC reads these to decide pass or fail. A cut-short failing build looks like a passing build. That is worse than any saving. |
+| The gate hit an error | It always lets the read through. Then it writes down what went wrong. |
+
+**The gate cannot see a file you read with a shell command** such as `cat` or
+`head`. It only sees the `Read` tool.
+
+### Why 1000 lines
+
+Sending an agent is not free. One real agent read cost about 13,000 tokens and
+about 76 seconds. A line in this project is about 55 characters. So a file must
+be near 1000 lines before sending an agent costs less than reading it yourself.
+
+Below that number, sending an agent costs more than it saves.
+
+You can change it:
+
+```
+orc config set read_gate_max_lines 500
+```
+
+### What it never does
+
+- It never stops an agent's read.
+- It never stops a read outside an ORC run.
+- It never stops a `Bash` command.
+- It never reads the file to you. It only counts the lines.
+- It never fails closed. If the hook breaks, your read still happens.
+
+### Where to look when it acts
+
+Every `warn` and every `block` writes one line in the run trace:
+
+```
+[070926 14:22:01.220] hook     READ-GATE block :: lines=2400 max=1000 file=big-plan.md
+```
+
+An allowed read writes nothing. `orc doctor` tells you if the gate is on but not
+wired, and if it ever had to let a read through because it could not judge it.
+
+---
+
 ## For maintainers
 
 - The hook is `orc-statusline.js`. `orc init` installs it and wires it into
@@ -285,3 +373,24 @@ it did not see.
 - The cache file is `.claude/orc/usage-session.json`. The hook reads it once and
   writes it once, after the text is ready. It stores raw numbers only — never a
   word like `fresh` or `STALE`, which is computed each time it is shown.
+
+### The read gate
+
+- The hook is `orc-read-gate.js`, on `PreToolUse` with matcher `Read`. `orc
+  init` wires it even though `read_gate` defaults to `off`, so arming it is a
+  config edit and never an install step somebody has to find.
+- **`off` is byte-identical to not having the hook**, and a test asserts it.
+- **`agent_id` is the only way to tell a subagent's read from the main
+  session's, and this was MEASURED, not assumed.** `PreToolUse` does fire
+  inside a dispatched subagent, and `session_id` and `transcript_path` are
+  identical in both. A gate written against either would block the full read an
+  executor must do before it edits, and a reconstructed `old_string` corrupts
+  files. Test for the PRESENCE of `agent_id`. Never test for the absence of
+  another key — that is not a positive statement about anything.
+- The threshold is measured, not borrowed. See `read_gate_max_lines`.
+- It fails open on every path, and each failure it can name writes
+  `.claude/orc/read-gate-fallback.json` for `orc doctor` to turn into a
+  sentence — only while the feature is armed.
+- It writes one trace line per `warn` and per `block`, never on an allow. That
+  is affordable here for a structural reason: the gate only acts while a run is
+  open, so a trace always exists.