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

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:

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):

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