@azure-id/orc 1.8.1 → 1.9.0

package/templates/skills/orc-quick/references/context-doc.md

@@ -1,114 +1,145 @@
-# The quick context doc — shape and rules
-
-This is the file orc-quick writes after every request. It is written for a
-HUMAN to read later, in this session or a different one.
-
-## Where it goes
-
-```
-<projectRoot>/orc-quick/<slug>/quick-context.md
-```
-
-- `<slug>` is the slug of the **first** request in the thread. No date in the
-  folder name.
-- **One file per folder. Never make a second `.md` file.** No `review.md`, no
-  `diff.md`, no per-request files.
-- It sits at the project root, next to folders like `test-generator/` and
-  `learning-docs/` — never inside `.claude/`.
-
-## Rules
-
-1. **Write it BEFORE the offers** (test / review / commit). If the user walks
-   away, the entry is still complete.
-2. **Every request gets an entry** — even a read-only dig. There, the answer IS
-   the result.
-3. **Never read the body of this file.** Only two exceptions:
-   - the TOC block, when you re-open a thread;
-   - the user asks you to read it.
-4. **Never commit it.** It is not staged, ever. Do not edit `.gitignore`.
-5. One entry can hold **several dispatches**. A dig that turns into a fix is ONE
-   entry with two rows in its table.
-
-## The TOC block
-
-The top of the file has a short list between markers:
-
-```markdown
-<!-- orc-quick:toc -->
-1. Change json payload A → B                05-08-2026 14:23:10  ✅ committed a1b2c3d
-2. How does tenant scoping work?            05-08-2026 15:47:02  ℹ answered
-3. Why does /orders 500? — found & fixed    10-08-2026 09:15:44  ✅ committed 7f2e1a9
-<!-- /orc-quick:toc -->
-```
-
-**Why the markers matter.** When you open a thread again, you need to know the
-next number. You read ONLY this block — it is small and cheap. You do not read
-the entries below it. That is how "never read the doc" and "keep counting" can
-both be true.
-
-Inside one session, the count is also kept in
-`.claude/orc/run/<run-slug>/quick-checkpoint.md`. That file is run state, not
-the deliverable, so you may read it freely.
-
-**If the TOC is broken or missing:** rebuild it by scanning ONLY the lines that
-start with `## <number>.`. Do not read the text under them. Then write the block
-back between the markers. Never start a second thread because of a broken TOC.
-
-## Entry shape
-
-Use as many of these as apply. Leave out what does not fit.
-
-```markdown
-## <n>. <short title>
-**asked** DD-MM-YYYY HH:MM:SS
-> the user's request, word for word
-
-**kind** code-change | context-dig | investigate → code-change | pr-comments | …
-**resolved intent** one or two sentences: what you actually decided to do.
-
-**clarified**
-- <question> → **Y**: <what won> · X was <what the user first said> ·
-  Z was <the other idea, and why it lost>
-
-**knowledge** wiki FRESH · docs=<paths> · pattern express@v3
-
-**dispatches**
-| # | kind | agent / model | expect | actual | result |
-|---|---|---|---|---|---|
-| 1 | recon | claude-sonnet-4-6 / medium *(ad-hoc, untraced-by-hook)* | sonnet-4-6/medium | sonnet-4-6/medium ✅ | what it found |
-| 2 | executor | `orc-executor-sonnet-4-6-med` | sonnet-4-6/medium | sonnet-4-6/medium ✅ | 3 files |
-
-**files changed** path · path · path
-
-**how it was resolved** a short, plain explanation of the fix and WHY this way.
-Say what you did not do, and why. This is the most useful part later.
-
-**build** GREEN · **tests** 41 passed
-**unmet** things you did not do, on purpose or not
-
-**follow-through** tests · review result · commit hash · pushed or not
-```
-
-For PR work, also add:
-
-```markdown
-**pr** #142 "title" · branch · url
-
-**threads taken** 2 of 3
-| # | reviewer | anchor | comment |
-|---|---|---|---|
-| 1 | @dana | src/routes/export.js:34 | the comment text |
-
-**github writes** NONE — no reply, no resolve, no review.
-```
-
-## Writing style for entries
-
-Write for a person who comes back in three weeks and forgot everything.
-
-- Use plain words. Short sentences.
-- Always name real files and line numbers.
-- Say **why** you chose one option and not the other. A rejected idea with its
-  reason saves the next person from trying it again.
-- Record what you did NOT do. "Backfill not done — user asked to leave it" is
-  more useful than silence.
+# The quick context doc — shape and rules
+
+This is the file orc-quick writes after every request. It is written for a
+HUMAN to read later, in this session or a different one.
+
+## Where it goes
+
+```
+<projectRoot>/orc-quick/<slug>/quick-context.md
+```
+
+- `<slug>` is the slug of the **first** request in the thread. No date in the
+  folder name.
+- **One file per folder. Never make a second `.md` file.** No `review.md`, no
+  `diff.md`, no per-request files.
+- It sits at the project root, next to folders like `test-generator/` and
+  `learning-docs/` — never inside `.claude/`.
+
+## Rules
+
+1. **Write it BEFORE the offers** (test / review / commit). If the user walks
+   away, the entry is still complete.
+2. **Every request gets an entry** — even a read-only dig. There, the answer IS
+   the result.
+3. **Never read the body of this file.** Only two exceptions:
+   - the TOC block, when you re-open a thread;
+   - the user asks you to read it.
+4. **Never commit it.** It is not staged, ever. Do not edit `.gitignore`.
+5. One entry can hold **several dispatches**. A dig that turns into a fix is ONE
+   entry with two rows in its table.
+
+## The TOC block
+
+The top of the file has a short list between markers:
+
+```markdown
+<!-- orc-quick:toc -->
+1. Change json payload A → B                05-08-2026 14:23:10  ✅ committed a1b2c3d
+2. How does tenant scoping work?            05-08-2026 15:47:02  ℹ answered
+3. Why does /orders 500? — found & fixed    10-08-2026 09:15:44  ✅ committed 7f2e1a9
+<!-- /orc-quick:toc -->
+```
+
+**Why the markers matter.** When you open a thread again, you need to know the
+next number. You read ONLY this block — it is small and cheap. You do not read
+the entries below it. That is how "never read the doc" and "keep counting" can
+both be true.
+
+Inside one session, the count is also kept in
+`.claude/orc/run/<run-slug>/quick-checkpoint.md`. That file is run state, not
+the deliverable, so you may read it freely.
+
+**If the TOC is broken or missing:** rebuild it by scanning ONLY the lines that
+start with `## <number>.`. Do not read the text under them. Then write the block
+back between the markers. Never start a second thread because of a broken TOC.
+
+## Entry shape
+
+Use as many of these as apply. Leave out what does not fit.
+
+```markdown
+## <n>. <short title>
+**asked** DD-MM-YYYY HH:MM:SS
+> the user's request, word for word
+
+**kind** code-change | context-dig | investigate → code-change | pr-comments | …
+**resolved intent** one or two sentences: what you actually decided to do.
+
+**clarified**
+- <question> → **Y**: <what won> · X was <what the user first said> ·
+  Z was <the other idea, and why it lost>
+
+**knowledge** wiki FRESH · docs=<paths> · pattern express@v3
+
+**dispatches**
+| # | kind | agent / model | expect | actual | result |
+|---|---|---|---|---|---|
+| 1 | recon | `orc-recon-sonnet-4-6-med` | sonnet-4-6/medium | sonnet-4-6/medium ✅ | what it found |
+| 2 | executor | `orc-executor-sonnet-4-6-med` | sonnet-4-6/medium | sonnet-4-6/medium ✅ | 3 files |
+
+Only an **other** dispatch keeps the `*(ad-hoc, untraced-by-hook)*` mark. A
+dispatch of either pinned recon agent is a normal row with the agent's name.
+
+**files changed** path · path · path
+
+**repro** red → green · `npm test -- tests/orders.search.test.js` (before: exit 1 · after: exit 0)
+**blast radius** 3 symbols · callers 7 in 4 files · tests reach 2 · risk high: searchByItemPrefix (exported, fan-in 4, no test reaches it)
+**tests** reached 12 passed · suite 41 passed
+**graph** gen 42 · cards 2 · <the `orc graph gain` line, word for word>
+
+**how it was resolved** a short, plain explanation of the fix and WHY this way.
+Say what you did not do, and why. This is the most useful part later.
+
+**build** GREEN · **tests** 41 passed
+**unmet** things you did not do, on purpose or not
+
+**follow-through** tests · review result · commit hash · pushed or not
+```
+
+For PR work, also add:
+
+```markdown
+**pr** #142 "title" · branch · url
+
+**threads taken** 2 of 3
+| # | reviewer | anchor | comment |
+|---|---|---|---|
+| 1 | @dana | src/routes/export.js:34 | the comment text |
+
+**github writes** NONE — no reply, no resolve, no review.
+```
+
+These four lines are optional and go in that order, after `**files changed**`.
+Leave out the ones that do not apply:
+
+- **`repro`** — only on a defect entry. `repro: none` writes
+  `**repro** not reproduced — <the reason>` instead. Never leave it out to keep
+  the entry tidy: an unreproduced fix is the thing the reader most needs to know.
+- **`blast radius`** — a `risk` word NEVER appears without its `why`. Nothing in
+  the graph → `none indexed (<n> files not in the graph)`.
+- **`graph`** — the gain line is an estimate with a range. Copy it; never turn
+  it into a saving.
+
+## A read-only entry
+
+A dig has no files, no build and no tests. It still gets a full entry:
+
+- **`how it was resolved`** holds the recon `answer`.
+- **`unmet`** holds the recon `unresolved[]`.
+- A blast-radius dig lists the four caller classes apart — `direct`, `route`
+  (reached through a URL), `via_alias`, `inherited` — and, when any list rests
+  on the graph alone, the sentence the agent returned, word for word:
+  *A card lists every caller that NAMES the symbol. A card's silence is not
+  proof of absence.*
+
+## Writing style for entries
+
+Write for a person who comes back in three weeks and forgot everything.
+
+- Use plain words. Short sentences.
+- Always name real files and line numbers.
+- Say **why** you chose one option and not the other. A rejected idea with its
+  reason saves the next person from trying it again.
+- Record what you did NOT do. "Backfill not done — user asked to leave it" is
+  more useful than silence.

package/templates/skills/orc-quick/references/defect.md

@@ -0,0 +1,101 @@
+# A defect entry shows the bug RED first
+
+## 1. When this applies
+
+Q1 sorted the request as **`kind: defect`**. The user described a behaviour that
+is wrong:
+
+- *"the orders page returns 500"*
+- *"it shows the wrong total"*
+- *"find it and fix it"*
+- *"this used to work last week"*
+
+A request to ADD something is not a defect. A request to clean something up is
+not a defect. Only a behaviour the user says is wrong.
+
+## 2. Why red first
+
+Without a reproduction, the fix is proven against the **test suite**. With one,
+the fix is proven against the **bug**.
+
+Those are not the same thing. A suite that was green before the fix is still
+green after a fix that changed nothing the user cares about. A reproduction that
+goes from red to green is the only cheap proof that the thing the user reported
+is the thing that got fixed.
+
+It costs one extra run of one command. It is the cheapest correctness step in
+this lane.
+
+## 3. What goes in the slice
+
+```yaml
+repro:
+  required: true
+  kind: test | command
+  hint: "GET /orders/search?item=blue returns 500 — see src/routes/orders.js:16"
+```
+
+- **`kind: test`** when the project has a test runner. The executor writes a
+  failing test in the project's own framework.
+- **`kind: command`** when it has none. The executor writes a command that shows
+  the fault — a `curl`, a script, a one-line node call.
+
+**A good `hint` is specific.** Give the exact input the user described and the
+`file:line` your dig found:
+
+| Weak | Good |
+|---|---|
+| "search is broken" | `GET /orders/search?item=blue` returns 500 — `src/routes/orders.js:16` |
+| "the total is wrong" | cart with 2 × 4.99 shows 9.99, not 9.98 — `src/cart/total.js:22` |
+
+## 4. Who writes it
+
+**The executor writes the reproduction, in the SAME slice as the fix. Never
+you.**
+
+A reproduction written by the orchestrator and handed over is a sketch the
+executor has to trust. One written by the executor is a thing it ran and
+watched fail. The second is worth something; the first is a longer slice.
+
+## 5. What comes back
+
+```yaml
+repro:
+  command: "npm test -- tests/orders.search.test.js"
+  before: { exit_code: 1, tail: "…" }
+  after:  { exit_code: 0, tail: "…" }
+```
+
+Two of these are malformed returns, and both are treated as a failure
+(`../../_shared/return-validation.md` §5d):
+
+- `status: done` with `before.exit_code` of 0 — it was never red, so nothing was
+  reproduced.
+- `status: done` with `after.exit_code` not 0 — it is still red, so nothing was
+  fixed.
+
+Print both runs, two lines, and emit `REPRO red :: <cmd> exit=<n>` and
+`REPRO green :: <cmd> exit=0` into the record.
+
+## 6. When it cannot be reproduced
+
+Sometimes there is no runner and no reachable entry point. Sometimes the fault
+needs production data.
+
+```yaml
+repro: none
+reason: "no test runner, and the failing path needs a live Stripe webhook"
+```
+
+**That is an honest return, not a failure.** But it changes what the user is
+told. The entry says **not reproduced** with the reason, and the commit offer
+shows it on its own line:
+
+```
+commit? — 2 files changed
+⚠ not reproduced: no test runner, and the failing path needs a live Stripe webhook
+```
+
+A user who knows the fix was never seen to work can decide to test it by hand.
+A user who was not told cannot. **Never invent a reproduction to fill the
+field.**

package/templates/skills/orc-quick/references/dispatch-gate.md

@@ -11,7 +11,7 @@ what is about to be spent, before it is spent.
 | Kind | Offer | Traced by the hook | Downgrade check |
 |------|-------|--------------------|-----------------|
 | Writes code | `orc-executor-sonnet-4-6-med` · `orc-executor-opus-5-low` · **a third option when a `quick-executor` position is held** | yes | yes (a foreign return has no `actual_model` — §2b) |
-| Read only (recon) | ad-hoc **model + effort** | no | yes (self-report) |
+| Read only (recon) | `orc-recon-sonnet-4-6-med` · `orc-recon-opus-5-low` · **other — name a model** | yes · yes · no | yes |
 | Review | `orc-reviewer-opus-5-med` · or ad-hoc | yes / no | yes |
 | Build repair, round 1–2 | *reused — not asked* | yes | yes |
 | Build repair, round 3 | asked again | yes | yes |
@@ -22,7 +22,9 @@ what is about to be spent, before it is spent.
 Which executor for entry 2 — "add retry header"?
 
   1. orc-executor-sonnet-4-6-med    cheap, fits a 3-file change
-  2. orc-executor-opus-5-low        thinks harder, about 3× the cost
+  2. orc-executor-opus-5-low        thinks harder, about 3× the cost   → suggested: callers 9 in 5 files
+
+Your choice — nothing runs until you answer.
 ```
 
 Give a short reason next to each one, based on what the dig found. The user
@@ -73,34 +75,63 @@ answers.
 
 ### Read-only work (recon)
 
-Suggest a model and an effort. Let the user change either one.
+Recon is a **pinned pair**. Both agents answer ONE question with `file:line`
+evidence and return the same fields, so the user is choosing a model, nothing
+else.
 
 ```
-Entry 3 is a context dig. What should look into it?
+Entry 3 is a context dig. Which agent should look?
 
-  model    claude-sonnet-4-6      (suggested — finding things, not deciding)
-  effort   medium                 (suggested)
+  1. orc-recon-sonnet-4-6-med     finding things, not deciding      → suggested
+  2. orc-recon-opus-5-low         a wide or subtle question
+  3. other — name a model (effort follows your session; not traced by the hook)
 
-  accept / change / cancel
+Your choice — nothing runs until you answer.
 ```
 
-This is an **ad-hoc** dispatch: you name the model and effort directly instead
-of using an agent file. That is on purpose — recon is cheap and varied, and a
-new agent file for every combination is not worth it.
-
-**The cost of ad-hoc, and what you do about it.** The trace hook only sees
-agents whose name starts with `orc-`. So it writes no `SPAWN` or `RETURN` line
-for an ad-hoc dispatch. Two of the three signals still work, because YOU write
-them, not the hook:
-
-- You still emit `DISPATCH model=… effort=… adhoc=true` and `VERIFY` into the
-  trace packet.
-- The downgrade check still works, because the slice tells the agent to report
-  its own `actual_model` and `actual_effort`.
-
-What is truly lost: `/orc-retro` cannot count these runs. That is fine —
-orc-quick has no score bands to tune. Mark the row
-`*(ad-hoc, untraced-by-hook)*` in the doc so a human can see the gap.
+**Why a pair and not an ad-hoc model.** Ad-hoc was cheap and varied, and the
+price was measured: the trace hook only sees an agent whose name starts with
+`orc-`, so an ad-hoc recon wrote no `SPAWN` or `RETURN` line, `orc run inflight`
+could not see it in flight, and `/orc-retro` could not count it. The pair fixes
+all three at once and gives recon a return contract the gate can check.
+
+**Line 3 is the escape hatch, and it names a MODEL only.** The Agent tool takes
+a per-call model and has no per-call effort knob, so an "effort" option there
+was a setting that did not exist; effort follows your session. An `other`
+dispatch is still untraced by the hook, and two of the three signals still work
+because YOU write them:
+
+- You still emit `DISPATCH model=… adhoc=true` and `VERIFY` into the trace packet.
+- The downgrade check still works: the slice tells the agent to report its own
+  `actual_model` and `actual_effort`.
+
+What is truly lost is `/orc-retro` aggregation. Mark the row
+`*(ad-hoc, untraced-by-hook)*` in the doc so a human can see the gap. A dispatch
+of either pinned agent is a normal row with the agent's name.
+
+## The suggestion
+
+One line on a menu MAY carry `→ suggested`. It is a recommendation with its
+reason attached, the same shape every ORC question uses
+(`../../_shared/interview.md`). **It is never a pre-selection and never a
+default**, and the menu still ends with
+`Your choice — nothing runs until you answer.`
+
+The reason comes from the dig, never from a feeling. Suggest
+`orc-executor-opus-5-low` when ANY of these holds:
+
+| Suggest the stronger executor when | Because |
+|---|---|
+| confident callers of the files to change ≥ 8 (from the dig, or from `orc graph changes`) | the change is felt in more places than a cheap pass checks |
+| a risk class is visible: auth · money · migration · security · concurrency · data-integrity | the same six classes the full lane's planner floors to 70 |
+| more than 3 files will really change | the cheap executor's sweet spot is a 1–3 file change |
+| **otherwise** → `orc-executor-sonnet-4-6-med` | the boring choice for a mechanical edit |
+
+**Always print the reason beside the marker.** A marker with no reason is a
+default wearing a recommendation's clothes, and rule 1 forbids it.
+
+For recon, the suggestion is simpler: `orc-recon-sonnet-4-6-med` finds things;
+`orc-recon-opus-5-low` is for a wide or a subtle question.
 
 ## Rules