karajan-code 4.1.6 → 4.1.7

package/package.json

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

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;
   }
 
@@ -53,9 +71,10 @@ export async function huCommand({ config = null, action, args = [], flags = {} }
       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/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);

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

@@ -140,6 +140,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 });

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;