@azure-id/orc 2.0.2 → 2.1.0

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

@@ -49,13 +49,14 @@ unavailable, apply the same checks manually from
 
 ## Step 2 — dispatch the compiled flow
 
+First `orc lane config orc-diy --json`. **`habits{}` in it → print `habits.line`,
+read `../_shared/habits.md` NOW**; none → ignore every `(H …)`. Then:
 Read `.claude/orc/diy/FLOW-COMPILED.md` and follow it as your orchestrator
 spine for this run — it is self-contained: tier self-check, locked rules,
 phase sequence, and the references it cherry-picks from the installed orc
 skill. Honor its generated header: if its own self-gate fails, stop exactly
-as it says. Do not consult this stub again for the rest of the run, and do
-not load orc's SKILL.md as a spine (the compiled flow already references the
-exact orc subskills and schemas it needs).
+as it says. Never consult this stub again this run, and never load orc's
+SKILL.md as a spine — the flow names every subskill and schema it needs.
 
 ## Lane contract (`../_shared/lane-contract.md` — read it ONLY when a call exits ≠ 0)
 
@@ -64,8 +65,7 @@ exact orc subskills and schemas it needs).
 - **Config:** `orc lane config orc-diy --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`).
-- **Habits:** `habits{}` in the config answer → read `../_shared/habits.md`. No
-  `habits{}` → ignore every `(H …)` mark.
+- **Habits:** Step 2, first.
 - **Rules:** `orc rules slice --lane orc-diy --json` is the ONLY assembler
   (`../_shared/phases/rules.md`). Its `line` prints VERBATIM at preflight.
 

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

@@ -38,6 +38,11 @@ without the manifest (`../_shared/lane-contract.md` §Phases).
 
 Emit a `GATE` trace line per check.
 
+**0. Config, FIRST.** `orc lane config orc-fast --json`: obey `effective`, print
+`announce[]` VERBATIM, honour `stops[]`; never merge `.claude/orc.config.yaml`
+(`../_shared/config-precedence.md`). **`habits{}` in it → print `habits.line`,
+read `../_shared/habits.md` NOW.**
+
 **a. Wiki gate.** Decide existence with `orc wiki status` — the deterministic
 probe in `../_shared/detecting-artifacts.md`, never an ad-hoc `find` (`.claude`
 is hidden). `none` = gate FAILED → fallback; else read the tier from
@@ -76,9 +81,8 @@ then one `orc graph notes pending` batch — the next run starts from this cache
 
 **d. Extra — a PROBE, not a gate (P0).** Run `orc extra resolve --slot fast-executor --json` (0 = extra, 1 = Claude) — **a gate that is never probed is a gate that is always off**, and without this step the lane silently runs on Claude however `extra_enabled` and `orc extra role` were set. `extra` → print the `extra:` line HERE and carry the answer into F2; `claude` → print nothing, never fall back, never stop.
 
-The SHAPE of these steps — the order, and the four rules that make it worth
-having — is `../_shared/phases/preflight.md` (`core`). The probes
-themselves are this lane's own and stay here.
+Their shape and four rules: `../_shared/phases/preflight.md` (`core`). The
+probes are this lane's own.
 
 ## Phase F1 — Fit gate + micro-intake (one pass, ONE user round-trip)
 
@@ -182,9 +186,7 @@ in the SAME step. A phase that ends with `zero new trace lines is a protocol vio
 
 - **Calls:** `orc lane calls orc-fast --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-fast --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`).
+- **Config:** F0 step 0.
 - **Rules:** `orc rules slice --lane orc-fast --json` is the ONLY assembler
   (`../_shared/phases/rules.md`). Its `line` prints VERBATIM at preflight.
 

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

@@ -0,0 +1,110 @@
+---
+name: orc-fix
+description: >
+  Say "this is a fix, and here is what it fixes". Use for "/orc-fix", "this
+  fixes Sonar typescript:S3776", "ORC caused this defect", "this bug came from
+  AI-generated code", "record this fix". It classifies the fix from evidence,
+  asks once, and records it so the next review sees it. A rider: it opens no
+  run and returns to exactly where the run was. With no run open it can also
+  make the fix, like /orc-quick.
+---
+
+# ORC — the fix record
+
+A RIDER lane, like `/orc-wait` and `/orc-explain`. It opens no run of its own,
+writes no `run-<lane>-<slug>` pointer and never writes `.current`. The user can
+call it at any time — also while another lane waits at a question.
+
+## What this lane never does
+
+- It never begins between a dispatch and its validated return.
+- It never changes the host run: no re-plan, no re-score, no new task. A
+  suspend does not widen anyone's authority.
+- With a run open, it never writes code. The host lane makes the fix — two
+  writers on one tree is the conflict `/orc-wait` forbids (DE-12).
+- It never sets `miss` itself, and never records `author: orc`. The CLI does
+  the first, and refuses the second.
+
+## F0 — look (silent)
+
+Run `orc fix classify --text "<the user's words>" --json`. The CLI reads the
+git state, `git blame` on the named lines, the traces and the host run, and
+proposes ONE class on two axes:
+
+- `source` (what found it): `sonar` · `ci` · `defect` · `pr` · `review` · `other`
+- `introduced_by` (who wrote the bad lines): `orc` · `ai` · `human` · `unknown`
+
+| exit | meaning | what you do |
+|---|---|---|
+| 0 | classified | go to F1 |
+| 1 | a dispatch is in flight | say so, wait for its return, then run F0 again |
+| 2 | no text | ask what the fix fixes |
+
+Never classify in your head. The user's three cases: "a SonarQube fix" →
+`source: sonar`; "a defect caused by ORC" → `source: defect, introduced_by:
+orc`; "a bug caused by AI-generated code" → `introduced_by: ai`.
+
+## F1 — ask once (H `fix.f1.class`)
+
+Show the proposed class, every `evidence` line and the file, then:
+
+```text
+This fix:  source sonar · introduced by ORC (run-mini-total-290926)
+  - a Sonar rule key (typescript:S3776)
+  - git blame → 4c1e2a9: the commit falls inside the run's trace window ...
+  1. confirm   2. change the class   3. cancel
+```
+
+The user's word wins over the evidence. A changed class goes into the record
+as `class_by: "user"`; a confirmed one as `class_by: "evidence"`. Cancel →
+nothing is written; return to the run.
+
+## F2 — record
+
+Pipe the classify answer's `record` object (with the user's class and
+`class_by`) to `orc fix record - --json`. The CLI:
+
+1. writes ONE observation through the gotcha store — with a Sonar issue key it
+   uses the importer's own id, so a later `gotcha sync` completes the same row;
+2. computes `miss` from the stored review scopes;
+3. writes ONE `FIX` line into the HOST run's trace, when one is open;
+4. prints ONE line. Show it VERBATIM, then stop.
+
+Exit 1 → a dispatch started meanwhile; nothing was written. Wait, then F2 again.
+
+## No run open — offer the fix (DE-12)
+
+`mode: may-fix` from F0 → offer to make the fix before F2, like `/orc-quick`:
+
+1. The user picks the executor at the `/orc-quick` dispatch gate (that lane's
+   `dispatch-gate.md` reference, "Writing code") — nothing spawns without a yes.
+2. The slice carries `orc rules slice --lane orc-fix --json` (below).
+3. The smoke gate (`../_shared/smoke-gate.md`): red blocks the record.
+4. F2 with `outcome: "addressed"` and `via: "orc-fix"`.
+
+The user can also say "record only" — then F2 at once.
+
+## Config
+
+`orc lane config orc-fix --json`, obey `effective`. Never merge
+`.claude/orc.config.yaml` yourself (`../_shared/config-precedence.md`).
+
+## Rules — the anti-slop card (`../_shared/phases/rules.md`)
+
+`orc rules slice --lane orc-fix --json` is the ONLY assembler. It rides only in
+an executor slice of the no-run fix.
+
+## Habits and trace
+
+**Habits:** the host run had `habits{}` in its config answer → read
+`../_shared/habits.md`; its next packet takes the `ASK` for `fix.f1.class`
+(class `never`: a fact is never a habit). No `habits{}` → ignore `(H …)`.
+
+**Trace:** the CLI writes the `FIX` line itself. You do not narrate it and you
+do not repeat it. With no run open, nothing is traced — the record is the
+observation.
+
+## 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 **after the record is written**. Nothing here to checkpoint, so all three modes behave identically — say so rather than asking.

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

@@ -93,7 +93,7 @@ Docs-only → gate N/A, say so. `orc run inflight` FIRST — exit 2 REFUSES, bec
 (`return-validation.md` §0). **A `risk: high` row adds ONE option,
 never a phase** (H `mini.phase-m.risk-high`): an exported symbol with fan-in 3+ that no test reaches adds one
 option to the EXISTING end-of-run batch (mock example · test authoring · ship)
-— *a. dispatch `orc-reviewer-opus-5-med` with `../_shared/review-slice.md`* (H `any.ship.review-before-push`) *(P0/P1 block the commit
+— *a. dispatch `orc-reviewer-opus-5-low` with `../_shared/review-slice.md`* (H `any.ship.review-before-push`) *(P0/P1 block the commit
 offer once) · b. write a test in Phase T · c. ship anyway*. No new user turn;
 mini still skips full review.
 
@@ -154,9 +154,9 @@ Models pinned in `.claude/agents/`; look one up here, never reconstruct a name (
 
 | Role | Agent (dispatch this) | Model / effort | When `opus5_only` |
 |------|-----------------------|----------------|-------------------|
-| mini analysis (docs only) | `orc-analyze-mini-sonnet-5-high` | claude-sonnet-5 / high | `orc-analyze-mini-opus-5-med` |
-| mini planning | `orc-planner-mini-sonnet-5-high` | claude-sonnet-5 / high | `orc-planner-mini-opus-5-med` |
-| mini execution | `orc-executor-sonnet-5-high` | claude-sonnet-5 / high | `orc-executor-opus-5-low` |
+| mini analysis (docs only) | `orc-analyze-mini-sonnet-5-high` | claude-sonnet-5-5 / high | `orc-analyze-mini-opus-5-med` |
+| mini planning | `orc-planner-mini-sonnet-5-high` | claude-sonnet-5-5 / high | `orc-planner-mini-opus-5-med` |
+| mini execution | `orc-executor-sonnet-5-high` | claude-sonnet-5-5 / high | `orc-executor-opus-5-low` |
 | test authoring (opt-in) | `orc-test-author-opus-5-med` | claude-opus-5-5 / medium | unchanged |
 
 ## Lane contract (`../_shared/lane-contract.md` — read it ONLY when a call exits ≠ 0)

package/templates/skills/orc-mini/examples/mini-run-mock.md

@@ -31,10 +31,10 @@ O: GATE complexity :: complexity: mini-ok — 2 files · confident callers 1 in
 
 ## Phase 3 — Execute (ONE subagent)
 O: graph: --for-slice card (2 files) · wiki: 1 path (pointer, body never read here)
-O: → claude-sonnet-5 / high :: DISPATCH orc-executor-sonnet-5-high :: add --json flag
+O: → claude-sonnet-5-5 / high :: DISPATCH orc-executor-sonnet-5-high :: add --json flag
    [executor edits cli/report.py + updates tests, returns actual_files + actual_model
    + evidence {`pytest tests/test_report.py`, exit 0, tail quoted} + empty unmet[]]
-O: VERIFY actual=claude-sonnet-5/high ✅ MATCH · evidence present ✓
+O: VERIFY actual=claude-sonnet-5-5/high ✅ MATCH · evidence present ✓
 
 ## Phase M — Smoke gate (build + test; blocks ship on red)
 O: GRAPH-CHANGES → tests reached 1 file (call 1)
@@ -60,5 +60,7 @@ O: Self-QA plan: test-generator/report-json-flag/TEST-PLAN.md (committed on ship
 O: Current branch: feat/report-json. Commit? Push? PR?
 U: commit
 O: knowledge: wiki 1 page offered · used tests/test_report.py note · graph used 1 target
+   (risk none → no review option, so no `orc gotcha observe` call. A risk-high run
+   that took option a records each finding with it, `run` included.)
 O: [commits] Done. Usage: dispatch log below + run /usage for your limits.
    (Switch to full flow any time — the run folder + checkpoint are shared.)

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

@@ -139,7 +139,7 @@ Code review this change?
 
 ```
 Which reviewer?
-  1. orc-reviewer-opus-5-med       knows your express@v3 pattern
+  1. orc-reviewer-opus-5-low       knows your express@v3 pattern
   2. other — name model + effort
 ```
 

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

@@ -223,7 +223,7 @@ with a range; never restate it as a saving.
 Append entry N to `orc-quick/<slug>/quick-context.md`
 (`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. Then record what it proved (`../_shared/gotchas.md` §10). A code-writing entry
+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
@@ -245,7 +245,7 @@ committed, and print the card's `undo` row 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`.
 

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

@@ -12,7 +12,7 @@ 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 |
 
@@ -20,7 +20,8 @@ what is about to be spent, before it is spent.
 `../../_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 and the `FINDING-OUTCOME` line (`../../_shared/gotchas.md` §10).
+each outcome with `orc gotcha observe` (one per finding, with `run`) and the
+`FINDING-OUTCOME` line (`../../_shared/gotchas.md` §10).
 
 ### Writing code
 

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

@@ -176,8 +176,10 @@ orc gotcha import sarif <file> --json
 - 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, the next
-  import records the group as `addressed`. Do not record it yourself.
+- 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.
 

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`).

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

@@ -45,31 +45,31 @@ 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
+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)