@agile-vibe-coding/avc 0.1.1 → 0.3.1

package/cli/checks/story/ui.json

@@ -0,0 +1,102 @@
+{
+  "perspective": "ui",
+  "scope": "story",
+  "checks": [
+    {
+      "id": "ui-story-01",
+      "tier": 1,
+      "perspective": "ui",
+      "severity": "critical",
+      "category": "acceptance-criteria",
+      "universal": false,
+      "applicabilityQuestion": "Does this story involve UI components, visual design, or design system elements? (Does it include component specs, styling, or visual layout?)",
+      "question": "Is each acceptance criterion testable and measurable?",
+      "failDescription": "One or more acceptance criteria are not testable or measurable",
+      "failSuggestion": "Make each AC testable: specify exact visual outcomes, component states, or measurable UI properties"
+    },
+    {
+      "id": "ui-story-02",
+      "tier": 1,
+      "perspective": "ui",
+      "severity": "major",
+      "category": "acceptance-criteria",
+      "universal": false,
+      "applicabilityQuestion": "Does this story involve UI components, visual design, or design system elements?",
+      "question": "Do criteria cover happy path, edge cases, and error scenarios?",
+      "failDescription": "Criteria do not cover UI edge cases or error states",
+      "failSuggestion": "Add UI edge cases: overflow text, empty states, loading skeletons, error displays, responsive breakpoints"
+    },
+    {
+      "id": "ui-story-03",
+      "tier": 1,
+      "perspective": "ui",
+      "severity": "major",
+      "category": "acceptance-criteria",
+      "universal": false,
+      "applicabilityQuestion": "Does this story involve UI components, visual design, or design system elements?",
+      "question": "Are UI requirements explicitly stated?",
+      "failDescription": "UI requirements are not explicitly stated",
+      "failSuggestion": "State UI requirements: component variants, colors, spacing, typography, responsive behavior"
+    },
+    {
+      "id": "ui-story-04",
+      "tier": 1,
+      "perspective": "ui",
+      "severity": "major",
+      "category": "implementation-clarity",
+      "universal": false,
+      "applicabilityQuestion": "Does this story involve UI components, visual design, or design system elements?",
+      "question": "Does the story provide enough UI detail for implementation?",
+      "failDescription": "Insufficient UI detail for implementation",
+      "failSuggestion": "Add UI details: component dimensions, color values, spacing units, font sizes, animation timing"
+    },
+    {
+      "id": "ui-story-05",
+      "tier": 1,
+      "perspective": "ui",
+      "severity": "minor",
+      "category": "implementation-clarity",
+      "universal": false,
+      "applicabilityQuestion": "Does this story involve UI components, visual design, or design system elements?",
+      "question": "Are UI patterns and approaches specified?",
+      "failDescription": "UI patterns and approaches are not specified",
+      "failSuggestion": "Specify UI patterns: component composition, design token usage, responsive strategy, theme support"
+    },
+    {
+      "id": "ui-story-06",
+      "tier": 1,
+      "perspective": "ui",
+      "severity": "major",
+      "category": "testability",
+      "universal": false,
+      "applicabilityQuestion": "Does this story involve UI components, visual design, or design system elements?",
+      "question": "Does the story have a test-boundary AC naming specific scenarios a developer must test?",
+      "failDescription": "Story lacks a test-boundary AC",
+      "failSuggestion": "Add test-boundary AC: 'Tests must cover: (1) default state, (2) hover/focus, (3) error state, (4) responsive, (5) accessibility'"
+    },
+    {
+      "id": "ui-story-07",
+      "tier": 1,
+      "perspective": "ui",
+      "severity": "minor",
+      "category": "scope-dependencies",
+      "universal": false,
+      "applicabilityQuestion": "Does this story involve UI components, visual design, or design system elements?",
+      "question": "Are dependencies on other stories explicit?",
+      "failDescription": "Dependencies on other stories are not explicit",
+      "failSuggestion": "Make dependencies explicit: reference design system stories, component library dependencies"
+    },
+    {
+      "id": "ui-story-08",
+      "tier": 1,
+      "perspective": "ui",
+      "severity": "minor",
+      "category": "best-practices",
+      "universal": false,
+      "applicabilityQuestion": "Does this story involve UI components, visual design, or design system elements?",
+      "question": "Does the story follow UI best practices?",
+      "failDescription": "UI best practices are not followed",
+      "failSuggestion": "Follow UI best practices: consistent design tokens, accessibility contrast ratios, responsive design, visual hierarchy"
+    }
+  ]
+}

package/cli/checks/story/ux.json

@@ -0,0 +1,102 @@
+{
+  "perspective": "ux",
+  "scope": "story",
+  "checks": [
+    {
+      "id": "ux-story-01",
+      "tier": 1,
+      "perspective": "ux",
+      "severity": "critical",
+      "category": "acceptance-criteria",
+      "universal": false,
+      "applicabilityQuestion": "Does this story involve user experience, user flows, or interaction design? (Does it define user journeys, navigation, or usability requirements?)",
+      "question": "Is each acceptance criterion testable and measurable?",
+      "failDescription": "One or more acceptance criteria are not testable or measurable",
+      "failSuggestion": "Make each AC testable: specify user actions, expected outcomes, and measurable UX metrics"
+    },
+    {
+      "id": "ux-story-02",
+      "tier": 1,
+      "perspective": "ux",
+      "severity": "major",
+      "category": "acceptance-criteria",
+      "universal": false,
+      "applicabilityQuestion": "Does this story involve user experience, user flows, or interaction design?",
+      "question": "Do criteria cover happy path, edge cases, and error scenarios?",
+      "failDescription": "Criteria do not cover UX edge cases or error scenarios",
+      "failSuggestion": "Add UX edge cases: empty states, error recovery flows, timeout handling, progressive disclosure"
+    },
+    {
+      "id": "ux-story-03",
+      "tier": 1,
+      "perspective": "ux",
+      "severity": "major",
+      "category": "acceptance-criteria",
+      "universal": false,
+      "applicabilityQuestion": "Does this story involve user experience, user flows, or interaction design?",
+      "question": "Are UX requirements explicitly stated?",
+      "failDescription": "UX requirements are not explicitly stated",
+      "failSuggestion": "State UX requirements: user flow steps, interaction patterns, feedback mechanisms, accessibility needs"
+    },
+    {
+      "id": "ux-story-04",
+      "tier": 1,
+      "perspective": "ux",
+      "severity": "major",
+      "category": "implementation-clarity",
+      "universal": false,
+      "applicabilityQuestion": "Does this story involve user experience, user flows, or interaction design?",
+      "question": "Does the story provide enough UX detail for implementation?",
+      "failDescription": "Insufficient UX detail for implementation",
+      "failSuggestion": "Add UX details: user flow diagrams, interaction states, feedback timing, animation expectations"
+    },
+    {
+      "id": "ux-story-05",
+      "tier": 1,
+      "perspective": "ux",
+      "severity": "minor",
+      "category": "implementation-clarity",
+      "universal": false,
+      "applicabilityQuestion": "Does this story involve user experience, user flows, or interaction design?",
+      "question": "Are UX patterns and approaches specified?",
+      "failDescription": "UX patterns and approaches are not specified",
+      "failSuggestion": "Specify UX patterns: progressive disclosure, inline validation, optimistic feedback, error recovery"
+    },
+    {
+      "id": "ux-story-06",
+      "tier": 1,
+      "perspective": "ux",
+      "severity": "major",
+      "category": "testability",
+      "universal": false,
+      "applicabilityQuestion": "Does this story involve user experience, user flows, or interaction design?",
+      "question": "Does the story have a test-boundary AC naming specific scenarios a developer must test?",
+      "failDescription": "Story lacks a test-boundary AC",
+      "failSuggestion": "Add test-boundary AC: 'Tests must cover: (1) happy flow, (2) error recovery, (3) empty state, (4) loading state, (5) accessibility'"
+    },
+    {
+      "id": "ux-story-07",
+      "tier": 1,
+      "perspective": "ux",
+      "severity": "minor",
+      "category": "scope-dependencies",
+      "universal": false,
+      "applicabilityQuestion": "Does this story involve user experience, user flows, or interaction design?",
+      "question": "Are dependencies on other stories explicit?",
+      "failDescription": "Dependencies on other stories are not explicit",
+      "failSuggestion": "Make dependencies explicit: reference related user flow stories and shared UX patterns"
+    },
+    {
+      "id": "ux-story-08",
+      "tier": 1,
+      "perspective": "ux",
+      "severity": "minor",
+      "category": "best-practices",
+      "universal": false,
+      "applicabilityQuestion": "Does this story involve user experience, user flows, or interaction design?",
+      "question": "Does the story follow UX best practices?",
+      "failDescription": "UX best practices are not followed",
+      "failSuggestion": "Follow UX best practices: minimize cognitive load, provide clear feedback, support undo, maintain consistency"
+    }
+  ]
+}

package/cli/coding-order.js

@@ -0,0 +1,401 @@
+/**
+ * coding-order.js — Computes implementation ordering from epic/story dependency graphs.
+ *
+ * Pure functions: no side effects, no file I/O.  All I/O is done by the caller
+ * (SprintPlanningProcessor.generateCodingOrder).
+ */
+
+/**
+ * Build adjacency maps from hierarchy dependencies.
+ * @param {{ epics: Array }} hierarchy
+ * @returns {{ epicGraph: Map<string,Set<string>>, storyGraphs: Map<string,Map<string,Set<string>>>, allNodes: Map<string,{id,name,type,parentId?}> }}
+ */
+export function buildDependencyGraph(hierarchy) {
+  const epicGraph = new Map();   // epicId → Set<epicId it depends on>
+  const storyGraphs = new Map(); // epicId → Map<storyId, Set<storyId>>
+  const allNodes = new Map();    // id → { id, name, type, parentId? }
+
+  for (const epic of hierarchy.epics || []) {
+    const epicId = epic.id;
+    allNodes.set(epicId, { id: epicId, name: epic.name, type: 'epic' });
+
+    // Epic-level deps: only keep references that look like epic IDs (context-XXXX)
+    const epicDeps = new Set();
+    for (const dep of epic.dependencies || []) {
+      if (/^context-\d{4}$/.test(dep) && dep !== epicId) {
+        epicDeps.add(dep);
+      }
+    }
+    epicGraph.set(epicId, epicDeps);
+
+    // Story-level: intra-epic deps only
+    const storyMap = new Map();
+    const epicStoryIds = new Set((epic.stories || []).map(s => s.id));
+
+    for (const story of epic.stories || []) {
+      allNodes.set(story.id, { id: story.id, name: story.name, type: 'story', parentId: epicId });
+      const storyDeps = new Set();
+      for (const dep of story.dependencies || []) {
+        if (epicStoryIds.has(dep) && dep !== story.id) {
+          storyDeps.add(dep); // intra-epic story dependency
+        }
+        // Cross-epic story deps → promote to epic dependency
+        if (/^context-\d{4}$/.test(dep) && dep !== epicId) {
+          epicDeps.add(dep);
+        }
+      }
+      storyMap.set(story.id, storyDeps);
+    }
+
+    storyGraphs.set(epicId, storyMap);
+  }
+
+  return { epicGraph, storyGraphs, allNodes };
+}
+
+/**
+ * Kahn's algorithm — topological sort with cycle detection.
+ * @param {Map<string,Set<string>>} graph — nodeId → Set<dependency nodeIds>
+ * @returns {{ sorted: string[], hasCycle: boolean, cycleNodes: string[] }}
+ */
+export function topologicalSort(graph) {
+  const inDegree = new Map();
+  const adjList = new Map(); // forward edges: dep → [dependents]
+
+  for (const [node] of graph) {
+    if (!inDegree.has(node)) inDegree.set(node, 0);
+    if (!adjList.has(node)) adjList.set(node, []);
+  }
+
+  for (const [node, deps] of graph) {
+    for (const dep of deps) {
+      if (!graph.has(dep)) continue; // skip refs to non-existent nodes
+      if (!adjList.has(dep)) adjList.set(dep, []);
+      adjList.get(dep).push(node);
+      inDegree.set(node, (inDegree.get(node) || 0) + 1);
+    }
+  }
+
+  const queue = [];
+  for (const [node, deg] of inDegree) {
+    if (deg === 0) queue.push(node);
+  }
+  queue.sort(); // deterministic ordering for ties
+
+  const sorted = [];
+  while (queue.length > 0) {
+    const node = queue.shift();
+    sorted.push(node);
+    for (const dependent of adjList.get(node) || []) {
+      const newDeg = inDegree.get(dependent) - 1;
+      inDegree.set(dependent, newDeg);
+      if (newDeg === 0) {
+        queue.push(dependent);
+        queue.sort();
+      }
+    }
+  }
+
+  const hasCycle = sorted.length < graph.size;
+  const cycleNodes = hasCycle
+    ? [...graph.keys()].filter(n => !sorted.includes(n))
+    : [];
+
+  // If cycle, append remaining nodes in ID order to still produce output
+  if (hasCycle) {
+    for (const node of cycleNodes.sort()) {
+      sorted.push(node);
+    }
+  }
+
+  return { sorted, hasCycle, cycleNodes };
+}
+
+/**
+ * Group epics into implementation phases by longest-path distance from root nodes.
+ * Phase 0 = no dependencies, Phase N = longest dep chain is N.
+ * @param {Map<string,Set<string>>} epicGraph
+ * @returns {Array<{ phase: number, epicIds: string[] }>}
+ */
+export function computePhases(epicGraph) {
+  const depth = new Map();
+
+  function getDepth(node, visited = new Set()) {
+    if (depth.has(node)) return depth.get(node);
+    if (visited.has(node)) return 0; // cycle guard
+    visited.add(node);
+
+    const deps = epicGraph.get(node) || new Set();
+    let maxDepth = 0;
+    for (const dep of deps) {
+      if (epicGraph.has(dep)) {
+        maxDepth = Math.max(maxDepth, getDepth(dep, visited) + 1);
+      }
+    }
+    depth.set(node, maxDepth);
+    return maxDepth;
+  }
+
+  for (const [node] of epicGraph) getDepth(node);
+
+  // Group by phase
+  const phaseMap = new Map();
+  for (const [node, d] of depth) {
+    if (!phaseMap.has(d)) phaseMap.set(d, []);
+    phaseMap.get(d).push(node);
+  }
+
+  return [...phaseMap.entries()]
+    .sort((a, b) => a[0] - b[0])
+    .map(([phase, epicIds]) => ({ phase, epicIds: epicIds.sort() }));
+}
+
+/**
+ * Find the longest path through the epic dependency graph (critical path).
+ * @param {Map<string,Set<string>>} epicGraph
+ * @returns {{ path: string[], length: number }}
+ */
+export function computeCriticalPath(epicGraph) {
+  const memo = new Map();
+
+  function longestFrom(node, visited = new Set()) {
+    if (memo.has(node)) return memo.get(node);
+    if (visited.has(node)) return [node]; // cycle guard
+    visited.add(node);
+
+    // Find all nodes that depend on this one
+    const dependents = [];
+    for (const [n, deps] of epicGraph) {
+      if (deps.has(node)) dependents.push(n);
+    }
+
+    let best = [node];
+    for (const dep of dependents) {
+      const sub = longestFrom(dep, new Set(visited));
+      if (sub.length + 1 > best.length) {
+        best = [node, ...sub];
+      }
+    }
+    memo.set(node, best);
+    return best;
+  }
+
+  // Find roots (nodes with no dependencies)
+  const roots = [];
+  for (const [node, deps] of epicGraph) {
+    if (deps.size === 0) roots.push(node);
+  }
+
+  let criticalPath = [];
+  for (const root of roots) {
+    const path = longestFrom(root);
+    if (path.length > criticalPath.length) criticalPath = path;
+  }
+
+  return { path: criticalPath, length: criticalPath.length };
+}
+
+/**
+ * Topologically sort stories within a single epic.
+ * @param {Map<string,Set<string>>} storyGraph — storyId → Set<intra-epic dep storyIds>
+ * @returns {string[]}
+ */
+export function orderStoriesWithinEpic(storyGraph) {
+  return topologicalSort(storyGraph).sorted;
+}
+
+/**
+ * Render the coding order as a Markdown document.
+ */
+export function generateCodingOrderMd(phases, storyOrders, allNodes, criticalPath) {
+  const lines = [
+    '# Coding Order',
+    '',
+    `Generated: ${new Date().toISOString()}`,
+    '',
+  ];
+
+  // Mermaid dependency graph
+  lines.push('## Dependency Graph', '', '```mermaid', 'graph LR');
+  for (const [id, node] of allNodes) {
+    if (node.type === 'epic') {
+      const label = node.name.replace(/"/g, "'");
+      lines.push(`  ${id}["${label}"]`);
+    }
+  }
+  // Edges: for each epic, draw edges FROM its dependencies TO it
+  for (const phase of phases) {
+    for (const epicId of phase.epicIds) {
+      // Find this epic's node in allNodes and look up its deps
+      // We need the original graph — reconstruct from phases
+    }
+  }
+  // Use phases to reconstruct edges from allNodes
+  // Actually we need epicGraph — let's take it as parameter
+  lines.push('```', '');
+
+  // Critical path
+  lines.push('## Critical Path', '');
+  if (criticalPath.path.length > 0) {
+    const pathStr = criticalPath.path
+      .map(id => { const n = allNodes.get(id); return n ? `${id} (${n.name})` : id; })
+      .join(' → ');
+    lines.push(pathStr);
+    lines.push(``, `Length: ${criticalPath.length} epics`, '');
+  } else {
+    lines.push('No dependencies — all epics are independent.', '');
+  }
+
+  // Implementation phases
+  lines.push('## Implementation Phases', '');
+  for (const phase of phases) {
+    const parallel = phase.epicIds.length > 1 ? ' (parallel)' : '';
+    const depNote = phase.phase === 0 ? ' — no dependencies' : ` — depends on Phase ${phase.phase}`;
+    lines.push(`### Phase ${phase.phase + 1}${parallel}${depNote}`, '');
+
+    for (const epicId of phase.epicIds) {
+      const epic = allNodes.get(epicId);
+      const epicName = epic ? epic.name : epicId;
+      lines.push(`#### ${epicId}: ${epicName}`, '');
+
+      const stories = storyOrders.get(epicId) || [];
+      if (stories.length > 0) {
+        lines.push('| # | Story | ID |', '|---|-------|-----|');
+        stories.forEach((storyId, idx) => {
+          const story = allNodes.get(storyId);
+          const storyName = story ? story.name : storyId;
+          lines.push(`| ${idx + 1} | ${storyName} | ${storyId} |`);
+        });
+        lines.push('');
+      }
+    }
+  }
+
+  return lines.join('\n');
+}
+
+/**
+ * Render the coding order as structured JSON for the kanban API.
+ */
+export function generateCodingOrderJson(phases, storyOrders, allNodes, criticalPath) {
+  return {
+    generatedAt: new Date().toISOString(),
+    criticalPath: {
+      epicIds: criticalPath.path,
+      length: criticalPath.length,
+      epics: criticalPath.path.map(id => {
+        const n = allNodes.get(id);
+        return { id, name: n?.name || id };
+      }),
+    },
+    phases: phases.map(phase => ({
+      phase: phase.phase + 1,
+      parallel: phase.epicIds.length > 1,
+      epics: phase.epicIds.map(epicId => {
+        const epic = allNodes.get(epicId);
+        const stories = (storyOrders.get(epicId) || []).map((storyId, idx) => {
+          const story = allNodes.get(storyId);
+          return { order: idx + 1, id: storyId, name: story?.name || storyId };
+        });
+        return { id: epicId, name: epic?.name || epicId, stories };
+      }),
+    })),
+  };
+}
+
+/**
+ * Main entry point — compute everything from a hierarchy.
+ * @param {{ epics: Array }} hierarchy
+ * @returns {{ md: string, json: object, phases: Array, criticalPath: object }}
+ */
+export function computeCodingOrder(hierarchy) {
+  const { epicGraph, storyGraphs, allNodes } = buildDependencyGraph(hierarchy);
+  const phases = computePhases(epicGraph);
+  const criticalPath = computeCriticalPath(epicGraph);
+
+  // Order stories within each epic
+  const storyOrders = new Map();
+  for (const [epicId, storyGraph] of storyGraphs) {
+    storyOrders.set(epicId, orderStoriesWithinEpic(storyGraph));
+  }
+
+  // Render mermaid edges using epicGraph
+  const md = generateCodingOrderMdWithGraph(phases, storyOrders, allNodes, criticalPath, epicGraph);
+  const json = generateCodingOrderJson(phases, storyOrders, allNodes, criticalPath);
+
+  return { md, json, phases, criticalPath };
+}
+
+/**
+ * Full Markdown rendering with mermaid graph edges.
+ */
+function generateCodingOrderMdWithGraph(phases, storyOrders, allNodes, criticalPath, epicGraph) {
+  const lines = [
+    '# Coding Order',
+    '',
+    `Generated: ${new Date().toISOString()}`,
+    '',
+    '## Dependency Graph',
+    '',
+    '```mermaid',
+    'graph LR',
+  ];
+
+  // Nodes
+  for (const [id, node] of allNodes) {
+    if (node.type === 'epic') {
+      const label = node.name.replace(/"/g, "'");
+      lines.push(`  ${id}["${label}"]`);
+    }
+  }
+
+  // Edges
+  for (const [epicId, deps] of epicGraph) {
+    for (const dep of deps) {
+      lines.push(`  ${dep} --> ${epicId}`);
+    }
+  }
+
+  // Highlight critical path
+  if (criticalPath.path.length > 1) {
+    lines.push(`  style ${criticalPath.path.join(' stroke:#f44,stroke-width:3px;  style ')} stroke:#f44,stroke-width:3px`);
+  }
+
+  lines.push('```', '');
+
+  // Critical path
+  lines.push('## Critical Path', '');
+  if (criticalPath.path.length > 0) {
+    const pathStr = criticalPath.path
+      .map(id => { const n = allNodes.get(id); return n ? `**${n.name}**` : id; })
+      .join(' → ');
+    lines.push(pathStr, '', `Length: ${criticalPath.length} epics`, '');
+  } else {
+    lines.push('No dependencies — all epics are independent.', '');
+  }
+
+  // Phases
+  lines.push('## Implementation Phases', '');
+  for (const phase of phases) {
+    const parallel = phase.epicIds.length > 1 ? ' (parallel)' : '';
+    const depNote = phase.phase === 0 ? '' : ` — requires Phase ${phase.phase} complete`;
+    lines.push(`### Phase ${phase.phase + 1}${parallel}${depNote}`, '');
+
+    for (const epicId of phase.epicIds) {
+      const epic = allNodes.get(epicId);
+      lines.push(`#### ${epicId}: ${epic?.name || epicId}`, '');
+
+      const stories = storyOrders.get(epicId) || [];
+      if (stories.length > 0) {
+        lines.push('| # | Story | ID |', '|---|-------|-----|');
+        stories.forEach((storyId, idx) => {
+          const story = allNodes.get(storyId);
+          lines.push(`| ${idx + 1} | ${story?.name || storyId} | \`${storyId}\` |`);
+        });
+        lines.push('');
+      }
+    }
+  }
+
+  return lines.join('\n');
+}