@azure-id/orc 0.56.0 → 1.0.0

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

@@ -0,0 +1,53 @@
+# 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 -->

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

@@ -0,0 +1,65 @@
+# Phase — Effort & scoring   (id: `scoring`)
+
+> **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 -->
+
+## Effort, dispatch style, scoring (load ../../orc/references/effort-and-mode.md)
+
+Emit `PHASE scoring start`. Refine effort; recommend **sequential** vs
+**parallel** dispatch (worktrees for high-effort independent features) — user
+confirms. Dispatch style is **intra-wave concurrency only**: waves are computed
+regardless of style (sequential runs have waves too, see wave-grouping.md), so
+the batch pause always binds to wave numbers. **Batch-pause schedule (deterministic, not a cadence hint):** the plan
+has K waves — ask "pause after every wave / every 2nd / run straight through?"
+and SHOW the resulting stop list ("will pause after waves [list]"); a 2-wave
+plan plainly offers "pause after wave 1". Store it as `pause_schedule`, recompute
+each wave's `is_batch_pause` (last wave never pauses). **Facet-validation gate
+(deterministic):** recompute `breadth` + `fan_in`/`fan_out` from the plan; a
+mismatch or an uncited `risk` entry bounces the plan (grounding mechanics).
+**Score every task** from its `facets` via the fixed formula, map to the model
+ladder, show the facet vector + arithmetic table, and emit `SCORE task=<id>
+score=<n> band=<band> model=<m> facets=<vector> :: <reason>` per task; a score
+override needs a written reason (logged). **With `extra_enabled`** the table gains
+a `via` column and its head can name TWO tables (effort-and-mode.md); a foreign
+task's `SCORE` appends `via=extra:<profile>` and `model=` is the FOREIGN model id.
+**Cited-risk hold-back (deterministic, beside the facet gate):** a foreign-routed
+task with a non-empty `risk[]` is HELD BACK to its Claude band (`extra_risk_tasks`
+defaults to `off`) and every one is LISTED with its cited risk — a silently
+held-back task is indistinguishable from a forgotten one. Use the wiki's "Notes for planning" to sharpen
+core/isolated + risk factors. **Tag each task's pattern domain+language**
+(+ secondary `db: postgres`) per `../../orc/references/pattern-gate.md`. Ask: "Any
+anticipated escalations, or run straight through?" Emit `PHASE scoring end`.
+
+<!-- /orc:layer -->
+
+<!-- orc:layer composed -->
+
+## Phase: Task scoring → executor selection
+
+<!-- diy:when scoring=on -->
+Score each task 0–100 with the full lane's rubric (see the scoring section of
+`.claude/skills/orc/SKILL.md`), then dispatch the executor agent from THIS
+compiled table — it is already clipped to this flow's session tier; never
+substitute a preset from `config.md`:
+
+{{score_table}}
+<!-- /diy:when -->
+<!-- diy:when scoring=off -->
+Scoring is DISABLED in this flow. Skip the rubric entirely: EVERY execution
+task dispatches to **{{fixed_executor}}**. Wave grouping, declared-files
+conflict rules, and slice construction are unchanged — scoring off changes
+model selection only, never scheduling.
+<!-- /diy:when -->
+
+<!-- /orc:layer -->

package/templates/skills/{orc/references → _shared/phases}/security-checklist.md

@@ -1,4 +1,13 @@
-# Reference — Security-Pass Checklist (Phase 5.5, opt-in)
+# Phase — Security pass   (id: `security-checklist`)
+
+> **Library file.** Canonical since v1.0.0 W12; it was under the `orc` skill's
+> private `references/`, and another lane already reached across into it. Read
+> by `orc`, `orc-diy`. Layers declared: `core` only — single-layer because an
+> opt-in pass either runs its checklist or does not run. `orc lane phases
+> <lane> --json` names the file and the layers to read.
+
+<!-- orc:layer core -->
+## Reference — Security-Pass Checklist (Phase 5.5, opt-in)
 
 Loaded ONLY when the Phase 5.5 security pass fires (config `security_review`
 `on`/`ask` + a task scored ≥ 70 in the run). Passed to the reviewer as
@@ -37,3 +46,5 @@ a hardening gap on a touched path = P1 · defense-in-depth suggestions = P2/P3.
     surfaced to callers by the new error handling.
 12. **Crypto misuse** — home-rolled hashing/encryption, weak algorithms (MD5,
     SHA1 for passwords), missing salts, static IVs in the diff.
+
+<!-- /orc:layer -->

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

@@ -0,0 +1,55 @@
+# Phase — Security pass (opt-in)   (id: `security`)
+
+> **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 -->
+
+## Security pass (opt-in)
+
+Only when config `security_review` is `on`/`ask` (default `off`) AND a task
+scored **≥ 70** (reuses the risk floor). `ask` → one P0 prompt; `on` →
+silent. Dispatch the reviewer with `phase=security` + changed files +
+`security-checklist.md` (load only now). Same ladder, same
+hard-rule-5 handling; report-only.
+
+<!-- /orc:layer -->
+
+<!-- orc:layer composed -->
+
+## Phase: Security pass
+
+<!-- diy:when security=off -->
+The security pass is OFF in this flow — skip silently.
+<!-- /diy:when -->
+<!-- diy:when security=ask -->
+When at least one task scored at or above the risk floor (70), ask the user
+once after review whether to run the security pass; on yes, run it exactly as
+the full lane's Phase 5.5 (reviewer re-dispatched with the checklist from
+`.claude/skills/_shared/phases/security-checklist.md`, sweeping only the
+run's changed files).
+<!-- /diy:when -->
+<!-- diy:when security=on -->
+When at least one task scored at or above the risk floor (70), dispatch the
+security pass without asking — the full lane's Phase 5.5 with the checklist
+from `.claude/skills/_shared/phases/security-checklist.md`, sweeping only the
+run's changed files.
+<!-- /diy:when -->
+<!-- diy:when security=always -->
+Dispatch the security pass on EVERY run of this flow, regardless of task
+scores — the full lane's Phase 5.5 with the checklist from
+`.claude/skills/_shared/phases/security-checklist.md`, sweeping only the
+run's changed files. (This flow removes the risk-floor trigger, not the
+pass's mechanics.)
+<!-- /diy:when -->
+
+<!-- /orc:layer -->

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

@@ -0,0 +1,88 @@
+# 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 -->

package/templates/skills/{orc/references/stop-and-resume.md → _shared/phases/stop-resume.md}

@@ -1,160 +1,169 @@
-# Reference — Stop Sequence, Usage Report, and Fresh-Session Resume
-
-The token-saving heart of ORC. Load whenever a stop fires (batch
-boundary, token pressure, phase transition worth guarding, or user request).
-
-## When a stop is MANDATORY vs a judgment call
-
-Most stops are yours to judge (token pressure, a phase worth guarding, a user
-request). **The batch boundary is NOT a judgment call — it is a hard gate.**
-Waves are computed for every run regardless of dispatch style (sequential runs
-have waves too — see `wave-grouping.md`), so the boundary binds to wave numbers
-in both styles. After completing wave W, if `W % batch_pause_every == 0` **and at
-least one wave remains** (`W < total_waves`), the stop sequence below is MANDATORY
-and deterministic: **never dispatch wave W+1 past an unacknowledged boundary.** The
-boundary is computed from the answered pause schedule at intake (Phase 2) and
-stored as `pause_schedule` in the checkpoint, so a resumed session enforces the
-same boundaries. Emit `GATE wave-boundary :: wave=W of K → STOP (batch_pause_every=N)`
-before the stop. Token pressure and user request remain judgment; the batch
-boundary is not.
-
-## The stop sequence (order is mandatory)
-
-1. **Decide** to stop (your judgment for token/phase/user stops; the batch
-   boundary above is not a decision but a hard gate). The checkpoint skill
-   never decides.
-2. **Write the checkpoint** into the run subfolder via
-   `subskills/orc-checkpoint/SKILL.md`. VALIDATE the
-   return. If the write fails → DO NOT STOP; surface the write failure instead.
-   Stopping without a good checkpoint is the one thing that loses work.
-3. **Update `run/{run-slug}/state-of-play.md`** — the 10-line human-readable re-anchor:
-   current phase, wave, done/pending tasks, last decision, next action.
-3b. **Write `{run_dir}/{run-slug}/RESUME.md`** — the same breath as steps 2–3,
-   by YOU, never a dispatched agent. Overwrite; never append. Shape below.
-4. **Usage report** (see below).
-5. **Generate the resume block** (see below) — regenerate FRESH at every stop,
-   never reuse an old one. It is printed inline AND is the body of `RESUME.md`.
-6. Tell the user: what's done / remaining, then BOTH continue paths:
-   "Reply **continue** here, or paste the block below in a **fresh session**
-   (recommended if this conversation is long — cheaper and cleaner than
-   dragging this context forward)."
-7. End the turn.
-
-## Usage report (at EVERY stop and ALSO at run completion)
-
-Do NOT attempt to invoke `/usage` — it cannot be called programmatically.
-Instead, at every stop and at run completion:
-1. Report the **dispatch log** you fully control: every subagent's model,
-   effort, and score. At completion, show the full per-task table (task, score
-   + override reason, model, effort) so the user sees where tokens went.
-2. **Remind the user to run `/usage` themselves** for their 5-hour and weekly
-   limit numbers: "Run `/usage` to see your remaining limits."
-
-Never skip either part.
-
-## The resume block — printed inline AND written to `RESUME.md`
-
-A fresh session + disk state is cheaper AND higher-fidelity than a long compacted
-session: near-empty context, perfect state. Offer it proactively at every pause
-once the run is more than ~2 waves old or usage is heavy — do not wait to be
-forced.
-
-**The problem this file fixes.** ORC used to print the block and nothing else. If
-the user closed the window, got distracted, or came back three days later, the
-work was safe (the checkpoint is on disk) but the *way back in* was gone.
-
-### Where it goes, and why there
-
-```
-{run_dir}/{run-slug}/RESUME.md
-```
-
-Inside the run folder — with `checkpoint.json` and `state-of-play.md`, where run
-state has lived safely since v0.34.1 — **never at the project root**.
-`/orc-quick` and `/orc-grill` put their docs at the root because those are
-deliverables a human reads later. A resume prompt is *transient run state*: dead
-the moment the run finishes, and it must never be at risk of being committed.
-Discovery is `orc resume`'s job, not the filesystem's.
-
-### Lifecycle — the file existing IS the "unfinished" flag
-
-- **Written at EVERY stop**, as the third write in the same breath as
-  `checkpoint.json` and `state-of-play.md`. ORC writes it itself — no dispatch.
-  A dispatch inside the stop sequence would mean a stop can fail because a
-  subagent did, at the one step whose entire job is not losing work.
-- **ONE per run slug, always overwritten, never appended.** This is already the
-  protocol's rule above ("regenerated FRESH at every stop, never reuse an old
-  one"), because a stale resume block points at a wave that is already done. This
-  gives that rule a place on disk.
-- **Deleted at `FINISH`** — in the same Phase 8 step that deletes
-  `log_dir/.current`. So a `RESUME.md` existing means **this run is still waiting
-  for you**, with no stale entries and no separate "is this consumed?"
-  bookkeeping.
-- **NOT deleted when a resume merely starts.** If that session then dies, the
-  pointer must still be there.
-
-### Contents (deterministic — this shape, not an improvisation)
-
-```
-Continue ORC run `merchant-notifications`.
-
-Read .claude/orc/run/merchant-notifications/state-of-play.md,
-then .claude/orc/run/merchant-notifications/checkpoint.json.
-Resume from the checkpoint's phase and wave.
-The intent-spec is approved — do not re-plan. Do not redo tasks marked done.
-
-Where it stands:  /orc · phase execution · wave 2 of 4 done
-Done:             T1, T2, T3, T5
-Left:             T4 (requeued — see failure_reason), T6, T7
-Watch out for:    T4 failed once on a missing migration; the gotcha is recorded
-Next action:      dispatch wave 3 (T6, T7)
-```
-
-Every blank is a value you hold at that instant (phase, wave, task states,
-failure reasons) — which is exactly why no model is needed to fill them in.
-
-**Keep the `Where it stands:` line in exactly that shape** — lane, then phase,
-then `wave K of N`, separated by ` · `. It is the ONE line `orc resume` and
-`orc run list` parse, which is how they can list every waiting run without ever
-opening a `checkpoint.json`. Prose elsewhere in the file is free-form.
-
-### Always tell the user both paths
-
-```
-Paused after wave 2 of 4.
-
-To continue in a NEW session (cheaper and cleaner than this long one):
-open a fresh session and paste the contents of
-
-  .claude/orc/run/merchant-notifications/RESUME.md
-  (or just run `orc resume` and pick it from the list)
-
-Or reply `continue` here.
-```
-
-Name the path AND the command. A user who lost the chat has neither the block nor
-the slug in front of them.
-
-## Compaction-proofing (always on, not just at stops)
-
-- **Disk is truth.** Everything needed to continue lives in `run/` files you
-  created: intent-spec, checkpoint, state-of-play, decision log. Conversation
-  is a disposable cache.
-- Write the checkpoint EAGERLY: after every wave, every escalation answer,
-  every phase transition — so a surprise compaction never catches state that
-  exists only in conversation.
-- On ANY suspicion of compaction (context feels summarized, details missing):
-  re-read state-of-play → checkpoint → re-anchor BEFORE acting.
-
-## Resume procedure (both paths: "continue" here, or fresh session)
-
-1. Read `run/{run-slug}/state-of-play.md` (one-glance orientation).
-2. Read the newest valid checkpoint (`updated_at` wins).
-3. One-line intent reconfirm (fresh session only): "Resuming: <scope>. Still
-   correct?"
-4. From task_state: done stays done; partial resumes from
-   `progress.files_written` (last milestone); pending awaits its wave;
-   requeued/failed re-dispatch reading `failure_reason`; stale_review gets a
-   review pass.
-5. Re-attach the decision log, regenerate the digest, continue from the
-   checkpoint's phase.
+# Phase — Stop, usage report, resume   (id: `stop-resume`)
+
+> **Library file.** Canonical since v1.0.0 W11; it was
+> the `orc` skill's own `stop-and-resume` reference. Layers declared: `core` only — the stop
+> sequence is identical in every lane that stops, and the lane-specific half
+> (which moments are MANDATORY stops) is already a per-lane rule in the spine.
+
+<!-- orc:layer core -->
+
+The token-saving heart of ORC. Load whenever a stop fires (batch
+boundary, token pressure, phase transition worth guarding, or user request).
+
+## When a stop is MANDATORY vs a judgment call
+
+Most stops are yours to judge (token pressure, a phase worth guarding, a user
+request). **The batch boundary is NOT a judgment call — it is a hard gate.**
+Waves are computed for every run regardless of dispatch style (sequential runs
+have waves too — see `wave-grouping.md`), so the boundary binds to wave numbers
+in both styles. After completing wave W, if `W % batch_pause_every == 0` **and at
+least one wave remains** (`W < total_waves`), the stop sequence below is MANDATORY
+and deterministic: **never dispatch wave W+1 past an unacknowledged boundary.** The
+boundary is computed from the answered pause schedule at intake (Phase 2) and
+stored as `pause_schedule` in the checkpoint, so a resumed session enforces the
+same boundaries. Emit `GATE wave-boundary :: wave=W of K → STOP (batch_pause_every=N)`
+before the stop. Token pressure and user request remain judgment; the batch
+boundary is not.
+
+## The stop sequence (order is mandatory)
+
+1. **Decide** to stop (your judgment for token/phase/user stops; the batch
+   boundary above is not a decision but a hard gate). The checkpoint skill
+   never decides.
+2. **Write the checkpoint** into the run subfolder via
+   `subskills/orc-checkpoint/SKILL.md`. VALIDATE the
+   return. If the write fails → DO NOT STOP; surface the write failure instead.
+   Stopping without a good checkpoint is the one thing that loses work.
+3. **Update `run/{run-slug}/state-of-play.md`** — the 10-line human-readable re-anchor:
+   current phase, wave, done/pending tasks, last decision, next action.
+3b. **Write `{run_dir}/{run-slug}/RESUME.md`** — the same breath as steps 2–3,
+   by YOU, never a dispatched agent. Overwrite; never append. Shape below.
+4. **Usage report** (see below).
+5. **Generate the resume block** (see below) — regenerate FRESH at every stop,
+   never reuse an old one. It is printed inline AND is the body of `RESUME.md`.
+6. Tell the user: what's done / remaining, then BOTH continue paths:
+   "Reply **continue** here, or paste the block below in a **fresh session**
+   (recommended if this conversation is long — cheaper and cleaner than
+   dragging this context forward)."
+7. End the turn.
+
+## Usage report (at EVERY stop and ALSO at run completion)
+
+Do NOT attempt to invoke `/usage` — it cannot be called programmatically.
+Instead, at every stop and at run completion:
+1. Report the **dispatch log** you fully control: every subagent's model,
+   effort, and score. At completion, show the full per-task table (task, score
+   + override reason, model, effort) so the user sees where tokens went.
+2. **Remind the user to run `/usage` themselves** for their 5-hour and weekly
+   limit numbers: "Run `/usage` to see your remaining limits."
+
+Never skip either part.
+
+## The resume block — printed inline AND written to `RESUME.md`
+
+A fresh session + disk state is cheaper AND higher-fidelity than a long compacted
+session: near-empty context, perfect state. Offer it proactively at every pause
+once the run is more than ~2 waves old or usage is heavy — do not wait to be
+forced.
+
+**The problem this file fixes.** ORC used to print the block and nothing else. If
+the user closed the window, got distracted, or came back three days later, the
+work was safe (the checkpoint is on disk) but the *way back in* was gone.
+
+### Where it goes, and why there
+
+```
+{run_dir}/{run-slug}/RESUME.md
+```
+
+Inside the run folder — with `checkpoint.json` and `state-of-play.md`, where run
+state has lived safely since v0.34.1 — **never at the project root**.
+`/orc-quick` and `/orc-grill` put their docs at the root because those are
+deliverables a human reads later. A resume prompt is *transient run state*: dead
+the moment the run finishes, and it must never be at risk of being committed.
+Discovery is `orc resume`'s job, not the filesystem's.
+
+### Lifecycle — the file existing IS the "unfinished" flag
+
+- **Written at EVERY stop**, as the third write in the same breath as
+  `checkpoint.json` and `state-of-play.md`. ORC writes it itself — no dispatch.
+  A dispatch inside the stop sequence would mean a stop can fail because a
+  subagent did, at the one step whose entire job is not losing work.
+- **ONE per run slug, always overwritten, never appended.** This is already the
+  protocol's rule above ("regenerated FRESH at every stop, never reuse an old
+  one"), because a stale resume block points at a wave that is already done. This
+  gives that rule a place on disk.
+- **Deleted at `FINISH`** — in the same Phase 8 step that deletes
+  `log_dir/.current`. So a `RESUME.md` existing means **this run is still waiting
+  for you**, with no stale entries and no separate "is this consumed?"
+  bookkeeping.
+- **NOT deleted when a resume merely starts.** If that session then dies, the
+  pointer must still be there.
+
+### Contents (deterministic — this shape, not an improvisation)
+
+```
+Continue ORC run `merchant-notifications`.
+
+Read .claude/orc/run/merchant-notifications/state-of-play.md,
+then .claude/orc/run/merchant-notifications/checkpoint.json.
+Resume from the checkpoint's phase and wave.
+The intent-spec is approved — do not re-plan. Do not redo tasks marked done.
+
+Where it stands:  /orc · phase execution · wave 2 of 4 done
+Done:             T1, T2, T3, T5
+Left:             T4 (requeued — see failure_reason), T6, T7
+Watch out for:    T4 failed once on a missing migration; the gotcha is recorded
+Next action:      dispatch wave 3 (T6, T7)
+```
+
+Every blank is a value you hold at that instant (phase, wave, task states,
+failure reasons) — which is exactly why no model is needed to fill them in.
+
+**Keep the `Where it stands:` line in exactly that shape** — lane, then phase,
+then `wave K of N`, separated by ` · `. It is the ONE line `orc resume` and
+`orc run list` parse, which is how they can list every waiting run without ever
+opening a `checkpoint.json`. Prose elsewhere in the file is free-form.
+
+### Always tell the user both paths
+
+```
+Paused after wave 2 of 4.
+
+To continue in a NEW session (cheaper and cleaner than this long one):
+open a fresh session and paste the contents of
+
+  .claude/orc/run/merchant-notifications/RESUME.md
+  (or just run `orc resume` and pick it from the list)
+
+Or reply `continue` here.
+```
+
+Name the path AND the command. A user who lost the chat has neither the block nor
+the slug in front of them.
+
+## Compaction-proofing (always on, not just at stops)
+
+- **Disk is truth.** Everything needed to continue lives in `run/` files you
+  created: intent-spec, checkpoint, state-of-play, decision log. Conversation
+  is a disposable cache.
+- Write the checkpoint EAGERLY: after every wave, every escalation answer,
+  every phase transition — so a surprise compaction never catches state that
+  exists only in conversation.
+- On ANY suspicion of compaction (context feels summarized, details missing):
+  re-read state-of-play → checkpoint → re-anchor BEFORE acting.
+
+## Resume procedure (both paths: "continue" here, or fresh session)
+
+1. Read `run/{run-slug}/state-of-play.md` (one-glance orientation).
+2. Read the newest valid checkpoint (`updated_at` wins).
+3. One-line intent reconfirm (fresh session only): "Resuming: <scope>. Still
+   correct?"
+4. From task_state: done stays done; partial resumes from
+   `progress.files_written` (last milestone); pending awaits its wave;
+   requeued/failed re-dispatch reading `failure_reason`; stale_review gets a
+   review pass.
+5. Re-attach the decision log, regenerate the digest, continue from the
+   checkpoint's phase.
+
+<!-- /orc:layer -->