maestro-flow 0.3.11 → 0.3.12

package/workflows/fork.md

@@ -121,12 +121,25 @@ IF syncMode:
 ## Step 5: Validate & Confirm
 
 ```
-// Load phase index files for all milestone phases
+// Load phase status — artifact registry first, fallback to legacy phases/
 phaseList = []
-for (phaseNum of milestonePhases):
-  Glob: .workflow/phases/{NN}-*/index.json where NN matches phaseNum
-  Read index.json → phaseIndex
-  phaseList.push(phaseIndex)
+artifacts = projectState.artifacts ?? []
+useArtifactRegistry = artifacts.length > 0
+
+IF useArtifactRegistry:
+  // Derive phase status from artifact registry
+  for (phaseNum of milestonePhases):
+    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 })
+ELSE:
+  // Legacy: load from phases/ directory
+  for (phaseNum of milestonePhases):
+    Glob: .workflow/phases/{NN}-*/index.json where NN matches phaseNum
+    Read index.json → phaseIndex
+    phaseList.push(phaseIndex)
 
 // Validate: milestone should have at least one non-completed phase
 nonCompleted = phaseList.filter(p => p.status !== "completed")
@@ -172,7 +185,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 +195,92 @@ 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):
-    IF NOT ownedPhaseNumbers.includes(dep):
-      allDeps.add(dep)
+// 6e: Copy milestone artifacts to worktree
+ownedPhaseNumbers = milestonePhases.slice()  // all phases in this milestone
 
-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}/
+IF useArtifactRegistry:
+  // 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}/
+ELSE:
+  // Legacy: copy phase directories
+  Bash("mkdir -p {wtPath}/.workflow/phases")
+  for (p of phaseList):
+    NN = String(p.phase).padStart(2, '0')
+    Copy .workflow/phases/{NN}-{p.slug}/ → {wtPath}/.workflow/phases/{NN}-{p.slug}/
+
+// 6f: Copy dependency artifacts (phases outside this milestone)
+IF useArtifactRegistry:
+  // 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):
+        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}/
+ELSE:
+  // Legacy: copy completed dependency phase dirs
+  allDeps = new Set()
+  for (p of phaseList):
+    IF p.depends_on:
+      for (dep of p.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: Build phase_dependencies map for worktree-scope
+phaseDeps = {}
+IF useArtifactRegistry:
+  IF milestoneEntry.depends_on:
+    for (phaseNum of ownedPhaseNumbers):
+      phaseDeps[String(phaseNum)] = milestoneEntry.depends_on
+        .filter(d => !ownedPhaseNumbers.includes(d))
+ELSE:
+  for (p of phaseList):
+    IF p.depends_on:
+      externalDeps = p.depends_on.filter(d => !ownedPhaseNumbers.includes(d))
+      IF externalDeps.length > 0:
+        phaseDeps[String(p.phase)] = externalDeps
 
-// 6g: Write worktree-scope.json
+// 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: useArtifactRegistry
+    ? artifacts.filter(a => a.milestone === milestoneName || ownedPhaseNumbers.includes(a.phase))
+    : []
 }
 Write {wtPath}/.workflow/state.json: scopedState
 ```
@@ -260,14 +319,20 @@ 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"
+IF useArtifactRegistry:
+  // 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)
+ELSE:
+  // Legacy: mark phase index.json as forked
+  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
 
 mainState.last_updated = getUtc8ISOString()
 Write .workflow/state.json: mainState
@@ -295,7 +360,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/integration-test.md

@@ -15,13 +15,25 @@ 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 (artifact registry or legacy `.workflow/phases/{NN}-{slug}/`) |
 | `--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 ?? []
+IF artifacts.length > 0:
+  art = artifacts.find(a => a.type === 'execute' && a.phase === phaseNum)
+  PHASE_DIR = ".workflow/" + art.path
+ELSE:
+  Glob: .workflow/phases/{NN}-*/
+  PHASE_DIR = resolved path
+```
+
 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,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/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
 ```
 

package/workflows/retrospective.md

@@ -9,7 +9,7 @@ This is a **post-execution analysis** workflow. It reads only — until the rout
 ## Prerequisites
 
 - `.workflow/` initialized (`.workflow/state.json` exists)
-- At least one phase directory under `.workflow/phases/{NN}-{slug}/`
+- At least one completed phase (via artifact registry in state.json, or legacy `.workflow/phases/{NN}-{slug}/`)
 - Target phase has been executed (has `.task/` and `.summaries/`)
 - `maestro delegate` available (used for the four lens analyses via Agent calls)
 
@@ -61,19 +61,46 @@ This is a **post-execution analysis** workflow. It reads only — until the rout
 
 ```
 candidates = []
-FOR each .workflow/phases/{NN}-{slug}/index.json:
-  Read index.json
-  IF index.json.status == "completed":
-    has_retro = file exists at "{phase_dir}/retrospective.json"
-    candidates.push({
-      number: NN,
-      slug: slug,
-      title: index.json.title or slug,
-      completed_at: index.json.completed_at,
-      has_retro: has_retro,
-      gaps: index.json.verification?.gaps?.length or 0,
-      review_verdict: index.json.review?.verdict or "—"
-    })
+
+Read .workflow/state.json → state
+artifacts = state.artifacts ?? []
+useArtifactRegistry = artifacts.length > 0
+
+IF useArtifactRegistry:
+  // Resolve completed phases from artifact registry
+  phaseNums = [...new Set(artifacts.map(a => a.phase).filter(Boolean))]
+  FOR each phaseNum in phaseNums:
+    execArt = artifacts.find(a => a.type === 'execute' && a.phase === phaseNum && a.status === 'completed')
+    IF execArt:
+      scratchDir = ".workflow/" + execArt.path
+      has_retro = file exists at "{scratchDir}/retrospective.json"
+      candidates.push({
+        number: phaseNum,
+        slug: execArt.slug ?? "phase-" + phaseNum,
+        title: execArt.title ?? execArt.slug ?? "Phase " + phaseNum,
+        completed_at: execArt.completed_at,
+        has_retro: has_retro,
+        phase_dir: scratchDir,
+        gaps: 0,
+        review_verdict: "—"
+      })
+ELSE:
+  // Legacy: scan phases/ directory
+  FOR each .workflow/phases/{NN}-{slug}/index.json:
+    Read index.json
+    IF index.json.status == "completed":
+      phase_dir = ".workflow/phases/{NN}-{slug}"
+      has_retro = file exists at "{phase_dir}/retrospective.json"
+      candidates.push({
+        number: NN,
+        slug: slug,
+        title: index.json.title or slug,
+        completed_at: index.json.completed_at,
+        has_retro: has_retro,
+        phase_dir: phase_dir,
+        gaps: index.json.verification?.gaps?.length or 0,
+        review_verdict: index.json.review?.verdict or "—"
+      })
 ```
 
 ### Display backlog
@@ -103,24 +130,26 @@ FOR each .workflow/phases/{NN}-{slug}/index.json:
 
 If overwriting existing retrospective.json:
 ```
-mkdir -p "{phase_dir}/.history"
+mkdir -p "{candidate.phase_dir}/.history"
 TIMESTAMP = format(now(), "YYYY-MM-DDTHH-mm-ss")
-mv "{phase_dir}/retrospective.json" "{phase_dir}/.history/retrospective-{TIMESTAMP}.json"
-mv "{phase_dir}/retrospective.md"   "{phase_dir}/.history/retrospective-{TIMESTAMP}.md"
+mv "{candidate.phase_dir}/retrospective.json" "{candidate.phase_dir}/.history/retrospective-{TIMESTAMP}.json"
+mv "{candidate.phase_dir}/retrospective.md"   "{candidate.phase_dir}/.history/retrospective-{TIMESTAMP}.md"
 ```
 
 ---
 
 ## Stage 3: load_artifacts (per phase)
 
-For each selected phase, build the in-memory artifacts bundle:
+For each selected phase (using `candidate.phase_dir` resolved in Stage 2), build the in-memory artifacts bundle:
 
 ```
+phase_dir = candidate.phase_dir  // already resolved: scratch path (artifact registry) or legacy phases/ path
+
 artifacts = {
   phase_num: NN,
   phase_slug: slug,
-  phase_dir: ".workflow/phases/{NN}-{slug}",
-  index: read JSON,
+  phase_dir: phase_dir,
+  index: read "{phase_dir}/index.json" or null,
   state: read .workflow/state.json,
   plan: read "{phase_dir}/plan.json" or null,
   verification: read "{phase_dir}/verification.json" or null,
@@ -130,7 +159,17 @@ artifacts = {
   task_jsons: read all "{phase_dir}/.task/TASK-*.json",
   phase_issues: filter ".workflow/issues/issues.jsonl" + ".workflow/issues/issue-history.jsonl"
                 where issue.phase_ref == phase_slug or issue.phase_ref == NN,
-  prior_retro: (if --compare M) read .workflow/phases/{MM}-*/retrospective.json
+  prior_retro: null
+}
+
+// Resolve --compare target
+IF --compare M:
+  IF useArtifactRegistry:
+    compareArt = state.artifacts.find(a => a.type === 'execute' && a.phase === M)
+    IF compareArt:
+      artifacts.prior_retro = read ".workflow/" + compareArt.path + "/retrospective.json"
+  ELSE:
+    artifacts.prior_retro = read .workflow/phases/{MM}-*/retrospective.json
 }
 ```
 
@@ -422,7 +461,7 @@ retrospective = {
 | {INS-id} | note | ... |
 ```
 
-Write both files:
+Write both files (phase_dir already resolved in Stage 2):
 ```
 Write "{phase_dir}/retrospective.json"
 Write "{phase_dir}/retrospective.md"

package/workflows/review.md

@@ -15,10 +15,23 @@ Tiered multi-dimensional code review with parallel agents, severity classificati
 
 ```
 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
+
+Read .workflow/state.json → state
+artifacts = state.artifacts ?? []
+useArtifactRegistry = artifacts.length > 0
+
+IF useArtifactRegistry:
+  IF number: art = artifacts.find(a => a.type === 'execute' && a.phase === number)
+  IF slug:   art = artifacts.find(a => a.type === 'execute' && a.slug?.includes(slug))
+  IF art:    PHASE_DIR = ".workflow/" + art.path
+  ELSE:      ERROR "Phase not found in artifact registry"
+ELSE:
+  // Legacy: resolve from phases/ directory
+  IF number: find .workflow/phases/{NN}-*/index.json
+  IF slug:   find .workflow/phases/*-{slug}/index.json
+  PHASE_DIR = resolved path
+
+Validate execution has occurred (tasks_completed > 0 or .task/ exists)
 ```
 
 ---