@azure-id/orc 1.7.1 → 1.8.1

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

@@ -1,53 +1,63 @@
-# Phase — Review   (id: `review`)
-
-> **Shared phase file.** Moved out of `orc/SKILL.md` at v1.0.0 W12, and into
-> this library at W13 when `orc-diy` became its second reader. A spine is loaded
-> IN FULL when its skill activates; this is loaded when the phase fires, and most
-> runs skip most phases.
->
-> **Two layers, and a lane reads exactly one.** `full` is `/orc`'s procedure.
-> `composed` is what `orc diy compile` stitches — the same phase expressed as
-> `<!-- diy:when -->` variants over a composed flow, NOT a second copy of the
-> procedure. Reading the wrong one is the failure `README.md` names: a lane
-> doing a phase its product promise says it does differently.
-> `orc lane phases <lane> --json` names the layer for each lane.
-
-<!-- orc:layer full -->
-
-## Review (load ../../orc/subskills/orc-review-verify/, spawned)
-
-Emit `PHASE review start`. Superpowers path: its review skill incl. tests
-(Sonnet 4.6 medium). OpenSpec/self path: review worker (Opus 5 medium). Pass the resolved
-`code_pattern` + its invariants + gate lines for the re-check
-(pattern-gate.md); no resolved pattern → FIRST ask for one (paste/md/none).
-FE tasks in run → pass `fe_rules[]` from `../../orc-pattern/references/` fe-a11y
-+ fe-perf. Findings arrive on the **P0–P3 ladder** (invariant violation or
-unmet gate line = P0; every P0–P2 carries `file:line` + VERBATIM `quote`;
-unanchored → P3). Apply hard rule 5 INCLUDING the quote spot-check: P0 →
-auto-fix once · P1 → ask, then fix once · P2/P3 → record for Phase 7. Emit
-`FINDING p0=<n> p1=<n> p2=<n> p3=<n>` on the return, then `PHASE review end`.
-
-<!-- /orc:layer -->
-
-<!-- orc:layer composed -->
-
-## Phase: Review
-
-<!-- diy:when review=off -->
-Code review is DISABLED in this flow. Say so in the run summary line ("review
-skipped by flow config") — never imply the work was reviewed.
-<!-- /diy:when -->
-<!-- diy:when review=on -->
-Dispatch the reviewer exactly as the full lane does — follow the review half
-of `.claude/skills/orc/subskills/orc-review-verify/SKILL.md` (reviewer agent
-`orc-reviewer-opus-5-med`; findings ride the severity ladder from the
-locked rules, blocking and advisory findings both surfaced).
-<!-- /diy:when -->
-<!-- diy:when review=blocking-only -->
-Dispatch the reviewer exactly as the full lane does — follow the review half
-of `.claude/skills/orc/subskills/orc-review-verify/SKILL.md` — but only
-P0/P1 findings gate anything; P2/P3 findings are listed once in the summary
-and never re-offered as fix-up tasks.
-<!-- /diy:when -->
-
-<!-- /orc:layer -->
+# Phase — Review   (id: `review`)
+
+> **Shared phase file.** Moved out of `orc/SKILL.md` at v1.0.0 W12, and into
+> this library at W13 when `orc-diy` became its second reader. A spine is loaded
+> IN FULL when its skill activates; this is loaded when the phase fires, and most
+> runs skip most phases.
+>
+> **Two layers, and a lane reads exactly one.** `full` is `/orc`'s procedure.
+> `composed` is what `orc diy compile` stitches — the same phase expressed as
+> `<!-- diy:when -->` variants over a composed flow, NOT a second copy of the
+> procedure. Reading the wrong one is the failure `README.md` names: a lane
+> doing a phase its product promise says it does differently.
+> `orc lane phases <lane> --json` names the layer for each lane.
+
+<!-- orc:layer full -->
+
+## Review (load ../../orc/subskills/orc-review-verify/, spawned)
+
+Emit `PHASE review start`. Superpowers path: its review skill incl. tests
+(Sonnet 4.6 medium). OpenSpec/self path: review worker (Opus 5 medium). Pass the resolved
+`code_pattern` + its invariants + gate lines for the re-check
+(pattern-gate.md); no resolved pattern → FIRST ask for one (paste/md/none).
+FE tasks in run → pass `fe_rules[]` from `../../orc-pattern/references/` fe-a11y
++ fe-perf. **Code graph (`../code-graph.md` §7):** with the graph on, also pass
+`orc graph changes --if-enabled --json` — the symbols THIS diff's hunks overlap,
+each with its callers, its tests and a risk word that carries its own reason. It
+replaces a whole-file `orc graph impact` here: a file card reports every symbol in
+a touched file, and a symbol nobody edited is not a finding. An unchanged caller of
+a changed signature is a finding candidate, anchored like any other. Findings arrive on the **P0–P3 ladder** (invariant violation or
+unmet gate line = P0; every P0–P2 carries `file:line` + VERBATIM `quote`;
+unanchored → P3). Apply hard rule 5 INCLUDING the quote spot-check: P0 →
+auto-fix once · P1 → ask, then fix once · P2/P3 → record for Phase 7. Emit
+`FINDING p0=<n> p1=<n> p2=<n> p3=<n>` on the return, then `PHASE review end`.
+
+<!-- /orc:layer -->
+
+<!-- orc:layer composed -->
+
+## Phase: Review
+
+<!-- diy:when review=off -->
+Code review is DISABLED in this flow. Say so in the run summary line ("review
+skipped by flow config") — never imply the work was reviewed.
+<!-- /diy:when -->
+<!-- diy:when review=on -->
+Dispatch the reviewer exactly as the full lane does — follow the review half
+of `.claude/skills/orc/subskills/orc-review-verify/SKILL.md` (reviewer agent
+`orc-reviewer-opus-5-med`; findings ride the severity ladder from the
+locked rules, blocking and advisory findings both surfaced).
+<!-- /diy:when -->
+<!-- diy:when review=blocking-only -->
+Dispatch the reviewer exactly as the full lane does — follow the review half
+of `.claude/skills/orc/subskills/orc-review-verify/SKILL.md` — but only
+P0/P1 findings gate anything; P2/P3 findings are listed once in the summary
+and never re-offered as fix-up tasks.
+<!-- /diy:when -->
+<!-- diy:when code_graph=on -->
+With the code graph on, the reviewer also gets the callers from
+`orc graph changes --if-enabled --json` — an unchanged caller of a
+changed signature is a finding candidate (`.claude/skills/_shared/code-graph.md` §7).
+<!-- /diy:when -->
+
+<!-- /orc:layer -->

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

@@ -1,88 +1,96 @@
-# Phase — Ship   (id: `ship`)
-
-> **Shared phase file.** Moved out of `orc/SKILL.md` at v1.0.0 W12, and into
-> this library at W13 when `orc-diy` became its second reader. A spine is loaded
-> IN FULL when its skill activates; this is loaded when the phase fires, and most
-> runs skip most phases.
->
-> **Two layers, and a lane reads exactly one.** `full` is `/orc`'s procedure.
-> `composed` is what `orc diy compile` stitches — the same phase expressed as
-> `<!-- diy:when -->` variants over a composed flow, NOT a second copy of the
-> procedure. Reading the wrong one is the failure `README.md` names: a lane
-> doing a phase its product promise says it does differently.
-> `orc lane phases <lane> --json` names the layer for each lane.
-
-<!-- orc:layer full -->
-
-## Ship (load ../../orc/subskills/orc-pr/SKILL.md)
-
-Emit `PHASE ship start`. Show current branch.
-
-**Stacked-PR gate FIRST (deterministic; full `/orc` + `/orc-ultra` only — load
-`../../orc/subskills/orc-pr/stack-gate.md`; never mini/fast/diy).** Measure the change
-(`git diff --numstat`, exclusions applied) vs config `stacked_pr_loc`/
-`stacked_pr_files`. Under threshold or `stacked_pr: off` → silent, ship normally
-(`GATE stack-gate pass :: under-threshold`). Tripped → surface report + ONE P0
-question (stack into layers? or one regular PR?) in the SAME round as its two
-prerequisites — **a ticket** and a resolved PR template
-(`_shared/pr-templates.md`; none found → recommend three options). No ticket, no
-template, or "no" → **one regular PR, never re-asked**. "Yes" → commit on the
-current branch (the driver's snapshot), write `stacked-pr/<slug>/STACK-FROM.md`
-(`_shared/stack-plan.md`, `ENTRY-MODE: orc-run`, this run's `RUN-DIR`), then hand
-off **`/orc-pr-setup`** → **`/orc-pr-driver`**. ORC never cuts layers itself.
-
-**Handoff seam (one sentence, only when it applies):** if any changed file is a
-GREEN surface in `orc handoff surfaces --json`, say so —
-*"2 of these were changes a PM could have made alone — `/orc-handoff` next time."*
-That sentence is how anyone finds out that lane exists.
-
-Then ask together: **commit? push? create PR?** (PR: ticket +
-title + target branch; generate from `../../orc/subskills/orc-pr/pr.md`). If Phase 6.5 ran,
-commit `test-generator/<change-slug>/` too (a user deliverable, never gitignored).
-**`mock-examples/` is NEVER staged** (drift-recovery.md; no `.gitignore` edit —
-just never `git add` it).
-On success: delete the ephemeral decision log; KEEP checkpoint + dispatch log.
-**Wiki stale-flag:** flag (never re-scan) wiki docs whose covered files this
-run changed; point at `/orc-wiki`. **Post-ship refresh ask** (BIG runs, /orc +
-/orc-ultra — the `wiki_refresh_ask_tasks`/`_files` triggers and full rules in
-`../../orc-wiki/references/staleness.md`): upgrade the passive note to **"Refresh
-wiki now?"**; on "later" print the prominent stale warning and stamp
-`wiki_refresh_declined` in the checkpoint. Then ALWAYS show the completion
-usage report — /usage limits + the full dispatch log (model/effort/score per
-subagent). The user must always know what the run cost. 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
-file existing is what marks a run unfinished — stop-resume.md).
-
-<!-- /orc:layer -->
-
-<!-- orc:layer composed -->
-
-## Phase: Ship
-
-State the current branch and the change summary BEFORE any git action, and
-never ship on a red build (locked rule).
-
-<!-- diy:when ship_mode=ask -->
-Ask the user how to ship: commit, PR (via
-`.claude/skills/orc/subskills/orc-pr/SKILL.md`), or leave the working tree
-as-is. Default when auto-accepted by autonomy: leave as-is and report.
-<!-- /diy:when -->
-<!-- diy:when ship_mode=commit -->
-Commit the run's changes on a green gate without asking (branch first if on
-the default branch; conventional message from the intent). PRs only if the
-user asks afterwards.
-<!-- /diy:when -->
-<!-- diy:when ship_mode=pr -->
-On a green gate, create the PR without asking via
-`.claude/skills/orc/subskills/orc-pr/SKILL.md` (branch + commit + push + PR
-body from the run artifacts).
-<!-- /diy:when -->
-<!-- diy:when ship_mode=report-only -->
-NEVER commit or push in this flow. Leave the working tree modified, and end
-with the change report + suggested commit message the user can apply
-themselves.
-<!-- /diy:when -->
-
-<!-- /orc:layer -->
+# Phase — Ship   (id: `ship`)
+
+> **Shared phase file.** Moved out of `orc/SKILL.md` at v1.0.0 W12, and into
+> this library at W13 when `orc-diy` became its second reader. A spine is loaded
+> IN FULL when its skill activates; this is loaded when the phase fires, and most
+> runs skip most phases.
+>
+> **Two layers, and a lane reads exactly one.** `full` is `/orc`'s procedure.
+> `composed` is what `orc diy compile` stitches — the same phase expressed as
+> `<!-- diy:when -->` variants over a composed flow, NOT a second copy of the
+> procedure. Reading the wrong one is the failure `README.md` names: a lane
+> doing a phase its product promise says it does differently.
+> `orc lane phases <lane> --json` names the layer for each lane.
+
+<!-- orc:layer full -->
+
+## Ship (load ../../orc/subskills/orc-pr/SKILL.md)
+
+Emit `PHASE ship start`. Show current branch.
+
+**Stacked-PR gate FIRST (deterministic; full `/orc` + `/orc-ultra` only — load
+`../../orc/subskills/orc-pr/stack-gate.md`; never mini/fast/diy).** Measure the change
+(`git diff --numstat`, exclusions applied) vs config `stacked_pr_loc`/
+`stacked_pr_files`. Under threshold or `stacked_pr: off` → silent, ship normally
+(`GATE stack-gate pass :: under-threshold`). Tripped → surface report + ONE P0
+question (stack into layers? or one regular PR?) in the SAME round as its two
+prerequisites — **a ticket** and a resolved PR template
+(`_shared/pr-templates.md`; none found → recommend three options). No ticket, no
+template, or "no" → **one regular PR, never re-asked**. "Yes" → commit on the
+current branch (the driver's snapshot), write `stacked-pr/<slug>/STACK-FROM.md`
+(`_shared/stack-plan.md`, `ENTRY-MODE: orc-run`, this run's `RUN-DIR`), then hand
+off **`/orc-pr-setup`** → **`/orc-pr-driver`**. ORC never cuts layers itself.
+
+**Handoff seam (one sentence, only when it applies):** if any changed file is a
+GREEN surface in `orc handoff surfaces --json`, say so —
+*"2 of these were changes a PM could have made alone — `/orc-handoff` next time."*
+That sentence is how anyone finds out that lane exists.
+
+Then ask together: **commit? push? create PR?** (PR: ticket +
+title + target branch; generate from `../../orc/subskills/orc-pr/pr.md`). If Phase 6.5 ran,
+commit `test-generator/<change-slug>/` too (a user deliverable, never gitignored).
+**`mock-examples/` is NEVER staged** (drift-recovery.md; no `.gitignore` edit —
+just never `git add` it).
+On success: delete the ephemeral decision log; KEEP checkpoint + dispatch log.
+**Wiki stale-flag:** flag (never re-scan) wiki docs whose covered files this
+run changed; point at `/orc-wiki`. **Post-ship refresh ask** (BIG runs, /orc +
+/orc-ultra — the `wiki_refresh_ask_tasks`/`_files` triggers and full rules in
+`../../orc-wiki/references/staleness.md`): upgrade the passive note to **"Refresh
+wiki now?"**; on "later" print the prominent stale warning and stamp
+`wiki_refresh_declined` in the checkpoint. Then ALWAYS show the completion
+usage report — /usage limits + the full dispatch log (model/effort/score per
+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
+`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
+file existing is what marks a run unfinished — stop-resume.md).
+
+<!-- /orc:layer -->
+
+<!-- orc:layer composed -->
+
+## Phase: Ship
+
+State the current branch and the change summary BEFORE any git action, and
+never ship on a red build (locked rule).
+
+<!-- diy:when code_graph=on -->
+Before the ship action, run `orc graph update --if-enabled` once more — fix rounds
+move code (`.claude/skills/_shared/code-graph.md` §5).
+<!-- /diy:when -->
+<!-- diy:when ship_mode=ask -->
+Ask the user how to ship: commit, PR (via
+`.claude/skills/orc/subskills/orc-pr/SKILL.md`), or leave the working tree
+as-is. Default when auto-accepted by autonomy: leave as-is and report.
+<!-- /diy:when -->
+<!-- diy:when ship_mode=commit -->
+Commit the run's changes on a green gate without asking (branch first if on
+the default branch; conventional message from the intent). PRs only if the
+user asks afterwards.
+<!-- /diy:when -->
+<!-- diy:when ship_mode=pr -->
+On a green gate, create the PR without asking via
+`.claude/skills/orc/subskills/orc-pr/SKILL.md` (branch + commit + push + PR
+body from the run artifacts).
+<!-- /diy:when -->
+<!-- diy:when ship_mode=report-only -->
+NEVER commit or push in this flow. Leave the working tree modified, and end
+with the change report + suggested commit message the user can apply
+themselves.
+<!-- /diy:when -->
+
+<!-- /orc:layer -->

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

@@ -231,6 +231,12 @@ supplies the fact in a packet, the writer writes the line. `SPAWN`, `RETURN` and
 | `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-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-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 |
 | `DISPATCH <agent> :: <task> expect=<model>/<effort>` | orc → writer | orchestrator dispatched a named agent (the claim). **A FOREIGN dispatch appends `via=extra:<profile>`** and its `expect=` names the profile's model rather than a Claude tier — additive, the way `/orc-doc`'s `sections=` was. A foreign worker is not a Claude subagent, so the hook emits NO `SPAWN` and NO `RETURN` for it (P7, the `/orc-quick` ad-hoc-recon precedent): this line and `EXTRA` are the whole record, which is why neither is optional. **The `/orc-doc` lane's tail NAMES ITS SECTIONS** (v0.49.2) — `doc write sections=03-scope,04-risks part=sections/03-scope.md`, `doc check sections=03-goals`, `doc digest source=<path>` — which is the only thing that makes `orc doc cost`'s per-section attribution honest rather than a guess. It is additive: the tail was already captured whole |