maestro-flow 0.3.15 → 0.3.17

package/dist/src/tools/store-knowhow.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Store KnowHow Tool — Create and search reusable knowledge entries.
+ *
+ * Replaces the deprecated core_memory tool. Writes directly to
+ * .workflow/knowhow/ as markdown files, automatically indexed by WikiIndexer.
+ *
+ * Operations: add, search
+ * Storage: .workflow/knowhow/{PREFIX}-{timestamp}.md
+ *
+ * Content types with type-specific fields:
+ *   session (KNW-) — session state recovery
+ *   tip     (TIP-) — quick note / reminder
+ *   template (TPL-) — code/config template [+ lang]
+ *   recipe   (RCP-) — step-by-step guide
+ *   reference (REF-) — external doc summary [+ source]
+ *   decision (DCS-) — architecture decision record [+ status]
+ */
+import type { ToolSchema, CcwToolResult } from '../types/tool-schema.js';
+export declare const schema: ToolSchema;
+export declare function handler(params: Record<string, unknown>): Promise<CcwToolResult>;
+//# sourceMappingURL=store-knowhow.d.ts.map

package/dist/src/tools/store-knowhow.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store-knowhow.d.ts","sourceRoot":"","sources":["../../../src/tools/store-knowhow.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAGH,OAAO,KAAK,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AA2MzE,eAAO,MAAM,MAAM,EAAE,UA+EpB,CAAC;AAIF,wBAAsB,OAAO,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,aAAa,CAAC,CAkBrF"}

package/dist/src/tools/store-knowhow.js

@@ -0,0 +1,295 @@
+/**
+ * Store KnowHow Tool — Create and search reusable knowledge entries.
+ *
+ * Replaces the deprecated core_memory tool. Writes directly to
+ * .workflow/knowhow/ as markdown files, automatically indexed by WikiIndexer.
+ *
+ * Operations: add, search
+ * Storage: .workflow/knowhow/{PREFIX}-{timestamp}.md
+ *
+ * Content types with type-specific fields:
+ *   session (KNW-) — session state recovery
+ *   tip     (TIP-) — quick note / reminder
+ *   template (TPL-) — code/config template [+ lang]
+ *   recipe   (RCP-) — step-by-step guide
+ *   reference (REF-) — external doc summary [+ source]
+ *   decision (DCS-) — architecture decision record [+ status]
+ */
+import { z } from 'zod';
+import { existsSync, mkdirSync, readFileSync, writeFileSync, readdirSync } from 'fs';
+import { join } from 'path';
+import { getProjectRoot } from '../utils/path-validator.js';
+// --- Types ---
+const CATEGORIES = ['session', 'tip', 'template', 'recipe', 'reference', 'decision'];
+const PREFIX_MAP = {
+    session: 'KNW',
+    tip: 'TIP',
+    template: 'TPL',
+    recipe: 'RCP',
+    reference: 'REF',
+    decision: 'DCS',
+};
+const DECISION_STATUSES = ['proposed', 'accepted', 'superseded'];
+// --- Zod Schema ---
+const OperationEnum = z.enum(['add', 'search']);
+const ParamsSchema = z.object({
+    operation: OperationEnum,
+    // add params
+    type: z.enum(CATEGORIES).optional(),
+    title: z.string().optional(),
+    body: z.string().optional(),
+    tags: z.array(z.string()).optional(),
+    // type-specific fields (persisted to frontmatter)
+    lang: z.string().optional(), // template: programming language
+    source: z.string().optional(), // reference: original URL
+    status: z.enum(DECISION_STATUSES).optional(), // decision: lifecycle status
+    // search params
+    query: z.string().optional(),
+    limit: z.number().optional().default(20),
+});
+// --- Storage ---
+function getKnowhowDir() {
+    return join(getProjectRoot(), '.workflow', 'knowhow');
+}
+function slugify(text) {
+    return text
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-|-$/g, '');
+}
+function generateId(type) {
+    const now = new Date();
+    const pad = (n) => String(n).padStart(2, '0');
+    const ts = `${now.getFullYear()}${pad(now.getMonth() + 1)}${pad(now.getDate())}-${pad(now.getHours())}${pad(now.getMinutes())}`;
+    const prefix = PREFIX_MAP[type];
+    const filename = `${prefix}-${ts}.md`;
+    return { id: `knowhow-${slugify(ts)}`, filename };
+}
+function escapeYamlValue(value) {
+    if (/[:\n"'#,{}[\]]/.test(value))
+        return JSON.stringify(value);
+    return value;
+}
+function parseFrontmatter(raw) {
+    const match = raw.match(/^---\s*\n([\s\S]*?)\n---\s*\n?/);
+    if (!match)
+        return { data: {}, body: raw };
+    const data = {};
+    for (const line of match[1].split('\n')) {
+        const kv = line.match(/^(\w[\w\s]*?):\s*(.*)$/);
+        if (kv)
+            data[kv[1].trim()] = kv[2].trim();
+    }
+    return { data, body: raw.slice(match[0].length) };
+}
+// --- Operations ---
+function executeAdd(params) {
+    const { type, title, body, tags, lang, source, status } = params;
+    if (!type)
+        return { success: false, error: 'Parameter "type" is required for add operation' };
+    if (!title)
+        return { success: false, error: 'Parameter "title" is required for add operation' };
+    if (!body)
+        return { success: false, error: 'Parameter "body" is required for add operation' };
+    // Validate type-specific fields
+    if (lang && type !== 'template') {
+        return { success: false, error: 'Parameter "lang" is only valid for type "template"' };
+    }
+    if (source && type !== 'reference') {
+        return { success: false, error: 'Parameter "source" is only valid for type "reference"' };
+    }
+    if (status && type !== 'decision') {
+        return { success: false, error: 'Parameter "status" is only valid for type "decision"' };
+    }
+    const dir = getKnowhowDir();
+    if (!existsSync(dir))
+        mkdirSync(dir, { recursive: true });
+    const { id, filename } = generateId(type);
+    const filePath = join(dir, filename);
+    // Build YAML frontmatter with type-specific fields
+    const now = new Date().toISOString();
+    const fmLines = ['---'];
+    fmLines.push(`title: ${escapeYamlValue(title)}`);
+    fmLines.push(`type: ${type}`);
+    fmLines.push(`category: ${type}`);
+    fmLines.push(`created: ${now}`);
+    if (tags && tags.length > 0) {
+        fmLines.push(`tags:`);
+        for (const t of tags)
+            fmLines.push(`  - ${t}`);
+    }
+    // Type-specific frontmatter fields
+    if (lang)
+        fmLines.push(`lang: ${lang}`);
+    if (source)
+        fmLines.push(`source: ${escapeYamlValue(source)}`);
+    if (status)
+        fmLines.push(`status: ${status}`);
+    fmLines.push('---', '', body);
+    writeFileSync(filePath, fmLines.join('\n'), 'utf-8');
+    return {
+        success: true,
+        result: {
+            operation: 'add',
+            id,
+            filename,
+            type,
+            path: `knowhow/${filename}`,
+            message: `Created ${type} entry: ${id}`,
+        },
+    };
+}
+function executeSearch(params) {
+    const { query, limit } = params;
+    if (!query)
+        return { success: false, error: 'Parameter "query" is required for search operation' };
+    const dir = getKnowhowDir();
+    if (!existsSync(dir)) {
+        return { success: true, result: { operation: 'search', query, matches: [], total_matches: 0 } };
+    }
+    const queryLower = query.toLowerCase();
+    const queryTerms = queryLower.split(/\s+/).filter(Boolean);
+    const results = [];
+    for (const name of readdirSync(dir)) {
+        if (!name.endsWith('.md'))
+            continue;
+        try {
+            const raw = readFileSync(join(dir, name), 'utf-8');
+            const { data, body: bodyText } = parseFrontmatter(raw);
+            const contentLower = raw.toLowerCase();
+            const matchCount = queryTerms.filter((t) => contentLower.includes(t)).length;
+            if (matchCount === 0)
+                continue;
+            const score = matchCount / queryTerms.length;
+            const prefix = name.match(/^([A-Z]+)-\d{8}/)?.[1] ?? '';
+            const typeCat = Object.entries(PREFIX_MAP).find(([, p]) => p === prefix)?.[0] ?? '';
+            results.push({
+                id: data.id || name.replace('.md', ''),
+                filename: name,
+                title: data.title || 'Untitled',
+                type: typeCat,
+                lang: data.lang,
+                source: data.source,
+                status: data.status,
+                score: Math.round(score * 100) / 100,
+                excerpt: bodyText.substring(0, 200) + (bodyText.length > 200 ? '...' : ''),
+            });
+        }
+        catch {
+            continue;
+        }
+    }
+    results.sort((a, b) => b.score - a.score);
+    const limited = results.slice(0, limit);
+    return {
+        success: true,
+        result: {
+            operation: 'search',
+            query,
+            matches: limited,
+            total_matches: results.length,
+        },
+    };
+}
+// --- Tool Schema ---
+export const schema = {
+    name: 'store_knowhow',
+    description: `Store reusable knowledge (knowhow) entries to .workflow/knowhow/.
+
+**Operations:**
+
+*   **add** — Create a new knowhow entry.
+    Required: type, title, body
+    Type-specific fields:
+      template:  lang (programming language)
+      reference: source (URL)
+      decision:  status (proposed | accepted | superseded)
+    Optional: tags (string[])
+
+*   **search** — Full-text search knowhow entries.
+    Required: query
+    Optional: limit (default: 20)
+
+**Types & prefixes:**
+  session   → KNW-{ts}.md   session state recovery
+  tip       → TIP-{ts}.md   quick note / reminder
+  template  → TPL-{ts}.md   code/config template
+  recipe    → RCP-{ts}.md   step-by-step guide
+  reference → REF-{ts}.md   external doc summary
+  decision  → DCS-{ts}.md   architecture decision record
+
+Entries are automatically indexed by WikiIndexer (type=knowhow, category={type}).`,
+    inputSchema: {
+        type: 'object',
+        properties: {
+            operation: {
+                type: 'string',
+                enum: ['add', 'search'],
+                description: 'Operation to perform',
+            },
+            type: {
+                type: 'string',
+                enum: CATEGORIES,
+                description: 'Knowhow content type. Required for add.',
+            },
+            title: {
+                type: 'string',
+                description: 'Entry title. Required for add.',
+            },
+            body: {
+                type: 'string',
+                description: 'Entry body in markdown. Required for add.',
+            },
+            tags: {
+                type: 'array',
+                items: { type: 'string' },
+                description: 'Categorization tags.',
+            },
+            // type-specific
+            lang: {
+                type: 'string',
+                description: '[template] Programming language (e.g. typescript, python, bash, yaml).',
+            },
+            source: {
+                type: 'string',
+                description: '[reference] Original URL or document identifier.',
+            },
+            status: {
+                type: 'string',
+                enum: DECISION_STATUSES,
+                description: '[decision] Lifecycle status: proposed → accepted → superseded.',
+            },
+            // search
+            query: {
+                type: 'string',
+                description: 'Search query. Required for search.',
+            },
+            limit: {
+                type: 'number',
+                description: 'Max search results (default: 20).',
+            },
+        },
+        required: ['operation'],
+    },
+};
+// --- Handler ---
+export async function handler(params) {
+    const parsed = ParamsSchema.safeParse(params);
+    if (!parsed.success) {
+        return { success: false, error: `Invalid params: ${parsed.error.message}` };
+    }
+    try {
+        switch (parsed.data.operation) {
+            case 'add':
+                return executeAdd(parsed.data);
+            case 'search':
+                return executeSearch(parsed.data);
+            default:
+                return { success: false, error: `Unknown operation: ${parsed.data.operation}` };
+        }
+    }
+    catch (error) {
+        return { success: false, error: error.message };
+    }
+}
+//# sourceMappingURL=store-knowhow.js.map

package/dist/src/tools/store-knowhow.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"store-knowhow.js","sourceRoot":"","sources":["../../../src/tools/store-knowhow.ts"],"names":[],"mappings":"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"}

package/package.json

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

package/shared/agent-types.ts

@@ -36,6 +36,8 @@ export interface AgentConfig {
   envFile?: string;
   /** When true, spawn in interactive mode (stdin kept open for follow-up messages) */
   interactive?: boolean;
+  /** Path to MCP config JSON file for CLI agents (claude-code --mcp-config) */
+  mcpConfigPath?: string;
   /** Opaque metadata bag — used to pass team session context through the spawn pipeline */
   metadata?: Record<string, unknown>;
 }

package/workflows/analyze.md

@@ -54,47 +54,19 @@ $ARGUMENTS: "[phase|topic] [-y] [-c] [-q]"
 ## 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}
+Worktree guard: If .workflow/worktree-scope.json exists, reject phase args not in owned_phases.
+
+Auto-bootstrap: Create minimal .workflow/state.json if missing.
+
+Scope determination → OUTPUT_DIR:
+  (no args) + milestone + roadmap → scope="milestone", OUTPUT_DIR=.workflow/scratch/analyze-{milestone_slug}-{date}/
+  (no args) without milestone/roadmap → ERROR E001
+  (number) + milestone + roadmap   → scope="phase", OUTPUT_DIR=.workflow/scratch/analyze-{phase_slug}-{date}/
+  (number) without milestone/roadmap → ERROR
+  (text) + milestone               → scope="adhoc", OUTPUT_DIR=.workflow/scratch/analyze-{topic_slug}-{date}/
+  (text) without milestone         → scope="standalone", OUTPUT_DIR=.workflow/scratch/analyze-{topic_slug}-{date}/
+
+Create OUTPUT_DIR.
 ```
 
 ## Output Structure
@@ -152,20 +124,8 @@ Before writing any new artifacts, archive existing ones to preserve history:
 ```
 ARCHIVE_TARGETS = ["discussion.md", "analysis.md", "explorations.json", "perspectives.json", "conclusions.json", "exploration-codebase.json"]
 
-has_existing = false
-FOR artifact IN ARCHIVE_TARGETS:
-  IF file exists "$OUTPUT_DIR/${artifact}":
-    has_existing = true
-    break
-
-IF has_existing:
-  mkdir -p "$OUTPUT_DIR/.history"
-  TIMESTAMP = current timestamp formatted as "YYYY-MM-DDTHH-mm-ss"
-  FOR artifact IN ARCHIVE_TARGETS:
-    IF file exists "$OUTPUT_DIR/${artifact}":
-      // Extract name and extension: "analysis.md" → "analysis" + "md"
-      mv "$OUTPUT_DIR/${artifact}" "$OUTPUT_DIR/.history/${name}-${TIMESTAMP}.${ext}"
-  display "Archived previous analysis artifacts to .history/"
+If any ARCHIVE_TARGETS exist in OUTPUT_DIR:
+  Move each existing target to OUTPUT_DIR/.history/{name}-{YYYY-MM-DDTHH-mm-ss}.{ext}
 ```
 
 ### Step 2: Scoping & Dimension Selection
@@ -222,47 +182,18 @@ Codebase exploration FIRST, then (optionally) external research, then CLI analys
 Orchestrator performs targeted web searches, then hands results to `workflow-phase-researcher` agent for synthesis.
 
 ```
-// Step 4.0.1: Orchestrator web searches (2-3 focused queries)
-queries = [
-  "{phase_goal} standard library stack {current_year}",
-  "{phase_goal} architecture patterns best practices",
-  "{phase_goal} common pitfalls mistakes"
-]
-
-For each query:
-  results = WebSearch(query)
-  // For top 1-2 results: WebFetch(url) to get official docs / README
-
-// Step 4.0.2: Hand raw search output to researcher agent
-Agent(
-  subagent_type="workflow-phase-researcher",
-  prompt="""
-<objective>
-Synthesize the following web search results for Phase {PHASE_NUM}: {phase_name}.
-Goal: {phase_goal}
-</objective>
-
-<search_results>
-{raw_search_output}
-</search_results>
-
-<task>
-From the search results above, extract and structure:
-- ## Standard Stack: concrete library recommendations with versions
-- ## Architecture Patterns: recommended patterns for this type of work
-- ## Don't Hand-Roll: problems with existing solutions (don't build custom)
-- ## Common Pitfalls: mistakes to avoid
-
-Be prescriptive ("use X") not exploratory ("consider X or Y").
-Cite sources. Assign confidence levels (HIGH/MEDIUM/LOW).
-Do NOT write any files — return structured markdown only.
-</task>
-  """,
-  run_in_background=false
-)
-
-// Step 4.0.3: Store as researchContext (in-memory, no file written)
-researchContext = agent_output
+1. WebSearch 2-3 queries: "{phase_goal} standard library stack", "architecture patterns best practices", "common pitfalls mistakes"
+   Fetch top 1-2 results per query for official docs.
+
+2. Hand raw search output to workflow-phase-researcher agent to synthesize into:
+   - ## Standard Stack: concrete library recommendations with versions
+   - ## Architecture Patterns: recommended patterns
+   - ## Don't Hand-Roll: problems with existing solutions
+   - ## Common Pitfalls: mistakes to avoid
+   Style: prescriptive ("use X"), cite sources, confidence levels (HIGH/MEDIUM/LOW).
+   Agent returns structured markdown only (no file writes).
+
+3. Store agent output as researchContext (in-memory).
 ```
 
 `researchContext` is passed into Step 4.2 CLI Analysis and Step 8 Decision Extraction.
@@ -550,75 +481,34 @@ Write to `OUTPUT_DIR/context.md`:
 **8.6: Update project.md Key Decisions** (phase mode only)
 
 ```
-IF phase mode AND Locked decisions exist:
-  Read .workflow/project.md
-  Find "## Key Decisions" table
-
-  For each Locked decision from Step 8.4:
-    Check if decision already exists in Key Decisions table (by title match)
-    If not duplicate:
-      Append row to Key Decisions table:
-        | {decision title} | {rationale summary} | Phase {NN} — {date} |
-
-  Write updated project.md
-  Display: "project.md: {count} key decisions recorded"
+Phase mode only: Append each new Locked decision to .workflow/project.md "## Key Decisions" table.
+Row format: | {decision title} | {rationale summary} | Phase {NN} — {date} |
+Skip duplicates (match by title).
 ```
 
 **8.7: Auto-create Issues from Deferred Items**
 
 ```
-deferred_items = decisions.filter(d => d.classification == "Deferred")
-
-IF deferred_items.length > 0:
-  mkdir -p ".workflow/issues"
-  today = format(now(), "YYYYMMDD")
-  counter = next sequence number for today
-
-  FOR each item IN deferred_items:
-    issue_id = "ISS-{today}-{counter padded to 3 digits}"
-    issue = {
-      id: issue_id,
-      title: "Deferred: " + item.title,
-      status: "deferred",
-      priority: 5,
-      severity: "low",
-      source: "analyze",
-      phase_ref: PHASE_NUM,
-      description: item.context + " -- Chosen to defer: " + item.reason,
-      tags: ["deferred", "analyze"],
-      created_at: now()
-    }
-    Append JSON line to .workflow/issues/issues.jsonl
-    counter++
-
-  Print: "Created {deferred_items.length} deferred issues for tracking"
+For each Deferred decision, create an issue in .workflow/issues/issues.jsonl:
+  id: "ISS-{YYYYMMDD}-{NNN}"
+  title: "Deferred: {item.title}"
+  status: "deferred", priority: 5, severity: "low"
+  source: "analyze", phase_ref: PHASE_NUM
+  description: "{item.context} -- Chosen to defer: {item.reason}"
+  tags: ["deferred", "analyze"]
 ```
 
 ### 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)
+Register artifact in .workflow/state.json:
+  id: "ANL-{next sequential 3-digit id}"
+  type: "analyze", scope: scope, status: "completed"
+  milestone: current_milestone (null if standalone)
+  phase: phase_num (null if milestone/adhoc/standalone)
+  path: OUTPUT_DIR relative to .workflow/
+  harvested: false, created_at: session_start_time, completed_at: now()
+Atomic write (tmp + rename).
 ```
 
 ### Step 9: Report & Next Step
@@ -649,36 +539,22 @@ Handle selection:
 Before invoking maestro-plan, build and persist `implementation_scope` so the planner has concrete "what + done-when" specs:
 
 ```
-// Step A: Build implementation scope from accepted/modified recommendations
-actionableRecs = conclusions.recommendations
-  .filter(r => r.review_status in ["accepted", "modified"])
-  .sort by priority (high first)
-
-implementation_scope = actionableRecs.map(rec => ({
-  objective: rec.action,                         // WHAT to do
-  rationale: rec.rationale,                       // WHY
-  priority: rec.priority,
-  target_files: rec.steps.flatMap(s => s.target)  // WHERE (from steps + code_anchors)
-    .concat(code_anchors matching rec),
-  acceptance_criteria: rec.steps.map(s =>         // DONE WHEN
-    s.verification || s.description),
-  change_summary: rec.steps.map(s =>              // HOW (brief)
-    "${s.target}: ${s.description}").join('; ')
-}))
-
-// Step B: User scope confirmation (skip in auto mode / quick mode)
-IF NOT AUTO_MODE:
-  Display implementation scope summary:
-    For each item: objective [priority], target files, "Done when: ..."
-  AskUserQuestion (single-select, header: "Scope确认"):
-    - "确认执行": Scope is clear, proceed to planning
-    - "调整范围": Narrow or expand scope
-    - "补充标准": Add/refine acceptance criteria
-  Handle adjustments, re-confirm if needed
-
-// Step C: Persist to conclusions.json
-conclusions.implementation_scope = implementation_scope
-Write updated conclusions.json to OUTPUT_DIR
+// Step A: Build implementation_scope from accepted/modified recommendations (sorted by priority)
+Each scope item:
+  objective: rec.action          // WHAT
+  rationale: rec.rationale       // WHY
+  priority: rec.priority
+  target_files: from rec.steps targets + matching code_anchors  // WHERE
+  acceptance_criteria: from rec.steps verification/description  // DONE WHEN
+  change_summary: "{target}: {description}" per step            // HOW
+
+// Step B: User scope confirmation (skip in auto/quick mode)
+AskUserQuestion (single-select, header: "Scope确认"):
+  - "确认执行": Proceed to planning
+  - "调整范围": Narrow or expand scope
+  - "补充标准": Add/refine acceptance criteria
+
+// Step C: Persist implementation_scope to conclusions.json
 
 // Step D: Invoke plan
 Phase mode: Skill({ skill: "maestro-plan", args: "{phase}" })