@azure-id/orc 2.1.0 → 2.1.1

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

@@ -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-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)
+# 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-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
+
+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": "2.1.0",
+  "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"