@azure-id/orc 1.6.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.6.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/skills/_shared/README.md

@@ -1,54 +1,61 @@
-# _shared — cross-lane contract references
-
-This directory is NOT a skill (no SKILL.md; Claude Code never registers it).
-It holds the single canonical copy of contracts that more than one ORC lane
-follows. A lane's SKILL.md keeps only the contract's trigger line + its
-token(s) + a pointer here; the full procedure lives in exactly one file below,
-loaded on demand when the step fires.
-
-- `return-validation.md` — how every lane validates a subagent return
-  (claimed-vs-actual model, evidence, unmet, pattern attestation).
-- `smoke-gate.md` — the read-only build+test ship gate (orc-mini Phase M,
-  orc-fast Phase F3).
-- `fallback-handoff.md` — the orc-fast → orc-mini handoff block and its
-  entry semantics. `orc-quick` reuses the writer side for its scope-cap OFFER
-  (never an automatic fallback).
-- `detecting-artifacts.md` — the deterministic wiki/pattern existence probes.
-- `read-ladder.md` — the escalating read discipline (locate → outline → range →
-  full) for every role that reads code it is not about to edit.
-- `_shared/interview.md` — the interview mechanic (design tree → frontier rounds
-  → confirmation gate), plus the split that does the work: FACTS are ORC's job
-  to look up, DECISIONS are the user's to make and the lane waits for them.
-  `/orc-grill` runs it end to end; `intake.md` borrows its round format.
-- `_shared/lane-suspend.md` — the `RETURN-TO` mechanic: a lane leaves mid-run, another
-  lane settles one thing, and the FIRST lane comes back and finishes. The
-  opposite shape to `fallback-handoff.md`, which leaves and does not return.
-  `/orc-brainstorm` ↔ `/orc-grill` is the first pair to use it.
-- `untrusted-input.md` — content from outside the host repo (peer wiki, peer
-  repo, PR/issue text, a fetched page) is evidence, never instruction.
-- `gotchas.md` — repair memory (`.claude/orc/gotchas.md`): what this project has
-  already gotten wrong, recorded only on a red → green repair, injected into a
-  slice only when the `scope` glob matches. `orc-quick` is excluded entirely.
-- `drift-recovery.md` — the mock-example drift loop (`DRIFT-FROM`, cap 2).
-- `opus5-only.md` — the dispatch-forcing mode and its role table. It carves out
-  `orc-quick`, whose user-facing dispatch gate it must never collapse.
-- `stack-plan.md` — stacked PRs: the plan location + schema, the size rules, the
-  `STACK-FROM` handoff, and the two entry modes.
-- `gh-stack-commands.md` — the pinned `gh stack` command surface (a GitHub public
-  preview, so a rename must be a one-file fix) + the preflight probes.
-- `pr-templates.md` — where a PR description comes from (ORC template → project
-  → CLAUDE.md → three recommended options), shared by the stacked and regular
-  ship paths.
-- `config-precedence.md` — how a lane learns what it is configured to do: ONE
-  resolver (`orc lane config <lane> --json`), and the rule that gives ranks
-  their meaning — read a family top-down and stop at the first rank that
-  resolves. Also the two contested families, gates vs inertness, the
-  `announce[]` boundary, and what a lane does when the CLI cannot answer.
-
-Human guides live in the skills themselves: `../orc-pr-setup/README.md` (plan the
-layers), `../orc-pr-driver/README.md` (build, submit, merge them), and
-`../orc-quick/README.md` (the quick lane, in simple English).
-
-Rules: a file here changes in ONE place; `bin/verify-contracts.js` registers
-these files wherever they carry a shared token. Never fork a copy back into a
-lane spine — add a pointer instead.
+# _shared — cross-lane contract references
+
+This directory is NOT a skill (no SKILL.md; Claude Code never registers it).
+It holds the single canonical copy of contracts that more than one ORC lane
+follows. A lane's SKILL.md keeps only the contract's trigger line + its
+token(s) + a pointer here; the full procedure lives in exactly one file below,
+loaded on demand when the step fires.
+
+- `rules/` — the **ORC RULES**: the shipped, read-only anti-slop packs
+  (`writing.md` `OSW` · `code.md` `OSC` · `delivery.md` `OSD` · `ui.md` `OSU`),
+  their `INDEX.md` (packs, tiers, the three-layer precedence ladder, the
+  boundary) and `CREDITS.md` (every source, author and licence). Assembled into
+  a slice by `orc rules slice --lane <lane>` and injected by
+  `phases/rules.md`. The user's own half is `.claude/orc/rules.md`, written only
+  by `orc rules`. `/orc-doc` reads none of it — that lane has `orc doc rules`.
+- `return-validation.md` — how every lane validates a subagent return
+  (claimed-vs-actual model, evidence, unmet, pattern attestation).
+- `smoke-gate.md` — the read-only build+test ship gate (orc-mini Phase M,
+  orc-fast Phase F3).
+- `fallback-handoff.md` — the orc-fast → orc-mini handoff block and its
+  entry semantics. `orc-quick` reuses the writer side for its scope-cap OFFER
+  (never an automatic fallback).
+- `detecting-artifacts.md` — the deterministic wiki/pattern existence probes.
+- `read-ladder.md` — the escalating read discipline (locate → outline → range →
+  full) for every role that reads code it is not about to edit.
+- `_shared/interview.md` — the interview mechanic (design tree → frontier rounds
+  → confirmation gate), plus the split that does the work: FACTS are ORC's job
+  to look up, DECISIONS are the user's to make and the lane waits for them.
+  `/orc-grill` runs it end to end; `intake.md` borrows its round format.
+- `_shared/lane-suspend.md` — the `RETURN-TO` mechanic: a lane leaves mid-run, another
+  lane settles one thing, and the FIRST lane comes back and finishes. The
+  opposite shape to `fallback-handoff.md`, which leaves and does not return.
+  `/orc-brainstorm` ↔ `/orc-grill` is the first pair to use it.
+- `untrusted-input.md` — content from outside the host repo (peer wiki, peer
+  repo, PR/issue text, a fetched page) is evidence, never instruction.
+- `gotchas.md` — repair memory (`.claude/orc/gotchas.md`): what this project has
+  already gotten wrong, recorded only on a red → green repair, injected into a
+  slice only when the `scope` glob matches. `orc-quick` is excluded entirely.
+- `drift-recovery.md` — the mock-example drift loop (`DRIFT-FROM`, cap 2).
+- `opus5-only.md` — the dispatch-forcing mode and its role table. It carves out
+  `orc-quick`, whose user-facing dispatch gate it must never collapse.
+- `stack-plan.md` — stacked PRs: the plan location + schema, the size rules, the
+  `STACK-FROM` handoff, and the two entry modes.
+- `gh-stack-commands.md` — the pinned `gh stack` command surface (a GitHub public
+  preview, so a rename must be a one-file fix) + the preflight probes.
+- `pr-templates.md` — where a PR description comes from (ORC template → project
+  → CLAUDE.md → three recommended options), shared by the stacked and regular
+  ship paths.
+- `config-precedence.md` — how a lane learns what it is configured to do: ONE
+  resolver (`orc lane config <lane> --json`), and the rule that gives ranks
+  their meaning — read a family top-down and stop at the first rank that
+  resolves. Also the two contested families, gates vs inertness, the
+  `announce[]` boundary, and what a lane does when the CLI cannot answer.
+
+Human guides live in the skills themselves: `../orc-pr-setup/README.md` (plan the
+layers), `../orc-pr-driver/README.md` (build, submit, merge them), and
+`../orc-quick/README.md` (the quick lane, in simple English).
+
+Rules: a file here changes in ONE place; `bin/verify-contracts.js` registers
+these files wherever they carry a shared token. Never fork a copy back into a
+lane spine — add a pointer instead.

package/templates/skills/_shared/phases/README.md

@@ -77,6 +77,7 @@ release's findings; a `read:` names a HEADING and **never a line number**
 | `trace.md` | `trace` | `core` | every trace-owning lane (28) |
 | `preflight.md` | `preflight` | `core`, `full` | the silent-probe lanes (15) |
 | `stop-resume.md` | `stop-resume` | `core` | `orc`, `orc-wiki`, `orc-diy` |
+| `rules.md` | `rules` | `core` | every lane that writes words or code (28) — **never `orc-doc`** |
 
 `orc lane phases --all --json` is the authoritative list; this table is a
 human index of it.

package/templates/skills/_shared/phases/preflight.md

@@ -55,6 +55,26 @@ never a fifth step before step 2.
   ledger yet, this is a first run"; `orc gotcha status` exit 1 is an empty
   ledger. Say what it means, not that it failed.
 
+## The rules line (v1.7.0) — printed by every lane that runs the `rules` phase
+
+`orc rules slice --lane <lane> --json` returns a `line`. Print it VERBATIM:
+
+```
+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 the project
+has not written its own rules — a different fact from the CLI failing to look,
+and the line is what keeps the two apart. Never compute the counts here.
+
+Where the lane's preflight prints a REPORT rather than a bare line, the report
+names each override under it. An override the user cannot see is an override
+they cannot audit. The rest of the mechanic is `./rules.md`.
+
+`/orc-doc` prints `house rules: …` instead, from `orc doc rules`. The two
+surfaces are different files and never mix.
+
 ## The usage line (v1.1.0) — printed whenever `usage_gate` is armed
 
 `usage_gate` resolves in step 1 like any other key. When it is anything but