@azure-id/orc 2.1.1 → 2.2.0

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

@@ -12,7 +12,7 @@ description: >
 
 The quick lane. You ask for something. It looks, asks you **one** set of
 questions, dispatches one agent, and writes down what happened. **Three steps
-per request, one user turn. Fewer than any other lane. Do not add steps.**
+per request, one user turn. Do not add steps.**
 
 **You never implement — you spawn.** You read only to FIND the right files. To
 UNDERSTAND something, you dispatch an agent.
@@ -21,7 +21,7 @@ UNDERSTAND something, you dispatch an agent.
 decide if it only READS or also WRITES → pick what to dispatch → **ask the
 user** → dispatch → check the return → write the doc entry. No request is "not
 supported"; a request can only be **too big**, and then you OFFER `/orc-mini`.
-**What this lane is NOT** — no teaching doc, no repo scan, no spec, no plan, no
+**What this lane is NOT** — no repo scan, no spec, no plan, no
 waves, no scoring, no acceptance pass (`README.md` §2).
 
 ---
@@ -34,10 +34,9 @@ without the manifest (`../_shared/lane-contract.md` §Phases).
 
 ## Q0 — Preflight (ONE time per session, silent, nothing can stop the run)
 
-1. **Config.** Read `log_dir` only. Read no other key. **One exception, and it
+1. **Config.** Read `log_dir` only. **One exception, and it
    is a PROBE, not a key read:** `probes["extra-slot"]` in the `orc lane config`
-   answer (`resolved`: extra or claude) answers the master gate, the position and the
-   routing in one, so the code-writing menu can offer line 3. Do not call
+   answer (`resolved`: extra or claude) answers the gate and the routing, so the code-writing menu can offer line 3. Do not call
    `orc extra resolve --slot quick-executor`. **A gate that is never probed is a
    gate that is always off.** Keep the answer for this session; it is an OPTION
    on a menu, never a default (`references/dispatch-gate.md`). **`habits{}` in
@@ -61,7 +60,7 @@ without the manifest (`../_shared/lane-contract.md` §Phases).
 4. **Code graph cache — never skipped** (`../_shared/code-graph.md` §0). Print
    `probes["graph-status"].line`; run
    `orc graph status --if-enabled --heal --json --brief` only when `heal_needed` is true. Put the `trace` (`GRAPH-CONSULT …`) in
-   the packet VERBATIM. Exit 3 = off → no other graph call this session. Every graph
+   the packet VERBATIM. Exit 3 (`off` or `semi`) → no other graph call this session. Every graph
    call carries `--if-enabled`, so the CLI reads the `code_graph` keys —
    this lane still reads `log_dir` and nothing else.
 5. **`gh` probe — only when the request names a PR** (`pr <n>`, `PR <n>`, a
@@ -96,16 +95,15 @@ Print it on ONE line:
 
 **The dig — graph first** (`references/look.md`). Ask the graph BEFORE any
 Grep; Grep only for what the graph does not know.
-- Names a file or symbol → `orc graph ctx <targets> --if-enabled --json --brief`, 5 at
-  most. Names none → `orc graph map --focus "<3–6 words>" --budget 800
-  --if-enabled --json --brief`, then `ctx` on the files it ranks first. Asks what breaks
-  or who uses something → `ctx <symbol> --depth 2` and `orc graph coverage
-  <files> --if-enabled --json --brief` before you call anything absent. Exit 3 →
-  Grep/Glob. Exit 4 → Grep the name, carry EVERY candidate into your question.
-  Copy each `line` into chat, each `trace` into the running record. A `map`
-  answer is ONE call; a card never replaces reading the range it names.
+- Names a symbol → ONE `orc graph ctx <symbol> --anchors --focus=<words> --if-enabled
+  --json --brief`: callers, tests (also via a caller), coverage — no Grep of that name,
+  `coverage` only on `partial`; `anchors_card` = the slice's `graph_anchors` (no
+  `--for-slice`), declared = target file + its caller files. Files → `ctx <files>` (≤ 5).
+  None → `orc graph map --focus=<3–6 words> --budget 800 …`, then ONE `ctx` (≤ 5), not
+  `cat`/`grep`. Exit 3 → Grep/Glob. Exit 4 → Grep the name, carry EVERY candidate.
+  `line` → chat, `trace` → the record. A card never replaces reading its range.
 - Wiki exists → pick 1–3 pages from `wiki/INDEX.md` and keep their **PATHS**
-  only. Never paste wiki text into a slice. Emit
+  only. With `graph_anchors` in the slice, list at most ONE wiki page path (the one about the feature's intent), not 1–3. Never paste wiki text into a slice. Emit
   `WIKI-CONSULT <tier> :: docs=<paths>`.
 - Pattern cached → keep it for the slice.
 - Always put this line in every slice, word for word:
@@ -157,12 +155,14 @@ Rules:
 
 ### 3.1 Dispatch and check the return
 
-Put in the slice: the change sketch, the Q2 answers, 2–3 acceptance bullets, the
-`graph` block from `orc graph ctx <declared files> --for-slice --if-enabled
---json --brief` (the OUTSIDE view — `references/look.md` §5), the wiki **paths**, the
-cached pattern (whole text), the `house_rules` card
-(`../_shared/phases/house-rules.md`, whole text), the `rules_card` under it
-(`orc rules slice --lane orc-quick --json` → `text`, whole text), PR comments
+Put in the slice: the change sketch, Q2 answers, 2–3 acceptance bullets, the
+`graph_anchors` (WHOLE `card` VERBATIM, `read all:` + code) from ONE `orc graph ctx --for-slice <declared files>
+--focus=<3–8 words: request, doc, copy-from name> [--refs=<copy-FROM files,
+found first>] --anchors --if-enabled --json --brief`
+(print `line`; exit 3/4 or one file, no outside change → none — `references/look.md`
+§5), the wiki **paths**, the cached pattern, the `house_rules` card
+(`../_shared/phases/house-rules.md`), the `rules_card` under it
+(`orc rules slice --lane orc-quick --json` → `text`) — all three whole text, PR comments
 with their `file:line`, and a short-return rule. A `kind: defect` entry also
 carries `repro` — the EXECUTOR writes it red, then fixes it green, never you
 (`references/defect.md`). An **ad-hoc** dispatch is also told to report its own
@@ -170,7 +170,7 @@ carries `repro` — the EXECUTOR writes it red, then fixes it green, never you
 
 Check the return with `../_shared/return-validation.md` §1–§3 + each injected
 field's §: honest `unmet[]`, `pattern_version` + `invariants_checked`,
-`graph_used` (absent on a slice that carried a card = malformed), `repro` when
+`graph_used` (absent on a slice that carried `graph_anchors` = malformed), `repro` when
 the slice asked for it, and `actual_model` / `actual_effort` → emit `VERIFY`, which names
 `graph_used=<n> targets gen <n>` and `repro red→green` beside the model match,
 and show ⛔ DOWNGRADE if they differ. Also compare `git status --short`
@@ -209,16 +209,13 @@ Never offer commit while tests are red.
 
 ### 3.3 Write the doc — ALWAYS, and BEFORE any offer
 
-**After a request that WROTE code** (never after a read-only one), so the next
-request and the next session start from a current cache, in this order:
+**After a request that WROTE code** (never after a read-only one), and ONLY
+when `probes["graph-status"].update_step` is `lane`:
 `orc graph update --notes-pending --files <actual_files> --if-enabled --json --brief`
 — ONE call that answers both (print its `line`, copy its `trace`). Exit 0 on
-`notes` → dispatch `orc-graph-noter-sonnet-4-6-med` in the SAME tool block as
-this doc write. It is ORC bookkeeping, like the trace writer — not a Q2 gate
-dispatch (`references/dispatch-gate.md` rule 8). Exit 3 or 5 → nothing. Then,
-after the entry is appended, `orc graph gain --run <this run> --if-enabled
---json --brief` → print its `line` VERBATIM into chat and the entry. It is an estimate
-with a range; never restate it as a saving.
+`notes` → dispatch `orc-graph-noter-haiku-5-high` in the SAME tool block as
+this doc write — bookkeeping, not a Q2 gate dispatch (`references/dispatch-gate.md` rule 8). Exit 3 or 5 → nothing.
+`hook`, `preflight` or `none` → no update call. No lane runs the gain meter.
 
 Append entry N to `orc-quick/<slug>/quick-context.md`
 (`references/context-doc.md`, only `## Entry shape` or `## A read-only entry`).
@@ -270,8 +267,8 @@ every event is a protocol violation. Pipe each packet to
 
 ## Lane contract (`../_shared/lane-contract.md` — read it ONLY when a call exits ≠ 0)
 
-- **Calls:** `orc lane calls orc-quick --json` names every call and its exit codes.
-  **An exit code is an ANSWER where it says so, not a failure.** Make no other call.
+- **Calls:** `orc lane calls orc-quick --json` names shared calls and exit codes.
+  **An exit code is an ANSWER where it says so, not a failure.** Own calls are here; make no other.
 - **Config:** `orc lane config orc-quick --json`. Obey `effective`, print every line
   in `announce[]` VERBATIM at preflight, and honour `stops[]` before wave 1.
   Never merge `.claude/orc.config.yaml` yourself (`../_shared/config-precedence.md`).

package/templates/skills/orc-quick/references/context-doc.md

@@ -1,145 +1,145 @@
-# The quick context doc — shape and rules
-
-This is the file orc-quick writes after every request. It is written for a
-HUMAN to read later, in this session or a different one.
-
-## Where it goes
-
-```
-<projectRoot>/orc-quick/<slug>/quick-context.md
-```
-
-- `<slug>` is the slug of the **first** request in the thread. No date in the
-  folder name.
-- **One file per folder. Never make a second `.md` file.** No `review.md`, no
-  `diff.md`, no per-request files.
-- It sits at the project root, next to folders like `test-generator/` and
-  `learning-docs/` — never inside `.claude/`.
-
-## Rules
-
-1. **Write it BEFORE the offers** (test / review / commit). If the user walks
-   away, the entry is still complete.
-2. **Every request gets an entry** — even a read-only dig. There, the answer IS
-   the result.
-3. **Never read the body of this file.** Only two exceptions:
-   - the TOC block, when you re-open a thread;
-   - the user asks you to read it.
-4. **Never commit it.** It is not staged, ever. Do not edit `.gitignore`.
-5. One entry can hold **several dispatches**. A dig that turns into a fix is ONE
-   entry with two rows in its table.
-
-## The TOC block
-
-The top of the file has a short list between markers:
-
-```markdown
-<!-- orc-quick:toc -->
-1. Change json payload A → B                05-08-2026 14:23:10  ✅ committed a1b2c3d
-2. How does tenant scoping work?            05-08-2026 15:47:02  ℹ answered
-3. Why does /orders 500? — found & fixed    10-08-2026 09:15:44  ✅ committed 7f2e1a9
-<!-- /orc-quick:toc -->
-```
-
-**Why the markers matter.** When you open a thread again, you need to know the
-next number. You read ONLY this block — it is small and cheap. You do not read
-the entries below it. That is how "never read the doc" and "keep counting" can
-both be true.
-
-Inside one session, the count is also kept in
-`.claude/orc/run/<run-slug>/quick-checkpoint.md`. That file is run state, not
-the deliverable, so you may read it freely.
-
-**If the TOC is broken or missing:** rebuild it by scanning ONLY the lines that
-start with `## <number>.`. Do not read the text under them. Then write the block
-back between the markers. Never start a second thread because of a broken TOC.
-
-## Entry shape
-
-Use as many of these as apply. Leave out what does not fit.
-
-```markdown
-## <n>. <short title>
-**asked** DD-MM-YYYY HH:MM:SS
-> the user's request, word for word
-
-**kind** code-change | context-dig | investigate → code-change | pr-comments | …
-**resolved intent** one or two sentences: what you actually decided to do.
-
-**clarified**
-- <question> → **Y**: <what won> · X was <what the user first said> ·
-  Z was <the other idea, and why it lost>
-
-**knowledge** wiki FRESH · docs=<paths> · pattern express@v3
-
-**dispatches**
-| # | kind | agent / model | expect | actual | result |
-|---|---|---|---|---|---|
-| 1 | recon | `orc-recon-sonnet-5-med` | sonnet-5-5/medium | sonnet-5-5/medium ✅ | what it found |
-| 2 | executor | `orc-executor-sonnet-5-med` | sonnet-5-5/medium | sonnet-5-5/medium ✅ | 3 files |
-
-Only an **other** dispatch keeps the `*(ad-hoc, untraced-by-hook)*` mark. A
-dispatch of either pinned recon agent is a normal row with the agent's name.
-
-**files changed** path · path · path
-
-**repro** red → green · `npm test -- tests/orders.search.test.js` (before: exit 1 · after: exit 0)
-**blast radius** 3 symbols · callers 7 in 4 files · tests reach 2 · risk high: searchByItemPrefix (exported, fan-in 4, no test reaches it)
-**tests** reached 12 passed · suite 41 passed
-**graph** gen 42 · cards 2 · <the `orc graph gain` line, word for word>
-
-**how it was resolved** a short, plain explanation of the fix and WHY this way.
-Say what you did not do, and why. This is the most useful part later.
-
-**build** GREEN · **tests** 41 passed
-**unmet** things you did not do, on purpose or not
-
-**follow-through** tests · review result · commit hash · pushed or not
-```
-
-For PR work, also add:
-
-```markdown
-**pr** #142 "title" · branch · url
-
-**threads taken** 2 of 3
-| # | reviewer | anchor | comment |
-|---|---|---|---|
-| 1 | @dana | src/routes/export.js:34 | the comment text |
-
-**github writes** NONE — no reply, no resolve, no review.
-```
-
-These four lines are optional and go in that order, after `**files changed**`.
-Leave out the ones that do not apply:
-
-- **`repro`** — only on a defect entry. `repro: none` writes
-  `**repro** not reproduced — <the reason>` instead. Never leave it out to keep
-  the entry tidy: an unreproduced fix is the thing the reader most needs to know.
-- **`blast radius`** — a `risk` word NEVER appears without its `why`. Nothing in
-  the graph → `none indexed (<n> files not in the graph)`.
-- **`graph`** — the gain line is an estimate with a range. Copy it; never turn
-  it into a saving.
-
-## A read-only entry
-
-A dig has no files, no build and no tests. It still gets a full entry:
-
-- **`how it was resolved`** holds the recon `answer`.
-- **`unmet`** holds the recon `unresolved[]`.
-- A blast-radius dig lists the four caller classes apart — `direct`, `route`
-  (reached through a URL), `via_alias`, `inherited` — and, when any list rests
-  on the graph alone, the sentence the agent returned, word for word:
-  *A card lists every caller that NAMES the symbol. A card's silence is not
-  proof of absence.*
-
-## Writing style for entries
-
-Write for a person who comes back in three weeks and forgot everything.
-
-- Use plain words. Short sentences.
-- Always name real files and line numbers.
-- Say **why** you chose one option and not the other. A rejected idea with its
-  reason saves the next person from trying it again.
-- Record what you did NOT do. "Backfill not done — user asked to leave it" is
-  more useful than silence.
+# The quick context doc — shape and rules
+
+This is the file orc-quick writes after every request. It is written for a
+HUMAN to read later, in this session or a different one.
+
+## Where it goes
+
+```
+<projectRoot>/orc-quick/<slug>/quick-context.md
+```
+
+- `<slug>` is the slug of the **first** request in the thread. No date in the
+  folder name.
+- **One file per folder. Never make a second `.md` file.** No `review.md`, no
+  `diff.md`, no per-request files.
+- It sits at the project root, next to folders like `test-generator/` and
+  `learning-docs/` — never inside `.claude/`.
+
+## Rules
+
+1. **Write it BEFORE the offers** (test / review / commit). If the user walks
+   away, the entry is still complete.
+2. **Every request gets an entry** — even a read-only dig. There, the answer IS
+   the result.
+3. **Never read the body of this file.** Only two exceptions:
+   - the TOC block, when you re-open a thread;
+   - the user asks you to read it.
+4. **Never commit it.** It is not staged, ever. Do not edit `.gitignore`.
+5. One entry can hold **several dispatches**. A dig that turns into a fix is ONE
+   entry with two rows in its table.
+
+## The TOC block
+
+The top of the file has a short list between markers:
+
+```markdown
+<!-- orc-quick:toc -->
+1. Change json payload A → B                05-08-2026 14:23:10  ✅ committed a1b2c3d
+2. How does tenant scoping work?            05-08-2026 15:47:02  ℹ answered
+3. Why does /orders 500? — found & fixed    10-08-2026 09:15:44  ✅ committed 7f2e1a9
+<!-- /orc-quick:toc -->
+```
+
+**Why the markers matter.** When you open a thread again, you need to know the
+next number. You read ONLY this block — it is small and cheap. You do not read
+the entries below it. That is how "never read the doc" and "keep counting" can
+both be true.
+
+Inside one session, the count is also kept in
+`.claude/orc/run/<run-slug>/quick-checkpoint.md`. That file is run state, not
+the deliverable, so you may read it freely.
+
+**If the TOC is broken or missing:** rebuild it by scanning ONLY the lines that
+start with `## <number>.`. Do not read the text under them. Then write the block
+back between the markers. Never start a second thread because of a broken TOC.
+
+## Entry shape
+
+Use as many of these as apply. Leave out what does not fit.
+
+```markdown
+## <n>. <short title>
+**asked** DD-MM-YYYY HH:MM:SS
+> the user's request, word for word
+
+**kind** code-change | context-dig | investigate → code-change | pr-comments | …
+**resolved intent** one or two sentences: what you actually decided to do.
+
+**clarified**
+- <question> → **Y**: <what won> · X was <what the user first said> ·
+  Z was <the other idea, and why it lost>
+
+**knowledge** wiki FRESH · docs=<paths> · pattern express@v3
+
+**dispatches**
+| # | kind | agent / model | expect | actual | result |
+|---|---|---|---|---|---|
+| 1 | recon | `orc-recon-sonnet-5-med` | sonnet-5-5/medium | sonnet-5-5/medium ✅ | what it found |
+| 2 | executor | `orc-executor-sonnet-5-med` | sonnet-5-5/medium | sonnet-5-5/medium ✅ | 3 files |
+
+Only an **other** dispatch keeps the `*(ad-hoc, untraced-by-hook)*` mark. A
+dispatch of either pinned recon agent is a normal row with the agent's name.
+
+**files changed** path · path · path
+
+**repro** red → green · `npm test -- tests/orders.search.test.js` (before: exit 1 · after: exit 0)
+**blast radius** 3 symbols · callers 7 in 4 files · tests reach 2 · risk high: searchByItemPrefix (exported, fan-in 4, no test reaches it)
+**tests** reached 12 passed · suite 41 passed
+**graph** gen 42 · <the pack `line`, word for word>
+
+**how it was resolved** a short, plain explanation of the fix and WHY this way.
+Say what you did not do, and why. This is the most useful part later.
+
+**build** GREEN · **tests** 41 passed
+**unmet** things you did not do, on purpose or not
+
+**follow-through** tests · review result · commit hash · pushed or not
+```
+
+For PR work, also add:
+
+```markdown
+**pr** #142 "title" · branch · url
+
+**threads taken** 2 of 3
+| # | reviewer | anchor | comment |
+|---|---|---|---|
+| 1 | @dana | src/routes/export.js:34 | the comment text |
+
+**github writes** NONE — no reply, no resolve, no review.
+```
+
+These four lines are optional and go in that order, after `**files changed**`.
+Leave out the ones that do not apply:
+
+- **`repro`** — only on a defect entry. `repro: none` writes
+  `**repro** not reproduced — <the reason>` instead. Never leave it out to keep
+  the entry tidy: an unreproduced fix is the thing the reader most needs to know.
+- **`blast radius`** — a `risk` word NEVER appears without its `why`. Nothing in
+  the graph → `none indexed (<n> files not in the graph)`.
+- **`graph`** — the pack `line`, as the CLI printed it. Copy it; never
+  change it.
+
+## A read-only entry
+
+A dig has no files, no build and no tests. It still gets a full entry:
+
+- **`how it was resolved`** holds the recon `answer`.
+- **`unmet`** holds the recon `unresolved[]`.
+- A blast-radius dig lists the four caller classes apart — `direct`, `route`
+  (reached through a URL), `via_alias`, `inherited` — and, when any list rests
+  on the graph alone, the sentence the agent returned, word for word:
+  *A card lists every caller that NAMES the symbol. A card's silence is not
+  proof of absence.*
+
+## Writing style for entries
+
+Write for a person who comes back in three weeks and forgot everything.
+
+- Use plain words. Short sentences.
+- Always name real files and line numbers.
+- Say **why** you chose one option and not the other. A rejected idea with its
+  reason saves the next person from trying it again.
+- Record what you did NOT do. "Backfill not done — user asked to leave it" is
+  more useful than silence.