karajan-code 4.63.0 → 4.64.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "karajan-code",
-  "version": "4.63.0",
+  "version": "4.64.0",
   "description": "Local multi-agent coding orchestrator with TDD, SonarQube, and code review pipeline",
   "type": "module",
   "license": "AGPL-3.0",

package/src/cli/advanced-commands.js

@@ -33,7 +33,7 @@ export const META_COMMANDS = ["advanced", "help"];
 export const ADVANCED_GROUPS = [
   { title: "Pipeline (piezas sueltas)", commands: ["autorun", "code", "review", "solomon", "agent", "scan", "tournament"] },
   { title: "Análisis pre-run", commands: ["discover", "triage", "researcher", "architect", "onboard", "brief"] },
-  { title: "Búsqueda / RAG", commands: ["rag", "qmd", "watch"] },
+  { title: "Búsqueda / RAG", commands: ["rag", "qmd", "watch", "doc"] },
   { title: "Calidad / auditoría", commands: ["audit", "check", "mutate", "webperf", "sonar", "privacy", "release", "policy", "rules", "rulesync", "claims", "steward", "pr-size"] },
   { title: "Sesión / board", commands: ["resume", "report", "board", "hu", "adr", "worktree", "undo", "standby", "sentinel", "identity", "security", "handoff"] },
   { title: "Infra / setup", commands: ["install-tools", "ollama", "skills", "roles", "agents", "env"] },

package/src/cli/register-meta.js

@@ -29,6 +29,7 @@ import { mutateCommand } from "../commands/mutate.js";
 import { hardenCommand } from "../commands/harden.js";
 import { telemetryPreviewCommand, telemetryStatusCommand } from "../commands/telemetry.js";
 import { envInstallCommand, briefCommand } from "../commands/env.js";
+import { docCommand } from "../commands/doc.js";
 import { runReleaseCheck } from "../checks/release-check.js";
 import { agentRunCommand } from "../commands/agent-run.js";
 import { reportIssueCommand } from "../commands/report-issue.js";
@@ -75,7 +76,7 @@ export function registerMeta(program, { pkgVersion }) {
     .action(async (task, flags) => {
       await withConfig(pkgVersion, "discover", flags, async ({ config, logger }) => {
         const { resolveTaskInput } = await import("../utils/task-file.js");
-        const resolvedTask = await resolveTaskInput({ task, taskFile: flags.taskFile, projectDir: config.projectDir, logger });
+        const resolvedTask = await resolveTaskInput({ task, taskFile: flags.taskFile, projectDir: config.projectDir, logger, indexFirstBytes: config.docs?.indexFirstBytes });
         await discoverCommand({ task: resolvedTask, config, logger, mode: flags.mode, json: flags.json });
       });
     });
@@ -91,7 +92,7 @@ export function registerMeta(program, { pkgVersion }) {
     .action(async (task, flags) => {
       await withConfig(pkgVersion, "triage", flags, async ({ config, logger }) => {
         const { resolveTaskInput } = await import("../utils/task-file.js");
-        const resolvedTask = await resolveTaskInput({ task, taskFile: flags.taskFile, projectDir: config.projectDir, logger });
+        const resolvedTask = await resolveTaskInput({ task, taskFile: flags.taskFile, projectDir: config.projectDir, logger, indexFirstBytes: config.docs?.indexFirstBytes });
         await triageCommand({ task: resolvedTask, config, logger, json: flags.json });
       });
     });
@@ -106,7 +107,7 @@ export function registerMeta(program, { pkgVersion }) {
     .action(async (task, flags) => {
       await withConfig(pkgVersion, "researcher", flags, async ({ config, logger }) => {
         const { resolveTaskInput } = await import("../utils/task-file.js");
-        const resolvedTask = await resolveTaskInput({ task, taskFile: flags.taskFile, projectDir: config.projectDir, logger });
+        const resolvedTask = await resolveTaskInput({ task, taskFile: flags.taskFile, projectDir: config.projectDir, logger, indexFirstBytes: config.docs?.indexFirstBytes });
         await researcherCommand({ task: resolvedTask, config, logger });
       });
     });
@@ -123,7 +124,7 @@ export function registerMeta(program, { pkgVersion }) {
     .action(async (task, flags) => {
       await withConfig(pkgVersion, "architect", flags, async ({ config, logger }) => {
         const { resolveTaskInput } = await import("../utils/task-file.js");
-        const resolvedTask = await resolveTaskInput({ task, taskFile: flags.taskFile, projectDir: config.projectDir, logger });
+        const resolvedTask = await resolveTaskInput({ task, taskFile: flags.taskFile, projectDir: config.projectDir, logger, indexFirstBytes: config.docs?.indexFirstBytes });
         await architectCommand({ task: resolvedTask, config, logger, context: flags.context, json: flags.json });
       });
     });
@@ -542,6 +543,29 @@ export function registerMeta(program, { pkgVersion }) {
       });
     });
 
+  // KJC-TSK-1183 — a long markdown document is read by index: the headings first, then only the
+  // sections a task needs, each one whole and exactly as the file has it.
+  const doc = program.command("doc").description("Read a markdown document by index: headings first, whole sections on demand");
+  doc.command("index")
+    .description("List the headings of a markdown file with their level and line (a heading inside a code block is text)")
+    .argument("<file>", "Markdown file")
+    .option("--json", "Machine-readable output")
+    .action(async (file, flags) => {
+      await withConfig(pkgVersion, "doc-index", flags, async () => {
+        docCommand({ action: "index", file, flags });
+      });
+    });
+  doc.command("section")
+    .description("Print one section whole, as the file has it, up to the next heading of the same or a higher level; an unknown heading lists the available ones")
+    .argument("<file>", "Markdown file")
+    .argument("<heading>", "Heading title, exact or case-insensitive")
+    .option("--json", "Machine-readable output")
+    .action(async (file, heading, flags) => {
+      await withConfig(pkgVersion, "doc-section", flags, async () => {
+        docCommand({ action: "section", file, heading, flags });
+      });
+    });
+
   // KJC-TSK-0712 — memory is the reminder, the check is the guarantee.
   const release = program.command("release").description("Release ceremony helpers");
   release.command("check")
@@ -798,7 +822,8 @@ export function registerMeta(program, { pkgVersion }) {
     .option("--alpha <n>", "Deprecated: hybrid fusion is reciprocal rank since 4.63; tune rag.search.rrf_k (default 60) in kj.config.yml", "0.6")
     .option("--where <clause>", "Metadata filter: 'symbol=loadConfig', 'hu_id=HU-003 AND kind=plan', or a prefix with ~= such as 'source~=src/billing' (relative to the project)")
     .option("--library", "Query the distilled engineering canon (pattern cards shipped with kj + ~/.karajan/library, in ~/.karajan/library.db) instead of the project corpus; a project's own .karajan/library cards live in its index and answer normal queries. Cards carry problem signatures, when-NOT-to-apply and canonical citations (KJC-TSK-0697).")
-    .option("--rerank", "Apply cross-encoder rerank to top-K (needs @huggingface/transformers, slower but more precise)")
+    .option("--rerank", "Re-score the top-N candidates with a cross-encoder (needs @huggingface/transformers; or rag.search.rerank.enabled in kj.config.yml)")
+    .option("--rerank-top-n <n>", "Candidates the cross-encoder re-scores before the top-K is cut (default 40, or rag.search.rerank.top_n)")
     .option("--rerank-model <name>", "Cross-encoder model id. Default: Xenova/ms-marco-MiniLM-L-6-v2")
     .option("--json", "Output the hits as JSON")
     .action(async (text, flags) => {
@@ -821,6 +846,8 @@ export function registerMeta(program, { pkgVersion }) {
     .option("--save-baseline <path>", "Write recall@k, MRR and latency to this file as the frozen baseline")
     .option("--baseline <path>", "Fail (exit 1) if recall@k, MRR or p95 latency got worse than that baseline")
     .option("--project <slug>", "Filter by project slug. Pass 'all' to query across every indexed project.")
+    .option("--rerank", "Measure with the cross-encoder rerank on (needs @huggingface/transformers)")
+    .option("--rerank-top-n <n>", "Candidates the cross-encoder re-scores before the top-K is cut (default 40)")
     .option("--json", "Emit the full report as JSON")
     .action(async (flags) => {
       await withConfig(pkgVersion, "rag-eval", flags, async ({ config, logger }) => {

package/src/cli/register-pipeline.js

@@ -153,7 +153,7 @@ export function registerPipeline(program, { pkgVersion }) {
             effectiveTask = plan.task;
           }
         }
-        const resolvedTask = await resolveTaskInput({ task: effectiveTask, taskFile: flags.taskFile, projectDir: config.projectDir, logger });
+        const resolvedTask = await resolveTaskInput({ task: effectiveTask, taskFile: flags.taskFile, projectDir: config.projectDir, logger, indexFirstBytes: config.docs?.indexFirstBytes });
         const res = await runCommandHandler({ task: resolvedTask, config, logger, flags });
         // KJC-TSK-0674 (issue #1289): an aborted run (spec-review cancel,
         // unanswerable non-interactive gate) must be observable by CI.

package/src/cli/register-plan.js

@@ -52,7 +52,7 @@ export function registerPlan(program, { pkgVersion }) {
     .action(async (task, flags) => {
       await withConfig(pkgVersion, "plan", flags, async ({ config, logger }) => {
         const { resolveTaskInput } = await import("../utils/task-file.js");
-        const resolvedTask = await resolveTaskInput({ task, taskFile: flags.taskFile, projectDir: config.projectDir, logger });
+        const resolvedTask = await resolveTaskInput({ task, taskFile: flags.taskFile, projectDir: config.projectDir, logger, indexFirstBytes: config.docs?.indexFirstBytes });
 
         // REASONS Canvas auto-detection: a SPEC that contains
         // `## REASONS:Section` headings is treated as a structured

package/src/commands/doc.js

@@ -0,0 +1,26 @@
+// KJC-TSK-1183 — `kj doc index <file>` and `kj doc section <file> <heading>`: a long markdown
+// document is read by index, the headings first and only the sections a task needs, each one
+// whole and exactly as the file has it. The headings are the index; nothing extra to keep in sync.
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { indexMarkdown, sectionOf } from "../docs/markdown-index.js";
+
+export function docCommand({ action, file, heading = null, flags = {}, cwd = process.cwd(), out = process.stdout }) {
+  if (!file) throw new Error("usage: kj doc index <file> | kj doc section <file> <heading>");
+  const path = resolve(cwd, file);
+  const text = readFileSync(path, "utf8"); // a missing file fails loud, with the path
+  if (action === "index") {
+    const headings = indexMarkdown(text);
+    if (flags.json) out.write(`${JSON.stringify({ file: path, headings })}\n`);
+    else for (const h of headings) out.write(`${"  ".repeat(h.level - 1)}${"#".repeat(h.level)} ${h.title}  (line ${h.line})\n`);
+    return headings;
+  }
+  if (action === "section") {
+    if (!heading) throw new Error("usage: kj doc section <file> <heading>");
+    const section = sectionOf(text, heading);
+    if (flags.json) out.write(`${JSON.stringify({ file: path, ...section })}\n`);
+    else out.write(section.text); // exactly as the file has it, nothing added
+    return section;
+  }
+  throw new Error(`unknown action "${action}": use index | section`);
+}

package/src/commands/hu.js

@@ -14,6 +14,7 @@ import { effectiveGitEmail } from "../identity/detect.js";
 import { roleSkills } from "../skills/role-skills.js";
 import { readBoardConfig, setBoardBackend } from "../hu/board-config.js";
 import { createHu, listHus, claim, setStatus, assertNotHeld, isOffline } from "../hu/github-board.js";
+import { assertGhIdentity } from "../hu/gh-identity.js";
 import { listWithCache, queueMove, flushQueue } from "../hu/team-board-cache.js";
 import { writeTeamMirror } from "../hu/team-board-mirror.js";
 
@@ -196,6 +197,9 @@ export async function huCommand({ config = null, action, args = [], flags = {},
     return emit(r, `✓ HU Board: ${where} — commit ${files} in a PR so the whole team inherits it`);
   }
   const board = await (deps.boardConfig ?? readBoardConfig)(projectDir);
+  // KJC-TSK-1186: the shared board is written as the active gh account; with an identity declared
+  // it must be that one, said with the remedy before any gh call instead of a GraphQL permission error.
+  if (board.backend === "github") (deps.assertGhIdentity ?? assertGhIdentity)({ projectDir });
   const who = deps.who === undefined ? workerOf(projectDir) : deps.who;
   // KJC-TSK-1166 (TEAM-GH-E): the HUs created before the shared board, moved to it once.
   if (action === "migrate") {

package/src/commands/rag.js

@@ -174,7 +174,7 @@ export async function ragQueryCommand({ text, config, logger, flags = {} }) {
     // composed clause cannot leak past the kind filter; it fails loudly.
     let where = flags.where || null;
     if (library) where = flags.where ? `kind=library AND ${flags.where}` : "kind=library";
-    const rerankOpts = flags.rerank ? { model: flags.rerankModel } : null;
+    const rerankOpts = rerankOptionsFor({ config, flags, logger });
     const ranked = await query(db, makeGovernedEmbedder(config), text, { topK, scope, project, mode, rrfK, where, whereRoot, rerankOpts });
     const hits = library ? ranked : withPathNamedHits(pathNamedHits(db, text, { project, projectDir: config?.projectDir || process.cwd() }), ranked, topK);
     if (flags.json) {
@@ -193,6 +193,28 @@ export async function ragQueryCommand({ text, config, logger, flags = {} }) {
   }
 }
 
+// KJC-TSK-1181 (RAG-D2): the cross-encoder, from the flag or from rag.search.rerank in the config
+// (enabled, top_n, model). Without the library or the model the retrieval answers alone and the
+// install is said once per process, never on every query, never in silence.
+const rerankWarned = new Set();
+export function rerankOptionsFor({ config, flags = {}, logger }) {
+  const cfg = config?.rag?.search?.rerank ?? {};
+  const enabled = flags.rerank === true || (flags.rerank !== false && cfg.enabled === true);
+  if (!enabled) return null;
+  const topN = flags.rerankTopN ?? cfg.top_n;
+  if (topN !== undefined && !(Number.isInteger(Number(topN)) && Number(topN) > 0)) throw new Error(`rag.search.rerank.top_n must be a positive integer, got ${JSON.stringify(topN)}`);
+  const key = config?.projectDir || "rerank";
+  return {
+    model: flags.rerankModel || cfg.model || undefined,
+    ...(topN === undefined ? {} : { topN: Number(topN) }),
+    onUnavailable: (err) => {
+      if (rerankWarned.has(key)) return;
+      rerankWarned.add(key);
+      logger.warn(`[rag] rerank skipped: ${err.message}. Install it with npm install @huggingface/transformers; the retrieval answered without it`);
+    },
+  };
+}
+
 // KJC-TSK-0483 — `kj rag eval`. Runs the retriever against a golden query
 // set and reports recall@5, recall@10 and MRR per query and aggregated.
 // Exit code != 0 when `--min-recall` is set and the aggregated recall@5
@@ -207,7 +229,9 @@ export async function ragEvalCommand({ config, logger, flags = {} }) {
     const detected = projectSlug(config?.projectDir || process.cwd());
     const project = flags.project === "all" ? null : (flags.project || detected || null);
     const embedder = makeGovernedEmbedder(config);
-    const runQuery = async (text, k) => query(db, embedder, text, { topK: k, scope: "all", project });
+    // KJC-TSK-1181: measured with the cross-encoder too, so its default is a number, not a hunch.
+    const rerankOpts = rerankOptionsFor({ config, flags, logger });
+    const runQuery = async (text, k) => query(db, embedder, text, { topK: k, scope: "all", project, rerankOpts });
     const report = await runEval(queries, runQuery, { topK, ks: [5, 10] });
     const { aggregate: agg } = report;
     if (flags.json) {

package/src/config/defaults.js

@@ -274,6 +274,9 @@ const DEFAULTS = {
     // safe default blocks them (local ollama/onnx always allowed).
     sensitivity: "internal"
   },
+  // KJC-TSK-1183 — a document over this size (task file, ADR) reaches the roles as its headings
+  // index; they fetch a section whole with `kj doc section` when the task needs it.
+  docs: { indexFirstBytes: 12000 },
   // Opt-in. Set by the `kj init` wizard (explicit consent prompt in the OS
   // locale). When the key is absent or false, no events are sent. See
   // src/utils/telemetry.js and the Privacy & Telemetry section of README.md.

package/src/docs/index-first.js

@@ -0,0 +1,31 @@
+// KJC-TSK-1183 — Roles read long documents by index. Over the limit, a document reaches the prompt
+// as its preamble plus its headings and the command that fetches one section whole; under it, or
+// without headings to index, it travels as it is.
+import { indexMarkdown } from "./markdown-index.js";
+
+export const DEFAULT_INDEX_FIRST_BYTES = 12000;
+const PREAMBLE_MAX = 1500;
+const shellQuote = (s) => (/^[A-Za-z0-9_./:@%+=-]+$/.test(s) ? s : ["'", s.replaceAll("'", String.raw`'\''`), "'"].join(""));
+
+/**
+ * What the agent reads instead of the whole document, or null when the whole fits or there is
+ * nothing to index (fewer than two headings: a single one covers it all).
+ * @param {{ path: string, text: string, limit?: number }} doc
+ */
+export function indexFirstView({ path, text, limit = DEFAULT_INDEX_FIRST_BYTES }) {
+  if (!Number.isInteger(limit) || limit <= 0 || text.length <= limit) return null;
+  const headings = indexMarkdown(text);
+  if (headings.length < 2) return null;
+  const preamble = text.split("\n").slice(0, headings[1].line - 1).join("\n").trim().slice(0, PREAMBLE_MAX);
+  const index = headings.map((h) => `${"  ".repeat(h.level - 1)}- ${h.title}`).join("\n");
+  const file = shellQuote(path);
+  return [
+    preamble,
+    "",
+    `_This document is ${text.length} characters, over the ${limit} read-whole limit, so it is read by index. Its headings:_`,
+    "",
+    index,
+    "",
+    `Read a section whole only when the task needs it: \`kj doc section ${file} "<heading>"\` (the index again: \`kj doc index ${file}\`).`,
+  ].join("\n");
+}

package/src/docs/markdown-index.js

@@ -0,0 +1,62 @@
+/**
+ * KJC-TSK-1183 — Long markdown documents read by index: the headings first, then only the
+ * sections a task needs, each one whole and exactly as it is in the file. The headings are the
+ * index, so there is nothing extra to keep in sync. Independent of any spec kit's format.
+ */
+
+// ATX headings only: up to three spaces, `#` to `######`, a space, the title, an optional closing run of `#`.
+const HEADING = /^ {0,3}(#{1,6})[ \t]+(.+?)(?:[ \t]+#+)?[ \t]*$/;
+// A fence opens with three or more of one character; it closes with the same character, a run at
+// least as long, and nothing else on the line (CommonMark): ```` is not closed by ```.
+const FENCE_OPEN = /^[ \t]{0,3}(`{3,}|~{3,})/;
+const FENCE_CLOSE = /^[ \t]{0,3}(`{3,}|~{3,})[ \t]*$/;
+
+export class UnknownHeadingError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "UnknownHeadingError";
+  }
+}
+
+/** The headings of the document, with level and 1-based line; a heading inside a fenced code block is text. */
+export function indexMarkdown(text) {
+  const headings = [];
+  let fence = null; // the opening run, e.g. "````", while inside a code block
+  text.split("\n").forEach((raw, i) => {
+    const line = raw.endsWith("\r") ? raw.slice(0, -1) : raw;
+    if (fence !== null) {
+      const c = FENCE_CLOSE.exec(line);
+      if (c && c[1][0] === fence[0] && c[1].length >= fence.length) fence = null;
+      return;
+    }
+    const o = FENCE_OPEN.exec(line);
+    if (o) {
+      fence = o[1];
+      return;
+    }
+    const m = HEADING.exec(line);
+    if (m) headings.push({ level: m[1].length, title: m[2], line: i + 1 });
+  });
+  return headings;
+}
+
+/**
+ * The section under `title`: its heading line and everything up to the next heading of the same
+ * or a higher level, as the file has it. Exact title first, case-insensitive as a fallback; with
+ * duplicates the first wins and the others are named by line. An unknown title is an error that
+ * lists the headings, never an empty section.
+ */
+export function sectionOf(text, title) {
+  const headings = indexMarkdown(text);
+  let hits = headings.filter((h) => h.title === title);
+  if (hits.length === 0) hits = headings.filter((h) => h.title.toLowerCase() === title.toLowerCase());
+  if (hits.length === 0) {
+    const available = headings.map((h) => h.title).join(", ") || "none";
+    throw new UnknownHeadingError(`"${title}" is not a heading of this document; the headings are: ${available}`);
+  }
+  const [first, ...others] = hits;
+  const lines = text.split("\n");
+  const next = headings.find((h) => h.line > first.line && h.level <= first.level);
+  const body = next ? `${lines.slice(first.line - 1, next.line - 1).join("\n")}\n` : lines.slice(first.line - 1).join("\n");
+  return { level: first.level, title: first.title, line: first.line, text: body, ...(others.length ? { duplicates: others.map((h) => h.line) } : {}) };
+}

package/src/hu/gh-identity.js

@@ -0,0 +1,44 @@
+// KJC-TSK-1186: the shared board is written as whoever gh is logged in as. With several GitHub
+// accounts on one machine, another session switching the active one turned `kj hu move` into an
+// opaque GraphQL permission error, three times in a day. The clone declares its account in
+// .karajan/identity.local.yml (ADR 0005): with a declaration, the active account must be it.
+import { readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import yaml from "js-yaml";
+import { readIdentity } from "../identity/store.js";
+import { BoardRejectedError } from "./github-board.js";
+
+/** Where gh keeps its accounts, honouring the same overrides gh does. */
+export function ghHostsPath(env = process.env) {
+  const dir = env.GH_CONFIG_DIR || join(env.XDG_CONFIG_HOME || join(homedir(), ".config"), "gh");
+  return join(dir, "hosts.yml");
+}
+
+/** The account gh would use now for github.com, or null when gh has none. */
+export function activeGhUser(env = process.env) {
+  let raw;
+  try {
+    raw = readFileSync(ghHostsPath(env), "utf8");
+  } catch (err) {
+    if (err.code === "ENOENT") return null;
+    throw err;
+  }
+  const user = yaml.load(raw)?.["github.com"]?.user;
+  return typeof user === "string" && user.length > 0 ? user : null;
+}
+
+/**
+ * With an identity declared, the active gh account must be it; the error carries the exact remedy.
+ * Without a declaration nothing is asserted: gh answers for itself.
+ * @returns {{ declared: string | null, active: string | null }}
+ */
+export function assertGhIdentity({ projectDir, env = process.env }) {
+  const declared = readIdentity(projectDir)?.gh_user ?? null;
+  if (!declared) return { declared: null, active: null };
+  const active = activeGhUser(env);
+  if (active && active !== declared) {
+    throw new BoardRejectedError(`the active gh account is ${active} and this clone declares ${declared}: run gh auth switch --user ${declared} and retry`);
+  }
+  return { declared, active };
+}

package/src/orchestrator/stages/coder-stage.js

@@ -73,6 +73,8 @@ export async function runCoderStage({ coderRoleInstance, coderRole, config, logg
       // the plan, the rest are scoped to this HU. All four pass through
       // untouched when the caller omits them (legacy single-task runs).
       adrs, specSection, reviewerFindings, huId,
+      // KJC-TSK-1183: a long ADR reaches the coder as its index, sections on demand.
+      indexFirstBytes: config?.docs?.indexFirstBytes ?? null,
       // PAR-E2 (KJC-TSK-0629): the stage's config wins over the role's own —
       // worktree lanes pass a laneConfig whose projectDir is the worktree.
       projectDir: config?.projectDir || null,

package/src/plan/adr-loader.js

@@ -49,7 +49,7 @@ export async function loadActiveAdrs(projectDir, planId) {
     mdFiles.map(async (file) => {
       try {
         const md = await readFile(join(dir, file), "utf-8");
-        return { id: file.replace(/\.md$/, ""), markdown: md };
+        return { id: file.replace(/\.md$/, ""), markdown: md, path: join(dir, file) };
       } catch { return null; /* skip unreadable file */ }
     })
   );

package/src/prompts/coder.js

@@ -2,6 +2,7 @@ import { buildRtkInstructions } from "./rtk-snippet.js";
 import { roleSkills, buildRoleSkillSection } from "../skills/role-skills.js";
 import { getLanguageInstruction } from "../utils/locale.js";
 import { section, buildPromptLayout, joinLayout, STABLE, VOLATILE } from "./prompt-layout.js";
+import { indexFirstView } from "../docs/index-first.js";
 
 const SUBAGENT_PREAMBLE = [
   "IMPORTANT: You are running as a Karajan sub-agent.",
@@ -95,9 +96,11 @@ function renderAcceptanceTestsSection(tests) {
  * 8 ADRs (the planner shouldn't realistically emit more for one
  * plan, but bound it just in case).
  */
-function renderAdrSection(adrs) {
+function renderAdrSection(adrs, indexFirstBytes = null) {
   if (!Array.isArray(adrs) || adrs.length === 0) return "";
   const capped = adrs.slice(0, 8);
+  // KJC-TSK-1183: a long ADR travels as its index; the coder fetches a section when it needs it.
+  const bodyOf = (adr) => (indexFirstBytes && adr.path ? indexFirstView({ path: adr.path, text: adr.markdown, limit: indexFirstBytes }) : null) ?? adr.markdown;
   const lines = [
     "## Architecture Decision Records (active)",
     "",
@@ -105,7 +108,7 @@ function renderAdrSection(adrs) {
     "",
   ];
   for (const adr of capped) {
-    lines.push(adr.markdown.trim(), "", "---", "");
+    lines.push(bodyOf(adr).trim(), "", "---", "");
   }
   if (adrs.length > capped.length) {
     lines.push(`_(…${adrs.length - capped.length} more ADRs not shown — see ~/.kj/plans/<slug>/<planId>/adrs/.)_`, "");
@@ -189,7 +192,7 @@ function buildStackSection({ stack, testFramework }) {
  * volatile: per-HU/iteration content, rendered LAST preserving the relative
  * order the legacy prompt used (ADRs → SPEC → findings → tests → … → feedback).
  */
-export async function buildCoderPromptLayout({ task, reviewerFeedback = null, sonarSummary = null, coderRules = null, methodology = "tdd", serenaEnabled = false, rtkAvailable = false, deferredContext = null, productContext = null, domainContext = null, plan = null, projectDir = null, language = "en", provider = null, acceptanceTests = null, adrs = null, specSection = null, reviewerFindings = null, huId = null, stack = null, testFramework = null }) {
+export async function buildCoderPromptLayout({ task, reviewerFeedback = null, sonarSummary = null, coderRules = null, methodology = "tdd", serenaEnabled = false, rtkAvailable = false, deferredContext = null, productContext = null, domainContext = null, plan = null, projectDir = null, language = "en", provider = null, acceptanceTests = null, adrs = null, specSection = null, reviewerFindings = null, huId = null, stack = null, testFramework = null, indexFirstBytes = null }) {
   const langInstruction = getLanguageInstruction(language);
   // KJC-BUG-0032 (PR-I): hard rule about file paths. Real bug: a HU
   // titled "Initialize project skeleton: create assistant/ directory…"
@@ -278,7 +281,7 @@ export async function buildCoderPromptLayout({ task, reviewerFeedback = null, so
     section(skillSection, STABLE),
     section(`Task:\n${task}`, VOLATILE),
     section(plan ? `## Implementation Plan (from planner)\nFollow these steps:\n${plan}` : null, VOLATILE),
-    section(renderAdrSection(adrs) || null, VOLATILE),
+    section(renderAdrSection(adrs, indexFirstBytes) || null, VOLATILE),
     section(renderSpecSectionLine(specSection) || null, VOLATILE),
     section(renderReviewerFindingsSection(reviewerFindings, huId) || null, VOLATILE),
     section(renderAcceptanceTestsSection(acceptanceTests) || null, VOLATILE),

package/src/utils/task-file.js

@@ -25,6 +25,7 @@
 
 import fs from "node:fs/promises";
 import path from "node:path";
+import { indexFirstView } from "../docs/index-first.js";
 
 export const DEFAULT_TASK_FILE_MAX_BYTES = 256 * 1024;
 
@@ -41,7 +42,7 @@ export async function readTaskFile(filePath, opts = {}) {
   if (!filePath || typeof filePath !== "string") {
     throw new Error("readTaskFile: path must be a non-empty string");
   }
-  const { projectDir, maxBytes = DEFAULT_TASK_FILE_MAX_BYTES } = opts;
+  const { projectDir, maxBytes = DEFAULT_TASK_FILE_MAX_BYTES, indexFirstBytes = null, logger = null } = opts;
   const base = projectDir || process.cwd();
   const resolved = path.isAbsolute(filePath) ? filePath : path.resolve(base, filePath);
 
@@ -68,6 +69,12 @@ export async function readTaskFile(filePath, opts = {}) {
   if (!trimmed) {
     throw new Error(`Task file is empty (or whitespace-only): ${resolved}`);
   }
+  // KJC-TSK-1183: over the limit the roles get the index and fetch sections on demand.
+  const view = indexFirstBytes ? indexFirstView({ path: resolved, text: trimmed, limit: indexFirstBytes }) : null;
+  if (view) {
+    logger?.info?.(`[docs] ${resolved} read by index (${trimmed.length} chars > ${indexFirstBytes}): sections on demand with kj doc section`);
+    return view;
+  }
   return trimmed;
 }
 
@@ -89,7 +96,7 @@ export async function readTaskFile(filePath, opts = {}) {
  * @param {Object} [args.logger]             - optional; uses `logger.warn(msg)` only
  * @returns {Promise<string>}
  */
-export async function resolveTaskInput({ task, taskFile, projectDir, logger } = {}) {
+export async function resolveTaskInput({ task, taskFile, projectDir, logger, indexFirstBytes = null } = {}) {
   const hasTask = typeof task === "string" && task.trim().length > 0;
   const hasFile = typeof taskFile === "string" && taskFile.trim().length > 0;
 
@@ -103,7 +110,7 @@ export async function resolveTaskInput({ task, taskFile, projectDir, logger } =
     return task.trim();
   }
   if (hasFile) {
-    return readTaskFile(taskFile, { projectDir });
+    return readTaskFile(taskFile, { projectDir, indexFirstBytes, logger });
   }
   return task.trim();
 }