karajan-code 4.20.1 → 4.22.0

package/src/identity/detect.js

@@ -0,0 +1,51 @@
+/**
+ * Identity lock — detect (IDN-A, KJC-TSK-0762). What is EFFECTIVE right now,
+ * with no network and no spawned `gh`: the active gh account is read from
+ * gh's own hosts.yml (the file `gh auth switch` mutates), the git email from
+ * `git config user.email`. Both return null when unknown — never a guess.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { execFileSync } from "node:child_process";
+import { join } from "node:path";
+import { homedir } from "node:os";
+import yaml from "js-yaml";
+
+export function defaultHostsPath() {
+  const base = process.env.GH_CONFIG_DIR || join(process.env.XDG_CONFIG_HOME || join(homedir(), ".config"), "gh");
+  return join(base, "hosts.yml");
+}
+
+/**
+ * @param {{hostsPath?: string, host?: string}} [opts]
+ * @returns {string|null} active gh login for the host, null without a session
+ */
+export function activeGhUser({ hostsPath = defaultHostsPath(), host = "github.com" } = {}) {
+  if (!existsSync(hostsPath)) return null;
+  try {
+    const parsed = yaml.load(readFileSync(hostsPath, "utf8"));
+    const user = parsed?.[host]?.user;
+    return typeof user === "string" && user.length > 0 ? user : null;
+  } catch {
+    return null;
+  }
+}
+
+const defaultGitFn = (projectDir) =>
+  execFileSync("git", ["config", "--get", "user.email"], { cwd: projectDir, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] });
+
+/**
+ * @param {string} projectDir
+ * @param {{gitFn?: (projectDir: string) => string}} [opts]
+ * @returns {string|null}
+ */
+export function effectiveGitEmail(projectDir, { gitFn = defaultGitFn } = {}) {
+  try {
+    // --get yields the single effective value; keep the last line anyway so a
+    // multi-line answer from an odd config can never leak a newline into it.
+    const out = String(gitFn(projectDir) || "").trim().split("\n").at(-1).trim();
+    return out.length > 0 ? out : null;
+  } catch {
+    return null;
+  }
+}

package/src/identity/store.js

@@ -0,0 +1,66 @@
+/**
+ * Identity lock — store (IDN-A, KJC-TSK-0762, epic KJC-PCS-0079).
+ *
+ * Each CLONE declares the identity it is worked with: the gh account and the
+ * git email. It is per developer, not per project, so it lives in
+ * `.karajan/identity.local.yml`, never tracked (this module keeps it in the
+ * .gitignore). Born from the 2026-08-20 incident: one `gh` call without an
+ * explicit account switch posted as a client account on a public repo.
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import yaml from "js-yaml";
+
+export const IDENTITY_FILE = ".karajan/identity.local.yml";
+
+/** @param {string} projectDir */
+export function identityPath(projectDir) {
+  return join(projectDir, ".karajan", "identity.local.yml");
+}
+
+/**
+ * @param {string} projectDir
+ * @returns {{gh_user: string, git_email: string, declared_at: string}|null}
+ */
+export function readIdentity(projectDir) {
+  const p = identityPath(projectDir);
+  if (!existsSync(p)) return null;
+  let parsed;
+  try {
+    parsed = yaml.load(readFileSync(p, "utf8"));
+  } catch {
+    return null; // corrupt or half-written file = no identity (review catch)
+  }
+  if (!parsed || typeof parsed !== "object" || !parsed.gh_user || !parsed.git_email) return null;
+  return { gh_user: String(parsed.gh_user), git_email: String(parsed.git_email), declared_at: String(parsed.declared_at || "") };
+}
+
+/**
+ * Write the declaration and make sure it never gets tracked. Fails loud on
+ * an incomplete identity — a half-declared lock is no lock.
+ * @param {string} projectDir
+ * @param {{gh_user: string, git_email: string}} identity
+ */
+export function writeIdentity(projectDir, identity) {
+  for (const field of ["gh_user", "git_email"]) {
+    if (!identity?.[field] || typeof identity[field] !== "string") {
+      throw new Error(`identity: "${field}" is required (got ${JSON.stringify(identity?.[field])})`);
+    }
+  }
+  // Ignore FIRST, write SECOND (review catch): if the ignore step fails, no
+  // unignored identity file is ever left on disk for git to pick up.
+  ensureIgnored(projectDir);
+  mkdirSync(join(projectDir, ".karajan"), { recursive: true });
+  const record = { gh_user: identity.gh_user, git_email: identity.git_email, declared_at: new Date().toISOString() };
+  writeFileSync(identityPath(projectDir), yaml.dump(record, { lineWidth: 120 }), "utf8");
+  return record;
+}
+
+function ensureIgnored(projectDir) {
+  const ignorePath = join(projectDir, ".gitignore");
+  const current = existsSync(ignorePath) ? readFileSync(ignorePath, "utf8") : "";
+  if (current.split("\n").some((line) => line.trim() === IDENTITY_FILE)) return;
+  const sep = current.length === 0 || current.endsWith("\n") ? "" : "\n";
+  writeFileSync(ignorePath, `${current}${sep}${IDENTITY_FILE}\n`, "utf8");
+}

package/src/policy/exceptions.js

@@ -24,13 +24,23 @@ function defaultIdentity(projectDir) {
  * @returns {{standing: object[], discarded: number}}
  */
 export function loadStandingExceptions(projectDir) {
+  const { records, discarded } = loadExceptionRecords(projectDir);
+  return { standing: records.filter((rec) => rec.scopeKind === "permanente"), discarded };
+}
+
+/**
+ * TODOS los registros del jsonl (permanentes y puntuales) con el mismo parse
+ * tolerante — el informe (PL-E) cuenta también las puntuales.
+ * @returns {{records: object[], discarded: number}}
+ */
+export function loadExceptionRecords(projectDir) {
   let raw;
   try {
     raw = readFileSync(join(projectDir, ".karajan", "policy-exceptions.jsonl"), "utf8");
   } catch {
-    return { standing: [], discarded: 0 };
+    return { records: [], discarded: 0 };
   }
-  const standing = [];
+  const records = [];
   let discarded = 0;
   for (const line of raw.split("\n")) {
     if (!line.trim()) continue;
@@ -39,12 +49,12 @@ export function loadStandingExceptions(projectDir) {
       // JSON válido pero no-objeto (null, número…) es tan corrupto como el
       // que no parsea: se descarta contando (catch de codex, explícito).
       if (typeof rec !== "object" || rec === null) discarded += 1;
-      else if (rec.scopeKind === "permanente") standing.push(rec);
+      else records.push(rec);
     } catch {
       discarded += 1;
     }
   }
-  return { standing, discarded };
+  return { records, discarded };
 }
 
 function defaultAppend(projectDir, line) {

package/src/policy/report.js

@@ -0,0 +1,99 @@
+/**
+ * PL-E (KJC-TSK-0767) — el informe de policy, PURO (líneas del decision log +
+ * excepciones + policy + reloj ⇒ objeto determinista; cero I/O, cero LLM).
+ * Responde: ¿qué reglas avisan y cuánto (gana dientes con datos)?, ¿qué
+ * denegaciones siguen abiertas (la renuncia deja rastro)?, ¿qué concesiones
+ * viven, vencen o se renuevan (la renovación es señal)?
+ */
+import { verifyDecisionChain } from "@karajan-family/governance";
+
+const DAY_MS = 86_400_000;
+const WARN_SIGNAL_MIN = 5;
+
+/** enforcement/class de una regla según la policy cargada (null si no se sabe). */
+function ruleMeta(policy, ruleId) {
+  if (!policy) return {};
+  if (ruleId.startsWith("defaults.")) return { enforcement: "deny", class: "security" };
+  const m = /^roles\.([^.]+)\.([^.]+)/.exec(ruleId);
+  const spec = m ? policy.roles?.[m[1]]?.[m[2]] : policy.invariants?.find((i) => i.id === ruleId);
+  if (!spec) return {};
+  return { enforcement: spec.enforcement || "warn", ...(spec.class ? { class: spec.class } : {}) };
+}
+
+function parseDecisions(lines) {
+  const records = [];
+  let discarded = 0;
+  for (const line of lines) {
+    try {
+      const rec = JSON.parse(line);
+      if (typeof rec === "object" && rec !== null) records.push(rec);
+      else discarded += 1;
+    } catch {
+      discarded += 1;
+    }
+  }
+  return { records, discarded };
+}
+
+// Abiertas = denies posteriores al último allow/exempt: el log acaba en
+// rechazo sin que nada haya pasado después. Heurística declarada — el log
+// no lleva rama ni autor, así que no distingue "arreglado" de "abandonado".
+const lastResolvedIndex = (records) => records.findLastIndex((r) => r.decision === "allow" || r.decision === "exempt");
+
+function tallyRules(records, policy, lastResolved) {
+  const rules = new Map();
+  const row = (id) => {
+    if (!rules.has(id)) rules.set(id, { rule_id: id, ...ruleMeta(policy, id), warns: 0, denies: 0, exempts: 0, open: 0 });
+    return rules.get(id);
+  };
+  // Un sello lleva un rule_id por FICHERO violador: se cuentan decisiones
+  // por regla, no ficheros — de ahí el Set por entrada.
+  const ids = (list) => new Set(list ?? []);
+  records.forEach((rec, i) => {
+    for (const id of ids(rec.warn_rule_ids)) row(id).warns += 1;
+    if (rec.decision === "deny") for (const id of ids(rec.rule_ids)) { row(id).denies += 1; if (i > lastResolved) row(id).open += 1; }
+    if (rec.decision === "exempt") for (const id of ids(rec.rule_ids)) row(id).exempts += 1;
+  });
+  return [...rules.values()].toSorted((a, b) => (b.denies + b.warns) - (a.denies + a.warns));
+}
+
+function tallyGrants(exceptionRecords, now, soonDays) {
+  const perm = exceptionRecords.filter((e) => e?.scopeKind === "permanente");
+  // Una caducidad ilegible (NaN) NO está viva: la excepción falla cerrada.
+  const alive = [];
+  const expired = [];
+  for (const e of perm) (Date.parse(e.expiresAt) > now.getTime() ? alive : expired).push(e);
+  const soon = alive.filter((e) => Date.parse(e.expiresAt) - now.getTime() <= soonDays * DAY_MS);
+  const counts = Map.groupBy(perm, (e) => e.rule_id);
+  const renewals = [...counts].filter(([, v]) => v.length >= 2).map(([rule_id, v]) => ({ rule_id, count: v.length }));
+  return { alive, expired, soon, renewals, point: exceptionRecords.length - perm.length };
+}
+
+function signalsFor(rules, grants) {
+  const out = [];
+  for (const g of grants.renewals) out.push(`[${g.rule_id}] concedida ${g.count} veces — una excepción que se renueva ya no es una excepción: es la política pidiendo cambio (PR a .karajan/policy.yml)`);
+  for (const r of rules) {
+    if (r.warns >= WARN_SIGNAL_MIN && r.denies === 0 && r.enforcement !== "deny") out.push(`[${r.rule_id}] ha avisado ${r.warns} veces y nunca ha bloqueado — decide: promover a enforcement=deny o retirarla; un aviso perpetuo es ruido`);
+    if (r.open > 0) out.push(`[${r.rule_id}] ${r.open} denegación(es) abierta(s) — el log acaba en rechazo: ¿arreglo pendiente, excepción por pedir, o renuncia?`);
+  }
+  for (const g of grants.soon) out.push(`[${g.rule_id}] vence ${g.expiresAt} — al vencer vuelve a bloquear sola; renueva por su cauce o deja que caduque`);
+  return out;
+}
+
+/**
+ * @returns {{chain: object, decisions: object, rules: object[], grants: object, signals: string[]}}
+ */
+export function buildPolicyReport({ decisionLines = [], exceptionRecords = [], policy = null, now = new Date(), soonDays = 7 } = {}) {
+  const chain = decisionLines.length ? verifyDecisionChain(decisionLines) : { ok: true, length: 0 };
+  const { records, discarded } = parseDecisions(decisionLines);
+  const count = (d) => records.filter((r) => r.decision === d).length;
+  const chokepoints = Object.fromEntries([...Map.groupBy(records, (r) => r.chokepoint ?? "unknown")].map(([k, v]) => [k, v.length]));
+  const lastResolved = lastResolvedIndex(records);
+  const rules = tallyRules(records, policy, lastResolved);
+  const grants = tallyGrants(exceptionRecords, now, soonDays);
+  const decisions = {
+    total: records.length, discarded, allow: count("allow"), deny: count("deny"), exempt: count("exempt"),
+    open: records.filter((r, i) => r.decision === "deny" && i > lastResolved).length, chokepoints,
+  };
+  return { chain, decisions, rules, grants, signals: signalsFor(rules, grants) };
+}

package/src/review/card-first.js

@@ -14,7 +14,10 @@ const LIVE_STATUSES = new Set(["pending", "running", "failed"]);
 // Card-shaped reference: LIN-123, bb-002 and multi-segment ids like
 // KJC-TSK-0684 (optional middle segments) — tight enough to skip slugs.
 // Shared with the method report (MG-D): one pattern, one truth.
-export const CARD_REF_RE = /\b[a-z][a-z0-9]{1,9}(?:-[a-z][a-z0-9]{1,9})*-\d{1,6}\b/i;
+// The lookahead keeps a version tail from reading as a card (KJC-BUG-0154):
+// `chore/release-4.22.0` matched "release-4" at the dot's word boundary, and
+// the board-sync gate then demanded moving a card that exists nowhere.
+export const CARD_REF_RE = /\b[a-z][a-z0-9]{1,9}(?:-[a-z][a-z0-9]{1,9})*-\d{1,6}\b(?!\.\d)/i;
 const DEFAULT_EXEMPT_PREFIXES = ["chore/release-"];
 
 // Token-boundary match: BB-002 must not satisfy a branch that actually

package/src/review/one-shot-review.js

@@ -12,9 +12,10 @@ import { createAgent } from "../agents/index.js";
 import { resolveRole } from "../config/role-resolver.js";
 import { buildReviewerPrompt } from "../prompts/reviewer.js";
 import { resolveReviewProfile } from "./profiles.js";
-import { parseMaybeJsonString } from "./parser.js";
+import { parseMaybeJsonString, normalizeReviewPayload } from "./parser.js";
 import { detectAvailableAgents, detectHostAgent } from "../utils/agent-detect.js";
-import { saveVerdict } from "./verdict-store.js";
+import { saveVerdict, diffHash } from "./verdict-store.js";
+import { reportUnparseableVerdict } from "./unparseable-verdict.js";
 import { detectWorkspace } from "./workspace.js";
 import { isQuotaExhausted, candidateStatus, pickQuotaFallback, formatCandidateMenu } from "./reviewer-fallback.js";
 
@@ -103,9 +104,14 @@ export async function runOneShotReview({
     throw new Error(`reviewer ${activeReviewer} failed: ${result?.error || "no output"}`);
   }
 
-  const parsed = parseMaybeJsonString(result.output);
+  // KJC-BUG-0146, second half: parseMaybeJsonString only PARSES — it returns whatever JSON came
+  // back, wrapper and all. Yesterday's fix taught normalizeReviewPayload to unwrap {ok, result},
+  // but this path never called it, so the bug survived with a green test on the wrong function.
+  // A test can only prove the code it actually exercises.
+  const parsed = normalizeReviewPayload(parseMaybeJsonString(result.output));
   if (!parsed || typeof parsed.approved !== "boolean") {
-    throw new Error(`reviewer ${activeReviewer} returned no parseable verdict`);
+    // KJC-BUG-0146: keep the answer. Throwing it away is what left eight occurrences undiagnosed.
+    throw new Error(await reportUnparseableVerdict({ projectDir, reviewer: activeReviewer, output: result.output, hash: diffHash(diff) }));
   }
 
   return saveVerdict(projectDir, diff, {

package/src/review/parser.js

@@ -33,10 +33,19 @@ export function normalizeReviewPayload(payload) {
   if (isReviewPayload(payload)) return payload;
   if (Array.isArray(payload)) return findReviewInArray(payload);
 
+  // KJC-BUG-0146 — the verdict often arrives WRAPPED by the CLI that produced it:
+  // {"ok":true,"result":{approved,...}}. Only the string form was unwrapped, so a
+  // perfectly good approval from codex was thrown away as "no parseable verdict"
+  // eight times in three days. The evidence came from the raw answer this bug's
+  // first fix started saving.
   if (typeof payload.result === "string") {
     const parsedResult = parseMaybeJsonString(payload.result);
     if (parsedResult?.approved !== undefined) return parsedResult;
   }
+  if (payload.result && typeof payload.result === "object") {
+    const inner = normalizeReviewPayload(payload.result);
+    if (inner) return inner;
+  }
 
   return null;
 }

package/src/review/unparseable-verdict.js

@@ -0,0 +1,50 @@
+/**
+ * KJC-BUG-0146 — when a reviewer answers something the parser cannot read.
+ *
+ * Until now that answer was thrown away: the error said "no parseable verdict"
+ * and not one byte of what the reviewer actually replied survived. Eight
+ * occurrences produced zero evidence, which is why the bug stayed undiagnosed
+ * for two days. A failure nobody can inspect is a failure nobody can fix.
+ *
+ * So the raw answer is written next to the verdicts and an excerpt travels in
+ * the error. Nothing else changes: an unreadable answer is still a refusal,
+ * never a pass — it COULD be a rejection in the wrong shape, and switching to
+ * another reviewer would turn it into an approval.
+ */
+import fs from "node:fs/promises";
+import path from "node:path";
+
+const DIR = path.join(".karajan", "reviews");
+const EXCERPT = 400;
+
+/** One line about what came back, so the shape is visible without opening anything. */
+export function describeOutput(output) {
+  if (output === undefined || output === null) return "no output at all";
+  if (typeof output !== "string") return `${typeof output}, not a string`;
+  if (output.trim() === "") return "empty output";
+  return `${output.length} chars, starts with ${JSON.stringify(output.slice(0, 60))}`;
+}
+
+/**
+ * Writes the raw answer for inspection and returns the error message to raise.
+ * A failure to write is never allowed to hide the original problem.
+ * @param {{projectDir?: string, reviewer: string, output: unknown, hash: string, writeFile?: Function}} args
+ */
+export async function reportUnparseableVerdict({ projectDir = process.cwd(), reviewer, output, hash, writeFile = fs.writeFile }) {
+  const file = path.join(projectDir, DIR, `${hash}.unparseable.txt`);
+  const body = typeof output === "string" ? output : JSON.stringify(output ?? null, null, 2);
+  let saved = null;
+  try {
+    await fs.mkdir(path.dirname(file), { recursive: true });
+    await writeFile(file, `reviewer: ${reviewer}\n\n${body}\n`, "utf8");
+    saved = file;
+  } catch {
+    // Could not save it — the excerpt below still travels, and the message says so.
+  }
+  const excerpt = typeof output === "string" && output.trim() ? `\n--- what ${reviewer} answered (first ${EXCERPT} chars) ---\n${output.slice(0, EXCERPT)}\n---` : "";
+  return [
+    `reviewer ${reviewer} returned no parseable verdict (${describeOutput(output)})`,
+    saved ? `full answer saved to ${path.relative(projectDir, saved)}` : "the full answer could NOT be saved to disk",
+    "an unreadable answer is a refusal, not a pass: it may be a rejection in the wrong shape (KJC-BUG-0146)",
+  ].join("\n") + excerpt;
+}