Document explicitly requested handoffs with replayable examples

docs/reference.md

@@ -4,6 +4,10 @@ Start with the [README](../README.md) for a first conversion, or the [architectu
 
 Theme-folder and whole-site commands, Wesper 0.5.0 and the Node 22.13/24 floor require 0.9.11 or later; 0.9.10 predates them. The [theme and site guide](../skills/block-runner/references/SITE.md) owns the whole-site input and lifecycle examples.
 
+When a formal handoff or portable failure reproduction is requested, use the optional
+[handoff template](../skills/block-runner/references/HANDOFF.md) and
+[worked examples](../examples/handoff/README.md). Ordinary runs do not require a handoff package.
+
 ## Native block support boundaries
 
 Four different claims need different evidence:

examples/handoff/README.md

@@ -0,0 +1,78 @@
+# Two requested handoffs
+
+These synthetic examples exercise the [optional handoff template](../../skills/block-runner/references/HANDOFF.md).
+They are local validity/reproduction examples, not WordPress or visual acceptance.
+
+Copy `config.json`, `success.json` and `failure.json` from this directory into an empty
+directory. The explicit empty config prevents ambient configuration from changing the run.
+Install the exact runtime used for these examples, then retain the normal CLI artifacts:
+
+```sh
+npm init -y
+npm install --no-audit --no-fund block-runner@0.9.11
+node --version
+npx --no-install block-runner --version
+npx --no-install block-runner assemble success.json --config config.json --out success.html --json > success.report.json
+npx --no-install block-runner assemble failure.json --config config.json --json > failure.report.json
+```
+
+The success command exits 0. The failure command intentionally exits 1; run it separately
+if your shell stops on errors. Keep its JSON report. Do not turn the expected failure
+into a successful conversion or discard the source. For a candidate package, install
+the reviewed tarball instead of the release and record its revision/hash.
+
+## Success handoff
+
+**Outcome and next action:** native markup is retained in `success.html`. Deliver it to
+the agreed destination; no WordPress write has occurred in this example.
+
+**Run identity:** Block Runner 0.9.11, route `assemble`; record your observed Node version
+and run date. The selected input is `success.json`, with explicit `config.json`.
+
+**Reproduction:** run the success command above from the directory containing those files.
+Expected: exit 0, `ok: true`, two valid blocks, zero invalid blocks and zero warnings.
+
+**Evidence:** `success.report.json` is the original complete report; `success.html` is
+its output. There are no companion assets in this input. Inspect both retained files;
+their paths refer to the reproduction directory, not this documentation directory.
+
+**Checks and limits:** headless validity is observed in the report. Appearance, native
+edit/save/reopen, interaction and production behaviour are unverified.
+
+**Continuation:** use the normal delivery workflow when a destination is available.
+Do not call the example a rendered or installed result.
+
+## Failure handoff
+
+**Outcome and next action:** assembly rejects the unregistered block. Correct the input
+to an intended supported block, or investigate the required project-owned block route;
+do not silently replace its content with an empty result.
+
+**Run identity:** Block Runner 0.9.11, route `assemble`; record your Node version/date.
+The selected input is `failure.json`, with explicit `config.json`.
+
+**Reproduction:** run the failure command above in a fresh directory. Expected: exit 1,
+`ok: false`, one invalid input, no output markup. The original diagnostic reason is:
+
+```text
+assembly failed: blocks[0]: block type "example/not-registered" is not registered
+```
+
+**Evidence:** `failure.report.json` retains the diagnostic at source path `failure.json`.
+This result has no separate diagnostic `code` field; use the exact reason and stage.
+
+**Checks and limits:** local input rejection is observed. No target-site operation was
+attempted; target registration, appearance and save persistence are unverified.
+
+**Continuation:** retain the original input/report alongside any corrected revision.
+Only the selected JSON files and pinned package are needed to reproduce this failure;
+no original checkout, browser, site state or credentials are required.
+
+## Recorded replay
+
+On 2026-10-24, both commands were run from a fresh temporary directory with Node
+22.23.1 and the published `block-runner@0.9.11` package. Only the three JSON files
+above were copied in; the run did not read the original checkout. Success returned
+exit 0 and `blocks: 2, valid: 2, invalid: 0, warnings: 0`. Failure returned exit 1,
+`ok: false`, `invalid: 1`, and the exact reason above at `failure.json`.
+This verifies a clean consumer replay, not an independent engineer's review.

examples/handoff/config.json

@@ -0,0 +1 @@
+{}

examples/handoff/failure.json

@@ -0,0 +1,5 @@
+{
+  "blocks": [
+    { "block": "example/not-registered", "text": "Keep this source when reporting the failure." }
+  ]
+}

examples/handoff/success.json

@@ -0,0 +1,6 @@
+{
+  "blocks": [
+    { "block": "core/heading", "level": 2, "text": "A retained result" },
+    { "block": "core/paragraph", "text": "This paragraph remains native and editable." }
+  ]
+}

skills/block-runner/SKILL.md

@@ -87,3 +87,7 @@ otherwise ask in plain language.
 Block structure rules, the full node schema and per-section mappings are in
 `references/ASSEMBLE.md`. Token and media resolution, exit codes, and failure posture are in
 `references/GUIDE.md`.
+
+For an explicitly requested formal handoff or reproducible failure package, use
+[HANDOFF.md](references/HANDOFF.md). Do not create a formal handoff by default;
+ordinary delivery needs only the result, relevant evidence and remaining limits.

skills/block-runner/references/HANDOFF.md

@@ -0,0 +1,56 @@
+# A handoff when requested
+
+Use this only when the user explicitly requests a formal handoff, reproduction package
+or transferable run record. Do not generate one for every conversion or visual review.
+Ordinary delivery still needs a concise result and honest limits; it does not require
+this template, extra files or a separate approval step.
+
+Keep original reports, receipts and journals authoritative. Link to them instead of
+copying their full contents or translating their statuses. Use the parts of this
+template that the run needs; omit irrelevant detail rather than inventing it.
+
+```markdown
+# <Artifact or task> handoff
+
+## Outcome and next action
+<Delivered or blocked; exact next action and any outstanding decision.>
+
+## Run identity
+<Date, Block Runner/Node versions, route and source revision/hash.
+Relevant observed WordPress/theme/plugin versions, or unknown.>
+
+## Inputs and reproduction
+<Relative input/config/context/media paths, working directory, exact command/options,
+required environment-variable names and expected exit/result. No credential values.>
+
+## Outputs and evidence
+<Links to existing output, companion CSS/assets, complete reports, receipts,
+journals and captures. Reuse their hashes where available.>
+
+## Checks and limits
+| Claim | Check and observed result | Evidence |
+| --- | --- | --- |
+| <Validity, visual, save, interaction or production> | <Actual result or unverified> | <Link> |
+
+## Failure or continuation
+<Exact diagnostic code/location or observed failing stage, suspected cause labelled
+as such, retained reproduction and remaining action.>
+```
+
+For a portable failure, explicitly select the smallest sanitised input and dependencies.
+Keep normal filenames and relative paths. Test the recorded command in a fresh directory
+with the pinned package and without the original checkout or ambient configuration.
+Record an expected failing exit code. If the result needs inaccessible site state or
+private files, name that dependency and do not call the package self-contained.
+
+Preserve warnings, source locations and partial/unknown journal outcomes. A valid
+report is not proof of appearance, editor persistence or production behaviour. Missing
+evidence stays unverified. A screenshot needs a recorded observation to support a
+visual claim. Include editorial TODOs only where relevant.
+
+Review selected files for sensitive content before sharing. No automatic collection,
+redaction, upload or support submission is implied. Referenced receipt evidence must
+remain accessible; a link to an unavailable local file is not a portable reproduction.
+
+See the [worked success and failure examples](../../../examples/handoff/README.md).
+They use existing CLI reports and plain Markdown, with no new executable or schema.