@azure-id/orc 1.9.2 → 2.1.0

package/mock-run/INDEX.md

@@ -1,107 +1,110 @@
-# Mocked runs — what each ORC lane looks like when it runs
-
-New to ORC? Start here. Every file below is a **mocked run**: the screen you
-would see, the questions you would be asked, and the files that would land on
-disk — written the way the real lane writes them.
-
-Nothing here was executed. It is documentation, and it is here because you
-should not have to spend tokens to find out what a command does.
-
-All of it uses **easy English**, short sentences, and the same fake project.
-
-> **Read it in the panel instead:** `orc ui` ▸ **Mocked Skill Use** — the same
-> documents, searchable, with a reading pane. From the terminal:
-> `orc mock-run list` and `orc mock-run show <slug>`.
-
----
-
-## Start here
-
-| Doc | What it shows |
-|---|---|
-| [The example project](the-example-project.md) | `shopcart`, the fake project every mock uses, and how to read these files |
-| [A normal day](a-normal-day.md) | `/orc-pact`, `/orc-boundary`, `/orc-budget`, `/orc-aftermath` and the rest, all inside one ordinary run |
-
-## Build a change
-
-| Doc | Lane | One line |
-|---|---|---|
-| [orc](orc.md) | `/orc` | The full pipeline: intake → plan → score → parallel waves → review → verify → ship |
-| [orc-ultra](orc-ultra.md) | `/orc-ultra` | The same, plus an advisor and three judgment gates. Costs the most |
-| [orc-mini](../templates/skills/orc-mini/examples/mini-run-mock.md) | `/orc-mini` | One executor, a smoke gate, ship |
-| [orc-fast](orc-fast.md) | `/orc-fast` | No analyst, no planner — the wiki and the pattern already did that work |
-| [orc-quick](orc-quick.md) | `/orc-quick` | Ask for anything. Look → ask once → do, and it always asks which agent |
-| [orc-diy](orc-diy.md) | `/orc-diy` | Your own lane, composed in the terminal and compiled |
-
-## Decide what to build
-
-| Doc | Lane | One line |
-|---|---|---|
-| [orc-brainstorm](orc-brainstorm.md) | `/orc-brainstorm` | No idea yet: it generates the options and **you** pick |
-| [orc-grill](orc-grill.md) | `/orc-grill` | One vague idea, sharpened by questions — it never answers its own |
-| [orc-doc](orc-doc.md) | `/orc-doc` | A PRD, TSD, agreement, report or runbook — written in parts, so nothing holds it all |
-| [orc-plan](orc-plan.md) | `/orc-plan` | A real task plan: grounded files, dependencies, facets, test dispositions |
-| [orc-route](orc-route.md) | `/orc-route` | You have a plan — which lane should build it, and which cannot |
-| [orc-explain](orc-explain.md) | `/orc-explain` | "Wait, what?" — it says the last message again, properly |
-| [orc-analyze](../templates/skills/orc-analyze/examples/analyze-mock.md) | `/orc-analyze` | A document turned into code-grounded requirements |
-| [orc-analyze-mini](../templates/skills/orc-analyze-mini/examples/quick-analysis-mock.md) | *(inside `/orc-mini`)* | The same, single pass, much cheaper |
-| [context-combiner](context-combiner.md) | — | Two related analyses merged into one spec, with a 100% conservation gate |
-| [orc-poly](../templates/skills/orc-poly/examples/poly-run-mock.md) | `/orc-poly` | One change across two or more repos, without drift |
-
-## Teach ORC your project
-
-| Doc | Lane | One line |
-|---|---|---|
-| [orc-rules](orc-rules.md) | `orc rules` | The anti-slop rules: 65 shipped read-only, plus your own, which win |
-| [orc-wiki](../templates/skills/orc-wiki/examples/wiki-run-mock.md) | `/orc-wiki` | Scan the codebase into an evidence-anchored knowledge base |
-| [orc-pattern](orc-pattern.md) | `/orc-pattern` | Learn your real conventions so executors match your house style |
-| [orc-learn](../templates/skills/orc-learn/examples/learn-run-mock.md) | `/orc-learn` | Onboarding docs for a human, per feature |
-| [orc-claude](../templates/skills/orc-claude/examples/claude-run-mock.md) | `/orc-claude` | Build or refresh this repo's `CLAUDE.md` from verified facts |
-| [orc-export](orc-export.md) | `/orc-export` | Compile it all into a portable `AGENTS.md` so ORC is not a trap |
-
-## Check what happened
-
-| Doc | Lane | One line |
-|---|---|---|
-| [orc-verify](../templates/skills/orc-verify/examples/verify-mock.md) | `/orc-verify` | Verify only your git-modified changes. Read-only |
-| [orc-challenge](orc-challenge.md) | `/orc-challenge` | Grade a finished document, then stop and make you fix it in another session |
-| [orc-challenge-council](orc-challenge-council.md) | `/orc-challenge` | Six more ways of looking at the same document — and you choose which ones run |
-| [orc-pact](orc-pact.md) | `/orc-pact` | The promises your system makes, and which are in doubt right now |
-| [orc-boundary](orc-boundary.md) | `/orc-boundary` | What the agent should **not** try here, and what would change that |
-| [orc-aftermath](orc-aftermath.md) | `/orc-aftermath` | Did what we shipped hold up. Churn is a signal, never a verdict |
-| [orc-budget](orc-budget.md) | `/orc-budget` | What a run costs, in the unit you are billed in |
-| [orc-retro](../templates/skills/orc-retro/examples/retro-mock.md) | `/orc-retro` | Mine the behavior traces into a calibration report |
-
-## Ship and hand over
-
-| Doc | Lane | One line |
-|---|---|---|
-| [orc-pr-setup / orc-pr-driver](orc-pr-setup.md) | `/orc-pr-setup`, `/orc-pr-driver` | Split a big change into a stack of PRs, then build and merge them |
-| [orc-handoff](orc-handoff.md) | `/orc-handoff` | What a non-developer can safely change, graded by whether a check exists |
-
-## Panel and terminal
-
-| Doc | One line |
-|---|---|
-| [orc-ui](orc-ui.md) | The local control panel for everything that is not ai (**video placeholder here**) |
-| [orc-cli](orc-cli.md) | The terminal commands: install, config, probes, run state, stats |
-| [orc-extra](orc-extra.md) | Run some of ORC's work on a different AI model, and still know what left your machine |
-| [extra-recovery](extra-recovery.md) | When that other model stops half-way: what it left on disk, whose fault it was, and how to continue |
-| [extra-slots](extra-slots.md) | The four lanes that never score a task: giving one JOB to a cheaper model, and what ORC says before it does |
-
----
-
-## Two kinds of document
-
-- **Walkthroughs** (this folder) — written for a person, in easy English.
-- **Annotated examples** (`templates/skills/<skill>/examples/`) — dense, written
-  for the model, and shipped inside your `.claude/` install. Both appear in
-  `orc mock-run list` and in the **Mocked Skill Use** panel.
-
-## Adding one
-
-Drop a `.md` file in this folder with a `# Title` heading and a `> one line`
-summary under it. It appears in `orc mock-run`, in the panel, and here — no list
-to update anywhere else. Reading order comes from `GROUP_OF` in
-[`bin/mockrun-catalog.js`](../bin/mockrun-catalog.js); a file nobody placed
-there still shows, under **More**.
+# Mocked runs — what each ORC lane looks like when it runs
+
+New to ORC? Start here. Every file below is a **mocked run**: the screen you
+would see, the questions you would be asked, and the files that would land on
+disk — written the way the real lane writes them.
+
+Nothing here was executed. It is documentation, and it is here because you
+should not have to spend tokens to find out what a command does.
+
+All of it uses **easy English**, short sentences, and the same fake project.
+
+> **Read it in the panel instead:** `orc ui` ▸ **Mocked Skill Use** — the same
+> documents, searchable, with a reading pane. From the terminal:
+> `orc mock-run list` and `orc mock-run show <slug>`.
+
+---
+
+## Start here
+
+| Doc | What it shows |
+|---|---|
+| [The example project](the-example-project.md) | `shopcart`, the fake project every mock uses, and how to read these files |
+| [A normal day](a-normal-day.md) | `/orc-pact`, `/orc-boundary`, `/orc-budget`, `/orc-aftermath` and the rest, all inside one ordinary run |
+
+## Build a change
+
+| Doc | Lane | One line |
+|---|---|---|
+| [orc](orc.md) | `/orc` | The full pipeline: intake → plan → score → parallel waves → review → verify → ship |
+| [orc-ultra](orc-ultra.md) | `/orc-ultra` | The same, plus an advisor and three judgment gates. Costs the most |
+| [orc-mini](../templates/skills/orc-mini/examples/mini-run-mock.md) | `/orc-mini` | One executor, a smoke gate, ship |
+| [orc-fast](orc-fast.md) | `/orc-fast` | No analyst, no planner — the wiki and the pattern already did that work |
+| [orc-quick](orc-quick.md) | `/orc-quick` | Ask for anything. Look → ask once → do, and it always asks which agent |
+| [orc-diy](orc-diy.md) | `/orc-diy` | Your own lane, composed in the terminal and compiled |
+
+## Decide what to build
+
+| Doc | Lane | One line |
+|---|---|---|
+| [orc-brainstorm](orc-brainstorm.md) | `/orc-brainstorm` | No idea yet: it generates the options and **you** pick |
+| [orc-grill](orc-grill.md) | `/orc-grill` | One vague idea, sharpened by questions — it never answers its own |
+| [orc-doc](orc-doc.md) | `/orc-doc` | A PRD, TSD, agreement, report or runbook — written in parts, so nothing holds it all |
+| [orc-plan](orc-plan.md) | `/orc-plan` | A real task plan: grounded files, dependencies, facets, test dispositions |
+| [orc-route](orc-route.md) | `/orc-route` | You have a plan — which lane should build it, and which cannot |
+| [orc-explain](orc-explain.md) | `/orc-explain` | "Wait, what?" — it says the last message again, properly |
+| [orc-analyze](../templates/skills/orc-analyze/examples/analyze-mock.md) | `/orc-analyze` | A document turned into code-grounded requirements |
+| [orc-analyze-mini](../templates/skills/orc-analyze-mini/examples/quick-analysis-mock.md) | *(inside `/orc-mini`)* | The same, single pass, much cheaper |
+| [context-combiner](context-combiner.md) | — | Two related analyses merged into one spec, with a 100% conservation gate |
+| [orc-poly](../templates/skills/orc-poly/examples/poly-run-mock.md) | `/orc-poly` | One change across two or more repos, without drift |
+
+## Teach ORC your project
+
+| Doc | Lane | One line |
+|---|---|---|
+| [orc-rules](orc-rules.md) | `orc rules` | The anti-slop rules: 65 shipped read-only, plus your own, which win |
+| [orc-wiki](../templates/skills/orc-wiki/examples/wiki-run-mock.md) | `/orc-wiki` | Scan the codebase into an evidence-anchored knowledge base |
+| [orc-pattern](orc-pattern.md) | `/orc-pattern` | Learn your real conventions so executors match your house style |
+| [orc-learn](../templates/skills/orc-learn/examples/learn-run-mock.md) | `/orc-learn` | Onboarding docs for a human, per feature |
+| [orc-claude](../templates/skills/orc-claude/examples/claude-run-mock.md) | `/orc-claude` | Build or refresh this repo's `CLAUDE.md` from verified facts |
+| [orc-export](orc-export.md) | `/orc-export` | Compile it all into a portable `AGENTS.md` so ORC is not a trap |
+| [habits](habits.md) | `orc habit` | The answers you keep giving, proposed once at the end of a run. Off by default, never applied without your yes |
+| [gotcha-import](gotcha-import.md) | `orc gotcha import` | Teach the repair memory from SARIF, Sonar, PR threads and closed defects |
+
+## Check what happened
+
+| Doc | Lane | One line |
+|---|---|---|
+| [orc-verify](../templates/skills/orc-verify/examples/verify-mock.md) | `/orc-verify` | Verify only your git-modified changes. Read-only |
+| [orc-challenge](orc-challenge.md) | `/orc-challenge` | Grade a finished document, then stop and make you fix it in another session |
+| [orc-challenge-council](orc-challenge-council.md) | `/orc-challenge` | Six more ways of looking at the same document — and you choose which ones run |
+| [orc-pact](orc-pact.md) | `/orc-pact` | The promises your system makes, and which are in doubt right now |
+| [orc-boundary](orc-boundary.md) | `/orc-boundary` | What the agent should **not** try here, and what would change that |
+| [orc-aftermath](orc-aftermath.md) | `/orc-aftermath` | Did what we shipped hold up. Churn is a signal, never a verdict |
+| [orc-budget](orc-budget.md) | `/orc-budget` | What a run costs, in the unit you are billed in |
+| [orc-retro](../templates/skills/orc-retro/examples/retro-mock.md) | `/orc-retro` | Mine the behavior traces into a calibration report |
+| [orc-fix](orc-fix.md) | `/orc-fix` | Record a fix and what it fixes, so the next review sees it — and see what a review missed |
+
+## Ship and hand over
+
+| Doc | Lane | One line |
+|---|---|---|
+| [orc-pr-setup / orc-pr-driver](orc-pr-setup.md) | `/orc-pr-setup`, `/orc-pr-driver` | Split a big change into a stack of PRs, then build and merge them |
+| [orc-handoff](orc-handoff.md) | `/orc-handoff` | What a non-developer can safely change, graded by whether a check exists |
+
+## Panel and terminal
+
+| Doc | One line |
+|---|---|
+| [orc-ui](orc-ui.md) | The local control panel for everything that is not ai (**video placeholder here**) |
+| [orc-cli](orc-cli.md) | The terminal commands: install, config, probes, run state, stats |
+| [orc-extra](orc-extra.md) | Run some of ORC's work on a different AI model, and still know what left your machine |
+| [extra-recovery](extra-recovery.md) | When that other model stops half-way: what it left on disk, whose fault it was, and how to continue |
+| [extra-slots](extra-slots.md) | The four lanes that never score a task: giving one JOB to a cheaper model, and what ORC says before it does |
+
+---
+
+## Two kinds of document
+
+- **Walkthroughs** (this folder) — written for a person, in easy English.
+- **Annotated examples** (`templates/skills/<skill>/examples/`) — dense, written
+  for the model, and shipped inside your `.claude/` install. Both appear in
+  `orc mock-run list` and in the **Mocked Skill Use** panel.
+
+## Adding one
+
+Drop a `.md` file in this folder with a `# Title` heading and a `> one line`
+summary under it. It appears in `orc mock-run`, in the panel, and here — no list
+to update anywhere else. Reading order comes from `GROUP_OF` in
+[`bin/mockrun-catalog.js`](../bin/mockrun-catalog.js); a file nobody placed
+there still shows, under **More**.

package/mock-run/extra-slots.md

@@ -49,7 +49,7 @@ ORC · extra — the positions
   fast-executor       claude · orc-executor-sonnet-4-6-high   /orc-fast
   doc-writer          claude · orc-doc-writer-opus-5-med      /orc-doc
   doc-checker         claude · orc-doc-checker-opus-5-low     /orc-doc
-  wiki-scanner-deep   claude · orc-wiki-scanner-opus-4-8-high /orc-wiki
+  wiki-scanner-deep   claude · orc-wiki-scanner-opus-5-low /orc-wiki
   wiki-scanner-light  claude · orc-wiki-scanner-sonnet-5-high /orc-wiki
 
   what each position is

package/mock-run/gotcha-import.md

@@ -0,0 +1,118 @@
+# Mock run — gotcha import and sync (`orc gotcha`)
+
+> Teach the repair memory from what your tools and your reviewers already
+> said: SARIF, Sonar, PR threads and closed defects. No model, and nothing is
+> written to GitHub.
+
+---
+
+## 1. What it does
+
+Gotchas are ORC's repair memory: what this project already got wrong, and how
+it was fixed. Before 2.0.0 only a red → green inside a run could add one. Now
+the CLI also reads four outside sources and turns each finding into an
+**observation** in `.claude/orc/observations.jsonl`.
+
+An observation is not an entry yet. A candidate becomes an entry only by a
+fixed rule — or when you promote it yourself. The reviewer then gets a short
+**card** of the entries that match the files it reviews.
+
+---
+
+## 2. Import once, from each source
+
+```
+$ orc gotcha import sarif reports/eslint.sarif
+  sarif · ESLint · 14 results · 1 suppressed (skipped) · 13 observations
+  new since the last ESLint import: 4
+
+$ export SONAR_TOKEN=…            # the token is never a config key
+$ orc config set sonar_url https://sonarcloud.io
+$ orc config set sonar_project shopcart
+$ orc config set sonar_org shopcart-team
+$ orc gotcha import sonar --branch main
+  sonar · 9 issues · 9 observations
+
+$ orc gotcha import pr 212
+  pr #212 · 6 threads · 5 by people, 1 by a bot (measured, not recorded)
+  5 observations (3 addressed · 1 disputed · 1 open)
+
+$ orc gotcha import issues --label bug
+  issues · 4 closed defects with a closing PR · 4 observations
+```
+
+Every import is read-only. `gh` is used only to read, and a test with a fake
+`gh` proves that no call writes.
+
+---
+
+## 3. Keep it fresh
+
+```
+$ orc gotcha sync
+  sarif    nothing new
+  sonar    2 new issues
+  pr       #214: 1 new thread
+  issues   nothing new
+  synced · 3 observations · next sync due in 6 h (gotcha_sync_hours)
+```
+
+`sync` runs every source that is available, reads only what is new, and has a
+time limit. The review step of a lane runs it too. If a source fails, the lane
+goes on — a failed import never blocks a review.
+
+---
+
+## 4. From observations to an entry
+
+```
+$ orc gotcha list --candidates
+  C-004  money rounding in cart totals   3 addressed cases in 2 PRs   → promoted as G-017
+  C-007  missing await on db.save        2 addressed cases in 1 PR    needs 1 more case in 1 more PR
+  C-009  "prefer template literals"      4 disputed                   proposed suppression
+
+$ orc gotcha accept C-007
+  C-007 → G-018 (promoted by a person)
+```
+
+The fixed rule promotes a candidate on ONE of these:
+
+- a red → green inside a lane, with a reproduction;
+- a miss — an ORC review read those lines and did not flag them;
+- a security finding with a CWE tag or a HIGH impact (one case is enough);
+- 3 addressed cases in 2 PRs within 90 days.
+
+---
+
+## 5. What the reviewer sees
+
+```
+$ orc gotcha card --files src/cart/total.ts
+  gotchas · 2 of 18 match · budget 600 tokens · 0 dropped
+  G-017  money rounding in cart totals — round once, at the end, in cents
+  G-011  totals cached across currency switch — clear on currency change
+```
+
+The card is always on. `gotcha_card_budget` sets its size (600 tokens, at
+least 200). An entry that does not fit is counted in the header, never dropped
+in silence.
+
+---
+
+## 6. What to notice
+
+- **People teach, bots are measured.** A bot comment is counted for quality,
+  but it never becomes an entry by itself.
+- **`orc gotcha filter` never removes a P0 or a P1.** It removes only
+  suppressed, folded and noisy advice.
+- **Your v1 file stays valid.** `gotchas.md` is not rewritten, and ORC 1.9.2
+  can still read the file 2.0.0 writes.
+- **Quality is measured.** `orc gotcha quality` shows the acceptance per
+  category after five reviews, and `orc ui` ▸ **Behaviour** draws it.
+
+---
+
+## 7. Related
+
+- The full guide: [`guides/habits-and-gotchas.md`](../guides/habits-and-gotchas.md)
+- A normal run that uses the card: [orc](orc.md)

package/mock-run/habits.md

@@ -0,0 +1,129 @@
+# Mock run — habits (`orc habit`)
+
+> You keep giving the same answer to the same question. ORC notices, asks you
+> ONCE at the end of a run, and applies nothing without your yes.
+
+---
+
+## 1. What it does
+
+Every lane asks you questions: review first or commit now, use TDD or not,
+open a PR or commit only. Some of those answers are the same every time.
+
+With habits on, each answer writes one `ASK` line into the run's trace. The
+CLI (`orc habit`, no model) counts those lines. When one answer is clearly your
+usual, it proposes it — once, at the end of a run, inside the questions the
+lane already asks.
+
+Habits are **off by default**. Off costs zero tokens: no line is written, no
+question changes, and `orc lane config --json` has no habits field.
+
+---
+
+## 2. Turn it on
+
+```
+$ orc config set habits propose
+  habits: off → propose
+  ORC now writes one ASK line per answered question. At the end of a run it may
+  ask ONE question. Nothing is applied without your yes.
+```
+
+`observe` is the quieter step: ORC counts, and `orc habit show` tells you what
+it sees, but it never proposes.
+
+---
+
+## 3. Six runs later
+
+You ran `/orc-quick` six times on `shopcart`. Each time, at the Q3 offers, you
+chose **review first**. The seventh run opens with the usual preflight lines,
+plus one more:
+
+```
+habits: propose — 0 learned, 0 usual mark(s), 1 proposal for the end of the run
+```
+
+The work runs as normal. The dispatch gate still asks which agent to use —
+every time, with or without habits. At the end, the proposal is ONE line in
+the offers you already get:
+
+```
+Entry 7 written to orc-quick/cart-rounding/quick-context.md
+
+  1  review first     dispatch orc-reviewer-opus-5-low on the diff
+  2  commit directly
+  3  stop
+
+You chose review first in 6 of your last 6 answers to "Code review before
+commit". Make it your usual? [yes · not now · never]
+
+> 1, and yes
+```
+
+ORC runs the command that the `lane config` answer named for "yes". Nothing
+else changes in this run.
+
+---
+
+## 4. The next run
+
+```
+habits: propose — 0 learned, 1 usual mark(s), no proposal
+```
+
+```
+  1  review → then commit   → usual (6 of 6)
+  2  commit without review
+  3  stop
+```
+
+The usual answer is FIRST and marked. It is not pre-selected: the question is
+still asked, and the review is still a dispatch, so its gate still asks which
+agent.
+
+---
+
+## 5. Look at it, and undo it
+
+```
+$ orc habit show
+  mode propose · window 30d · 7 runs · 7 answers
+
+  H-3f9a2c  Code review before commit   applied   6 of 6
+            You chose review first in 6 of your last 6 answers to "Code review
+            before commit".
+            rule: Wilson95 LB 0.61 (n_eff 6, raw n 6) — proposes at ≥ 0.55 with
+            n ≥ 5 and the last 3 agreeing
+            undo: orc habit forget H-3f9a2c
+
+$ orc habit why H-3f9a2c        # every ASK line behind it
+$ orc habit forget H-3f9a2c     # back to asking with no mark
+```
+
+`orc ui` ▸ **Behaviour** shows the same rows, with the buttons the CLI allows.
+
+---
+
+## 6. What to notice
+
+- **Nothing is applied without your yes.** There is no automatic level, and
+  `orc config set habits auto` is refused by name.
+- **A habit moves only toward the careful side.** A habit can turn
+  `review_before_push`, `mini_tdd` or `quick_update_tests` to `on`. A habit to
+  skip a review, drop TDD or continue on a stale wiki is never applied.
+- **Your config file wins.** An accepted habit is the `learned` rank, below
+  `.claude/orc.config.yaml`. `orc config set` always beats it.
+- **Your words are never stored.** An answer in your own words is recorded as
+  `chose=other`.
+- **A habit can go stale.** Two overrides in the last three answers, or 90 days
+  without use, and ORC asks again at the end of a run.
+- **Old runs do not count.** Traces from before 2.0.0 have no `ASK` lines, so
+  habits start at `none yet`.
+
+---
+
+## 7. Related
+
+- The full guide: [`guides/habits-and-gotchas.md`](../guides/habits-and-gotchas.md)
+- The quick lane: [orc-quick](orc-quick.md)