karajan-code 3.0.0 → 3.1.0

package/packages/hu-board/public/index.html

@@ -51,6 +51,26 @@
     <div class="modal" id="modal-content"></div>
   </div>
 
+  <script src="/utils/formatters.js"></script>
+  <script src="/utils/modals.js"></script>
+  <script src="/utils/api.js"></script>
+  <script src="/utils/sessions-view.js"></script>
+  <script src="/utils/board-view.js"></script>
+  <script src="/utils/dashboard-view.js"></script>
+  <script src="/utils/graph-view.js"></script>
+  <script src="/utils/project-picker-view.js"></script>
+  <script src="/utils/story-detail-view.js"></script>
+  <script src="/utils/preflight-view.js"></script>
+  <script src="/utils/plan-rollup-view.js"></script>
+  <script src="/utils/log-panel.js"></script>
+  <script src="/utils/hu-actions.js"></script>
+  <script src="/utils/project-actions.js"></script>
+  <script src="/utils/story-edit-form.js"></script>
+  <script src="/utils/config-editor.js"></script>
+  <script src="/utils/command-launcher.js"></script>
+  <script src="/utils/run-launcher.js"></script>
+  <script src="/utils/server-push.js"></script>
   <script src="/app.js"></script>
+  <script src="/utils/init-listeners.js"></script>
 </body>
 </html>

package/packages/hu-board/public/utils/api.js

@@ -0,0 +1,139 @@
+// KJC-TSK-0501 — API + polling helpers extracted from app.js (step 3/8).
+// Loaded as a classic script before app.js (after modals.js) — all
+// top-level declarations hoist to global scope so app.js consumes them
+// transparently.
+//
+// Contents:
+//   - api(): thin JSON fetch wrapper used everywhere in the UI.
+//   - triggerSync(): POST /api/sync — fired on page load and the 🔄 button.
+//   - Standby banner: _standbyData state + refreshStandby() +
+//     _renderStandbyBanner() + _tickStandbyCountdowns() +
+//     startStandbyPolling() — KJC-TSK-0414 PR4.
+//   - Server-restart detector: pollServerVersion() + __versionBaseline +
+//     window.forceRefresh — KJC-TSK-0379.
+//
+// Dependencies: `esc()` from formatters.js (already global).
+// `setInterval(pollServerVersion, 30_000)` + initial call fire at the
+// bottom of the file so the detector starts as soon as the script loads.
+
+async function api(path) {
+  const res = await fetch(path);
+  if (!res.ok) throw new Error(`API error: ${res.status}`);
+  return res.json();
+}
+
+// KJC-TSK-0414 PR4: standby banner — sesiones hibernadas pendientes de resume.
+// Polleamos /api/standby cada 30s + tick countdown cada 1s.
+let _standbyData = { sessions: [] };
+let _standbyPollTimer = null;
+let _standbyTickTimer = null;
+
+function _fmtCountdown(ms) {
+  if (ms <= 0) return '✓ resume inmediato';
+  const s = Math.round(ms / 1000);
+  const h = Math.floor(s / 3600);
+  const m = Math.floor((s % 3600) / 60);
+  const sec = s % 60;
+  return `${String(h).padStart(2, '0')}:${String(m).padStart(2, '0')}:${String(sec).padStart(2, '0')}`;
+}
+
+async function refreshStandby() {
+  try {
+    const r = await api('/api/standby');
+    _standbyData = r || { sessions: [] };
+    _renderStandbyBanner();
+  } catch { /* silencioso — endpoint nuevo, podría no existir en versiones viejas */ }
+}
+
+function _renderStandbyBanner() {
+  let banner = document.getElementById('standby-banner');
+  const sessions = _standbyData.sessions || [];
+  if (sessions.length === 0) {
+    if (banner) banner.remove();
+    return;
+  }
+  if (!banner) {
+    banner = document.createElement('div');
+    banner.id = 'standby-banner';
+    banner.style.cssText = 'background:rgba(251,191,36,0.12);border-left:4px solid #fbbf24;padding:10px 16px;margin:0 0 12px;font-size:0.85rem';
+    const app = document.getElementById('app');
+    if (app?.parentNode) app.parentNode.insertBefore(banner, app);
+  }
+  const now = Date.now();
+  banner.innerHTML = `
+    <div style="display:flex;align-items:center;gap:12px;flex-wrap:wrap">
+      <strong>💤 ${sessions.length} sesión(es) hibernadas:</strong>
+      ${sessions.map((s) => {
+        const ms = new Date(s.cooldownUntil).getTime() - now;
+        const label = _fmtCountdown(ms);
+        const reason = s.reason || '?';
+        const planInfo = s.planId ? ` · ${s.planId}${s.huId ? '/' + s.huId : ''}` : '';
+        return `<span data-session="${esc(s.sessionId)}" data-cooldown="${esc(s.cooldownUntil)}" style="background:rgba(0,0,0,0.15);padding:4px 8px;border-radius:4px;font-family:monospace" title="${esc(reason)}${esc(planInfo)}">${esc(s.sessionId)} · <span class="standby-countdown">${label}</span></span>`;
+      }).join('')}
+      <span style="margin-left:auto;color:var(--text-muted);font-size:0.75rem">Auto-resume al llegar el cooldown (board) o <code>kj resume &lt;id&gt;</code></span>
+    </div>
+  `;
+}
+
+function _tickStandbyCountdowns() {
+  const banner = document.getElementById('standby-banner');
+  if (!banner) return;
+  const now = Date.now();
+  for (const chip of banner.querySelectorAll('[data-cooldown]')) {
+    const target = new Date(chip.getAttribute('data-cooldown')).getTime();
+    const span = chip.querySelector('.standby-countdown');
+    if (span) span.textContent = _fmtCountdown(target - now);
+  }
+}
+
+function startStandbyPolling() {
+  if (_standbyPollTimer || _standbyTickTimer) return;
+  refreshStandby();
+  _standbyPollTimer = setInterval(refreshStandby, 30_000);
+  _standbyTickTimer = setInterval(_tickStandbyCountdowns, 1000);
+}
+
+/**
+ * Trigger a full re-scan of disk data (hu-stories + sessions).
+ * Called on page load and via the sync button.
+ */
+async function triggerSync() {
+  try {
+    await fetch('/api/sync', { method: 'POST' });
+  } catch { /* ignore — board may not support sync yet */ }
+}
+
+// --- Server-restart detector (KJC-TSK-0379) ---------------------------
+// Poll /api/version every 30s. First response anchors the baseline; if
+// `boot_time` later differs, the server restarted (likely after a `kj
+// board start`) and the client reloads to pick up any new HTML/JS
+// served with `Cache-Control: no-store`. Avoids the "I killed the
+// server but the browser keeps showing stale UI" pain.
+let __versionBaseline = null;
+async function pollServerVersion() {
+  try {
+    const res = await api('/version');
+    if (!__versionBaseline) { __versionBaseline = res; return; }
+    if (res.boot_time !== __versionBaseline.boot_time) {
+      console.info('[hu-board] server restart detected, reloading...');
+      window.forceRefresh();
+    }
+  } catch (_) { /* network blip; try next tick */ }
+}
+setInterval(pollServerVersion, 30_000);
+pollServerVersion();
+
+// Manual escape hatch: bound to the 🔄 button in the header. Wipes all
+// caches the browser may be holding (Cache API + sessionStorage) and
+// hard-reloads. Useful when the user thinks something is wrong even
+// though the version-poll hasn't fired.
+window.forceRefresh = async function forceRefresh() {
+  try {
+    if ('caches' in window) {
+      const keys = await caches.keys();
+      await Promise.all(keys.map((k) => caches.delete(k)));
+    }
+    sessionStorage.clear();
+  } catch (_) { /* best effort */ }
+  window.location.reload();
+};

package/packages/hu-board/public/utils/board-view.js

@@ -0,0 +1,453 @@
+// KJC-TSK-0501 step 5/8 — Board view (kanban, columns, story card, result helpers).
+//
+// Classic script. Loaded by index.html after utils/sessions-view.js, before
+// app.js. Function declarations hoist to the global scope so app.js (and
+// inline onclick handlers) can call them transparently.
+//
+// Globals consumed from app.js / earlier scripts:
+//   - api(), esc(), renderEmptyState(), renderProjectPicker(),
+//     renderPreflightPanel(), renderPlanRollup(), confirmRunWithPreflight(),
+//     runProject(), openGenericLogPanel(), humaniseProjectName(),
+//     resolveProjectMeta(), shortStoryId(), truncate(), scoreClass(),
+//     qualityBar(), timeAgo(), showError(), showConfirm(),
+//     showStoryDetail(), showOutcomeModal(), runSingleHuFromCard(),
+//     renameProjectModal()
+//   - mutable: selectedProject, lastOpenedLog, projectNameCache,
+//     projectInitialsCache
+// All lookups are runtime-bound; load order only needs board-view.js to live
+// in the same realm before app.js executes its bootstrap.
+
+/**
+ * Renders the kanban board view.
+ */
+async function renderBoard() {
+  const app = document.getElementById('app');
+  app.innerHTML = '<div class="loading"><div class="loading__spinner"></div><p>Loading board...</p></div>';
+
+  try {
+    // No project selected → render the project picker instead of
+    // mixing every project's HUs in one kanban. The user's
+    // complaint: "if no project is selected, show me the list of
+    // projects". A mixed kanban hides which HU belongs to which
+    // project and is borderline useless on a multi-project setup.
+    if (!selectedProject) {
+      await renderProjectPicker();
+      return;
+    }
+
+    const stories = await api(`/api/projects/${encodeURIComponent(selectedProject)}/stories`);
+
+    // Pre-resolve project initials + name for every distinct project_id in
+    // the fetched stories so `renderStoryCard` is synchronous and the header
+    // can show the human-friendly project name (e.g. "Linux Assistant
+    // Orchestrator" instead of the raw slug). Cached globally → at most one
+    // API round-trip per project over the session.
+    const uniqueProjectIds = [...new Set(stories.map((s) => s.project_id))];
+    await Promise.all(uniqueProjectIds.map(resolveProjectMeta));
+    if (selectedProject && !projectNameCache[selectedProject]) {
+      await resolveProjectMeta(selectedProject);
+    }
+    const projectDisplayName = selectedProject
+      ? (projectNameCache[selectedProject] || humaniseProjectName(selectedProject))
+      : '';
+
+    // KJC-TSK-0403: status/result ortogonal. 3 columnas (Pending /
+    // Running / Done) en vez de 4. Las HUs que fallaron NO van a una
+    // columna "Failed" — vuelven a Pending con result=fail y badge ✗.
+    // status=failed legacy se trata como pending (migración lazy).
+    const columns = {
+      pending: stories.filter((s) =>
+        ['pending', 'certified', 'needs_context', 'blocked', 'failed'].includes(s.status)
+      ),
+      running: stories.filter((s) => ['coding', 'reviewing'].includes(s.status)),
+      done: stories.filter((s) => s.status === 'done'),
+    };
+
+    if (stories.length === 0) {
+      app.innerHTML = renderEmptyState();
+      return;
+    }
+
+    // "Run plan" bulk action: visible when a project is selected AND at
+    // least one HU is still awaiting execution AND nothing's currently
+    // running (to avoid accidentally launching a second pipeline over a
+    // live one). Replaces the old "Mark as certified" button — the
+    // intermediate "certified" state was noise from the user's POV.
+    const awaitingCount = columns.pending.length;
+    const runningCount = columns.running.length;
+    const canRun = Boolean(selectedProject) && awaitingCount > 0 && runningCount === 0;
+    const isRunning = runningCount > 0;
+
+    // KJC-TSK-0403: 3 canonical lanes. Failed eliminado — HUs con
+    // result=fail aparecen en Pending con badge ✗.
+    const visibleColumns = [
+      { title: 'Pending', cls: 'pending', rows: columns.pending },
+      { title: 'Running', cls: 'running', rows: columns.running },
+      { title: 'Done', cls: 'done', rows: columns.done },
+    ];
+
+    app.innerHTML = `
+      <div class="section-header">
+        <span class="section-header__title" title="${selectedProject ? esc(selectedProject) : ''}">Story Board${selectedProject ? ` - ${esc(projectDisplayName)}` : ''}</span>
+        ${selectedProject ? `
+          <button class="control-btn project-rename-btn"
+                  style="background:transparent;border:none;color:var(--text-muted);cursor:pointer;font-size:0.9rem;padding:2px 6px;"
+                  title="Renombrar este proyecto"
+                  onclick="event.stopPropagation(); window.renameProjectModal('${esc(selectedProject)}', '${esc(projectDisplayName.replace(/'/g, '&#39;'))}');">✎</button>
+        ` : ''}
+        <span class="section-header__count">${stories.length} stories</span>
+        ${isRunning ? `
+          <button id="running-badge-btn" class="section-header__badge"
+                style="margin-left:auto;padding:4px 10px;font-size:0.8rem;background:var(--color-yellow,#eab308);color:#000;border-radius:var(--radius-sm);font-weight:600;border:none;cursor:pointer;"
+                title="Abrir el log de la HU en marcha">
+            ⚙ ${runningCount} running…
+          </button>
+          <button id="stop-run-btn" class="control-btn"
+                style="padding:4px 10px;font-size:0.8rem;background:var(--color-red,#ef4444);color:#fff;border:none;border-radius:var(--radius-sm);cursor:pointer;font-weight:600;"
+                title="Abortar todos los kj run en marcha de este proyecto (SIGTERM con escalado a SIGKILL tras 5s)">
+            ⏹ Stop
+          </button>
+        ` : ''}
+        ${lastOpenedLog ? `
+          <button class="control-btn" id="view-log-btn"
+                  style="${isRunning ? '' : 'margin-left:auto;'}padding:6px 12px;font-size:0.85rem;background:var(--bg-primary);border:1px solid var(--border);color:var(--text);border-radius:var(--radius-sm);cursor:pointer;"
+                  title="Re-open the log of the most recent run/command">
+            📜 View log
+          </button>
+        ` : ''}
+        ${canRun ? `
+          <button class="control-btn" id="run-plan-btn"
+                  style="margin-left:auto;padding:6px 14px;font-size:0.9rem;background:var(--color-green);color:#fff;border:none;border-radius:var(--radius-sm);cursor:pointer;font-weight:600;"
+                  title="Launch kj run --plan over every plan in this project">
+            ▶ Run plan (${awaitingCount} HU${awaitingCount === 1 ? '' : 's'})
+          </button>
+        ` : ''}
+      </div>
+      <div id="preflight-panel" class="preflight-panel" style="margin:8px 0;">
+        <div class="preflight-panel__loading" style="font-size:0.8rem;color:var(--text-muted);padding:6px 10px;">
+          Comprobando estado del proyecto…
+        </div>
+      </div>
+      <div id="rag-panel" class="rag-panel" style="margin:8px 0;display:flex;gap:8px;align-items:flex-start;flex-wrap:wrap;">
+        <input id="rag-query" type="text" placeholder="🔍 RAG search: ask anything about this project's plans / onboarding / code…"
+               style="flex:1;min-width:260px;padding:6px 10px;font-size:0.85rem;background:var(--bg-primary);border:1px solid var(--border);color:var(--text);border-radius:var(--radius-sm);" />
+        <select id="rag-scope" style="padding:6px 10px;font-size:0.85rem;background:var(--bg-primary);border:1px solid var(--border);color:var(--text);border-radius:var(--radius-sm);">
+          <option value="all">All</option><option value="plans">Plans</option><option value="onboarding">Onboarding</option><option value="code">Code</option>
+        </select>
+        <button id="rag-search-btn" class="control-btn"
+                style="padding:6px 12px;font-size:0.85rem;background:var(--color-blue,#3b82f6);color:#fff;border:none;border-radius:var(--radius-sm);cursor:pointer;font-weight:600;">
+          Search
+        </button>
+        <div id="rag-results" style="flex-basis:100%;font-size:0.8rem;color:var(--text-muted);"></div>
+      </div>
+      <div id="plan-rollup-banner"></div>
+      <div class="kanban">
+        ${visibleColumns.map((c) => renderKanbanColumn(c.title, c.cls, c.rows)).join('')}
+      </div>
+    `;
+
+    if (canRun) {
+      document.getElementById('run-plan-btn').addEventListener('click', async () => {
+        // Pre-run safety: ask preflight if anything risky is missing
+        // (no remote, dirty tree, missing agents, etc.). The modal
+        // shows blockers + warnings in plain Spanish and the user
+        // can cancel or proceed anyway. If everything is green we
+        // skip the modal and run straight away.
+        const ok = await confirmRunWithPreflight(selectedProject);
+        if (!ok) return;
+        await runProject(selectedProject);
+      });
+    }
+    // Preflight panel is rendered AFTER the kanban so we can fetch
+    // it without blocking the initial paint. Replaces a placeholder
+    // div in-place (no full re-render).
+    renderPreflightPanel(selectedProject).catch(() => {});
+    // PR3: render the plan-level rollup banner if any plan in this
+    // project has a stamped outcome. Non-blocking — if it fails the
+    // user just doesn't see the banner.
+    renderPlanRollup(selectedProject).catch(() => {});
+    const viewLogBtn = document.getElementById('view-log-btn');
+    if (viewLogBtn && lastOpenedLog) {
+      viewLogBtn.addEventListener('click', () => openGenericLogPanel({
+        id: lastOpenedLog.id,
+        label: lastOpenedLog.label,
+        tailUrl: lastOpenedLog.tailUrl,
+      }));
+    }
+    // Wire the yellow "⚙ N running…" badge so it opens the live log of the
+    // first running HU. Without this the badge was decorative — and if the
+    // run was started before the current page load (refresh / new browser
+    // session) `lastOpenedLog` is null, so the "📜 View log" button isn't
+    // even rendered. Then the user has no way to see the live output.
+    //
+    // For a single-HU run the log lives at:
+    //   ~/.karajan/hu-board-runs/<planId>--hu-<localHuId>.log
+    // which the /api/runs/:commandId/log endpoint serves when commandId
+    // matches the basename. The composite id stored in SQLite is
+    // "<projectId>::<localHuId>", so we strip the prefix to derive
+    // localHuId and concatenate with plan_id (already on the story row).
+    const runningBadgeBtn = document.getElementById('running-badge-btn');
+    if (runningBadgeBtn) {
+      runningBadgeBtn.addEventListener('click', async () => {
+        const running = stories.find((s) => s.status === 'coding' || s.status === 'reviewing');
+        if (!running) return;
+        const planId = running.plan_id;
+        if (!planId) {
+          await showError('Esta HU no tiene plan_id asociado, no puedo localizar su log.', { title: 'Sin log' });
+          return;
+        }
+        const localHuId = running.id.includes('::') ? running.id.split('::').pop() : running.id;
+        const logBasename = `${planId}--hu-${localHuId}`;
+        const tailUrl = (offset) => `/api/runs/${encodeURIComponent(logBasename)}/log?offset=${offset || 0}`;
+        lastOpenedLog = { id: logBasename, label: `HU ${localHuId}`, tailUrl };
+        openGenericLogPanel({ id: logBasename, label: `HU ${localHuId}`, tailUrl });
+      });
+    }
+
+    // KJC-TSK-0396: botón ⏹ Stop. Abortar todos los kj run vivos del
+    // proyecto. Si hay múltiples planes corriendo (caso raro pero
+    // posible), itera sobre cada planId único de las HUs running.
+    const stopRunBtn = document.getElementById('stop-run-btn');
+    if (stopRunBtn) {
+      stopRunBtn.addEventListener('click', async () => {
+        const runningHus = stories.filter((s) => s.status === 'coding' || s.status === 'reviewing');
+        const planIds = [...new Set(runningHus.map((s) => s.plan_id).filter(Boolean))];
+        if (planIds.length === 0) {
+          await showError('No hay plan_id asociado a las HUs en marcha.', { title: 'Sin runs' });
+          return;
+        }
+        const ok = await showConfirm(
+          `Esto matará ${planIds.length === 1 ? 'el proceso' : `los ${planIds.length} procesos`} del orquestador en marcha y dejará las HUs en curso (coding/reviewing) en pending para que puedas relanzarlas.\n\n¿Seguro?`,
+          { title: 'Abortar kj run', okLabel: 'Stop', cancelLabel: 'Cancelar', destructive: true }
+        );
+        if (!ok) return;
+        const summaries = [];
+        for (const planId of planIds) {
+          try {
+            const res = await fetch(`/api/runs/${encodeURIComponent(planId)}/stop`, {
+              method: 'POST', headers: { 'Content-Type': 'application/json' }, body: '{}',
+            });
+            const body = await res.json();
+            if (!res.ok) summaries.push(`${planId}: error ${body.error || res.status}`);
+            else summaries.push(`${planId}: ${body.stopped} SIGTERM, ${body.killed} SIGKILL, ${body.hu_reset_count || 0} HUs → pending`);
+          } catch (err) {
+            summaries.push(`${planId}: ${err.message}`);
+          }
+        }
+        await fetch('/api/sync', { method: 'POST' }).catch(() => {});
+        await renderBoard();
+        if (summaries.some((s) => s.includes('SIGKILL') && !s.startsWith('0 ')) && summaries.some((s) => /\b[1-9]\d* SIGKILL/.test(s))) {
+          await showError(
+            `Algún proceso no respondió a SIGTERM en 5s y fue forzado con SIGKILL:\n\n${summaries.join('\n')}`,
+            { title: 'Forzado con SIGKILL' }
+          );
+        }
+      });
+    }
+
+    // RAG search panel (KJC-PCS-0049 Step 8) — input + scope + render hits.
+    const ragInput = document.getElementById('rag-query');
+    const ragScope = document.getElementById('rag-scope');
+    const ragBtn = document.getElementById('rag-search-btn');
+    const ragResults = document.getElementById('rag-results');
+    async function runRagSearch() {
+      const text = ragInput?.value?.trim();
+      if (!text) return;
+      ragResults.innerHTML = '<em>Searching…</em>';
+      try {
+        const res = await fetch('/api/rag/query', {
+          method: 'POST', headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify({ text, topK: 5, scope: ragScope?.value || 'all' }),
+        });
+        const body = await res.json();
+        if (!res.ok) { ragResults.innerHTML = `<span style="color:var(--color-red);">Error: ${esc(body.error || res.status)}</span>`; return; }
+        if (body.empty) { ragResults.innerHTML = '<em>No chunks indexed yet. Run <code>kj rag index</code> in this project\'s terminal first.</em>'; return; }
+        if (body.hits.length === 0) { ragResults.innerHTML = '<em>No hits.</em>'; return; }
+        ragResults.innerHTML = body.hits.map((h) => {
+          const label = h.metadata?.hu_id || h.metadata?.symbol || h.metadata?.headingPath?.join(' > ') || 'block';
+          const snippet = h.text.length > 240 ? `${esc(h.text.slice(0, 240))}…` : esc(h.text);
+          return `<div style="border-left:3px solid var(--color-blue,#3b82f6);padding:6px 10px;margin:6px 0;background:var(--bg-primary);">
+            <div style="font-size:0.75rem;color:var(--text-muted);margin-bottom:4px;">[${esc(h.kind)} · ${esc(label)} · score=${h.score.toFixed(4)}] ${esc(h.source)}</div>
+            <div style="font-size:0.85rem;white-space:pre-wrap;">${snippet}</div>
+          </div>`;
+        }).join('');
+      } catch (err) {
+        ragResults.innerHTML = `<span style="color:var(--color-red);">Error: ${esc(err.message)}</span>`;
+      }
+    }
+    ragBtn?.addEventListener('click', runRagSearch);
+    ragInput?.addEventListener('keydown', (e) => { if (e.key === 'Enter') runRagSearch(); });
+  } catch (err) {
+    app.innerHTML = `<div class="empty-state"><div class="empty-state__title">Error loading board</div><div class="empty-state__text">${esc(err.message)}</div></div>`;
+  }
+}
+
+/**
+ * Renders a single kanban column.
+ * @param {string} title
+ * @param {string} cssClass
+ * @param {Array<object>} stories
+ * @returns {string}
+ */
+function renderKanbanColumn(title, cssClass, stories) {
+  // Empty lanes render the header (so the user keeps the 4-column
+  // mental map) but no body placeholder — "No stories" text on four
+  // empty columns was noise on fresh plans.
+  return `
+    <div class="kanban__column kanban__column--${cssClass}" data-column="${cssClass}"${stories.length === 0 ? ' style="opacity:0.55"' : ''}>
+      <div class="kanban__column-header">
+        <span class="kanban__column-title">${title}</span>
+        <span class="kanban__column-count" data-column-count>${stories.length}</span>
+      </div>
+      ${stories.map(renderStoryCard).join('')}
+    </div>
+  `;
+}
+
+/**
+ * Renders a story card for the kanban board.
+ * @param {object} story
+ * @returns {string}
+ */
+function renderStoryCard(story) {
+  const title = story.title || story.original_text || story.id;
+  const antipatterns = story.antipatterns ? JSON.parse(story.antipatterns) : [];
+  // Prefer denormalised counters stamped at sync time; fall back to
+  // parsing the JSON blob for pre-migration rows so the card still shows
+  // the AC count without a board DB nuke.
+  const acCount = typeof story.ac_count === 'number'
+    ? story.ac_count
+    : (story.acceptance_criteria ? JSON.parse(story.acceptance_criteria).length : 0);
+  const testCount = typeof story.test_count === 'number' ? story.test_count : 0;
+  const blockedBy = story.blocked_by ? JSON.parse(story.blocked_by) : [];
+  const initials = projectInitialsCache[story.project_id] || 'kj';
+  const shortId = shortStoryId(story, initials);
+
+  // Human-readable dep list: `lao-001, lao-003` instead of the raw HU ids.
+  const shortDep = (depId) => {
+    const m = /_(\d+)(?!.*\d)/.exec(depId);
+    return `${initials}-${m ? m[1] : '?'}`;
+  };
+
+  // Tests-first flag: a HU with zero acceptance_tests has no contract
+  // for the coder, so `Run plan` will refuse to execute it. Surface
+  // this on the card so the user edits the HU before trying to run.
+  const missingTestContract = testCount === 0 && ['pending', 'certified'].includes(story.status);
+
+  // PR4: per-HU ▶ Run button. Visible when:
+  //   - the HU is in a re-runnable lifecycle state (certified / failed /
+  //     pending / done — KJC-TSK-0394 step 2 adds `done` so the user can
+  //     replay a HU whose `result` was fail or partial without having to
+  //     "reset to pending" first) AND
+  //   - it has at least one acceptance test (otherwise the run would
+  //     refuse) AND
+  //   - it isn't currently coding/reviewing AND
+  //   - KJC-BUG-0048: it has no unresolved blocked_by deps. The card
+  //     already shows "⏳ waits for: ..." below the title; the ▶ button
+  //     must match that gating or the user can launch a HU whose deps
+  //     don't exist yet, hitting the missing-prereq path at runtime.
+  const canRunHu = ['certified', 'failed', 'pending', 'done'].includes(story.status)
+    && testCount > 0
+    && !['coding', 'reviewing'].includes(story.status)
+    && blockedBy.length === 0;
+
+  return `
+    <div class="story-card" data-story-id="${esc(story.id)}" data-status="${esc(story.status || 'pending')}" onclick="showStoryDetail('${esc(story.id)}')">
+      <div class="story-card__id" title="${esc(story.id)}">
+        ${esc(shortId)}
+        ${canRunHu ? `
+          <button class="story-card__run-btn"
+                  style="float:right;padding:1px 6px;font-size:0.7rem;background:var(--color-green);color:#fff;border:none;border-radius:var(--radius-sm);cursor:pointer;"
+                  title="Lanzar solo esta HU"
+                  onclick="event.stopPropagation(); window.runSingleHuFromCard('${esc(story.id)}', '${esc(title.replace(/'/g, '&#39;'))}');">▶</button>
+        ` : ''}
+      </div>
+      <div class="story-card__title">${esc(truncate(title, 100))}</div>
+      <div class="story-card__meta" style="gap:10px">
+        ${acCount > 0 ? `<span title="${acCount} acceptance criteria">📋 ${acCount} AC${acCount === 1 ? '' : 's'}</span>` : ''}
+        ${testCount > 0 ? `<span title="${testCount} acceptance tests declared">✅ ${testCount} test${testCount === 1 ? '' : 's'}</span>` : ''}
+        ${story.spec_section ? `<span title="Implements SPEC ${esc(story.spec_section)}" style="font-family:var(--font-mono, monospace)">📖 §${esc(story.spec_section)}</span>` : ''}
+        ${story.quality_total !== null ? `
+          <span class="story-card__score ${scoreClass(story.quality_total)}" title="INVEST score">
+            ${story.quality_total}/60 ${qualityBar(story.quality_total)}
+          </span>
+        ` : ''}
+      </div>
+      ${missingTestContract ? `
+        <div class="story-card__meta" style="margin-top:4px;font-size:0.75rem;color:var(--color-yellow,#eab308);font-weight:600" title="This HU has no acceptance_tests declared — Run plan will reject it until you add at least one.">
+          ⚠ missing test contract
+        </div>
+      ` : ''}
+      ${blockedBy.length > 0 ? `
+        <div class="story-card__meta" style="margin-top:4px;font-size:0.75rem;color:var(--text-muted)" title="This HU waits on: ${esc(blockedBy.join(', '))}">
+          ⏳ waits for: ${blockedBy.map((d) => esc(shortDep(d))).join(', ')}
+        </div>
+      ` : (story.status === 'pending' || story.status === 'certified') && !missingTestContract ? `
+        <div class="story-card__meta" style="margin-top:4px;font-size:0.75rem;color:var(--color-green)" title="No dependencies — runs first on the next 'Run plan'">
+          🟢 ready to run
+        </div>
+      ` : ''}
+      ${antipatterns.length > 0 ? `<div class="story-card__antipattern">${antipatterns.map((a) => esc(a)).join(', ')}</div>` : ''}
+      <div class="story-card__meta" style="margin-top:6px">
+        <span class="story-card__status status--${story.status}">${esc(story.status)}</span>
+        ${renderResultBadge(computeEffectiveResult(story))}
+        <span class="story-card__time">${timeAgo(story.updated_at)}</span>
+        ${renderOutcomeChip(story.outcome)}
+      </div>
+    </div>
+  `;
+}
+
+/**
+ * KJC-TSK-0394 step 5: result "efectivo" para la UI. Sobre el campo
+ * persistido `story.result` (si existe), o inferido del status legacy
+ * (done→pass, failed→fail).
+ */
+function computeEffectiveResult(story) {
+  if (!story) return null;
+  if (story.result !== undefined && story.result !== null) return story.result;
+  if (story.status === 'done') return 'pass';
+  if (story.status === 'failed') return 'fail';
+  return null;
+}
+
+/**
+ * Render the per-HU `result` badge. Ortogonal al status.
+ * @param {string|null} result
+ * @returns {string} HTML
+ */
+function renderResultBadge(result) {
+  if (!result) return '';
+  const icons = { pass: '✓', fail: '✗', partial: '~' };
+  const titles = {
+    pass: 'Última ejecución: todos los tests pasaron',
+    fail: 'Última ejecución: falló',
+    partial: 'Última ejecución: pasó parcialmente',
+  };
+  const icon = icons[result];
+  if (!icon) return '';
+  return `<span class="story-card__result result--${esc(result)}" title="${esc(titles[result])}">${icon}</span>`;
+}
+
+/**
+ * Render the per-HU outcome chip (📄 resumen). Tolerates both string and
+ * object shapes.
+ * @param {string|object|null} outcome
+ * @returns {string} HTML
+ */
+function renderOutcomeChip(outcome) {
+  if (!outcome) return '';
+  let parsed;
+  try { parsed = typeof outcome === 'string' ? JSON.parse(outcome) : outcome; }
+  catch { return ''; }
+  if (!parsed || typeof parsed !== 'object') return '';
+  const summary = parsed.summary || `Resultado: ${parsed.status || 'desconocido'}`;
+  return `
+    <span class="story-card__outcome-chip"
+          style="margin-left:auto;padding:2px 8px;font-size:0.7rem;background:var(--bg-primary);border:1px solid var(--border);border-radius:var(--radius-sm);cursor:pointer;color:var(--text-muted);"
+          title="${esc(summary)}"
+          onclick="event.stopPropagation(); showOutcomeModal('${esc(JSON.stringify(parsed).replace(/'/g, '&#39;'))}');">
+      📄 resumen
+    </span>
+  `;
+}