@azure-id/orc 2.0.2 → 2.1.1

package/mock-run/orc-fast.md

@@ -39,12 +39,12 @@ Fit gate + one question
 
 > nothing, follow api/orders/
 
-Dispatch  orc-executor-sonnet-4-6-high
+Dispatch  orc-executor-sonnet-5-med
   slice carries:
     · wiki pointers   wiki/orc-feature-orders.md  (the route table)
     · the express pattern, copied in literally
     · your one constraint
-  returned as: claude-sonnet-4-6 / high      ✓
+  returned as: claude-sonnet-5-5 / medium     ✓
 
 Smoke gate
   build   ✓

package/mock-run/orc-fix.md

@@ -0,0 +1,87 @@
+# Mock run — `/orc-fix`
+
+> You fixed something, and the fix says something about an earlier review.
+> Type this, and ORC records what the fix fixes, so the next review sees it.
+
+---
+
+## 1. What it does
+
+It records ONE fix and what it fixes. It looks at the evidence first: what
+found the problem (Sonar, a failed check, a defect, a PR comment) and who wrote
+the bad lines (an ORC run, an AI tool, a person). It asks you once. Then it
+records the fix and goes back to exactly where you were.
+
+It opens no run of its own. You can type it in the middle of another run, also
+while that run waits at a question.
+
+- **A run is open** → it only records. The run you are in makes the fix.
+- **No run is open** → it can also make the fix, like `/orc-quick`: you pick
+  the agent, the build and the tests must be green, and then it records.
+
+---
+
+## 2. The run
+
+Rina is in an `/orc-quick` run. Sonar flagged `computeTotal()` as too complex,
+and those lines came from last week's `/orc-mini` run, which had a review.
+
+```
+> /orc-fix this fixes Sonar typescript:S3776 in src/orders/total.ts:40-58
+```
+
+```
+This fix:  source sonar · introduced by ORC (run-mini-total-290926-101500)
+  - a Sonar rule key (typescript:S3776)
+  - git blame → 4c1e2a9: the commit falls inside the run's trace window and
+    src/orders/total.ts is in the run's changed set
+  host run: run-quick-total-fix-021026-091200 — record only, the host lane
+  makes the fix
+
+  1. confirm   2. change the class   3. cancel
+```
+
+```
+> 1
+```
+
+```
+recorded F-9f2c41ab · sonar typescript:S3776 · introduced by ORC
+(run-mini-total-290926-101500) · missed by review run-mini-total-290926-101500
+· the next review sees it
+
+Back to the run. Entry 3 is waiting for your "go".
+```
+
+The next time a reviewer looks at `src/orders/total.ts`, its card has this line:
+
+```
+fix: src/orders/total.ts — Sonar typescript:S3776 after ORC run
+run-mini-total-290926-101500 · missed by review
+```
+
+---
+
+## 3. What to notice
+
+- **It classifies from evidence, and your word wins.** `orc fix classify` reads
+  `git blame`, the traces and the run snapshots. If you change the class, the
+  record says `class_by: user`.
+- **"Missed by review" is computed.** Every review stores the line ranges it
+  read. A fix on those lines, from an earlier run, is a miss. ORC never guesses
+  it, and you never type it.
+- **A fix is never a review.** The record's author is who FOUND the problem
+  (Sonar is a bot, a user report is a person). Review Quality counts reviews
+  apart, and shows fixes in their own block: **Fixes after review**.
+- **A Sonar fix and the Sonar import are the same row.** With the issue key, the
+  record uses the importer's id, so the next `orc gotcha sync` completes it.
+- **One trace line.** `orc fix record` writes ONE `FIX` line into the run you
+  are in. It never writes the run pointer.
+
+---
+
+## 4. Related
+
+- The panel: `orc ui` ▸ Behaviour ▸ Review quality ▸ **Fixes after review**
+- The records: `orc fix list`
+- The Sonar import: [gotcha-import](gotcha-import.md)

package/mock-run/orc-pattern.md

@@ -1,112 +1,112 @@
-# Mock run — `/orc-pattern`
-
-> Learns how **your** code is actually written, and caches it, so every future
-> executor writes code that looks like yours.
-
----
-
-## 1. What it does
-
-ORC ships a generic best-practice playbook for each language (React, Vue,
-Next.js, Angular, Express, NestJS, Django, FastAPI, Go, Postgres, plus a11y and
-performance rule packs). On its own, a playbook would fight your codebase.
-
-So the pattern is a **reconciliation** of two things, with two different rules:
-
-| Rule class | Example | Who wins |
-|---|---|---|
-| **Conventions** — style and shape | folder layout, naming, how you do DI | **Your project wins**, even if the playbook disagrees |
-| **Invariants** — correctness and security | no SQL built by string concat, no stack traces in a response, no index as a React key | **Always applied.** A project breaking these is buggy, not different |
-
-The result is cached at `.claude/orc/patterns/<lang>-pattern.md` and copied
-**word for word** into every executor slice from then on.
-
----
-
-## 2. The run
-
-```
-> /orc-pattern
-```
-
-```
-Languages I can see in this repo:
-  express   api/          38 files      no cached pattern
-  react     web/          52 files      no cached pattern
-
-Learning a pattern reads your most recently changed files with a subagent.
-That costs tokens once, and every run after it is cheaper and more accurate.
-
-Codify which?  [both / express / react / none]
-
-> both
-```
-
-```
-Dispatching orc-pattern-codifier-sonnet-5-high (express) …
-returned as: claude-sonnet-5 / high        ✓
-
-PATTERN — express     source: reconciled     14 recent files read
-
-Conventions taken FROM YOUR CODE (the playbook lost these)
-  · routes live in api/<area>/routes.ts, handlers in the same folder
-  · every handler is `export async function`, never an arrow const
-  · errors go through next(err) — you do not try/catch in handlers
-  · money is always integer minor units (api/payments/*.ts, 6 files)
-
-Invariants KEPT from the playbook (not negotiable)
-  · no SQL string interpolation — you use parameterised queries already ✓
-  · no stack trace or raw error in a response body
-  · every route that reads :id re-checks ownership
-
-Conflicts I will not guess about (1)
-  · api/refunds/ uses try/catch in 3 handlers while api/orders/ uses
-    next(err). Most recently modified wins → next(err). Say so if that is
-    backwards and I will flip it.
-
-Written: .claude/orc/patterns/express-pattern.md
-
-Dispatching orc-pattern-codifier-sonnet-5-high (react) …
-Written: .claude/orc/patterns/react-pattern.md
-```
-
----
-
-## 3. How other lanes see it
-
-```
-$ orc pattern status express
-express   cached   2026-08-12   (exit 0)
-
-$ orc pattern status svelte
-svelte    unknown language key   (exit 2)
-          keys come from orc-pattern/references/INDEX.md — it is a framework
-          name, never a file extension
-
-$ orc pattern status go
-go        not cached   (exit 1)
-```
-
-That exit code is how `/orc-fast` decides whether it is allowed to run. It is
-a deterministic probe, never a guess and never a file search — the `.claude/`
-folder is hidden, so a plain search would say "missing" from the wrong folder.
-
----
-
-## 4. What to notice
-
-- **ORC does not codify by itself.** It sends a subagent, reads the answer,
-  and writes the cache itself.
-- **The cache survives updates.** It lives outside `templates/`, so
-  `orc update` never touches it.
-- **Ambiguity is reported once, not guessed silently.** The try/catch conflict
-  above is a real example of that rule.
-- **A brand new language folder gets the plain playbook**, marked
-  `source: generic` — there is nothing to reconcile yet.
-
----
-
-## 5. Related
-
-- The lane that requires this: [`/orc-fast`](orc-fast.md)
-- Build the other half of the knowledge: [`/orc-wiki`](../templates/skills/orc-wiki/examples/wiki-run-mock.md)
+# Mock run — `/orc-pattern`
+
+> Learns how **your** code is actually written, and caches it, so every future
+> executor writes code that looks like yours.
+
+---
+
+## 1. What it does
+
+ORC ships a generic best-practice playbook for each language (React, Vue,
+Next.js, Angular, Express, NestJS, Django, FastAPI, Go, Postgres, plus a11y and
+performance rule packs). On its own, a playbook would fight your codebase.
+
+So the pattern is a **reconciliation** of two things, with two different rules:
+
+| Rule class | Example | Who wins |
+|---|---|---|
+| **Conventions** — style and shape | folder layout, naming, how you do DI | **Your project wins**, even if the playbook disagrees |
+| **Invariants** — correctness and security | no SQL built by string concat, no stack traces in a response, no index as a React key | **Always applied.** A project breaking these is buggy, not different |
+
+The result is cached at `.claude/orc/patterns/<lang>-pattern.md` and copied
+**word for word** into every executor slice from then on.
+
+---
+
+## 2. The run
+
+```
+> /orc-pattern
+```
+
+```
+Languages I can see in this repo:
+  express   api/          38 files      no cached pattern
+  react     web/          52 files      no cached pattern
+
+Learning a pattern reads your most recently changed files with a subagent.
+That costs tokens once, and every run after it is cheaper and more accurate.
+
+Codify which?  [both / express / react / none]
+
+> both
+```
+
+```
+Dispatching orc-pattern-codifier-sonnet-5-high (express) …
+returned as: claude-sonnet-5-5 / high        ✓
+
+PATTERN — express     source: reconciled     14 recent files read
+
+Conventions taken FROM YOUR CODE (the playbook lost these)
+  · routes live in api/<area>/routes.ts, handlers in the same folder
+  · every handler is `export async function`, never an arrow const
+  · errors go through next(err) — you do not try/catch in handlers
+  · money is always integer minor units (api/payments/*.ts, 6 files)
+
+Invariants KEPT from the playbook (not negotiable)
+  · no SQL string interpolation — you use parameterised queries already ✓
+  · no stack trace or raw error in a response body
+  · every route that reads :id re-checks ownership
+
+Conflicts I will not guess about (1)
+  · api/refunds/ uses try/catch in 3 handlers while api/orders/ uses
+    next(err). Most recently modified wins → next(err). Say so if that is
+    backwards and I will flip it.
+
+Written: .claude/orc/patterns/express-pattern.md
+
+Dispatching orc-pattern-codifier-sonnet-5-high (react) …
+Written: .claude/orc/patterns/react-pattern.md
+```
+
+---
+
+## 3. How other lanes see it
+
+```
+$ orc pattern status express
+express   cached   2026-08-12   (exit 0)
+
+$ orc pattern status svelte
+svelte    unknown language key   (exit 2)
+          keys come from orc-pattern/references/INDEX.md — it is a framework
+          name, never a file extension
+
+$ orc pattern status go
+go        not cached   (exit 1)
+```
+
+That exit code is how `/orc-fast` decides whether it is allowed to run. It is
+a deterministic probe, never a guess and never a file search — the `.claude/`
+folder is hidden, so a plain search would say "missing" from the wrong folder.
+
+---
+
+## 4. What to notice
+
+- **ORC does not codify by itself.** It sends a subagent, reads the answer,
+  and writes the cache itself.
+- **The cache survives updates.** It lives outside `templates/`, so
+  `orc update` never touches it.
+- **Ambiguity is reported once, not guessed silently.** The try/catch conflict
+  above is a real example of that rule.
+- **A brand new language folder gets the plain playbook**, marked
+  `source: generic` — there is nothing to reconcile yet.
+
+---
+
+## 5. Related
+
+- The lane that requires this: [`/orc-fast`](orc-fast.md)
+- Build the other half of the knowledge: [`/orc-wiki`](../templates/skills/orc-wiki/examples/wiki-run-mock.md)

package/mock-run/orc-quick.md

@@ -1,146 +1,146 @@
-# Mock run — `/orc-quick`
-
-> Ask for anything. Three steps: look → ask once → do. It always asks you
-> which agent should run.
-
----
-
-## 1. What it does
-
-Every other lane has a fixed job. This one does not. A small fix, a question
-about how something works, a defect hunt, a dependency bump, or the review
-comments on a pull request — all the same three steps.
-
-The point of the lane is the **dispatch gate**: before every single dispatch it
-asks you which agent to use. No default. No "same as last time". No setting can
-turn it off — `opus5_only`, `fable5_*` and `rubric_bands_override` are all
-inert here, and the gate says so when they are on.
-
----
-
-## 2. The run
-
-```
-> /orc-quick the refund badge shows "pending" even after the webhook lands
-```
-
-### Q1 — Look (silent)
-
-ORC reads first and says nothing until it has something to say. It asks the
-**code graph** before it greps: one call gives the symbol, who calls it, and
-which tests reach it. The request says a behaviour is wrong, so the entry is
-sorted as a **defect** — which means the bug gets reproduced before it is
-fixed.
-
-### Q2 — Ask (one turn: questions **and** the agent choice together)
-
-```
-I looked. Here is what I found and what I need from you.
-
-  · web/refunds/RefundBadge.tsx:22 maps status → label
-  · the map has no case for `sent_to_bank`, so it falls through to "pending"
-  · api/refunds/webhook.ts:52 does write that status
-
-Two questions:
-  1  Add the missing case only, or review the whole map?
-  2  Should the badge colour change too?
-
-And which agent should do it?
-  a  orc-executor-sonnet-4-6-med    small, one file    → suggested: 1 file, no risk class
-  b  orc-executor-opus-5-low        thinks harder, about 3× the cost
-  c  other — name a model
-
-Your choice — nothing runs until you answer.
-
-> 1 just the missing case. 2 yes, amber. agent a.
-```
-
-The `→ suggested` marker always carries its reason, and it never pre-selects.
-The menu still waits for you.
-
-### Q3 — Do
-
-```
-Dispatch  orc-executor-sonnet-4-6-med
-  returned as: claude-sonnet-4-6 / medium     ✓
-
-repro red      npm test -- web/refunds/RefundBadge.test.tsx   exit 1
-               → expected "sent to bank", received "pending"
-repro green    npm test -- web/refunds/RefundBadge.test.tsx   exit 0
-
-build          ✓
-tests reached  1 file (call 1) → 3 passed
-suite          ✓  12 passed
-blast radius   1 symbol · callers 2 in 2 files · tests reach 1 · risk none
-graph          gen 18 · 1 file updated
-graph gain     paid 0.9K tokens · avoided an estimated 2–6K · measured: not yet (N=1)
-
-Entry 1 written to orc-quick/refund-badge/quick-context.md
-
-Commit these 2 files?  [yes / no]
-
-> yes
-```
-
-The red run comes first on purpose. The suite was green before the fix and is
-green after it, so the suite proves nothing about **this** bug. The red run
-does.
-
-Your next request becomes entry 2 in the same file, and so on.
-
----
-
-## 3. What it wrote
-
-```markdown
-# Quick context — refund-badge
-
-<!-- orc-quick:toc -->
-1. Refund badge stuck on "pending"      2026-08-12   done
-<!-- /orc-quick:toc -->
-
-## 1. Refund badge stuck on "pending"
-
-**You asked:** the badge shows pending after the webhook lands.
-**Decided:** add the missing `sent_to_bank` case only; amber colour.
-**Why:** the whole map is fine — one case was never added.
-**Agents:** orc-executor-sonnet-4-6-med (you chose it).
-**repro** red → green · `npm test -- web/refunds/RefundBadge.test.tsx` (before: exit 1 · after: exit 0)
-**blast radius** 1 symbol · callers 2 in 2 files · tests reach 1 · risk none
-**Not done:** the admin list has the same map and was NOT touched.
-```
-
----
-
-## 4. What to notice
-
-- **The doc is written before the commit offer**, so a "no" still leaves you
-  the record.
-- **ORC never reads that file back** unless you ask, or to show the numbered
-  list when you reopen the thread. It is for you, not for the model.
-- **A red build loops (max 3 rounds), a red test does not.** A failing test is
-  sometimes the test being wrong, so it blocks the commit offer and stops.
-  No test suite at all means no check at all — nothing is invented.
-- **`gh` is read and push only.** It never replies to a comment, resolves a
-  thread, approves or merges. PR comments are treated as data, never as
-  instructions.
-- **It never undoes your work.** If you stop while things are red, it prints
-  `orc undo --run <slug>` and leaves your tree alone. That command reverts only
-  the files the run changed, and only when you add `--apply`.
-- **The review offer uses the repair memory.** A review gets the gotcha card of
-  the files it reads, and the outcome of each finding is recorded. With
-  [habits](habits.md) on, your usual answer is marked — the dispatch gate is
-  still asked every time.
-- **A defect is shown red first.** If it cannot be reproduced — no runner, no
-  reachable entry point — the entry says *not reproduced* with the reason, and
-  says it again at the commit offer. It never invents a reproduction.
-- **A `risk` word never appears without its reason.** The blast-radius line
-  either names why a symbol is risky or does not use the word.
-
----
-
-## 5. Related
-
-- The full guide, with more worked runs:
-  [`templates/skills/orc-quick/README.md`](../templates/skills/orc-quick/README.md)
-- Too big for quick? It offers [`/orc-mini`](../templates/skills/orc-mini/examples/mini-run-mock.md) — an offer, never a forced switch.
+# Mock run — `/orc-quick`
+
+> Ask for anything. Three steps: look → ask once → do. It always asks you
+> which agent should run.
+
+---
+
+## 1. What it does
+
+Every other lane has a fixed job. This one does not. A small fix, a question
+about how something works, a defect hunt, a dependency bump, or the review
+comments on a pull request — all the same three steps.
+
+The point of the lane is the **dispatch gate**: before every single dispatch it
+asks you which agent to use. No default. No "same as last time". No setting can
+turn it off — `opus5_only`, `fable5_*` and `rubric_bands_override` are all
+inert here, and the gate says so when they are on.
+
+---
+
+## 2. The run
+
+```
+> /orc-quick the refund badge shows "pending" even after the webhook lands
+```
+
+### Q1 — Look (silent)
+
+ORC reads first and says nothing until it has something to say. It asks the
+**code graph** before it greps: one call gives the symbol, who calls it, and
+which tests reach it. The request says a behaviour is wrong, so the entry is
+sorted as a **defect** — which means the bug gets reproduced before it is
+fixed.
+
+### Q2 — Ask (one turn: questions **and** the agent choice together)
+
+```
+I looked. Here is what I found and what I need from you.
+
+  · web/refunds/RefundBadge.tsx:22 maps status → label
+  · the map has no case for `sent_to_bank`, so it falls through to "pending"
+  · api/refunds/webhook.ts:52 does write that status
+
+Two questions:
+  1  Add the missing case only, or review the whole map?
+  2  Should the badge colour change too?
+
+And which agent should do it?
+  a  orc-executor-sonnet-5-med    small, one file    → suggested: 1 file, no risk class
+  b  orc-executor-opus-5-low        thinks harder, about 3× the cost
+  c  other — name a model
+
+Your choice — nothing runs until you answer.
+
+> 1 just the missing case. 2 yes, amber. agent a.
+```
+
+The `→ suggested` marker always carries its reason, and it never pre-selects.
+The menu still waits for you.
+
+### Q3 — Do
+
+```
+Dispatch  orc-executor-sonnet-5-med
+  returned as: claude-sonnet-5-5 / medium     ✓
+
+repro red      npm test -- web/refunds/RefundBadge.test.tsx   exit 1
+               → expected "sent to bank", received "pending"
+repro green    npm test -- web/refunds/RefundBadge.test.tsx   exit 0
+
+build          ✓
+tests reached  1 file (call 1) → 3 passed
+suite          ✓  12 passed
+blast radius   1 symbol · callers 2 in 2 files · tests reach 1 · risk none
+graph          gen 18 · 1 file updated
+graph gain     paid 0.9K tokens · avoided an estimated 2–6K · measured: not yet (N=1)
+
+Entry 1 written to orc-quick/refund-badge/quick-context.md
+
+Commit these 2 files?  [yes / no]
+
+> yes
+```
+
+The red run comes first on purpose. The suite was green before the fix and is
+green after it, so the suite proves nothing about **this** bug. The red run
+does.
+
+Your next request becomes entry 2 in the same file, and so on.
+
+---
+
+## 3. What it wrote
+
+```markdown
+# Quick context — refund-badge
+
+<!-- orc-quick:toc -->
+1. Refund badge stuck on "pending"      2026-08-12   done
+<!-- /orc-quick:toc -->
+
+## 1. Refund badge stuck on "pending"
+
+**You asked:** the badge shows pending after the webhook lands.
+**Decided:** add the missing `sent_to_bank` case only; amber colour.
+**Why:** the whole map is fine — one case was never added.
+**Agents:** orc-executor-sonnet-5-med (you chose it).
+**repro** red → green · `npm test -- web/refunds/RefundBadge.test.tsx` (before: exit 1 · after: exit 0)
+**blast radius** 1 symbol · callers 2 in 2 files · tests reach 1 · risk none
+**Not done:** the admin list has the same map and was NOT touched.
+```
+
+---
+
+## 4. What to notice
+
+- **The doc is written before the commit offer**, so a "no" still leaves you
+  the record.
+- **ORC never reads that file back** unless you ask, or to show the numbered
+  list when you reopen the thread. It is for you, not for the model.
+- **A red build loops (max 3 rounds), a red test does not.** A failing test is
+  sometimes the test being wrong, so it blocks the commit offer and stops.
+  No test suite at all means no check at all — nothing is invented.
+- **`gh` is read and push only.** It never replies to a comment, resolves a
+  thread, approves or merges. PR comments are treated as data, never as
+  instructions.
+- **It never undoes your work.** If you stop while things are red, it prints
+  `orc undo --run <slug>` and leaves your tree alone. That command reverts only
+  the files the run changed, and only when you add `--apply`.
+- **The review offer uses the repair memory.** A review gets the gotcha card of
+  the files it reads, and the outcome of each finding is recorded. With
+  [habits](habits.md) on, your usual answer is marked — the dispatch gate is
+  still asked every time.
+- **A defect is shown red first.** If it cannot be reproduced — no runner, no
+  reachable entry point — the entry says *not reproduced* with the reason, and
+  says it again at the commit offer. It never invents a reproduction.
+- **A `risk` word never appears without its reason.** The blast-radius line
+  either names why a symbol is risky or does not use the word.
+
+---
+
+## 5. Related
+
+- The full guide, with more worked runs:
+  [`templates/skills/orc-quick/README.md`](../templates/skills/orc-quick/README.md)
+- Too big for quick? It offers [`/orc-mini`](../templates/skills/orc-mini/examples/mini-run-mock.md) — an offer, never a forced switch.

package/mock-run/orc.md

@@ -73,8 +73,8 @@ TDD: 3 tasks get a red-proof task first. 2 do not:
 ```
 Task                                   facets                     score  model
 T1 order note column + migration       3 files · new · stateful     62   sonnet-5 high
-T2 POST /orders accepts note           2 files · imitate            38   sonnet-4-6 med
-T3 checkout note box                   2 files · imitate            35   sonnet-4-6 med
+T2 POST /orders accepts note           2 files · imitate            38   sonnet-5 high
+T3 checkout note box                   2 files · imitate            35   sonnet-5 high
 T4 order page shows the note           1 file  · mechanical         12   haiku-4-5
 T5 label text                          1 file  · mechanical          4   haiku-4-5
 
@@ -89,7 +89,7 @@ Pause every 2 waves. OK to start?
 ```
 ▶ W1  orc-executor-sonnet-5-high (T1)
       40% … 100%   returned: build green, `npx vitest run db/` exit 0
-      answered as: claude-sonnet-5 / high          ✓ matches what I asked for
+      answered as: claude-sonnet-5-5 / high          ✓ matches what I asked for
 
 ▶ W2  two agents at the same time
       T3 asked me a question: "note max length?"  → your call:
@@ -113,7 +113,7 @@ Pause every 2 waves. OK to start?
 ### Phases 5–6 — Review, then verify
 
 ```
-Review (orc-reviewer-opus-5-med):
+Review (orc-reviewer-opus-5-low):
   P1  note is not length-checked on the server — api/orders/create.ts:44
       I re-read line 44 myself. The quote matches. Fix it?   > yes
   P3  naming nit ×2  (counted, not fixed)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@azure-id/orc",
-  "version": "2.0.2",
+  "version": "2.1.1",
   "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"