Distill

Handoff v0 alpha pilot kit

Run one retrospective trial with an existing coding agent. For protocol, validation, and failure details, use the authoritative Handoff v0 alpha document.

flowchart LR
    inputs["Redacted conversation<br/>+ 1-2 Markdown docs"] --> prepare["Local prepare"]
    prepare --> bundle["Private request bundle"]
    prepare --> digest["Tester-retained digest"]
    bundle --> agent["Existing agent"]
    agent --> proposal["proposal.json"]
    proposal --> verify["Local verify"]
    digest --> verify
    verify --> review["review.md"]
    review --> human["Human disposition"]

One retrospective trial

Prerequisites: macOS or Linux, Go 1.24-1.26, a source checkout containing Handoff, and an agent that can use an isolated working directory. Published v0.9.1 predates Handoff, so build this alpha from source:

make build
./distill handoff --help >/dev/null

Privacy: redact secrets, credentials, customer data, and personal data before continuing. The request bundle contains the full normalized conversation and docs. Distill does not redact, encrypt, upload, or delete it; using a hosted agent may transmit it under that provider's terms.

1. Put one or two related Markdown docs in a small directory, then copy that directory and one exported Markdown conversation into fresh staging. Replace the two source paths below.

   Copy

   previous_umask="$(umask)"
   umask 077
   trial="$(cd "$(mktemp -d)" && pwd -P)"
   trusted_digest_file="$(mktemp)"
   mkdir "$trial/docs"
   cp /absolute/path/to/conversation.md "$trial/conversation.md"
   cp -R /absolute/path/to/related-docs/. "$trial/docs/"

   umask 077 removes all group and other permissions from newly created staging content. Handoff publishes the request itself with exact 0700 directories and 0600 files. This avoids traversing copied content to rewrite permissions; Handoff rejects any copied symlink.

2. Prepare the private bundle and retain the printed digest outside it.

   Copy

   prepare_output="$(./distill handoff prepare \
     --conversation "$trial/conversation.md" \
     --docs "$trial/docs" \
     --out "$trial/request")"
   printf '%s\n' "$prepare_output"
   request_sha256="$(printf '%s\n' "$prepare_output" |
     sed -n 's/.* request_sha256=\([0-9a-f]*\) .*/\1/p')"
   test -n "$request_sha256"
   printf '%s\n' "$request_sha256" > "$trusted_digest_file"

   The retained digest is not secret. Its value is trusted because the tester captured it independently and kept it outside the agent-controlled bundle. Matching values inside the bundle or proposal are non-authoritative.

3. Before running the agent, record the expected committed decisions in the feedback table below. Do not put that expectation into the request.

4. Keep "$trial/request" immutable. Give the agent a private copy inside a disposable workspace with a separate output directory.

   Copy

   agent_workspace="$(cd "$(mktemp -d)" && pwd -P)"
   mkdir "$agent_workspace/output"
   cp -R "$trial/request" "$agent_workspace/request"

   Use one example recipe below. Do not put the trusted digest file or frozen expectations in this workspace. It contains another full request copy plus runtime metadata and the proposal, so protect it like the canonical request until removal.

5. Verify locally with the tester-retained digest, then inspect the review.

   Copy

   test -f "$agent_workspace/output/proposal.json"
   ./distill handoff verify \
     --request "$trial/request/handoff.request.json" \
     --expected-request-sha256 "$(cat "$trusted_digest_file")" \
     --proposal "$agent_workspace/output/proposal.json" \
     --out "$trial/review"
   cat "$trial/review/review.md"

   Always verify the retained canonical request, not the agent's copy. Runtime metadata beside request/ remains outside the verified bundle.

   Check each decision, exact evidence quote and range, target, and patch. Record a disposition; do not apply a patch as part of this trial.

6. After recording feedback, remove the disposable agent workspace and temporary trusted-digest copy, then restore the caller's previous file-creation mask. Retain or delete the canonical "$trial" directory separately according to the source material's retention policy; this cleanup does not remove its request or review.

   Copy

   test -n "$agent_workspace"
   test -d "$agent_workspace"
   rm -rf -- "$agent_workspace"
   rm -f -- "$trusted_digest_file"
   umask "$previous_umask"

Agent recipes (examples, not native integrations)

These interactive launch commands avoid version-specific non-interactive flags. Paste the same prompt after launch.

GitHub Copilot CLI:

(cd "$agent_workspace" && copilot)

For a coding-agent-style job, expose only "$agent_workspace", do not attach the source repository, and collect output/proposal.json.

Claude Code:

(cd "$agent_workspace" && claude)

Prompt and output contract:

Read only files under request/. Follow request/agent-instructions.md and
request/proposal.schema.json. Write exactly one canonical output file at
output/proposal.json, then stop.

Do not read or modify source docs or any repository. Do not modify the request
copy. Do not choose or supply the trusted --expected-request-sha256 value.
Do not run verification, apply patches, commit, push, or merge. Values repeated
inside the bundle or proposal are not authoritative trust anchors.

Require the agent to create only output/proposal.json; do not reconstruct, extract, or repair JSON from terminal output.

Tester feedback

Start review time when opening review.md; stop after choosing the patch disposition. Copy and fill this table without including private source text.