karajan-code 4.38.0 → 4.40.0

package/src/commands/rules-compile.js

@@ -0,0 +1,116 @@
+/**
+ * kj rules compile (KJC-TSK-0940, MDR-D, ADR 0016): the brief for whoever
+ * compiles the rules of the MD files that have no gate yet. kj calls no model:
+ * the host agent knows its own tools and their arguments, which is what a
+ * condition has to name. It proposes; `kj rules check` proves the proposal and
+ * the user approves it (`kj rules approve`, a human act).
+ */
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+import yaml from "js-yaml";
+
+import { shownSource } from "../rules/inventory.js";
+import { loadRules, PROPOSAL_FILE, RULES_FILE, rulesCoverage } from "./rules.js";
+
+const FORMAT = `\`\`\`yaml
+version: 1
+rules:
+  - id: R-0a1b2c3d4e          # the id below, as is
+    source: CLAUDE.md          # the MD file the rule is written in
+    text: "Sprints: uno por día."   # the rule's text, word for word
+    kind: deterministic
+    when:                      # WHEN TO DENY the call
+      tool: "mcp__planning-game*__create_sprint"   # a glob, or a list of globs
+      any:                     # all: every condition holds; any: at least one
+        - { arg: allowLongSprint, equals: true }
+        - { arg: endDate, days_from: startDate, gt: 0 }
+    message: "Un sprint dura un día."   # what the denied agent reads
+    examples:                  # the rule is run against them: both lists required
+      deny: [{ tool: mcp__planning-game-x__create_sprint, input: { startDate: "2026-10-05", endDate: "2026-10-11" } }]
+      allow: [{ tool: mcp__planning-game-x__create_sprint, input: { startDate: "2026-10-05", endDate: "2026-10-05" } }]
+  - { id: R-1a2b3c4d5e, source: CLAUDE.md, text: "No preguntes obviedades.", kind: judgment, when: { tool: AskUserQuestion } }
+  - { id: R-2a3b4c5d6e, source: CLAUDE.md, text: "Habla español correcto.", kind: out-of-scope, reason: "no tool call breaks it" }
+\`\`\``;
+
+const HOW = [
+  "A condition reads ONE argument of the tool input (`arg`, a dotted path such as updates.status) with exactly one",
+  "operator: equals, in (a list), matches (a regex), exists (true/false), gt, lt. With days_from, gt/lt compare the",
+  "calendar days from that other argument to `arg`. There is nothing else: no other keys, no free code.",
+  "",
+  "Choose the kind of each rule:",
+  "- deterministic: ONE tool call breaks it and the tool name and its arguments are enough to tell. Name the tools",
+  "  as you see them (MCP tools included). Deny only what the rule forbids: a gate that denies honest calls gets removed.",
+  "- judgment: a tool call breaks it, but telling takes reading what the call says. Give `when.tool` only.",
+  "- out-of-scope: it is about how you think or answer, and no tool call breaks it. Give the `reason`.",
+  "Do not stretch a rule into a condition it does not state, and do not leave a rule out: every rule gets a kind.",
+];
+
+/**
+ * KJC-TSK-0953: kj writes the skeleton of the proposal, so nobody retypes the
+ * literal texts. It starts from what rules.yml holds minus the stale, lays the
+ * proposal already there over it (what is filled in stays), and adds one entry
+ * per pending rule that is missing, with no kind yet.
+ * @returns {number|null} the entries with no kind, or null when the proposal there is not YAML
+ */
+function writeSkeleton({ projectDir, home, pending, kept, gone }) {
+  const file = path.join(projectDir, PROPOSAL_FILE);
+  let proposed = [];
+  if (fs.existsSync(file)) {
+    try { proposed = yaml.load(fs.readFileSync(file, "utf8"))?.rules; } catch { return null; }
+    if (!Array.isArray(proposed)) return null;
+  }
+  // The approved rules are the base: a proposal that forgot one would remove its
+  // gate on approval. What the proposal says about a rule wins; the stale leave.
+  const byId = new Map(kept.map((rule) => [rule.id, rule]));
+  const loose = []; // entries with no usable id: kept, for kj rules check to name
+  for (const entry of proposed) {
+    if (typeof entry?.id !== "string") loose.push(entry);
+    else if (!gone.has(entry.id)) byId.set(entry.id, entry);
+  }
+  for (const rule of pending) {
+    if (!byId.has(rule.id)) byId.set(rule.id, { id: rule.id, source: shownSource(rule.file, projectDir, home), text: rule.text });
+  }
+  const rules = [...byId.values(), ...loose];
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, yaml.dump({ version: 1, rules }, { lineWidth: -1 }));
+  return rules.filter((entry) => !entry?.kind).length;
+}
+
+/** @returns {{code: 0|1, lines: string[]}} */
+export function rulesCompileBrief({ projectDir, home = os.homedir() }) {
+  const covered = rulesCoverage({ projectDir, home });
+  if (!covered.output) return covered;
+  const pending = covered.output.rows.filter((row) => row.status === "none");
+  const { stale } = covered.output;
+  if (pending.length + stale.length === 0) return { code: 0, lines: ["✓ every rule of the MD files is decided: nothing to compile"] };
+  const gone = new Set(stale.map((rule) => rule.id));
+  const kept = loadRules(projectDir).rules.filter((rule) => !gone.has(rule.id));
+  const undecided = writeSkeleton({ projectDir, home, pending, kept, gone });
+  if (undecided === null) return { code: 1, lines: [`✗ ${PROPOSAL_FILE} is not valid YAML with a rules list: fix it or delete it`] };
+  return {
+    code: 0,
+    lines: [
+      "# Compile the rules of the MD files into gates (ADR 0016)",
+      "",
+      `${PROPOSAL_FILE} is written: what ${RULES_FILE} holds today, as it is, and one entry per rule with no gate,`,
+      `with its id, source and literal text. ${undecided} entr${undecided === 1 ? "y has" : "ies have"} no kind yet: edit each one, give it its kind and`,
+      `what that kind takes. Leave id, source and text as they are. You propose; you cannot write ${RULES_FILE}.`,
+      ...(stale.length ? [`Left out, their text is in no MD any more: ${stale.map((rule) => rule.id).join(", ")}`] : []),
+      "",
+      FORMAT,
+      "",
+      ...HOW,
+      "",
+      "A rule with a condition (deterministic) you write by hand, in its entry. The rest take no condition, and you",
+      "decide many at once: `kj rules decide <id>... --kind judgment --tool <tool>` or",
+      "`kj rules decide <id>... --kind out-of-scope --reason \"<why no tool call breaks it>\"`.",
+      "",
+      "## Then",
+      "Run `kj rules check` and fix the proposal until it holds. Then run `kj rules review`: a different AI judges",
+      "whether each compilation is as strong as its text, and a rule you weakened comes back to you. Only then ask your",
+      "user to read it and run `kj rules approve` from their own terminal: no agent session can.",
+    ],
+  };
+}

package/src/commands/rules-decide.js

@@ -0,0 +1,51 @@
+/**
+ * kj rules decide (KJC-TSK-0969, MDR-G, ADR 0016): a real project has more than
+ * a hundred rules, and most take no condition. Their kind is decided in one go:
+ * judgment with the tool it shows on, or out of scope with the reason. kj writes
+ * the proposal, as it writes its skeleton. A deterministic rule is not decided
+ * here: its condition and its examples are written rule by rule.
+ */
+import fs from "node:fs";
+import path from "node:path";
+
+import yaml from "js-yaml";
+
+import { PROPOSAL_FILE } from "./rules.js";
+
+const failed = (line) => ({ code: 1, lines: [`✗ ${line}`] });
+
+/** What each kind takes, or why it cannot be decided this way. */
+function decision({ kind, tools = [], reason = "" }) {
+  if (kind === "judgment") {
+    if (tools.length === 0) return { error: "a judgment rule names the tool it shows on: --tool <glob> (repeatable)" };
+    return { fields: { kind, when: { tool: tools.length === 1 ? tools[0] : tools } } };
+  }
+  if (kind === "out-of-scope") {
+    if (!reason.trim()) return { error: "an out-of-scope rule says why no tool call breaks it: --reason <text>" };
+    return { fields: { kind, reason: reason.trim() } };
+  }
+  return { error: "--kind is judgment or out-of-scope; a deterministic rule is written by hand, with its condition and its examples" };
+}
+
+/**
+ * @param {{projectDir: string, file?: string, ids: string[], kind: string, tools?: string[], reason?: string}} opts
+ * @returns {{code: 0|1, lines: string[]}}
+ */
+export function rulesDecide({ projectDir, file = PROPOSAL_FILE, ids, kind, tools, reason }) {
+  if (!Array.isArray(ids) || ids.length === 0) return failed("name at least one rule id (R-...)");
+  const { fields, error } = decision({ kind, tools, reason });
+  if (error) return failed(error);
+  const target = path.resolve(projectDir, file);
+  let doc;
+  try { doc = yaml.load(fs.readFileSync(target, "utf8")); } catch { return failed(`no readable ${file}: run \`kj rules compile\` first`); }
+  if (!Array.isArray(doc?.rules)) return failed(`${file} has no rules list`);
+  const wanted = new Set(ids);
+  const known = new Set(doc.rules.map((entry) => entry?.id));
+  const missing = ids.filter((id) => !known.has(id));
+  if (missing.length) return failed(`not in ${file}: ${missing.join(", ")}`);
+  // What identifies the rule stays; what its previous kind took goes.
+  doc.rules = doc.rules.map((entry) => (wanted.has(entry?.id) ? { id: entry.id, source: entry.source, text: entry.text, ...fields } : entry));
+  fs.writeFileSync(target, yaml.dump(doc, { lineWidth: -1 }));
+  const undecided = doc.rules.filter((entry) => !entry?.kind).length;
+  return { code: 0, lines: [`✓ ${wanted.size} rule(s) decided as ${kind}; ${undecided} entr${undecided === 1 ? "y has" : "ies have"} no kind yet`] };
+}

package/src/commands/rules-review.js

@@ -0,0 +1,44 @@
+/**
+ * kj rules review (KJC-TSK-0963, MDR-F4, ADR 0017): the agent the rules will
+ * watch wrote the proposal, so it is not the one who calls it good. A DIFFERENT
+ * AI reads it rule by rule, and its verdict is tied to the exact bytes of the
+ * proposal (the same store and the same primitive as `kj review`). Without an
+ * approved verdict for those bytes, `kj rules approve` does not offer it.
+ */
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+import { runOneShotReview } from "../review/one-shot-review.js";
+import { PROPOSAL_FILE, rulesCheck } from "./rules.js";
+
+const TASK = [
+  "This is NOT code: it is a proposal of compiled rules (YAML). Each entry carries the literal `text` of a rule the user",
+  "wrote in their MD files (already verified word for word) and what an agent compiled it into. That agent is the one these",
+  "rules are going to watch, so it gains from a compilation that never fires. Judge every rule on one question: does the",
+  "compilation enforce what the text says?",
+  "- kind deterministic: `when` must deny the tool calls the text forbids. Too narrow a condition (it would rarely fire), or",
+  "  examples picked so that a weak condition passes, is a defect. So is a condition so wide that it denies honest calls.",
+  "- kind judgment or out-of-scope: nothing is blocked on these. If a condition over a tool name and its arguments could",
+  "  have enforced the text, the rule has been weakened.",
+  "Report as a BLOCKING issue every rule that is weaker than its text, naming its id (R-...) and saying what would enforce it.",
+  "Approve only when no rule is weaker than its text.",
+].join("\n");
+
+/**
+ * @param {{projectDir: string, file?: string, home?: string, config: object, logger?: object, deps?: object}} opts
+ *   `deps` are the seams of runOneShotReview (hostAgent, createAgentFn, detectAgents).
+ * @returns {Promise<{code: 0|1, lines: string[]}>}
+ */
+export async function rulesReview({ projectDir, file = PROPOSAL_FILE, home = os.homedir(), config, logger, deps = {} }) {
+  let text;
+  try { text = fs.readFileSync(path.resolve(projectDir, file), "utf8"); } catch { return { code: 1, lines: [`✗ no ${file}: nothing to review`] }; }
+  const checked = rulesCheck({ projectDir, home, text });
+  if (checked.code !== 0) return { code: 1, lines: checked.lines };
+  const record = await runOneShotReview({ diff: text, task: TASK, config, logger, projectDir, ...deps });
+  if (record.verdict === "approved") {
+    return { code: 0, lines: [`✓ APPROVED by ${record.reviewer}: ${record.summary || "the compilation enforces the rules as written"}`, "Now your user reads it and runs `kj rules approve` from their own terminal."] };
+  }
+  const issues = record.issues.map((issue) => `  - ${issue.description ?? issue.message ?? JSON.stringify(issue)}`);
+  return { code: 1, lines: [`✗ REJECTED by ${record.reviewer} — ${issues.length} rule(s) weaker than their text:`, ...issues, "Fix the proposal and run `kj rules review` again: the verdict is tied to its exact content."] };
+}

package/src/commands/rules.js

@@ -0,0 +1,169 @@
+/**
+ * kj rules eval (KJC-TSK-0943, MDR-B2, ADR 0016): the hook's contract, the same
+ * as `kj policy eval --strict`. One tool call in, a JSON verdict out, exit
+ * 0 = allow, 2 = deny, 1 = it could not be evaluated (invalid or unreadable
+ * rules.yml, unreadable input).
+ */
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+import { isObject, parseRules } from "../rules/compiled.js";
+import { coverage, NO_GATE } from "../rules/coverage.js";
+import { evalRules } from "../rules/evaluate.js";
+import { inProject, listRules, shownSource } from "../rules/inventory.js";
+
+export const RULES_FILE = path.join(".karajan", "rules.yml");
+/** ADR 0017: rules whose source is outside the project. Never versioned. */
+export const LOCAL_RULES_FILE = path.join(".karajan", "rules.local.yml");
+
+/**
+ * The compiled rules of a project. A file that does not exist is no rules; a
+ * file that exists and cannot be read is an error (rules silently off would be
+ * every call allowed).
+ */
+function loadRulesFile(projectDir, file) {
+  let text;
+  try {
+    text = fs.readFileSync(path.resolve(projectDir, file), "utf8");
+  } catch (err) {
+    if (err.code === "ENOENT") return { present: false, rules: [], errors: [] };
+    return { present: true, rules: [], errors: [`cannot read ${file}: ${err.code || err.message}`] };
+  }
+  return { present: true, ...parseRules(text) };
+}
+
+/**
+ * With a `file`, that file alone (a proposal). Without one, what governs the
+ * project (KJC-TSK-0954, ADR 0017): the versioned rules and the local ones, as
+ * one rule set. An error in either leaves no rules; a rule lives in one file.
+ */
+export function loadRules(projectDir, file) {
+  if (file) return loadRulesFile(projectDir, file);
+  const loaded = [RULES_FILE, LOCAL_RULES_FILE].map((name) => ({ name, ...loadRulesFile(projectDir, name) }));
+  const errors = loaded.flatMap(({ name, errors: found }) => found.map((e) => `${name}: ${e}`));
+  const rules = loaded.flatMap((part) => part.rules);
+  const ids = rules.map((rule) => rule.id);
+  errors.push(...new Set(ids.filter((id, i) => ids.indexOf(id) !== i).map((id) => `${id}: in both ${RULES_FILE} and ${LOCAL_RULES_FILE}, a rule lives in one file`)));
+  return { present: loaded.some((part) => part.present), rules: errors.length ? [] : rules, errors };
+}
+
+const failed = (...errors) => ({ code: 1, output: { errors } });
+
+/**
+ * KJC-TSK-0946: `--input -` reads the tool input from stdin. The hook passes it
+ * that way, because a large Write does not fit in one argument. Read as a
+ * stream: a synchronous read of a pipe fails (EAGAIN) once the input is large.
+ */
+export async function readToolInput(flag, stdin = process.stdin) {
+  if (flag !== "-") return flag;
+  let text = "";
+  for await (const chunk of stdin) text += chunk;
+  return text;
+}
+
+/** @returns {{code: 0|1|2, output: object}} */
+export function rulesEval({ projectDir, tool, input = "{}" }) {
+  if (typeof tool !== "string" || !tool) return failed("--tool is required");
+  let args;
+  try { args = JSON.parse(input); } catch { return failed("--input must be valid JSON"); }
+  if (!isObject(args)) return failed("--input must be a JSON object (the tool input)");
+  const { rules, errors } = loadRules(projectDir);
+  if (errors.length) return failed(...errors);
+  const output = evalRules(rules, { tool, input: args });
+  return { code: output.decision === "deny" ? 2 : 0, output };
+}
+
+const isCall = (c) => isObject(c) && typeof c.tool === "string" && c.tool !== "" && (c.input === undefined || isObject(c.input));
+const isCallList = (list) => Array.isArray(list) && list.length > 0 && list.every(isCall);
+
+/** What a rule's examples say against the rule itself, alone. */
+function exampleFailures(rule) {
+  const { deny, allow } = isObject(rule.examples) ? rule.examples : {};
+  if (!isCallList(deny) || !isCallList(allow)) return [`${rule.id}: needs examples.deny and examples.allow, each a list of { tool, input } calls`];
+  const verdict = (call) => evalRules([rule], call).decision;
+  return [
+    ...deny.flatMap((call, i) => (verdict(call) === "deny" ? [] : [`${rule.id}: deny example #${i + 1} was allowed`])),
+    ...allow.flatMap((call, i) => (verdict(call) === "deny" ? [`${rule.id}: allow example #${i + 1} was denied`] : [])),
+  ];
+}
+
+/**
+ * kj rules test (KJC-TSK-0945, MDR-B3): every deterministic rule against its own
+ * deny/allow examples. A rule with no examples is untested, and that fails too.
+ * @returns {{code: 0|1, lines: string[]}}
+ */
+export function rulesTest({ projectDir }) {
+  const { present, rules, errors } = loadRules(projectDir);
+  if (errors.length) return { code: 1, lines: errors.map((e) => `✗ ${e}`) };
+  if (!present) return { code: 0, lines: [`no ${RULES_FILE}: nothing to test`] };
+  const tested = rules.filter((rule) => rule.kind === "deterministic");
+  const failures = tested.flatMap(exampleFailures);
+  if (failures.length) return { code: 1, lines: failures.map((f) => `✗ ${f}`) };
+  const examples = tested.reduce((n, rule) => n + rule.examples.deny.length + rule.examples.allow.length, 0);
+  return { code: 0, lines: [`✓ ${tested.length} rule(s), ${examples} example(s)`] };
+}
+
+export const PROPOSAL_FILE = path.join(".karajan", "rules.proposed.yml");
+
+/**
+ * What a proposed rule says against the MD files: it is one of their rules, word
+ * for word, and its source is where they write it (KJC-TSK-0961: the source
+ * decides whether a rule is versioned, so the proposal does not get to choose it).
+ * @param {object} rule
+ * @param {object[]|undefined} written every place the inventory found this rule
+ * @param {(file: string) => string} shown
+ */
+function inventoryFailures(rule, written, shown) {
+  if (!written) return [`${rule.id}: no rule of the MD files has this id (kj rules list)`];
+  const [first] = written;
+  if (rule.text !== first.text) return [`${rule.id}: text is not what the MD says (${first.file}:${first.line}): ${first.text}`];
+  const sources = written.map((found) => shown(found.file));
+  return sources.includes(rule.source) ? [] : [`${rule.id}: source is not where the MD files write it (${sources.join(", ")})`];
+}
+
+/**
+ * kj rules check (KJC-TSK-0950, MDR-D1): a proposal of compiled rules proves
+ * itself before a human reads it. Every rule is one of the MD files and cites
+ * its literal text; every deterministic one passes its own examples.
+ * With `text`, that content is checked and the file is not read again: whoever
+ * installs a proposal installs the bytes that were checked.
+ * `local` holds the ids written in no file of the project: those are not versioned.
+ * @returns {{code: 0|1, lines: string[], rules?: object[], local?: Set<string>}}
+ */
+export function rulesCheck({ projectDir, file = PROPOSAL_FILE, home = os.homedir(), text }) {
+  const { present, rules, errors } = text === undefined ? loadRules(projectDir, file) : { present: true, ...parseRules(text) };
+  if (!present) return { code: 1, lines: [`✗ no ${file}: nothing to check`] };
+  if (errors.length) return { code: 1, lines: errors.map((e) => `✗ ${e}`) };
+  const inventory = Map.groupBy(listRules(projectDir, { home }), (rule) => rule.id);
+  const shown = (found) => shownSource(found, projectDir, home);
+  const failures = rules.flatMap((rule) => [
+    ...inventoryFailures(rule, inventory.get(rule.id), shown),
+    ...(rule.kind === "deterministic" ? exampleFailures(rule) : []),
+  ]);
+  if (failures.length) return { code: 1, lines: failures.map((f) => `✗ ${f}`) };
+  const count = (kind) => rules.filter((rule) => rule.kind === kind).length;
+  const local = new Set(rules.filter((rule) => !inventory.get(rule.id).some((found) => inProject(found.file, projectDir))).map((rule) => rule.id));
+  return { code: 0, rules, local, lines: [`✓ ${rules.length} rule(s) hold: ${count("deterministic")} deterministic, ${count("judgment")} judgment, ${count("out-of-scope")} out of scope`] };
+}
+
+/**
+ * kj rules coverage (KJC-TSK-0941, MDR-E): every rule of the governing MD files
+ * against rules.yml. `strict` fails while a rule has no gate or a compiled rule
+ * is stale, so a rule nobody decided about cannot go unseen.
+ * @returns {{code: 0|1, lines: string[], output?: object}}
+ */
+export function rulesCoverage({ projectDir, strict = false, home }) {
+  const { rules, errors } = loadRules(projectDir);
+  if (errors.length) return { code: 1, lines: errors.map((e) => `✗ ${e}`) };
+  const { rows, stale } = coverage(listRules(projectDir, home ? { home } : {}), rules);
+  const count = (status) => rows.filter((row) => row.status === status).length;
+  const counts = { deterministic: count("deterministic"), judgment: count("judgment"), "out-of-scope": count("out-of-scope"), [NO_GATE]: count(NO_GATE), stale: stale.length };
+  const ungated = rows.filter((row) => row.status === NO_GATE);
+  const lines = [
+    ...ungated.map((r) => `✗ no gate  ${r.id}  ${r.file}:${r.line}  ${r.text}`),
+    ...stale.map((r) => `✗ stale    ${r.id}  ${r.source ?? "?"}  ${r.text ?? ""} (its text is in no MD any more: compile it again)`),
+    `${rows.length} rule(s): ${counts.deterministic} deterministic, ${counts.judgment} judgment, ${counts["out-of-scope"]} out of scope, ${ungated.length} with no gate; ${stale.length} stale`,
+  ];
+  return { code: strict && ungated.length + stale.length > 0 ? 1 : 0, lines, output: { counts, rows, stale } };
+}

package/src/config/loader.js

@@ -194,10 +194,32 @@ function stripRuntimeOnlyKeys(config) {
   return out;
 }
 
+// KJC-BUG-0253: a project's .karajan/kj.config.yml is versioned with the repo,
+// so the SonarQube credentials never go there; they live in the global config
+// (~/.karajan), where the token bootstrap already saves them.
+const SECRET_KEYS = ["token", "admin_password"];
+const isProjectConfig = (configPath) =>
+  path.basename(configPath) === "kj.config.yml"
+  && path.basename(path.dirname(configPath)) === ".karajan"
+  && path.resolve(configPath) !== path.resolve(getConfigPath());
+
+function stripSecrets(config) {
+  if (!config?.sonarqube || typeof config.sonarqube !== "object") return { out: config, stripped: [] };
+  const stripped = SECRET_KEYS.filter((k) => config.sonarqube[k] != null);
+  if (!stripped.length) return { out: config, stripped };
+  const sonarqube = { ...config.sonarqube };
+  for (const k of stripped) delete sonarqube[k];
+  return { out: { ...config, sonarqube }, stripped: stripped.map((k) => `sonarqube.${k}`) };
+}
+
+/** @returns {Promise<{strippedSecrets: string[]}>} the secret keys kept out of a project config */
 export async function writeConfig(configPath, config) {
   await ensureDir(path.dirname(configPath));
-  const sanitized = stripRuntimeOnlyKeys(config);
+  let sanitized = stripRuntimeOnlyKeys(config);
+  let strippedSecrets = [];
+  if (isProjectConfig(configPath)) ({ out: sanitized, stripped: strippedSecrets } = stripSecrets(sanitized));
   await fs.writeFile(configPath, yaml.dump(sanitized, { lineWidth: 120 }), "utf8");
+  return { strippedSecrets };
 }
 
 // Declarative mappings for applyRunOverrides to reduce cognitive complexity.

package/src/environment/adr.js

@@ -8,6 +8,9 @@ import fs from "node:fs/promises";
 import path from "node:path";
 
 const ADR_DIR = path.join(".karajan", "adrs");
+// KJC-BUG-0272: whoever records a decision proposes it. Accepting is the user's:
+// they set `Status: accepted` in the file. Born accepted, nobody had decided.
+const NEW_STATUS = "proposed";
 
 const slugify = (t) => t.toLowerCase().replaceAll(/[^a-z0-9]+/g, "-").replaceAll(/^-|-$/g, "").slice(0, 60);
 
@@ -34,12 +37,12 @@ export async function addAdr(projectDir, { title, decision, context = "", conseq
   const file = path.join(ADR_DIR, `${String(number).padStart(4, "0")}-${slugify(title)}.md`);
   const body = [
     `# ${title}`, "",
-    `Status: accepted`, `Date: ${new Date().toISOString().slice(0, 10)}`, "",
+    `Status: ${NEW_STATUS}`, `Date: ${new Date().toISOString().slice(0, 10)}`, "",
     ...(context ? ["## Context", "", context, ""] : []),
     "## Decision", "", decision, "",
     ...(consequences ? ["## Consequences", "", consequences, ""] : []),
   ].join("\n");
   await fs.mkdir(path.join(projectDir, ADR_DIR), { recursive: true });
   await fs.writeFile(path.join(projectDir, file), body);
-  return { number, file, title };
+  return { number, file, title, status: NEW_STATUS };
 }

package/src/harden/config-templates.js

@@ -42,6 +42,9 @@ export const COMMITLINT_BODY = [
 // project has no eslint config of its own.
 export const ESLINT_BODY = [
   "export default [",
+  // KJC-BUG-0254 (#1902): third-party and generated code is not the project's to
+  // lint (a vendored tf.min.js gave 6607 false no-var errors).
+  '  { ignores: ["vendor/**", "dist/**", "build/**", "coverage/**", ".scannerwork/**", "**/*.min.{js,mjs,cjs}"] },',
   "  {",
   '    files: ["**/*.{js,mjs,cjs,ts,mts,cts,jsx,tsx}"],',
   '    languageOptions: { ecmaVersion: 2025, sourceType: "module" },',

package/src/harden/harness-hooks.js

@@ -3,8 +3,9 @@
  * Field case 2026-08-02: text rules were not enough — the environment must
  * impose them AT TOOL TIME. `kj harden` writes a PreToolUse script and wires
  * it into the project's `.claude/settings.json` (merged, never clobbered):
- * Write over an existing file blocks ("use Edit", KJ_ALLOW_WRITE=1 escapes);
- * Bash that reserializes whole JSON files blocks (KJ_ALLOW_REWRITE=1).
+ * Write over an existing file blocks ("use Edit"), with no escape (ADR 0015).
+ * Writes through Bash are the Sentinel's bash-write guard (KJC-BUG-0237), which
+ * replaced the JSON-reserialization guard that lived here.
  * Claude-only v1 — the abstraction arrives with the second host that
  * supports tool hooks.
  */
@@ -19,94 +20,15 @@ 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, 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)), "..", "..");
+import { existsSync } from "node:fs";
 let raw = "";
 process.stdin.on("data", (d) => { raw += d; });
 process.stdin.on("end", () => {
   try {
     const { tool_name: tool, tool_input: input = {} } = JSON.parse(raw);
-    if (tool === "Write" && process.env.KJ_ALLOW_WRITE !== "1") {
-      if (input.file_path && existsSync(input.file_path)) {
-        console.error("kj tool gate: Write over an EXISTING file destroys unseen changes — use Edit for targeted changes (KJ_ALLOW_WRITE=1 to override consciously).");
-        process.exit(2);
-      }
-    }
-    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);
-      // 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);
-      }
+    if (tool === "Write" && input.file_path && existsSync(input.file_path)) {
+      console.error("kj tool gate: Write over an EXISTING file destroys unseen changes — use Edit for targeted changes.");
+      process.exit(2);
     }
   } catch { /* fail open */ }
   process.exit(0);

package/src/harden/hook-templates.js

@@ -62,10 +62,11 @@ function baseBranchGuard(baseBranch) {
   return [
     "# Branch-first guard — the base branch only moves via PR. KJC-BUG-0186:",
     "# the bootstrap commit is exempt, there is no commit to branch from yet.",
-    'if [ "$KJ_ALLOW_BASE_COMMIT" != "1" ] && git rev-parse --verify HEAD >/dev/null 2>&1; then',
+    "# No escape (ADR 0015): an env prefix on git commit was one the agent could raise.",
+    "if git rev-parse --verify HEAD >/dev/null 2>&1; then",
     '  current_branch=$(git symbolic-ref --short HEAD 2>/dev/null || echo "")',
     `  if [ "$current_branch" = "${baseBranch}" ]; then`,
-    `    echo 'kj harden: direct commits on ${baseBranch} are not allowed — create a branch and open a PR (KJ_ALLOW_BASE_COMMIT=1 to override)'; exit 1`,
+    `    echo 'kj harden: direct commits on ${baseBranch} are not allowed — create a branch and open a PR'; exit 1`,
     "  fi",
     "fi",
   ];
@@ -78,7 +79,7 @@ function baseBranchGuard(baseBranch) {
 function identityGuard(hook) {
   const head = [
     "# Identity lock (IDN-C, ADR 0005) — this clone's declared identity governs.",
-    'if [ "$KJ_ALLOW_IDENTITY" != "1" ] && [ -f .karajan/identity.local.yml ]; then',
+    "if [ -f .karajan/identity.local.yml ]; then",
   ];
   const tail = [
     "elif [ ! -f .karajan/identity.local.yml ]; then",
@@ -92,7 +93,7 @@ function identityGuard(hook) {
       "  kj_author=$(git var GIT_AUTHOR_IDENT | sed 's/.*<\\(.*\\)>.*/\\1/')",
       "  kj_committer=$(git var GIT_COMMITTER_IDENT | sed 's/.*<\\(.*\\)>.*/\\1/')",
       '  if [ -n "$kj_declared_email" ] && { [ "$kj_author" != "$kj_declared_email" ] || [ "$kj_committer" != "$kj_declared_email" ]; }; then',
-      '    echo "kj harden: identity lock — committing as $kj_author / $kj_committer but this clone is declared as $kj_declared_email (kj identity show; KJ_ALLOW_IDENTITY=1 to override)"; exit 1',
+      '    echo "kj harden: identity lock — committing as $kj_author / $kj_committer but this clone is declared as $kj_declared_email (kj identity show)"; exit 1',
       "  fi",
       ...tail,
     ];
@@ -103,7 +104,7 @@ function identityGuard(hook) {
     '  kj_hosts="${GH_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/gh}/hosts.yml"',
     "  kj_active_gh=$(awk '/^github.com:/{f=1;next} f&&/^[^[:space:]]/{f=0} f&&/^[[:space:]]*user:/{sub(/^[[:space:]]*user:[[:space:]]*/,\"\");print;exit}' \"$kj_hosts\" 2>/dev/null)",
     '  if [ -n "$kj_declared_gh" ] && [ "$kj_active_gh" != "$kj_declared_gh" ]; then',
-    '    echo "kj harden: identity lock — gh session is ${kj_active_gh:-none} but this clone is declared as $kj_declared_gh — run: gh auth switch --user $kj_declared_gh (KJ_ALLOW_IDENTITY=1 to override)"; exit 1',
+    '    echo "kj harden: identity lock — gh session is ${kj_active_gh:-none} but this clone is declared as $kj_declared_gh — run: gh auth switch --user $kj_declared_gh"; exit 1',
     "  fi",
     ...tail,
   ];