catlog22 Terminology: this command uses 'session' throughout. The underlying workflow file (fork.md) may use 'milestone' as a legacy alias for 'session'. Treat them as equivalent: --session maps to workflow's -m, state.json.sessions[] maps to state.json.milestones[].
--base <ref>: git ref (branch, tag, or commit hash) to fork from. Default: HEAD.
Modes (Fork / Sync), flags (--session, --base, --sync), session resolution, worktree layout, and artifact scoping are defined in workflow fork.md.
Fork and sync algorithm steps are defined in workflow fork.md.
Gates (MANDATORY, BLOCKING)
Fork mode:
GATE 1: Validation → Worktree Creation
- REQUIRED: Session resolved from
state.json.sessions[]by session_id or intent slug. - REQUIRED: No existing active worktree for this session (E008).
- REQUIRED: Not running inside a worktree (E003).
- BLOCKED if: session not found (E006), already forked (E008), or running inside worktree (E003).
GATE 2: Worktree Creation → Artifact Copy
- REQUIRED: Git worktree created with branch (
session/{slug}). - REQUIRED: Shared
.workflow/files copied (project.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: request_user_input confirmation before registry writes — show session scope, worktree path, and state entries to be written. User must confirm or abort.
- REQUIRED:
worktree-scope.jsonwritten with session scope (after confirmation). - REQUIRED: Scoped
state.jsonwritten (only this session's data) (after confirmation). - REQUIRED:
worktrees.jsonregistry updated in main worktree (after confirmation). - 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.
| Condition | Suggestion |
|---|---|
| Fork complete | cd {wt.path}, then route step analyze through /maestro-next or the canonical receipt-chained session open -> session chain insert --command analyze --arg "<goal>" -> run next flow |
| Fork + automated | maestro delegate "run full lifecycle for session" --cd {wt.path} --mode write |
| Sync complete | Resume work in worktree |
| Sync conflicts found | Resolve manually, then retry |
Sync mode:
- Git merge main into worktree branch
- Shared artifacts re-copied (project.md, config.json, specs/)
- Conflicts reported if any