karajan-code 4.34.0 → 4.35.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "karajan-code",
-  "version": "4.34.0",
+  "version": "4.35.1",
   "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/audit/harness-scorecard.js

@@ -40,9 +40,16 @@ export function hintForReason(reason, image) {
   }
 }
 
+/**
+ * KJC-BUG-0228 (issue #1840) — OPT-IN. La imagen por defecto es de un tercero y
+ * dejo de existir en el registro publico, asi que el paso venia activo, fallaba
+ * con "pull access denied" y se saltaba en cada `kj audit`. kj no puede depender
+ * por defecto de algo que otro puede borrar: quien quiera el scorecard lo pide,
+ * y quien tenga su propia imagen la declara en `audit.harness.image`.
+ */
 export function normalizeHarnessConfig(h = {}) {
   return {
-    enabled: h.enabled !== false,
+    enabled: h?.enabled === true,
     image: h.image || D.image,
     pullTimeoutMs: pos(h.pull_timeout_ms, D.pullTimeoutMs),
     assessTimeoutMs: pos(h.assess_timeout_ms, D.assessTimeoutMs),

package/src/audit/harness-section.js

@@ -20,7 +20,12 @@ const ts = () => new Date().toISOString().replaceAll(/[:.]/g, "-");
 
 export async function runHarnessSection({ projectDir, harnessConfig = null, runAssess = runHarnessAssess } = {}) {
   const cfg = normalizeHarnessConfig(harnessConfig || {});
-  if (!cfg.enabled) return { ok: true, skipped: true, reason: "disabled" };
+  // KJC-BUG-0228: desactivado por defecto, y DICHO. Un paso que desaparece en
+  // silencio del informe se lee como un paso aprobado.
+  if (!cfg.enabled) {
+    const asked = harnessConfig?.enabled === false;
+    return { ok: true, skipped: true, reason: asked ? "disabled" : "opt-in" };
+  }
   const res = await runAssess(projectDir, cfg);
   if (!res.ok) return { ok: false, error: res.error, reason: res.reason, hint: res.hint, image: cfg.image };
   const outDir = path.join(projectDir, ".karajan", "audit-runs", ts());
@@ -38,7 +43,13 @@ export async function runHarnessSection({ projectDir, harnessConfig = null, runA
 }
 
 export function formatHarnessSection(summary) {
-  if (!summary || summary.skipped) return "";
+  if (!summary) return "";
+  // KJC-BUG-0228: cuando no corre porque nadie lo pidio, se dice como pedirlo.
+  // Callarlo dejaba un informe que parecia completo sin serlo.
+  if (summary.reason === "opt-in") {
+    return "## Harness Scorecard\n\n_not run: it is opt-in (`audit.harness.enabled: true`), and it needs a scorecard image you can pull — declare yours in `audit.harness.image`._\n";
+  }
+  if (summary.skipped) return "";
   if (!summary.ok) {
     const reason = summary.reason ? ` (${summary.reason})` : "";
     const hint = summary.hint ? `\n\n${summary.hint}\n` : "";

package/src/checks/rag-coverage.js

@@ -41,7 +41,10 @@ export function createRagCoverageCheck({ openStore = (dim) => openVecStore({ dim
           const sample = gaps.slice(0, 3).join(", ") + (gaps.length > 3 ? ", …" : "");
           return { ok: false, severity: "fail", detail: `${c.missing.length} source(s) outside the RAG index, ${c.stale.length} stale (${sample}) — ${fix}` };
         }
-        return { ok: true, severity: "info", detail: `${c.indexed}/${c.total} sources indexed at ${c.lastIndexedCommit.slice(0, 9)}` };
+        // KJC-BUG-0221: lo que kj genera no se exige indexado, pero se dice —
+        // una exencion que no se ve es indistinguible de un gate que dejo de mirar.
+        const generated = c.generated?.length ? `, ${c.generated.length} generated by kj (not required)` : "";
+        return { ok: true, severity: "info", detail: `${c.indexed}/${c.total} sources indexed at ${c.lastIndexedCommit.slice(0, 9)}${generated}` };
       } finally {
         db.close();
       }

package/src/checks/runner.js

@@ -92,8 +92,14 @@ export async function runChecks(checks, ctx, options = {}) {
     entries.map(async (entry) => {
       if (entry.status === STATUS.SKIPPED) return;
       const start = Date.now();
+      // Per-check override: checks that spawn slow tools (e.g. `npx <pkg>` cold
+      // start) declare detectTimeoutMs so the blanket pipeline timeout doesn't
+      // kill them. Falls back to the pipeline-wide timeoutMs.
+      const detectTimeoutMs = Number.isFinite(entry.check.detectTimeoutMs)
+        ? entry.check.detectTimeoutMs
+        : timeoutMs;
       try {
-        const result = await withTimeout(entry.check.detect({ config, signal }), timeoutMs, entry.check.name);
+        const result = await withTimeout(entry.check.detect({ config, signal }), detectTimeoutMs, entry.check.name);
         entry.detectResult = result;
         entry.runMs = Date.now() - start;
         entry.status = resolveStatusFromDetect(entry.check, result);
@@ -112,9 +118,21 @@ export async function runChecks(checks, ctx, options = {}) {
       } catch (err) {
         entry.runMs = Date.now() - start;
         if (err instanceof TimeoutError) {
-          entry.detectResult = { ok: false, severity: "warn", detail: `Timeout after ${timeoutMs}ms` };
-          entry.status = STATUS.TIMEOUT;
-          entry.detail = entry.detectResult.detail;
+          entry.detectResult = { ok: false, severity: "warn", detail: `Timeout after ${detectTimeoutMs}ms` };
+          // A timeout on a degradable (optional) check must not block the
+          // pipeline: degrade to WARN and disable its feature flags, same as
+          // a regular failure (KJC-BUG-0049 semantics).
+          if (entry.check.degradable) {
+            for (const dotPath of entry.check.degradable.disables || []) {
+              setDotPath(overrides, dotPath, false);
+            }
+            entry.status = STATUS.WARN;
+            entry.detail = `${entry.detectResult.detail} → ${entry.check.degradable.warn}`;
+            entry.degraded = true;
+          } else {
+            entry.status = STATUS.TIMEOUT;
+            entry.detail = entry.detectResult.detail;
+          }
         } else {
           entry.detectResult = { ok: false, severity: "fail", detail: `Detection error: ${err.message}` };
           entry.status = STATUS.FAIL;
@@ -172,7 +190,11 @@ export async function runChecks(checks, ctx, options = {}) {
       entries.filter((e) => e.remediated).map(async (entry) => {
         const start = Date.now();
         try {
-          const result = await withTimeout(entry.check.detect({ config: verifyConfig, signal }), timeoutMs, `${entry.check.name}:reverify`);
+          const result = await withTimeout(
+            entry.check.detect({ config: verifyConfig, signal }),
+            Number.isFinite(entry.check.detectTimeoutMs) ? entry.check.detectTimeoutMs : timeoutMs,
+            `${entry.check.name}:reverify`
+          );
           entry.runMs += Date.now() - start;
           if (!result.ok) {
             entry.status = STATUS.FAIL;

package/src/checks/skills.js

@@ -23,6 +23,16 @@ export function createOpenSkillsCheck() {
     strategy: STRATEGY.PROMPT,
     applies: skillsEnabled,
     describe: "Install OpenSkills globally: npm install -g openskills",
+    // Detection shells out to `npx openskills --version`; a cold npx cache
+    // downloads the package first (~8s observed), well above the pipeline's
+    // 3s blanket timeout. Must exceed openskills-client's internal 15s timeout.
+    detectTimeoutMs: 20_000,
+    // Optional feature: even if detection times out, degrade instead of
+    // blocking the whole preflight (skill injection is skipped for the run).
+    degradable: {
+      disables: ["skills.enabled"],
+      warn: "skill auto-install disabled for this run",
+    },
     async detect() {
       const available = await isOpenSkillsAvailable();
       if (available) {

package/src/checks/types.js

@@ -59,7 +59,11 @@
  * @property {DegradableSpec} [degradable]       - KJC-BUG-0049: si está definido y el check falla, en lugar de abortar
  *                                                  el preflight, se desactivan los flags listados en `disables` y se emite
  *                                                  WARN con `warn`. Útil para features opcionales (auto_pr, auto_push,
- *                                                  sonar advisory, etc.) que no son blockers absolutos.
+ *                                                  sonar advisory, etc.) que no son blockers absolutos. También aplica
+ *                                                  cuando el detect agota su timeout (timeout → WARN, no TIMEOUT).
+ * @property {number} [detectTimeoutMs]          - per-check detect timeout override. Use for checks that spawn slow
+ *                                                  tools (e.g. `npx <pkg>` cold start) where the pipeline-wide
+ *                                                  timeoutMs would kill an otherwise healthy detect.
  */
 
 /**

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/commands/review-gate.js

@@ -386,8 +386,8 @@ export async function reviewGateCommand({ config, logger = null, flags = {} }) {
       console.log(`⚠ rag [${RAG_RULE_ID}]: the pipeline verdict carries no session ledger — the headless pipeline does not consult the RAG yet; sealed as a warn`);
       if (!warnIds.includes(RAG_RULE_ID)) warnIds.push(RAG_RULE_ID);
     } else if (res.ok) {
-      const { harness, verified, mismatched } = readRagLedger(projectDir);
-      const rreq = checkRagVerdict({ config, stagedFiles: changedFiles, rag: res.verdict.rag, harness, verified, mismatched, standingExceptions: std.standing });
+      const { harness, verified, mismatched, drift } = readRagLedger(projectDir);
+      const rreq = checkRagVerdict({ config, stagedFiles: changedFiles, rag: res.verdict.rag, harness, verified, mismatched, drift, standingExceptions: std.standing });
       if (!rreq.ok) res = { ok: false, verdict: res.verdict, reason: rreq.reason };
       else if (rreq.mode === "granted" && rreq.grant) console.log(formatRagGrant(rreq.grant));
     }

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/config-templates.js

@@ -118,6 +118,17 @@ export const GO_CONFIGS = [{ file: ".golangci.yml", blockId: "golangci", style:
 export const PHPSTAN_BODY = ["parameters:", "  level: 6", "  paths:", "    - src", "    - tests"].join("\n");
 export const PHP_CONFIGS = [{ file: "phpstan.neon", blockId: "phpstan", style: "hash", body: PHPSTAN_BODY }];
 
+
+/**
+ * KJC-BUG-0221 — los nombres que kj ESCRIBE en el proyecto. Lo consume la
+ * cobertura del RAG para no denunciar como drift un fichero que kj acaba de
+ * generar. Se deriva de las tablas de arriba: anadir un config aqui no obliga
+ * a acordarse de una segunda lista en otro modulo.
+ */
+export const GENERATED_CONFIG_FILES = new Set(
+  [...UNIVERSAL_CONFIGS, ...JS_CONFIGS, ...PY_CONFIGS, ...GO_CONFIGS, ...PHP_CONFIGS].map((c) => c.file),
+);
+
 /** Lint/format configs by detected language. Unknown ⇒ universal only. */
 export const CONFIGS_BY_LANGUAGE = {
   javascript: JS_CONFIGS,

package/src/harden/harness-hooks.js

@@ -9,6 +9,7 @@
  * supports tool hooks.
  */
 
+import { execFileSync } from "node:child_process";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 
@@ -18,7 +19,11 @@ const SCRIPT_BODY = `#!/usr/bin/env node
 // so a gate bug never bricks the session.
 import console from "node:console";
 import process from "node:process";
-import { existsSync } from "node:fs";
+import { existsSync, realpathSync } from "node:fs";
+import { dirname, join, relative, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+// El guard vive en <repo>/.karajan/harness/, asi que el arbol es dos arriba.
+const ROOT = join(dirname(fileURLToPath(import.meta.url)), "..", "..");
 let raw = "";
 process.stdin.on("data", (d) => { raw += d; });
 process.stdin.on("end", () => {
@@ -30,10 +35,75 @@ process.stdin.on("end", () => {
         process.exit(2);
       }
     }
-    if (tool === "Bash" && process.env.KJ_ALLOW_REWRITE !== "1") {
+    if (tool === "Bash") {
       const cmd = String(input.command || "");
+      // KJC-BUG-0227: el escape tambien viaja en el PROPIO comando, como en el
+      // resto de guardias. Mirando solo process.env el agente no tenia salida:
+      // un export dentro del comando jamas llega a este proceso.
+      // Solo cuentan las asignaciones DEL PRINCIPIO, que son las que el shell
+      // aplica al comando. Buscarla en cualquier parte del texto dejaba pasar
+      // un "echo KJ_ALLOW_REWRITE=1; python3 ..." (catch de la review).
+      const toks = cmd.trim().split(/\\s+/);
+      let i = 0;
+      let named = false;
+      while (i < toks.length && /^[A-Z][A-Z0-9_]*=/.test(toks[i])) {
+        if (toks[i] === "KJ_ALLOW_REWRITE=1") named = true;
+        i += 1;
+      }
+      // Una asignacion delante solo alcanza a SU comando, asi que el escape del
+      // comando vale unicamente en un comando SIMPLE: en "VAR=1 true && python"
+      // o "VAR=1 && python" el python nunca la recibe (catch de la review). Lo
+      // que va entre comillas no encadena nada, asi que no cuenta.
+      // Tampoco es simple si hay sustitucion: el proceso de dentro de $( ) no
+      // hereda la asignacion (catch de la review). Mismo criterio que el resto
+      // de guardias del Sentinel.
+      // Dentro de comillas SIMPLES todo es literal; dentro de dobles, un ; no
+      // encadena pero $( ) si ejecuta. Por eso se miran dos cosas distintas.
+      const noSingle = cmd.replaceAll(/'[^']*'/g, "");
+      const substitutes = noSingle.includes("$(") || noSingle.includes("\\u0060");
+      const bare = noSingle.replaceAll(/"[^"]*"/g, "");
+      const simple = !substitutes && !/[;&|]/.test(bare) && !bare.includes("\\n");
+      const cmdEscape = named && simple && i < toks.length;
+      const escaped = process.env.KJ_ALLOW_REWRITE === "1" || cmdEscape;
+      // Un escape ignorado EN SILENCIO era el bug: si esta puesto y no vale, se dice.
+      if (named && !cmdEscape) console.error("kj tool gate: KJ_ALLOW_REWRITE=1 presente pero IGNORADO — solo vale delante del comando y en uno simple (sin ; | & fuera de comillas).");
       const writes = /open\\s*\\([^)]*["'][wa]["']|>\\s*\\S+\\.json\\b/.test(cmd);
-      if (/json\\.dumps?\\s*\\(/.test(cmd) && writes) {
+      // KJC-BUG-0227: y solo se vigila lo que esta DENTRO del arbol. Un fichero
+      // temporal del scratchpad no es asunto de este guard, y bloquearlo
+      // ensenaba a rodearlo. Sin ruta reconocible se vigila: el lado seguro.
+      const targets = cmd.match(/[\\w./-]+\\.json\\b/g) || [];
+      // Solo se exime lo que se puede establecer CON CERTEZA: una ruta absoluta
+      // fuera del arbol. Una relativa depende del cwd del shell, que este hook
+      // no conoce — "cd packages && ... open(\\"../package.json\\")" escribe
+      // dentro del repo (catch de la review), asi que se sigue vigilando.
+      // Un enlace puede apuntar dentro: /tmp/link.json escribiria en el repo
+      // (catch de la review). Se resuelve el padre real antes de clasificar, y
+      // si no se puede resolver, se vigila.
+      // Fuera del arbol es SALIR de el, no que el nombre empiece por dos puntos:
+      // <repo>/..config.json esta dentro (catch de la review).
+      const escapesRoot = (rel) => rel === ".." || rel.startsWith("../");
+      const outsideForSure = (t) => {
+        if (!t.startsWith("/")) return false;
+        const abs = resolve(t);
+        try {
+          const root = realpathSync(ROOT);
+          // El propio fichero puede SER el enlace (/tmp/link.json -> repo/cfg.json),
+          // asi que se resuelve entero cuando existe; si aun no existe, manda su
+          // directorio real.
+          if (existsSync(abs)) return escapesRoot(relative(root, realpathSync(abs)));
+          const parts = abs.split("/");
+          const name = parts.pop();
+          return escapesRoot(relative(root, realpathSync(parts.join("/") || "/") + "/" + name));
+        } catch {
+          return false;
+        }
+      };
+      // Con expansion del shell no se sabe a donde apunta nada: "$PWD/cfg.json"
+      // deja el trozo "/cfg.json", que parece absoluto y ajeno sin serlo (catch
+      // de la review). Ante la duda se vigila.
+      const expands = /[$~]/.test(cmd) || cmd.includes("\\u0060");
+      const mine = expands || targets.length === 0 || !targets.every(outsideForSure);
+      if (!escaped && mine && /json\\.dumps?\\s*\\(/.test(cmd) && writes) {
         console.error("kj tool gate: reserializing a whole JSON file makes the diff unreviewable — make targeted edits instead (KJ_ALLOW_REWRITE=1 to override consciously).");
         process.exit(2);
       }
@@ -100,8 +170,27 @@ export function mergeClaudeHooks({ projectDir, logger = console, entries }) {
   return { wired: true };
 }
 
+/**
+ * La raiz del proyecto: el toplevel de git, o el directorio dado si no hay git.
+ * Vive aqui y no se importa de sentinel-hooks porque ese modulo importa de
+ * este: el ciclo rompe la carga.
+ */
+function resolveProjectRoot(dir) {
+  try {
+    return execFileSync("git", ["rev-parse", "--show-toplevel"], { cwd: dir, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim() || dir;
+  } catch {
+    return dir;
+  }
+}
+
 /** Write the script and merge the PreToolUse entries into .claude/settings.json. */
 export function installHarnessHooks({ projectDir = process.cwd(), logger = console } = {}) {
+  // KJC-BUG-0223: el harness es del proyecto y vive en su raiz. Instalado desde
+  // un subdirectorio sembraba ahi un segundo `.karajan/harness` que no gobierna
+  // nada, y el gate seguia mirando otro sitio.
+  const root = resolveProjectRoot(projectDir);
+  if (root !== projectDir) logger?.info?.(`kj harden: el harness es del proyecto, se instala en su raíz (${root})`);
+  projectDir = root;
   const scriptAbs = writeHarnessScript(projectDir, "pretooluse.mjs", SCRIPT_BODY);
   const { wired } = mergeClaudeHooks({
     projectDir,

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);
+            }
           }
         }
       }
@@ -1184,7 +1198,11 @@ export function verifySentinelScripts({ projectDir, readFileFn = readFileSync, g
     ok: true,
     mismatched: [],
     drift,
-    reason: "el harness instalado está sellado y las plantillas de este árbol van por delante (kj harden lo pone al día) — no es manipulación",
+    // KJC-BUG-0222: `kj harden` NO pone al dia un guard sellado, lo deja en paz
+    // a proposito (KJC-BUG-0193), asi que mandarlo era un bucle: ejecutas,
+    // sale "unchanged" y el gate repite lo mismo. El que resuelve ESTE estado
+    // es `kj harden --commit`, y es acto del humano.
+    reason: "el harness instalado está sellado y las plantillas de este árbol van por delante — no es manipulación, y `kj harden` lo deja como está a propósito: quien lo avanza es el humano con `kj harden --commit`",
   };
 }
 
@@ -1200,6 +1218,13 @@ export function verifySentinelScripts({ projectDir, readFileFn = readFileSync, g
  * guard is still the right move.
  */
 export function installSentinelHooks({ projectDir = process.cwd(), logger = console, human = false, gitShowFn = null } = {}) {
+  // KJC-BUG-0223: instalado desde un subdirectorio, esto sembraba un segundo
+  // `.karajan/harness` ahi, y el gate (que mira otro sitio) pasaba a verlo. El
+  // ritual quedaba "arreglado" y el arbol se llenaba de arneses huerfanos que
+  // no gobiernan nada. El harness es del proyecto: va a su raiz.
+  const root = resolveSentinelRoot(projectDir);
+  if (root !== projectDir) logger?.info?.(`kj harden: el harness es del proyecto, se instala en su raíz (${root})`);
+  projectDir = root;
   const sealed = human ? new Map() : sealedByPath(projectDir, gitShowFn);
   const deferred = [];
   const keepsItsSeal = (name) => {