karajan-code 4.32.0 → 4.33.0

package/src/checks/action-pins.js

@@ -0,0 +1,131 @@
+/**
+ * KJC-TSK-0870 — the maintenance that pinning moved onto kj.
+ *
+ * Issue #1374 was right: `kj harden` generated workflows with moving tags
+ * (`actions/checkout@v4`), and kj's own `kj audit --security` flagged them, so
+ * five of the project's seven warnings came from files kj had just written.
+ * They are pinned to commit SHAs now.
+ *
+ * Pinning trades one risk for another: nobody can move the tag under you, and
+ * nobody delivers the upstream patch either. A pin that nobody revisits is a
+ * vulnerability with a long shelf life, and since kj writes those lines, kj is
+ * the one that has to notice. That is this check.
+ *
+ * It lives in `kj doctor` (a person asking about their environment) and NOT in
+ * `kj check` (a gate that CI runs): a gate that needs the network is a gate
+ * that fails on a plane, and turning red over an unreachable API is how a gate
+ * loses its credibility.
+ */
+
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+
+import { PINNED_ACTIONS } from "../harden/workflow-templates.js";
+
+const execFileAsync = promisify(execFile);
+// Nobody waits for a diagnostic. Both clients are capped, and the pins are
+// asked in parallel, so an unreachable GitHub costs one timeout and not one
+// per action.
+const CALL_TIMEOUT_MS = 5_000;
+
+const STRATEGY_MANUAL = "manual";
+const API = "https://api.github.com/repos";
+
+/** `owner/repo@sha # tag` as written in the templates. */
+export function parsePin(pin) {
+  const m = /^([^@\s]+)@([0-9a-f]{40})\s*#\s*(\S+)$/i.exec(String(pin || "").trim());
+  return m ? { action: m[1], sha: m[2].toLowerCase(), tag: m[3] } : null;
+}
+
+const SHA_RE = /^[0-9a-f]{40}$/;
+const clean = (s) => String(s || "").trim().toLowerCase();
+
+/**
+ * The SHA a tag points at today, asked through `gh` when it is there.
+ *
+ * Measured, not assumed: plain unauthenticated `fetch` answered 403 on the
+ * first real run, because GitHub allows 60 calls an hour PER IP and any shared
+ * or NAT-ed address burns that between everyone behind it. A check that
+ * answers "could not check" almost always is decorative. `gh` carries the
+ * user's own credentials (5000/hour) and kj already relies on it elsewhere;
+ * `fetch` stays as the fallback for whoever has no gh.
+ *
+ * @returns {Promise<string|null>} null when the answer cannot be trusted.
+ */
+export async function currentSha(action, tag, { fetchFn = fetch, ghFn = ghSha } = {}) {
+  const viaGh = await ghFn(action, tag);
+  if (viaGh) return viaGh;
+  const res = await fetchFn(`${API}/${action}/commits/${encodeURIComponent(tag)}`, {
+    headers: { Accept: "application/vnd.github.sha", "User-Agent": "karajan-code" },
+    signal: AbortSignal.timeout(CALL_TIMEOUT_MS),
+  });
+  if (!res?.ok) return null;
+  const body = clean(await res.text());
+  return SHA_RE.test(body) ? body : null;
+}
+
+/** @returns {Promise<string|null>} null when gh is absent, unauthenticated or unhappy. */
+async function ghSha(action, tag) {
+  try {
+    const { stdout } = await execFileAsync("gh", ["api", `repos/${action}/commits/${tag}`, "--jq", ".sha"], {
+      encoding: "utf8",
+      timeout: CALL_TIMEOUT_MS,
+    });
+    const sha = clean(stdout);
+    return SHA_RE.test(sha) ? sha : null;
+  } catch {
+    return null;
+  }
+}
+
+/** @internal Exported for dynamic import from tests. */
+export function createActionPinsCheck({ pins = PINNED_ACTIONS, deps = {} } = {}) {
+  return {
+    name: "action-pins",
+    label: "actions fijadas por SHA",
+    strategy: STRATEGY_MANUAL,
+    describe: "Detect a pinned GitHub Action whose tag has moved on without it",
+    async detect() {
+      const entries = Object.entries(pins).map(([key, pin]) => ({ key, ...(parsePin(pin) || {}) }));
+      const malformed = entries.filter((e) => !e.sha);
+      const asked = await Promise.all(
+        entries.filter((x) => x.sha).map(async (e) => {
+          // offline, rate limited, DNS down, gh missing: not an answer
+          const latest = await currentSha(e.action, e.tag, deps).catch(() => null);
+          return { ...e, latest };
+        }),
+      );
+      const stale = asked.filter((e) => e.latest && e.latest !== e.sha);
+      const unchecked = asked.filter((e) => !e.latest).length;
+
+      if (malformed.length > 0) {
+        return {
+          ok: false,
+          severity: "warn",
+          detail: `pin mal formado: ${malformed.map((m) => m.key).join(", ")} — un pin que no se puede leer no se puede comprobar`,
+          fix: "revisa PINNED_ACTIONS en src/harden/workflow-templates.js: owner/repo@<sha de 40> # <tag>",
+        };
+      }
+      if (stale.length > 0) {
+        return {
+          ok: false,
+          severity: "warn",
+          detail: stale.map((s) => `${s.action} ${s.tag} apunta hoy a ${s.latest.slice(0, 12)} y kj fija ${s.sha.slice(0, 12)}`).join(" · "),
+          fix: stale.map((s) => `${s.action}@${s.latest} # ${s.tag}`).join("  ·  "),
+        };
+      }
+      // Never claim what was not looked at (the card's own acceptance
+      // criterion): an unreachable API is said, not passed off as green.
+      if (unchecked > 0) {
+        return {
+          ok: true,
+          severity: "info",
+          detail: unchecked === entries.length
+            ? "no se pudo comprobar ninguna action (¿sin red o con la API de GitHub limitando?)"
+            : `${unchecked} action(s) sin comprobar (¿sin red o con la API de GitHub limitando?)`,
+        };
+      }
+      return { ok: true, severity: "info", detail: `${entries.length} action(s) fijadas y al día` };
+    },
+  };
+}

package/src/checks/project-checks.js

@@ -24,6 +24,7 @@ import { checkBinary } from "../utils/agent-detect.js";
 import { getInstallCommand } from "../utils/os-detect.js";
 import { STRATEGY } from "./types.js";
 import { createRepoStateCheck } from "./repo-state.js";
+import { createActionPinsCheck } from "./action-pins.js";
 
 /**
  * Detect signals del proyecto. Devuelve un set de tags con qué hay en el
@@ -246,5 +247,10 @@ export function getProjectChecks({ projectDir }) {
     // check looks at — the order it was set up in, whether the contract
     // travels, whether this clone declares who works it.
     createRepoStateCheck({ projectDir }),
+    // KJC-TSK-0870: pinning the actions by SHA (issue #1374) moved their
+    // maintenance onto kj. Doctor asks upstream whether a tag has moved on
+    // without its pin; `kj check` deliberately does not, because a gate that
+    // needs the network is a gate that fails on a plane.
+    createActionPinsCheck(),
   ];
 }

package/src/cli/register-pipeline.js

@@ -179,11 +179,21 @@ export function registerPipeline(program, { pkgVersion }) {
     .argument("[task]", "Task description (REQUIRED — provide as argument or via --task-file)")
     .option("--task-file <path>", "Read the task from a file (e.g. .md)")
     .option("--coder <name>")
+    // KJC-TSK-0864: --coder is the pipeline's word for it, --agent is the
+    // session's. Same knob, two vocabularies; naming both and disagreeing is
+    // an error, never a silent precedence.
+    .option("--agent <name>", "The agent that writes (alias of --coder)")
+    .option("--card <ref>", "Card/HU the work belongs to — its statement and criteria reach the coder")
     .option("--coder-model <name>")
     .action(async (task, flags) => {
+      if (flags.agent && flags.coder && flags.agent !== flags.coder) {
+        console.error(`kj code: --agent ${flags.agent} and --coder ${flags.coder} name different agents — pick one`);
+        process.exit(2);
+      }
+      if (flags.agent) flags.coder = flags.agent;
       await withConfig(pkgVersion, "code", flags, async ({ config, logger }) => {
         const resolvedTask = await resolveTaskInput({ task, taskFile: flags.taskFile, projectDir: config.projectDir, logger });
-        await codeCommand({ task: resolvedTask, config, logger });
+        await codeCommand({ task: resolvedTask, config, logger, flags });
       });
     });
 

package/src/commands/check.js

@@ -9,6 +9,7 @@ import { collectMethodStats, formatMethodStats } from "../checks/method.js";
 import { createRagCoverageCheck } from "../checks/rag-coverage.js";
 import { checkAiSurface, formatAiSurface } from "../checks/ai-surface.js";
 import { detectObservedAgents } from "../utils/agent-detect.js";
+import { panelSummary } from "../environment/panel.js";
 import { loadConfig } from "../config.js";
 
 export async function checkCommand({ projectDir = process.cwd(), profile = "standard", json = false, logger = console } = {}) {
@@ -44,6 +45,10 @@ export async function checkCommand({ projectDir = process.cwd(), profile = "stan
   if (method) logger.info?.(`  method: ${formatMethodStats(method)}`);
   logger.info?.(`  ${ragCoverage.ok ? "✓" : "✗"} rag-coverage: ${ragCoverage.detail}`);
   if (aiSurface) logger.info?.(`  ${formatAiSurface(aiSurface)}`);
+  // KJC-TSK-0865: who writes and who reviews is the user's choice, so it is
+  // said out loud next to everything else that describes the project. Never
+  // a check: it has no ok/fail, it informs.
+  logger.info?.(`  ${panelSummary(config)}`);
   if (ok) logger.info?.("Harness OK.");
   else if (result.ok) logger.info?.("RAG index drift detected — a gate cannot protect what it cannot see.");
   else logger.info?.("Harness drift detected — run `kj harden` to repair.");

package/src/commands/code.js

@@ -2,13 +2,35 @@ import fs from "node:fs/promises";
 import { createAgent } from "../agents/index.js";
 import { assertAgentsAvailable } from "../agents/availability.js";
 import { buildCoderPrompt } from "../prompts/coder.js";
+import { resolveCardContext } from "../prompts/card-context.js";
+import { composeTask, resolveRagContext } from "../prompts/session-context.js";
 import { resolveRole } from "../config.js";
+import { withBrainRecovery, DEFAULT_RECOVERY_POLICY } from "../brain/with-brain-recovery.js";
+import { buildRoleFallbackChain } from "../brain/role-fallback-chain.js";
+import { ERROR_CLASS } from "../brain/agent-error-classifier.js";
+
+// KJC-TSK-0859: the agents no longer substitute a dead model behind your back,
+// so the command needs the declared chain. A one-shot CLI must not inherit the
+// pipeline's standby either: sleeping five hours inside `kj code` would be
+// worse than the failure. A quota wall takes the next candidate at once, and
+// with none left it stops and says what it tried.
+const ONE_SHOT_POLICY = Object.freeze({
+  ...DEFAULT_RECOVERY_POLICY,
+  classes: {
+    ...DEFAULT_RECOVERY_POLICY.classes,
+    [ERROR_CLASS.QUOTA_EXHAUSTED_DAILY]: { mode: "abort", maxRetries: 0, fallbackEligible: true, fallbackImmediate: true },
+    [ERROR_CLASS.QUOTA_EXHAUSTED_MONTHLY]: { mode: "abort", maxRetries: 0, fallbackEligible: true, fallbackImmediate: true },
+  },
+});
 import { withCliRunLog } from "../utils/cli-run-log.js";
 import { createCliProgressReporter } from "../utils/cli-progress.js";
 
-export async function codeCommand({ task, config, logger }) {
+export async function codeCommand({ task, config, logger, flags = {} }) {
   return withCliRunLog("code", { projectDir: config?.projectDir, logger }, async ({ runLog }) => {
     const coderRole = resolveRole(config, "coder");
+    // KJC-TSK-0864: no quota, not authenticated or simply absent? This THROWS
+    // with the agent named. The one thing it never does is quietly fall back
+    // to whoever happens to be reachable.
     await assertAgentsAvailable([coderRole.provider]);
     logger.info(`Coder (${coderRole.provider}) starting...`);
     runLog.logText(`[coder] provider=${coderRole.provider}`);
@@ -21,11 +43,39 @@ export async function codeCommand({ task, config, logger }) {
         try { coderRules = await fs.readFile("coder-rules.md", "utf8"); } catch { /* no coder rules file */ }
       }
     }
-    const prompt = await buildCoderPrompt({ task, coderRules, methodology: config.development?.methodology || "tdd" });
+    const card = await resolveCardContext({ projectDir: config.projectDir, ref: flags.card || null });
+    if (card?.external) logger.warn(`card ${card.huId} lives on a board kj cannot read — passing the reference, not its text`);
+    else if (card) logger.info(`Card ${card.huId}: ${card.title}`);
+    // The method's first invariant is that the RAG answers before you assume.
+    // The session asks on the coder's behalf: a subprocess coder cannot run
+    // `kj rag query` itself, so it used to guess the codebase instead.
+    const rag = await resolveRagContext({ task, config, logger });
+    // The pipeline always passed projectDir (it arms the directory-boundary
+    // rule and the skills section) and the provider. `kj code` did not, so the
+    // declared coder got a weaker prompt from the session than from `kj run`.
+    const prompt = await buildCoderPrompt({
+      task: composeTask(task, [card?.section, rag?.section]),
+      coderRules,
+      methodology: config.development?.methodology || "tdd",
+      projectDir: config.projectDir,
+      provider: coderRole.provider,
+      huId: card?.huId ?? null,
+      acceptanceTests: card?.acceptanceTests ?? null,
+      serenaEnabled: Boolean(config.serena?.enabled),
+      rtkAvailable: Boolean(config.rtk?.available),
+    });
     const progress = createCliProgressReporter({ role: "coder" });
     let result;
     try {
-      result = await coder.runTask({ prompt, onOutput: progress.onOutput, role: "coder" });
+      result = await withBrainRecovery({
+        agent: { runTask: (args) => coder.runTask(args), provider: coderRole.provider, model: coderRole.model },
+        taskArgs: { prompt, onOutput: progress.onOutput, role: "coder" },
+        role: "coder",
+        provider: coderRole.provider,
+        logger,
+        policy: ONE_SHOT_POLICY,
+        fallback: buildRoleFallbackChain({ config, role: "coder", logger }),
+      });
       progress.finish(result.ok ? "done" : "failed");
     } catch (err) { progress.finish("failed"); throw err; }
     if (!result.ok) {
@@ -39,7 +89,10 @@ export async function codeCommand({ task, config, logger }) {
       logger.warn(result.error);
     }
     logger.info(`Coder completed (exit ${result.exitCode})`);
+    // The work is in the tree, not committed: the gate is the next step and a
+    // DIFFERENT AI runs it. Saying so here is what keeps the panel honest.
+    logger.info(`The work is in the tree. Review it before committing: kj review --staged (a different AI than ${coderRole.provider}).`);
     runLog.logText(`[coder] finished (exit=${result.exitCode})`);
-    return { ok: true };
+    return { ok: true, provider: coderRole.provider, card: card?.huId ?? null, ragSources: rag?.sources ?? [] };
   });
 }

package/src/commands/env.js

@@ -71,6 +71,7 @@ export async function envInstallCommand({ config = null, logger = null, flags =
     projectDir, target: flags.target || "all",
     stateBackend: config?.state_backend || "hu-board",
     boardName: config?.board?.name || null,
+    config, // KJC-TSK-0865: the panel travels with the method
   });
   console.log(`✓ Karajan playbook installed in: ${result.files.join(", ")}`);
 
@@ -213,7 +214,7 @@ export async function envInstallCommand({ config = null, logger = null, flags =
     // CLAUDE.md, but the running session loaded its context BEFORE — nobody
     // re-reads it. Print the method so it enters THIS conversation now.
     console.log("\n— The Karajan method below is IN EFFECT from this very message. If your session started before this install, apply it from now on:\n");
-    console.log(renderPlaybook({ stateBackend: config?.state_backend || "hu-board", boardName: config?.board?.name || null }));
+    console.log(renderPlaybook({ stateBackend: config?.state_backend || "hu-board", boardName: config?.board?.name || null, config }));
   }
   return result;
 }

package/src/commands/harden.js

@@ -171,7 +171,9 @@ export async function hardenCommand({
     ? installWorkflows({ projectDir, language: roots[0]?.language ?? null, profile, mutation, dryRun })
     : null;
   const withGuidelines = guidelines && profile !== "minimal";
-  const gl = withGuidelines ? installGuidelines({ projectDir, dryRun }) : null;
+  // KJC-BUG-0199 (issue #1773): the same detected language the workflows and
+  // the configs already use — a Python project must not be told to use `const`.
+  const gl = withGuidelines ? installGuidelines({ projectDir, language: roots[0]?.language ?? null, dryRun }) : null;
   const out = {
     ok: true,
     ...result,

package/src/commands/review-gate.js

@@ -22,6 +22,7 @@ import { checkCardFirst } from "../review/card-first.js";
 import { liftSealedSupervisorViolations } from "../policy/supervisor-verify.js";
 import { checkTestsWithCode } from "../review/tests-with-code.js";
 import { loadPrivacyList, scanText } from "../privacy/scan.js";
+import { isGeneratedPath, splitAddedByFile } from "../privacy/diff-scope.js";
 import { checkStagedDiff, loadPolicy } from "../policy/engine.js";
 import { loadStandingExceptions, recordPolicyException } from "../policy/exceptions.js";
 import { policyFileHash, recordGateDecision } from "../policy/decisions.js";
@@ -230,17 +231,24 @@ export async function reviewGateCommand({ config, logger = null, flags = {} }) {
   // don't publish. In the SEA binary the privacy module is stubbed and
   // throws: the gate degrades with a note instead of crashing.
   try {
-    const added = diff.split("\n").filter((l) => l.startsWith("+") && !l.startsWith("+++")).map((l) => l.slice(1)).join("\n");
-    const findings = scanText(added, { list: loadPrivacyList(), source: "<staged diff>" });
+    // KJC-BUG-0203: per file, so a finding can name where it lives and so
+    // build output is judged as what it is. Generic heuristics are silenced
+    // there (nobody typed a minified bundle); a denylist hit is not, because
+    // the incident behind this scanner was personal data inside a build.
+    const list = loadPrivacyList();
+    const findings = splitAddedByFile(diff).flatMap(({ file, added }) => {
+      const found = scanText(added, { list, source: file });
+      return isGeneratedPath(file) ? found.filter((f) => f.severity === "block") : found;
+    });
     const blocks = findings.filter((f) => f.severity === "block");
     const warns = findings.filter((f) => f.severity === "warn");
-    for (const f of warns) console.log(`⚠ privacy: [${f.type}] added line ${f.line} → ${f.masked} — personal data? move it out before it ships`);
+    for (const f of warns) console.log(`⚠ privacy: [${f.type}] ${f.source}:${f.line} → ${f.masked} — personal data? move it out before it ships`);
     const hardened = config?.privacy?.generic === "block" && warns.length > 0;
     if (blocks.length > 0 || hardened) {
       if (process.env.KJ_ALLOW_PII === "1") {
         console.log(`⚠ privacy exempt: ${blocks.length} denylist hit(s) — KJ_ALLOW_PII=1 (explicit escape hatch)`);
       } else {
-        for (const f of blocks) console.log(`✗ privacy: [${f.type}] on added line ${f.line} → ${f.masked}`);
+        for (const f of blocks) console.log(`✗ privacy: [${f.type}] ${f.source}:${f.line} → ${f.masked}`);
         const reason = `${blocks.length || warns.length} personal-data finding(s) in the staged diff — this must not reach the repo (KJ_ALLOW_PII=1 to override consciously)`;
         console.log(`✗ privacy gate: ${reason}`);
         process.exitCode = 1;

package/src/environment/panel.js

@@ -0,0 +1,52 @@
+/**
+ * The project's panel, said out loud (KJC-TSK-0865).
+ *
+ * The user chooses who writes and who reviews. `kj run` honoured that choice
+ * because it launched the agents itself; since v4 the HOST agent orchestrates,
+ * and nothing carried the choice into the session, so the host wrote the code
+ * and the user found out by accident.
+ *
+ * The panel line travels with the playbook, which is what every host reads at
+ * session start. It ANNOUNCES, it never blocks: the host may still write the
+ * code, and then it says so instead of staying quiet.
+ */
+import { resolveRole } from "../config/role-resolver.js";
+
+/** Roles worth announcing: who writes, who reviews, who arbitrates. */
+export const PANEL_ROLES = ["coder", "reviewer", "solomon"];
+
+/**
+ * @returns {{coder: string|null, reviewer: string|null, solomon: string|null}}
+ *   the provider declared (or inherited) for each panel role.
+ */
+export function resolvePanel(config) {
+  const panel = {};
+  for (const role of PANEL_ROLES) panel[role] = resolveRole(config, role).provider || null;
+  return panel;
+}
+
+/**
+ * One agent-facing line naming the panel, or null when the project declares
+ * no coder and no reviewer. A project without a panel gets no line at all:
+ * announcing "coder: nobody" would spend attention to say nothing.
+ */
+export function panelLine(config) {
+  const { coder, reviewer, solomon } = resolvePanel(config);
+  if (!coder && !reviewer) return null;
+  const parts = [`coder=${coder || "unset"}`, `reviewer=${reviewer || "unset"}`];
+  if (solomon && solomon !== coder) parts.push(`solomon=${solomon}`);
+  return [
+    `- The panel is your user's, not yours: ${parts.join(", ")}.`,
+    "  When the coder is not you, the writing is ITS job; write it yourself",
+    "  anyway and say so in your closing message, never in silence.",
+  ].join("\n");
+}
+
+/** Human-facing one-liner for `kj check` and friends. */
+export function panelSummary(config) {
+  const { coder, reviewer, solomon } = resolvePanel(config);
+  if (!coder && !reviewer) return "panel: not declared (no coder, no reviewer)";
+  const parts = [`coder ${coder || "unset"}`, `reviewer ${reviewer || "unset"}`];
+  if (solomon && solomon !== coder) parts.push(`solomon ${solomon}`);
+  return `panel: ${parts.join(" · ")}`;
+}

package/src/environment/playbook.js

@@ -12,6 +12,7 @@
 import fs from "node:fs/promises";
 import path from "node:path";
 import { upsertManagedBlock } from "../utils/managed-markers.js";
+import { panelLine } from "./panel.js";
 
 // AB-A (KJC-TSK-0650): any agent can be the brain. AGENTS.md is the
 // emerging standard (Codex, Cursor and most new CLIs read it); GEMINI.md
@@ -48,7 +49,7 @@ function trackingLine(stateBackend, boardName) {
 // AB-C2 (KJC-TSK-0653): outcome-first — invariants over step scripts.
 // Frontier models choose their own path best; what they need explicit are
 // the limits. The git gates enforce these regardless of what any brain does.
-const playbookBody = (stateBackend, boardName) => `# Karajan method (v4)
+const playbookBody = (stateBackend, boardName, panel) => `# Karajan method (v4)
 
 You are the orchestrator; Karajan governs. A task is DONE when its
 done-statement is literally true, the full suite is green, and every commit
@@ -68,7 +69,7 @@ Invariants (the git gates enforce these — they are not suggestions):
 - Every diff is reviewed by a DIFFERENT AI before it is committed
   (\`kj review --staged\`): verdicts bind to the exact diff — change the code
   and it must be reviewed again. Disagree with a rejection? \`kj solomon\`.
-- Security findings are never overridable — not even by arbitration. You
+${panel ? `${panel}\n` : ""}- Security findings are never overridable — not even by arbitration. You
   absorb the security role: \`kj brief security\` states what must be true.
   Task touches auth, user input, secrets, network or deps? Run
   \`kj audit --security\` (zero tokens) and remediate BEFORE the review.
@@ -100,15 +101,15 @@ kj announces a newer version? Tell your user what it brings and ask —
 never run \`kj update\` on your own.
 `;
 
-export function renderPlaybook({ stateBackend = "hu-board", boardName = null } = {}) {
-  return playbookBody(stateBackend, boardName);
+export function renderPlaybook({ stateBackend = "hu-board", boardName = null, config = null } = {}) {
+  return playbookBody(stateBackend, boardName, panelLine(config));
 }
 
 /**
  * Install/refresh the playbook block in the target agent files.
  * User content outside the managed block is never touched.
  */
-export async function installPlaybook({ projectDir, target = "all", version = "1", stateBackend = "hu-board", boardName = null }) {
+export async function installPlaybook({ projectDir, target = "all", version = "1", stateBackend = "hu-board", boardName = null, config = null }) {
   if (!PLAYBOOK_TARGETS.includes(target)) {
     throw new Error(`unknown target "${target}" — use one of: ${PLAYBOOK_TARGETS.join(", ")}`);
   }
@@ -118,7 +119,7 @@ export async function installPlaybook({ projectDir, target = "all", version = "1
     let source = "";
     try { source = await fs.readFile(fullPath, "utf8"); } catch { /* new file */ }
     const { content, action } = upsertManagedBlock({
-      source, blockId: "playbook", version, body: renderPlaybook({ stateBackend, boardName }), style: "html",
+      source, blockId: "playbook", version, body: renderPlaybook({ stateBackend, boardName, config }), style: "html",
       note: "do not edit: regenerated by kj env install",
     });
     if (action !== "unchanged") await fs.writeFile(fullPath, content);

package/src/harden/config-templates.js

@@ -90,9 +90,14 @@ export const GOLANGCI_BODY = [
 ].join("\n");
 
 /** Language-agnostic configs (every stack gets these). */
+// KJC-BUG-0201 (issue #1774, reported from the field): commitlint used to live
+// here, so a Python repo needed a Node runtime just to validate commit
+// messages. The generated commit-msg hook ALREADY enforces that contract in
+// pure sh (Conventional Commits, the 100-char cap, the AI-attribution ban), so
+// nothing is lost by scoping the tool to the stack that already has Node. The
+// GUARANTEE is language-agnostic; the tool does not have to be.
 export const UNIVERSAL_CONFIGS = [
   { file: ".editorconfig", blockId: "editorconfig", style: "hash", body: EDITORCONFIG_BODY },
-  { file: "commitlint.config.js", blockId: "commitlint", style: "slash", body: COMMITLINT_BODY },
 ];
 
 /**
@@ -102,6 +107,7 @@ export const UNIVERSAL_CONFIGS = [
  * tool is decorative, and kj never generates a demand it didn't satisfy.
  */
 export const JS_CONFIGS = [
+  { file: "commitlint.config.js", blockId: "commitlint", style: "slash", body: COMMITLINT_BODY },
   { file: "eslint.config.js", blockId: "eslint", style: "slash", body: ESLINT_BODY, requires: "eslint" },
   { file: ".prettierrc.json", json: true, body: PRETTIER_BODY, requires: "prettier" },
 ];

package/src/harden/guidelines-engine.js

@@ -9,7 +9,7 @@ import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 
 import { upsertManagedBlock } from "../utils/managed-markers.js";
-import { GUIDELINES_BODY } from "./guidelines-templates.js";
+import { guidelinesBody } from "./guidelines-templates.js";
 
 const BLOCK_VERSION = 1;
 const TARGETS = ["AGENTS.md", "CLAUDE.md"];
@@ -28,7 +28,11 @@ export function stripDevHooksBlock(source) {
   return { content: `${before}${joiner}${after}`, migrated: true };
 }
 
-export function installGuidelines({ projectDir = process.cwd(), dryRun = false } = {}) {
+export function installGuidelines({ projectDir = process.cwd(), dryRun = false, language = null } = {}) {
+  // KJC-BUG-0199 (issue #1773): the rules that enter the agent's context must
+  // be the rules of THIS project's language. kj harden already detects it for
+  // the configs; the guidelines just never asked.
+  const body = guidelinesBody(language);
   const results = [];
   for (const file of TARGETS) {
     const target = join(projectDir, file);
@@ -38,7 +42,7 @@ export function installGuidelines({ projectDir = process.cwd(), dryRun = false }
       source,
       blockId: "guidelines",
       version: BLOCK_VERSION,
-      body: GUIDELINES_BODY,
+      body,
       style: "html",
     });
     if (!dryRun && (migrated || action !== "unchanged")) writeFileSync(target, content);

package/src/harden/guidelines-templates.js

@@ -7,14 +7,21 @@
  * bloat dilutes the signal. Distilled from the dev-toolkit guidelines.
  */
 
-export const GUIDELINES_BODY = [
+// KJC-BUG-0199 (issue #1773, reported from the field): this used to be ONE
+// fixed text, so a Python project was told to use `const`, target ES2025 and
+// prefer ES modules over require. These rules enter the agent's context on
+// EVERY run, so the noise is not harmless: it dilutes the signal and states
+// things that do not apply. The configs were already language-aware (ruff for
+// Python, golangci for Go); the guidelines had not caught up.
+//
+// Shape: a CORE that holds in any language, plus one block per language. A
+// language kj does not know gets the core ALONE, never another language's
+// rules, which is the failure this fixes.
+const CORE = [
   "# Project guidelines (kj harden)",
   "",
   "## Code",
-  "- SOLID, DRY, KISS, YAGNI. `const` by default; arrow callbacks; template literals.",
-  "- ES2025 target: never `var`, `document.write`, `alert`/`confirm`/`prompt`, `escape`/`unescape`, `substr`.",
-  "  Prefer modern APIs (`structuredClone`, `Object.groupBy`, `Array.at`/`findLast`/`toSorted`, optional chaining, `??`).",
-  "- ES modules (`import`/`export`), never `require` in new code. Names in English, descriptive.",
+  "- SOLID, DRY, KISS, YAGNI. Names in English, descriptive.",
   "- No silent fallbacks: the system works or fails loudly. Validate and sanitize all input.",
   "",
   "## Commits & PRs",
@@ -26,11 +33,54 @@ export const GUIDELINES_BODY = [
   "- Test-first. Run the tests after each meaningful change. Never skip tests.",
   "",
   "## Security",
-  "- Never commit secrets, keys or tokens. Parameterized queries; sanitize output against XSS.",
-  "",
-  "## UI/UX",
-  "- No native `alert`/`confirm`/`prompt` — use the app's modal system. Loading states; accessible; mobile-first.",
+  "- Never commit secrets, keys or tokens. Parameterized queries; sanitize output against injection.",
   "",
   "## Files",
   "- Edit existing files in place; never overwrite a whole file to make a small change.",
-].join("\n");
+];
+
+/** Per-language rules. A language absent from here gets the core alone. */
+export const LANGUAGE_GUIDELINES = {
+  javascript: [
+    "",
+    "## JavaScript / TypeScript",
+    "- `const` by default; arrow callbacks; template literals.",
+    "- ES2025 target: never `var`, `document.write`, `alert`/`confirm`/`prompt`, `escape`/`unescape`, `substr`.",
+    "  Prefer modern APIs (`structuredClone`, `Object.groupBy`, `Array.at`/`findLast`/`toSorted`, optional chaining, `??`).",
+    "- ES modules (`import`/`export`), never `require` in new code. Avoid `any` in TypeScript.",
+    "",
+    "## UI/UX",
+    "- No native `alert`/`confirm`/`prompt` — use the app's modal system. Loading states; accessible; mobile-first.",
+  ],
+  python: [
+    "",
+    "## Python",
+    "- PEP 8, and type hints on every public signature. Prefer `pathlib` over string paths.",
+    "- Never a bare `except:` — catch what you can handle and let the rest fail loudly.",
+    "- f-strings over concatenation or `%`. Comprehensions when they read better than a loop, not by default.",
+    "- Tooling and dependencies declared in `pyproject.toml`; no other language's runtime imposed on the project.",
+  ],
+  go: [
+    "",
+    "## Go",
+    "- `gofmt` is not negotiable. Errors are values: wrap with `%w` and handle them where the caller can decide.",
+    "- No naked returns in long functions; accept interfaces, return structs.",
+    "- Concurrency with a purpose: a goroutine with no way to stop it is a leak.",
+  ],
+  rust: [
+    "",
+    "## Rust",
+    "- `cargo fmt` and `cargo clippy` clean before a commit.",
+    "- No `unwrap()` outside tests: propagate with `?` and let the type say what can fail.",
+    "- `unsafe` needs a comment naming the invariant that makes it sound.",
+  ],
+};
+
+/** The guidelines body for a language (unknown or absent ⇒ the core alone). */
+export function guidelinesBody(language = null) {
+  const extra = LANGUAGE_GUIDELINES[String(language || "").toLowerCase()] ?? [];
+  return [...CORE, ...extra].join("\n");
+}
+
+/** Back-compat for callers that predate the language split. */
+export const GUIDELINES_BODY = guidelinesBody("javascript");

package/src/harden/hook-templates.js

@@ -126,7 +126,10 @@ export function hookBody(hook, cmds = {}, { globalHooksDir = null, baseBranch =
         "# KJC-BUG-0170: the generated supervisor hooks (.karajan/hooks/pre-commit,",
         "# commit-msg) also CONTAIN the pattern by design — the bootstrap commit",
         "# that versions them must not self-detect in the consumer repo.",
-        `if git diff --cached -- . ':(exclude).github/workflows/kj-no-ai-attribution.yml' ':(exclude)src/harden/hook-templates.js' ':(exclude)src/harden/workflow-templates.js' ':(exclude)src/harden/sentinel-hooks.js' ':(exclude)scripts/ai-attribution-guard.yml' ':(exclude)tests/harden/attribution-guard.test.js' ':(exclude)tests/harden/sentinel-hooks.test.js' ':(exclude).karajan/hooks/pre-commit' ':(exclude).karajan/hooks/commit-msg' | grep '^+' | grep -qiE '${AI_ATTRIBUTION}|generated with \\[?claude'; then`,
+        "# KJC-BUG-0200 (issue #1772): the same is true of .karajan/harness — the",
+        "# whole DIRECTORY is excluded, not one file, so a supervisor script added",
+        "# later cannot bring the bug back.",
+        `if git diff --cached -- . ':(exclude).github/workflows/kj-no-ai-attribution.yml' ':(exclude)src/harden/hook-templates.js' ':(exclude)src/harden/workflow-templates.js' ':(exclude)src/harden/sentinel-hooks.js' ':(exclude)scripts/ai-attribution-guard.yml' ':(exclude)tests/harden/attribution-guard.test.js' ':(exclude)tests/harden/sentinel-hooks.test.js' ':(exclude).karajan/hooks/pre-commit' ':(exclude).karajan/hooks/commit-msg' ':(exclude).karajan/harness/' | grep '^+' | grep -qiE '${AI_ATTRIBUTION}|generated with \\[?claude'; then`,
         "  echo 'kj harden: AI attribution is not allowed in committed content'; exit 1",
         "fi",
         "# v4 review gate (ENV-C1, opt-in via `kj review --install-gate`):",