Initial commit

skills/phase-task-verification/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: phase-task-verification
+description: Shared branch creation and verification logic for sequential and parallel task execution - handles git operations, HEAD verification, and MODE-specific behavior
+---
+
+# Phase Task Verification
+
+## When to Use
+
+Invoked by `sequential-phase-task` and `parallel-phase-task` after task implementation to create and verify git-spice branch.
+
+## Parameters
+
+- **RUN_ID**: 6-char run ID (e.g., "8c8505")
+- **TASK_ID**: Phase-task (e.g., "1-1")
+- **TASK_NAME**: Short name (e.g., "create-verification-skill")
+- **COMMIT_MESSAGE**: Full commit message
+- **MODE**: "sequential" or "parallel"
+
+## The Process
+
+**Step 1: Stage and create branch**
+```bash
+git add .
+gs branch create {RUN_ID}-task-{TASK_ID}-{TASK_NAME} -m "{COMMIT_MESSAGE}"
+```
+
+**Step 2: Verify based on MODE**
+
+**MODE: sequential** - Verify HEAD points to expected branch:
+```bash
+CURRENT=$(git rev-parse --abbrev-ref HEAD)
+EXPECTED="{RUN_ID}-task-{TASK_ID}-{TASK_NAME}"
+[ "$CURRENT" = "$EXPECTED" ] || { echo "ERROR: HEAD=$CURRENT, expected $EXPECTED"; exit 1; }
+```
+
+**MODE: parallel** - Detach HEAD (makes branch accessible in parent repo):
+```bash
+git switch --detach
+CURRENT=$(git rev-parse --abbrev-ref HEAD)
+[ "$CURRENT" = "HEAD" ] || { echo "ERROR: HEAD not detached ($CURRENT)"; exit 1; }
+```
+
+## Rationalization Table
+
+| Rationalization | Why It's Wrong |
+|----------------|----------------|
+| "Verification is optional" | Silent failures lose work |
+| "Skip detach in parallel mode" | Breaks worktree cleanup |
+| "Branch create errors are obvious" | Silent failures aren't detected until cleanup fails |
+| "Detach can happen later" | Cleanup runs in parent repo - branch must be accessible |
+| "HEAD verification adds overhead" | <100ms cost prevents hours of lost work debugging |
+
+## Error Handling
+
+**git add fails:**
+- **No changes to stage**: Error is expected - task implementation failed or incomplete
+  - Check if task was actually implemented
+  - Verify files were modified in expected locations
+  - Do NOT continue with branch creation
+- **Permission issues**: Git repository permissions corrupted
+  - Check file ownership: `ls -la .git`
+  - Verify worktree is accessible
+  - Escalate to orchestrator
+
+**gs branch create fails:**
+- **Duplicate branch name**: Branch already exists
+  - Check existing branches: `git branch | grep {RUN_ID}-task-{TASK_ID}`
+  - Verify task wasn't already completed
+  - May indicate resume scenario - escalate to orchestrator
+- **Git-spice errors**: Repository state issues
+  - Run `gs repo sync` to fix state
+  - Verify git-spice initialized: `gs ls`
+  - Check for uncommitted changes blocking operation
+- **Invalid branch name**: Name contains invalid characters
+  - Verify RUN_ID is 6-char alphanumeric
+  - Verify TASK_NAME contains only alphanumeric + hyphens
+  - Do NOT sanitize - escalate to orchestrator (indicates data corruption)
+
+**HEAD verification fails (sequential mode):**
+- **Expected**: `gs branch create` should checkout new branch automatically
+- **Actual**: Still on previous branch or detached HEAD
+  - Indicates git-spice behavior change or bug
+  - Do NOT continue - task is not properly staged
+  - Escalate to orchestrator with exact HEAD state
+
+**HEAD verification fails (parallel mode):**
+- **Expected**: `git switch --detach` should detach HEAD
+- **Actual**: Still on branch after detach command
+  - Indicates git version issue or repository corruption
+  - Do NOT continue - cleanup will fail to access branch
+  - Escalate to orchestrator with git version: `git --version`