karajan-code 4.31.1 → 4.33.0

package/src/commands/review-gate.js

@@ -15,12 +15,14 @@ import { ensureGateTrackable } from "../review/gate-gitignore.js";
 import { runSonarPregate, formatSonarFinding, addedLinesByFile } from "../review/sonar-pregate.js";
 import { checkSonarRequirement, SONAR_RULE_ID } from "../review/sonar-requirement.js";
 import { checkRagRequirement, checkRagVerdict, ragBlock, RAG_RULE_ID } from "../review/rag-requirement.js";
+import { checkUiEvidence, uiBlock } from "../review/ui-evidence.js";
 import { readRagLedger } from "../review/rag-ledger.js";
 import { runMutationPregate, formatSurvivor } from "../review/mutation-pregate.js";
 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";
@@ -229,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;
@@ -482,6 +491,20 @@ export async function reviewGateCommand({ config, logger = null, flags = {} }) {
       + twins.map((t) => `- ${t}`).join("\n");
   }
 
+  // BOOT-D (KJC-TSK-0863): green is not proof for what a person SEES. kj does
+  // not drive the browser (the host has it); it demands the walkthrough and
+  // records it in the verdict, bound to the diff like sonar and rag. It WARNS:
+  // the last proof, never the only one, and a gate that fires often teaches
+  // people to skip gates.
+  const walked = Array.isArray(flags.walked) ? flags.walked : [];
+  const uiReq = checkUiEvidence({
+    stagedFiles: changedFiles,
+    evidence: walked.length > 0 ? { walked, tool: flags.walkedWith ?? null } : null,
+    standingExceptions: std.standing,
+  });
+  if (uiReq.warn) console.log(`⚠ ${uiReq.reason}`);
+  const uiRecord = uiBlock(uiReq);
+
   // MUT-A (KJC-TSK-0716): mutation pre-gate — opt-in (method_gates.mutation),
   // SOLO en --staged (jamás en pre-commit: cuesta minutos; y jamás en --range:
   // el scope es el ÍNDICE y anotaría trabajo ajeno — catch de codex). block
@@ -504,7 +527,7 @@ export async function reviewGateCommand({ config, logger = null, flags = {} }) {
     }
   }
 
-  const record = await runOneShotReview({ diff, task, config, logger, projectDir, sonar: sonarRecord, rag: ragRecord });
+  const record = await runOneShotReview({ diff, task, config, logger, projectDir, sonar: sonarRecord, rag: ragRecord, ui: uiRecord });
   printVerdict(record);
   process.exitCode = record.verdict === "approved" ? 0 : 1;
   return record;

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`):",

package/src/privacy/diff-scope.js

@@ -0,0 +1,58 @@
+/**
+ * Which part of a diff the privacy gate reads, and how (KJC-BUG-0203).
+ *
+ * The gate used to concatenate every added line of the diff and scan the lump.
+ * Two consequences: a finding could not name the file it came from, and build
+ * output got judged as if a person had written it. A minified Starlight page
+ * warned twice for `[phone]` over an Astro class hash, which is the kind of
+ * false alarm that teaches people to skip the gate.
+ *
+ * The exemption is by SEVERITY, not by file. Generic heuristics (a shape that
+ * could be a phone, a card, an id) are silenced on generated output, where
+ * nobody typed anything. A denylist hit is NOT: the incident that created this
+ * scanner was personal emails published on a landing, which is exactly a
+ * denylist datum inside a build artifact.
+ *
+ * `kj privacy scan <dir>` is untouched. Scanning an artifact you are about to
+ * publish must keep looking at everything, generated or not.
+ */
+
+/** Paths that are build output in this project's own vocabulary. */
+const GENERATED = [
+  /(^|\/)dist\//,
+  /(^|\/)build\//,
+  /(^|\/)coverage\//,
+  /(^|\/)node_modules\//,
+  /(^|\/)\.astro\//,
+  /(^|\/)public\/docs\//,
+  /\.min\.(js|css)$/,
+  /\.map$/,
+];
+
+/** @param {string} file @returns {boolean} */
+export function isGeneratedPath(file) {
+  if (!file) return false;
+  return GENERATED.some((re) => re.test(file));
+}
+
+/**
+ * Split a unified diff into its added lines, per file.
+ * @param {string} diff
+ * @returns {Array<{file: string, added: string}>} files with at least one added line
+ */
+export function splitAddedByFile(diff) {
+  const out = [];
+  let current = null;
+  for (const line of String(diff || "").split("\n")) {
+    const header = /^diff --git a\/(?:.+) b\/(.+)$/.exec(line);
+    if (header) {
+      current = { file: header[1], lines: [] };
+      out.push(current);
+      continue;
+    }
+    if (!current) continue;
+    // `+++ b/x` is the header, not content; `+` alone is an added blank line.
+    if (line.startsWith("+") && !line.startsWith("+++")) current.lines.push(line.slice(1));
+  }
+  return out.filter((f) => f.lines.length > 0).map((f) => ({ file: f.file, added: f.lines.join("\n") }));
+}

package/src/privacy/scan.js

@@ -73,6 +73,24 @@ const FIREBASE_KEY_HINT = "si es la clave web de Firebase (publica por diseno):
 const CONTEXT_DISCARDS = [
   { type: "git-sha", re: /\b(?:[0-9a-f]{64}|[0-9a-f]{40})\b/g },
   { type: "doc-domain-email", re: /\b[A-Za-z0-9._%+-]+@(?:[A-Za-z0-9-]+\.)*(?:example\.(?:com|org|net)|test|invalid|localhost|example)\b/g },
+  // KJC-BUG-0202: an HU Board id is `HU-<Date.now()>-<n>`, and Date.now() is
+  // 13 digits — exactly a card's length, so every project using the default
+  // board got a credit-card warning over its own card ids. The rule covers
+  // the family (an alphabetic prefix, a dash, a long digit run: HU-…, KJC-…,
+  // any tracker's) and NOTHING else.
+  //
+  // It deliberately does not go further, and it took three rejections to get
+  // this narrow:
+  //   1. discarding every card-shaped run that fails Luhn — wrong, a
+  //      truncated or mistyped card also fails Luhn and is still sensitive;
+  //   2. any alphabetic prefix — `card-4111111111111111` swallowed;
+  //   3. any uppercase prefix with any digits — `CARD-4111111111111111-1`
+  //      swallowed.
+  // So the middle segment must be an actual millisecond timestamp: exactly 13
+  // digits starting 16-19 (years 2022-2033). No card range begins with a 1
+  // (Visa 4, Mastercard 2/5, Amex 3, Discover 6), so a card number cannot
+  // occupy that slot at any length.
+  { type: "tracker-id", re: /\b[A-Z]{2,6}-1[6-9]\d{11}-\d{1,4}\b/g },
 ];
 
 /**

package/src/prompts/card-context.js

@@ -0,0 +1,57 @@
+/**
+ * The coder gets the CARD, not just a sentence (KJC-TSK-0864).
+ *
+ * `kj code` handed the agent a bare task string: no card, no acceptance
+ * criteria, not even the project boundary the pipeline always passed. That is
+ * the gap the user hit, because when the host orchestrates instead of
+ * `kj run`, `kj code` IS the way the declared coder gets invoked, and a coder
+ * without the card writes to a sentence instead of to a contract.
+ *
+ * A local HU is read from the board. A reference kj cannot read (an external
+ * board lives in the host's own MCP, not here) travels as the reference it is
+ * and says so: the coder learns the card exists and where to ask for it,
+ * instead of receiving a silently empty context.
+ */
+import { getHu } from "../hu/store.js";
+
+/** Ids minted by the HU Board; anything else belongs to an external board. */
+const LOCAL_HU = /^HU-/i;
+
+const externalSection = (ref) =>
+  [
+    `## Card ${ref}`,
+    "",
+    `This work is tracked as ${ref} on the project's own board, which kj cannot read from here.`,
+    "Treat the task below as the card's statement, and if something the card should answer is missing, ASK instead of guessing.",
+  ].join("\n");
+
+const localSection = (hu) => {
+  const lines = [`## Card ${hu.id} — ${hu.title}`, ""];
+  if (hu.description?.trim()) lines.push(hu.description.trim(), "");
+  lines.push(`Status on the board: ${hu.status}. The card is the contract: done means its statement is literally true.`);
+  return lines.join("\n");
+};
+
+/**
+ * @param {{projectDir: string, ref: string|null, deps?: {getHu?: Function}}} args
+ * @returns {Promise<null|{huId: string, title: string|null, section: string,
+ *   acceptanceTests: Array|null, external: boolean}>}
+ */
+export async function resolveCardContext({ projectDir, ref, deps = {} }) {
+  if (!ref?.trim()) return null;
+  const id = ref.trim();
+  if (!LOCAL_HU.test(id)) {
+    return { huId: id, title: null, section: externalSection(id), acceptanceTests: null, external: true };
+  }
+  // A missing local HU is an error, never an empty context: the caller asked
+  // for a card by id and kj either delivers it or says it does not exist.
+  const hu = await (deps.getHu || getHu)(projectDir, id);
+  const criteria = hu.acceptanceCriteria?.trim();
+  return {
+    huId: hu.id,
+    title: hu.title,
+    section: localSection(hu),
+    acceptanceTests: criteria ? [{ type: "gherkin", content: criteria }] : null,
+    external: false,
+  };
+}

package/src/prompts/session-context.js

@@ -0,0 +1,68 @@
+/**
+ * What the coder knows before it writes (KJC-TSK-0864).
+ *
+ * The method's first invariant is "the RAG answers before you assume", and
+ * `kj run` honours it through the researcher stage. `kj code` did not: the
+ * declared coder started from a sentence and guessed the codebase. So the
+ * session asks the index on the coder's behalf and hands it what came back.
+ *
+ * Retrieval is best-effort and LOUD: an empty or unreachable index warns and
+ * the coder works without project context, because blocking here would stop
+ * work in a repo that simply has no index yet. What it never does is stay
+ * quiet about it.
+ */
+import { ragQueryCommand } from "../commands/rag.js";
+
+/** Hits to carry and how much of each: the prompt pays for every line. */
+const TOP_K = 5;
+const EXCERPT = 400;
+
+const label = (hit) =>
+  hit.metadata?.symbol || hit.metadata?.hu_id || hit.metadata?.headingPath?.join(" > ") || hit.kind || "block";
+
+/** @returns {string|null} the agent-facing section, or null when there is nothing to say. */
+export function ragSection(hits) {
+  if (!Array.isArray(hits) || hits.length === 0) return null;
+  const lines = [
+    "## What the project's RAG index answers about this task",
+    "",
+    "Retrieved for you, so you do not guess what the codebase does. These are excerpts: open the file before changing it.",
+    "",
+  ];
+  for (const hit of hits) {
+    const text = hit.text || "";
+    lines.push(`### ${hit.source} · ${label(hit)}`);
+    lines.push("```", text.length > EXCERPT ? `${text.slice(0, EXCERPT)}…` : text, "```", "");
+  }
+  return lines.join("\n");
+}
+
+/**
+ * @returns {Promise<null|{section: string|null, sources: string[]}>}
+ */
+export async function resolveRagContext({ task, config, logger, deps = {} }) {
+  const run = deps.ragQueryCommand || ragQueryCommand;
+  // The index warns on stdout in CLI mode; here the hits are the product, so
+  // its narration is swallowed and only OUR verdict reaches the user.
+  const quiet = { info: () => {}, warn: () => {}, error: () => {} };
+  let hits;
+  try {
+    hits = await run({ text: task, config, logger: quiet, flags: { topK: TOP_K } });
+  } catch (err) {
+    logger?.warn?.(`rag context unavailable (${err.message}) — the coder writes without project context`);
+    return null;
+  }
+  if (!hits?.length) {
+    logger?.warn?.("the RAG index returned nothing for this task — the coder writes without project context");
+    return null;
+  }
+  const sources = [...new Set(hits.map((h) => h.source))];
+  logger?.info?.(`RAG context: ${sources.length} file(s) — ${sources.join(", ")}`);
+  return { section: ragSection(hits), sources };
+}
+
+/** The task the coder reads: everything it was given, then its own statement. */
+export function composeTask(task, sections = []) {
+  const kept = sections.filter(Boolean);
+  return kept.length ? `${kept.join("\n\n")}\n\n## Task\n\n${task}` : task;
+}

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

@@ -47,6 +47,8 @@ export async function runOneShotReview({
   sonar = null,
   // KJC-TSK-0849 (ADR 0010): what the session's RAG ledger proved, same place.
   rag = null,
+  // BOOT-D (KJC-TSK-0863): the walkthrough of what a person sees, same place.
+  ui = null,
   hostAgent = detectHostAgent(),
   createAgentFn = createAgent,
   detectAgents = detectAvailableAgents,
@@ -129,6 +131,9 @@ export async function runOneShotReview({
     summary: parsed.summary || parsed.raw_summary || "",
     ...(sonar ? { sonar } : {}),
     ...(rag ? { rag } : {}),
+    // BOOT-D (KJC-TSK-0863): the walkthrough of what a person sees travels with
+    // the verdict, bound to this diff, like the other two proofs.
+    ...(ui ? { ui } : {}),
     confidence: parsed.confidence ?? null,
   });
 }

package/src/review/ui-evidence.js

@@ -0,0 +1,65 @@
+/**
+ * BOOT-D (KJC-TSK-0863) — the done-statement of something a person SEES is not
+ * proved by a green suite.
+ *
+ * The Anthropic write-up on long-running agents reports it as an observed
+ * failure: the agent marked features complete without checking them. This
+ * codebase has the same hole. `impeccable` gives an AI OPINION about the diff,
+ * which is precisely what KJC-TSK-0726 rejects; what is missing is the proof
+ * that the route works when a person walks it.
+ *
+ * kj does not drive the browser: the host already has Chrome DevTools, and
+ * duplicating that would tie kj to one runner. kj DEMANDS the evidence and
+ * records it in the verdict, bound to the diff, exactly as it does with sonar
+ * and rag.
+ *
+ * It WARNS, it does not block. The article itself admits the browser misses
+ * native modals, so this is the last proof, never the only one — and a gate
+ * that fails often teaches people to skip gates, which is the doctrine behind
+ * every other rule here.
+ */
+
+export const UI_RULE_ID = "method.ui.evidence";
+
+// What a person can actually see. Deliberately narrow: a false demand costs
+// more than a missed one while this only warns.
+const VISIBLE = /\.(jsx|tsx|vue|svelte|astro|css|scss|sass|less|html)$/i;
+
+const liveGrant = (standingExceptions, now) => (standingExceptions || []).find((e) => {
+  if (e?.rule_id !== UI_RULE_ID) return false;
+  const until = Date.parse(e?.expiresAt ?? "");
+  return Number.isFinite(until) && until > now.getTime();
+});
+
+/**
+ * @returns {{ok: boolean, mode: "not-visible"|"walked"|"granted"|"missing", visible: string[], warn?: boolean, reason?: string, evidence?: object, grant?: object}}
+ */
+export function checkUiEvidence({ stagedFiles = [], evidence = null, standingExceptions = [], now = new Date() } = {}) {
+  const visible = stagedFiles.filter((f) => VISIBLE.test(String(f)));
+  if (visible.length === 0) return { ok: true, mode: "not-visible", visible };
+
+  const walked = Array.isArray(evidence?.walked) ? evidence.walked.filter(Boolean) : [];
+  if (walked.length > 0) return { ok: true, mode: "walked", visible, evidence: { walked, tool: evidence.tool ?? null } };
+
+  const grant = liveGrant(standingExceptions, now);
+  if (grant) return { ok: true, mode: "granted", visible, grant };
+
+  return {
+    ok: true,
+    warn: true,
+    mode: "missing",
+    visible,
+    reason: `verde no es prueba: ${visible.length} fichero(s) que una persona VE (${visible.join(", ")}) sin recorrido comprobado — recórrelo como lo haría ella y deja constancia`,
+  };
+}
+
+/** The block that travels inside the verdict, bound to the diff like sonar's. */
+export function uiBlock(req) {
+  if (!req || req.mode === "not-visible") return null;
+  return {
+    mode: req.mode,
+    walked: req.evidence?.walked ?? [],
+    tool: req.evidence?.tool ?? null,
+    visible: req.visible ?? [],
+  };
+}