karajan-code 4.1.6 → 4.1.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "karajan-code",
-  "version": "4.1.6",
+  "version": "4.1.8",
   "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/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/scripts/install-binary.ps1

@@ -1,50 +1,158 @@
 <#
 .SYNOPSIS
-  Karajan Code — standalone binary installer for Windows (no Node required).
+  Karajan Code installer for Windows — guarantees a COMPLETE install (KJC-TSK-0667).
 
 .DESCRIPTION
-  Downloads the prebuilt kj.exe for Windows x64 from the GitHub release,
-  verifies its SHA256 checksum, installs it to %LOCALAPPDATA%\Karajan, and
-  adds that folder to the user PATH (idempotently). Re-running updates the
-  binary in place without duplicating PATH entries.
-
   Run it with:
     irm https://karajancode.com/install.ps1 | iex
 
-  Override with env vars: $env:KJ_VERSION (e.g. v3.7.2), $env:KJ_INSTALL_DIR.
+  Default route: npm — the full product (CLI + RAG + HU Board + MCP).
+    1. Node >= 22.12 present  -> npm install -g karajan-code
+    2. No usable Node         -> auto-provision the official Node LTS zip into
+       ~\.karajan\node (checksum-verified, nothing system-wide touched),
+       install karajan-code with it, drop kj/karajan-mcp wrappers into the
+       install dir and add it to the user PATH.
+  Standalone route (CLI only, no native-module features — RAG/board/MCP
+  unavailable): opt-in with $env:KJ_STANDALONE = "1".
 
-  KJC-TSK-0594.
+  Env overrides (irm|iex cannot take parameters): KJ_VERSION, KJ_INSTALL_DIR,
+  KJ_STANDALONE. Windows PowerShell 5.1 compatible.
 #>
 $ErrorActionPreference = "Stop"
 
 $repo = "manufosela/karajan-code"
 $version = if ($env:KJ_VERSION) { $env:KJ_VERSION } else { "latest" }
 $installDir = if ($env:KJ_INSTALL_DIR) { $env:KJ_INSTALL_DIR } else { Join-Path $env:LOCALAPPDATA "Karajan" }
-$asset = "kj-win-x64.exe"
+$mode = if ($env:KJ_STANDALONE -eq "1") { "standalone" } else { "full" }
+$nodeMajor = 22
+$nodeMinMinor = 12
+
+function Get-NpmPkg {
+  if ($version -eq "latest") { "karajan-code" } else { "karajan-code@" + $version.TrimStart("v") }
+}
 
-if ($version -eq "latest") {
-  $base = "https://github.com/$repo/releases/latest/download"
-} else {
-  $base = "https://github.com/$repo/releases/download/$version"
+function Test-NodeOk {
+  $node = Get-Command node -ErrorAction SilentlyContinue
+  if (-not $node) { return $false }
+  $v = (& node --version) 2>$null
+  if (-not $v) { return $false }
+  $parts = $v.TrimStart("v").Split(".")
+  $major = [int]$parts[0]; $minor = [int]$parts[1]
+  return ($major -gt $nodeMajor) -or ($major -eq $nodeMajor -and $minor -ge $nodeMinMinor)
+}
+
+function Add-UserPath([string]$dir) {
+  $userPath = [Environment]::GetEnvironmentVariable("Path", "User")
+  $parts = @()
+  if ($userPath) { $parts = $userPath.Split(";") | Where-Object { $_ -ne "" } }
+  $already = $parts | Where-Object { $_.TrimEnd("\") -ieq $dir.TrimEnd("\") }
+  if (-not $already) {
+    $newPath = if ($userPath) { "$userPath;$dir" } else { $dir }
+    [Environment]::SetEnvironmentVariable("Path", $newPath, "User")
+    Write-Host "kj-install: added '$dir' to your user PATH. Open a NEW terminal to use 'kj'."
+  }
 }
 
-# Download to a temp folder; only install once the checksum matches, so a
-# failure never leaves a half-installed binary behind.
 $tmp = Join-Path ([System.IO.Path]::GetTempPath()) ("kj-install-" + [System.Guid]::NewGuid().ToString("N"))
 New-Item -ItemType Directory -Path $tmp -Force | Out-Null
+
 try {
+  if ($mode -eq "full") {
+    if (Test-NodeOk) {
+      Write-Host "kj-install: Node $(& node --version) found — installing via npm (full product)..."
+      & npm install -g (Get-NpmPkg)
+      if ($LASTEXITCODE -ne 0) { throw "npm install failed (exit $LASTEXITCODE)." }
+      Write-Host "kj-install: installed. Run 'kj doctor' next, then 'kj install-tools' to complete the whole stack."
+      return
+    }
+
+    Write-Host "kj-install: no usable Node (need >= $nodeMajor.$nodeMinMinor) — provisioning official Node LTS into ~\.karajan\node (nothing system-wide)..."
+    $dist = "https://nodejs.org/dist/latest-v$nodeMajor.x"
+    $shaFile = Join-Path $tmp "SHASUMS256.txt"
+    Invoke-WebRequest -Uri "$dist/SHASUMS256.txt" -OutFile $shaFile -UseBasicParsing
+    $shaLines = Get-Content $shaFile
+    $assetLine = $shaLines | Where-Object { $_ -match "node-v[0-9.]+-win-x64\.zip" } | Select-Object -First 1
+    if (-not $assetLine) { throw "no official Node build for win-x64 in $dist" }
+    $nodeAsset = ($assetLine -split "\s+")[1]
+    $expected = ($assetLine -split "\s+")[0].ToLower()
+
+    Write-Host "kj-install: downloading $nodeAsset..."
+    $zip = Join-Path $tmp $nodeAsset
+    Invoke-WebRequest -Uri "$dist/$nodeAsset" -OutFile $zip -UseBasicParsing
+    $actual = (Get-FileHash -Algorithm SHA256 -Path $zip).Hash.ToLower()
+    if ($expected -ne $actual) { throw "Node checksum mismatch — aborting, nothing installed." }
+
+    # Stage everything (extract + npm install) and only swap into place once
+    # EVERYTHING succeeded — a failure must never destroy a previous working
+    # ~\.karajan\node.
+    $nodeHome = Join-Path $env:USERPROFILE ".karajan\node"
+    $staging = "$nodeHome.staging.$PID"
+    $extract = Join-Path $tmp "extract"
+    if (Test-Path $staging) { Remove-Item -Recurse -Force $staging }
+    Expand-Archive -Path $zip -DestinationPath $extract -Force
+    # The zip wraps everything in a node-vX.Y.Z-win-x64\ top folder — unwrap it.
+    $inner = Get-ChildItem -Directory $extract | Select-Object -First 1
+    New-Item -ItemType Directory -Path (Split-Path $staging) -Force | Out-Null
+    Move-Item -Path $inner.FullName -Destination $staging
+
+    Write-Host "kj-install: installing karajan-code with the provisioned Node..."
+    $env:Path = "$staging;$env:Path"
+    # Explicit --prefix: the official Windows npm ships a builtin prefix of
+    # %AppData%\npm — without this the global shims would land OUTSIDE the
+    # self-contained ~\.karajan\node home (on Windows, prefix root IS the
+    # global bin dir, so shims land at $staging\kj.cmd).
+    & (Join-Path $staging "npm.cmd") install -g --prefix "$staging" (Get-NpmPkg)
+    if ($LASTEXITCODE -ne 0) { throw "npm install failed with the provisioned Node (exit $LASTEXITCODE)." }
+    foreach ($bin in @("kj", "karajan-mcp")) {
+      if (-not (Test-Path (Join-Path $staging "$bin.cmd"))) {
+        throw "npm reported success but the $bin shim is missing from the staged prefix — the full product needs both kj and karajan-mcp. Aborting, nothing swapped."
+      }
+    }
+
+    # Swap keeping the previous install recoverable: park it as a backup,
+    # move the staged one in, restore the backup if that move fails.
+    $backup = "$nodeHome.old.$PID"
+    if (Test-Path $nodeHome) { Move-Item -Path $nodeHome -Destination $backup -Force }
+    try {
+      Move-Item -Path $staging -Destination $nodeHome
+    } catch {
+      if (Test-Path $backup) { Move-Item -Path $backup -Destination $nodeHome -Force }
+      throw "could not move the staged install into place (previous install restored). $_"
+    }
+    if (Test-Path $backup) { Remove-Item -Recurse -Force $backup }
+
+    # Wrappers, not copies: npm's own .cmd shims live inside nodeHome and
+    # resolve node via their folder; these put nodeHome on PATH for children
+    # (kj spawns node tooling) and forward every argument.
+    New-Item -ItemType Directory -Path $installDir -Force | Out-Null
+    foreach ($bin in @("kj", "karajan-mcp")) {
+      $shim = Join-Path $nodeHome "$bin.cmd"
+      $wrapper = @(
+        "@echo off",
+        "set `"PATH=$nodeHome;%PATH%`"",
+        "`"$shim`" %*"
+      )
+      Set-Content -Path (Join-Path $installDir "$bin.cmd") -Value $wrapper -Encoding ASCII
+    }
+    Add-UserPath $installDir
+    $installed = (& (Join-Path $installDir "kj.cmd") --version) 2>$null
+    Write-Host "kj-install: installed kj $installed (full product) — kj at $(Join-Path $installDir 'kj.cmd')"
+    Write-Host "kj-install: next — run 'kj doctor', then 'kj install-tools' to complete the whole stack."
+    return
+  }
+
+  # --- Standalone route: prebuilt single binary (CLI only). ---
+  Write-Host "kj-install: standalone mode — single binary, NO native-module features (RAG, HU Board and MCP need the npm install)."
+  $asset = "kj-win-x64.exe"
+  $base = if ($version -eq "latest") { "https://github.com/$repo/releases/latest/download" }
+          else { "https://github.com/$repo/releases/download/$version" }
+
   $binTmp = Join-Path $tmp "kj.exe"
   $shaTmp = Join-Path $tmp "kj.exe.sha256"
-
   Write-Host "kj-install: downloading $asset ($version)..."
-  try {
-    Invoke-WebRequest -Uri "$base/$asset" -OutFile $binTmp -UseBasicParsing
-    Invoke-WebRequest -Uri "$base/$asset.sha256" -OutFile $shaTmp -UseBasicParsing
-  } catch {
-    throw "could not download $base/$asset — does that version/asset exist, and is the network reachable? ($_)"
-  }
+  Invoke-WebRequest -Uri "$base/$asset" -OutFile $binTmp -UseBasicParsing
+  Invoke-WebRequest -Uri "$base/$asset.sha256" -OutFile $shaTmp -UseBasicParsing
 
-  # certutil writes a multi-line file; keep only the hex of the hash line.
   $shaLine = (Get-Content $shaTmp | Where-Object { $_ -notmatch "SHA256|CertUtil" } | Select-Object -First 1)
   $expected = ($shaLine -replace "[^0-9A-Fa-f]", "").ToLower()
   $actual = (Get-FileHash -Algorithm SHA256 -Path $binTmp).Hash.ToLower()
@@ -52,38 +160,15 @@ try {
     throw "checksum mismatch (expected '$expected', got '$actual'). Aborting, nothing installed."
   }
 
-  # Install: move into place, replacing any previous install (idempotent).
   New-Item -ItemType Directory -Path $installDir -Force | Out-Null
   $dest = Join-Path $installDir "kj.exe"
   Move-Item -Path $binTmp -Destination $dest -Force
-
-  # The download carries a "mark of the web" (Zone.Identifier) that makes
-  # SmartScreen warn on first run. The binary is not code-signed with a paid
-  # certificate, so clear the mark on the copy we just verified ourselves.
+  # Clear the mark-of-the-web on the copy we just checksum-verified ourselves.
   Unblock-File -Path $dest -ErrorAction SilentlyContinue
-
+  Add-UserPath $installDir
   $installed = (& $dest --version) 2>$null
-  Write-Host "kj-install: installed kj $installed to $dest"
-
-  # Add to the user PATH only if it is not already there (no duplicates).
-  $userPath = [Environment]::GetEnvironmentVariable("Path", "User")
-  $parts = @()
-  if ($userPath) { $parts = $userPath.Split(";") | Where-Object { $_ -ne "" } }
-  $already = $parts | Where-Object { $_.TrimEnd("\") -ieq $installDir.TrimEnd("\") }
-  if (-not $already) {
-    $newPath = if ($userPath) { "$userPath;$installDir" } else { $installDir }
-    [Environment]::SetEnvironmentVariable("Path", $newPath, "User")
-    Write-Host "kj-install: added '$installDir' to your user PATH. Open a new terminal to use 'kj'."
-  } else {
-    Write-Host "kj-install: '$installDir' is already on your user PATH — run 'kj --help' to get started."
-  }
-
-  # The binary bundles no toolchain. kj orchestrates external tools, so name
-  # the hard requirements and let `kj doctor` check them for this machine.
-  Write-Host ""
-  Write-Host "kj-install: next step — run 'kj doctor' to check prerequisites."
-  Write-Host "  Required: git, plus at least one agent CLI (Claude Code, Codex or Gemini)."
-  Write-Host "  Optional: Docker (local models, SonarQube) and Node/npm (helper tools: Squeezr, qmd)."
+  Write-Host "kj-install: installed standalone kj $installed to $dest"
+  Write-Host "kj-install: next — run 'kj doctor'. For the full product later: re-run without KJ_STANDALONE."
 } finally {
   Remove-Item -Path $tmp -Recurse -Force -ErrorAction SilentlyContinue
 }

package/src/audit/osv-findings.js

@@ -35,6 +35,11 @@ const SEVERITY_ORDER = ["CRITICAL", "HIGH", "MEDIUM", "LOW", "MODERATE"];
  * @returns {Promise<{available: boolean, reason?: string, total?: number, vulnerabilities?: object[]}>}
  */
 export async function collectOsvFindings(projectDir, logger = null) {
+  // KJC-BUG-0122: same kill-switch as semgrep — external scanners never
+  // fire from the unit suite; e2e opts in with KJ_ALLOW_REAL_SCANS=1.
+  if (process.env.VITEST && process.env.KJ_ALLOW_REAL_SCANS !== "1") {
+    return { available: false, reason: "real scans disabled under the test runner (set KJ_ALLOW_REAL_SCANS=1 to opt in)" };
+  }
   let stdout;
   try {
     const { stdout: out } = await execFileAsync(

package/src/audit/semgrep-findings.js

@@ -34,6 +34,14 @@ const SEVERITY_ORDER = ["ERROR", "WARNING", "INFO"];
  * @returns {Promise<{available: boolean, reason?: string, total?: number, findings?: object[]}>}
  */
 export async function collectSemgrepFindings(projectDir, logger = null) {
+  // KJC-BUG-0122: a full `--config auto` scan must NEVER fire from the unit
+  // suite — on machines with the complete stack installed (the product
+  // default since v4.1.2) parallel vitest workers each launched a real
+  // whole-repo scan: load average 50, orphaned semgrep-core processes.
+  // E2E tests that genuinely want the real scan opt in explicitly.
+  if (process.env.VITEST && process.env.KJ_ALLOW_REAL_SCANS !== "1") {
+    return { available: false, reason: "real scans disabled under the test runner (set KJ_ALLOW_REAL_SCANS=1 to opt in)" };
+  }
   let stdout;
   try {
     const { stdout: out } = await execFileAsync(

package/src/commands/hu.js

@@ -8,6 +8,14 @@
 import { addHu, updateHuStatus } from "../plan/plan-hu-ops.js";
 import { generatePlanId } from "../plan/plan-id.js";
 import { savePlan, listPlans, loadPlan } from "../plan/plan-store.js";
+import { detectHostAgent } from "../utils/agent-detect.js";
+
+// KJC-TSK-0661 (Jorge's friction): every HU records WHO created it — the
+// board must never show work nobody can trace. Host agent env → that agent;
+// a human typing in a terminal → "human"; anything else headless → "agent".
+export function creatorLabel() {
+  return detectHostAgent() || (process.stdin.isTTY ? "human" : "agent");
+}
 
 export const HU_STATUSES = ["pending", "running", "done", "failed", "skipped"];
 const BACKLOG_NAME = "brain-backlog";
@@ -35,12 +43,22 @@ export async function huCommand({ config = null, action, args = [], flags = {} }
     for (const meta of plans) {
       const plan = await loadPlan(projectDir, meta.planId);
       for (const h of plan.hus || []) {
-        rows.push({ id: h.id, short_id: h.short_id, title: h.title, status: h.status, plan: plan.alias || plan.planId });
+        rows.push({
+          id: h.id, short_id: h.short_id, title: h.title, status: h.status,
+          plan: plan.alias || plan.planId,
+          // KJC-TSK-0661: provenance — where a card came from is part of
+          // the card. Older HUs predate the stamp: shown as "?".
+          created_by: h.created_by || null, created_at: h.createdAt || null,
+        });
       }
     }
     if (flags.json) { console.log(JSON.stringify(rows)); return rows; }
-    for (const r of rows) console.log(`${(r.short_id || r.id).padEnd(28)} ${r.status.padEnd(8)} ${r.title}`);
+    for (const r of rows) {
+      const origin = `${r.plan} · by ${r.created_by || "?"}${r.created_at ? ` · ${r.created_at.slice(0, 10)}` : ""}`;
+      console.log(`${(r.short_id || r.id).padEnd(28)} ${r.status.padEnd(8)} ${r.title}  [${origin}]`);
+    }
     if (rows.length === 0) console.log("no HUs yet — create one with: kj hu add \"<story>\"");
+    else console.log("→ work one: ask your agent, or kj run --plan <plan> · discard one: kj hu move <id> skipped");
     return rows;
   }
 
@@ -48,14 +66,28 @@ 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,
       acceptance_criteria: flags.criteria ? [flags.criteria] : [],
     });
+    hu.created_by = creatorLabel();
     await savePlan(projectDir, plan);
-    return emit({ id: hu.id, short_id: hu.short_id, status: hu.status },
-      `✓ HU created: ${hu.short_id || hu.id} (pending) — it shows up in \`kj board\``);
+    return emit({ id: hu.id, short_id: hu.short_id, status: hu.status, created_by: hu.created_by },
+      `✓ HU created: ${hu.short_id || hu.id} (pending, by ${hu.created_by}) — it shows up in \`kj board\``);
   }
 
   if (action === "move") {

package/src/commands/init.js

@@ -6,6 +6,7 @@ import { sonarUp, checkVmMaxMapCount } from "../sonar/manager.js";
 import { ollamaUp, waitForOllamaReady, normalizeOllamaConfig } from "../rag/ollama-manager.js";
 import { checkOllamaCapability, pullOllamaModel } from "../rag/ollama-capability.js";
 import { exists, ensureDir } from "../utils/fs.js";
+import { ensureContractBlockPresent } from "../review/gate-gitignore.js";
 import { getKarajanHome } from "../utils/paths.js";
 import { getTemplatesRoot } from "../utils/templates-root.js";
 import { detectAvailableAgents } from "../utils/agent-detect.js";
@@ -672,6 +673,7 @@ const GITIGNORE_ENTRIES = [
   { pattern: ".kj/", comment: "Karajan runtime (logs, worktrees)" },
   { pattern: ".agent/", comment: "Agent skills (OpenSkills)" },
   { pattern: ".scannerwork/", comment: "SonarQube scanner temp" },
+  { pattern: ".reviews/", comment: "Legacy review artifacts" },
 ];
 
 async function ensureGitignoreEntries(projectDir, logger) {
@@ -685,16 +687,22 @@ async function ensureGitignoreEntries(projectDir, logger) {
   if (!content) content = "";
 
   const missing = GITIGNORE_ENTRIES.filter(e => !content.includes(e.pattern));
-  if (missing.length === 0) return;
-
-  const block = [
-    "",
-    "# Karajan Code",
-    ...missing.map(e => e.pattern)
-  ].join("\n") + "\n";
-
-  await fs.appendFile(gitignorePath, block, "utf8");
-  logger.info(`Added to .gitignore: ${missing.map(e => e.pattern).join(", ")}`);
+  if (missing.length > 0) {
+    const block = [
+      "",
+      "# Karajan Code",
+      ...missing.map(e => e.pattern)
+    ].join("\n") + "\n";
+    await fs.appendFile(gitignorePath, block, "utf8");
+    logger.info(`Added to .gitignore: ${missing.map(e => e.pattern).join(", ")}`);
+  }
+
+  // KJC-BUG-0123 (issue #1268): the .karajan entries were missing entirely —
+  // and they must land as the CONTRACT BLOCK (`.karajan/*` + re-includes),
+  // never a bare `.karajan/` dir-exclude, or git cannot re-include the
+  // review-gate/hooks/adrs the whole team inherits (KJC-TSK-0646).
+  const res = await ensureContractBlockPresent(projectDir);
+  if (res.changed) logger.info("Added the .karajan contract block to .gitignore (verdicts stay local; gate/hooks/adrs tracked)");
 }
 
 /**

package/src/commands/plan/add-hu.js

@@ -15,6 +15,8 @@ export async function planAddHuCommand({ config, planId, title, type, deps, scop
     scope: scope || null,
     blocked_by: deps ? deps.split(",").map(d => d.trim()) : []
   });
+  const { creatorLabel } = await import("../hu.js");
+  hu.created_by = creatorLabel(); // KJC-TSK-0661: provenance stamp
 
   await savePlan(projectDir, plan);
   console.log(`Added: ${hu.id} — ${hu.title}`);

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

@@ -229,6 +229,9 @@ async function planGenerateImpl({ task, config, logger, json, context, runLog, f
       reviewer_model: models.reviewer_model,
       reviewer_provider: models.reviewer_provider,
     });
+    // KJC-TSK-0661: provenance stamp (addHu builds its object explicitly,
+    // so this goes on the returned reference, not in huData).
+    hu.created_by = "planner";
     if (symbolicId) symbolicToHuId.set(symbolicId, hu.id);
     const deps = typeof step === "object" && Array.isArray(step.dependencies) ? step.dependencies : [];
     stepDeps.push(deps);
@@ -367,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/orchestrator/config-init.js

@@ -5,6 +5,7 @@
 import fs from "node:fs/promises";
 import path from "node:path";
 import { computeBaseRef, setSnapshot } from "../review/diff-generator.js";
+import { ensureContractBlockPresent } from "../review/gate-gitignore.js";
 import { revParse } from "../utils/git.js";
 import { buildCoderPrompt } from "../prompts/coder.js";
 import { buildReviewerPrompt } from "../prompts/reviewer.js";
@@ -55,8 +56,11 @@ export async function autoInit(projectDir, logger) {
   }
 
   // Ensure .gitignore exists with universal entries only (stack-specific added after planner)
+  // KJC-BUG-0123: `.karajan/` is NOT in this list on purpose — a bare
+  // dir-exclude breaks the gate contract (git cannot re-include children);
+  // the canonical block is appended below from its single source.
   const gitignorePath = path.join(projectDir, ".gitignore");
-  const universalIgnores = [".env", "*.log", ".DS_Store", ".karajan/", ".reviews/"];
+  const universalIgnores = [".env", "*.log", ".DS_Store", ".reviews/"];
   try {
     let content = "";
     if (await exists(gitignorePath)) {
@@ -68,6 +72,7 @@ export async function autoInit(projectDir, logger) {
       await fs.appendFile(gitignorePath, append, "utf8");
       logger.info(`Created .gitignore with universal entries`);
     }
+    await ensureContractBlockPresent(projectDir);
   } catch (err) {
     logger.warn(`Failed to create .gitignore: ${err.message}`);
   }

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:
@@ -140,6 +162,7 @@ export function applyFixerPatch(plan, patch) {
       acceptance_tests: a.acceptance_tests,
       reuse: a.reuse || [],
     });
+    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 });
@@ -162,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/review/gate-gitignore.js

@@ -12,7 +12,10 @@
 import fs from "node:fs/promises";
 import path from "node:path";
 
-const CONTRACT_BLOCK = [
+// KJC-BUG-0123 (issue #1268): exported as the SINGLE source of truth — kj
+// init and the orchestrator's autoInit write this same block instead of a
+// bare `.karajan/` exclude (which git cannot re-include children of).
+export const CONTRACT_BLOCK = [
   ".karajan/*",
   "# …except the v4 environment contract, which the whole team inherits:",
   "!.karajan/review-gate",
@@ -25,6 +28,22 @@ const CONTRACT_BLOCK = [
   "!.karajan/adrs/",
 ];
 
+/**
+ * KJC-BUG-0123: append the canonical contract block to .gitignore when the
+ * file has no `.karajan` mention at all (fresh projects — `kj init` path).
+ * Files that already mention .karajan are left to ensureGateTrackable,
+ * which rewrites legacy root excludes without touching anything else.
+ */
+export async function ensureContractBlockPresent(projectDir) {
+  const file = path.join(projectDir, ".gitignore");
+  let text = "";
+  try { text = (await fs.readFile(file, "utf8")) || ""; } catch { /* no .gitignore yet */ }
+  if (text.includes(".karajan")) return { changed: false };
+  const sep = text && !text.endsWith("\n") ? "\n" : "";
+  await fs.writeFile(file, `${text}${sep}# Karajan environment (verdicts stay local; the contract is tracked)\n${CONTRACT_BLOCK.join("\n")}\n`);
+  return { changed: true };
+}
+
 export async function ensureGateTrackable(projectDir) {
   const file = path.join(projectDir, ".gitignore");
   let text;