| name | bundle-extract |
| description | Copy artifacts from a worktree to a main-tree archive directory with per-file sha256 verification. |
Bundle extract
When to invoke
After every evidence-only-output dispatch completes (before merging the worktree back to main), and during any bundle-archival workflow that moves artifacts out of an agent worktree into a main-tree perf-evidence archive. The sha256 round-trip catches transport corruption and silent races.
What it does
Invokes tools/bundle-extract.sh with a source worktree path, a destination archive directory, and a comma-separated manifest of paths (relative to source). For each path it copies the file to the destination, computes sha256 at both ends, and reports a per-file match flag plus an aggregate all_match boolean. Per ADR-016 §6 Worktree Retention Discipline, the marker-commit primitive keeps the worktree alive long enough for this extractor to run against it.
Contract with primitive
- Primitive:
tools/bundle-extract.sh
- Flags / inputs:
--source <worktree-path> (required)
--dest <dest-dir> (required; created if absent)
--manifest <comma-separated-paths> (required; paths relative to --source)
--json (output is JSON regardless; flag retained for symmetry)
- Output shape:
{
"extracted": [
{"file": "<relpath>", "sha256_source": "<hash>", "sha256_dest": "<hash>", "match": true},
...
],
"all_match": true
}
- Exit semantics: 0 if
all_match is true; 1 on any mismatch or missing source file.
Example invocation
tools/bundle-extract.sh \
--source .claude/worktrees/agent-xxxx \
--dest apps/amnesia/docs/perf-evidence/2026-05-11/o4fp.6 \
--manifest manifest.json,raw-metrics.json,summary.md
Halt conditions
all_match is false — sha256 mismatch indicates corruption or a race; halt + surface the per-file evidence before relying on the archive.
- A source file in the manifest is missing — halt + surface the missing path.
Related
- ADR-016 §6 Worktree Retention Discipline: codifies the marker-commit-then-extract handoff.
- Sibling skill:
bundle-extract is normally paired with marker-commit.sh upstream (commit keeps worktree alive) and with closure-attest.sh downstream (records the archived paths in the attestation).