iikit-dashboard 1.4.0 → 1.5.1

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/bin/iikit-dashboard.js

@@ -2,11 +2,11 @@
 'use strict';
 
 const path = require('path');
-const { createServer } = require('../src/server');
+const { createServer, removePidfile } = require('../src/server');
 
 // Parse arguments
 const args = process.argv.slice(2);
-let projectPath = process.cwd();
+let projectPath = path.resolve(process.cwd());
 let port = 3000;
 
 for (let i = 0; i < args.length; i++) {
@@ -46,6 +46,7 @@ async function main() {
     // Handle graceful shutdown
     process.on('SIGINT', () => {
       console.log('\n  Shutting down...');
+      removePidfile(projectPath);
       result.server.close(() => {
         if (result.watcher) result.watcher.close();
         process.exit(0);
@@ -53,6 +54,7 @@ async function main() {
     });
 
     process.on('SIGTERM', () => {
+      removePidfile(projectPath);
       result.server.close(() => {
         if (result.watcher) result.watcher.close();
         process.exit(0);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "iikit-dashboard",
-  "version": "1.4.0",
+  "version": "1.5.1",
   "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/public/index.html

@@ -93,6 +93,17 @@
       flex: 1 1 auto;
     }
 
+    .project-label {
+      font-size: 12px;
+      color: var(--color-text-muted);
+      max-width: 160px;
+      overflow: hidden;
+      text-overflow: ellipsis;
+      white-space: nowrap;
+      border-left: 1px solid var(--color-border);
+      padding-left: 12px;
+    }
+
     .feature-selector {
       position: relative;
       min-width: 100px;
@@ -713,8 +724,7 @@
       border-radius: var(--radius-md);
       cursor: pointer;
       transition: background var(--transition-fast), transform var(--transition-fast);
-      flex: 0 1 96px;
-      width: 96px;
+      flex: 0 1 auto;
       min-width: 40px;
       position: relative;
       border: 1px solid var(--color-border-subtle);
@@ -2368,6 +2378,7 @@
         <div class="logo-icon" aria-hidden="true">D</div>
         <span>IIKit Dashboard</span>
       </div>
+      <div class="project-label" id="projectLabel" title=""></div>
       <div class="feature-selector" role="navigation" aria-label="Feature selector">
         <select id="featureSelect" aria-label="Select feature to display" tabindex="0">
           <option value="">Loading features...</option>
@@ -5188,6 +5199,12 @@
       applyTheme(themeMode);
 
       // ====== Init ======
+      fetch('/api/meta').then(r => r.json()).then(meta => {
+        const label = document.getElementById('projectLabel');
+        const dirName = meta.projectPath.split('/').pop();
+        label.textContent = dirName;
+        label.title = meta.projectPath;
+      }).catch(() => {});
       loadFeatures();
       connectWebSocket();
     })();

package/src/server.js

@@ -98,6 +98,33 @@ function getBoardState(projectPath, featureId) {
   return { ...board, integrity };
 }
 
+/**
+ * Write a pidfile with metadata so external scripts can identify this dashboard instance.
+ */
+function writePidfile(projectPath, port) {
+  const resolved = path.resolve(projectPath);
+  const specifyDir = path.join(resolved, '.specify');
+  fs.mkdirSync(specifyDir, { recursive: true });
+  const pidData = {
+    pid: process.pid,
+    port,
+    directory: resolved,
+    startedAt: new Date().toISOString()
+  };
+  fs.writeFileSync(path.join(specifyDir, 'dashboard.pid.json'), JSON.stringify(pidData, null, 2));
+}
+
+/**
+ * Remove the pidfile on shutdown.
+ */
+function removePidfile(projectPath) {
+  try {
+    fs.unlinkSync(path.join(path.resolve(projectPath), '.specify', 'dashboard.pid.json'));
+  } catch (err) {
+    if (err.code !== 'ENOENT') throw err;
+  }
+}
+
 /**
  * Create and configure the Express server with WebSocket support.
  *
@@ -107,11 +134,17 @@ function getBoardState(projectPath, featureId) {
  * @returns {Promise<{server: http.Server, port: number, wss: WebSocketServer}>}
  */
 function createServer({ projectPath, port = 3000 }) {
+  const resolvedPath = path.resolve(projectPath);
   const app = express();
 
   // Serve static files from src/public
   app.use(express.static(path.join(__dirname, 'public')));
 
+  // API: project metadata
+  app.get('/api/meta', (req, res) => {
+    res.json({ projectPath: resolvedPath });
+  });
+
   // API: list features
   app.get('/api/features', (req, res) => {
     try {
@@ -363,9 +396,10 @@ function createServer({ projectPath, port = 3000 }) {
   return new Promise((resolve) => {
     server.listen(port, () => {
       const actualPort = server.address().port;
-      resolve({ server, port: actualPort, wss, watcher });
+      writePidfile(resolvedPath, actualPort);
+      resolve({ server, port: actualPort, wss, watcher, projectPath: resolvedPath });
     });
   });
 }
 
-module.exports = { createServer, listFeatures, getBoardState };
+module.exports = { createServer, listFeatures, getBoardState, removePidfile };