maestro-flow 0.3.8 → 0.3.9

package/dist/src/tools/transition-recorder.js

@@ -4,7 +4,9 @@
  * Provides pure functions for building transition entries and appending
  * them to the transition_history array in .workflow/state.json.
  */
-import { readFileSync, writeFileSync, existsSync } from 'node:fs';
+import { readFileSync, writeFileSync, existsSync, readdirSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { evaluatePhaseGate } from './phase-gate-evaluator.js';
 // ---------------------------------------------------------------------------
 // Public API
 // ---------------------------------------------------------------------------
@@ -33,10 +35,31 @@ export function buildTransitionEntry(opts) {
 /**
  * Append a transition entry to state.json's transition_history[].
  * Creates the array if it doesn't exist.
+ *
+ * For phase-completion transitions, evaluates the phase gate first.
+ * Throws if the gate blocks and force is false.
  */
 export function appendTransition(statePath, entry) {
     if (!existsSync(statePath))
         return;
+    // Gate check: validate phase readiness before allowing completion
+    if (entry.type === 'phase' && entry.from_phase != null) {
+        const phaseIndex = loadPhaseIndex(statePath, entry.from_phase);
+        if (phaseIndex) {
+            const gate = evaluatePhaseGate(phaseIndex);
+            if (!gate.allowed) {
+                if (!gate.overridable || !entry.force) {
+                    const tag = gate.overridable ? '[GATE_BLOCKED]' : '[GATE_HARD_BLOCK]';
+                    throw new Error(`${tag} Phase ${entry.from_phase} cannot be completed:\n` +
+                        gate.reasons.map((r) => `  - ${r}`).join('\n') +
+                        (gate.overridable ? '\nUse force=true to override soft blocks.' : '\nResolve BLOCK verdict before completing.'));
+                }
+                // Force override — record the reasons in snapshot for audit
+                entry.snapshot.verification_status =
+                    `force_override: ${gate.reasons.join('; ')}`;
+            }
+        }
+    }
     const state = JSON.parse(readFileSync(statePath, 'utf8'));
     if (!Array.isArray(state.transition_history)) {
         state.transition_history = [];
@@ -45,4 +68,32 @@ export function appendTransition(statePath, entry) {
     state.last_updated = new Date().toISOString();
     writeFileSync(statePath, JSON.stringify(state, null, 2));
 }
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+/**
+ * Load phase index.json from the phases directory sibling to state.json.
+ * Returns null if not found.
+ */
+function loadPhaseIndex(statePath, phaseNum) {
+    const workflowDir = dirname(statePath);
+    const phasesDir = join(workflowDir, 'phases');
+    if (!existsSync(phasesDir))
+        return null;
+    // Find directory starting with the phase number prefix (e.g. "01-")
+    try {
+        const prefix = String(phaseNum).padStart(2, '0') + '-';
+        const entries = readdirSync(phasesDir);
+        const phaseSlug = entries.find((e) => e.startsWith(prefix));
+        if (!phaseSlug)
+            return null;
+        const indexPath = join(phasesDir, phaseSlug, 'index.json');
+        if (!existsSync(indexPath))
+            return null;
+        return JSON.parse(readFileSync(indexPath, 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
 //# sourceMappingURL=transition-recorder.js.map

package/dist/src/tools/transition-recorder.js.map

@@ -1 +1 @@
-{"version":3,"file":"transition-recorder.js","sourceRoot":"","sources":["../../../src/tools/transition-recorder.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAuClE,8EAA8E;AAC9E,aAAa;AACb,8EAA8E;AAE9E;;;GAGG;AACH,MAAM,UAAU,oBAAoB,CAAC,IAAyB;IAC5D,OAAO;QACL,IAAI,EAAE,IAAI,CAAC,IAAI;QACf,UAAU,EAAE,IAAI,CAAC,SAAS;QAC1B,QAAQ,EAAE,IAAI,CAAC,OAAO;QACtB,SAAS,EAAE,IAAI,CAAC,SAAS;QACzB,eAAe,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;QACzC,OAAO,EAAE,IAAI,CAAC,OAAO;QACrB,KAAK,EAAE,IAAI,CAAC,KAAK;QACjB,QAAQ,EAAE;YACR,gBAAgB,EAAE,IAAI,CAAC,eAAe;YACtC,YAAY,EAAE,IAAI,CAAC,WAAW;YAC9B,cAAc,EAAE,IAAI,CAAC,aAAa;YAClC,mBAAmB,EAAE,IAAI,CAAC,kBAAkB;YAC5C,eAAe,EAAE,IAAI,CAAC,cAAc;SACrC;KACF,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAAC,SAAiB,EAAE,KAAsB;IACxE,IAAI,CAAC,UAAU,CAAC,SAAS,CAAC;QAAE,OAAO;IAEnC,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC,CAAC;IAC1D,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,kBAAkB,CAAC,EAAE,CAAC;QAC7C,KAAK,CAAC,kBAAkB,GAAG,EAAE,CAAC;IAChC,CAAC;IACD,KAAK,CAAC,kBAAkB,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IACrC,KAAK,CAAC,YAAY,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IAC9C,aAAa,CAAC,SAAS,EAAE,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;AAC3D,CAAC"}
+{"version":3,"file":"transition-recorder.js","sourceRoot":"","sources":["../../../src/tools/transition-recorder.ts"],"names":[],"mappings":"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"}

package/dist/src/utils/get-version.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"get-version.d.ts","sourceRoot":"","sources":["../../../src/utils/get-version.ts"],"names":[],"mappings":"AAUA;;;GAGG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,CAO1C"}
+{"version":3,"file":"get-version.d.ts","sourceRoot":"","sources":["../../../src/utils/get-version.ts"],"names":[],"mappings":"AAUA;;;GAGG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,CAiB1C"}

package/dist/src/utils/get-version.js

@@ -12,10 +12,21 @@ let cached = null;
 export function getPackageVersion() {
     if (cached)
         return cached;
-    // Compiled JS lives at dist/src/utils/get-version.js → 4 levels up to project root
-    const pkgRoot = resolve(fileURLToPath(import.meta.url), '..', '..', '..', '..');
-    const pkg = JSON.parse(readFileSync(resolve(pkgRoot, 'package.json'), 'utf-8'));
-    cached = pkg.version ?? '0.0.0';
+    // Walk up from this file until we find a package.json with "maestro" in it
+    let dir = resolve(fileURLToPath(import.meta.url), '..');
+    for (let i = 0; i < 8; i++) {
+        const pkgPath = resolve(dir, 'package.json');
+        try {
+            const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
+            if (pkg.name === 'maestro-flow' || pkg.name === 'maestro') {
+                cached = pkg.version ?? '0.0.0';
+                return cached;
+            }
+        }
+        catch { /* not found, keep going up */ }
+        dir = resolve(dir, '..');
+    }
+    cached = '0.0.0';
     return cached;
 }
 //# sourceMappingURL=get-version.js.map

package/dist/src/utils/get-version.js.map

@@ -1 +1 @@
-{"version":3,"file":"get-version.js","sourceRoot":"","sources":["../../../src/utils/get-version.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,0EAA0E;AAC1E,8EAA8E;AAE9E,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEzC,IAAI,MAAM,GAAkB,IAAI,CAAC;AAEjC;;;GAGG;AACH,MAAM,UAAU,iBAAiB;IAC/B,IAAI,MAAM;QAAE,OAAO,MAAM,CAAC;IAC1B,mFAAmF;IACnF,MAAM,OAAO,GAAG,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC;IAChF,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,OAAO,CAAC,OAAO,EAAE,cAAc,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC;IAChF,MAAM,GAAI,GAAG,CAAC,OAAkB,IAAI,OAAO,CAAC;IAC5C,OAAO,MAAM,CAAC;AAChB,CAAC"}
+{"version":3,"file":"get-version.js","sourceRoot":"","sources":["../../../src/utils/get-version.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,0EAA0E;AAC1E,8EAA8E;AAE9E,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEzC,IAAI,MAAM,GAAkB,IAAI,CAAC;AAEjC;;;GAGG;AACH,MAAM,UAAU,iBAAiB;IAC/B,IAAI,MAAM;QAAE,OAAO,MAAM,CAAC;IAC1B,2EAA2E;IAC3E,IAAI,GAAG,GAAG,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,IAAI,CAAC,CAAC;IACxD,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;QAC3B,MAAM,OAAO,GAAG,OAAO,CAAC,GAAG,EAAE,cAAc,CAAC,CAAC;QAC7C,IAAI,CAAC;YACH,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC;YACvD,IAAI,GAAG,CAAC,IAAI,KAAK,cAAc,IAAI,GAAG,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;gBAC1D,MAAM,GAAI,GAAG,CAAC,OAAkB,IAAI,OAAO,CAAC;gBAC5C,OAAO,MAAM,CAAC;YAChB,CAAC;QACH,CAAC;QAAC,MAAM,CAAC,CAAC,8BAA8B,CAAC,CAAC;QAC1C,GAAG,GAAG,OAAO,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;IAC3B,CAAC;IACD,MAAM,GAAG,OAAO,CAAC;IACjB,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "maestro-flow",
-  "version": "0.3.8",
+  "version": "0.3.9",
   "description": "Workflow orchestration CLI with MCP endpoint support and extensible architecture",
   "type": "module",
   "imports": {

package/templates/config.json

@@ -49,5 +49,12 @@
     "doc_index": true,
     "auto_sync_after_execute": true,
     "action_log": true
+  },
+
+  "worktree": {
+    "enabled": true,
+    "root": ".worktrees",
+    "branch_prefix": "milestone/",
+    "auto_cleanup": true
   }
 }

package/templates/worktree-scope.json

@@ -0,0 +1,10 @@
+{
+  "worktree": true,
+  "milestone_num": "{{MILESTONE_NUMBER}}",
+  "milestone": "{{MILESTONE_NAME}}",
+  "owned_phases": [],
+  "main_worktree": "{{MAIN_WORKTREE_PATH}}",
+  "branch": "milestone/{{MILESTONE_SLUG}}",
+  "base_commit": "{{BASE_COMMIT}}",
+  "created_at": "{{TIMESTAMP}}"
+}

package/templates/worktrees.json

@@ -0,0 +1,27 @@
+{
+  "version": "1.0",
+  "worktrees": [
+    {
+      "milestone_num": "{{MILESTONE_NUMBER}}",
+      "milestone": "{{MILESTONE_NAME}}",
+      "slug": "{{MILESTONE_SLUG}}",
+      "branch": "milestone/{{MILESTONE_SLUG}}",
+      "path": "{{WORKTREE_ROOT}}/m{{MILESTONE_NUMBER}}-{{MILESTONE_SLUG}}",
+      "base_commit": "{{BASE_COMMIT}}",
+      "status": "active",
+      "created_at": "{{TIMESTAMP}}",
+      "owned_phases": [],
+      "fork_session": "{{FORK_SESSION_ID}}"
+    }
+  ],
+  "fork_sessions": [
+    {
+      "session_id": "fork-{{TIMESTAMP_SHORT}}",
+      "created_at": "{{TIMESTAMP}}",
+      "milestone_num": "{{MILESTONE_NUMBER}}",
+      "milestone": "{{MILESTONE_NAME}}",
+      "base_branch": "{{BASE_BRANCH}}",
+      "base_commit": "{{BASE_COMMIT}}"
+    }
+  ]
+}

package/workflows/analyze.md

@@ -41,29 +41,60 @@ Quick mode (-q):
 ## Arguments
 
 ```
-$ARGUMENTS: "<phase|topic> [-y] [-c] [-q]"
+$ARGUMENTS: "[phase|topic] [-y] [-c] [-q]"
 
-<phase>     -- Phase number (phase mode, operates within phase directory)
-<topic>     -- Topic text (scratch mode, creates scratch directory)
+(no args)   -- Milestone-wide analysis (requires init + roadmap)
+<phase>     -- Phase number (phase-scoped, requires init + roadmap)
+<topic>     -- Topic text (adhoc if milestone exists, standalone if not)
 -y / --yes  -- Auto mode, skip interactive scoping, auto-deepen
 -c / --continue -- Resume from existing session
 -q / --quick -- Quick mode, skip exploration + scoring, go straight to decision extraction
 ```
 
-## Dual-Mode Routing
-
-```
-IF $ARGUMENTS matches /^\d+$/
-  → Phase mode
-  → Resolve phase dir from state.json + roadmap
-  → Set OUTPUT_DIR = .workflow/phases/{NN}-{slug}/
-  → Update index.json: status → "exploring"
-
-ELSE
-  → Scratch mode
-  → Slugify topic (lowercase, hyphens, max 40 chars)
-  → Set OUTPUT_DIR = .workflow/scratch/analyze-{slug}-{date}/
-  → Create directory + index.json from scratch-index template (type="analyze")
+## Scope Routing
+
+```
+// Worktree scope check
+IF file_exists(".workflow/worktree-scope.json"):
+  scope = read(".workflow/worktree-scope.json")
+  IF $ARGUMENTS matches /^\d+$/ AND parseInt($ARGUMENTS) NOT IN scope.owned_phases:
+    ERROR "Phase {$ARGUMENTS} 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() }
+
+// Scope determination
+IF $ARGUMENTS is empty:
+  IF state.json.current_milestone is non-null AND roadmap.md exists:
+    → scope = "milestone"
+    → milestone_slug = slugify(current_milestone name)
+    → Set OUTPUT_DIR = .workflow/scratch/analyze-{milestone_slug}-{date}/
+  ELSE:
+    → ERROR E001 "No args and no roadmap — provide topic text or create roadmap first"
+
+ELSE IF $ARGUMENTS matches /^\d+$/:
+  IF state.json.current_milestone is non-null AND roadmap.md exists:
+    → scope = "phase"
+    → phase_num = parsed number
+    → phase_slug = resolve from roadmap.md
+    → Set OUTPUT_DIR = .workflow/scratch/analyze-{phase_slug}-{date}/
+  ELSE:
+    → ERROR "Phase number requires init + roadmap"
+
+ELSE (text argument):
+  → topic_slug = slugify(text, max 40 chars)
+  IF state.json.current_milestone is non-null:
+    → scope = "adhoc"
+  ELSE:
+    → scope = "standalone"
+  → Set OUTPUT_DIR = .workflow/scratch/analyze-{topic_slug}-{date}/
+
+// Create output directory
+mkdir -p {OUTPUT_DIR}
 ```
 
 ## Output Structure
@@ -89,31 +120,23 @@ Parse $ARGUMENTS to determine mode and flags:
 - `-c` present: locate existing session folder (discussion.md exists), resume from last round
 - `-y` present: set AUTO_MODE=true
 - `-q` present: set QUICK_MODE=true (skip Steps 2-7, jump to Step 8: Decision Extraction)
-- Number (e.g., "3") = phase mode: resolve `.workflow/phases/{NN}-*/`, verify phase exists in roadmap
-- Text (e.g., "microservices vs monolith") = scratch mode: slugify topic, prepare scratch directory path
-- Missing/empty = error E001
+- Number (e.g., "3") = phase scope: resolve phase slug from roadmap, output to scratch/analyze-{phase-slug}-{date}/
+- Text (e.g., "microservices vs monolith") = adhoc/standalone scope: output to scratch/analyze-{slug}-{date}/
+- Missing/empty = milestone scope (if roadmap exists) or error E001
 
 **Session initialization:**
 - Session ID: `ANL-{slug}-{YYYY-MM-DD}`
-- Phase mode output: phase directory
-- Scratch mode output: `.workflow/scratch/analyze-{slug}-{date}/`
+- Output: `OUTPUT_DIR` (always under `.workflow/scratch/`)
 
-**Load prior context** (phase mode):
+**Load prior context** (milestone/phase scope):
 1. Read `.workflow/project.md` — project vision, constraints, Validated requirements (already shipped), Active requirements (current scope)
 2. Read `.workflow/roadmap.md` — phase structure and dependencies
-3. Read index.json in phase dir — goal, success_criteria
-4. Read `.brainstorming/guidance-specification.md` in phase dir (if exists) — detailed requirements, constraints, RFC 2119 decisions from brainstorm. Skip areas marked as MUST/MUST NOT (already locked).
-5. Read `.brainstorming/feature-index.json` in phase dir (if exists) — feature decomposition
-6. Read `brainstorm.md` in phase dir (if exists, legacy fallback, skip if guidance-specification.md loaded)
-7. Read `analysis.md` in phase dir (if exists, for continuation)
-8. Read `conclusions.json` in phase dir (if exists, for continuation)
-9. Read prior phases' `context.md` files — skip already-decided areas
-10. Read existing `context.md` in this phase (if exists, for continuation)
-11. Load project specs: `specs_content = maestro spec load --category planning`
-    Ensures analysis decisions don't conflict with existing architecture constraints.
-12. Read `.workflow/state.json` → `accumulated_context` (key_decisions, deferred items, blockers)
-
-**Load prior context** (scratch mode):
+3. Read `.workflow/state.json` → `current_milestone`, `artifacts[]`, `accumulated_context` (key_decisions, deferred items, blockers)
+4. Find prior analyze artifacts from `state.json.artifacts[]` where type=analyze and same milestone → load their `context.md` to skip already-decided areas
+5. Find brainstorm artifacts from `state.json.artifacts[]` where type=brainstorm and same milestone → load `guidance-specification.md` if exists
+6. Load project specs: `specs_content = maestro spec load --category planning`
+
+**Load prior context** (adhoc/standalone scope):
 1. Read `.workflow/project.md` (if exists) — project vision, Validated requirements, Active requirements, Key Decisions
 2. Read `.workflow/state.json` (if exists) → `accumulated_context` (key_decisions, deferred, blockers)
 3. Load project specs: `specs_content = maestro spec load --category planning`
@@ -571,6 +594,33 @@ IF deferred_items.length > 0:
   Print: "Created {deferred_items.length} deferred issues for tracking"
 ```
 
+### Step 8.8: Register Artifact
+
+```
+// Register in state.json artifact registry
+Read .workflow/state.json
+next_id = max(artifacts.filter(a => a.type == "analyze").map(a => parseInt(a.id.replace("ANL-","")))) + 1
+  // If no analyze artifacts exist: next_id = 1
+
+artifact = {
+  id: "ANL-{next_id padded to 3}",
+  type: "analyze",
+  milestone: state.json.current_milestone,  // null if standalone
+  phase: phase_num,                          // null if milestone/adhoc/standalone
+  scope: scope,                              // "milestone"|"phase"|"adhoc"|"standalone"
+  path: OUTPUT_DIR relative to .workflow/,   // e.g. "scratch/analyze-auth-2026-04-20"
+  status: "completed",
+  depends_on: null,
+  harvested: false,
+  created_at: session_start_time,
+  completed_at: now()
+}
+
+state.json.artifacts.push(artifact)
+state.json.last_updated = now()
+Write state.json (atomic: write tmp + rename)
+```
+
 ### Step 9: Report & Next Step
 
 Display summary:

package/workflows/brainstorm.md

@@ -47,8 +47,8 @@ Phase 3: Single Role Analysis → Detection → Context → Agent → Validation
 ## Input
 
 - `$ARGUMENTS`: topic text (auto mode) or role name (single role mode)
-- Phase mode: operates within `.workflow/phases/{NN}-{slug}/`
-- Scratch mode: creates `.workflow/scratch/brainstorm-{slug}-{date}/`
+- All output goes to `.workflow/scratch/brainstorm-{slug}-{date}/`
+- Registers artifact (type=brainstorm) in state.json on completion
 
 ### Parameters
 
@@ -80,32 +80,21 @@ Phase 3: Single Role Analysis → Detection → Context → Agent → Validation
 
 ### Directory Structure
 
-**Phase mode**:
-```
-.workflow/phases/{NN}-{slug}/
-├── brainstorm.md                        # Legacy simple output (if no session)
-├── index.json                           # Updated timestamps
-└── .brainstorming/                      # Full brainstorm session
-    ├── guidance-specification.md         # Phase 2 output
-    ├── feature-index.json               # Phase 4 output
-    ├── synthesis-changelog.md            # Phase 4 audit trail
-    ├── feature-specs/                   # Phase 4 feature specs
-    │   ├── F-001-{slug}.md
-    │   └── F-00N-{slug}.md
-    ├── {role}/                          # Phase 3 role analyses (immutable)
-    │   ├── {role}-context.md
-    │   ├── analysis.md
-    │   ├── analysis-cross-cutting.md
-    │   └── analysis-F-{id}-{slug}.md
-    └── synthesis-specification.md       # Non-feature mode fallback
-```
-
-**Scratch mode**:
+All brainstorm output goes to scratch:
 ```
 .workflow/scratch/brainstorm-{slug}-{date}/
-├── index.json                           # scratch-index template
-└── .brainstorming/                      # Same structure as phase mode
-    └── ...
+├── guidance-specification.md         # Phase 2 output
+├── feature-index.json               # Phase 4 output
+├── synthesis-changelog.md            # Phase 4 audit trail
+├── feature-specs/                   # Phase 4 feature specs
+│   ├── F-001-{slug}.md
+│   └── F-00N-{slug}.md
+├── {role}/                          # Phase 3 role analyses (immutable)
+│   ├── {role}-context.md
+│   ├── analysis.md
+│   ├── analysis-cross-cutting.md
+│   └── analysis-F-{id}-{slug}.md
+└── synthesis-specification.md       # Non-feature mode fallback
 ```
 
 ---
@@ -138,17 +127,8 @@ Parse $ARGUMENTS to determine execution mode:
 
 **Output Directory Resolution**:
 - Phase mode (number): `.workflow/phases/{NN}-{slug}/.brainstorming/`
-- Scratch mode (text): `.workflow/scratch/brainstorm-{slug}-{date}/.brainstorming/`
-- Existing session: use session's `.brainstorming/` directory
-
-**Archive previous brainstorming session** (Phase mode only, skip if `--session` or `--update`):
-```
-PARENT_DIR = parent of output directory (e.g., .workflow/phases/{NN}-{slug}/)
-IF directory exists "${PARENT_DIR}/.brainstorming" AND NOT --session AND NOT --update:
-  mkdir -p "${PARENT_DIR}/.history"
-  TIMESTAMP = current timestamp formatted as "YYYY-MM-DDTHH-mm-ss"
-  mv "${PARENT_DIR}/.brainstorming" "${PARENT_DIR}/.history/.brainstorming-${TIMESTAMP}"
-```
+- All output: `.workflow/scratch/brainstorm-{slug}-{date}/`
+- Existing session: use existing session directory
 
 ---
 

package/workflows/execute.md

@@ -2,32 +2,59 @@
 
 Wave-based parallel execution with atomic commits, breakpoint resume, and optional sync/reflection.
 
+Core principle: **Execute per-plan, not per-phase.** Each plan's wave DAG runs independently. Multiple plans execute sequentially.
+
 ---
 
 ## Prerequisites
 
-- Phase has a completed plan: `plan.json` + `.task/TASK-*.json` exist
-- `index.json` present with `plan.waves` populated
+- Plan exists in scratch directory: `plan.json` + `.task/TASK-*.json`
 - OR: executionContext handoff received from `/workflow:plan`
 
 ---
 
-## Phase Resolution
+## Plan Resolution
 
 ```
-Input: <phase> argument (number or slug) OR --dir <path>
+Input: [phase] argument OR --dir <path>
 
-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)
-  4. Set PHASE_NUM = null, PHASE_SLUG = directory basename
+# 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
 
-ELSE (standard phase resolution):
-  1. If number: find .workflow/phases/{NN}-*/index.json
-  2. If slug: find .workflow/phases/*-{slug}/index.json
-  3. Validate plan exists (index.json.plan.task_count > 0)
-  4. Set PHASE_DIR = resolved path
+# Auto-bootstrap state.json if missing
+IF NOT file_exists(".workflow/state.json"):
+  mkdir -p .workflow/scratch/
+  Write minimal state.json
+
+IF --dir <path> is provided:
+  1. Set PLAN_DIRS = [<path>]  // single plan
+  2. Validate directory exists and contains plan.json
+
+ELSE IF no arguments:
+  // Find all pending plans for current milestone
+  1. Read state.json.artifacts
+  2. Filter: milestone == current_milestone, type == "plan", status == "completed"
+  3. Exclude plans that already have a corresponding EXC artifact (same path)
+  4. Sort by phase order (from roadmap), adhoc plans last
+  5. Set PLAN_DIRS = filtered plan paths
+  6. If empty: ERROR E001 "No pending plans found"
+
+ELSE IF argument is a number:
+  // Find pending plans for specific phase
+  1. Read state.json.artifacts
+  2. Filter: milestone == current_milestone, type == "plan", status == "completed", phase == arg
+  3. Exclude plans with existing EXC artifacts
+  4. Set PLAN_DIRS = filtered plan paths
+
+// Execute plans sequentially
+FOR each PLAN_DIR IN PLAN_DIRS:
+  execute_single_plan(PLAN_DIR)
+  register_exc_artifact(PLAN_DIR)
+  extract_incremental_learnings(PLAN_DIR)
 ```
 
 ---
@@ -43,11 +70,11 @@ ELSE (standard phase resolution):
 
 ---
 
-## E1: Load Plan
+## E1: Load Plan (per PLAN_DIR)
 
-**Purpose:** Build or receive the execution queue.
+**Purpose:** Build or receive the execution queue for a single plan.
 
-### From executionContext handoff (preferred)
+### From executionContext handoff (preferred, first plan only)
 
 ```
 If executionContext is available in memory:
@@ -60,23 +87,22 @@ If executionContext is available in memory:
   Skip disk reload
 ```
 
-### From disk (fallback / resume)
+### From disk (fallback / resume / subsequent plans)
 
 ```
-Read ${PHASE_DIR}/index.json
-Read ${PHASE_DIR}/plan.json
+Read ${PLAN_DIR}/plan.json
 
 executionMethod = --method flag || config.json.execution.method || "agent"
 defaultExecutor = --executor flag || config.json.execution.default_executor || "gemini"
-executorAssignments = index.json.plan.executor_assignments || {}
+executorAssignments = plan.json.executor_assignments || {}
 ```
 
 ### Detect completed tasks (breakpoint resume)
 
 ```
 completed_tasks = []
-For each task_id in index.json.plan.task_ids:
-  Read .task/${task_id}.json
+For each task_id in plan.json.task_ids:
+  Read ${PLAN_DIR}/.task/${task_id}.json
   If status == "completed":
     completed_tasks.push(task_id)
 
@@ -89,7 +115,7 @@ If completed_tasks.length > 0:
 ### Build wave execution queue
 
 ```
-waves = plan.json.waves (or index.json.plan.waves)
+waves = plan.json.waves
 
 execution_queue = []
 For each wave in waves:
@@ -195,7 +221,9 @@ For each wave in execution_queue (sequential):
     Read .workflow/state.json
     If state.json.status != "executing":
       state.json.status = "executing"
-      state.json.phases_summary.in_progress += 1
+      # 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
 
@@ -466,7 +494,7 @@ If config.json.workflow.reflection == true:
     - Any blocked tasks?
     - Patterns observed?
 
-  Append to ${PHASE_DIR}/reflection-log.md:
+  Append to ${PLAN_DIR}/reflection-log.md:
     ## Reflection - Wave Execution {timestamp}
     - Strategy adjustments: [...]
     - Patterns noted: [...]
@@ -506,12 +534,50 @@ If NOT SCRATCH_MODE:
 
 ---
 
+## E5: Register Artifact & Extract Learnings (per PLAN_DIR)
+
+**Purpose:** Register execution completion and extract incremental learnings.
+
+```
+// Register EXC artifact
+Read .workflow/state.json
+plan_artifact = state.json.artifacts.find(a => a.type == "plan" && a.path == PLAN_DIR_relative)
+next_id = max(artifacts.filter(a => a.type == "execute").map(a => parseInt(a.id.replace("EXC-","")))) + 1
+
+artifact = {
+  id: "EXC-{next_id padded to 3}",
+  type: "execute",
+  milestone: plan_artifact.milestone,
+  phase: plan_artifact.phase,
+  scope: plan_artifact.scope,
+  path: plan_artifact.path,    // same path — execute writes into plan dir
+  status: "completed",
+  depends_on: plan_artifact.id,
+  harvested: false,
+  created_at: execution_start_time,
+  completed_at: now()
+}
+
+state.json.artifacts.push(artifact)
+state.json.last_updated = now()
+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"
+Mark artifact.harvested = true
+Write state.json (atomic)
+```
+
+---
+
 ## Error Handling
 
 | Error | Action |
 |-------|--------|
-| Phase directory not found | Abort: "Phase {phase} not found." |
-| No plan exists | Abort: "No plan found. Run /workflow:plan first." |
+| No pending plans found | Abort: "No pending plans. Run /workflow:plan first." |
+| Plan directory not found | Abort: "Plan dir not found." |
 | Task file missing | Skip task, log error, continue wave |
 | Agent spawn fails | Retry once, then mark task as "blocked" |
 | Delegate fails | Resume with `--resume ${fixedId}`, then fallback to agent |