@azure-id/orc 1.9.2 → 2.1.0

package/templates/skills/orc-quick/SKILL.md

@@ -15,7 +15,7 @@ questions, dispatches one agent, and writes down what happened. **Three steps
 per request, one user turn. Fewer than any other lane. Do not add steps.**
 
 **You never implement — you spawn.** You read only to FIND the right files. To
-UNDERSTAND something, you dispatch an agent. This keeps your context small.
+UNDERSTAND something, you dispatch an agent.
 
 **It is open.** Almost any request works (`README.md` §1). For anything else:
 decide if it only READS or also WRITES → pick what to dispatch → **ask the
@@ -28,37 +28,40 @@ waves, no scoring, no acceptance pass (`README.md` §2).
 
 ## Phases
 
-`orc lane phases orc-quick --json` is this lane's pipeline: the ordered list, where
-each phase lives, and how much of it to read. **The CLI owns the order** — never
-derive it from the headings below, and never renumber or rename one without the
-manifest, because a `read: section` pointer names a HEADING and a renamed heading
-is a pointer into nothing.
+`orc lane phases orc-quick --json` is this lane's pipeline. **The CLI owns the order**:
+never derive it from the headings below, and never rename or renumber one
+without the manifest (`../_shared/lane-contract.md` §Phases).
 
 ## Q0 — Preflight (ONE time per session, silent, nothing can stop the run)
 
 1. **Config.** Read `log_dir` only. Read no other key. **One exception, and it
-   is a PROBE, not a key read:** `orc extra resolve --slot quick-executor --json`
-   (0 = extra, 1 = Claude) answers the master gate, the position and the routing
-   in one, so the code-writing menu can offer line 3. **A gate that is never
-   probed is a gate that is always off.** Keep the answer for this session; it is
-   an OPTION on a menu, never a default (`references/dispatch-gate.md`).
+   is a PROBE, not a key read:** `probes["extra-slot"]` in the `orc lane config`
+   answer (`resolved`: extra or claude) answers the master gate, the position and the
+   routing in one, so the code-writing menu can offer line 3. Do not call
+   `orc extra resolve --slot quick-executor`. **A gate that is never probed is a
+   gate that is always off.** Keep the answer for this session; it is an OPTION
+   on a menu, never a default (`references/dispatch-gate.md`). **`habits{}` in
+   that answer → print `habits.line`, read `../_shared/habits.md` NOW**; none →
+   ignore every `(H …)` mark.
 2. **Trace + the running record.** Write `log_dir/.current` =
    `run-quick-<slug>-<DDMMYY>-<HHMMSS>.txt` and `touch the trace file` of that
-   name in the SAME step. Both, or neither. Create
+   name in the SAME step. Both, or neither. Then `orc run snapshot --run <run-slug>`. Create
    `.claude/orc/run/<run-slug>/quick-checkpoint.md` in the same step too: from
    now on append every event to it WITH THE TIME IT HAPPENED (`HH:MM:SS`). Each
    trace packet is built from that file, never stamped "now".
-3. **Knowledge probes** (`../_shared/detecting-artifacts.md`; never a raw `find`
-   — `.claude` is hidden). `orc wiki status` → only `none` means no wiki.
-   `orc pattern status <lang>` → 0 cached, 1 absent, 2 wrong key; `<lang>` is a
-   framework key from `../orc-pattern/references/INDEX.md` (`express`, `react`,
-   …), never a file extension. **Both are helpful extras only:** missing
+3. **Knowledge probes** — from `probes{}` (preflight.md step 3;
+   `../_shared/detecting-artifacts.md`). `orc wiki status` → only `none` means
+   no wiki. `<lang>` is cached when
+   `probes["pattern-status"].langs` names it; `<lang>` is a framework key from
+   `../orc-pattern/references/INDEX.md` (`express`, `react`, …), never a file
+   extension. Call `orc pattern status <lang>` only when you are not sure the
+   key is a framework key. **Both are helpful extras only:** missing
    knowledge never stops the run, never causes a fallback, never triggers a
    scan. Print ONE line each.
-4. **Code graph cache — never skipped** (`../_shared/code-graph.md` §0). Run
-   `orc graph status --if-enabled --heal --json --brief`: it builds or updates the cache
-   in the same call. Print its `line`; put its `trace` (`GRAPH-CONSULT …`) in the
-   packet VERBATIM. Exit 3 = off → no other graph call this session. Every graph
+4. **Code graph cache — never skipped** (`../_shared/code-graph.md` §0). Print
+   `probes["graph-status"].line`; run
+   `orc graph status --if-enabled --heal --json --brief` only when `heal_needed` is true. Put the `trace` (`GRAPH-CONSULT …`) in
+   the packet VERBATIM. Exit 3 = off → no other graph call this session. Every graph
    call carries `--if-enabled`, so the CLI reads the `code_graph` keys —
    this lane still reads `log_dir` and nothing else.
 5. **`gh` probe — only when the request names a PR** (`pr <n>`, `PR <n>`, a
@@ -67,8 +70,7 @@ is a pointer into nothing.
    works; ask the user to paste the comments instead.
 6. Emit one `GATE` line per check — `GATE graph` included.
 
-The SHAPE of these steps is `../_shared/phases/preflight.md` (`core`); the
-probes themselves are this lane's own and stay here.
+Shape: `../_shared/phases/preflight.md` (`core`); the probes stay here.
 
 ## Q1 — LOOK (silent — no questions here)
 
@@ -89,7 +91,7 @@ rule and the never-write-to-GitHub boundary are in `references/gh-mode.md`.
 
 **Intent ledger.** Read the user's message for things they already decided —
 which agent, update tests, review, commit, push. Do not ask those again in Q3.
-Print it on ONE line so nothing is skipped in secret:
+Print it on ONE line:
 `ledger: review=yes commit=yes push=yes · test-update=ask · dispatch=ask`
 
 **The dig — graph first** (`references/look.md`). Ask the graph BEFORE any
@@ -111,7 +113,7 @@ Grep; Grep only for what the graph does not know.
 
 **Cap: 12 files.** If you go over, or you cannot find the right files, or the
 job needs more than about 3 files of real edits: print a `GATE` line, say it
-plainly, and **offer** `/orc-mini` (`../_shared/fallback-handoff.md`, REASON
+plainly, and **offer** `/orc-mini` (H `quick.q1.too-big`; `../_shared/fallback-handoff.md`, REASON
 `dig-inconclusive` or `scope-too-large`). Never keep digging in silence. It is
 an OFFER — the user may still say "keep going".
 
@@ -132,18 +134,20 @@ the job is not quick: offer the Q1 fallback.
 
 ### b. The dispatch gate — HARD, never skip it
 
-**Ask before every single dispatch** — the three kinds are code, read-only
-(recon) and review. **The menu, per kind, is `references/dispatch-gate.md`.**
+**Ask before every single dispatch** (H `quick.q2.gate.code` · `quick.q2.gate.recon`) — the three kinds are code, read-only
+(recon) and review. **The menu: `references/dispatch-gate.md`, only
+`### Writing code` or `### Read-only work (recon)`, `## The suggestion` and `## Rules`.**
 Every menu ends with `Your choice — nothing runs until you answer.`
 
 Rules:
-- Never pick for the user. Never reuse the last answer. Never remember it for
-  the next entry. One line MAY carry `→ suggested` with its reason from the dig
-  (`references/dispatch-gate.md`, "The suggestion") — a recommendation, never a
-  pre-selection.
+- Never pick for the user. Never reuse the last answer by yourself. One line
+  MAY carry `→ suggested` with its reason — from the dig (`## The suggestion`),
+  or from `habits.suggestions` (the CLI's count of your own past picks, printed
+  with its numbers). A suggestion is never a pre-selection; the gate is asked
+  every time.
 - If the user already said it ("use opus 5 low"), the gate is **answered**, not
   skipped. Say which one you are using.
-- No config changes this menu. See `## Config`.
+- No config changes this menu. See `## Lane contract`.
 - If the model asked for is higher than the session model, say so once: the
   subagent will quietly drop to the session model and you will report it.
 
@@ -164,17 +168,17 @@ carries `repro` — the EXECUTOR writes it red, then fixes it green, never you
 (`references/defect.md`). An **ad-hoc** dispatch is also told to report its own
 `actual_model` and `actual_effort`.
 
-Check the return with `../_shared/return-validation.md`: honest `unmet[]`,
-`pattern_version` + `invariants_checked`, `graph_used` (absent on a slice that
-carried a card = malformed), `repro` when the slice asked for it (§5d), and
-`actual_model` / `actual_effort` → emit `VERIFY`, which names
+Check the return with `../_shared/return-validation.md` §1–§3 + each injected
+field's §: honest `unmet[]`, `pattern_version` + `invariants_checked`,
+`graph_used` (absent on a slice that carried a card = malformed), `repro` when
+the slice asked for it, and `actual_model` / `actual_effort` → emit `VERIFY`, which names
 `graph_used=<n> targets gen <n>` and `repro red→green` beside the model match,
-and show a ⛔ DOWNGRADE line if they differ. Also compare `git status --short`
+and show ⛔ DOWNGRADE if they differ. Also compare `git status --short`
 before and after: a file changed outside `declared_files` is a violation. A
 **recon** return adds one check: `answer` ≤ 12 lines. A broken return = a
 failure: re-dispatch once, then offer the fallback.
 
-**Before any re-dispatch, run `orc run inflight`** (0 clear · 1 in-flight · 2 unknown). A Task error does not kill the agent behind it, and exit 2 REFUSES by default — `a lane that re-dispatches over a live attempt` has broken the contract. Canonical: `../_shared/return-validation.md`.
+**Before any re-dispatch, run `orc run inflight`**. A Task error does not kill the agent behind it, and exit 2 REFUSES by default — `a lane that re-dispatches over a live attempt` has broken the contract. Canonical: `return-validation.md` §0.
 
 ### 3.2 Build and tests — there is NO smoke gate
 
@@ -193,15 +197,13 @@ the suite — a runner that takes no file list → one line saying so — and ap
 ` → <n> passed`. Then the suite. Then print its `blast_line` VERBATIM: the CLI
 attaches every `risk` word's `why`, so never restate it. Exit 3 → nothing.
 
-`tests reached  3 files (ROUTE 2 · call 1) → 12 passed` · then the suite · then
-`blast radius   3 symbols · callers 7 in 4 files · tests reach 2 · risk high: <symbol> (exported, fan-in 4, no test reaches it)`
-
 **Build is RED → repair loop.** Rounds 1 and 2 reuse the same executor; round 3
 **asks again**; after 3, ask and show how the errors MOVED, not just "still
 red". Each new batch of 3 works the same way. Shape and wording:
-`references/dispatch-gate.md`. Put every round in the entry's dispatch table.
+its `## The build repair loop`. Put every round in the entry's dispatch table.
 
-**Tests are RED → stop, do NOT loop.** Show the failures. Let the user choose:
+**Tests are RED → the flaky check first** (`../_shared/smoke-gate.md` §Flaky).
+Still red → stop, do NOT loop. Show the failures. Let the user choose:
 fix it with a new gated dispatch · the test itself is wrong · accept it · stop.
 Never offer commit while tests are red.
 
@@ -219,20 +221,22 @@ after the entry is appended, `orc graph gain --run <this run> --if-enabled
 with a range; never restate it as a saving.
 
 Append entry N to `orc-quick/<slug>/quick-context.md`
-(`references/context-doc.md`). Every request gets an entry — a read-only dig
-included, where the answer IS the result.
+(`references/context-doc.md`, only `## Entry shape` or `## A read-only entry`).
+Every request gets an entry — a read-only dig too, where the answer IS the
+result. A code-writing entry
+ends with the card (`../_shared/phases/summary.md` §End-of-run card).
 
 ### 3.4 If the user stops while it is red
 
 **Never undo anything yourself.** Say how many files changed, that nothing is
-committed, and print `git checkout -- .` as the undo.
+committed, and print the card's `undo` row as the undo.
 
 ### 3.5 Offers (skip any the ledger already answered)
 
-1. **Update tests and run them** — only if a test suite exists AND the change
+1. **Update tests and run them** (H `quick.q3.offer.tests`) — only if a test suite exists AND the change
    made a test wrong or left new code untested. If the executor already fixed
    the tests and they pass, **do not ask at all**.
-2. **Code review** — this is a dispatch, so **ask the gate first**. Pattern
+2. **Code review** (H `quick.q3.offer.review`) — this is a dispatch, so **ask the gate first**. Pattern
    cached → review against it. Findings use the `P0|P1|P2|P3` ladder: P0/P1
    block the commit offer and get one repair round; P2/P3 are advice only.
 3. **Commit / push / stop** — stage **only the files the task changed**. Never
@@ -241,7 +245,7 @@ committed, and print `git checkout -- .` as the undo.
    or merge — even when the user said "push". A `repro: none` entry shows the
    **not reproduced** line here.
 
-Write the results of these offers back into entry N. **Then:** another request →
+Write the results of these offers back into entry N. Then record what it proved (`../_shared/gotchas.md` §10). **Then:** another request →
 **Q1** as entry N+1, and Q0 never runs again; the user is done → emit `OUTCOME`
 + `FINISH`, send the last trace packet, and only THEN delete `log_dir/.current`.
 
@@ -252,72 +256,37 @@ Write the results of these offers back into entry N. **Then:** another request
 One folder per thread, **one file inside, never a second file**:
 `<projectRoot>/orc-quick/<slug>/quick-context.md`, with a list between
 `<!-- orc-quick:toc -->` markers at the top. **Never read the body** — two
-exceptions: the TOC block on re-open, and when the user asks. Shape:
-`references/context-doc.md`.
+exceptions: the TOC block on re-open, and when the user asks.
 
 ## Behavior trace (always on)
 
-`../_shared/phases/trace.md` (`core`, at run start; `orc lane phases` names the
-file and the layers). Lane token `quick`, tier **Iterative** — ONE packet per
-finished numbered entry, paired with the next entry's first dispatch, plus the
-`FINISH` packet. Each packet is built from `quick-checkpoint.md`, so every event
-carries the time it happened; one time for every event is a protocol violation.
-Nothing else about the protocol is restated here; a phase that
-ends with `zero new trace lines is a protocol violation`. Ad-hoc dispatches are
-not named `orc-*`, so the hook writes no `SPAWN`/`RETURN` for them: you still
-emit `DISPATCH … adhoc=true` and `VERIFY` yourself, and the downgrade check
-still works from the agent's own report.
-
-## Config
-
-**ONE resolver, and it is not you:** `orc lane config orc-quick --json`. Obey
-`effective`, print every line in `announce[]` VERBATIM at preflight, and honour
-`stops[]` before wave 1. Never re-derive a value, a precedence or an inertness
-from `.claude/orc.config.yaml` — a key this lane does not read is not in the
-answer, and a key another key shadows comes back already marked. Exit ≠ 0 → say
-the CLI is unavailable and fall back to `../_shared/config-precedence.md`'s
-documented defaults, out loud. Priorities and families:
-`../_shared/config-precedence.md`.
-
-**Nothing can override this lane.** orc-quick has no config key of its own.
-These config keys **do nothing here**: `opus5_only` · `rubric_bands_override` ·
-`extra_resume` · `extra_on_failure` · `extra_fallback_agent`. All five come back
-INERT with a reason — say that at the gate so the user is not confused
-(`../_shared/opus5-only.md` names orc-quick as the one exception). The user
-always picks the agent. **`extra_enabled` is the one key that does something
-here, and it is small:** with a `quick-executor` position held
-(`orc extra role`), the code-writing menu gets a THIRD option that sends the
-slice to a third party — never a default, never sticky, asked again after a
-failure. Recon and review stay on Claude. See `references/dispatch-gate.md`
-rule 4 and `../_shared/extra-dispatch.md`.
-
-## Rules — the anti-slop card (`../_shared/phases/rules.md`)
-
-`orc rules slice --lane orc-quick --json` is the ONLY assembler; never build
-the card here. It rides under the house rules and above the task —
-**house rules > your project's rules > ORC's own packs** — and its `line` prints
-VERBATIM at preflight. Returns gain `rules_applied[]`, `rules_conflicts[]` (a gap,
-never a silent choice) and `rules_overridden[]`.
-## Calls
-
-**ONE catalogue, and it is not you:** `orc lane calls orc-quick --json` names every
-CLI call this lane makes, each with its exit-code contract, its cost, when to run
-it, and what an EMPTY answer means. Never invent a spelling, never re-word an
-exit code, and never re-derive a state word — the CLI's state words are the only
-state words, and **an exit code is an ANSWER wherever that contract says so, not
-a failure**. A call the answer does not name is a call this lane does not make.
-Exit ≠ 0 from the catalogue itself → say the CLI is unavailable and name the
-command you are about to run, out loud, before running it.
+`../_shared/phases/trace.md` (`core`, at run start; `orc lane phases orc-quick --json` →
+`trace_grammar` gives the verbs). Lane token `quick`, tier
+**Iterative** — the unit is ONE finished numbered entry. Build each packet from
+`quick-checkpoint.md`, so every event carries the time it happened; one time for
+every event is a protocol violation. Pipe each packet to
+`orc trace write --packet -`. A phase that ends with
+`zero new trace lines is a protocol violation`. Ad-hoc dispatches (no hook `SPAWN`): `references/dispatch-gate.md`, recon line 3.
+
+## Lane contract (`../_shared/lane-contract.md` — read it ONLY when a call exits ≠ 0)
+
+- **Calls:** `orc lane calls orc-quick --json` names every call and its exit codes.
+  **An exit code is an ANSWER where it says so, not a failure.** Make no other call.
+- **Config:** `orc lane config orc-quick --json`. Obey `effective`, print every line
+  in `announce[]` VERBATIM at preflight, and honour `stops[]` before wave 1.
+  Never merge `.claude/orc.config.yaml` yourself (`../_shared/config-precedence.md`).
+- **Rules:** `orc rules slice --lane orc-quick --json` is the ONLY assembler
+  (`../_shared/phases/rules.md`). Its `line` prints VERBATIM at preflight.
+
+**Nothing can override this lane** — `references/dispatch-gate.md` rule 4.
 
 ## Rules this lane always keeps
 
-Never implement yourself · ask the gate before every dispatch · check every
-return (broken = failure) · never offer commit while tests are red · never undo
-the user's files · write the doc before the offers · stage only the task's files
-· never write anything to GitHub · tell the user to run `/usage` (never run it
-yourself).
+Never implement yourself · check every return (broken = failure) · never undo
+the user's files · stage only the task's files · never write anything to GitHub
+· tell the user to run `/usage` (never run it yourself).
 
 ## Waiting mid-run (`/orc-wait`)
 
 Canonical: `../_shared/wait.md`. **`a lane that waits without a hand-back` has broken this contract.**
-Checkpoint **entry** · safe point **after an entry closes**. `soft` FORCES that checkpoint and does NOT stop if the write fails; `hard` skips it and can lose an in-flight return. Never begin a wait between a dispatch and its validated return, or before the smoke gate has reported.
+Checkpoint **entry** · safe point **after an entry closes**.

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

@@ -12,10 +12,17 @@ what is about to be spent, before it is spent.
 |------|-------|--------------------|-----------------|
 | 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) | `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 |
+| Review | `orc-reviewer-opus-5-low` · or ad-hoc | yes / no | yes |
 | Build repair, round 1–2 | *reused — not asked* | yes | yes |
 | Build repair, round 3 | asked again | yes | yes |
 
+**Review slice.** The review offer builds its slice from
+`../../_shared/review-slice.md` (`--lane orc-quick`): the §1 free check first,
+then the §2 fields, and its §3 after-filter on the return. No disprove pass here.
+A finding the user calls "not a problem here" is a `disputed` outcome; record
+each outcome with `orc gotcha observe` (one per finding, with `run`) and the
+`FINDING-OUTCOME` line (`../../_shared/gotchas.md` §10).
+
 ### Writing code
 
 ```
@@ -37,7 +44,7 @@ Show a third line ONLY when all three are true:
 - `extra_enabled` is true, AND
 - a `quick-executor` position is held (`orc extra role set quick-executor
   <profile>/<model>`), AND
-- `orc extra resolve --slot quick-executor --json` answers `extra`.
+- `probes["extra-slot"]` (Q0 step 1) answers `resolved: extra`.
 
 ```
 Which executor for entry 2 — "add retry header"?
@@ -117,7 +124,8 @@ reason attached, the same shape every ORC question uses
 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
+The reason comes from the dig, or from `habits.suggestions` with the CLI's
+count (`../../_shared/habits.md`), never from a feeling. Suggest
 `orc-executor-opus-5-low` when ANY of these holds:
 
 | Suggest the stronger executor when | Because |
@@ -139,8 +147,11 @@ For recon, the suggestion is simpler: `orc-recon-sonnet-4-6-med` finds things;
 2. **Never sticky.** Do not carry the last answer into the next entry.
 3. **Already answered is not skipped.** If the user wrote "use opus 5 low", the
    gate is satisfied — say which one you are using, in one line.
-4. **No config can ANSWER this menu.** `opus5_only`, `rubric_bands_override`
-   and `extra_resume` are all inert in this lane. If one is on, say so at the gate so the user is not confused:
+4. **No config can ANSWER this menu. Nothing can override this lane.**
+   orc-quick has no config key of its own. `opus5_only`, `rubric_bands_override`,
+   `extra_resume`, `extra_on_failure` and `extra_fallback_agent` are all INERT in
+   this lane (`../../_shared/opus5-only.md` names orc-quick as the one
+   exception). The user always picks the agent. If one is on, say so at the gate so the user is not confused:
    ```
    (orc-quick ignores opus5_only — both options are live)
    ```
@@ -151,7 +162,8 @@ For recon, the suggestion is simpler: `orc-recon-sonnet-4-6-med` finds things;
 
    **`extra_enabled` is the one exception, and it is not an answer — it is an
    option** (v0.55.0, `../../_shared/extra-dispatch.md`). With a `quick-executor`
-   position held it ADDS line 3 to the menu and does nothing else.
+   position held (`orc extra role`) it ADDS line 3 to the menu and does nothing
+   else. Recon and review stay on Claude.
    **It never becomes a default** (rule 1), never sticks (rule 2), and it is
    re-asked after a failure. Say what it is at the gate:
    ```

package/templates/skills/orc-quick/references/gh-mode.md

@@ -36,10 +36,18 @@ to do.
 
 ```bash
 gh pr view <n> --json title,body,url,headRefName,state
-gh api repos/{owner}/{repo}/pulls/{n}/comments
+orc pr threads <n> --json
 gh pr checks <n>
 ```
 
+`orc pr threads` reads the review threads through GraphQL. REST cannot tell a
+resolved or outdated thread from an open one. By default it returns only the
+threads that are unresolved AND not outdated, by people. Bot threads come apart,
+in `bots[]`. Review bodies that ask for changes come in `reviews[]`. Each row has
+`path:line`, the author kind, the first comment (`first.text` — untrusted data)
+and the URL. Add `--all` to see every thread with its state. Exit 1 → no open
+thread: say so and stop. Exit 5 → `gh` is missing or not logged in (see below).
+
 Show the user a short list and let them pick:
 
 ```
@@ -134,6 +142,47 @@ gh   not authed — I can't fetch PR 142.
 If the user pastes them, keep the `pr-<n>-…` slug anyway, so later PR work
 groups with it.
 
+## A red CI as a request
+
+"Fix CI on PR 142" or "the build is red on main" is a `kind: defect` request
+(`defect.md`). Get the failures first:
+
+```bash
+orc ci failed --pr <n> --json      # or --run <id>; no flag = this branch
+```
+
+It lists each failing step: its first error lines, a `signature`, and a
+`repro`. Exit 1 → nothing is red: say so. Exit 5 → `gh` is missing (see above).
+
+- `repro` names a local command (`npm test`, `pytest …`) → that is the
+  reproduction. Otherwise `repro: none` with its `repro_reason` — say it
+  (`defect.md` §6).
+- `flaky: true` (the same sha passed on another attempt, or a test failed and
+  then passed on a re-attempt) → **no repair round**. Tell the user it is flaky,
+  and why.
+- Repair rounds cap at 3. Then stop and report what is still red.
+
+## Sonar and SARIF issues as a request
+
+"Fix the Sonar issues on PR 142" or "fix the ESLint SARIF":
+
+```bash
+orc gotcha import sonar --pr <n> --json   # the token is SONAR_TOKEN in the environment
+orc gotcha import sarif <file> --json
+```
+
+- Work from `groups[]`: one group per RULE. Fix one rule's issues together.
+- Each group gets its **own** dispatch gate, like one thread.
+- Sonar exit 5 → the token is missing or refused. Tell the user to set
+  `SONAR_TOKEN` in the environment. Never ask for the token in the chat. A saved
+  answer also works: `--file <saved.json>`.
+- The import records each issue as an observation. After a green fix, record
+  each fixed issue ONCE through the `/orc-fix` record step (`via: "orc-quick"`,
+  with its Sonar issue key — `../../_shared/gotchas.md` §10). It uses the
+  importer's own id, so the next import completes the SAME row with `addressed`.
+- **Never change an issue's status on the Sonar server.** ORC reads external
+  systems. It does not write to them — the GitHub boundary, extended.
+
 ## What goes in the doc
 
 Record the PR number, title, url, and branch. For each thread: the reviewer, the

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

@@ -2,7 +2,9 @@
 
 This is Q1's read-only half. It has one job: **find the right files, fast, and
 then stop.** You are not studying the code here. An agent does that later, if
-the user says yes at the gate.
+the user says yes at the gate. This keeps your context small.
+
+The intent ledger prints on ONE line so nothing is skipped in secret.
 
 ## 1. Why the graph goes first
 

package/templates/skills/orc-retro/SKILL.md

@@ -22,7 +22,7 @@ return spoke of that flywheel. It turns the raw `.txt` traces into an answer to
 three questions: **is the scoring rubric calibrated? are the workers honest?
 where does the pipeline leak?**
 
-Run as Opus 4.8 high (orchestrator). The mining itself is dispatched to
+Run as Opus 5.5 low or better (orchestrator). The mining itself is dispatched to
 `orc-retro-sonnet-5-high` — cheap, because it reads trace text, not code — or
 to `orc-retro-opus-5-med` when `opus5_only: true` forces it
 (`../_shared/opus5-only.md`).
@@ -70,7 +70,7 @@ to `orc-retro-opus-5-med` when `opus5_only: true` forces it
    date range from `$ARGUMENTS`). Show the count and ask nothing else.
 2. Dispatch `orc-retro-sonnet-5-high` (or `orc-retro-opus-5-med` under
    `opus5_only`) with the slice: trace file paths + the
-   verb reference (`../_shared/phases/trace.md`). The agent mines the
+   verb reference (`../_shared/phases/trace-verbs.md`). The agent mines the
    `<trace>.jsonl` sidecar first when present (structured — no regex over free
    text) and falls back to `.txt` parsing for pre-v0.32.0 traces, merging the
    hook's `.txt`-only skeleton lines by timestamp. It parses the CLOSED verb set
@@ -94,10 +94,11 @@ to `orc-retro-opus-5-med` when `opus5_only: true` forces it
    - **Trace hygiene → narration coverage:** the hook's `PHASE-EDGE` lines
      segment every run with zero model cooperation, so a missing narration is
      now DETERMINISTICALLY visible: count the phases whose edge-interval
-     contains no trace-writer `SPAWN`. Report `covered/total` + the unnarrated
-     phases. The question is no longer "were rich markers forgotten?" but
-     "which phases never dispatched their writer?" — a run with edges and zero
-     writer spawns is a total narration failure and is named as such.
+     contains no trace-writer `SPAWN` and no narrated (non-`hook`) line STAMPED
+     inside it — the CLI writes most packets, with no SPAWN. Report
+     `covered/total` + the unnarrated phases. The question is "which phases were
+     never narrated?" — a run with edges and no narration at all is a total
+     narration failure and is named as such.
 2a. **Repair memory as calibration input (READ-ONLY).** Probe `orc gotcha status`
    (exit 0 = entries, 1 = none — never a `find`). On a hit, add
    `.claude/orc/gotchas.md` to the agent's slice as one more read-only source:
@@ -241,16 +242,16 @@ exit code, and never re-derive a state word — the CLI's state words are the on
 state words, and **an exit code is an ANSWER wherever that contract says so, not
 a failure**. A call the answer does not name is a call this lane does not make.
 Exit ≠ 0 from the catalogue itself → say the CLI is unavailable and name the
-command you are about to run, out loud, before running it.
-
-## Rules — the anti-slop card (`../_shared/phases/rules.md`)
-
-`orc rules slice --lane orc-retro --json` is the ONLY assembler; never build
-the card here. It rides under the house rules and above the task —
-**house rules > your project's rules > ORC's own packs** — and its `line` prints
-VERBATIM at preflight. Returns gain `rules_applied[]`, `rules_conflicts[]` (a gap,
-never a silent choice) and `rules_overridden[]`.
-## Waiting mid-run (`/orc-wait`)
-
-Canonical: `../_shared/wait.md`. **`a lane that waits without a hand-back` has broken this contract.**
-Checkpoint **none** · safe point **read-only, seconds long**. Nothing here to checkpoint, so all three modes behave identically — say so rather than asking. Never begin a wait between a dispatch and its validated return, or before the smoke gate has reported.
+command you are about to run, out loud, before running it.
+
+## Rules — the anti-slop card (`../_shared/phases/rules.md`)
+
+`orc rules slice --lane orc-retro --json` is the ONLY assembler; never build
+the card here. It rides under the house rules and above the task —
+**house rules > your project's rules > ORC's own packs** — and its `line` prints
+VERBATIM at preflight. Returns gain `rules_applied[]`, `rules_conflicts[]` (a gap,
+never a silent choice) and `rules_overridden[]`.
+## Waiting mid-run (`/orc-wait`)
+
+Canonical: `../_shared/wait.md`. **`a lane that waits without a hand-back` has broken this contract.**
+Checkpoint **none** · safe point **read-only, seconds long**. Nothing here to checkpoint, so all three modes behave identically — say so rather than asking. Never begin a wait between a dispatch and its validated return, or before the smoke gate has reported.

package/templates/skills/orc-retro/examples/retro-mock.md

@@ -45,32 +45,32 @@ lane wrote:
 `run-orc-feat-auth-090726-144001.txt` (full pipeline — the rich one; every
 non-hook line was written by the trace writer from a phase packet):
 ```
-[090726 14:40:02.300] writer   SCORE task=T3 score=72 band=[65,90) model=opus-5 :: multi-file, judgment
+[090726 14:40:02.300] writer   SCORE task=T3 score=72 band=[41,90) model=opus-5 :: multi-file, judgment
 [090726 14:40:03.010] writer   DISPATCH orc-executor-opus-5-low :: T3 expect=opus-5/low
 [090726 14:44:12.900] writer   VERIFY T3 actual=opus-5/low ✅ MATCH
 [090726 14:44:13.000] writer   VERIFY T5 actual=sonnet-4-6/high ⛔ DOWNGRADE expected=opus-5/med
 [090726 15:02:00.000] reviewer FINDING p0=1 p1=0 p2=3 p3=2
 [090726 15:04:10.000] writer   GATE coverage bounce :: T4 unowned (no owning req)
 [090726 15:10:00.000] verifier VERDICT pass :: 8/8 acceptance criteria
-[090726 15:11:30.000] writer   OUTCOME task=T3 score=72 band=[65,90) model=opus-5 retries=1 requeues=0 needs_context=0 unmet=0
+[090726 15:11:30.000] writer   OUTCOME task=T3 score=72 band=[41,90) model=opus-5 retries=1 requeues=0 needs_context=0 unmet=0
 [090726 15:12:00.000] writer   FINISH :: shipped PR #123
 ```
 
 `run-claude-readme-100726-091401.txt` (single-dispatch lane — ONE end-of-run
 packet; its meaningful signal is the writer's tier honesty):
 ```
-[100726 09:14:02.110] writer   DISPATCH orc-claude-writer :: refresh expect=opus-4-8/high
-[100726 09:14:02.230] hook     SPAWN orc-claude-writer-opus-4-8-high
+[100726 09:14:02.110] writer   DISPATCH orc-claude-writer :: refresh expect=opus-5/low
+[100726 09:14:02.230] hook     SPAWN orc-claude-writer-opus-5-low
 [100726 09:15:47.900] hook     RETURN
-[100726 09:15:48.010] writer   VERIFY writer actual=sonnet-4-6/high ⛔ DOWNGRADE expected=opus-4-8/high
+[100726 09:15:48.010] writer   VERIFY writer actual=sonnet-4-6/high ⛔ DOWNGRADE expected=opus-5/low
 [100726 09:15:48.120] writer   FINISH :: refresh CLAUDE.md v0.0.3
 ```
 
 ### Step 2 — dispatch the miner (never mines itself)
 
 ```
-C: Spawning orc-retro-sonnet-5-high → claude-sonnet-5 / high
-   slice: trace_files=[3 paths] + verb_reference=_shared/phases/trace.md
+C: Spawning orc-retro-sonnet-5-high → claude-sonnet-5-5 / high
+   slice: trace_files=[3 paths] + verb_reference=_shared/phases/trace-verbs.md
    (This lane writes NO run pointer and emits NO markers — tracing the retro
     would pollute the very data it mines.)
 ```
@@ -82,23 +82,23 @@ verb set, and returns EXACTLY the contract:
 runs_analyzed: 3
 tasks_analyzed: 6
 band_stats:
-  - {band: "[65,90)", model: opus-5, tasks: 2, avg_retries: 0.5, avg_requeues: 0, avg_needs_context: 0, avg_unmet: 0}
-  - {band: "[55,65)", model: sonnet-5, tasks: 3, avg_retries: 1.3, avg_requeues: 0.7, avg_needs_context: 1.0, avg_unmet: 0.3}
+  - {band: "[41,90)", model: opus-5, tasks: 2, avg_retries: 0.5, avg_requeues: 0, avg_needs_context: 0, avg_unmet: 0}
+  - {band: "[31,41)", model: sonnet-5, tasks: 3, avg_retries: 1.3, avg_requeues: 0.7, avg_needs_context: 1.0, avg_unmet: 0.3}
 downgrades:
   - {agent: orc-executor-opus-5-low,        expected: opus-5/low,   actual: sonnet-4-6/high, run: feat-auth-090726}
-  - {agent: orc-claude-writer-opus-4-8-high, expected: opus-4-8/high, actual: sonnet-4-6/high, run: orc-claude-100726}
+  - {agent: orc-claude-writer-opus-5-low, expected: opus-5/low, actual: sonnet-4-6/high, run: orc-claude-100726}
 leaks:
   - {kind: verdict-fail, evidence: "run-orc-feat-auth-090726-144001.txt:L31 (FINDING p0=1)", count: 1}
   - {kind: gate-bounce,  evidence: "run-orc-feat-auth-090726-144001.txt:L33 (coverage bounce)", count: 1}
   - {kind: context-gap,  evidence: "run-mini-fix-cache-110726-101200.txt:L4,L7", count: 2}
 recommendations:
-  - finding: "Both downgrades share a fingerprint: an opus-4-8/high pin ran as sonnet-4-6 — the main session was below Opus when the child spawned."
-    suggested_change: "Not a rubric issue — surface to the user: run the pinned lanes from an Opus 4.8 session. No config edit."
+  - finding: "Both downgrades share a fingerprint: an opus-5/low pin ran as sonnet-4-6 — the main session was below Opus when the child spawned."
+    suggested_change: "Not a rubric issue — surface to the user: run the pinned lanes from an Opus 5.5 session. No config edit."
     confidence: strong
-  - finding: "sonnet-5 band [55,65) shows avg_needs_context=1.0 across 3 tasks — slices may be under-specified."
-    suggested_change: "config.md — tighten the planner's declared-files discipline, or nudge the [55,65) band slice detail."
+  - finding: "sonnet-5 band [31,41) shows avg_needs_context=1.0 across 3 tasks — slices may be under-specified."
+    suggested_change: "config.md — tighten the planner's declared-files discipline, or nudge the [31,41) band slice detail."
     confidence: weak      # n<3 in this band
-actual_model: claude-sonnet-5
+actual_model: claude-sonnet-5-5
 actual_effort: high
 ```
 
@@ -113,8 +113,8 @@ C: Return validates. Writing report →
    level to run traces + their sidecars)
 
 ── orc-retro summary (n=3 runs, 6 tasks) ──────────────────────────────
-Scoring calibrated?  ~ mostly — [65,90) clean; [40,65) shows a context-gap (weak, n=3)
-Workers honest?      ⛔ NO — 2 silent downgrades (opus-4-8 → sonnet-4-6)
+Scoring calibrated?  ~ mostly — [41,90) clean; [31,41) shows a context-gap (weak, n=3)
+Workers honest?      ⛔ NO — 2 silent downgrades (opus-5 → sonnet-4-6)
 Where it leaks?      1 coverage-gate bounce, 1 P0 review finding, 2 context-gaps
 Narrated?            11/12 phases had a writer dispatch (1 execution phase blind)
 Recommendations: 2 (1 strong, 1 weak)