iikit-dashboard 1.5.0 → 1.6.0

package/README.md

@@ -11,11 +11,12 @@ The dashboard launches automatically early in the IIKit workflow — no manual s
 You can also start it standalone to browse historical data for any project that has feature specs:
 
 ```bash
-npx iikit-dashboard              # current directory
-npx iikit-dashboard /path/to/project   # specific project
+npx iikit-dashboard                       # current directory
+npx iikit-dashboard /path/to/project      # specific project
+npx iikit-dashboard --port 3001           # custom port
 ```
 
-The dashboard opens at `http://localhost:3000`.
+The dashboard opens at `http://localhost:3000` by default. A pidfile (`.specify/dashboard.pid.json`) is written on startup so external tools can discover which project a running dashboard serves and at which port.
 
 ## Views
 
@@ -23,40 +24,48 @@ The pipeline bar at the top shows all nine IIKit workflow phases. Click any phas
 
 | Phase | View |
 |-------|------|
-| **Constitution** | Radar chart of governance principles with obligation levels (MUST / SHOULD / MAY) |
-| **Spec** | Story map with swim lanes by priority + interactive requirements graph (US / FR / SC nodes and edges) |
-| **Clarify** | Q&A trail from clarification sessions, with clickable spec-item references that navigate back to the Spec view |
-| **Plan** | Tech stack badge wall, interactive file-structure tree (existing vs. planned files), rendered architecture diagram, and Tessl tile cards |
+| **Constitution** | Radar chart of governance principles with obligation levels (MUST / SHOULD / MAY) and version timeline |
+| **Spec** | Story map with swim lanes by priority + interactive force-directed requirements graph (US / FR / SC nodes and edges) with detail side-panel |
+| **Clarify** | Q&A trail from clarification sessions grouped by date, with clickable spec-item references that navigate to the Spec view |
+| **Plan** | Tech context key-value pairs, interactive file-structure tree (existing vs. planned files), rendered architecture diagram, and Tessl tile cards with live eval scores |
 | **Checklist** | Progress rings per checklist file with color coding (red/yellow/green), gate traffic light (OPEN/BLOCKED), and accordion detail view with CHK IDs and tag badges |
-| **Testify** | *Coming soon* |
-| **Tasks** | *Coming soon* |
-| **Analyze** | *Coming soon* |
-| **Implement** | Kanban board with cards sliding Todo → In Progress → Done as the agent checks off tasks |
+| **Testify** | Assertion integrity seal (Verified/Tampered/Missing), Sankey traceability diagram (Requirements → Test Specs → Tasks), test pyramid, and gap highlighting for untested requirements |
+| **Tasks** | Redirects to the Implement board (tasks are managed there) |
+| **Analyze** | Health gauge (0–100) with four weighted factors, coverage heatmap (Tasks/Tests/Plan per requirement), and sortable/filterable severity table of analysis findings |
+| **Implement** | Kanban board with cards sliding Todo → In Progress → Done as the agent checks off tasks, with collapsible per-story task lists |
 
 ## Features
 
 - **Live updates** — all views refresh in real time via WebSocket as project files change
 - **Pipeline navigation** — phase nodes show status (complete / in-progress / skipped / not started) with progress percentages
+- **Cross-panel navigation** — Cmd/Ctrl+click any FR, US, SC, or task identifier to jump to its linked panel (Spec, Testify, Implement, Checklist, or Clarify)
 - **Feature selector** — dropdown to switch between features in `specs/`, sorted newest-first
-- **Clarification traceability** — Q&A entries link back to the FR / US / SC spec items they clarify
-- **Integrity badges** — shows whether test assertions have been tampered with
+- **Project label** — header shows the project directory name with full path on hover, so you know which project a dashboard tab belongs to
+- **Integrity badges** — shows whether test assertions have been tampered with (verified / tampered / missing)
+- **Tessl eval scores** — Plan view tile cards display live eval data (score, pass/fail chart) when available
+- **Activity indicator** — green dot pulses in the header when files are actively changing
+- **Multi-project support** — pidfile at `.specify/dashboard.pid.json` lets external scripts identify running instances per project
 - **Three-state theme** — cycles System (OS preference) → Light → Dark
 - **Zero build step** — single HTML file with inline CSS and JS
 
 ## How It Works
 
-The server reads directly from your project's `specs/` directory:
+The server reads directly from your project's directory:
 
 | File | Purpose |
 |------|---------|
-| `spec.md` | User stories, requirements, success criteria, and clarification Q&A |
-| `plan.md` | Tech stack, file structure, and architecture diagram |
-| `tasks.md` | Task checkboxes grouped by `[US1]`, `[US2]` tags |
-| `checklists/*.md` | Checklist items with completion status, CHK IDs, and category groupings |
 | `CONSTITUTION.md` | Governance principles and obligation levels |
-| `tessl.json` | Installed Tessl tiles for the dependency panel |
-
-A file watcher (chokidar) detects changes and pushes updates to the browser via WebSocket with 300 ms debounce.
+| `specs/<feature>/spec.md` | User stories, requirements, success criteria, and clarification Q&A |
+| `specs/<feature>/plan.md` | Tech stack, file structure, and architecture diagram |
+| `specs/<feature>/research.md` | Research decisions (displayed as tooltips in Plan view) |
+| `specs/<feature>/tasks.md` | Task checkboxes grouped by `[US1]`, `[US2]` tags |
+| `specs/<feature>/checklists/*.md` | Checklist items with completion status, CHK IDs, and category groupings |
+| `specs/<feature>/tests/test-specs.md` | Test specifications for the Testify traceability view |
+| `specs/<feature>/context.json` | Assertion hash for integrity verification |
+| `specs/<feature>/analysis.md` | Consistency analysis findings, coverage, and metrics |
+| `tessl.json` | Installed Tessl tiles for the Plan dependency panel |
+
+A file watcher (chokidar) monitors the project tree (excluding `node_modules` and `.git`) and pushes updates to the browser via WebSocket with 300 ms debounce.
 
 ## Requirements
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "iikit-dashboard",
-  "version": "1.5.0",
+  "version": "1.6.0",
   "description": "Real-time dashboard for Intent Integrity Kit (IIKit) — visualizes every phase of specification-driven AI development",
   "main": "src/server.js",
   "bin": {
@@ -12,7 +12,9 @@
   ],
   "scripts": {
     "start": "node bin/iikit-dashboard.js",
-    "test": "jest --forceExit"
+    "test": "jest --forceExit --testPathIgnorePatterns=test/visual",
+    "test:visual": "npx playwright test",
+    "test:visual:update": "npx playwright test --update-snapshots"
   },
   "keywords": [
     "iikit",
@@ -40,6 +42,7 @@
     "ws": "^8.19.0"
   },
   "devDependencies": {
+    "@playwright/test": "^1.58.2",
     "jest": "^30.2.0"
   }
 }

package/src/board.js

@@ -19,8 +19,9 @@ function computeBoardState(stories, tasks) {
   if (!stories || !Array.isArray(stories)) return board;
   if (!tasks) tasks = [];
 
-  // Group tasks by storyTag
+  // Group tasks by storyTag or bugTag
   const tasksByStory = {};
+  const tasksByBug = {};
   const untaggedTasks = [];
 
   for (const task of tasks) {
@@ -29,6 +30,11 @@ function computeBoardState(stories, tasks) {
         tasksByStory[task.storyTag] = [];
       }
       tasksByStory[task.storyTag].push(task);
+    } else if (task.bugTag) {
+      if (!tasksByBug[task.bugTag]) {
+        tasksByBug[task.bugTag] = [];
+      }
+      tasksByBug[task.bugTag].push(task);
     } else {
       untaggedTasks.push(task);
     }
@@ -87,6 +93,33 @@ function computeBoardState(stories, tasks) {
     board[column].push(card);
   }
 
+  // Handle bug fix tasks — group into per-bug cards
+  for (const [bugId, bugTasks] of Object.entries(tasksByBug)) {
+    const checkedCount = bugTasks.filter(t => t.checked).length;
+    const totalCount = bugTasks.length;
+
+    let column;
+    if (checkedCount === 0) {
+      column = 'todo';
+    } else if (checkedCount === totalCount) {
+      column = 'done';
+    } else {
+      column = 'in_progress';
+    }
+
+    const card = {
+      id: bugId,
+      title: `Bug Fix: ${bugId}`,
+      priority: 'P2',
+      tasks: bugTasks,
+      progress: `${checkedCount}/${totalCount}`,
+      column,
+      isBugCard: true
+    };
+
+    board[column].push(card);
+  }
+
   return board;
 }
 

package/src/bugs.js

@@ -0,0 +1,168 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { parseBugs, parseTasks } = require('./parser');
+
+const SEVERITY_ORDER = { critical: 0, high: 1, medium: 2, low: 3 };
+
+/**
+ * Resolve a GitHub issue reference like "#13" to a full URL.
+ *
+ * @param {string|null} issueRef - Issue reference (e.g., "#13") or null
+ * @param {string|null} repoUrl - Repository URL from git remote or null
+ * @returns {string|null} Full URL or null
+ */
+function resolveGitHubIssueUrl(issueRef, repoUrl) {
+  if (!issueRef || !repoUrl) return null;
+
+  // Skip sentinel values
+  if (/^_\(/.test(issueRef)) return null;
+
+  // Extract issue number
+  const numMatch = issueRef.match(/#(\d+)/);
+  if (!numMatch) return null;
+
+  const issueNumber = numMatch[1];
+
+  // Normalize repo URL
+  let baseUrl = repoUrl;
+
+  // Handle SSH format: git@github.com:user/repo.git
+  const sshMatch = baseUrl.match(/^git@([^:]+):(.+?)(?:\.git)?$/);
+  if (sshMatch) {
+    baseUrl = `https://${sshMatch[1]}/${sshMatch[2]}`;
+  }
+
+  // Strip trailing .git
+  baseUrl = baseUrl.replace(/\.git$/, '');
+
+  return `${baseUrl}/issues/${issueNumber}`;
+}
+
+/**
+ * Compute the bugs state for a feature.
+ * Reads bugs.md and tasks.md, cross-references fix tasks by [BUG-NNN] tag.
+ *
+ * @param {string} projectPath - Path to the project root
+ * @param {string} featureId - Feature directory name (e.g., "009-bugs-tab")
+ * @returns {{exists: boolean, bugs: Array, orphanedTasks: Array, summary: Object, repoUrl: string|null}}
+ */
+function computeBugsState(projectPath, featureId) {
+  const featureDir = path.join(projectPath, 'specs', featureId);
+  const bugsPath = path.join(featureDir, 'bugs.md');
+  const tasksPath = path.join(featureDir, 'tasks.md');
+
+  const emptySummary = {
+    total: 0,
+    open: 0,
+    fixed: 0,
+    highestOpenSeverity: null,
+    bySeverity: { critical: 0, high: 0, medium: 0, low: 0 }
+  };
+
+  if (!fs.existsSync(bugsPath)) {
+    return { exists: false, bugs: [], orphanedTasks: [], summary: emptySummary, repoUrl: null };
+  }
+
+  const bugsContent = fs.readFileSync(bugsPath, 'utf-8');
+  const bugs = parseBugs(bugsContent);
+
+  // Parse tasks for fix task cross-referencing
+  const tasksContent = fs.existsSync(tasksPath) ? fs.readFileSync(tasksPath, 'utf-8') : '';
+  const allTasks = parseTasks(tasksContent);
+  const bugFixTasks = allTasks.filter(t => t.isBugFix && t.bugTag);
+
+  // Build lookup: BUG-NNN -> [task, ...]
+  const tasksByBug = {};
+  for (const task of bugFixTasks) {
+    if (!tasksByBug[task.bugTag]) tasksByBug[task.bugTag] = [];
+    tasksByBug[task.bugTag].push(task);
+  }
+
+  // Track which bug IDs exist
+  const bugIds = new Set(bugs.map(b => b.id));
+
+  // Enrich bugs with fix tasks
+  for (const bug of bugs) {
+    const tasks = tasksByBug[bug.id] || [];
+    bug.fixTasks = {
+      total: tasks.length,
+      checked: tasks.filter(t => t.checked).length,
+      tasks: tasks.map(t => ({
+        id: t.id,
+        description: t.description,
+        checked: t.checked
+      }))
+    };
+  }
+
+  // Sort bugs: severity descending (critical first), then ID ascending
+  bugs.sort((a, b) => {
+    const sevA = SEVERITY_ORDER[a.severity] !== undefined ? SEVERITY_ORDER[a.severity] : 3;
+    const sevB = SEVERITY_ORDER[b.severity] !== undefined ? SEVERITY_ORDER[b.severity] : 3;
+    const sevDiff = sevA - sevB;
+    if (sevDiff !== 0) return sevDiff;
+    return a.id.localeCompare(b.id);
+  });
+
+  // Detect orphaned tasks (T-B tasks referencing non-existent BUG-NNN)
+  const orphanedTasks = bugFixTasks
+    .filter(t => !bugIds.has(t.bugTag))
+    .map(t => ({ id: t.id, bugTag: t.bugTag, description: t.description, checked: t.checked }));
+
+  // Compute summary
+  const openBugs = bugs.filter(b => b.status !== 'fixed');
+  const fixedBugs = bugs.filter(b => b.status === 'fixed');
+
+  const bySeverity = { critical: 0, high: 0, medium: 0, low: 0 };
+  for (const bug of openBugs) {
+    if (bySeverity.hasOwnProperty(bug.severity)) {
+      bySeverity[bug.severity]++;
+    }
+  }
+
+  let highestOpenSeverity = null;
+  for (const sev of ['critical', 'high', 'medium', 'low']) {
+    if (bySeverity[sev] > 0) {
+      highestOpenSeverity = sev;
+      break;
+    }
+  }
+
+  // Try to get repo URL from git remote
+  let repoUrl = null;
+  try {
+    const { execSync } = require('child_process');
+    repoUrl = execSync('git remote get-url origin', {
+      cwd: projectPath,
+      encoding: 'utf-8',
+      stdio: ['pipe', 'pipe', 'pipe']
+    }).trim();
+    // Strip .git suffix
+    repoUrl = repoUrl.replace(/\.git$/, '');
+    // Handle SSH format
+    const sshMatch = repoUrl.match(/^git@([^:]+):(.+)$/);
+    if (sshMatch) {
+      repoUrl = `https://${sshMatch[1]}/${sshMatch[2]}`;
+    }
+  } catch {
+    // No git remote — repoUrl stays null
+  }
+
+  return {
+    exists: true,
+    bugs,
+    orphanedTasks,
+    summary: {
+      total: bugs.length,
+      open: openBugs.length,
+      fixed: fixedBugs.length,
+      highestOpenSeverity,
+      bySeverity
+    },
+    repoUrl
+  };
+}
+
+module.exports = { computeBugsState, resolveGitHubIssueUrl };

package/src/parser.js

@@ -57,23 +57,31 @@ function parseSpecStories(content) {
 /**
  * Parse tasks.md to extract tasks with checkbox status and story tags.
  * Pattern: - [x] TXXX [P]? [USy]? Description
+ * Extended: also matches T-B\d+ IDs and [BUG-\d+] tags for bug fix tasks.
  *
  * @param {string} content - Raw markdown content of tasks.md
- * @returns {Array<{id: string, storyTag: string|null, description: string, checked: boolean}>}
+ * @returns {Array<{id: string, storyTag: string|null, bugTag: string|null, description: string, checked: boolean, isBugFix: boolean}>}
  */
 function parseTasks(content) {
   if (!content || typeof content !== 'string') return [];
 
-  const regex = /- \[([ x])\] (T\d+)\s+(?:\[P\]\s*)?(?:\[(US\d+)\]\s*)?(.*)/g;
+  const regex = /- \[([ x])\] (T(?:-B)?\d+)\s+(?:\[P\]\s*)?(?:\[(US\d+|BUG-\d+)\]\s*)?(.*)/g;
   const tasks = [];
   let match;
 
   while ((match = regex.exec(content)) !== null) {
+    const id = match[2];
+    const tag = match[3] || null;
+    const isBugFix = id.startsWith('T-B');
+    const isBugTag = tag && /^BUG-\d+$/.test(tag);
+
     tasks.push({
-      id: match[2],
-      storyTag: match[3] || null,
+      id,
+      storyTag: (tag && !isBugTag) ? tag : null,
+      bugTag: isBugTag ? tag : null,
       description: match[4].trim(),
-      checked: match[1] === 'x'
+      checked: match[1] === 'x',
+      isBugFix
     });
   }
 
@@ -1179,4 +1187,75 @@ function parsePhaseSeparation(content) {
   }).filter(Boolean);
 }
 
-module.exports = { parseSpecStories, parseTasks, parseChecklists, parseChecklistsDetailed, parseConstitutionTDD, hasClarifications, parseConstitutionPrinciples, parseRequirements, parseSuccessCriteria, parseClarifications, parseStoryRequirementRefs, parseTechContext, parseFileStructure, parseAsciiDiagram, parseTesslJson, parseResearchDecisions, parseTestSpecs, parseTaskTestRefs, parseAnalysisFindings, parseAnalysisCoverage, parseAnalysisMetrics, parseConstitutionAlignment, parsePhaseSeparation };
+/**
+ * Parse bugs.md to extract bug entries.
+ * Pattern: ## BUG-NNN headings with field lines.
+ * Permissive parsing — returns [] on missing/empty/malformed input.
+ *
+ * @param {string} content - Raw markdown content of bugs.md
+ * @returns {Array<{id: string, reported: string|null, severity: string, status: string, githubIssue: string|null, description: string|null, rootCause: string|null, fixReference: string|null}>}
+ */
+function parseBugs(content) {
+  if (!content || typeof content !== 'string') return [];
+
+  const validSeverities = new Set(['critical', 'high', 'medium', 'low']);
+  const validStatuses = new Set(['reported', 'fixed']);
+
+  const headingRegex = /^## (BUG-\d+)\s*$/gm;
+  const bugStarts = [];
+  let match;
+
+  while ((match = headingRegex.exec(content)) !== null) {
+    bugStarts.push({ id: match[1], index: match.index });
+  }
+
+  const bugs = [];
+
+  for (let i = 0; i < bugStarts.length; i++) {
+    const start = bugStarts[i].index;
+    const end = i + 1 < bugStarts.length ? bugStarts[i + 1].index : content.length;
+    const section = content.substring(start, end);
+
+    const bug = {
+      id: bugStarts[i].id,
+      reported: extractField(section, 'Reported'),
+      severity: extractField(section, 'Severity') || 'medium',
+      status: extractField(section, 'Status') || 'reported',
+      githubIssue: extractField(section, 'GitHub Issue'),
+      description: extractField(section, 'Description'),
+      rootCause: extractField(section, 'Root Cause'),
+      fixReference: extractField(section, 'Fix Reference')
+    };
+
+    // Validate severity
+    if (!validSeverities.has(bug.severity)) {
+      bug.severity = 'medium';
+    }
+
+    // Validate status
+    if (!validStatuses.has(bug.status)) {
+      bug.status = 'reported';
+    }
+
+    bugs.push(bug);
+  }
+
+  return bugs;
+}
+
+/**
+ * Extract a **Field**: Value from a bug section.
+ * Returns null for _(none)_, _(empty...)_ patterns, and missing fields.
+ */
+function extractField(section, fieldName) {
+  const regex = new RegExp(`\\*\\*${fieldName}\\*\\*:\\s*(.+)`, 'm');
+  const match = section.match(regex);
+  if (!match) return null;
+
+  const value = match[1].trim();
+  if (!value || /^_\(/.test(value)) return null;
+
+  return value;
+}
+
+module.exports = { parseSpecStories, parseTasks, parseChecklists, parseChecklistsDetailed, parseConstitutionTDD, hasClarifications, parseConstitutionPrinciples, parseRequirements, parseSuccessCriteria, parseClarifications, parseStoryRequirementRefs, parseTechContext, parseFileStructure, parseAsciiDiagram, parseTesslJson, parseResearchDecisions, parseTestSpecs, parseTaskTestRefs, parseAnalysisFindings, parseAnalysisCoverage, parseAnalysisMetrics, parseConstitutionAlignment, parsePhaseSeparation, parseBugs };

package/src/public/index.html

@@ -724,9 +724,9 @@
       border-radius: var(--radius-md);
       cursor: pointer;
       transition: background var(--transition-fast), transform var(--transition-fast);
-      flex: 0 1 96px;
-      width: 96px;
-      min-width: 40px;
+      flex: 1 1 0;
+      min-width: 72px;
+      max-width: 110px;
       position: relative;
       border: 1px solid var(--color-border-subtle);
       background: transparent;
@@ -830,6 +830,340 @@
       opacity: 0.8;
     }
 
+    /* ====== Bugs Tab (standalone, no connector) ====== */
+    .bugs-tab-gap {
+      width: 16px;
+      flex-shrink: 0;
+    }
+
+    .bugs-tab {
+      display: flex;
+      flex-direction: column;
+      align-items: center;
+      gap: 4px;
+      padding: 6px 12px;
+      cursor: pointer;
+      border-radius: 8px;
+      border: 1px solid var(--color-border);
+      background: var(--color-surface);
+      transition: all 0.15s ease;
+      position: relative;
+      font-family: inherit;
+      color: inherit;
+    }
+
+    .bugs-tab:hover {
+      border-color: var(--color-text-secondary);
+      background: rgba(255, 255, 255, 0.06);
+    }
+
+    .bugs-tab.active {
+      border-color: var(--color-accent);
+      background: rgba(99, 102, 241, 0.08);
+    }
+
+    .bugs-tab.muted {
+      opacity: 0.45;
+    }
+
+    .bugs-tab-icon {
+      font-size: 14px;
+      line-height: 1;
+    }
+
+    .bugs-tab-label {
+      font-size: 10px;
+      text-transform: uppercase;
+      letter-spacing: 0.5px;
+      color: var(--color-text-secondary);
+    }
+
+    .bugs-tab-badge {
+      position: absolute;
+      top: -6px;
+      right: -6px;
+      min-width: 18px;
+      height: 18px;
+      padding: 0 5px;
+      border-radius: 9px;
+      font-size: 11px;
+      font-weight: 600;
+      line-height: 18px;
+      text-align: center;
+      color: #fff;
+    }
+
+    .bugs-tab-badge.muted {
+      opacity: 0.4;
+      background: var(--color-text-secondary);
+    }
+
+    .bugs-tab-badge.severity-critical { background: #ff4757; }
+    .bugs-tab-badge.severity-high { background: #ffa502; }
+    .bugs-tab-badge.severity-medium { background: #f1c40f; color: #1a1a2e; }
+    .bugs-tab-badge.severity-low { background: #6b7189; }
+
+    /* ====== Bug Severity Colors ====== */
+    .severity-critical { color: #ff4757; }
+    .severity-high { color: #ffa502; }
+    .severity-medium { color: #f1c40f; }
+    .severity-low { color: #6b7189; }
+
+    .severity-badge {
+      display: inline-block;
+      padding: 2px 8px;
+      border-radius: 4px;
+      font-size: 11px;
+      font-weight: 600;
+      text-transform: uppercase;
+      letter-spacing: 0.3px;
+    }
+
+    .severity-badge.severity-critical { background: rgba(255, 71, 87, 0.15); color: #ff4757; }
+    .severity-badge.severity-high { background: rgba(255, 165, 2, 0.15); color: #ffa502; }
+    .severity-badge.severity-medium { background: rgba(241, 196, 15, 0.15); color: #f1c40f; }
+    .severity-badge.severity-low { background: rgba(107, 113, 137, 0.15); color: #6b7189; }
+
+    /* ====== Bugs View ====== */
+    .bugs-view {
+      padding: 24px;
+      max-width: 1200px;
+      margin: 0 auto;
+    }
+
+    .bugs-view-header {
+      margin-bottom: 20px;
+    }
+
+    .bugs-view-title {
+      font-size: 20px;
+      font-weight: 600;
+      color: var(--color-text-primary);
+    }
+
+    .bugs-view-subtitle {
+      font-size: 13px;
+      color: var(--color-text-secondary);
+      margin-top: 4px;
+    }
+
+    .bugs-table {
+      width: 100%;
+      border-collapse: collapse;
+      font-size: 13px;
+    }
+
+    .bugs-table th {
+      text-align: left;
+      padding: 10px 12px;
+      font-weight: 600;
+      color: var(--color-text-secondary);
+      border-bottom: 1px solid var(--color-border);
+      font-size: 11px;
+      text-transform: uppercase;
+      letter-spacing: 0.5px;
+    }
+
+    .bugs-table td {
+      padding: 10px 12px;
+      border-bottom: 1px solid rgba(255, 255, 255, 0.04);
+      vertical-align: middle;
+    }
+
+    .bugs-table tr:hover td {
+      background: rgba(255, 255, 255, 0.02);
+    }
+
+    .bugs-table tr.highlighted td {
+      background: rgba(99, 102, 241, 0.12);
+      transition: background 0.3s ease;
+    }
+
+    .bugs-table .bug-id {
+      font-family: 'SF Mono', 'Fira Code', monospace;
+      font-weight: 600;
+      color: var(--color-text-primary);
+    }
+
+    .bugs-table .bug-status {
+      text-transform: capitalize;
+    }
+
+    .bugs-table .bug-status.fixed {
+      color: var(--color-done);
+    }
+
+    .bugs-table .bug-progress {
+      font-family: 'SF Mono', 'Fira Code', monospace;
+      font-size: 12px;
+    }
+
+    .bugs-table .bug-description {
+      max-width: 300px;
+      overflow: hidden;
+      text-overflow: ellipsis;
+      white-space: nowrap;
+    }
+
+    .bugs-table .github-link {
+      color: var(--color-accent);
+      text-decoration: none;
+    }
+
+    .bugs-table .github-link:hover {
+      text-decoration: underline;
+    }
+
+    .bugs-empty {
+      display: flex;
+      flex-direction: column;
+      align-items: center;
+      justify-content: center;
+      padding: 80px 20px;
+      text-align: center;
+    }
+
+    .bugs-empty-icon {
+      font-size: 48px;
+      margin-bottom: 16px;
+      opacity: 0.4;
+    }
+
+    .bugs-empty-title {
+      font-size: 18px;
+      font-weight: 600;
+      color: var(--color-text-primary);
+      margin-bottom: 8px;
+    }
+
+    .bugs-empty-text {
+      font-size: 14px;
+      color: var(--color-text-secondary);
+    }
+
+    .orphaned-section {
+      margin-top: 24px;
+      padding: 16px;
+      border: 1px dashed var(--color-border);
+      border-radius: 8px;
+      opacity: 0.7;
+    }
+
+    .orphaned-title {
+      font-size: 13px;
+      font-weight: 600;
+      color: var(--color-text-secondary);
+      margin-bottom: 8px;
+    }
+
+    .orphaned-task {
+      font-size: 12px;
+      color: var(--color-text-secondary);
+      padding: 4px 0;
+    }
+
+    .bug-icon-inline {
+      display: inline-block;
+      width: 14px;
+      height: 14px;
+      margin-right: 4px;
+      vertical-align: middle;
+      opacity: 0.7;
+    }
+
+    /* Pipeline bugs gap & node (spec aliases) */
+    .pipeline-bugs-gap {
+      width: 20px;
+      flex-shrink: 0;
+    }
+    .pipeline-node-bugs.muted {
+      opacity: 0.5;
+    }
+    .bugs-dot {
+      background: var(--color-surface-elevated) !important;
+      border: 2px solid var(--color-border) !important;
+      color: var(--color-text-muted) !important;
+    }
+    .bug-count-badge {
+      display: inline-flex;
+      align-items: center;
+      justify-content: center;
+      min-width: 18px;
+      height: 18px;
+      padding: 0 5px;
+      border-radius: 9px;
+      font-size: 11px;
+      font-weight: 700;
+      margin-left: 4px;
+      vertical-align: middle;
+    }
+    .bug-count-badge.muted {
+      background: var(--color-surface-elevated);
+      color: var(--color-text-muted);
+    }
+
+    /* Bug view additional styles */
+    .bugs-view-container {
+      padding: 24px;
+      max-width: 1200px;
+    }
+    .bugs-view-container h2 {
+      font-size: 18px;
+      font-weight: 600;
+      margin-bottom: 16px;
+      color: var(--color-text);
+    }
+    .bug-row:hover {
+      background: var(--color-surface-hover);
+    }
+    .fix-progress {
+      font-variant-numeric: tabular-nums;
+      font-weight: 500;
+    }
+    .bug-status {
+      text-transform: capitalize;
+    }
+    .bug-status.fixed {
+      color: var(--color-success, #2ecc71);
+    }
+    .bug-github-link {
+      color: var(--color-accent);
+      text-decoration: none;
+    }
+    .bug-github-link:hover {
+      text-decoration: underline;
+    }
+    .bug-empty-state {
+      text-align: center;
+      padding: 48px 24px;
+      color: var(--color-text-muted);
+      font-size: 14px;
+    }
+    .bug-empty-state svg {
+      display: block;
+      margin: 0 auto 12px;
+      opacity: 0.4;
+    }
+    .orphaned-tasks-section {
+      margin-top: 32px;
+      padding: 16px;
+      background: var(--color-surface-elevated);
+      border-radius: var(--radius-md);
+      border: 1px solid var(--color-warning, #f5a623);
+      opacity: 0.7;
+    }
+    .orphaned-tasks-section h3 {
+      font-size: 13px;
+      font-weight: 600;
+      color: var(--color-warning, #f5a623);
+      margin-bottom: 8px;
+    }
+    .orphaned-tasks-section .task-item {
+      font-size: 12px;
+      color: var(--color-text-muted);
+      padding: 4px 0;
+    }
+
     /* ====== Content Area ====== */
     .content-area {
       flex: 1;
@@ -868,6 +1202,8 @@
       font-size: 13px;
       color: var(--color-text-muted);
       max-width: 360px;
+      margin: 0 auto;
+      text-align: center;
     }
 
     /* ====== Checklist Quality Gates Tab ====== */
@@ -1559,6 +1895,10 @@
       text-align: center;
       padding: 60px 20px;
       color: var(--color-text-muted);
+      max-width: 480px;
+      margin: 0 auto;
+      word-break: normal;
+      overflow-wrap: break-word;
     }
 
     .clarify-header {
@@ -2427,6 +2767,7 @@
       let expandedChecklist = null;
       let currentTestify = null;
       let currentAnalyze = null;
+      let currentBugs = null;
       let activeTab = null;
       let externalSankeyHighlight = null;
       let ws = null;
@@ -2453,6 +2794,25 @@
         available: '●'
       };
 
+      const BUG_ICON_SMALL = '<svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M8 2l1.88 1.88M14.12 3.88L16 2M9 7.13v-1a3 3 0 0 1 6 0v1M12 20c-3.3 0-6-2.7-6-6v-3a4 4 0 0 1 4-4h4a4 4 0 0 1 4 4v3c0 3.3-2.7 6-6 6zM3.5 11H2M5.06 6.5l-1.5-1M22 11h-1.5M18.94 6.5l1.5-1M12 20v2"/></svg>';
+
+      function getBugsBadgeHtml(bugsData) {
+        if (!bugsData || !bugsData.exists) return '';
+        const count = bugsData.summary.open;
+        const sev = bugsData.summary.highestOpenSeverity;
+
+        const colors = { critical: '#ff4757', high: '#ffa502', medium: '#f1c40f', low: '#6b7189' };
+        const textColors = { critical: '#fff', high: '#fff', medium: '#1a1a2e', low: '#fff' };
+
+        if (count === 0) {
+          return ' <span class="bug-count-badge muted">0</span>';
+        }
+
+        const bg = colors[sev] || '#6b7189';
+        const fg = textColors[sev] || '#fff';
+        return ` <span class="bug-count-badge" style="background:${bg};color:${fg}">${count}</span>`;
+      }
+
       function renderPipeline(pipeline) {
         if (!pipeline || !pipeline.phases) return;
         currentPipeline = pipeline;
@@ -2487,6 +2847,28 @@
           node.addEventListener('click', () => switchTab(phase.id));
           pipelineBar.appendChild(node);
         });
+
+        // Bugs tab — standalone, no connector
+        const bugsGap = document.createElement('div');
+        bugsGap.className = 'pipeline-bugs-gap';
+        pipelineBar.appendChild(bugsGap);
+
+        const bugsTab = document.createElement('button');
+        bugsTab.className = 'bugs-tab' + (activeTab === 'bugs' ? ' active' : '');
+        bugsTab.setAttribute('data-view', 'bugs');
+        bugsTab.setAttribute('tabindex', '0');
+        if (activeTab === 'bugs') bugsTab.setAttribute('aria-current', 'true');
+
+        const badgeHtml = currentBugs ? getBugsBadgeHtml(currentBugs) : '';
+        bugsTab.innerHTML = `
+          <div class="pipeline-dot bugs-dot">${BUG_ICON_SMALL}</div>
+          <span class="pipeline-label">Bugs${badgeHtml}</span>
+        `;
+        if (currentBugs && !currentBugs.exists) {
+          bugsTab.classList.add('muted');
+        }
+        bugsTab.addEventListener('click', () => switchTab('bugs'));
+        pipelineBar.appendChild(bugsTab);
       }
 
       function switchTab(phaseId) {
@@ -2519,6 +2901,8 @@
           renderTestifyView();
         } else if (phaseId === 'analyze') {
           renderAnalyzeView();
+        } else if (phaseId === 'bugs') {
+          renderBugsView();
         } else {
           renderPlaceholderView(phaseId);
         }
@@ -2533,7 +2917,8 @@
         // Sentinel elements per panel — poll until the panel has rendered
         const sentinels = {
           spec: '.graph-node', testify: '.sankey-node', implement: '.card',
-          checklist: '.checklist-item', clarify: '.clarify-entry', analyze: '.heatmap-row'
+          checklist: '.checklist-item', clarify: '.clarify-entry', analyze: '.heatmap-row',
+          bugs: '.bug-row'
         };
         const sel = sentinels[panelId];
         if (sel) {
@@ -2549,7 +2934,8 @@
           testify: highlightTestifyEntity,
           implement: highlightBoardEntity,
           checklist: highlightChecklistEntity,
-          clarify: highlightClarifyEntity
+          clarify: highlightClarifyEntity,
+          bugs: highlightBugsEntity
         };
         const fn = highlighters[panelId];
         if (fn) fn(entityId);
@@ -2687,6 +3073,138 @@
         }
       }
 
+      // ====== Bugs View (T014, T015, T016) ======
+
+      async function renderBugsView() {
+        if (!currentFeature) return;
+
+        contentArea.innerHTML = '<div class="loading">Loading bug data...</div>';
+        try {
+          const res = await fetch(`/api/bugs/${currentFeature}`);
+          if (!res.ok) throw new Error(`HTTP ${res.status}`);
+          const data = await res.json();
+          currentBugs = data;
+          if (currentPipeline) renderPipeline(currentPipeline);
+          renderBugsContent(data);
+        } catch (err) {
+          contentArea.innerHTML = `<div class="error-message">Error loading bugs: ${escapeHtml(err.message)}</div>`;
+        }
+      }
+
+      function renderBugsContent(data) {
+        if (!data || !data.exists || data.bugs.length === 0) {
+          // T015: Empty state
+          const msg = !data || !data.exists
+            ? 'No bugs have been reported for this feature.'
+            : 'All clear — no bug entries found.';
+          contentArea.innerHTML = `
+            <div class="bugs-empty">
+              <div class="bugs-empty-icon">&#10003;</div>
+              <div class="bugs-empty-title">No Bugs</div>
+              <div class="bugs-empty-text">${msg}</div>
+            </div>`;
+          return;
+        }
+
+        const { bugs, orphanedTasks, summary, repoUrl } = data;
+
+        let tableRows = '';
+        for (const bug of bugs) {
+          // Fix task progress
+          const progressText = bug.fixTasks.total > 0
+            ? `${bug.fixTasks.checked}/${bug.fixTasks.total}`
+            : '\u2014';
+
+          // GitHub link (T016)
+          let githubHtml = '\u2014';
+          if (bug.githubIssue) {
+            const resolvedUrl = resolveGitHubUrl(bug.githubIssue, repoUrl);
+            if (resolvedUrl) {
+              githubHtml = `<a href="${escapeHtml(resolvedUrl)}" class="github-link bug-github-link" target="_blank" rel="noopener">${escapeHtml(bug.githubIssue)} <svg width="12" height="12" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" style="vertical-align:middle"><path d="M18 13v6a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2V8a2 2 0 0 1 2-2h6M15 3h6v6M10 14L21 3"/></svg></a>`;
+            } else {
+              githubHtml = escapeHtml(bug.githubIssue);
+            }
+          }
+
+          // Fix task list for cross-links
+          let taskLinks = '';
+          if (bug.fixTasks.total > 0) {
+            taskLinks = bug.fixTasks.tasks.map(t =>
+              `<span class="task-id cross-link" data-cross-target="implement" data-cross-id="${t.id}" style="cursor:pointer;color:var(--color-accent);font-family:monospace;font-size:11px;">${t.id}</span>`
+            ).join(', ');
+          }
+
+          tableRows += `
+            <tr class="bug-row" data-bug-id="${bug.id}">
+              <td class="bug-id">${bug.id}</td>
+              <td><span class="severity-badge severity-${bug.severity}">${bug.severity}</span></td>
+              <td class="bug-status ${bug.status === 'fixed' ? 'fixed' : ''}">${bug.status}</td>
+              <td class="bug-progress">${progressText}${taskLinks ? '<br>' + taskLinks : ''}</td>
+              <td class="bug-description" title="${escapeHtml(bug.description || '')}">${escapeHtml(bug.description || '\u2014')}</td>
+              <td>${githubHtml}</td>
+            </tr>`;
+        }
+
+        // Orphaned tasks section (TS-020)
+        let orphanedHtml = '';
+        if (orphanedTasks && orphanedTasks.length > 0) {
+          orphanedHtml = `
+            <div class="orphaned-section">
+              <div class="orphaned-title">&#9888; Orphaned Fix Tasks (no matching bug in bugs.md)</div>
+              ${orphanedTasks.map(t => `
+                <div class="orphaned-task">
+                  <span class="task-id cross-link" data-cross-target="implement" data-cross-id="${t.id}" style="cursor:pointer;color:var(--color-accent);">${t.id}</span>
+                  [${t.bugTag}] ${escapeHtml(t.description)}
+                </div>
+              `).join('')}
+            </div>`;
+        }
+
+        contentArea.innerHTML = `
+          <div class="bugs-view">
+            <div class="bugs-view-header">
+              <div class="bugs-view-title">Bug Tracking</div>
+              <div class="bugs-view-subtitle">${summary.total} total &middot; ${summary.open} open &middot; ${summary.fixed} fixed</div>
+            </div>
+            <div class="cross-link-tip">Tip: ${CROSS_LINK_MOD_KEY}+click task IDs to navigate to the Implement board</div>
+            <table class="bugs-table" role="table" aria-label="Bug status table">
+              <thead>
+                <tr>
+                  <th>Bug ID</th>
+                  <th aria-sort="descending">Severity</th>
+                  <th>Status</th>
+                  <th>Fix Tasks</th>
+                  <th>Description</th>
+                  <th>GitHub</th>
+                </tr>
+              </thead>
+              <tbody>${tableRows}</tbody>
+            </table>
+            ${orphanedHtml}
+          </div>`;
+      }
+
+      // T016: Client-side GitHub URL resolution
+      function resolveGitHubUrl(issueRef, repoUrl) {
+        if (!issueRef || !repoUrl) return null;
+        const match = issueRef.match(/#(\d+)/);
+        if (!match) return null;
+        let base = repoUrl.replace(/\.git$/, '');
+        const ssh = base.match(/^git@([^:]+):(.+)$/);
+        if (ssh) base = 'https://' + ssh[1] + '/' + ssh[2];
+        return base + '/issues/' + match[1];
+      }
+
+      // T021: Highlight a bug row in the Bugs tab
+      function highlightBugsEntity(entityId) {
+        const row = contentArea.querySelector(`tr[data-bug-id="${entityId}"]`);
+        if (row) {
+          row.scrollIntoView({ behavior: 'smooth', block: 'center' });
+          row.classList.add('highlighted');
+          setTimeout(() => row.classList.remove('highlighted'), 2000);
+        }
+      }
+
       function renderPlaceholderView(phaseId) {
         const phaseNames = {
           constitution: 'Constitution', spec: 'Specification', clarify: 'Clarification',
@@ -3720,11 +4238,22 @@
 
       function renderClarifyContent(clarifications) {
         if (!clarifications.length) {
+          // TS-019/TS-020: Distinguish "clarify was run, no issues" from "never run"
+          const clarifyPhase = currentPipeline?.phases?.find(p => p.id === 'clarify');
+          const clarifyWasRun = clarifyPhase && (clarifyPhase.status === 'complete' || clarifyPhase.status === 'skipped');
+
+          const title = clarifyWasRun
+            ? 'Clarification Complete'
+            : 'Clarify Not Yet Run';
+          const text = clarifyWasRun
+            ? 'The clarification phase was completed with no ambiguities found. The specification is clear as written.'
+            : 'This is an optional phase. Run <code>/iikit-02-clarify</code> to identify and resolve ambiguities in the spec.';
+
           contentArea.innerHTML = `
             <div class="clarify-view" role="region" aria-label="Clarifications">
               <div class="clarify-empty">
-                <div class="placeholder-view-title">No Clarifications Recorded</div>
-                <div class="placeholder-view-text">This is an optional phase. The specification exists but no clarification sessions have been recorded. Run <code>/iikit-02-clarify</code> to identify and resolve ambiguities in the spec.</div>
+                <div class="placeholder-view-title">${title}</div>
+                <div class="placeholder-view-text">${text}</div>
               </div>
             </div>`;
           return;
@@ -4419,6 +4948,7 @@
             featureSelect.value = currentFeature;
             loadPipeline(currentFeature);
             loadBoard(currentFeature);
+            loadBugs(currentFeature);
           } else if (features.length === 0) {
             showEmptyState();
           }
@@ -4451,8 +4981,10 @@
           currentPlanView = null; // Reset plan view cache
           currentTestify = null; // Reset testify cache
           currentAnalyze = null; // Reset analyze cache
+          currentBugs = null; // Reset bugs cache
           loadPipeline(val);
           loadBoard(val);
+          loadBugs(val);
           // Resubscribe WebSocket
           if (ws && ws.readyState === WebSocket.OPEN) {
             ws.send(JSON.stringify({ type: 'subscribe', feature: val }));
@@ -4483,6 +5015,21 @@
         }
       }
 
+      async function loadBugs(featureId) {
+        try {
+          const res = await fetch(`/api/bugs/${featureId}`);
+          if (res.ok) {
+            currentBugs = await res.json();
+            // Update badge on pipeline bar
+            if (currentPipeline) renderPipeline(currentPipeline);
+            // If bugs view is active, re-render it
+            if (activeTab === 'bugs') renderBugsContent(currentBugs);
+          }
+        } catch {
+          // Silently fail — bugs are optional
+        }
+      }
+
       function showLoading() {
         boardEl.innerHTML = '<div class="loading"><div class="loading-spinner"></div></div>';
       }
@@ -4576,9 +5123,11 @@
         if (targetEl) renderBoardInto(targetEl, board);
       }
 
+      const BUG_SVG_ICON = '<svg class="bug-icon-inline" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M8 2l1.88 1.88M14.12 3.88L16 2M9 7.13v-1a3.003 3.003 0 116 0v1M12 20c-3.3 0-6-2.7-6-6v-3a4 4 0 014-4h4a4 4 0 014 4v3c0 3.3-2.7 6-6 6zM2 11h3M19 11h3M2 16h3M19 16h3"/></svg>';
+
       function createCardElement(card, columnKey) {
         const el = document.createElement('div');
-        el.className = 'card';
+        el.className = 'card' + (card.isBugCard ? ' bug-card' : '');
         el.setAttribute('data-card-id', card.id);
         el.setAttribute('role', 'article');
         el.setAttribute('aria-label', `${card.title} - ${card.priority} - ${card.progress} tasks complete`);
@@ -4590,10 +5139,14 @@
 
         const priorityClass = card.priority ? card.priority.toLowerCase() : 'p3';
 
+        const cardIdHtml = card.isBugCard
+          ? `<div class="card-id cross-link" data-cross-target="bugs" data-cross-id="${card.id}">${BUG_SVG_ICON}${card.id}</div>`
+          : `<div class="card-id cross-link" data-cross-target="spec" data-cross-id="${card.id}">${card.id}</div>`;
+
         el.innerHTML = `
-          <div class="card-id cross-link" data-cross-target="spec" data-cross-id="${card.id}">${card.id}</div>
+          ${cardIdHtml}
           <div class="card-header">
-            <div class="card-title" title="${escapeHtml(card.title)}">${escapeHtml(card.title)}</div>
+            <div class="card-title" title="${escapeHtml(card.title)}">${card.isBugCard ? BUG_SVG_ICON : ''}${escapeHtml(card.title)}</div>
             <span class="priority-badge ${priorityClass}" aria-label="Priority ${card.priority}">${card.priority}</span>
           </div>
           <div class="progress-container">
@@ -4610,13 +5163,19 @@
             ${(card.tasks || []).length} tasks
           </button>
           <ul class="task-list collapsed" id="tasks-${card.id}" aria-label="Tasks for ${card.id}">
-            ${(card.tasks || []).map(t => `
-              <li class="task-item ${t.checked ? 'checked' : ''}">
+            ${(card.tasks || []).map(t => {
+              const isBugTask = t.isBugFix || (t.id && t.id.startsWith('T-B'));
+              const taskIcon = isBugTask ? BUG_SVG_ICON : '';
+              const bugTagLink = t.bugTag
+                ? ` <span class="cross-link" data-cross-target="bugs" data-cross-id="${t.bugTag}" style="cursor:pointer;color:var(--color-accent);font-size:11px;">[${t.bugTag}]</span>`
+                : '';
+              return `
+              <li class="task-item ${t.checked ? 'checked' : ''}" data-task-id="${t.id}">
                 <span class="task-checkbox ${t.checked ? 'checked' : ''}" aria-hidden="true"></span>
-                <span class="task-id cross-link" data-cross-target="testify" data-cross-id="${t.id}">${t.id}</span>
+                ${taskIcon}<span class="task-id cross-link" data-cross-target="testify" data-cross-id="${t.id}">${t.id}</span>${bugTagLink}
                 <span class="task-description">${escapeHtml(t.description)}</span>
-              </li>
-            `).join('')}
+              </li>`;
+            }).join('')}
           </ul>`;
 
         return el;
@@ -5126,6 +5685,16 @@
             }
             break;
 
+          case 'bugs_update':
+            if (msg.feature === currentFeature && msg.bugs) {
+              currentBugs = msg.bugs;
+              if (currentPipeline) renderPipeline(currentPipeline);
+              if (activeTab === 'bugs') {
+                renderBugsContent(msg.bugs);
+              }
+            }
+            break;
+
           case 'features_update':
             if (msg.features) {
               updateFeatureSelector(msg.features);

package/src/server.js

@@ -15,6 +15,7 @@ const { computePlanViewState } = require('./planview');
 const { computeChecklistViewState } = require('./checklist');
 const { computeTestifyState } = require('./testify');
 const { computeAnalyzeState } = require('./analyze');
+const { computeBugsState } = require('./bugs');
 
 /**
  * List features from specs/ directory.
@@ -245,6 +246,20 @@ function createServer({ projectPath, port = 3000 }) {
     }
   });
 
+  // API: bugs state for a feature
+  app.get('/api/bugs/:feature', (req, res) => {
+    try {
+      const featureDir = path.join(projectPath, 'specs', req.params.feature);
+      if (!fs.existsSync(featureDir)) {
+        return res.status(404).json({ error: 'Feature not found' });
+      }
+      const bugs = computeBugsState(projectPath, req.params.feature);
+      res.json(bugs);
+    } catch (err) {
+      res.status(500).json({ error: err.message });
+    }
+  });
+
   // API: board state for a feature
   app.get('/api/board/:feature', (req, res) => {
     try {
@@ -358,6 +373,14 @@ function createServer({ projectPath, port = 3000 }) {
                   analyze
                 }));
               }
+              const bugs = computeBugsState(projectPath, ws.currentFeature);
+              if (bugs) {
+                ws.send(JSON.stringify({
+                  type: 'bugs_update',
+                  feature: ws.currentFeature,
+                  bugs
+                }));
+              }
             } catch {
               // ignore errors during push
             }