karajan-code 4.34.0 → 4.35.0

package/package.json

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

package/src/agents/base-agent.js

@@ -34,6 +34,28 @@ export class BaseAgent {
     this.environment = environment;
   }
 
+  /**
+   * KJC-BUG-0217 (issue #1409) — los flags con los que kj invoca el CLI de un
+   * provider eran una constante del codigo, y hay versiones que rechazan la
+   * combinacion: kimi-code 0.27.0 responde "Cannot combine --prompt with
+   * --yolo" y dejaba `kj agent run` inutilizable, sin mas salida que parchear
+   * kj. Ahora el proyecto puede declararlos:
+   *
+   *   agents: { kimi: { task_args: [], review_args: [] } }
+   *
+   * Sin declaracion valen los de siempre. Una declaracion que no sea una lista
+   * de cadenas se ignora: la config no puede romper la invocacion.
+   *
+   * @param {"task"|"review"} kind
+   * @param {string[]} fallback
+   * @returns {string[]}
+   */
+  declaredArgs(kind, fallback) {
+    const declared = this.config?.agents?.[this.name]?.[`${kind}_args`];
+    if (!Array.isArray(declared) || declared.some((a) => typeof a !== "string")) return fallback;
+    return declared;
+  }
+
   /**
    * Run a shell command through the injected CommandRunner. Subclasses should
    * call this instead of importing runCommand directly so tests can swap in

package/src/agents/kimi-agent.js

@@ -1,6 +1,9 @@
 import { BaseAgent } from "./base-agent.js";
 import { resolveBin } from "./resolve-bin.js";
 
+/** El rechazo de kimi-code 0.27.0 a `-p` junto con `-y`, en su forma literal. */
+const REJECTS_COMBINATION = /cannot combine .* with /i;
+
 /**
  * Kimi Code (Moonshot, binary `kimi`) — KJC-TSK-0729 fase 2: the eighth
  * built-in agent and the free-tier reserve of the reviewer/solomon panel.
@@ -17,7 +20,7 @@ import { resolveBin } from "./resolve-bin.js";
 export class KimiAgent extends BaseAgent {
   async runTask(task) {
     // Coder mode IS an agentic run: file edits and shell need approval.
-    return this._exec(task, this.getRoleModel(task.role || "coder"), ["-y"]);
+    return this._exec(task, this.getRoleModel(task.role || "coder"), this.declaredArgs("task", ["-y"]));
   }
 
   async reviewTask(task) {
@@ -27,7 +30,7 @@ export class KimiAgent extends BaseAgent {
     return this._exec(
       { ...task, prompt: `Do NOT use any tools. Answer directly from this prompt only.\n\n${task.prompt}` },
       this.getRoleModel(task.role || "reviewer"),
-      [],
+      this.declaredArgs("review", []),
     );
   }
 
@@ -40,6 +43,12 @@ export class KimiAgent extends BaseAgent {
       timeout: task.timeoutMs,
       cwd: task.cwd,
     });
-    return { ok: res.exitCode === 0, output: res.stdout, error: res.stderr, exitCode: res.exitCode };
+    // KJC-BUG-0217 (issue #1409): el CLI puede rechazar la COMBINACION de flags
+    // (kimi-code 0.27.0: "Cannot combine --prompt with --yolo"). Ese error crudo
+    // no dice que hacer; el de kj si.
+    const error = REJECTS_COMBINATION.test(String(res.stderr || ""))
+      ? `${res.stderr}\n\nkimi rechaza la combinacion de flags con la que kj lo invoca. Declara los que acepta esta version: agents.kimi.task_args (una lista vacia deja el prompt solo, sin auto-aprobado).`
+      : res.stderr;
+    return { ok: res.exitCode === 0, output: res.stdout, error, exitCode: res.exitCode };
   }
 }

package/src/cli/register-meta.js

@@ -11,7 +11,7 @@ import { identityCommand } from "../commands/identity.js";
 import { policyCommand } from "../commands/policy.js";
 import { claimsCommand, claimsGateCommand } from "../commands/claims.js";
 import { stewardSweepCommand } from "../commands/steward.js";
-import { ragIndexCommand, ragQueryCommand, ragInstallHooksCommand, ragEvalCommand } from "../commands/rag.js";
+import { ragIndexCommand, ragQueryCommand, ragInstallHooksCommand, ragEvalCommand, ragCoversCommand } from "../commands/rag.js";
 import { qmdQueryCommand } from "../commands/qmd.js";
 import { ragMcpCommand } from "../commands/rag-mcp.js";
 import { watchStartCommand, watchStopCommand, watchStatusCommand } from "../commands/watch.js";
@@ -532,6 +532,16 @@ export function registerMeta(program, { pkgVersion }) {
         await ragIndexCommand({ config, logger, flags });
       });
     });
+  // KJC-BUG-0216: el gate rag-first no puede pedir lo imposible. Esto responde
+  // si el RAG PUEDE hablar de un fichero, y si no, por que.
+  rag.command("covers <file>")
+    .description("Whether the RAG can answer about a file: exit 0 when indexed, 1 with the reason it cannot (no adapter, skipped path, empty or stale index)")
+    .option("--json", "Emit the state as JSON")
+    .action(async (file, flags) => {
+      await withConfig(pkgVersion, "rag-covers", flags, async ({ config, logger }) => {
+        await ragCoversCommand({ file, config, logger, flags });
+      });
+    });
   rag.command("install-hooks")
     .description("Install the post-merge git hook so the RAG index auto-refreshes after pulls/merges (KJC-TSK-0455)")
     .option("--json", "Output the result as JSON")

package/src/commands/rag.js

@@ -5,6 +5,7 @@
 import { openVecStore, countChunks, projectSlug, getLastIndexedCommit, setLastIndexedCommit } from "../rag/vec-store.js";
 import { makeGovernedEmbedder } from "../rag/governed-embedder.js";
 import { indexProject, indexProjectDelta } from "../rag/indexer.js";
+import { fileIndexState } from "../rag/coverage.js";
 import { query } from "../rag/retriever.js";
 import { installPostMergeHook, maybeAutoUpdate } from "../rag/auto-update.js";
 import { indexLibrary, LIBRARY_PROJECT } from "../rag/library.js";
@@ -171,3 +172,23 @@ export async function ragEvalCommand({ config, logger, flags = {} }) {
     db.close();
   }
 }
+
+/**
+ * KJC-BUG-0216 (issue #1807) — el hecho comprobable que el gate rag-first
+ * necesita antes de exigir una consulta: PUEDE el RAG responder sobre este
+ * fichero. Exit 0 = si; exit 1 = no, y la razon (sin adapter, segmento
+ * excluido, indice vacio o por detras) va en la salida.
+ */
+export async function ragCoversCommand({ file, config, flags = {} }) {
+  const projectDir = config?.projectDir || process.cwd();
+  const db = openDb(config);
+  try {
+    const state = fileIndexState(projectDir, file, { db });
+    if (flags.json) process.stdout.write(`${JSON.stringify(state)}\n`);
+    else process.stdout.write(`${state.state}: ${state.reason}\n`);
+    if (!state.canAnswer) process.exitCode = 1;
+    return state;
+  } finally {
+    db.close();
+  }
+}

package/src/config/defaults.js

@@ -68,7 +68,10 @@ const DEFAULTS = {
   state_backend: "hu-board",
   // verify_cmd (KJC-TSK-0732): user adapter that checks a card ref against
   // the real tracker — prints {exists, live, status} JSON; {ref} substituted.
-  board: { name: null, verify_cmd: null },
+  // unverifiable (KJC-TSK-0878): que hacer cuando el adaptador no puede
+  // responder (sin red, sin credenciales, JSON invalido). "warn" degrada a
+  // branch-ref diciendolo; "block" se niega a aprobar lo que no ha comprobado.
+  board: { name: null, verify_cmd: null, unverifiable: "warn" },
   // Method gates (KJC-PCS-0068): rules climb from playbook text to
   // deterministic enforcement. card_first: "auto" = block with hu-board
   // (fully verifiable), warn with planning-game/external (presence only);
@@ -91,6 +94,11 @@ const DEFAULTS = {
   coder_rules: "./.karajan/coder-rules.md",
   base_branch: "main",
   coder_options: { model: null, auto_approve: true, fallback_coder: null },
+  // KJC-BUG-0217: los flags con los que kj invoca el CLI de cada provider son
+  // los que su version acepta, y eso cambia con el CLI. Aqui se declaran por
+  // agente cuando los de serie no valen: { kimi: { task_args: [] } } deja el
+  // prompt solo, sin auto-aprobado, para una version que rechaza la combinacion.
+  agents: {},
   reviewer_options: {
     output_format: "json",
     require_schema: true,
@@ -256,6 +264,10 @@ const DEFAULTS = {
       enabled: true,
       patterns: [],
       protected_files: [],
+      // KJC-BUG-0215: cauce declarado para el falso positivo de las reglas que
+      // acusan por el NOMBRE del identificador. Entradas `NAME` (todo el repo)
+      // o `path/to/file:NAME` (solo ese fichero, que es lo preferible).
+      non_secret_assignments: [],
       on_violation: "block"
     },
     perf: {

package/src/guards/output-guard.js

@@ -12,7 +12,7 @@ const DESTRUCTIVE_PATTERNS = [
 const CREDENTIAL_PATTERNS = [
   { id: "aws-key", pattern: /AKIA[0-9A-Z]{16}/, severity: "critical", message: "AWS access key exposed" },
   { id: "private-key", pattern: /-----BEGIN\s+(RSA\s+)?PRIVATE\s+KEY-----/, severity: "critical", message: "Private key exposed" },
-  { id: "generic-secret", pattern: /(password|secret|token|api_key|apikey)\s*[:=]\s*["'][^"']{8,}["']/i, severity: "critical", message: "Hardcoded secret detected. Use .env file + process.env instead" },
+  { id: "generic-secret", pattern: /(password|secret|token|api_key|apikey)\s*[:=]\s*["'][^"']{8,}["']/i, severity: "critical", message: "Hardcoded secret detected. Move it to the environment or a secrets manager" },
   { id: "github-token", pattern: /gh[pousr]_[A-Za-z0-9_]{36,}/, severity: "critical", message: "GitHub token exposed" },
   { id: "npm-token", pattern: /npm_[A-Za-z0-9]{36,}/, severity: "critical", message: "npm token exposed" },
   { id: "openai-key", pattern: /sk-[A-Za-z0-9]{20,}/, severity: "critical", message: "OpenAI API key exposed" },
@@ -24,7 +24,7 @@ const CREDENTIAL_PATTERNS = [
   { id: "slack-token", pattern: /xox[bpors]-[A-Za-z0-9-]{10,}/, severity: "critical", message: "Slack token exposed" },
   { id: "jwt-secret", pattern: /jwt[_-]?secret\s*[:=]\s*["'][^"']{8,}["']/i, severity: "critical", message: "JWT secret hardcoded. Use .env file" },
   { id: "database-url", pattern: /(mongodb|postgres|mysql|redis):\/\/[^"'\s]+:[^"'\s]+@/i, severity: "critical", message: "Database URL with credentials exposed. Use .env file" },
-  { id: "hardcoded-key-assignment", pattern: /(?:const|let|var)\s+\w*(?:key|secret|token|password)\w*\s*=\s*["'][A-Za-z0-9_-]{16,}["']/i, severity: "critical", message: "Hardcoded key in variable. Use process.env or .env file" },
+  { id: "hardcoded-key-assignment", pattern: /(?:const|let|var)\s+\w*(?:key|secret|token|password)\w*\s*=\s*["'][A-Za-z0-9_-]{16,}["']/i, severity: "critical", message: "Hardcoded key in an assignment. Move it to the environment or a secrets manager" },
 ];
 
 // Default protected files (block if these appear in added/modified lines)
@@ -115,6 +115,49 @@ export function checkProtectedFiles(diff, protectedFiles) {
   return violations;
 }
 
+/**
+ * KJC-BUG-0215 (issue #1733): estas dos reglas acusan por el NOMBRE del
+ * identificador, no por la forma del valor, asi que un prefijo de cache llamado
+ * EXPERIMENTS_HANDOFF_TOKENS_NAMESPACE bloqueo una ejecucion entera con
+ * severidad critica y sin salida. Las demas reglas miran el valor (AKIA…,
+ * sk_live_…) y esas aciertan.
+ *
+ * El arreglo NO es adivinar: la review tumbo tres heuristicas seguidas y con
+ * razon, porque `const dbPassword = "db-password"` tambien tiene pinta inocente
+ * y es una credencial. Lo que faltaba era CAUCE: que el proyecto pueda declarar
+ * la excepcion en su configuracion versionada, donde se revisa en la PR como
+ * cualquier otra linea, y que el guard diga como hacerlo cuando bloquea.
+ */
+const NAME_BASED_RULES = new Set(["hardcoded-key-assignment", "generic-secret"]);
+
+const HOW_TO_DECLARE = "If it is not a secret, declare it in guards.output.non_secret_assignments as NAME or path/to/file:NAME";
+
+/** El identificador al que se asigna, cuando la linea deja leerlo. */
+const assignedName = (content) => /([A-Za-z_$][\w$]*)\s*[:=]\s*["']/.exec(content)?.[1] ?? null;
+
+/** Una entrada declarada se lee como `NAME` o `path/to/file:NAME`. */
+const splitEntry = (entry) => {
+  const cut = entry.lastIndexOf(":");
+  return cut === -1 ? { path: null, name: entry } : { path: entry.slice(0, cut), name: entry.slice(cut + 1) };
+};
+
+/**
+ * Excepcion DECLARADA, no inferida: el proyecto afirma por escrito que esta
+ * asignacion no guarda un secreto. Sin `file` la declaracion vale para todo el
+ * repositorio; con el, solo para ese fichero, que es lo estrecho y preferible.
+ */
+export function declaredNonSecret(configGuards, file, content) {
+  const declared = configGuards?.output?.non_secret_assignments;
+  if (!Array.isArray(declared) || declared.length === 0) return false;
+  const name = assignedName(content);
+  if (!name) return false;
+  return declared.some(entry => {
+    if (typeof entry !== "string") return false;
+    const target = splitEntry(entry.trim());
+    return target.name === name && (target.path === null || target.path === file);
+  });
+}
+
 /**
  * Scan a diff for pattern violations.
  * Returns { pass: boolean, violations: Array<{id, severity, file, line, message, matchedContent}> }
@@ -133,8 +176,17 @@ export function scanDiff(diff, config = {}) {
   // Check patterns against added lines
   for (const { file, line, content } of addedLines) {
     for (const { id, pattern, severity, message } of patterns) {
-      if (pattern.test(content)) {
-        violations.push({ id, severity, file, line, message, matchedContent: content.trim().slice(0, 200) });
+      if (!pattern.test(content)) continue;
+      const matchedContent = content.trim().slice(0, 200);
+      // KJC-BUG-0215: una regla que acusa por el nombre necesita un cauce
+      // declarado para el falso positivo, y decirlo cuando bloquea.
+      if (!NAME_BASED_RULES.has(id)) {
+        violations.push({ id, severity, file, line, message, matchedContent });
+      } else if (declaredNonSecret(configGuards, file, content)) {
+        violations.push({ id, severity: "warning", file, line, matchedContent,
+          message: `${message}. Declared as non-secret in guards.output.non_secret_assignments` });
+      } else {
+        violations.push({ id, severity, file, line, matchedContent, message: `${message}. ${HOW_TO_DECLARE}` });
       }
     }
   }

package/src/harden/sentinel-hooks.js

@@ -971,8 +971,22 @@ process.stdin.on("end", () => {
             // Recorded ONCE per session: the escape is a conscious exception, not a per-edit tax.
             if (!(rs.escapes || []).includes("KJ_ALLOW_NO_RAG")) recordEscape(sid, "KJ_ALLOW_NO_RAG", tool);
           } else {
-            console.error("karajan sentinel: rag-first — el RAG no ha respondido sobre " + rel + " en esta sesion; consulta antes de tocarlo: kj_rag_query / kj rag query <que hace " + rel + " y donde mas vive ese concepto>. (KJ_ALLOW_NO_RAG=1 = excepcion consciente, queda registrada)" + doc("rag-first"));
-            process.exit(2);
+            // KJC-BUG-0216 (issue #1807): un .astro, un .php o cualquier fichero
+            // sin adapter NO puede estar en el indice, asi que exigir una
+            // respuesta del RAG sobre el es pedir lo imposible, y empujaba a
+            // dejar KJ_ALLOW_NO_RAG puesta para siempre. La exencion es SOLO
+            // esa: un indice vacio o por detras si tiene arreglo (kj rag index)
+            // y sigue bloqueando, porque si no el gate desapareceria en
+            // cualquier proyecto sin indexar. Nada legible = se bloquea.
+            const cov = spawnSync("kj", ["rag", "covers", rel, "--json"], { cwd: ROOT, encoding: "utf8" });
+            let blind = null;
+            try { const c = JSON.parse(String(cov.stdout || "")); if (c.state === "not-indexable") blind = c.reason; } catch { blind = null; }
+            if (blind) {
+              console.error("karajan sentinel: rag-first — " + blind + " — no se te exige consultar lo que el indice no puede tener; el gate lo anota y sigue" + doc("rag-first"));
+            } else {
+              console.error("karajan sentinel: rag-first — el RAG no ha respondido sobre " + rel + " en esta sesion; consulta antes de tocarlo: kj_rag_query / kj rag query <que hace " + rel + " y donde mas vive ese concepto>. (KJ_ALLOW_NO_RAG=1 = excepcion consciente, queda registrada)" + doc("rag-first"));
+              process.exit(2);
+            }
           }
         }
       }

package/src/orchestrator/config-init.js

@@ -5,7 +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 { ensureContractBlockPresent, excludeLocalArtifacts } from "../review/gate-gitignore.js";
 import { revParse } from "../utils/git.js";
 import { buildCoderPrompt } from "../prompts/coder.js";
 import { buildReviewerPrompt } from "../prompts/reviewer.js";
@@ -55,26 +55,18 @@ 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", ".reviews/"];
+  // KJC-BUG-0213 (issue #1734): el .gitignore es del equipo y viaja con el repo.
+  // Ahi solo entra el contrato v4, que el equipo entero hereda; los artefactos
+  // de una ejecucion son nuestros y locales, asi que van a .git/info/exclude.
+  // Lo que kj metia antes (.env, *.log, .DS_Store) era opinion sobre un
+  // proyecto ajeno, y aparecia en el diff de otra persona sin haberlo pedido.
   try {
-    let content = "";
-    if (await exists(gitignorePath)) {
-      content = await fs.readFile(gitignorePath, "utf8");
-    }
-    const missing = universalIgnores.filter(entry => !content.includes(entry));
-    if (missing.length > 0) {
-      const append = (content && !content.endsWith("\n") ? "\n" : "") + missing.join("\n") + "\n";
-      await fs.appendFile(gitignorePath, append, "utf8");
-      logger.info(`Created .gitignore with universal entries`);
-    }
-    await ensureContractBlockPresent(projectDir);
+    const contract = await ensureContractBlockPresent(projectDir);
+    if (contract.changed) logger.info("El contrato v4 se ha anadido a .gitignore (lo hereda quien clone)");
+    const local = await excludeLocalArtifacts(projectDir);
+    if (local.changed) logger.info(`Artefactos de kj excluidos en .git/info/exclude: ${local.added.join(", ")}`);
   } catch (err) {
-    logger.warn(`Failed to create .gitignore: ${err.message}`);
+    logger.warn(`Failed to prepare .gitignore: ${err.message}`);
   }
 
   const karajanDir = path.join(projectDir, ".karajan");
@@ -125,89 +117,11 @@ export async function autoInit(projectDir, logger) {
   }
 }
 
-// Stack-specific .gitignore patterns keyed by language/framework
-const STACK_GITIGNORE = {
-  javascript: ["node_modules/", "dist/", "build/", "coverage/", ".cache/", "*.tsbuildinfo"],
-  typescript: ["node_modules/", "dist/", "build/", "coverage/", ".cache/", "*.tsbuildinfo"],
-  python: ["__pycache__/", "*.pyc", ".venv/", "venv/", "*.egg-info/", ".pytest_cache/", "htmlcov/", ".mypy_cache/"],
-  java: ["target/", "*.class", "*.jar", "*.war", ".gradle/", "build/", ".settings/", ".classpath", ".project"],
-  kotlin: ["target/", "*.class", "build/", ".gradle/", ".kotlin/"],
-  go: ["bin/", "*.exe", "vendor/"],
-  rust: ["target/", "Cargo.lock"],
-  ruby: ["vendor/bundle/", ".bundle/", "coverage/", "tmp/"],
-  php: ["vendor/", ".phpunit.result.cache", "storage/logs/"],
-  csharp: ["bin/", "obj/", "*.suo", "*.user", "packages/", ".vs/"],
-  swift: [".build/", "Packages/", "*.xcodeproj/", "DerivedData/"],
-  dart: [".dart_tool/", "build/", ".packages"],
-};
-
-/**
- * Update .gitignore with stack-specific entries after planner/architect decides the stack.
- * Detects stack from: triage taskType, architect output, planner output, or task keywords.
- */
-export async function updateGitignoreForStack(projectDir, { stageResults, task, logger }) {
-  const gitignorePath = path.join(projectDir, ".gitignore");
-  const detected = new Set();
-
-  // From architect — if it chose layers/patterns, it may hint at the language
-  const arch = stageResults?.architect?.architecture;
-  if (arch) {
-    const archText = JSON.stringify(arch).toLowerCase();
-    for (const lang of Object.keys(STACK_GITIGNORE)) {
-      if (archText.includes(lang)) detected.add(lang);
-    }
-  }
-
-  // From planner — scan plan text for language keywords
-  const planText = (stageResults?.planner?.plan || "").toLowerCase();
-  // From task description
-  const taskText = (task || "").toLowerCase();
-  const combined = `${planText} ${taskText}`;
-
-  const langKeywords = {
-    javascript: ["node", "npm", "express", "react", "vue", "next", "vite", "vitest", "jest", "pnpm", "yarn", "javascript", "js"],
-    typescript: ["typescript", "tsx", "tsc"],
-    python: ["python", "django", "flask", "fastapi", "pip", "pytest", "poetry"],
-    java: ["java", "spring", "maven", "gradle", "junit"],
-    kotlin: ["kotlin", "ktor"],
-    go: ["golang", "go mod", "gin", "fiber"],
-    rust: ["rust", "cargo", "tokio"],
-    ruby: ["ruby", "rails", "gem", "bundler", "rspec"],
-    php: ["php", "laravel", "composer", "symfony"],
-    csharp: ["c#", "csharp", "dotnet", ".net", "aspnet"],
-    swift: ["swift", "swiftui", "vapor"],
-    dart: ["dart", "flutter"],
-  };
-
-  for (const [lang, keywords] of Object.entries(langKeywords)) {
-    if (keywords.some(kw => combined.includes(kw))) detected.add(lang);
-  }
-
-  if (detected.size === 0) return;
-
-  // Collect all entries for detected stacks
-  const entries = [];
-  for (const lang of detected) {
-    entries.push(...(STACK_GITIGNORE[lang] || []));
-  }
-  const unique = [...new Set(entries)];
-
-  try {
-    let content = "";
-    if (await exists(gitignorePath)) {
-      content = await fs.readFile(gitignorePath, "utf8");
-    }
-    const missing = unique.filter(entry => !content.includes(entry));
-    if (missing.length > 0) {
-      const header = `\n# ${[...detected].join(" + ")} project\n`;
-      const append = header + missing.join("\n") + "\n";
-      await fs.appendFile(gitignorePath, append, "utf8");
-      logger.info(`Updated .gitignore for ${[...detected].join(" + ")}: ${missing.join(", ")}`);
-    }
-  } catch (err) {
-    logger.warn(`Failed to update .gitignore for stack: ${err.message}`);
-  }
-}
+// KJC-BUG-0213 (issue #1734): aqui vivia updateGitignoreForStack, que deducia
+// el stack buscando palabras como "ts" o "js" en el texto del plan y de la
+// tarea. Cualquier frase las contiene, asi que un proyecto Laravel acabo con
+// reglas de TypeScript en SU .gitignore. Un acierto por casualidad no vale para
+// escribir en un fichero que no es nuestro: la funcion se retira entera.
 
 /**
  * Load product context from well-known file locations.

package/src/orchestrator/drivers/iteration-phases/guards.js

@@ -24,10 +24,17 @@ export async function runGuardStages({ config, logger, emitter, eventBase, sessi
 
   if (!outputEnabled && !perfEnabled) return { action: "ok" };
 
+  // KJC-BUG-0214 (issue #1733): los guards juzgan LO QUE HA HECHO ESTE RUN, no
+  // la rama entera. Con el merge-base contra la base, cualquier linea anadida
+  // en cualquier momento de la rama contaba como recien escrita, y una
+  // ejecucion se bloqueo por codigo preexistente que el coder no toco. La
+  // sesion ya guarda HEAD al arrancar precisamente para esto.
   const baseBranch = config.base_branch || "main";
+  const runStart = session?.head_at_start || session?.session_start_sha || null;
   let diff;
   try {
-    const baseRef = await computeBaseRef({ baseBranch });
+    const baseRef = runStart || await computeBaseRef({ baseBranch });
+    if (!runStart) logger.warn("Guards: sin punto de arranque del run, se juzga la rama entera contra la base");
     diff = await generateDiff({ baseRef, projectDir: config?.projectDir || null });
   } catch {
     logger.warn("Guards: could not generate diff, skipping");

package/src/orchestrator/drivers/pre-loop.js

@@ -57,7 +57,7 @@ import { maybeGenerateAutoHuBatch } from "./pre-loop-phases/auto-hu-batch.js";
 
 import {
   applyTriageOverrides, applyAutoSimplify, applyFlagOverrides,
-  resolvePipelinePolicies, updateGitignoreForStack,
+  resolvePipelinePolicies,
 } from "../config-init.js";
 import { tryCiComment } from "../ci-integration.js";
 import { getIntegration } from "../integrations.js";
@@ -350,7 +350,6 @@ export async function runPreLoopStages({ config, logger, emitter, eventBase, ses
 
   // --- Update .gitignore with stack-specific entries based on planner/architect output ---
   const projectDir = updatedConfig.projectDir || process.cwd();
-  await updateGitignoreForStack(projectDir, { stageResults, task, logger });
 
   // --- Auto-HU: when triage recommended decomposition and no manual huFile, generate HU batch ---
   await maybeGenerateAutoHuBatch({

package/src/rag/coverage.js

@@ -8,7 +8,7 @@
  * matchers are the single truth, here and in the indexer.
  */
 import { execa } from "execa";
-import { isAbsolute, relative } from "node:path";
+import { extname, isAbsolute, normalize, relative } from "node:path";
 import { detectAdaptersForProject, buildMatchers } from "../lang/registry.js";
 import { getLastIndexedCommit, projectSlug } from "./vec-store.js";
 
@@ -46,3 +46,34 @@ export async function ragIndexCoverage(projectDir, { db }) {
 
   return { project, total: sources.length, indexed: sources.length - missing.length, missing, stale, lastIndexedCommit, absent: indexed.size === 0 };
 }
+
+/**
+ * KJC-BUG-0216 (issue #1807) — POR QUE el RAG no puede responder sobre un
+ * fichero. El gate rag-first exigia una respuesta sobre cualquier fichero
+ * tocado, y para un .astro (o .php, o cualquier lenguaje sin adapter) eso es
+ * imposible: el indexador nunca lo toma. La unica salida era KJ_ALLOW_NO_RAG
+ * puesta por costumbre en todos los comandos, y con ella puesta el gate deja de
+ * informar y borra la diferencia entre "no pude consultar" y "no quise".
+ *
+ * `canAnswer` es la respuesta que el gate necesita: solo cuando es true tiene
+ * sentido exigir que el RAG haya hablado de ese fichero.
+ *
+ * @returns {{state: "indexed"|"stale"|"not-indexable"|"index-empty", rel: string, canAnswer: boolean, reason: string}}
+ */
+export function fileIndexState(projectDir, file, { db }) {
+  const project = projectSlug(projectDir);
+  // `./src/a.js` y `src/a.js` son el mismo fichero: sin normalizar, el segundo
+  // salia "stale" estando indexado (catch de la review).
+  const rel = normalize(isAbsolute(file) ? relative(projectDir, file) : file);
+  const matchers = buildMatchers(detectAdaptersForProject(projectDir));
+  const rows = db.prepare("SELECT DISTINCT source FROM chunks WHERE project_slug = ?").all(project);
+  const indexed = new Set(rows.map((r) => normalize(isAbsolute(r.source) ? relative(projectDir, r.source) : r.source)));
+
+  if (indexed.has(rel)) return { state: "indexed", rel, canAnswer: true, reason: `the index holds chunks for ${rel}` };
+  if (indexed.size === 0) return { state: "index-empty", rel, canAnswer: false, reason: `nothing of this project is indexed yet: kj rag index` };
+  if (matchers.shouldSkip(rel)) return { state: "not-indexable", rel, canAnswer: false, reason: `${rel} lives under a path the indexer always skips` };
+  if (!matchers.isCodeFile(rel) && extname(rel).toLowerCase() !== ".md") {
+    return { state: "not-indexable", rel, canAnswer: false, reason: `no language adapter covers ${extname(rel) || "a file with no extension"}, so the indexer never takes ${rel}` };
+  }
+  return { state: "stale", rel, canAnswer: false, reason: `${rel} is indexable but absent from the index: kj rag index --since auto` };
+}

package/src/review/card-first.js

@@ -93,6 +93,18 @@ export async function checkCardFirst({ config = {}, projectDir = process.cwd(),
         ? { ok: false, mode: "block", reason, level: v.level }
         : { ok: true, mode: "warn", reason, level: v.level };
     }
+    // KJC-TSK-0878 (issue #1371): "no he podido verificar" y "he verificado y
+    // esta mal" no son lo mismo, y ambas pueden merecer una parada. El proyecto
+    // decide si la primera para, y el mensaje dice cual de las dos es: un gate
+    // que aprueba lo que no ha comprobado da una confianza que no ha ganado.
+    // Sin adaptador declarado no hay nada que bloquear: la opcion no castiga a
+    // quien aun no tiene verify_cmd.
+    if (v.verified === null && config.board?.unverifiable === "block" && config.board?.verify_cmd) {
+      return {
+        ok: false, mode: "block", level: v.level,
+        reason: `branch references ${ref} but the card could not be verified against ${boardName} — ${v.note} (board.unverifiable: block refuses to approve a check kj did not make)`,
+      };
+    }
     return { ok: true, mode: "pass", ref, level: v.level, ...(v.note ? { note: v.note } : {}) };
   }
   const reason = `no card reference in branch "${branch}" — card-first on ${boardName}: create the card there and name the branch after it (e.g. feat/ABC-123-summary)`;

package/src/review/gate-gitignore.js

@@ -12,6 +12,8 @@
 import fs from "node:fs/promises";
 import path from "node:path";
 
+import { runCommand } from "../utils/process.js";
+
 // 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).
@@ -48,6 +50,37 @@ export async function ensureContractBlockPresent(projectDir) {
   return { changed: true };
 }
 
+/**
+ * KJC-BUG-0213 (issue #1734): lo que kj deja en el repo durante una ejecucion
+ * es suyo y es local, asi que se excluye donde no molesta a nadie:
+ * `.git/info/exclude` no viaja con el repo ni aparece en el diff de otro.
+ * La ruta se pregunta a git para que funcione tambien en un worktree, donde
+ * `.git` es un fichero y no un directorio.
+ */
+const LOCAL_ARTIFACTS = [".reviews/", ".kj/", ".kj-ready.json"];
+
+export async function excludeLocalArtifacts(projectDir, run = runCommand) {
+  let file = path.join(projectDir, ".git", "info", "exclude");
+  try {
+    const res = await run("git", ["-C", projectDir, "rev-parse", "--git-path", "info/exclude"]);
+    const out = res?.stdout?.trim();
+    if (res?.exitCode === 0 && out) file = path.isAbsolute(out) ? out : path.join(projectDir, out);
+  } catch { /* sin git utilizable: se intenta la ruta por defecto */ }
+  let text = "";
+  try { text = (await fs.readFile(file, "utf8")) || ""; } catch { /* aun no existe */ }
+  const lines = new Set(text.split("\n").map((l) => l.trim()));
+  const missing = LOCAL_ARTIFACTS.filter((a) => !lines.has(a));
+  if (missing.length === 0) return { changed: false, added: [] };
+  try {
+    await fs.mkdir(path.dirname(file), { recursive: true });
+    const sep = text && !text.endsWith("\n") ? "\n" : "";
+    await fs.appendFile(file, `${sep}# Karajan run artifacts (local only, never shared)\n${missing.join("\n")}\n`, "utf8");
+    return { changed: true, added: missing };
+  } catch {
+    return { changed: false, added: [] };
+  }
+}
+
 export async function ensureGateTrackable(projectDir) {
   const file = path.join(projectDir, ".gitignore");
   let text;