declare-cc 0.5.0 → 0.5.3

package/bin/install.js

@@ -1567,6 +1567,9 @@ function install(isGlobal, runtime = 'claude') {
   const activityCommand = isGlobal
     ? buildHookCommand(targetDir, 'declare-activity.js')
     : 'node ' + dirName + '/hooks/declare-activity.js';
+  const serverCommand = isGlobal
+    ? buildHookCommand(targetDir, 'declare-server.js')
+    : 'node ' + dirName + '/hooks/declare-server.js';
 
   // Enable experimental agents for Gemini CLI (required for custom sub-agents)
   if (isGemini) {
@@ -1594,16 +1597,22 @@ function install(isGlobal, runtime = 'claude') {
 
     if (!hasGsdUpdateHook) {
       settings.hooks.SessionStart.push({
-        hooks: [
-          {
-            type: 'command',
-            command: updateCheckCommand
-          }
-        ]
+        hooks: [{ type: 'command', command: updateCheckCommand }]
       });
       console.log(`  ${green}✓${reset} Configured update check hook`);
     }
 
+    // Dashboard server hook — starts/restarts server for this project on SessionStart
+    const hasServerHook = settings.hooks.SessionStart.some(entry =>
+      entry.hooks && entry.hooks.some(h => h.command && h.command.includes('declare-server'))
+    );
+    if (!hasServerHook) {
+      settings.hooks.SessionStart.push({
+        hooks: [{ type: 'command', command: serverCommand }]
+      });
+      console.log(`  ${green}✓${reset} Configured dashboard server hook`);
+    }
+
     // Configure PreToolUse + PostToolUse hooks for activity feed (Claude Code only)
     if (!isOpencode && !isGemini) {
       if (!settings.hooks.PreToolUse)  settings.hooks.PreToolUse  = [];

package/commands/declare/dashboard.md

@@ -6,71 +6,60 @@ allowed-tools:
 
 Open the Declare interactive DAG dashboard — a live web UI showing declarations, milestones, and actions as a navigable graph.
 
-**Step 1: Check if the server is already running.**
+**Step 1: Resolve the port for this project.**
+
+Each project gets its own stable port derived from the project path. Check if it's already been assigned:
 
 ```bash
-curl -sf http://localhost:3847/api/graph -o /dev/null && echo "RUNNING" || echo "NOT_RUNNING"
+cat .planning/server.port 2>/dev/null || echo "NOT_SET"
 ```
 
-**Step 2: Start the server if it is not running.**
+If a port file exists, use that port. If not, the SessionStart hook hasn't fired yet — use the default port 3847 and set PORT to it.
 
-If the output from Step 1 is `NOT_RUNNING`:
+```bash
+PORT=$(cat .planning/server.port 2>/dev/null || echo "3847")
+echo "PORT=$PORT"
+```
 
-Start the server in the background, capturing its PID:
+**Step 2: Check if the server is already running on that port.**
 
 ```bash
-nohup node dist/declare-tools.cjs serve --port 3847 > /tmp/declare-dashboard.log 2>&1 &
-echo $!
+curl -sf http://localhost:${PORT}/api/graph -o /dev/null && echo "RUNNING" || echo "NOT_RUNNING"
 ```
 
-Then wait briefly and confirm it started:
+**Step 3: Start the server if it is not running.**
+
+If `NOT_RUNNING`:
 
 ```bash
-sleep 1 && curl -sf http://localhost:3847/api/graph -o /dev/null && echo "STARTED" || echo "FAILED"
+nohup node dist/declare-tools.cjs serve --port ${PORT} > /tmp/declare-dashboard.log 2>&1 &
+sleep 1 && curl -sf http://localhost:${PORT}/api/graph -o /dev/null && echo "STARTED" || echo "FAILED"
 ```
 
-If the result is `FAILED`, report the error and show the last lines of the log:
-
+If `FAILED`:
 ```bash
 tail -20 /tmp/declare-dashboard.log
 ```
 
-**Step 3: Open the dashboard in the browser.**
-
-Detect the OS and open the URL:
+**Step 4: Open the dashboard in the browser.**
 
 ```bash
 if [[ "$OSTYPE" == "darwin"* ]]; then
-  open http://localhost:3847
+  open http://localhost:${PORT}
 else
-  xdg-open http://localhost:3847 2>/dev/null || echo "Visit http://localhost:3847 in your browser"
+  xdg-open http://localhost:${PORT} 2>/dev/null || echo "Visit http://localhost:${PORT} in your browser"
 fi
 ```
 
-**Step 4: Confirm to the user.**
-
-Show the user:
-
-```
-Dashboard running at http://localhost:3847
-
-The graph auto-refreshes every 5 seconds.
-Click any node to inspect its details.
+**Step 5: Confirm to the user.**
 
-Server log: /tmp/declare-dashboard.log
-To stop:    kill <PID>
 ```
+Dashboard running at http://localhost:[PORT]
 
-Where `<PID>` is the process ID captured in Step 2 (or a reminder to find it with `lsof -ti :3847`).
-
-If the server was already running (Step 1 returned `RUNNING`), say "Server was already running."
+The graph updates live as agents run and files change.
+Click any node to inspect details and exec-plan.
 
-**Step 5: Tail server output (optional).**
-
-If `$ARGUMENTS` contains `--tail` or `--log`:
-
-```bash
-tail -f /tmp/declare-dashboard.log
+To stop: kill $(lsof -ti :[PORT])
 ```
 
-Otherwise, skip this step.
+If the server was already running (Step 2 returned `RUNNING`), say "Server was already running."

package/dist/declare-tools.cjs

@@ -1329,7 +1329,7 @@ var require_help = __commonJS({
             usage: "/declare:help"
           }
         ],
-        version: "0.4.7"
+        version: "0.5.2"
       };
     }
     module2.exports = { runHelp: runHelp2 };
@@ -2987,6 +2987,13 @@ var require_sync_status = __commonJS({
             actionResults.push({ id: action.id, milestone: m.id, changed: false, reason: "already DONE" });
             continue;
           }
+          const summaryPath = join(folderPath, `${action.id}-SUMMARY.md`);
+          if (existsSync(summaryPath)) {
+            planContent = updateActionStatus(planContent, action.id, "DONE");
+            planDirty = true;
+            actionResults.push({ id: action.id, milestone: m.id, changed: true, reason: "SUMMARY.md exists" });
+            continue;
+          }
           if (milestoneAlreadyDone) {
             planContent = updateActionStatus(planContent, action.id, "DONE");
             planDirty = true;

package/dist/public/app.js

@@ -203,24 +203,103 @@ function renderStatusBar() {
 
 // ─── Node element builder ─────────────────────────────────────────────────────
 
+const COMPLETED = new Set(['DONE','KEPT','HONORED']);
+const IN_PROGRESS_STORED = new Set(['ACTIVE']);
+
+/**
+ * Compute derived workflow status for a milestone from its action statuses.
+ * This overrides the stored MILESTONES.md status so the dashboard always
+ * reflects reality even if sync-status hasn't been called.
+ *
+ * @param {{ id: string, status: string, hasPlan: boolean }} milestone
+ * @param {Array<{ id: string, status: string, causes: string[] }>} allActions
+ * @returns {{ displayStatus: string, doneCount: number, totalCount: number }}
+ */
+function deriveMilestoneStatus(milestone, allActions) {
+  // Authoritative integrity/terminal states — always trust these
+  if (['KEPT','HONORED','BROKEN','RENEGOTIATED'].includes(milestone.status)) {
+    const myActions = allActions.filter(a => (a.causes||[]).includes(milestone.id));
+    return { displayStatus: milestone.status, doneCount: myActions.filter(a=>COMPLETED.has(a.status)).length, totalCount: myActions.length };
+  }
+
+  const myActions = allActions.filter(a => (a.causes||[]).includes(milestone.id));
+  const doneCount  = myActions.filter(a => COMPLETED.has(a.status)).length;
+  const totalCount = myActions.length;
+
+  let displayStatus;
+  if (totalCount === 0) {
+    displayStatus = milestone.hasPlan ? 'PLANNED' : 'PENDING';
+  } else if (doneCount === totalCount) {
+    displayStatus = 'DONE';
+  } else if (doneCount > 0) {
+    displayStatus = 'EXECUTING';
+  } else {
+    displayStatus = 'PLANNED';
+  }
+
+  return { displayStatus, doneCount, totalCount };
+}
+
+/**
+ * Compute derived workflow status for a declaration from its milestone statuses.
+ * @param {{ id: string, status: string, milestones: string[] }} declaration
+ * @param {Array<{ id: string, displayStatus: string }>} enrichedMilestones
+ * @returns {string}
+ */
+function deriveDeclarationStatus(declaration, enrichedMilestones) {
+  if (['KEPT','HONORED','BROKEN','RENEGOTIATED'].includes(declaration.status)) return declaration.status;
+
+  const myMilestones = enrichedMilestones.filter(m => (declaration.milestones||[]).includes(m.id));
+  if (myMilestones.length === 0) return 'PENDING';
+
+  const doneCount     = myMilestones.filter(m => COMPLETED.has(m.displayStatus)).length;
+  const executingCount = myMilestones.filter(m => m.displayStatus === 'EXECUTING').length;
+  const plannedCount  = myMilestones.filter(m => m.displayStatus === 'PLANNED').length;
+
+  if (doneCount === myMilestones.length) return 'DONE';
+  if (executingCount > 0 || doneCount > 0) return 'EXECUTING';
+  if (plannedCount > 0) return 'PLANNED';
+  return 'PENDING';
+}
+
 /**
  * Build a node DOM element.
- * @param {{ id: string, title?: string, statement?: string, status?: string }} item
+ * @param {object} item
  * @param {'declaration'|'milestone'|'action'} type
+ * @param {{ displayStatus?: string, doneCount?: number, totalCount?: number }} [derived]
  * @returns {HTMLElement}
  */
-function buildNodeEl(item, type) {
+function buildNodeEl(item, type, derived = {}) {
+  const displayStatus = derived.displayStatus || item.status || 'PENDING';
   const el = document.createElement('div');
-  el.className = `node node-${type} status-${statusClass(item.status || 'pending')}`;
-  el.dataset.nodeId = item.id;
+  el.className = `node node-${type} status-${statusClass(displayStatus)}`;
+  el.dataset.nodeId   = item.id;
   el.dataset.nodeType = type;
 
   const title = item.title || item.statement || item.id;
 
+  // Progress bar for milestones with actions
+  let progressHtml = '';
+  if (type === 'milestone' && derived.totalCount > 0) {
+    const pct = Math.round((derived.doneCount / derived.totalCount) * 100);
+    const countLabel = `${derived.doneCount}/${derived.totalCount}`;
+    progressHtml = `
+      <div class="node-progress" title="${countLabel} actions done">
+        <div class="node-progress-fill" style="width:${pct}%"></div>
+      </div>`;
+  }
+
+  // Badge label — show progress count for executing milestones
+  let badgeLabel = displayStatus;
+  if (type === 'milestone' && displayStatus === 'EXECUTING' && derived.totalCount > 0) {
+    badgeLabel = `${derived.doneCount}/${derived.totalCount} DONE`;
+  }
+
   el.innerHTML = `
     <div class="node-id">${item.id}</div>
     <div class="node-title">${truncate(title, 55)}</div>
-    <span class="status-badge">${item.status || 'PENDING'}</span>
+    <span class="status-badge">${badgeLabel}</span>
+    ${progressHtml}
   `;
 
   el.addEventListener('click', () => selectNode(item.id, type));
@@ -234,22 +313,37 @@ function renderGraph() {
 
   const { declarations, milestones, actions } = graphData;
 
+  // ── Compute derived statuses from action data (always reflects reality) ──────
+  // Milestones
+  const enrichedMilestones = (milestones || []).map(m => ({
+    ...m,
+    ...deriveMilestoneStatus(m, actions || []),
+  }));
+
+  // Declarations
+  const enrichedDeclarations = (declarations || []).map(d => ({
+    ...d,
+    displayStatus: deriveDeclarationStatus(d, enrichedMilestones),
+  }));
+
   // Clear containers
   $nodesDecls.innerHTML = '';
   $nodesMiles.innerHTML = '';
   $nodesActs.innerHTML  = '';
 
-  // Render declarations
-  (declarations || []).forEach(d => {
-    $nodesDecls.appendChild(buildNodeEl(d, 'declaration'));
+  // Render
+  enrichedDeclarations.forEach(d => {
+    $nodesDecls.appendChild(buildNodeEl(d, 'declaration', { displayStatus: d.displayStatus }));
   });
 
-  // Render milestones
-  (milestones || []).forEach(m => {
-    $nodesMiles.appendChild(buildNodeEl(m, 'milestone'));
+  enrichedMilestones.forEach(m => {
+    $nodesMiles.appendChild(buildNodeEl(m, 'milestone', {
+      displayStatus: m.displayStatus,
+      doneCount:     m.doneCount,
+      totalCount:    m.totalCount,
+    }));
   });
 
-  // Render actions
   (actions || []).forEach(a => {
     $nodesActs.appendChild(buildNodeEl(a, 'action'));
   });
@@ -1230,7 +1324,13 @@ const COMPLETED_STATES = new Set(['DONE', 'KEPT', 'HONORED']);
 function checkProjectComplete(graph) {
   if (confettiFired) return;
   if (!graph || !graph.declarations || graph.declarations.length === 0) return;
-  const allDone = graph.declarations.every(d => COMPLETED_STATES.has(d.status));
+  // Use derived statuses (computed from actions) not stored MILESTONES.md status
+  const enriched = (graph.milestones || []).map(m => ({
+    ...m, ...deriveMilestoneStatus(m, graph.actions || []),
+  }));
+  const allDone = graph.declarations.every(d =>
+    COMPLETED_STATES.has(deriveDeclarationStatus(d, enriched))
+  );
   if (!allDone) return;
   confettiFired = true;
   fireConfetti();

package/dist/public/index.html

@@ -41,6 +41,15 @@
       --act-done-bg: #08180f;
       --act-done-border: #123428;
 
+      /* workflow progress tones */
+      --planned-color:   #5ba3ff;
+      --planned-bg:      #091828;
+      --planned-border:  #12305a;
+
+      --executing-color: #fbbf24;
+      --executing-bg:    #1a1200;
+      --executing-border:#3d2c00;
+
       --broken-color: #ff4d6d;
       --broken-bg: #2a0a10;
       --broken-border: #5a1520;
@@ -264,6 +273,41 @@
       opacity: 0.82;
     }
 
+    /* Workflow progress states — computed from action data, not MILESTONES.md */
+    .node.status-planned {
+      background: var(--planned-bg);
+      border-color: var(--planned-border);
+      color: var(--planned-color);
+      opacity: 0.9;
+    }
+    .node.status-executing {
+      background: var(--executing-bg);
+      border-color: var(--executing-border);
+      color: var(--executing-color);
+      box-shadow: 0 0 0 1px var(--executing-border), 0 0 12px rgba(251,191,36,0.15);
+    }
+    .node.status-planned .node-title  { color: var(--planned-color); }
+    .node.status-executing .node-title { color: var(--executing-color); }
+
+    /* Progress bar inside milestone node */
+    .node-progress {
+      margin-top: 7px;
+      height: 3px;
+      background: rgba(255,255,255,0.08);
+      border-radius: 2px;
+      overflow: hidden;
+    }
+    .node-progress-fill {
+      height: 100%;
+      border-radius: 2px;
+      transition: width 0.4s ease;
+    }
+    .status-executing .node-progress-fill { background: var(--executing-color); }
+    .status-planned   .node-progress-fill { background: var(--planned-color); opacity:0.3; }
+    .status-done      .node-progress-fill,
+    .status-kept      .node-progress-fill,
+    .status-honored   .node-progress-fill { background: var(--act-done-color); }
+
     .node.status-broken {
       background: var(--broken-bg);
       border-color: var(--broken-border);

package/hooks/declare-activity.js

@@ -81,10 +81,22 @@ function buildEvent(data) {
     return null; // skip noisy general bash
   }
 
-  // Write tool — track planning file changes
+  // Write tool — track planning file changes + auto-sync on SUMMARY.md writes
   if (tool === 'Write' && hookEvent === 'PostToolUse') {
     const fp = input.file_path || '';
     if (fp.includes('.planning/')) {
+      // When an executor writes A-XX-SUMMARY.md, auto-run sync-status so
+      // PLAN.md and MILESTONES.md update immediately without manual intervention
+      if (fp.includes('-SUMMARY.md')) {
+        const { execSync } = require('child_process');
+        try {
+          execSync(`node "${path.join(cwd, '.claude', 'declare-tools.cjs')}" sync-status`, {
+            cwd,
+            timeout: 10000,
+            stdio: 'ignore',
+          });
+        } catch (_) { /* silent — never block Claude */ }
+      }
       return { ts, phase: 'done', tool: 'Write', file: fp.replace(cwd, '.') };
     }
     return null;

package/hooks/declare-server.js

@@ -0,0 +1,116 @@
+#!/usr/bin/env node
+// Declare dashboard server — SessionStart hook
+//
+// On every Claude Code session start (for a Declare project):
+//   1. Derive a stable port for this project (hash of cwd, range 3847-4846)
+//   2. If a server is already running on that port for THIS project, leave it
+//   3. If a server is running on that port for a DIFFERENT project, kill it
+//   4. Start a fresh server for the current project
+//   5. Write the port to .planning/server.port for /declare:dashboard to read
+//
+// This means each project gets its own port, servers survive between sessions,
+// and switching projects always gives you the right server.
+
+'use strict';
+
+const fs     = require('fs');
+const path   = require('path');
+const http   = require('http');
+const cp     = require('child_process');
+
+const cwd         = process.cwd();
+const planningDir = path.join(cwd, '.planning');
+
+// Only run for Declare projects
+if (!fs.existsSync(planningDir)) process.exit(0);
+
+const PORT_BASE  = 3847;
+const PORT_RANGE = 1000; // ports 3847–4846
+
+/**
+ * Simple djb2 hash to derive a stable port from the project path.
+ * @param {string} str
+ * @returns {number} port in [PORT_BASE, PORT_BASE + PORT_RANGE)
+ */
+function projectPort(str) {
+  let h = 5381;
+  for (let i = 0; i < str.length; i++) {
+    h = ((h << 5) + h) ^ str.charCodeAt(i);
+    h = h >>> 0; // keep unsigned 32-bit
+  }
+  return PORT_BASE + (h % PORT_RANGE);
+}
+
+const port = projectPort(cwd);
+const portFile = path.join(planningDir, 'server.port');
+const bundle   = path.join(cwd, '.claude', 'declare-tools.cjs');
+
+// If bundle doesn't exist, nothing to do
+if (!fs.existsSync(bundle)) process.exit(0);
+
+/**
+ * Ask the running server on `port` which cwd it's serving, via /api/graph.
+ * Returns the project name or null if nothing is running / not a Declare server.
+ */
+function checkRunningServer(port, callback) {
+  const req = http.get(`http://127.0.0.1:${port}/api/graph`, { timeout: 1500 }, res => {
+    let body = '';
+    res.on('data', c => body += c);
+    res.on('end', () => {
+      try {
+        const data = JSON.parse(body);
+        // If it has a valid graph response it's our server
+        callback(data && !data.error ? 'declare' : null);
+      } catch { callback(null); }
+    });
+  });
+  req.on('error', () => callback(null));
+  req.on('timeout', () => { req.destroy(); callback(null); });
+}
+
+/**
+ * Kill any process currently listening on the given port.
+ */
+function killPort(port) {
+  try {
+    const pid = cp.execSync(`lsof -ti :${port} 2>/dev/null`, { encoding: 'utf8' }).trim();
+    if (pid) {
+      pid.split('\n').forEach(p => {
+        try { process.kill(parseInt(p), 'SIGTERM'); } catch {}
+      });
+    }
+  } catch {}
+}
+
+/**
+ * Start the dashboard server for this project in the background.
+ */
+function startServer() {
+  const child = cp.spawn(process.execPath, [bundle, 'serve', '--port', String(port)], {
+    cwd,
+    detached: true,
+    stdio: 'ignore',
+  });
+  child.unref();
+
+  // Write port file so /declare:dashboard knows where to open
+  setTimeout(() => {
+    try { fs.writeFileSync(portFile, String(port)); } catch {}
+  }, 800);
+}
+
+// Check if something is already running on this port
+checkRunningServer(port, status => {
+  if (status === 'declare') {
+    // A Declare server is already up on our port.
+    // It might be from a previous session for this same project — reuse it.
+    // Write port file to make sure /declare:dashboard finds it.
+    try { fs.writeFileSync(portFile, String(port)); } catch {}
+    process.exit(0);
+  }
+
+  // Nothing running (or non-Declare process) — kill whatever is there and start fresh
+  killPort(port);
+  setTimeout(startServer, 300);
+  process.exit(0);
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "declare-cc",
-  "version": "0.5.0",
+  "version": "0.5.3",
   "description": "A future-driven meta-prompting engine for agentic development, rooted in declared futures and causal graph structure.",
   "bin": {
     "declare-cc": "bin/install.js"