declare-cc 0.4.5 → 0.5.0

package/bin/install.js

@@ -1564,6 +1564,9 @@ function install(isGlobal, runtime = 'claude') {
   const updateCheckCommand = isGlobal
     ? buildHookCommand(targetDir, 'declare-check-update.js')
     : 'node ' + dirName + '/hooks/declare-check-update.js';
+  const activityCommand = isGlobal
+    ? buildHookCommand(targetDir, 'declare-activity.js')
+    : 'node ' + dirName + '/hooks/declare-activity.js';
 
   // Enable experimental agents for Gemini CLI (required for custom sub-agents)
   if (isGemini) {
@@ -1600,6 +1603,21 @@ function install(isGlobal, runtime = 'claude') {
       });
       console.log(`  ${green}✓${reset} Configured update check hook`);
     }
+
+    // Configure PreToolUse + PostToolUse hooks for activity feed (Claude Code only)
+    if (!isOpencode && !isGemini) {
+      if (!settings.hooks.PreToolUse)  settings.hooks.PreToolUse  = [];
+      if (!settings.hooks.PostToolUse) settings.hooks.PostToolUse = [];
+
+      const hasActivityPre = settings.hooks.PreToolUse.some(e =>
+        e.hooks && e.hooks.some(h => h.command && h.command.includes('declare-activity'))
+      );
+      if (!hasActivityPre) {
+        settings.hooks.PreToolUse.push({ hooks: [{ type: 'command', command: activityCommand }] });
+        settings.hooks.PostToolUse.push({ hooks: [{ type: 'command', command: activityCommand }] });
+        console.log(`  ${green}✓${reset} Configured activity feed hooks`);
+      }
+    }
   }
 
   // Write file manifest for future modification detection
@@ -1618,11 +1636,13 @@ function install(isGlobal, runtime = 'claude') {
 function finishInstall(settingsPath, settings, statuslineCommand, shouldInstallStatusline, runtime = 'claude', isGlobal = true) {
   const isOpencode = runtime === 'opencode';
 
-  if (shouldInstallStatusline && !isOpencode) {
-    settings.statusLine = {
-      type: 'command',
-      command: statuslineCommand
-    };
+  // Statusline is a global UI element — only configure it for global installs.
+  // Local installs must not write statusLine: it would point to a project-specific
+  // path that breaks when the project moves or is deleted.
+  // Users who only do local installs should run `npx declare-cc --claude --global`
+  // once to get the statusline, or configure it manually.
+  if (shouldInstallStatusline && !isOpencode && isGlobal) {
+    settings.statusLine = { type: 'command', command: statuslineCommand };
     console.log(`  ${green}✓${reset} Configured statusline`);
   }
 
@@ -1639,9 +1659,12 @@ function finishInstall(settingsPath, settings, statuslineCommand, shouldInstallS
   if (runtime === 'gemini') program = 'Gemini';
 
   const command = isOpencode ? '/declare-help' : '/declare:help';
+  const statuslineNote = (!isGlobal && !isOpencode)
+    ? `\n  ${yellow}Tip:${reset} For the context-window statusline, run once globally:\n  ${dim}npx declare-cc --claude --global${reset}\n`
+    : '';
   console.log(`
   ${green}Done!${reset} Launch ${program} and run ${cyan}${command}${reset}.
-
+${statuslineNote}
   ${cyan}Docs & source:${reset} https://github.com/decocms/declare-cc
 `);
 }

package/commands/declare/execute.md

@@ -188,25 +188,28 @@ If `--confirm` flag was set, pause after successful verification:
 - "Wave N complete and verified. Proceed to Wave N+1? (yes/no)"
 - Wait for user confirmation before continuing.
 
-**3e. Update action statuses in PLAN.md:**
+**3e. Propagate statuses after each wave:**
 
-After successful wave verification, update each completed action's status in the milestone's PLAN.md file:
+After successful wave verification, run sync-status to update PLAN.md, MILESTONES.md, and FUTURE.md atomically. This keeps the dashboard live as waves complete:
 
-1. Use the `milestoneFolderPath` from Step 2 to locate the PLAN.md file.
-2. Read the PLAN.md file.
-3. For each action in the completed wave, find `**Status:** PENDING` (or `**Status:** ACTIVE`) for that action and change it to `**Status:** DONE`.
-4. Write the updated PLAN.md back.
+```bash
+node dist/declare-tools.cjs sync-status
+```
+
+Do not manually edit PLAN.md or MILESTONES.md — sync-status handles all of it correctly.
+
+**Step 4: After all waves complete, propagate statuses.**
 
-**Step 4: After all waves complete, check milestone completion.**
+Run sync-status to propagate action → milestone → declaration completion automatically:
+
+```bash
+node dist/declare-tools.cjs sync-status
+```
 
-If `milestoneCompletable` is true from the final verify-wave result:
-1. Read `.planning/MILESTONES.md`.
-2. Find the row for M-XX in the milestones table.
-3. Change its Status from PENDING or ACTIVE to DONE.
-4. Write the updated MILESTONES.md back.
-5. Display: "Milestone M-XX marked as DONE (pending verification)."
+Parse the result. It will show which actions, milestones, and declarations were marked DONE.
+Display: "Status propagated — [summary from sync-status result]."
 
-Proceed to Step 5. Do NOT display a completion banner yet -- that happens in Step 8 after verification.
+Proceed to Step 5. Do NOT display a completion banner yet — that happens in Step 8 after verification.
 
 **Step 5: Milestone truth verification.**
 

package/dist/declare-tools.cjs

@@ -1329,7 +1329,7 @@ var require_help = __commonJS({
             usage: "/declare:help"
           }
         ],
-        version: "0.4.4"
+        version: "0.4.7"
       };
     }
     module2.exports = { runHelp: runHelp2 };
@@ -3096,6 +3096,167 @@ var require_sync_status = __commonJS({
   }
 });
 
+// src/commands/get-exec-plan.js
+var require_get_exec_plan = __commonJS({
+  "src/commands/get-exec-plan.js"(exports2, module2) {
+    "use strict";
+    var { existsSync, readFileSync, readdirSync } = require("node:fs");
+    var { join } = require("node:path");
+    var { parseFlag } = require_parse_args();
+    var { buildDagFromDisk } = require_build_dag();
+    var { findMilestoneFolder } = require_milestone_folders();
+    function parseFrontmatter(fmText) {
+      const result = {};
+      const lines = fmText.split("\n");
+      let i = 0;
+      while (i < lines.length) {
+        const line = lines[i];
+        const keyMatch = line.match(/^(\w[\w_]*):\s*(.*)/);
+        if (!keyMatch) {
+          i++;
+          continue;
+        }
+        const [, key, rest] = keyMatch;
+        if (rest.trim() === "") {
+          const children = [];
+          i++;
+          while (i < lines.length && (lines[i].startsWith("  ") || lines[i].trim() === "")) {
+            const child = lines[i];
+            const listItem = child.match(/^\s+-\s+(.*)/);
+            const nestedKey = child.match(/^\s+(\w[\w_]*):\s*(.*)/);
+            if (listItem) {
+              children.push({ type: "item", value: listItem[1].replace(/^["']|["']$/g, "") });
+            } else if (nestedKey) {
+              children.push({ type: "key", key: nestedKey[1], value: nestedKey[2] });
+            }
+            i++;
+          }
+          if (children.length > 0 && children[0].type === "item") {
+            result[key] = children.map((c) => c.value);
+          } else if (children.length > 0 && children[0].type === "key") {
+            result[key] = {};
+            let subKey = null;
+            let subItems = [];
+            for (const c of children) {
+              if (c.type === "key") {
+                if (subKey) result[key][subKey] = subItems;
+                subKey = c.key;
+                subItems = c.value.trim() ? [c.value.replace(/^["']|["']$/g, "")] : [];
+              } else if (c.type === "item") {
+                subItems.push(c.value);
+              }
+            }
+            if (subKey) result[key][subKey] = subItems;
+          }
+        } else {
+          result[key] = rest.trim().replace(/^["']|["']$/g, "");
+          i++;
+        }
+      }
+      return result;
+    }
+    function extractTag(content, tag) {
+      const re = new RegExp(`<${tag}[^>]*>([\\s\\S]*?)<\\/${tag}>`, "i");
+      const m = content.match(re);
+      return m ? m[1].trim() : null;
+    }
+    function parseTasks(tasksContent) {
+      const tasks = [];
+      const taskRe = /<task([^>]*)>([\s\S]*?)<\/task>/gi;
+      let m;
+      while ((m = taskRe.exec(tasksContent)) !== null) {
+        const attrs = m[1];
+        const body = m[2];
+        const typeMatch = attrs.match(/type="([^"]+)"/);
+        const taskType = typeMatch ? typeMatch[1] : "auto";
+        tasks.push({
+          type: taskType,
+          name: extractTag(body, "name") || "",
+          action: extractTag(body, "action"),
+          verify: extractTag(body, "verify"),
+          done: extractTag(body, "done"),
+          howToVerify: extractTag(body, "how-to-verify"),
+          resumeSignal: extractTag(body, "resume-signal"),
+          whatBuilt: extractTag(body, "what-built")
+        });
+      }
+      return tasks;
+    }
+    function findExecPlan(milestoneFolder, actionId) {
+      if (!existsSync(milestoneFolder)) return null;
+      const entries = readdirSync(milestoneFolder);
+      const match = entries.find(
+        (f) => f.toUpperCase().startsWith(actionId.toUpperCase() + "-EXEC-PLAN") || f.toUpperCase().startsWith("EXEC-PLAN-" + actionId.replace(/^A-/, ""))
+      );
+      return match ? join(milestoneFolder, match) : null;
+    }
+    function runGetExecPlan2(cwd, args) {
+      const actionId = parseFlag(args, "action");
+      if (!actionId) {
+        return { error: "Missing --action flag. Usage: get-exec-plan --action A-XX" };
+      }
+      const graphResult = buildDagFromDisk(cwd);
+      if ("error" in graphResult) return graphResult;
+      const { dag } = graphResult;
+      const action = dag.getNode(actionId);
+      if (!action) return { error: `Action not found: ${actionId}` };
+      const upstreamMilestones = dag.getUpstream(actionId).filter((n) => n.type === "milestone");
+      if (upstreamMilestones.length === 0) return { error: `No milestone found for action ${actionId}` };
+      const milestone = upstreamMilestones[0];
+      const planningDir = join(cwd, ".planning");
+      const milestoneFolder = findMilestoneFolder(planningDir, milestone.id);
+      if (!milestoneFolder) {
+        return { error: `Milestone folder not found for ${milestone.id}` };
+      }
+      const execPlanPath = findExecPlan(milestoneFolder, actionId);
+      if (!execPlanPath) {
+        return {
+          actionId,
+          actionTitle: action.title,
+          status: action.status,
+          milestoneId: milestone.id,
+          milestoneTitle: milestone.title,
+          execPlan: null,
+          summaryExists: false
+        };
+      }
+      const raw = readFileSync(execPlanPath, "utf-8");
+      const fmMatch = raw.match(/^---\n([\s\S]*?)\n---/);
+      const frontmatter = fmMatch ? parseFrontmatter(fmMatch[1]) : {};
+      const objective = extractTag(raw, "objective");
+      const tasksRaw = extractTag(raw, "tasks");
+      const tasks = tasksRaw ? parseTasks(tasksRaw) : [];
+      const successCriteria = extractTag(raw, "success_criteria");
+      const verification = extractTag(raw, "verification");
+      const summaryPath = join(milestoneFolder, `${actionId}-SUMMARY.md`);
+      const summaryExists = existsSync(summaryPath);
+      const summaryContent = summaryExists ? readFileSync(summaryPath, "utf-8") : null;
+      return {
+        actionId,
+        actionTitle: action.title,
+        status: action.status,
+        milestoneId: milestone.id,
+        milestoneTitle: milestone.title,
+        execPlan: {
+          wave: frontmatter.wave ? Number(frontmatter.wave) : null,
+          autonomous: frontmatter.autonomous === "true" || frontmatter.autonomous === true,
+          dependsOn: Array.isArray(frontmatter.depends_on) ? frontmatter.depends_on : [],
+          filesModified: Array.isArray(frontmatter.files_modified) ? frontmatter.files_modified : [],
+          declarations: Array.isArray(frontmatter.declarations) ? frontmatter.declarations : [],
+          mustHaves: frontmatter.must_haves || null,
+          objective,
+          tasks,
+          successCriteria,
+          verification
+        },
+        summaryExists,
+        summaryContent
+      };
+    }
+    module2.exports = { runGetExecPlan: runGetExecPlan2 };
+  }
+});
+
 // src/commands/quick-task.js
 var require_quick_task = __commonJS({
   "src/commands/quick-task.js"(exports2, module2) {
@@ -3666,6 +3827,7 @@ var require_server = __commonJS({
     var path = require("node:path");
     var { runLoadGraph: runLoadGraph2 } = require_load_graph();
     var { runStatus: runStatus2 } = require_status();
+    var { runGetExecPlan: runGetExecPlan2 } = require_get_exec_plan();
     var MIME_TYPES = {
       ".html": "text/html; charset=utf-8",
       ".js": "application/javascript; charset=utf-8",
@@ -3762,6 +3924,26 @@ var require_server = __commonJS({
         sendJson(res, 500, { error: String(err) });
       }
     }
+    function handleActivity(res, cwd) {
+      const activityFile = path.join(cwd, ".planning", "activity.jsonl");
+      if (!fs.existsSync(activityFile)) {
+        sendJson(res, 200, { events: [] });
+        return;
+      }
+      try {
+        const lines = fs.readFileSync(activityFile, "utf-8").split("\n").filter(Boolean).slice(-100);
+        const events = lines.map((l) => {
+          try {
+            return JSON.parse(l);
+          } catch {
+            return null;
+          }
+        }).filter(Boolean).reverse();
+        sendJson(res, 200, { events });
+      } catch (err) {
+        sendJson(res, 500, { error: String(err) });
+      }
+    }
     var sseClients = /* @__PURE__ */ new Set();
     function broadcastChange() {
       for (const client of sseClients) {
@@ -3775,14 +3957,30 @@ var require_server = __commonJS({
     function watchPlanning(cwd) {
       const planningDir = path.join(cwd, ".planning");
       if (!fs.existsSync(planningDir)) return;
-      let debounceTimer = null;
+      let graphTimer = null;
+      let activityTimer = null;
+      const activityFile = path.join(planningDir, "activity.jsonl");
       try {
-        fs.watch(planningDir, { recursive: true }, () => {
-          if (debounceTimer) clearTimeout(debounceTimer);
-          debounceTimer = setTimeout(() => {
-            broadcastChange();
-            debounceTimer = null;
-          }, 200);
+        fs.watch(planningDir, { recursive: true }, (_evt, filename) => {
+          if (filename && filename.endsWith("activity.jsonl")) {
+            if (activityTimer) clearTimeout(activityTimer);
+            activityTimer = setTimeout(() => {
+              for (const client of sseClients) {
+                try {
+                  client.write("event: activity\ndata: {}\n\n");
+                } catch {
+                  sseClients.delete(client);
+                }
+              }
+              activityTimer = null;
+            }, 50);
+          } else {
+            if (graphTimer) clearTimeout(graphTimer);
+            graphTimer = setTimeout(() => {
+              broadcastChange();
+              graphTimer = null;
+            }, 200);
+          }
         });
       } catch (_) {
       }
@@ -3829,6 +4027,16 @@ var require_server = __commonJS({
         handleMilestone(res, cwd, milestoneMatch[1]);
         return;
       }
+      if (urlPath === "/api/activity") {
+        handleActivity(res, cwd);
+        return;
+      }
+      const actionMatch = urlPath.match(/^\/api\/action\/([^/]+)$/);
+      if (actionMatch) {
+        const result = runGetExecPlan2(cwd, ["--action", actionMatch[1]]);
+        sendJson(res, result.error ? 404 : 200, result);
+        return;
+      }
       const publicDir = getPublicDir(cwd);
       if (urlPath === "/") {
         const indexPath = path.join(publicDir, "index.html");
@@ -3918,6 +4126,7 @@ var { runComputePerformance } = require_compute_performance();
 var { runRenegotiate } = require_renegotiate();
 var { runCompleteMilestone } = require_complete_milestone();
 var { runSyncStatus } = require_sync_status();
+var { runGetExecPlan } = require_get_exec_plan();
 var { runQuickTask } = require_quick_task();
 var { runAddTodo, runCheckTodos, runCompleteTodo } = require_todo();
 var { runConfigGet } = require_config_get();
@@ -4094,6 +4303,13 @@ function main() {
         if (result.error) process.exit(1);
         break;
       }
+      case "get-exec-plan": {
+        const cwdGep = parseCwdFlag(args) || process.cwd();
+        const result = runGetExecPlan(cwdGep, args.slice(1));
+        console.log(JSON.stringify(result));
+        if (result.error) process.exit(1);
+        break;
+      }
       case "execute": {
         const cwdExecute = parseCwdFlag(args) || process.cwd();
         const result = runExecute(cwdExecute, args.slice(1));

package/dist/public/app.js

@@ -146,6 +146,7 @@ async function loadData() {
     renderStatusBar();
     renderGraph();
     updateLastUpdated();
+    checkProjectComplete(graph);
 
     // Re-apply selection highlight if node still exists
     if (selectedNodeId) {
@@ -650,10 +651,16 @@ function renderPanelChain(item, type) {
         const causedBy = actions.filter(a => (a.causes || []).includes(s.item.id));
         if (causedBy.length) html += chainTagSection('Actions', causedBy, 'action');
       }
-      if (s.type === 'action' && s.item.produces) {
-        html += `<div style="margin-top:14px">
-          <div class="detail-label">Produces</div>
-          <div class="detail-value" style="margin-top:5px">${escHtml(s.item.produces)}</div>
+      if (s.type === 'action') {
+        if (s.item.produces) {
+          html += `<div style="margin-top:14px">
+            <div class="detail-label">Produces</div>
+            <div class="detail-value" style="margin-top:5px">${escHtml(s.item.produces)}</div>
+          </div>`;
+        }
+        // Exec-plan placeholder — filled asynchronously after render
+        html += `<div id="exec-plan-detail" style="margin-top:16px">
+          <div class="detail-label" style="opacity:0.4">Loading exec-plan…</div>
         </div>`;
       }
     }
@@ -667,6 +674,12 @@ function renderPanelChain(item, type) {
       selectNode(tag.dataset.chainId, tag.dataset.chainType);
     });
   });
+
+  // If an action is focused, fetch and render its exec-plan
+  const focusSection = sections.find(s => s.role === 'focus');
+  if (focusSection && focusSection.type === 'action') {
+    loadExecPlan(focusSection.item.id);
+  }
 }
 
 function chainTagSection(label, items, type) {
@@ -680,6 +693,121 @@ function chainTagSection(label, items, type) {
   </div>`;
 }
 
+/**
+ * Fetch /api/action/:id and render the exec-plan into #exec-plan-detail.
+ * @param {string} actionId
+ */
+async function loadExecPlan(actionId) {
+  const container = document.getElementById('exec-plan-detail');
+  if (!container) return;
+
+  try {
+    const res = await fetch(`/api/action/${encodeURIComponent(actionId)}`);
+    const data = await res.json();
+
+    if (data.error || !data.execPlan) {
+      container.innerHTML = `<div class="detail-label" style="opacity:0.4">No exec-plan found</div>`;
+      return;
+    }
+
+    const ep = data.execPlan;
+    let html = '';
+
+    // Execution metadata bar
+    const metaParts = [];
+    if (ep.wave != null) metaParts.push(`Wave ${ep.wave}`);
+    if (ep.autonomous != null) metaParts.push(ep.autonomous ? '⚡ Autonomous' : '🧑 Checkpoint');
+    if (ep.dependsOn && ep.dependsOn.length) metaParts.push(`Depends: ${ep.dependsOn.join(', ')}`);
+    if (data.summaryExists) metaParts.push('✓ Executed');
+
+    if (metaParts.length) {
+      html += `<div style="display:flex;flex-wrap:wrap;gap:6px;margin-bottom:14px">
+        ${metaParts.map(p => `<span style="background:var(--surface2);border:1px solid var(--border);border-radius:6px;padding:2px 8px;font-size:10px;font-weight:600;color:var(--text-dim)">${p}</span>`).join('')}
+      </div>`;
+    }
+
+    // Files modified
+    if (ep.filesModified && ep.filesModified.length) {
+      html += `<div style="margin-bottom:14px">
+        <div class="detail-label">Files</div>
+        <div style="display:flex;flex-wrap:wrap;gap:4px;margin-top:5px">
+          ${ep.filesModified.map(f => `<span style="background:var(--act-bg);border:1px solid var(--act-border);color:var(--act-color);border-radius:4px;padding:2px 7px;font-size:10px;font-family:monospace">${escHtml(f)}</span>`).join('')}
+        </div>
+      </div>`;
+    }
+
+    // Objective
+    if (ep.objective) {
+      html += `<div style="margin-bottom:14px">
+        <div class="detail-label">Objective</div>
+        <div class="detail-value" style="margin-top:5px;white-space:pre-wrap">${escHtml(ep.objective)}</div>
+      </div>`;
+    }
+
+    // Tasks
+    if (ep.tasks && ep.tasks.length) {
+      html += `<div style="margin-bottom:14px">
+        <div class="detail-label">Tasks (${ep.tasks.length})</div>
+        <div style="margin-top:8px;display:flex;flex-direction:column;gap:8px">
+          ${ep.tasks.map((t, i) => {
+            const isCheckpoint = t.type && t.type.includes('checkpoint');
+            const typeColor = isCheckpoint ? 'var(--renegotiated-color)' : 'var(--act-color)';
+            const typeBg = isCheckpoint ? 'var(--renegotiated-bg)' : 'var(--act-bg)';
+            const typeBorder = isCheckpoint ? 'var(--renegotiated-border)' : 'var(--act-border)';
+            const taskText = t.action || t.whatBuilt || '';
+            const verifyText = t.howToVerify || t.verify || '';
+            return `<div style="background:var(--surface2);border:1px solid var(--border);border-radius:6px;padding:10px 12px">
+              <div style="display:flex;align-items:center;gap:6px;margin-bottom:6px">
+                <span style="font-size:10px;font-weight:700;color:var(--text-dim)">${i + 1}</span>
+                <span style="font-weight:600;font-size:12px;color:var(--text-bright);flex:1">${escHtml(t.name)}</span>
+                <span style="background:${typeBg};color:${typeColor};border:1px solid ${typeBorder};border-radius:4px;padding:1px 6px;font-size:9px;font-weight:700;white-space:nowrap">${escHtml(t.type)}</span>
+              </div>
+              ${taskText ? `<div style="font-size:11px;color:var(--text-dim);white-space:pre-wrap;margin-bottom:6px">${escHtml(taskText.slice(0, 300))}${taskText.length > 300 ? '…' : ''}</div>` : ''}
+              ${verifyText ? `<div style="font-size:10px;color:var(--text-dim);border-top:1px solid var(--border);padding-top:6px;margin-top:4px;white-space:pre-wrap"><span style="font-weight:700">Verify:</span> ${escHtml(verifyText.slice(0, 200))}${verifyText.length > 200 ? '…' : ''}</div>` : ''}
+            </div>`;
+          }).join('')}
+        </div>
+      </div>`;
+    }
+
+    // Must-haves
+    if (ep.mustHaves) {
+      if (ep.mustHaves.truths && ep.mustHaves.truths.length) {
+        html += `<div style="margin-bottom:14px">
+          <div class="detail-label">Must be true</div>
+          <ul style="margin-top:6px;padding-left:16px;display:flex;flex-direction:column;gap:3px">
+            ${ep.mustHaves.truths.map(t => `<li style="font-size:11px;color:var(--text-dim)">${escHtml(t)}</li>`).join('')}
+          </ul>
+        </div>`;
+      }
+      if (ep.mustHaves.artifacts && ep.mustHaves.artifacts.length) {
+        html += `<div style="margin-bottom:14px">
+          <div class="detail-label">Artifacts</div>
+          <div style="display:flex;flex-direction:column;gap:4px;margin-top:6px">
+            ${ep.mustHaves.artifacts.map(a => `<div style="font-size:11px;color:var(--text-dim)">
+              <span style="font-family:monospace;color:var(--act-color)">${escHtml(a.path || '')}</span>
+              ${a.provides ? ` — ${escHtml(a.provides)}` : ''}
+            </div>`).join('')}
+          </div>
+        </div>`;
+      }
+    }
+
+    // Success criteria
+    if (ep.successCriteria) {
+      html += `<div style="margin-bottom:8px">
+        <div class="detail-label">Success criteria</div>
+        <div class="detail-value" style="margin-top:5px;white-space:pre-wrap">${escHtml(ep.successCriteria)}</div>
+      </div>`;
+    }
+
+    container.innerHTML = html || `<div class="detail-label" style="opacity:0.4">No exec-plan details</div>`;
+
+  } catch (e) {
+    if (container) container.innerHTML = `<div class="detail-label" style="opacity:0.4">Could not load exec-plan</div>`;
+  }
+}
+
 // ─── Focus mode — FLIP technique ──────────────────────────────────────────────
 // Exiting nodes: removed from flow instantly (→ flex re-centers), then overlaid
 // at their original positions via position:fixed for the directional slide-out.
@@ -1087,6 +1215,144 @@ document.getElementById('canvas-wrap').addEventListener('scroll', () => {
   if (graphData) requestAnimationFrame(() => drawEdges());
 });
 
+// ─── Confetti ────────────────────────────────────────────────────────────────
+// Fires once when all declarations reach a completed state (DONE/KEPT/HONORED).
+// Pure canvas — no external deps.
+
+let confettiFired = false;
+
+const COMPLETED_STATES = new Set(['DONE', 'KEPT', 'HONORED']);
+
+/**
+ * Check if all declarations are complete and fire confetti if so.
+ * @param {{ declarations: any[] } | null} graph
+ */
+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));
+  if (!allDone) return;
+  confettiFired = true;
+  fireConfetti();
+}
+
+function fireConfetti() {
+  const canvas = document.createElement('canvas');
+  canvas.style.cssText = 'position:fixed;top:0;left:0;width:100%;height:100%;pointer-events:none;z-index:9999';
+  document.body.appendChild(canvas);
+
+  const ctx = canvas.getContext('2d');
+  canvas.width  = window.innerWidth;
+  canvas.height = window.innerHeight;
+
+  const COLORS = [
+    '#5ba3ff', '#a66bff', '#34d399',   // brand: blue, purple, green
+    '#fbbf24', '#f87171', '#38bdf8',   // yellow, red, sky
+    '#ffffff',                          // white
+  ];
+
+  const count  = 180;
+  const pieces = Array.from({ length: count }, () => ({
+    x:    Math.random() * canvas.width,
+    y:    Math.random() * canvas.height * -0.5 - 10,
+    w:    6 + Math.random() * 8,
+    h:    3 + Math.random() * 5,
+    rot:  Math.random() * Math.PI * 2,
+    rotV: (Math.random() - 0.5) * 0.2,
+    vx:   (Math.random() - 0.5) * 4,
+    vy:   2 + Math.random() * 4,
+    color: COLORS[Math.floor(Math.random() * COLORS.length)],
+    alpha: 1,
+  }));
+
+  let frame;
+  function draw() {
+    ctx.clearRect(0, 0, canvas.width, canvas.height);
+    let alive = 0;
+    for (const p of pieces) {
+      p.x   += p.vx;
+      p.y   += p.vy;
+      p.vy  += 0.07;           // gravity
+      p.vx  *= 0.99;           // drag
+      p.rot += p.rotV;
+      // fade out once off-screen bottom
+      if (p.y > canvas.height * 0.85) p.alpha -= 0.025;
+      if (p.alpha <= 0) continue;
+      alive++;
+      ctx.save();
+      ctx.globalAlpha = p.alpha;
+      ctx.translate(p.x, p.y);
+      ctx.rotate(p.rot);
+      ctx.fillStyle = p.color;
+      ctx.fillRect(-p.w / 2, -p.h / 2, p.w, p.h);
+      ctx.restore();
+    }
+    if (alive > 0) {
+      frame = requestAnimationFrame(draw);
+    } else {
+      canvas.remove();
+    }
+  }
+  frame = requestAnimationFrame(draw);
+
+  // Safety cleanup after 8s
+  setTimeout(() => { cancelAnimationFrame(frame); canvas.remove(); }, 8000);
+}
+
+// ─── Activity feed ────────────────────────────────────────────────────────────
+
+const $activityFeed   = document.getElementById('activity-feed');
+const $activityList   = document.getElementById('activity-list');
+const $activityPulse  = document.getElementById('activity-pulse');
+const $activityToggle = document.getElementById('activity-toggle');
+let activityExpanded  = false;
+
+$activityToggle.addEventListener('click', () => {
+  activityExpanded = !activityExpanded;
+  $activityFeed.classList.toggle('expanded', activityExpanded);
+});
+
+/**
+ * Fetch /api/activity and render the event list.
+ */
+async function loadActivity() {
+  try {
+    const res = await fetch('/api/activity');
+    const { events } = await res.json();
+    if (!events || events.length === 0) return;
+
+    $activityFeed.classList.add('has-events');
+
+    const html = events.slice(0, 50).map(ev => {
+      const time = new Date(ev.ts).toLocaleTimeString([], { hour: '2-digit', minute: '2-digit', second: '2-digit' });
+
+      if (ev.tool === 'Task') {
+        const icon = ev.phase === 'start' ? '⟳' : '✓';
+        const cls  = ev.phase === 'start' ? 'agent-start' : 'agent-done';
+        const label = ev.phase === 'start'
+          ? `Spawning ${ev.agent || 'agent'}: ${ev.desc}`
+          : `Done: ${ev.desc}`;
+        return `<div class="activity-event"><span class="ae-time">${time}</span><span class="ae-icon">${icon}</span><span class="ae-text ${cls}">${escHtml(label)}</span></div>`;
+      }
+      if (ev.tool === 'Bash') {
+        const icon = ev.phase === 'start' ? '▶' : '■';
+        return `<div class="activity-event"><span class="ae-time">${time}</span><span class="ae-icon" style="opacity:0.5">${icon}</span><span class="ae-text bash">${escHtml(ev.cmd || '')}</span></div>`;
+      }
+      if (ev.tool === 'Write') {
+        return `<div class="activity-event"><span class="ae-time">${time}</span><span class="ae-icon" style="opacity:0.5">✎</span><span class="ae-text write">${escHtml(ev.file || '')}</span></div>`;
+      }
+      return '';
+    }).filter(Boolean).join('');
+
+    $activityList.innerHTML = html || $activityList.innerHTML;
+
+    // Flash pulse
+    $activityPulse.classList.add('live');
+    clearTimeout($activityPulse._timer);
+    $activityPulse._timer = setTimeout(() => $activityPulse.classList.remove('live'), 3000);
+  } catch (_) {}
+}
+
 // ─── Live updates via Server-Sent Events ─────────────────────────────────────
 // Server watches .planning/ with fs.watch and pushes a 'change' event.
 // Client re-renders only when idle (not mid-animation).
@@ -1097,6 +1363,9 @@ function connectSSE() {
     if (focusNodeId || focusCleanupTimer) return; // skip during animation
     loadData();
   });
+  es.addEventListener('activity', () => {
+    loadActivity();
+  });
   es.addEventListener('error', () => {
     // Connection dropped — reconnect after 3s
     es.close();
@@ -1110,3 +1379,4 @@ connectSSE();
 
 showLoading();
 loadData();
+loadActivity();

package/dist/public/index.html

@@ -146,6 +146,7 @@
       overflow: auto;
       background: var(--bg);
       padding-right: var(--panel-width);
+      padding-bottom: 40px; /* room for activity feed */
     }
 
     #canvas-container {
@@ -545,6 +546,85 @@
       z-index: 50;
     }
     #focus-hint.visible { opacity: 1; }
+    /* ── Activity feed ── */
+    #activity-feed {
+      position: fixed;
+      bottom: 0;
+      left: 0;
+      right: var(--panel-width);
+      height: 36px;
+      background: var(--surface);
+      border-top: 1px solid var(--border);
+      display: flex;
+      align-items: center;
+      overflow: hidden;
+      z-index: 20;
+      transition: height 0.2s ease;
+    }
+    #activity-feed.expanded { height: 180px; align-items: flex-start; }
+    #activity-feed.has-events { border-top-color: var(--act-border); }
+
+    #activity-toggle {
+      flex-shrink: 0;
+      padding: 0 12px;
+      font-size: 10px;
+      font-weight: 700;
+      letter-spacing: 0.06em;
+      color: var(--text-dim);
+      cursor: pointer;
+      user-select: none;
+      display: flex;
+      align-items: center;
+      gap: 6px;
+      height: 36px;
+    }
+    #activity-toggle:hover { color: var(--text-bright); }
+    #activity-pulse {
+      width: 6px; height: 6px;
+      border-radius: 50%;
+      background: var(--act-color);
+      opacity: 0;
+      transition: opacity 0.3s;
+    }
+    #activity-pulse.live { opacity: 1; animation: pulse 1.5s ease-in-out infinite; }
+    @keyframes pulse {
+      0%, 100% { opacity: 1; }
+      50%       { opacity: 0.3; }
+    }
+
+    #activity-list {
+      flex: 1;
+      overflow-y: auto;
+      overflow-x: hidden;
+      padding: 0 8px;
+      font-size: 11px;
+      font-family: monospace;
+      display: flex;
+      flex-direction: column;
+      gap: 0;
+    }
+    #activity-feed:not(.expanded) #activity-list { flex-direction: row; align-items: center; gap: 16px; overflow: hidden; white-space: nowrap; }
+
+    .activity-event {
+      padding: 4px 0;
+      color: var(--text-dim);
+      border-bottom: 1px solid var(--surface2);
+      display: flex;
+      align-items: baseline;
+      gap: 8px;
+      flex-shrink: 0;
+    }
+    #activity-feed:not(.expanded) .activity-event { border: none; padding: 0; }
+    .activity-event:last-child { border-bottom: none; }
+
+    .ae-time { opacity: 0.4; font-size: 10px; flex-shrink: 0; }
+    .ae-icon { flex-shrink: 0; }
+    .ae-text { flex: 1; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+    .ae-text.agent-start { color: var(--act-color); font-weight: 600; }
+    .ae-text.agent-done  { color: var(--mile-color); }
+    .ae-text.bash        { color: var(--text-dim); }
+    .ae-text.write       { color: var(--decl-color); }
+
   </style>
 </head>
 <body>
@@ -595,6 +675,17 @@
   </div>
 </div>
 
+<!-- Activity feed — live agent/tool event stream -->
+<div id="activity-feed">
+  <div id="activity-toggle">
+    <div id="activity-pulse"></div>
+    <span id="activity-label">ACTIVITY</span>
+  </div>
+  <div id="activity-list">
+    <span style="color:var(--text-dim);font-size:10px;opacity:0.4">No activity yet — agents will appear here when running</span>
+  </div>
+</div>
+
 <!-- Loading/error overlay -->
 <div id="overlay">
   <div class="spinner"></div>

package/hooks/declare-activity.js

@@ -0,0 +1,94 @@
+#!/usr/bin/env node
+// Declare activity hook — PreToolUse + PostToolUse
+// Writes interesting tool events to .planning/activity.jsonl
+// Server watches .planning/ via fs.watch and pushes SSE events to dashboard.
+//
+// Installed for PreToolUse and PostToolUse hook events.
+// Runs fast: read stdin → decide → append one line → exit.
+
+'use strict';
+
+const fs   = require('fs');
+const path = require('path');
+const os   = require('os');
+
+const cwd          = process.cwd();
+const planningDir  = path.join(cwd, '.planning');
+const activityFile = path.join(planningDir, 'activity.jsonl');
+
+// Only write if .planning/ exists (i.e. this is a Declare project)
+if (!fs.existsSync(planningDir)) process.exit(0);
+
+let raw = '';
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', c => raw += c);
+process.stdin.on('end', () => {
+  try {
+    const data = JSON.parse(raw);
+    const event = buildEvent(data);
+    if (!event) process.exit(0);
+
+    // Ensure file exists
+    if (!fs.existsSync(activityFile)) fs.writeFileSync(activityFile, '');
+
+    // Append event + trim to last 200 lines
+    const line = JSON.stringify(event) + '\n';
+    fs.appendFileSync(activityFile, line);
+
+    // Trim to last 200 lines to avoid unbounded growth
+    const content = fs.readFileSync(activityFile, 'utf8');
+    const lines = content.split('\n').filter(Boolean);
+    if (lines.length > 200) {
+      fs.writeFileSync(activityFile, lines.slice(-200).join('\n') + '\n');
+    }
+  } catch (_) {
+    // Silent fail — never block Claude
+  }
+  process.exit(0);
+});
+
+/**
+ * Build an activity event from a hook payload, or return null to skip.
+ * @param {any} data
+ * @returns {object|null}
+ */
+function buildEvent(data) {
+  const tool      = data.tool_name || '';
+  const input     = data.tool_input || {};
+  const response  = data.tool_response;
+  const hookEvent = data.hook_event_name || ''; // PreToolUse or PostToolUse
+  const ts        = Date.now();
+  const phase     = hookEvent === 'PostToolUse' ? 'done' : 'start';
+
+  // Task spawns — most important for agent visibility
+  if (tool === 'Task') {
+    return {
+      ts, phase, tool: 'Task',
+      desc:  input.description || '',
+      agent: input.subagent_type || '',
+      // truncate prompt to avoid massive payloads
+      prompt: (input.prompt || '').slice(0, 200),
+      bg: hookEvent === 'PostToolUse',
+    };
+  }
+
+  // Bash commands that involve declare-tools (execution steps)
+  if (tool === 'Bash') {
+    const cmd = input.command || '';
+    if (cmd.includes('declare-tools') || cmd.includes('/declare:')) {
+      return { ts, phase, tool: 'Bash', cmd: cmd.slice(0, 200) };
+    }
+    return null; // skip noisy general bash
+  }
+
+  // Write tool — track planning file changes
+  if (tool === 'Write' && hookEvent === 'PostToolUse') {
+    const fp = input.file_path || '';
+    if (fp.includes('.planning/')) {
+      return { ts, phase: 'done', tool: 'Write', file: fp.replace(cwd, '.') };
+    }
+    return null;
+  }
+
+  return null;
+}

package/hooks/declare-check-update.js

@@ -0,0 +1,62 @@
+#!/usr/bin/env node
+// Check for Declare updates in background, write result to cache
+// Called by SessionStart hook - runs once per session
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const { spawn } = require('child_process');
+
+const homeDir = os.homedir();
+const cwd = process.cwd();
+const cacheDir = path.join(homeDir, '.claude', 'cache');
+const cacheFile = path.join(cacheDir, 'declare-update-check.json');
+
+// VERSION file locations (check project first, then global)
+const projectVersionFile = path.join(cwd, '.claude', 'declare', 'VERSION');
+const globalVersionFile = path.join(homeDir, '.claude', 'declare', 'VERSION');
+
+// Ensure cache directory exists
+if (!fs.existsSync(cacheDir)) {
+  fs.mkdirSync(cacheDir, { recursive: true });
+}
+
+// Run check in background (spawn background process, windowsHide prevents console flash)
+const child = spawn(process.execPath, ['-e', `
+  const fs = require('fs');
+  const { execSync } = require('child_process');
+
+  const cacheFile = ${JSON.stringify(cacheFile)};
+  const projectVersionFile = ${JSON.stringify(projectVersionFile)};
+  const globalVersionFile = ${JSON.stringify(globalVersionFile)};
+
+  // Check project directory first (local install), then global
+  let installed = '0.0.0';
+  try {
+    if (fs.existsSync(projectVersionFile)) {
+      installed = fs.readFileSync(projectVersionFile, 'utf8').trim();
+    } else if (fs.existsSync(globalVersionFile)) {
+      installed = fs.readFileSync(globalVersionFile, 'utf8').trim();
+    }
+  } catch (e) {}
+
+  let latest = null;
+  try {
+    latest = execSync('npm view declare-cc version', { encoding: 'utf8', timeout: 10000, windowsHide: true }).trim();
+  } catch (e) {}
+
+  const result = {
+    update_available: latest && installed !== latest,
+    installed,
+    latest: latest || 'unknown',
+    checked: Math.floor(Date.now() / 1000)
+  };
+
+  fs.writeFileSync(cacheFile, JSON.stringify(result));
+`], {
+  stdio: 'ignore',
+  windowsHide: true,
+  detached: true  // Required on Windows for proper process detachment
+});
+
+child.unref();

package/hooks/declare-statusline.js

@@ -0,0 +1,91 @@
+#!/usr/bin/env node
+// Claude Code Statusline - Declare Edition
+// Shows: model | current task | directory | context usage
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+// Read JSON from stdin
+let input = '';
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', chunk => input += chunk);
+process.stdin.on('end', () => {
+  try {
+    const data = JSON.parse(input);
+    const model = data.model?.display_name || 'Claude';
+    const dir = data.workspace?.current_dir || process.cwd();
+    const session = data.session_id || '';
+    const remaining = data.context_window?.remaining_percentage;
+
+    // Context window display (shows USED percentage scaled to 80% limit)
+    // Claude Code enforces an 80% context limit, so we scale to show 100% at that point
+    let ctx = '';
+    if (remaining != null) {
+      const rem = Math.round(remaining);
+      const rawUsed = Math.max(0, Math.min(100, 100 - rem));
+      // Scale: 80% real usage = 100% displayed
+      const used = Math.min(100, Math.round((rawUsed / 80) * 100));
+
+      // Build progress bar (10 segments)
+      const filled = Math.floor(used / 10);
+      const bar = '█'.repeat(filled) + '░'.repeat(10 - filled);
+
+      // Color based on scaled usage (thresholds adjusted for new scale)
+      if (used < 63) {        // ~50% real
+        ctx = ` \x1b[32m${bar} ${used}%\x1b[0m`;
+      } else if (used < 81) { // ~65% real
+        ctx = ` \x1b[33m${bar} ${used}%\x1b[0m`;
+      } else if (used < 95) { // ~76% real
+        ctx = ` \x1b[38;5;208m${bar} ${used}%\x1b[0m`;
+      } else {
+        ctx = ` \x1b[5;31m💀 ${bar} ${used}%\x1b[0m`;
+      }
+    }
+
+    // Current task from todos
+    let task = '';
+    const homeDir = os.homedir();
+    const todosDir = path.join(homeDir, '.claude', 'todos');
+    if (session && fs.existsSync(todosDir)) {
+      try {
+        const files = fs.readdirSync(todosDir)
+          .filter(f => f.startsWith(session) && f.includes('-agent-') && f.endsWith('.json'))
+          .map(f => ({ name: f, mtime: fs.statSync(path.join(todosDir, f)).mtime }))
+          .sort((a, b) => b.mtime - a.mtime);
+
+        if (files.length > 0) {
+          try {
+            const todos = JSON.parse(fs.readFileSync(path.join(todosDir, files[0].name), 'utf8'));
+            const inProgress = todos.find(t => t.status === 'in_progress');
+            if (inProgress) task = inProgress.activeForm || '';
+          } catch (e) {}
+        }
+      } catch (e) {
+        // Silently fail on file system errors - don't break statusline
+      }
+    }
+
+    // Declare update available?
+    let gsdUpdate = '';
+    const cacheFile = path.join(homeDir, '.claude', 'cache', 'declare-update-check.json');
+    if (fs.existsSync(cacheFile)) {
+      try {
+        const cache = JSON.parse(fs.readFileSync(cacheFile, 'utf8'));
+        if (cache.update_available) {
+          gsdUpdate = '\x1b[33m⬆ /declare:update\x1b[0m │ ';
+        }
+      } catch (e) {}
+    }
+
+    // Output
+    const dirname = path.basename(dir);
+    if (task) {
+      process.stdout.write(`${gsdUpdate}\x1b[2m${model}\x1b[0m │ \x1b[1m${task}\x1b[0m │ \x1b[2m${dirname}\x1b[0m${ctx}`);
+    } else {
+      process.stdout.write(`${gsdUpdate}\x1b[2m${model}\x1b[0m │ \x1b[2m${dirname}\x1b[0m${ctx}`);
+    }
+  } catch (e) {
+    // Silent fail - don't break statusline on parse errors
+  }
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "declare-cc",
-  "version": "0.4.5",
+  "version": "0.5.0",
   "description": "A future-driven meta-prompting engine for agentic development, rooted in declared futures and causal graph structure.",
   "bin": {
     "declare-cc": "bin/install.js"
@@ -10,6 +10,7 @@
     "commands",
     "agents",
     "dist",
+    "hooks",
     "scripts",
     "workflows",
     "templates"