---
name: worktree-release-completion
description: Complete an already-implemented feature branch in a separate Git worktree with lockfile-safe frontend gates, responsive UAT, commit, and exact remote-ref verification.
version: 1.0.0
---

# Worktree Release Completion

Use when implementation already exists in a feature worktree and the task is strictly to verify, commit, and publish that branch—without starting a follow-on sprint.

## 1. Immutable preflight

1. Confirm branch name, `HEAD`, expected parent/base, and clean-or-exactly-expected working diff.
2. Inspect both tracked changes **and untracked files**; `git diff --stat` alone omits untracked files.
3. Confirm the remote owner/repository and restrict all remote operations to the named feature branch.
4. Stop if branch/base/diff materially differs from the approved state.

## 2. Lockfile-pinned frontend setup

When explicitly authorized to install only committed dependencies:

1. Verify the target worktree's `package-lock.json` is tracked and valid JSON.
2. Record hashes of `package.json` and lockfile.
3. Run only `npm ci --no-audit --no-fund` from that worktree's frontend directory.
4. Recheck hashes, `git status`, and manifest/lock diff immediately.
5. Do not use `npm install`, alternate package managers, global packages, or browser-binary installs.

## 3. Required verification order

Run the narrow feature tests first, then the complete frontend suite, TypeScript check, production build, and configured lint script. Do not invent a substitute linter if no lint script is configured; report that fact.

Keep backend gates scoped to the request: do not rerun already-green backend suites unless frontend fixes touched backend code.

Treat non-failing legacy warnings separately from failures. Never weaken or skip tests to obtain green output.

### Independent immutable-HEAD gate

When the task is a final independent review rather than implementation/publishing, do not modify files and do not rerun broad suites when the user requests focused probes only. Verify the exact full target/base SHAs and clean status, inspect the complete diff, trace each prior P0/P1/P2 end-to-end through storage, service, API, and UI, and use deterministic synthetic probes for residual contract failures. Recheck HEAD and worktree status after probing.

For cursor-generation mutation probes, financial completeness propagation, one-scan aggregation parity, review facet/eligibility parity, client generation guards, and verdict-only reporting, follow `references/independent-release-gating-review.md`.

## 4. Responsive browser UAT

Use the worktree's own running frontend, not another worktree's server. Verify desktop/laptop, iPad landscape, and approximately 390px mobile.

For an API-dependent UI with no approved runtime data, use synthetic **read-only** responses only and state that UAT is synthetic. Assert:

- no horizontal overflow (`scrollWidth <= viewport width`);
- the new result/status and freshness/quality signals are visually and semantically distinct;
- partial data leaves previously available primary information visible;
- required existing navigation/disabled states remain correct.

Capture screenshots for at least the mobile feature state and do not claim a production-data UAT from mocked data. See `references/worktree-frontend-release-gate.md` for a reusable CDP pattern.

## 5. Finalize safely

For workflow-file credentials, exact-count gates, staged safety ordering, Actions API/job-log diagnosis, and non-force CI recovery, see `references/github-pr-ci-recovery.md`.

1. Update handoff documentation with actual—not planned—test, build, warning, and UAT results.
2. Stage the complete intended file set first, including any explicitly forced ignored file; then run `git diff --cached --check` and the repository safety scan against the exact staged candidate.
3. Inspect the staged name/status list and diff. Never add files after the final safety scan without rerunning it.
4. Before the new commit, perform a non-force feature-branch push dry-run with process-local credentials.
5. Commit once, push only the approved branch with upstream, and verify `refs/heads/<branch>` equals local `HEAD`.
6. After publication, use additive corrective commits; amending or force-pushing published history requires explicit approval.
7. Report local SHA, parent, remote SHA, upstream, ahead/behind, manifest invariance, gates, UAT scope, and final clean status.

## Pitfalls

- Build output and `node_modules` must remain ignored and uncommitted.
- A push preflight must target the feature ref, never `origin HEAD` or `main`.
- Temporary `GIT_ASKPASS` helpers must be removed and their environment variables unset after use.
- If an actual frontend code fix follows a prior review, rerun affected gates and obtain the narrowly required delta review before commit.