@azure-id/orc 1.9.2 → 2.1.0

package/templates/skills/orc-pr-driver/SKILL.md

@@ -2,15 +2,11 @@
 name: orc-pr-driver
 description: >
   Stacked-PR DRIVER. Use for "/orc-pr-driver", "build the stacked PRs", "submit
-  the stack", "restack / sync / merge my stack". Takes an approved
-  stacked-pr/<slug>/stack-plan.md — written by /orc-pr-setup, generated by
-  `orc pr stack template` and filled in by hand, or handed over by ORC's ship
-  phase — and executes it: one branch per layer, only that layer's files, a
-  MANDATORY per-layer green gate (build + tests + lint scoped to the layer's own
-  base + the repo's own hooks, never --no-verify), then `gh stack submit`, PR
-  bodies from the resolved template, and the ongoing sync / rebase / conflict /
-  bottom-up merge care. Refuses to run on a plan with unanswered uncertainties,
-  a missing ticket or a red build.
+  the stack", "restack / sync / merge my stack". Executes an approved
+  stacked-pr/<slug>/stack-plan.md: one branch per layer, a MANDATORY per-layer
+  green gate (build + tests + lint + the repo's own hooks, never --no-verify),
+  then `gh stack submit` and the sync / rebase / bottom-up merge care. Refuses a
+  plan with open uncertainties or a red build.
 ---
 
 # ORC-PR-DRIVER (stacked-PR driver)
@@ -61,17 +57,14 @@ modes) · `../_shared/gh-stack-commands.md` (preflight + command surface) ·
 
 ## Phases
 
-`orc lane phases orc-pr-driver --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-pr-driver --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).
 
 ## Phase D0 — Read the plan + hard gate
 
-1. **Probe, do not search:** `orc pr stack status [<slug>]` — exit 0 = READY,
-   exit 1 = absent or unfilled (`../_shared/stack-plan.md`). Exit 1 → say which
-   it is and offer `/orc-pr-setup` (plan it) or `orc pr stack template` (skeleton
+1. **Probe, do not search:** `orc pr stack status [<slug>]` — exit 1 =
+   absent or unfilled (`../_shared/stack-plan.md`) → say which it is and offer `/orc-pr-setup` (plan it) or `orc pr stack template` (skeleton
    to fill in by hand).
 2. Read `stacked-pr/<slug>/stack-plan.md`, plus
    `stacked-pr/<slug>/STACK-FROM.md` when present (source, ticket, entry mode,
@@ -150,14 +143,12 @@ lands, delete the snapshot branch (ask first) and report the final state.
 
 ## Behavior trace (always on)
 
-`../_shared/phases/trace.md` (`core`, at run start; `orc lane phases` names
-the file and the layers). Lane token `prdriver`, tier **Multi-dispatch** —
-one packet per LAYER boundary (each layer's green gate closes) + the
-end-of-run packet.
-At run start write `log_dir/.current` = `run-prdriver-<slug>-<DDMMYY>-<HHMMSS>.txt` AND
-`touch the trace file` of that name in the SAME step.
-Nothing else about the protocol is restated here; a phase that ends with
-`zero new trace lines is a protocol violation`.
+`../_shared/phases/trace.md` (`core`, at run start; `orc lane phases orc-pr-driver --json` →
+`trace_grammar` gives the verbs). Lane token `prdriver`, tier
+**Multi-dispatch** — one packet per LAYER (each layer's green
+gate closes). At run start write `log_dir/.current` =
+`run-prdriver-<slug>-<DDMMYY>-<HHMMSS>.txt` AND `touch the trace file` of that name
+in the SAME step. A phase that ends with `zero new trace lines is a protocol violation`.
 
 Events: `PHASE D0..D5`, `GATE layer-green pass|bounce :: L<n> <step>`,
 `QUESTION count=<n>`, `GATE stack-certainty` on a mid-run re-cut, `FINISH`;
@@ -176,29 +167,12 @@ answers verbatim).
 - Reminder: to see usage limits, tell the user to run `/usage` (never invoke it
   programmatically).
 
-## Config
-
-Resolve with `orc lane config orc-pr-driver --json` and obey `effective`. Never merge
-`.claude/orc.config.yaml` yourself, and never re-derive a precedence. Exit ≠ 0 →
-say so and use `../_shared/config-precedence.md`'s documented defaults, out
-loud. Nothing this lane reads is contested, gated or a stop, so it owes no
-preflight line and has no gate to honour.
-
-## Calls
-
-**ONE catalogue, and it is not you:** `orc lane calls orc-pr-driver --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.
-
-## Rules — the anti-slop card (`../_shared/phases/rules.md`)
-
-`orc rules slice --lane orc-pr-driver --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[]`.
+## Lane contract (`../_shared/lane-contract.md` — read it ONLY when a call exits ≠ 0)
+
+- **Calls:** `orc lane calls orc-pr-driver --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-pr-driver --json`. Obey `effective`. Never merge
+  `.claude/orc.config.yaml` yourself (`../_shared/config-precedence.md`). Nothing
+  here is contested, gated or a stop: no preflight line, no gate to honour.
+- **Rules:** `orc rules slice --lane orc-pr-driver --json` is the ONLY assembler
+  (`../_shared/phases/rules.md`). Its `line` prints VERBATIM at preflight.

package/templates/skills/orc-pr-driver/references/green-gate.md

@@ -1,105 +1,113 @@
-# Reference — the per-layer GREEN GATE (mandatory)
-
-Loaded at Phase D2, run once per layer and again after every rebase above a
-changed layer.
-
-**Rule: no layer is submitted, pushed or merged until its own gate is green at
-its OWN base.** Never `git commit --no-verify`. Never `gh stack submit` over a red
-layer. "Green when the whole stack is applied" is not green.
-
-## The ladder — all four steps, in order, per layer
-
-Detect the stack from the repo (never ask what the repo can tell you) and run the
-four rungs. The commands below are the common shapes; the repo's own scripts win.
-
-| # | Rung | Go | Node/TS | Java/Kotlin | Python | Rust |
-|---|------|----|---------|-------------|--------|------|
-| 1 | **build** at this layer's base | `go build ./...` | `npm run build` | `./gradlew compileJava` / `mvn -q compile` | `python -m compileall` / type-check | `cargo build` |
-| 2 | **tests** for the layer's scope | `go test ./<pkgs>/...` | `npm test -- <paths>` | `./gradlew test --tests …` | `pytest <paths>` | `cargo test <filter>` |
-| 3 | **lint scoped to THIS layer's base** | `golangci-lint run --new-from-rev <base> ./<pkgs>/...` | `eslint <changed files>` | `./gradlew checkstyleMain` / detekt | `ruff check <paths>` | `cargo clippy -- -D warnings` |
-| 4 | **the repo's own pre-commit hooks, unbypassed** | `git commit` (hooks run) | same | same | same | same |
-
-Mocks/codegen first when the project needs them (`mockery`, `go generate`,
-`protoc`, `npm run codegen`) — a missing generated file reads as a compile error
-and sends you hunting the wrong thing. Platform quirks belong here too: e.g. on
-macOS, Go tests that monkey-patch need `GOARCH=amd64 … -gcflags=all=-l`.
-
-Any rung red → **stop, fix, re-run the whole ladder from rung 1** for that layer.
-Do not proceed to the next layer. Do not push.
-
-## Attribution — the stacked-specific trap
-
-Many repos pin their linter's "new code" baseline to the trunk (e.g.
-`issues.new-from-rev: origin/main` in `.golangci.yml`). On layer 4 that flags
-layers 1–3's diff too: noisy and **misattributed**. Override per layer with
-`--new-from-rev <that layer's base>` (or the equivalent) so each layer is judged
-on **its own** diff.
-
-## Code-quality scans (SonarQube and friends) are a STACK-LEVEL gate
-
-A scan that analyzes the project key directly, with no PR decoration, measures
-the **cumulative** L1..LN diff against the trunk — not layer N's diff. So:
-
-- per-layer new-code coverage from such a scan is **not a trustworthy per-layer
-  signal** — verify coverage locally, per layer;
-- treat the scan as a **stack-level** gate;
-- a scan reported as `SKIPPED` on a layer usually means that layer's test job
-  failed first — the gate never ran. Read it as red, not as flaky.
-
-Keep each layer's tests **with its code** for exactly this reason: a FOUNDATION
-layer with no tests can red-gate on its own coverage rule.
-
-## Dead-code / `unused` on a FOUNDATION layer — a P0 QUESTION, never auto-fixed
-
-Linters flag declared-but-unreferenced identifiers (Go's `unused`, TS
-`noUnusedLocals`, Rust `dead_code`) even when the compiler is happy. A FOUNDATION
-layer that declares something only a LATER layer calls will go RED. **That is a
-real signal about the seam**, so stop and ask:
-
-```
-L2 declares repo.FindByRef()
-L4 (handler) is its only caller
-lint --new-from-rev <L2 base>: unused → RED
-
-ASK: [a] merge L2 into L4 (one layer, no dead code)          ← recommended
-     [b] keep the split, land the first caller in L2
-     [c] accept it: one suppression, with a reason naming the consumer layer
-         (user override only)
-```
-
-Never silently add a suppression, never invent a fake caller, never delete the
-identifier to go green. Record the answer under the plan's `## Decisions`.
-
-## Re-verification after ANY lower-layer change (the rule people get wrong)
-
-Amending layer N rewrites every branch above it, so previously-green upper layers
-can go red:
-
-```
-amend L2  →  gh stack rebase --upstack
-for layer in L2..Ltop, bottom-up:
-    run the FULL ladder (codegen + build + tests + lint + hooks)
-    RED → stop, fix, restart from that layer
-all green → gh stack push  /  gh stack submit
-```
-
-The same applies after `gh stack sync` when the trunk moves, and after
-`gh stack modify` (insert / reorder / drop / combine).
-
-## Merge-time gate
-
-Bottom-up only. Before `gh stack merge`, confirm the layer's own CI is green
-(`gh stack view --json` + `gh pr view <n> --json statusCheckRollup`); after each
-merge, confirm the upper layers auto-retargeted and their CI re-ran.
-
-## Gate red flags
-
-| Excuse | Reality |
-|---|---|
-| "Tests pass on the top layer, the stack is fine" | The gate is per-layer at its own base. Merging L1 alone must not break the trunk. |
-| "The build is clean, lint is cosmetic" | Lint blocks the repo's pre-commit hook. Clean build ≠ committable. |
-| "I'll `--no-verify` and fix lint in a follow-up" | Forbidden. The hooks are the gate; bypassing means the PR cannot land. |
-| "It was green before the rebase" | A rebase rewrites every upper branch. Re-run the ladder at every tip above the change. |
-| "`unused` is a false positive — the caller is in layer 4" | It is a TRUE positive about layer 2 *as a standalone PR*. That is the P0 question, not a suppression. |
-| "The scan says new coverage is fine on layer 3" | Layer 3's scan measures L1..L3 cumulatively. Verify per-layer coverage locally. |
-| "The scan was SKIPPED — it's flaky" | The layer's test job failed first; the gate never ran. Red. |
+# Reference — the per-layer GREEN GATE (mandatory)
+
+Loaded at Phase D2, run once per layer and again after every rebase above a
+changed layer.
+
+**Rule: no layer is submitted, pushed or merged until its own gate is green at
+its OWN base.** Never `git commit --no-verify`. Never `gh stack submit` over a red
+layer. "Green when the whole stack is applied" is not green.
+
+## The ladder — all four steps, in order, per layer
+
+Detect the stack from the repo (never ask what the repo can tell you) and run the
+four rungs. The commands below are the common shapes; the repo's own scripts win.
+
+| # | Rung | Go | Node/TS | Java/Kotlin | Python | Rust |
+|---|------|----|---------|-------------|--------|------|
+| 1 | **build** at this layer's base | `go build ./...` | `npm run build` | `./gradlew compileJava` / `mvn -q compile` | `python -m compileall` / type-check | `cargo build` |
+| 2 | **tests** for the layer's scope | `go test ./<pkgs>/...` | `npm test -- <paths>` | `./gradlew test --tests …` | `pytest <paths>` | `cargo test <filter>` |
+| 3 | **lint scoped to THIS layer's base** | `golangci-lint run --new-from-rev <base> ./<pkgs>/...` | `eslint <changed files>` | `./gradlew checkstyleMain` / detekt | `ruff check <paths>` | `cargo clippy -- -D warnings` |
+| 4 | **the repo's own pre-commit hooks, unbypassed** | `git commit` (hooks run) | same | same | same | same |
+
+Mocks/codegen first when the project needs them (`mockery`, `go generate`,
+`protoc`, `npm run codegen`) — a missing generated file reads as a compile error
+and sends you hunting the wrong thing. Platform quirks belong here too: e.g. on
+macOS, Go tests that monkey-patch need `GOARCH=amd64 … -gcflags=all=-l`.
+
+Any rung red → **stop, fix, re-run the whole ladder from rung 1** for that layer.
+Do not proceed to the next layer. Do not push.
+
+**Gotcha card (advice only).** Before rung 1, run `orc gotcha sync --json`
+(due at most once per `gotcha_sync_hours`; any failure → go on), then
+`orc gotcha card --files <this layer's files> --lane orc-pr-driver --json`
+(the `gotcha_card` field of `../../_shared/review-slice.md` §2) and print its
+`text`. It names failures this project already paid for in these files. It
+never turns a rung red: the gate stays build · tests · lint · hooks. A rung that
+went red → green after a lint/seam fix is recorded (`../../_shared/gotchas.md` §10).
+
+## Attribution — the stacked-specific trap
+
+Many repos pin their linter's "new code" baseline to the trunk (e.g.
+`issues.new-from-rev: origin/main` in `.golangci.yml`). On layer 4 that flags
+layers 1–3's diff too: noisy and **misattributed**. Override per layer with
+`--new-from-rev <that layer's base>` (or the equivalent) so each layer is judged
+on **its own** diff.
+
+## Code-quality scans (SonarQube and friends) are a STACK-LEVEL gate
+
+A scan that analyzes the project key directly, with no PR decoration, measures
+the **cumulative** L1..LN diff against the trunk — not layer N's diff. So:
+
+- per-layer new-code coverage from such a scan is **not a trustworthy per-layer
+  signal** — verify coverage locally, per layer;
+- treat the scan as a **stack-level** gate;
+- a scan reported as `SKIPPED` on a layer usually means that layer's test job
+  failed first — the gate never ran. Read it as red, not as flaky.
+
+Keep each layer's tests **with its code** for exactly this reason: a FOUNDATION
+layer with no tests can red-gate on its own coverage rule.
+
+## Dead-code / `unused` on a FOUNDATION layer — a P0 QUESTION, never auto-fixed
+
+Linters flag declared-but-unreferenced identifiers (Go's `unused`, TS
+`noUnusedLocals`, Rust `dead_code`) even when the compiler is happy. A FOUNDATION
+layer that declares something only a LATER layer calls will go RED. **That is a
+real signal about the seam**, so stop and ask:
+
+```
+L2 declares repo.FindByRef()
+L4 (handler) is its only caller
+lint --new-from-rev <L2 base>: unused → RED
+
+ASK: [a] merge L2 into L4 (one layer, no dead code)          ← recommended
+     [b] keep the split, land the first caller in L2
+     [c] accept it: one suppression, with a reason naming the consumer layer
+         (user override only)
+```
+
+Never silently add a suppression, never invent a fake caller, never delete the
+identifier to go green. Record the answer under the plan's `## Decisions`.
+
+## Re-verification after ANY lower-layer change (the rule people get wrong)
+
+Amending layer N rewrites every branch above it, so previously-green upper layers
+can go red:
+
+```
+amend L2  →  gh stack rebase --upstack
+for layer in L2..Ltop, bottom-up:
+    run the FULL ladder (codegen + build + tests + lint + hooks)
+    RED → stop, fix, restart from that layer
+all green → gh stack push  /  gh stack submit
+```
+
+The same applies after `gh stack sync` when the trunk moves, and after
+`gh stack modify` (insert / reorder / drop / combine).
+
+## Merge-time gate
+
+Bottom-up only. Before `gh stack merge`, confirm the layer's own CI is green
+(`gh stack view --json` + `gh pr view <n> --json statusCheckRollup`); after each
+merge, confirm the upper layers auto-retargeted and their CI re-ran.
+
+## Gate red flags
+
+| Excuse | Reality |
+|---|---|
+| "Tests pass on the top layer, the stack is fine" | The gate is per-layer at its own base. Merging L1 alone must not break the trunk. |
+| "The build is clean, lint is cosmetic" | Lint blocks the repo's pre-commit hook. Clean build ≠ committable. |
+| "I'll `--no-verify` and fix lint in a follow-up" | Forbidden. The hooks are the gate; bypassing means the PR cannot land. |
+| "It was green before the rebase" | A rebase rewrites every upper branch. Re-run the ladder at every tip above the change. |
+| "`unused` is a false positive — the caller is in layer 4" | It is a TRUE positive about layer 2 *as a standalone PR*. That is the P0 question, not a suppression. |
+| "The scan says new coverage is fine on layer 3" | Layer 3's scan measures L1..L3 cumulatively. Verify per-layer coverage locally. |
+| "The scan was SKIPPED — it's flaky" | The layer's test job failed first; the gate never ran. Red. |

package/templates/skills/orc-pr-setup/SKILL.md

@@ -4,13 +4,9 @@ description: >
   Stacked-PR PLANNER. Use for "/orc-pr-setup", "plan the stacked PRs", "split
   this change into stacked pull requests", "where do the PR cut lines go".
   Decides the LAYERING of a big change — ordered layers, each with a purpose, a
-  value class, an explicit file list, a measured LoC/file budget and a
-  dependency reason — and writes stacked-pr/<slug>/stack-plan.md. Runs
-  INDEPENDENTLY (no orchestrator needed) and is also the lane ORC's ship phase
-  hands off to when a change is too big for one PR. It NEVER touches git
-  history: no branches, no commits, no pushes — that is orc-pr-driver's job.
-  P0 HARD GATE: when a boundary is uncertain it STOPS and asks, one decision at
-  a time, and records the answer.
+  file list, a size budget and a dependency reason — and writes
+  stacked-pr/<slug>/stack-plan.md. It never touches git history. When a boundary
+  is uncertain it STOPS and asks.
 ---
 
 # ORC-PR-SETUP (stacked-PR planner)
@@ -62,11 +58,9 @@ how any of this works; never load it to drive the run.
 
 ## Phases
 
-`orc lane phases orc-pr-setup --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-pr-setup --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).
 
 ## Phase S0 — Preflight (probe, never assume)
 
@@ -173,13 +167,11 @@ exceptions`. Then:
 
 ## Behavior trace (always on)
 
-`../_shared/phases/trace.md` (`core`, at run start; `orc lane phases` names
-the file and the layers). Lane token `prsetup`, tier **Single-dispatch** —
-exactly ONE end-of-run packet, dispatched solo before `.current` is deleted.
-At run start write `log_dir/.current` = `run-prsetup-<slug>-<DDMMYY>-<HHMMSS>.txt` AND
-`touch the trace file` of that name in the SAME step.
-Nothing else about the protocol is restated here; a phase that ends with
-`zero new trace lines is a protocol violation`.
+`../_shared/phases/trace.md` (`core`, at run start; `orc lane phases orc-pr-setup --json` →
+`trace_grammar` gives the verbs). Lane token `prsetup`, tier
+**Single-dispatch**. At run start write `log_dir/.current` =
+`run-prsetup-<slug>-<DDMMYY>-<HHMMSS>.txt` AND `touch the trace file` of that name
+in the SAME step. A phase that ends with `zero new trace lines is a protocol violation`.
 
 ## Boundaries
 
@@ -192,29 +184,12 @@ Nothing else about the protocol is restated here; a phase that ends with
 - Reminder: to see usage limits, tell the user to run `/usage` (never invoke it
   programmatically).
 
-## Config
-
-Resolve with `orc lane config orc-pr-setup --json` and obey `effective`. Never merge
-`.claude/orc.config.yaml` yourself, and never re-derive a precedence. Exit ≠ 0 →
-say so and use `../_shared/config-precedence.md`'s documented defaults, out
-loud. Nothing this lane reads is contested, gated or a stop, so it owes no
-preflight line and has no gate to honour.
-
-## Calls
-
-**ONE catalogue, and it is not you:** `orc lane calls orc-pr-setup --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.
-
-## Rules — the anti-slop card (`../_shared/phases/rules.md`)
-
-`orc rules slice --lane orc-pr-setup --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[]`.
+## Lane contract (`../_shared/lane-contract.md` — read it ONLY when a call exits ≠ 0)
+
+- **Calls:** `orc lane calls orc-pr-setup --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-pr-setup --json`. Obey `effective`. Never merge
+  `.claude/orc.config.yaml` yourself (`../_shared/config-precedence.md`). Nothing
+  here is contested, gated or a stop: no preflight line, no gate to honour.
+- **Rules:** `orc rules slice --lane orc-pr-setup --json` is the ONLY assembler
+  (`../_shared/phases/rules.md`). Its `line` prints VERBATIM at preflight.

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
 ```
 
@@ -165,6 +165,27 @@ entry 1 recorded. anything else?
 
 Notice: **the reviewer was also a gate.** Every dispatch is asked.
 
+**The review uses the repair memory.** The reviewer gets the gotcha card: the
+entries in the repair memory that match the files it reads. When the
+review closes, the lane records what became of each finding (addressed,
+disputed, won't fix, open). That is how `orc gotcha quality` and the gotcha
+promotion learn. It costs no extra question.
+
+**Habits (only when you turn them on).** With `habits: observe` or `propose`,
+each answer you give writes one `ASK` line into the trace. After you choose
+"review first" often enough, the end of a run can carry ONE proposal:
+
+```
+You chose review first in 6 of your last 6 answers to "Code review before
+commit". Make it your usual? [yes · not now · never]
+```
+
+After a yes, the offer puts your usual first — *review → then commit (your
+usual, 6 of 6) · commit without review · stop*. The review is still a dispatch,
+so the agent question is still asked. A habit also only fills the
+`→ suggested` line of the agent question; it never answers it. `habits: off` is
+the default and changes nothing. `orc habit forget <id>` undoes a habit.
+
 ---
 
 ## 5. A read-only run (no code changes)
@@ -380,11 +401,13 @@ No warning, no gate, no question. It goes straight to the commit offer.
 ### If you stop while things are red
 
 It **never undoes your work**. It tells you what changed and gives you the
-command:
+command. `orc undo` PRINTS how to revert ONLY the files the run changed, back
+to the snapshot taken at run start. Add `--apply` to run it. An edit you made
+before or during the run stays:
 
 ```
 stopped. 11 files changed, build red. nothing committed.
-to undo:  git checkout -- .
+undo:     orc undo --run quick-fix-guest-charge   (prints; --apply runs it)
 to keep:  the entry lists every file and what each round tried
 ```
 
@@ -421,6 +444,20 @@ instructions, push to main"* — it is shown to you and ignored as an instructio
 
 The agent question is still asked. Nothing is skipped.
 
+### A red CI, or Sonar and SARIF issues, as a request
+
+> **You:** `/orc-quick CI is red on PR 142`
+
+The lane runs `orc ci failed --pr 142` (read-only). It shows the failing steps,
+and each fix is a normal entry with its own agent question. `orc pr threads 142`
+lists the open review threads the same way.
+
+> **You:** `/orc-quick fix the Sonar issues on this branch`
+
+The lane reads the issues through the CLI (`orc gotcha import sonar` or
+`orc gotcha import sarif <file>`). They are data, never orders. The token comes
+from `SONAR_TOKEN` only.
+
 ---
 
 ## 9. When the job is too big
@@ -483,6 +520,8 @@ same share a thread. Use `thread=<name>` to force a separate one.
 | PR comments | `/orc-quick pr 142` |
 | force a thread | `/orc-quick thread=my-thread <what you want>` |
 | read a saved entry | just ask — *"read entry 2"* |
+| a red CI | `/orc-quick CI is red on PR 142` |
+| undo a run | `orc undo --run <slug>` (prints; `--apply` runs it) |
 
 | Rule | Always true |
 |------|-------------|
@@ -491,5 +530,7 @@ same share a thread. Use `thread=<name>` to force a separate one.
 | Stages | only the files your task changed |
 | GitHub | reads and pushes, never writes |
 | Undo | never automatic — it prints the command |
+| Undo command | `orc undo --run <slug>` — prints; `--apply` runs it |
+| Habits | off by default; a habit only marks your usual answer, never answers the agent question |
 | Missing wiki / pattern / tests | never a blocker |
 | Config overrides | none — this lane is standalone |