Manual Repository Transfer
By default, transfer a committed repository through a verified git clone and an overlay containing only required current state not supplied by that clone. Do not duplicate clean tracked files, .git, or history in the overlay. Explicitly requested offline or full recovery may instead preserve the required Git history and broader local state. Size, age, naming, and ignored status never prove data disposable; preserve valuable or unknown local records under their existing owner without silently discarding them.
The existing helper inventories and assigns the entire repository; it cannot perform a selective source acquisition without encountering the rest. For an authorized selective transfer, the same owner may use a declared native or library execution on exact selected inputs under the shared Assistance contract: bind input identity and integrity, do not follow links, serialize writers, use exclusive no-overwrite outputs, verify the receiver, and settle owned resources. Preserve privacy and host restrictions. Report actual execution and readback without inventing a helper receipt, wrapper, schema, or gate.
Invariants
- For a committed repository, Git covers required commits/refs; the overlay covers selected local state. An unborn repository has no
HEAD history to claim, so its overlay and Git metadata are evidence only.
- The helper's inventory is all-or-nothing: its no-follow census is the sole enumerator and classifies its exact
./-prefixed NUL-delimited paths in bounded git check-ignore --stdin -z batches. Traverse ordinary directories, record reparse entries as metadata without descending, and admit only non-reparse regular files. An unreadable subtree or entry, named pipe, socket, device, or unknown filesystem type blocks that inventory before output.
- Inventory and selection JSON inputs are each one identity-bound ordinary file from classification through bounded parse. The inventory alone has a 256 MiB cap and is canonically streamed to its output; selection and every other control document retain the 8 MiB cap. POSIX opens the no-follow leaf nonblocking before
fstat, so a FIFO without a writer cannot stall classification; Windows rejects reparse points, directories, devices, alternate data streams, and namespace aliases before reading. Type, size, held identity, parent identity, and pathname binding must remain stable through parse.
- Each selected ZIP payload is one identity-bound ordinary file from no-follow, nonblocking classification through chunked hashing and ZIP emission. The helper streams the already-open descriptor, never reopens the pathname for content, and requires the held leaf, parents, size, digest, and final pathname binding to remain stable before close; FIFOs, sockets, links, directories, devices, alternate data streams, and reparse points fail promptly.
- The helper's manifest assigns every local file or link one non-overlapping disposition.
- ZIP contains regular-file bytes. Restricted data and links use content-bound external receipts.
- A Lead or human selects and verifies one explicit absolute Git executable outside the repository before invoking the helper; the helper never resolves
git from PATH, the current directory, or an environment override.
- Before the first process launch, the helper resolves a repository alias or subdirectory to the nearest physical root with a strict ordinary
.git directory or gitfile marker, then binds one physically canonical, reparse-free Git executable outside that root by identity and SHA-256. It discards the alias for process working directories, requires Git's reported top-level to match, and rechecks the executable around later Git launches. Failures use TRANSFER-REPOSITORY-BOUNDARY-INVALID, TRANSFER-GIT-BINDING-INVALID, TRANSFER-GIT-ROOT-MISMATCH, or TRANSFER-GIT-BINDING-DRIFT; a same-user replacement after the final pre-open check remains outside this guarantee.
- UTF-8
surrogateescape path bytes round-trip in canonical JSON by escaping only U+DC80..U+DCFF; ordinary Unicode keeps the existing Version 1 bytes and digests, while every other lone surrogate fails as TRANSFER-PATH-ENCODING-INVALID. Such paths are hostile metadata-only entries requiring one exact external receipt; payload, deletion, ancestor inclusion, or ZIP placement fails as TRANSFER-HOSTILE-PATH-EXTERNAL-REQUIRED.
- The helper verifies and previews; only a repository/lifecycle owner applies an authorized deletion plan.
inventory and bundle refuse an existing output by default; only their explicit --force replaces one output. The helper binds the ordinary parent and, when present, the exact ordinary output identity before generation. After the completed temporary is flushed and synchronized, an absent output is published by one atomic no-replace Windows rename or POSIX descriptor-relative link followed by temporary unlink, while a forced existing output is published by rechecking that same parent and exact ordinary identity immediately before one os.replace. Raced outputs, links, reparse points, directories, unsafe ancestors, and identity drift fail closed. A same-user substitution after the final identity check is outside the 1.x guarantee. verify and cleanup never accept --force.
- Any Git, lifecycle, recovery, or tool-state mutation invalidates the inventory. Rebuild.
Receiving from repository cleanup
When $repo-cleanup transfer mode invokes this skill, accept a current-invocation RepoCleanupReportV1, bound to the same physical repository identity and HEAD/unborn state, only when it has PASS or its sole nonpassing cause is the shared host-policy-denial exception for explicitly deferred, freshly proven harmless empty agent-owned directory residue. In the exception case, cleanup and zero-residue predicates remain fail; every transfer gate must independently pass, transfer must not depend on the directory, and the final inventory and selection process must explicitly account for the deferred target and prove that no valuable data is silently omitted. Then own exactly cleanup PASS or qualifying deferred residue accounted -> final inventory -> bundle -> trusted verify -> post-transfer classification. This skill does not run cleanup again, and neither the cleanup report nor the exception authorizes bundle creation, copying, deletion, wipe, publication, or removal. Report the exact residue and resume condition in the transfer handoff. A direct explicit $manual-repo-transfer request without cleanup intent continues to enter this skill directly.
Consume Root Lead's current original-target classification under the shared repository-cleanup rule, including requested repository roots/registered worktrees, material task dispositions and required Git outcomes. This skill verifies preservation and supplies its evidence; it does not decide task closure or Git settlement. For a cleanup-and-transfer target with a required open obligation, even a byte-verified ZIP is a provisional recovery snapshot, not final handoff; name the unfinished obligation, owning cause, next action and resume point. Preserve unrelated/unknown state without treating every active item as a blocker. An explicit direct transfer without cleanup or recovery-copy request may copy unfinished work and complete its own copy outcome, while reporting the unfinished broader target as provisional; no forced clean tree, publication or automatic parking follows.
Full-inventory helper workflow
Read repository governance and validation docs. Discover dot-directories, ignored/untracked state, and self-ignored workspaces. A clean git status is insufficient. Query owning tools through API/MCP; validate stored config/memory against the active project. Use local-state categories.
Discover requested project indices, project settings, and configuration through their available owner, Model Context Protocol (MCP), or tool. Record whether each is portable, requires an external backup receipt, or must be rebuilt on the receiver. Do not create indices, install providers, or transfer global authentication or provider credentials as project state.
Have the owning roles finish or explicitly freeze all authorized source, Git, lifecycle, and recovery changes that must reach the receiver. Promote required scratch results to canonical artifacts; retain raw scratch only while recovery requires it. Preserve selected dirty, staged, untracked, and local-only Git state; do not clean, reset, commit, or publish merely to simplify transfer. Run an earlier full inventory, bundle, and verification rehearsal only when a recorded actual risk justifies it; its output is non-handoff evidence, and every later mutation invalidates it.
Quiesce writers. After the last source, Git, or lifecycle change, refresh or revalidate each requested index, project setting, and configuration with its documented owner command; require fresh successful output and settle its writers. Preserve fresh portable state in the overlay. Preserve nonportable state through its appropriate backup plus an explicit receiver rebuild. A failed refresh is not fresh, and any change after freeze invalidates index freshness and the inventory snapshot. Freeze this state, then record repository history state, HEAD when committed, refs, credential-redacted remotes, dirty/index state, reparse points, lifecycle state, stashes, registered worktrees, and Git recovery surfaces. The helper excludes .git; audit it separately. Launch every inventory, bundle, verification, and diagnostic import with python -B and with PYTHONDONTWRITEBYTECODE=1 set in that subprocess before imports; do not change an interpreter, process-global, or user environment. -B prevents new bytecode but does not remove existing caches; classification and cleanup ownership are unchanged.
Generate the final inventory outside the worktree:
python -B <skill>/scripts/repo_transfer.py inventory --repo <repo> --git-executable <absolute-git-executable> --output <inventory.json> [--force]
Create a selection using the manifest schema. Assign every required entry exactly one disposition:
| Disposition |
Meaning |
include |
Preserve ordinary unique local state in the ZIP. |
external |
Preserve restricted data or link metadata in separately verified storage. |
delete |
Add a content-bound, evidence-backed item to the preview-only deletion plan. |
Rows may not overlap. Ambiguity means include. Never follow a link; classify its target separately.
For a committed repository, use the selected remote's local-tracking evidence plus policy-required server probes. Otherwise create and verify a Git bundle; copying .git is not the default. For an unborn repository, select only gitStrategy.mode: none: no remote can cover a nonexistent HEAD, and a standard Git bundle cannot preserve nonexistent history.
Build and source-verify the overlay from that final inventory:
python -B <skill>/scripts/repo_transfer.py bundle --repo <repo> --git-executable <absolute-git-executable> --inventory <inventory.json> --selection <selection.json> --output <transfer.zip> [--force]
python -B <skill>/scripts/repo_transfer.py verify --bundle <transfer.zip> --git-executable <absolute-git-executable> --inventory <inventory.json> --selection <selection.json> --source <repo>
Store the artifact independently from the source PC. If the receiver is unavailable, rehearse a clean local restore of the final artifact before authorizing a wipe. Generate the deletion preview with cleanup; after separate authorization, the owner applies it and proves the resulting census. Only this post-freeze, verified artifact is the handoff.
On the receiver: verify the ZIP against its separate SHA-256; restore Git and regular-file overlay entries; run payload/source verification; restore external artifacts through receipts; regenerate dependencies/caches; run repository checks. For an unborn inventory, the ZIP preserves file bytes plus staged/unstaged/status evidence but does not recreate index equivalence or fabricate an initial commit. Retain transfer artifacts until acceptance; settle temporary scratch through its producer.
Stop conditions
Unclassified or incompletely enumerated state, unreadable or unsupported filesystem entries, overlap, drift, unsafe archive members, missing hashes, live writers, path escapes, unexpected links, unverifiable receipts, or failed restore checks block cleanup and wipe. Copy success, listing, size, or callback is not integrity evidence. Transfer preparation never grants publication, wipe, or deletion authority.
Terms and Abbreviations
- Local-state overlay: selected state outside verified Git history.
- Reparse point: Windows link-like filesystem object, including a junction.
- SHA-256: Secure Hash Algorithm 256-bit digest.
1---2name: manual-repo-transfer3description: Use when a Git repository moves machines without losing dirty work, ignored task memory, or local runtime evidence.4metadata:5 source: https://skillmd.com/skills/applicate2628/manual-repo-transfer6---78# Manual Repository Transfer910By default, transfer a committed repository through a verified `git clone` and an overlay containing only required current state not supplied by that clone. Do not duplicate clean tracked files, `.git`, or history in the overlay. Explicitly requested offline or full recovery may instead preserve the required Git history and broader local state. Size, age, naming, and ignored status never prove data disposable; preserve valuable or unknown local records under their existing owner without silently discarding them.1112The existing helper inventories and assigns the entire repository; it cannot perform a selective source acquisition without encountering the rest. For an authorized selective transfer, the same owner may use a declared native or library execution on exact selected inputs under the shared Assistance contract: bind input identity and integrity, do not follow links, serialize writers, use exclusive no-overwrite outputs, verify the receiver, and settle owned resources. Preserve privacy and host restrictions. Report actual execution and readback without inventing a helper receipt, wrapper, schema, or gate.1314## Invariants1516- For a committed repository, Git covers required commits/refs; the overlay covers selected local state. An unborn repository has no `HEAD` history to claim, so its overlay and Git metadata are evidence only.17- The helper's inventory is all-or-nothing: its no-follow census is the sole enumerator and classifies its exact `./`-prefixed NUL-delimited paths in bounded `git check-ignore --stdin -z` batches. Traverse ordinary directories, record reparse entries as metadata without descending, and admit only non-reparse regular files. An unreadable subtree or entry, named pipe, socket, device, or unknown filesystem type blocks that inventory before output.18- Inventory and selection JSON inputs are each one identity-bound ordinary file from classification through bounded parse. The inventory alone has a 256 MiB cap and is canonically streamed to its output; selection and every other control document retain the 8 MiB cap. POSIX opens the no-follow leaf nonblocking before `fstat`, so a FIFO without a writer cannot stall classification; Windows rejects reparse points, directories, devices, alternate data streams, and namespace aliases before reading. Type, size, held identity, parent identity, and pathname binding must remain stable through parse.19- Each selected ZIP payload is one identity-bound ordinary file from no-follow, nonblocking classification through chunked hashing and ZIP emission. The helper streams the already-open descriptor, never reopens the pathname for content, and requires the held leaf, parents, size, digest, and final pathname binding to remain stable before close; FIFOs, sockets, links, directories, devices, alternate data streams, and reparse points fail promptly.20- The helper's manifest assigns every local file or link one non-overlapping disposition.21- ZIP contains regular-file bytes. Restricted data and links use content-bound external receipts.22- A Lead or human selects and verifies one explicit absolute Git executable outside the repository before invoking the helper; the helper never resolves `git` from PATH, the current directory, or an environment override.23- Before the first process launch, the helper resolves a repository alias or subdirectory to the nearest physical root with a strict ordinary `.git` directory or gitfile marker, then binds one physically canonical, reparse-free Git executable outside that root by identity and SHA-256. It discards the alias for process working directories, requires Git's reported top-level to match, and rechecks the executable around later Git launches. Failures use `TRANSFER-REPOSITORY-BOUNDARY-INVALID`, `TRANSFER-GIT-BINDING-INVALID`, `TRANSFER-GIT-ROOT-MISMATCH`, or `TRANSFER-GIT-BINDING-DRIFT`; a same-user replacement after the final pre-open check remains outside this guarantee.24- UTF-8 `surrogateescape` path bytes round-trip in canonical JSON by escaping only `U+DC80..U+DCFF`; ordinary Unicode keeps the existing Version 1 bytes and digests, while every other lone surrogate fails as `TRANSFER-PATH-ENCODING-INVALID`. Such paths are hostile metadata-only entries requiring one exact external receipt; payload, deletion, ancestor inclusion, or ZIP placement fails as `TRANSFER-HOSTILE-PATH-EXTERNAL-REQUIRED`.25- The helper verifies and previews; only a repository/lifecycle owner applies an authorized deletion plan.26- `inventory` and `bundle` refuse an existing output by default; only their explicit `--force` replaces one output. The helper binds the ordinary parent and, when present, the exact ordinary output identity before generation. After the completed temporary is flushed and synchronized, an absent output is published by one atomic no-replace Windows rename or POSIX descriptor-relative link followed by temporary unlink, while a forced existing output is published by rechecking that same parent and exact ordinary identity immediately before one `os.replace`. Raced outputs, links, reparse points, directories, unsafe ancestors, and identity drift fail closed. A same-user substitution after the final identity check is outside the 1.x guarantee. `verify` and `cleanup` never accept `--force`.27- Any Git, lifecycle, recovery, or tool-state mutation invalidates the inventory. Rebuild.2829## Receiving from repository cleanup3031When `$repo-cleanup` transfer mode invokes this skill, accept a current-invocation `RepoCleanupReportV1`, bound to the same physical repository identity and `HEAD`/unborn state, only when it has `PASS` or its sole nonpassing cause is the shared host-policy-denial exception for explicitly deferred, freshly proven harmless empty agent-owned directory residue. In the exception case, cleanup and zero-residue predicates remain `fail`; every transfer gate must independently pass, transfer must not depend on the directory, and the final inventory and selection process must explicitly account for the deferred target and prove that no valuable data is silently omitted. Then own exactly `cleanup PASS or qualifying deferred residue accounted -> final inventory -> bundle -> trusted verify -> post-transfer classification`. This skill does not run cleanup again, and neither the cleanup report nor the exception authorizes bundle creation, copying, deletion, wipe, publication, or removal. Report the exact residue and resume condition in the transfer handoff. A direct explicit `$manual-repo-transfer` request without cleanup intent continues to enter this skill directly.3233Consume Root Lead's current original-target classification under the shared repository-cleanup rule, including requested repository roots/registered worktrees, material task dispositions and required Git outcomes. This skill verifies preservation and supplies its evidence; it does not decide task closure or Git settlement. For a cleanup-and-transfer target with a required open obligation, even a byte-verified ZIP is a provisional recovery snapshot, not final handoff; name the unfinished obligation, owning cause, next action and resume point. Preserve unrelated/unknown state without treating every active item as a blocker. An explicit direct transfer without cleanup or recovery-copy request may copy unfinished work and complete its own copy outcome, while reporting the unfinished broader target as provisional; no forced clean tree, publication or automatic parking follows.3435## Full-inventory helper workflow36371. Read repository governance and validation docs. Discover dot-directories, ignored/untracked state, and self-ignored workspaces. A clean `git status` is insufficient. Query owning tools through API/MCP; validate stored config/memory against the active project. Use [local-state categories](references/manifest-schema.md#local-state-categories).382. Discover requested project indices, project settings, and configuration through their available owner, Model Context Protocol (MCP), or tool. Record whether each is portable, requires an external backup receipt, or must be rebuilt on the receiver. Do not create indices, install providers, or transfer global authentication or provider credentials as project state.393. Have the owning roles finish or explicitly freeze all authorized source, Git, lifecycle, and recovery changes that must reach the receiver. Promote required scratch results to canonical artifacts; retain raw scratch only while recovery requires it. Preserve selected dirty, staged, untracked, and local-only Git state; do not clean, reset, commit, or publish merely to simplify transfer. Run an earlier full inventory, bundle, and verification rehearsal only when a recorded actual risk justifies it; its output is non-handoff evidence, and every later mutation invalidates it.404. Quiesce writers. After the last source, Git, or lifecycle change, refresh or revalidate each requested index, project setting, and configuration with its documented owner command; require fresh successful output and settle its writers. Preserve fresh portable state in the overlay. Preserve nonportable state through its appropriate backup plus an explicit receiver rebuild. A failed refresh is not fresh, and any change after freeze invalidates index freshness and the inventory snapshot. Freeze this state, then record repository history state, `HEAD` when committed, refs, credential-redacted remotes, dirty/index state, reparse points, lifecycle state, stashes, registered worktrees, and Git recovery surfaces. The helper excludes `.git`; audit it separately. Launch every inventory, bundle, verification, and diagnostic import with `python -B` and with `PYTHONDONTWRITEBYTECODE=1` set in that subprocess before imports; do not change an interpreter, process-global, or user environment. `-B` prevents new bytecode but does not remove existing caches; classification and cleanup ownership are unchanged.415. Generate the final inventory outside the worktree:4243 ```text44 python -B <skill>/scripts/repo_transfer.py inventory --repo <repo> --git-executable <absolute-git-executable> --output <inventory.json> [--force]45 ```46476. Create a selection using [the manifest schema](references/manifest-schema.md). Assign every required entry exactly one disposition:4849 | Disposition | Meaning |50 | --- | --- |51 | `include` | Preserve ordinary unique local state in the ZIP. |52 | `external` | Preserve restricted data or link metadata in separately verified storage. |53 | `delete` | Add a content-bound, evidence-backed item to the preview-only deletion plan. |5455 Rows may not overlap. Ambiguity means `include`. Never follow a link; classify its target separately.567. For a committed repository, use the selected remote's local-tracking evidence plus policy-required server probes. Otherwise create and verify a Git bundle; copying `.git` is not the default. For an unborn repository, select only `gitStrategy.mode: none`: no remote can cover a nonexistent `HEAD`, and a standard Git bundle cannot preserve nonexistent history.578. Build and source-verify the overlay from that final inventory:5859 ```text60 python -B <skill>/scripts/repo_transfer.py bundle --repo <repo> --git-executable <absolute-git-executable> --inventory <inventory.json> --selection <selection.json> --output <transfer.zip> [--force]61 python -B <skill>/scripts/repo_transfer.py verify --bundle <transfer.zip> --git-executable <absolute-git-executable> --inventory <inventory.json> --selection <selection.json> --source <repo>62 ```63649. Store the artifact independently from the source PC. If the receiver is unavailable, rehearse a clean local restore of the final artifact before authorizing a wipe. Generate the deletion preview with `cleanup`; after separate authorization, the owner applies it and proves the resulting census. Only this post-freeze, verified artifact is the handoff.6510. On the receiver: verify the ZIP against its separate SHA-256; restore Git and regular-file overlay entries; run payload/source verification; restore external artifacts through receipts; regenerate dependencies/caches; run repository checks. For an unborn inventory, the ZIP preserves file bytes plus staged/unstaged/status evidence but does not recreate index equivalence or fabricate an initial commit. Retain transfer artifacts until acceptance; settle temporary scratch through its producer.6667## Stop conditions6869Unclassified or incompletely enumerated state, unreadable or unsupported filesystem entries, overlap, drift, unsafe archive members, missing hashes, live writers, path escapes, unexpected links, unverifiable receipts, or failed restore checks block cleanup and wipe. Copy success, listing, size, or callback is not integrity evidence. Transfer preparation never grants publication, wipe, or deletion authority.7071## Terms and Abbreviations7273- Local-state overlay: selected state outside verified Git history.74- Reparse point: Windows link-like filesystem object, including a junction.75- SHA-256: Secure Hash Algorithm 256-bit digest.