maestro-flow 0.3.10 → 0.3.12

package/workflows/issue.md

@@ -178,8 +178,13 @@ 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)
+   c. For each other-milestone phase, resolve phase dir and check if plan.json exists:
+      Read .workflow/state.json → state; artifacts = state.artifacts ?? []
+      IF artifacts.length > 0:
+        art = artifacts.find(a => a.type === 'plan' && a.phase === phaseNum)
+        IF art: Read .workflow/{art.path}/plan.json (if exists)
+      ELSE:
+        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}"
@@ -449,8 +454,13 @@ Process bidirectional link:
    If not found → error: "Issue {ID} not found"
 
 2. Locate task file:
-   - Search .workflow/phases/*/.task/{TASK_ID}.json
-   - If not found → search .workflow/scratch/*/.task/{TASK_ID}.json
+   - Read .workflow/state.json → state
+   - artifacts = state.artifacts ?? []
+   - IF artifacts.length > 0:
+       Search .workflow/scratch/*/.task/{TASK_ID}.json (artifact registry scratch paths)
+     ELSE:
+       Search .workflow/phases/*/.task/{TASK_ID}.json (legacy)
+   - Also search .workflow/scratch/*/.task/{TASK_ID}.json (standalone scratch tasks)
    - If still not found → error: "Task {TASK_ID} not found"
 
 3. Update issue record:

package/workflows/learn.md

@@ -86,9 +86,14 @@ IF .workflow/state.json exists:
   IF state.current_phase is not null:
     phase = state.current_phase
 
-    # Resolve slug
-    Glob ".workflow/phases/{NN}-*/" where NN == phase
-    phase_slug = matched directory basename (e.g. "01-auth")
+    # Resolve slug — artifact registry first, fallback to legacy phases/
+    artifacts = state.artifacts ?? []
+    IF artifacts.length > 0:
+      art = artifacts.find(a => a.phase === phase)
+      phase_slug = art?.slug ?? "phase-" + phase
+    ELSE:
+      Glob ".workflow/phases/{NN}-*/" where NN == phase
+      phase_slug = matched directory basename (e.g. "01-auth")
 ```
 
 If `--phase 0` is passed, force `phase = null, phase_slug = null` regardless.
@@ -299,8 +304,17 @@ IF row is null → error E004: "Insight {target_id} not found"
 ```
 phase_context = null
 IF row.phase_slug is not null:
-  phase_dir = ".workflow/phases/" + row.phase_slug
-  IF directory exists:
+  // Resolve phase dir — artifact registry first, fallback to legacy phases/
+  Read .workflow/state.json → state
+  artifacts = state.artifacts ?? []
+  phase_dir = null
+  IF artifacts.length > 0:
+    art = artifacts.find(a => a.phase === row.phase && a.path)
+    IF art: phase_dir = ".workflow/" + art.path
+  ELSE:
+    phase_dir = ".workflow/phases/" + row.phase_slug
+
+  IF phase_dir AND directory exists:
     phase_context = {
       title: read index.json.title from phase_dir,
       status: read index.json.status,

package/workflows/maestro.md

@@ -789,6 +789,7 @@ const context = {
 const AUTO_FLAG_MAP = {
   'maestro-analyze':       '-y',
   'maestro-brainstorm':    '-y',
+  'maestro-roadmap':       '-y',
   'maestro-ui-design':     '-y',
   'maestro-plan':          '--auto',
   'maestro-spec-generate': '-y',

package/workflows/map.md

@@ -1,111 +1,111 @@
-# Workflow: map
-
-Codebase scanning with parallel mapper agents.
-
----
-
-## Step 1: Pre-check
-
-1. Check if `.workflow/research/` already exists with documents:
-   - If documents exist and are recent (< 7 days):
-     - Ask user: "Codebase map exists. Refresh or skip?"
-     - "refresh" → continue to Step 2 (overwrite)
-     - "skip" → exit with route suggestions
-   - If documents are stale or missing → continue to Step 2
-
-2. Create `.workflow/research/` directory if it does not exist.
-
----
-
-## Step 2: Spawn Parallel Mapper Agents
-
-Spawn 4 parallel `workflow-codebase-mapper` agents. Each agent scans the codebase independently with a specific focus and writes its output directly to `.workflow/research/`.
-
-```
-Agent 1: tech focus
-  Scan: package.json, go.mod, requirements.txt, build files, dependencies
-  Output: .workflow/research/STACK.md
-  Content: languages, frameworks, build tools, key dependencies, versions
-
-Agent 2: arch focus
-  Scan: directory structure, module boundaries, entry points, data flow
-  Output: .workflow/research/ARCHITECTURE.md
-  Content: architecture style, layer separation, module graph, key abstractions
-
-Agent 3: features focus
-  Scan: routes, handlers, components, services, models
-  Output: .workflow/research/FEATURES.md
-  Content: feature inventory, feature-to-file mapping, completeness assessment
-
-Agent 4: concerns focus
-  Scan: error handling, logging, tests, config, security, performance
-  Output: .workflow/research/PITFALLS.md
-  Content: tech debt, missing tests, security gaps, performance concerns, known issues
-```
-
-If `$ARGUMENTS` (focus area) is provided, pass it to each agent as a focus filter: "Prioritize analysis of {focus_area} subsystem."
-
-**Load project specs for mapper context:**
-```
-specs_content = maestro spec load --category planning
-```
-
-**Agent spawn pattern:**
-```
-For each agent (1-4) in parallel:
-  Agent({
-    subagent_type: "workflow-codebase-mapper",
-    prompt: "Focus: {focus}. Scan the codebase and write {output_file}.
-             Project specs for reference: ${specs_content}
-             Write directly to the file. Return only a confirmation with line count.",
-    run_in_background: false
-  })
-```
-
----
-
-## Step 3: Verification
-
-After all 4 agents complete:
-
-1. Verify all documents exist with content:
-   ```
-   .workflow/research/STACK.md         — exists, >10 lines
-   .workflow/research/ARCHITECTURE.md  — exists, >10 lines
-   .workflow/research/FEATURES.md      — exists, >10 lines
-   .workflow/research/PITFALLS.md      — exists, >10 lines
-   ```
-
-2. If any document is missing or empty:
-   - Log which agent failed
-   - Re-spawn that specific agent (max 1 retry per agent)
-
----
-
-## Step 4: Summary
-
-1. Create `.workflow/research/SUMMARY.md`:
-   - Read all 4 documents
-   - Write a consolidated executive summary covering:
-     - Tech stack overview (from STACK.md)
-     - Architecture highlights (from ARCHITECTURE.md)
-     - Feature inventory count (from FEATURES.md)
-     - Top 3 concerns (from PITFALLS.md)
-     - Recommendations for next steps
-
----
-
-## Step 5: Commit and Route
-
-1. If git repo: commit `.workflow/research/` with message `"chore: map codebase"`
-
-2. Display summary:
-   ```
-   Codebase mapped successfully.
-   Documents: 5 files in .workflow/research/
-   ```
-
-3. Route next steps based on project state:
-   - No `.workflow/state.json` → "Run `/workflow:init` to initialize project"
-   - Has state, no roadmap → "Run `/workflow:init` to create roadmap"
-   - Has roadmap → "Run `/workflow:plan {next_phase}` to start planning"
+# Workflow: map
+
+Codebase scanning with parallel mapper agents.
+
+---
+
+## Step 1: Pre-check
+
+1. Check if `.workflow/research/` already exists with documents:
+   - If documents exist and are recent (< 7 days):
+     - Ask user: "Codebase map exists. Refresh or skip?"
+     - "refresh" → continue to Step 2 (overwrite)
+     - "skip" → exit with route suggestions
+   - If documents are stale or missing → continue to Step 2
+
+2. Create `.workflow/research/` directory if it does not exist.
+
+---
+
+## Step 2: Spawn Parallel Mapper Agents
+
+Spawn 4 parallel `workflow-codebase-mapper` agents. Each agent scans the codebase independently with a specific focus and writes its output directly to `.workflow/research/`.
+
+```
+Agent 1: tech focus
+  Scan: package.json, go.mod, requirements.txt, build files, dependencies
+  Output: .workflow/research/STACK.md
+  Content: languages, frameworks, build tools, key dependencies, versions
+
+Agent 2: arch focus
+  Scan: directory structure, module boundaries, entry points, data flow
+  Output: .workflow/research/ARCHITECTURE.md
+  Content: architecture style, layer separation, module graph, key abstractions
+
+Agent 3: features focus
+  Scan: routes, handlers, components, services, models
+  Output: .workflow/research/FEATURES.md
+  Content: feature inventory, feature-to-file mapping, completeness assessment
+
+Agent 4: concerns focus
+  Scan: error handling, logging, tests, config, security, performance
+  Output: .workflow/research/PITFALLS.md
+  Content: tech debt, missing tests, security gaps, performance concerns, known issues
+```
+
+If `$ARGUMENTS` (focus area) is provided, pass it to each agent as a focus filter: "Prioritize analysis of {focus_area} subsystem."
+
+**Load project specs for mapper context:**
+```
+specs_content = maestro spec load --category arch
+```
+
+**Agent spawn pattern:**
+```
+For each agent (1-4) in parallel:
+  Agent({
+    subagent_type: "workflow-codebase-mapper",
+    prompt: "Focus: {focus}. Scan the codebase and write {output_file}.
+             Project specs for reference: ${specs_content}
+             Write directly to the file. Return only a confirmation with line count.",
+    run_in_background: false
+  })
+```
+
+---
+
+## Step 3: Verification
+
+After all 4 agents complete:
+
+1. Verify all documents exist with content:
+   ```
+   .workflow/research/STACK.md         — exists, >10 lines
+   .workflow/research/ARCHITECTURE.md  — exists, >10 lines
+   .workflow/research/FEATURES.md      — exists, >10 lines
+   .workflow/research/PITFALLS.md      — exists, >10 lines
+   ```
+
+2. If any document is missing or empty:
+   - Log which agent failed
+   - Re-spawn that specific agent (max 1 retry per agent)
+
+---
+
+## Step 4: Summary
+
+1. Create `.workflow/research/SUMMARY.md`:
+   - Read all 4 documents
+   - Write a consolidated executive summary covering:
+     - Tech stack overview (from STACK.md)
+     - Architecture highlights (from ARCHITECTURE.md)
+     - Feature inventory count (from FEATURES.md)
+     - Top 3 concerns (from PITFALLS.md)
+     - Recommendations for next steps
+
+---
+
+## Step 5: Commit and Route
+
+1. If git repo: commit `.workflow/research/` with message `"chore: map codebase"`
+
+2. Display summary:
+   ```
+   Codebase mapped successfully.
+   Documents: 5 files in .workflow/research/
+   ```
+
+3. Route next steps based on project state:
+   - No `.workflow/state.json` → "Run `/workflow:init` to initialize project"
+   - Has state, no roadmap → "Run `/workflow:init` to create roadmap"
+   - Has roadmap → "Run `/workflow:plan {next_phase}` to start planning"

package/workflows/merge.md

@@ -103,15 +103,31 @@ IF NOT target:
 completedPhases = []
 incompletePhases = []
 
-for (phaseNum of target.owned_phases):
-  NN = String(phaseNum).padStart(2, '0')
-  Glob: {target.path}/.workflow/phases/{NN}-*/index.json
-  Read → wtIndex
+// Read worktree state for artifact registry check
+Read {target.path}/.workflow/state.json → wtState (if exists)
+wtArtifacts = wtState?.artifacts ?? []
+useArtifactRegistry = wtArtifacts.length > 0
+
+IF useArtifactRegistry:
+  // Check phase completeness via artifact registry
+  for (phaseNum of target.owned_phases):
+    execArtifacts = wtArtifacts.filter(a => a.type === 'execute' && a.phase === phaseNum)
+    IF execArtifacts.some(a => a.status === 'completed'):
+      completedPhases.push({ phase: phaseNum })
+    ELSE:
+      status = execArtifacts.length > 0 ? execArtifacts[0].status : 'no_execute_artifact'
+      incompletePhases.push({ phase: phaseNum, status })
+ELSE:
+  // Legacy: check phases/ directory
+  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 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:"
@@ -181,51 +197,90 @@ 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 useArtifactRegistry:
+  // 7a: Copy scratch dirs from worktree to main
+  Read {target.path}/.workflow/state.json → wtState
+  wtArtifacts = wtState?.artifacts ?? []
+  milestoneArtifacts = wtArtifacts.filter(a =>
+    a.path && (a.milestone === target.milestone || target.owned_phases.includes(a.phase))
+  )
+  for (art of milestoneArtifacts):
+    srcDir = target.path + "/.workflow/" + art.path
+    dstDir = ".workflow/" + art.path
+    IF directory_exists(srcDir):
+      Bash("mkdir -p {dstDir} && cp -r {srcDir}/* {dstDir}/")
+
+  // 7b: Merge artifact registries
+  mainArtifacts = mainState.artifacts ?? []
+  existingIds = new Set(mainArtifacts.map(a => a.id))
+  for (art of wtArtifacts):
+    IF existingIds.has(art.id):
+      // Update existing artifact status
+      idx = mainArtifacts.findIndex(a => a.id === art.id)
+      mainArtifacts[idx] = art
+    ELSE:
+      mainArtifacts.push(art)
+  mainState.artifacts = mainArtifacts
+
+  // Record merge in transition history
+  mainState.transition_history = mainState.transition_history ?? []
+  mainState.transition_history.push({
+    milestone_num: target.milestone_num,
+    milestone: target.milestone,
+    action: "worktree_merge",
+    completed_at: getUtc8ISOString(),
+    branch: target.branch,
+    phases: target.owned_phases
+  })
+
+ELSE:
+  // Legacy: copy phase directories from worktree to main
+  // 7a: Copy all owned phase directories
+  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: Update phase summaries
+  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 (both paths)
+IF NOT useArtifactRegistry:
+  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):
@@ -236,12 +291,15 @@ IF wtState?.accumulated_context:
 mainState.last_updated = getUtc8ISOString()
 Write .workflow/state.json: mainState
 
-// 7c: Update roadmap.md
+// 7c: Update roadmap.md (mark completed phases)
 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
+  IF useArtifactRegistry:
+    isCompleted = completedPhases.some(p => p.phase === phaseNum)
+  ELSE:
+    Read phase index → isCompleted = (status === "completed")
+  IF isCompleted:
+    Append " ✅ COMPLETED" to phase title line in roadmap
 Write .workflow/roadmap.md: roadmap
 ```