@azure-id/orc 1.9.2 → 2.1.0

package/templates/skills/_shared/gotchas.md

@@ -1,177 +1,248 @@
-# Shared contract — Gotchas (repair memory that outlives the run)
-
-Canonical file: `_shared/gotchas.md`. THE one description of ORC's repair memory:
-what a gotcha is, where it lives, when one is recorded, when one is injected, and
-which lane may do which. Gate: config `gotchas` (`on` | `off`, default `on`).
-
-## 1. What a gotcha is
-
-**ONE project-specific failure that a repair in this project already solved.**
-Not a rule, not a preference, not a lesson in general.
-
-It is deliberately none of the other three knowledge artifacts:
-
-| Artifact | Answers | Not this |
-|---|---|---|
-| the wiki | "what IS this codebase" | a gotcha is not a fact about the code |
-| the pattern cache | "how does this project WRITE code" | a gotcha is not a convention |
-| `tdd_spec` | "what must this change PROVE" | a gotcha is not an acceptance test |
-| **gotchas** | **"what has this project already gotten WRONG here"** | — |
-
-If a finding fits one of the first three rows, it belongs there. A gotcha is the
-residue of a repair: something went red, a specific cause was found, a specific
-fix made it green.
-
-## 2. The artifact
-
-```
-.claude/orc/gotchas.md            # live entries, capped at gotchas_max
-.claude/orc/gotchas-archive.md    # evicted entries — never hard-dropped
-```
-
-Both sit BESIDE the pattern cache (`orc/patterns/`), never inside it. Like every
-file ORC generates under `.claude/orc/`, neither is in the install manifest — so
-`orc update --prune` can never delete them and `orc update` never overwrites them.
-They are user data by ORC's own rules.
-
-**Entry format** — the parser and every writer depend on this exactly:
-
-```markdown
-## G-014 · express · repair
-- trigger:   adding a route handler that awaits a Mongoose query
-- symptom:   Cannot read properties of undefined (reading 'session') in tests
-- cause:     the test harness stubs req.session only for authed routes
-- fix:       register the route under authedRouter, not app
-- scope:     src/routes/**/*.js
-- origin:    run-orc-add-billing-050826-141233 · TDD repair round 2
-- hits:      3
-- last_seen: 05-08-2026
-```
-
-- Heading: `## G-<3-digit id> · <lang-or-area> · <kind>`; `kind` ∈
-  `repair | drift | review | verify`.
-- Field order is FIXED. Every field is required. Values are single-line.
-- `scope` is a glob matched against a task's `declared_files`.
-- Dates are `DD-MM-YYYY` (the repo's convention).
-- IDs are monotonic; **never reused**, even after archival — an archived gotcha
-  stays traceable from a trace or a run doc that cited it.
-
-## 3. Existence probe (never a `find`)
-
-```
-orc gotcha status     exit 0 = one or more live entries · exit 1 = none
-orc gotcha list       the same contract, and prints the entries
-orc gotcha prune      archive the low-value tail down to gotchas_max
-```
-
-**The exit code IS the contract**, same convention as `orc pattern status <lang>`
-and `orc diy status`. `.claude/` is a hidden directory, so an ad-hoc `find`/glob
-false-negatives from the wrong CWD or when it skips dot-dirs — the same reason
-`detecting-artifacts.md` exists for the wiki and the pattern cache. Probe once,
-treat the result as the source of truth, and never second-guess a positive probe.
-
-## 4. When one is RECORDED
-
-At phase close, **when and only when a repair loop went red → green**:
-
-- the TDD repair loop turned a failing `tdd_spec` test green;
-- a `DRIFT-FROM` recovery round resolved the drift;
-- a reviewer P0/P1 that THIS SAME RUN fixed;
-- a verifier `unmet[]` entry that THIS SAME RUN closed.
-
-**A loop that hit its cap and STOPPED records NOTHING.** An unsolved failure is
-not a gotcha — it is an open problem, and the honest red report is where it
-belongs. Writing one anyway would seed the memory with advice that never worked.
-
-Nothing else records. A first-try success has no repair to remember; a green
-`regression-guard` test proved something, but it was never red.
-
-## 5. Who writes it
-
-Three parties, and they do not overlap:
-
-1. **The agent RETURNS the body** in `gotcha_recorded` (see
-   `return-validation.md` §7) — either the entry fields or `none` + a one-line
-   reason. The agent that did the repair is the only party that knows the cause.
-2. **The ORCHESTRATOR appends it** to `.claude/orc/gotchas.md`, at the same
-   phase-close point where it dispatches the trace packet. **A subagent never
-   writes either gotcha file.**
-3. **The CLI owns counting, capping and archival** (`orc gotcha prune`) —
-   deterministic bookkeeping, never a model's judgement.
-
-## 6. Dedupe (before every append)
-
-Compare the returned `symptom` + `scope` against the live entries. A match:
-increment `hits`, refresh `last_seen`, and **append nothing**. Only a genuinely
-new failure gets a new ID. Without this the file grows one duplicate per run and
-the injection cap fills with the same entry three times.
-
-## 7. When one is INJECTED
-
-Into an executor slice, **filtered by the `scope` glob against that task's
-`declared_files`**.
-
-- **NEVER inject unfiltered.** An unfiltered injection is the exact failure mode
-  that turns this feature into the bloat it exists to prevent.
-- Cap **3 entries per slice**, highest `hits` first.
-- **Zero matches = no gotcha block at all** — not an empty one. An empty block
-  costs tokens and says nothing.
-
-The block rides beside `pattern` in the slice, and like `pattern` it is injected
-LITERALLY, never as a file pointer.
-
-## 8. Who reads it
-
-- **Phase 1 preflight** — one line, never silent (see
-  `../orc/references/preflight-report.md`).
-- **executor slices** — filtered, capped, per §7.
-- **the reviewer** — the matching entries as a checklist: has this change
-  reintroduced a failure this project already paid for?
-- **`/orc-retro`** — read-only calibration input. It never writes one.
-
-## 9. Staleness is the user's job
-
-An injected gotcha is presented to an executor as **fact**. Nothing in ORC
-re-verifies that it is still true — `orc gotcha prune` handles CAPACITY, not
-correctness.
-
-So, plainly: **delete an entry that stopped being true.** Open
-`.claude/orc/gotchas.md` and remove the block. That is the whole procedure, and
-it is deliberately manual — a model deciding which of its own memories to forget
-is a worse failure mode than a stale line a human can read.
-
-## 10. Lane policy
-
-| Lane | Reads | Writes |
-|------|-------|--------|
-| `/orc`, `/orc-ultra` | yes | yes |
-| `/orc-mini` | yes | yes |
-| `/orc-fast` | yes | no |
-| `/orc-diy` | compile-owned (`gotchas` flow key) | compile-owned |
-| `/orc-quick` | **no** | **no** |
-| `/orc-retro` | yes | no (read-only by contract) |
-
-### Per-lane mechanics (the spines keep the trigger; this is the detail)
-
-**`/orc-mini` — reads AND writes, trimmed to one row.** Phase 1: probe
-`orc gotcha status` and print exactly one of `gotchas: <n> known · <m> match` /
-`none yet` / `off` — never silent. Phase 3: inject the scope-matching entries into
-the single executor slice beside the pattern (cap 3, highest `hits` first; zero
-matches = no block, NEVER unfiltered). After the return: dedupe a
-`gotcha_recorded` body on `symptom`+`scope` (a match bumps `hits`/`last_seen`) and
-append it to `.claude/orc/gotchas.md` yourself. A capped-and-stopped loop records
-nothing. Mini has no separate review/verify phase, so its only writer is the
-executor return.
-
-**`/orc-fast` — reads only, and gains no third prerequisite.** Its two hard gates
-(a FRESH/AGING wiki + a cached pattern) are its entire design; a missing gotchas
-file is never a reason to fall back, and gotchas here are purely additive: probe,
-inject the scope-matching entries into the F2 slice, and stop there. It never
-writes one, because one executor plus one repair round is too little signal to
-attribute a cause — and a lane with no analyst writing repair memory is how that
-memory fills with guesses.
-
-**`/orc-quick` does not participate at all — not even reading.** Its Q0 preflight
-reads `log_dir` and no other config key, by contract. A `gotchas` key read would
-break that guarantee, and the lane's whole premise is fewer steps, not more
-knowledge. This exclusion is intentional and is not an oversight to "fix".
+# Shared contract — Gotchas (repair memory that outlives the run)
+
+Canonical file: `_shared/gotchas.md`. THE one description of ORC's repair memory:
+what a gotcha is, where it lives, when one is recorded, when one is injected, and
+which lane may do which. Gate: config `gotchas` (`on` | `off`, default `on`).
+
+## 1. What a gotcha is
+
+**ONE project-specific failure that a repair in this project already solved.**
+Not a rule, not a preference, not a lesson in general.
+
+It is deliberately none of the other three knowledge artifacts:
+
+| Artifact | Answers | Not this |
+|---|---|---|
+| the wiki | "what IS this codebase" | a gotcha is not a fact about the code |
+| the pattern cache | "how does this project WRITE code" | a gotcha is not a convention |
+| `tdd_spec` | "what must this change PROVE" | a gotcha is not an acceptance test |
+| **gotchas** | **"what has this project already gotten WRONG here"** | — |
+
+If a finding fits one of the first three rows, it belongs there. A gotcha is the
+residue of a repair: something went red, a specific cause was found, a specific
+fix made it green.
+
+## 2. The artifact
+
+```
+.claude/orc/gotchas.md            # live entries, capped at gotchas_max
+.claude/orc/gotchas-archive.md    # evicted entries — never hard-dropped
+```
+
+Both sit BESIDE the pattern cache (`orc/patterns/`), never inside it. Like every
+file ORC generates under `.claude/orc/`, neither is in the install manifest — so
+`orc update --prune` can never delete them and `orc update` never overwrites them.
+They are user data by ORC's own rules.
+
+**Entry format** — the parser and every writer depend on this exactly:
+
+```markdown
+## G-014 · express · repair
+- trigger:   adding a route handler that awaits a Mongoose query
+- symptom:   Cannot read properties of undefined (reading 'session') in tests
+- cause:     the test harness stubs req.session only for authed routes
+- fix:       register the route under authedRouter, not app
+- scope:     src/routes/**/*.js
+- origin:    run-orc-add-billing-050826-141233 · TDD repair round 2
+- hits:      3
+- last_seen: 05-08-2026
+```
+
+- Heading: `## G-<3-digit id> · <lang-or-area> · <kind>`; `kind` ∈
+  `repair | drift | review | verify`.
+- Field order is FIXED. Every field is required. Values are single-line.
+- `scope` is a glob matched against a task's `declared_files`.
+- Dates are `DD-MM-YYYY` (the repo's convention).
+- IDs are monotonic; **never reused**, even after archival — an archived gotcha
+  stays traceable from a trace or a run doc that cited it.
+
+## 3. Existence probe (never a `find`)
+
+```
+orc gotcha status     exit 0 = one or more live entries · exit 1 = none
+orc gotcha list       the same contract, and prints the entries
+orc gotcha prune      archive the low-value tail down to gotchas_max
+```
+
+**The exit code IS the contract**, same convention as `orc pattern status <lang>`
+and `orc diy status`. `.claude/` is a hidden directory, so an ad-hoc `find`/glob
+false-negatives from the wrong CWD or when it skips dot-dirs — the same reason
+`detecting-artifacts.md` exists for the wiki and the pattern cache. Probe once,
+treat the result as the source of truth, and never second-guess a positive probe.
+
+## 4. When one is RECORDED
+
+At phase close, **when and only when a repair loop went red → green**:
+
+- the TDD repair loop turned a failing `tdd_spec` test green;
+- a `DRIFT-FROM` recovery round resolved the drift;
+- a reviewer P0/P1 that THIS SAME RUN fixed;
+- a verifier `unmet[]` entry that THIS SAME RUN closed.
+
+**A loop that hit its cap and STOPPED records NOTHING.** An unsolved failure is
+not a gotcha — it is an open problem, and the honest red report is where it
+belongs. Writing one anyway would seed the memory with advice that never worked.
+
+Nothing else records. A first-try success has no repair to remember; a green
+`regression-guard` test proved something, but it was never red.
+
+## 5. Who writes it
+
+Three parties, and they do not overlap:
+
+1. **The agent RETURNS the body** in `gotcha_recorded` (see
+   `return-validation.md` §7) — either the entry fields or `none` + a one-line
+   reason. The agent that did the repair is the only party that knows the cause.
+2. **The ORCHESTRATOR hands it to `orc gotcha add -`** (§10), at the same
+   phase-close point where it dispatches the trace packet. **A subagent never
+   writes either gotcha file.**
+3. **The CLI owns counting, capping and archival** (`orc gotcha prune`) —
+   deterministic bookkeeping, never a model's judgement.
+
+## 6. Dedupe (before every append)
+
+`orc gotcha add` does this; the rule is written here so a person can check it.
+Compare the returned `symptom` + `scope` against the live entries. A match:
+increment `hits`, refresh `last_seen`, and **append nothing**. Only a genuinely
+new failure gets a new ID. Without this the file grows one duplicate per run and
+the injection cap fills with the same entry three times.
+
+## 7. When one is INJECTED
+
+Into an executor slice, **filtered by the `scope` glob against that task's
+`declared_files`**.
+
+- **NEVER inject unfiltered.** An unfiltered injection is the exact failure mode
+  that turns this feature into the bloat it exists to prevent.
+- Cap **3 entries per slice**, highest `hits` first.
+- **Zero matches = no gotcha block at all** — not an empty one. An empty block
+  costs tokens and says nothing.
+
+The block rides beside `pattern` in the slice, and like `pattern` it is injected
+LITERALLY, never as a file pointer.
+
+## 8. Who reads it
+
+- **Phase 1 preflight** — one line, never silent (see
+  `../orc/references/preflight-report.md`).
+- **executor slices** — filtered, capped, per §7.
+- **the reviewer** — the matching entries as a checklist: has this change
+  reintroduced a failure this project already paid for?
+- **`/orc-retro`** — read-only calibration input. It never writes one.
+
+## 9. Staleness is the user's job
+
+An injected gotcha is presented to an executor as **fact**. Nothing in ORC
+re-verifies that it is still true — `orc gotcha prune` handles CAPACITY, not
+correctness.
+
+So, plainly: **delete an entry that stopped being true.** Open
+`.claude/orc/gotchas.md` and remove the block. That is the whole procedure, and
+it is deliberately manual — a model deciding which of its own memories to forget
+is a worse failure mode than a stale line a human can read.
+
+## 10. Lane policy (v2.0.0 — who reads, who records, and where)
+
+| Lane | Reads | Records (an observation; promotion is computed) |
+|------|-------|-------|
+| `/orc`, `/orc-ultra` | match (executors) · card (Phase 5 reviewer, Phase 6 verifier, ultra gate 3) · filter (after Phase 5) | repairs (via `add`) · every Phase 5 finding's outcome · defect repros |
+| `/orc-mini` | match · card (when the risk option dispatches the reviewer) · filter | repairs · a smoke-gate repair round that went green · reviewer outcomes |
+| `/orc-fast` | match | nothing |
+| `/orc-quick` | card for the review offer · match for code dispatches | a defect repro red → green · a PR thread taken and fixed · a Sonar/SARIF item fixed · a CI failure fixed · a review-offer P0/P1 fixed · a finding the user disputed |
+| `/orc-verify` | card (its adversarial pass) | nothing — read-only lane stays read-only |
+| `/orc-pr-driver` | card at the per-layer gate | a green-gate lint/seam fix |
+| `/orc-diy` | compile-owned (`gotchas` flow key) | compile-owned |
+| `/orc-retro` | yes | no (read-only by contract) |
+
+The `gotchas` key (`on` | `off`) now gates ONLY the executor block
+(`orc gotcha match` exits 4 under `off`). The reviewer card has no off answer
+(review learning is always on); `gotcha_card_budget` is only its size.
+
+### How a lane records — ONE CLI call, where it already writes
+
+- **An observation:** `orc gotcha observe - --json`, stdin ONE JSON object:
+  `source` (`repair` · `drift` · `review` · `verify` · `defect` · `ci` · `pr` ·
+  `sonar` · `sarif` · `dismissal`), `ref` (unique per event, e.g.
+  `<run> · F3` — the same `ref` REPLACES the earlier line), `outcome`
+  (`addressed` · `disputed` · `wontfix` · `open` · `flaky`), `author` (`orc` ·
+  `human` · `bot`), `rule` or `sig` (the finding text), and when known
+  `category`, `severity`, `path`, `lines`, `run`, `gotcha` (the `G-###` the
+  finding cited). Exit 0 = appended and promotion ran · 2 = malformed: say it
+  once and go on. **It never blocks a run.** The CLI alone writes
+  `.claude/orc/observations.jsonl`; a lane never edits it.
+- **A red → green repair:** the `gotcha_recorded` body goes to
+  `orc gotcha add -` (exit 0 added · 3 bumped an existing entry · 2 malformed).
+  The CLI dedupes, assigns the id and writes the entry. Nobody appends by hand.
+- **The outcome is PROGRAMMATIC**, never a model's opinion: the flagged lines
+  changed before ship = `addressed`; the user said "not a problem here" =
+  `disputed`; declined with no reason = `wontfix`; none of these yet = `open`.
+
+### Review close — the same step in every lane that ran a review
+
+After `review-slice.md` §3 and the fixes: ONE observation per finding
+(`source: review`, `author: orc`, the outcome above, `gotcha` when the finding
+cited one), then ONE trace line:
+`FINDING-OUTCOME addressed=<n> disputed=<n> wontfix=<n> open=<n> pre=<n> suppressed=<n> :: <cat>:<addressed>/<total>,…`.
+Where: `/orc` and `/orc-ultra` at Phase 7 (`phases/summary.md`), `/orc-mini`
+after the risk option's review, `/orc-quick` after the review offer. A review
+with zero findings records no observation and is a HEALTHY answer: its
+`FINDING-OUTCOME` line (or the hook `RETURN orc-reviewer-*` line) already counts
+it as a review in `orc gotcha quality` (v2.1.0). An `author: orc` observation
+without `run` is refused (exit 2) — a `ref` that starts with the run id fills it.
+
+**The reviewed ranges (v2.1.0, DE-13).** In the same step, store what the review
+READ: `orc gotcha observe -` with
+`{"kind": "review-scope", "run": "<trace name>", "commit": "<HEAD>", "files": {"<path>": [[start, end], …]}}`
+— the slice's `diff_ranges`, a clean review too. The CLI keeps the last 500
+reviews in `.claude/orc/review-scope.jsonl` (user data, never pruned by age) and
+counts what it drops. A later `orc fix record` on lines inside a stored range
+of an EARLIER run is a computed `miss`: the fix is promoted at 1 case and goes
+first in the next card.
+
+### Per-lane mechanics (the spines keep the trigger; this is the detail)
+
+**`/orc-mini` — reads AND writes, trimmed to one row.** Phase 1: probe
+`orc gotcha status` and print exactly one of `gotchas: <n> known · <m> match` /
+`none yet` / `off` — never silent. Phase 3: inject the scope-matching entries into
+the single executor slice beside the pattern (cap 3, highest `hits` first; zero
+matches = no block, NEVER unfiltered). After the return: pipe a
+`gotcha_recorded` body to `orc gotcha add -` (a match on `symptom`+`scope`
+bumps `hits`/`last_seen`). A capped-and-stopped loop records nothing. A
+smoke-gate repair round that went green records `source: repair`. When the
+risk option ran the reviewer, record its outcomes as "Review close" says.
+
+**`/orc-fast` — reads only, and gains no third prerequisite.** Its two hard gates
+(a FRESH/AGING wiki + a cached pattern) are its entire design; a missing gotchas
+file is never a reason to fall back, and gotchas here are purely additive: probe,
+inject the scope-matching entries into the F2 slice, and stop there. It never
+writes one, because one executor plus one repair round is too little signal to
+attribute a cause — and a lane with no analyst writing repair memory is how that
+memory fills with guesses. **A review is different (v2.1.0):** when `/orc-fast` runs
+a review (the F4 offer, or the user asks for one), it records that review's outcomes
+as "Review close" says — an observation is REVIEW LEARNING, not a repair-memory
+entry, and every lane that ran a review records it.
+
+**`/orc-quick` — reads and records, since 2.0.0 (a deliberate reversal).**
+Record after the step 3.5 offers (v2.1.0 — it was 3.3, before the review offer
+existed to record), and only for a request with programmatic proof: a defect entry with `REPRO red` then `REPRO green`
+(`source: defect`, `reproduced: true`) · a PR thread the request took and fixed
+(`source: pr`) · a Sonar or SARIF item fixed (`source: sonar` / `sarif`) · a CI
+failure fixed (`source: ci`) · every finding of a review offer, ONE observation per finding
+with its outcome, as "Review close" says (`source: review`; "not a problem here"
+= `disputed`). A plain fix with none of these records nothing.
+A FIX of a named finding (a Sonar issue, a failed check, a defect ORC or an AI
+tool caused) goes through `orc fix record -` (`via: "orc-quick"`, v2.1.0): the
+author is the finder, never `orc`; a Sonar issue key gives the importer's own id,
+so a later gotcha sync completes the same row; and the CLI computes `miss`
+from `review-scope.jsonl`.
+Why the reversal: quick is where most of the fixes happen, so a memory that
+skips it never learns; a PR thread is a human's judgement and a red → green
+repro is proof, so the v1 "too little signal" objection does not apply; and the
+card and `observe` are CLI calls — the CLI reads the `gotchas` key, so Q0 still
+reads `log_dir` and no other config key itself.
+
+**`/orc-pr-driver` — the card is advice only.** A rung that went red and then
+green after a lint or seam fix records `source: repair` (`ref`: the layer and
+the rung). The gate itself stays build · tests · lint · hooks.
+
+**`/orc-verify` and `/orc-retro` never record.** Both are read-only by contract.

package/templates/skills/_shared/habits.md

@@ -0,0 +1,101 @@
+# Shared contract — habits (the lane side, read ON DEMAND)
+
+Canonical file: `_shared/habits.md`. **Read it ONLY when the
+`orc lane config <lane> --json` answer has a `habits{}` block.** No block means
+`habits: off` (the default). Then the lane emits NO `ASK` line, shows NO
+suggestion, prints NO habits line and makes NO proposal, and every `(H <qid>)`
+mark in a spine or phase file means nothing. Off costs zero tokens.
+
+The CLI owns the rule (`orc habit`, `bin/habit.js`). The lane reads `habits{}`,
+shows what it says, and records each answer. **Nothing is applied without a
+yes.** `orc habit points --json` lists every qid and its option ids.
+
+## 1. Preflight — one line
+
+Print `habits.line` VERBATIM with the other preflight lines. A learned key
+(`habits.learned[]`) is already resolved into `effective` at the `learned`
+rank, and its line is already in `announce[]` — print it like every other
+announce line. Do not re-derive it.
+
+## 2. At each question marked `(H <qid>)`
+
+**Never ask what is already answered.** The request said it (the intent
+ledger), a config key set it, or a learned key answers it → do not ask. Use
+that answer, say it in one line, and record `by=ledger|config|learned`.
+`orc stats --json` → `questions{}` counts the questions asked per run, per lane
+and per point, so each extra question shows.
+
+1. **Suggestion.** A `habits.suggestions[]` row with this `qid` (and a `bucket`
+   that matches this question's ctx) → put its `option` FIRST and add its `mark`
+   (`→ usual (<count> of <total>)`) beside it. It is a recommendation, never a
+   pre-selection. **The question is still asked.** Under `observe` the CLI
+   sends no suggestion.
+2. **Learned key.** A `learned[]` row answers the key of this qid → do not ask;
+   use its value and say so in one line. The user can still override it.
+3. **Record.** Put ONE `ASK` event in the phase packet (grammar:
+   `trace_grammar` → `ASK`, `./phases/trace-verbs.md`):
+   `ASK <qid> :: offered=<o1|o2|…> rec=<o|none> chose=<o|other> by=<…> [pre=<o>] [ctx=<k=v,…>]`
+   - `offered`, `rec`, `chose`, `pre` are option ids from `orc habit points`.
+     An answer in the user's own words is `chose=other`. **Never store the
+     words.**
+   - `by`: `user` answered it · `ledger` the request said it up front ·
+     `learned` a learned key or a `→ usual` pre-mark answered and the user
+     kept it · `config` a config key answered and the question was not shown ·
+     `default` the lane default answered and the question was not shown.
+   - `pre=<o>` only when an option was pre-marked or pre-selected.
+   - `ctx` only with what the lane knows: `branch=main|feature|fix|release|other`,
+     `kind=feature|defect|pr|read|refactor`, `size=s|m|l`, `risk=none|cited`.
+     Never guess a missing key.
+
+## 3. Run end — at most ONE proposal
+
+`habits.proposal` is set → add its `line` to the EXISTING end-of-run batch. One
+line, no new turn. Run the command the answer names — it is part of the
+`lane config` answer, so it is an allowed call:
+yes → `proposal.yes` · keep asking (a re-ask) → `proposal.keep` ·
+later / not now → `proposal.later` · never → `proposal.never`.
+A `null` command is an answer that is not offered. Put `proposal.trace` in the
+last packet with `chose=` filled in. No proposal → say nothing.
+The end-of-run batch per lane: `/orc` and `/orc-ultra` the Phase 8 completion
+report · `/orc-mini` the end-of-run batch · `/orc-fast` the F4 ship offer ·
+`/orc-quick` the Q3 offers · `/orc-analyze` the Phase F choice · `/orc-diy` the
+compiled flow's last phase. `/orc-wait` makes no proposal.
+
+## 4. Lane notes
+
+- **`/orc-quick`.** The dispatch gate is asked EVERY time. A habit only fills
+  its `→ suggested` line (Q2b), with the CLI's numbers as the reason.
+  `review_before_push` and `quick_update_tests` touch the OFFERS after the work,
+  never the gate. A `quick.q3.offer.review` suggestion of `review-first` makes
+  offers 2 and 3 ONE offer: *review → then commit (your usual, 9 of 10) ·
+  commit without review · stop*. The review is a dispatch, so its gate is still
+  asked. ctx: `kind`, `branch`.
+- **`/orc-mini`.** A learned `mini_tdd: on` → intake does not ask the TDD
+  question; its `announce[]` line names the habit and its undo. A habit
+  toward `no` is a pre-mark only, never applied. A learned
+  `review_before_push: on` → the end-of-run batch ALWAYS carries option *a*
+  (dispatch `orc-reviewer-opus-5-low` on the diff), marked `→ usual`, even with
+  no `risk: high` row. Record `any.ship.review-before-push` whenever option *a*
+  is offered: `chose=review` when the user takes it, else `push`.
+- **`/orc-fast`.** `fast.f0.stale-wiki`: a habit NEVER suggests `continue`
+  (a stale wiki is a risk the user takes each time). The CLI never proposes
+  it (`never_option`); a suggestion row that names it anyway is ignored. Show
+  a `refresh` or `mini` suggestion only, and never apply one. A learned `review_before_push: on` → F4
+  offers a dispatch of `orc-reviewer-opus-5-low` on the diff FIRST (P0/P1 block
+  the commit), marked `→ usual`; the reviewer is not in the fast pipeline, so
+  it runs only on that yes. Record `any.ship.review-before-push` whenever it is
+  offered.
+- **`/orc` and `/orc-ultra`.** The points live in the phase files. Ultra forces
+  its overrides for the run: a habit never answers a forced key or question
+  (analysis depth, pattern findings, test authoring, security review) — record
+  those `ASK`s `by=config`, and the habits line says ultra wins.
+- **`any.analysis.depth`** (`/orc`, `/orc-analyze`): a suggestion only. `deep`
+  needs the user's explicit yes EVERY run — a habit never picks it and never
+  skips the question. ctx: none.
+- **`/orc-diy`.** The compiled flow asks the same questions as the phases it
+  came from and emits the same `ASK`. A question the flow's `autonomy`
+  (`semi` · `hands-off`) answered is `by=default` and never counts toward a
+  habit — it was not a choice.
+- **`/orc-wait`.** `any.stop.where` only, at W6. The wait opens no run: the
+  `ASK` goes in the NEXT packet of the run in flight, and only when that run's
+  `lane config` answer had `habits{}`.

package/templates/skills/_shared/lane-contract.md

@@ -0,0 +1,84 @@
+# Shared contract — the lane contract (Calls · Config · Rules · Trace · Phases · Wait)
+
+Canonical file: `_shared/lane-contract.md`. It holds, ONCE, the text that every
+coding-lane spine used to repeat in six blocks. **Read it ONLY when a CLI call
+exits ≠ 0.** Otherwise the spine's pointer lines are enough: each pointer names
+the lane's OWN values (its `orc lane calls` / `orc lane config` spelling, its
+trace token and tier, its checkpoint and safe point). This file never restates
+those values, and a spine never restates this file.
+
+## Calls
+
+**ONE catalogue, and it is not you:** `orc lane calls <lane> --json` names every
+CLI call the lane makes. Each row gives the exit-code contract, the cost, when
+to run the call, and what an EMPTY answer means.
+
+- Never invent a spelling. Never re-word an exit code.
+- Never re-derive a state word. The CLI's state words are the only state words.
+- **An exit code is an ANSWER wherever that contract says so, not a failure.**
+- A call that the answer does not name is a call the lane does not make.
+- The catalogue itself exits ≠ 0 → say that the CLI is unavailable. Before you
+  run a command, name it out loud.
+
+## Config
+
+**ONE resolver, and it is not you:** `orc lane config <lane> --json`. A spine
+carries ONE of two forms. `bin/verify-contracts.js` decides which one.
+
+- **Full form** — the lane reads a contested, gated or inert key. Obey
+  `effective`. Print every line in `announce[]` VERBATIM at preflight. Honour
+  `stops[]` before wave 1 (or before the lane's first unit of work, which the
+  spine names).
+- **Short form** — the lane reads nothing contested, gated or a stop. Obey
+  `effective`. The lane owes no preflight line and has no gate to honour.
+
+Both forms:
+
+- Never merge `.claude/orc.config.yaml` yourself.
+- Never re-derive a value, a precedence or an inertness from that file. A key
+  that the lane does not read is not in the answer. A key that another key
+  shadows comes back already marked.
+- Exit ≠ 0 → say that the CLI is unavailable. Fall back to the documented
+  defaults of `config-precedence.md`, out loud.
+- Priorities and families: `config-precedence.md`.
+
+## Rules — the anti-slop card
+
+`orc rules slice --lane <lane> --json` is the ONLY assembler. Never build the
+card in the spine. Canonical: `phases/rules.md`.
+
+- The card rides under the house rules and above the task:
+  **house rules > your project's rules > ORC's own packs**.
+- Its `line` prints VERBATIM at preflight.
+- Returns gain `rules_applied[]`, `rules_conflicts[]` (a gap, never a silent
+  choice) and `rules_overridden[]`.
+
+## Trace
+
+Canonical: `phases/trace.md` (layer `core`, loaded at run start).
+`orc lane phases <lane> --json` names the file and the layers, and its
+`trace_grammar` gives the verbs. The tier table in `trace.md` defines the
+packet count for each tier. The spine names only its token, its tier, its own
+unit, and its run-start step. Nothing else about the protocol is restated in a
+spine.
+
+## Phases
+
+`orc lane phases <lane> --json` is the 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 spine's headings.
+- Never renumber or rename a phase heading without the manifest. A
+  `read: section` pointer names a HEADING, so a renamed heading is a pointer
+  into nothing.
+
+## Wait
+
+Canonical: `wait.md`. The spine names its checkpoint and its safe point, the
+same values as `orc wait lanes`. The modes, the safe points and the
+never-begin-a-wait list are in `wait.md` only.
+
+- Checkpoint `none` → nothing to checkpoint, so the three modes behave the
+  same. Say so. Do not ask.
+- Any other checkpoint → `soft` FORCES the checkpoint and does NOT stop if the
+  write fails. `hard` skips it and can lose an in-flight return.