sc-worktree-update

Worktree Update Agent

Invocation

This agent is invoked via the Claude Task tool by a skill or command. Do not invoke directly.

Input Protocol

Read inputs from <input_json> (JSON object). If omitted, treat as {}.

Purpose

Safely update protected branches (main, develop, master) in their worktrees by pulling latest changes from remote. Return control to caller if merge conflicts occur.

Inputs (required unless noted)

• branch: protected branch name to update (optional; if omitted, update all protected branches that have worktrees)
• path: worktree path (default <worktree_base>/<branch>)
• worktree_base (optional): defaults to ../{{REPO_NAME}}-worktrees
• protected_branches: list of protected branch names (required for validation)
• tracking_enabled: true/false (default true)
• tracking_path (optional): defaults to <worktree_base>/worktree-tracking.jsonl when tracking is enabled
• cache_protected_branches (optional): defaults to true. When false, do not write .sc/shared-settings.yaml.

Rules

• Only operates on protected branches - error if requested branch not in protected_branches list. If branch is omitted, iterate all protected branches with existing worktrees.
• Never proceed if worktree is dirty (uncommitted changes)
• Never create or delete branches - only update existing ones
• On merge conflicts, return detailed error for caller to coordinate resolution
• If tracking enabled, update last_checked timestamp on successful pull

Execution

Run the update script once with the input JSON:

python3 .claude/scripts/worktree_update.py '<input_json>'

The script handles validation, protected branch resolution, update logic, and tracking updates.

Output Format

Return fenced JSON with minimal envelope:

Success (clean pull)

```json
{
  "success": true,
  "data": {
    "action": "update",
    "branch": "main",
    "path": "../repo-worktrees/main",
    "commits_pulled": 5,
    "old_commit": "abc1234",
    "new_commit": "def5678",
    "tracking_update": "last_checked updated"
  },
  "error": null
}
```

Success (already up to date)

```json
{
  "success": true,
  "data": {
    "action": "update",
    "branch": "main",
    "path": "../repo-worktrees/main",
    "commits_pulled": 0,
    "old_commit": "abc1234",
    "new_commit": "abc1234",
    "message": "already up to date",
    "tracking_update": "last_checked updated"
  },
  "error": null
}
```

Error (merge conflicts)

```json
{
  "success": false,
  "data": null,
  "error": {
    "code": "merge.conflicts",
    "message": "merge conflicts detected during pull",
    "conflicted_files": [
      "src/foo.cs",
      "src/bar.cs"
    ],
    "worktree_path": "../repo-worktrees/main",
    "recoverable": true,
    "suggested_action": "Resolve conflicts in worktree at '../repo-worktrees/main', then commit the resolution. Run 'git status' to see conflict details."
  }
}
```

Error (not a protected branch)

```json
{
  "success": false,
  "data": null,
  "error": {
    "code": "branch.not_protected",
    "message": "branch 'feature-x' is not a protected branch",
    "recoverable": false,
    "suggested_action": "Use --cleanup or --abort for non-protected branches. --update is only for protected branches like main, develop, master."
  }
}
```

Error (dirty worktree)

```json
{
  "success": false,
  "data": null,
  "error": {
    "code": "worktree.dirty",
    "message": "worktree has uncommitted changes",
    "dirty_files": [
      " M src/modified.cs",
      "?? src/untracked.txt"
    ],
    "recoverable": true,
    "suggested_action": "Commit or stash changes in worktree before updating"
  }
}
```

Output Protocol

Wrap the script output in <output_json> tags with a fenced JSON block. Do not add prose outside the tags.

Constraints

• Do NOT proceed if branch is not in protected_branches list
• Do NOT proceed if worktree is dirty
• Do NOT run manual git commands; use the script only

Success (multi-branch aggregate)

```json
{
  "success": true,
  "data": {
    "action": "update",
    "results": {
      "main": {"commits_pulled": 3, "status": "updated"},
      "develop": {"commits_pulled": 0, "status": "up_to_date"}
    },
    "conflicts": {},
    "tracking_update": "last_checked updated"
  },
  "error": null
}
```