karajan-code 4.48.1 → 4.49.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "karajan-code",
-  "version": "4.48.1",
+  "version": "4.49.0",
   "description": "Local multi-agent coding orchestrator with TDD, SonarQube, and code review pipeline",
   "type": "module",
   "license": "AGPL-3.0",
@@ -104,6 +104,7 @@
     "@babel/parser": "^7.29.7",
     "@karajan-family/governance": "^0.1.0",
     "@modelcontextprotocol/sdk": "^1.29.0",
+    "@xterm/xterm": "^6.0.0",
     "better-sqlite3": "^12.10.0",
     "chokidar": "^5.0.0",
     "commander": "^15.0.0",
@@ -120,8 +121,12 @@
     "sqlite-vec": "^0.1.9",
     "valibot": "^1.4.1",
     "web-tree-sitter": "^0.26.9",
+    "ws": "^8.21.3",
     "yaml": "^2.9.0"
   },
+  "optionalDependencies": {
+    "node-pty": "^1.1.0"
+  },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
     "@vitest/coverage-v8": "^4.1.8",

package/src/commands/architect.js

@@ -5,44 +5,32 @@ import { buildArchitectPrompt, parseArchitectOutput } from "../prompts/architect
 import { createCliProgressReporter } from "../utils/cli-progress.js";
 import { withBrainRecovery } from "../brain/with-brain-recovery.js";
 
-function formatLayers(layers, lines) {
-  lines.push("### Layers");
-  for (const l of layers) {
-    lines.push(typeof l === "string" ? `- ${l}` : `- **${l.name}**: ${l.responsibility || ""}`);
-  }
-  lines.push("");
-}
-
-function formatTradeoffs(tradeoffs, lines) {
-  lines.push("### Tradeoffs");
-  for (const t of tradeoffs) {
-    lines.push(`- **${t.decision}**: ${t.rationale || ""}`);
-    if (t.alternatives?.length) lines.push(`  Alternatives: ${t.alternatives.join(", ")}`);
-  }
+// KJC-BUG-0313 (#2061): the agent answers each list with plain strings or with
+// objects; both render, and a section with neither prints nothing, never "undefined".
+function section(title, items, render, lines) {
+  if (!items?.length) return;
+  lines.push(`### ${title}`);
+  for (const item of items) lines.push(...(typeof item === "string" ? [`- ${item}`] : render(item)));
   lines.push("");
 }
 
-function formatApiContracts(contracts, lines) {
-  lines.push("### API Contracts");
-  for (const c of contracts) {
-    lines.push(`- \`${c.method || "GET"} ${c.endpoint}\``);
-  }
-  lines.push("");
-}
+const named = (o, detail) => [`- **${o.name ?? o.decision ?? JSON.stringify(o)}**${detail ? `: ${detail}` : ""}`];
+const contract = (c) => [`- \`${c.method || "GET"} ${c.endpoint ?? c.path ?? ""}\``];
+const tradeoff = (t) => [...named(t, t.rationale), ...(t.alternatives?.length ? [`  Alternatives: ${t.alternatives.join(", ")}`] : [])];
+const entity = (e) => named(e, Array.isArray(e.fields) ? e.fields.join(", ") : e.description);
 
 function formatArchitecture(arch, lines) {
   if (arch.type) lines.push(`**Type:** ${arch.type}`, "");
-  if (arch.layers?.length) formatLayers(arch.layers, lines);
-  if (arch.patterns?.length) {
-    lines.push("### Patterns");
-    for (const p of arch.patterns) lines.push(`- ${p}`);
-    lines.push("");
-  }
-  if (arch.tradeoffs?.length) formatTradeoffs(arch.tradeoffs, lines);
-  if (arch.apiContracts?.length) formatApiContracts(arch.apiContracts, lines);
+  section("Layers", arch.layers, (l) => named(l, l.responsibility), lines);
+  section("Patterns", arch.patterns, (p) => [`- ${p.name ?? JSON.stringify(p)}`], lines);
+  section("Data Model", arch.dataModel?.entities, entity, lines);
+  // A contract given as a string ("GET /x") is code too: same backticks as an object's.
+  section("API Contracts", arch.apiContracts?.map((c) => (typeof c === "string" ? { raw: c } : c)), (c) => (c.raw ? [`- \`${c.raw}\``] : contract(c)), lines);
+  section("Dependencies", arch.dependencies, (d) => named(d, d.reason), lines);
+  section("Tradeoffs", arch.tradeoffs, tradeoff, lines);
 }
 
-function formatArchitect(result) {
+export function formatArchitect(result) {
   const lines = [];
   lines.push(`## Architecture Design`);
   lines.push(`**Verdict:** ${result.verdict || "unknown"}`, "");

package/src/commands/plan/fix.js

@@ -8,7 +8,7 @@ import { assertAgentsAvailable } from "../../agents/availability.js";
 import { resolveRole } from "../../config.js";
 import { createCliProgressReporter } from "../../utils/cli-progress.js";
 import { reviewPlan, findingsCount, findingsCountByType } from "../../plan/plan-reviewer.js";
-import { applyReviewerFeedback, applyFixerPatch } from "../../plan/plan-fixer.js";
+import { applyReviewerFeedback, applyFixerPatch, patchChanged } from "../../plan/plan-fixer.js";
 import { runStructuralPass } from "../../plan/plan-structural-pass.js";
 import { loadPlan, savePlan } from "../../plan/plan-store.js";
 
@@ -50,7 +50,9 @@ export async function planFixCommand({ config, planId, prompt, logger, json }) {
 
   // Self-fix loop con smart convergence guard (mismo que generate.js).
   const maxIter = 4;
-  for (let i = 1; i <= maxIter && count > 0; i++) {
+  // KJC-BUG-0316: with user feedback the fixer runs at least once, even when
+  // the reviewer flagged nothing, so the feedback is applied, not just read.
+  for (let i = 1; i <= maxIter && (count > 0 || (i === 1 && prompt)); i++) {
     const husSnapshot = JSON.parse(JSON.stringify(plan.hus));
     const reviewSnapshot = JSON.parse(JSON.stringify(plan.review));
     const fixProgress = createCliProgressReporter({ role: `plan-fix:iter ${i}`, quiet: Boolean(json) });
@@ -60,7 +62,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.archived === 0) { fixProgress.finish("done"); break; }
+    if (!patchChanged(ops)) { 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

@@ -7,7 +7,7 @@ import { createCliProgressReporter } from "../../utils/cli-progress.js";
 import { runAutoGC, summarizeGC } from "../../utils/garbage-collector.js";
 import { promptProjectName } from "../../utils/prompt-project-name.js";
 import { deriveProjectNameFromCwd } from "../../utils/derive-project-name-from-cwd.js";
-import { applyReviewerFeedback, applyFixerPatch } from "../../plan/plan-fixer.js";
+import { applyReviewerFeedback, applyFixerPatch, patchChanged } from "../../plan/plan-fixer.js";
 import { runStructuralPass } from "../../plan/plan-structural-pass.js";
 import { recommendModelsForHu, complexityFromTaskType } from "../../hu/model-router.js";
 import { withBrainRecovery } from "../../brain/with-brain-recovery.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.archived} archived`);
-          if (ops.added + ops.depsAdded + ops.archived === 0) {
+          runLog.logText(`[planner] self-fix iter ${i} applied: +${ops.added} HU, +${ops.depsAdded} dep, -${ops.depsRemoved} dep, ${ops.scopesEdited} scope, ${ops.archived} archived, ${ops.cyclesRejected} cycle(s) rejected`);
+          if (!patchChanged(ops)) {
             fixProgress.finish("done");
             runLog.logText(`[planner] self-fix iter ${i} empty patch — stopping`);
             break;

package/src/environment/playbook.js

@@ -84,7 +84,8 @@ ${panel ? `${panel}\n` : ""}- Security findings are never overridable — not ev
 - Publishing ANY artifact (a build's dist/, a docs site, a tarball)?
   \`kj privacy scan <dir>\` first — nothing personal or secret-shaped ships.
 - Branch first: never commit on the base branch — every change reaches it
-  through an atomic PR (~150 net lines, Conventional Commits). More than one
+  through an atomic PR (~150 net lines of code, Conventional Commits; human
+  docs, lockfiles, snapshots and dist/ do not count, AI-rule files do). More than one
   task, or the base tree must stay untouched? \`kj worktree start <slug>\`
   (one lane per task; \`kj worktree done <slug>\` after merge). Never CLAIM
   isolation without proof: in a lane, \`git rev-parse --git-dir\` differs

package/src/harden/workflow-templates.js

@@ -212,7 +212,7 @@ export const SHRINK_BUDGET_WORKFLOW = [
   // enter the agent's context every run and unbounded growth there dilutes the
   // signal. Documentation is exempt where documentation lives; markdown that
   // instructs an agent is code.
-  "          d=$(git diff --numstat \"origin/${BASE_REF}...HEAD\" -- . ':!**/docs/**/*.md' ':!**/docs/**/*.mdx' ':!**/docs/**/*.txt' ':!**/docs/**/*.rst' ':!README.md' ':!README.*.md' ':!CHANGELOG.md' ':!CONTRIBUTING.md' ':!SECURITY.md' ':!CODE_OF_CONDUCT.md' ':!MIGRATION*.md' ':!TODO*.md' ':!*.lock' ':!package-lock.json' ':!pnpm-lock.yaml' ':!npm-shrinkwrap.json' ':!dist/**' ':!build/**' ':!coverage/**' ':!**/*.snap' ':!**/__snapshots__/**' ':!**/*.min.js' ':!**/*.map' || true)",
+  "          d=$(git diff --numstat \"origin/${BASE_REF}...HEAD\" -- . ':!**/docs/**/*.md' ':!**/docs/**/*.mdx' ':!**/docs/**/*.txt' ':!**/docs/**/*.rst' ':!README.md' ':!README.*.md' ':!CHANGELOG.md' ':!CONTRIBUTING.md' ':!SECURITY.md' ':!CODE_OF_CONDUCT.md' ':!MIGRATION*.md' ':!TODO*.md' ':!*.lock' ':!package-lock.json' ':!pnpm-lock.yaml' ':!npm-shrinkwrap.json' ':!dist/**' ':!build/**' ':!coverage/**' ':!**/*.snap' ':!**/__snapshots__/**' ':!**/*.min.js' ':!**/*.map' ':(glob,exclude).karajan-shared/plans/*.json' || true)",
   '          a=$(printf "%s\\n" "$d" | awk \'$1!="-"{s+=$1}END{print s+0}\')',
   '          r=$(printf "%s\\n" "$d" | awk \'$2!="-"{s+=$2}END{print s+0}\')',
   '          net=$((a - r)); echo "net=$net (limit=$LOC_LIMIT)"',

package/src/hu/graph.js

@@ -1,3 +1,40 @@
+/**
+ * KJC-BUG-0315 (#2065): the first blocked_by cycle among `stories`, as a closed path
+ * (["080", "075", "010", "080"]), or null. A dependency on an id outside the set
+ * (an HU already done, or in another batch) is not a cycle.
+ * @param {Array<{id: string, blocked_by?: string[]}>} stories
+ * @returns {string[]|null}
+ */
+export function findCycle(stories) {
+  const deps = new Map(stories.map((s) => [s.id, s.blocked_by || []]));
+  const state = new Map(); // id -> "visiting" | "done"
+  const path = [];
+  const visit = (id) => {
+    if (state.get(id) === "done" || !deps.has(id)) return null;
+    if (state.get(id) === "visiting") return [...path.slice(path.indexOf(id)), id];
+    state.set(id, "visiting");
+    path.push(id);
+    for (const dep of deps.get(id)) {
+      const cycle = visit(dep);
+      if (cycle) return cycle;
+    }
+    path.pop();
+    state.set(id, "done");
+    return null;
+  };
+  for (const s of stories) {
+    const cycle = visit(s.id);
+    if (cycle) return cycle;
+  }
+  return null;
+}
+
+/** Throws, naming the cycle, when `stories` have one: there is no valid order to run them in. */
+export function assertNoCycle(stories) {
+  const cycle = findCycle(stories);
+  if (cycle) throw new Error(`Circular dependency between HUs: ${cycle.join(" -> ")}; no valid execution order exists, fix blocked_by (kj plan fix) before running`);
+}
+
 /**
  * Topological sort of HU stories respecting blocked_by dependencies.
  * Returns ordered array of story IDs (dependencies first).

package/src/orchestrator/hu-sub-pipeline.js

@@ -2,7 +2,7 @@
  * HU Sub-Pipeline — executes each certified HU as an independent sub-pipeline
  * with per-HU state tracking, topological ordering, and dependency-aware blocking.
  */
-import { topologicalSort } from "../hu/graph.js";
+import { assertNoCycle, topologicalSort } from "../hu/graph.js";
 import { updateStoryStatus, loadHuBatch, saveHuBatch, HU_STATUS } from "../hu/store.js";
 import { emitProgress, makeEvent } from "../utils/events.js";
 import { refineHuWithContext } from "../hu/lazy-planner.js";
@@ -455,10 +455,13 @@ export async function runHuSubPipeline({ huReviewerResult, runIterationFn, emitt
   }
 
   const certifiedStories = batch.stories.filter(s => s.status === HU_STATUS.CERTIFIED);
+  // KJC-BUG-0315 (#2065): a cycle has no valid order. The catch below fell back to
+  // the list order and ran it anyway; a cycle now stops the run and is named.
+  assertNoCycle(certifiedStories);
   let orderedIds;
   try {
     orderedIds = topologicalSort(certifiedStories);
-  } catch { /* cyclic dependency */
+  } catch { /* a dependency outside the certified batch (done or pending): keep the list order */
     orderedIds = certifiedStories.map(s => s.id);
   }
 

package/src/plan/plan-fixer.js

@@ -15,7 +15,8 @@ import { normaliseAcceptanceTests } from "./plan-schema.js";
 import { withBrainRecovery } from "../brain/with-brain-recovery.js";
 
 export function buildFixerPrompt({ task, hus, findings }) {
-  const huSummary = hus.map((h) => {
+  // KJC-BUG-0314: archived (skipped) HUs are not offered to the fixer to patch.
+  const huSummary = hus.filter((h) => h.status !== "skipped").map((h) => {
     const deps = Array.isArray(h.blocked_by) && h.blocked_by.length > 0
       ? ` ← blocked_by: ${h.blocked_by.join(", ")}` : "";
     return `- ${h.id}: ${h.title || "(untitled)"}${deps}`;
@@ -34,19 +35,25 @@ export function buildFixerPrompt({ task, hus, findings }) {
     "- missing_hus → MUST add one HU each",
     "- missing_dependencies → MUST declare each edge",
     "- scope_overlaps → MUST drop one of the pair or merge them",
+    "- USER FEEDBACK in the task (if any) → apply it too: deps_to_remove for",
+    "  an edge it says to drop, scope_edits for a scope it says to narrow",
     "Do NOT propose new features outside the findings list. Do not add new",
     "tests/logging/refactors. The fixer is scoped to the report ONLY.",
+    "A dependency that would close a cycle is rejected.",
     "",
     "Output MUST be a JSON object:",
     "```json",
     "{",
     '  "additions": [',
     '    { "id": "<symbolic>", "description": "<sentence>",',
+    '      "replaces": "<huId of a deleted HU it supersedes, if any>",',
     '      "spec_section": "<ref>", "dependencies": ["<huId>"],',
     '      "acceptance_tests": [ { "type":"gherkin","content":"…" } ],',
     '      "reuse": [] }',
     "  ],",
     '  "deps_to_add": [ { "huId": "<huId>", "on": "<huId>" } ],',
+    '  "deps_to_remove": [ { "huId": "<huId>", "on": "<huId>" } ],',
+    '  "scope_edits": [ { "huId": "<huId>", "scope": "<the narrowed scope>" } ],',
     '  "deletions": [ "<huId>" ]',
     "}",
     "```",
@@ -65,14 +72,19 @@ export function buildFixerPrompt({ task, hus, findings }) {
   ].filter(Boolean).join("\n");
 }
 
+const normaliseEdges = (list) => (Array.isArray(list) ? list : [])
+  .filter(d => d && typeof d.huId === "string" && typeof d.on === "string")
+  .map(d => ({ huId: d.huId.trim(), on: d.on.trim() }));
+
 function normalisePatch(raw) {
-  const out = { additions: [], deps_to_add: [], deletions: [] };
+  const out = { additions: [], deps_to_add: [], deps_to_remove: [], scope_edits: [], deletions: [] };
   if (!raw || typeof raw !== "object") return out;
   if (Array.isArray(raw.additions)) {
     out.additions = raw.additions
       .filter(a => a && typeof a === "object" && typeof a.description === "string" && a.description.trim())
       .map(a => ({
         id: typeof a.id === "string" ? a.id.trim() : null,
+        replaces: typeof a.replaces === "string" && a.replaces.trim() ? a.replaces.trim() : null,
         description: String(a.description).trim(),
         spec_section: typeof a.spec_section === "string" ? a.spec_section.trim() || null : null,
         dependencies: Array.isArray(a.dependencies) ? a.dependencies.map(String) : [],
@@ -80,10 +92,12 @@ function normalisePatch(raw) {
         reuse: Array.isArray(a.reuse) ? a.reuse.map(String) : [],
       }));
   }
-  if (Array.isArray(raw.deps_to_add)) {
-    out.deps_to_add = raw.deps_to_add
-      .filter(d => d && typeof d.huId === "string" && typeof d.on === "string")
-      .map(d => ({ huId: d.huId.trim(), on: d.on.trim() }));
+  out.deps_to_add = normaliseEdges(raw.deps_to_add);
+  out.deps_to_remove = normaliseEdges(raw.deps_to_remove);
+  if (Array.isArray(raw.scope_edits)) {
+    out.scope_edits = raw.scope_edits
+      .filter(e => e && typeof e.huId === "string" && typeof e.scope === "string" && e.scope.trim())
+      .map(e => ({ huId: e.huId.trim(), scope: e.scope.trim() }));
   }
   if (Array.isArray(raw.deletions)) {
     out.deletions = raw.deletions.filter(d => typeof d === "string" && d.trim()).map(d => d.trim());
@@ -110,8 +124,46 @@ export async function applyReviewerFeedback({ agent, task, hus, findings, onOutp
   return { ok: true, patch: normalisePatch(parsed) };
 }
 
+// KJC-BUG-0316: whether `from` depends on `target`, directly or transitively.
+function dependsOn(plan, from, target) {
+  const seen = new Set();
+  const stack = [from];
+  while (stack.length > 0) {
+    const id = stack.pop();
+    if (id === target) return true;
+    if (seen.has(id)) continue;
+    seen.add(id);
+    stack.push(...(plan.hus.find((h) => h.id === id)?.blocked_by || []));
+  }
+  return false;
+}
+
+/** Whether applying the patch changed the plan (a rejected cycle is not a change). */
+export function patchChanged(counts) {
+  return counts.added + counts.depsAdded + counts.depsRemoved + counts.scopesEdited + counts.archived > 0;
+}
+
 export function applyFixerPatch(plan, patch) {
-  const counts = { added: 0, depsAdded: 0, archived: 0 };
+  const counts = { added: 0, depsAdded: 0, depsRemoved: 0, scopesEdited: 0, archived: 0, cyclesRejected: 0 };
+  // KJC-BUG-0316 (#2066): an edge the feedback says to drop, and a scope it says to narrow.
+  for (const { huId, on } of patch.deps_to_remove || []) {
+    const hu = plan.hus.find((h) => h.id === huId);
+    if (!hu?.blocked_by?.includes(on)) continue;
+    hu.blocked_by = hu.blocked_by.filter((d) => d !== on);
+    counts.depsRemoved += 1;
+  }
+  for (const { huId, scope } of patch.scope_edits || []) {
+    const hu = plan.hus.find((h) => h.id === huId);
+    if (!hu || hu.scope === scope) continue;
+    hu.scope = scope;
+    counts.scopesEdited += 1;
+  }
+  // KJC-BUG-0314 (#2063): what a deleted HU depended on and who depended on it,
+  // taken before archiving cleans the edges, so its replacement can take over.
+  const replaced = new Map((patch.deletions || []).map((id) => [id, {
+    deps: [...(plan.hus.find((h) => h.id === id)?.blocked_by || [])],
+    dependents: plan.hus.filter((h) => h.id !== id && h.blocked_by?.includes(id)).map((h) => h.id),
+  }]));
   // 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
@@ -165,15 +217,23 @@ export function applyFixerPatch(plan, patch) {
     hu.created_by = "plan-reviewer"; // KJC-TSK-0661: provenance stamp
     if (symbolicId) symbolicToHuId.set(symbolicId, hu.id);
     const depsSymbolic = Array.isArray(a.dependencies) ? a.dependencies : [];
-    addedHus.push({ hu, depsSymbolic });
+    addedHus.push({ hu, depsSymbolic, replaces: a.replaces });
     counts.added += 1;
   }
-  // Pasada 2: resolver deps simbólicas de las additions a ids largos.
-  for (const { hu, depsSymbolic } of addedHus) {
+  // Pasada 2: resolver deps simbólicas de las additions a ids largos. KJC-BUG-0314:
+  // a dependency given by the HU's own long id resolves too.
+  const liveIds = new Set(plan.hus.filter((h) => h.status !== "skipped").map((h) => h.id));
+  for (const { hu, depsSymbolic, replaces } of addedHus) {
     const resolved = depsSymbolic
-      .map((s) => typeof s === "string" ? symbolicToHuId.get(s.trim()) : null)
+      .map((s) => (typeof s === "string" ? symbolicToHuId.get(s.trim()) ?? (liveIds.has(s.trim()) ? s.trim() : null) : null))
       .filter(Boolean);
-    if (resolved.length > 0) hu.blocked_by = resolved;
+    const takeOver = replaced.get(replaces);
+    const deps = [...new Set([...resolved, ...(takeOver?.deps || []).filter((d) => liveIds.has(d))])];
+    if (deps.length > 0) hu.blocked_by = deps;
+    for (const id of takeOver?.dependents || []) {
+      const dependent = plan.hus.find((h) => h.id === id);
+      if (dependent && !dependent.blocked_by?.includes(hu.id)) dependent.blocked_by = [...(dependent.blocked_by || []), hu.id];
+    }
   }
   const knownIds = new Set(plan.hus.map(h => h.id));
   for (const { huId, on } of patch.deps_to_add || []) {
@@ -182,10 +242,11 @@ export function applyFixerPatch(plan, patch) {
     if (!hu) continue;
     const blocked = Array.isArray(hu.blocked_by) ? hu.blocked_by : [];
     if (blocked.includes(on)) continue;
+    if (dependsOn(plan, on, huId)) { counts.cyclesRejected += 1; continue; }
     hu.blocked_by = [...blocked, on];
     counts.depsAdded += 1;
   }
-  if (counts.added + counts.depsAdded + counts.archived > 0) {
+  if (patchChanged(counts)) {
     plan.updatedAt = new Date().toISOString();
   }
   return counts;

package/src/plan/plan-reviewer.js

@@ -42,7 +42,8 @@ import { withBrainRecovery } from "../brain/with-brain-recovery.js";
  * @returns {string}
  */
 export function buildReviewerPrompt({ task, hus }) {
-  const huSummary = hus.map((h, i) => {
+  // KJC-BUG-0314: an archived (skipped) HU is history, not part of the plan to review.
+  const huSummary = hus.filter((h) => h.status !== "skipped").map((h, i) => {
     const deps = Array.isArray(h.blocked_by) && h.blocked_by.length > 0
       ? ` ← blocked_by: ${h.blocked_by.join(", ")}`
       : "";

package/src/plan/plan-schema.js

@@ -5,6 +5,7 @@
  */
 
 import { generatePlanId } from "./plan-id.js";
+import { findCycle } from "../hu/graph.js";
 
 const VALID_PLAN_STATUSES = new Set(["draft", "ready", "running", "done", "failed"]);
 // KJC-TSK-0394 step 5: el modelo CANONICAL del lifecycle es
@@ -24,6 +25,9 @@ const VALID_HU_STATUSES = new Set([
   "pending", "running", "done",
   // Legacy
   "certified", "coding", "reviewing", "failed", "blocked", "needs_context",
+  // KJC-BUG-0314 (#2063): HUs are never deleted (KJC-TSK-0669); the fix loop
+  // archives them as skipped, and validate rejected its own archive status.
+  "skipped",
 ]);
 export const CANONICAL_HU_STATUSES = new Set(["pending", "running", "done"]);
 // KJC-TSK-0394: nuevo campo `result` ortogonal a status. Reemplaza la
@@ -301,34 +305,9 @@ export function validatePlan(plan) {
     }
   }
 
-  // Check for circular dependencies
-  try {
-    topoSort(plan.hus || []);
-  } catch {
-    errors.push("Circular dependency detected in HU blocked_by graph");
-  }
+  // KJC-BUG-0315 (#2065): the cycle is named, so the person knows which edge to cut.
+  const cycle = findCycle(plan.hus || []);
+  if (cycle) errors.push(`Circular dependency in HU blocked_by graph: ${cycle.join(" -> ")}`);
 
   return errors.length === 0 ? { valid: true } : { valid: false, errors };
 }
-
-/** Simple topological sort for cycle detection. */
-function topoSort(hus) {
-  const visited = new Set();
-  const visiting = new Set();
-  const order = [];
-  const map = new Map(hus.map(h => [h.id, h]));
-
-  function visit(id) {
-    if (visited.has(id)) return;
-    if (visiting.has(id)) throw new Error("cycle");
-    visiting.add(id);
-    const hu = map.get(id);
-    for (const dep of hu?.blocked_by || []) visit(dep);
-    visiting.delete(id);
-    visited.add(id);
-    order.push(id);
-  }
-
-  for (const hu of hus) visit(hu.id);
-  return order;
-}

package/src/policy/supervisor-verify.js

@@ -20,6 +20,16 @@ const HARNESS_PREFIX = ".karajan/harness/";
 const SAFE_DIR = /^(\$HOME)?(\/[\w.@%+~-]+)+$/;
 
 const sha256 = (buf) => createHash("sha256").update(buf).digest("hex");
+// KJC-BUG-0311: the kj judging now, to tell a seal made by another version. Read
+// lazily and never fatal (a bundled binary may not carry package.json): unknown
+// means no seal counts as "older", so the strict re-render rule applies.
+let kjVersionCache;
+const kjVersion = () => {
+  if (kjVersionCache === undefined) {
+    try { kjVersionCache = JSON.parse(readFileSync(new URL("../../package.json", import.meta.url), "utf8")).version ?? null; } catch { kjVersionCache = null; }
+  }
+  return kjVersionCache;
+};
 
 /**
  * @returns {{files: Set<string>, reason?: string}} rutas repo-relativas de
@@ -41,6 +51,11 @@ export function verifiedSupervisorFiles({ projectDir, trackedOnly = false }) {
   if (!signed.ok) return { files: new Set(), reason: signed.reason };
   const ok = new Set();
   const unjudgeable = new Set();
+  const signedAbsent = new Set();
+  const current = kjVersion();
+  const olderSeal = current && typeof prov?.kj_version === "string" && prov.kj_version !== current ? prov.kj_version : null;
+  let vouched = false;
+  let stale = false;
   // KJC-BUG-0259 (user's decision, option A): history is judged with the kj of
   // when it was committed. The harness guards are machine-local and never in the
   // repo; the review and each PR's CI verify them when the seal is made. A check
@@ -72,6 +87,9 @@ export function verifiedSupervisorFiles({ projectDir, trackedOnly = false }) {
     // tiene que ser el de un guardia que kj CONOCE, o una procedencia forjada
     // colaria entradas ausentes con cualquier hash (catch de la review).
     if (prefix === HARNESS_PREFIX && st === null) {
+      // KJC-TSK-0877: with the roster's signature verified, the human signed this
+      // guard's hash with the rest; that vouches for it without seeing the file.
+      if (signed.required && typeof entry.sha256 === "string") { signedAbsent.add(entry.file); continue; }
       const body = canonicalHarnessBody(entry.file.slice(prefix.length));
       if (body != null && typeof entry.sha256 === "string" && sha256(Buffer.from(body, "utf8")) === entry.sha256) unjudgeable.add(entry.file);
       continue;
@@ -87,13 +105,23 @@ export function verifiedSupervisorFiles({ projectDir, trackedOnly = false }) {
       continue;
     }
     if (canonical != null && sha256(Buffer.from(canonical, "utf8")) === entry.sha256) ok.add(entry.file);
+    // KJC-BUG-0311 (#2052): sealed with another kj whose template this kj cannot
+    // re-render. A phone of the roster signed these very bytes: that vouches for
+    // them. Without that signature recomputation is the only proof, so it stays
+    // denied (an unsigned provenance could claim any version to skip it).
+    else if (olderSeal && signed.required) { ok.add(entry.file); vouched = true; }
+    else if (olderSeal) stale = true;
   }
   // `complete` = ninguna entrada FALLO y alguna verifico. Exigir que todas
   // verifiquen hacia imposible sellar desde cualquier sitio que no fuera la
   // maquina que sello, porque los guardias no viajan con el repo (0212).
-  const judged = (e) => ok.has(e.file) || unjudgeable.has(e.file);
+  const judged = (e) => ok.has(e.file) || unjudgeable.has(e.file) || signedAbsent.has(e.file);
   const complete = ok.size > 0 && entries.every((e) => typeof e?.file === "string" && judged(e));
-  return { files: ok, complete, unjudgeable, signed: signed.required };
+  return {
+    files: ok, complete, unjudgeable, signedAbsent, signed: signed.required,
+    ...(vouched ? { vouchedOlder: olderSeal } : {}),
+    ...(stale ? { reason: `sellado con kj ${olderSeal} y este kj (${current}) no puede recomputar su plantilla, y sin firma del padrón nada más lo respalda: re-séllalo con kj harden --commit` } : {}),
+  };
 }
 
 /**
@@ -113,10 +141,13 @@ export function liftSealedSupervisorViolations({ projectDir, violations, tracked
     && (sealed.files.has(v.file) || (v.file === PROVENANCE_FILE && sealed.complete === true));
   const kept = violations.filter((v) => !liftable(v));
   const unjudged = sealed.unjudgeable?.size ?? 0;
+  const vouchedAbsent = sealed.signedAbsent?.size ?? 0;
   const notes = [
     ...(unjudged > 0 ? [`${unjudged} guardia(s) del sello no existen en este checkout y no se han podido comprobar aquí`] : []),
+    ...(vouchedAbsent > 0 ? [`${vouchedAbsent} guardia(s) del sello no existen en este checkout y están respaldados por la firma del padrón`] : []),
     // KJC-TSK-0964: what the signature did or did not prove is said, never assumed.
     ...(sealed.signed === false ? ["proyecto sin padrón de firmantes: el sello no lleva firma verificable y su garantía es solo local"] : []),
+    ...(sealed.vouchedOlder ? [`sellado con kj ${sealed.vouchedOlder}: este kj no puede recomputar su plantilla y lo respalda la firma del padrón sobre esos bytes`] : []),
     ...(kept.length === violations.length && sealed.reason ? [sealed.reason] : []),
   ];
   return {

package/src/privacy/scan.js

@@ -98,6 +98,12 @@ const CONTEXT_DISCARDS = [
   // (about 1 in 100) still warns, because nothing tells it apart from a phone
   // written after "R-"; the allow list is the way out for that one.
   { type: "rule-id", re: /\bR-(?=\d*[a-f])[0-9a-f]{10}\b/g },
+  // KJC-BUG-0317: a kj plan id is `plan-` + a YYYYMMDDHHMMSS stamp + `-` + 4
+  // lowercase alphanumerics, also inside an HU id (hu_<planId>_007, hence the
+  // lookarounds instead of \b). Only that WHOLE shape with a real 20xx date and
+  // time: no card of 14 digits starts with 20 (Diners is 30/36/38), and a
+  // 16-digit card does not fit the slot.
+  { type: "plan-id", re: /(?<![A-Za-z0-9])plan-20\d\d(?:0[1-9]|1[0-2])(?:0[1-9]|[12]\d|3[01])(?:[01]\d|2[0-3])[0-5]\d[0-5]\d-[a-z0-9]{4}(?![A-Za-z0-9])/g },
 ];
 
 /**

package/src/review/loc-budget.js

@@ -33,6 +33,8 @@ const EXEMPT = [
   /(^|\/)(package-lock\.json|pnpm-lock\.yaml|yarn\.lock|npm-shrinkwrap\.json)$/,
   /\.lock$/,
   /(^|\/)tests\/_diet\//,
+  // KJC-BUG-0318: the plan `kj plan share` writes, at the project root only.
+  /^\.karajan-shared\/plans\/[^/]+\.json$/,
   // Human documentation, wherever the project keeps it. The landing's docs
   // moved into the monorepo (MONO-3) and the old root-anchored `docs/` rule
   // stopped matching them, which is how documenting started costing budget.

package/src/skills/addyosmani-catalog.js

@@ -97,6 +97,23 @@ export function __resetGitProbe() {
   _gitAvailable = null;
 }
 
+/**
+ * KJC-BUG-0320: check out only skills/. The rest of the repo (evals/ with its
+ * *.test.js fixtures, scripts/) is never read, and under a project-local
+ * KARAJAN home the project's test runner picked those fixtures up.
+ * Idempotent, so an older full clone narrows on its next refresh.
+ */
+async function narrowToSkills(root, logger) {
+  const result = await runCommand("git", ["-C", root, "sparse-checkout", "set", SKILLS_SUBDIR], { timeout: 30_000 });
+  if (result?.exitCode === 0) return null;
+  // Neither a full checkout (it brings the fixtures back) nor a half one stays:
+  // the clone goes, the caller reports it, and the next use clones again.
+  await fs.rm(root, { recursive: true, force: true });
+  const error = `skills/ could not be checked out alone: ${(result?.stderr || "").trim() || "sparse-checkout failed"}`;
+  logger?.warn?.(`addyosmani-catalog: ${error} (catalog removed)`);
+  return error;
+}
+
 /**
  * Clone the addyosmani/agent-skills repo (shallow) if it does not already
  * exist locally. No-op when it is already present.
@@ -121,7 +138,7 @@ export async function ensureCatalog(opts = {}) {
 
   const result = await runCommand(
     "git",
-    ["clone", "--depth", "1", repoUrl, root],
+    ["clone", "--depth", "1", "--sparse", repoUrl, root],
     { timeout: 120_000 }
   );
 
@@ -130,6 +147,8 @@ export async function ensureCatalog(opts = {}) {
     logger?.warn?.(`addyosmani-catalog: clone failed — ${stderr}`);
     return { ok: false, error: stderr || `clone failed (exit ${result.exitCode})` };
   }
+  const narrowError = await narrowToSkills(root, logger);
+  if (narrowError) return { ok: false, error: narrowError };
 
   await writeMeta({
     repoUrl,
@@ -204,6 +223,8 @@ export async function refreshIfStale(opts = {}) {
     action = "reset";
     logger?.info?.("addyosmani-catalog: ff-only failed, recovered via fetch+reset (upstream force-pushed)");
   }
+  const narrowError = await narrowToSkills(root, logger);
+  if (narrowError) return { ok: false, action: "skipped", error: narrowError };
 
   await writeMeta({
     ...(meta || {}),