maestro-flow 0.3.8 → 0.3.9

package/workflows/maestro.md

@@ -56,31 +56,26 @@ test -f .workflow/state.json && echo "exists" || echo "missing"
 ```
 
 **If `.workflow/state.json` exists:**
-1. Read `state.json` → extract `current_milestone`, `current_phase`, `status`, `phases_summary`, `accumulated_context`
+1. Read `state.json` → extract `current_milestone`, `status`, `milestones[]`, `artifacts[]`, `accumulated_context`
 2. Read `.workflow/roadmap.md` → extract phase list with titles
-3. For current_phase, read `.workflow/phases/{NN}-{slug}/index.json`:
-   - Extract: `status`, `plan`, `execution`, `verification`, `validation`, `uat`
-4. Check for artifacts in current phase directory:
-   ```bash
-   ls .workflow/phases/{NN}-{slug}/ 2>/dev/null | grep -E "(brainstorm|analysis|context|plan\.json|verification\.json|uat)\.md"
-   ```
-5. Build `$PROJECT_STATE`:
+3. Derive progress from artifact registry:
+   - Group `artifacts[]` by phase for current milestone
+   - For each phase: determine furthest artifact type (analyze→plan→execute→verify)
+   - Identify which phases have pending plans (plan artifact without execute artifact)
+4. Build `$PROJECT_STATE`:
    ```json
    {
      "initialized": true,
-     "current_phase": 1,
-     "phase_slug": "auth-system",
-     "phase_title": "Authentication System",
-     "phase_status": "pending|exploring|planning|executing|verifying|testing|completed|blocked",
-     "phase_artifacts": {
-       "brainstorm": false, "analysis": false, "context": false,
-       "plan": false, "verification": false, "uat": false
+     "current_milestone": "M1",
+     "milestone_name": "MVP Auth",
+     "milestone_progress": {
+       "phases_total": 3,
+       "phases_with_execute": 1,
+       "phases_with_plan": 2,
+       "adhoc_count": 0
      },
-     "execution": { "tasks_completed": 0, "tasks_total": 0 },
-     "verification_status": "pending",
-     "uat_status": "pending",
-     "phases_total": 3,
-     "phases_completed": 0,
+     "latest_artifact": { "id": "PLN-002", "type": "plan", "phase": 2 },
+     "pending_actions": ["execute phase 2", "analyze phase 3"],
      "has_blockers": false,
      "suggested_next": null
    }
@@ -95,7 +90,7 @@ test -f .workflow/state.json && echo "exists" || echo "missing"
 ### Step 3: Analyze Intent
 
 **If `$FORCED_CHAIN` is set:**
-- Validate against known chains: `full-lifecycle`, `spec-driven`, `brainstorm-driven`, `ui-design-driven`, `analyze-plan-execute`, `execute-verify`, `quality-loop`, `milestone-close`, `next-milestone`, `quick`, `review`, `issue-full`, `issue-quick`
+- Validate against known chains: `full-lifecycle`, `spec-driven`, `brainstorm-driven`, `ui-design-driven`, `analyze-plan-execute`, `execute-verify`, `quality-loop`, `milestone-close`, `next-milestone`, `quick`, `review`, `issue-full`, `issue-quick`, `fork`, `merge`
 - If valid: skip intent analysis, jump to **Step 5**
 - If invalid: display valid chains, ask user to choose
 
@@ -152,6 +147,8 @@ Instead of regex pattern matching, extract a structured intent tuple from the us
 | `transition` | Move to next phase/milestone — next phase, advance, complete milestone |
 | `continue` | Resume work — continue, next, go on, 继续 |
 | `sync` | Update docs/state — sync, refresh, update docs, 同步 |
+| `fork` | Create worktree for parallel milestone — fork, worktree, parallel, 分叉, 并行 |
+| `merge` | Merge worktree back — merge worktree, merge milestone, 合并工作树 |
 | `learn` | Capture insights — learn, capture insight, eureka, 记录洞察 |
 | `retrospect` | Post-mortem review — retrospective, retro, 复盘, post-mortem |
 
@@ -260,7 +257,7 @@ function routeIntent(intent, projectState) {
     'manage': {
       'issue':       'issue',
       'milestone':   'milestone_audit',
-      'phase':       'phase_transition',
+      'phase':       'milestone_close',
       'memory':      'memory',
       'doc':         'sync',
       'codebase':    'codebase_refresh',
@@ -269,9 +266,9 @@ function routeIntent(intent, projectState) {
       '_default':    'status',
     },
     'transition': {
-      'phase':       'phase_transition',
+      'phase':       'milestone_close',
       'milestone':   'milestone_complete',
-      '_default':    'phase_transition',
+      '_default':    'milestone_close',
     },
     'continue':    { '_default': 'state_continue' },
     'sync': {
@@ -279,6 +276,8 @@ function routeIntent(intent, projectState) {
       'codebase':    'codebase_refresh',
       '_default':    'sync',
     },
+    'fork':        { '_default': 'fork' },
+    'merge':       { '_default': 'merge' },
     'learn':       { '_default': 'learn' },
     'retrospect':  { '_default': 'retrospective' },
   };
@@ -455,7 +454,7 @@ function detectNextAction(state) {
       if (rev === 'BLOCK') return { chain: 'review-fix', steps: ['maestro-plan --gaps', 'maestro-execute', 'quality-review'] };
       // Review passed or warned — proceed to UAT
       if (uat === 'pending') return { chain: 'test', steps: ['quality-test'] };
-      if (uat === 'passed') return { chain: 'phase-transition', steps: ['maestro-phase-transition'] };
+      if (uat === 'passed') return { chain: 'milestone-close', steps: ['maestro-milestone-audit', 'maestro-milestone-complete'] };
       if (uat === 'failed') return { chain: 'debug', steps: ['quality-debug --from-uat {phase}'] };
       if (uat === 'in_progress') return { chain: 'test', steps: ['quality-test'] };
       return { chain: 'test', steps: ['quality-test'] };
@@ -466,7 +465,7 @@ function detectNextAction(state) {
 
   // Testing
   if (ps === 'testing') {
-    if (uat === 'passed') return { chain: 'phase-transition', steps: ['maestro-phase-transition'] };
+    if (uat === 'passed') return { chain: 'milestone-close', steps: ['maestro-milestone-audit', 'maestro-milestone-complete'] };
     return { chain: 'debug', steps: ['quality-debug --from-uat {phase}'] };
   }
 
@@ -474,7 +473,16 @@ function detectNextAction(state) {
   if (ps === 'completed') {
     if (state.phases_completed >= state.phases_total)
       return { chain: 'milestone-close', steps: ['maestro-milestone-audit', 'maestro-milestone-complete'] };
-    return { chain: 'phase-transition', steps: ['maestro-phase-transition'] };
+    return { chain: 'milestone-close', steps: ['maestro-milestone-audit', 'maestro-milestone-complete'] };
+  }
+
+  // Phase forked (developed in a worktree)
+  if (ps === 'forked') {
+    // Check if worktree is complete — suggest merge
+    if (fileExists('.workflow/worktrees.json')) {
+      return { chain: 'merge', steps: ['maestro-merge'] };
+    }
+    return { chain: 'status', steps: ['manage-status'] };
   }
 
   // Blocked
@@ -511,8 +519,7 @@ const chainMap = {
   'retrospective':      [{ cmd: 'quality-retrospective', args: '{phase}' }],
   'learn':              [{ cmd: 'manage-learn', args: '"{description}"' }],
   'sync':               [{ cmd: 'quality-sync', args: '{phase}' }],
-  'phase_transition':   [{ cmd: 'maestro-phase-transition' }],
-  'phase_add':          [{ cmd: 'maestro-phase-add', args: '"{description}"' }],
+  'milestone_close':   [{ cmd: 'maestro-milestone-audit' }, { cmd: 'maestro-milestone-complete' }],
   'milestone_audit':    [{ cmd: 'maestro-milestone-audit' }],
   'milestone_complete': [{ cmd: 'maestro-milestone-complete' }],
   'codebase_rebuild':   [{ cmd: 'manage-codebase-rebuild' }],
@@ -529,6 +536,8 @@ const chainMap = {
   'issue_execute':      [{ cmd: 'manage-issue-execute', args: '"{description}"' }],
   'memory':             [{ cmd: 'manage-memory', args: '"{description}"' }],
   'quick':              [{ cmd: 'maestro-quick', args: '"{description}"' }],
+  'fork':               [{ cmd: 'maestro-fork', args: '-m {milestone_num}' }],
+  'merge':              [{ cmd: 'maestro-merge', args: '-m {milestone_num}' }],
 
   // Team skills (independent, single-step)
   'team_lifecycle':     [{ cmd: 'team-lifecycle-v4', args: '"{description}"' }],
@@ -547,7 +556,7 @@ const chainMap = {
     { cmd: 'maestro-verify', args: '{phase}' },
     { cmd: 'quality-review', args: '{phase}' },
     { cmd: 'quality-test', args: '{phase}' },
-    { cmd: 'maestro-phase-transition' }
+    { cmd: 'maestro-milestone-audit' }
   ],
   'spec-driven': [
     { cmd: 'maestro-init' },
@@ -637,7 +646,7 @@ Cross-validate intent against project state:
 - Intent says `execute` but phase has no plan → warn, prepend `maestro-plan`
 - Intent says `verify` but phase not executed → warn, prepend `maestro-execute`
 - Intent says `test` but phase not verified → warn, prepend `maestro-verify`
-- Intent says `phase_transition` but phase not verified → warn, prepend `maestro-verify`
+- Intent says `milestone_close` but not all phases executed → warn, suggest completing execution first
 
 Display warning but let user override.
 
@@ -661,10 +670,10 @@ function resolvePhase(intent_analysis, project_state) {
   // 5. Chain doesn't need phase (init, status, memory, issue, etc.)
   const noPhaseCommands = ['manage-status', 'manage-issue', 'manage-issue-discover',
     'manage-issue-analyze', 'manage-issue-plan', 'manage-issue-execute',
-    'maestro-init', 'maestro-spec-generate',
+    'maestro-init', 'maestro-spec-generate', 'maestro-fork', 'maestro-merge',
     'maestro-roadmap', 'spec-setup', 'manage-memory', 'manage-memory-capture', 'manage-learn',
     'manage-codebase-rebuild', 'manage-codebase-refresh', 'maestro-milestone-audit',
-    'maestro-milestone-complete', 'maestro-phase-transition', 'maestro-phase-add'];
+    'maestro-milestone-complete', 'maestro-milestone-audit'];
   if (chain.every(s => noPhaseCommands.includes(s.cmd))) return null;
 
   // 6. Ask user
@@ -819,6 +828,14 @@ function assembleArgs(step, context) {
   Args: {assembled_args}
 ```
 
+**7a-1. Context cleanup hint (after step 3+):**
+
+If `i >= 3` and not `$AUTO_MODE`:
+```
+  ⚡ 已执行 {i} 步，上下文较重。可随时 /maestro -c 在新上下文中恢复。
+```
+If `$AUTO_MODE` and `i >= 4`: log one-line warning to status.json, continue.
+
 **7b. Update status.json:** Set step status = `"running"`, started_at = now.
 
 **7c. Execute via Skill():**
@@ -886,7 +903,7 @@ Display completion report:
 
 | Chain | Steps | Use Case |
 |-------|-------|----------|
-| `full-lifecycle` | plan → execute → verify → review → test → transition | Full phase completion |
+| `full-lifecycle` | plan → execute → verify → review → test → milestone-audit → milestone-complete | Full milestone completion |
 | `spec-driven` | init → spec-generate → plan → execute → verify | Start from idea/requirements (heavy path) |
 | `roadmap-driven` | init → maestro-roadmap → plan → execute → verify | Start from requirements (light path) |
 | `brainstorm-driven` | brainstorm → plan → execute → verify | Start from exploration |
@@ -931,7 +948,7 @@ Shows how structured extraction routes common inputs — especially cases where
 | `"复盘 phase 2"` | `{retrospect, phase}` | retrospective | quality-retrospective |
 | `"team review code"` | `{review, team}` | team_review | team-review |
 | `"team qa full scan"` | `{analyze, team}` | team_qa | team-quality-assurance |
-| `"next phase"` | `{transition, phase}` | phase_transition | maestro-phase-transition |
+| `"next phase"` | `{transition, milestone}` | milestone_close | maestro-milestone-audit → milestone-complete |
 | `"milestone audit"` | `{manage, milestone}` | milestone_audit | maestro-milestone-audit |
 | `-y "implement feature X"` | `{execute, feature}` | execute | maestro-execute (auto mode) |
 

package/workflows/merge.md

@@ -0,0 +1,285 @@
+# Workflow: merge
+
+Two-phase merge of a completed milestone worktree branch back into main. Phase 1: git merge (source code). Phase 2: artifact sync (workflow state). Artifact sync only proceeds after successful git merge.
+
+Merges operate at the **milestone level** — one worktree per milestone, all phases merged together.
+
+---
+
+## Step 1: Parse Arguments and Flags
+
+```javascript
+const getUtc8ISOString = () => new Date(Date.now() + 8 * 60 * 60 * 1000).toISOString()
+
+const force = $ARGUMENTS.includes('--force')
+const dryRun = $ARGUMENTS.includes('--dry-run')
+const noCleanup = $ARGUMENTS.includes('--no-cleanup')
+const continueMode = $ARGUMENTS.includes('--continue')
+
+// Parse milestone number: -m <N> or bare <N>
+const mFlagMatch = $ARGUMENTS.match(/-m\s+(\d+)/)
+const cleaned = $ARGUMENTS
+  .replace(/--force|--dry-run|--no-cleanup|--continue|-m\s+\d+/g, '')
+  .trim()
+const bareNumMatch = cleaned.match(/^(\d+)$/)
+const milestoneNum = mFlagMatch
+  ? parseInt(mFlagMatch[1])
+  : bareNumMatch
+    ? parseInt(bareNumMatch[1])
+    : null
+```
+
+---
+
+## Step 2: Validate Context
+
+```
+IF file_exists(".workflow/worktree-scope.json"):
+  ERROR E001: "Cannot merge from inside a worktree. Run from the main worktree."
+  EXIT
+
+IF NOT file_exists(".workflow/worktrees.json"):
+  ERROR E002: "No worktree registry found. Nothing to merge."
+  EXIT
+
+Read .workflow/worktrees.json → registry
+```
+
+---
+
+## Step 3: Registry Health Check
+
+```
+staleEntries = []
+for (entry of registry.worktrees):
+  IF NOT directory_exists(entry.path):
+    staleEntries.push(entry)
+
+IF staleEntries.length > 0:
+  WARN W001: "Found {staleEntries.length} stale worktree entries (directories missing):"
+  for (entry of staleEntries):
+    Display "  M{entry.milestone_num} ({entry.milestone}): {entry.path} — MISSING"
+  registry.worktrees = registry.worktrees.filter(w => !staleEntries.includes(w))
+  Write .workflow/worktrees.json: registry
+```
+
+---
+
+## Step 4: Resolve Merge Target
+
+```
+IF continueMode:
+  IF NOT file_exists(".workflow/.merge-state.json"):
+    ERROR E003: "--continue but no merge state found. Start a fresh merge."
+    EXIT
+  Read .workflow/.merge-state.json → mergeState
+  target = mergeState.target
+  GOTO Step_7
+
+ELSE IF milestoneNum !== null:
+  target = registry.worktrees.find(w =>
+    w.milestone_num === milestoneNum && w.status === "active"
+  )
+ELSE:
+  ERROR E004: "Milestone number required. Usage: maestro-merge -m <number>"
+  EXIT
+
+IF NOT target:
+  activeList = registry.worktrees
+    .filter(w => w.status === "active")
+    .map(w => "  M" + w.milestone_num + ": " + w.milestone + " (" + w.path + ")")
+    .join("\n")
+  Display "No active worktree for milestone {milestoneNum}."
+  IF activeList:
+    Display "Active worktrees:\n{activeList}"
+  EXIT
+```
+
+---
+
+## Step 5: Validate Readiness
+
+```
+completedPhases = []
+incompletePhases = []
+
+for (phaseNum of target.owned_phases):
+  NN = String(phaseNum).padStart(2, '0')
+  Glob: {target.path}/.workflow/phases/{NN}-*/index.json
+  Read → wtIndex
+
+  IF wtIndex.status === "completed":
+    completedPhases.push({ phase: phaseNum, index: wtIndex })
+  ELSE:
+    incompletePhases.push({ phase: phaseNum, status: wtIndex.status })
+
+IF incompletePhases.length > 0 AND NOT force:
+  WARN W002: "M{target.milestone_num} ({target.milestone}) has incomplete phases:"
+  for (p of incompletePhases):
+    Display "  Phase {p.phase}: {p.status}"
+  IF NOT dryRun:
+    AskUserQuestion: "Merge anyway? (y/n, or use --force)"
+    IF response !== 'y': EXIT
+
+IF dryRun:
+  Display "=== DRY RUN ==="
+  Display "  Would merge: {target.branch} → current branch"
+  Display "  Milestone: M{target.milestone_num} ({target.milestone})"
+  Display "  Completed: {completedPhases.map(p => p.phase).join(', ')}"
+  Display "  Incomplete: {incompletePhases.map(p => p.phase + '(' + p.status + ')').join(', ')}"
+  EXIT
+```
+
+---
+
+## Step 6: Phase 1 — Git Merge
+
+```
+Display "=== Merging M{target.milestone_num}: {target.milestone} ==="
+
+// 6a: Pre-merge rebase
+Display "Pulling main into worktree branch..."
+rebaseResult = Bash("cd {target.path} && git merge main --no-edit 2>&1")
+
+IF rebaseResult.exitCode !== 0:
+  WARN W003: "Conflict pulling main into worktree. Resolve in {target.path} first."
+  Display rebaseResult.output
+  Display "After resolving: cd {target.path} && git merge --continue"
+  Display "Then retry: /maestro-merge -m {target.milestone_num}"
+  EXIT
+
+// 6b: Merge worktree branch into main
+Display "Merging {target.branch} into current branch..."
+mergeResult = Bash("git merge {target.branch} --no-ff -m 'merge: M{target.milestone_num} {target.milestone}' 2>&1")
+
+IF mergeResult.exitCode !== 0:
+  Display "MERGE CONFLICT detected."
+  Display mergeResult.output
+
+  Write .workflow/.merge-state.json:
+    {
+      "target": target,
+      "phase": "git_merge_conflict",
+      "created_at": getUtc8ISOString()
+    }
+
+  Display ""
+  Display "Resolve conflicts, then:"
+  Display "  git add <resolved-files> && git merge --continue"
+  Display "  /maestro-merge --continue"
+  EXIT
+
+Display "Git merge successful."
+```
+
+---
+
+## Step 7: Phase 2 — Artifact Sync
+
+```
+Step_7:
+
+Display "Syncing workflow artifacts for M{target.milestone_num} ({target.milestone})..."
+
+// 7a: Copy all owned phase directories from worktree to main
+for (phaseNum of target.owned_phases):
+  NN = String(phaseNum).padStart(2, '0')
+  Glob: {target.path}/.workflow/phases/{NN}-*/
+  phaseDir = matched directory name
+
+  srcDir = target.path + "/.workflow/phases/" + phaseDir + "/"
+  dstDir = ".workflow/phases/" + phaseDir + "/"
+
+  Bash("cp -r {srcDir}* {dstDir}")
+
+// 7b: Atomic state reconciliation
+Read .workflow/state.json → mainState
+
+for (phaseNum of target.owned_phases):
+  NN = String(phaseNum).padStart(2, '0')
+  Glob: .workflow/phases/{NN}-*/index.json
+  Read → phaseIndex
+
+  IF phaseIndex.status === "completed":
+    mainState.phases_summary.completed += 1
+    mainState.phases_summary.pending -= 1
+    IF mainState.phases_summary.pending < 0:
+      mainState.phases_summary.pending = 0
+
+    mainState.transition_history = mainState.transition_history ?? []
+    mainState.transition_history.push({
+      milestone_num: target.milestone_num,
+      milestone: target.milestone,
+      phase: phaseNum,
+      action: "worktree_merge",
+      completed_at: phaseIndex.completed_at ?? getUtc8ISOString(),
+      branch: target.branch
+    })
+  ELSE IF phaseIndex.status !== "forked":
+    mainState.phases_summary.in_progress += 1
+    mainState.phases_summary.pending -= 1
+    IF mainState.phases_summary.pending < 0:
+      mainState.phases_summary.pending = 0
+
+  phaseIndex.updated_at = getUtc8ISOString()
+  Write .workflow/phases/{NN}-{slug}/index.json: phaseIndex
+
+// Merge accumulated context from worktree
+Read target.path + "/.workflow/state.json" → wtState (if exists)
+IF wtState?.accumulated_context:
+  for (decision of (wtState.accumulated_context.key_decisions ?? [])):
+    IF NOT mainState.accumulated_context.key_decisions.includes(decision):
+      mainState.accumulated_context.key_decisions.push(decision)
+  for (deferred of (wtState.accumulated_context.deferred ?? [])):
+    mainState.accumulated_context.deferred.push(deferred)
+
+mainState.last_updated = getUtc8ISOString()
+Write .workflow/state.json: mainState
+
+// 7c: Update roadmap.md
+Read .workflow/roadmap.md → roadmap
+for (phaseNum of target.owned_phases):
+  Read phase index → check if completed
+  IF completed:
+    Append " ✅ COMPLETED" to phase title line
+Write .workflow/roadmap.md: roadmap
+```
+
+---
+
+## Step 8: Cleanup
+
+```
+IF NOT noCleanup:
+  Display "Cleaning up worktree..."
+  Bash("git worktree remove --force {target.path}")
+  Bash("git branch -D {target.branch}")
+
+registry.worktrees = registry.worktrees.filter(w =>
+  !(w.milestone_num === target.milestone_num && w.branch === target.branch)
+)
+Write .workflow/worktrees.json: registry
+
+IF file_exists(".workflow/.merge-state.json"):
+  Bash("rm .workflow/.merge-state.json")
+```
+
+---
+
+## Step 9: Summary
+
+```
+Display:
+  === MERGE COMPLETE ===
+  Milestone:  M{target.milestone_num} — {target.milestone}
+  Branch:     {target.branch}
+  Phases:     {target.owned_phases.join(', ')}
+  Completed:  {completedPhases.length}/{target.owned_phases.length}
+
+  State:   .workflow/state.json updated
+  Roadmap: .workflow/roadmap.md updated
+
+  Next steps:
+    Skill({ skill: "manage-status" })          -- View dashboard
+    Skill({ skill: "maestro-milestone-audit" }) -- Audit merged milestone
+```