@azure-id/orc 0.55.0

package/templates/skills/_shared/fable5-override.md

@@ -0,0 +1,56 @@
+# Shared contract — Fable 5 role override (hard-gated)
+
+Canonical rule for routing selected roles to Fable 5 agents. Consumed by the
+full orc spine and the ultra lane; the lint pins the `fable5-override.md` pointer
+into every lane that honors it.
+
+## The gate
+
+Read the resolved config at run start (`config.md` defaults ← `orc.config.yaml`).
+The override is **hard-gated**: absolutely nothing changes unless
+`fable5_enabled: true`. When it is false (the default), dispatch every role
+exactly as today — this file is inert.
+
+## The mapping (only when `fable5_enabled: true`)
+
+For each role listed in `fable5_roles` (a subset of
+`analyze, plan, advisor, judge, review`), dispatch the Fable 5 variant agent
+**instead of** the default role agent — same task slice, same return contract,
+same phase:
+
+| Role token | Default agent | Fable 5 variant |
+|-----------|---------------|-----------------|
+| `analyze` | `orc-system-analyst-opus-5-high` | `orc-analyst-fable-5` |
+| `plan`    | `orc-planner-opus-5-med`         | `orc-planner-fable-5` |
+| `advisor` | `orc-advisor-opus-5-xhigh`         | `orc-advisor-fable-5` |
+| `judge`   | `orc-judge-opus-5-xhigh`           | `orc-judge-fable-5` |
+| `review`  | `orc-reviewer-opus-5-med`       | `orc-reviewer-fable-5` |
+
+A role NOT in `fable5_roles` keeps its default agent. `advisor` and `judge` are
+ultra-lane only — they take effect solely under `/orc-ultra`, and only when
+explicitly selected. `fable5_enabled: true` with an empty `fable5_roles` does
+nothing (the CLI warns on set).
+
+## Out of scope — never overridden
+
+- **`orc-quick`.** The lane asks the USER which agent to spawn before every
+  dispatch; a role override that silently swapped the answer would defeat that
+  hard gate. `fable5_enabled` / `fable5_roles` are neither read nor honored
+  there, in addition to `opus5_only` (`opus5-only.md`) and
+  `rubric_bands_override`. See `orc-quick/references/dispatch-gate.md`.
+- **`orc-trace-writer-haiku-4-5`** and **`orc-diy`** — same carve-outs as
+  `opus5-only.md`.
+
+## Effort
+
+The Fable 5 agents' effort is `fable5_effort` (enum `medium | high | xhigh |
+max`, default `medium`). Effort lives in each agent's frontmatter; the
+`orc config set fable5_effort <v>` CLI rewrites the `effort:` line of the
+installed copies deterministically — the skill never edits agent files.
+
+## Why it's safe
+
+Fable 5 is a strictly-capable model (it never downgrades a subagent), so a
+Fable 5 role agent runs at or above the baseline. The `CONFIG` trace line at
+Phase 1 records the resolved `fable5_*` values, so `/orc-retro` can audit that a
+run's dispatch honored the config.

package/templates/skills/_shared/fallback-handoff.md

@@ -0,0 +1,42 @@
+# Fallback handoff (orc-fast → orc-mini)
+
+Canonical contract for the fast lane's fallback. orc-fast WRITES this block;
+orc-mini READS it. Fallback is the router — orc-fast never stops the chat.
+
+## The block (written into the shared run folder)
+
+```
+FALLBACK-FROM: orc-fast
+REASON: wiki-absent | wiki-stale-user-choice | pattern-absent | fit-gate | smoke-red-escalation
+INTENT-SPEC: <path to the intent-spec if fast's Phase F1 completed, else "none — raw request follows">
+REQUEST: <the raw user request, verbatim>
+```
+
+## Writer side (orc-fast)
+
+Announce which prerequisite/gate failed in one line, write the block, invoke
+orc-mini pointing at it. The run folder is already in the shared
+`.claude/orc/run/{run-slug}/` format — no migration, no new slug.
+
+## Reader side (orc-mini)
+
+On entry: acknowledge the fallback + reason in one line, then run the normal
+mini lane — but SKIP re-deriving anything carried over:
+
+- An attached INTENT-SPEC replaces the Phase 0 draft (still do the soft
+  sign-off).
+- Reuse the run folder and slug.
+- `REASON: smoke-red-escalation` means code was already written — start from
+  the failing state, not from scratch.
+
+## What carries over
+
+| Carries over | The receiver RE-DERIVES | On conflict |
+|---|---|---|
+| The user's original request, verbatim | The knowledge gate (wiki tier, pattern, and its own probes) | The receiver's own probe wins |
+| Why the handoff fired — the exact failed prerequisite | The plan, the scoring, the waves | — |
+| Anything the user already confirmed in this session | Every file claim the sender made | HOST code wins |
+
+The middle column is the point: a receiving lane must not inherit the sender's
+findings as fact. An inherited claim is a HINT with a known author, never
+evidence — re-anchor it or drop it.

package/templates/skills/_shared/gh-stack-commands.md

@@ -0,0 +1,65 @@
+# Shared contract — `gh stack` command surface (pinned)
+
+Canonical, single-copy reference for GitHub's stacked-pull-request CLI. Both
+stacked-PR lanes (`orc-pr-setup`, `orc-pr-driver`) and ORC's ship-phase stack
+gate read THIS file — never a remembered command list.
+
+**Why one file:** stacked PRs are a GitHub **public preview** (shipped
+2026-07-30). The command surface can be renamed under us. Pinning it here makes
+a breaking rename a one-file fix instead of a hunt across five skills.
+
+## Preflight (probe, never assume)
+
+| Check | Command | Fail meaning |
+|---|---|---|
+| gh present, ≥ 2.0 | `gh --version` | no `gh` → stacking is impossible; regular push |
+| authed | `gh auth status` | not authed → regular push |
+| extension | `gh extension list` (look for `github/gh-stack`) | absent → offer `gh extension install github/gh-stack` |
+| same repo, not a fork | `gh repo view --json isFork,nameWithOwner` | **fork → STOP.** Cross-fork stacks are unsupported; this workflow does not apply |
+| trunk name | `gh repo view --json defaultBranchRef` | the bottom layer's base |
+| protections / required checks | `gh api repos/{owner}/{repo}/branches/{trunk}/protection` (404 = none) | tells you N layers = N full CI runs |
+| merge queue | same protection payload | preview support is rolling out — **probe, never assume** |
+
+## Command table (verbatim surface)
+
+| Command | Purpose |
+|---|---|
+| `gh stack init [-b <base>] [branches...]` | start a stack in the current repo (interactive with no args; can adopt the current branch as layer 1) |
+| `gh stack add [-A] [-u] [-m <msg>] [branch]` | new branch on top of the current stack |
+| `gh stack view [-s] [--json]` | show the stack — `--json` is the machine-readable form every gate reads |
+| `gh stack checkout <stack-no \| pr-no \| pr-url \| branch>` | check out a stack |
+| `gh stack modify [--continue] [--abort]` | interactive restructure: drop / combine / insert / reorder / rename |
+| `gh stack unstack [<stack-no>] [--local]` | remove from tracking / unstack on GitHub |
+| `gh stack submit [--auto] [--open] [--remote <n>]` | push branches, create/update PRs, create the stack |
+| `gh stack sync [--remote <n>] [--prune]` | fetch, rebase, push, sync PR state |
+| `gh stack rebase [--downstack] [--upstack] [--no-trunk] [--continue] [--abort]` | cascading rebase |
+| `gh stack push [--remote <n>]` | push active branches |
+| `gh stack link [--base <b>] <a> <b> [...]` | link EXISTING PRs into a stack (no local tracking) — the retrofit path |
+| `gh stack merge [<stack-no> \| <pr-no>] [--merge\|--squash\|--rebase] [-y]` | merge one or more layers |
+| `gh stack switch` / `up [n]` / `down [n]` / `top` / `bottom` / `trunk` | navigate |
+| `gh stack alias [--remove] [name]` | shorthand alias |
+
+## Semantics that shape the lanes
+
+- **stack** = an ordered chain of PRs in ONE repo. **layer** = one PR in it.
+  Bottom layer's base is the trunk; each upper layer's base is the branch below.
+- **retarget** — merging a lower layer automatically repoints the layers above.
+- **restack** — server-side cascading rebase from the PR UI, or `gh stack rebase`.
+- **merge is BOTTOM-UP.** Merging the top "ready" layer lands every unmerged
+  layer below it in one operation; merging one layer leaves the ones above open
+  and auto-rebased. History equals merging each layer individually from the
+  bottom. commit / squash / rebase are all supported.
+- The **stack map** renders at the top of every PR in the stack.
+- Layers can be reviewed **in parallel** by different reviewers — that is the
+  whole point of splitting.
+- **Every layer runs full CI.** N layers = N CI runs (plus N code-quality scans).
+  Layer count is a cost, so it is justified, never maximized.
+- No documented maximum layer count — the cap in
+  `_shared/stack-plan.md` is ORC's, for review sanity.
+
+## Fallback when `gh stack` is unavailable
+
+No `gh`, no extension, or a fork → say so in one line and ship the change as a
+**single regular PR**. Never hand-roll a stack with bare `git push` + manual
+base edits: without the extension nothing retargets on merge, and a half-built
+stack is worse than one honest big PR.

package/templates/skills/_shared/gotchas.md

@@ -0,0 +1,177 @@
+# Shared contract — Gotchas (repair memory that outlives the run)
+
+Canonical file: `_shared/gotchas.md`. THE one description of ORC's repair memory:
+what a gotcha is, where it lives, when one is recorded, when one is injected, and
+which lane may do which. Gate: config `gotchas` (`on` | `off`, default `on`).
+
+## 1. What a gotcha is
+
+**ONE project-specific failure that a repair in this project already solved.**
+Not a rule, not a preference, not a lesson in general.
+
+It is deliberately none of the other three knowledge artifacts:
+
+| Artifact | Answers | Not this |
+|---|---|---|
+| the wiki | "what IS this codebase" | a gotcha is not a fact about the code |
+| the pattern cache | "how does this project WRITE code" | a gotcha is not a convention |
+| `tdd_spec` | "what must this change PROVE" | a gotcha is not an acceptance test |
+| **gotchas** | **"what has this project already gotten WRONG here"** | — |
+
+If a finding fits one of the first three rows, it belongs there. A gotcha is the
+residue of a repair: something went red, a specific cause was found, a specific
+fix made it green.
+
+## 2. The artifact
+
+```
+.claude/orc/gotchas.md            # live entries, capped at gotchas_max
+.claude/orc/gotchas-archive.md    # evicted entries — never hard-dropped
+```
+
+Both sit BESIDE the pattern cache (`orc/patterns/`), never inside it. Like every
+file ORC generates under `.claude/orc/`, neither is in the install manifest — so
+`orc update --prune` can never delete them and `orc update` never overwrites them.
+They are user data by ORC's own rules.
+
+**Entry format** — the parser and every writer depend on this exactly:
+
+```markdown
+## G-014 · express · repair
+- trigger:   adding a route handler that awaits a Mongoose query
+- symptom:   Cannot read properties of undefined (reading 'session') in tests
+- cause:     the test harness stubs req.session only for authed routes
+- fix:       register the route under authedRouter, not app
+- scope:     src/routes/**/*.js
+- origin:    run-orc-add-billing-050826-141233 · TDD repair round 2
+- hits:      3
+- last_seen: 05-08-2026
+```
+
+- Heading: `## G-<3-digit id> · <lang-or-area> · <kind>`; `kind` ∈
+  `repair | drift | review | verify`.
+- Field order is FIXED. Every field is required. Values are single-line.
+- `scope` is a glob matched against a task's `declared_files`.
+- Dates are `DD-MM-YYYY` (the repo's convention).
+- IDs are monotonic; **never reused**, even after archival — an archived gotcha
+  stays traceable from a trace or a run doc that cited it.
+
+## 3. Existence probe (never a `find`)
+
+```
+orc gotcha status     exit 0 = one or more live entries · exit 1 = none
+orc gotcha list       the same contract, and prints the entries
+orc gotcha prune      archive the low-value tail down to gotchas_max
+```
+
+**The exit code IS the contract**, same convention as `orc pattern status <lang>`
+and `orc diy status`. `.claude/` is a hidden directory, so an ad-hoc `find`/glob
+false-negatives from the wrong CWD or when it skips dot-dirs — the same reason
+`detecting-artifacts.md` exists for the wiki and the pattern cache. Probe once,
+treat the result as the source of truth, and never second-guess a positive probe.
+
+## 4. When one is RECORDED
+
+At phase close, **when and only when a repair loop went red → green**:
+
+- the TDD repair loop turned a failing `tdd_spec` test green;
+- a `DRIFT-FROM` recovery round resolved the drift;
+- a reviewer P0/P1 that THIS SAME RUN fixed;
+- a verifier `unmet[]` entry that THIS SAME RUN closed.
+
+**A loop that hit its cap and STOPPED records NOTHING.** An unsolved failure is
+not a gotcha — it is an open problem, and the honest red report is where it
+belongs. Writing one anyway would seed the memory with advice that never worked.
+
+Nothing else records. A first-try success has no repair to remember; a green
+`regression-guard` test proved something, but it was never red.
+
+## 5. Who writes it
+
+Three parties, and they do not overlap:
+
+1. **The agent RETURNS the body** in `gotcha_recorded` (see
+   `return-validation.md` §7) — either the entry fields or `none` + a one-line
+   reason. The agent that did the repair is the only party that knows the cause.
+2. **The ORCHESTRATOR appends it** to `.claude/orc/gotchas.md`, at the same
+   phase-close point where it dispatches the trace packet. **A subagent never
+   writes either gotcha file.**
+3. **The CLI owns counting, capping and archival** (`orc gotcha prune`) —
+   deterministic bookkeeping, never a model's judgement.
+
+## 6. Dedupe (before every append)
+
+Compare the returned `symptom` + `scope` against the live entries. A match:
+increment `hits`, refresh `last_seen`, and **append nothing**. Only a genuinely
+new failure gets a new ID. Without this the file grows one duplicate per run and
+the injection cap fills with the same entry three times.
+
+## 7. When one is INJECTED
+
+Into an executor slice, **filtered by the `scope` glob against that task's
+`declared_files`**.
+
+- **NEVER inject unfiltered.** An unfiltered injection is the exact failure mode
+  that turns this feature into the bloat it exists to prevent.
+- Cap **3 entries per slice**, highest `hits` first.
+- **Zero matches = no gotcha block at all** — not an empty one. An empty block
+  costs tokens and says nothing.
+
+The block rides beside `pattern` in the slice, and like `pattern` it is injected
+LITERALLY, never as a file pointer.
+
+## 8. Who reads it
+
+- **Phase 1 preflight** — one line, never silent (see
+  `../orc/references/preflight-report.md`).
+- **executor slices** — filtered, capped, per §7.
+- **the reviewer** — the matching entries as a checklist: has this change
+  reintroduced a failure this project already paid for?
+- **`/orc-retro`** — read-only calibration input. It never writes one.
+
+## 9. Staleness is the user's job
+
+An injected gotcha is presented to an executor as **fact**. Nothing in ORC
+re-verifies that it is still true — `orc gotcha prune` handles CAPACITY, not
+correctness.
+
+So, plainly: **delete an entry that stopped being true.** Open
+`.claude/orc/gotchas.md` and remove the block. That is the whole procedure, and
+it is deliberately manual — a model deciding which of its own memories to forget
+is a worse failure mode than a stale line a human can read.
+
+## 10. Lane policy
+
+| Lane | Reads | Writes |
+|------|-------|--------|
+| `/orc`, `/orc-ultra` | yes | yes |
+| `/orc-mini` | yes | yes |
+| `/orc-fast` | yes | no |
+| `/orc-diy` | compile-owned (`gotchas` flow key) | compile-owned |
+| `/orc-quick` | **no** | **no** |
+| `/orc-retro` | yes | no (read-only by contract) |
+
+### Per-lane mechanics (the spines keep the trigger; this is the detail)
+
+**`/orc-mini` — reads AND writes, trimmed to one row.** Phase 1: probe
+`orc gotcha status` and print exactly one of `gotchas: <n> known · <m> match` /
+`none yet` / `off` — never silent. Phase 3: inject the scope-matching entries into
+the single executor slice beside the pattern (cap 3, highest `hits` first; zero
+matches = no block, NEVER unfiltered). After the return: dedupe a
+`gotcha_recorded` body on `symptom`+`scope` (a match bumps `hits`/`last_seen`) and
+append it to `.claude/orc/gotchas.md` yourself. A capped-and-stopped loop records
+nothing. Mini has no separate review/verify phase, so its only writer is the
+executor return.
+
+**`/orc-fast` — reads only, and gains no third prerequisite.** Its two hard gates
+(a FRESH/AGING wiki + a cached pattern) are its entire design; a missing gotchas
+file is never a reason to fall back, and gotchas here are purely additive: probe,
+inject the scope-matching entries into the F2 slice, and stop there. It never
+writes one, because one executor plus one repair round is too little signal to
+attribute a cause — and a lane with no analyst writing repair memory is how that
+memory fills with guesses.
+
+**`/orc-quick` does not participate at all — not even reading.** Its Q0 preflight
+reads `log_dir` and no other config key, by contract. A `gotchas` key read would
+break that guarantee, and the lane's whole premise is fewer steps, not more
+knowledge. This exclusion is intentional and is not an oversight to "fix".

package/templates/skills/_shared/interview.md

@@ -0,0 +1,144 @@
+# Shared contract — The interview (turning a vague idea into a settled one)
+
+Canonical file: `_shared/interview.md`. THE canonical way any ORC lane
+interrogates a human until an idea is sharp enough to act on. Load it wherever a
+lane must ask more than a fixed questionnaire's worth of questions: `/orc-grill`
+runs it end to end, and `references/intake.md` borrows its round format when a
+tier's question set runs long.
+
+This is not "ask good questions". It is a specific mechanic with a termination
+rule, and the mechanic is what makes the output load-bearing instead of merely a
+good conversation.
+
+## Why this exists
+
+ORC's spec quality is capped by the opening message. A fixed questionnaire asks
+the same things of "add a retry to the webhook" and "something is wrong with our
+refunds" — and gets a usable answer for one and noise for the other. Worse, the
+expensive instruments are the wrong fix: `/orc-analyze` checks a requirement
+**against the code**, so pointing it at a fuzzy *intent* spends a scan asking
+questions a conversation asks for free.
+
+## The design tree
+
+Model the idea as a tree of open questions, not a list. A question is **settled**
+when the user has answered it (or explicitly deferred it); it is **open**
+otherwise. A question **depends on** another when its sensible options change
+based on that answer.
+
+> "Which queue?" depends on "is this async at all?" — asking both at once
+> produces an answer to the second that the first may delete.
+
+## The frontier, and the round
+
+The **frontier** is every open question whose prerequisites are all settled.
+
+**Ask the whole frontier in ONE round.** Not one question at a time (that is a
+slow interrogation), not everything at once (that is a form). Two questions never
+share a round if one depends on the other — if they do, you have mis-drawn the
+tree, and the answer to the dependent one is worthless.
+
+After each round: record the answers, re-derive the frontier, ask the next round.
+Rounds get shorter as the tree settles. That shrinking is the progress signal.
+
+## Fixed question shape (so a round is answerable by number)
+
+```
+❓ **Q1** — **<short title>**: <the question, in plain words>
+➡️ <your recommendation, alone on this line, with the one-line reason>
+```
+
+Every question carries a recommendation. A user who does not care answers
+"1, 3, default the rest" and the round still moves. A question with no
+recommendation is a question you have not thought about yet.
+
+## Facts vs decisions — the split that does the work
+
+**A FACT is ORC's job, never the user's.** If the answer exists somewhere ORC can
+look, looking is cheaper and more accurate than asking. Never make a human recite
+their own codebase back to you. Resolve facts in this order — this is
+`_shared/read-ladder.md` applied to interviewing, and you stop at the step that
+answers:
+
+| Step | Source |
+|------|--------|
+| 1 | `orc wiki status` — is there a wiki, and is it fresh? (`_shared/detecting-artifacts.md`) |
+| 2 | the wiki pages themselves, when the tier is FRESH or AGING |
+| 3 | the cached code-pattern (`orc pattern status <lang>`) |
+| 4 | `orc gotcha list` — what this project already got wrong here |
+| 5 | a read-only ad-hoc dispatch, **last** — it costs tokens and wall-clock |
+
+**Never block a round on a running fact-find.** Ask the rest of the frontier
+while it runs; only the questions genuinely downstream of that fact wait.
+
+**A DECISION is the user's, and the lane waits for it.** Trade-offs, scope,
+priorities, what "done" means, what is explicitly not being built — these have no
+correct answer discoverable in a repository. Recommend, argue for the
+recommendation, and then wait. Put plainly:
+**a lane that answers its own interview question has broken this contract.**
+A default silently adopted is
+indistinguishable, one week later, from a decision the user made — and it is the
+one the build gets wrong.
+
+**The mirrored half, for a lane that GENERATES options** (`/orc-brainstorm`):
+producing candidates is ORC's job, choosing between them is the user's, and
+**The third half, for a lane that GRADES** (`/orc-challenge`): ORC judges, the
+user fixes, ORC re-judges — and **a lane that fixes what it judged has broken
+this contract**, because a session that just wrote the fix will grade its own
+homework and it will always pass. Its intake is this same split applied to the
+PURPOSE of the review: **a lane that guesses the user's goal has broken this
+contract** too, because a finding is only a finding relative to a goal, and a
+*defensible* finding about the wrong thing is worse than an obviously wrong one.
+
+**a lane that picks its own favourite** and moves on has broken the same
+contract. Convergent and divergent work split the same way; the two sentences are
+registered as a pair so neither lane can drift into the other's habits.
+
+**The fourth half, for a lane that CHOOSES ITS REVIEWERS** (`/orc-challenge`'s
+council): deriving a suggested roster from the artifact's kind and goal is a
+FACT, so ORC may compute it — but accepting it is a DECISION, so the lane waits,
+and **a lane that picks its own council has broken this contract.** A council
+chosen by ORC is ORC deciding which kinds of criticism the user is allowed to
+hear, which is a bigger decision than any single finding in the run. Registered
+alongside the other three for the same reason: all four are one contract seen
+from four sides.
+
+## The confirmation gate — an empty frontier does NOT end the session
+
+When no open question remains, do not declare victory. Play the idea back in
+plain words — what it is, what was decided, what was ruled out — and ask:
+
+> Does this match what you meant?
+
+The user saying **yes, we understand each other** ends the interview. Nothing
+else does. A "no" is not a failure; it is the tree being wrong, which is exactly
+what this gate exists to catch. Re-open, add the questions the mismatch implies,
+and run another round.
+
+## Tag every settled decision — what makes this load-bearing
+
+This is ORC's addition, and it is the reason an interview is worth running rather
+than just chatting. As each decision settles, tag it exactly one way:
+
+- **`intent`** — what the user wants built. Flows into the intent-spec / the
+  requirement statement.
+- **`constraint`** — a boundary the build must not cross ("no new dependencies",
+  "must stay backward-compatible with the v1 payload"). Becomes a
+  `spec_invariants[]` entry, appended **verbatim** to every executor slice.
+
+A constraint recorded as prose in a document nobody re-reads is a constraint that
+gets violated in wave 2. A constraint that rides in every slice does not.
+
+## Questions an interview cannot settle — name them, do not talk around them
+
+Some questions are not answerable by conversation at all:
+
+- **"How should this feel?"** — taste, layout, tone. Talking produces agreement
+  on words, not on the artifact. This is what ORC's `mock_example` phase is for
+  (`mock-examples/<slug>/`): make something to look at, then react to it.
+- **"Does the code actually do that?"** — a claim about the repository. That is
+  `/orc-analyze`, not another round of questions.
+
+Say which class an unsettled question is in and point at the right instrument.
+Carrying it as an open question with the instrument named is a complete answer;
+grinding on it for three more rounds is not.

package/templates/skills/_shared/lane-suspend.md

@@ -0,0 +1,82 @@
+# Shared contract — Lane SUSPEND and RESUME (`RETURN-TO`)
+
+Canonical file: `_shared/lane-suspend.md`. THE canonical mechanic for a lane that
+must **leave mid-run, let another lane settle something, and come back to the
+work it had already done**. Load it wherever a lane hands control away and
+expects control back.
+
+## Why this is not a fallback
+
+ORC already has `_shared/fallback-handoff.md` (`FALLBACK-FROM`), used when
+`/orc-fast` cannot proceed. That contract **leaves and does not return** — the
+receiving lane finishes the job and the sender is done.
+
+A SUSPEND is the other shape. The sender has real work in hand — a half-built
+frame, a pool of candidates, decisions already tagged — and that state must
+survive the trip. Sending it through a fallback would silently destroy it.
+
+| | `FALLBACK-FROM` | `RETURN-TO` |
+|---|---|---|
+| Who finishes the run | the receiver | the **sender**, after coming back |
+| Sender state | abandoned | **snapshotted, then resumed** |
+| The receiver's exits | its own | its own **plus** a return option |
+| Trace | one run | **two runs, correctly counted as two** |
+
+## The block
+
+The suspending lane writes this into the receiving lane's opening context:
+
+```
+RETURN-TO: <sender-lane>/<slug>
+SNAPSHOT: <path to the sender's state file on disk>
+GAP: <the one thing the receiver is being asked to settle, in one sentence>
+```
+
+## Sender obligations — all four, in order
+
+1. **Snapshot first, before leaving.** Write the sender's current state to disk.
+   A suspended run that cannot resume is worse than a file nobody asked for, so
+   this write happens even in a lane whose deliverable is otherwise gated on an
+   explicit yes — it is **run state, not the deliverable**, and the sender says
+   so in one line when it writes it.
+2. **Offer, never force.** A suspend is one option among the alternatives
+   (answer it here · park it as a stated assumption and continue). The user
+   chooses; the lane waits.
+3. **Enter the receiving lane** with the block above and the `GAP` as its opening
+   sentence.
+4. **On return, resume at the phase you left** — never from scratch, never by
+   re-asking what the trip just settled.
+
+## Receiver obligations
+
+- **Run completely normally.** Its own phases, its own gates, its own trace, its
+  own run. A `RETURN-TO` marker changes nothing about how it works.
+- **Add ONE exit option, present only under `RETURN-TO`:**
+  `Return to /<sender-lane> — carry these decisions back`, and it is the
+  recommended option in that state. Every other exit still works: a user who
+  picks "stop, save nothing" simply does not come back, and the sender's
+  snapshot is still on disk for a later re-open.
+- **Carry decisions back with their tags intact** (`intent` / `constraint`, per
+  `_shared/interview.md`) plus `source: /<receiver-lane>`, and merge the facts it
+  looked up into the sender's own table. A decision that returns untagged is a
+  decision that stops becoming a `spec_invariants[]` entry downstream.
+
+## The trace-pointer rule (the one that is easy to skip, and expensive)
+
+A receiving lane **deletes `log_dir/.current` at its `FINISH`**. If the sender
+resumes without noticing, every line it writes after the return goes nowhere —
+the v0.34.2 split-run defect family wearing a new hat.
+
+> **On RESUME, the suspending lane re-writes its own `.current` AND must
+> `touch the trace file` it names, in the SAME step. Both, or neither.**
+
+Then it narrates the trip: one event for the suspend, one for the return, in the
+sender's own trace. **Two traces are correct here** — two lanes ran, and
+`orc stats` counts two. The sender's trace records the trip; the receiver's
+records the content.
+
+## What never travels
+
+A suspend does not widen anyone's authority. The receiver may not write the
+sender's deliverable, and the sender may not re-open the receiver's decisions on
+return — it records them and carries on.