diff --git a/docs/reference.md b/docs/reference.md index 8789af4..ac3ccde 100644 --- a/docs/reference.md +++ b/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: diff --git a/examples/handoff/README.md b/examples/handoff/README.md new file mode 100644 index 0000000..9e2aea1 --- /dev/null +++ b/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. diff --git a/examples/handoff/config.json b/examples/handoff/config.json new file mode 100644 index 0000000..0967ef4 --- /dev/null +++ b/examples/handoff/config.json @@ -0,0 +1 @@ +{} diff --git a/examples/handoff/failure.json b/examples/handoff/failure.json new file mode 100644 index 0000000..53b0fa2 --- /dev/null +++ b/examples/handoff/failure.json @@ -0,0 +1,5 @@ +{ + "blocks": [ + { "block": "example/not-registered", "text": "Keep this source when reporting the failure." } + ] +} diff --git a/examples/handoff/success.json b/examples/handoff/success.json new file mode 100644 index 0000000..de4c5a4 --- /dev/null +++ b/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." } + ] +} diff --git a/skills/block-runner/SKILL.md b/skills/block-runner/SKILL.md index 9a4421e..e816f77 100644 --- a/skills/block-runner/SKILL.md +++ b/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. diff --git a/skills/block-runner/references/HANDOFF.md b/skills/block-runner/references/HANDOFF.md new file mode 100644 index 0000000..f7e111c --- /dev/null +++ b/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 +# handoff + +## Outcome and next action + + +## Run identity + + +## Inputs and reproduction + + +## Outputs and evidence + + +## Checks and limits +| Claim | Check and observed result | Evidence | +| --- | --- | --- | +| | | | + +## Failure or continuation + +``` + +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.