karajan-code 4.61.1 → 4.62.1

package/package.json

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

package/src/cli/register-meta.js

@@ -353,6 +353,15 @@ export function registerMeta(program, { pkgVersion }) {
         await huCommand({ config, action: "list", flags });
       });
     });
+  // KJC-TSK-1163 (ADR 0025): the team board, turned on once per repo.
+  hu.command("backend <backend>")
+    .description("Turn the repo's HU Board on: github (shared, in GitHub Issues) or local; writes .karajan/board.yml for a PR")
+    .option("--json", "Machine-readable output")
+    .action(async (backend, flags) => {
+      await withConfig(pkgVersion, "hu", flags, async ({ config }) => {
+        await huCommand({ config, action: "backend", args: [backend], flags });
+      });
+    });
 
   const adr = program.command("adr").description("Architecture decision records in .karajan/adrs/ (git-tracked)");
   adr.command("add <title>")

package/src/commands/hu.js

@@ -12,6 +12,8 @@ import { detectHostAgent } from "../utils/agent-detect.js";
 import { readIdentity } from "../identity/store.js";
 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 } from "../hu/github-board.js";
 
 // KJC-TSK-0661 (Jorge's friction): every HU records WHO created it — the
 // board must never show work nobody can trace. Host agent env → that agent;
@@ -46,6 +48,45 @@ export function findTitleMatches(title, allHus) {
   return { identical, similar };
 }
 
+/** A repeatable flag as lines: one value or many, each split per line, blanks dropped. */
+function linesOf(v) {
+  const values = Array.isArray(v) ? v : [v];
+  return values.filter((s) => s != null && s !== "").flatMap((s) => String(s).split("\n")).map((s) => s.trim()).filter(Boolean);
+}
+
+/** KJC-TSK-1163: kj hu add on the shared board; the same no-duplicates rule, checked against the issues. */
+async function addToTeamBoard({ repo, title, flags, deps, emit }) {
+  if (flags.id) throw new Error(`--id is not used with the shared board: GitHub gives each HU its id (the issue number)`);
+  const { identical, similar } = findTitleMatches(title, await (deps.listTeamHus ?? listHus)({ repo }));
+  if (identical.length > 0) {
+    throw new Error(`An HU with this title already exists: ${identical[0].short_id} (status: ${identical[0].status}). Work that card or move it with: kj hu move ${identical[0].short_id} <status>`);
+  }
+  if (similar.length > 0) {
+    const candidates = similar.map((h) => `  · ${h.short_id} (${h.status}) "${h.title}"`).join("\n");
+    console.warn("⚠ possible duplicate — check before working it:\n" + candidates);
+  }
+  const hu = await (deps.createTeamHu ?? createHu)({
+    repo, title, acceptanceCriteria: [...linesOf(flags.ac), ...linesOf(flags.criteria)], tests: linesOf(flags.tests), ref: flags.ref ? String(flags.ref).trim() : null,
+  });
+  return emit({ ...hu, board: "github", repo }, `✓ HU created: ${hu.short_id} (pending) in the shared board, issue #${hu.number} of ${repo}`);
+}
+
+/** KJC-TSK-1164: kj hu move on the shared board; starting it claims it (the assignee) first. */
+async function moveOnTeamBoard({ repo, args, flags, deps, emit, who }) {
+  const [ref, status] = args;
+  if (!ref || !status) throw new Error("usage: kj hu move <id> <status>");
+  if (!HU_STATUSES.includes(status)) throw new Error(`invalid status "${status}" — valid: ${HU_STATUSES.join(", ")}`);
+  const number = Number(/^(?:HU-|#)(\d+)$/i.exec(ref)?.[1]);
+  if (!Number.isInteger(number)) throw new Error(`"${ref}" is not a shared-board HU: use HU-<issue number>`);
+  // GitHub assigns by login: kj identity must name the GitHub user of this clone.
+  if (!who || who.includes("@")) throw new Error("the shared board reserves by GitHub login: declare it with kj identity set");
+  // Starting it, or releasing it, claims it; any other move of a HU someone else runs is refused.
+  if (status === "running" || flags.release) await (deps.claimTeamHu ?? claim)({ repo, number, who, release: Boolean(flags.release) });
+  else await (deps.assertNotHeld ?? assertNotHeld)({ repo, number, who });
+  await (deps.setTeamStatus ?? setStatus)({ repo, number, status });
+  return emit({ id: `HU-${number}`, status, claimed_by: status === "running" ? who : null }, `✓ HU-${number} → ${status}`);
+}
+
 // Exported for the Steward's proposed-work sync (KJC-TSK-0792): broken
 // invariants land in the same backlog the brain already consumes.
 export async function backlogPlan(projectDir) {
@@ -72,6 +113,30 @@ export async function huCommand({ config = null, action, args = [], flags = {},
   // tracker coexists with it: each HU points at its replica there (--ref).
   const externalBoard = config?.state_backend === "external" ? (config?.board?.name || "the external board") : null;
 
+  // KJC-TSK-1163/1164 (ADR 0025): the repo's board; with the shared one on, add/list/move go to GitHub.
+  // The repo turns its board on once; the file travels in a PR. Before reading it: it may be what is fixed.
+  if (action === "backend") {
+    if (!args[0]) throw new Error("usage: kj hu backend <github | local>");
+    const r = await (deps.setBackend ?? setBoardBackend)({ projectDir, backend: args[0] });
+    const where = r.backend === "github" ? `GitHub Issues of ${r.repo}` : "the local board";
+    const files = r.gitignoreChanged ? `${r.file} and .gitignore` : r.file;
+    return emit(r, `✓ HU Board: ${where} — commit ${files} in a PR so the whole team inherits it`);
+  }
+  const board = await (deps.boardConfig ?? readBoardConfig)(projectDir);
+  if (board.backend === "github" && action === "list") {
+    const rows = (await (deps.listTeamHus ?? listHus)({ repo: board.repo })).map((h) => ({ ...h, id: h.short_id, plan: "github" }));
+    if (flags.json) { console.log(JSON.stringify(rows)); return rows; }
+    for (const r of rows) {
+      const held = r.claimed_by ? " · held by " + r.claimed_by : "";
+      console.log(`${r.short_id.padEnd(28)} ${r.status.padEnd(8)} ${r.title}  [${board.repo}${held}]`);
+    }
+    if (rows.length === 0) console.log("no HUs yet — create one with: kj hu add \"<story>\"");
+    return rows;
+  }
+  // KJC-BUG-0392: a zero-padded id (HU-0104) is a local HU from before the shared board: it stays local.
+  const legacyLocal = /^HU-0\d+$/i.test(String(args[0] ?? ""));
+  if (board.backend === "github" && action === "move" && !legacyLocal) return moveOnTeamBoard({ repo: board.repo, args, flags, deps, emit, who: deps.who === undefined ? workerOf(projectDir) : deps.who });
+
   if (action === "list") {
     const plans = await listPlans(projectDir);
     const rows = [];
@@ -104,6 +169,8 @@ export async function huCommand({ config = null, action, args = [], flags = {},
   if (action === "add") {
     const title = args[0];
     if (!title || !title.trim()) throw new Error("kj hu add requires a title: kj hu add \"<story>\"");
+    // KJC-TSK-1163 (ADR 0025): with the shared board on, the HU is an issue and GitHub gives its id.
+    if (board.backend === "github") return addToTeamBoard({ repo: board.repo, title, flags, deps, emit });
     // Cross-plan title dedup (KJC-TSK-0675) — check BEFORE creating anything.
     const allHus = [];
     for (const meta of await listPlans(projectDir)) {
@@ -152,8 +219,7 @@ export async function huCommand({ config = null, action, args = [], flags = {},
     if (flags.taskType && !TASK_TYPES.includes(flags.taskType)) {
       throw new Error(`invalid --task-type "${flags.taskType}" — valid: ${TASK_TYPES.join(", ")}`);
     }
-    const splitLines = (v) => (Array.isArray(v) ? v : v ? [v] : [])
-      .flatMap((s) => String(s).split("\n")).map((s) => s.trim()).filter(Boolean);
+    const splitLines = linesOf;
     const hu = addHu(plan, {
       title,
       // KJC-BUG-0189: the card-first gate demands a branch that references a
@@ -249,5 +315,5 @@ export async function huCommand({ config = null, action, args = [], flags = {},
     return emit({ id: hu.id, status, claimed_by: hu.claimed_by ?? null }, `✓ ${label} → ${status}`);
   }
 
-  throw new Error(`unknown action "${action}" — use: add | move | list`);
+  throw new Error(`unknown action "${action}" — use: add | move | list | backend`);
 }

package/src/hu/board-config.js

@@ -0,0 +1,80 @@
+/**
+ * KJC-TSK-1163 (TEAM-GH-B, ADR 0025): which HU Board a repo uses. The shared
+ * board on GitHub Issues is turned on once per repo (kj hu backend github),
+ * in a versioned file the whole team inherits with a pull; kj never turns it
+ * on because the remote happens to be GitHub. No file means the local board.
+ */
+import fs from "node:fs/promises";
+import path from "node:path";
+import { parse as parseYaml, stringify as toYaml } from "yaml";
+import { runCommand } from "../utils/process.js";
+import { ensureGateTrackable } from "../review/gate-gitignore.js";
+
+export const BOARD_FILE = ".karajan/board.yml";
+const BACKENDS = ["github", "local"];
+const REPO_RE = /^[\w.-]+\/[\w.-]+$/;
+
+/** owner/repo of a GitHub remote (https, ssh, or an ssh host alias like github.com-work), or null. */
+export function repoFromRemote(url) {
+  const u = String(url).trim();
+  // The host is github.com exactly, or an ssh alias of it written github.com-<name>; never a lookalike.
+  const shapes = [
+    /^https:\/\/(?:[^@/]+@)?github\.com\/([\w.-]+)\/([\w.-]+?)(?:\.git)?\/?$/,
+    /^ssh:\/\/(?:[\w.-]+@)?github\.com(?:-\w+)?(?::\d+)?\/([\w.-]+)\/([\w.-]+?)(?:\.git)?\/?$/,
+    /^(?:[\w.-]+@)?github\.com(?:-\w+)?:([\w.-]+)\/([\w.-]+?)(?:\.git)?\/?$/,
+  ];
+  const m = shapes.map((re) => re.exec(u)).find(Boolean);
+  return m ? `${m[1]}/${m[2]}` : null;
+}
+
+/** The repo's board: {backend: "local"} with no file, or the validated content of the file. */
+export async function readBoardConfig(projectDir) {
+  let text;
+  try {
+    text = await fs.readFile(path.join(projectDir, BOARD_FILE), "utf8");
+  } catch (err) {
+    if (err.code === "ENOENT") return { backend: "local" };
+    throw err;
+  }
+  const raw = parseYaml(text) || {};
+  if (!BACKENDS.includes(raw.backend)) throw new Error(`${BOARD_FILE}: backend must be one of ${BACKENDS.join(", ")}`);
+  if (raw.backend === "local") return { backend: "local" };
+  if (!REPO_RE.test(String(raw.repo ?? ""))) throw new Error(`${BOARD_FILE}: repo must be owner/repo, got "${raw.repo}"`);
+  return { backend: "github", repo: raw.repo };
+}
+
+/** Turn a board on for the repo, writing the versioned file and making sure git tracks it. */
+export async function setBoardBackend({ projectDir, backend, run = runCommand, trackable = ensureGateTrackable }) {
+  if (!BACKENDS.includes(backend)) throw new Error(`unknown board backend "${backend}": use ${BACKENDS.join(", ")}`);
+  const git = (...args) => run("git", ["-C", projectDir, ...args]);
+  const doc = { backend };
+  if (backend === "github") {
+    const remote = await git("remote", "get-url", "origin");
+    const repo = remote.exitCode === 0 ? repoFromRemote(remote.stdout) : null;
+    if (!repo) throw new Error(`origin is not a GitHub remote (${(remote.stdout || remote.stderr || "").trim() || "none"}): the shared board lives in GitHub Issues`);
+    doc.repo = repo;
+  }
+  // Trackable BEFORE it is written (check-ignore needs no file): a board the team cannot
+  // inherit is never left behind. Exit 0 means git ignores it.
+  const isIgnored = async () => (await git("check-ignore", "-q", BOARD_FILE)).exitCode === 0;
+  const ignored = await isIgnored();
+  if (ignored) {
+    // A .karajan root exclude becomes the canonical block, which re-includes the board file.
+    await trackable(projectDir);
+    if (await isIgnored()) await appendReInclude(projectDir);
+    if (await isIgnored()) throw new Error(`git still ignores ${BOARD_FILE}: re-include it in .gitignore so the team inherits the board`);
+  }
+  await fs.mkdir(path.join(projectDir, ".karajan"), { recursive: true });
+  await fs.writeFile(path.join(projectDir, BOARD_FILE), toYaml(doc), "utf8");
+  return { ...doc, file: BOARD_FILE, gitignoreChanged: ignored };
+}
+
+async function appendReInclude(projectDir) {
+  const file = path.join(projectDir, ".gitignore");
+  // Ignored by a global exclude with no .gitignore: the repo's own file outranks it.
+  const text = await fs.readFile(file, "utf8").catch((err) => {
+    if (err.code === "ENOENT") { return ""; }
+    throw err;
+  });
+  await fs.writeFile(file, `${text}${text === "" || text.endsWith("\n") ? "" : "\n"}!${BOARD_FILE}\n`, "utf8");
+}

package/src/hu/github-board.js

@@ -0,0 +1,124 @@
+/**
+ * KJC-TSK-1162 (TEAM-GH-A, ADR 0025): the shared HU Board on GitHub Issues.
+ * Each HU is an issue of the repo: its number is the id (HU-<n>, unique by
+ * construction, so two people never mint the same one), its state a
+ * kj:<status> label, and who holds it the assignee. gh authenticates each
+ * person; every call names the repo explicitly.
+ */
+import { runCommand } from "../utils/process.js";
+
+export const HU_LABEL = "kj:hu";
+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 {}
+/** GitHub answered and said no (permissions, missing repo...). */
+export class BoardRejectedError extends Error {}
+/** The HU is running and someone else holds it: taking it over is explicit (release). */
+export class HuClaimedError extends Error {}
+
+// 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;
+
+async function gh(run, args) {
+  const res = await run("gh", args);
+  if (res.exitCode === 0) return res.stdout ?? "";
+  const why = (res.stderr || res.stdout || "").trim();
+  const Kind = OFFLINE.test(why) ? BoardOfflineError : BoardRejectedError;
+  throw new Kind(`gh ${args.slice(0, 2).join(" ")} failed: ${why}`);
+}
+
+// KJC-BUG-0393: a --json listing that matches nothing prints nothing at all, not "[]".
+const listOf = (stdout) => (stdout.trim() === "" ? [] : JSON.parse(stdout));
+
+async function ensureLabels(repo, run) {
+  const existing = new Set(listOf(await gh(run, ["label", "list", "-R", repo, "--search", "kj:", "--json", "name", "--limit", "100"])).map((l) => l.name));
+  for (const name of [HU_LABEL, ...STATUSES.map(statusLabel)].filter((n) => !existing.has(n))) {
+    await gh(run, ["label", "create", name, "-R", repo, "--color", "1f6feb", "--description", "Karajan HU Board"]);
+  }
+}
+
+const section = (title, items) => (items.length ? [`## ${title}`, ...items.map((i) => `- ${i}`), ""] : []);
+
+/** Create the HU as an issue; returns its id, never one made up when GitHub did not answer. */
+export async function createHu({ repo, title, acceptanceCriteria = [], tests = [], ref = null, run = runCommand }) {
+  await ensureLabels(repo, run);
+  const body = [...section("Acceptance criteria", acceptanceCriteria), ...section("Tests", tests), ...(ref ? [`Ref: ${ref}`, ""] : []), "<!-- kj:hu -->"].join("\n");
+  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}`);
+  return { short_id: `HU-${number}`, number, status: "pending", title };
+}
+
+/** Every HU of the repo, with its status and who holds it. */
+export async function listHus({ repo, run = runCommand }) {
+  const issues = listOf(await gh(run, ["issue", "list", "-R", repo, "--label", HU_LABEL, "--state", "all", "--limit", "1000", "--json", "number,title,state,labels,assignees"]));
+  return issues.map((i) => ({ short_id: `HU-${i.number}`, number: i.number, title: i.title, status: statusOf(i), claimed_by: i.assignees[0]?.login ?? null }));
+}
+
+/** The one kj:<status> of an issue; none or several is a board someone broke by hand. */
+function statusOf(issue) {
+  const found = issue.labels.map((l) => l.name).filter((n) => STATUSES.some((s) => statusLabel(s) === n));
+  if (found.length !== 1) throw new BoardRejectedError(`HU-${issue.number} has ${found.length} status labels (${found.join(", ") || "none"}): fix it to exactly one kj:<status>`);
+  return found[0].slice(3);
+}
+
+async function view(repo, number, run) {
+  const issue = JSON.parse(await gh(run, ["issue", "view", String(number), "-R", repo, "--json", "state,labels,assignees"]));
+  // KJC-BUG-0392: only issues kj created as HUs are its to move; any other issue is left alone.
+  if (!issue.labels.some((l) => l.name === HU_LABEL)) throw new BoardRejectedError(`issue #${number} is not a kj HU (no ${HU_LABEL} label): kj does not touch it`);
+  return { ...issue, number, status: statusOf({ ...issue, number }), holders: issue.assignees.map((a) => a.login) };
+}
+
+/** Move the HU to `status`; done and skipped close the issue, anything else keeps it open. */
+export async function setStatus({ repo, number, status, run = runCommand }) {
+  if (!STATUSES.includes(status)) throw new Error(`invalid status "${status}": use ${STATUSES.join(", ")}`);
+  const issue = await view(repo, number, run);
+  // Every other status label goes, not only the one read: a concurrent move must not leave two.
+  const others = STATUSES.filter((s) => s !== status).flatMap((s) => ["--remove-label", statusLabel(s)]);
+  await gh(run, ["issue", "edit", String(number), "-R", repo, "--add-label", statusLabel(status), ...others]);
+  const after = await view(repo, number, run);
+  if (after.status !== status) throw new BoardRejectedError(`HU-${number} was moved to ${after.status} at the same time: check it before moving it again`);
+  const closes = status === "done" || status === "skipped";
+  if (closes && issue.state === "OPEN") await gh(run, ["issue", "close", String(number), "-R", repo]);
+  if (!closes && issue.state === "CLOSED") await gh(run, ["issue", "reopen", String(number), "-R", repo]);
+}
+
+/** A running HU held by someone else is theirs: any move of it by `who` needs release. */
+export async function assertNotHeld({ repo, number, who, run = runCommand }) {
+  const issue = await view(repo, number, run);
+  const others = issue.holders.filter((h) => h !== who);
+  if (issue.status === "running" && others.length > 0) {
+    throw new HuClaimedError(`HU-${number} is held by ${others.join(", ")}: taking it over is explicit (release)`);
+  }
+}
+
+/** Reserve the HU for `who` (the assignee is the reservation); a running HU held by another needs release. */
+export async function claim({ repo, number, who, release = false, run = runCommand }) {
+  const issue = await view(repo, number, run);
+  const others = issue.holders.filter((h) => h !== who);
+  if (others.length > 0 && issue.status === "running" && !release) {
+    throw new HuClaimedError(`HU-${number} is held by ${others.join(", ")}: taking it over is explicit (release)`);
+  }
+  const drop = others.flatMap((h) => ["--remove-assignee", h]);
+  await gh(run, ["issue", "edit", String(number), "-R", repo, "--add-assignee", who, ...drop]);
+  // Two people may claim at once and both see it free: read it back, and the same rule
+  // on both sides (the first login in order keeps it; a release always keeps it) leaves one.
+  const after = (await view(repo, number, run)).holders;
+  const rivals = after.filter((h) => h !== who);
+  if (rivals.length > 0) {
+    if (!release && [who, ...rivals].sort()[0] !== who) {
+      await gh(run, ["issue", "edit", String(number), "-R", repo, "--remove-assignee", who]);
+      throw new HuClaimedError(`HU-${number} was claimed at the same time by ${rivals.join(", ")}, who keeps it`);
+    }
+    // The one who keeps it does not rely on the others backing off: it removes them.
+    await gh(run, ["issue", "edit", String(number), "-R", repo, ...rivals.flatMap((h) => ["--remove-assignee", h])]);
+  }
+  // Every claim, release or not, ends with who as the only holder, or says it did not.
+  const final = rivals.length > 0 ? (await view(repo, number, run)).holders : after;
+  if (final.length !== 1 || final[0] !== who) {
+    throw new HuClaimedError(`HU-${number} is held by ${final.join(", ") || "nobody"} after a concurrent claim: check it before working it`);
+  }
+  return { claimed_by: who };
+}

package/src/review/gate-gitignore.js

@@ -44,6 +44,8 @@ export const CONTRACT_BLOCK = [
   "!.karajan/rules.yml",
   // KJC-TSK-0995 (HUM-D, ADR 0018): the security level, signed when lowered, is the team's.
   "!.karajan/security-level.json",
+  // KJC-TSK-1163 (ADR 0025): which HU Board the repo uses; the team shares it.
+  "!.karajan/board.yml",
 ];
 
 /**