@azure-id/orc 1.8.1 → 1.9.0

package/templates/skills/_shared/phases/rules.md

@@ -1,159 +1,172 @@
-# Phase — Rules   (id: `rules`)
-
-> **Library file.** New at v1.7.0 W5. Layers declared: `core` only — single-layer
-> for the same reason `house-rules.md` is: it is a standing card injected
-> VERBATIM into a slice, and a layered card would be a different card. What
-> varies between lanes is DATA (which packs, whether a task is front-end), not
-> prose. `orc lane phases <lane> --json` names the file and the layers to read.
->
-> **What is NOT here:** the rules. They are `../rules/` — four packs, read-only,
-> shipped. This file is the SHAPE: who assembles the card, where it sits in a
-> slice, what comes back, and what the phase must never do.
->
-> **`/orc-doc` does not run this phase.** That lane has its own ledger
-> (`orc doc rules`) and its own frozen-per-document mechanic. Excluded means
-> excluded, and `orc rules slice --lane orc-doc` refuses by name.
-
-<!-- orc:layer core -->
-
-## One assembler, and it is not you
-
-```
-orc rules slice --lane <lane> [--pack ui] [--json]
-```
-
-That command is the **only** thing that builds this card. A lane never
-concatenates the packs itself, never re-orders them, never summarises a rule and
-never drops one it judges irrelevant.
-
-Two reasons, and both have cost this repo money elsewhere:
-
-1. **Drift.** A card assembled in twenty-eight spines is twenty-eight ideas of
-   the precedence order. The same argument as `orc lane phases`: *a second idea
-   of the pipeline is the drift this exists to make impossible.*
-2. **Cost.** This card rides on **every spawn**. One assembler is the only place
-   its token weight can be measured, and therefore the only place it can be cut.
-
-Print the command's `line` VERBATIM at preflight. Never compute it:
-
-```
-rules:    ORC 65 (W 23 · C 22 · D 10 · U 10) · yours 9 lines (P0 4 · P1 2 · P2 3) · 1 override
-rules:    ORC 65 (W 23 · C 22 · D 10 · U 10) · yours none
-```
-
-**Both spellings are mandatory in their state.** `yours none` is an ANSWER — it
-says the project has not written its own rules, which is a different fact from
-the CLI failing to look.
-
-## Where it sits in a slice — the order IS the contract
-
-```
-1  HOUSE RULES              ./house-rules.md, injected verbatim
-2  YOUR PROJECT'S RULES     from the slice, P0 then P1 then P2, verbatim
-3  ORC RULES                from the slice, the packs this lane carries
-4  the task                 the lane's own dispatch contract
-```
-
-Nothing goes above 1. Nothing goes between 2 and 3. The assembler emits 2 and 3
-as one block in that order, so the lane's job is to place that block directly
-under the house card and before the task.
-
-**The slice field is `rules_card`, and it is the `text` field — not the `line`.**
-Run the command at DISPATCH, not only at preflight. The `line` tells the user
-which rules are in force; the `text` is what the agent reads. A lane that prints
-the line and injects only the house card has reported rules that no agent got.
-
-## Precedence, and the one sentence that gets it wrong
-
-```
-house rules  >  your rules  >  ORC rules
-```
-
-**The house card is CODE and BEHAVIOUR only.** It governs how a change is made:
-surgical, simple, honest, in-slice. It says nothing about the words an agent
-writes, so it never overrules a writing rule — *it does not speak about prose at
-all.* A lane that presents the house card as beating `OSW-*` has misread it.
-
-**A project rule beats an ORC rule outright.** Not a waiver and not a
-negotiation: the ORC rule is removed from the slice, and the removal is stated
-inside it. The assembler does that. The lane does not decide it.
-
-Where a lane's preflight prints a report rather than a bare line, the report
-**names** each override. An override the user cannot see is an override they
-cannot audit.
-
-## The `ui` pack rides per TASK, never per lane
-
-`ui` is in no lane's default set. Add it to a single slice, at dispatch time:
-
-> If a task's **declared files** are front-end — `.css`, `.scss`, `.html`,
-> `.jsx`, `.tsx`, `.vue`, `.svelte`, or a directory the wiki or the cached
-> pattern identifies as the UI layer — assemble that task's card with
-> `--pack ui`. Otherwise do not.
-
-A UI rule in a backend slice is tokens paid on every spawn for a rule that
-cannot apply. A lane that dispatches no tasks never passes `--pack ui` at all.
-
-## What comes back
-
-Every return from a slice that carried this card gains three fields
-(`../return-validation.md`):
-
-| Field | What it holds |
-|---|---|
-| `rules_applied[]` | the ids the agent acted on |
-| `rules_conflicts[]` | two rules that disagree. **A gap, never a silent choice** |
-| `rules_overridden[]` | an ORC id a project rule replaced |
-
-A `rules_conflicts[]` entry is relayed to the user as a gap through the lane's
-own gap channel. Resolving it quietly is the failure the field exists to prevent.
-
-## The boundary — declared, never validated
-
-Rules govern **what is written and how it reads**, and **what shape of code is
-acceptable**. They can never change how a lane **runs**: the scoring, the wave
-order, the gates, the dispatch contract, the ship rules, or any lane's
-structural and safety rules.
-
-A rule that asks for one of those comes back as `unsupported_request` and is
-relayed as a gap. **Never a guessed compromise.**
-
-**Do not build a detector for this.** The CLI declares the boundary and does not
-pretend to enforce it, for the reason `orc doc rules` already settled: a
-validator that sometimes works is worse than none, because a clean pass then
-means nothing. The agent is the only reader that can tell a content rule from a
-structural one, so the agent is where the answer comes from.
-
-## The free lint
-
-```
-orc rules lint <path…|--staged|--diff> [--pack w,c,d,u] [--json]
-```
-
-Deterministic, zero tokens. Exit `0` clean · `1` findings · `2` nothing to lint.
-
-It checks only the rules a string match can prove, and it prints — in every
-mode — how many it did not check. **Relay that coverage line whenever you relay
-a lint result.** A clean exit allowed to stand in for a review nobody did is the
-whole failure that line prevents.
-
-Findings are ADVISORY. This phase adds no gate: a style preference that fails a
-build gets switched off within a week, and then nothing is enforced at all.
-
-An exemption is never silent either. The lint skips the rules packs themselves
-(a rule that bans a word has to print that word to define it) and any file
-marked `orc-rules-ignore-file`, and it reports the count of both.
-
-## Cost, and where to cut it
-
-Measured at v1.7.0: roughly **3 600 tokens** per build-lane slice, **4 300** with
-the UI pack, **2 200** for a prose-only lane. The card already carries HARD rules
-in full and PURPOSE/LOCK rules as one line plus the file to open when one
-applies.
-
-If it must come down, the lever is the worked examples inside the HARD bodies,
-and the only place to pull it is `rulesSlice()` in `bin/cli.js`. **Never by a
-lane deciding to trim its own card** — that is the drift this phase exists to
-prevent, arriving disguised as a saving.
-
-<!-- /orc:layer -->
+# Phase — Rules   (id: `rules`)
+
+> **Library file.** New at v1.7.0 W5. Layers declared: `core` only — single-layer
+> for the same reason `house-rules.md` is: it is a standing card injected
+> VERBATIM into a slice, and a layered card would be a different card. What
+> varies between lanes is DATA (which packs, whether a task is front-end), not
+> prose. `orc lane phases <lane> --json` names the file and the layers to read.
+>
+> **What is NOT here:** the rules. They are `../rules/` — four packs, read-only,
+> shipped. This file is the SHAPE: who assembles the card, where it sits in a
+> slice, what comes back, and what the phase must never do.
+>
+> **`/orc-doc` does not run this phase.** That lane has its own ledger
+> (`orc doc rules`) and its own frozen-per-document mechanic. Excluded means
+> excluded, and `orc rules slice --lane orc-doc` refuses by name.
+
+<!-- orc:layer core -->
+
+## One assembler, and it is not you
+
+```
+orc rules slice --lane <lane> [--pack ui] [--json]
+```
+
+That command is the **only** thing that builds this card. A lane never
+concatenates the packs itself, never re-orders them, never summarises a rule and
+never drops one it judges irrelevant.
+
+Two reasons, and both have cost this repo money elsewhere:
+
+1. **Drift.** A card assembled in twenty-eight spines is twenty-eight ideas of
+   the precedence order. The same argument as `orc lane phases`: *a second idea
+   of the pipeline is the drift this exists to make impossible.*
+2. **Cost.** This card rides on **every spawn**. One assembler is the only place
+   its token weight can be measured, and therefore the only place it can be cut.
+
+Print the command's `line` VERBATIM at preflight. Never compute it:
+
+```
+rules:    ORC 65 (W 23 · C 22 · D 10 · U 10) · yours 9 lines (P0 4 · P1 2 · P2 3) · 1 override
+rules:    ORC 65 (W 23 · C 22 · D 10 · U 10) · yours none
+```
+
+**Both spellings are mandatory in their state.** `yours none` is an ANSWER — it
+says the project has not written its own rules, which is a different fact from
+the CLI failing to look.
+
+## Where it sits in a slice — the order IS the contract
+
+```
+1  HOUSE RULES              ./house-rules.md, injected verbatim
+2  YOUR PROJECT'S RULES     from the slice, P0 then P1 then P2, verbatim
+3  ORC RULES                from the slice, the packs this lane carries
+4  the task                 the lane's own dispatch contract
+```
+
+Nothing goes above 1. Nothing goes between 2 and 3. The assembler emits 2 and 3
+as one block in that order, so the lane's job is to place that block directly
+under the house card and before the task.
+
+**The slice field is `rules_card`, and it is the `text` field — not the `line`.**
+Run the command at DISPATCH, not only at preflight. The `line` tells the user
+which rules are in force; the `text` is what the agent reads. A lane that prints
+the line and injects only the house card has reported rules that no agent got.
+
+## Precedence, and the one sentence that gets it wrong
+
+```
+house rules  >  your rules  >  ORC rules
+```
+
+**The house card is CODE and BEHAVIOUR only.** It governs how a change is made:
+surgical, simple, honest, in-slice. It says nothing about the words an agent
+writes, so it never overrules a writing rule — *it does not speak about prose at
+all.* A lane that presents the house card as beating `OSW-*` has misread it.
+
+**A project rule beats an ORC rule outright.** Not a waiver and not a
+negotiation: the ORC rule is removed from the slice, and the removal is stated
+inside it. The assembler does that. The lane does not decide it.
+
+Where a lane's preflight prints a report rather than a bare line, the report
+**names** each override. An override the user cannot see is an override they
+cannot audit.
+
+## The `ui` pack rides per TASK, never per lane
+
+`ui` is in no lane's default set. Add it to a single slice, at dispatch time:
+
+> If a task's **declared files** are front-end — `.css`, `.scss`, `.html`,
+> `.jsx`, `.tsx`, `.vue`, `.svelte`, or a directory the wiki or the cached
+> pattern identifies as the UI layer — assemble that task's card with
+> `--pack ui`. Otherwise do not.
+
+A UI rule in a backend slice is tokens paid on every spawn for a rule that
+cannot apply. A lane that dispatches no tasks never passes `--pack ui` at all.
+
+## What comes back
+
+Every return from a slice that carried this card gains three fields
+(`../return-validation.md`):
+
+| Field | What it holds |
+|---|---|
+| `rules_applied[]` | the ids the agent acted on |
+| `rules_conflicts[]` | two rules that disagree. **A gap, never a silent choice** |
+| `rules_overridden[]` | an ORC id a project rule replaced |
+
+A `rules_conflicts[]` entry is relayed to the user as a gap through the lane's
+own gap channel. Resolving it quietly is the failure the field exists to prevent.
+
+## The boundary — declared, never validated
+
+Rules govern **what is written and how it reads**, and **what shape of code is
+acceptable**. They can never change how a lane **runs**: the scoring, the wave
+order, the gates, the dispatch contract, the ship rules, or any lane's
+structural and safety rules.
+
+A rule that asks for one of those comes back as `unsupported_request` and is
+relayed as a gap. **Never a guessed compromise.**
+
+**Do not build a detector for this.** The CLI declares the boundary and does not
+pretend to enforce it, for the reason `orc doc rules` already settled: a
+validator that sometimes works is worse than none, because a clean pass then
+means nothing. The agent is the only reader that can tell a content rule from a
+structural one, so the agent is where the answer comes from.
+
+## The free lint
+
+```
+orc rules lint <path…|--staged|--diff> [--pack w,c,d,u] [--json]
+```
+
+Deterministic, zero tokens. Exit `0` clean · `1` findings · `2` nothing to lint.
+
+It checks only the rules a string match can prove, and it prints — in every
+mode — how many it did not check. **Relay that coverage line whenever you relay
+a lint result.** A clean exit allowed to stand in for a review nobody did is the
+whole failure that line prevents.
+
+Findings are ADVISORY. This phase adds no gate: a style preference that fails a
+build gets switched off within a week, and then nothing is enforced at all.
+
+An exemption is never silent either. The lint skips the rules packs themselves
+(a rule that bans a word has to print that word to define it) and any file
+marked `orc-rules-ignore-file`, and it reports the count of both.
+
+## Cost, and where to cut it
+
+Measured at v1.7.0: roughly **3 600 tokens** per build-lane slice, **4 300** with
+the UI pack, **2 200** for a prose-only lane. The card already carries HARD rules
+in full and PURPOSE/LOCK rules as one line plus the file to open when one
+applies.
+
+If it must come down, the lever is the worked examples inside the HARD bodies,
+and the only place to pull it is `rulesSlice()` in `bin/cli.js`. **Never by a
+lane deciding to trim its own card** — that is the drift this phase exists to
+prevent, arriving disguised as a saving.
+
+**v1.9.0 — the COMPACT form, and the CLI decides which lanes get it.** The
+lever above is now pulled for **`orc-quick`** and for no one else: every HARD
+rule keeps its id, its title and its first line — the instruction — and the
+worked examples come out, with the pack file named beside them. Measured
+**13 874 → 5 838 chars** (~3 470 → ~1 460 tokens) with every HARD id still
+present. The lane that gets it is the lane with the smallest tasks under the
+largest fixed card, and the card is re-sent on every executor turn.
+
+The answer says which form it is: `compact: true` in the JSON. A reader that
+cannot tell a short card from a stripped one cannot trust either. `line` is
+IDENTICAL in both forms — it counts the rules in force, and compacting changes
+how a rule is written, never whether it applies.
+
+<!-- /orc:layer -->

package/templates/skills/_shared/phases/ship.md

@@ -53,7 +53,11 @@ subagent). The user must always know what the run cost. **Code graph
 (`../code-graph.md` §5–§6):** run `orc graph update --if-enabled` once more —
 fix rounds move code — and emit `GRAPH-UPDATE`; then run `orc graph notes pending
 --files <every path the run changed> --at end --if-enabled` — exit 0 → one noter
-dispatch, exit 3 or 5 → nothing. Finally emit
+dispatch, exit 3 or 5 → nothing. Then ONE line, once, copied VERBATIM from
+`orc graph gain --run <this run's trace name> --if-enabled --json` (emit
+`GRAPH-GAIN`): what the graph put in, and an ESTIMATE of the retrieval it kept
+out. Exit 1 or 3 → no line. **Never restate it as one number** — the range and
+the word "estimate" are the claim. Finally emit
 `PHASE ship end`, then the one-line `STATS lane=… dispatches=… downgrades=…`
 summary (trace.md — what `orc stats` reads), then `FINISH :: <detail>`,
 and in ONE step delete BOTH `log_dir/.current` and the run's `RESUME.md` (that

package/templates/skills/_shared/phases/trace.md

@@ -227,15 +227,17 @@ supplies the fact in a packet, the writer writes the line. `SPAWN`, `RETURN` and
 | Verb | Emitted by | Meaning |
 |------|-----------|---------|
 | `PHASE <name> start\|end` | orc → writer | phase transition |
-| `PHASE-EDGE <role-family> :: first=<agent>` | hook | **deterministic phase inference.** ORC agent names encode their role, so when a SPAWN's role family differs from the previous SPAWN's, the hook segments the run itself — families: `analyst\|scout → analysis`, `planner → planning`, `executor → execution`, `reviewer → review`, `verifier → verify`, `test-author → testgen`, `advisor\|judge → ultra-gate` (the trace writer never opens an edge). Zero model dependence: even a run where every writer dispatch was forgotten still reads planning → execution → review → verify, and `/orc-retro` computes NARRATION COVERAGE from edges with vs without a writer `SPAWN` between them |
+| `PHASE-EDGE <role-family> :: first=<agent>` | hook | **deterministic phase inference.** ORC agent names encode their role, so when a SPAWN's role family differs from the previous SPAWN's, the hook segments the run itself — families: `recon → recon` (v1.9.0 — /orc-quick's read-only half; a question answered for a person is not an analysis), `analyst\|scout → analysis`, `planner → planning`, `executor → execution`, `reviewer → review`, `verifier → verify`, `test-author → testgen`, `advisor\|judge → ultra-gate` (the trace writer never opens an edge). Zero model dependence: even a run where every writer dispatch was forgotten still reads planning → execution → review → verify, and `/orc-retro` computes NARRATION COVERAGE from edges with vs without a writer `SPAWN` between them |
 | `CONFIG <key=value …>` | orc → writer | Phase 1 — the resolved config values this run will consume (ALWAYS `opus5_only` — it selects the executor table AND every fixed role, so retro can segment outcomes by dispatch mode). Runtime proof that the run honored the config; `/orc-retro` audits it against behavior |
 | `WIKI-CONSULT <tier> :: docs=<list>` | orc → writer | project wiki consulted for grounding (full/mini at planning; fast at slice-build) — tier ∈ `fresh` \| `aging` \| `stale` \| `absent` \| `empty`; `docs=` the pages pulled/handed to the executor (comma list) or `none`. Records whether the run grounded in the wiki and whether it was stale (surfaces grounding + staleness for later audit) |
 | `CROSSLINK <state> :: boundaries=<n> peers=<names>` | orc → writer | cross-repo peer-knowledge state at the consult point — state ∈ `cached` (peer cache present) \| `configured-no-cache` (crosslink configured but the cache is not built) \| `none`. Per-task `CROSSLINK inject task=<id> :: <boundary>` when a slice receives a linked contract. Records whether peer contracts were injected this run (full orc consumes only the pre-built crosslink cache — it never reads peer source live; mechanism in `wiki-consult.md`) |
 | `GRAPH-CONSULT <state> :: files=<n> symbols=<n>` | orc → writer | the code graph's preflight state (`code-graph.md` §4) — state ∈ `fresh` \| `updated` \| `built` \| `drifted` \| `none` \| `off`. Copied VERBATIM from the `trace` field of `orc graph status --heal --json`; a `GATE` line that describes the graph in other words does not replace it. Plus `GRAPH-CONSULT card task=<id> :: targets=<…>` (the `trace` of `orc graph ctx --json`, with `task=` added) when a slice receives cards |
 | `GRAPH-UPDATE <state> :: parsed=<n> reused=<n> deleted=<n> gen=<n> route=<n> ms=<n>` | orc → writer | one graph update at a wave close, a green smoke gate, a code-writing `/orc-quick` request, or ship — the `trace` field of `orc graph update --json`, verbatim. The graph HOOK writes its own `GRAPH-UPDATE … :: by=hook …` lines directly; never copy one of those, it is already in the file |
+| `GRAPH-MAP <repo|focused> :: files=<shown>/<total> [focus=<a,b>] gen=<n>` | orc → writer | ONE line at the START of planning (and at a `/orc-quick` Q1 look that had no file to name) — the `trace` field of `orc graph map --json`, verbatim. `files=` is how many the budget SHOWED over how many the repository has, so a short map can be told from a small repository. `focused` means `--focus` re-ranked the repository around what the request named. RANK is a hint about where to look first and the trace never says more than that |
 | `GRAPH-CHANGES <found\|none> :: symbols=<n> high=<n> medium=<n> low=<n> gen=<n>` | orc → writer | one line at review — the `trace` field of `orc graph changes --json`, verbatim. `high` counts symbols that are exported, have three or more callers and NO test reaching them |
 | `GRAPH-COCHANGE <found\|none> :: rows=<n> commits=<n>` | orc → writer | one line per planning batch, not per file — the `trace` field of `orc graph cochange --json` for the file that produced the widest answer |
 | `GRAPH-HINT injected=<n> subagent_start=<n> read_notes=<n> updates=<n>` | orc → writer | ONE line per phase close, not one per hint — the counters `orc-graph-hook.js` keeps in `<log_dir>/<run>.graph-hook.json`. Omitted when the file does not exist (the hook is off, or it never had anything to say) |
+| `GRAPH-GAIN paid=<n> low=<n> high=<n> calls=<n>` | orc → writer | ONE line per run, at ship — the `trace` field of `orc graph gain --run <trace name> --json`, verbatim. `paid` is exact (the tokens the graph put in); `low`/`high` are an ESTIMATE of the retrieval it kept out, and they are never collapsed into one number. Omitted when the ledger is empty or the graph is off |
 | `GRAPH-NOTES <applied\|below-min\|none\|deferred\|off\|skipped> :: <detail>` | orc → writer | one notes batch: the noter's ONE-line return copied verbatim (`applied`), the `trace` field of `orc graph notes pending --json` when it exited 3 or 5, `skipped` under the Opus-5-only mode |
 | `SPAWN <agent>` | hook | an agent dispatch was observed (skeleton) |
 | `RETURN <agent> :: <desc> dur=<m>m<s>s [model=<id>]` | hook | a subagent finished (skeleton). The hook attributes the RETURN to the finishing agent from the SubagentStop payload (`~<agent>` = approximate FIFO match on older Claude Code that omits `agent_type`; `~agent :: unattributed` = ≥2 agents in flight, so it deliberately claimed NO pending record rather than starve the right one), echoes the SPAWN's desc + wall-clock duration, and appends `model=<id>` when the return's `actual_model` is visible in the last message. A duplicate stop for an agent whose record was already consumed is DROPPED, never written as a desc-less RETURN. Still hook-written skeleton — NOT an orchestrator obligation; the authoritative model check is the `VERIFY` line |
@@ -254,6 +256,7 @@ supplies the fact in a packet, the writer writes the line. `SPAWN`, `RETURN` and
 | `DRIFT loop=<n> :: <user description, compressed>` | orc → writer | mock-example drift-recovery loop opened (`PHASE mock-example`; canonical `_shared/drift-recovery.md`; hard cap 2 loops) |
 | `TDD-RED task=<id> iter=<n> :: <failing tests>` | executor→orc → writer | TDD repair-loop iteration — the plan's acceptance tests still red (cap `tdd_loop_max`; a paired TDD task's red proof also emits iter=0) |
 | `TDD-GREEN task=<id> iter=<n>` | executor→orc → writer | the task's TDD acceptance tests pass (the non-exempt definition-of-done) |
+| `REPRO red\|green :: <cmd> exit=<n>` | executor→orc → writer | a DEFECT task's reproduction, before and after the fix (`_shared/return-validation.md` §5d). TWO lines per reproduced defect, in this order: the `before` run must be RED and the `after` run GREEN, or the return was malformed. `REPRO none :: <reason>` when no reproduction could be written — an honest answer, never a missing line. A reproduction is NOT a plan-time acceptance test, so it never reuses `TDD-RED`/`TDD-GREEN`: `/orc-retro` counts "we proved the bug first" apart from "we drove the plan's acceptance tests" |
 | `NOTE :: <decisions>` | writer | the packet's `decisions` field — the WHY layer (scoring rationale, user answers verbatim, what was rejected). One line per packet, only when `decisions` is non-empty |
 | `STATS lane=<l> slug=<s> dispatches=<n> waves=<n> tasks=<n> bands=<h:n,m:n,l:n> downgrades=<n> duration_ms=<n>` | orc → writer | ONE deterministic summary line per run, in the `FINISH` packet, immediately BEFORE the `FINISH` line. This is what `orc stats` reads — one line per file, never a parse of the whole trace. Omit a field you genuinely do not have (a lane with no waves omits `waves=`); never guess one. Every trace-owning lane emits it, not just `orc` |
 | `PACT <state> :: <ids>` | orc → writer | invariant-ledger state at the Phase-1 probe (`pact_gate`), and `PACT inject task=<id> :: <PACT-id>` when a DRIFTED/BROKEN promise is appended to a task's `constraints[]`. `PACT recheck pass\|fail :: <ids>` at Phase 6. Records whether last month's decisions constrained this month's plan |

package/templates/skills/_shared/phases/wiki-consult.md

@@ -74,19 +74,23 @@ in play.
   whenever the request uses project jargon, `orc-reference-config-env` for
   config/env work.
 
-**Lane delta — orc-fast passes POINTERS, not content:** fast selects 1–3 page
-PATHS from `wiki/INDEX.md` and puts the paths in the executor slice with the
+**Lane delta — orc-fast and orc-mini pass POINTERS, not content:** each selects
+1–3 page PATHS from `wiki/INDEX.md` and puts the paths in its slices with the
 instruction to READ them first (TL;DR for orientation, `Contracts & shapes` for
-specifics). Fast never pastes wiki bodies into a slice (a Sonnet-medium
-orchestrator curating wiki prose defeats the lane). Full/mini read the content
-themselves at planning time.
+specifics). Neither pastes a wiki body into a slice, and neither reads one into
+its OWN context — for fast, a Sonnet-medium orchestrator curating wiki prose
+defeats the lane; for mini (v1.9.0), the orchestrator's context is the surface
+that fills up first, and the planner and the executor can read a page far more
+cheaply than it can carry one. The FULL lane still reads the content itself at
+planning time, because it has a reviewer and a verifier to spend that context
+on.
 
 ## Step 3 — Precedence (everywhere the wiki is consumed)
 
 `code > fresh wiki > stale wiki (hints) > model priors`
 
 When the code graph is on, it slots in without changing that order —
-`code > graph structure (current blob) > fresh wiki > stale wiki (hints) > graph notes > model priors`
+`code > graph structure (current blob) > fresh wiki > stale wiki (hints) > graph notes and doc notes > model priors`
 — canonical in `../code-graph.md`. The graph never needs a wiki: an absent wiki
 changes nothing about how the graph is consulted.
 

package/templates/skills/_shared/read-ladder.md

@@ -21,7 +21,7 @@ Escalate one step at a time. Stop at the step that answers the question.
 |------|----|----------------|
 | 1. Locate | `Grep` / `Glob` for the symbol, route, config key, or error string | You only needed to know WHERE it is |
 | 2. Outline | Read the file's declaration lines — imports, exports, top-level signatures | You needed the API surface |
-| 3. Range | Read the ±40 lines around the anchor found in step 1 | You needed one function's behaviour |
+| 3. Range | Read the ±40 lines around the anchor found in step 1 — or let step 0 print them (`--source`) | You needed one function's behaviour |
 | 4. Full | Read the whole file | It is the subject of the task — or you will edit it |
 
 ## Step 0 — ask the graph (always first; the CLI decides if it is on)
@@ -32,6 +32,14 @@ answers step 1 and step 2 together: where the symbol is, its line range, who
 calls or uses it, what it calls, and which effects it has. Then continue at
 step 3 — read the RANGE the card names before you act on behaviour. The graph is
 a locator, never the truth: a card whose header says CHANGED is hints only.
+
+**`--source [N]` answers step 3 in the SAME call** (v1.8.2). `orc graph ctx
+<symbol> --source --if-enabled --json` prints the card and then the target's own
+lines (default 80, hard cap 200), charged against the same `--budget`; the
+footer says how many lines it cut. Use it for the CALLER'S range, the callee's,
+the neighbour you will not touch. **It never replaces exception 1**: a file you
+will EDIT is read IN FULL with `Read` first, because an `old_string` rebuilt
+from a printed range is the same corruption bug as one rebuilt from an outline.
 Exit 3 (off) → skip step 0 for the rest of the task. Exit 1 (no index) or 4 (not
 in the graph) → step 1 as before. Name the card targets you used in
 `graph_used`. Both exceptions below apply unchanged.
@@ -117,7 +125,7 @@ The ladder governs HOW MUCH to read. It never decides WHETHER knowledge exists
 that is `detecting-artifacts.md` — and it never overrides precedence:
 `code > fresh wiki > stale wiki (hints) > model priors`. With the code graph on,
 the same order gains two rungs and loses none:
-`code > graph structure (current blob) > fresh wiki > stale wiki (hints) > graph notes > model priors`.
+`code > graph structure (current blob) > fresh wiki > stale wiki (hints) > graph notes and doc notes > model priors`.
 
 What a lane INVOKES, and what each exit code means, is not here either: that is
 `orc lane calls <lane> --json`, whose catalogue is the one copy of every call

package/templates/skills/_shared/return-validation.md

@@ -231,6 +231,28 @@ A rule the slice could not honour because this lane structurally cannot do it
 comes back as `unsupported_request`, relayed as a gap. **Never a guessed
 compromise.**
 
+## 5d. Reproduce-first attestation (when a `repro` was requested — v1.9.0)
+
+A slice that carried `repro: {required: true, kind, hint}` must come back with a
+`repro` field. Either both runs, quoted verbatim, or an honest `none`:
+
+```
+repro: { command, before: {exit_code, tail}, after: {exit_code, tail} }
+repro: none  — <one line of reason>
+```
+
+Two malformed shapes, and they are the whole point of the field. **`status=done`
+with `before.exit_code` 0** means the "reproduction" never failed, so it proved
+nothing; **`status=done` with a non-zero `after.exit_code`** means the bug is
+still there. Either one is a failure of the return, not a finding about the
+code. A `repro: none` is a valid answer — a defect with no reachable entry point
+and no runner cannot be shown red — and the lane says **not reproduced** out
+loud rather than letting a green suite imply a fixed bug.
+
+`repro` is required ONLY when the slice carried `repro.required: true`. A slice
+that asked for none gets none back, exactly like `tdd_spec`, `wiki_used` and
+`graph_used`.
+
 ## 6. Worktree delta (post-wave, every lane that dispatches executors)
 
 Compare `git status --short` before and after each dispatch. A path that

package/templates/skills/context-combiner/SKILL.md

@@ -11,10 +11,10 @@ description: >
   collapsed, conflicts, ordering) one issue at a time; proves NOTHING WAS LOST
   via a source coverage matrix and a 100% coverage gate before handoff;
   spot-checks inherited evidence and marks stale anchors; writes
-  combined-report.md + combined-requirement-spec.md (the merged spec reuses the
-  requirement-spec schema, so the planner/build pipeline is unchanged). Full
-  lane only (Opus 5 high). The orchestrator DISPATCHES this to a subagent —
-  it never combines itself, and the combiner never builds or spawns subagents.
+  combined-report.md + combined-requirement-spec.md, which reuse the
+  requirement-spec schema, so the planner/build pipeline is unchanged. Full
+  lane only. The orchestrator DISPATCHES this to a subagent — it never
+  combines itself, and the combiner never spawns subagents.
 ---
 
 # CONTEXT-COMBINER
@@ -211,12 +211,12 @@ exit code, and never re-derive a state word — the CLI's state words are the on
 state words, and **an exit code is an ANSWER wherever that contract says so, not
 a failure**. A call the answer does not name is a call this lane does not make.
 Exit ≠ 0 from the catalogue itself → say the CLI is unavailable and name the
-command you are about to run, out loud, before running it.
-
-## Rules — the anti-slop card (`../_shared/phases/rules.md`)
-
-`orc rules slice --lane context-combiner --json` is the ONLY assembler; never build
-the card here. It rides under the house rules and above the task —
-**house rules > your project's rules > ORC's own packs** — and its `line` prints
-VERBATIM at preflight. Returns gain `rules_applied[]`, `rules_conflicts[]` (a gap,
-never a silent choice) and `rules_overridden[]`.
+command you are about to run, out loud, before running it.
+
+## Rules — the anti-slop card (`../_shared/phases/rules.md`)
+
+`orc rules slice --lane context-combiner --json` is the ONLY assembler; never build
+the card here. It rides under the house rules and above the task —
+**house rules > your project's rules > ORC's own packs** — and its `line` prints
+VERBATIM at preflight. Returns gain `rules_applied[]`, `rules_conflicts[]` (a gap,
+never a silent choice) and `rules_overridden[]`.

package/templates/skills/orc/SKILL.md

@@ -205,7 +205,7 @@ them; they are never dispatched as subagents).
 - Phase 5.5 → `../_shared/phases/security-checklist.md`; 6.5 → `subskills/orc-testgen/`
 - Phase 8 → `subskills/orc-pr/SKILL.md` (template `subskills/orc-pr/pr.md`);
   stack gate → `subskills/orc-pr/stack-gate.md` + `_shared/pr-templates.md`
-- Code graph cache, NEVER skipped (§0 of the contract) — `orc graph status --if-enabled --heal --json` at preflight BEFORE the first dispatch (builds or updates it) · ONE `orc graph ctx <declared files>` call per slice · `orc graph impact` + `orc graph cochange` at planning, `orc graph changes` at review · `orc graph coverage` before you trust a card's silence · `orc graph update` + `orc graph notes` at every wave close and ship · print each JSON `line`, copy each `trace` VERBATIM (CLI-resolved) → `../_shared/code-graph.md`
+- Code graph cache, NEVER skipped (§0 of the contract) — `orc graph status --if-enabled --heal --json` at preflight BEFORE the first dispatch (builds or updates it) · ONE `orc graph ctx <declared files>` call per slice · `orc graph map` FIRST at planning (orientation — before any Glob, before `impact`) then `orc graph impact` + `orc graph cochange`, `orc graph changes` at review · `orc graph coverage` before you trust a card's silence · `orc graph update` + `orc graph notes` at every wave close and ship · print each JSON `line`, copy each `trace` VERBATIM (CLI-resolved) → `../_shared/code-graph.md`
 - Schemas (you own; pass slices only): `schemas/intent-spec.md`,
   `schemas/planning-output.md`, `schemas/checkpoint.md`
 - Worked example (orient only — never execute from it) → `examples/full-run-mock.md`