maestro-flow 0.3.15 → 0.3.17

package/workflows/map.md

@@ -19,48 +19,20 @@ Codebase scanning with parallel mapper agents.
 
 ## 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
-  })
-```
+Spawn 4 parallel `workflow-codebase-mapper` agents, each writing to `.workflow/research/`:
+
+| Agent | Focus | Output | Content |
+|-------|-------|--------|---------|
+| 1 | tech | STACK.md | languages, frameworks, build tools, dependencies, versions |
+| 2 | arch | ARCHITECTURE.md | architecture style, layers, module graph, key abstractions |
+| 3 | features | FEATURES.md | feature inventory, feature-to-file mapping, completeness |
+| 4 | concerns | PITFALLS.md | tech debt, missing tests, security gaps, performance issues |
+
+If `$ARGUMENTS` provided, pass as focus filter to each agent.
+
+Load project specs: `maestro spec load --category arch`
+
+Each agent spawned in parallel as `workflow-codebase-mapper` subagent with specs context.
 
 ---
 
@@ -68,17 +40,8 @@ For each agent (1-4) in parallel:
 
 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)
+1. Verify all 4 documents exist with >10 lines each.
+2. If any missing/empty → log failure, re-spawn that agent (max 1 retry).
 
 ---
 

package/workflows/merge.md

@@ -8,25 +8,15 @@ Merges operate at the **milestone level** — one worktree per milestone, all ph
 
 ## 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
+```
+Timestamps use UTC+8 ISO format throughout.
+
+Parse from $ARGUMENTS:
+  --force       → force (skip incomplete-phase confirmation)
+  --dry-run     → dryRun (preview only)
+  --no-cleanup  → noCleanup (keep worktree after merge)
+  --continue    → continueMode (resume after conflict resolution)
+  -m <N> or bare <N> → milestoneNum (1-based)
 ```
 
 ---
@@ -34,15 +24,9 @@ const milestoneNum = mFlagMatch
 ## 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
+Reject: .workflow/worktree-scope.json present (E001 — must run from main worktree).
+Require: .workflow/worktrees.json (E002 — nothing to merge without registry).
+Read registry from worktrees.json.
 ```
 
 ---
@@ -50,17 +34,8 @@ 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
+Detect worktree entries whose directories no longer exist.
+If stale entries found → warn (W001), remove from registry, rewrite worktrees.json.
 ```
 
 ---
@@ -68,31 +43,9 @@ IF staleEntries.length > 0:
 ## 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
+--continue → load target from .workflow/.merge-state.json (E003 if missing), skip to Step 7.
+Otherwise → find active worktree for milestoneNum in registry (E004 if no milestone specified).
+If no matching target → display active worktrees and exit.
 ```
 
 ---
@@ -100,37 +53,9 @@ IF NOT target:
 ## Step 5: Validate Readiness
 
 ```
-completedPhases = []
-incompletePhases = []
-
-// Read worktree state for artifact registry check
-Read {target.path}/.workflow/state.json → wtState (if exists)
-wtArtifacts = wtState?.artifacts ?? []
-
-// 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 })
-
-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
+Check phase completeness via worktree artifact registry (execute artifacts → completed or incomplete).
+If incomplete phases and not --force → warn (W002), confirm with user.
+If --dry-run → display merge preview (branch, milestone, completed/incomplete phases) and exit.
 ```
 
 ---
@@ -138,39 +63,12 @@ IF dryRun:
 ## 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
+6a: Pull main into worktree branch (cd {target.path} && git merge main --no-edit).
+    On conflict → warn (W003), instruct to resolve in worktree, exit.
+
+6b: Merge worktree branch into main (git merge {target.branch} --no-ff).
+    On conflict → save .workflow/.merge-state.json {target, phase:"git_merge_conflict"},
+    instruct: resolve, git merge --continue, then /maestro-merge --continue. Exit.
 
 Display "Git merge successful."
 ```
@@ -182,63 +80,19 @@ Display "Git merge successful."
 ```
 Step_7:
 
-Display "Syncing workflow artifacts for M{target.milestone_num} ({target.milestone})..."
-
-Read .workflow/state.json → mainState
-
-// 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
-})
-
-// Merge accumulated context from worktree
-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 (mark completed phases)
-Read .workflow/roadmap.md → roadmap
-for (phaseNum of target.owned_phases):
-  isCompleted = completedPhases.some(p => p.phase === phaseNum)
-  IF isCompleted:
-    Append " ✅ COMPLETED" to phase title line in roadmap
-Write .workflow/roadmap.md: roadmap
+7a: Copy milestone artifact directories from worktree → main .workflow/.
+    Filter: artifacts matching target.milestone or target.owned_phases.
+
+7b: Merge artifact registries — update existing by ID, append new entries.
+
+7c: Record in mainState.transition_history:
+    { milestone_num, milestone, action:"worktree_merge", completed_at, branch, phases }
+
+7d: Merge accumulated_context — deduplicate key_decisions, append deferred items.
+
+Update mainState.last_updated, write .workflow/state.json.
+
+7e: Mark completed phases in .workflow/roadmap.md with completion indicator.
 ```
 
 ---
@@ -246,18 +100,9 @@ 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")
+Unless --no-cleanup: remove git worktree and delete branch.
+Remove target entry from worktrees.json registry.
+Clean up .workflow/.merge-state.json if present.
 ```
 
 ---

package/workflows/milestone-audit.md

@@ -12,65 +12,27 @@ Cross-phase integration audit for milestone completion. Based on artifact regist
 
 2. Parse `.workflow/roadmap.md` to identify all phases belonging to this milestone
 
-3. Group artifacts by type for this milestone:
-   ```
-   FROM state.json.artifacts
-   WHERE milestone = target_milestone
-   GROUP BY type
-
-   → analyze_artifacts: [ANL-001, ANL-002, ...]
-   → plan_artifacts:    [PLN-001, PLN-002, ...]
-   → execute_artifacts: [EXC-001, EXC-002, ...]
-   → verify_artifacts:  [VRF-001, ...]
-   ```
+3. Group milestone artifacts by type → `analyze_artifacts`, `plan_artifacts`, `execute_artifacts`, `verify_artifacts`
 
 ---
 
 ## Step 2: Phase Coverage Check
 
-For each phase defined in roadmap for this milestone:
+Parse roadmap.md phases for this milestone. For each phase, verify completed artifacts exist for analyze, plan, and execute types.
 
-```
-phases_from_roadmap = parse roadmap.md → list of { number, slug, title }
-
-coverage = {}
-FOR each phase IN phases_from_roadmap:
-  has_analyze = artifacts.some(a => a.type == "analyze" && a.phase == phase.number && a.status == "completed")
-  has_plan = artifacts.some(a => a.type == "plan" && a.phase == phase.number && a.status == "completed")
-  has_execute = artifacts.some(a => a.type == "execute" && a.phase == phase.number && a.status == "completed")
-
-  coverage[phase.number] = { has_analyze, has_plan, has_execute }
-
-  IF NOT has_execute:
-    WARN: "Phase {phase.number} ({phase.title}) missing execute artifact"
-```
+WARN if any phase is missing its execute artifact: "Phase {number} ({title}) missing execute artifact"
 
 ---
 
 ## Step 3: Ad-hoc Completeness Check
 
-```
-adhoc_artifacts = artifacts.filter(a => a.scope == "adhoc" && a.milestone == target_milestone)
-
-incomplete_adhoc = adhoc_artifacts.filter(a => a.status != "completed")
-IF incomplete_adhoc.length > 0:
-  WARN: "Ad-hoc artifacts incomplete: {list ids}"
-```
+Check all ad-hoc artifacts (`scope == "adhoc"`) for this milestone are completed. WARN if any incomplete (list ids).
 
 ---
 
 ## Step 4: Execution Completeness Check
 
-For each execute artifact, verify all tasks completed:
-
-```
-FOR each exc IN execute_artifacts:
-  plan_dir = exc.path
-  tasks = read all ${plan_dir}/.task/TASK-*.json
-  incomplete = tasks.filter(t => t.status != "completed" && t.status != "skipped")
-  IF incomplete.length > 0:
-    WARN: "Plan {plan_dir}: {incomplete.length} tasks not completed"
-```
+For each execute artifact, read `{path}/.task/TASK-*.json` and verify all tasks are completed or skipped. WARN if any tasks remain incomplete: "Plan {plan_dir}: {N} tasks not completed"
 
 ---
 

package/workflows/milestone-complete.md

@@ -18,13 +18,7 @@ Archive completed milestone, move artifacts to history, and prepare for next.
      - If NO → exit
    - If verdict is FAIL: ERROR E002
 
-3. Verify all artifacts completed:
-   ```
-   milestone_artifacts = state.json.artifacts.filter(a => a.milestone == target_milestone)
-   incomplete = milestone_artifacts.filter(a => a.status != "completed")
-   IF incomplete.length > 0:
-     ERROR E003: "Incomplete artifacts: {list ids and statuses}"
-   ```
+3. Verify all milestone artifacts have status "completed" → ERROR E003 if any incomplete (list ids and statuses)
 
 ---
 
@@ -40,12 +34,7 @@ Archive completed milestone, move artifacts to history, and prepare for next.
    cp .workflow/roadmap.md .workflow/milestones/{milestone}/roadmap-snapshot.md
    ```
 
-3. Archive scratch directories:
-   ```
-   FOR each artifact IN milestone_artifacts:
-     IF directory exists at .workflow/{artifact.path}:
-       cp -r .workflow/{artifact.path} .workflow/milestones/{milestone}/artifacts/{basename}/
-   ```
+3. Archive scratch directories: copy each milestone artifact's `.workflow/{artifact.path}` to `.workflow/milestones/{milestone}/artifacts/{basename}/`
 
 ---
 
@@ -66,37 +55,16 @@ Check existing entries to avoid duplicates when appending in Step 3.
    - Extract patterns discovered
    - Extract pitfalls encountered
 
-2. Aggregate learnings and append to `.workflow/specs/learnings.md` using `<spec-entry>` closed-tag format:
+2. Aggregate learnings and append to `.workflow/specs/learnings.md` using `<spec-entry>` closed-tag format. Each entry (strategy adjustment, pattern, or pitfall) follows this template:
    ```
-   For each strategy adjustment:
-     <spec-entry category="learning" keywords="{auto-extracted}" date="{YYYY-MM-DD}" source="milestone-complete">
-
-     ### {summary}
-
-     {content}
-     Milestone: {milestone}
-
-     </spec-entry>
-
-   For each pattern:
-     <spec-entry category="learning" keywords="{auto-extracted}" date="{YYYY-MM-DD}" source="milestone-complete">
-
-     ### {summary}
+   <spec-entry category="learning" keywords="{auto-extracted}" date="{YYYY-MM-DD}" source="milestone-complete">
 
-     {content}
-     Milestone: {milestone}
+   ### {summary}
 
-     </spec-entry>
+   {content}
+   Milestone: {milestone}
 
-   For each pitfall:
-     <spec-entry category="learning" keywords="{auto-extracted}" date="{YYYY-MM-DD}" source="milestone-complete">
-
-     ### {summary}
-
-     {content}
-     Milestone: {milestone}
-
-     </spec-entry>
+   </spec-entry>
    ```
 
    **Keyword extraction**: Extract 3-5 domain-specific terms from the content (same rules as `spec-add`).
@@ -121,21 +89,9 @@ Check existing entries to avoid duplicates when appending in Step 3.
    }
    ```
 
-2. Clear artifacts array (remove milestone-affiliated entries):
-   ```
-   state.json.artifacts = state.json.artifacts.filter(a => a.milestone != target_milestone)
-   ```
+2. Clear artifacts array: remove all entries where `milestone == target_milestone`
 
-3. Advance to next milestone:
-   ```
-   next_milestone = state.json.milestones.find(m => m.status == "pending")
-   IF next_milestone:
-     state.json.current_milestone = next_milestone.id
-     next_milestone.status = "active"
-   ELSE:
-     state.json.current_milestone = null
-     state.json.status = "completed"
-   ```
+3. Advance to next milestone: activate first pending milestone → set as `current_milestone`. If none pending → set `current_milestone = null`, `status = "completed"`
 
 4. Write state.json (atomic)
 
@@ -143,12 +99,7 @@ Check existing entries to avoid duplicates when appending in Step 3.
 
 ## Step 5: Clean Scratch
 
-Remove archived scratch directories:
-```
-FOR each artifact IN archived_artifacts:
-  IF directory exists at .workflow/{artifact.path}:
-    rm -rf .workflow/{artifact.path}
-```
+Remove archived scratch directories: delete `.workflow/{artifact.path}` for each archived artifact.
 
 ---