reachable-wip-via-temporary-refs

name	reachable-wip-via-temporary-refs
description	Capture in-flight WIP via `git stash create`, make it reachable through temporary refs, and tear down the refs after bundling finishes.
metadata	{"author":"ychampion"}

SKILL: Reachable WIP Via Temporary Refs

Domain: safety-worktrees
Trigger: Apply when bundling or seeding a repository and you want to include uncommitted work without disturbing the working tree or leaving dangling refs. Source Pattern: Distilled from reviewed repo-safety, packaging, and worktree-management patterns.

Core Method

Call git stash create to materialize the working tree and index into a temporary commit while leaving the workspace untouched. If the command returns a SHA then advertise it via a short-lived ref such as refs/seed/stash so downstream tooling (bundle list-heads, receivers) can reach those objects; treat an empty response as “no WIP,” log both success and error cases, and clean up the temporary ref after the upload completes or earlier runs leave stale pointers.

Key Rules

• Always run the ref cleanup loop (refs/seed/stash, refs/seed/root) before bundling so previous runs do not influence new bundles or leak stale WIP markers.
• Accept that git stash create can fail non-fatally; log the stderr, skip ref creation, but continue bundling the committed tree.
• Only call git update-ref refs/seed/stash <sha> when the stash SHA is non-empty; otherwise the ref would dereference to nothing.
• Record a boolean flag (hasWip) when the temporary stash exists so telemetry and later steps can know whether to expect extra objects.
• After the bundle (and after the finally block), delete the temporary refs even if the upstream run failed to keep the user repo clean.

Example Application

When writing an upload helper for a CLI that seeds a remote CCR process, use this skill to wrap the git stash create/git update-ref pair, expose hasWip, and ensure the finally block always runs git update-ref -d refs/seed/stash before returning.

Anti-Patterns (What NOT to do)

• Do not rely on the regular stash stack (refs/stash) because git bundle should not touch the user-visible stack; git stash create avoids a working-tree mutation.
• Do not advertise an empty SHA: bundlers that list heads will fail to find objects.
• Do not skip cleanup: leaving refs/seed/stash behind pollutes the repo and may cause future bundling runs to include WIP twice.