iikit-dashboard 1.0.0

package/README.md

@@ -0,0 +1,77 @@
+# IIKit Dashboard
+
+**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.
+
+## 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`.
+
+## Setup
+
+```bash
+npm install
+tessl install   # installs tile dependencies (like npm install for tiles)
+```
+
+## Views
+
+The pipeline bar at the top shows all nine IIKit workflow phases. Click any phase to see its visualization:
+
+| 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 |
+| **Checklist** | *Coming soon* |
+| **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 |
+
+## 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
+- **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
+- **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:
+
+| 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 |
+| `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
+
+## License
+
+MIT

package/bin/iikit-dashboard.js

@@ -0,0 +1,68 @@
+#!/usr/bin/env node
+'use strict';
+
+const path = require('path');
+const { createServer } = require('../src/server');
+
+// Parse arguments
+const args = process.argv.slice(2);
+let projectPath = process.cwd();
+let port = 3000;
+
+for (let i = 0; i < args.length; i++) {
+  if (args[i] === '--path' && args[i + 1]) {
+    projectPath = path.resolve(args[i + 1]);
+    i++;
+  } else if (args[i] === '--port' && args[i + 1]) {
+    port = parseInt(args[i + 1], 10);
+    i++;
+  } else if (!args[i].startsWith('--')) {
+    // Positional argument = project path
+    projectPath = path.resolve(args[i]);
+  }
+}
+
+async function main() {
+  console.log(`\n  IIKit Dashboard`);
+  console.log(`  ===============\n`);
+  console.log(`  Project: ${projectPath}`);
+
+  try {
+    const result = await createServer({ projectPath, port });
+    const url = `http://localhost:${result.port}`;
+    console.log(`  Server:  ${url}`);
+    console.log(`\n  Open your browser to view the dashboard.\n`);
+
+    // Try to open browser (best effort, don't fail if it doesn't work)
+    try {
+      const { exec } = require('child_process');
+      const cmd = process.platform === 'darwin' ? 'open' :
+                  process.platform === 'win32' ? 'start' : 'xdg-open';
+      exec(`${cmd} ${url}`);
+    } catch {
+      // Ignore browser open errors
+    }
+
+    // Handle graceful shutdown
+    process.on('SIGINT', () => {
+      console.log('\n  Shutting down...');
+      result.server.close(() => {
+        if (result.watcher) result.watcher.close();
+        process.exit(0);
+      });
+    });
+
+    process.on('SIGTERM', () => {
+      result.server.close(() => {
+        if (result.watcher) result.watcher.close();
+        process.exit(0);
+      });
+    });
+
+  } catch (err) {
+    console.error(`  Error: ${err.message}`);
+    process.exit(1);
+  }
+}
+
+main();

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "iikit-dashboard",
+  "version": "1.0.0",
+  "description": "IIKit Dashboard — real-time visualization for Intent Integrity Kit projects",
+  "main": "src/server.js",
+  "bin": {
+    "iikit-dashboard": "bin/iikit-dashboard.js"
+  },
+  "files": [
+    "bin/",
+    "src/"
+  ],
+  "scripts": {
+    "start": "node bin/iikit-dashboard.js",
+    "test": "jest --forceExit"
+  },
+  "keywords": [
+    "iikit",
+    "intent-integrity",
+    "dashboard",
+    "specification",
+    "kanban",
+    "pipeline",
+    "tdd",
+    "live-updates"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/intent-integrity-chain/iikit-dashboard"
+  },
+  "author": "Baruch Sadogursky",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "@anthropic-ai/sdk": "^0.74.0",
+    "chokidar": "^3.6.0",
+    "express": "^5.2.1",
+    "ws": "^8.19.0"
+  },
+  "devDependencies": {
+    "jest": "^30.2.0"
+  }
+}

package/src/board.js

@@ -0,0 +1,93 @@
+'use strict';
+
+/**
+ * Compute board state: assign stories to todo/in_progress/done columns
+ * based on their task completion status.
+ *
+ * Column assignment rules (from data-model.md):
+ * - todo: all tasks unchecked (or no tasks)
+ * - in_progress: at least 1 task checked but not all
+ * - done: all tasks checked
+ *
+ * @param {Array<{id: string, title: string, priority: string}>} stories
+ * @param {Array<{id: string, storyTag: string|null, description: string, checked: boolean}>} tasks
+ * @returns {{todo: Array, in_progress: Array, done: Array}}
+ */
+function computeBoardState(stories, tasks) {
+  const board = { todo: [], in_progress: [], done: [] };
+
+  if (!stories || !Array.isArray(stories)) return board;
+  if (!tasks) tasks = [];
+
+  // Group tasks by storyTag
+  const tasksByStory = {};
+  const untaggedTasks = [];
+
+  for (const task of tasks) {
+    if (task.storyTag) {
+      if (!tasksByStory[task.storyTag]) {
+        tasksByStory[task.storyTag] = [];
+      }
+      tasksByStory[task.storyTag].push(task);
+    } else {
+      untaggedTasks.push(task);
+    }
+  }
+
+  // Assign each story to a column
+  for (const story of stories) {
+    const storyTasks = tasksByStory[story.id] || [];
+    const checkedCount = storyTasks.filter(t => t.checked).length;
+    const totalCount = storyTasks.length;
+
+    let column;
+    if (totalCount === 0 || checkedCount === 0) {
+      column = 'todo';
+    } else if (checkedCount === totalCount) {
+      column = 'done';
+    } else {
+      column = 'in_progress';
+    }
+
+    const card = {
+      id: story.id,
+      title: story.title,
+      priority: story.priority,
+      tasks: storyTasks,
+      progress: `${checkedCount}/${totalCount}`,
+      column
+    };
+
+    board[column].push(card);
+  }
+
+  // Handle untagged tasks — put them in an "Unassigned" card
+  if (untaggedTasks.length > 0) {
+    const checkedCount = untaggedTasks.filter(t => t.checked).length;
+    const totalCount = untaggedTasks.length;
+
+    let column;
+    if (checkedCount === 0) {
+      column = 'todo';
+    } else if (checkedCount === totalCount) {
+      column = 'done';
+    } else {
+      column = 'in_progress';
+    }
+
+    const card = {
+      id: 'Unassigned',
+      title: 'Unassigned Tasks',
+      priority: 'P3',
+      tasks: untaggedTasks,
+      progress: `${checkedCount}/${totalCount}`,
+      column
+    };
+
+    board[column].push(card);
+  }
+
+  return board;
+}
+
+module.exports = { computeBoardState };

package/src/integrity.js

@@ -0,0 +1,63 @@
+'use strict';
+
+const crypto = require('crypto');
+
+/**
+ * Extract Given/When/Then lines from test-specs.md,
+ * normalize whitespace, sort, and compute SHA256 hash.
+ *
+ * @param {string} content - Raw content of test-specs.md
+ * @returns {string|null} SHA256 hex hash, or null if no assertions found
+ */
+function computeAssertionHash(content) {
+  if (!content || typeof content !== 'string') return null;
+
+  const lines = content.split('\n');
+  const assertionLines = [];
+
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (
+      trimmed.startsWith('**Given**:') ||
+      trimmed.startsWith('**When**:') ||
+      trimmed.startsWith('**Then**:')
+    ) {
+      // Normalize whitespace: collapse multiple spaces to single space
+      const normalized = trimmed.replace(/\s+/g, ' ').trim();
+      assertionLines.push(normalized);
+    }
+  }
+
+  if (assertionLines.length === 0) return null;
+
+  // Sort for deterministic ordering
+  assertionLines.sort();
+
+  const joined = assertionLines.join('\n');
+  return crypto.createHash('sha256').update(joined, 'utf8').digest('hex');
+}
+
+/**
+ * Compare current assertion hash against stored hash.
+ *
+ * @param {string|null} currentHash - Hash computed from current test-specs.md
+ * @param {string|null} storedHash - Hash from context.json
+ * @returns {{status: string, currentHash: string|null, storedHash: string|null}}
+ */
+function checkIntegrity(currentHash, storedHash) {
+  if (!currentHash || !storedHash) {
+    return {
+      status: 'missing',
+      currentHash: currentHash || null,
+      storedHash: storedHash || null
+    };
+  }
+
+  return {
+    status: currentHash === storedHash ? 'valid' : 'tampered',
+    currentHash,
+    storedHash
+  };
+}
+
+module.exports = { computeAssertionHash, checkIntegrity };