zefiro 0.3.7 → 0.4.0

package/dist/mcp.js

@@ -1,7 +1,9 @@
 #!/usr/bin/env node
 import {
-  runStage1
-} from "./cli-ek34kdc1.js";
+  runStage1,
+  validateQAMap,
+  validateQAMapV3
+} from "./cli-fc97msmj.js";
 import {
   $ZodObject,
   $ZodType,
@@ -14871,12 +14873,15 @@ function summarizeAST(ast, savedPath) {
     routes: ast.routes.map((r) => ({
       path: r.path,
       filePath: r.filePath,
-      isDynamic: r.isDynamic
+      isDynamic: r.isDynamic,
+      layoutChain: r.layoutChain,
+      routeGroup: r.routeGroup
     })),
     fileTree: ast.files.map((f) => f.path),
     componentNames: ast.components.map((c) => c.name),
     hookNames: ast.hooks.filter((h) => h.isCustom).map((h) => h.name),
     directoryGroups: dirGroups,
+    navigationPatternCount: ast.navigationPatterns?.length ?? 0,
     astScanPath: savedPath
   };
 }
@@ -14904,6 +14909,9 @@ function filterASTByCategory(ast, category, filter, limit) {
     case "files":
       items = filter ? ast.files.filter((f) => matchesFilter(f.path)) : ast.files;
       break;
+    case "navigationPatterns":
+      items = ast.navigationPatterns ? filter ? ast.navigationPatterns.filter((n) => matchesFilter(n.sourceFile) || matchesFilter(n.targetRoute ?? "")) : ast.navigationPatterns : [];
+      break;
   }
   if (limit && limit > 0) {
     items = items.slice(0, limit);
@@ -14916,221 +14924,6 @@ function filterASTByCategory(ast, category, filter, limit) {
   };
 }
 
-// src/scanner/validate.ts
-var WORKFLOW_TYPES = ["navigation", "crud", "multi-step", "configuration", "search-filter"];
-var COMPONENT_TYPES = ["form", "display", "navigation", "modal", "layout", "feedback"];
-var SCENARIO_CATEGORIES = ["happy-path", "permission", "validation", "error", "edge-case", "precondition"];
-var SCENARIO_PRIORITIES = ["critical", "high", "medium", "low"];
-var BRANCH_TYPES = ["validation", "permission", "error", "business-logic"];
-function validateQAMap(payload) {
-  const errors = [];
-  const warnings = [];
-  if (!payload || typeof payload !== "object") {
-    return { valid: false, errors: ["Payload must be a non-null object"], warnings };
-  }
-  const p = payload;
-  const features = assertArray(p, "features", errors);
-  const workflows = assertArray(p, "workflows", errors);
-  const components = assertArray(p, "components", errors);
-  const scenarios = assertArray(p, "scenarios", errors);
-  if (errors.length > 0) {
-    return { valid: false, errors, warnings };
-  }
-  const featureIds = new Set;
-  const workflowIds = new Set;
-  const componentIds = new Set;
-  const scenarioIds = new Set;
-  const workflowStepIds = new Set;
-  for (const f of features) {
-    requireString(f, "id", "feature", errors);
-    requireString(f, "name", "feature", errors);
-    requireString(f, "description", "feature", errors);
-    requireArray(f, "routes", "feature", errors);
-    requireArray(f, "workflowIds", "feature", errors);
-    requireArray(f, "sourceFiles", "feature", errors);
-    if (f.id) {
-      if (featureIds.has(f.id))
-        errors.push(`Duplicate feature id: ${f.id}`);
-      featureIds.add(f.id);
-    }
-  }
-  for (const w of workflows) {
-    requireString(w, "id", "workflow", errors);
-    requireString(w, "name", "workflow", errors);
-    requireString(w, "featureId", "workflow", errors);
-    requireEnum(w, "type", WORKFLOW_TYPES, "workflow", errors);
-    requireArray(w, "preconditions", "workflow", errors);
-    requireArray(w, "steps", "workflow", errors);
-    requireArray(w, "componentIds", "workflow", errors);
-    if (w.id) {
-      if (workflowIds.has(w.id))
-        errors.push(`Duplicate workflow id: ${w.id}`);
-      workflowIds.add(w.id);
-    }
-    if (Array.isArray(w.steps)) {
-      for (const s of w.steps) {
-        requireString(s, "id", "workflowStep", errors);
-        requireNumber(s, "order", "workflowStep", errors);
-        requireString(s, "description", "workflowStep", errors);
-        requireArray(s, "componentIds", "workflowStep", errors);
-        requireArray(s, "apiCalls", "workflowStep", errors);
-        requireArray(s, "conditionalBranches", "workflowStep", errors);
-        if (s.id)
-          workflowStepIds.add(s.id);
-        if (Array.isArray(s.conditionalBranches)) {
-          for (const b of s.conditionalBranches) {
-            requireString(b, "condition", "conditionalBranch", errors);
-            requireString(b, "outcome", "conditionalBranch", errors);
-            requireEnum(b, "type", BRANCH_TYPES, "conditionalBranch", errors);
-          }
-        }
-      }
-    }
-  }
-  for (const c of components) {
-    requireString(c, "id", "component", errors);
-    requireString(c, "name", "component", errors);
-    requireEnum(c, "type", COMPONENT_TYPES, "component", errors);
-    requireArray(c, "sourceFiles", "component", errors);
-    requireArray(c, "props", "component", errors);
-    requireArray(c, "referencedByWorkflows", "component", errors);
-    if (c.id) {
-      if (componentIds.has(c.id))
-        errors.push(`Duplicate component id: ${c.id}`);
-      componentIds.add(c.id);
-    }
-  }
-  for (const s of scenarios) {
-    requireString(s, "id", "scenario", errors);
-    requireString(s, "workflowId", "scenario", errors);
-    requireString(s, "featureId", "scenario", errors);
-    requireString(s, "name", "scenario", errors);
-    requireString(s, "description", "scenario", errors);
-    requireEnum(s, "category", SCENARIO_CATEGORIES, "scenario", errors);
-    requireArray(s, "preconditions", "scenario", errors);
-    requireArray(s, "steps", "scenario", errors);
-    requireString(s, "expectedOutcome", "scenario", errors);
-    requireArray(s, "componentIds", "scenario", errors);
-    requireArray(s, "workflowStepIds", "scenario", errors);
-    requireEnum(s, "priority", SCENARIO_PRIORITIES, "scenario", errors);
-    if (s.id) {
-      if (scenarioIds.has(s.id))
-        errors.push(`Duplicate scenario id: ${s.id}`);
-      scenarioIds.add(s.id);
-    }
-    if (Array.isArray(s.steps)) {
-      for (const step of s.steps) {
-        requireNumber(step, "order", "scenarioStep", errors);
-        requireString(step, "action", "scenarioStep", errors);
-        requireString(step, "expectedResult", "scenarioStep", errors);
-      }
-    }
-  }
-  for (const w of workflows) {
-    if (w.featureId && !featureIds.has(w.featureId)) {
-      errors.push(`Workflow "${w.id}" references unknown feature: ${w.featureId}`);
-    }
-    if (Array.isArray(w.componentIds)) {
-      for (const cid of w.componentIds) {
-        if (!componentIds.has(cid)) {
-          errors.push(`Workflow "${w.id}" references unknown component: ${cid}`);
-        }
-      }
-    }
-  }
-  for (const f of features) {
-    if (Array.isArray(f.workflowIds)) {
-      for (const wid of f.workflowIds) {
-        if (!workflowIds.has(wid)) {
-          errors.push(`Feature "${f.id}" references unknown workflow: ${wid}`);
-        }
-      }
-    }
-  }
-  for (const s of scenarios) {
-    if (s.workflowId && !workflowIds.has(s.workflowId)) {
-      errors.push(`Scenario "${s.id}" references unknown workflow: ${s.workflowId}`);
-    }
-    if (s.featureId && !featureIds.has(s.featureId)) {
-      errors.push(`Scenario "${s.id}" references unknown feature: ${s.featureId}`);
-    }
-    if (Array.isArray(s.componentIds)) {
-      for (const cid of s.componentIds) {
-        if (!componentIds.has(cid)) {
-          errors.push(`Scenario "${s.id}" references unknown component: ${cid}`);
-        }
-      }
-    }
-    if (Array.isArray(s.workflowStepIds)) {
-      for (const wsid of s.workflowStepIds) {
-        if (!workflowStepIds.has(wsid)) {
-          errors.push(`Scenario "${s.id}" references unknown workflow step: ${wsid}`);
-        }
-      }
-    }
-  }
-  for (const c of components) {
-    if (Array.isArray(c.referencedByWorkflows)) {
-      for (const wid of c.referencedByWorkflows) {
-        if (!workflowIds.has(wid)) {
-          errors.push(`Component "${c.id}" references unknown workflow: ${wid}`);
-        }
-      }
-    }
-  }
-  for (const f of features) {
-    if (Array.isArray(f.workflowIds) && f.workflowIds.length === 0) {
-      warnings.push(`Feature "${f.id}" has no workflows`);
-    }
-  }
-  for (const w of workflows) {
-    const hasScenarios = scenarios.some((s) => s.workflowId === w.id);
-    if (!hasScenarios) {
-      warnings.push(`Workflow "${w.id}" has no scenarios`);
-    }
-  }
-  const referencedComponentIds = new Set;
-  for (const w of workflows) {
-    if (Array.isArray(w.componentIds)) {
-      for (const cid of w.componentIds)
-        referencedComponentIds.add(cid);
-    }
-  }
-  for (const c of components) {
-    if (c.id && !referencedComponentIds.has(c.id)) {
-      warnings.push(`Component "${c.id}" is not referenced by any workflow`);
-    }
-  }
-  return { valid: errors.length === 0, errors, warnings };
-}
-function assertArray(obj, field, errors) {
-  if (!Array.isArray(obj[field])) {
-    errors.push(`Missing or invalid top-level array: ${field}`);
-    return [];
-  }
-  return obj[field];
-}
-function requireString(obj, field, context, errors) {
-  if (typeof obj?.[field] !== "string" || obj[field].length === 0) {
-    errors.push(`${context} missing required string field: ${field} (id: ${obj?.id ?? "unknown"})`);
-  }
-}
-function requireNumber(obj, field, context, errors) {
-  if (typeof obj?.[field] !== "number") {
-    errors.push(`${context} missing required number field: ${field} (id: ${obj?.id ?? "unknown"})`);
-  }
-}
-function requireArray(obj, field, context, errors) {
-  if (!Array.isArray(obj?.[field])) {
-    errors.push(`${context} missing required array field: ${field} (id: ${obj?.id ?? "unknown"})`);
-  }
-}
-function requireEnum(obj, field, allowed, context, errors) {
-  if (typeof obj?.[field] !== "string" || !allowed.includes(obj[field])) {
-    errors.push(`${context} invalid ${field}: "${obj?.[field]}" — expected one of: ${allowed.join(", ")} (id: ${obj?.id ?? "unknown"})`);
-  }
-}
-
 // src/utils/scan.ts
 import { readdirSync, existsSync, readFileSync } from "node:fs";
 import { join, relative } from "node:path";
@@ -15201,11 +14994,12 @@ var SERVER_INSTRUCTIONS = `
 # Zefiro — Scanner & QA Map Guide
 
 You have access to Zefiro, an AI-powered codebase scanner and QA map generator.
+Supports two schema versions: V2 (flat/linear) and V3 (hierarchical/DAG). **Default to V3.**
 
 ## Core Workflow
 
 1. **Scan.** Call \`zefiro_scan_ast()\` to run the AST scanner and get a compact summary.
-2. **Explore.** Use \`zefiro_scan_ast_detail()\` to drill into routes, components, hooks, or files.
+2. **Explore.** Use \`zefiro_scan_ast_detail()\` to drill into routes, components, hooks, files, or navigationPatterns.
 3. **Propose & discuss.** Present candidate features to the user, ask clarifying questions.
 4. **Build.** Construct the QA map payload and validate with \`zefiro_build_qa_map({ dryRun: true })\`.
 5. **Write.** Once validated and approved, call \`zefiro_build_qa_map({ dryRun: false })\` to save.
@@ -15214,126 +15008,207 @@ You have access to Zefiro, an AI-powered codebase scanner and QA map generator.
 ## Tools
 
 - \`zefiro_scan_codebase\` — scan test files, configs, fixtures, path aliases
-- \`zefiro_scan_ast\` — deep AST scan: routes, components, hooks, imports
-- \`zefiro_scan_ast_detail\` — drill into a specific AST category
-- \`zefiro_build_qa_map\` — validate + write QAMapV2Payload
+- \`zefiro_scan_ast\` — deep AST scan: routes, components, hooks, imports, navigation patterns
+- \`zefiro_scan_ast_detail\` — drill into a specific AST category (routes, components, hooks, dependencies, files, navigationPatterns)
+- \`zefiro_build_qa_map\` — validate + write QA map payload (V2 or V3, auto-detected)
 - \`zefiro_read_qa_map\` — read existing QA map
 
+## Scanner V3 Enhancements
+
+The AST scanner extracts additional data useful for V3 map generation:
+- **Navigation patterns**: \`<Link>\`, \`router.push()\`, \`redirect()\` — used for entry point detection
+- **Layout chains**: layout files in route hierarchy — used for section grouping
+- **Route groups**: Next.js route groups like \`(authenticated)\` — section boundaries
+- **Conditional logic**: if/ternary/switch counts and guard patterns per component — branching hints
+
+Use \`zefiro_scan_ast_detail({ category: "navigationPatterns" })\` to explore navigation links.
+Routes returned by \`zefiro_scan_ast_detail({ category: "routes" })\` include \`layoutChain\` and \`routeGroup\`.
+Components include \`conditionalCount\` and \`guardPatterns\`.
+
 ---
 
-## QAMapV2Payload Schema Reference
+## QAMapV3Payload Schema Reference (preferred)
 
-The payload passed to \`zefiro_build_qa_map\` MUST conform exactly to this schema. All fields are required unless marked optional.
+V3 payloads include \`schemaVersion: 3\` and support hierarchical features, DAG workflows, and structured conditions.
 
 ### Top-level structure
 \`\`\`
 {
-  features:   Feature[]    // required, may be []
-  workflows:  Workflow[]   // required, may be []
-  components: Component[]  // required, may be []
-  scenarios:  Scenario[]   // required, may be []
-  commitSha?: string       // optional, auto-injected by the tool
-  metadata?:  object       // optional free-form
+  schemaVersion: 3
+  sections:   Section[]    // required, may be []
+  features:   FeatureV3[]  // required, may be []
+  workflows:  WorkflowV3[] // required, may be []
+  components: Component[]  // required, may be [] (same as V2)
+  scenarios:  ScenarioV3[] // required, may be []
+  commitSha?: string
+  metadata?:  object
 }
 \`\`\`
 
-### Feature
+### ConditionV3 (used in preconditions, postconditions, branchCondition)
 \`\`\`
 {
-  id:          string    // unique, e.g. "feat-auth"
+  entity:   string   // "user", "form", "list", "session"
+  state:    string   // "role", "count", "isValid", "status"
+  operator: "equals" | "notEquals" | "greaterThan" | "lessThan" | "contains" | "exists" | "isEmpty"
+  value:    string | number | boolean
+}
+\`\`\`
+
+### Section (3-level hierarchy top level)
+\`\`\`
+{
+  id:          string    // "sec:<slug>"
   name:        string
   description: string
-  routes:      string[]  // URL paths this feature covers, e.g. ["/login", "/register"]
-  workflowIds: string[]  // IDs of workflows that belong to this feature
-  sourceFiles: string[]  // relative file paths, e.g. ["src/app/login/page.tsx"]
+  featureIds:  string[]  // top-level feature IDs in this section
 }
 \`\`\`
 
-### Workflow
+### FeatureV3
 \`\`\`
 {
-  id:            string
-  name:          string
-  featureId:     string   // must match an existing feature id
-  type:          "navigation" | "crud" | "multi-step" | "configuration" | "search-filter"
-  preconditions: string[] // may be []
-  steps:         WorkflowStep[]
-  componentIds:  string[] // component ids used by this workflow, may be []
+  id:              string   // "feat:<slug>-<hash>"
+  name:            string
+  description:     string
+  sectionId:       string   // must match a section id
+  parentFeatureId?: string  // set if sub-feature
+  subFeatureIds:   string[] // child feature IDs
+  routes:          string[]
+  workflowIds:     string[]
+  sourceFiles:     string[]
+  entryPoints:     EntryPoint[] // how users reach this feature
 }
 \`\`\`
 
-### WorkflowStep
+### EntryPoint
 \`\`\`
 {
-  id:                  string
-  order:               number  // 1-based integer
-  description:         string
-  componentIds:        string[] // component ids involved in this step, may be []
-  apiCalls:            string[] // API endpoints called, e.g. ["POST /api/login"], may be []
-  conditionalBranches: ConditionalBranch[] // may be []
+  type:             "sidebar-nav" | "breadcrumb" | "deep-link" | "redirect" | "button" | "notification" | "url-direct"
+  sourceFeatureId?: string   // feature the link originates from
+  description:      string
 }
 \`\`\`
 
-### ConditionalBranch
+### WorkflowV3 (DAG-based)
 \`\`\`
 {
-  condition: string  // e.g. "invalid credentials"
-  outcome:   string  // e.g. "show error message"
-  type:      "validation" | "permission" | "error" | "business-logic"
+  id:             string
+  name:           string
+  featureId:      string
+  type:           "navigation" | "crud" | "multi-step" | "configuration" | "search-filter" | "authentication" | "notification" | "integration"
+  preconditions:  ConditionV3[]
+  postconditions: ConditionV3[]
+  steps:          WorkflowStepV3[]
+  edges:          WorkflowEdge[]
+  entryStepIds:   string[]   // steps with no incoming edges
+  componentIds:   string[]
 }
 \`\`\`
 
-### Component
+### WorkflowStepV3
 \`\`\`
 {
-  id:                   string
-  name:                 string
-  type:                 "form" | "display" | "navigation" | "modal" | "layout" | "feedback"
-  sourceFiles:          string[] // relative file paths
-  props:                string[] // prop names, may be []
-  referencedByWorkflows: string[] // workflow ids that use this component, may be []
+  id:              string   // "step:<workflowId>:<slug>"
+  description:     string
+  action:          "user-action" | "system-response" | "navigation" | "api-call" | "conditional"
+  componentIds:    string[]
+  apiCalls:        string[]
+  nextStepIds:     string[]  // outgoing edges — empty = terminal step
+  branchCondition?: ConditionV3  // set when action="conditional"
+  metadata?:       object
+}
+\`\`\`
+
+### WorkflowEdge
+\`\`\`
+{
+  fromStepId: string
+  toStepId:   string
+  label?:     string   // "valid", "invalid", "admin", "error"
+  edgeType:   "default" | "branch" | "error" | "convergence"
 }
 \`\`\`
 
-### Scenario
+### ScenarioV3
 \`\`\`
 {
   id:              string
-  workflowId:      string   // must match an existing workflow id
-  featureId:       string   // must match an existing feature id
+  workflowId:      string
+  featureId:       string
   name:            string
   description:     string
   category:        "happy-path" | "permission" | "validation" | "error" | "edge-case" | "precondition"
-  preconditions:   string[] // may be []
+  preconditions:   ConditionV3[]
+  path:            string[]     // ordered step IDs tracing one path through the DAG
   steps:           ScenarioStep[]
   expectedOutcome: string
-  componentIds:    string[] // component ids exercised, may be []
-  workflowStepIds: string[] // workflow step ids covered, may be []
+  componentIds:    string[]
   priority:        "critical" | "high" | "medium" | "low"
 }
 \`\`\`
 
-### ScenarioStep
+### Component (same as V2)
+\`\`\`
+{
+  id:                    string
+  name:                  string
+  type:                  "form" | "display" | "navigation" | "modal" | "layout" | "feedback"
+  sourceFiles:           string[]
+  props:                 string[]
+  referencedByWorkflows: string[]
+}
+\`\`\`
+
+### ScenarioStep (same as V2)
 \`\`\`
 {
-  order:          number  // 1-based integer
-  action:         string  // what the user/system does
-  expectedResult: string  // what should happen
+  order:          number
+  action:         string
+  expectedResult: string
 }
 \`\`\`
 
-### Referential integrity rules
+### V3 DAG rules
+- Every step must be reachable from at least one entryStepId
+- No cycles allowed (DAG = Directed Acyclic Graph)
+- Steps with \`action: "conditional"\` MUST have 2+ nextStepIds
+- Terminal steps have \`nextStepIds: []\`
+- Every edge in \`edges[]\` must reference valid step IDs in \`steps[]\`
+- Scenario \`path[]\` must trace a valid walk from an entry step to a terminal step
+
+### V3 Referential integrity
+- Every \`feature.sectionId\` must exist in \`sections[].id\`
+- Every \`section.featureIds[]\` must exist in \`features[].id\`
 - Every \`workflow.featureId\` must exist in \`features[].id\`
-- Every \`feature.workflowIds[]\` entry must exist in \`workflows[].id\`
-- Every \`workflow.componentIds[]\` entry must exist in \`components[].id\`
-- Every \`scenario.workflowId\` must exist in \`workflows[].id\`
-- Every \`scenario.featureId\` must exist in \`features[].id\`
-- Every \`scenario.componentIds[]\` entry must exist in \`components[].id\`
-- Every \`scenario.workflowStepIds[]\` entry must exist in a \`workflow.steps[].id\`
-- Every \`component.referencedByWorkflows[]\` entry must exist in \`workflows[].id\`
-- All ids must be unique within their entity type
+- Every \`scenario.workflowId\` and \`scenario.featureId\` must exist
+- All V2 referential integrity rules also apply
+
+---
+
+## QAMapV2Payload Schema Reference (legacy)
+
+V2 payloads do NOT include a schemaVersion field. Flat features, linear workflow steps.
+
+### Top-level
+\`\`\`
+{
+  features:   Feature[]
+  workflows:  Workflow[]
+  components: Component[]
+  scenarios:  Scenario[]
+  commitSha?: string
+  metadata?:  object
+}
+\`\`\`
+
+### V2 Feature: \`{ id, name, description, routes: string[], workflowIds: string[], sourceFiles: string[] }\`
+### V2 Workflow: \`{ id, name, featureId, type: "navigation"|"crud"|"multi-step"|"configuration"|"search-filter", preconditions: string[], steps: WorkflowStep[], componentIds: string[] }\`
+### V2 WorkflowStep: \`{ id, order: number, description, componentIds: string[], apiCalls: string[], conditionalBranches: ConditionalBranch[] }\`
+### V2 ConditionalBranch: \`{ condition, outcome, type: "validation"|"permission"|"error"|"business-logic" }\`
+### V2 Scenario: \`{ id, workflowId, featureId, name, description, category, preconditions: string[], steps: ScenarioStep[], expectedOutcome, componentIds: string[], workflowStepIds: string[], priority }\`
 `.trim();
-var server = new McpServer({ name: "zefiro", version: "0.3.2" }, { instructions: SERVER_INSTRUCTIONS });
+var server = new McpServer({ name: "zefiro", version: "0.4.0" }, { instructions: SERVER_INSTRUCTIONS });
 server.registerTool("zefiro_scan_codebase", {
   title: "Scan Codebase",
   description: "Scan a project directory for test files, configs, fixtures, path aliases, and sample test content.",
@@ -15378,7 +15253,7 @@ server.registerTool("zefiro_scan_ast_detail", {
   title: "Scan AST Detail",
   description: "Retrieve a filtered slice of the AST scan. Requires a prior zefiro_scan_ast call. " + "Use to drill into routes, components, hooks, dependencies, or files.",
   inputSchema: exports_external.object({
-    category: exports_external.enum(["routes", "components", "hooks", "dependencies", "files"]),
+    category: exports_external.enum(["routes", "components", "hooks", "dependencies", "files", "navigationPatterns"]),
     filter: exports_external.string().optional().describe("Glob pattern to filter results"),
     limit: exports_external.number().optional().describe("Max number of items to return")
   })
@@ -15397,15 +15272,16 @@ server.registerTool("zefiro_scan_ast_detail", {
 });
 server.registerTool("zefiro_build_qa_map", {
   title: "Build QA Map",
-  description: "Validate and optionally write a QAMapV2Payload. Use dryRun: true to validate without writing.",
+  description: "Validate and optionally write a QA map payload (V2 or V3, auto-detected by schemaVersion field). Use dryRun: true to validate without writing.",
   inputSchema: exports_external.object({
-    payload: exports_external.any().describe("QAMapV2Payload JSON object"),
+    payload: exports_external.any().describe("QAMapV2Payload or QAMapV3Payload JSON object. V3 must include schemaVersion: 3."),
     output: exports_external.string().optional().describe(`Output file path (defaults to ${CONFIG_DIR}/qa-map.json)`),
     dryRun: exports_external.boolean().optional().describe("Validate only, do not write (default: false)")
   })
 }, async ({ payload, output, dryRun }) => {
   try {
-    const validation = validateQAMap(payload);
+    const isV3 = payload && typeof payload === "object" && payload.schemaVersion === 3;
+    const validation = isV3 ? validateQAMapV3(payload) : validateQAMap(payload);
     if (validation.valid && payload && typeof payload === "object") {
       try {
         const sha = execSync("git rev-parse HEAD", { encoding: "utf-8" }).trim();
@@ -15423,6 +15299,7 @@ server.registerTool("zefiro_build_qa_map", {
     }
     const p = payload;
     const stats = validation.valid ? {
+      sections: isV3 && Array.isArray(p?.sections) ? p.sections.length : undefined,
       features: Array.isArray(p?.features) ? p.features.length : 0,
       workflows: Array.isArray(p?.workflows) ? p.workflows.length : 0,
       components: Array.isArray(p?.components) ? p.components.length : 0,
@@ -15431,7 +15308,7 @@ server.registerTool("zefiro_build_qa_map", {
     return {
       content: [{
         type: "text",
-        text: JSON.stringify({ valid: validation.valid, errors: validation.errors, warnings: validation.warnings, written, outputPath: written ? outputPath : null, stats }, null, 2)
+        text: JSON.stringify({ valid: validation.valid, schemaVersion: isV3 ? 3 : 2, errors: validation.errors, warnings: validation.warnings, written, outputPath: written ? outputPath : null, stats }, null, 2)
       }]
     };
   } catch (err) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zefiro",
-  "version": "0.3.7",
+  "version": "0.4.0",
   "type": "module",
   "bin": {
     "zefiro": "./dist/cli.js",
@@ -16,7 +16,10 @@
       "import": "./dist/index.js"
     }
   },
-  "files": ["dist/", "agents/"],
+  "files": [
+    "dist/",
+    "agents/"
+  ],
   "scripts": {
     "build": "bun build src/cli.ts src/index.ts src/mcp.ts --outdir dist --target node --format esm --splitting --packages=bundle --external react-devtools-core",
     "dev": "bun run src/cli.ts"