maestro-flow 0.3.7 → 0.3.9

package/workflows/plan.md

@@ -4,34 +4,61 @@
 
 Produces two-layer plan output: `plan.json` (overview with task_ids[] and waves[]) + `.task/TASK-{NNN}.json` (individual task definitions).
 
+All output goes to `.workflow/scratch/plan-{slug}-{date}/`.
+
 ---
 
 ## Prerequisites
 
-- `.workflow/` directory initialized (`/workflow:init` completed)
-- Phase directory exists at `.workflow/phases/{NN}-{slug}/` — OR `--dir` specifies a scratch directory
-- `index.json` present in target directory
+- None for standalone operation (state.json auto-bootstraps)
+- For milestone/phase scope: init + roadmap required
 
 ---
 
-## Phase Resolution
+## Scope Resolution
 
 ```
-Input: <phase> argument (number or slug) OR --dir <path>
+Input: [phase] argument OR --dir <path>
+
+# Worktree scope check
+IF file_exists(".workflow/worktree-scope.json"):
+  scope = read(".workflow/worktree-scope.json")
+  IF <phase> is a number AND <phase> NOT IN scope.owned_phases:
+    ERROR "Phase {phase} not owned by this worktree. Owned: {scope.owned_phases}"
+    EXIT
+
+# Auto-bootstrap state.json if missing
+IF NOT file_exists(".workflow/state.json"):
+  mkdir -p .workflow/scratch/
+  Write minimal state.json: { project: null, status: "active", current_milestone: null,
+    current_task_id: null, milestones: [], artifacts: [], last_updated: now() }
 
 IF --dir <path> is provided:
-  1. Set PHASE_DIR = <path> (absolute or relative to project root)
-  2. Validate directory exists and contains index.json
-  3. Set SCRATCH_MODE = true (skip roadmap validation, phase transition)
+  1. Set CONTEXT_DIR = <path> (absolute or relative to .workflow/)
+  2. Validate directory exists (context.md or conclusions.json present)
+  3. Determine scope from parent artifact in state.json (if registered), else "standalone"
   4. Set PHASE_NUM = null, PHASE_SLUG = directory basename
 
-ELSE (standard phase resolution):
-  1. If number: find .workflow/phases/{NN}-*/index.json
-  2. If slug: find .workflow/phases/*-{slug}/index.json
-  3. Validate phase exists and status is not "completed"
-  4. Set PHASE_DIR = resolved path
-  5. Set PHASE_NUM and PHASE_SLUG from directory name
-  6. Set SCRATCH_MODE = false
+ELSE IF no arguments:
+  IF state.json.current_milestone AND roadmap.md exists:
+    scope = "milestone"
+    milestone_slug = slugify(current_milestone name)
+    CONTEXT_DIR = find latest analyze artifact for this milestone from state.json.artifacts[]
+  ELSE:
+    ERROR E001 "No args and no roadmap — provide phase number or create roadmap"
+
+ELSE IF argument is a number:
+  IF state.json.current_milestone AND roadmap.md exists:
+    scope = "phase"
+    PHASE_NUM = parsed number
+    PHASE_SLUG = resolve from roadmap.md
+    CONTEXT_DIR = find latest analyze artifact for this phase from state.json.artifacts[]
+  ELSE:
+    ERROR "Phase number requires init + roadmap"
+
+# Output directory (always scratch)
+OUTPUT_DIR = .workflow/scratch/plan-{PHASE_SLUG or milestone_slug}-{date}/
+mkdir -p {OUTPUT_DIR}/.task/
 ```
 
 ---
@@ -56,8 +83,10 @@ ELSE (standard phase resolution):
 
 1. **Load user decisions**
    ```
-   Read ${PHASE_DIR}/context.md
-   -> If missing: warn "No context.md found. Run /maestro-analyze -q first or proceed with defaults."
+   IF CONTEXT_DIR exists:
+     Read ${CONTEXT_DIR}/context.md
+   ELSE:
+     warn "No upstream analyze found. Run /maestro-analyze first or proceed with defaults."
    ```
 
 2. **Load spec reference** (if `--spec` flag or index.json has spec_ref)
@@ -401,7 +430,8 @@ Build plan.json with gap-fix tasks
      task_ids: [extracted from plan.json],
      task_count: plan.json.task_count,
      complexity: plan.json.complexity,
-     waves: plan.json.waves
+     waves: plan.json.waves,
+     executor_assignments: {}  # populated by user override or auto-assignment in P5
    }
    index.json.status = "planning"
    index.json.updated_at = now()
@@ -414,6 +444,53 @@ Build plan.json with gap-fix tasks
 
 ---
 
+## P4.5: Collision Detection
+
+**Purpose:** Warn if this plan's files overlap with existing plans in the same milestone.
+
+**Skip if:** scope == "standalone" (no milestone context to compare against)
+
+```
+// 1. Collect existing plan file sets
+existing_plans = state.json.artifacts
+  .filter(a => a.milestone == current_milestone
+           && a.type == "plan"
+           && a.status == "completed")
+
+existing_files = {}  // { file_path: [plan_id, ...] }
+FOR each plan IN existing_plans:
+  tasks = load_all_tasks(plan.path + "/.task/")
+  FOR each task IN tasks:
+    FOR each file IN task.files:
+      existing_files[file].push(plan.id)
+
+// 2. Collect new plan's file set
+new_tasks = load_all_tasks(OUTPUT_DIR + "/.task/")
+new_files = Set()
+FOR each task IN new_tasks:
+  FOR each file IN task.files:
+    new_files.add(file)
+
+// 3. Check intersection
+collisions = []
+FOR each file IN new_files:
+  IF file IN existing_files:
+    collisions.push({ file, existing_plans: existing_files[file] })
+
+// 4. Report (non-blocking)
+IF collisions.length > 0:
+  WARN: "碰撞检测发现 {collisions.length} 个文件重叠:"
+  FOR each c IN collisions:
+    "  {c.file} ← 已在 {c.existing_plans.join(', ')} 中规划"
+  "建议: 确认是否有意覆盖，或调整 task 范围"
+ELSE:
+  "碰撞检测通过: 无文件重叠"
+```
+
+**Note:** Only checks `task.files[]` (write targets). `task.read_first[]` (read-only references) are excluded.
+
+---
+
 ## P5: Confirmation
 
 **Purpose:** Present plan to user and determine next action.
@@ -442,6 +519,10 @@ Build plan.json with gap-fix tasks
 
 3. **executionContext handoff** (if "Execute now")
    ```
+   executionMethod = config.json.execution.method || "agent"
+   defaultExecutor = config.json.execution.default_executor || "gemini"
+   executorAssignments = index.json.plan.executor_assignments || {}
+
    executionContext = {
      planObject: {
        plan: plan.json contents,
@@ -449,7 +530,9 @@ Build plan.json with gap-fix tasks
      },
      explorations: [ exploration-*.json contents ],
      clarifications: clarificationContext,
-     executionMethod: config.json.execution.method || "agent",
+     executionMethod: executionMethod,
+     defaultExecutor: defaultExecutor,
+     executorAssignments: executorAssignments,
      phaseIndex: index.json contents,
      specRef: spec-ref contents (if loaded)
    }
@@ -457,6 +540,35 @@ Build plan.json with gap-fix tasks
    Hand off to /workflow:execute with executionContext in memory
    ```
 
+4. **Register artifact in state.json**
+   ```
+   Read .workflow/state.json
+   // Find upstream analyze artifact
+   upstream_analyze = state.json.artifacts
+     .filter(a => a.type == "analyze" && a.path == CONTEXT_DIR relative path)
+     .last()  // most recent
+
+   next_id = max(artifacts.filter(a => a.type == "plan").map(a => parseInt(a.id.replace("PLN-","")))) + 1
+
+   artifact = {
+     id: "PLN-{next_id padded to 3}",
+     type: "plan",
+     milestone: state.json.current_milestone,
+     phase: PHASE_NUM,
+     scope: scope,
+     path: OUTPUT_DIR relative to .workflow/,
+     status: "completed",
+     depends_on: upstream_analyze?.id || null,
+     harvested: false,
+     created_at: plan_start_time,
+     completed_at: now()
+   }
+
+   state.json.artifacts.push(artifact)
+   state.json.last_updated = now()
+   Write state.json (atomic: write tmp + rename)
+   ```
+
 ---
 
 ## Error Handling

package/workflows/retrospective.md

@@ -507,14 +507,14 @@ insight.routed_id = "SPEC-retro-{phase_num}-{INS_id}-{slug}.md"
 
 #### Target: note
 
-Reuse the existing `manage-memory-capture` skill in tip mode — do not duplicate the memory pipeline.
+Reuse the existing `manage-learn` skill in tip mode — do not duplicate the learning pipeline.
 
 ```
 note_text = "[Retro phase {NN} / {lens}] {insight.title}: {insight.summary}"
 tags = insight.tags + ["retrospective", "phase-{NN}", insight.lens]
 
 Skill({
-  skill: "manage-memory-capture",
+  skill: "manage-learn",
   args: "tip \"{note_text}\" --tag " + tags.join(",")
 })
 
@@ -667,7 +667,7 @@ Write .workflow/learning/learning-index.json
 
 ### Backward-compat append to specs/learnings.md
 
-`phase-transition` Step 5e already writes free-form learnings to `.workflow/specs/learnings.md`. To stay backward-compatible (so phase-transition's reader can still find retrospective output), append a one-line summary per insight:
+Append learnings to `.workflow/specs/learnings.md` (shared with milestone-complete's learning extraction). Append a one-line summary per insight:
 
 ```
 IF .workflow/specs/learnings.md exists:
@@ -679,7 +679,7 @@ IF .workflow/specs/learnings.md exists:
       Phase: {NN} | Source: retrospective | Insight: {INS_id} | Lens: {lens}
 ```
 
-If the file does not exist, do not create it (phase-transition owns its lifecycle).
+If the file does not exist, create it with a `## Entries` header.
 
 ---
 
@@ -707,7 +707,7 @@ Next steps (suggested):
   Skill({ skill: "manage-status" })                                    — Review project state
   Skill({ skill: "manage-issue", args: "list --source retrospective" }) — Triage created issues
   Skill({ skill: "manage-learn", args: "list" })                       — Browse the lessons library
-  Skill({ skill: "maestro-phase-transition" })                         — Close the phase if not yet transitioned
+  Skill({ skill: "maestro-milestone-audit" })                          — Audit milestone if all phases done
 ```
 
 If `mode == "range"` or `--all`, loop Stages 3–8 per phase, then print an aggregate summary at the end:

package/workflows/roadmap.md

@@ -4,6 +4,15 @@ Interactive roadmap creation with iterative refinement. Lightweight path from re
 
 ---
 
+## Worktree Guard
+
+```
+# Block in worktree
+IF file_exists(".workflow/worktree-scope.json"):
+  ERROR "Cannot run maestro-roadmap inside a worktree. Run from the main worktree."
+  EXIT
+```
+
 ## Step 1: Session Initialization
 
 ```javascript
@@ -61,7 +70,7 @@ IF .workflow/state.json exists:
     - key_decisions[] → architectural_constraints
     - blockers[] → known_risks
 
-IF .workflow/codebase/ exists (from spec-map or codebase-rebuild):
+IF .workflow/codebase/ exists (from codebase-rebuild or codebase-refresh):
   Read available codebase docs for feature inventory
 ```
 
@@ -302,10 +311,9 @@ Phase directories use `{NN}-{slug}` format (e.g., `01-auth`, `02-api`).
 
    **Requirements traceability**: Cross-check that every Active requirement from project.md maps to exactly one phase. Surface unmapped requirements as gaps.
 
-2. **Create phase directories**: `.workflow/phases/{NN}-{slug}/` for each phase
-   - Create empty `index.json` in each
+2. **Ensure scratch directory**: `mkdir -p .workflow/scratch/`
 
-3. **Update state.json** (if exists): set `current_phase: 1`
+3. **Update state.json** (if exists): set milestones from roadmap, set `current_milestone` to first milestone
 
 ---
 

package/workflows/spec-generate.md

@@ -2,6 +2,15 @@
 
 Specification document chain producing a complete specification package (Product Brief, PRD, Architecture, Epics, Roadmap) through 7 sequential phases with multi-CLI analysis and interactive refinement. Pure documentation — no code generation.
 
+## Worktree Guard
+
+```
+# Block in worktree
+IF file_exists(".workflow/worktree-scope.json"):
+  ERROR "Cannot run maestro-spec-generate inside a worktree. Run from the main worktree."
+  EXIT
+```
+
 ## Pipeline Position
 
 ```

package/workflows/status.md

@@ -44,43 +44,57 @@ Status dashboard with intelligent routing.
 
 ---
 
-## Step 2: Load Phase Details
+## Step 2: Build Virtual Phase View from Artifact Registry
 
-For each phase directory in `.workflow/phases/*/`:
+Derive phase progress from `state.json.artifacts[]`:
 
-1. Read `index.json` if exists:
-   - Extract: phase number, slug, title, status, goal
-   - Extract: plan (task_count, tasks_completed), execution progress
-   - Extract: verification status, validation status, uat status
-
-2. Build phase summary array:
-   ```
-   phases[] = {
-     number, slug, title, status,
-     tasks_total, tasks_completed,
-     verification_status, validation_status
-   }
-   ```
+```
+// Group artifacts by phase for current milestone
+milestone_artifacts = state.json.artifacts.filter(a => a.milestone == current_milestone)
+
+// Build phase view from roadmap + artifact registry
+phases_from_roadmap = parse roadmap.md → list of { number, slug, title }
+
+FOR each phase IN phases_from_roadmap:
+  phase_artifacts = milestone_artifacts.filter(a => a.phase == phase.number)
+  has_analyze = phase_artifacts.some(a => a.type == "analyze" && a.status == "completed")
+  has_plan = phase_artifacts.some(a => a.type == "plan" && a.status == "completed")
+  has_execute = phase_artifacts.some(a => a.type == "execute" && a.status == "completed")
+  has_verify = phase_artifacts.some(a => a.type == "verify" && a.status == "completed")
+
+  // Derive status from artifact chain
+  status = has_verify ? "verified" :
+           has_execute ? "executed" :
+           has_plan ? "planned" :
+           has_analyze ? "analyzed" :
+           "pending"
+
+  // Get task counts from plan artifacts
+  plan_artifact = phase_artifacts.find(a => a.type == "plan" && a.status == "completed")
+  IF plan_artifact:
+    plan_json = read .workflow/{plan_artifact.path}/plan.json
+    tasks_total = plan_json.task_ids.length
+    tasks_completed = count .task/TASK-*.json where status == "completed"
+
+phases[] = { number, slug, title, status, tasks_total, tasks_completed, has_verify }
+
+// Also show adhoc artifacts
+adhoc_artifacts = milestone_artifacts.filter(a => a.scope == "adhoc")
+```
 
 ---
 
-## Step 2.5: Roadmap ↔ State Consistency Check
-
-Verify that `roadmap.md` and `state.json` agree on phase structure:
+## Step 2.5: Artifact Registry Consistency Check
 
 ```
 IF .workflow/roadmap.md exists:
   roadmap_phases = parse phase headings from roadmap.md (count "### Phase N:" entries)
-  state_total = state.json.phases_summary.total
-  actual_dirs = count .workflow/phases/*/ directories
+  artifact_phases = unique phase numbers from milestone_artifacts
 
-  IF roadmap_phases != state_total OR roadmap_phases != actual_dirs:
-    Display WARNING:
-      ⚠️  STATE SYNC WARNING
-      Roadmap phases: {roadmap_phases}
-      State total:    {state_total}
-      Phase dirs:     {actual_dirs}
-      Run /maestro-roadmap or /maestro-phase-add to reconcile.
+  // Check for unregistered work (artifacts without matching roadmap phases)
+  orphan_artifacts = milestone_artifacts.filter(a => a.phase && !roadmap_phases.includes(a.phase))
+  IF orphan_artifacts.length > 0:
+    Display WARNING: "Artifacts reference phases not in roadmap"
 
 ELSE IF NOT .workflow/roadmap.md exists AND state.json.phases_summary.total > 0:
   Display WARNING:
@@ -175,6 +189,41 @@ Status icons:
 - `[ ]` pending
 - `[!]` blocked
 
+### Step 4.2: Render Worktree Status
+
+```
+IF file_exists(".workflow/worktree-scope.json"):
+  // Running inside a worktree
+  Read .workflow/worktree-scope.json → scope
+  Display:
+    ┌─────────────────────────────────────────┐
+    │ WORKTREE MODE                           │
+    ├─────────────────────────────────────────┤
+    │ Milestone: {scope.milestone}            │
+    │ Branch:    {scope.branch}               │
+    │ Phases:    {scope.owned_phases}         │
+    │ Main:      {scope.main_worktree}        │
+    └─────────────────────────────────────────┘
+
+ELSE IF file_exists(".workflow/worktrees.json"):
+  // Running in main worktree with active worktrees
+  Read .workflow/worktrees.json → registry
+  activeWorktrees = registry.worktrees.filter(w => w.status === "active")
+
+  IF activeWorktrees.length > 0:
+    Display:
+      ┌─────────────────────────────────────────┐
+      │ ACTIVE WORKTREES                        │
+      ├─────────────────────────────────────────┤
+      {for each wt in activeWorktrees}
+      │ {wt.milestone} | {wt.branch} | {wt.path} │
+      {/for}
+      │                                         │
+      │ Sync:  /maestro-fork <milestone> --sync │
+      │ Merge: /maestro-merge <milestone>       │
+      └─────────────────────────────────────────┘
+```
+
 ---
 
 ## Step 5: Route Next Step

package/workflows/ui-design.md

@@ -14,28 +14,30 @@ Pipeline position: analyze -> **ui-design** -> plan -> execute -> verify
 
 ## Prerequisites
 
-- `.workflow/` directory initialized
-- Phase directory exists at `.workflow/phases/{NN}-{slug}/` — OR scratch mode for standalone
+- `.workflow/` directory initialized (or auto-bootstrap)
 - Python 3 available (required by ui-ux-pro-max skill)
 - ui-ux-pro-max skill installed (search.py available)
 
 ---
 
-## Phase Resolution
+## Scope Resolution
 
 ```
-Input: <phase> argument (number or slug) OR topic text
+Input: <phase> argument (number) OR topic text
 
-IF argument is a number or matches phase pattern:
-  1. Find .workflow/phases/{NN}-*/index.json
-  2. Set PHASE_DIR = resolved path, SCRATCH_MODE = false
+All output goes to scratch: .workflow/scratch/ui-design-{slug}-{date}/
 
-ELSE (topic text — scratch mode):
+IF argument is a number:
+  1. Resolve phase slug from roadmap.md
+  2. OUTPUT_DIR = .workflow/scratch/ui-design-{phase-slug}-{date}
+  3. scope = "phase", register artifact with phase number
+
+ELSE (topic text):
   1. slug = slugify(topic)
-  2. PHASE_DIR = .workflow/scratch/ui-design-{slug}-{YYYYMMDD}
-  3. mkdir -p ${PHASE_DIR}
-  4. Create minimal index.json (type="ui-design", goal=topic)
-  5. Set SCRATCH_MODE = true
+  2. OUTPUT_DIR = .workflow/scratch/ui-design-{slug}-{date}
+  3. scope = state.json.current_milestone ? "adhoc" : "standalone"
+
+mkdir -p ${OUTPUT_DIR}
 ```
 
 ---

package/workflows/verify.md

@@ -12,14 +12,50 @@ Dual verification: Goal-Backward structural verification + Nyquist test coverage
 
 ---
 
-## Phase Resolution
-
-```
-Input: <phase> argument (number or slug)
-  1. If number: find .workflow/phases/{NN}-*/index.json
-  2. If slug: find .workflow/phases/*-{slug}/index.json
-  3. Validate execution has occurred (index.json.execution.tasks_completed > 0)
-  4. Set PHASE_DIR = resolved path
+## Scope Resolution
+
+```
+Input: [phase] argument OR --dir <path>
+
+# Worktree scope check
+IF file_exists(".workflow/worktree-scope.json"):
+  scope = read(".workflow/worktree-scope.json")
+  IF <phase> is a number AND <phase> NOT IN scope.owned_phases:
+    ERROR "Phase {phase} not owned by this worktree. Owned: {scope.owned_phases}"
+    EXIT
+
+IF --dir <path> is provided:
+  // Single plan verification
+  PLAN_DIRS = [<path>]
+  VERIFY_MODE = "single"
+  VERIFY_OUTPUT_DIR = <path>  // verification.json written into plan dir
+
+ELSE IF no arguments:
+  // Milestone-level verification
+  Read state.json.artifacts
+  PLAN_DIRS = artifacts.filter(a =>
+    a.milestone == current_milestone &&
+    a.type == "execute" &&
+    a.status == "completed"
+  ).map(a => a.path)
+  IF PLAN_DIRS is empty: ERROR E001
+  VERIFY_MODE = "milestone"
+  milestone_slug = slugify(current_milestone name)
+  VERIFY_OUTPUT_DIR = .workflow/scratch/verify-{milestone_slug}-{date}/
+  mkdir -p VERIFY_OUTPUT_DIR
+
+ELSE IF argument is a number:
+  // Phase-level verification
+  Read state.json.artifacts
+  PLAN_DIRS = artifacts.filter(a =>
+    a.milestone == current_milestone &&
+    a.type == "execute" &&
+    a.phase == arg &&
+    a.status == "completed"
+  ).map(a => a.path)
+  IF PLAN_DIRS is empty: ERROR E001
+  VERIFY_MODE = "phase"
+  VERIFY_OUTPUT_DIR = first plan dir  // single plan → write there
 ```
 
 ---