@karajan-family/code 4.21.0

package/src/hu/store.js

@@ -0,0 +1,392 @@
+/**
+ * HU (Historia de Usuario / User Story) storage. Persists HU batches and
+ * their stories to the session directory.
+ *
+ * @typedef {import("../types/hu.js").HUStory} HUStory
+ * @typedef {import("../types/hu.js").HUBatch} HUBatch
+ * @typedef {import("../types/hu.js").HUStatus} HUStatus
+ */
+
+import fs from "node:fs/promises";
+import path from "node:path";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+
+const execFileAsync = promisify(execFile);
+import { getKarajanHome } from "../utils/paths.js";
+
+// FUTURE: hu-storage adapter for PG/Trello/etc — currently local files only
+
+/**
+ * Valid HU story status values.
+ * @type {Readonly<{PENDING: "pending", CODING: "coding", REVIEWING: "reviewing", DONE: "done", FAILED: "failed", BLOCKED: "blocked", CERTIFIED: "certified", NEEDS_CONTEXT: "needs_context"}>}
+ */
+export const HU_STATUS = Object.freeze({
+  PENDING: "pending",
+  CODING: "coding",
+  REVIEWING: "reviewing",
+  DONE: "done",
+  FAILED: "failed",
+  BLOCKED: "blocked",
+  CERTIFIED: "certified",
+  NEEDS_CONTEXT: "needs_context"
+});
+
+/** @returns {string} Path to the hu-stories directory (evaluated at call time). */
+function getHuDir() {
+  return path.join(getKarajanHome(), "hu-stories");
+}
+
+/**
+ * Create a new HU batch from an array of story definitions.
+ * @param {string} sessionId - The session identifier.
+ * @param {Array<{id?: string, text: string, blocked_by?: string[]}>} stories - Raw story inputs.
+ * @returns {Promise<object>} The created batch object.
+ */
+export async function createHuBatch(sessionId, stories) {
+  const dir = path.join(getHuDir(), sessionId);
+  await fs.mkdir(dir, { recursive: true });
+
+  const batch = {
+    session_id: sessionId,
+    created_at: new Date().toISOString(),
+    stories: stories.map((s, i) => ({
+      id: s.id || `HU-${Date.now()}-${i}`,
+      status: "pending",
+      original: { text: s.text },
+      blocked_by: s.blocked_by || [],
+      certified: null,
+      quality: null,
+      context_requests: [],
+      created_at: new Date().toISOString(),
+      updated_at: new Date().toISOString()
+    }))
+  };
+
+  await fs.writeFile(path.join(dir, "batch.json"), JSON.stringify(batch, null, 2));
+  return batch;
+}
+
+/**
+ * Load an existing HU batch from disk.
+ * @param {string} sessionId - The session identifier.
+ * @returns {Promise<object>} The loaded batch object.
+ */
+export async function loadHuBatch(sessionId) {
+  const file = path.join(getHuDir(), sessionId, "batch.json");
+  const raw = await fs.readFile(file, "utf8");
+  return JSON.parse(raw);
+}
+
+/**
+ * Save a batch back to disk.
+ *
+ * Ensures the target directory exists before writing — the previous
+ * implementation assumed createHuBatch had already done the mkdir,
+ * which holds for the auto-HU path but NOT for plan-driven runs:
+ * `kj run --plan <id>` derives a batchSessionId from the plan id,
+ * loads the (non-existent) batch.json, falls back to in-memory, then
+ * crashes here with ENOENT on the first save attempt because no one
+ * created `~/.karajan/hu-stories/<sessionId>/`. The fix is one
+ * mkdir -p; cheap and idempotent.
+ *
+ * @param {string} sessionId - The session identifier.
+ * @param {object} batch - The batch object to persist.
+ * @returns {Promise<void>}
+ */
+export async function saveHuBatch(sessionId, batch) {
+  const dir = path.join(getHuDir(), sessionId);
+  await fs.mkdir(dir, { recursive: true });
+  batch.updated_at = new Date().toISOString();
+  await fs.writeFile(path.join(dir, "batch.json"), JSON.stringify(batch, null, 2));
+}
+
+/**
+ * Update the status of a single story within a batch.
+ * @param {object} batch - The batch object.
+ * @param {string} storyId - Story ID to update.
+ * @param {string} status - New status value.
+ * @param {object} [extra={}] - Additional fields to merge.
+ * @returns {object} The updated story.
+ */
+export function updateStoryStatus(batch, storyId, status, extra = {}) {
+  const story = batch.stories.find(s => s.id === storyId);
+  if (!story) throw new Error(`Story ${storyId} not found`);
+  story.status = status;
+  const now = new Date().toISOString();
+  story.statusChangedAt = now;
+  story.updated_at = now;
+  Object.assign(story, extra);
+  return story;
+}
+
+/**
+ * Store quality scores on a story.
+ * @param {object} batch - The batch object.
+ * @param {string} storyId - Story ID.
+ * @param {object} quality - Quality scores object.
+ * @returns {object} The updated story.
+ */
+export function updateStoryQuality(batch, storyId, quality) {
+  const story = batch.stories.find(s => s.id === storyId);
+  if (!story) throw new Error(`Story ${storyId} not found`);
+  story.quality = { ...quality, evaluated_at: new Date().toISOString() };
+  story.updated_at = new Date().toISOString();
+  return story;
+}
+
+/**
+ * Mark a story as certified with the provided certified data.
+ * @param {object} batch - The batch object.
+ * @param {string} storyId - Story ID.
+ * @param {object} certified - Certified HU data.
+ * @returns {object} The updated story.
+ */
+export function updateStoryCertified(batch, storyId, certified) {
+  const story = batch.stories.find(s => s.id === storyId);
+  if (!story) throw new Error(`Story ${storyId} not found`);
+  story.certified = certified;
+  story.status = "certified";
+  story.updated_at = new Date().toISOString();
+  return story;
+}
+
+/**
+ * Add a context request to a story and set its status to needs_context.
+ * @param {object} batch - The batch object.
+ * @param {string} storyId - Story ID.
+ * @param {{fields_needed: string[], question: string}} request - Context request.
+ * @returns {object} The updated story.
+ */
+export function addContextRequest(batch, storyId, request) {
+  const story = batch.stories.find(s => s.id === storyId);
+  if (!story) throw new Error(`Story ${storyId} not found`);
+  story.context_requests.push({
+    requested_at: new Date().toISOString(),
+    fields_needed: request.fields_needed,
+    question_to_fde: request.question,
+    answered_at: null,
+    answer: null
+  });
+  story.status = "needs_context";
+  story.updated_at = new Date().toISOString();
+  return story;
+}
+
+/**
+ * Answer the most recent pending context request and reset status to pending.
+ * @param {object} batch - The batch object.
+ * @param {string} storyId - Story ID.
+ * @param {string} answer - The FDE's answer.
+ * @returns {object} The updated story.
+ */
+export function answerContextRequest(batch, storyId, answer) {
+  const story = batch.stories.find(s => s.id === storyId);
+  if (!story) throw new Error(`Story ${storyId} not found`);
+  const pending = story.context_requests.find(r => !r.answered_at);
+  if (pending) {
+    pending.answered_at = new Date().toISOString();
+    pending.answer = answer;
+  }
+  story.status = "pending"; // back to pending for re-evaluation
+  story.updated_at = new Date().toISOString();
+  return story;
+}
+
+/**
+ * Create a lightweight history record for a pipeline run.
+ * Stores a minimal single-HU batch in the same hu-stories directory
+ * so the HU Board can pick it up alongside full batches.
+ * @param {string} sessionId - The session identifier.
+ * @param {{task: string, result: string, approved: boolean, summary?: string, timestamp?: string}} data
+ * @returns {Promise<object>} The created batch object.
+ */
+export async function createHistoryRecord(sessionId, { task, result, approved, summary, timestamp }) {
+  const ts = timestamp || new Date().toISOString();
+  const dir = path.join(getHuDir(), sessionId);
+  await fs.mkdir(dir, { recursive: true });
+
+  const batch = {
+    session_id: sessionId,
+    created_at: ts,
+    stories: [
+      {
+        id: `HU-hist-${sessionId}`,
+        status: approved ? "certified" : "failed",
+        original: { text: task },
+        blocked_by: [],
+        certified: approved ? { summary: summary || result } : null,
+        quality: null,
+        context_requests: [],
+        created_at: ts,
+        updated_at: ts
+      }
+    ],
+    history: {
+      task,
+      result,
+      approved,
+      summary: summary || null,
+      timestamp: ts
+    }
+  };
+
+  await fs.writeFile(path.join(dir, "batch.json"), JSON.stringify(batch, null, 2));
+  return batch;
+}
+
+/* ── Splitting metadata ──────────────────────────────────────────── */
+
+/**
+ * Add splitting metadata to a story within a batch.
+ * Used to track the relationship between an original HU and its sub-HUs
+ * after a split operation.
+ *
+ * @param {object} batch - The batch object.
+ * @param {string} huId - Story ID to annotate.
+ * @param {{ original_hu_id?: string, split_children?: string[], indicators_detected?: string[], heuristic_applied?: string, split_confirmed_by_fde?: boolean, validation?: object }} metadata - Splitting metadata.
+ * @returns {object} The updated story.
+ */
+export function addSplittingMetadata(batch, huId, metadata) {
+  const story = batch.stories.find(s => s.id === huId);
+  if (!story) throw new Error(`Story ${huId} not found`);
+  story.splitting = { ...(story.splitting || {}), ...metadata };
+  story.updated_at = new Date().toISOString();
+  return story;
+}
+
+/* ── Manual HU management ─────────────────────────────────────────── */
+
+/**
+ * Detect project info from the given directory.
+ * @param {string} cwd - Directory to detect project from.
+ * @returns {Promise<{ name: string, remoteUrl: string|null }>}
+ */
+export async function detectProject(cwd) {
+  const name = path.basename(cwd);
+  let remoteUrl = null;
+  try {
+    const { stdout } = await execFileAsync("git", ["remote", "get-url", "origin"], { cwd, encoding: "utf8" });
+    remoteUrl = stdout.trim();
+  } catch { /* not a git repo or no remote */ }
+  return { name, remoteUrl };
+}
+
+/**
+ * Derive a project slug from a directory path.
+ * @param {string} projectDir - Absolute path to the project.
+ * @returns {string}
+ */
+function projectSlug(projectDir) {
+  return path.basename(projectDir);
+}
+
+/**
+ * Get the batch file path for a project.
+ * @param {string} projectDir
+ * @returns {string}
+ */
+function projectBatchPath(projectDir) {
+  return path.join(getHuDir(), projectSlug(projectDir), "batch.json");
+}
+
+/**
+ * Load the project batch, or return a fresh empty batch if none exists.
+ * @param {string} projectDir
+ * @returns {Promise<object>}
+ */
+async function loadProjectBatch(projectDir) {
+  const filePath = projectBatchPath(projectDir);
+  try {
+    const raw = await fs.readFile(filePath, "utf8");
+    return JSON.parse(raw);
+  } catch { /* no saved batch for this project */
+    return {
+      project: projectSlug(projectDir),
+      created_at: new Date().toISOString(),
+      stories: []
+    };
+  }
+}
+
+/**
+ * Save a project batch to disk (auto-creates directory).
+ * @param {string} projectDir
+ * @param {object} batch
+ */
+async function saveProjectBatch(projectDir, batch) {
+  const filePath = projectBatchPath(projectDir);
+  await fs.mkdir(path.dirname(filePath), { recursive: true });
+  batch.updated_at = new Date().toISOString();
+  await fs.writeFile(filePath, JSON.stringify(batch, null, 2));
+}
+
+/**
+ * Create a manual HU (user story) for a project.
+ * Auto-creates the batch file if it doesn't exist.
+ * @param {string} projectDir
+ * @param {{ title: string, description?: string, status?: string, acceptanceCriteria?: string }} data
+ * @returns {Promise<object>} The created HU.
+ */
+export async function createManualHu(projectDir, { title, description, status, acceptanceCriteria }) {
+  if (!title) throw new Error("title is required to create a HU");
+  const batch = await loadProjectBatch(projectDir);
+  const now = new Date().toISOString();
+  const hu = {
+    id: `HU-${Date.now()}-${batch.stories.length}`,
+    title,
+    description: description || "",
+    status: status || HU_STATUS.PENDING,
+    acceptanceCriteria: acceptanceCriteria || "",
+    createdAt: now,
+    updatedAt: now
+  };
+  batch.stories.push(hu);
+  await saveProjectBatch(projectDir, batch);
+  return hu;
+}
+
+/**
+ * List all HUs for a project.
+ * @param {string} projectDir
+ * @returns {Promise<Array<{ id: string, title: string, status: string, createdAt: string }>>}
+ */
+export async function listHus(projectDir) {
+  const batch = await loadProjectBatch(projectDir);
+  return batch.stories.map(s => ({
+    id: s.id,
+    title: s.title,
+    status: s.status,
+    createdAt: s.createdAt
+  }));
+}
+
+/**
+ * Update the status of a specific HU.
+ * @param {string} projectDir
+ * @param {string} huId
+ * @param {string} status
+ * @returns {Promise<object>} The updated HU.
+ */
+export async function updateHuStatus(projectDir, huId, status) {
+  const batch = await loadProjectBatch(projectDir);
+  const hu = batch.stories.find(s => s.id === huId);
+  if (!hu) throw new Error(`HU ${huId} not found`);
+  hu.status = status;
+  hu.updatedAt = new Date().toISOString();
+  await saveProjectBatch(projectDir, batch);
+  return hu;
+}
+
+/**
+ * Get a single HU by id.
+ * @param {string} projectDir
+ * @param {string} huId
+ * @returns {Promise<object>}
+ */
+export async function getHu(projectDir, huId) {
+  const batch = await loadProjectBatch(projectDir);
+  const hu = batch.stories.find(s => s.id === huId);
+  if (!hu) throw new Error(`HU ${huId} not found`);
+  return hu;
+}

package/src/hu/worktree-bootstrap.js

@@ -0,0 +1,59 @@
+/**
+ * PAR-G (KJC-TSK-0630): make a freshly created lane worktree operative.
+ *
+ * `git worktree add` produces a clean checkout: no node_modules, no
+ * initialized submodules — and a container/bind-mounted process cannot
+ * init them itself because the worktree's real .git lives in the parent
+ * repo (gotcha reported by Jorge del Casar's worktree-docker-envs skill).
+ * Without this step, --parallel lanes die on the first `npm test` in any
+ * real project.
+ *
+ * Best-effort by contract: a failed or slow bootstrap warns and the lane
+ * continues — the acceptance tests deliver the real verdict.
+ */
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { runCommand } from "../utils/process.js";
+
+const STEP_TIMEOUT_MS = 5 * 60 * 1000;
+
+/**
+ * @param {object} params
+ * @param {string} params.worktreePath  Absolute path of the lane worktree.
+ * @param {string|null} [params.setupCommand]  session.worktree_setup — wins over auto-detect.
+ * @param {object|null} [params.logger]
+ * @param {number} [params.timeoutMs]
+ * @param {Function} [params.run]  Injectable runner (tests).
+ * @returns {Promise<{ok: boolean, steps: string[], warnings: string[]}>}
+ */
+export async function bootstrapWorktree({ worktreePath, setupCommand = null, logger = null, timeoutMs = STEP_TIMEOUT_MS, run = runCommand }) {
+  const warnings = [];
+  const steps = [];
+
+  if (existsSync(join(worktreePath, ".gitmodules"))) {
+    steps.push({ name: "submodules", cmd: "git", args: ["submodule", "update", "--init", "--recursive"] });
+  }
+
+  const explicit = typeof setupCommand === "string" && setupCommand.trim() ? setupCommand.trim() : null;
+  if (explicit) {
+    steps.push({ name: "setup", cmd: "sh", args: ["-c", explicit] });
+  } else if (existsSync(join(worktreePath, "package-lock.json"))) {
+    steps.push({ name: "deps", cmd: "npm", args: ["ci", "--no-audit", "--no-fund"] });
+  }
+
+  for (const step of steps) {
+    try {
+      const res = await run(step.cmd, step.args, { cwd: worktreePath, timeout: timeoutMs });
+      if (res.exitCode !== 0) {
+        warnings.push(`${step.name} failed (exit ${res.exitCode}): ${String(res.stderr || res.stdout || "").slice(0, 200)}`);
+      } else {
+        logger?.info?.(`worktree bootstrap: ${step.name} ok`);
+      }
+    } catch (err) {
+      warnings.push(`${step.name} threw: ${err.message}`);
+    }
+  }
+
+  for (const w of warnings) logger?.warn?.(`worktree bootstrap: ${w} — lane continues`);
+  return { ok: warnings.length === 0, steps: steps.map((s) => s.name), warnings };
+}

package/src/identity/bootstrap.js

@@ -0,0 +1,48 @@
+/**
+ * Identity lock — bootstrap (IDN-A, KJC-TSK-0762). Runs at the end of
+ * `kj harden` (and therefore `kj env install`): if this clone has no declared
+ * identity, capture it — but ONLY with a human confirming on a TTY. Headless
+ * runs never bind blindly (the first real `set --yes` bound a clone to an
+ * account another session had switched to); they report the pending step
+ * with the exact command instead. Fail-loud, never a guess.
+ */
+
+import { readIdentity, writeIdentity } from "./store.js";
+import { activeGhUser, effectiveGitEmail } from "./detect.js";
+import { createWizard, isTTY } from "../utils/wizard.js";
+
+/**
+ * @param {{projectDir: string, logger?: object, deps?: object}} args
+ * @returns {Promise<{declared: boolean, identity: object|null, pending: string|null}>}
+ */
+export async function ensureIdentity({ projectDir, logger = null, deps = {} }) {
+  const existing = readIdentity(projectDir);
+  if (existing) return { declared: true, identity: existing, pending: null };
+
+  const gh = activeGhUser(deps.hostsPath ? { hostsPath: deps.hostsPath } : {});
+  const email = effectiveGitEmail(projectDir, deps.gitFn ? { gitFn: deps.gitFn } : {});
+  const hint = `kj identity set --gh ${gh ?? "<user>"} --email ${email ?? "<email>"}`;
+  const tty = (deps.isTTY || isTTY)();
+
+  if (!tty || !gh || !email) {
+    const why = !gh || !email ? "no active gh session or git email" : "non-interactive run";
+    const pending = `identity not declared for this clone (${why}) — run: ${hint}`;
+    logger?.warn?.(`kj identity: ${pending}`);
+    return { declared: false, identity: null, pending };
+  }
+
+  const wizard = (deps.makeWizard || createWizard)();
+  try {
+    const ok = await wizard.confirm(`Bind this clone to gh ${gh} / git ${email}? (other sessions may switch gh accounts — verify)`, true);
+    if (!ok) {
+      const pending = `identity not declared (declined) — run: ${hint}`;
+      logger?.warn?.(`kj identity: ${pending}`);
+      return { declared: false, identity: null, pending };
+    }
+  } finally {
+    wizard.close();
+  }
+  const identity = writeIdentity(projectDir, { gh_user: gh, git_email: email });
+  logger?.info?.(`kj identity: declared gh ${gh} / git ${email} → .karajan/identity.local.yml (ignored by git)`);
+  return { declared: true, identity, pending: null };
+}

package/src/identity/compare.js

@@ -0,0 +1,38 @@
+/**
+ * Identity lock — compare (IDN-A, KJC-TSK-0762). Pure: declared vs effective
+ * → {ok, mismatches}. Every mismatch carries the LITERAL remedy, because the
+ * gate (IDN-B) and the hooks (IDN-C) print it instead of auto-switching —
+ * changing the user's keyring is the user's act, never the agent's.
+ */
+
+/**
+ * @param {{gh_user: string, git_email: string}|null} declared
+ * @param {{gh_user: string|null, git_email: string|null}} effective
+ * @returns {{ok: boolean, mismatches: Array<{field: string, declared: string|null, effective: string|null, remedy: string}>}}
+ */
+export function compareIdentity(declared, effective) {
+  if (!declared) {
+    return {
+      ok: false,
+      mismatches: [{ field: "identity", declared: null, effective: null, remedy: "kj identity set — this clone has no declared identity yet" }],
+    };
+  }
+  const mismatches = [];
+  if (effective.gh_user !== declared.gh_user) {
+    mismatches.push({
+      field: "gh_user",
+      declared: declared.gh_user,
+      effective: effective.gh_user ?? null,
+      remedy: effective.gh_user ? `gh auth switch --user ${declared.gh_user}` : `gh auth login (as ${declared.gh_user}) or gh auth switch --user ${declared.gh_user}`,
+    });
+  }
+  if (effective.git_email !== declared.git_email) {
+    mismatches.push({
+      field: "git_email",
+      declared: declared.git_email,
+      effective: effective.git_email ?? null,
+      remedy: `git config user.email ${declared.git_email} (or -c user.email=${declared.git_email} on the command)`,
+    });
+  }
+  return { ok: mismatches.length === 0, mismatches };
+}

package/src/identity/detect.js

@@ -0,0 +1,51 @@
+/**
+ * Identity lock — detect (IDN-A, KJC-TSK-0762). What is EFFECTIVE right now,
+ * with no network and no spawned `gh`: the active gh account is read from
+ * gh's own hosts.yml (the file `gh auth switch` mutates), the git email from
+ * `git config user.email`. Both return null when unknown — never a guess.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { execFileSync } from "node:child_process";
+import { join } from "node:path";
+import { homedir } from "node:os";
+import yaml from "js-yaml";
+
+export function defaultHostsPath() {
+  const base = process.env.GH_CONFIG_DIR || join(process.env.XDG_CONFIG_HOME || join(homedir(), ".config"), "gh");
+  return join(base, "hosts.yml");
+}
+
+/**
+ * @param {{hostsPath?: string, host?: string}} [opts]
+ * @returns {string|null} active gh login for the host, null without a session
+ */
+export function activeGhUser({ hostsPath = defaultHostsPath(), host = "github.com" } = {}) {
+  if (!existsSync(hostsPath)) return null;
+  try {
+    const parsed = yaml.load(readFileSync(hostsPath, "utf8"));
+    const user = parsed?.[host]?.user;
+    return typeof user === "string" && user.length > 0 ? user : null;
+  } catch {
+    return null;
+  }
+}
+
+const defaultGitFn = (projectDir) =>
+  execFileSync("git", ["config", "--get", "user.email"], { cwd: projectDir, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] });
+
+/**
+ * @param {string} projectDir
+ * @param {{gitFn?: (projectDir: string) => string}} [opts]
+ * @returns {string|null}
+ */
+export function effectiveGitEmail(projectDir, { gitFn = defaultGitFn } = {}) {
+  try {
+    // --get yields the single effective value; keep the last line anyway so a
+    // multi-line answer from an odd config can never leak a newline into it.
+    const out = String(gitFn(projectDir) || "").trim().split("\n").at(-1).trim();
+    return out.length > 0 ? out : null;
+  } catch {
+    return null;
+  }
+}

package/src/identity/store.js

@@ -0,0 +1,66 @@
+/**
+ * Identity lock — store (IDN-A, KJC-TSK-0762, epic KJC-PCS-0079).
+ *
+ * Each CLONE declares the identity it is worked with: the gh account and the
+ * git email. It is per developer, not per project, so it lives in
+ * `.karajan/identity.local.yml`, never tracked (this module keeps it in the
+ * .gitignore). Born from the 2026-08-20 incident: one `gh` call without an
+ * explicit account switch posted as a client account on a public repo.
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import yaml from "js-yaml";
+
+export const IDENTITY_FILE = ".karajan/identity.local.yml";
+
+/** @param {string} projectDir */
+export function identityPath(projectDir) {
+  return join(projectDir, ".karajan", "identity.local.yml");
+}
+
+/**
+ * @param {string} projectDir
+ * @returns {{gh_user: string, git_email: string, declared_at: string}|null}
+ */
+export function readIdentity(projectDir) {
+  const p = identityPath(projectDir);
+  if (!existsSync(p)) return null;
+  let parsed;
+  try {
+    parsed = yaml.load(readFileSync(p, "utf8"));
+  } catch {
+    return null; // corrupt or half-written file = no identity (review catch)
+  }
+  if (!parsed || typeof parsed !== "object" || !parsed.gh_user || !parsed.git_email) return null;
+  return { gh_user: String(parsed.gh_user), git_email: String(parsed.git_email), declared_at: String(parsed.declared_at || "") };
+}
+
+/**
+ * Write the declaration and make sure it never gets tracked. Fails loud on
+ * an incomplete identity — a half-declared lock is no lock.
+ * @param {string} projectDir
+ * @param {{gh_user: string, git_email: string}} identity
+ */
+export function writeIdentity(projectDir, identity) {
+  for (const field of ["gh_user", "git_email"]) {
+    if (!identity?.[field] || typeof identity[field] !== "string") {
+      throw new Error(`identity: "${field}" is required (got ${JSON.stringify(identity?.[field])})`);
+    }
+  }
+  // Ignore FIRST, write SECOND (review catch): if the ignore step fails, no
+  // unignored identity file is ever left on disk for git to pick up.
+  ensureIgnored(projectDir);
+  mkdirSync(join(projectDir, ".karajan"), { recursive: true });
+  const record = { gh_user: identity.gh_user, git_email: identity.git_email, declared_at: new Date().toISOString() };
+  writeFileSync(identityPath(projectDir), yaml.dump(record, { lineWidth: 120 }), "utf8");
+  return record;
+}
+
+function ensureIgnored(projectDir) {
+  const ignorePath = join(projectDir, ".gitignore");
+  const current = existsSync(ignorePath) ? readFileSync(ignorePath, "utf8") : "";
+  if (current.split("\n").some((line) => line.trim() === IDENTITY_FILE)) return;
+  const sep = current.length === 0 || current.endsWith("\n") ? "" : "\n";
+  writeFileSync(ignorePath, `${current}${sep}${IDENTITY_FILE}\n`, "utf8");
+}