@azure-id/orc 1.8.1 → 1.8.2

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/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`

package/templates/skills/orc-analyze/SKILL.md

@@ -244,16 +244,16 @@ 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 orc-analyze --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[]`.
-## Waiting mid-run (`/orc-wait`)
-
-Canonical: `../_shared/wait.md`. **`a lane that waits without a hand-back` has broken this contract.**
-Checkpoint **full** · safe point **after the analyst returns**. `soft` FORCES that checkpoint and does NOT stop if the write fails; `hard` skips it and can lose an in-flight return. Never begin a wait between a dispatch and its validated return, or before the smoke gate has reported.
+command you are about to run, out loud, before running it.
+
+## Rules — the anti-slop card (`../_shared/phases/rules.md`)
+
+`orc rules slice --lane orc-analyze --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[]`.
+## Waiting mid-run (`/orc-wait`)
+
+Canonical: `../_shared/wait.md`. **`a lane that waits without a hand-back` has broken this contract.**
+Checkpoint **full** · safe point **after the analyst returns**. `soft` FORCES that checkpoint and does NOT stop if the write fails; `hard` skips it and can lose an in-flight return. Never begin a wait between a dispatch and its validated return, or before the smoke gate has reported.

package/templates/skills/orc-diy/references/flow-schema.md

@@ -27,7 +27,7 @@ selector.
 | `mock_example` | `ask` / `on` / `off` | Post-verify mocked example + drift recovery (`mock-examples/<slug>/`, never committed) |
 | `tdd` | `on` / `off` | TDD-anchored planning: plan-time `tdd_spec` (scoped by `disposition`), paired TDD tasks for the red proof, TDD gate in the verify slot |
 | `gotchas` | `on` / `off` | Repair memory: inject scope-matching gotchas into slices, record one when a repair loop goes red → green (`_shared/gotchas.md`) |
-| `code_graph` | `on` (default) / `off` | Code-graph cache steps: `orc graph status --heal` at preflight, `orc graph ctx` cards in slices, `orc graph impact` + `orc graph cochange` at planning, `orc graph changes` at review, `orc graph coverage` on demand, `orc graph update` after every wave and at ship, one `orc graph notes` batch per wave when notes are on. `on` compiles them in and the global `code_graph` key decides at run time (every call carries `--if-enabled`); `off` removes them (`_shared/code-graph.md`) |
+| `code_graph` | `on` (default) / `off` | Code-graph cache steps: `orc graph status --heal` at preflight, `orc graph ctx` cards in slices, `orc graph map` then `orc graph impact` + `orc graph cochange` at planning, `orc graph changes` at review, `orc graph coverage` on demand, `orc graph update` after every wave and at ship, one `orc graph notes` batch per wave when notes are on. `on` compiles them in and the global `code_graph` key decides at run time (every call carries `--if-enabled`); `off` removes them (`_shared/code-graph.md`) |
 | `wiki_gate` | `notice` / `off` / `hard` | Wiki freshness handling at preflight |
 | `post_ship_wiki_ask` | `on` / `off` | Post-ship wiki refresh offer on big runs |
 | `summary` | `full` / `off` / `short` | Summary depth |

package/templates/skills/orc-wiki/references/staleness.md

@@ -14,7 +14,7 @@ claim override what a file actually shows; never let a model prior override a
 fresh, evidence-anchored wiki claim without reading the code.
 
 With the local code graph on, the 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.**
 Graph structure outranks the wiki because it is extracted from the exact current
 bytes; graph notes rank below it because a model wrote them. Canonical:
 `skills/_shared/code-graph.md`.