[noeltock]

Problem

A requested handoff should let another engineer inspect what ran and reproduce a failure without reconstructing chat history. Closes #197.

Solution

Add a short, explicitly optional Markdown template and two runnable synthetic examples. Existing reports remain the evidence; ordinary conversions and visual reviews do not generate a formal handoff automatically.

Behaviour	Read first	Proof
Formal handoff only on explicit request	skills/block-runner/references/HANDOFF.md	Scope stated in the template and skill link
Success retains normal output/report	examples/handoff/README.md	Fresh-directory run: two valid blocks, no warnings
Failure can be replayed without the checkout	examples/handoff/failure.json	Pinned published package: exit 1 with matching source-located reason

Diff

7 files, +154 / −0. No runtime/API changes.

 skills/block-runner/SKILL.md
+ explicit request → references/HANDOFF.md
+ six-section Markdown template → original reports and evidence
 examples/handoff/
+ config.json + success.json + failure.json
+ README.md → exact commands, expected results and recorded replay
 docs/reference.md
+ link to optional handoff guidance

Testing & verification

Reviewed revision: b9cb675. Node 22.23.1, macOS; replay used published block-runner@0.9.11 in a fresh temporary directory.

• npm run build, npm run check:private, git diff --check: passed.
• npx --no-install vitest run dev/test/skill.test.ts: 3 tests passed.
• npm run pack:check: passed; package inventory includes the template and all four example files.
• npx --no-install block-runner assemble success.json --config config.json --out success.html --json: exit 0, two valid blocks, zero invalid blocks/warnings.
• npx --no-install block-runner assemble failure.json --config config.json --json: exit 1, ok: false, one invalid input; exact unregistered-block reason at failure.json.

Not verified: a second engineer's independent walkthrough remains for review. These examples prove local validity and portability only; they do not prove WordPress persistence, appearance or production behaviour.

Risk / rollout

Documentation and synthetic inputs only. Detection: replay the documented commands and inspect the complete reports. Rollback: revert this documentation change; no stored state or runtime migration is introduced.

⟁ AI-generated. Facts may have been approximated for performance.