@azure-id/orc 1.9.2 → 2.1.0

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

@@ -125,7 +125,12 @@ Your next request becomes entry 2 in the same file, and so on.
   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
-  the `git` command and leaves your tree alone.
+  `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.

package/mock-run/orc.md

@@ -1,157 +1,157 @@
-# Mock run — `/orc`
-
-> The full pipeline: understand → plan → score → build in parallel → review →
-> verify → ship.
-
-Use this when the job is a real feature, not a one-line fix.
-
----
-
-## 1. What it does
-
-`/orc` never writes code itself. It is the **coordinator**. It splits the work
-into tasks, gives each task a score from 0 to 100, and sends each task to the
-**cheapest model that can still do it**. Tasks that do not touch the same files
-run at the same time (a "wave").
-
-It writes everything to disk as it goes, so you can stop any time and come back
-tomorrow — even in a brand new chat.
-
----
-
-## 2. The run
-
-Rina wants order notes on the checkout page and a new API field.
-
-```
-> /orc add order notes: a note field on checkout, saved with the order,
-  shown on the order page
-```
-
-### Phase 0 — Intake (it asks, you sign off)
-
-```
-Run folder:  .claude/orc/run/order-notes/
-
-I read the repo: TypeScript, vitest, Express. I will not ask you about that.
-Size looks medium. Four questions, one round:
-
-  1  What must exist when this is done?
-  2  What is NOT part of this?
-  3  How will we know it works?
-  4  Any file or pattern to stay away from?
-
-> 1 note box on checkout + note saved + note shown on order page
-> 2 no editing a note after the order is placed, no admin view
-> 3 a new order keeps its note after a page reload
-> 4 follow api/orders/, do not touch api/payments/
-
-Draft written: .claude/orc/run/order-notes/intent-spec.md
-Sign-off:  gate (I stop until you approve)  or  soft?
-
-> gate
-
-Approved.
-```
-
-### Phase 1 — Planning
-
-```
-Planner: ORC's own planner.
-
-5 tasks. Every file path checked against the real repo:
-  14 of 15 paths exist. `api/orders/note_servce.ts` does NOT exist (typo).
-  → plan sent back to the planner → corrected to note_service.ts ✓
-
-TDD: 3 tasks get a red-proof task first. 2 do not:
-  T4  covered-by-existing → api/orders/orders.test.ts:120 (checked, it exists)
-  T5  no-behavior         → a string in web/locales/en.json
-```
-
-### Phase 2 — Scoring (arithmetic, not opinion)
-
-```
-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
-T4 order page shows the note           1 file  · mechanical         12   haiku-4-5
-T5 label text                          1 file  · mechanical          4   haiku-4-5
-
-Waves:  W1 {T1}   W2 {T2, T3}   W3 {T4, T5}
-Pause every 2 waves. OK to start?
-
-> yes
-```
-
-### Phase 3 — Building
-
-```
-▶ 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
-
-▶ W2  two agents at the same time
-      T3 asked me a question: "note max length?"  → your call:
-
-      > 500 characters
-
-      Answered. Both returned ✓. No two tasks touched the same file.
-
-⏸  PAUSE (2 waves done)
-   Checkpoint saved. To continue in a fresh chat, paste this:
-
-   | Continue ORC run `order-notes`.
-   | Read .claude/orc/run/order-notes/state-of-play.md, then checkpoint.json.
-   | Do not re-plan. Do not redo finished tasks.
-
-> continue
-
-▶ W3  two haiku agents → done. 5 of 5 tasks complete.
-```
-
-### Phases 5–6 — Review, then verify
-
-```
-Review (orc-reviewer-opus-5-med):
-  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)
-
-Verify (orc-verifier-opus-5-med) — against YOUR definition of done:
-  note saved         ✓  orders.test.ts:131
-  note survives F5   ✗  no test covers a reload  → P0, fixed once, re-checked ✓
-  PASSED   18/18 tests green
-```
-
-### Phase 8 — Ship
-
-```
-Branch feat/order-notes. Commit? Push? Open a PR?   > yes to all
-Ticket / title / target?   > SHOP-214 / Add order notes / develop
-
-✓ committed  ✓ pushed  ✓ PR body written from your pr.md template
-
-5 tasks · 3 waves · 5 subagents · 1 pause · 1 question to you · 0 downgrades
-```
-
----
-
-## 3. What to notice
-
-- **The orchestrator never wrote a line of code.** Even the 4-point label task
-  went to a subagent. That is what keeps it able to run for hours.
-- **A bad file path was caught before any agent started.** The planner claimed
-  `note_servce.ts`; ORC checked the disk and bounced the plan.
-- **The score picked the model, and the trace proves what answered.** Every
-  return says which model really replied, so a silent downgrade is visible.
-- **The pause is real.** It stops. It does not "keep going a bit more".
-
----
-
-## 4. Related
-
-- The dense, annotated version of this run (written for the model, not for
-  people): [`templates/skills/orc/examples/full-run-mock.md`](../templates/skills/orc/examples/full-run-mock.md)
-- Smaller job? [`/orc-mini`](../templates/skills/orc-mini/examples/mini-run-mock.md)
-- Not sure which lane? [`/orc-route`](orc-route.md)
+# Mock run — `/orc`
+
+> The full pipeline: understand → plan → score → build in parallel → review →
+> verify → ship.
+
+Use this when the job is a real feature, not a one-line fix.
+
+---
+
+## 1. What it does
+
+`/orc` never writes code itself. It is the **coordinator**. It splits the work
+into tasks, gives each task a score from 0 to 100, and sends each task to the
+**cheapest model that can still do it**. Tasks that do not touch the same files
+run at the same time (a "wave").
+
+It writes everything to disk as it goes, so you can stop any time and come back
+tomorrow — even in a brand new chat.
+
+---
+
+## 2. The run
+
+Rina wants order notes on the checkout page and a new API field.
+
+```
+> /orc add order notes: a note field on checkout, saved with the order,
+  shown on the order page
+```
+
+### Phase 0 — Intake (it asks, you sign off)
+
+```
+Run folder:  .claude/orc/run/order-notes/
+
+I read the repo: TypeScript, vitest, Express. I will not ask you about that.
+Size looks medium. Four questions, one round:
+
+  1  What must exist when this is done?
+  2  What is NOT part of this?
+  3  How will we know it works?
+  4  Any file or pattern to stay away from?
+
+> 1 note box on checkout + note saved + note shown on order page
+> 2 no editing a note after the order is placed, no admin view
+> 3 a new order keeps its note after a page reload
+> 4 follow api/orders/, do not touch api/payments/
+
+Draft written: .claude/orc/run/order-notes/intent-spec.md
+Sign-off:  gate (I stop until you approve)  or  soft?
+
+> gate
+
+Approved.
+```
+
+### Phase 1 — Planning
+
+```
+Planner: ORC's own planner.
+
+5 tasks. Every file path checked against the real repo:
+  14 of 15 paths exist. `api/orders/note_servce.ts` does NOT exist (typo).
+  → plan sent back to the planner → corrected to note_service.ts ✓
+
+TDD: 3 tasks get a red-proof task first. 2 do not:
+  T4  covered-by-existing → api/orders/orders.test.ts:120 (checked, it exists)
+  T5  no-behavior         → a string in web/locales/en.json
+```
+
+### Phase 2 — Scoring (arithmetic, not opinion)
+
+```
+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
+T4 order page shows the note           1 file  · mechanical         12   haiku-4-5
+T5 label text                          1 file  · mechanical          4   haiku-4-5
+
+Waves:  W1 {T1}   W2 {T2, T3}   W3 {T4, T5}
+Pause every 2 waves. OK to start?
+
+> yes
+```
+
+### Phase 3 — Building
+
+```
+▶ W1  orc-executor-sonnet-5-high (T1)
+      40% … 100%   returned: build green, `npx vitest run db/` exit 0
+      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:
+
+      > 500 characters
+
+      Answered. Both returned ✓. No two tasks touched the same file.
+
+⏸  PAUSE (2 waves done)
+   Checkpoint saved. To continue in a fresh chat, paste this:
+
+   | Continue ORC run `order-notes`.
+   | Read .claude/orc/run/order-notes/state-of-play.md, then checkpoint.json.
+   | Do not re-plan. Do not redo finished tasks.
+
+> continue
+
+▶ W3  two haiku agents → done. 5 of 5 tasks complete.
+```
+
+### Phases 5–6 — Review, then verify
+
+```
+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)
+
+Verify (orc-verifier-opus-5-med) — against YOUR definition of done:
+  note saved         ✓  orders.test.ts:131
+  note survives F5   ✗  no test covers a reload  → P0, fixed once, re-checked ✓
+  PASSED   18/18 tests green
+```
+
+### Phase 8 — Ship
+
+```
+Branch feat/order-notes. Commit? Push? Open a PR?   > yes to all
+Ticket / title / target?   > SHOP-214 / Add order notes / develop
+
+✓ committed  ✓ pushed  ✓ PR body written from your pr.md template
+
+5 tasks · 3 waves · 5 subagents · 1 pause · 1 question to you · 0 downgrades
+```
+
+---
+
+## 3. What to notice
+
+- **The orchestrator never wrote a line of code.** Even the 4-point label task
+  went to a subagent. That is what keeps it able to run for hours.
+- **A bad file path was caught before any agent started.** The planner claimed
+  `note_servce.ts`; ORC checked the disk and bounced the plan.
+- **The score picked the model, and the trace proves what answered.** Every
+  return says which model really replied, so a silent downgrade is visible.
+- **The pause is real.** It stops. It does not "keep going a bit more".
+
+---
+
+## 4. Related
+
+- The dense, annotated version of this run (written for the model, not for
+  people): [`templates/skills/orc/examples/full-run-mock.md`](../templates/skills/orc/examples/full-run-mock.md)
+- Smaller job? [`/orc-mini`](../templates/skills/orc-mini/examples/mini-run-mock.md)
+- Not sure which lane? [`/orc-route`](orc-route.md)

package/package.json

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