buildcrew 1.9.0 → 1.9.2

package/bin/setup.js

@@ -649,6 +649,97 @@ async function runWatch() {
   });
 }
 
+async function runReport() {
+  // Show coherence-report.md output by the coherence-auditor agent.
+  // Usage:
+  //   npx buildcrew report                Show latest coherence-report
+  //   npx buildcrew report --list         List all reports with timestamps
+  //   npx buildcrew report <feature>      Show specific feature's report
+  //   npx buildcrew report --raw          Print raw markdown (for piping)
+  const args = process.argv.slice(3);
+  const wantList = args.includes("--list") || args.includes("-l");
+  const wantRaw = args.includes("--raw");
+  const featureArg = args.find(a => !a.startsWith("-"));
+
+  const PIPELINE_DIR = join(process.cwd(), ".claude", "pipeline");
+  if (!(await exists(PIPELINE_DIR))) {
+    log(`${YELLOW}No pipeline runs found yet.${RESET}`);
+    log(`${DIM}Run ${BOLD}@buildcrew <feature>${RESET}${DIM} in Claude Code to generate one.${RESET}\n`);
+    return;
+  }
+
+  // Collect all coherence-report.md files and their mtimes
+  const features = await readdir(PIPELINE_DIR, { withFileTypes: true });
+  const reports = [];
+  const { stat } = await import("fs/promises");
+  for (const entry of features) {
+    if (!entry.isDirectory()) continue;
+    const reportPath = join(PIPELINE_DIR, entry.name, "coherence-report.md");
+    if (await exists(reportPath)) {
+      const s = await stat(reportPath);
+      reports.push({ feature: entry.name, path: reportPath, mtime: s.mtime });
+    }
+  }
+
+  if (reports.length === 0) {
+    log(`${YELLOW}No coherence-report.md found in any pipeline run.${RESET}`);
+    log(`${DIM}coherence-auditor runs at the end of Feature mode. If you ran a feature recently and don't see a report, check your buildcrew version (need >= 1.9.0).${RESET}\n`);
+    return;
+  }
+
+  reports.sort((a, b) => b.mtime - a.mtime);
+
+  if (wantList) {
+    log(`\n  ${BOLD}Coherence reports${RESET} ${DIM}(newest first)${RESET}\n`);
+    for (const r of reports) {
+      const ago = ((Date.now() - r.mtime) / 1000 / 60) | 0;
+      const when = ago < 60 ? `${ago}m ago` : ago < 1440 ? `${(ago/60)|0}h ago` : `${(ago/1440)|0}d ago`;
+      log(`  ${CYAN}${r.feature.padEnd(30)}${RESET} ${DIM}${when.padStart(8)}${RESET}  ${DIM}${r.path}${RESET}`);
+    }
+    log(`\n  ${DIM}Show one: ${BOLD}npx buildcrew report ${CYAN}<feature>${RESET}\n`);
+    return;
+  }
+
+  // Pick target report
+  let target;
+  if (featureArg) {
+    target = reports.find(r => r.feature === featureArg);
+    if (!target) {
+      log(`${RED}No coherence-report for feature "${featureArg}".${RESET}`);
+      log(`${DIM}List all: ${BOLD}npx buildcrew report --list${RESET}\n`);
+      process.exit(1);
+    }
+  } else {
+    target = reports[0]; // latest
+  }
+
+  const content = await readFile(target.path, "utf8");
+
+  if (wantRaw) {
+    process.stdout.write(content);
+    return;
+  }
+
+  // Pretty header + content. If TTY supports it, try less for paging.
+  const header = `${BOLD}${CYAN}═══ ${target.feature} ═══${RESET}  ${DIM}${target.path}${RESET}\n\n`;
+
+  if (process.stdout.isTTY && content.split("\n").length > process.stdout.rows) {
+    // Try paging through `less -R` (preserves ANSI). Fallback to direct print.
+    try {
+      const { spawn } = await import("child_process");
+      const less = spawn("less", ["-R", "-X"], { stdio: ["pipe", "inherit", "inherit"] });
+      less.stdin.write(header + content);
+      less.stdin.end();
+      await new Promise((resolve) => less.on("exit", resolve));
+      return;
+    } catch {
+      // fall through to direct print
+    }
+  }
+
+  process.stdout.write(header + content + "\n");
+}
+
 async function runUninstall() {
   const files = (await readdir(AGENTS_SRC)).filter(f => f.endsWith(".md"));
   if (!(await exists(TARGET_DIR))) { log(`${YELLOW}No agents found.${RESET}`); return; }
@@ -681,6 +772,8 @@ async function main() {
     npx buildcrew add <name>   Add a harness template
     npx buildcrew harness      Show harness file status
     npx buildcrew watch        Live terminal monitor (stays in your shell)
+    npx buildcrew report       Show latest coherence-report (team coordination score)
+    npx buildcrew report --list   List all coherence reports
 
   ${BOLD}Options:${RESET}
     --force, -f    Overwrite existing files
@@ -700,12 +793,14 @@ async function main() {
     return;
   }
 
-  if (args.includes("--list") || args.includes("-l")) return runList();
-  if (args.includes("--uninstall")) return runUninstall();
+  // Subcommand routing takes priority over global --list (so `report --list` works)
   if (command === "init") return runInit(force);
   if (command === "add") return runAdd(subcommand, force);
   if (command === "harness") return runHarnessStatus();
   if (command === "watch") return runWatch();
+  if (command === "report") return runReport();
+  if (args.includes("--list") || args.includes("-l")) return runList();
+  if (args.includes("--uninstall")) return runUninstall();
 
   return runInstall(force);
 }

package/bin/watch.js

@@ -11,9 +11,13 @@
  * Exit with q or Ctrl-C.
  */
 
-import { createReadStream, watchFile, statSync, existsSync, mkdirSync, closeSync, openSync } from "node:fs";
-import { join } from "node:path";
+import { createReadStream, watchFile, statSync, existsSync, mkdirSync, closeSync, openSync, readdirSync, readFileSync } from "node:fs";
+import { join, resolve, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
 import readline, { createInterface } from "node:readline";
+import { spawnSync } from "node:child_process";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
 
 const EVENTS_PATH = process.env.BUILDCREW_EVENTS_PATH
   ?? join(process.cwd(), ".claude", "buildcrew", "events.jsonl");
@@ -28,11 +32,23 @@ const c = NO_COLOR
       reset: "\x1b[0m", bold: "\x1b[1m", dim: "\x1b[2m",
       black: "\x1b[30m", red: "\x1b[31m", green: "\x1b[32m",
       gold:  "\x1b[33m", blue: "\x1b[34m", mag: "\x1b[35m",
-      cyan:  "\x1b[36m", gray: "\x1b[90m",
+      cyan:  "\x1b[36m",
+      // Primary secondary text — readable on dark terminals (was \x1b[90m which rendered too dim)
+      gray: "\x1b[38;5;250m",
+      // Muted — for truly tertiary metadata (timestamps, separators)
+      muted: "\x1b[38;5;244m",
       bgWood: "\x1b[48;5;94m",
     };
 
-const CLEAR = "\x1b[2J\x1b[H";
+// Anti-flicker rendering primitives.
+// HOME moves cursor to top-left WITHOUT clearing — we overwrite in place and
+// use CLR_EOL per line + CLR_BELOW at the end to erase leftovers. The old
+// `\x1b[2J\x1b[H` caused a visible flash every frame (blank → redraw).
+const HOME = "\x1b[H";
+const CLR_EOL = "\x1b[K";      // clear from cursor to end of line
+const CLR_BELOW = "\x1b[J";    // clear from cursor to end of screen
+const ALT_SCREEN_ON = "\x1b[?1049h";
+const ALT_SCREEN_OFF = "\x1b[?1049l";
 const HIDE_CURSOR = "\x1b[?25l";
 const SHOW_CURSOR = "\x1b[?25h";
 
@@ -88,8 +104,54 @@ const state = {
   sessionId: null,
   sessionStartAt: null,
   sessionEndAt: null,
+  // Coherence: loaded from .claude/pipeline/*/coherence-report.md after coherence-auditor runs
+  coherence: null,             // { score, status, feature, gaps, fabrications, edgesActual, edgesPossible, path, ts }
 };
 
+// ------------------------------------------------------------------
+// Coherence report loader — reads .claude/pipeline/{feature}/coherence-report.md
+// Triggered on agent.completed(coherence-auditor) or file.written(*/coherence-report.md)
+// ------------------------------------------------------------------
+function loadLatestCoherence() {
+  try {
+    const pipelineDir = join(process.cwd(), ".claude", "pipeline");
+    if (!existsSync(pipelineDir)) return;
+    const features = readdirSync(pipelineDir, { withFileTypes: true }).filter(d => d.isDirectory());
+    let newest = null;
+    for (const f of features) {
+      const p = join(pipelineDir, f.name, "coherence-report.md");
+      if (!existsSync(p)) continue;
+      const s = statSync(p);
+      if (!newest || s.mtimeMs > newest.mtime) {
+        newest = { path: p, feature: f.name, mtime: s.mtimeMs };
+      }
+    }
+    if (!newest) return;
+    const content = readFileSync(newest.path, "utf8");
+    // Tolerant parsing — coherence-auditor writes Korean or English.
+    const score = parseInt(content.match(/Coordination Score\*?\*?:?\s*\*?\*?(\d+)\s*%/)?.[1] ?? "", 10);
+    const edges = content.match(/\((\d+)\s*\/\s*(\d+)\s+edges?\)/);
+    const status = content.match(/Status:\s*([A-Za-z]+)/)?.[1] ?? "";
+    const fabrications = parseInt(content.match(/Fabrications?:\s*\*?\*?(\d+)/)?.[1] ?? "0", 10);
+    // Gap count from "## Gaps (N)" heading
+    const gaps = parseInt(content.match(/##\s*Gaps?\s*\((\d+)\)/)?.[1] ?? "0", 10);
+    state.coherence = {
+      score: Number.isFinite(score) ? score : null,
+      status,
+      feature: newest.feature,
+      gaps,
+      fabrications,
+      edgesActual: edges ? parseInt(edges[1], 10) : null,
+      edgesPossible: edges ? parseInt(edges[2], 10) : null,
+      path: newest.path,
+      ts: newest.mtime,
+    };
+    scheduleRender();
+  } catch {
+    // Swallow — coherence is best-effort, never crashes the watch
+  }
+}
+
 function handleEvent(ev) {
   state.events += 1;
   const at = Date.parse(ev.at) || Date.now();
@@ -98,12 +160,37 @@ function handleEvent(ev) {
 
   switch (ev.type) {
     case "session.start":
+      // New session → clear per-session state. Watch is a live observer for the
+      // current session; persistent project progress belongs in docs/ (PDCA).
+      // Keep: coherence (file-derived), session metadata itself.
+      state.currentStage = null;
+      state.completedStages = new Set();
+      state.activeAgents = new Map();
+      state.completedAgents = new Map();
+      state.events = 0;
+      state.files = 0;
+      state.issues = { critical: 0, high: 0, med: 0, low: 0 };
+      state.recent = [];
+      state.recentFiles = [];
+      state.recentIssues = [];
       state.sessionStartAt = at;
       state.sessionEndAt = null;
       if (ev.session_id) state.sessionId = ev.session_id;
       break;
     case "session.end":
       state.sessionEndAt = at;
+      // Sweep any agents still marked active — completed events can be missed
+      // (e.g. @mentions in prompt text that hook logs as dispatched but never
+      // actually invoke the Agent tool). Session end implies nothing is running.
+      for (const id of [...state.activeAgents.keys()]) {
+        const a = state.activeAgents.get(id);
+        state.activeAgents.delete(id);
+        state.completedAgents.set(id, {
+          lastAt: at,
+          duration: Math.max(0, at - a.startAt),
+          summary: "",
+        });
+      }
       break;
     case "agent.dispatched": {
       if (!ev.agent) break;
@@ -130,10 +217,18 @@ function handleEvent(ev) {
       };
       if (ev.agent) closeAgent(ev.agent, at);
       else if (ev.sweep) for (const id of [...state.activeAgents.keys()]) closeAgent(id, at);
+      // Coherence: when coherence-auditor finishes, reload the latest report
+      if (ev.agent === "coherence-auditor") {
+        loadLatestCoherence();
+      }
       break;
     }
     case "file.written":
       state.files += 1;
+      // Coherence: if a coherence-report.md was just written, reload
+      if (ev.path && ev.path.endsWith("/coherence-report.md")) {
+        loadLatestCoherence();
+      }
       if (ev.path) {
         state.recentFiles.push({ path: ev.path, tool: ev.tool_name, agent: ev.agent, at });
         if (state.recentFiles.length > 6) state.recentFiles.shift();
@@ -226,7 +321,7 @@ function renderNow(width) {
       const emoji = (AGENTS.find(a => a.id === id)?.emoji) ?? "●";
       const elapsed = formatDuration(Math.floor((now - info.startAt) / 1000));
       const prompt = truncate(info.prompt, Math.max(20, width - 28));
-      console.log(`  ${c.gold}●${c.reset} ${emoji} ${c.bold}${id}${c.reset} ${c.gray}${elapsed} · ${prompt}${c.reset}`);
+      console.log(`  ${c.gold}●${c.reset} ${emoji} ${c.bold}${id}${c.reset} ${c.muted}${elapsed} ·${c.reset} ${prompt}`);
     }
   }
   console.log("");
@@ -299,6 +394,40 @@ function renderIssues(width) {
   console.log("");
 }
 
+function renderCoherence(width) {
+  if (!state.coherence) return;
+  const co = state.coherence;
+  console.log(sectionTitle("COHERENCE", width));
+  // Score color: 90+ green, 70-89 cyan, 50-69 gold, <50 red
+  let scoreColor = c.gray, statusEmoji = "○";
+  if (co.score == null) {
+    scoreColor = c.gray;
+    statusEmoji = "?";
+  } else if (co.score >= 90) {
+    scoreColor = c.green; statusEmoji = "✓";
+  } else if (co.score >= 70) {
+    scoreColor = c.cyan; statusEmoji = "●";
+  } else if (co.score >= 50) {
+    scoreColor = c.gold; statusEmoji = "⚠";
+  } else {
+    scoreColor = c.red; statusEmoji = "✗";
+  }
+  const scoreStr = co.score == null ? `${c.gray}—${c.reset}` : `${scoreColor}${c.bold}${co.score}%${c.reset}`;
+  const statusStr = co.status ? `${scoreColor}${co.status}${c.reset}` : `${c.gray}—${c.reset}`;
+  const edgesStr = (co.edgesActual != null && co.edgesPossible != null)
+    ? `${c.gray}(${co.edgesActual}/${co.edgesPossible} edges)${c.reset}`
+    : "";
+  const fabBadge = co.fabrications > 0
+    ? `  ${c.red}🚨 ${co.fabrications} fabrication${co.fabrications > 1 ? "s" : ""}${c.reset}`
+    : "";
+  const gapBadge = co.gaps > 0
+    ? `  ${c.gold}⚠ ${co.gaps} gap${co.gaps > 1 ? "s" : ""}${c.reset}`
+    : `  ${c.gray}no gaps${c.reset}`;
+  console.log(`  ${statusEmoji} ${scoreStr} ${statusStr} ${edgesStr}${gapBadge}${fabBadge}`);
+  console.log(`  ${c.gray}feature ${c.cyan}${co.feature}${c.reset}  ${c.gray}· press ${c.bold}r${c.reset}${c.gray} for full report${c.reset}`);
+  console.log("");
+}
+
 function renderRecent(width) {
   console.log(sectionTitle("LOG", width));
   if (state.recent.length === 0) {
@@ -319,7 +448,7 @@ function formatEvent(ev, maxLen) {
   let body;
   switch (ev.type) {
     case "agent.dispatched":
-      body = `${c.gold}▶${c.reset} ${c.bold}${ev.agent ?? "?"}${c.reset} ${c.gray}· ${truncate(ev.prompt, 60)}${c.reset}`;
+      body = `${c.gold}▶${c.reset} ${c.bold}${ev.agent ?? "?"}${c.reset} ${c.muted}·${c.reset} ${truncate(ev.prompt, 60)}`;
       break;
     case "agent.completed":
       body = `${c.green}✓${c.reset} ${ev.agent ?? "*"} ${c.gray}done${c.reset}`;
@@ -347,15 +476,36 @@ function formatEvent(ev, maxLen) {
 
 function render() {
   const width = Math.max(60, process.stdout.columns ?? 80);
-  process.stdout.write(CLEAR);
-  renderHeader();
-  renderNow(width);
-  renderPipeline(width);
-  renderAgents(width);
-  renderFiles(width);
-  renderIssues(width);
-  renderRecent(width);
-  process.stdout.write(`\n${c.gray}q / Ctrl-C to exit${c.reset}\n`);
+
+  // Capture every render*() call's output into an in-memory buffer by
+  // monkey-patching console.log for the duration of the render. This lets us
+  // emit the whole frame in a single process.stdout.write — eliminating the
+  // per-line flicker that came from 30+ separate writes.
+  const lines = [];
+  const origLog = console.log;
+  console.log = (...args) => {
+    lines.push(args.length === 0 ? "" : args.map(String).join(" "));
+  };
+  try {
+    renderHeader();
+    renderNow(width);
+    renderPipeline(width);
+    renderAgents(width);
+    renderFiles(width);
+    renderIssues(width);
+    renderCoherence(width);
+    renderRecent(width);
+  } finally {
+    console.log = origLog;
+  }
+  lines.push("");
+  lines.push(`${c.gray}q quit  ·  r show full coherence report${c.reset}`);
+
+  // Single atomic frame: cursor home → each line + clear-to-EOL (erases any
+  // leftover chars from a previous longer line) → clear-below (handles frame
+  // shrinkage). No `\x1b[2J` flash.
+  const frame = HOME + lines.map(l => l + CLR_EOL).join("\n") + "\n" + CLR_BELOW;
+  process.stdout.write(frame);
 }
 
 // ------------------------------------------------------------------
@@ -381,6 +531,13 @@ async function replayExisting() {
     tailOffset = 0;
     return;
   }
+  // Empty events.jsonl (first run / fresh install) — nothing to replay.
+  // createReadStream with end: -1 would throw RangeError.
+  if (tailOffset === 0) {
+    state.connected = true;
+    scheduleRender();
+    return;
+  }
   const stream = createReadStream(EVENTS_PATH, { encoding: "utf8", end: tailOffset - 1 });
   const rl = createInterface({ input: stream, crlfDelay: Infinity });
   for await (const line of rl) {
@@ -420,12 +577,15 @@ function subscribeTail() {
 // ------------------------------------------------------------------
 // Bootstrap
 // ------------------------------------------------------------------
-process.stdout.write(HIDE_CURSOR);
-process.on("exit", () => process.stdout.write(SHOW_CURSOR));
-process.on("SIGINT", () => { process.stdout.write(SHOW_CURSOR); process.exit(0); });
-process.on("SIGTERM", () => { process.stdout.write(SHOW_CURSOR); process.exit(0); });
-
-// Allow 'q' to quit
+// Enter alternate screen so the dashboard doesn't scribble over the user's
+// scrollback. On exit we return the terminal to its pre-watch state.
+process.stdout.write(ALT_SCREEN_ON + HIDE_CURSOR);
+const restoreTerm = () => process.stdout.write(SHOW_CURSOR + ALT_SCREEN_OFF);
+process.on("exit", restoreTerm);
+process.on("SIGINT", () => { restoreTerm(); process.exit(0); });
+process.on("SIGTERM", () => { restoreTerm(); process.exit(0); });
+
+// Keypress handlers: q/Ctrl-C quit, r open full coherence report
 if (process.stdin.isTTY) {
   readline.emitKeypressEvents(process.stdin);
   process.stdin.setRawMode(true);
@@ -434,6 +594,23 @@ if (process.stdin.isTTY) {
       process.stdout.write(SHOW_CURSOR);
       process.exit(0);
     }
+    if (key?.name === "r") {
+      // Open the full coherence report. Hand off the terminal to setup.js's
+      // report subcommand which uses `less -R` for paging. Leave the alt
+      // screen so less paints on the main buffer; re-enter on return.
+      process.stdout.write(SHOW_CURSOR + ALT_SCREEN_OFF);
+      process.stdin.setRawMode(false);
+      const setupEntry = resolve(__dirname, "setup.js");
+      spawnSync(process.execPath, [setupEntry, "report"], {
+        stdio: "inherit",
+        cwd: process.cwd(),
+        env: process.env,
+      });
+      // Restore raw mode + alt screen + hide cursor + redraw
+      process.stdin.setRawMode(true);
+      process.stdout.write(ALT_SCREEN_ON + HIDE_CURSOR);
+      scheduleRender();
+    }
   });
 }
 
@@ -444,6 +621,9 @@ setInterval(scheduleRender, 1000);
 (async () => {
   await ensureEventsFile();
   await replayExisting();
+  // Surface the latest coherence report (if any) on startup, even before any
+  // new events fire — so users see their last score when they open watch.
+  loadLatestCoherence();
   subscribeTail();
   render();
 })();

package/lib/install-hooks.js

@@ -2,10 +2,18 @@
  * buildcrew CC hook installer.
  *
  * Registers hook entries in .claude/settings.json that invoke
- * `npx buildcrew-hook <kind>` on each agent/file event. The hook writes
+ * `node <abs-path>/lib/hook.js <kind>` on each agent/file event. The hook writes
  * a styled banner to the terminal AND appends to events.jsonl so that
  * `npx buildcrew watch` can show a live view in a separate pane.
  *
+ * We resolve an absolute path to the installed buildcrew package's hook.js at
+ * install time rather than using `npx buildcrew-hook` because:
+ *   - Bare `npx buildcrew-hook` looks up a package literally named
+ *     "buildcrew-hook" → E404 (it's a bin inside the `buildcrew` package).
+ *   - `npx -p buildcrew buildcrew-hook` works but re-fetches on cache miss and
+ *     adds 200-500ms latency per CC hook invocation.
+ *   - Absolute node path is zero-overhead and immune to npx cache eviction.
+ *
  * Idempotent — re-install replaces prior buildcrew entries without
  * touching other hooks or permissions in the file.
  */
@@ -13,9 +21,15 @@
 import { promises as fsp } from "node:fs";
 import path from "node:path";
 import os from "node:os";
+import { fileURLToPath } from "node:url";
 
 const BUILDCREW_TAG = "buildcrew-hook";
 
+// Absolute path to this package's hook script — resolved at import time so the
+// generated settings.json entries are self-contained (no PATH lookups needed).
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const HOOK_SCRIPT = path.resolve(__dirname, "hook.js");
+
 export function resolveSettingsPath({ scope, cwd }) {
   if (scope === "global") return path.join(os.homedir(), ".claude", "settings.json");
   return path.join(cwd, ".claude", "settings.json");
@@ -27,7 +41,9 @@ export function resolvePermissionsPath({ scope, cwd }) {
 }
 
 export function buildcrewHooks() {
-  const cmd = (kind) => `npx buildcrew-hook ${kind}`;
+  // Shell-escape the path in case the install location contains spaces or
+  // non-ASCII characters (e.g. Korean path segments on macOS).
+  const cmd = (kind) => `node "${HOOK_SCRIPT}" ${kind}`;
   const mk = (kind, matcher) => ({
     [BUILDCREW_TAG]: true,
     ...(matcher ? { matcher } : {}),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "buildcrew",
-  "version": "1.9.0",
+  "version": "1.9.2",
   "description": "15 AI agents for Claude Code — full development lifecycle from product thinking to production monitoring",
   "homepage": "https://buildcrew-landing.vercel.app",
   "author": "z1nun",