maestro-flow 0.3.8 → 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)
@@ -415,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.
@@ -464,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

@@ -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
@@ -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
 ```
 
 ---

package/.claude/commands/maestro-phase-add.md

@@ -1,63 +0,0 @@
----
-name: maestro-phase-add
-description: Add or insert a new phase into the project roadmap with automatic renumbering
-argument-hint: "<slug> <title> [--after N]"
-allowed-tools:
-  - Read
-  - Write
-  - Edit
-  - Bash
-  - Glob
-  - Grep
-  - Agent
-  - AskUserQuestion
----
-
-<purpose>
-Add a new phase to the project roadmap, either appending it at the end or inserting it after a specified phase number. Handles automatic renumbering of subsequent phase directories, updates roadmap.md with the new entry, and initializes the phase directory with an index.json so it is ready for planning.
-</purpose>
-
-<required_reading>
-@~/.maestro/workflows/phase-add.md
-</required_reading>
-
-<deferred_reading>
-- [index.json](~/.maestro/templates/index.json) — read when creating new phase index
-</deferred_reading>
-
-<context>
-$ARGUMENTS -- phase slug and title (required), optional --after N flag.
-
-**Flags:**
-- `--after N` -- Insert after phase N (renumbers subsequent phases). If omitted, appends at end.
-
-**State files:**
-- `.workflow/roadmap.md` -- milestone and phase structure
-- `.workflow/state.json` -- project-level state
-- `.workflow/phases/` -- existing phase directories
-</context>
-
-<execution>
-Follow '~/.maestro/workflows/phase-add.md' completely.
-
-**Next-step routing on completion:**
-- Plan the new phase → Skill({ skill: "maestro-plan", args: "{new_phase_number}" })
-- Analyze before planning → Skill({ skill: "maestro-analyze", args: "{new_phase_number}" })
-- View updated roadmap → Skill({ skill: "manage-status" })
-</execution>
-
-<error_codes>
-| Code | Meaning                          |
-|------|----------------------------------|
-| E001 | Phase name/slug required         |
-| E002 | roadmap.md not found             |
-| E003 | Duplicate phase name/slug exists |
-</error_codes>
-
-<success_criteria>
-- [ ] Phase directory created with NN-slug format
-- [ ] roadmap.md updated with new phase entry at correct position
-- [ ] index.json initialized in new phase directory with status = "pending"
-- [ ] Subsequent phases renumbered correctly (if --after N used)
-- [ ] state.json updated if renumbering affected tracked phases
-</success_criteria>

package/.claude/commands/maestro-phase-transition.md

@@ -1,75 +0,0 @@
----
-name: maestro-phase-transition
-description: Mark current or specified phase as complete, extract learnings, advance to next phase
-argument-hint: "[phase-number] [--force]"
-allowed-tools:
-  - Read
-  - Write
-  - Edit
-  - Bash
-  - Glob
-  - Grep
-  - Agent
-  - AskUserQuestion
----
-
-<purpose>
-Transition from one phase to the next after verification passes. Validates that the current phase meets all completion criteria (tasks done, verification passed, no unresolved gaps), marks it complete in the phase index, and advances the project state to the next phase. If the next phase directory does not exist, it is created and initialized.
-</purpose>
-
-<required_reading>
-@~/.maestro/workflows/phase-transition.md
-</required_reading>
-
-<deferred_reading>
-- [state.json](~/.maestro/templates/state.json) — read when updating project state
-- [index.json](~/.maestro/templates/index.json) — read when updating phase index
-</deferred_reading>
-
-<context>
-$ARGUMENTS -- phase number to transition from (optional, defaults to current_phase from state.json).
-
-**Flags:**
-- `--force` -- Skip gap check and force transition even with warnings
-
-**State files:**
-- `.workflow/state.json` -- project-level state (current_phase, milestones)
-- `.workflow/phases/{NN}-{slug}/index.json` -- phase metadata and status
-- `.workflow/phases/{NN}-{slug}/verification.json` -- verification results
-- `.workflow/phases/{NN}-{slug}/review.json` -- code review results (if exists)
-</context>
-
-<execution>
-Follow '~/.maestro/workflows/phase-transition.md' completely.
-
-**Next-step routing on completion:**
-- Next phase exists, ready to plan → Skill({ skill: "maestro-plan", args: "{next_phase}" })
-- Next phase needs analysis first → Skill({ skill: "maestro-analyze", args: "{next_phase}" })
-- Next phase needs UI design → Skill({ skill: "maestro-ui-design", args: "{next_phase}" })
-- All phases in milestone complete → Skill({ skill: "maestro-milestone-audit" })
-- View updated dashboard → Skill({ skill: "manage-status" })
-</execution>
-
-<error_codes>
-| Code | Meaning                                    |
-|------|--------------------------------------------|
-| E001 | Phase number required (could not determine) |
-| E002 | Phase has not passed verification           |
-| E003 | Phase has unresolved critical gaps          |
-| W001 | Phase has warnings but no blockers          |
-| W002 | UAT test failures exist (quality-test) — review recommended before transition |
-| W003 | Code review verdict is BLOCK — Skill({ skill: "quality-review" }) findings should be fixed first |
-| W004 | Code review not yet run — Skill({ skill: "quality-review" }) recommended before transition |
-| W005 | Orphan specs found in wiki — consider linking or removing before transition |
-</error_codes>
-
-<success_criteria>
-- [ ] Current phase index.json marked status = "complete" with completed_at timestamp
-- [ ] Next phase directory created (if not already existing)
-- [ ] Next phase index.json initialized with status = "pending"
-- [ ] state.json current_phase updated to next phase number
-- [ ] Wiki health score reported — warnings emitted if orphan specs found
-- [ ] Learnings extracted and appended to specs/learnings.md
-- [ ] project.md requirements moved Active → Validated for completed phase
-- [ ] roadmap.md phase marked as ✅ COMPLETED
-</success_criteria>