maestro-flow 0.3.8 → 0.3.9

package/workflows/fork.md

@@ -0,0 +1,309 @@
+# Workflow: fork
+
+Create a git worktree for an entire milestone, enabling inter-milestone parallel development. Copies `.workflow/` context into the worktree since `.workflow/` is gitignored.
+
+Worktrees operate at the **milestone level** — all phases within a milestone are owned by one worktree and executed sequentially inside it. Per-phase parallelism within a milestone is not supported.
+
+---
+
+## Step 1: Parse Arguments and Flags
+
+```javascript
+const getUtc8ISOString = () => new Date(Date.now() + 8 * 60 * 60 * 1000).toISOString()
+
+// Parse flags
+const syncMode = $ARGUMENTS.includes('--sync')
+const baseMatch = $ARGUMENTS.match(/--base\s+(\S+)/)
+const baseBranch = baseMatch ? baseMatch[1] : 'HEAD'
+
+// Parse milestone number: -m <N> or bare <N>
+const mFlagMatch = $ARGUMENTS.match(/-m\s+(\d+)/)
+const cleaned = $ARGUMENTS
+  .replace(/--sync|--base\s+\S+|-m\s+\d+/g, '')
+  .trim()
+const bareNumMatch = cleaned.match(/^(\d+)$/)
+const milestoneNum = mFlagMatch
+  ? parseInt(mFlagMatch[1])
+  : bareNumMatch
+    ? parseInt(bareNumMatch[1])
+    : null
+```
+
+---
+
+## Step 2: Validate Prerequisites
+
+```
+IF NOT file_exists(".workflow/state.json"):
+  ERROR E001: "Project not initialized. Run maestro-init first."
+  EXIT
+
+IF NOT file_exists(".workflow/roadmap.md"):
+  ERROR E002: "No roadmap found. Run maestro-roadmap first."
+  EXIT
+
+IF file_exists(".workflow/worktree-scope.json"):
+  ERROR E003: "Cannot fork from inside a worktree. Run from the main worktree."
+  EXIT
+
+IF milestoneNum === null:
+  ERROR E004: "Milestone number required. Usage: maestro-fork -m <number>"
+  EXIT
+
+Read .workflow/state.json → projectState
+Read .workflow/config.json → config (if exists, else use defaults)
+
+worktreeRoot = config.worktree?.root ?? ".worktrees"
+branchPrefix = config.worktree?.branch_prefix ?? "milestone/"
+```
+
+---
+
+## Step 3: Resolve Milestone
+
+```
+// Lookup milestone by number from state.json.milestones[]
+IF NOT projectState.milestones || NOT Array.isArray(projectState.milestones):
+  ERROR E005: "No milestones defined in state.json."
+  EXIT
+
+// milestones[] is 0-indexed, milestoneNum is 1-based
+milestoneEntry = projectState.milestones[milestoneNum - 1]
+
+IF NOT milestoneEntry:
+  availableList = projectState.milestones
+    .map((m, i) => "  M" + (i + 1) + ": " + m.name + " (" + m.title + ")")
+    .join("\n")
+  ERROR E006: "Milestone {milestoneNum} not found.\nAvailable:\n{availableList}"
+  EXIT
+
+milestoneName = milestoneEntry.name       // e.g. "Production"
+milestoneTitle = milestoneEntry.title      // e.g. "生产就绪"
+milestonePhases = milestoneEntry.phases    // e.g. [3, 4]
+milestoneSlug = milestoneName.toLowerCase().replace(/[^a-z0-9]+/g, '-').substring(0, 40)
+```
+
+---
+
+## Step 4: Sync Mode (--sync)
+
+If `syncMode` is true, this is a sync operation on an existing worktree, not a fork.
+
+```
+IF syncMode:
+  Read .workflow/worktrees.json → registry
+  entry = registry.worktrees.find(w =>
+    w.milestone_num === milestoneNum && w.status === "active"
+  )
+
+  IF NOT entry:
+    ERROR E007: "No active worktree for milestone {milestoneNum} ({milestoneName})"
+    EXIT
+
+  // Step 4a: Pull source code
+  Bash("cd {entry.path} && git merge main")
+  IF conflict:
+    WARN "Merge conflict in worktree. Resolve in {entry.path} before continuing."
+    EXIT
+
+  // Step 4b: Re-copy shared context
+  Copy .workflow/project.md → {entry.path}/.workflow/project.md
+  Copy .workflow/roadmap.md → {entry.path}/.workflow/roadmap.md
+  Copy .workflow/config.json → {entry.path}/.workflow/config.json (if exists)
+  Copy .workflow/specs/ → {entry.path}/.workflow/specs/ (if exists)
+
+  Display "Worktree for M{milestoneNum} ({milestoneName}) synced with main."
+  EXIT (sync complete)
+```
+
+---
+
+## Step 5: Validate & Confirm
+
+```
+// Load phase index files for all milestone phases
+phaseList = []
+for (phaseNum of milestonePhases):
+  Glob: .workflow/phases/{NN}-*/index.json where NN matches phaseNum
+  Read index.json → phaseIndex
+  phaseList.push(phaseIndex)
+
+// Validate: milestone should have at least one non-completed phase
+nonCompleted = phaseList.filter(p => p.status !== "completed")
+IF nonCompleted.length === 0:
+  Display "All phases in M{milestoneNum} ({milestoneName}) are already completed. Nothing to fork."
+  EXIT
+
+// Check for already-forked milestone
+IF file_exists(".workflow/worktrees.json"):
+  Read .workflow/worktrees.json → existingRegistry
+  alreadyForked = existingRegistry.worktrees.find(w =>
+    w.milestone_num === milestoneNum && w.status === "active"
+  )
+  IF alreadyForked:
+    ERROR E008: "M{milestoneNum} already has an active worktree at {alreadyForked.path}. Merge or cleanup first."
+    EXIT
+
+Display "Fork Milestone {milestoneNum}: {milestoneName} ({milestoneTitle})"
+Display "Phases ({phaseList.length}):"
+for (p of phaseList):
+  Display "  Phase {p.phase}: {p.title} [{p.status}]"
+
+AskUserQuestion: "Create worktree for this milestone? (y/n)"
+IF response !== 'y': EXIT
+```
+
+---
+
+## Step 6: Create Worktree
+
+```
+const forkSessionId = "fork-" + getUtc8ISOString().substring(0, 19).replace(/[-:T]/g, '')
+const baseCommit = Bash("git rev-parse HEAD").trim()
+const branch = branchPrefix + milestoneSlug
+const wtPath = worktreeRoot + "/m" + milestoneNum + "-" + milestoneSlug
+
+// 6a: Clean up stale worktree/branch if exists
+IF directory_exists(wtPath):
+  Bash("git worktree remove --force {wtPath}") // ignore errors
+Bash("git branch -D {branch}") // ignore errors (may not exist)
+
+// 6b: Create worktree
+Bash("git worktree add -b {branch} {wtPath} {baseBranch}")
+
+// 6c: Create .workflow/ structure in worktree
+Bash("mkdir -p {wtPath}/.workflow/phases")
+
+// 6d: Copy shared context (read-only)
+Copy .workflow/project.md → {wtPath}/.workflow/project.md
+Copy .workflow/roadmap.md → {wtPath}/.workflow/roadmap.md
+IF file_exists(".workflow/config.json"):
+  Copy .workflow/config.json → {wtPath}/.workflow/config.json
+IF directory_exists(".workflow/specs"):
+  Copy .workflow/specs/ → {wtPath}/.workflow/specs/
+
+// 6e: Copy ALL phase directories for this milestone
+ownedPhaseNumbers = []
+for (p of phaseList):
+  NN = String(p.phase).padStart(2, '0')
+  Copy .workflow/phases/{NN}-{p.slug}/ → {wtPath}/.workflow/phases/{NN}-{p.slug}/
+  ownedPhaseNumbers.push(p.phase)
+
+// 6f: Copy completed dependency phase dirs outside this milestone (read-only reference)
+allDeps = new Set()
+for (p of phaseList):
+  for (dep of p.depends_on):
+    IF NOT ownedPhaseNumbers.includes(dep):
+      allDeps.add(dep)
+
+for (dep of allDeps):
+  depNN = String(dep).padStart(2, '0')
+  Glob: .workflow/phases/{depNN}-*/index.json
+  Read → depIndex
+  Copy .workflow/phases/{depNN}-{depIndex.slug}/ → {wtPath}/.workflow/phases/{depNN}-{depIndex.slug}/
+
+// 6g: Write worktree-scope.json
+Write {wtPath}/.workflow/worktree-scope.json:
+  {
+    "worktree": true,
+    "milestone_num": milestoneNum,
+    "milestone": milestoneName,
+    "owned_phases": ownedPhaseNumbers,
+    "main_worktree": resolve(cwd),
+    "branch": branch,
+    "base_commit": baseCommit,
+    "created_at": getUtc8ISOString()
+  }
+
+// 6h: Write scoped state.json
+Read .workflow/state.json → mainState
+firstPending = phaseList.find(p => p.status !== "completed")
+scopedState = {
+  ...mainState,
+  current_phase: firstPending?.phase ?? phaseList[0].phase,
+  current_milestone: milestoneName
+}
+Write {wtPath}/.workflow/state.json: scopedState
+```
+
+---
+
+## Step 7: Update Main Registry
+
+```
+IF file_exists(".workflow/worktrees.json"):
+  Read .workflow/worktrees.json → registry
+ELSE:
+  registry = { version: "1.0", worktrees: [], fork_sessions: [] }
+
+registry.worktrees.push({
+  milestone_num: milestoneNum,
+  milestone: milestoneName,
+  slug: milestoneSlug,
+  branch: branch,
+  path: wtPath,
+  base_commit: baseCommit,
+  status: "active",
+  created_at: getUtc8ISOString(),
+  owned_phases: ownedPhaseNumbers,
+  fork_session: forkSessionId
+})
+
+registry.fork_sessions.push({
+  session_id: forkSessionId,
+  created_at: getUtc8ISOString(),
+  milestone_num: milestoneNum,
+  milestone: milestoneName,
+  base_branch: baseBranch,
+  base_commit: baseCommit
+})
+
+Write .workflow/worktrees.json: registry
+
+// Mark milestone phases as "forked" in main
+for (p of phaseList):
+  IF p.status !== "completed":
+    NN = String(p.phase).padStart(2, '0')
+    Read .workflow/phases/{NN}-{p.slug}/index.json → idx
+    idx.status = "forked"
+    idx.updated_at = getUtc8ISOString()
+    Write .workflow/phases/{NN}-{p.slug}/index.json: idx
+
+mainState.last_updated = getUtc8ISOString()
+Write .workflow/state.json: mainState
+```
+
+---
+
+## Step 8: Display Summary
+
+```
+Display:
+  === FORK COMPLETE ===
+  Session:    {forkSessionId}
+  Base:       {baseBranch} ({baseCommit.substring(0, 7)})
+  Milestone:  M{milestoneNum} — {milestoneName} ({milestoneTitle})
+  Branch:     {branch}
+  Path:       {wtPath}
+  Phases:     {ownedPhaseNumbers.join(', ')}
+
+  Next steps (run in the worktree):
+    cd {wtPath}
+
+    # Sequential lifecycle for each phase:
+    /maestro-analyze {firstPending.phase}
+    /maestro-plan {firstPending.phase}
+    /maestro-execute {firstPending.phase}
+    /maestro-verify {firstPending.phase}
+    /maestro-phase-transition {firstPending.phase}
+    # ... repeat for next phases in milestone
+
+  Or delegate (automated):
+    maestro delegate "run full lifecycle for milestone" --cd {wtPath} --mode write
+
+  Sync worktree with main (if needed later):
+    /maestro-fork -m {milestoneNum} --sync
+
+  When all phases in milestone complete:
+    /maestro-merge -m {milestoneNum}
+```

package/workflows/init.md

@@ -4,6 +4,15 @@ Project initialization with automatic state detection. Creates project infrastru
 
 ---
 
+## Worktree Guard
+
+```
+# Block in worktree
+IF file_exists(".workflow/worktree-scope.json"):
+  ERROR "Cannot run maestro-init inside a worktree. Run from the main worktree."
+  EXIT
+```
+
 ## Step 1: State Detection
 
 Detect current project state to determine initialization path.
@@ -41,7 +50,7 @@ CHECK .workflow/state.json exists?
 
    If `--auto` flag: skip interactive questioning, extract from @ referenced document.
    If `--from-brainstorm SESSION-ID`:
-   - Locate brainstorm session directory (`.workflow/scratch/brainstorm-*/` or `.workflow/phases/*/`)
+   - Locate brainstorm session directory (`.workflow/scratch/brainstorm-*/`)
    - Read `guidance-specification.md`:
      - Problem statement → project vision + core value
      - Features → project goals (Active requirements)

package/workflows/issue.md

@@ -65,14 +65,21 @@ Parse options from ARGS:
 Options:
   --title TEXT        Issue title (required)
   --severity VALUE    critical|high|medium|low (default: medium)
-  --source VALUE      verification|antipattern|discuss|discovery|manual (default: manual)
+  --source VALUE      planned|supplement|bug|review|verification|discovery|manual (default: manual)
   --phase VALUE       Phase reference, e.g. "01-auth" (optional)
+  --milestone VALUE   Milestone reference, e.g. "MVP" (optional, auto-derived from state.json if omitted)
   --description TEXT  Detailed description (optional, prompted if missing)
   --priority NUMBER   1-5, lower is higher priority (default: 3)
   --tags TAG1,TAG2    Comma-separated tags (optional)
 
 If --title is missing:
   AskUserQuestion({ question: "What is the issue title?" })
+
+Derive milestone_ref if not provided:
+  IF --milestone not provided AND file_exists(".workflow/state.json"):
+    milestone_ref = state.json.current_milestone
+  ELSE:
+    milestone_ref = --milestone value or null
 ```
 
 Generate issue ID:
@@ -96,6 +103,7 @@ Build issue record from template:
   "priority": {PRIORITY},
   "severity": "{SEVERITY}",
   "source": "{SOURCE}",
+  "milestone_ref": "{MILESTONE_REF or null}",
   "phase_ref": "{PHASE_REF or null}",
   "gap_ref": null,
   "description": "{DESCRIPTION}",
@@ -135,8 +143,56 @@ Write to storage:
    Title:   {TITLE}
    Status:  open
    Severity: {SEVERITY}
+```
+
+Ask for supplementary information:
+
+```
+4. Ask user for supplementary context:
+   AskUserQuestion({
+     question: "Do you have any supplementary information for this issue?\n1. Additional context or background?\n2. Reproduction steps or affected files?\n3. Related issues or tasks?\n4. Other notes?\n\n(Press Enter to skip)"
+   })
+
+5. Process user response:
+   - If response is non-empty:
+     a. Build supplement entry:
+        {
+          "content": "{RESPONSE_TEXT}",
+          "stage": "post_creation",
+          "author": "user",
+          "created_at": "{NOW_ISO}"
+        }
+     b. Read issues.jsonl
+     c. Find the just-created issue by {ID}
+     d. Initialize supplements as [] if not present
+     e. Append the supplement entry
+     f. Set updated_at = NOW_ISO
+     g. Rewrite issues.jsonl with updated record
+     h. Display: "Added supplement to {ID}"
+   - If response is empty: skip supplement step
+```
 
-4. Suggest next steps:
+Cross-milestone conflict check (for supplement issues):
+
+```
+6. IF source == "supplement" AND milestone_ref is not null:
+   a. Read .workflow/roadmap.md
+   b. Identify phases belonging to OTHER milestones (not milestone_ref)
+   c. For each other-milestone phase, check if plan.json exists:
+      Read .workflow/phases/{NN}-{slug}/plan.json (if exists)
+      Collect files_to_create[] as planned_files
+   d. IF affected_components in the new issue overlap with planned_files:
+      WARNING: "Conflict detected: this supplement issue affects components planned in milestone {other_milestone}"
+      Display:
+        "  Issue affects: {overlapping_components}"
+        "  Planned in: Phase {NN} ({milestone})"
+      Display: "Consider: minimal fix now (supplement), or defer to {other_milestone} for full rework"
+```
+
+Suggest next steps:
+
+```
+7. Suggest next steps:
    - Skill({ skill: "manage-issue", args: "status {ID}" }) -- View full details
    - Skill({ skill: "manage-issue", args: "link {ID} --task TASK-NNN" }) -- Link to a task
    - Skill({ skill: "manage-issue", args: "list" }) -- List all issues
@@ -150,11 +206,12 @@ Parse filter options from ARGS:
 
 ```
 Options:
-  --status VALUE    Filter by status (open|in_progress|completed|failed|deferred)
-  --phase VALUE     Filter by phase_ref
-  --severity VALUE  Filter by severity (critical|high|medium|low)
-  --source VALUE    Filter by source
-  --all             Include closed issues from issue-history.jsonl
+  --status VALUE      Filter by status (open|in_progress|completed|failed|deferred)
+  --phase VALUE       Filter by phase_ref
+  --milestone VALUE   Filter by milestone_ref
+  --severity VALUE    Filter by severity (critical|high|medium|low)
+  --source VALUE      Filter by source
+  --all               Include closed issues from issue-history.jsonl
 ```
 
 Read and filter:
@@ -167,6 +224,7 @@ Read and filter:
    - If --status: match record.status == VALUE
    - If --phase: match record.phase_ref contains VALUE
    - If --severity: match record.severity == VALUE
+   - If --milestone: match record.milestone_ref == VALUE
    - If --source: match record.source == VALUE
 5. Sort by priority (ascending), then severity order (critical > high > medium > low)
 ```
@@ -284,6 +342,7 @@ Options:
   --tags TAG1,TAG2        Replace tags
   --add-tag TAG           Add a tag
   --phase VALUE           Set phase_ref
+  --milestone VALUE       Set milestone_ref
   --fix-direction TEXT    Set fix_direction
   --description TEXT      Update description
   --note TEXT             Add feedback entry (type=clarification)

package/workflows/maestro-coordinate.md

@@ -37,9 +37,9 @@ test -f .workflow/state.json && echo "exists" || echo "missing"
 ```javascript
 const projectState = {
   initialized: true,
-  current_phase: /* from state.json */,
-  phase_slug: '...',
-  phase_status: '...', // pending|exploring|planning|executing|verifying|testing|completed|blocked
+  current_milestone: /* from state.json */,
+  latest_artifact: /* last artifact in artifacts[] */,
+  milestone_progress: '...', // derived from artifact registry
   phase_artifacts: { brainstorm: false, analysis: false, context: false, plan: false, verification: false, uat: false },
   execution: { tasks_completed: 0, tasks_total: 0 },
   verification_status: 'pending',
@@ -75,6 +75,10 @@ if (exactMatch[normalized]) {
 
 #### 3a-2: Structured intent extraction (LLM-native)
 
+> **Implementation note**: The runtime (`src/coordinator/intent-router.ts`) currently
+> uses pattern-based regex matching via `chains/_intent-map.json`. The structured
+> extraction below is a design target, not the current implementation.
+
 Instead of regex, extract a structured intent tuple using LLM semantic understanding:
 
 ```json
@@ -105,7 +109,7 @@ function routeIntent(intent, projectState) {
   // Action × Object matrix
   const matrix = {
     'fix':       { 'bug': 'debug', 'issue': 'issue', 'code': 'debug', 'performance': 'debug', 'security': 'debug', '_default': 'debug' },
-    'create':    { 'feature': 'quick', 'issue': 'issue', 'test': 'test_gen', 'spec': 'spec_generate', 'ui': 'ui_design', 'config': 'init', 'phase': 'phase_add', '_default': 'quick' },
+    'create':    { 'feature': 'quick', 'issue': 'issue', 'test': 'test_gen', 'spec': 'spec_generate', 'ui': 'ui_design', 'config': 'init', 'phase': 'roadmap', '_default': 'quick' },
     'analyze':   { 'bug': 'analyze', 'issue': 'issue_analyze', 'code': 'analyze', 'codebase': 'spec_map', '_default': 'analyze' },
     'explore':   { 'issue': 'issue_discover', 'feature': 'brainstorm', 'ui': 'ui_design', '_default': 'brainstorm' },
     'plan':      { 'issue': 'issue_plan', 'spec': 'spec_generate', '_default': 'plan' },
@@ -115,8 +119,8 @@ function routeIntent(intent, projectState) {
     'test':      { '_default': 'test' },
     'debug':     { '_default': 'debug' },
     'refactor':  { '_default': 'refactor' },
-    'manage':    { 'issue': 'issue', 'milestone': 'milestone_audit', 'phase': 'phase_transition', 'memory': 'memory', 'doc': 'sync', 'codebase': 'codebase_refresh', 'team': 'team_coordinate', '_default': 'status' },
-    'transition':{ 'phase': 'phase_transition', 'milestone': 'milestone_complete', '_default': 'phase_transition' },
+    'manage':    { 'issue': 'issue', 'milestone': 'milestone_audit', 'phase': 'milestone_close', 'memory': 'memory', 'doc': 'sync', 'codebase': 'codebase_refresh', 'team': 'team_coordinate', '_default': 'status' },
+    'transition':{ 'phase': 'milestone_close', 'milestone': 'milestone_complete', '_default': 'milestone_close' },
     'continue':  { '_default': 'state_continue' },
     'sync':      { '_default': 'sync' },
     'learn':     { '_default': 'learn' },
@@ -166,18 +170,18 @@ function detectNextAction(s) {
     if (s.verification_status === 'passed') {
       if (!s.review_verdict) return { chain: 'review', steps: [{ cmd: 'quality-review', args: '{phase}' }] };
       if (s.uat_status === 'pending') return { chain: 'test', steps: [{ cmd: 'quality-test', args: '{phase}' }] };
-      if (s.uat_status === 'passed') return { chain: 'phase-transition', steps: [{ cmd: 'maestro-phase-transition' }] };
+      if (s.uat_status === 'passed') return { chain: 'milestone-close', steps: [{ cmd: 'maestro-milestone-audit' }, { cmd: 'maestro-milestone-complete' }] };
       return { chain: 'debug', steps: [{ cmd: 'quality-debug', args: '--from-uat {phase}' }] };
     }
     return { chain: 'quality-loop-partial', steps: [{ cmd: 'maestro-plan', args: '{phase} --gaps' }, { cmd: 'maestro-execute', args: '{phase}' }, { cmd: 'maestro-verify', args: '{phase}' }] };
   }
   if (ps === 'testing') {
-    if (s.uat_status === 'passed') return { chain: 'phase-transition', steps: [{ cmd: 'maestro-phase-transition' }] };
+    if (s.uat_status === 'passed') return { chain: 'milestone-close', steps: [{ cmd: 'maestro-milestone-audit' }, { cmd: 'maestro-milestone-complete' }] };
     return { chain: 'debug', steps: [{ cmd: 'quality-debug', args: '--from-uat {phase}' }] };
   }
   if (ps === 'completed') {
     if (s.phases_completed >= s.phases_total) return { chain: 'milestone-close', steps: [{ cmd: 'maestro-milestone-audit' }, { cmd: 'maestro-milestone-complete' }] };
-    return { chain: 'phase-transition', steps: [{ cmd: 'maestro-phase-transition' }] };
+    return { chain: 'milestone-close', steps: [{ cmd: 'maestro-milestone-audit' }, { cmd: 'maestro-milestone-complete' }] };
   }
   if (ps === 'blocked') return { chain: 'debug', steps: [{ cmd: 'quality-debug' }] };
   return { chain: 'status', steps: [{ cmd: 'manage-status' }] };
@@ -205,8 +209,8 @@ 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' }],
+  'roadmap':            [{ cmd: 'maestro-roadmap', args: '"{description}"' }],
   'milestone_audit':    [{ cmd: 'maestro-milestone-audit' }],
   'milestone_complete': [{ cmd: 'maestro-milestone-complete' }],
   'codebase_rebuild':   [{ cmd: 'manage-codebase-rebuild' }],
@@ -223,6 +227,8 @@ const chainMap = {
   'issue_plan':         [{ cmd: 'manage-issue-plan', args: '"{description}"' }],
   'issue_execute':      [{ cmd: 'manage-issue-execute', 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_lifecycle':     [{ cmd: 'team-lifecycle-v4', args: '"{description}"' }],
   'team_coordinate':    [{ cmd: 'team-coordinate', args: '"{description}"' }],
   'team_qa':            [{ cmd: 'team-quality-assurance', args: '"{description}"' }],
@@ -234,7 +240,7 @@ const chainMap = {
   'spec-driven':     [{ cmd: 'maestro-init' }, { cmd: 'maestro-spec-generate', args: '"{description}"' }, { cmd: 'maestro-plan', args: '{phase}' }, { cmd: 'maestro-execute', args: '{phase}' }, { cmd: 'maestro-verify', args: '{phase}' }],
   'brainstorm-driven': [{ cmd: 'maestro-brainstorm', args: '"{description}"' }, { cmd: 'maestro-plan', args: '{phase}' }, { cmd: 'maestro-execute', args: '{phase}' }, { cmd: 'maestro-verify', args: '{phase}' }],
   'ui-design-driven': [{ cmd: 'maestro-ui-design', args: '{phase}' }, { cmd: 'maestro-plan', args: '{phase}' }, { cmd: 'maestro-execute', args: '{phase}' }, { cmd: 'maestro-verify', args: '{phase}' }],
-  'full-lifecycle':  [{ cmd: 'maestro-plan', args: '{phase}' }, { cmd: 'maestro-execute', args: '{phase}' }, { cmd: 'maestro-verify', args: '{phase}' }, { cmd: 'quality-review', args: '{phase}' }, { cmd: 'quality-test', args: '{phase}' }, { cmd: 'maestro-phase-transition' }],
+  'full-lifecycle':  [{ cmd: 'maestro-plan', args: '{phase}' }, { cmd: 'maestro-execute', args: '{phase}' }, { cmd: 'maestro-verify', args: '{phase}' }, { cmd: 'quality-review', args: '{phase}' }, { cmd: 'quality-test', args: '{phase}' }, { cmd: 'maestro-milestone-audit' }, { cmd: 'maestro-milestone-complete' }],
   'execute-verify':  [{ cmd: 'maestro-execute', args: '{phase}' }, { cmd: 'maestro-verify', args: '{phase}' }],
   'quality-loop':    [{ cmd: 'maestro-verify', args: '{phase}' }, { cmd: 'quality-review', args: '{phase}' }, { cmd: 'quality-test', args: '{phase}' }, { cmd: 'quality-debug', args: '--from-uat {phase}' }, { cmd: 'maestro-plan', args: '{phase} --gaps' }, { cmd: 'maestro-execute', args: '{phase}' }],
   'milestone-close': [{ cmd: 'maestro-milestone-audit' }, { cmd: 'maestro-milestone-complete' }],
@@ -269,7 +275,8 @@ function resolvePhase() {
   // Fallback regex
   const m = intent.match(/phase\s*(\d+)|^(\d+)$/);
   if (m) return m[1] || m[2];
-  if (projectState.initialized) return projectState.current_phase;
+  // With scratch-based architecture, commands default to milestone-wide when no phase specified
+  // Return null to let commands use their default scope routing
   return null;
 }
 
@@ -320,7 +327,7 @@ const state = {
 };
 Write(`${sessionDir}/state.json`, JSON.stringify(state, null, 2));
 
-const context = { current_phase: resolvedPhase, user_intent: intent, issue_id: resolvedIssueId, spec_session_id: null };
+const context = { resolved_phase: resolvedPhase, user_intent: intent, issue_id: resolvedIssueId, spec_session_id: null };
 ```
 
 ---
@@ -338,7 +345,7 @@ const AUTO_FLAG_MAP = {
 
 function assembleArgs(step) {
   let a = (step.args || '')
-    .replace(/\{phase\}/g, context.current_phase || '')
+    .replace(/\{phase\}/g, context.resolved_phase || '')  // empty = milestone-wide default
     .replace(/\{description\}/g, context.user_intent || '')
     .replace(/\{issue_id\}/g, context.issue_id || '')
     .replace(/\{spec_session_id\}/g, context.spec_session_id || '')
@@ -418,7 +425,7 @@ step.completed_at = new Date().toISOString();
 
 // Context propagation
 const phaseMatch = output.match(/PHASE:\s*(\d+)/m);
-if (phaseMatch) context.current_phase = phaseMatch[1];
+if (phaseMatch) context.resolved_phase = phaseMatch[1];
 const specMatch = output.match(/SPEC-[\w-]+/);
 if (specMatch) context.spec_session_id = specMatch[0];
 const scratchMatch = output.match(/scratch_dir:\s*(.+)/m);