@azure-id/orc 2.1.1 → 2.2.0

package/templates/skills/orc-doc/references/resume-protocol.md

@@ -1,228 +1,229 @@
-# Resuming — the contract that makes a document survive a session
-
-> **The context is gathered once and frozen.** A resumed session reads
-> `context.md` from disk; it never re-interviews the user for what session 1
-> already settled. **a lane that re-asks a frozen question** has broken this
-> contract.
-
-## Entry
-
-```
-/orc-doc resume                      → lists every document with its status line
-/orc-doc resume prd-checkout-refund  → prefix match; an ambiguous prefix lists candidates
-```
-
-`orc doc list --json` supplies the list. It may only claim what the disk proves:
-`document.md` missing means **"not started"**, never "failed".
-
-## The resumed session's first four moves
-
-1. `orc doc status <slug> --json` (0 nothing to do · 1 something to do · 2
-   unknown slug) and **`orc doc parts <slug> --json`** — which works BEFORE a
-   single compile has ever run, because the section files ARE the progress.
-2. **Read `context.md` and `outline.md`. NOT the document.**
-3. **Detect the user's own edits.** Sections whose live hash ≠ the hash
-   `doc.json` recorded are `user-edited`. Say so, **by section name**. A part
-   with no recorded hash at all is `unconfirmed` — a wave killed mid-flight —
-   and it is re-written, never shipped.
-4. **HARD STOP and ask what should change.**
-
-```
-Picking up: PRD — checkout refunds (started 13-08-2026, cycle 2).
-I have read the context you gave me — you do not need to repeat it.
-
-  Sections:  17 planned · 14 written · wave 5 of 7
-  You edited since last time: §02 Summary, §08 Requirements   ← I will not touch these unless you say so
-  Not written yet: §12 Risks · §13 Rollout
-  document.md is 2 sections behind sections/ — rebuilding it is free.
-
-What should change?  (a section to rewrite, something to add, a finding to fix,
-or "finish the rest")
-```
-
-**No change request → no work.** The lane stops there. Regenerating a document
-nobody asked to change is the most expensive possible way to do nothing.
-
-## `RESUME.md` — the P0 hand-back
-
-Written by **the lane itself, never by a dispatched agent** — a dispatch inside
-a stop sequence lets a stop fail because a subagent did.
-
-**v0.49.5 — the CLI writes it, and it is never behind.** `orc doc resume-file
-<slug>` composes the whole page from `doc.json`, and `doc.json` refreshes it on
-**every** write, so it exists from `orc doc init` onward. This replaces a rule
-the orchestrator had to remember at every stop, which is the bet this repo has
-already lost twice (the v0.32.0 narration lesson): a hand-back you are TOLD to
-write at every stop is the hand-back that goes missing on the one run that
-mattered — the one a usage limit killed.
-
-**Rule 16 — `every question points at RESUME.md`.** Before ORC asks the user
-anything, it runs `orc doc resume-file <slug>` and ends the message with that
-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 page is written for someone who does not read code: what this document is,
-where the files are, what is not written yet, what happens next, and the one
-line to paste. Nothing in it needs interpreting.
-
-**It lives at `{run_dir}/{slug}/RESUME.md`** — the registered v0.42.0 home, and
-the ONLY place `listRuns()` looks. It is not in the document folder, and there is
-no second copy there: two copies is two ideas, and they drift. Anyone browsing
-the folder gets the same line from `orc doc status`.
-
-```markdown
-# Resume this document
-
-Paste this line into a new Claude Code session, in this project:
-
-    /orc-doc resume prd-checkout-refund-130826
-
-Where it stands:  /orc-doc · PRD · cycle 2 · 14 of 17 sections written · phase D6 · wave 5 of 7
-
-- Sections:   orc/orc-doc/prd-checkout-refund-130826/sections/   ← the source of truth
-- Document:   document.md is a BUILD ARTIFACT — `orc doc compile` rebuilds it, free
-- Context:    context.md  (the new session reads this first — you do not repeat yourself)
-- Not written yet: §12 Risks · §13 Rollout
-
-## What the new session will do
-1. Read context.md and doc.json. It will NOT re-ask what you already answered.
-2. Start at wave 6, and re-read NOTHING it already wrote.
-3. Ask you what should change. **It will not touch the document until you say.**
-```
-
-**The `Where it stands:` line is at COLUMN 0.** Never `## Where it stands:` —
-`parseStands` is line-anchored, so a heading prefix means it never matches, and
-that single line is what `orc doc list`, `orc resume` and `orc run list` all
-parse. There is a test that feeds this exact template to the real parser.
-
-**One generator, not two.** The whole file comes from `orc doc resume-file`,
-which builds the `Where it stands:` line with the same function `orc doc status`
-uses. Never assemble your own copy of either. The CLI computes, the skill points
-at the result, and the two can then never disagree.
-
-## The wave hand-back (P0, every wave)
-
-```
-Wave 2 of 7 done — 6 of 17 sections written.
-
-  orc/orc-doc/acme-prd-170826/sections/04-detailed-design/01-data-model.md    142 L
-  orc/orc-doc/acme-prd-170826/sections/04-detailed-design/02-api-surface.md   118 L
-  orc/orc-doc/acme-prd-170826/sections/05-rollout.md                           96 L
-
-Read them now if you want to redirect — nothing later is bought yet.
-See it as one file (free):   orc doc compile acme-prd-170826 --partial
-
-To carry on — new session, or after your usage limit resets:
-
-    /orc-doc resume acme-prd-170826
-
-Everything needed is on disk. The next session starts at wave 3 and re-reads
-nothing it already wrote.
-
-The full picture, in plain words:
-    .claude/orc/run/acme-prd-170826/RESUME.md
-```
-
-**Every message that asks the user something ends with those last two lines**
-(rule 16) — a gate, a wave stop, a revision round, an offer. The path is what
-`orc doc resume-file` just printed; never type one from memory.
-
-## The hand-back mention (P0, every cycle)
-
-After **every** cycle that touched the document — the first run and every
-resume — this is the last thing on screen, always in this shape:
-
-```
-Saved to  orc/orc-doc/prd-checkout-refund-130826/sections/   (the source of truth)
-          orc/orc-doc/prd-checkout-refund-130826/document.md (rebuilt, free)
-
-Editing it yourself is expected — go ahead. When you want to carry on, even in a
-brand-new chat, paste this line:
-
-    /orc-doc resume prd-checkout-refund-130826
-
-The full picture is in that folder's RESUME.md — it remembers the context, the
-audience and what is still open, so you never have to explain it twice.
-```
-
-Then the two things this lane offers but never does:
-
-```
-Not staged, not committed. If your team should see it:
-    git add orc/orc-doc/prd-checkout-refund-130826/
-
-Want it graded before you send it? In a NEW session:
-    /orc-challenge orc/orc-doc/prd-checkout-refund-130826/document.md
-```
-
-`/orc-challenge` is offered and never run from here. It is the same separation
-its own contract already enforces from the other side: a session that wrote the
-thing cannot honestly grade it.
-
-## The user's edits are sacred
-
-A `user-edited` section is **never** rewritten without an explicit instruction
-naming it. If a finding lands inside one, the finding is *reported* and the fix
-is *offered*, never applied. Overwriting a human's paragraph is unrecoverable
-from this lane's side — the part file is gone, and their wording with it.
-
-## `changelog.md`
-
-One entry per cycle, appended, newest last. It is the answer to "what did the
-last session actually do", and it is written by the lane, not derived:
-
-```markdown
-## Cycle 2 — 14-08-2026
-- You asked: tighten §04 Goals and add the fraud limit to §12.
-- Changed: sections/04-goals-and-metrics.md (rewritten, 22 → 18 lines), sections/12-risks.md (one row added).
-- Untouched: §02 and §08 — you edited those yourself.
-- Not written yet: §13 Rollout.
-```
-
-An Open question or an Assumption does NOT go here and does not go into the
-document. It goes into the journal as a gap —
-`orc doc log <slug> --kind gap --sections <id> --text "…"` — and the CLI derives
-`gaps.md` from that. The deliverable carries content only.
-
----
-
-## The journal — what you asked for, in order (v0.48.1)
-
-`changelog.md` above is **lane-written prose**. The journal is the **derived**
-companion, and the two are not the same thing: one is a narrative someone wrote,
-the other is a merge of four sources with the provenance of every row attached.
-
-```
-orc doc log     <slug> --kind request|decision|gate|note|gap --text "…" [--sections a,b] [--source user|/orc-grill|/orc-brainstorm]
-orc doc journal <slug> [--json]
-```
-
-| `origin` | source | what it is |
-|---|---|---|
-| `recorded` | `journal[]` | the user's own words, **verbatim** |
-| `derived` | `cycles[]` | a write / check / edit / compile cycle — a machine fact |
-| `derived` | the ship / unship records | a machine fact |
-| `observed` | a section that turned `user-edited` | a machine fact, no text |
-
-**It never invents an entry.** A cycle that ran with nothing logged renders as
-an explicit gap — *"cycle 2 ran · no request was recorded for it"* — and **never**
-a plausible reconstruction from file mtimes. **a lane that invents a journal entry**
-has broken this contract. Same honesty rule as `/orc-pact`'s
-**UNCHECKABLE**: not knowing is an answer, and faking it teaches people to
-distrust the rows that are real.
-
-**Call `orc doc log` at D1 with the user's words verbatim.** A resumed session
-reads the journal to answer *"what have I been asking for?"*, and a paraphrase
-there is the same failure as a paraphrase in `context.md` — it is where a
-resumed session quietly starts writing a different document.
-
-## Resuming is a loop now, not a memory
-
-The resumed session's moves are unchanged — `orc doc status`, `orc doc parts`,
-read `context.md` and `outline.md` (**not the document**), name what the user
-edited, then HARD STOP and ask. After that, **`orc doc next <slug> --json` says
-what happens next** and this lane does exactly that, until it exits 1.
-
-Nothing about the pipeline is remembered across the gap any more. That is the
-point: a session resumed months later in a fresh context has the same
-information as the one that started it.
+# Resuming — the contract that makes a document survive a session
+
+> **The context is gathered once and frozen.** A resumed session reads
+> `context.md` from disk; it never re-interviews the user for what session 1
+> already settled. **a lane that re-asks a frozen question** has broken this
+> contract.
+
+## Entry
+
+```
+/orc-doc resume                      → lists every document with its status line
+/orc-doc resume prd-checkout-refund  → prefix match; an ambiguous prefix lists candidates
+```
+
+`orc doc list --json` supplies the list. It may only claim what the disk proves:
+`document.md` missing means **"not started"**, never "failed".
+
+## The resumed session's first four moves
+
+1. `orc doc status <slug> --json` (0 nothing to do · 1 something to do · 2
+   unknown slug) and **`orc doc parts <slug> --json`** — which works BEFORE a
+   single compile has ever run, because the section files ARE the progress.
+2. **Read `context.md` and `outline.md`. NOT the document.**
+3. **Detect the user's own edits.** Sections whose live hash ≠ the hash
+   `doc.json` recorded are `user-edited`. Say so, **by section name**. A part
+   with no recorded hash at all is `unconfirmed` — a wave killed mid-flight —
+   and it is re-written, never shipped.
+4. **HARD STOP and ask what should change.**
+
+```
+Picking up: PRD — checkout refunds (started 13-08-2026, cycle 2).
+I have read the context you gave me — you do not need to repeat it.
+
+  Sections:  17 planned · 14 written · wave 5 of 7
+  You edited since last time: §02 Summary, §08 Requirements   ← I will not touch these unless you say so
+  Not written yet: §12 Risks · §13 Rollout
+  document.md is 2 sections behind sections/ — rebuilding it is free.
+
+What should change?  (a section to rewrite, something to add, a finding to fix,
+or "finish the rest")
+```
+
+**No change request → no work.** The lane stops there. Regenerating a document
+nobody asked to change is the most expensive possible way to do nothing.
+
+## `RESUME.md` — the P0 hand-back
+
+Written by **the lane itself, never by a dispatched agent** — a dispatch inside
+a stop sequence lets a stop fail because a subagent did.
+
+**v0.49.5 — the CLI writes it, and it is never behind.** `orc doc resume-file
+<slug>` composes the whole page from `doc.json`, and `doc.json` refreshes it on
+**every** write, so it exists from `orc doc init` onward. This replaces a rule
+the orchestrator had to remember at every stop, which is the bet this repo has
+already lost twice (the v0.32.0 narration lesson): a hand-back you are TOLD to
+write at every stop is the hand-back that goes missing on the one run that
+mattered — the one a usage limit killed.
+
+**Rule 16 — `every question points at RESUME.md`.** Before ORC asks the user
+anything, it runs `orc doc resume-file <slug>` and ends the message with that
+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 page is written for someone who does not read code: what this document is,
+where the files are, what is not written yet, what happens next, and the one
+line to paste. Nothing in it needs interpreting.
+
+**It lives at `{run_dir}/{slug}/RESUME.md`** — the registered v0.42.0 home, and
+the ONLY place `listRuns()` looks. It is not in the document folder, and there is
+no second copy there: two copies is two ideas, and they drift. Anyone browsing
+the folder gets the same line from `orc doc status`.
+
+```markdown
+# Resume this document
+
+Paste this line into a new Claude Code session, in this project:
+
+    /orc-doc resume prd-checkout-refund-130826
+
+Where it stands:  /orc-doc · PRD · cycle 2 · 14 of 17 sections written · phase D6 · wave 5 of 7
+
+- Sections:   orc/orc-doc/prd-checkout-refund-130826/sections/   ← the source of truth
+- Document:   document.md is a BUILD ARTIFACT — `orc doc compile` rebuilds it, free
+- Context:    context.md  (the new session reads this first — you do not repeat yourself)
+- Not written yet: §12 Risks · §13 Rollout
+
+## What the new session will do
+1. Read context.md and doc.json. It will NOT re-ask what you already answered.
+2. Start at wave 6, and re-read NOTHING it already wrote.
+3. Ask you what should change. **It will not touch the document until you say.**
+```
+
+**The `Where it stands:` line is at COLUMN 0.** Never `## Where it stands:` —
+`parseStands` is line-anchored, so a heading prefix means it never matches, and
+that single line is what `orc doc list`, `orc resume` and `orc run list` all
+parse. There is a test that feeds this exact template to the real parser.
+
+**One generator, not two.** The whole file comes from `orc doc resume-file`,
+which builds the `Where it stands:` line with the same function `orc doc status`
+uses. Never assemble your own copy of either. The CLI computes, the skill points
+at the result, and the two can then never disagree.
+
+## The wave hand-back (P0, every wave)
+
+```
+Wave 2 of 7 done — 6 of 17 sections written.
+
+  orc/orc-doc/acme-prd-170826/sections/04-detailed-design/01-data-model.md    142 L
+  orc/orc-doc/acme-prd-170826/sections/04-detailed-design/02-api-surface.md   118 L
+  orc/orc-doc/acme-prd-170826/sections/05-rollout.md                           96 L
+
+Read them now if you want to redirect — nothing later is bought yet.
+See it as one file (free):   orc doc compile acme-prd-170826 --partial
+
+To carry on — new session, or after your usage limit resets:
+
+    /orc-doc resume acme-prd-170826
+
+Everything needed is on disk. The next session starts at wave 3 and re-reads
+nothing it already wrote.
+
+The full picture, in plain words:
+    .claude/orc/run/acme-prd-170826/RESUME.md
+```
+
+**Every message that asks the user something ends with those last two lines**
+(rule 16) — a gate, a wave stop, a revision round, an offer. The path is what
+`orc doc resume-file` just printed; never type one from memory.
+
+## The hand-back mention (P0, every cycle)
+
+After **every** cycle that touched the document — the first run and every
+resume — this is the last thing on screen, always in this shape:
+
+```
+Saved to  orc/orc-doc/prd-checkout-refund-130826/sections/   (the source of truth)
+          orc/orc-doc/prd-checkout-refund-130826/document.md (rebuilt, free)
+
+Editing it yourself is expected — go ahead. When you want to carry on, even in a
+brand-new chat, paste this line:
+
+    /orc-doc resume prd-checkout-refund-130826
+
+The full picture is in that folder's RESUME.md — it remembers the context, the
+audience and what is still open, so you never have to explain it twice.
+```
+
+Then the two things this lane offers but never does:
+
+```
+Not staged, not committed. If your team should see it:
+    git add orc/orc-doc/prd-checkout-refund-130826/
+
+Want it graded before you send it? In a NEW session:
+    /orc-challenge orc/orc-doc/prd-checkout-refund-130826/document.md
+```
+
+`/orc-challenge` is offered and never run from here. It is the same separation
+its own contract already enforces from the other side: a session that wrote the
+thing cannot honestly grade it.
+
+## The user's edits are sacred
+
+A `user-edited` section is **never** rewritten without an explicit instruction
+naming it. If a finding lands inside one, the finding is *reported* and the fix
+is *offered*, never applied. Overwriting a human's paragraph is unrecoverable
+from this lane's side — the part file is gone, and their wording with it.
+
+## `changelog.md`
+
+One entry per cycle, appended, newest last. It is the answer to "what did the
+last session actually do", and it is written by the lane, not derived:
+
+```markdown
+## Cycle 2 — 14-08-2026
+- You asked: tighten §04 Goals and add the fraud limit to §12.
+- Changed: sections/04-goals-and-metrics.md (rewritten, 22 → 18 lines), sections/12-risks.md (one row added).
+- Untouched: §02 and §08 — you edited those yourself.
+- Not written yet: §13 Rollout.
+```
+
+An Open question or an Assumption does NOT go here and does not go into the
+document. It goes into the journal as a gap —
+`orc doc log <slug> --kind gap --sections <id> --text "…"` — and the CLI derives
+`gaps.md` from that. The deliverable carries content only.
+
+---
+
+## The journal — what you asked for, in order (v0.48.1)
+
+`changelog.md` above is **lane-written prose**. The journal is the **derived**
+companion, and the two are not the same thing: one is a narrative someone wrote,
+the other is a merge of four sources with the provenance of every row attached.
+
+```
+orc doc log     <slug> --kind request|decision|gate|note|gap --text "…" [--sections a,b] [--source user|/orc-grill|/orc-brainstorm]
+orc doc journal <slug> [--json]
+```
+
+| `origin` | source | what it is |
+|---|---|---|
+| `recorded` | `journal[]` | the user's own words, **verbatim** |
+| `derived` | `cycles[]` | a write / check / edit / compile cycle — a machine fact |
+| `derived` | the ship / unship records | a machine fact |
+| `observed` | a section that turned `user-edited` | a machine fact, no text |
+
+**It never invents an entry.** A cycle that ran with nothing logged renders as
+an explicit gap — *"cycle 2 ran · no request was recorded for it"* — and **never**
+a plausible reconstruction from file mtimes. **a lane that invents a journal entry**
+has broken this contract. Same honesty rule as `/orc-pact`'s
+**UNCHECKABLE**: not knowing is an answer, and faking it teaches people to
+distrust the rows that are real.
+
+**Call `orc doc log` right after `orc doc init` (D5) with the user's D1 words
+verbatim.** The slug does not exist before D5. A resumed session
+reads the journal to answer *"what have I been asking for?"*, and a paraphrase
+there is the same failure as a paraphrase in `context.md` — it is where a
+resumed session quietly starts writing a different document.
+
+## Resuming is a loop now, not a memory
+
+The resumed session's moves are unchanged — `orc doc status`, `orc doc parts`,
+read `context.md` and `outline.md` (**not the document**), name what the user
+edited, then HARD STOP and ask. After that, **`orc doc next <slug> --json` says
+what happens next** and this lane does exactly that, until it exits 1.
+
+Nothing about the pipeline is remembered across the gap any more. That is the
+point: a session resumed months later in a fresh context has the same
+information as the one that started it.

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

@@ -1,88 +1,88 @@
----
-name: orc-explain
-description: >
-  Say it again, so it lands. Use for "/orc-explain", "wait, what?", "I did not
-  follow that", "explain that again". The user has just read something from ORC
-  they did not understand — a preflight block, a scoring line, a gate result, a
-  question. Re-pitch that message: add the background it assumed, use ordinary
-  words, and define every ORC-only term it used. It reports a failure of
-  UNDERSTANDING, not a request for fewer words. Explains only what was just said
-  — it never re-does the work, never dispatches, never writes a file.
----
-
-# ORC-EXPLAIN
-
-The user just read something from ORC and it did not land. That is the whole
-trigger, and it is a specific one.
-
-**"Wait, what?" is not "be shorter".** It reports *my understanding failed* —
-which is answered by supplying what was missing, not by compressing what was
-already there. A summary of a message someone did not understand is the same
-message, shorter.
-
-## What to do
-
-Take the message the user is pointing at (the last ORC output, unless they name
-an earlier one) and give it again:
-
-1. **Say the point first**, in one sentence, in ordinary words.
-2. **Add the background the message assumed.** This is almost always the real
-   gap — the message was accurate and complete for someone who already knew what
-   a wave is.
-3. **Define every ORC-only term it used**, in this project's own terms: band,
-   facet, disposition, P0–P3, freshness tier, wave, slice, gate, packet, lane.
-   Use `wiki/orc-orientation.md` when a wiki exists, so the words match the words
-   the rest of this repo's docs use.
-4. **Say what it means for the user** — what decision, if any, is now theirs.
-
-Then stop, and return to exactly where the run was. Nothing about the run
-changes: no re-plan, no re-score, no undo, no new question.
-
-## Keep this skill short
-
-Its brevity is the design. A long skill that says "be clear" produces a verbose
-model, because the model copies the length it sees. There is nothing else here on
-purpose.
-
-## Rules
-
-- **Explain only.** Never dispatch an agent, never edit or write any file, never
-  change a gate outcome or a phase.
-- **No trace.** This lane owns no run, writes no trace and deletes no pointer —
-  it can fire many times in one session and tracing it would flood `log_dir` for
-  zero signal. The consequence is accepted and stated: `/orc-explain` usage is
-  invisible to `orc stats`, which says so in its own help text.
-- **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.
-
-## Rules — the anti-slop card (`../_shared/phases/rules.md`)
-
-`orc rules slice --lane orc-explain --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[]`.
-## 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.
-
-## Waiting mid-run (`/orc-wait`)
-
-Canonical: `../_shared/wait.md`. **`a lane that waits without a hand-back` has broken this contract.**
-Checkpoint **none** · safe point **read-only, seconds long**. Nothing here to checkpoint, so all three modes behave identically — say so rather than asking. Never begin a wait between a dispatch and its validated return, or before the smoke gate has reported.
+---
+name: orc-explain
+description: >
+  Say it again, so it lands. Use for "/orc-explain", "wait, what?", "I did not
+  follow that", "explain that again". The user has just read something from ORC
+  they did not understand — a preflight block, a scoring line, a gate result, a
+  question. Re-pitch that message: add the background it assumed, use ordinary
+  words, and define every ORC-only term it used. It reports a failure of
+  UNDERSTANDING, not a request for fewer words. Explains only what was just said
+  — it never re-does the work, never dispatches, never writes a file.
+---
+
+# ORC-EXPLAIN
+
+The user just read something from ORC and it did not land. That is the whole
+trigger, and it is a specific one.
+
+**"Wait, what?" is not "be shorter".** It reports *my understanding failed* —
+which is answered by supplying what was missing, not by compressing what was
+already there. A summary of a message someone did not understand is the same
+message, shorter.
+
+## What to do
+
+Take the message the user is pointing at (the last ORC output, unless they name
+an earlier one) and give it again:
+
+1. **Say the point first**, in one sentence, in ordinary words.
+2. **Add the background the message assumed.** This is almost always the real
+   gap — the message was accurate and complete for someone who already knew what
+   a wave is.
+3. **Define every ORC-only term it used**, in this project's own terms: band,
+   facet, disposition, P0–P3, freshness tier, wave, slice, gate, packet, lane.
+   Use `wiki/orc-orientation.md` when a wiki exists, so the words match the words
+   the rest of this repo's docs use.
+4. **Say what it means for the user** — what decision, if any, is now theirs.
+
+Then stop, and return to exactly where the run was. Nothing about the run
+changes: no re-plan, no re-score, no undo, no new question.
+
+## Keep this skill short
+
+Its brevity is the design. A long skill that says "be clear" produces a verbose
+model, because the model copies the length it sees. There is nothing else here on
+purpose.
+
+## Rules
+
+- **Explain only.** Never dispatch an agent, never edit or write any file, never
+  change a gate outcome or a phase.
+- **No trace.** This lane owns no run, writes no trace and deletes no pointer —
+  it can fire many times in one session and tracing it would flood `log_dir` for
+  zero signal. The consequence is accepted and stated: `/orc-explain` usage is
+  invisible to `orc stats`, which says so in its own help text.
+- **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.
+
+## Rules — the anti-slop card (`../_shared/phases/rules.md`)
+
+`orc rules slice --lane orc-explain --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[]`.
+## Calls
+
+**ONE catalogue, and it is not you:** `orc lane calls orc-explain --json` names every
+SHARED 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 that neither it nor this skill names 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.
+
+## Waiting mid-run (`/orc-wait`)
+
+Canonical: `../_shared/wait.md`. **`a lane that waits without a hand-back` has broken this contract.**
+Checkpoint **none** · safe point **read-only, seconds long**. Nothing here to checkpoint, so all three modes behave identically — say so rather than asking. Never begin a wait between a dispatch and its validated return, or before the smoke gate has reported.