@azure-id/orc 1.9.2 → 2.1.0

package/CHANGELOG.md

@@ -10,6 +10,728 @@ Format: `### v<version> — <title> _(<date>)_`.
 
 ---
 
+### v2.1.0 — the review counts, the score table moves up, and old logs can go _(2026-10-02)_
+
+**Still on the unscoped `orc` package?** Do this once first - your `orc upgrade`
+is the pre-v0.56.0 one and cannot install itself. Full detail in the CAUTION at
+the top of this file.
+
+- **Step 1 - release the command from the old package:** `npm uninstall -g orc`
+- **Step 2 - install the current package:** `npm i -g @azure-id/orc`
+- **Step 3 - re-apply it to your project:** `orc update`
+
+**Do not use `npm i -g -f`.** Full detail in v0.56.0 below.
+
+This release has eight parts. It moves the score table up to newer models, it
+makes Review quality count the reviews that really ran, and it adds a way to
+delete old logs.
+
+**1. Opus 4.x leaves the roles that do not write code**
+
+- The deep wiki scanner and the CLAUDE.md writer now use **Opus 5.5 low**. They
+  used Opus 4.8 high. An agent's model change is always a rename, so the files
+  change name:
+  - `orc-wiki-scanner-opus-4-8-high` → `orc-wiki-scanner-opus-5-low`
+  - `orc-claude-writer-opus-4-8-high` → `orc-claude-writer-opus-5-low`
+- The `opus5_only` twins of these two roles are **deleted**
+  (`orc-wiki-scanner-opus-5-med`, `orc-claude-writer-opus-5-med`). The defaults
+  are already Opus 5.5 low, so `opus5_only` has nothing to change. Under
+  `opus5_only`, a wiki scan and a CLAUDE.md write are now low effort, not medium
+  (cheaper).
+- The coding lanes and the `/orc` main-session baseline do not change. Opus 4.6
+  is used nowhere.
+
+**2. Sonnet 5 runs on `claude-sonnet-5-5`**
+
+- Every Sonnet 5 agent now has `model: claude-sonnet-5-5`. The agent names keep
+  `-sonnet-5-`, as Opus did in v1.9.2. A config that names `claude-sonnet-5` is
+  still valid.
+
+**3. A new score table with five bands**
+
+| Score | Agent | Model · effort |
+|---|---|---|
+| `[0,21)` | `orc-executor-sonnet-5-low` (new) | Sonnet 5 · low |
+| `[21,31)` | `orc-executor-sonnet-5-med` (new) | Sonnet 5 · medium |
+| `[31,41)` | `orc-executor-sonnet-5-high` | Sonnet 5 · high |
+| `[41,90)` | `orc-executor-opus-5-low` | Opus 5.5 · low |
+| `[90,100]` | `orc-executor-opus-5-med` | Opus 5.5 · medium |
+
+- The table had six bands. Seven executors now have no band
+  (`haiku-4-5`, `sonnet-4-6-med`, `sonnet-4-6-high`, `opus-4-7-med`,
+  `opus-4-7-high`, `opus-4-8-high`, `opus-5-high`). They still ship.
+  `rubric_bands_override`, `orc diy`'s `fixed_executor` and
+  `extra_fallback_agent` can still name them.
+- **The cost effect:**
+  - Scores 41–64 move from Sonnet (Sonnet 4.6 high $3/$15, Sonnet 5 high $2/$10)
+    to **Opus 5.5 low ($4/$20)**. This is the largest change.
+  - Scores 0–29 move from Haiku 4.5 ($1/$5) to Sonnet 5 low or medium ($2/$10).
+  - Scores 30–39 move from Sonnet 4.6 medium ($3/$15) to Sonnet 5 high ($2/$10).
+  - **Every band from 41 needs an Opus 5.5 main session.** Before, this was from
+    65. A lower main session runs these tasks on the session model, and the tier
+    line says so.
+  - Sandbox sample (14 scored tasks): the Opus share goes from 6 to 7 of 14, and
+    the Haiku share from 6 to 0. The sample is small. Measure your own project
+    with `orc stats`.
+- **`opus5_only` does not change** (`[0,90)` low · `[90,100]` medium). It now
+  differs from the default table only below score 41. The `opus5_only` text in
+  `orc config` showed an old three-band ladder; it now shows the real two bands.
+- A user route row in `orc diy` that spans two Claude bands now names both
+  agents.
+
+**4. The price table is correct** (`bin/pricing.json`, dated 2026-10-01)
+
+- `claude-sonnet-5-5` is added: $2 input · $2.50 cache write · $0.20 cache read
+  · $10 output per MTok.
+- `claude-sonnet-5` was $3/$15; it is now $2 / $2.50 / $0.20 / $10.
+- `claude-opus-5`, `claude-opus-4-8` and `claude-opus-4-7` are now
+  $5 / $6.25 / $0.50 / $25.
+- `claude-fable-5` is now $10 / $12.50 / $1 / $50.
+- `claude-sonnet-5-5` has a context window row, so `orc budget` shows its
+  context risk.
+
+**5. Review**
+
+- **The reviewer is `orc-reviewer-opus-5-low`** (renamed from
+  `orc-reviewer-opus-5-med`; low effort). In the live eval, low effort found
+  100% of the seeded defects that were still in the diff. **A script that names
+  the old file breaks.** `orc update` removes the old file.
+- **Review quality no longer says "0 so far" after real reviews.** It read only
+  `observations.jsonl`, and no lane wrote that file. Now a run with a
+  `FINDING-OUTCOME` line or a reviewer return in its trace counts as a review. A
+  clean review counts too. `orc gotcha quality --json` has two new fields:
+  `reviews_traced` and `reviews_observed`.
+- **An observation with `author: orc` must name its `run`.** Without it, `orc
+  gotcha observe` exits 2 and names `run`. A `ref` that starts with the run id
+  fills `run` for you.
+- **Your project's own review rule.** New command **`orc review policy`**. It
+  reads CLAUDE.md and AGENTS.md for a line that asks for a different review (for
+  example "All code review must go through /code-review"). When it finds one,
+  every coding lane that changed code asks: ORC review, that review, or skip.
+  The answer goes in a new trace line, `REVIEW-WHICH`. An external review is
+  counted as "Project reviews" and never in the ORC headline.
+- **Fixes the review can see.** An observation can now carry `introduced_by`
+  (`orc` · `ai` · `human` · `unknown`, from `git blame`), and a fix after a
+  review is recorded. The reviewer card shows a `fix` line for each changed file.
+  A review that missed a later fix is counted as a miss.
+- **New lane `/orc-fix`** with the commands **`orc fix classify`**, **`orc fix
+  record`** and **`orc fix list`**. Inside a paused run, `/orc-fix` only records:
+  one observation and one `FIX` line in the trace of that run. With no run open,
+  it fixes the way `/orc-quick` does, and it asks which agent to use. It refuses
+  while a dispatch is in flight.
+
+**6. The Behaviour tab**
+
+- The gate habit now proposes: one agent name written three ways now counts as
+  one answer.
+- `/orc-fast` reads its lane config first, so it records your answers.
+  `/orc-analyze` and `/orc-diy` do the same.
+- With `habits: off` you still see the Review quality and Gotchas tabs. Review
+  learning is always on.
+- The answer log shows the question, not only its id.
+- A run is dated from its file name. Rows say `orc-quick`, not `quick`. An empty
+  row is not shown.
+- At the end of a run, `orc trace write` names a question whose key you set in
+  your config when the lane wrote no answer for it.
+
+**7. Clear old logs**
+
+- New command **`orc clear logs`**. It shows the old traces and finished run
+  folders that it can delete, and why it keeps the rest. **`orc clear logs
+  --apply`** deletes them.
+- New key **`log_retention_days`**: 30 · 60 · 90 · 120 · 240 · 360 days
+  (default 90). The cutoff is never shorter than `aftermath_window_days`.
+- It never deletes your data, a waiting run, the active trace, a file younger
+  than 6 hours, or a trace with a habit answer that is younger than 180 days.
+- `orc stats` keeps the totals of a deleted run in `.claude/orc/logs-rollup.json`
+  and says "includes N pruned runs".
+- **The promise "log_dir is never deleted automatically" changes.** It is still
+  true by default. New key **`log_retention_auto`** (default `off`): `on` runs
+  the delete after a lane's last trace packet, at most once per 24 hours.
+- `orc ui` ▸ Maintenance has a **Clear old logs** row with a full preview.
+
+**8. The status line timer**
+
+- New key **`statusline_refresh`**: `off` · `1` · `2` · `3` · `5` · `10` seconds
+  (3 is new). It writes `statusLine.refreshInterval` in `settings.json`, the same
+  as `orc statusline refresh`, and `orc config list` reads it from there.
+- **The floor is 1 second.** Claude Code gives no timer below 1 second. A value
+  below 1 is refused, and the message names the nearest value. In `orc ui` ▸ CLI
+  Hook Interface, 0.2 · 0.5 · 0.7 are disabled.
+- With a timer, a pet moves one step for each redraw. `usage.json` is written
+  only when the numbers change.
+- `orc doctor` tells you when the value is below the floor, when a moving part
+  has no timer, and when the timer is on the sub-agent board.
+
+**Defects found in the live evals, and fixed**
+
+- **D1:** `/orc-fast` refused to record review observations. Every lane that
+  runs a review now records them.
+- **D2:** a free-text `FINDING` line (`FINDING 9 findings — P0×2 …`) was
+  accepted. The CLI now checks the count head (`FINDING p0= p1= p2= p3=`).
+- **D3:** a `REVIEW-WHICH` line was written with no project rule and no name.
+  The CLI now checks the format, and refuses it when `orc review policy` says
+  "orc".
+- **D4:** the question "which review" was asked with no project rule. It is now
+  refused by name.
+- **D5:** a `FINDING-OUTCOME` line used its own category names. The categories
+  are now checked against the closed set of the review return.
+- **D6:** an `/orc` run skipped review and verify for a small change. At the
+  end, `orc trace write` now names the skipped phase. `/orc` always runs both.
+- **D7:** an `/orc-quick` run wrote its trace lines by hand. No CLI check and no
+  end-of-run reminder ran, and the lane then said the findings were recorded.
+  The session hook now stops the turn once when a trace has more narration lines
+  than its `.jsonl` twin, and names `orc trace write` and `orc gotcha observe`.
+- **D8:** an `/orc` run ignored the end-of-run reminder to record its review
+  outcomes. The session hook now stops the turn once when a finished run had a
+  review with findings and no observation names the run.
+
+**Live evals.** Five rounds ran `/orc-mini`, `/orc-fast`, `/orc-quick` and `/orc`
+in a sandbox (17 sessions, about 43 USD). The reviewer at low effort found every
+seeded defect that was still in the diff, habit capture and the review count
+passed, and D1–D8 were each found live, fixed, and checked again in a later
+round. The `/orc-fix` eval (E-F1) is still to do. The result
+files are in `eval/results/2.1.0/` (maintainer copy, not in the package).
+
+**What you have to do**
+
+| You have … | What happens |
+|---|---|
+| any install | Run `orc update`. It removes the three renamed agent files and the two deleted twins. |
+| a compiled `orc diy` flow | The status line shows `STALE→recompile`, and `/orc-diy` refuses. Run `orc diy compile`. |
+| `rubric_bands_override`, `fixed_executor` or `extra_fallback_agent` with an old executor | It works. Those executors still ship. |
+| a main session on Opus 4.8 or Sonnet | Scores 41–64 now run on the session model (before, from 65). The tier line says so. |
+| a config or old traces that name `claude-sonnet-5` | They still work and still price. |
+| old traces that name the old reviewer | `orc stats` and `/orc-retro` still read them. |
+| a script that names `orc-reviewer-opus-5-med` | It breaks. Change it to `orc-reviewer-opus-5-low`. |
+| a script that observes with `author: orc` and no `run` | It exits 2 and names `run`. Add `run`. |
+| a 2.0.4 CLI on the same project | It reads the new observation fields. If it writes the same observation again, it drops `introduced_by` for that one row. |
+| Review quality in the panel | The review count goes up, because traces count now. Acceptance does not change. |
+| `refreshInterval` 1–60 in `settings.json` | `orc update` keeps it. |
+| habits off | `orc lane config --json --no-probes` is byte-identical. |
+
+New files `review-scope.jsonl` and `logs-rollup.json` are your data: they are not
+in the install manifest, they survive `orc update`, `--prune` and `doctor --fix`,
+and `orc clear logs` never deletes them.
+
+---
+
+### v2.0.4 — design the status line to the last cell _(2026-09-30)_
+
+**Still on the unscoped `orc` package?** Do this once first - your `orc upgrade`
+is the pre-v0.56.0 one and cannot install itself. Full detail in the CAUTION at
+the top of this file.
+
+- **Step 1 - release the command from the old package:** `npm uninstall -g orc`
+- **Step 2 - install the current package:** `npm i -g @azure-id/orc`
+- **Step 3 - re-apply it to your project:** `orc update`
+
+**Do not use `npm i -g -f`.** Full detail in v0.56.0 below.
+
+`orc ui` ▸ CLI Hook Interface can now change almost everything a terminal cell can
+show. Before, a bar drew only its cells: you could not put words before, after,
+above or below it, and a gradient used fixed colours. Every item below is a
+`orc statusline set` flag, and the part editor has a control for each one.
+
+**Words around any shape**
+
+- **A name on every shape.** `--label` now draws on a bar, a spark, an icon and a
+  motion mark too. `--label-pos before|after|above|below` says where it goes. A name
+  you already typed on a bar shows before it when you choose no position.
+- **Text before and after the shape.** `--prefix` and `--suffix` wrap a bar, for
+  example `[██░░]`.
+- **The number next to the bar.** `--value-pos before|after` draws the value of the
+  part beside its shape, with your number format.
+- **Captions.** `--caption "five-hour window"` puts a short text on a row above or
+  below the part, at the column of the part (`--caption-pos`, `--caption-align
+  left|center|right`, `--caption-color`, `--caption-case`). `{value}` and `{label}`
+  in the text are replaced.
+- **Small text.** A terminal has no font size, so `--case` (and `--caption-case`)
+  have three Unicode styles: `small` (ꜱᴍᴀʟʟ ᴄᴀᴘꜱ), `super` (ˢᵘᵖᵉʳ) and `sub` (numbers like ₆₁).
+
+**Bars in your own colours and characters**
+
+- `--fill-color` and `--empty-color` colour the filled and the empty cells.
+- `--ramp-colors "#22c55e,#eab308,#ef4444"` and `--ramp-stops "0,60,85"` give any
+  part your own colour range. On `gradient` with hex colours, each cell is blended
+  in true colour.
+- `--fill-char ■ --empty-char □` draw the bar with your own characters (one cell
+  each).
+- `--threshold` sets the mark on `split` and `marker`.
+
+**More control on every part**
+
+- `--brackets "⟦,⟧"`, `--pad-left`, `--pad-right`, `--align`, `--sign`, `--max-len`
+  and `--unknown dash|hide`.
+- `--bg` and any `#rrggbb` colour are in the editor now, and you can pick more than
+  one weight (bold and underline).
+- `--state-color "ok=green,critical=red"` and `--state-glyph "ok=✓"` per state.
+- `--param k=v` sets the settings of a part (the text of `text`, the clock format).
+
+**Lines**
+
+- `orc statusline line <n> --align right|center` and `--sep-color`. The panel also
+  takes your own separator text.
+
+**Six parts that drew nothing now work**
+
+- `text`, `divider`, `spacer`, `icon-static`, `fill` and `config` bound a value that
+  is always empty, and no command could set their text. They draw now. `fill`
+  pushes the parts after it to the right edge of the terminal.
+
+**Animated pets and weather**
+
+- **Eight pets that move** (group "Pets and motion"): `pet-cat` (a pixel cat drawn
+  in braille dots), `pet-mouse`, `pet-chase` (the cat chases the mouse),
+  `pet-cat-text` (ᓚᘏᗢ), `pet-pacman` (it eats the dots), `pet-fish`, `pet-bird` and
+  `pet-dog`. Each has three shapes: `run` (across the track), `bounce` (right and
+  back) and `idle` (stays and moves its legs), a track width of 6–40 cells, and a
+  `speed` setting.
+- **Weather:** `weather` (the temperature), `weather-icon` (☼ ◐ ☁ ☂ ❄ ϟ ≋) and
+  `weather-desc`. Set `location` (empty = found from your network address) and
+  `units` (`metric` or `us`). The hook never waits on the network: a small
+  background fetcher asks wttr.in at most every 30 minutes, and only while a weather
+  part is on your layout. `ORC_STATUSLINE_NO_NET=1` stops it.
+- **`orc statusline refresh <seconds|off>`** sets `refreshInterval` in the status
+  line setting. Claude Code redraws the status line only on events, or on this
+  timer (at least 1 second). So a pet moves about one step per second. The panel has
+  the same control, and tells you when a moving part has no timer.
+
+**The panel**
+
+- **Live preview of unsaved changes.** The panel replays your staged changes in a
+  temporary copy and draws the real result before you press Apply. A change that
+  the CLI refuses is named before Apply.
+- **The preview moves.** A layout with a pet or a motion mark plays 12 frames in the
+  panel (at most 20 seconds, never when your system asks for reduced motion).
+- A new `designer` preset shows the new powers.
+
+**Fixes**
+
+- **Text above or below a part showed at the start of the line.** Claude Code
+  removes the spaces at the start of every status line row, so a caption row, a
+  line prefix and a right-aligned line lost their indent. The first space of such a
+  row is now a braille blank (U+2800), which Claude Code keeps. The caption shows
+  above or below its own part.
+- **Spark showed nothing.** `burn-rate` and `tok-speed` never recorded a history,
+  the first sample came after 20 seconds, and an empty history drew `░░░░░░░░`.
+  Now every history is recorded, the first sample is taken at once, the spark adds
+  the current value as its last point, and an empty spark shows `—`. `spark-braille`
+  keeps its width, and `trend` with one point shows `—`.
+- **An unknown value on a bar drew an empty bar** (it read as 0%). It shows `—` now.
+- **A small value on a bar drew no cell** (6% on 10 cells). A value above 0 fills
+  at least one cell.
+- **`fill` could make a row wrap.** It leaves the last column free.
+- **Parts disappeared on a wide terminal.** When any line was wider than 72 cells,
+  the plan for a narrow terminal was used on every wider one too, and it could
+  remove a part from a line that fitted. Now a part is removed only when the
+  terminal is narrower than the widest line, and only from a line that does not fit.
+- Clearing a text field or a weight in the panel returned HTTP 400 ("missing
+  argument"). The clear now reaches the CLI.
+- A label, caption or separator with a control character (for example ESC) is
+  refused. Before, a layout could send terminal escape codes to your terminal.
+- `orc statusline set … --board subagent` read `subagent` as the part type.
+
+**What you have to do:** `orc update`. Layouts you already have compile to the same
+bytes.
+
+---
+
+### v2.0.3 — the status line you designed is the status line you see _(2026-09-30)_
+
+**Still on the unscoped `orc` package?** Do this once first - your `orc upgrade`
+is the pre-v0.56.0 one and cannot install itself. Full detail in the CAUTION at
+the top of this file.
+
+- **Step 1 - release the command from the old package:** `npm uninstall -g orc`
+- **Step 2 - install the current package:** `npm i -g @azure-id/orc`
+- **Step 3 - re-apply it to your project:** `orc update`
+
+**Do not use `npm i -g -f`.** Full detail in v0.56.0 below.
+
+A patch for `orc ui` ▸ CLI Hook Interface. You designed a status line, the panel said
+"Your lines are showing", and the terminal showed ORC's built-in lines. Some settings
+also did nothing when you applied them. Each fix is below.
+
+**Why your design fell back to the built-in lines**
+
+- **The hook compared version numbers, not the parts it can draw.** It refused a
+  compiled layout when the ORC version that compiled it was not the version of the
+  installed hooks. A CLI one patch newer than the hooks, or any upgrade, sent the bar
+  back to the built-in lines. Now `orc init` and `orc update` write `catalog_hash` into
+  `hooks/orc-version.json`, and the hook compares that hash with the lock. A different
+  version with the same parts renders your layout. An install with no hash keeps the
+  old version check.
+- **`orc update` recompiles your layout.** Before, nothing recompiled it after an
+  upgrade. Both boards are recompiled when their layout exists and validates. A layout
+  that does not validate is not touched, and the output says so.
+- **The panel tells you when your terminal does not show your layout.** `statusline
+  show --json` now carries `hook` (the installed hook, its version, whether it matches,
+  the recorded fallback and the fix). The status card shows "NOT IN YOUR TERMINAL" and
+  the command to copy (`orc update`, `orc update --global` or `orc statusline compile`).
+  `orc doctor` reports the same as `statusline-hook-skew`, with `fix_command`.
+- **A good render and a compile both clear the old fallback record**, so `orc doctor`
+  does not report a problem that is already gone.
+- **`statusline_custom: on  # a comment` now arms the layout** (and the same for
+  `subagent_line_custom`).
+- **A compiled op the hook does not know** falls back as `statusline-layout-skew`.
+
+**Settings that did nothing**
+
+- **You can clear a field.** An empty Name, Before, After or number sets the field back
+  to the shared value, and the colour and weight pickers have a "shared" option
+  (`--value-color inherit`). Before, the write said "ok" and changed nothing.
+- **A value that starts with `-` is kept** (for example a `-` prefix).
+- **Change part (swap) works** when the old shape does not fit the new part. The CLI
+  drops the old shape, name and width instead of refusing the swap.
+- **Your own colour and weight reach a bar.** A default colour ramp won over the value
+  colour you set, and the emphasis was lost with it.
+- **`mono` has no colour.** A default ramp no longer colours a `mono` bar.
+- **Apply stops at the first refused change.** The writes use positions, so a write
+  after a refusal changed the wrong part. The message names the refused change and how
+  many changes were not sent.
+- **A chip on the board shows the part as you saved it** (your name, colours and theme),
+  not the catalogue sample.
+
+**Parts that drew the wrong text**
+
+- `api-time` and `wall-time` showed milliseconds as minutes (`api 960000m`).
+- `clock` showed a raw number (`1767225600000`). It shows `HH:mm` now.
+- `pill` put the value inside the brackets (`⟪ORC2.0.2⟫`). It is `⟪ORC⟫2.0.2` now.
+- `effort` with `dots` drew nothing.
+- `lines-added` showed `+ +412`.
+- Four part descriptions still said the limit is five parts. It is six.
+
+**Also in `orc ui`**
+
+- The global-install banner could show twice, and it offered the wrong command
+  (`orc wiki sync`). It shows once and offers `orc update --global`.
+
+**What you have to do:** `orc update`. Your layout is recompiled for you.
+
+---
+
+### v2.0.2 — the lanes record what you answered, and the reviewer always gets the card _(2026-09-28)_
+
+**Still on the unscoped `orc` package?** Do this once first - your `orc upgrade`
+is the pre-v0.56.0 one and cannot install itself. Full detail in the CAUTION at
+the top of this file.
+
+- **Step 1 - release the command from the old package:** `npm uninstall -g orc`
+- **Step 2 - install the current package:** `npm i -g @azure-id/orc`
+- **Step 3 - re-apply it to your project:** `orc update`
+
+**Do not use `npm i -g -f`.** Full detail in v0.56.0 below.
+
+A patch from the live evals of 2.0 (E1–E4 in the eval sandbox). The habits feature did
+not work in live use until this release: the lanes forgot to record answers, used their
+own option and question names, and recorded a follow-up decision as the same question.
+Each fix below is in the CLI or a hook, not in more lane prose.
+
+- **`orc trace write` checks every `ASK` as it arrives.** A wrong option id, an unknown
+  question id, or a repeat of the same question with no new executor dispatch (a
+  follow-up) is kept OUT of the trace and handed back with the real ids, first in the
+  answer. The rest of the packet is written.
+- **The FINISH packet names the questions nobody recorded.** With `habits` on, the answer
+  lists each registered question of the lane that has no `ASK` in the run, with its
+  option ids. A late packet with `run: <trace name>` still lands after `.current` is gone.
+- **Habit evidence is not split by context.** The "any context" row counts every answer;
+  a row with `kind`/`branch` is a refinement. A dispatch-gate answer may list a
+  third-party slot. The habit cache version changed, so a parser change clears it.
+- **The narration guard** (session hook, `Stop`). A run that dispatched agents and wrote
+  NO narration line is stopped ONCE, with the command that fixes it. Never twice, never
+  for a subagent.
+- **The reviewer always gets the gotcha card** (session hook, `SubagentStart`). A live
+  review got no card in 5 of 5 runs. Now every `orc-reviewer-*`, `orc-verifier-*` and
+  `orc-judge-*` receives the card for the files git sees as changed. `orc update` wires
+  the new event; `orc doctor` names it when it is missing.
+- **`/orc-quick` takes the undo snapshot.** Its own start step names
+  `orc run snapshot` (before: 3 of 8 runs took it; after: 6 of 6).
+- **`rules_card_compact` is `on` by default.** Eval E4 (12 runs) passed: no new
+  `unmet[]`, no new `rules_conflicts[]`, the smoke gate green on the first try in 6 of 6
+  runs with the compact card against 3 of 6 without. `off` gives the full card.
+
+**Eval results:** E1 (the trim broke nothing) passed · E2 (habits) passed — 6 answers →
+the offer "5 of 5" → accepted → the next run marks `→ usual` and still asks; with
+`habits: off` zero `ASK` lines · E3 (the gotcha card): E3 (the gotcha card): with the card the reviewer found all 3 recurring defects in 5 of 5 runs (without: 2.4 of 3; the float-money defect 5 of 5 against 2 of 5), ordinary recall was equal (3.0), false positives fell from 2.2 to 1.0 per run. The planned gap of 1.0 could not be reached: without the card the reviewer already finds 2 of the 3, so the most the card could add was 0.6, and it added all of it · E4 passed (above).
+
+**What you have to do:** `orc update`.
+
+---
+
+### v2.0.1 — the trace keeps the gate name, and the lanes find the habits rule _(2026-09-27)_
+
+**Still on the unscoped `orc` package?** Do this once first - your `orc upgrade`
+is the pre-v0.56.0 one and cannot install itself. Full detail in the CAUTION at
+the top of this file.
+
+- **Step 1 - release the command from the old package:** `npm uninstall -g orc`
+- **Step 2 - install the current package:** `npm i -g @azure-id/orc`
+- **Step 3 - re-apply it to your project:** `orc update`
+
+**Do not use `npm i -g -f`.** Full detail in v0.56.0 below.
+
+A patch. The first live runs of 2.0.0 in the eval sandbox found four defects. Nothing
+changes for a user who has `habits` off, except that traces are complete again.
+
+- **`orc trace write` keeps the gate name.** A lane often sent `verb: GATE` and put
+  the rest in the tail. The CLI then wrote `GATE :: …`, and the name and the
+  `pass|bounce|escalate` word were lost (`orc stats` and `/orc-retro` read them).
+  The CLI now puts each event into the shape of its own grammar in `TRACE_VERBS`:
+  - `note:`, `detail:` or `text:` is used as the tail when `tail` is missing
+    (before: an EMPTY `.txt` line);
+  - a ` :: ` inside `verb` splits into head and tail, and a tail that starts with
+    `::` loses it (before: `GATE x :: :: …`);
+  - a verb with no ` :: ` in its grammar (`OUTCOME`, `FINDING`, `PHASE` …) that
+    has only a tail is joined to its head;
+  - a verb whose grammar needs head arguments (`GATE <name> pass|…`, `ASK <qid>`,
+    `DISPATCH <agent>`, `SCORE task=…`) is repaired from `args :: detail` in the
+    tail, or REFUSED by name (exit 2, nothing written) — the lane then uses the
+    writer agent.
+  `_shared/phases/trace.md` says it once: `verb` = the WHOLE head, `tail` = the detail.
+- **The lanes find the habits rule.** The `habits{}` pointer sat in each spine's
+  lane-contract block, far from the step that reads the answer, and a live
+  `/orc-quick` run with `habits: propose` never opened `_shared/habits.md` and
+  wrote no `ASK`. The rule now sits IN the step that reads `orc lane config`:
+  `/orc-quick` Q0 step 1, `/orc-mini` Phase 0, and `_shared/phases/preflight.md`
+  step 1 (orc, fast, test, pr-setup). The orc and fast spine copies were removed.
+
+**What you have to do:** `orc update`.
+
+---
+
+### v2.0.0 — the coding lanes remember what you fixed and how you work _(2026-09-27)_
+
+**Still on the unscoped `orc` package?** Do this once first - your `orc upgrade`
+is the pre-v0.56.0 one and cannot install itself. Full detail in the CAUTION at
+the top of this file.
+
+- **Step 1 - release the command from the old package:** `npm uninstall -g orc`
+- **Step 2 - install the current package:** `npm i -g @azure-id/orc`
+- **Step 3 - re-apply it to your project:** `orc update`
+
+**Do not use `npm i -g -f`.** Full detail in v0.56.0 below.
+
+This release does five things. The coding lanes load less than half the text
+they loaded before. ORC can learn the answers you give to its questions, but
+only when you turn that on, and it applies nothing without your yes. The repair
+memory (gotchas) learns from reviews, Sonar, SARIF, PR threads and closed
+defects. The reviewer returns more facts about each finding. And a set of small
+tools: `orc undo`, `orc pr threads`, `orc ci failed`, `orc ci flaky`, an
+end-of-run card, questions per run in `orc stats`, a terminal bell, and the run
+pointer after a compact.
+
+**BREAKING.** This is a major version because five contracts change in a way
+that a 1.9.x user or a fork can see:
+
+1. **`/orc-quick` now takes part in the review memory.** Before, quick did not
+   read gotchas and did not record them, and its dispatch gate said never to
+   remember an answer for the next entry. Now quick reads the gotcha card when
+   it offers a review, records the review outcome, and shows a habit
+   suggestion on its `→ suggested` line (only when `habits` is not `off`). The
+   gate is still asked every time.
+2. **The reviewer return has new REQUIRED fields**: `category` (a closed set of
+   11 values), `scenario` on every P0 and P1, and `pre_existing`. A forked or
+   hand-edited reviewer agent that does not return them fails the return
+   validation, and the orchestrator treats its return as malformed.
+3. **The closed trace verb set is larger**: `ASK` (one answered question),
+   `FINDING-OUTCOME` (what became of each finding at review close) and the
+   `GATE flaky` result. `FINDING` has optional tail fields
+   (`pre=` `suppressed=` `folded=`). A trace reader that treats the verb set as
+   closed must learn them. Old traces parse as before.
+4. **The lane spines have a new shape.** The shared lane contract text moved to
+   `_shared/lane-contract.md`, and worker instructions live in the agent files
+   only. `orc update` overwrites an installed spine as it always did, so a
+   hand patch on a spine is lost.
+5. **Config resolution has a new rank, `learned`,** below your config file and
+   above the shipped default, and a new state word `learned`. Both appear ONLY
+   when `habits` is not `off`.
+
+Nothing is removed: no config key is retired, no command is renamed, and no file
+that you own moves.
+
+**T — the lanes load less.** Each lane reads the same rules from fewer bytes.
+The trace protocol went from 36,089 to 7,885 bytes (the full verb table is now
+on demand, and each lane gets only its own verbs from `orc lane phases`). The
+file banners, history and repeated exit codes left the payload. The coding
+spines have a 16,384-byte cap. Worker instructions have one source, the agent
+file. The descriptions that load in every session went from 11,711 to 6,587
+characters, and three internal skills are hidden from the skill list.
+`orc lane config --json` now carries a `probes{}` block, so a preflight reads
+up to seven probe answers from one call. `orc trace write --packet -` writes
+the `.txt` and the `.jsonl` of a trace from one packet (the Haiku trace writer
+is now the fallback). 16 more agent files are generated from
+`agents-src/twins/`, and `node bin/build-agents.js --check` (part of
+`npm run verify`) covers them.
+
+Always-loaded bytes per lane (`spine + command + when: "always"` references):
+
+| Lane | 1.9.2 | after the trim | 2.0.0 | change |
+|---|---|---|---|---|
+| orc | 60,169 | 29,289 | 29,124 | −52 % |
+| orc-mini | 56,153 | 24,851 | 24,697 | −56 % |
+| orc-fast | 59,142 | 27,793 | 27,750 | −53 % |
+| orc-quick | 61,858 | 30,998 | 30,768 | −50 % |
+| orc-verify | 42,330 | 13,224 | 13,035 | −69 % |
+| orc-test | 61,566 | 28,295 | 27,994 | −55 % |
+| orc-pr-setup | 56,130 | 24,673 | 24,380 | −57 % |
+| orc-pr-driver | 48,456 | 18,071 | 17,882 | −63 % |
+| orc-analyze | 52,351 | 21,514 | 21,339 | −59 % |
+| orc-analyze-mini | 43,792 | 13,401 | 13,212 | −70 % |
+| orc-poly | 51,483 | 20,826 | 20,637 | −60 % |
+| orc-route | 47,454 | 16,923 | 16,734 | −65 % |
+| orc-wait | 7,082 | 6,696 | 6,693 | −5 % |
+| orc-diy | 8,098 | 5,292 | 5,278 | −35 % |
+| context-combiner | 13,193 | 11,472 | 11,472 | −13 % |
+| orc-pattern | 45,748 | 16,249 | 16,060 | −65 % |
+| orc-advisor | 2,916 | 2,605 | 2,605 | −11 % |
+| orc-judge | 4,679 | 4,280 | 4,280 | −9 % |
+| **sum** | **722,600** | **316,452** | **313,940** | **−57 %** |
+
+The habits, gotchas and review work that came after the trim added no byte to
+any lane above its trimmed value: the new text is read on demand.
+
+**H — habits (off by default).** New key `habits`: `off` · `observe` ·
+`propose`.
+
+- `off` (the default) costs zero tokens: `orc lane config --json` has no
+  habits field (with `--no-probes` it is byte-identical to 1.9.2), and no lane
+  writes an `ASK` line.
+- `observe`: each answered question writes one `ASK` line into the trace.
+  `orc habit show` computes your usual answers from those lines. It proposes
+  nothing.
+- `propose`: at the END of a run, at most once, ORC asks whether an answer you
+  keep giving should become your usual one. The rule is fixed in the CLI: at
+  least 5 full-weight answers, a Wilson lower bound of 0.55 or more, and the
+  last 3 answers the same.
+- Nothing is applied without your yes. There is no automatic level, and
+  `auto` is refused by name. An accepted habit is the `learned` rank, below
+  your config file: `orc config set` always wins. `orc habit forget <id>`
+  undoes it.
+- A habit can learn only toward the careful side: `review_before_push: on`,
+  `mini_tdd: on`, `quick_update_tests: on`. A habit to skip a review, to drop
+  TDD or to continue on a stale wiki is never applied. A dispatch gate is
+  asked every time; a habit only orders the offer.
+- 30 question points in the lanes carry an `(H <qid>)` mark.
+  `orc habit points` lists them.
+- Commands: `orc habit show | log | points | why | accept | decline | forget |
+  reset | doctor | export | purge`, and `orc habit repo` for the soft
+  preferences read from git history (commit, branch and test naming).
+- New keys: `review_before_push` (`ask`), `mini_tdd` (`ask`),
+  `quick_update_tests` (`ask`).
+
+**G — gotchas v2, importers and sync.** The repair memory learns from more
+sources, and the reviewer gets a card.
+
+- `orc gotcha add | match | card | filter | observe | accept | quality | why`,
+  `orc gotcha list --candidates` and `orc gotcha export --review-md`.
+- `orc gotcha card` is the reviewer card, sized by `gotcha_card_budget`
+  (600 tokens, minimum 200). It is always on: `gotcha_card_budget` is a size,
+  not an off switch. An entry that does not fit is counted in the card header.
+- Observations go to `.claude/orc/observations.jsonl`. A candidate becomes an
+  entry by a fixed rule: an in-lane red → green with a reproduction, a miss, a
+  security finding with a CWE tag or a HIGH impact, or 3 addressed cases in 2
+  PRs within 90 days. `orc gotcha accept <C-id>` promotes one by hand.
+- `orc gotcha filter` drops suppressed, folded and noisy advice. It never
+  removes a P0 or a P1.
+- Importers: `orc gotcha import sarif <file>`,
+  `orc gotcha import sonar` (the token comes from `SONAR_TOKEN` only),
+  `orc gotcha import pr <n>` (human threads only) and
+  `orc gotcha import issues`. `orc gotcha sync` runs every source that is
+  available, incremental and time-boxed. New keys: `gotcha_card_budget`,
+  `gotcha_sync_hours` (6), `sonar_url`, `sonar_project`, `sonar_org`.
+- A v1 `gotchas.md` stays valid, with no rewrite. The 1.9.2 parser still reads
+  a file that 2.0.0 wrote (a test copies its regex).
+- The status line gotcha count now shows a number. It was always empty.
+
+**R — the reviewer v2.** New `_shared/review-slice.md` names the slice fields
+once. The reviewer gets the diff ranges, the gotcha card, the rules card and
+the tool findings. It returns `category`, `cwe`, `scenario`, `pre_existing`,
+`group` and `confidence` on each finding. `/orc` and `/orc-ultra` can dispatch
+a disprove pass on a P0/P1. A re-review gets the previous findings. At review
+close the lane records each outcome, and `orc gotcha quality` measures the
+acceptance per category.
+
+**Q — quality of life.**
+
+- **`orc undo --run <slug>`** prints the commands that revert ONLY the files the
+  run changed, back to the snapshot taken at run start
+  (`orc run snapshot`). It changes nothing until you add `--apply`. An edit you
+  made before the run stays.
+- **`orc pr threads <n>`** lists the unresolved review threads.
+  **`orc ci failed`** lists the failing CI steps. Both are read-only.
+  `/orc-quick` takes a red CI, or Sonar and SARIF issues, as a request.
+- **`orc ci flaky`** tells a flaky local red from a real one. A flaky re-run
+  does not use a repair round, and the trace gets `GATE flaky`.
+- **The end-of-run card** names what changed and the undo command. Quick
+  prints it in place of `git checkout -- .`.
+- **`orc stats --json`** has `questions{}`: questions per run, per lane and per
+  point.
+- **`notify: bell`** rings the terminal bell once when a turn of an ORC run
+  ends. `off` is the default and is silent.
+- **After a compact**, the session hook prints the run pointer line again.
+- **`rules_card_compact`** (`off`) would give `/orc-mini` and `/orc-fast` the
+  compact rules card. It stays off until eval E4 passes.
+
+**U — `orc ui` ▸ Behaviour.** A new panel under Stats, key `u`. It shows the
+learning switch (Off · Observe · Propose), your habits with their evidence and
+the buttons the CLI allows, the rhythm of your runs, the gotchas and what the
+reviewer will see, review quality per category, and the answer log. It renders
+the CLI's lines and computes no habit. A `never` habit has no button. With
+`habits: off`, one card replaces the tabs. Reduced motion stops all motion.
+
+**Upgrade notes — what a 1.9.2 install keeps, and what changes.**
+
+- `.claude/orc.config.yaml` is read as it is. No key is renamed or retired. The
+  new keys resolve to their defaults: `habits: off`, `review_before_push: ask`,
+  `mini_tdd: ask`, `quick_update_tests: ask`, `gotcha_card_budget: 600`,
+  `gotcha_sync_hours: 6`, `notify: off`, `rules_card_compact: off`, and the
+  `sonar_*` keys empty.
+- `.claude/orc/gotchas.md` and its archive stay valid, with no rewrite. A
+  downgrade to 1.9.2 still parses the file.
+- `gotchas: off` no longer removes the reviewer card, because review learning is
+  always on. `orc config set gotchas off` says so. An old `gotchas: off` still
+  turns off the executor block (`orc gotcha match` exits 4).
+- Old traces are read as they are. They have no `ASK` lines, so the habits start
+  at `none yet`. Nothing is guessed from old `NOTE` lines.
+- Every existing field of `orc lane config --json` and `orc config list --json`
+  is unchanged (a test pins them). `probes{}` is added; `habits{}`, the
+  `learned` source and the `learned` state appear only when `habits` is on.
+- `orc gotcha status | list | show | prune` are unchanged, with the same exit
+  codes.
+- **A DIY flow compiled by 1.9.x is STALE after the update**, because the
+  version and the composed layers changed. Run `orc diy compile` after the
+  update. Until then `orc diy status` exits 1 and `/orc-diy` offers the compile
+  or plain `/orc`.
+- A forked or hand-edited reviewer agent fails the v2 return validation (see
+  BREAKING item 2). Hand-edited installed spines are overwritten, as always.
+- **`orc update` wires the new session hook** (`orc-session-hook.js`) into
+  `.claude/settings.json`: ONE `Stop` entry and ONE `SessionStart` entry with
+  the matcher `compact`. It is always wired. The `Stop` hook reads `notify` first
+  and stays silent unless `notify: bell`. `orc doctor` checks both entries, and
+  when one is missing it names `orc update` as the fix
+  (`session-hook-unwired`).
+- New files are user data: `habits-state.json`, `habits-cache.json`,
+  `observations.jsonl`, `gotchas-sync.json`. They are never in the install
+  manifest, and they survive `update`, `update --prune` and `doctor --fix`.
+- Node ≥ 18 and zero npm dependencies, as before.
+
+**Evals owed.** Four evals are prepared and NOT run. Each needs a live Claude
+Code session in the sandbox:
+
+- **E1** — trace parity before and after the trim.
+- **E2** — six `/orc-quick` requests under `habits: propose` give one proposal,
+  and the seventh shows `→ usual`.
+- **E3** — five reviews with the gotcha card and five without it. The card
+  stays on whatever the result is.
+- **E4** — the compact rules card on `/orc-mini` and `/orc-fast`.
+  `rules_card_compact` stays `off` until E4 passes.
+
+**What you have to do:** `orc update`. Then, if you use `/orc-diy`,
+`orc diy compile`. To try habits, `orc config set habits observe`.
+
+---
+
 ### v1.9.2 — the code graph gets its own tab, and Opus 5 becomes Opus 5.5 _(2026-09-23)_
 
 **Still on the unscoped `orc` package?** Do this once first - your `orc upgrade`