karajan-code 4.70.3 → 5.0.0

package/packages/hu-board/src/routes/governance.js

@@ -84,9 +84,31 @@ router.get("/", async (req, res) => {
     if (err?.code === "ENOENT") return res.status(503).json({ ok: false, error: "kj not installed", installable: true });
     return res.status(500).json({ ok: false, error: String(err.message || err) });
   }
-  res.json({ ok: true, dir, policy: policySummary(dir), report, anchor: anchorState(dir, report.chain?.length ?? 0), identity: identityState(dir) });
+  res.json({ ok: true, dir, policy: policySummary(dir), report, anchor: anchorState(dir, report.chain?.length ?? 0), identity: identityState(dir), lanes: await laneWarnings(dir) });
 });
 
+/**
+ * KJC-TSK-1314: lanes outside the method. A branch naming no card, and a lane whose PR is merged
+ * with nothing after it (a fresh lane also has 0 commits ahead, so the merged PR is what tells).
+ */
+async function laneWarnings(dir) {
+  const none = (error) => ({ noCard: [], merged: [], error });
+  try {
+    const r = await runCommand("kj", ["worktree", "list", "--json", "--prs"], { cwd: dir });
+    const line = String(r.stdout || "").trim().split("\n").findLast((l) => l.startsWith("["));
+    if (r.exitCode !== 0 || !line) return none(`kj worktree list --json failed (exit ${r.exitCode})`);
+    const lanes = JSON.parse(line);
+    return {
+      noCard: lanes.filter((l) => l.cards.length === 0).map(({ slug, branch }) => ({ slug, branch })),
+      merged: lanes.filter((l) => l.pr?.state === "MERGED" && l.ahead === 0)
+        .map(({ slug, branch, pr }) => ({ slug, branch, pr: pr.number, done: `kj worktree done ${slug}` })),
+      error: null,
+    };
+  } catch (err) {
+    return none(String(err.message || err));
+  }
+}
+
 // GUI-C (KJC-TSK-0773): actions go through the SAME CLI commands the
 // terminal uses — the inexemptable (security, defaults.*) is refused by kj
 // itself and its message travels back verbatim; nothing is re-implemented.

package/packages/hu-board/src/routes/lanes.js

@@ -0,0 +1,40 @@
+// KJC-TSK-1313: the worktree lanes working each card of a project, for the badge on the card.
+// They come from `kj worktree list --json`: read from git every time, never stored, and the board
+// stays decoupled from the CLI tree (KJC-TSK-0632). A failure is data for the view, never a 500.
+import { Router } from 'express';
+import { runCommand } from 'karajan-core/process';
+
+import { requestProjectDir } from '../project-dir.js';
+
+const router = Router();
+
+// KJC-TSK-1316: each lane's PR comes from GitHub; a good answer is kept a minute per project.
+const CACHE_MS = 60_000;
+const cache = new Map();
+
+router.get('/:project', async (req, res) => {
+  const { project } = req.params;
+  const hit = cache.get(project);
+  if (hit && Date.now() - hit.at < CACHE_MS) return res.json(hit.body);
+  try {
+    const dir = requestProjectDir(project);
+    const r = await runCommand('kj', ['worktree', 'list', '--json', '--prs'], { cwd: dir });
+    const line = String(r.stdout || '').trim().split('\n').findLast((l) => l.startsWith('['));
+    if (r.exitCode !== 0 || !line) return res.json({ byStory: {}, error: `kj worktree list --json failed (exit ${r.exitCode})` });
+    const byStory = {};
+    for (const lane of JSON.parse(line)) {
+      // Story ids on the board are `<project>::<hu id>` (sync.js).
+      for (const card of lane.cards) {
+        const key = `${project}::${card}`;
+        byStory[key] ??= [];
+        byStory[key].push(lane);
+      }
+    }
+    cache.set(project, { at: Date.now(), body: { byStory } });
+    return res.json({ byStory });
+  } catch (err) {
+    return res.json({ byStory: {}, error: String(err.message || err) });
+  }
+});
+
+export default router;

package/packages/hu-board/src/routes/rag.js

@@ -4,7 +4,7 @@
 // "uninitialized" payload so the dashboard renders an empty state cleanly.
 import { Router } from "express";
 import { existsSync, statSync } from "node:fs";
-import Database from "better-sqlite3";
+import { openDatabase } from "karajan-core/db";
 import { dbPath } from "karajan-core/vec-store";
 import { readConfig } from "../config-yaml.js";
 
@@ -23,8 +23,9 @@ router.get("/stats", (_req, res) => {
   const path = dbPath();
   if (!existsSync(path)) return res.json({ ok: true, initialized: false, message: "rag.db not initialized — run `kj rag index <dir>` to start indexing.", embedder: embedder() });
   try {
-    const db = new Database(path, { readonly: true, fileMustExist: true });
-    // KJC-BUG-0068 — readonly handler cannot run the project_slug migration
+    // KJC-TSK-0617: node:sqlite adapter. The file was checked above and this route only reads.
+    const db = openDatabase(path);
+    // KJC-BUG-0068 — this route never runs the project_slug migration
     // (KJC-TSK-0438). Legacy DBs created pre-v2.27 lack the column; detect
     // and fall back so the dashboard renders instead of crashing with 500.
     const hasProjectSlug = db.prepare("PRAGMA table_info(chunks)").all().some((c) => c.name === "project_slug");

package/packages/hu-board/src/server.js

@@ -11,6 +11,7 @@ import pipelineRoutes from './routes/pipeline.js';
 import ragRoutes from './routes/rag.js';
 import wikiRoutes from './routes/wiki.js';
 import governanceRoutes from './routes/governance.js';
+import lanesRoutes from './routes/lanes.js';
 import { authMiddleware } from './auth.js';
 import { getOrCreateToken, getTokenPath } from './token-store.js';
 import { createRequire } from 'node:module';
@@ -165,21 +166,29 @@ export function buildRateLimiter() {
   });
 }
 
+/**
+ * KJC-BUG-0463: mounted on /api after every API router, so an API route that does not
+ * exist gets a 404 JSON naming it instead of falling to the SPA's index.html (a 200
+ * the caller then fails to parse).
+ * @type {import('express').RequestHandler}
+ */
+export function apiNotFound(req, res) {
+  res.status(404).json({ error: `no such API route: ${req.method} ${req.originalUrl}` });
+}
+
 /**
  * Main entry point: initializes database, syncs data, and starts the server.
  */
 async function main() {
-  // Initialize SQLite. better-sqlite3 is a native module — when its
-  // prebuilt binary is missing or ABI-mismatched (Node was upgraded),
-  // initDb() throws. Surface an actionable message instead of a bare
-  // stack trace so the user knows exactly what to run.
+  // Initialize SQLite (node:sqlite, built into Node 22+: KJC-TSK-0617). When
+  // initDb() throws, surface an actionable message instead of a bare stack trace.
   console.log('[server] Initializing database...');
   try {
     initDb();
   } catch (err) {
     console.error('[server] FATAL: could not initialize the database.');
-    console.error('[server] The native module better-sqlite3 failed to load, or the DB file could not be opened.');
-    console.error('[server] Fix: run `npm rebuild better-sqlite3` (or reinstall karajan-code).');
+    console.error('[server] The DB file could not be opened, or this Node has no node:sqlite (it needs Node 22.12 or newer).');
+    console.error('[server] Fix: check the path in the error below, or upgrade Node.');
     console.error('[server] Original error:', err?.stack || String(err));
     process.exit(1);
   }
@@ -235,34 +244,6 @@ async function main() {
     console.warn(`[hu-zombie-reaper] skipped: ${err.message}`);
   }
 
-  // KJC-TSK-0414 PR2 — reconciliación de sesiones hibernadas al arrancar.
-  // Para cada session en ~/.kj/standby/<id>.json:
-  //   - cooldownUntil <= now → spawn `kj resume <id>` inmediato
-  //   - cooldownUntil > now  → re-programa setTimeout que dispara en cooldown
-  // Idempotente (lockfile per session). Cero polling.
-  try {
-    const { reconcileAll } = await import('karajan-core/standby-scheduler');
-    const { spawn } = await import('node:child_process');
-    const { join, dirname } = await import('node:path');
-    const { fileURLToPath } = await import('node:url');
-    const KJ_CLI = join(dirname(fileURLToPath(import.meta.url)), '..', '..', '..', 'src', 'cli.js');
-    const onResume = (sessionId) => {
-      console.log(`[standby] reanudando sesión ${sessionId} (spawn kj standby resume)`);
-      try {
-        const child = spawn(process.execPath, [KJ_CLI, 'standby', 'resume', sessionId], {
-          detached: true, stdio: 'ignore', env: process.env,
-        });
-        child.unref();
-      } catch (err) {
-        console.warn(`[standby] spawn resume falló para ${sessionId}: ${err.message}`);
-      }
-    };
-    const r = reconcileAll({ onResume, logger: { info: console.log.bind(console), warn: console.warn.bind(console) } });
-    if (r.total > 0) console.log(`[standby] reconcile: ${r.total} session(es) — ${r.immediate} resume inmediato, ${r.scheduled} programadas`);
-  } catch (err) {
-    console.warn(`[standby] reconcile skipped: ${err.message}`);
-  }
-
   // KJC-TSK-0371 (board polish #3) — clean up ephemeral projects
   // (`/tmp/`-rooted, `tmp_*`/`test_*`/`demo_*`/`kj-test-*` prefixed)
   // that have been inactive for >24h. Runs AFTER the zombie-reaper
@@ -308,6 +289,7 @@ async function main() {
   app.use('/api/rag', authMiddleware(), ragRoutes);
   app.use('/api/wiki', authMiddleware(), wikiRoutes);
   app.use('/api/governance', authMiddleware(), governanceRoutes);
+  app.use('/api/lanes', authMiddleware(), lanesRoutes);
 
   // Terminal embebida (KJC-TSK-0816, ADR 0008): la lógica vive en
   // terminal.js; aquí solo el montaje. El agente arranca en el cwd del
@@ -327,6 +309,10 @@ async function main() {
     '/vendor/xterm',
     express.static(dirname(requireCjs.resolve('@xterm/xterm/package.json'))),
   );
+  // KJC-TSK-1198: driver.js (MIT, pinned) for the guided tour, from the dependency's dist/.
+  app.use('/vendor/driver', express.static(dirname(requireCjs.resolve('driver.js'))));
+
+  app.use('/api', apiNotFound);
 
   // SPA fallback: serve index.html for non-API, non-static routes
   app.get('/{*splat}', (_req, res) => {

package/packages/hu-board/src/sync-files.js

@@ -0,0 +1,318 @@
+// KJC-TSK-0542: how one file on disk becomes rows in the board DB: a session.json or a v2 plan.
+// sync.js runs them from fullScan and the watcher, and re-exports syncPlanFile.
+import { readFileSync, rmSync } from 'node:fs';
+import { dirname, join, basename } from 'node:path';
+import {
+  upsertProject,
+  upsertStory,
+  upsertSession,
+  getDb,
+  isTombstoned,
+  getTombstone,
+  removeTombstone,
+} from './db.js';
+import { publish as publishEvent } from './event-bus.js';
+import { isSharedPath } from 'karajan-core/shared-paths';
+import {
+  deriveProjectIdFromDir,
+  canonicalProjectDir,
+  titleCaseBasename,
+  slugToTitle,
+} from './sync-project.js';
+
+/**
+ * Skip + best-effort fs cleanup when the resource is tombstoned. Returns
+ * true if the caller should bail out (resource is dead).
+ *
+ * KJC-TSK-0380: without this, every fullScan/chokidar event resurrects
+ * resources the user already deleted via the API.
+ */
+function skipIfTombstoned(resourceType, resourceId, fsPathToRemove) {
+  if (!isTombstoned(resourceType, resourceId)) return false;
+  if (fsPathToRemove) {
+    try { rmSync(fsPathToRemove, { recursive: true, force: true }); } catch { /* best effort */ }
+  }
+  return true;
+}
+
+/**
+ * Parses a session.json file and syncs to SQLite.
+ * @param {string} filePath - Absolute path to session.json
+ */
+export function syncSessionFile(filePath) {
+  try {
+    const raw = readFileSync(filePath, 'utf-8');
+    const data = JSON.parse(raw);
+    const sessionId = data.id || basename(join(filePath, '..'));
+
+    if (skipIfTombstoned('session', sessionId, dirname(filePath))) return;
+
+    // Resolve which project this session belongs to:
+    //   1. If a plan / HU batch already created `auto-<sessionId>`, reuse it
+    //      so plan-based runs group with their HU batch.
+    //   2. Otherwise fall back to the session's declared `project_id`.
+    //   3. Otherwise → REJECT. Orphan sessions (no project_id and no batch)
+    //      USED to be promoted to a fake "Orphan sessions" project, which
+    //      violated the user's invariant: "Si se crea proyecto y se crean
+    //      hus se asocian a proyecto. ES IMPOSIBLE QUE [no exista esa
+    //      asociación]". Now we skip them entirely. The fix for the source
+    //      (kj run always stamps project_id derived from cwd) lives in
+    //      PR-F; this is the safety net so a leftover orphan can never
+    //      again appear as a phantom project on the board.
+    const autoProjectId = `auto-${sessionId}`;
+    const db = getDb();
+    const existingBatch = db.prepare('SELECT id FROM projects WHERE id = ?').get(autoProjectId);
+    let projectId;
+    if (existingBatch) {
+      projectId = autoProjectId;
+    } else if (data.project_id) {
+      projectId = data.project_id;
+    } else {
+      // Orphan: log + skip. Never promote to "default".
+      console.warn(`[sync] Session ${sessionId} has no project_id and no matching batch — skipping (orphan). File: ${filePath}`);
+      return;
+    }
+
+    // Ensure the project row exists. Skip when an auto-batch owns it already
+    // (that row was written with richer metadata and we do
+    // not want to overwrite name/total_stories).
+    if (!existingBatch) {
+      upsertProject({
+        id: projectId,
+        name: projectId,
+        last_activity: data.updated_at || data.created_at || new Date().toISOString(),
+        total_stories: 0,
+      });
+    }
+
+    // Calculate iterations from checkpoints
+    const checkpoints = data.checkpoints || [];
+    const maxIteration = checkpoints.reduce((max, cp) => Math.max(max, cp.iteration || 0), 0);
+
+    // Calculate duration from first and last checkpoint
+    let durationMs = null;
+    if (data.created_at && data.updated_at) {
+      durationMs = new Date(data.updated_at).getTime() - new Date(data.created_at).getTime();
+    }
+
+    // Collect completed stages
+    const stagesSet = new Set();
+    for (const cp of checkpoints) {
+      if (cp.stage && !cp.stage.includes('attempt') && !cp.stage.includes('checkpoint')) {
+        stagesSet.add(cp.stage);
+      }
+    }
+
+    // Project row was created above (unless an auto-batch owns it); the
+    // session always has a project to attach to now.
+
+    upsertSession({
+      id: sessionId,
+      project_id: projectId,
+      task: data.task || null,
+      status: data.status || 'unknown',
+      created_at: data.created_at,
+      updated_at: data.updated_at,
+      iterations: maxIteration,
+      duration_ms: durationMs,
+      approved: data.status === 'approved' ? 1 : 0,
+      commits: data.commits ? JSON.stringify(data.commits) : null,
+      stages_completed: JSON.stringify([...stagesSet]),
+      checkpoints: JSON.stringify(checkpoints),
+      llm_calls: data.llm_calls ? JSON.stringify(data.llm_calls) : null,
+      config_snapshot: data.config_snapshot ? JSON.stringify(data.config_snapshot) : null,
+      budget: data.budget ? JSON.stringify(data.budget) : null,
+    });
+
+    console.log(`[sync] Synced session ${sessionId}: status=${data.status}, iterations=${maxIteration}`);
+    publishEvent({ type: 'session', projectId, sessionId });
+  } catch (err) {
+    console.error(`[sync] Error syncing session file ${filePath}:`, err.message);
+  }
+}
+
+/**
+ * Sync a v2 plan file (with embedded HUs) to SQLite.
+ * Plans are the authoritative source — replaces hu-stories for plan-based runs.
+ */
+export function syncPlanFile(filePath) {
+  try {
+    const raw = readFileSync(filePath, 'utf-8');
+    const data = JSON.parse(raw);
+    // KJC-BUG-0124 (issue #1277): a strict `version !== 2` silently hid
+    // every plan whose version drifted — the board showed 0 stories with no
+    // trace, and users concluded their work was lost. Tolerant now: any
+    // v2+ plan syncs, with a LOUD warn on version drift (fired before the
+    // empty check so drift is visible even on empty plans). Pre-v2 plans
+    // keep their historical silent skip (they never synced and carry no
+    // hus[]), and an empty v2 plan has nothing to sync — skipping it
+    // loses nothing.
+    if (typeof data.version !== 'number' || data.version < 2) return;
+    if (data.version > 2) {
+      console.warn(`[sync] ${filePath}: plan version ${data.version} (expected 2) — syncing anyway; re-save with current kj to normalize`);
+    }
+    if (!Array.isArray(data.hus) || data.hus.length === 0) return;
+
+    // Bug fix: pre-patch, `projectId = data.planId` — every plan was a separate
+    // "project" on the board, so 2 464 plans across the same repo produced
+    // 2 464 boxes in the UI instead of one. Now we derive the project from
+    // the stamped `projectDir` so every plan for the same source tree groups
+    // under a single board entry. Legacy plans without `projectDir` still
+    // fall back to `planId` (conservative — they at least continue to show
+    // up, just each on its own card).
+    // KJC-BUG-0160: la identidad es el ROOT del repo — un plan creado desde
+    // un worktree/carril agrupa bajo el mismo proyecto que el árbol principal.
+    const canonicalDir = data.projectDir ? canonicalProjectDir(data.projectDir) : null;
+    const projectId = canonicalDir ? deriveProjectIdFromDir(canonicalDir) : data.planId;
+
+    if (skipIfTombstoned('plan', data.planId, filePath)) return;
+    // KJC-BUG-0055 (supersedes KJC-BUG-0050): gating por timestamp.
+    // El "fix" anterior quitaba el tombstone del proyecto en CUALQUIER
+    // llegada de plan — eso resucitaba proyectos borrados cuando un plan
+    // anterior reaparecía (DB nueva + plan-files viejos en disco) o
+    // cuando un fullScan posterior los re-encontraba. Comportamiento:
+    //   • plan.updatedAt/createdAt > tombstone.deleted_at → el usuario
+    //     ha generado el plan DESPUÉS de borrar el proyecto → revivir.
+    //   • plan.updatedAt/createdAt <= tombstone.deleted_at → plan stale
+    //     pre-existente al borrado → respetar el tombstone y borrar el
+    //     fichero en disco para que no vuelva a re-importarse.
+    const projectTomb = getTombstone('project', projectId);
+    if (projectTomb) {
+      const planTime = data.updatedAt || data.createdAt || null;
+      const planTs = planTime ? Date.parse(planTime) : NaN;
+      const tombTs = Date.parse(projectTomb.deleted_at);
+      if (Number.isFinite(planTs) && planTs > tombTs) {
+        console.log(`[sync] Project ${projectId} resucitado: plan ${data.planId} es más reciente (${planTime}) que el tombstone (${projectTomb.deleted_at}).`);
+        removeTombstone('project', projectId);
+      } else {
+        console.log(`[sync] Plan ${data.planId} ignorado: proyecto ${projectId} tombstoned (${projectTomb.deleted_at}); borrando ${filePath}.`);
+        try { rmSync(filePath, { force: true }); } catch { /* best effort */ }
+        return;
+      }
+    }
+    // Human-friendly project name resolution order (most-specific first):
+    //   1. plan.name explicitly set by the user / planner ("Linux Assistant
+    //      Orchestrator" — preserved across renames done from the board).
+    //   2. titleCaseBasename(projectDir) — derived from the cwd of the
+    //      original kj plan invocation. NOTE: this is the SUBCARPETA of the
+    //      projectDir, NOT necessarily where the work happens. If the user
+    //      ran `kj plan` from inside `…/karajan-code/packages/hu-board/`
+    //      with a SPEC about "Linux Assistant", the basename here would
+    //      misleadingly say "Hu Board" — that's why plan.name wins.
+    //   3. slugToTitle of the task / projectId as a last resort.
+    // KJC-BUG-0162: the default backlog plan is named "brain-backlog" — a
+    // DEFAULT, not a user choice. Every project synced through it ended up
+    // named "brain-backlog", indistinguishable in the picker. Only a real,
+    // user-given plan name may override the repo-derived name.
+    const userGivenName = data.name && data.name !== 'brain-backlog' ? data.name : null;
+    const projectName = userGivenName
+      || (canonicalDir ? titleCaseBasename(basename(canonicalDir)) : null)
+      || slugToTitle(data.task || '')
+      || projectId;
+
+    // KJC-PRP-0002 PR3: stamp `is_shared` from the path (authoritative — works
+    // even for legacy plan files without the `shared:true` envelope marker).
+    // OR with existing value so a single shared plan promotes the project,
+    // while unsharing the LAST shared plan still leaves the flag set (we
+    // clear it lazily only when the user explicitly tombstones / re-creates).
+    upsertProject({
+      id: projectId,
+      name: projectName,
+      last_activity: data.updatedAt || data.createdAt || new Date().toISOString(),
+      total_stories: data.hus.length,
+      is_shared: isSharedPath(filePath) || data.shared === true ? 1 : undefined,
+    });
+
+    for (let i = 0; i < data.hus.length; i += 1) {
+      const hu = data.hus[i];
+      const acList = Array.isArray(hu.acceptance_criteria) ? hu.acceptance_criteria : [];
+      // Only count tests that carry real content. `kj plan` stamps a
+      // placeholder like `["npx vitest run ..."]` on every HU — those
+      // DO count as 1 test each. But empty strings / null entries
+      // (which show up in half-baked plans) must not inflate the
+      // badge to "🧪 1 test" on a HU that effectively has none.
+      // Drop empty entries but accept BOTH legacy shapes and the
+      // v2.7.5 structured form. The original anti-junk filter only
+      // knew the legacy shape (`name|title|description|given|gherkin|
+      // scope`) and silently nuked every test produced by the
+      // tests-synthesizer (which emits `{type, content, file?}`),
+      // leaving every HU flagged "missing test contract" on the
+      // board even though the plan JSON had 4 tests apiece.
+      const testList = (Array.isArray(hu.acceptance_tests) ? hu.acceptance_tests : [])
+        .filter((t) => {
+          if (!t) return false;
+          if (typeof t === 'string') return t.trim().length > 0;
+          if (typeof t !== 'object') return false;
+          // v2.7.5 structured form — primary shape going forward.
+          if (typeof t.content === 'string' && t.content.trim().length > 0) return true;
+          // Legacy shapes kept for back-compat with hand-edited plans.
+          return Boolean(t.name || t.title || t.description || t.given || t.gherkin || t.scope);
+        });
+      const blockedByList = Array.isArray(hu.blocked_by) ? hu.blocked_by : [];
+      const acText = acList.length > 0 ? JSON.stringify(acList) : null;
+
+      upsertStory({
+        id: `${projectId}::${hu.id}`,
+        project_id: projectId,
+        session_id: projectId,
+        status: hu.status || 'pending',
+        title: hu.title || hu.id,
+        original_text: hu.scope || null,
+        certified_as: null,
+        certified_want: hu.scope || null,
+        certified_so_that: null,
+        quality_total: null,
+        quality_d1: null, quality_d2: null, quality_d3: null,
+        quality_d4: null, quality_d5: null, quality_d6: null,
+        antipatterns: null,
+        ac_format: acText ? 'list' : null,
+        acceptance_criteria: acText,
+        created_at: hu.createdAt,
+        updated_at: hu.updatedAt,
+        certified_at: null,
+        // Stamp plan_id so the PATCH / mark-ready endpoints can locate
+        // the source plan JSON without walking the plans dir.
+        plan_id: data.planId,
+        // Denormalised counters + deps so the card renders "3 ACs ·
+        // 2 tests · waits for lao-001" without every client parsing JSON.
+        ac_count: acList.length,
+        test_count: testList.length,
+        blocked_by: blockedByList.length > 0 ? JSON.stringify(blockedByList) : null,
+        // Full test list goes to SQLite too so the modal can show
+        // "🧪 2 tests" next to the list. Pre-patch the card showed
+        // test_count but the modal had nothing to render.
+        acceptance_tests: testList.length > 0 ? JSON.stringify(testList) : null,
+        // Index in plan.hus[] — used by getStoriesByProject to order
+        // cards topologically (roots first, dependents last).
+        plan_order: i,
+        // Spec mapping (PR C): "implements §5.3" trace pointer.
+        spec_section: typeof hu.spec_section === 'string' && hu.spec_section.trim() ? hu.spec_section.trim() : null,
+        // PR3: per-HU outcome (iterations, duration, commits,
+        // blockers, summary). Stored as a JSON string in SQLite —
+        // the front parses on read. Null until hu-sub-pipeline
+        // stamps it at the end of each HU.
+        outcome: hu.outcome ? JSON.stringify(hu.outcome) : null,
+        // KJC-TSK-0394: result (pass|fail|partial|null) ortogonal al status.
+        // Distinto de `outcome` (blob JSON) — esto es el enum corto para
+        // badge ✓/✗ en la card.
+        result: hu.result || null,
+        // KJC-TSK-0406: coder_model y reviewer_model por HU. Reflejan
+        // qué modelo se va a usar (o se usó) en este HU. El modal del
+        // board los muestra y permite cambiarlos antes de run.
+        coder_model: hu.coder_model || null,
+        reviewer_model: hu.reviewer_model || null,
+        coder_provider: hu.coder_provider || null,
+        reviewer_provider: hu.reviewer_provider || null,
+        // KJC-PRP-0002 PR6: optional handle of the owner of this HU
+        // (free-form string). Only surfaced in UI when project is_shared,
+        // but stored unconditionally so values survive share/unshare flips.
+        assignee: typeof hu.assignee === 'string' && hu.assignee.trim() ? hu.assignee.trim() : null,
+      });
+    }
+
+    console.log(`[sync] Plan ${projectId}: ${data.hus.length} HUs (${projectName})`);
+    publishEvent({ type: 'plan', projectId, planId: data.planId });
+  } catch (err) {
+    console.error(`[sync] Failed to sync plan ${filePath}: ${err.message}`);
+  }
+}

package/packages/hu-board/src/sync-project.js

@@ -0,0 +1,99 @@
+// KJC-TSK-0542: how the sync names a project (id, canonical dir, display titles).
+// sync.js re-exports the public functions, so callers keep importing from there.
+import { execFileSync } from 'node:child_process';
+import { dirname, isAbsolute, resolve as resolvePath } from 'node:path';
+
+/**
+ * Derive a stable `project_id` from a plan's absolute `projectDir`.
+ * Used so every plan under the same source tree groups under one project
+ * on the board (instead of 1 project per plan — the 2 101-stories bug).
+ *
+ * @param {string} projectDir
+ * @returns {string}
+ */
+export function deriveProjectIdFromDir(projectDir) {
+  if (!projectDir || typeof projectDir !== 'string') return 'unknown';
+  // Same slug rule the plan-store uses, so identifiers match if we ever
+  // cross-reference `~/.kj/plans/<slug>/` with this project_id.
+  return projectDir
+    .replace(/^\//, '')
+    .replace(/[/\\]/g, '_')
+    .replace(/[^a-zA-Z0-9_.-]/g, '')
+    .slice(0, 120);
+}
+
+/** git-common-dir del directorio, con el stderr silenciado (no-git = throw). */
+const defaultGitCommonDir = (dir) =>
+  execFileSync('git', ['-C', dir, 'rev-parse', '--git-common-dir'], {
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'ignore'],
+  }).trim();
+
+const canonicalDirCache = new Map();
+
+/**
+ * Resolve a projectDir to the REPO's identity (KJC-BUG-0160): a linked
+ * worktree (`.claude/worktrees/*`, kj lanes) used to register the same
+ * repo as a brand-new project — 13+ same-named entries in a real picker.
+ * `git rev-parse --git-common-dir` points every worktree at the main
+ * tree's `.git`; its parent is the canonical root. A non-git directory
+ * keeps its own path as identity, as always.
+ *
+ * @param {string} projectDir
+ * @param {(dir: string) => string} [gitCommonDir] Inyectable en tests.
+ * @returns {string}
+ */
+export function canonicalProjectDir(projectDir, gitCommonDir = defaultGitCommonDir) {
+  if (!projectDir || typeof projectDir !== 'string') return projectDir;
+  if (canonicalDirCache.has(projectDir)) return canonicalDirCache.get(projectDir);
+  let canonical = projectDir;
+  try {
+    const common = gitCommonDir(projectDir);
+    const absCommon = isAbsolute(common) ? common : resolvePath(projectDir, common);
+    canonical = dirname(absCommon);
+  } catch {
+    // Sin git no hay más identidad que la ruta — comportamiento de siempre.
+  }
+  canonicalDirCache.set(projectDir, canonical);
+  return canonical;
+}
+
+/**
+ * Turn a directory basename into a human-friendly Title Case string,
+ * preserving every meaningful word. Unlike `slugToTitle`, this one does
+ * NOT apply stopword filtering — directory names are concise on purpose
+ * (e.g. "linux-assistant-orchestrator" → "Linux Assistant Orchestrator",
+ * "my-dev-tool" → "My Dev Tool").
+ *
+ * @param {string} name
+ * @returns {string}
+ */
+export function titleCaseBasename(name) {
+  const words = String(name || '')
+    .replace(/[_\s]+/g, '-')
+    .split('-')
+    .map((w) => w.replace(/[^\p{L}\p{N}]/gu, ''))
+    .filter(Boolean);
+  if (words.length === 0) return String(name || '');
+  return words.map((w) => w.charAt(0).toUpperCase() + w.slice(1).toLowerCase()).join(' ');
+}
+
+export function slugToTitle(text) {
+  const STOPWORDS = new Set([
+    'a', 'an', 'the', 'and', 'or', 'with', 'for', 'to', 'of', 'in', 'on',
+    'is', 'it', 'its', 'this', 'that', 'these', 'those', 'be', 'been', 'being',
+    'build', 'create', 'implement', 'make', 'develop', 'add', 'set', 'up',
+    'setup', 'write', 'code', 'new', 'complete', 'from', 'scratch',
+    'application', 'app', 'tool', 'system', 'project', 'using', 'use',
+    'full', 'full-stack', 'fullstack', 'stack', 'based', 'simple', 'basic',
+  ]);
+  const words = String(text || '')
+    .toLowerCase()
+    .replace(/[^\p{L}\p{N}\s-]/gu, ' ')
+    .split(/\s+/)
+    .filter((w) => w && !STOPWORDS.has(w));
+  const meaningful = words.slice(0, 6);
+  if (meaningful.length === 0) return String(text).slice(0, 60).trim();
+  const titled = meaningful.map((w) => w.charAt(0).toUpperCase() + w.slice(1)).join(' ');
+  return titled.length > 60 ? titled.slice(0, 57) + '...' : titled;
+}