maestro-flow 0.3.11 → 0.3.13

package/workflows/brainstorm.md

@@ -126,7 +126,16 @@ Parse $ARGUMENTS to determine execution mode:
 - None + single role mode → error E002
 
 **Output Directory Resolution**:
-- Phase mode (number): `.workflow/phases/{NN}-{slug}/.brainstorming/`
+- Phase mode (number):
+  ```
+  Read .workflow/state.json → state
+  artifacts = state.artifacts ?? []
+  art = artifacts.find(a => a.phase === phaseNum)
+  IF art:
+    output_dir = ".workflow/" + art.path + "/.brainstorming/"
+  ELSE:
+    ERROR "Phase {phaseNum} not found in artifact registry"
+  ```
 - All output: `.workflow/scratch/brainstorm-{slug}-{date}/`
 - Existing session: use existing session directory
 

package/workflows/codebase-rebuild.md

@@ -49,7 +49,7 @@ Scan src/ (and other source directories) for components:
 
 a. Identify source directories:
    - Check for: src/, lib/, app/, packages/
-   - Use project-tech.json source_dirs if available
+   - Read project.md Tech Stack section if available for context
 
 b. For each source directory, scan for component-forming files:
    - Directories that represent modules (contain index.ts/index.js or multiple files)
@@ -267,16 +267,7 @@ a. Update state.json:
    Set last_updated: "{ISO timestamp}"
    Write updated state.json
 
-b. Update project-tech.json (if exists):
-   Read .workflow/project-tech.json
-   Compare detected tech stack (from Step 2 scan) against existing entries:
-     - New languages, frameworks, databases, tools discovered
-     - Version changes detected (from package.json, go.mod, pyproject.toml, etc.)
-   If differences found:
-     Update project-tech.json with current detected stack
-     Display: "project-tech.json: updated with {count} changes"
-
-c. Update project.md Tech Stack (if exists):
+b. Update project.md Tech Stack (if exists):
    Read .workflow/project.md
    Compare "## Tech Stack" section against detected stack from Step 2
    If new entries or changes detected:
@@ -328,5 +319,4 @@ Suggest next:
 | `.workflow/codebase/feature-maps/_index.md` | Feature index |
 | `.workflow/codebase/feature-maps/{slug}.md` | Per-feature documentation |
 | `.workflow/state.json` | Updated: last_codebase_rebuild timestamp |
-| `.workflow/project-tech.json` | Updated: detected tech stack changes |
 | `.workflow/project.md` | Updated: Tech Stack section refreshed |

package/workflows/debug.md

@@ -14,10 +14,8 @@ When root causes found, auto-updates originating uat.md with diagnosis.
 ### Step 1: Check Active Sessions
 
 ```bash
-# Phase-scoped debug sessions
-find .workflow/phases -path "*/.debug/*" -name "understanding.md" 2>/dev/null | head -5
-
-# Standalone scratch debug sessions
+# Check scratch dirs (resolved via artifact registry) for debug sessions
+find .workflow/scratch -path "*/.debug/*" -name "understanding.md" 2>/dev/null | head -5
 find .workflow/scratch -type d -name "debug-*" 2>/dev/null | head -5
 ```
 
@@ -31,7 +29,7 @@ Display:
 
 | # | Location | Status | Current Hypothesis |
 |---|----------|--------|--------------------|
-| 1 | phases/03-auth/.debug/jwt-expiry/ | investigating | Token not refreshed on 401 |
+| 1 | scratch/plan-auth-2026-04-20/.debug/jwt-expiry/ | investigating | Token not refreshed on 401 |
 | 2 | scratch/debug-nav-crash-2026-03-14/ | checkpoint | Awaiting user input |
 
 Reply with a number to resume, or describe a new issue.
@@ -66,7 +64,7 @@ Pass to debug agents as prior knowledge (known issues, root causes, workarounds)
 
 Skip if --from-uat is not set. Go to Step 3 instead.
 
-Read `{phase_dir}/uat.md` Gaps section. For each gap:
+Read `{artifact_dir}/uat.md` Gaps section (artifact_dir resolved from artifact registry). For each gap:
 ```yaml
 - test: T-003
   truth: "User can reply to comments"
@@ -137,10 +135,21 @@ Create debug session directory and proceed to Step 6.
 
 | Mode | Directory |
 |------|-----------|
-| Phase-scoped (from UAT) | `.workflow/phases/{NN}-{slug}/.debug/{gap-slug}/` |
+| Phase-scoped (from UAT) | `{ARTIFACT_DIR}/.debug/{gap-slug}/` (ARTIFACT_DIR resolved from artifact registry) |
 | Standalone | `.workflow/scratch/debug-{slug}-{date}/` |
 
-```bash
+```
+IF TARGET_TYPE == "phase":
+  Read .workflow/state.json → state
+  artifacts = state.artifacts ?? []
+  art = artifacts.find(a => a.type === 'execute' && a.phase === phaseNum)
+  IF art:
+    DEBUG_DIR = ".workflow/" + art.path + "/.debug/{gap-slug}/"
+  ELSE:
+    ERROR "Phase {phaseNum} not found in artifact registry"
+ELSE:
+  DEBUG_DIR = ".workflow/scratch/debug-{slug}-{date}/"
+
 mkdir -p "$DEBUG_DIR"
 ```
 

package/workflows/execute.md

@@ -221,9 +221,6 @@ For each wave in execution_queue (sequential):
     Read .workflow/state.json
     If state.json.status != "executing":
       state.json.status = "executing"
-      # Worktree mode: skip phases_summary (reconciled on merge)
-      IF NOT file_exists(".workflow/worktree-scope.json"):
-        state.json.phases_summary.in_progress += 1
       state.json.last_updated = now()
       Write .workflow/state.json
 
@@ -565,7 +562,24 @@ Write state.json (atomic)
 // Incremental learning extraction
 Read all ${PLAN_DIR}/.summaries/TASK-*-summary.md
 Extract: strategy adjustments, patterns discovered, pitfalls encountered
-Append to .workflow/specs/learnings.md under "## Entries"
+
+// Check existing entries to avoid duplicates
+existing_learnings = maestro spec load --category learning
+
+// Append using <spec-entry> closed-tag format:
+FOR each extracted learning:
+  keywords = extract_keywords(learning.content)  // 3-5 domain-specific terms
+  IF not duplicate of existing_learnings:
+    Append to .workflow/specs/learnings.md:
+      <spec-entry category="learning" keywords="{keywords}" date="{YYYY-MM-DD}" source="execute">
+
+      ### {learning.summary}
+
+      {learning.content}
+      Phase: {phase} | Plan: {PLAN_DIR}
+
+      </spec-entry>
+
 Mark artifact.harvested = true
 Write state.json (atomic)
 ```

package/workflows/fork.md

@@ -121,12 +121,17 @@ IF syncMode:
 ## Step 5: Validate & Confirm
 
 ```
-// Load phase index files for all milestone phases
+// Load phase status from artifact registry
 phaseList = []
+artifacts = projectState.artifacts ?? []
+
+// Derive phase status from artifact registry
 for (phaseNum of milestonePhases):
-  Glob: .workflow/phases/{NN}-*/index.json where NN matches phaseNum
-  Read index.json → phaseIndex
-  phaseList.push(phaseIndex)
+  execArtifacts = artifacts.filter(a => a.type === 'execute' && a.phase === phaseNum)
+  status = execArtifacts.some(a => a.status === 'completed') ? 'completed'
+         : execArtifacts.length > 0 ? 'in_progress'
+         : 'pending'
+  phaseList.push({ phase: phaseNum, title: "Phase " + phaseNum, status })
 
 // Validate: milestone should have at least one non-completed phase
 nonCompleted = phaseList.filter(p => p.status !== "completed")
@@ -172,7 +177,7 @@ Bash("git branch -D {branch}") // ignore errors (may not exist)
 Bash("git worktree add -b {branch} {wtPath} {baseBranch}")
 
 // 6c: Create .workflow/ structure in worktree
-Bash("mkdir -p {wtPath}/.workflow/phases")
+Bash("mkdir -p {wtPath}/.workflow/scratch")
 
 // 6d: Copy shared context (read-only)
 Copy .workflow/project.md → {wtPath}/.workflow/project.md
@@ -182,46 +187,61 @@ IF file_exists(".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):
+// 6e: Copy milestone artifacts to worktree
+ownedPhaseNumbers = milestonePhases.slice()  // all phases in this milestone
+
+// Copy scratch dirs for this milestone's artifacts
+milestoneArtifacts = artifacts.filter(a =>
+  a.milestone === milestoneName && a.path
+)
+for (art of milestoneArtifacts):
+  IF directory_exists(".workflow/" + art.path):
+    Copy .workflow/{art.path}/ → {wtPath}/.workflow/{art.path}/
+
+// 6f: Copy dependency artifacts (phases outside this milestone)
+// Collect dependency phases from roadmap milestone entry
+// (cross-milestone dependencies are defined in milestoneEntry.depends_on or roadmap)
+depPhases = new Set()
+IF milestoneEntry.depends_on:
+  for (dep of milestoneEntry.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
+      depPhases.add(dep)
+// Copy dependency artifacts from main
+for (dep of depPhases):
+  depArtifacts = artifacts.filter(a => a.phase === dep && a.path)
+  for (art of depArtifacts):
+    IF directory_exists(".workflow/" + art.path):
+      Copy .workflow/{art.path}/ → {wtPath}/.workflow/{art.path}/
+
+// 6g: Build phase_dependencies map for worktree-scope
+phaseDeps = {}
+IF milestoneEntry.depends_on:
+  for (phaseNum of ownedPhaseNumbers):
+    phaseDeps[String(phaseNum)] = milestoneEntry.depends_on
+      .filter(d => !ownedPhaseNumbers.includes(d))
+
+// 6h: Write worktree-scope.json
 Write {wtPath}/.workflow/worktree-scope.json:
   {
     "worktree": true,
     "milestone_num": milestoneNum,
     "milestone": milestoneName,
     "owned_phases": ownedPhaseNumbers,
+    "phase_dependencies": phaseDeps,
     "main_worktree": resolve(cwd),
     "branch": branch,
     "base_commit": baseCommit,
     "created_at": getUtc8ISOString()
   }
 
-// 6h: Write scoped state.json
+// 6i: 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
+  current_milestone: milestoneName,
+  // Carry over milestone-scoped artifacts to worktree
+  artifacts: artifacts.filter(a => a.milestone === milestoneName || ownedPhaseNumbers.includes(a.phase))
 }
 Write {wtPath}/.workflow/state.json: scopedState
 ```
@@ -260,14 +280,10 @@ registry.fork_sessions.push({
 
 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
+// Mark milestone phases as "forked"
+// In artifact registry model, worktrees.json tracks forked state.
+// No per-phase marking needed — the registry entry signals ownership.
+// (worktrees.json already updated above with owned_phases)
 
 mainState.last_updated = getUtc8ISOString()
 Write .workflow/state.json: mainState
@@ -295,7 +311,6 @@ Display:
     /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):

package/workflows/init.md

@@ -88,7 +88,7 @@ CHECK .workflow/state.json exists?
 
 5. **Create project files:**
    - `.workflow/project.md` from @templates/project.md + user answers (include Core Value, Requirements, Key Decisions)
-   - `.workflow/state.json` from template (status: "idle", current_phase: null)
+   - `.workflow/state.json` from template (status: "idle")
    - `.workflow/config.json` already created in step 2
 
 ### Path B: Brownfield (has code, no .workflow/)
@@ -119,14 +119,12 @@ If `.workflow/specs/` does not exist:
 1. Create `.workflow/specs/` directory
 2. Auto-trigger `/workflow:specs-setup` — **MUST follow `specs-setup.md` templates exactly**:
    - Scan codebase for conventions
-   - Generate `project-tech.json`
    - Generate `specs/coding-conventions.md`
    - Generate `specs/architecture-constraints.md`
    - Generate `specs/quality-rules.md`
    - Generate `specs/debug-notes.md`
    - Generate `specs/test-conventions.md`
    - Generate `specs/review-standards.md`
-   - Generate `specs/validation-rules.md`
    - Create empty `specs/learnings.md`
 
 
@@ -143,7 +141,6 @@ Verify all required directories and files exist:
   config.json        ✓
   specs/             ✓
   research/          ✓ (if research enabled)
-  phases/            ✓ (create empty)
   scratch/           ✓ (create empty)
   milestones/        ✓ (create empty)
   codebase/          ✓ (create empty)

package/workflows/integration-test.md

@@ -15,13 +15,24 @@ L0-L3 progressive layers: Static Analysis -> Unit -> Integration -> E2E
 | Input | Result |
 |-------|--------|
 | No arguments | Error E001 |
-| Phase number | Resolve `.workflow/phases/{NN}-{slug}/` |
+| Phase number | Resolve phase dir from artifact registry |
 | `--max-iter N` | Set MAX_ITER = N (default 5) |
 | `--layer L2` | Start from L2 layer |
 
+**Resolve phase dir:**
+```
+Read .workflow/state.json → state
+artifacts = state.artifacts ?? []
+art = artifacts.find(a => a.type === 'execute' && a.phase === phaseNum)
+IF art:
+  PHASE_DIR = ".workflow/" + art.path
+ELSE:
+  ERROR "Phase {phaseNum} not found in artifact registry"
+```
+
 Check for existing integration test session:
 ```bash
-ls .workflow/phases/{NN}-*/.tests/integration/state.json 2>/dev/null
+ls ${PHASE_DIR}/.tests/integration/state.json 2>/dev/null
 ```
 
 If session exists: offer resume or restart.

package/workflows/issue.md

@@ -178,8 +178,10 @@ 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 ?? []
+      art = artifacts.find(a => a.type === 'plan' && a.phase === phaseNum)
+      IF art: Read .workflow/{art.path}/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 +451,10 @@ 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 ?? []
+   - Search artifact registry paths: .workflow/{artifact.path}/.task/{TASK_ID}.json
+   - 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

@@ -4,7 +4,7 @@ Atomic insight capture, search, and retrieval. Lightweight gstack-style "eureka
 
 Storage:
 - `.workflow/learning/lessons.jsonl` — append-only JSONL row per insight (shared with retrospective output)
-- `.workflow/learning/learning-index.json` — searchable index (mirrors `memory-index.json` schema)
+- `.workflow/learning/learning-index.json` — searchable index (searchable index)
 
 This workflow does NOT spawn agents or call CLI tools. It is a thin file operation: parse → infer → append → confirm.
 
@@ -83,12 +83,21 @@ phase_slug = null
 
 IF .workflow/state.json exists:
   state = read JSON
-  IF state.current_phase is not null:
-    phase = state.current_phase
+  artifacts = state.artifacts ?? []
 
-    # Resolve slug
-    Glob ".workflow/phases/{NN}-*/" where NN == phase
-    phase_slug = matched directory basename (e.g. "01-auth")
+  # Derive current phase from artifacts (first phase with in_progress, or first without completed execute)
+  phase = null
+  inProgressArt = artifacts.find(a => a.type === 'execute' && a.status === 'in_progress')
+  IF inProgressArt:
+    phase = inProgressArt.phase
+  ELSE:
+    phaseNums = [...new Set(artifacts.map(a => a.phase).filter(Boolean))].sort()
+    phase = phaseNums.find(p => !artifacts.some(a => a.phase === p && a.type === 'execute' && a.status === 'completed'))
+
+  IF phase is not null:
+    # Resolve slug from artifact registry
+    art = artifacts.find(a => a.phase === phase)
+    phase_slug = art?.slug ?? "phase-" + phase
 ```
 
 If `--phase 0` is passed, force `phase = null, phase_slug = null` regardless.
@@ -299,8 +308,14 @@ 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 from artifact registry
+  Read .workflow/state.json → state
+  artifacts = state.artifacts ?? []
+  phase_dir = null
+  art = artifacts.find(a => a.phase === row.phase && a.path)
+  IF art: phase_dir = ".workflow/" + art.path
+
+  IF phase_dir AND directory exists:
     phase_context = {
       title: read index.json.title from phase_dir,
       status: read index.json.status,
@@ -368,7 +383,7 @@ PHASE CONTEXT:
 | E002 | error | Unknown `--category` (allowed: pattern, antipattern, decision, tool, gotcha, technique) |
 | E003 | error | `show` mode requires an INS-id argument |
 | E004 | error | Insight id not found in lessons.jsonl |
-| W001 | warning | Auto-phase detection found a current_phase but no matching directory; phase set to null |
+| W001 | warning | Auto-phase detection found no matching artifact in registry; phase set to null |
 | W002 | warning | learning-index.json out of sync with lessons.jsonl (different row count); offer to rebuild |
 
 ---
@@ -378,7 +393,7 @@ PHASE CONTEXT:
 - [ ] Mode correctly routed (capture / list / search / show)
 - [ ] Capture mode: `lessons.jsonl` row appended, valid JSON, all required fields present
 - [ ] Capture mode: `learning-index.json` updated with matching entry
-- [ ] Capture mode: phase auto-link resolves correctly when state.json has current_phase
+- [ ] Capture mode: phase auto-link resolves correctly from artifact registry
 - [ ] Capture mode: category inference produces a sensible default when --category absent
 - [ ] List mode: filters apply; output sorted newest-first
 - [ ] Search mode: results ranked by title > tags > summary match

package/workflows/maestro.codex.md

@@ -37,7 +37,14 @@ if (fileExists(stateFile)) {
   const raw = JSON.parse(Read(stateFile));
   projectState = {
     initialized: true,
-    current_phase: raw.current_phase,
+    // Derive current_phase from artifacts (first in_progress execute, or first without completed execute)
+    current_phase: (() => {
+      const arts = raw.artifacts ?? [];
+      const ip = arts.find(a => a.type === 'execute' && a.status === 'in_progress');
+      if (ip) return ip.phase;
+      const phases = [...new Set(arts.map(a => a.phase).filter(Boolean))].sort((a,b) => a - b);
+      return phases.find(p => !arts.some(a => a.phase === p && a.type === 'execute' && a.status === 'completed')) ?? raw.current_phase ?? null;
+    })(),
     phase_slug: raw.phase_slug,
     phase_status: raw.phase_status,   // pending|exploring|planning|executing|verifying|testing|completed|blocked
     phase_artifacts: raw.phase_artifacts ?? {},

package/workflows/maestro.md

@@ -661,8 +661,17 @@ function resolvePhase(intent_analysis, project_state) {
   const phaseMatch = intent.match(/phase\s*(\d+)|^(\d+)$/);
   if (phaseMatch) return phaseMatch[1] || phaseMatch[2];
 
-  // 3. From project state
-  if (project_state.initialized) return project_state.current_phase;
+  // 3. From project state — derive from artifacts
+  if (project_state.initialized) {
+    // Derive current phase: first phase with in_progress execute, or first without completed execute
+    const arts = project_state.artifacts ?? [];
+    const inProgress = arts.find(a => a.type === 'execute' && a.status === 'in_progress');
+    if (inProgress) return inProgress.phase;
+    const phases = [...new Set(arts.map(a => a.phase).filter(Boolean))].sort((a,b) => a - b);
+    const current = phases.find(p => !arts.some(a => a.phase === p && a.type === 'execute' && a.status === 'completed'));
+    if (current) return current;
+    return project_state.latest_artifact?.phase ?? null;
+  }
 
   // 4. Scratch mode chains use {scratch_dir} instead of {phase}
   if (chainName === 'analyze-plan-execute') return null;
@@ -775,7 +784,7 @@ mkdir -p "${SESSION_DIR}"
 **Initialize execution context:**
 ```javascript
 const context = {
-  current_phase: resolvedPhase,
+  current_phase: resolvedPhase,  // derived from artifacts
   user_intent: intent,
   issue_id: resolvedIssueId,
   spec_session_id: null,
@@ -789,6 +798,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',