karajan-code 4.1.7 → 4.1.9

package/package.json

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

package/packages/hu-board/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@karajan/hu-board",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "HU Story Board dashboard for Karajan Code",
   "type": "module",
   "private": true,

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

@@ -208,9 +208,27 @@ function showPromptModal(prompt) {
   if (activePromptId === prompt.promptId) return;
   activePromptId = prompt.promptId;
   const dlg = ensureDialog();
+  // KJC-BUG-0125 (issue #1275): findings render as a readable, open list —
+  // "4 findings at severity fail" alone gives the user nothing to act on.
+  // Each finding shows its message and the concrete suggestion.
+  const sevColor = (s) => (s === 'fail' ? '#f87171' : s === 'warn' ? '#fbbf24' : '#60a5fa');
+  const findings = prompt.context?.detail?.findings || prompt.context?.findings;
+  const findingsBlock = Array.isArray(findings) && findings.length
+    ? `<div style="margin-top:10px;display:flex;flex-direction:column;gap:8px;max-height:280px;overflow:auto">`
+      + findings.map((f) => `
+        <div style="border-left:3px solid ${sevColor(f.severity)};padding:6px 10px;background:var(--bg-primary);border-radius:var(--radius-sm)">
+          <div style="font-size:0.78rem;color:var(--text-muted)">
+            <strong style="color:${sevColor(f.severity)}">${esc(String(f.severity || '').toUpperCase())}</strong>
+            · ${esc(f.category || '')}${f.id ? ` · ${esc(f.id)}` : ''}
+          </div>
+          <div style="font-size:0.86rem;line-height:1.45;margin-top:2px">${esc(f.message || '')}</div>
+          ${f.suggestion ? `<div style="font-size:0.8rem;color:var(--text-muted);margin-top:2px">→ ${esc(f.suggestion)}</div>` : ''}
+        </div>`).join('')
+      + `</div>`
+    : '';
   const ctxBlock = prompt.context
     ? `<details style="margin-top:8px">
-         <summary style="cursor:pointer;color:var(--text-muted);font-size:0.85rem">Context</summary>
+         <summary style="cursor:pointer;color:var(--text-muted);font-size:0.85rem">Raw context</summary>
          <pre style="white-space:pre-wrap;font-size:0.78rem;background:var(--bg-primary);padding:8px;border-radius:var(--radius-sm);overflow:auto;max-height:240px">${esc(JSON.stringify(prompt.context, null, 2))}</pre>
        </details>`
     : '';
@@ -221,6 +239,7 @@ function showPromptModal(prompt) {
     </div>
     <div style="padding:14px 18px">
       <div style="white-space:pre-wrap;font-size:0.95rem;line-height:1.55">${esc(prompt.question)}</div>
+      ${findingsBlock}
       ${ctxBlock}
       <textarea id="prompt-answer" rows="3"
                 placeholder="Type your answer (or 'stop' to abort the run)"

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

@@ -32,7 +32,6 @@ import {
   getSessionsByProject,
   getSessionDetail,
   deleteProject,
-  deleteStory,
   deleteSession,
   getKjHome,
   getHuBoardRunsDir,
@@ -462,19 +461,15 @@ router.delete('/prompts/:promptId', async (req, res) => {
  * it. Pre-tombstones this endpoint was a DB-only soft hide that the next
  * chokidar event undid silently.
  */
-router.delete('/stories/:id', async (req, res) => {
-  try {
-    const id = req.params.id;
-    const dir = path.join(huStoriesDir(), id);
-    const ok = deleteStory(id);
-    if (!ok) return res.status(404).json({ error: 'Story not found' });
-    addTombstone('story', id, { source: 'api', fsPaths: [dir] });
-    let dirRemoved = false;
-    try { await fsp.rm(dir, { recursive: true, force: true }); dirRemoved = true; } catch { /* */ }
-    res.json({ deleted: true, dirRemoved });
-  } catch (err) {
-    res.status(500).json({ error: err.message });
-  }
+router.delete('/stories/:id', (req, res) => {
+  // KJC-TSK-0671 (absolute product rule): stories are NEVER deleted — the
+  // delete-and-recreate "fix" agents improvise loses history and produced
+  // the field saga this closes. Discard goes through the lifecycle instead.
+  res.status(405).json({
+    error: 'Stories are never deleted. Discard one with: kj hu move <id> skipped '
+      + '(archived, history kept). Dashboard warnings are fixed with the command '
+      + 'they name — see kj brief board.',
+  });
 });
 
 /**

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

@@ -358,7 +358,19 @@ export function syncPlanFile(filePath) {
   try {
     const raw = readFileSync(filePath, 'utf-8');
     const data = JSON.parse(raw);
-    if (data.version !== 2 || !Array.isArray(data.hus) || data.hus.length === 0) return;
+    // 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

package/src/commands/hu.js

@@ -66,6 +66,19 @@ export async function huCommand({ config = null, action, args = [], flags = {} }
     const title = args[0];
     if (!title || !title.trim()) throw new Error("kj hu add requires a title: kj hu add \"<story>\"");
     const plan = await backlogPlan(projectDir);
+    // KJC-TSK-0669 (absolute rule): cards are permanent. The delete-and-
+    // recreate "fix" an agent improvises loses history and duplicates ids —
+    // refuse it with the norm spelled out.
+    if (flags.id) {
+      const dup = (plan.hus || []).find((h) => h.short_id === flags.id);
+      if (dup) {
+        throw new Error(
+          `HU "${flags.id}" already exists (status: ${dup.status}). HUs are never deleted or recreated — `
+          + `update its state with: kj hu move ${flags.id} <pending|running|done|failed|skipped>, `
+          + `or discard it with: kj hu move ${flags.id} skipped`
+        );
+      }
+    }
     const hu = addHu(plan, {
       title,
       short_id: flags.id || null,

package/src/commands/plan/fix.js

@@ -60,7 +60,7 @@ export async function planFixCommand({ config, planId, prompt, logger, json }) {
     });
     if (!fix.ok) { fixProgress.finish("failed"); break; }
     const ops = applyFixerPatch(plan, fix.patch);
-    if (ops.added + ops.depsAdded + ops.deleted === 0) { fixProgress.finish("done"); break; }
+    if (ops.added + ops.depsAdded + ops.archived === 0) { fixProgress.finish("done"); break; }
     const review2 = await reviewPlan({
       agent: planner, task: enrichedTask, hus: plan.hus,
       onOutput: fixProgress.onOutput, silenceTimeoutMs, timeoutMs,

package/src/commands/plan/generate.js

@@ -370,8 +370,8 @@ async function planGenerateImpl({ task, config, logger, json, context, runLog, f
             break;
           }
           const ops = applyFixerPatch(plan, fix.patch);
-          runLog.logText(`[planner] self-fix iter ${i} applied: +${ops.added} HU, +${ops.depsAdded} dep, -${ops.deleted} HU`);
-          if (ops.added + ops.depsAdded + ops.deleted === 0) {
+          runLog.logText(`[planner] self-fix iter ${i} applied: +${ops.added} HU, +${ops.depsAdded} dep, ${ops.archived} archived`);
+          if (ops.added + ops.depsAdded + ops.archived === 0) {
             fixProgress.finish("done");
             runLog.logText(`[planner] self-fix iter ${i} empty patch — stopping`);
             break;

package/src/environment/briefs.js

@@ -82,6 +82,18 @@ const B = {
       ],
       "findings with severity, category and file:line — or an explicit 'no security surface touched'."),
   },
+  board: {
+    purpose: "What the HU Board is and how to act on it without breaking it",
+    render: () => brief("Board",
+      "the HU Board is the permanent record of work: every card traces to who created it and what happened to it — a dashboard warning is fixed with the command it names, never by rebuilding the board.",
+      [
+        "Cards are NEVER deleted or recreated — not to fix warnings, not to tidy up. Discard = `kj hu move <id> skipped` (archived, history kept).",
+        "States move only via `kj hu move <id> <pending|running|done|failed|skipped>`.",
+        "A duplicate short_id means the card already exists: update that card, never add a twin.",
+        "A warning is information, not damage: run the command it names; if it looks like a kj bug, `kj report-issue` — never work around it by destroying state.",
+      ],
+      "the board reflects reality: the same cards before and after your action, with truthful states and provenance intact."),
+  },
   audit: {
     purpose: "Final look before shipping — does the whole thing hold?",
     render: () => brief("Audit",

package/src/environment/playbook.js

@@ -29,7 +29,7 @@ const TARGET_FILES = {
 // ENV-D1 (KJC-TSK-0642): the tracking invariant names the CHOSEN state
 // backend — a playbook that says "board or PG" makes the host guess.
 const BACKEND_TRACKING = {
-  "hu-board": "Every piece of work has a tracked story/bug in the HU Board (`kj hu add` / `kj board`) before it starts.",
+  "hu-board": "Every piece of work has a tracked story/bug in the HU Board (`kj hu add` / `kj board`) before it starts. Cards are permanent — never delete or recreate one; discard with `kj hu move <id> skipped`. `kj brief board` explains the board.",
   "planning-game": "Every piece of work has a tracked card in the Planning Game MCP before it starts (In Progress while you work it).",
 };
 
@@ -58,7 +58,7 @@ Invariants (the git gates enforce these — they are not suggestions):
   through an atomic PR (~150 net lines, Conventional Commits).
 
 Commands: \`kj rag query\` · \`kj brief <role>\` (triage, planner, researcher,
-architect, tester, security, audit) · \`kj hu add|move|list\` · \`kj adr add|list\` ·
+architect, tester, security, audit, board) · \`kj hu add|move|list\` · \`kj adr add|list\` ·
 \`kj review --staged\` · \`kj review --check\` · \`kj solomon --position\` ·
 \`kj agent run <agent>\` · \`kj report\` · \`kj check\`
 

package/src/plan/plan-fixer.js

@@ -10,7 +10,7 @@
  */
 
 import { extractFirstJson } from "../utils/json-extract.js";
-import { addHu, removeHu } from "./plan-hu-ops.js";
+import { addHu } from "./plan-hu-ops.js";
 import { normaliseAcceptanceTests } from "./plan-schema.js";
 import { withBrainRecovery } from "../brain/with-brain-recovery.js";
 
@@ -111,9 +111,31 @@ export async function applyReviewerFeedback({ agent, task, hus, findings, onOutp
 }
 
 export function applyFixerPatch(plan, patch) {
-  const counts = { added: 0, depsAdded: 0, deleted: 0 };
+  const counts = { added: 0, depsAdded: 0, archived: 0 };
+  // KJC-TSK-0669 (absolute rule): HUs are NEVER deleted — not even by the
+  // fix loop. Overlap resolutions ARCHIVE in place (status skipped +
+  // provenance), so history survives and ids stay referenceable. The
+  // references are cleaned exactly like removeHu used to, because a
+  // skipped dependency never satisfies the scheduler (deadlock otherwise).
   for (const huId of patch.deletions || []) {
-    if (removeHu(plan, huId)) counts.deleted += 1;
+    const hu = plan.hus.find(h => h.id === huId);
+    if (!hu) continue;
+    if (hu.status !== "skipped") {
+      hu.status = "skipped";
+      hu.archived_by = "plan-reviewer";
+      hu.archive_reason = "scope overlap resolved by the plan-review fix loop";
+      hu.updatedAt = new Date().toISOString();
+      counts.archived += 1;
+    }
+    for (const other of plan.hus) {
+      if (other.id === huId) continue;
+      if (Array.isArray(other.blocked_by) && other.blocked_by.includes(huId)) {
+        other.blocked_by = other.blocked_by.filter(d => d !== huId);
+      }
+      if (Array.isArray(other.reuse) && other.reuse.includes(huId)) {
+        other.reuse = other.reuse.filter(d => d !== huId);
+      }
+    }
   }
   // KJC-BUG-0053: las HUs añadidas por el fixer dejaban `short_id` y
   // `blocked_by` vacíos porque addHu no recibía esos campos. Resultado:
@@ -163,7 +185,7 @@ export function applyFixerPatch(plan, patch) {
     hu.blocked_by = [...blocked, on];
     counts.depsAdded += 1;
   }
-  if (counts.added + counts.depsAdded + counts.deleted > 0) {
+  if (counts.added + counts.depsAdded + counts.archived > 0) {
     plan.updatedAt = new Date().toISOString();
   }
   return counts;

package/src/spec-review/run-spec-review.js

@@ -11,6 +11,16 @@ import { RISK } from "../autonomy/policy.js";
 
 const MAX_REFINE_ITERATIONS = 5;
 
+// KJC-BUG-0125 (issue #1275): the prompt used to carry only counts and
+// categories — the dashboard modal showed "4 findings at severity fail"
+// with nothing to act on. The full findings travel with the prompt now
+// (capped: a runaway reviewer must not blow up the prompt payload).
+const MAX_FINDINGS_IN_PROMPT = 20;
+const findingsForPrompt = (findings) => findings.slice(0, MAX_FINDINGS_IN_PROMPT).map((f) => ({
+  id: f.id, severity: f.severity, category: f.category,
+  message: f.message, suggestion: f.suggestion || null,
+}));
+
 /**
  * Decide the gate action (`continue` | `refine`) autonomously: the Arbiter
  * picks PROCEED (proceed with the best reading) or RETRY_DIFFERENT_APPROACH
@@ -24,7 +34,7 @@ async function decideGateAutonomously(resolve, { severity, findings }) {
       { value: "PROCEED", label: "proceed with the best reading", conservative: true },
       { value: "RETRY_DIFFERENT_APPROACH", label: "auto-refine the spec" },
     ],
-    context: { severity, findingCount: findings.length, categories: [...new Set(findings.map((f) => f.category))] },
+    context: { severity, findingCount: findings.length, categories: [...new Set(findings.map((f) => f.category))], findings: findingsForPrompt(findings) },
     risk: severity === "fail" ? RISK.HIGH : RISK.LOW,
   });
   return choice === "RETRY_DIFFERENT_APPROACH" ? "refine" : "continue";
@@ -71,7 +81,7 @@ export async function runSpecReview({ spec, config, logger, askQuestion, flags =
       const answer = await askQuestion(
         `Spec review: ${findings.length} finding${findings.length === 1 ? "" : "s"} at severity ${severity}. [c]ontinue / [r]efine / [x]cancel? (default: continue)`,
         {
-          detail: { severity, findingCount: findings.length, categories: [...new Set(findings.map((f) => f.category))], iteration: iter + 1 },
+          detail: { severity, findingCount: findings.length, categories: [...new Set(findings.map((f) => f.category))], iteration: iter + 1, findings: findingsForPrompt(findings) },
           // KJC-BUG-0109: mirrors the interactive default — --yes presses Enter.
           defaultAnswer: "continue",
         },