iikit-dashboard 1.0.0 → 1.2.0

package/README.md

@@ -2,27 +2,21 @@
 
 **Watch your AI agent develop features in real time.**
 
-A browser-based dashboard for [Intent Integrity Kit](https://github.com/intent-integrity-chain/kit) projects. Visualizes every phase of the IIKit workflow — from constitution principles through specification, planning, and implementation — with live updates as artifacts change on disk.
+A browser-based dashboard for [Intent Integrity Kit (IIKit)](https://github.com/intent-integrity-chain/kit) projects. IIKit is a specification-driven development framework that guides AI agents through a structured workflow — from governance constitution through specification, clarification, planning, testing, and implementation. The dashboard visualizes every phase of that workflow with live updates as artifacts change on disk.
 
 ## Usage
 
-```bash
-# Run in your IIKit project directory
-npx iikit-dashboard
-
-# Or specify a project path
-npx iikit-dashboard /path/to/your/project
-```
-
-The dashboard opens at `http://localhost:3000`.
+The dashboard launches automatically early in the IIKit workflow — no manual setup needed.
 
-## Setup
+You can also start it standalone to browse historical data for any project that has feature specs:
 
 ```bash
-npm install
-tessl install   # installs tile dependencies (like npm install for tiles)
+npx iikit-dashboard              # current directory
+npx iikit-dashboard /path/to/project   # specific project
 ```
 
+The dashboard opens at `http://localhost:3000`.
+
 ## Views
 
 The pipeline bar at the top shows all nine IIKit workflow phases. Click any phase to see its visualization:
@@ -33,7 +27,7 @@ The pipeline bar at the top shows all nine IIKit workflow phases. Click any phas
 | **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 |
-| **Checklist** | *Coming soon* |
+| **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* |
@@ -58,19 +52,16 @@ The server reads directly from your project's `specs/` directory:
 | `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.
 
-## Integration with IIKit
-
-When you run `/iikit-08-implement`, the implement skill automatically launches the dashboard in the background. No manual setup needed.
-
 ## Requirements
 
 - Node.js 18+
-- An IIKit project with a `specs/` directory
+- A project with a `specs/` directory containing IIKit feature artifacts
 
 ## License
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "iikit-dashboard",
-  "version": "1.0.0",
-  "description": "IIKit Dashboard — real-time visualization for Intent Integrity Kit projects",
+  "version": "1.2.0",
+  "description": "Real-time dashboard for Intent Integrity Kit (IIKit) — visualizes every phase of specification-driven AI development",
   "main": "src/server.js",
   "bin": {
     "iikit-dashboard": "bin/iikit-dashboard.js"

package/src/checklist.js

@@ -0,0 +1,68 @@
+'use strict';
+
+const path = require('path');
+const { parseChecklistsDetailed } = require('./parser');
+
+/**
+ * Map a percentage (0-100) to a color bracket.
+ * @param {number} percentage
+ * @returns {string} "red" | "yellow" | "green"
+ */
+function percentageToColor(percentage) {
+  if (percentage <= 33) return 'red';
+  if (percentage <= 66) return 'yellow';
+  return 'green';
+}
+
+/**
+ * Compute gate status from an array of file objects with percentage fields.
+ * Uses worst-case precedence: red if any at 0%, yellow if all 1-99%, green if all 100%.
+ *
+ * @param {Array<{percentage: number}>} files
+ * @returns {{status: string, level: string, label: string}}
+ */
+function computeGateStatus(files) {
+  if (files.length === 0) {
+    return { status: 'blocked', level: 'red', label: 'GATE: BLOCKED' };
+  }
+
+  const anyAtZero = files.some(f => f.percentage === 0);
+  if (anyAtZero) {
+    return { status: 'blocked', level: 'red', label: 'GATE: BLOCKED' };
+  }
+
+  const allComplete = files.every(f => f.percentage === 100);
+  if (allComplete) {
+    return { status: 'open', level: 'green', label: 'GATE: OPEN' };
+  }
+
+  return { status: 'blocked', level: 'yellow', label: 'GATE: BLOCKED' };
+}
+
+/**
+ * Compute checklist view state for a feature.
+ * Returns per-file detail with items, percentage, color, and aggregate gate status.
+ *
+ * @param {string} projectPath - Path to the project root
+ * @param {string} featureId - Feature directory name (e.g., "001-kanban-board")
+ * @returns {{files: Array, gate: {status: string, level: string, label: string}}}
+ */
+function computeChecklistViewState(projectPath, featureId) {
+  const checklistDir = path.join(projectPath, 'specs', featureId, 'checklists');
+  const parsed = parseChecklistsDetailed(checklistDir);
+
+  const files = parsed.map(file => {
+    const percentage = file.total > 0 ? Math.round((file.checked / file.total) * 100) : 0;
+    return {
+      ...file,
+      percentage,
+      color: percentageToColor(percentage)
+    };
+  });
+
+  const gate = computeGateStatus(files);
+
+  return { files, gate };
+}
+
+module.exports = { computeChecklistViewState };

package/src/parser.js

@@ -115,6 +115,96 @@ function parseChecklists(checklistDir) {
   return result;
 }
 
+/**
+ * Parse all checklist files in a directory and return detailed per-file data
+ * with individual items, categories, CHK IDs, and tags.
+ *
+ * Applies same requirements.md-only filter as parseChecklists:
+ * if requirements.md is the only file, returns empty array.
+ *
+ * @param {string} checklistDir - Path to checklists/ directory
+ * @returns {Array<{name: string, filename: string, total: number, checked: number, items: Array}>}
+ */
+function parseChecklistsDetailed(checklistDir) {
+  if (!fs.existsSync(checklistDir)) return [];
+
+  const files = fs.readdirSync(checklistDir).filter(f => f.endsWith('.md'));
+
+  // Same filter as parseChecklists: skip if requirements.md is the only file
+  const hasDomainChecklists = files.some(f => f !== 'requirements.md');
+  if (!hasDomainChecklists) return [];
+
+  const result = [];
+
+  for (const file of files) {
+    const content = fs.readFileSync(path.join(checklistDir, file), 'utf-8');
+    const lines = content.split('\n');
+
+    // Derive human-readable name from filename
+    const baseName = file.replace(/\.md$/, '');
+    const name = baseName.split('-').map(w => w.charAt(0).toUpperCase() + w.slice(1)).join(' ');
+
+    const items = [];
+    let currentCategory = null;
+    let totalCount = 0;
+    let checkedCount = 0;
+
+    for (const line of lines) {
+      // Track category headings (## or ###)
+      const headingMatch = line.match(/^#{2,3}\s+(.+)/);
+      if (headingMatch) {
+        currentCategory = headingMatch[1].trim();
+        continue;
+      }
+
+      // Parse checkbox items
+      const checkboxMatch = line.match(/^- \[([ x])\]\s+(.*)/i);
+      if (!checkboxMatch) continue;
+
+      const isChecked = checkboxMatch[1].toLowerCase() === 'x';
+      let itemText = checkboxMatch[2].trim();
+      totalCount++;
+      if (isChecked) checkedCount++;
+
+      // Extract CHK-xxx ID
+      let chkId = null;
+      const chkMatch = itemText.match(/^(CHK-\d{3})\s+/);
+      if (chkMatch) {
+        chkId = chkMatch[1];
+        itemText = itemText.substring(chkMatch[0].length);
+      }
+
+      // Extract trailing tags [tag1] [tag2] — but not the checkbox itself
+      const tags = [];
+      const tagRegex = /\[([^\]]+)\]\s*$/;
+      let tagMatch;
+      while ((tagMatch = itemText.match(tagRegex))) {
+        // Don't treat spec references like [Completeness, FR-004] as simple tags
+        tags.unshift(tagMatch[1]);
+        itemText = itemText.substring(0, tagMatch.index).trim();
+      }
+
+      items.push({
+        text: itemText,
+        checked: isChecked,
+        chkId,
+        category: currentCategory,
+        tags
+      });
+    }
+
+    result.push({
+      name,
+      filename: file,
+      total: totalCount,
+      checked: checkedCount,
+      items
+    });
+  }
+
+  return result;
+}
+
 /**
  * Parse CONSTITUTION.md to determine if TDD is required.
  * Looks for strong TDD indicators combined with MUST/NON-NEGOTIABLE.
@@ -765,4 +855,83 @@ function parseResearchDecisions(content) {
   return decisions;
 }
 
-module.exports = { parseSpecStories, parseTasks, parseChecklists, parseConstitutionTDD, hasClarifications, parseConstitutionPrinciples, parseRequirements, parseSuccessCriteria, parseClarifications, parseStoryRequirementRefs, parseTechContext, parseFileStructure, parseAsciiDiagram, parseTesslJson, parseResearchDecisions };
+/**
+ * Parse tests/test-specs.md to extract test specification entries.
+ * Pattern: ### TS-XXX: Title, then **Type**: value, **Priority**: value, **Traceability**: refs
+ *
+ * @param {string} content - Raw markdown content of test-specs.md
+ * @returns {Array<{id: string, title: string, type: string, priority: string, traceability: string[]}>}
+ */
+function parseTestSpecs(content) {
+  if (!content || typeof content !== 'string') return [];
+
+  const specs = [];
+  const headingRegex = /### TS-(\d+): (.+)/g;
+  const headingStarts = [];
+  let match;
+
+  while ((match = headingRegex.exec(content)) !== null) {
+    headingStarts.push({
+      id: `TS-${match[1]}`,
+      title: match[2].trim(),
+      index: match.index
+    });
+  }
+
+  for (let i = 0; i < headingStarts.length; i++) {
+    const start = headingStarts[i].index;
+    const end = i + 1 < headingStarts.length ? headingStarts[i + 1].index : content.length;
+    const section = content.substring(start, end);
+
+    // Extract type
+    const typeMatch = section.match(/\*\*Type\*\*:\s*(acceptance|contract|validation)/);
+    const type = typeMatch ? typeMatch[1] : 'validation';
+
+    // Extract priority
+    const priorityMatch = section.match(/\*\*Priority\*\*:\s*(P\d+)/);
+    const priority = priorityMatch ? priorityMatch[1] : 'P3';
+
+    // Extract traceability — comma-separated IDs, filter to FR-/SC- only
+    let traceability = [];
+    const traceMatch = section.match(/\*\*Traceability\*\*:\s*(.+)/);
+    if (traceMatch) {
+      traceability = traceMatch[1]
+        .split(/,\s*/)
+        .map(s => s.trim())
+        .filter(s => /^(FR|SC)-\d+$/.test(s));
+    }
+
+    specs.push({
+      id: headingStarts[i].id,
+      title: headingStarts[i].title,
+      type,
+      priority,
+      traceability
+    });
+  }
+
+  return specs;
+}
+
+/**
+ * Extract "must pass TS-xxx" references from already-parsed task descriptions.
+ *
+ * @param {Array<{id: string, description: string}>} tasks - Parsed tasks array
+ * @returns {Object<string, string[]>} Map of taskId to testSpecIds array
+ */
+function parseTaskTestRefs(tasks) {
+  if (!tasks || !Array.isArray(tasks)) return {};
+
+  const refs = {};
+  for (const task of tasks) {
+    const match = task.description ? task.description.match(/must pass ((?:TS-\d+(?:,\s*)?)+)/) : null;
+    if (match) {
+      refs[task.id] = match[1].split(/,\s*/).map(s => s.trim()).filter(Boolean);
+    } else {
+      refs[task.id] = [];
+    }
+  }
+  return refs;
+}
+
+module.exports = { parseSpecStories, parseTasks, parseChecklists, parseChecklistsDetailed, parseConstitutionTDD, hasClarifications, parseConstitutionPrinciples, parseRequirements, parseSuccessCriteria, parseClarifications, parseStoryRequirementRefs, parseTechContext, parseFileStructure, parseAsciiDiagram, parseTesslJson, parseResearchDecisions, parseTestSpecs, parseTaskTestRefs };