@azure-id/orc 0.56.1 → 1.0.0

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

@@ -1,70 +1,129 @@
----
-name: orc-diy
-description: >
-  User-composable ORC lane. Use for "/orc-diy" or "run my custom orc flow".
-  The pipeline shape (analyze/review/verify/security/testgen on-off, scoring
-  or a fixed executor, autonomy, ship mode, session tier) is configured
-  ENTIRELY through the `orc diy` CLI and compiled into a flow file —
-  never configured in-session. HARD-GATED: no config or a stale compile →
-  this skill never runs the custom flow; it explains the CLI steps and offers
-  plain /orc instead. "/orc-diy compile" re-runs the deterministic CLI
-  compiler. See references/flow-schema.md and references/compile.md.
----
-
-# ORC-DIY (stub — gate + dispatcher)
-
-You are the entry gate for the user's compiled custom flow. You NEVER invent,
-modify, or interpret flow configuration in-session — the `orc diy` CLI is the
-only writer, the compiler is the only builder, and this stub only gates and
-dispatches. All state lives in the project's `.claude/` (project-scoped; no
-global variant).
-
-## Step 0 — route `compile`
-
-If the invocation argument is `compile` (from `/orc-diy compile`): run
-`orc diy compile` via Bash and relay its output. If the `orc` CLI is not on
-PATH, tell the user to run `orc diy compile` in their own terminal — do NOT
-reimplement the compiler in-session. Then end the turn. (`status` routes the
-same way to `orc diy status`.)
-
-## Step 1 — the hard gate (every other invocation)
-
-Run `orc diy status` via Bash and branch on the reported state. If the CLI is
-unavailable, apply the same checks manually from
-`.claude/orc-diy.config.yaml` + `.claude/orc/diy/flow.lock.json` per
-`references/flow-schema.md` — and treat ANYTHING you cannot verify as STALE
-(fail closed).
-
-- **UNCONFIGURED** — no config exists. Tell the user, in this order: what
-  orc-diy is (one sentence), the exact bootstrap
-  (`orc diy init` → optionally `orc diy set <key> <value>` →
-  `orc diy compile` — see the skill's README for the full guide), then ask
-  ONE question: *"Run this request through the regular full `/orc` lane
-  instead?"* Yes → invoke the `orc` skill with the user's original request
-  carried over verbatim. No → end the turn. Never proceed on an
-  unconfigured flow, and never write the config yourself.
-- **STALE** — configured but not runnable. Report the specific reason the
-  status gave (config changed since compile / orc was updated / compiled
-  flow modified or missing) and the fix (`orc diy compile`), then the same
-  single `/orc` fallback question as above. Never run a stale flow.
-- **READY** — proceed to Step 2.
-
-## Step 2 — dispatch the compiled flow
-
-Read `.claude/orc/diy/FLOW-COMPILED.md` and follow it as your orchestrator
-spine for this run — it is self-contained: tier self-check, locked rules,
-phase sequence, and the references it cherry-picks from the installed orc
-skill. Honor its generated header: if its own self-gate fails, stop exactly
-as it says. Do not consult this stub again for the rest of the run, and do
-not load orc's SKILL.md as a spine (the compiled flow already references the
-exact orc subskills and schemas it needs).
-
-## Hard rules
-
-1. The compiled flow is a build artifact — NEVER edit
-   `FLOW-COMPILED.md`, `flow.lock.json`, or `orc-diy.config.yaml` yourself,
-   and never "patch" the flow conversationally. Config changes go through
-   `orc diy set` + `orc diy compile`, both run by the user.
-2. Fail closed: any gate ambiguity = STALE, with the reason shown.
-3. The fallback ask is ONE question with two outcomes (`/orc` or stop) —
-   never a menu, never a silent fallback.
+---
+name: orc-diy
+description: >
+  User-composable ORC lane. Use for "/orc-diy" or "run my custom orc flow".
+  The pipeline shape (analyze/review/verify/security/testgen on-off, scoring
+  or a fixed executor, autonomy, ship mode, session tier) is configured
+  ENTIRELY through the `orc diy` CLI and compiled into a flow file —
+  never configured in-session. HARD-GATED: no config or a stale compile →
+  this skill never runs the custom flow; it explains the CLI steps and offers
+  plain /orc instead. "/orc-diy compile" re-runs the deterministic CLI
+  compiler. See references/flow-schema.md and references/compile.md.
+---
+
+# ORC-DIY (stub — gate + dispatcher)
+
+You are the entry gate for the user's compiled custom flow. You NEVER invent,
+modify, or interpret flow configuration in-session — the `orc diy` CLI is the
+only writer, the compiler is the only builder, and this stub only gates and
+dispatches. All state lives in the project's `.claude/` (project-scoped; no
+global variant).
+
+## Step 0 — route `compile`
+
+If the invocation argument is `compile` (from `/orc-diy compile`): run
+`orc diy compile` via Bash and relay its output. If the `orc` CLI is not on
+PATH, tell the user to run `orc diy compile` in their own terminal — do NOT
+reimplement the compiler in-session. Then end the turn. (`status` routes the
+same way to `orc diy status`.)
+
+## Step 1 — the hard gate (every other invocation)
+
+Run `orc diy status` via Bash and branch on the reported state. If the CLI is
+unavailable, apply the same checks manually from
+`.claude/orc-diy.config.yaml` + `.claude/orc/diy/flow.lock.json` per
+`references/flow-schema.md` — and treat ANYTHING you cannot verify as STALE
+(fail closed).
+
+- **UNCONFIGURED** — no config exists. Tell the user, in this order: what
+  orc-diy is (one sentence), the exact bootstrap
+  (`orc diy init` → optionally `orc diy set <key> <value>` →
+  `orc diy compile` — see the skill's README for the full guide), then ask
+  ONE question: *"Run this request through the regular full `/orc` lane
+  instead?"* Yes → invoke the `orc` skill with the user's original request
+  carried over verbatim. No → end the turn. Never proceed on an
+  unconfigured flow, and never write the config yourself.
+- **STALE** — configured but not runnable. Report the specific reason the
+  status gave (config changed since compile / orc was updated / compiled
+  flow modified or missing) and the fix (`orc diy compile`), then the same
+  single `/orc` fallback question as above. Never run a stale flow.
+- **READY** — proceed to Step 2.
+
+## Step 2 — dispatch the compiled flow
+
+Read `.claude/orc/diy/FLOW-COMPILED.md` and follow it as your orchestrator
+spine for this run — it is self-contained: tier self-check, locked rules,
+phase sequence, and the references it cherry-picks from the installed orc
+skill. Honor its generated header: if its own self-gate fails, stop exactly
+as it says. Do not consult this stub again for the rest of the run, and do
+not load orc's SKILL.md as a spine (the compiled flow already references the
+exact orc subskills and schemas it needs).
+
+## Where the compiled flow comes from
+
+You never read these; `orc diy compile` does, once, and stitches the result
+into `FLOW-COMPILED.md`. The table is here so a maintainer can see the
+provenance of a compiled phase without reading the compiler — `orc lane phases
+orc-diy --json` is the authoritative version and marks every row below
+`when: compile-time`.
+
+Eleven phases come from the shared library, as that file's `composed` LAYER —
+NOT its `full` layer, which is `/orc`'s procedure for the same phase:
+`../_shared/phases/trace.md` · `../_shared/phases/planning.md` ·
+`../_shared/phases/scoring.md` · `../_shared/phases/execution.md` ·
+`../_shared/phases/review.md` · `../_shared/phases/security.md` ·
+`../_shared/phases/verify.md` · `../_shared/phases/testgen.md` ·
+`../_shared/phases/mock-example.md` · `../_shared/phases/ship.md` ·
+`../_shared/phases/summary.md`.
+
+Five have no counterpart anywhere else in the payload and stay this lane's own:
+`references/blocks/header.md` (the tier self-gate), `wiki.md`, `analyze.md`,
+`pattern.md` and `extra.md`. They are composition prose about a decision only a
+composed flow makes, so there is nothing to share them WITH.
+
+Four more are pointed at from inside those stitched layers rather than stitched
+themselves: `../_shared/phases/intake.md`,
+`../_shared/phases/wave-grouping.md`,
+`../_shared/phases/security-checklist.md` and
+`../_shared/phases/stop-resume.md`.
+
+The stitch ORDER is the compiler's `order` array and is documented in
+`references/compile.md`; a golden test holds the three lists together.
+
+
+## Config
+
+**ONE resolver, and it is not you:** `orc lane config orc-diy --json`. Obey
+`effective`, print every line in `announce[]` VERBATIM at preflight, and honour
+`stops[]` before wave 1. Never re-derive a value, a precedence or an inertness
+from `.claude/orc.config.yaml` — a key this lane does not read is not in the
+answer, and a key another key shadows comes back already marked. Exit ≠ 0 → say
+the CLI is unavailable and fall back to `../_shared/config-precedence.md`'s
+documented defaults, out loud. Priorities and families:
+`../_shared/config-precedence.md`.
+
+The flow SHAPE is not in that answer: it is compile-owned and lives in
+`flow.lock.json`. The resolver answers for everything else this lane still
+reads, and `extra` is the same split — the flow decides WHETHER, the resolver
+still decides WHERE.
+
+## Calls
+
+**ONE catalogue, and it is not you:** `orc lane calls orc-diy --json` names every
+CLI call this lane makes, each with its exit-code contract, its cost, when to run
+it, and what an EMPTY answer means. Never invent a spelling, never re-word an
+exit code, and never re-derive a state word — the CLI's state words are the only
+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.
+
+## Hard rules
+
+1. The compiled flow is a build artifact — NEVER edit
+   `FLOW-COMPILED.md`, `flow.lock.json`, or `orc-diy.config.yaml` yourself,
+   and never "patch" the flow conversationally. Config changes go through
+   `orc diy set` + `orc diy compile`, both run by the user.
+2. Fail closed: any gate ambiguity = STALE, with the reason shown.
+3. The fallback ask is ONE question with two outcomes (`/orc` or stop) —
+   never a menu, never a silent fallback.

package/templates/skills/orc-diy/references/blocks/analyze.md

@@ -20,5 +20,5 @@ planning. No doc → go straight to planning.
 <!-- diy:when analyze=auto -->
 Route doc intake exactly as the full lane does: a document present triggers
 the System Analyst per the intake rules in
-`.claude/skills/orc/references/intake.md`; otherwise proceed to planning.
+`.claude/skills/_shared/phases/intake.md`; otherwise proceed to planning.
 <!-- /diy:when -->

package/templates/skills/orc-diy/references/compile.md

@@ -10,13 +10,27 @@ second implementation, and the skill never stitches the flow itself.
 
 1. **Validate.** Load `.claude/orc-diy.config.yaml`; run the full cross-key
    validation from `flow-schema.md`. Any hard error aborts the compile.
-2. **Resolve sources.** Block templates come from the installed stub
-   (`.claude/skills/orc-diy/references/blocks/`). Cherry-picked orc material
-   is REFERENCED in place, never copied: the compiler verifies that every
-   orc file a chosen variant points at actually exists under
-   `.claude/skills/` (project first, `~/.claude/skills/` fallback for a
-   global orc install) and aborts naming the missing file if orc is absent
-   or incomplete.
+2. **Resolve sources.** A block comes from ONE of two places, and which one
+   is not the compiler's choice — it is `LANE_PHASES` (`orc lane phases
+   orc-diy --json`).
+
+   - **Eleven come from the shared phase library** as that file's `composed`
+     LAYER: `.claude/skills/_shared/phases/<block>.md`. The `composed` layer
+     is this lane's variant of the phase; the `full` layer in the same file is
+     `/orc`'s procedure and is NEVER stitched here. A file whose `composed`
+     layer is missing aborts the compile naming the file — it must never
+     compile to an empty phase.
+   - **Five stay this lane's own** in the installed stub
+     (`.claude/skills/orc-diy/references/blocks/`): `header`, `wiki`,
+     `analyze`, `pattern`, `extra`. They are composition prose about a
+     decision only a composed flow makes, so there is nothing to share them
+     with.
+
+   Cherry-picked orc material is REFERENCED in place, never copied: the
+   compiler verifies that every orc file a chosen variant points at actually
+   exists under `.claude/skills/` (project first, `~/.claude/skills/`
+   fallback for a global orc install) and aborts naming the missing file if
+   orc is absent or incomplete.
 3. **Stitch.** Concatenate in fixed order — this list and the `order` array in
    `bin/cli.js` are ONE contract; change them together (a golden test compares
    them, because the drift is grammar-shaped and the contract lint cannot see

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

@@ -32,7 +32,7 @@ selector.
 | `summary` | `full` / `off` / `short` | Summary depth |
 | `autonomy` | `interactive` / `semi` / `hands-off` | Who answers routine asks |
 | `ship_mode` | `ask` / `commit` / `pr` / `report-only` | Terminal ship behavior |
-| `session_tier` | `sonnet-4-6-{med,high}` / `opus-4-7-{med,high}` / `opus-4-8-{med,high,xhigh,max}` / `opus-5-{med,high,xhigh,max}` / `fable-5-{med,high,xhigh,max}` | Required main-session model+effort (default `opus-4-8-high`) |
+| `session_tier` | `sonnet-4-6-{med,high}` / `opus-4-7-{med,high}` / `opus-4-8-{med,high,xhigh,max}` / `opus-5-{med,high,xhigh,max}` / `fable-5-{med,high,xhigh,max}` | Required main-session model+effort (default `opus-5-high`) |
 | `max_wave_tasks` | `3` (integer ≥ 1) | Wave hard cap |
 | `batch_pause_every` | `2` (integer ≥ 1) | Waves between pauses |
 | `rubric_bands` | `5` (2–8) | Scoring granularity (`scoring: on` only) |
@@ -67,7 +67,7 @@ Warnings (written, reported):
 ```json
 {
   "flow_name": "my-flow",
-  "session_tier": "opus-4-8-high",
+  "session_tier": "opus-5-high",
   "config_hash": "sha256 of orc-diy.config.yaml",
   "flow_hash": "sha256 of flow.md",
   "compiled_hash": "sha256 of FLOW-COMPILED.md (null until compiled)",

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

@@ -81,12 +81,20 @@ that recomputes one of these has forked it.**
 | **11** | **The orchestrator never runs `orc doc read`.** That command exists for the HUMAN, the same way `orc challenge report` does. Reading a section is still delegated — rule 0 is not softened by a command that happens to print prose. |
 | **12** | **The journal never invents an entry.** `orc doc log` records what the user actually said; `orc doc journal` merges that with machine facts and shows a cycle nobody logged AS A GAP. **a lane that invents a journal entry** has broken this contract. |
 | **13** | **Every wave is a stop.** A wave boundary is not a loop iteration: validate the returns, record the hashes, **run `orc doc resume-file <slug>` (ORC itself, first)**, print the paths, then dispatch the trace packet. A usage-limit kill between waves must leave something on disk that says where it stopped. |
-| **15** | **`house rules are read first`.** Every dispatched slice carries the project's own P0/P1/P2 house rules VERBATIM at the very top, ABOVE ORC's own generation rules. That order is the contract. They are a PLAIN TEXT config (`.claude/orc/doc-house-rules.md`) — three headings, as many lines under each as the project wanted, pasted from `doc_rules_text` and never re-wrapped. House rules govern what the document SAYS and how it READS — they can never change how this lane RUNS, and a rule that asks for a structural break comes back as `unsupported_request`, never a guessed compromise. `references/house-rules.md`. |
+| **15** | **`house rules are read first`.** Every dispatched slice carries the project's own P0/P1/P2 house rules VERBATIM at the very top, ABOVE ORC's own generation rules. That order is the contract. They are a PLAIN TEXT config (`.claude/orc/doc-house-rules.md`) — three headings, as many lines under each as the project wanted, pasted from `doc_rules_text` and never re-wrapped. House rules govern what the document SAYS and how it READS — they can never change how this lane RUNS, and a rule that asks for a structural break comes back as `unsupported_request`, never a guessed compromise. `../_shared/phases/house-rules.md`. |
 | **14** | **The wave hand-back is P0.** After every wave, print every file path written and the one line that resumes it. `orc doc parts` is what proves the progress — the section files ARE the record. |
 | **16** | **`every question points at RESUME.md`.** Before ORC asks the user ANYTHING — a gate, a wave stop, a revision round, an offer — it runs `orc doc resume-file <slug>` and ends the message with the file's path and the line to paste. A user who has to remember where they were is a user who does not come back. The CLI rewrites the file on every state change anyway, so this is a POINTER, never a rebuild the model has to compose. |
 
 ---
 
+## Phases
+
+`orc lane phases orc-doc --json` is this 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 headings below, and never renumber or rename one without the
+manifest, because a `read: section` pointer names a HEADING and a renamed heading
+is a pointer into nothing.
+
 ## D0 — Preflight (ONE time, silent)
 
 1. **Config.** `log_dir`, `doc_dir`, `doc_language`, `doc_max_lines_per_agent`,
@@ -104,6 +112,10 @@ that recomputes one of these has forked it.**
    rules live. Never compute that line yourself.
 5. If a slug was given, go straight to **Resuming** below.
 
+The SHAPE of these steps — the order, and the four rules that make it worth
+having — is `../_shared/phases/preflight.md` (`core`). The probes
+themselves are this lane's own and stay here.
+
 ## D1 — The context gate (P0 — the only blocking one)
 
 `references/gates.md`. One question, and **nothing is created until it is
@@ -399,14 +411,17 @@ is the most expensive possible way to do nothing.
 
 ## Behavior trace (always on)
 
-`../orc/references/trace-protocol.md`. Lane name `doc`. **Iterative tier: ONE
-packet per completed cycle — and a completed WAVE is a completed cycle.** So the
-packet is dispatched at the end of every wave (last in the stop sequence) and at
-D9, not at D9 only: a run that dies at wave 3 must not leave a trace with
-nothing but the hook's `SPAWN`/`RETURN` lines. Verb `DOC` with
-`cycle=N sections=K/M wave=K/N`. A phase that ends with
+`../_shared/phases/trace.md` (`core`, at run start; `orc lane phases` names
+the file and the layers). Lane token `doc`, tier **Iterative** —
+ONE packet per completed cycle — **and a completed WAVE is a completed
+cycle**, so the packet goes out at the end of every wave (last in the stop
+sequence) and at D9, not at D9 only.
+Nothing else about the protocol is restated here; a phase that ends with
 `zero new trace lines is a protocol violation`.
 
+A run that dies at wave 3 must not leave a trace holding nothing but the
+hook's `SPAWN`/`RETURN` lines. Verb `DOC` with `cycle=N sections=K/M wave=K/N`.
+
 ## How this lane fails — and the rule that prevents each
 
 | Failure | Prevention |
@@ -442,3 +457,25 @@ guess a line number · never split a section across agents · one file per secti
 · never overwrite a human's paragraph · never invent a fact · never put ORC's
 bookkeeping in the document · every wave is a stop · never pay for what the lint
 answers free · never stage, never commit.
+
+## Config
+
+**ONE resolver, and it is not you:** `orc lane config orc-doc --json`. Obey
+`effective`, print every line in `announce[]` VERBATIM at preflight, and honour
+`stops[]` before wave 1. Never re-derive a value, a precedence or an inertness
+from `.claude/orc.config.yaml` — a key this lane does not read is not in the
+answer, and a key another key shadows comes back already marked. Exit ≠ 0 → say
+the CLI is unavailable and fall back to `../_shared/config-precedence.md`'s
+documented defaults, out loud. Priorities and families:
+`../_shared/config-precedence.md`.
+
+## Calls
+
+**ONE catalogue, and it is not you:** `orc lane calls orc-doc --json` names every
+CLI call this lane makes, each with its exit-code contract, its cost, when to run
+it, and what an EMPTY answer means. Never invent a spelling, never re-word an
+exit code, and never re-derive a state word — the CLI's state words are the only
+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.

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

@@ -55,3 +55,22 @@ purpose.
 - **User-invoked only.** No lane ever calls this for the user.
 - If the user actually wanted the work redone rather than restated, say so and
   point at the lane that does it — do not quietly become that lane.
+
+## Config
+
+Resolve with `orc lane config orc-explain --json` and obey `effective`. Never merge
+`.claude/orc.config.yaml` yourself, and never re-derive a precedence. Exit ≠ 0 →
+say so and use `../_shared/config-precedence.md`'s documented defaults, out
+loud. Nothing this lane reads is contested, gated or a stop, so it owes no
+preflight line and has no gate to honour.
+
+## Calls
+
+**ONE catalogue, and it is not you:** `orc lane calls orc-explain --json` names every
+CLI call this lane makes, each with its exit-code contract, its cost, when to run
+it, and what an EMPTY answer means. Never invent a spelling, never re-word an
+exit code, and never re-derive a state word — the CLI's state words are the only
+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.

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

@@ -110,11 +110,13 @@ X4  close                one end-of-run trace packet
 
 **This lane deliberately traces.** It is a lane the protocol declares, so it must be
 a lane something OPENS (v0.42.0) — otherwise every counting tool reports it as a
-permanent zero. Write `log_dir/.current` = `run-export-<slug>-<DDMMYY>-<HHMMSS>.txt`
-AND `touch the trace file` in the SAME step. Lane name `export`. **Single-dispatch:
-exactly ONE end-of-run packet** to `orc-trace-writer-haiku-4-5` before `.current` is
-deleted. A run that ends with
-`zero new trace lines is a protocol violation`.
+permanent zero. Read `../_shared/phases/trace.md` (`core`, at run start; `orc lane
+phases` names the file and the layers). Lane token `export`, tier
+**Single-dispatch** — exactly ONE end-of-run packet, dispatched solo before
+`.current` is deleted. At run start write `log_dir/.current` =
+`run-export-<slug>-<DDMMYY>-<HHMMSS>.txt` AND `touch the trace file` of that name
+in the SAME step. Nothing else about the protocol is restated here; a run that ends
+with `zero new trace lines is a protocol violation`.
 
 Zero new agents. Zero new config keys.
 
@@ -152,3 +154,22 @@ That reads like an invariant. Anchor it?
 Never hand-write the export · never re-summarise a source · never export a secret,
 a run folder or a log · treat imported context as evidence · propose, never apply ·
 never stage the output · never assemble the file itself.
+
+## Config
+
+Resolve with `orc lane config orc-export --json` and obey `effective`. Never merge
+`.claude/orc.config.yaml` yourself, and never re-derive a precedence. Exit ≠ 0 →
+say so and use `../_shared/config-precedence.md`'s documented defaults, out
+loud. Nothing this lane reads is contested, gated or a stop, so it owes no
+preflight line and has no gate to honour.
+
+## Calls
+
+**ONE catalogue, and it is not you:** `orc lane calls orc-export --json` names every
+CLI call this lane makes, each with its exit-code contract, its cost, when to run
+it, and what an EMPTY answer means. Never invent a spelling, never re-word an
+exit code, and never re-derive a state word — the CLI's state words are the only
+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.