maestro-fork

<purpose>
Create or sync a milestone-level git worktree for parallel development.
Supports `--sync` mode to pull latest main changes into an active worktree.
</purpose>

<required_reading>
@~/.maestro/workflows/fork.md
</required_reading>

<deferred_reading>
- [worktrees.json](~/.maestro/templates/worktrees.json) — read when updating registry
- [worktree-scope.json](~/.maestro/templates/worktree-scope.json) — read when writing scope marker
</deferred_reading>

<context>
$ARGUMENTS -- milestone number and optional flags.

Modes (`Fork` / `Sync`), flags (`-m`, `--base`, `--sync`), milestone resolution, worktree layout, and artifact scoping are defined in workflow `fork.md`.
</context>

<execution>
Follow '~/.maestro/workflows/fork.md' completely.

Fork and sync algorithm steps are defined in workflow `fork.md`.

### Phase Gates (MANDATORY, BLOCKING)

**Fork mode:**

**GATE 1: Validation → Worktree Creation**
- REQUIRED: Milestone resolved from state.json.milestones[].
- REQUIRED: No existing active worktree for this milestone (E008).
- REQUIRED: Not running inside a worktree (E003).
- BLOCKED if: milestone not found (E006), already forked (E008), or running inside worktree (E003).

**GATE 2: Worktree Creation → Artifact Copy**
- REQUIRED: Git worktree created with branch (`milestone/{slug}`).
- REQUIRED: Shared `.workflow/` files copied (project.md, roadmap.md, config.json, specs/).
- BLOCKED if missing: worktree creation failed or shared files not copied — do not proceed to artifact scoping.

**GATE 3: Artifact Copy → Completion**
- REQUIRED: `worktree-scope.json` written with milestone scope.
- REQUIRED: Scoped `state.json` written (only this milestone's artifacts).
- REQUIRED: `worktrees.json` registry updated in main worktree.
- BLOCKED if missing: scope marker, scoped state, or registry update absent — worktree is unusable without these.

**Sync mode:**

**GATE: Sync → Completion**
- REQUIRED: Git merge main into worktree branch completed.
- REQUIRED: Shared artifacts re-copied.
- BLOCKED if: merge has unresolved conflicts or shared artifacts failed to copy.

</execution>

<completion>
### Next-step routing

| Condition | Suggestion |
|-----------|-----------|
| Fork complete | `cd {wt.path} && /maestro-analyze` |
| Fork + automated | `maestro delegate "run full lifecycle for milestone" --cd {wt.path} --mode write` |
| Fork + status check | Skill({ skill: "manage-status" }) |
| Sync complete | Resume work in worktree |
| Sync conflicts found | Resolve manually, then retry |
</completion>

<error_codes>
| Code | Severity | Condition | Recovery |
|------|----------|-----------|----------|
| E001 | error | Project not initialized | Run maestro-init first |
| E002 | error | No roadmap found | Run maestro-roadmap first |
| E003 | error | Running inside a worktree | Run from main worktree |
| E004 | error | No milestone number provided | Provide `-m <N>` |
| E005 | error | No milestones defined in state.json | Run maestro-roadmap first |
| E006 | error | Milestone number out of range | Check available milestones |
| E007 | error | No active worktree for milestone (--sync) | Check worktrees.json |
| E008 | error | Milestone already has active worktree | Merge or cleanup first |
</error_codes>

<success_criteria>
Fork mode:
- [ ] Milestone resolved from state.json.milestones[]
- [ ] Git worktree created with branch (`milestone/{slug}`)
- [ ] Shared `.workflow/` files copied (project.md, roadmap.md, config.json, specs/)
- [ ] Milestone scratch artifacts copied (filtered from artifact registry)
- [ ] `worktree-scope.json` written with milestone scope
- [ ] Scoped `state.json` written (only this milestone's artifacts)
- [ ] `worktrees.json` registry updated in main worktree
- [ ] Milestone marked as `"forked"` in main `state.json.milestones[]`
- [ ] Summary displayed with next-step commands

Sync mode:
- [ ] Git merge main into worktree branch
- [ ] Shared artifacts re-copied (project.md, roadmap.md, config.json, specs/)
- [ ] Conflicts reported if any
</success_criteria>