karajan-code 1.54.0 → 1.56.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "karajan-code",
-  "version": "1.54.0",
+  "version": "1.56.0",
   "description": "Local multi-agent coding orchestrator with TDD, SonarQube, and code review pipeline",
   "type": "module",
   "license": "AGPL-3.0",

package/src/bootstrap.js

@@ -22,6 +22,7 @@ import { checkBinary } from "./utils/agent-detect.js";
 import { exists } from "./utils/fs.js";
 import { getConfigPath, resolveRole } from "./config.js";
 import { isSonarReachable, sonarUp } from "./sonar/manager.js";
+import { withDocLink } from "./utils/doc-links.js";
 
 const BOOTSTRAP_VERSION = 1;
 const BOOTSTRAP_TTL_HOURS = 24;
@@ -185,14 +186,14 @@ function formatBootstrapFailure(failures) {
   const lines = failures.map(f =>
     `  FAIL  ${f.name}: ${f.detail}\n        Fix: ${f.fix}`
   );
-  return [
+  return withDocLink([
     "BOOTSTRAP FAILED — Environment not ready for Karajan Code.\n",
     "The following prerequisite(s) are not met:\n",
     ...lines,
     "",
     "Run 'kj_doctor' for a complete environment diagnostic.",
     "Do NOT work around these issues — fix them properly."
-  ].join("\n");
+  ].join("\n"), "bootstrap_failed");
 }
 
 // ── Public API ───────────────────────────────────────────────────────

package/src/cli.js

@@ -24,6 +24,8 @@ import { researcherCommand } from "./commands/researcher.js";
 import { architectCommand } from "./commands/architect.js";
 import { auditCommand } from "./commands/audit.js";
 import { boardCommand } from "./commands/board.js";
+import { undoCommand } from "./commands/undo.js";
+import { statusCommand } from "./commands/status.js";
 
 import { printUpdateNotice } from "./utils/update-check.js";
 
@@ -167,6 +169,14 @@ program
     await withConfig("doctor", {}, doctorCommand);
   });
 
+program
+  .command("status")
+  .description("Show pipeline dashboard with HU progress")
+  .option("-n, --lines <n>", "Max log lines to read", "50")
+  .action(async (flags) => {
+    await statusCommand({ lines: Number(flags.lines) });
+  });
+
 program
   .command("report")
   .description("Show latest session report")
@@ -324,6 +334,17 @@ program
     });
   });
 
+program
+  .command("undo")
+  .description("Revert last pipeline run")
+  .option("--hard", "Discard all changes (default: soft reset, keeps changes staged)")
+  .action(async (flags) => {
+    await withConfig("undo", flags, async ({ logger }) => {
+      const result = await undoCommand({ hard: !!flags.hard, logger });
+      if (!result.ok) process.exit(1);
+    });
+  });
+
 const sonar = program.command("sonar").description("Manage SonarQube container");
 sonar.command("status").action(async () => sonarCommand({ action: "status" }));
 sonar.command("start").action(async () => sonarCommand({ action: "start" }));

package/src/commands/doctor.js

@@ -11,6 +11,7 @@ import { resolveRoleMdPath, loadFirstExisting } from "../roles/base-role.js";
 import { ensureGitRepo } from "../utils/git.js";
 import { checkBinary, KNOWN_AGENTS } from "../utils/agent-detect.js";
 import { getInstallCommand } from "../utils/os-detect.js";
+import { withDocLink } from "../utils/doc-links.js";
 
 function getPackageVersion() {
   const pkgPath = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../../package.json");
@@ -36,7 +37,7 @@ async function checkConfigFile() {
     label: "Config file",
     ok: configExists,
     detail: configExists ? configPath : "Not found",
-    fix: configExists ? null : "Run 'kj init' to create the config file."
+    fix: configExists ? null : withDocLink("Run 'kj init' to create the config file.", "config_missing")
   };
 }
 
@@ -63,7 +64,7 @@ async function checkDocker() {
     label: "Docker",
     ok: docker.ok,
     detail: docker.ok ? docker.version : "Not found",
-    fix: docker.ok ? null : "Install Docker: https://docs.docker.com/get-docker/"
+    fix: docker.ok ? null : withDocLink("Install Docker: https://docs.docker.com/get-docker/", "sonar_docker")
   };
 }
 
@@ -91,7 +92,7 @@ async function checkSonarQube(config) {
     detail: sonarDetail(config, sonarOk, sonarHost),
     fix: isOkOrDisabled
       ? null
-      : "Run 'kj sonar start' or 'docker start karajan-sonarqube'. Use --no-sonar to skip."
+      : withDocLink("Run 'kj sonar start' or 'docker start karajan-sonarqube'. Use --no-sonar to skip.", "sonar_docker")
   };
 }
 
@@ -104,7 +105,7 @@ async function checkAgentCLIs() {
       label: `Agent: ${agent.name}`,
       ok: result.ok,
       detail: result.ok ? `${result.version} (${result.path})` : "Not found",
-      fix: result.ok ? null : `Install: ${agent.install}`
+      fix: result.ok ? null : withDocLink(`Install: ${agent.install}`, "agent_not_found")
     });
   }
   return checks;
@@ -220,7 +221,7 @@ async function checkRtk() {
     label: "RTK (Rust Token Killer)",
     ok: false,
     detail: "Not found — 60-90% token savings available",
-    fix: `Install: ${installCmd}`
+    fix: withDocLink(`Install: ${installCmd}`, "rtk_install")
   };
 }
 

package/src/commands/init.js

@@ -12,6 +12,7 @@ import { getInstallCommand } from "../utils/os-detect.js";
 import { detectOsLocale, SUPPORTED_LANGUAGES } from "../utils/locale.js";
 import { detectRtk } from "../utils/rtk-detect.js";
 import { installRtk } from "../utils/rtk-install.js";
+import { detectProjectStack } from "../utils/stack-detect.js";
 
 async function runWizard(config, logger) {
   const agents = await detectAvailableAgents();
@@ -330,6 +331,35 @@ export async function initCommand({ logger, flags = {} }) {
   await ensureCoderRules(coderRulesPath, logger);
   await installSkills(logger, interactive);
 
+  // Auto-detect project stack and preconfigure
+  const stack = await detectProjectStack(process.cwd());
+  if (stack.frameworks.length > 0 || stack.language) {
+    const parts = [];
+    if (stack.frameworks.length > 0) parts.push(stack.frameworks.join(" + "));
+    if (stack.language) parts.push(stack.language);
+    const stackType = stack.isFullstack ? "fullstack" : stack.isFrontend ? "frontend" : stack.isBackend ? "backend" : "unknown";
+    logger.info(`Detected stack: ${parts.join(" / ")} (${stackType})`);
+
+    if (stack.suggestions.impeccable) {
+      config.impeccable = config.impeccable || {};
+      config.impeccable.enabled = true;
+      logger.info("  -> Impeccable design audit enabled (frontend detected)");
+    }
+
+    if (stack.suggestions.skills.length > 0) {
+      logger.info(`  -> Suggested skills: ${stack.suggestions.skills.join(", ")}`);
+    }
+
+    if (stack.language && !configExists) {
+      config.development = config.development || {};
+      config.development.methodology = config.development.methodology || "tdd";
+    }
+
+    await writeConfig(configPath, config);
+  } else {
+    logger.info("No project stack detected — using default configuration.");
+  }
+
   // Check RTK availability — auto-install if missing
   const rtk = await detectRtk();
   if (rtk.available) {

package/src/commands/status.js

@@ -0,0 +1,35 @@
+/**
+ * CLI status command — shows a terminal dashboard of the current pipeline state.
+ */
+
+import { readRunLog } from "../utils/run-log.js";
+import { loadMostRecentSession } from "../session-store.js";
+import { buildDashboard } from "../utils/status-dashboard.js";
+
+/**
+ * Run the `kj status` command: print a human-readable dashboard to stdout.
+ * @param {object} options
+ * @param {number} [options.lines=50] - Max log lines to read.
+ * @param {string} [options.projectDir] - Project directory override.
+ */
+export async function statusCommand({ lines = 50, projectDir } = {}) {
+  const dir = projectDir || process.cwd();
+  const logResult = readRunLog(dir, lines);
+
+  let session = null;
+  try {
+    session = await loadMostRecentSession();
+  } catch { /* no session available */ }
+
+  let stories = [];
+  if (session) {
+    try {
+      const { loadHuBatch } = await import("../hu/store.js");
+      const batch = await loadHuBatch(session.id);
+      if (batch?.stories) stories = batch.stories;
+    } catch { /* no HU batch */ }
+  }
+
+  const dashboard = buildDashboard(session, logResult.lines || [], { stories });
+  console.log(dashboard);
+}

package/src/commands/undo.js

@@ -0,0 +1,62 @@
+import { loadMostRecentSession } from "../session-store.js";
+import { runCommand } from "../utils/process.js";
+
+/**
+ * Revert the last pipeline run by resetting to the pre-pipeline commit.
+ * Default: soft reset (keeps changes staged). With --hard: discards all changes.
+ */
+export async function undoCommand({ hard = false, logger } = {}) {
+  const session = await loadMostRecentSession();
+  if (!session) {
+    const msg = "No session to undo. No sessions found in the sessions directory.";
+    if (logger) logger.error(msg);
+    return { ok: false, error: msg };
+  }
+
+  const sha = session.session_start_sha;
+  if (!sha) {
+    const msg = `Session ${session.id} has no session_start_sha. Cannot determine the pre-pipeline commit.`;
+    if (logger) logger.error(msg);
+    return { ok: false, error: msg };
+  }
+
+  // Verify the SHA exists in git history
+  const verifyRes = await runCommand("git", ["cat-file", "-t", sha]);
+  if (verifyRes.exitCode !== 0 || verifyRes.stdout.trim() !== "commit") {
+    const msg = `Commit ${sha} not found in git history. It may have been garbage-collected or belong to a different repository.`;
+    if (logger) logger.error(msg);
+    return { ok: false, error: msg };
+  }
+
+  // Check there are commits after the SHA (HEAD is ahead)
+  const logRes = await runCommand("git", ["log", "--oneline", `${sha}..HEAD`]);
+  if (logRes.exitCode !== 0 || !logRes.stdout.trim()) {
+    const msg = `No commits to undo. HEAD is already at or before ${sha.slice(0, 8)}.`;
+    if (logger) logger.warn(msg);
+    return { ok: false, error: msg };
+  }
+
+  const mode = hard ? "--hard" : "--soft";
+  const resetRes = await runCommand("git", ["reset", mode, sha]);
+  if (resetRes.exitCode !== 0) {
+    const msg = `git reset ${mode} ${sha} failed: ${resetRes.stderr || resetRes.stdout}`;
+    if (logger) logger.error(msg);
+    return { ok: false, error: msg };
+  }
+
+  const shortSha = sha.slice(0, 8);
+  const message = hard
+    ? `Reverted to pre-pipeline state (commit ${shortSha}). All changes discarded.`
+    : `Reverted to pre-pipeline state (commit ${shortSha}). Changes are staged. Use \`git diff --cached\` to review.`;
+
+  if (logger) logger.info(message);
+  console.log(message);
+
+  return {
+    ok: true,
+    message,
+    sessionId: session.id,
+    sha,
+    mode: hard ? "hard" : "soft"
+  };
+}

package/src/mcp/handlers/management-handlers.js

@@ -14,6 +14,8 @@ import {
   responseText,
   buildConfig,
 } from "../server-handlers.js";
+import { buildDashboardJson } from "../../utils/status-dashboard.js";
+import { loadMostRecentSession } from "../../session-store.js";
 
 const AGENT_ROLES = new Set(["coder", "reviewer", "tester", "security", "solomon"]);
 
@@ -29,7 +31,26 @@ async function runBootstrapGate(server, a) {
 export async function handleStatus(a, server) {
   const maxLines = a.lines || 50;
   const projectDir = await resolveProjectDir(server, a.projectDir);
-  return readRunLog(projectDir, maxLines);
+  const logResult = readRunLog(projectDir, maxLines);
+
+  // Enrich with dashboard data when possible
+  try {
+    const session = await loadMostRecentSession();
+    const stories = [];
+    if (session) {
+      try {
+        const { loadHuBatch } = await import("../../hu/store.js");
+        const batch = await loadHuBatch(session.id);
+        if (batch?.stories) stories.push(...batch.stories);
+      } catch { /* no HU batch for this session */ }
+    }
+
+    const dashboard = buildDashboardJson(session, logResult.lines || [], { stories });
+    return { ...logResult, dashboard };
+  } catch {
+    // Fallback: return raw log without dashboard
+    return logResult;
+  }
 }
 
 export async function handleAgents(a) {
@@ -163,6 +184,18 @@ export async function handleBoard(a) {
   }
 }
 
+export async function handleUndo(a, server) {
+  const projectDir = await resolveProjectDir(server, a.projectDir);
+  const origCwd = process.cwd();
+  try {
+    process.chdir(projectDir);
+    const { undoCommand } = await import("../../commands/undo.js");
+    return undoCommand({ hard: !!a.hard });
+  } finally {
+    process.chdir(origCwd);
+  }
+}
+
 export async function buildPreflightRequiredResponse(toolName) {
   const { config } = await loadConfig();
   const { listAgents } = await import("../../commands/agents.js");

package/src/mcp/server-handlers.js

@@ -10,11 +10,12 @@ import { loadConfig, applyRunOverrides, validateConfig } from "../config.js";
 import { currentBranch } from "../utils/git.js";
 import { buildProgressNotifier } from "./progress.js";
 import { compressResponse, compactStringify } from "./response-compressor.js";
+import { withDocLink } from "../utils/doc-links.js";
 
 // ── Sub-module re-exports ────────────────────────────────────────────
 export { handleRunDirect, handleResumeDirect, validateResumeAnswer, handleRun, handleResume } from "./handlers/run-handler.js";
 export { handlePlanDirect, handleCodeDirect, handleReviewDirect, handleDiscoverDirect, handleTriageDirect, handleResearcherDirect, handleAuditDirect, handleArchitectDirect, handleCode, handleReview, handlePlan, handleDiscover, handleTriage, handleResearcher, handleArchitect, handleAudit } from "./handlers/direct-handlers.js";
-export { handleStatus, handleAgents, handlePreflight, handleRoles, handleReport, handleInit, handleDoctor, handleConfig, handleScan, handleBoard, buildPreflightRequiredResponse } from "./handlers/management-handlers.js";
+export { handleStatus, handleAgents, handlePreflight, handleRoles, handleReport, handleInit, handleDoctor, handleConfig, handleScan, handleBoard, handleUndo, buildPreflightRequiredResponse } from "./handlers/management-handlers.js";
 export { handleHu, handleSkills, handleSuggest } from "./handlers/hu-handlers.js";
 
 // ── Shared helpers (used by sub-modules and external consumers) ──────
@@ -82,22 +83,22 @@ const ERROR_CLASSIFIERS = [
   {
     test: (lower) => lower.includes("sonar") && (lower.includes("connect") || lower.includes("econnrefused") || lower.includes("not available") || lower.includes("not running")),
     category: "sonar_unavailable",
-    suggestion: "SonarQube is not reachable. Try: kj_init to set up SonarQube, or run 'docker start sonarqube' if already installed. Use --no-sonar to skip SonarQube."
+    suggestion: withDocLink("SonarQube is not reachable. Try: kj_init to set up SonarQube, or run 'docker start sonarqube' if already installed. Use --no-sonar to skip SonarQube.", "sonar_docker")
   },
   {
     test: (lower) => lower.includes("401") || lower.includes("unauthorized") || lower.includes("invalid token"),
     category: "auth_error",
-    suggestion: "Authentication failed. Regenerate the SonarQube token and update it via kj_init or in ~/.karajan/kj.config.yml under sonarqube.token."
+    suggestion: withDocLink("Authentication failed. Regenerate the SonarQube token and update it via kj_init or in ~/.karajan/kj.config.yml under sonarqube.token.", "sonar_token")
   },
   {
     test: (lower) => lower.includes("config") && (lower.includes("missing") || lower.includes("not found") || lower.includes("invalid")),
     category: "config_error",
-    suggestion: "Configuration issue detected. Run kj_doctor to diagnose, or kj_init to create a fresh config."
+    suggestion: withDocLink("Configuration issue detected. Run kj_doctor to diagnose, or kj_init to create a fresh config.", "config_missing")
   },
   {
     test: (lower) => lower.includes("missing provider") || lower.includes("not found") && (lower.includes("claude") || lower.includes("codex") || lower.includes("gemini") || lower.includes("aider")),
     category: "agent_missing",
-    suggestion: "Required agent CLI not found. Run kj_doctor to check which agents are installed and get installation instructions."
+    suggestion: withDocLink("Required agent CLI not found. Run kj_doctor to check which agents are installed and get installation instructions.", "agent_not_found")
   },
   {
     test: (lower) => lower.includes("timed out") || lower.includes("timeout"),
@@ -107,7 +108,7 @@ const ERROR_CLASSIFIERS = [
   {
     test: (lower) => lower.includes("you are on the base branch"),
     category: "branch_error",
-    suggestion: "Create a feature branch before running Karajan. Use 'git checkout -b feat/<task-description>' and then retry. Do NOT run kj_code directly on the base branch."
+    suggestion: withDocLink("Create a feature branch before running Karajan. Use 'git checkout -b feat/<task-description>' and then retry. Do NOT run kj_code directly on the base branch.", "branch_error")
   },
   {
     test: (lower) => lower.includes("not a git repository"),
@@ -117,7 +118,7 @@ const ERROR_CLASSIFIERS = [
   {
     test: (lower) => lower.includes("bootstrap failed"),
     category: "bootstrap_error",
-    suggestion: "Environment prerequisites not met. Run kj_doctor for diagnostics, then fix the issues listed. Do NOT work around these — fix them properly."
+    suggestion: withDocLink("Environment prerequisites not met. Run kj_doctor for diagnostics, then fix the issues listed. Do NOT work around these — fix them properly.", "bootstrap_failed")
   }
 ];
 
@@ -218,7 +219,7 @@ import {
 import {
   handleStatus, handleAgents, handlePreflight, handleRoles,
   handleReport, handleInit, handleDoctor, handleConfig,
-  handleScan, handleBoard
+  handleScan, handleBoard, handleUndo
 } from "./handlers/management-handlers.js";
 import { handleHu, handleSkills, handleSuggest } from "./handlers/hu-handlers.js";
 
@@ -245,7 +246,8 @@ const toolHandlers = {
   kj_board:       (a) => handleBoard(a),
   kj_hu:          (a, server) => handleHu(a, server),
   kj_suggest:     (a) => handleSuggest(a),
-  kj_skills:      (a) => handleSkills(a)
+  kj_skills:      (a) => handleSkills(a),
+  kj_undo:        (a, server) => handleUndo(a, server)
 };
 
 export async function handleToolCall(name, args, server, extra) {

package/src/mcp/tools.js

@@ -364,5 +364,16 @@ export const tools = [
       },
       required: ["action"]
     }
+  },
+  {
+    name: "kj_undo",
+    description: "Revert the last pipeline run by resetting to the pre-pipeline commit. Default: soft reset (keeps changes staged). Use hard=true to discard all changes.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        hard: { type: "boolean", description: "If true, discard all changes (git reset --hard). Default: false (soft reset, keeps changes staged)." },
+        projectDir: { type: "string", description: "Absolute path to the project directory" }
+      }
+    }
   }
 ];

package/src/orchestrator/preflight-checks.js

@@ -19,6 +19,7 @@ import {
   resolveSonarToken,
   resolveSonarCredentials,
 } from "../sonar/config-resolver.js";
+import { withDocLink } from "../utils/doc-links.js";
 
 function parseJsonSafe(text) {
   try {
@@ -188,7 +189,7 @@ export async function runPreflightChecks({ config, logger, emitter, eventBase, r
       result.errors.push({
         check: "docker",
         message: "Docker not available but SonarQube is enabled.",
-        fix: "Start Docker, or disable SonarQube: set sonarqube.enabled: false in kj.config.yml, or pass --no-sonar."
+        fix: withDocLink("Start Docker, or disable SonarQube: set sonarqube.enabled: false in kj.config.yml, or pass --no-sonar.", "sonar_docker")
       });
       logger.error("Preflight: Docker not found — SonarQube requires Docker");
 
@@ -222,7 +223,7 @@ export async function runPreflightChecks({ config, logger, emitter, eventBase, r
       result.errors.push({
         check: "sonar-reachable",
         message: `SonarQube not reachable at ${sonarHost}.`,
-        fix: "Start SonarQube: 'docker start karajan-sonarqube', or disable it: set sonarqube.enabled: false in kj.config.yml, or pass --no-sonar."
+        fix: withDocLink("Start SonarQube: 'docker start karajan-sonarqube', or disable it: set sonarqube.enabled: false in kj.config.yml, or pass --no-sonar.", "sonar_docker")
       });
       logger.error("Preflight: SonarQube not reachable after remediation attempt");
     }
@@ -248,7 +249,7 @@ export async function runPreflightChecks({ config, logger, emitter, eventBase, r
       result.errors.push({
         check: "sonar-auth",
         message: "SonarQube is running but no authentication token is configured.",
-        fix: "Fix: run 'kj init' to configure it, or set KJ_SONAR_TOKEN env var, or add sonarqube.token to ~/.karajan/kj.config.yml."
+        fix: withDocLink("Fix: run 'kj init' to configure it, or set KJ_SONAR_TOKEN env var, or add sonarqube.token to ~/.karajan/kj.config.yml.", "sonar_token")
       });
       logger.error("Preflight: Sonar auth failed");
     }

package/src/utils/doc-links.js

@@ -0,0 +1,27 @@
+/**
+ * Documentation links for error messages.
+ *
+ * Maps error types to their relevant documentation page so that
+ * every actionable error includes a "See: <url>" pointer.
+ */
+
+const BASE_URL = "https://karajancode.com/docs";
+
+const ERROR_DOCS = {
+  sonar_token: `${BASE_URL}/guides/configuration/#sonarqube`,
+  sonar_docker: `${BASE_URL}/getting-started/installation/#docker`,
+  agent_not_found: `${BASE_URL}/getting-started/installation/#agents`,
+  bootstrap_failed: `${BASE_URL}/guides/troubleshooting/`,
+  config_missing: `${BASE_URL}/getting-started/quick-start/`,
+  branch_error: `${BASE_URL}/guides/pipeline/#git-workflow`,
+  rtk_install: `${BASE_URL}/guides/configuration/#rtk`,
+};
+
+export function docLink(errorType) {
+  return ERROR_DOCS[errorType] || `${BASE_URL}/guides/troubleshooting/`;
+}
+
+export function withDocLink(message, errorType) {
+  const link = docLink(errorType);
+  return `${message}\n  See: ${link}`;
+}

package/src/utils/stack-detect.js

@@ -0,0 +1,135 @@
+/**
+ * Detects the project technology stack by scanning project files.
+ * Used by `kj init` to auto-configure roles, skills, and settings.
+ */
+
+import fs from "node:fs/promises";
+import path from "node:path";
+
+/**
+ * Frameworks detectable from package.json dependencies.
+ * Maps dependency name -> { name, type } where type is "frontend" | "backend" | "fullstack".
+ */
+const PKG_FRAMEWORKS = {
+  react: { name: "react", type: "frontend" },
+  "react-dom": { name: "react", type: "frontend" },
+  vue: { name: "vue", type: "frontend" },
+  svelte: { name: "svelte", type: "frontend" },
+  "@angular/core": { name: "angular", type: "frontend" },
+  astro: { name: "astro", type: "frontend" },
+  next: { name: "next", type: "fullstack" },
+  nuxt: { name: "nuxt", type: "fullstack" },
+  "solid-js": { name: "solid", type: "frontend" },
+  lit: { name: "lit", type: "frontend" },
+  express: { name: "express", type: "backend" },
+  fastify: { name: "fastify", type: "backend" },
+  "@nestjs/core": { name: "nestjs", type: "backend" },
+  hono: { name: "hono", type: "backend" },
+  koa: { name: "koa", type: "backend" },
+};
+
+/**
+ * Language markers: file presence -> { language, type }.
+ */
+const LANGUAGE_FILE_MARKERS = [
+  { file: "go.mod", language: "go", type: "backend" },
+  { file: "Cargo.toml", language: "rust", type: "backend" },
+  { file: "pom.xml", language: "java", type: "backend" },
+  { file: "build.gradle", language: "java", type: "backend" },
+  { file: "build.gradle.kts", language: "kotlin", type: "backend" },
+  { file: "pyproject.toml", language: "python", type: "backend" },
+  { file: "setup.py", language: "python", type: "backend" },
+  { file: "requirements.txt", language: "python", type: "backend" },
+  { file: "Gemfile", language: "ruby", type: "backend" },
+  { file: "composer.json", language: "php", type: "backend" },
+  { file: "pubspec.yaml", language: "dart", type: "frontend" },
+  { file: "Package.swift", language: "swift", type: "backend" },
+];
+
+/**
+ * Maps framework names to skill names for auto-install suggestions.
+ */
+const FRAMEWORK_TO_SKILL = {
+  react: "react",
+  vue: "vue",
+  svelte: "svelte",
+  angular: "angular",
+  astro: "astro",
+  next: "nextjs",
+  nuxt: "vue",
+  solid: "solid",
+  lit: "lit",
+  express: "express",
+  fastify: "fastify",
+  nestjs: "nestjs",
+};
+
+/**
+ * Detect the project technology stack.
+ * @param {string} projectDir - Absolute path to project root.
+ * @returns {Promise<{frameworks: string[], language: string|null, isFrontend: boolean, isBackend: boolean, isFullstack: boolean, suggestions: {impeccable: boolean, skills: string[]}}>}
+ */
+export async function detectProjectStack(projectDir) {
+  const frameworks = new Set();
+  let language = null;
+  let hasFrontend = false;
+  let hasBackend = false;
+
+  // 1. Scan package.json for known frameworks
+  try {
+    const pkgRaw = await fs.readFile(path.join(projectDir, "package.json"), "utf8");
+    const pkg = JSON.parse(pkgRaw);
+    const allDeps = { ...pkg.dependencies, ...pkg.devDependencies };
+
+    if (!language) language = "javascript";
+
+    // Check for TypeScript
+    if (allDeps.typescript || allDeps["ts-node"]) {
+      language = "typescript";
+    }
+
+    for (const [dep, info] of Object.entries(PKG_FRAMEWORKS)) {
+      if (allDeps[dep]) {
+        frameworks.add(info.name);
+        if (info.type === "frontend" || info.type === "fullstack") hasFrontend = true;
+        if (info.type === "backend" || info.type === "fullstack") hasBackend = true;
+      }
+    }
+  } catch { /* no package.json or parse error */ }
+
+  // 2. Check language file markers
+  for (const marker of LANGUAGE_FILE_MARKERS) {
+    try {
+      await fs.access(path.join(projectDir, marker.file));
+      if (!language || language === "javascript") {
+        language = marker.language;
+      }
+      if (marker.type === "frontend") hasFrontend = true;
+      if (marker.type === "backend") hasBackend = true;
+    } catch { /* file not found */ }
+  }
+
+  const frameworkList = Array.from(frameworks);
+  const isFullstack = hasFrontend && hasBackend;
+
+  // Build suggestions
+  const skills = [];
+  for (const fw of frameworkList) {
+    const skill = FRAMEWORK_TO_SKILL[fw];
+    if (skill && !skills.includes(skill)) {
+      skills.push(skill);
+    }
+  }
+
+  return {
+    frameworks: frameworkList,
+    language,
+    isFrontend: hasFrontend,
+    isBackend: hasBackend,
+    isFullstack,
+    suggestions: {
+      impeccable: hasFrontend,
+      skills,
+    },
+  };
+}

package/src/utils/status-dashboard.js

@@ -0,0 +1,254 @@
+/**
+ * Status dashboard formatter.
+ * Builds a structured terminal dashboard from session data and run-log lines.
+ */
+
+import { HU_STATUS } from "../hu/store.js";
+
+/**
+ * Status label mapping with visual indicators for terminal output.
+ * @type {Record<string, string>}
+ */
+const STATUS_LABELS = {
+  [HU_STATUS.PENDING]:       "pending",
+  [HU_STATUS.CODING]:        "coding",
+  [HU_STATUS.REVIEWING]:     "reviewing",
+  [HU_STATUS.DONE]:          "done",
+  [HU_STATUS.FAILED]:        "failed",
+  [HU_STATUS.BLOCKED]:       "blocked",
+  [HU_STATUS.CERTIFIED]:     "certified",
+  [HU_STATUS.NEEDS_CONTEXT]: "needs_ctx",
+};
+
+/**
+ * Format a millisecond duration into a human-readable string (e.g. "3m 42s").
+ * @param {number} ms
+ * @returns {string}
+ */
+export function formatDuration(ms) {
+  if (!ms || ms < 0) return "0s";
+  const totalSec = Math.floor(ms / 1000);
+  const hours = Math.floor(totalSec / 3600);
+  const minutes = Math.floor((totalSec % 3600) / 60);
+  const seconds = totalSec % 60;
+
+  const parts = [];
+  if (hours > 0) parts.push(`${hours}h`);
+  if (minutes > 0) parts.push(`${minutes}m`);
+  if (seconds > 0 || parts.length === 0) parts.push(`${seconds}s`);
+  return parts.join(" ");
+}
+
+/**
+ * Parse the current pipeline stage from log lines.
+ * @param {string[]} lines - Raw log lines.
+ * @returns {{ currentStage: string|null, lastEvent: string|null }}
+ */
+export function parseStageFromLog(lines) {
+  let currentStage = null;
+  let lastEvent = null;
+
+  for (const line of lines) {
+    const stageStart = /\[(\w+):start\]/.exec(line);
+    if (stageStart) currentStage = stageStart[1];
+
+    const stageDone = /\[(\w+):done\]|\[(\w+)\] finished/.exec(line);
+    if (stageDone) {
+      const doneName = stageDone[1] || stageDone[2];
+      if (doneName === currentStage) currentStage = "idle";
+    }
+
+    if (line.includes("[standby]") || line.includes("standby")) {
+      currentStage = "standby";
+    }
+
+    if (line.trim()) lastEvent = line.trim();
+  }
+
+  return { currentStage, lastEvent };
+}
+
+/**
+ * Format a single HU line for the dashboard.
+ * @param {object} story - HU story object.
+ * @param {boolean} isCurrent - Whether this is the currently active HU.
+ * @returns {string}
+ */
+function formatHuLine(story, isCurrent) {
+  const id = (story.id || "???").padEnd(12);
+  const rawStatus = story.status || "pending";
+  const label = STATUS_LABELS[rawStatus] || rawStatus;
+  const statusStr = `[${label}]`.padEnd(13);
+  const title = story.title || story.original?.text || "(untitled)";
+  const truncTitle = title.length > 40 ? title.slice(0, 37) + "..." : title;
+
+  let timing = "";
+  if (story.duration_ms) {
+    timing = formatDuration(story.duration_ms);
+  }
+
+  const blockedInfo = story.blocked_by?.length
+    ? ` (needs ${story.blocked_by.join(", ")})`
+    : "";
+
+  const marker = isCurrent ? "  <-- current" : "";
+  const timingStr = timing ? `  ${timing}` : "";
+
+  return `  ${id} ${statusStr} ${truncTitle}${blockedInfo}${timingStr}${marker}`;
+}
+
+/**
+ * Build a terminal dashboard string from session data and log lines.
+ *
+ * @param {object|null} sessionData - Session JSON (from session-store) or null.
+ * @param {string[]} logLines - Raw run-log lines.
+ * @param {object} [options] - Optional overrides.
+ * @param {object[]|null} [options.stories] - HU stories array (from hu batch).
+ * @returns {string}
+ */
+export function buildDashboard(sessionData, logLines, options = {}) {
+  if (!sessionData) {
+    return "No active pipeline";
+  }
+
+  const lines = [];
+  const config = sessionData.config_snapshot || {};
+  const maxIter = config.max_iterations ?? "?";
+  const status = sessionData.status || "unknown";
+
+  // Parse log for current stage info
+  const logInfo = parseStageFromLog(logLines || []);
+
+  // Determine iteration from session or log
+  const iteration = sessionData.reviewer_retry_count != null
+    ? sessionData.reviewer_retry_count + 1
+    : null;
+  const iterFromLog = parseIterationFromLog(logLines || []);
+  const displayIter = iterFromLog || iteration || "?";
+
+  // Pipeline header
+  const statusUpper = status.toUpperCase();
+  lines.push(`Pipeline: ${statusUpper} (iteration ${displayIter}/${maxIter})`);
+
+  // Duration
+  const duration = computeDuration(sessionData);
+  lines.push(`Duration: ${formatDuration(duration)}`);
+
+  // Agent info
+  const coderProvider = config.coder?.provider || config.roles?.coder?.provider || "?";
+  const reviewerProvider = config.reviewer?.provider || config.roles?.reviewer?.provider || "?";
+  lines.push(`Agent: ${coderProvider} (coder) / ${reviewerProvider} (reviewer)`);
+
+  // HU stories section
+  const stories = options.stories || [];
+  if (stories.length > 0) {
+    lines.push("");
+    lines.push("HUs:");
+
+    // Determine which story is currently being worked on
+    const currentStory = stories.find(s =>
+      s.status === HU_STATUS.CODING || s.status === HU_STATUS.REVIEWING
+    );
+
+    for (const story of stories) {
+      const isCurrent = currentStory && story.id === currentStory.id;
+      lines.push(formatHuLine(story, isCurrent));
+    }
+  }
+
+  // Current stage and last event
+  lines.push("");
+  const stage = logInfo.currentStage || "idle";
+  const iterSuffix = displayIter !== "?" ? ` (iteration ${displayIter})` : "";
+  lines.push(`Current stage: ${stage}${iterSuffix}`);
+
+  if (logInfo.lastEvent) {
+    // Truncate last event for display
+    const maxLen = 120;
+    const event = logInfo.lastEvent.length > maxLen
+      ? logInfo.lastEvent.slice(0, maxLen - 3) + "..."
+      : logInfo.lastEvent;
+    lines.push(`Last event: ${event}`);
+  }
+
+  // Errors
+  if (sessionData.deferred_issues?.length) {
+    lines.push("");
+    lines.push(`Deferred issues: ${sessionData.deferred_issues.length}`);
+  }
+
+  return lines.join("\n");
+}
+
+/**
+ * Build a structured JSON response for MCP consumers.
+ *
+ * @param {object|null} sessionData - Session JSON or null.
+ * @param {string[]} logLines - Raw run-log lines.
+ * @param {object} [options] - Optional overrides.
+ * @param {object[]|null} [options.stories] - HU stories array.
+ * @returns {object}
+ */
+export function buildDashboardJson(sessionData, logLines, options = {}) {
+  if (!sessionData) {
+    return { ok: false, message: "No active pipeline" };
+  }
+
+  const config = sessionData.config_snapshot || {};
+  const logInfo = parseStageFromLog(logLines || []);
+  const iterFromLog = parseIterationFromLog(logLines || []);
+  const iteration = iterFromLog
+    || (sessionData.reviewer_retry_count != null ? sessionData.reviewer_retry_count + 1 : null);
+
+  const stories = (options.stories || []).map(s => ({
+    id: s.id,
+    status: s.status || "pending",
+    title: s.title || s.original?.text || null,
+    blocked_by: s.blocked_by || [],
+    duration_ms: s.duration_ms || null,
+  }));
+
+  return {
+    ok: true,
+    pipeline: {
+      status: sessionData.status || "unknown",
+      iteration: iteration || null,
+      maxIterations: config.max_iterations ?? null,
+      duration_ms: computeDuration(sessionData),
+      coder: config.coder?.provider || config.roles?.coder?.provider || null,
+      reviewer: config.reviewer?.provider || config.roles?.reviewer?.provider || null,
+    },
+    hus: stories,
+    currentStage: logInfo.currentStage || "idle",
+    lastEvent: logInfo.lastEvent || null,
+  };
+}
+
+/**
+ * Parse iteration number from log lines.
+ * @param {string[]} lines
+ * @returns {number|null}
+ */
+function parseIterationFromLog(lines) {
+  let iteration = null;
+  for (const line of lines) {
+    const m = /[Ii]teration\s+(\d+)/.exec(line);
+    if (m) iteration = Number.parseInt(m[1], 10);
+  }
+  return iteration;
+}
+
+/**
+ * Compute pipeline duration in milliseconds from session timestamps.
+ * @param {object} sessionData
+ * @returns {number}
+ */
+function computeDuration(sessionData) {
+  const created = sessionData.created_at;
+  if (!created) return 0;
+  const start = new Date(created).getTime();
+  const now = sessionData.updated_at
+    ? new Date(sessionData.updated_at).getTime()
+    : Date.now();
+  return Math.max(0, now - start);
+}