@azure-id/orc 1.9.1 → 2.0.2

package/mock-run/INDEX.md

@@ -1,107 +1,109 @@
-# 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 |
+
+## 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/context-combiner.md

@@ -1,100 +1,100 @@
-# Mock run — the context combiner
-
-> Two analyses of two related documents, merged into one spec — and it proves
-> that nothing was lost.
-
-There is no slash command for this. It is offered by `/orc-analyze` when two or
-more related analyses already exist.
-
----
-
-## 1. What it does
-
-You analysed the refund policy PDF last week. Today you analysed the support
-escalation doc. Both talk about refunds. Building from either one alone means
-building half the thing.
-
-The combiner pools **every** requirement from **every** source and gives each
-one exactly one outcome. Then it counts. If the count is not 100%, it does not
-hand off.
-
----
-
-## 2. The run
-
-```
-/orc-analyze  …  Phase F:
-
-  Two related analyses found. Merge them into one spec?
-  · refund-policy       11 requirements   2026-08-04
-  · support-escalation   7 requirements   2026-08-12
-
-> yes
-```
-
-```
-Dispatching orc-context-combiner-opus-5-high …
-returned as: claude-opus-5 / high        ✓
-
-Phase B — are these really related?
-  shared files       api/refunds/ (both), web/refunds/ (both)
-  shared subject     refund state and who is told about it
-  Verdict: related. Continuing.
-
-Phase C — pooled 18 requirements, reconciled one at a time
-
-  exact duplicate    R-04 = S-02  "refund state must be visible to support"
-                     → ONE row, both sources cited
-  partial overlap    R-07 "notify the customer" vs S-05 "notify support"
-                     → SPLIT into two rows, never collapsed into "notify"
-  conflict           R-09 says refunds are final; S-06 describes a re-open
-                     → CONFLICT, raised to you (below)
-  ordering           S-01 must happen before R-02 (it creates the state)
-
-Phase D — one question at a time
-
-  ❓ R-09 vs S-06 — can a closed refund be re-opened?
-     R-09 (policy PDF, p.4): "a completed refund is final"
-     S-06 (escalation doc, §2): "support may re-open within 14 days"
-     ➡️  The escalation doc is newer. I recommend S-06 wins, with R-09 kept
-        as a note. Your call.
-
-  > S-06 wins, and add the 14 days as a hard rule
-
-Phase E — conservation gate
-  source requirements   18
-  rows in the merged spec 19   (one split into two)
-  every source id has exactly one outcome:
-     kept 15 · merged 2 · split 1→2 · resolved-by-you 1 · dropped 0
-  coverage_pct: 100        → handoff allowed
-
-Phase F — written
-  combined-report.md
-  combined-requirement-spec.md          (a normal spec, plus the source map)
-
-Evidence freshness: 2 anchors from last week no longer match HEAD.
-  api/refunds/create.ts:31 → now :44     (flagged, not silently fixed)
-```
-
----
-
-## 3. What to notice
-
-- **Nothing may vanish quietly.** Below 100% coverage there is no handoff.
-  Dropping a requirement is allowed — but only as your explicit decision, and
-  it is recorded as one.
-- **A partial overlap is split, never collapsed.** Collapsing two similar
-  requirements into one shorter sentence is how scope disappears.
-- **Old evidence is re-checked against HEAD**, because an anchor that was true
-  last week is not a fact today.
-- **The merged spec is a normal spec.** The planner and the build pipeline do
-  not know or care that it came from two documents.
-- **Full lane only.** There is no mini version of this, and it never builds
-  anything or spawns anything itself.
-
----
-
-## 4. Related
-
-- Where it starts: [`/orc-analyze`](../templates/skills/orc-analyze/examples/analyze-mock.md)
-- What happens next: [`/orc-plan`](orc-plan.md)
+# Mock run — the context combiner
+
+> Two analyses of two related documents, merged into one spec — and it proves
+> that nothing was lost.
+
+There is no slash command for this. It is offered by `/orc-analyze` when two or
+more related analyses already exist.
+
+---
+
+## 1. What it does
+
+You analysed the refund policy PDF last week. Today you analysed the support
+escalation doc. Both talk about refunds. Building from either one alone means
+building half the thing.
+
+The combiner pools **every** requirement from **every** source and gives each
+one exactly one outcome. Then it counts. If the count is not 100%, it does not
+hand off.
+
+---
+
+## 2. The run
+
+```
+/orc-analyze  …  Phase F:
+
+  Two related analyses found. Merge them into one spec?
+  · refund-policy       11 requirements   2026-08-04
+  · support-escalation   7 requirements   2026-08-12
+
+> yes
+```
+
+```
+Dispatching orc-context-combiner-opus-5-high …
+returned as: claude-opus-5-5 / high        ✓
+
+Phase B — are these really related?
+  shared files       api/refunds/ (both), web/refunds/ (both)
+  shared subject     refund state and who is told about it
+  Verdict: related. Continuing.
+
+Phase C — pooled 18 requirements, reconciled one at a time
+
+  exact duplicate    R-04 = S-02  "refund state must be visible to support"
+                     → ONE row, both sources cited
+  partial overlap    R-07 "notify the customer" vs S-05 "notify support"
+                     → SPLIT into two rows, never collapsed into "notify"
+  conflict           R-09 says refunds are final; S-06 describes a re-open
+                     → CONFLICT, raised to you (below)
+  ordering           S-01 must happen before R-02 (it creates the state)
+
+Phase D — one question at a time
+
+  ❓ R-09 vs S-06 — can a closed refund be re-opened?
+     R-09 (policy PDF, p.4): "a completed refund is final"
+     S-06 (escalation doc, §2): "support may re-open within 14 days"
+     ➡️  The escalation doc is newer. I recommend S-06 wins, with R-09 kept
+        as a note. Your call.
+
+  > S-06 wins, and add the 14 days as a hard rule
+
+Phase E — conservation gate
+  source requirements   18
+  rows in the merged spec 19   (one split into two)
+  every source id has exactly one outcome:
+     kept 15 · merged 2 · split 1→2 · resolved-by-you 1 · dropped 0
+  coverage_pct: 100        → handoff allowed
+
+Phase F — written
+  combined-report.md
+  combined-requirement-spec.md          (a normal spec, plus the source map)
+
+Evidence freshness: 2 anchors from last week no longer match HEAD.
+  api/refunds/create.ts:31 → now :44     (flagged, not silently fixed)
+```
+
+---
+
+## 3. What to notice
+
+- **Nothing may vanish quietly.** Below 100% coverage there is no handoff.
+  Dropping a requirement is allowed — but only as your explicit decision, and
+  it is recorded as one.
+- **A partial overlap is split, never collapsed.** Collapsing two similar
+  requirements into one shorter sentence is how scope disappears.
+- **Old evidence is re-checked against HEAD**, because an anchor that was true
+  last week is not a fact today.
+- **The merged spec is a normal spec.** The planner and the build pipeline do
+  not know or care that it came from two documents.
+- **Full lane only.** There is no mini version of this, and it never builds
+  anything or spawns anything itself.
+
+---
+
+## 4. Related
+
+- Where it starts: [`/orc-analyze`](../templates/skills/orc-analyze/examples/analyze-mock.md)
+- What happens next: [`/orc-plan`](orc-plan.md)

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)