@karajan-family/code 4.62.1 → 4.64.0

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/hu/github-board.js

@@ -12,11 +12,16 @@ export const STATUSES = ["pending", "running", "done", "failed", "skipped"];
 const statusLabel = (s) => `kj:${s}`;
 
 /** gh could not reach GitHub: the caller may queue the change, never invent data. */
-export class BoardOfflineError extends Error {}
+export class BoardOfflineError extends Error { name = "BoardOfflineError"; }
 /** GitHub answered and said no (permissions, missing repo...). */
-export class BoardRejectedError extends Error {}
+export class BoardRejectedError extends Error { name = "BoardRejectedError"; }
 /** The HU is running and someone else holds it: taking it over is explicit (release). */
-export class HuClaimedError extends Error {}
+export class HuClaimedError extends Error { name = "HuClaimedError"; }
+
+// KJC-TSK-1165: by name, not only instanceof: a test runner may load this module twice.
+export const isOffline = (err) => err instanceof BoardOfflineError || err?.name === "BoardOfflineError";
+/** GitHub answered and refused (rejected, or the HU is held by someone else): a conflict, not a failure of kj. */
+export const isRefusal = (err) => err instanceof BoardRejectedError || err instanceof HuClaimedError || ["BoardRejectedError", "HuClaimedError"].includes(err?.name);
 
 // gh is not localized: these are the network failures it prints.
 const OFFLINE = /dial tcp|no such host|could not resolve host|connection refused|i\/o timeout|network is unreachable|error connecting to/i;
@@ -48,6 +53,18 @@ export async function createHu({ repo, title, acceptanceCriteria = [], tests = [
   const url = (await gh(run, ["issue", "create", "-R", repo, "--title", title, "--body", body, "--label", HU_LABEL, "--label", statusLabel("pending")])).trim();
   const number = Number(/\/issues\/(\d+)$/.exec(url)?.[1]);
   if (!Number.isInteger(number)) throw new BoardRejectedError(`gh issue create returned no issue URL: ${url}`);
+  // KJC-BUG-0395 (HU-2408): GitHub answered the create and left the issue without its labels, so
+  // the next move refused it as "not a kj HU". An HU the board does not recognise is not announced:
+  // the labels are checked, put back once, and a second absence is said loud.
+  const wanted = [HU_LABEL, statusLabel("pending")];
+  const labelsOf = async () => new Set(JSON.parse(await gh(run, ["issue", "view", String(number), "-R", repo, "--json", "labels"])).labels.map((l) => l.name));
+  let have = await labelsOf();
+  if (wanted.some((l) => !have.has(l))) {
+    await gh(run, ["issue", "edit", String(number), "-R", repo, ...wanted.filter((l) => !have.has(l)).flatMap((l) => ["--add-label", l])]);
+    have = await labelsOf();
+    const missing = wanted.filter((l) => !have.has(l));
+    if (missing.length) throw new BoardRejectedError(`issue #${number} was created without ${missing.join(", ")} and gh could not add them: the board does not recognise it, add the labels by hand`);
+  }
   return { short_id: `HU-${number}`, number, status: "pending", title };
 }
 

package/src/hu/team-board-cache.js

@@ -0,0 +1,84 @@
+/**
+ * KJC-TSK-1165 (TEAM-GH-D, ADR 0025): the local copy of the shared board, and the
+ * queue of moves made without network. The copy is a cache, never the truth: it
+ * is rewritten on every answer from GitHub and only read when GitHub does not
+ * answer. A queued move is applied when the network is back; one GitHub rejects
+ * (someone else holds the HU) is reported and dropped, never forced. Creating a
+ * HU offline is refused elsewhere: an id is only ever minted by GitHub.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { isOffline, isRefusal } from "./github-board.js";
+
+const CACHE_FILE = ".karajan/board-cache.json";
+// A fresh object every time: a shared default array would carry one read's queue into the next.
+const empty = () => ({ hus: null, updatedAt: null, queue: [] });
+
+export function readCache(projectDir) {
+  try {
+    return { ...empty(), ...JSON.parse(fs.readFileSync(path.join(projectDir, CACHE_FILE), "utf8")) };
+  } catch (err) {
+    if (err.code === "ENOENT") return empty();
+    throw err;
+  }
+}
+
+function writeCache(projectDir, cache) {
+  const file = path.join(projectDir, CACHE_FILE);
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, `${JSON.stringify(cache, null, 2)}\n`, "utf8");
+}
+
+/** The HUs from GitHub (and the copy refreshed), or the copy when GitHub cannot be reached. */
+export async function listWithCache({ projectDir, repo, list }) {
+  try {
+    const rows = await list({ repo });
+    writeCache(projectDir, { ...readCache(projectDir), hus: rows, updatedAt: new Date().toISOString() });
+    return { source: "github", rows };
+  } catch (err) {
+    const cache = readCache(projectDir);
+    if (!isOffline(err) || !cache.hus) throw err;
+    return { source: "cache", rows: cache.hus, updatedAt: cache.updatedAt };
+  }
+}
+
+/**
+ * Remember a move to apply when the network is back. `expected` is the status the local
+ * copy shows now (null when the copy does not know the HU): when it is applied, a HU that
+ * moved meanwhile is a conflict, not something to overwrite. The copy takes the move so a
+ * second queued move on the same HU expects the first one's result.
+ */
+export function queueMove({ projectDir, number, status, who, release }) {
+  const cache = readCache(projectDir);
+  const row = cache.hus?.find((h) => h.number === number) ?? null;
+  cache.queue.push({ number, status, who, release: Boolean(release), expected: row?.status ?? null, queuedAt: new Date().toISOString() });
+  if (row) row.status = status;
+  writeCache(projectDir, cache);
+  return cache.queue.length;
+}
+
+/**
+ * Apply the queue in order. A move GitHub refuses is a conflict: reported, dropped, the
+ * HU stays as the other person left it. Still offline: stop, keep the rest for later.
+ * Any other error is kj's own: it surfaces, and the move stays queued.
+ * @returns {Promise<{applied: number, conflicts: string[], pending: number}>}
+ */
+export async function flushQueue({ projectDir, apply }) {
+  const cache = readCache(projectDir);
+  const conflicts = [];
+  let applied = 0;
+  while (cache.queue.length > 0) {
+    const op = cache.queue[0];
+    try {
+      await apply(op);
+      applied += 1;
+    } catch (err) {
+      if (isOffline(err)) break;
+      if (!isRefusal(err)) throw err;
+      conflicts.push(`HU-${op.number} → ${op.status} (queued ${op.queuedAt}) not applied: ${err.message}`);
+    }
+    cache.queue.shift();
+    writeCache(projectDir, cache);
+  }
+  return { applied, conflicts, pending: cache.queue.length };
+}

package/src/hu/team-board-mirror.js

@@ -0,0 +1,26 @@
+/**
+ * KJC-TSK-1166 (TEAM-GH-E, ADR 0025): what `kj board` shows of the shared board. The web
+ * board reads plans, so the shared board is mirrored into one read-only plan per project,
+ * rewritten from the issues every time kj reads them. It is a view: changing it is done
+ * with kj hu move, never from the web, and the board refuses to edit it.
+ */
+import { savePlan } from "../plan/plan-store.js";
+
+export const MIRROR_PLAN_ID = "plan_github-board";
+
+/** The shared board as a plan the web board can show, marked read-only. */
+export async function writeTeamMirror(projectDir, rows, { repo }) {
+  const now = new Date().toISOString();
+  const plan = {
+    version: 2, planId: MIRROR_PLAN_ID, name: "github", alias: "github",
+    task: `Shared HU Board: GitHub Issues of ${repo}`,
+    status: "ready", readonly: "github", createdAt: now,
+    hus: rows.map((r) => ({
+      id: r.short_id, short_id: r.short_id, title: r.title, status: r.status,
+      claimed_by: r.claimed_by ?? null, created_by: "github", external_ref: `${repo}#${r.number}`,
+      acceptance_criteria: [], acceptance_tests: [], createdAt: now, updatedAt: now,
+    })),
+  };
+  await savePlan(projectDir, plan);
+  return plan;
+}

package/src/lang/chunk-go.js

@@ -8,6 +8,7 @@
 // `type_declaration` contiene type_spec(s); usamos el primero como symbol.
 
 import { getLoaded, loadLanguage } from "./tree-sitter-loader.js";
+import { spanChunks } from "./chunk-span.js";
 
 const DEFAULT_LIMIT = 800;
 const DEFAULT_OVERLAP = 100;
@@ -21,16 +22,6 @@ export async function prepareGo() {
   return loadLanguage("go");
 }
 
-function windowText(text, limit, overlap) {
-  if (text.length <= limit) return [text];
-  const step = Math.max(1, limit - overlap);
-  const out = [];
-  for (let i = 0; i < text.length; i += step) {
-    out.push(text.slice(i, i + limit));
-    if (i + limit >= text.length) break;
-  }
-  return out;
-}
 
 function symbolForType(node) {
   for (const spec of node.namedChildren) {
@@ -74,21 +65,5 @@ function marksViaRegex(text) {
 }
 
 export function chunkGo(text, { path = "<src>", limit = DEFAULT_LIMIT, overlap = DEFAULT_OVERLAP } = {}) {
-  const marks = marksViaAST(text) ?? marksViaRegex(text);
-  if (marks.length === 0) {
-    return windowText(text, limit, overlap).map((piece) => ({
-      text: piece,
-      metadata: { source: path, kind: "code", symbol: null, language: "go" },
-    }));
-  }
-  const out = [];
-  for (let i = 0; i < marks.length; i += 1) {
-    const start = marks[i].idx;
-    const end = i + 1 < marks.length ? marks[i + 1].idx : text.length;
-    const body = text.slice(start, end);
-    for (const piece of windowText(body, limit, overlap)) {
-      out.push({ text: piece, metadata: { source: path, kind: "code", symbol: marks[i].symbol, language: "go" } });
-    }
-  }
-  return out;
+  return spanChunks(text, marksViaAST(text) ?? marksViaRegex(text), { path, language: "go", limit, overlap });
 }

package/src/lang/chunk-java.js

@@ -4,6 +4,7 @@
 // sin prefijar (coherente con chunk-go), el RAG ya lleva contexto del fichero.
 
 import { getLoaded, loadLanguage } from "./tree-sitter-loader.js";
+import { spanChunks } from "./chunk-span.js";
 
 const DEFAULT_LIMIT = 800;
 const DEFAULT_OVERLAP = 100;
@@ -23,17 +24,6 @@ export async function prepareJava() {
   return loadLanguage("java");
 }
 
-function windowText(text, limit, overlap) {
-  if (text.length <= limit) return [text];
-  const step = Math.max(1, limit - overlap);
-  const out = [];
-  for (let i = 0; i < text.length; i += step) {
-    out.push(text.slice(i, i + limit));
-    if (i + limit >= text.length) break;
-  }
-  return out;
-}
-
 function nameOf(node) {
   const n = node.childForFieldName("name");
   return n ? n.text : null;
@@ -47,14 +37,15 @@ function marksViaAST(text) {
   const marks = [];
   for (const child of tree.rootNode.namedChildren) {
     if (!CONTAINER_KINDS.has(child.type)) continue;
-    const s = nameOf(child);
-    if (s) marks.push({ idx: child.startIndex, symbol: s });
+    const className = nameOf(child);
+    if (className) marks.push({ idx: child.startIndex, symbol: className });
     const body = child.childForFieldName("body");
     if (!body) continue;
     for (const m of body.namedChildren) {
       if (!MEMBER_KINDS.has(m.type)) continue;
-      const ms = nameOf(m);
-      if (ms) marks.push({ idx: m.startIndex, symbol: ms });
+      const memberName = nameOf(m);
+      // KJC-TSK-1171: a member knows its class (by name); the chunk says both.
+      if (memberName) marks.push({ idx: m.startIndex, symbol: memberName, parent: className });
     }
   }
   marks.sort((a, b) => a.idx - b.idx);
@@ -70,21 +61,5 @@ function marksViaRegex(text) {
 }
 
 export function chunkJava(text, { path = "<src>", limit = DEFAULT_LIMIT, overlap = DEFAULT_OVERLAP } = {}) {
-  const marks = marksViaAST(text) ?? marksViaRegex(text);
-  if (marks.length === 0) {
-    return windowText(text, limit, overlap).map((piece) => ({
-      text: piece,
-      metadata: { source: path, kind: "code", symbol: null, language: "java" },
-    }));
-  }
-  const out = [];
-  for (let i = 0; i < marks.length; i += 1) {
-    const start = marks[i].idx;
-    const end = i + 1 < marks.length ? marks[i + 1].idx : text.length;
-    const body = text.slice(start, end);
-    for (const piece of windowText(body, limit, overlap)) {
-      out.push({ text: piece, metadata: { source: path, kind: "code", symbol: marks[i].symbol, language: "java" } });
-    }
-  }
-  return out;
+  return spanChunks(text, marksViaAST(text) ?? marksViaRegex(text), { path, language: "java", limit, overlap });
 }

package/src/lang/chunk-python.js

@@ -14,6 +14,7 @@
 // devuelve `[{ text, metadata: { source, kind, symbol, language } }]`.
 
 import { getLoaded, loadLanguage } from "./tree-sitter-loader.js";
+import { spanChunks } from "./chunk-span.js";
 
 const DEFAULT_LIMIT = 800;
 const DEFAULT_OVERLAP = 100;
@@ -23,16 +24,6 @@ export async function preparePython() {
   return loadLanguage("python");
 }
 
-function windowText(text, limit, overlap) {
-  if (text.length <= limit) return [text];
-  const step = Math.max(1, limit - overlap);
-  const out = [];
-  for (let i = 0; i < text.length; i += step) {
-    out.push(text.slice(i, i + limit));
-    if (i + limit >= text.length) break;
-  }
-  return out;
-}
 
 function marksViaAST(text) {
   const entry = getLoaded("python");
@@ -68,21 +59,5 @@ function marksViaRegex(text) {
 }
 
 export function chunkPython(text, { path = "<src>", limit = DEFAULT_LIMIT, overlap = DEFAULT_OVERLAP } = {}) {
-  const marks = marksViaAST(text) ?? marksViaRegex(text);
-  if (marks.length === 0) {
-    return windowText(text, limit, overlap).map((piece) => ({
-      text: piece,
-      metadata: { source: path, kind: "code", symbol: null, language: "python" },
-    }));
-  }
-  const out = [];
-  for (let i = 0; i < marks.length; i += 1) {
-    const start = marks[i].idx;
-    const end = i + 1 < marks.length ? marks[i + 1].idx : text.length;
-    const body = text.slice(start, end);
-    for (const piece of windowText(body, limit, overlap)) {
-      out.push({ text: piece, metadata: { source: path, kind: "code", symbol: marks[i].symbol, language: "python" } });
-    }
-  }
-  return out;
+  return spanChunks(text, marksViaAST(text) ?? marksViaRegex(text), { path, language: "python", limit, overlap });
 }

package/src/lang/chunk-rust.js

@@ -7,6 +7,7 @@
 // que metadata.symbol apunte al tipo implementado (útil para grep en RAG).
 
 import { getLoaded, loadLanguage } from "./tree-sitter-loader.js";
+import { spanChunks } from "./chunk-span.js";
 
 const DEFAULT_LIMIT = 800;
 const DEFAULT_OVERLAP = 100;
@@ -25,16 +26,6 @@ export async function prepareRust() {
   return loadLanguage("rust");
 }
 
-function windowText(text, limit, overlap) {
-  if (text.length <= limit) return [text];
-  const step = Math.max(1, limit - overlap);
-  const out = [];
-  for (let i = 0; i < text.length; i += step) {
-    out.push(text.slice(i, i + limit));
-    if (i + limit >= text.length) break;
-  }
-  return out;
-}
 
 function symbolForImpl(node) {
   const typeNode = node.childForFieldName("type");
@@ -82,21 +73,5 @@ function marksViaRegex(text) {
 }
 
 export function chunkRust(text, { path = "<src>", limit = DEFAULT_LIMIT, overlap = DEFAULT_OVERLAP } = {}) {
-  const marks = marksViaAST(text) ?? marksViaRegex(text);
-  if (marks.length === 0) {
-    return windowText(text, limit, overlap).map((piece) => ({
-      text: piece,
-      metadata: { source: path, kind: "code", symbol: null, language: "rust" },
-    }));
-  }
-  const out = [];
-  for (let i = 0; i < marks.length; i += 1) {
-    const start = marks[i].idx;
-    const end = i + 1 < marks.length ? marks[i + 1].idx : text.length;
-    const body = text.slice(start, end);
-    for (const piece of windowText(body, limit, overlap)) {
-      out.push({ text: piece, metadata: { source: path, kind: "code", symbol: marks[i].symbol, language: "rust" } });
-    }
-  }
-  return out;
+  return spanChunks(text, marksViaAST(text) ?? marksViaRegex(text), { path, language: "rust", limit, overlap });
 }

package/src/lang/chunk-span.js

@@ -0,0 +1,49 @@
+/**
+ * KJC-TSK-1171 (RAG-B, ADR 0026): the shared tail of every code chunker. A chunker
+ * finds marks ({ idx, symbol, parent? }); this slices the text from each mark to the
+ * next, windows what is too long for the embedder, and stamps each piece with its
+ * 1-based line range and the symbol it belongs to, so the embedded header and the
+ * citations can name file, symbol, parent and lines.
+ */
+const DEFAULT_LIMIT = 800;
+const DEFAULT_OVERLAP = 100;
+
+/** 1-based line of a character index. */
+export const lineAt = (text, idx) => {
+  let line = 1;
+  for (let i = 0; i < idx && i < text.length; i += 1) if (text.charCodeAt(i) === 10) line += 1;
+  return line;
+};
+
+// Trailing whitespace (a newline and the next line's indentation) is not a line of the symbol.
+const linesIn = (piece) => {
+  const body = piece.trimEnd();
+  let n = 0;
+  for (let i = 0; i < body.length; i += 1) if (body.charCodeAt(i) === 10) n += 1;
+  return n;
+};
+
+/** The slice at `startIdx`, windowed, each piece with its line range. */
+export function pieceSpans(text, startIdx, slice, { limit = DEFAULT_LIMIT, overlap = DEFAULT_OVERLAP } = {}) {
+  const step = Math.max(1, limit - overlap);
+  const out = [];
+  for (let i = 0; ; i += step) {
+    const piece = slice.slice(i, i + limit);
+    const startLine = lineAt(text, startIdx + i);
+    out.push({ text: piece, start_line: startLine, end_line: startLine + linesIn(piece) });
+    if (i + limit >= slice.length) break;
+  }
+  return out;
+}
+
+/** Chunks from marks; with no marks, the whole text as one anonymous symbol. */
+export function spanChunks(text, marks, { path = "<src>", kind = "code", language, limit, overlap } = {}) {
+  const base = { source: path, kind, ...(language === undefined ? {} : { language }) };
+  const ranges = marks.length === 0
+    ? [{ start: 0, end: text.length, symbol: null, parent: null }]
+    : marks.map((m, i) => ({ start: m.idx, end: i + 1 < marks.length ? marks[i + 1].idx : text.length, symbol: m.symbol, parent: m.parent ?? null }));
+  return ranges.flatMap(({ start, end, symbol, parent }) =>
+    pieceSpans(text, start, text.slice(start, end), { limit, overlap }).map(({ text: piece, start_line, end_line }) => ({
+      text: piece, metadata: { ...base, symbol, parent, start_line, end_line },
+    })));
+}

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/plan/plan-store.js

@@ -63,8 +63,11 @@ export function projectSlug(projectDir) {
     .slice(0, 120);
 }
 
+// KJC-TSK-1166: the board honours KJ_PLANS_DIR as its plans root; what kj writes must land
+// in the same root, or the board shows none of it.
 export function plansDir(projectDir) {
-  return path.join(getKjHome(), "plans", projectSlug(projectDir));
+  const root = process.env.KJ_PLANS_DIR || path.join(getKjHome(), "plans");
+  return path.join(root, projectSlug(projectDir));
 }
 
 /**

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),