@azure-id/orc 0.55.0

package/mock-run/orc-pr-setup.md

@@ -0,0 +1,126 @@
+# Mock run — `/orc-pr-setup` and `/orc-pr-driver`
+
+> One big change, split into a stack of small pull requests that each build and
+> test on their own.
+
+Two lanes, in order. **Setup** decides where the cut lines go and writes a plan.
+**Driver** takes that plan and actually creates the branches and the PRs.
+
+---
+
+## 1. `/orc-pr-setup` — where do the cuts go?
+
+```
+> /orc-pr-setup split the refund visibility change
+```
+
+```
+The change: 14 files, 980 lines added, 210 removed.
+
+Layers, bottom first. A layer may only depend on layers BELOW it.
+
+  L1  db + state enum            3 files   120 LoC   value: makes the state exist
+      db/migrations/0042_sent_to_bank.sql, api/refunds/state.ts, its test
+      why first: everything else imports this enum
+
+  L2  webhook writes the state   2 files   140 LoC   value: the state is real
+      depends on L1
+
+  L3  customer badge             4 files   260 LoC   value: customers see it
+      depends on L1 (not L2 — the badge only reads the enum)
+
+  L4  admin list + filters       5 files   410 LoC   value: support sees it
+      depends on L1
+
+One thing I am NOT sure about — I will not guess:
+
+  ❓ web/refunds/format.ts is used by BOTH L3 and L4.
+     a  put it in L1 (a "shared" layer at the bottom)
+     b  put it in L3, and L4 depends on L3
+     ➡️  I recommend (a). It makes L3 and L4 independent, so they can be
+        reviewed in parallel.
+
+> a
+
+Layer budget check: every layer is under 1000 LoC and 20 files ✓
+4 layers, under the soft cap of 6 ✓
+
+Written: stacked-pr/refund-visibility/stack-plan.md
+I have touched no branch, no commit, and no remote.
+```
+
+---
+
+## 2. `/orc-pr-driver` — build and submit the stack
+
+```
+> /orc-pr-driver
+```
+
+```
+Plan check
+  stacked-pr/refund-visibility/stack-plan.md   READY   (exit 0)
+  ticket SHOP-231 ✓ · PR template resolved ✓ · no unanswered questions ✓
+
+Snapshot taken first: your working tree is saved before anything moves.
+
+L1  branch refund/01-state
+    only L1's 3 files staged
+    GREEN GATE, at this layer's own base:
+      build ✓   tests ✓ 41 passed   lint ✓
+      (your repo's own hooks ran — never --no-verify)
+    pushed
+
+L2  branch refund/02-webhook  (base: refund/01-state)
+    GREEN GATE  ✓ ✓ ✓        pushed
+
+L3, L4 …  same shape
+
+gh stack submit
+  #412 L1 state   #413 L2 webhook   #414 L3 badge   #415 L4 admin
+  each PR body written from your template, with its layer's purpose
+```
+
+Later, when review comments land:
+
+```
+> /orc-pr-driver restack
+
+L1 got a change. Rebasing 02, 03, 04 on top, in order.
+  L2 clean · L3 clean · L4 CONFLICT in web/admin/RefundList.tsx
+  Stopping here and showing you the conflict. Nothing force-pushed yet.
+```
+
+And merging:
+
+```
+> /orc-pr-driver merge
+
+Bottom up, always: #412 first.
+  #412 approved ✓ merged
+  #413 retargeted to main, CI re-ran, ✓ merged
+  … 
+```
+
+---
+
+## 3. What to notice
+
+- **Setup never touches git.** No branch, no commit, no push. That belongs to
+  the driver.
+- **Every layer is green on its own base.** A stack where only the top builds
+  is not a stack, it is one PR wearing four hats.
+- **An uncertain cut line stops the lane.** Setup asks, one decision at a time,
+  and writes your answer into the plan.
+- **You can start at the driver.** `orc pr stack template` writes an empty plan
+  you fill in by hand — no planner run needed.
+- **Merging is bottom up, and that is not a preference.** Merging the top first
+  makes every layer below it lie about its own diff.
+
+---
+
+## 4. Related
+
+- Full guides: [ORC-PR-SETUP README](../templates/skills/orc-pr-setup/README.md) ·
+  [ORC-PR-DRIVER README](../templates/skills/orc-pr-driver/README.md)
+- ORC's own ship phase hands off here when a change is too big for one PR.

package/mock-run/orc-quick.md

@@ -0,0 +1,113 @@
+# 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.
+
+### 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)
+  b  orc-executor-opus-5-low
+  c  something else — tell me the model and effort
+
+> 1 just the missing case. 2 yes, amber. agent a.
+```
+
+### Q3 — Do
+
+```
+Dispatch  orc-executor-sonnet-4-6-med
+  returned as: claude-sonnet-4-6 / medium     ✓
+
+build   ✓
+tests   ✓  12 passed
+
+Entry 1 written to orc-quick/refund-badge/quick-context.md
+
+Commit these 2 files?  [yes / no]
+
+> yes
+```
+
+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).
+**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
+  the `git` command and leaves your tree alone.
+
+---
+
+## 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-route.md

@@ -0,0 +1,93 @@
+# Mock run — `/orc-route`
+
+> You have a plan. This tells you which lane should build it — and which lanes
+> cannot.
+
+---
+
+## 1. What it does
+
+It reads a **plan** — the numbers in it: how many tasks, how many waves, how
+many files, the top score, whether any task is marked risky. Then it checks
+ORC's own probes (is the wiki fresh, is a pattern cached, is a DIY flow ready,
+does any boundary card say REFUSE) and names **one** lane.
+
+It refuses to route a sentence. Routing from a plan is arithmetic. Routing from
+"I want to add refunds" is guessing, and a guess that looks calculated is worse
+than no answer.
+
+---
+
+## 2. The run — with a plan
+
+```
+> /orc-route .claude/orc/run/refund-visibility/plan.md
+```
+
+```
+Plan: refund-visibility — 7 tasks, 3 waves, 14 files touched
+      top score 78, two tasks marked risky (money)
+
+→ /orc          the plan has risky tasks and a task above 70;
+                review and verify are worth paying for here
+                1.23M raw · 18% of a 5-hour window on Max 20x
+
+   runner-up    /orc-mini — about 3x faster and 0.41M raw (6% of a window),
+                but it skips full review and verification. Fine only if you
+                will read the diff yourself.
+
+   not possible /orc-fast — needs a FRESH or AGING wiki (yours is STALE →
+                fix: /orc-wiki refresh) and this plan is 7 tasks; that lane
+                runs ONE task.
+
+   not possible /orc-diy — `orc diy status` exits 1 (UNCONFIGURED)
+                fix: orc diy init && orc diy compile
+
+Start /orc now?  [yes / no]
+
+> yes
+```
+
+---
+
+## 3. The run — without a plan
+
+```
+> /orc-route I want to make refunds faster
+```
+
+```
+That is a request, not a plan, so I will not route it.
+
+Routing is arithmetic over a plan's own numbers — tasks, waves, files, top
+score, risk. From a sentence I would be guessing, and a guess that looks
+calculated is the worst answer I can give you.
+
+Two ways forward:
+  · /orc-plan  "make refunds faster"   → gives you a plan, then come back
+  · /orc-grill                         → if the idea itself is still vague
+
+If you are new and just want to know which command to start with, that is
+`orc onboarding first-run`, not this lane.
+```
+
+---
+
+## 4. What to notice
+
+- **Every runner-up says what it costs you**, not just that it is cheaper.
+- **Every "not possible" names the blocking condition AND its fix.** A blocked
+  lane with no stated fix is a dead end.
+- **Cost is added only when it is knowable.** With no run history, the cost
+  column is simply absent — never a guessed number, and never a reason to
+  withhold the recommendation, which does not depend on cost.
+- **`/orc-ultra` is never a default.** It appears only when the plan itself
+  justifies it, and it says plainly that it costs the most.
+- **`/orc-plan` offers this automatically** after you choose "Save & stop".
+
+---
+
+## 5. Related
+
+- Make a plan first: [`/orc-plan`](orc-plan.md)
+- The cost numbers behind the column: [`/orc-budget`](orc-budget.md)

package/mock-run/orc-ui.md

@@ -0,0 +1,125 @@
+# Mock run — `orc ui`, the control panel
+
+> A local web page for everything in ORC that is **not** ai. It never runs a
+> lane and never calls a model.
+
+---
+
+## 🎬 Video walkthrough
+
+<!--
+  VIDEO PLACEHOLDER — the walkthrough goes right here.
+
+  1. Record the panel (`orc ui --fixtures`). Keep it under ~2 minutes.
+  2. Save it as:            mock-run/media/orc-ui-demo.mp4
+     and a still frame as:  mock-run/media/orc-ui-demo-poster.png
+  3. Replace the blockquote below with this line:
+
+       [![Watch the orc ui walkthrough](media/orc-ui-demo-poster.png)](media/orc-ui-demo.mp4)
+
+  GitHub note: a <video> tag with a repo-relative src does NOT play inline on
+  github.com. Two things that DO work:
+    · the image link above (click → opens the file), or
+    · drag the .mp4 into a GitHub issue/PR comment, copy the
+      https://github.com/user-attachments/... URL it produces, and paste that
+      URL on its own line here — GitHub renders that one as a player.
+-->
+
+> **Not recorded yet.** The two files to drop in, and the exact line to paste
+> here, are in [`media/README.md`](media/README.md).
+
+---
+
+## 1. Start it
+
+```bash
+$ orc ui
+```
+
+```
+orc ui  ·  http://127.0.0.1:9921/?t=3734924cb00ae0fe…
+  project   /home/rina/shopcart
+  token     new for this launch — the URL is the key
+  idle      shuts down after 30 minutes with no tab open
+
+Opening your browser.
+```
+
+Other ways to start it:
+
+```bash
+orc ui --port 9930     # an explicit port never auto-walks: a collision is an error
+orc ui --no-open       # print the URL only
+orc ui --idle 0        # never shut down on idle
+orc ui --fixtures      # canned data — no project needed, every state visible
+orc ui --stop          # stop this project's server (exit 0 stopped / 1 none)
+```
+
+---
+
+## 2. What is in it
+
+| Panel | Shows | Can change |
+|---|---|---|
+| **Overview** | version, `orc doctor`, wiki tier, what is waiting, and **Worth doing** — one list of everything wanting a decision | — |
+| **Settings** | every config key, grouped, each with the right control | staged edits, applied together |
+| **Runs** | run history; a row opens in place into state-of-play, resume prompt, checkpoint, trace tail | — |
+| **Knowledge** | wiki freshness and refresh scope, code patterns, gotchas, wiki debt | `wiki sync`, `gotcha prune` |
+| **Stats** | lane and agent usage, downgrades, and a **Cost** tab with a stacked token bar | — |
+| **Flow** | the compiled DIY flow, its gate, and a stepper of every phase in order | `diy set`, `diy compile`, presets |
+| **Crosslink** | Design (the boundary drawn as a graph) and Settings (each peer's freshness) | `crosslink add` / `remove` |
+| **Promises** | the pact ledger, with *"also flagged by"* when boundary and aftermath agree | `pact check`, `pact sync` |
+| **Boundary** | execute / escalate / refuse per area, and what would make a refuse a yes | — |
+| **Self-serve** | the graded surfaces a non-developer can change | `handoff set` |
+| **Mocked Skill Use** | every mocked run that ships with ORC, grouped and searchable | — |
+| **Learn** | the `orc onboarding` walkthrough, one section at a time | — |
+| **Experiment** | every lane with a copy button; opens a Claude session in a terminal | — |
+| **Maintenance** | `update`, `update --prune`, `doctor --fix`, `upgrade` | preview, then apply |
+
+---
+
+## 3. A maintenance action, start to finish
+
+```
+Maintenance ▸ Remove orphaned files
+
+  Command:   orc update --prune
+  [ Preview ]           ← Apply stays disabled until you press this
+
+  Preview (read-only, this is `orc doctor` output):
+    3 files ORC owns are no longer part of the payload:
+      .claude/agents/orc-executor-opus-4-8-med.md
+      .claude/skills/orc/references/old-scoring.md
+      .claude/commands/orc-config.md
+    Nothing else will be touched. Your config, patterns, wiki and run
+    folders are never in this list.
+
+  [ Apply ]   → confirm → the real command runs, output streams here
+```
+
+---
+
+## 4. What to notice
+
+- **The panel is the CLI.** Every number on screen came from
+  `orc <command> --json`, and every button shells the real command. It cannot
+  drift from the CLI, because it has no second copy of anything.
+- **A free action gets a button. A paid action gets a command to copy.**
+  Anything that would cost model tokens is never run from here.
+- **A prune names every file.** A count is not consent.
+- **It is treated as a write surface**: loopback only, a fresh token per
+  launch, a check against DNS rebinding, no CORS, and mutations must be POST.
+- **Project-scoped.** There is no `--global` config here. If a global install
+  exists that could win skill resolution, every page carries a banner saying
+  so — reported, never edited from here.
+- **English and Indonesian**, switched from the rail. Only the panel's own
+  words are translated: config keys, model ids, paths, commands and doctor
+  messages are printed exactly as the CLI wrote them, because a translated
+  config key is a key that does not exist.
+
+---
+
+## 5. Related
+
+- The terminal half: [`orc` CLI tour](orc-cli.md)
+- Compose a flow the panel can then edit: [`/orc-diy`](orc-diy.md)

package/mock-run/orc-ultra.md

@@ -0,0 +1,103 @@
+# Mock run — `/orc-ultra`
+
+> The same pipeline as `/orc`, plus an advisor at the start and three judges
+> along the way. It costs the most. Use it when a mistake is expensive.
+
+---
+
+## 1. What it does
+
+`/orc-ultra` adds four things to a normal `/orc` run:
+
+| Extra | When | What it is for |
+|---|---|---|
+| **Advisor** | before the analyst | Writes a brief: real risks, other ways to do it, a **security section**, and a **rubric** — the list of things a correct answer must get right here |
+| **Judge (analysis)** | after the analyst | Scores the analysis against that rubric |
+| **Judge (plan)** | after the planner | Same, for the plan |
+| **Judge (implementation)** | after verify | Did we build what was asked, at the quality asked |
+
+It also forces on: deep analysis, code patterns, test authoring, the security
+pass, and a floor on executor models. You do not configure any of that — the
+lane sets it for this run only and never writes it to your settings.
+
+---
+
+## 2. The run
+
+Rina is changing how refunds are calculated. Money code.
+
+```
+> /orc-ultra rewrite the refund amount calculation to support partial refunds
+```
+
+### Phase U0 — Advisor (runs once, before anything else)
+
+```
+Dispatching orc-advisor-opus-5-xhigh …
+returned as: claude-opus-5 / xhigh          ✓
+
+ADVISORY BRIEF — partial refunds
+
+Risks in this domain
+  · Rounding. A cent lost per refund is a real bug, not a rounding style.
+  · Double refunds. Retry + no idempotency key = money out twice.
+  · Currency. api/payments/ stores minor units; web/ formats major units.
+
+Security section (always written)
+  · The refund endpoint must re-check ownership. Today it checks the session
+    only — api/refunds/create.ts:31.
+
+RUBRIC — what a correct answer must get right here
+  R1  amounts are integers in minor units end to end
+  R2  a partial refund can never exceed the remaining refundable amount
+  R3  the operation is idempotent per refund request id
+  R4  every branch has a test with a real number in it
+
+OPEN QUESTIONS  (answer together, one round)
+  Q1  Can one order have several partial refunds?      default: yes
+  Q2  Rounding on a split refund — who gets the cent?  default: the last refund
+
+> Q1 yes.  Q2 the customer gets the cent, not us.
+```
+
+### Then the normal pipeline, with gates
+
+```
+Analyst (deep, 3 scouts) → done
+  Judge (gate=analysis): APPROVE with 1 note
+    R2 is not evidenced anywhere in the analysis. Cited section added.
+
+Planner → 6 tasks
+  Judge (gate=plan): REVISE
+    "T3 changes the refund total but has no test task. R4 fails."
+    → planner re-ran once → TDD task added → APPROVE
+
+Build → review → verify → PASSED
+  Judge (gate=implementation): APPROVE
+    R1 ✓ minor units, checked at refunds/calc.ts:18 and web/format.ts:9
+    R2 ✓ test "cannot refund more than remaining" — a real number, 1250
+    R3 ✓ idempotency key on the request row
+    R4 ✓ 9 new tests, all with numbers
+```
+
+---
+
+## 3. What to notice
+
+- **The judge can send work back, but only twice.** A REVISE loop is capped at
+  2 rounds. After that it must APPROVE, ESCALATE to you, or stop. It can never
+  argue with itself forever.
+- **A judge never fixes anything.** It reads and it votes. The author fixes.
+- **A judge never re-opens an earlier gate.** The plan judge does not re-argue
+  the analysis.
+- **The rubric came before the work.** That is the trick — the standard is
+  written by someone who has not seen the answer yet.
+- **`ultra_mode` is not a setting.** It exists only inside this command. `/orc`
+  and `/orc-mini` never turn it on.
+
+---
+
+## 4. Related
+
+- The normal pipeline: [`/orc`](orc.md)
+- What it will cost first: [`/orc-budget`](orc-budget.md)