refactor(vc-ship): consolidate references from 15 files to 6

skills/vc-ship/SKILL.md

@@ -7,132 +7,75 @@ description: Automates end-to-end git workflows from branch creation through PR
 
 - [workflow-phases.md](references/workflow-phases.md) - Step-by-step phase instructions
 - [commit-format.md](references/commit-format.md) - Commit message formatting rules
-- [rebase-guide.md](references/rebase-guide.md) - History cleanup safety guidelines
-- [phase-0-protocol.md](references/phase-0-protocol.md) - Protected branch detection at start of work
+- [branch-protection.md](references/branch-protection.md) - Protected branch detection (Phase 0 + Phase 6)
 - [phase-5-protocol.md](references/phase-5-protocol.md) - Pre-push quality review checklist
-- [protected-branch-protocol.md](references/protected-branch-protocol.md) - Push-time branch protection
-- [simple-feature.md](references/simple-feature.md) - Single atomic commit example
-- [bug-fix.md](references/bug-fix.md) - Mixed changes separated into logical commits
-- [large-refactor.md](references/large-refactor.md) - Multi-commit refactoring with task tracking
-- [messy-history.md](references/messy-history.md) - Cleaning up WIP commits before push
-- [pr-creation.md](references/pr-creation.md) - Multiple commits to PR with rich description
-- [eval-simple-feature.md](references/eval-simple-feature.md) - Evaluation: simple feature scenario
-- [eval-large-refactor.md](references/eval-large-refactor.md) - Evaluation: large refactor scenario
-- [eval-messy-history.md](references/eval-messy-history.md) - Evaluation: messy history scenario
-- [eval-symlink-edge-case.md](references/eval-symlink-edge-case.md) - Evaluation: symlinked files scenario
+- [rebase-guide.md](references/rebase-guide.md) - History cleanup with `git reset --soft`
+- [examples.md](references/examples.md) - Workflow examples (simple feature, bug fix, refactor, cleanup, PR)
 
 ---
 
 # Git Workflow Skill
 
-This skill provides intelligent, end-to-end Git workflow automation. It analyzes repository changes, organizes them into atomic commits with well-formatted messages, manages branches, cleans up commit history, and helps create pull requests.
-
-## Contents
-
-- [Workflow Overview](#workflow-overview)
-- [Edge Case Quick Reference](#edge-case-quick-reference)
-- [User Interaction Patterns](#user-interaction-patterns)
-- [Summary](#summary)
-- [When NOT to Use](#when-not-to-use)
+Analyzes repository changes, organizes them into atomic commits with well-formatted messages, manages branches, cleans up commit history, and helps create pull requests.
 
 ## Workflow Overview
 
-The skill follows an 8-phase workflow:
-
-0. **Branch Management** - Ensure work is on appropriate branch
-1. **Repository Analysis** - Understand current state and changes
-2. **Organize into Atomic Commits** - Group related changes logically
-3. **Create Commits** - Generate well-formatted commit messages
-4. **Commit History Cleanup** - Optionally reorganize commits before push
-5. **Pre-Push Quality Review** - Analyze commit quality and run tests (MANDATORY)
-6. **Push with Confirmation** - Push changes to remote after approval
-7. **Pull Request Creation** - Optionally create PR with generated description (Summary, Changes, Breaking Changes, Dependencies, Testing, Related Issues sections)
-
-| Phase | Goal                | Key Actions                                              | Reference                                                                                  |
-| ----- | ------------------- | -------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
-| 0     | Branch Management   | Block protected branches, suggest feature branch         | [phase-0-protocol.md](references/phase-0-protocol.md)                                      |
-| 1     | Repository Analysis | Check status, diffs, detect conflicts                    | [workflow-phases.md](references/workflow-phases.md#phase-1-repository-analysis)            |
-| 2     | Organize Commits    | Group related changes, create commit plan                | [workflow-phases.md](references/workflow-phases.md#phase-2-organize-into-atomic-commits)   |
-| 3     | Create Commits      | Stage files, format messages, execute commits            | [commit-format.md](references/commit-format.md)                                            |
-| 4     | History Cleanup     | Squash/reword commits (optional, use `git reset --soft`) | [rebase-guide.md](references/rebase-guide.md)                                              |
-| 5     | Quality Review      | Check message quality, offer tests (**mandatory**)       | [phase-5-protocol.md](references/phase-5-protocol.md)                                      |
-| 6     | Push                | Block protected branches, confirm, push with `-u`        | [protected-branch-protocol.md](references/protected-branch-protocol.md)                    |
-| 7     | Pull Request        | Generate PR title/description, create via `gh`           | [workflow-phases.md](references/workflow-phases.md#phase-7-pull-request-creation-optional) |
+| Phase | Goal              | Key Actions                                                   | Reference                                               |
+| ----- | ----------------- | ------------------------------------------------------------- | ------------------------------------------------------- |
+| 0     | Branch Management | Block protected branches, suggest feature branch              | [branch-protection.md](references/branch-protection.md) |
+| 1     | Repo Analysis     | Check status, diffs, detect conflicts, check branch freshness | [workflow-phases.md](references/workflow-phases.md)     |
+| 2     | Organize Commits  | Group related changes, create commit plan                     | [workflow-phases.md](references/workflow-phases.md)     |
+| 3     | Create Commits    | Stage files, format messages, execute commits                 | [commit-format.md](references/commit-format.md)         |
+| 4     | History Cleanup   | Squash/reword commits (optional, use `git reset --soft`)      | [rebase-guide.md](references/rebase-guide.md)           |
+| 5     | Quality Review    | Check message quality, offer tests (**mandatory**)            | [phase-5-protocol.md](references/phase-5-protocol.md)   |
+| 6     | Push              | Block protected branches, confirm, push with `-u`             | [branch-protection.md](references/branch-protection.md) |
+| 7     | Pull Request      | Generate PR title/description, create via `gh`                | [workflow-phases.md](references/workflow-phases.md)     |
 
 **Key rules:**
 
-- Never use `git rebase -i` (requires interactive input) - use `git reset --soft` instead
+- Never use `git rebase -i` (requires interactive input) — use `git reset --soft` instead
 - Always block pushes to protected branches (main/master/develop/production/staging)
-- Commit messages: ≤72 chars, imperative mood, explain WHY not WHAT
+- Commit messages: imperative mood, ≤72 chars, explain WHY not WHAT
 
 ## Edge Case Quick Reference
 
-| Situation                   | Action                                                                                                                             |
-| --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
-| No changes                  | Inform user, exit gracefully                                                                                                       |
-| Untracked files             | List, ask about inclusion, suggest .gitignore for secrets                                                                          |
-| Large changeset (10+ files) | Suggest splitting into multiple PRs                                                                                                |
-| Detached HEAD               | Alert user, offer to create branch                                                                                                 |
-| Merge conflicts             | STOP, show files, guide resolution                                                                                                 |
-| No remote                   | Detect in Phase 1, complete through Phase 5, then end workflow (skip push/PR)                                                      |
-| Protected branch            | BLOCK, require feature branch (see [phase-0-protocol.md](references/phase-0-protocol.md#scenario-1-uncommitted-changes--blocking)) |
-| Rebase in progress          | Alert, offer continue or abort                                                                                                     |
-| Symlinked files             | Detect in Phase 1, exclude from commit plan, inform user                                                                           |
-| Stale branch base           | Fetch origin, rebase onto `origin/main` if merge-base diverged (prevents SHA conflicts from rebase-merge)                          |
-| Bare git repo               | Not supported — use the repo's wrapper command (e.g., `dot`) for bare repo operations                                              |
+| Situation                   | Action                                                       |
+| --------------------------- | ------------------------------------------------------------ |
+| No changes                  | Inform user, exit gracefully                                 |
+| Untracked files             | List, ask about inclusion, suggest .gitignore for secrets    |
+| Large changeset (10+ files) | Suggest splitting into multiple PRs                          |
+| Detached HEAD               | Alert user, offer to create branch                           |
+| Merge conflicts             | STOP, show files, guide resolution                           |
+| No remote                   | Complete through Phase 5, skip push/PR                       |
+| Protected branch            | BLOCK, require feature branch                                |
+| Rebase in progress          | Alert, offer continue or abort                               |
+| Symlinked files             | Detect in Phase 1, exclude from commit plan, inform user     |
+| Stale branch base           | Fetch origin, rebase onto `origin/main` if diverged          |
+| Bare git repo               | Not supported — use the repo's wrapper command (e.g., `dot`) |
 
 ## User Interaction Patterns
 
-Use **AskUserQuestion** for:
-
-- Branch creation confirmation
-- Commit plan approval
-- Modifications to commit grouping
-- Push confirmation
-- PR creation confirmation
-- Force push warnings
-- Protected branch warnings
-
-Use **TaskCreate/TaskUpdate/TaskList** for:
-
-- Tracking multiple commits to create (3+ commits)
-- Long workflow with many steps
-- Keeping user informed of progress
+Use **AskUserQuestion** for: branch creation, commit plan approval, push confirmation, PR creation, force push warnings, protected branch warnings.
 
-Use **Bash** for:
+Use **TaskCreate** for: tracking multiple commits (3+), long workflows.
 
-- All git commands
-- All gh commands
-- Repository state inspection
+Use **Bash** for: all git and gh commands.
 
-## Summary
-
-This skill automates the entire Git workflow from analyzing changes to creating a PR. It emphasizes:
-
-- **Quality** over speed — well-formatted commits are important
-- **Safety** first — always check state and confirm destructive operations
-- **User control** — ask for approval at key decision points
-- **Education** — explain what's happening and why
-
-**Key workflow patterns**:
+## Key Workflow Patterns
 
 - One logical change = one commit; don't mix unrelated changes
 - Commits should build on each other (add new, migrate, remove old)
 - Clean up messy history before pushing
 - Include tests with the code they test
-- Keep config changes separate unless tightly coupled to code
+- Keep config changes separate unless tightly coupled
 - Always branch per feature; never commit directly to main
-- Explain WHY in commit messages, not just WHAT
 
 ## When NOT to Use
 
-This skill is **not appropriate** for:
-
-- **Simple single-file commits** - Direct `git add && git commit` is faster
-- **Amending the last commit** - Use `git commit --amend` directly
-- **Cherry-picking commits** - Use standard git cherry-pick workflow
-- **Resolving merge conflicts** - User must resolve manually first
-- **Submodule operations** - Complex submodule workflows need manual handling
-- **Force pushing to shared branches** - This skill blocks force pushes for safety
+- **Simple single-file commits** — direct `git add && git commit` is faster
+- **Amending the last commit** — use `git commit --amend` directly
+- **Cherry-picking or reverting** — use standard git workflows
+- **Resolving merge conflicts** — user must resolve manually first
+- **Submodule operations** — needs manual handling
 
-For syncing your local repo (switching to main, pulling latest, cleaning branches), use `vc-sync` instead.
+For syncing your local repo, use `vc-sync` instead.

skills/vc-ship/references/branch-protection.md

@@ -0,0 +1,120 @@
+# Branch Protection
+
+Prevents accidental work on protected branches (main/master/develop/production/staging) at two points: start-of-work (Phase 0) and push-time (Phase 6).
+
+**Philosophy**: Catch mistakes early and block them late — defense in depth.
+
+## Phase 0: Working Directory Protection
+
+Detects uncommitted changes on protected branches before work begins.
+
+### Detection Order
+
+1. Get current branch
+2. Detached HEAD → offer to create branch from current commit
+3. Already on feature/fix/refactor/docs/test/chore/hotfix/release branch → skip Phase 0
+4. Not on protected branch → skip Phase 0
+5. Check for uncommitted changes (staged + unstaged):
+   - **Dirty** → BLOCKING (Scenario 1)
+   - **Clean** → suggestion only (Scenario 2)
+
+### Scenario 1: Uncommitted Changes — BLOCKING
+
+Present 3 options via AskUserQuestion:
+
+**Option 1: Auto-suggest feature branch (Recommended)**
+
+1. Determine branch type from changed files (priority: test → docs → fix → chore → feature)
+2. Generate description from most-changed file (basename, kebab-case, lowercase)
+3. Combine: `{prefix}/{description}` (e.g., `fix/auth-controller`)
+4. Execute: `git stash push -u` → `git checkout -b {name}` → `git stash pop`
+5. On failure: rollback — return to protected branch, delete new branch, restore stash
+
+> If Phase 1 later excludes files (symlinks, secrets), consider renaming: `git branch -m <old> <new>`.
+
+**Option 2: Custom branch name**
+
+Ask user for name. Validate it starts with a standard prefix. If not, offer to prepend `feature/`. Same stash/checkout/pop migration.
+
+**Option 3: Override — continue on protected branch**
+
+- Strong warning (only for tiny config changes or critical hotfixes)
+- Require explicit confirmation
+- Create audit commit documenting the override
+
+### Scenario 2: Clean Working Directory — Suggestion
+
+Friendly tip suggesting a feature branch. Options:
+
+1. Create branch now (placeholder name with date)
+2. Skip — re-check if uncommitted changes appear later
+
+## Phase 6: Push-Time Protection
+
+Detects committed changes about to be pushed to protected branches.
+
+### Detection Order
+
+1. Check for detached HEAD → handle separately
+2. Fetch latest: `git fetch origin $BRANCH`
+3. Check for uncommitted changes → require commit or stash first
+4. Check if current branch is protected → if yes, BLOCK
+
+**Integration**: Phase 5 quality review runs BEFORE this check.
+
+### When Protected Branch Detected
+
+BLOCK the push. Present 3 options:
+
+**Option 1: Create feature branch (Recommended)**
+
+1. Suggest branch name from commit analysis
+2. Show migration plan
+3. Execute: `git checkout -b {feature} origin/{protected}` → cherry-pick commits → `git checkout {protected}` → `git reset --hard origin/{protected}` → `git checkout {feature}`
+4. On cherry-pick failure: abort, return to protected branch, delete feature branch
+5. Push feature branch with `-u`, offer Phase 7
+
+**Option 2: Rename current branch**
+
+1. Suggest name based on commits
+2. Execute: `git branch -m {protected} {feature}` → `git checkout -b {protected} origin/{protected}` → `git checkout {feature}`
+3. Push renamed branch, offer Phase 7
+
+**Option 3: Emergency override (hotfix only)**
+
+Valid reasons: security vulnerability, production down, critical data loss.
+
+1. Require justification (freeform text) and explicit confirmation
+2. Create audit commit documenting the override
+3. Push with final warning
+4. Recommend creating a documentation PR afterward
+
+### Force Push to Protected Branch — ABSOLUTELY BLOCKED
+
+No override. If `git rev-list --count HEAD..origin/$BRANCH` shows remote has commits we don't:
+
+- Show absolute block message
+- Explain: rewrites shared history, breaks others, can lose commits
+- Direct user to handle manually
+- Exit workflow
+
+## Edge Cases
+
+| Situation                   | Action                                                   |
+| --------------------------- | -------------------------------------------------------- |
+| Already on feature branch   | Skip Phase 0 entirely                                    |
+| Detached HEAD               | Offer: create branch or return to main                   |
+| Hotfix/release branch       | Allow push with warning; require PR to main              |
+| Stash pop conflicts         | Rollback, show manual recovery steps                     |
+| No remote                   | Proceed with local branch creation; skip Phase 6         |
+| Cherry-pick fails           | Abort, return to protected branch, delete feature branch |
+| Rename fails                | Check `git branch` to find commits, keep that branch     |
+| Some commits already pushed | Warn, migrate only new commits                           |
+
+## Rollback
+
+Recovery tools: `git status`, `git log --oneline -10`, `git branch -a`, `git reflog`.
+
+- **Cherry-pick fails**: abort, return to protected branch — commits unchanged
+- **Reset fails after cherry-pick**: commits on both branches safely — push feature, reset protected manually
+- **Override push fails**: audit commit local — retry push, or `git reset --soft HEAD~1`