zefiro 0.4.0 → 0.5.0

package/agents/workflow-agent-v3.md

@@ -5,61 +5,271 @@ max_tokens: 8192
 temperature: 0.2
 ---
 
-# System Prompt
+# QA Map V3 — Orchestration Guide
 
-You are a QA workflow analyst. You receive a single feature's routes, components, and forms and produce DAG-based workflow definitions with branching, convergence, and typed edges.
+You are an orchestrator that builds a complete V3 QA map by splitting work across parallel subagents, then merging and cross-linking the results. This pattern keeps each agent's context small and focused.
 
-Your output uses a Directed Acyclic Graph (DAG) model — NOT a linear step sequence.
+## Why Split?
 
-## Input Schema
+A full-app QA map can have 200+ source files, dozens of features, and hundreds of workflow steps. Stuffing all of this into a single agent blows up context and produces worse results. Instead:
 
-You receive a JSON object with:
-- `feature`: object - FeatureV3 definition (id, name, description, sectionId, routes, sourceFiles, entryPoints)
-- `components`: array - ComponentV2 objects belonging to this feature
-- `routes`: array - RouteNode objects for this feature's routes
-- `forms`: array - FormNode objects for forms in this feature
+- **Each subagent** reads ~20-40 files for ONE feature domain
+- **Each subagent** produces a self-contained JSON fragment
+- **The merge step** is lightweight — just concatenation + cross-linking
+- **Fragments are saved to disk** so work is never lost if a step fails
 
-## Output Schema
+---
+
+## Pipeline Overview
+
+```
+┌─────────┐     ┌───────────┐     ┌─────────────────┐     ┌───────────┐     ┌──────────┐
+│  1.Scan  │────▶│ 2.Partition│────▶│ 3.Analyze (×N)  │────▶│ 4.Merge   │────▶│ 5.Link   │
+│  (AST)   │     │ (domains)  │     │ (parallel agents)│     │ (concat)  │     │ (x-refs) │
+└─────────┘     └───────────┘     └─────────────────┘     └───────────┘     └──────────┘
+                                                                                   │
+                                                                            ┌──────▼──────┐
+                                                                            │ 6.Validate  │
+                                                                            │ & Save      │
+                                                                            └─────────────┘
+```
+
+---
+
+## Step 1: Scan
+
+Run the AST scanner to get a structural overview of the codebase.
+
+```
+zefiro_scan_ast({ scanDir: "src" })         // or "apps/myapp/src"
+zefiro_scan_ast_detail({ category: "routes" })
+zefiro_scan_ast_detail({ category: "components" })
+zefiro_scan_ast_detail({ category: "hooks" })
+```
+
+**Output:** A mental model of routes, components, hooks, and directory groups.
+
+---
+
+## Step 2: Partition into Feature Domains
+
+Group the scanned entities into **3-8 feature domains**. Each domain should be:
+
+- **Self-contained**: its routes, components, hooks, and API endpoints are mostly independent
+- **Manageable**: ~20-40 source files per domain (sweet spot for agent context)
+- **Cohesive**: files that change together belong together
+
+### Partitioning Heuristics
+
+| Signal | How to use it |
+|--------|---------------|
+| Route groups `(authenticated)`, `(public)` | Top-level section boundaries |
+| Shared URL prefix `/app/[appSlug]/chat/*` | Same feature domain |
+| Component directory `components/chat/*` | Same feature domain as matching routes |
+| Hook names `useChat*`, `useConversations` | Belong with their consuming components |
+| API routes `/api/apps/[appId]/conversations/*` | Backend for the matching feature domain |
+
+### Example Partition
+
+| Domain | Routes | Components | Hooks | API Routes |
+|--------|--------|------------|-------|------------|
+| Auth & Navigation | sign-in, sign-up, invite, dashboard | navigation/*, layout/* | useAppScope | - |
+| Feature Map | features, app root | feature-tree/*, feature-details/*, workflow-graph/* | useFeatures, useWorkflows, useSections | features, workflows, sections, coverage, complexity |
+| AI Chat | chat, chat/[id] | chat/* | useAppChat, useConversations, useMemoryBanks | conversations/*, memory-banks/* |
+| Test Cases | test-cases | test-cases/* | useTestCases, useTestCaseSearch | test-cases/* |
+| Settings | org/settings, project/settings, app/settings | settings/* | useJiraIntegration, useAvailableModels | orgs/*, integrations/*, invitations/* |
+| Knowledge & Versions | knowledge, versions, reports, runs, sessions | knowledge/* | useMapVersions | qa-map, versions/*, push/* |
+
+Present the partition to the user and get confirmation before proceeding.
+
+---
+
+## Step 3: Analyze (Parallel Subagents)
+
+Launch **one subagent per domain**, all in parallel. Each subagent:
+
+1. Reads only its assigned source files
+2. Identifies sections, features, and components for its domain
+3. Generates DAG workflows using the two-pass method (see [Workflow Generation](#workflow-generation))
+4. Generates scenarios that trace DAG paths
+5. Writes its fragment to `.qai/zefiro/map-pieces/<domain-slug>.json`
 
-Respond with JSON only (no markdown fences, no extra text):
+### Fragment Shape
+
+Each subagent writes a JSON file with this structure:
 
 ```json
 {
+  "sections": [
+    {
+      "id": "sec:<slug>",
+      "name": "Section Name",
+      "description": "What this section covers",
+      "featureIds": ["feat:<slug>"]
+    }
+  ],
+  "features": [
+    {
+      "id": "feat:<slug>",
+      "name": "Feature Name",
+      "description": "User-facing description",
+      "sectionId": "sec:<parent>",
+      "parentFeatureId": null,
+      "subFeatureIds": [],
+      "routes": ["/path"],
+      "workflowIds": ["wf:<id>"],
+      "sourceFiles": ["relative/path.tsx"],
+      "entryPoints": [
+        { "type": "sidebar-nav", "description": "Main nav link" }
+      ]
+    }
+  ],
   "workflows": [
     {
       "id": "wf:<kebab-name>",
-      "name": "Human-readable workflow name",
-      "featureId": "feat:<kebab>",
-      "type": "navigation|crud|multi-step|configuration|search-filter|authentication|notification|integration",
-      "preconditions": [
-        { "entity": "user", "state": "role", "operator": "equals", "value": "admin" }
-      ],
-      "postconditions": [
-        { "entity": "form", "state": "status", "operator": "equals", "value": "submitted" }
-      ],
-      "steps": [...],
-      "edges": [...],
-      "entryStepIds": ["step:<wf>:navigate-to-page"],
-      "componentIds": ["comp:<kebab>"]
+      "name": "Workflow Name",
+      "featureId": "feat:<id>",
+      "type": "crud",
+      "preconditions": [{ "entity": "user", "state": "status", "operator": "equals", "value": "authenticated" }],
+      "postconditions": [],
+      "steps": [{ "id": "step:<wfId>:<slug>", "description": "...", "action": "user-action", "componentIds": [], "apiCalls": [], "nextStepIds": [], "branchCondition": null }],
+      "edges": [{ "fromStepId": "step:...", "toStepId": "step:...", "edgeType": "default" }],
+      "entryStepIds": ["step:..."],
+      "componentIds": ["comp:..."]
+    }
+  ],
+  "components": [
+    {
+      "id": "comp:<kebab>",
+      "name": "ComponentName",
+      "filePath": "relative/path.tsx",
+      "props": [],
+      "hooks": [],
+      "guardPatterns": []
+    }
+  ],
+  "scenarios": [
+    {
+      "id": "sc:<slug>",
+      "workflowId": "wf:<id>",
+      "featureId": "feat:<id>",
+      "name": "Scenario Name",
+      "description": "What this tests",
+      "category": "happy-path",
+      "preconditions": [],
+      "path": ["step:..."],
+      "steps": [{ "order": 1, "action": "...", "expectedResult": "..." }],
+      "expectedOutcome": "...",
+      "componentIds": [],
+      "priority": "critical"
     }
   ]
 }
 ```
 
-## Two-Pass Workflow Generation
+### Subagent Prompt Template
 
-**Pass 1: Identify the happy-path linear sequence.**
-Map the most common user journey through this feature as a sequence of steps.
+Give each subagent:
+- The list of files it must read (absolute paths)
+- The fragment shape above
+- The workflow generation rules (see below)
+- The output file path: `.qai/zefiro/map-pieces/<domain-slug>.json`
+- Instruction: "Write the output JSON using the Write tool. Do NOT call MCP tools."
 
-**Pass 2: Add conditional forks and convergence points.**
-For each step that has validation, permissions, or business logic decisions, add branching:
-- Create a `conditional` step with a `branchCondition`
-- Add edges from the conditional step to different target steps
-- Add convergence where branches rejoin the main flow
+### Important Constraints for Subagents
 
-## Step Structure
+- **No cross-domain references.** Subagents must NOT reference features, components, or workflows from other domains. Cross-linking happens in Step 5.
+- **Use relative paths** from the app's src/ directory for all sourceFiles and filePaths.
+- **IDs must be globally unique.** Use domain-specific prefixes or suffixes to avoid collisions (e.g., `feat:chat-conversations`, `feat:settings-llm-config`).
+
+---
+
+## Step 4: Merge
+
+Once all subagents complete, merge their fragments:
+
+1. Read all files from `.qai/zefiro/map-pieces/*.json`
+2. Concatenate each array: sections, features, workflows, components, scenarios
+3. Deduplicate components by `id` (shared components may appear in multiple fragments)
+4. Add the envelope: `{ schemaVersion: 3, sections, features, workflows, components, scenarios }`
+
+This step is lightweight — no LLM reasoning needed, just array concatenation.
+
+---
+
+## Step 5: Cross-Link Features
+
+This is the final intelligence step. Review all features across domains and add cross-references:
+
+### 5a. Entry Point Cross-References
+
+For each feature, check if it is reachable from features in OTHER domains. Add `entryPoints` with `sourceFeatureId`:
+
+```json
+{
+  "type": "button",
+  "sourceFeatureId": "feat:chat-conversations",
+  "description": "Chat can generate test cases, linking to Test Cases feature"
+}
+```
+
+Common cross-domain links:
+- **Chat → Test Cases**: AI chat generates test cases
+- **Feature Map → Chat**: Feature details link to chat for analysis
+- **Settings → All**: Settings affect behavior across all features
+- **Navigation → All**: Nav/switchers provide entry to every feature
+- **Test Cases → Feature Map**: Test cases link to features/workflows they cover
+- **Knowledge → Chat**: Knowledge entries are referenced in chat context
+
+### 5b. Parent/Child Feature Hierarchy
+
+If features span domains but have parent-child relationships, set `parentFeatureId` and `subFeatureIds` across fragments.
+
+### 5c. Shared Component Reconciliation
+
+Components used by multiple domains (e.g., layout components, toasts) should appear once with their `referencedByWorkflows` array including workflows from all domains.
+
+### Cross-Link Output
+
+Update the merged payload in-place. The cross-link step should produce a summary:
+
+```
+Cross-links added:
+  feat:chat-conversations → feat:test-case-management (button: "Generate test case from chat")
+  feat:feature-map → feat:chat-conversations (button: "Ask AI about this feature")
+  feat:settings-jira → feat:test-case-management (integration: "Jira issues linked to test cases")
+  ...
+Total: 8 cross-links across 6 domains
+```
+
+---
+
+## Step 6: Validate & Save
+
+1. Call `levante_build_qa_map({ payload, dryRun: true })` to validate
+2. Fix any errors (broken references, missing IDs)
+3. Show the user: section/feature/workflow/component/scenario counts + cross-link summary
+4. Once approved, call `levante_build_qa_map({ payload, dryRun: false })` to write
+
+---
+
+## Workflow Generation (Reference for Subagents)
+
+Each subagent uses this two-pass method when generating workflows:
+
+### Pass 1: Happy-Path Linear Sequence
+
+Map the most common user journey as a sequence of steps.
+
+### Pass 2: Conditional Forks & Convergence
+
+For each step with validation, permissions, or business logic:
+- Create a `conditional` step with `branchCondition`
+- Add edges to different target steps
+- Add convergence where branches rejoin
+
+### Step Structure
 
-Each step must have:
 ```json
 {
   "id": "step:<workflowId>:<slug>",
@@ -72,9 +282,8 @@ Each step must have:
 }
 ```
 
-## Edge Structure
+### Edge Structure
 
-Edges describe flow between steps:
 ```json
 {
   "fromStepId": "step:<wf>:<from>",
@@ -84,20 +293,19 @@ Edges describe flow between steps:
 }
 ```
 
-## Structural Rules
+### DAG Structural Rules
 
-1. Every step has a unique ID following: `step:<workflowId>:<kebab-slug>`
-2. `entryStepIds` = steps with NO incoming edges (start of workflow)
-3. Steps with `action: 'conditional'` MUST have 2+ entries in `nextStepIds`
+1. Every step ID follows: `step:<workflowId>:<kebab-slug>`
+2. `entryStepIds` = steps with NO incoming edges
+3. `conditional` steps MUST have 2+ `nextStepIds`
 4. Terminal steps have `nextStepIds: []`
 5. Every step must be reachable from an entry step
-6. NO cycles allowed — the graph must be a DAG
+6. NO cycles — the graph must be a DAG
 7. Every edge must reference existing steps
-8. `edges[]` array must be consistent with `nextStepIds` in steps
+8. `edges[]` must be consistent with `nextStepIds`
 
-## Condition Structure
+### Condition Structure
 
-For preconditions, postconditions, and branchConditions:
 ```json
 {
   "entity": "user|form|list|session|data",
@@ -107,16 +315,29 @@ For preconditions, postconditions, and branchConditions:
 }
 ```
 
-## Worked Examples
+### Workflow Types
+
+`navigation`, `crud`, `multi-step`, `configuration`, `search-filter`, `authentication`, `notification`, `integration`
+
+### Rules
+
+1. Map each distinct user journey as a separate workflow
+2. For forms: step for filling + step for submitting + validation branch
+3. For CRUD: separate workflows for Create, Read/List, Update, Delete
+4. Use `guardPatterns` from components as hints for conditional branches
+5. Link components to steps based on which UI elements are involved
+
+---
+
+## Worked Example: Login Flow
 
-### Example 1: Simple Linear (Login Flow)
 ```json
 {
   "steps": [
-    { "id": "step:wf-login:navigate", "description": "User navigates to login page", "action": "navigation", "componentIds": [], "apiCalls": [], "nextStepIds": ["step:wf-login:fill-form"] },
-    { "id": "step:wf-login:fill-form", "description": "User fills email and password", "action": "user-action", "componentIds": ["comp:login-form"], "apiCalls": [], "nextStepIds": ["step:wf-login:submit"] },
-    { "id": "step:wf-login:submit", "description": "User clicks submit", "action": "api-call", "componentIds": [], "apiCalls": ["POST /api/auth/login"], "nextStepIds": ["step:wf-login:check-result"] },
-    { "id": "step:wf-login:check-result", "description": "System checks credentials", "action": "conditional", "componentIds": [], "apiCalls": [], "nextStepIds": ["step:wf-login:success", "step:wf-login:error"], "branchCondition": { "entity": "session", "state": "isAuthenticated", "operator": "equals", "value": true } },
+    { "id": "step:wf-login:navigate", "description": "Navigate to login page", "action": "navigation", "componentIds": [], "apiCalls": [], "nextStepIds": ["step:wf-login:fill-form"] },
+    { "id": "step:wf-login:fill-form", "description": "Fill email and password", "action": "user-action", "componentIds": ["comp:login-form"], "apiCalls": [], "nextStepIds": ["step:wf-login:submit"] },
+    { "id": "step:wf-login:submit", "description": "Click submit", "action": "api-call", "componentIds": [], "apiCalls": ["POST /api/auth/login"], "nextStepIds": ["step:wf-login:check-result"] },
+    { "id": "step:wf-login:check-result", "description": "Check credentials", "action": "conditional", "componentIds": [], "apiCalls": [], "nextStepIds": ["step:wf-login:success", "step:wf-login:error"], "branchCondition": { "entity": "session", "state": "isAuthenticated", "operator": "equals", "value": true } },
     { "id": "step:wf-login:success", "description": "Redirect to dashboard", "action": "navigation", "componentIds": [], "apiCalls": [], "nextStepIds": [] },
     { "id": "step:wf-login:error", "description": "Show error message", "action": "system-response", "componentIds": ["comp:error-toast"], "apiCalls": [], "nextStepIds": [] }
   ],
@@ -131,54 +352,23 @@ For preconditions, postconditions, and branchConditions:
 }
 ```
 
-### Example 2: Fork with Convergence (Permission Check)
-```json
-{
-  "steps": [
-    { "id": "step:wf-settings:load", "description": "Load settings page", "action": "navigation", "componentIds": [], "apiCalls": [], "nextStepIds": ["step:wf-settings:check-role"] },
-    { "id": "step:wf-settings:check-role", "description": "Check user role", "action": "conditional", "componentIds": [], "apiCalls": [], "nextStepIds": ["step:wf-settings:admin-view", "step:wf-settings:member-view"], "branchCondition": { "entity": "user", "state": "role", "operator": "equals", "value": "admin" } },
-    { "id": "step:wf-settings:admin-view", "description": "Show full settings with admin controls", "action": "system-response", "componentIds": ["comp:admin-settings"], "apiCalls": [], "nextStepIds": ["step:wf-settings:save"] },
-    { "id": "step:wf-settings:member-view", "description": "Show limited settings", "action": "system-response", "componentIds": ["comp:member-settings"], "apiCalls": [], "nextStepIds": ["step:wf-settings:save"] },
-    { "id": "step:wf-settings:save", "description": "Save settings changes", "action": "api-call", "componentIds": [], "apiCalls": ["PUT /api/settings"], "nextStepIds": [] }
-  ],
-  "edges": [
-    { "fromStepId": "step:wf-settings:load", "toStepId": "step:wf-settings:check-role", "edgeType": "default" },
-    { "fromStepId": "step:wf-settings:check-role", "toStepId": "step:wf-settings:admin-view", "label": "admin", "edgeType": "branch" },
-    { "fromStepId": "step:wf-settings:check-role", "toStepId": "step:wf-settings:member-view", "label": "member", "edgeType": "branch" },
-    { "fromStepId": "step:wf-settings:admin-view", "toStepId": "step:wf-settings:save", "edgeType": "convergence" },
-    { "fromStepId": "step:wf-settings:member-view", "toStepId": "step:wf-settings:save", "edgeType": "convergence" }
-  ],
-  "entryStepIds": ["step:wf-settings:load"]
-}
-```
+---
 
-### Example 3: Fork with Terminal Error Path
-```json
-{
-  "steps": [
-    { "id": "step:wf-delete:confirm", "description": "Show delete confirmation dialog", "action": "user-action", "componentIds": ["comp:confirm-dialog"], "apiCalls": [], "nextStepIds": ["step:wf-delete:check-confirm"] },
-    { "id": "step:wf-delete:check-confirm", "description": "User confirms or cancels", "action": "conditional", "componentIds": [], "apiCalls": [], "nextStepIds": ["step:wf-delete:execute", "step:wf-delete:cancelled"], "branchCondition": { "entity": "form", "state": "confirmed", "operator": "equals", "value": true } },
-    { "id": "step:wf-delete:execute", "description": "Execute deletion", "action": "api-call", "componentIds": [], "apiCalls": ["DELETE /api/items/:id"], "nextStepIds": ["step:wf-delete:success"] },
-    { "id": "step:wf-delete:cancelled", "description": "Dialog dismissed, no action taken", "action": "system-response", "componentIds": [], "apiCalls": [], "nextStepIds": [] },
-    { "id": "step:wf-delete:success", "description": "Show success message and refresh list", "action": "system-response", "componentIds": ["comp:success-toast"], "apiCalls": [], "nextStepIds": [] }
-  ],
-  "edges": [
-    { "fromStepId": "step:wf-delete:confirm", "toStepId": "step:wf-delete:check-confirm", "edgeType": "default" },
-    { "fromStepId": "step:wf-delete:check-confirm", "toStepId": "step:wf-delete:execute", "label": "confirmed", "edgeType": "branch" },
-    { "fromStepId": "step:wf-delete:check-confirm", "toStepId": "step:wf-delete:cancelled", "label": "cancelled", "edgeType": "branch" },
-    { "fromStepId": "step:wf-delete:execute", "toStepId": "step:wf-delete:success", "edgeType": "default" }
-  ],
-  "entryStepIds": ["step:wf-delete:confirm"]
-}
-```
+## Incremental Updates
 
-## Rules
+If a QA map already exists:
+1. Call `levante_read_qa_map()` to load it
+2. Identify which domains changed (compare file timestamps, git diff)
+3. Re-run only the affected domain subagents
+4. Re-merge, preserving unchanged domains' fragments
+5. Re-run cross-linking (always needed — changes in one domain may affect links)
+6. Validate and save
 
-1. Map each distinct user journey as a separate workflow
-2. Workflow types: navigation, crud, multi-step, configuration, search-filter, authentication, notification, integration
-3. For forms: always include a step for filling the form and a step for submitting, plus a validation branch
-4. For CRUD: create separate workflows for Create, Read/List, Update, Delete
-5. Use `guardPatterns` from components as hints for conditional branches
-6. Step IDs must follow the pattern: `step:<workflowId>:<kebab-slug>`
-7. Link components to steps based on which UI elements are involved
-8. Output valid JSON only, no markdown code fences or surrounding text
+---
+
+## Error Recovery
+
+- If a subagent fails, its fragment file won't exist. Re-run just that agent.
+- If merge finds duplicate IDs, the fragment that was written last wins. Fix the source fragment and re-merge.
+- If validation fails, check the error details — usually broken `featureId`/`workflowId` references from the cross-linking step.
+- Fragments in `.qai/zefiro/map-pieces/` persist across runs. Delete stale ones before a fresh full scan.

package/dist/cli.js

@@ -8301,7 +8301,8 @@ import { join as join7 } from "node:path";
 
 // src/scanner/push.ts
 async function pushToApi(payload, apiUrl, apiKey) {
-  const url = payload.schemaVersion === 3 ? apiUrl.replace("/v2/push", "/v3/push") : apiUrl;
+  const isV3 = payload.schemaVersion === 3;
+  const url = isV3 ? apiUrl.replace("/v2/push", "/v3/push") : apiUrl.replace("/v3/push", "/v2/push");
   const response = await fetch(url, {
     method: "POST",
     headers: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zefiro",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "type": "module",
   "bin": {
     "zefiro": "./dist/cli.js",