@azure-id/orc 0.55.0

package/mock-run/orc-boundary.md

@@ -0,0 +1,356 @@
+# Mock run — `/orc-boundary`
+
+> The lane that says what the AI should **not** try here, and why.
+
+---
+
+## 1. What it does
+
+Every AI coding skill in the world assumes the answer to *"should the AI do
+this?"* is **yes**.
+
+Research says this is expensive. Agents that do not know their limits spend
+**5 to 50 times longer** than a human expert, and most of that time is spent on
+work that was never going to succeed. When you teach an agent to stop early,
+performance goes up about **20%** and the wasted time drops about **80%**.
+
+Nobody has shipped this as a skill. `/orc-boundary` ships it.
+
+It gives one of three answers for each piece of work:
+
+| Verdict | Easy English |
+|---|---|
+| **EXECUTE** | Let the agent do it. It can check its own work here. |
+| **ESCALATE** | Let the agent do it, but a named human must look before ship. |
+| **REFUSE** | The agent should not try this. Here is what must change first. |
+
+**A REFUSE always says what would make it a yes.** "No" with no "unless" is not
+a boundary. It is just a shrug. ORC never does that.
+
+### How ORC decides — no guessing
+
+The verdict comes from four questions, and ORC already has a real answer to all
+four. It does not ask the model to feel it out.
+
+| Question | How ORC answers it, for real |
+|---|---|
+| Can the agent **check its own work**? | Does a test runner exist? Does the build run? Is there a smoke gate? |
+| Does the agent **know this area**? | `orc wiki status` coverage · `orc pattern status <lang>` · past traces that touched these files |
+| Is it **easy to undo**? | Is it a DB migration, a live payment call, a published package, a deleted row? |
+| Is it a **decision, not a fact**? | `_shared/interview.md` already draws this line. A decision belongs to the human. |
+
+---
+
+## 2. The run
+
+Rina has a plan from `/orc-plan`. 12 tasks. She wants to know what is safe to
+hand to the agent before she starts an expensive run.
+
+```
+> /orc-boundary plan.md
+```
+
+```
+ORC · boundary
+
+Preflight (silent probes)
+  wiki status       : FRESH — 12 docs
+  pattern status    : typescript → cached
+  test runner       : vitest  (npm test)          → the agent CAN check itself
+  build             : npm run build works
+  git remote        : origin (github)
+  past traces       : 31 runs, 9 touched api/payments
+  pact ledger       : 4 holding · 2 uncheckable
+
+Reading plan.md — 12 tasks, 4 waves.
+Looking at each task. Read-only. I will not change any file.
+```
+
+```
+ORC · boundary · verdicts
+
+EXECUTE — 8 tasks
+  T01  Add a partial-refund field to the refund form         web/refunds/
+  T02  Add the partial amount to the refund API type         api/refunds/
+  T03  Translate the 4 new labels                            web/locales/
+  T05  Add a unit test for the partial amount                api/refunds/
+  T06  Show the partial amount on the receipt                web/receipt/
+  T08  Add a red proof for the 45-day window                 api/refunds/
+  T10  Update the refund docs page                           docs/
+  T11  Add the new field to the admin table                  web/admin/
+
+  Why these are safe: tests exist for all of them, the wiki covers these
+  folders, and every change can be undone with `git revert`.
+
+ESCALATE — 3 tasks
+  T04  Change the refund payout target
+       reason  : PACT-006 covers this file and is UNCHECKABLE.
+                 The agent can write the code but cannot prove it is right.
+       who     : Rina (code) + Finance (behaviour)
+       when    : before ship, not before the wave
+
+  T07  Add a rate limit to POST /refunds
+       reason  : no load test exists. The agent can set a number but cannot
+                 tell you if that number is correct for real traffic.
+       who     : Rina
+       when    : before ship
+
+  T09  Call the Stripe refund API with the partial amount
+       reason  : this reaches a third party and moves real money.
+                 The sandbox key is present, so the agent can work — but a
+                 human must confirm the amount rounding before it goes live.
+       who     : Rina
+       when    : before ship
+
+REFUSE — 1 task
+  T12  Backfill partial_amount on 1.4M old refund rows
+       reason 1: this is a DB migration that writes to production data.
+                 It cannot be undone with git.
+       reason 2: no rollback migration exists in db/migrations/.
+       reason 3: no staging database is configured in config/app.yaml.
+
+       This becomes EXECUTE when ALL THREE are true:
+         [ ] a down-migration file exists next to the up-migration
+         [ ] config/app.yaml has a staging database URL
+         [ ] the backfill is written to run in batches with a resume point
+
+       Until then this is a human task. I can still WRITE the migration
+       for you as a draft that nobody runs — ask me and I will.
+```
+
+```
+ORC · boundary · cards
+
+Wrote 3 boundary cards:
+  .claude/orc/boundary/api-refunds.md
+  .claude/orc/boundary/api-payments.md
+  .claude/orc/boundary/db-migrations.md
+
+A card is per AREA, not per task. So the next run reads the card instead of
+thinking about this again. Cards go stale the same way a wiki doc does — only
+when the files they cover actually change.
+
+Trace: run-boundary-partial-refunds-100826-161240.txt
+```
+
+---
+
+## 3. The file it made
+
+### `.claude/orc/boundary/db-migrations.md`
+
+```markdown
+---
+area: db/migrations
+anchored_files:
+  - db/migrations/**
+  - config/app.yaml
+verified_commit: c273793
+generated_by: orc-boundary
+generated_at: 2026-08-10T16:12:40Z
+default_verdict: REFUSE
+---
+
+# Boundary card — db/migrations
+
+## Default verdict: REFUSE
+
+The agent should not run a migration in this repo yet.
+
+## Why
+
+| Check | Result | Evidence |
+|---|---|---|
+| Can the agent verify itself? | **No** | No migration test job. `npm test` does not touch the DB. |
+| Does the agent know this area? | Partly | Wiki covers the schema, not the migration process. |
+| Is it easy to undo? | **No** | No down-migration in any of the 7 files in `db/migrations/`. |
+| Is it a human decision? | Partly | Data loss on production is not the agent's call. |
+
+## What would change the verdict
+
+This area becomes **ESCALATE** when:
+- [ ] every migration file has a matching down-migration
+- [ ] `config/app.yaml` declares a `staging.database_url`
+
+This area becomes **EXECUTE** when the two above are true **and**:
+- [ ] a CI job runs migrations up and down against a throwaway database
+
+## What the agent MAY still do here
+
+- Write a migration file as a draft. Nobody runs it.
+- Read migrations to understand the schema.
+- Suggest the down-migration that is missing.
+
+## Not covered by this card
+
+`db/seeds/` — that is fixture data, graded separately. See
+`.claude/orc/boundary/db-seeds.md`.
+```
+
+---
+
+## 4. The CLI part
+
+```
+$ orc boundary status
+```
+
+```
+BOUNDARY · shopcart
+
+  api/refunds      ESCALATE   card fresh   (2 open preconditions)
+  api/payments     EXECUTE    card fresh
+  db/migrations    REFUSE     card fresh   (3 open preconditions)
+  web/             EXECUTE    card fresh
+  config/          ESCALATE   card STALE   → 4 commits since c273793
+
+  4 areas ready · 1 card needs a refresh
+```
+
+Exit code: `2` — because at least one area is REFUSE.
+
+**The exit codes:**
+
+| Code | Meaning |
+|---|---|
+| 0 | Everything in scope is EXECUTE |
+| 1 | At least one ESCALATE |
+| 2 | At least one REFUSE |
+| 3 | No card, or the card is stale |
+
+```
+$ orc boundary status db/migrations --json
+```
+
+```json
+{
+  "area": "db/migrations",
+  "verdict": "REFUSE",
+  "card_present": true,
+  "card_stale": false,
+  "verified_commit": "c273793",
+  "reasons": [
+    { "check": "self_verification", "pass": false, "evidence": "no migration test job" },
+    { "check": "reversible", "pass": false, "evidence": "no down-migration in db/migrations/" },
+    { "check": "domain_known", "pass": "partial", "evidence": "wiki covers schema, not process" }
+  ],
+  "preconditions": [
+    { "to_reach": "ESCALATE", "items": ["down-migration for every file", "staging.database_url in config/app.yaml"] },
+    { "to_reach": "EXECUTE", "items": ["CI job runs migrations up and down"] }
+  ],
+  "allowed_anyway": ["write a draft migration", "read migrations", "suggest a missing down-migration"],
+  "exit": 2
+}
+```
+
+---
+
+## 5. Inside a normal `/orc` run
+
+**Phase 1 — preflight.** One new line.
+
+```
+Preflight
+  wiki      : FRESH
+  pattern   : typescript cached
+  pact      : 4 holding · 2 uncheckable
+  boundary  : 8 execute · 3 escalate · 1 refuse      ← new
+```
+
+**Phase 3 — waves.** This is where it saves money.
+
+With `boundary_gate: block`:
+
+```
+Wave 3 of 4 — dispatching 3 tasks
+
+  T09  Stripe partial refund call        → orc-executor-opus-5-high   [ESCALATE]
+  T11  Admin table column                → orc-executor-sonnet-5-high [EXECUTE]
+  T12  Backfill 1.4M rows                → NOT DISPATCHED             [REFUSE]
+
+  T12 was lifted out of this wave.
+  Reason: db/migrations card says REFUSE — no down-migration, no staging DB.
+  It is now in the handback list. The wave continues without it.
+
+  This saved an estimated 1 executor dispatch at opus-5-high
+  (~38k tokens) that would have produced code nobody could safely run.
+```
+
+At the end of the run:
+
+```
+Ship
+
+  Shipped: 11 tasks
+  Handed back to you: 1 task
+
+  T12  Backfill partial_amount on 1.4M old refund rows
+       I did not attempt this. Here is what to do:
+         1. Write db/migrations/0009_backfill_partial.down.sql
+         2. Add staging.database_url to config/app.yaml
+         3. Re-run `orc boundary status db/migrations` — it should say ESCALATE
+         4. Then `/orc-quick` can do the backfill with you watching
+
+  ESCALATE items that need your eyes before merge:
+       T04  refund payout target      → PACT-006 has no test
+       T07  rate limit number         → no load test
+       T09  Stripe amount rounding    → real money
+```
+
+### The three settings
+
+```yaml
+boundary_gate: off | warn | block
+```
+
+- `off` — the lane still works when you call it. `/orc` ignores it.
+- `warn` (**default**) — the task is still dispatched, but the card goes into
+  the slice so the executor knows the risk.
+- `block` — a REFUSE task is never dispatched.
+
+Default is `warn` because `block` changes how existing runs behave, and a
+surprise on upgrade is bad. Move to `block` one release later.
+
+### It also fixes `/orc-route`
+
+```
+$ /orc-route plan.md
+```
+
+```
+Recommended lane: /orc
+
+  /orc-fast    NOT POSSIBLE
+               reason: the plan has 1 REFUSE task and 3 ESCALATE tasks.
+               orc-fast has one executor and no review phase. It cannot
+               hold an escalation.
+```
+
+Before `/orc-boundary`, routing could only count tasks and scores. Now it can
+say *why a lane is not allowed*.
+
+---
+
+## 6. Why this is good for ORC
+
+**It is the only lane in the world that does this.** The research is published
+and measured. The skill does not exist. ORC would be first, and the claim is
+easy to say out loud: *"ORC is the only agent that tells you what it should not
+try."*
+
+**It saves real money on every run.** A REFUSE task is a dispatch that never
+happens. In the mock above that is one `opus-5-high` executor — the most
+expensive band ORC has. The lane pays for itself the first time it stops one.
+
+**It uses probes ORC already has.** No new machinery. `orc wiki status`,
+`orc pattern status`, the smoke gate, the trace corpus, the pact ledger. Every
+input already ships. This is why ORC can build it in weeks and a standalone
+skill cannot build it at all.
+
+**It makes the other lanes smarter for free.** `/orc-route` gets a hard
+constraint. `/orc-ultra`'s judge gets something to score against. `/orc-quick`
+can show the card at its dispatch gate. One lane, four upgrades.
+
+**It answers the question every manager is asking in 2026.** *"How much should
+I let the AI do?"* Right now the honest answer everywhere is "try it and see".
+ORC would give a per-area answer with evidence and a checklist.

package/mock-run/orc-brainstorm.md

@@ -0,0 +1,177 @@
+# Mock run — `/orc-brainstorm`
+
+> For when you do not have the idea yet. It makes the options. **You** pick.
+
+---
+
+## 1. What it does
+
+`/orc-grill` sharpens one idea you already have. `/orc-brainstorm` is for the
+step before that: you have a problem, a goal, or a hunch, and no candidates.
+
+It works in two halves:
+
+- **Diverge** — it generates a lot of ideas on purpose, using named thinking
+  lenses, and says **nothing bad about any of them yet**. An objection said too
+  early kills the three ideas that would have come after it.
+- **Converge** — judgment comes back on. Every idea is stress-tested, then ORC
+  recommends one and **waits**.
+
+It does not have to be about code. A product name, an onboarding flow, or a
+support-queue problem are all fine.
+
+---
+
+## 2. The run
+
+```
+> /orc-brainstorm our refund support tickets keep growing and I don't know why
+```
+
+### B1 — Frame
+
+```
+Before I generate anything, let me pin the problem.
+
+  Problem     refund tickets are growing
+  Better      fewer tickets per 100 refunds, not faster replies
+  Fixed       we cannot change the bank's 3–5 day settlement
+  Free        anything in web/, api/, and the emails we send
+
+Is that the problem, or did I frame it wrong?
+
+> right, but also: support says most tickets are "where is my money"
+```
+
+### B2 — Diverge (no criticism here, on purpose)
+
+```
+Lens 1 — Inversion: how would we make this WORSE?
+  1  Say "refunded" the moment the button is pressed, then go silent
+  2  Send no email at all
+  3  Hide refund status behind a login wall
+
+  (Flipping each of those gives us:)
+  4  Tell the truth about the 3–5 days, in the moment of the refund
+  5  Send one email when the bank confirms
+  6  A public refund status link, no login
+
+Lens 2 — Analogy: what does a parcel company do?
+  7  A tracking page with 3 fixed steps and a date range
+  8  A "still on time" message that appears BEFORE anyone worries
+  9  One number to look up on the front page
+
+Lens 3 — This repo's own history:
+  10 We already built order tracking (wiki/orc-feature-orders.md). Reuse it
+     for refunds instead of building a second thing.
+  11 gotcha #7: we tried customer-facing ETAs once and support hated them
+     because the ETA was wrong. Any ETA must be a range, not a date.
+
+Lens 4 — Constraint flip: what if support could not answer tickets at all?
+  12 The refund email answers the question before it is asked
+  13 A canned reply that is one click and always correct
+
+That is 13 candidates across 4 lenses. More? Or shall I cluster?
+  · anything of your own to add — say it and it goes in the pool as #14
+
+> add: let support see the bank reference number. cluster after that.
+
+  14 (yours) support sees the bank reference number
+```
+
+### B3 — Cluster
+
+```
+4 directions. Every one of the 14 candidates is in exactly one of them, or
+in the graveyard with a reason.
+
+| Direction | The bet | Must be true | Costs | Kills |
+|---|---|---|---|---|
+| A Tell the truth early | People ask because we implied it was instant | Customers accept 3–5 days if told up front | Small: copy + one state | The word "instant" in marketing |
+| B Tracking page | People want to look, not to ask | They will visit a link | Medium: reuse order tracking (#10) | A second status system |
+| C Arm support | Tickets are fine, answering is slow | Support is the bottleneck, not the customer | Small | Nothing |
+| D Do nothing visible, fix the email | One good email removes the question | The email is opened | Smallest | — |
+
+Graveyard
+  #3  hide behind login — makes the problem worse, kept only as an inversion
+  #9  front-page lookup — no. YAGNI for our volume.
+```
+
+### B4 — Stress (judgment back on)
+
+```
+A · pre-mortem: "it failed because we told people 3–5 days and the bank took 9."
+    worst  a truthful message that is still wrong
+    best   ticket volume drops without any new screen
+    repo   gotcha #7 applies. Use a range, never a date.
+
+B · pre-mortem: "we built a page nobody visited."
+    worst  a second status system to maintain
+    best   support links it and stops typing the same reply
+    repo   order tracking already exists — this is cheaper than it looks
+
+C · pre-mortem: "support got faster at answering a question we caused."
+    worst  we optimise the symptom
+    best   immediate relief this week
+
+D · pre-mortem: "the email went to spam."
+```
+
+### B5 — Converge (ORC recommends, then stops)
+
+```
+Recommendation: A first, then B.
+
+Why: A is the cheapest thing that attacks the cause, and B is nearly free
+because #10 lets us reuse order tracking. C treats the symptom — but it is
+one afternoon, so do it alongside if support is drowning now.
+
+  1  A
+  2  A then B          ← my recommendation
+  3  B only
+  4  C only
+  5  something else, or combine — say it in your own words
+
+> 2, but the range must come from real data not a guess
+
+  constraint  any customer-facing refund ETA is a RANGE from measured
+              settlement times, never a fixed date
+  intent      tell the customer the truth at the moment of refund
+  intent      reuse the order tracking components for refunds
+```
+
+### B6 — Exit
+
+```
+Ready to write the session doc?  It saves the pick AND every direction that
+lost, with the reason.
+
+  1  Write it     → orc/brainstorming-session/refund-tickets/brainstorm-session.md
+  2  Carry into /orc-grill to sharpen direction A
+  3  Drop it
+
+> 1
+```
+
+---
+
+## 3. What to notice
+
+- **ORC never picks.** It recommends, then waits. A lane that picks its own
+  favourite has broken this lane's contract.
+- **Every menu ends with your own slot**, and it is always last. What you type
+  goes into the pool word for word and gets stress-tested like the rest.
+- **Nothing evaporates.** Every candidate lands in a direction or in the
+  graveyard **with a reason**. The most valuable part of the saved doc is *why
+  the others lost*.
+- **It stops before writing anything.** "Complete" is a proposal, never a
+  verdict.
+- **The repo's own history is a lens.** `gotcha #7` is the kind of thing no
+  generic brainstorm can give you.
+
+---
+
+## 4. Related
+
+- Sharpen the direction you picked: [`/orc-grill`](orc-grill.md)
+- Turn constraints into lasting promises: [`/orc-pact`](orc-pact.md)