karajan-code 4.42.0 → 4.44.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "karajan-code",
-  "version": "4.42.0",
+  "version": "4.44.0",
   "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

@@ -169,6 +169,16 @@ export function registerMeta(program, { pkgVersion }) {
       });
     });
 
+  // KJC-TSK-0986 (HUM-F): the invitation to enroll the phone, once per version.
+  identityCmd
+    .command("phone-invite")
+    .description("Print, once per kj version, the invitation to enroll the phone when none is enrolled (nothing otherwise)")
+    .action(async (flags) => {
+      await withConfig(pkgVersion, "identity-phone-invite", flags, async ({ config }) => {
+        process.exitCode = await identityCommand({ action: "phone-invite", config, flags: { ...flags, version: pkgVersion } });
+      });
+    });
+
   // BOOT-A (KJC-TSK-0857, cold-start ADR): the pieces existed, the ORDER did
   // not. One command from an empty directory to a project under the method.
   program

package/src/commands/doctor.js

@@ -21,6 +21,7 @@ import { getBinaryChecks } from "../checks/binaries.js";
 import { getSonarChecks } from "../checks/sonar.js";
 import { getOllamaChecks } from "../checks/ollama.js";
 import { getHarnessScorecardChecks } from "../checks/harness-scorecard.js";
+import { getPhoneChecks } from "../harden/phone-invite.js";
 import { getCiChecks } from "../checks/ci.js";
 import { getRtkChecks } from "../checks/rtk.js";
 import { getSqueezrChecks } from "../checks/squeezr.js";
@@ -67,6 +68,7 @@ function buildChecks(config, { projectOnly = false } = {}) {
     ...getSonarChecks(),
     ...getOllamaChecks(),
     ...getHarnessScorecardChecks(),
+    ...getPhoneChecks(),
     ...getPortChecks(),
     ...getTokenChecks(config),
     ...getMcpHealthChecks(),

package/src/commands/identity.js

@@ -9,6 +9,7 @@
  */
 
 import { addSigner, enrollPhone } from "../harden/phone-sign.js";
+import { phoneInvite } from "../harden/phone-invite.js";
 import { readIdentity, writeIdentity } from "../identity/store.js";
 import { activeGhUser, effectiveGitEmail } from "../identity/detect.js";
 import { compareIdentity } from "../identity/compare.js";
@@ -39,6 +40,14 @@ export async function identityCommand({ action = "show", config, flags = {}, dep
     return 0;
   }
 
+  // KJC-TSK-0986 (HUM-F): the once-per-version invitation to enroll the phone,
+  // printed for the SessionStart hook (which cannot import kj) and for scripts.
+  if (action === "phone-invite") {
+    const text = phoneInvite({ home: deps.home, version: flags.version });
+    if (text) log(text);
+    return 0;
+  }
+
   if (action === "set") {
     const candidate = { gh_user: flags.gh || effective.gh_user, git_email: flags.email || effective.git_email };
     if (!candidate.gh_user || !candidate.git_email) {

package/src/commands/pr-size.js

@@ -20,13 +20,19 @@ function mergeBase(projectDir, base) {
   throw new Error(`pr-size: no merge base with ${base} (nor origin/${base})`);
 }
 
-/** @returns {Promise<{added: number, exempt: number, testAdded: number, base: string}>} */
-export async function branchSize({ projectDir = process.cwd(), base = "main" } = {}) {
+/**
+ * @param {{projectDir?: string, base?: string, exclude?: string[]}} opts
+ *   `exclude` (KJC-BUG-0299): paths that will not be part of the commit (what
+ *   was pending before a pipeline run) are not the branch's size either.
+ * @returns {Promise<{added: number, exempt: number, testAdded: number, base: string}>}
+ */
+export async function branchSize({ projectDir = process.cwd(), base = "main", exclude = [] } = {}) {
   const from = mergeBase(projectDir, base);
+  const skip = new Set(exclude);
   // Working tree against the merge base: committed and uncommitted together.
-  let numstat = git(projectDir, ["diff", "--numstat", from]);
+  let numstat = git(projectDir, ["diff", "--numstat", from]).split("\n").filter((l) => l && !skip.has(l.split("\t").slice(2).join("\t"))).map((l) => `${l}\n`).join("");
   // New files not yet added are where a branch grows while it is written.
-  for (const file of git(projectDir, ["ls-files", "--others", "--exclude-standard"]).split("\n").filter(Boolean)) {
+  for (const file of git(projectDir, ["ls-files", "--others", "--exclude-standard"]).split("\n").filter((f) => f && !skip.has(f))) {
     let text;
     try { text = readFileSync(join(projectDir, file), "utf8"); } catch { continue; }
     if (text.includes("\0")) continue; // binary

package/src/config/defaults.js

@@ -115,6 +115,9 @@ const DEFAULTS = {
     // tests actually fail without the implementation. Off by default to
     // preserve current iteration latency.
     require_red_then_green: false,
+    // KJC-BUG-0298: with TDD the project's test suite runs every iteration and a
+    // red suite goes back to the coder, never to the reviewer.
+    require_green_suite: true,
     test_file_patterns: ["/tests/", "/__tests__/", ".test.", ".spec."],
     source_file_extensions: [".js", ".jsx", ".ts", ".tsx", ".py", ".go", ".java", ".rb", ".php", ".cs"]
   },
@@ -200,7 +203,8 @@ const DEFAULTS = {
     }
   },
   ci: { enabled: false, review_event: "kj-review", comment_event: "kj-comment", comment_prefix: true },
-  git: { auto_commit: false, auto_push: false, auto_pr: false, auto_rebase: true, branch_prefix: "feat/" },
+  // KJC-BUG-0299: pr_size_limit = lines added (CI budget count) over which the pipeline commits nothing.
+  git: { pr_size_limit: 200, auto_commit: false, auto_push: false, auto_pr: false, auto_rebase: true, branch_prefix: "feat/" },
   output: { report_dir: "./.reviews", log_level: "info", quiet: true },
   budget: {
     warn_threshold_pct: 80,

package/src/config/schema.js

@@ -118,12 +118,17 @@ const Development = v.optional(v.looseObject({
   require_test_changes: v.optional(v.boolean()),
   // KJC-TSK-0398: opt-in flag; module lands in PR1, integration in PR3.
   require_red_then_green: v.optional(v.boolean()),
+  // KJC-BUG-0298: run the suite every iteration under TDD (default true).
+  require_green_suite: v.optional(v.boolean()),
+  test_timeout_ms: v.optional(v.number()),
   test_file_patterns: v.optional(v.array(v.string())),
   source_file_extensions: v.optional(v.array(v.string())),
 }));
 
 const Git = v.optional(v.looseObject({
   auto_commit: v.optional(v.boolean()),
+  // KJC-BUG-0299: lines added (CI budget count) over which the pipeline commits nothing.
+  pr_size_limit: v.optional(v.number()),
   auto_push: v.optional(v.boolean()),
   auto_pr: v.optional(v.boolean()),
   auto_rebase: v.optional(v.boolean()),

package/src/config/test-harness.js

@@ -29,6 +29,7 @@
  * | config.testHarness key         | globalThis key                  | prod default |
  * |--------------------------------|----------------------------------|--------------|
  * | disableSonarStage              | __KJ_DISABLE_SONAR_STAGE        | false        |
+ * | disableSuiteGreenStage         | __KJ_DISABLE_SUITE_GREEN_STAGE  | false        |
  * | defaultSkillsMode              | __KJ_DEFAULT_SKILLS_MODE        | "auto"       |
  * | defaultPreflightExtended       | __KJ_DEFAULT_PREFLIGHT_EXTENDED | true         |
  * | defaultBrainDecisor            | __KJ_DEFAULT_BRAIN_DECISOR      | true         |
@@ -37,6 +38,9 @@
 
 const GLOBAL_KEYS = {
   disableSonarStage:        "__KJ_DISABLE_SONAR_STAGE",
+  // KJC-BUG-0298: the suite-green gate runs the project's REAL test command;
+  // under Vitest that is this repo's own suite inside a test. Off in tests/setup.js.
+  disableSuiteGreenStage:   "__KJ_DISABLE_SUITE_GREEN_STAGE",
   defaultSkillsMode:        "__KJ_DEFAULT_SKILLS_MODE",
   defaultPreflightExtended: "__KJ_DEFAULT_PREFLIGHT_EXTENDED",
   defaultBrainDecisor:      "__KJ_DEFAULT_BRAIN_DECISOR",
@@ -45,6 +49,7 @@ const GLOBAL_KEYS = {
 
 const PROD_DEFAULTS = Object.freeze({
   disableSonarStage:        false,
+  disableSuiteGreenStage:   false,
   defaultSkillsMode:        "auto",
   defaultPreflightExtended: true,
   defaultBrainDecisor:      true,

package/src/git/automation.js

@@ -5,6 +5,10 @@
 
 import { addCheckpoint } from "../session/store.js";
 import { pipelineSonarBlock, stampStagedVerdict } from "../review/verdict-store.js";
+import { branchSize } from "../commands/pr-size.js";
+import { pushRemedy } from "./hu-automation.js";
+import { resolveRunIdentity } from "./run-identity.js";
+import { getRunContext } from "../utils/run-context.js";
 import {
   ensureGitRepo,
   currentBranch,
@@ -13,6 +17,7 @@ import {
   syncBaseBranch,
   ensureBranchUpToDateWithBase,
   createBranch,
+  checkoutBranch,
   buildBranchName,
   commitAll,
   pushBranch,
@@ -79,7 +84,9 @@ export function commitMessageFromTask(task, taskType = null) {
     .replaceAll(/\s+/g, " ")
     .trim();
   const prefix = prefixForTaskType(taskType);
-  return `${prefix}: ${clean.slice(0, 72) || "karajan update"}`;
+  // KJC-BUG-0294 (#1993): cut on a word, never mid-word (a title with no blank keeps the hard cut).
+  const cut = clean.length > 72 ? clean.slice(0, 72).replace(/\s+\S*$/, "") : clean;
+  return `${prefix}: ${cut || "karajan update"}`;
 }
 
 /**
@@ -101,6 +108,17 @@ export function buildFinalizeCommitMessage({ task, taskType, pendingPaths }) {
   return commitMessageFromTask(task, taskType);
 }
 
+// KJC-BUG-0249 (#1896): a branch named after the card is the same on a second
+// run of that card, so one already there is taken, not recreated.
+async function checkoutRunBranch(created) {
+  try {
+    await createBranch(created);
+  } catch (err) {
+    if (!/already exists/i.test(err.message)) throw err;
+    await checkoutBranch(created);
+  }
+}
+
 export async function prepareGitAutomation({ config, task, logger, session }) {
   const enabled = config.git.auto_commit || config.git.auto_push || config.git.auto_pr;
   if (!enabled) return { enabled: false };
@@ -109,18 +127,37 @@ export async function prepareGitAutomation({ config, task, logger, session }) {
     throw new Error("Git automation requested but current directory is not a git repository");
   }
 
+  // KJC-BUG-0246 (#1893): one identity for every commit of the run, resolved
+  // once: the clone's declaration, else the repository's config, else the
+  // global one. From the global config it is said, because another session
+  // may switch it mid-run. Nothing resolvable: git refuses the commit loudly.
+  const identity = resolveRunIdentity({ projectDir: config.projectDir || process.cwd() });
+  const runContext = getRunContext();
+  if (identity && runContext) runContext.gitIdentity = identity;
+  if (identity) {
+    logger.info(`Git identity for this run: ${identity.name} <${identity.email}> (${identity.source})`);
+    if (identity.source === "global") logger.warn("The identity comes from the global git config, which another session may switch mid-run: declare this clone's with kj identity set, or set user.email in this repository");
+  } else {
+    logger.warn("No git identity resolvable (kj identity set, or git config user.name and user.email): the first commit will fail");
+  }
+
   const baseBranch = config.base_branch;
   const autoRebase = config.git.auto_rebase !== false;
+  // KJC-BUG-0294 (#1993): what is dirty or untracked NOW is not the run's; the
+  // pipeline commits only what it changes. Both names of a pending rename are
+  // kept. Fails closed: with no answer from git the run stops here rather than
+  // commit the person's pending changes later.
+  const preexisting = await listPendingPaths();
   const repoHasCommits = await hasCommits();
 
   // New repo without commits: create branch directly (no fetch/sync possible)
   if (!repoHasCommits) {
-    const created = buildBranchName(config.git.branch_prefix || "feat/", task);
+    const created = buildBranchName(config.git.branch_prefix || "feat/", task, session?.pg_task_id || null);
     // git checkout -b works even without commits (creates orphan-like branch on first commit)
     await createBranch(created);
     logger.info(`New repo — created working branch: ${created}`);
     await addCheckpoint(session, { stage: "git-prep", branch: created, created: true, newRepo: true });
-    return { enabled: true, branch: created, baseBranch, autoRebase };
+    return { enabled: true, branch: created, baseBranch, autoRebase, preexisting };
   }
 
   await fetchBase(baseBranch).catch(() => {
@@ -140,8 +177,8 @@ export async function prepareGitAutomation({ config, task, logger, session }) {
     await syncBaseBranch({ baseBranch, autoRebase }).catch(() => {
       // No remote tracking — skip sync for new projects
     });
-    const created = buildBranchName(config.git.branch_prefix || "feat/", task);
-    await createBranch(created);
+    const created = buildBranchName(config.git.branch_prefix || "feat/", task, session?.pg_task_id || null);
+    await checkoutRunBranch(created);
     branch = created;
     logger.info(`Created working branch: ${branch}`);
     await addCheckpoint(session, { stage: "git-prep", branch, created: true });
@@ -153,7 +190,7 @@ export async function prepareGitAutomation({ config, task, logger, session }) {
     await addCheckpoint(session, { stage: "git-prep", branch, created: false });
   }
 
-  return { enabled: true, branch, baseBranch, autoRebase };
+  return { enabled: true, branch, baseBranch, autoRebase, preexisting };
 }
 
 export function buildPrBody({ task: _task, stageResults }) {
@@ -194,7 +231,7 @@ export async function earlyPrCreation({ gitCtx, task, logger, session, stageResu
   if (!gitCtx?.enabled) return null;
 
   const commitMsg = commitMessageFromTask(task);
-  const commitResult = await commitAll(commitMsg);
+  const commitResult = await commitAll(commitMsg, null, { exclude: gitCtx.preexisting || [] });
   if (!commitResult.committed) {
     logger.info("earlyPrCreation: no changes to commit");
     return null;
@@ -230,7 +267,7 @@ export async function incrementalPush({ gitCtx, task, logger, session }) {
   if (!gitCtx?.enabled) return null;
 
   const commitMsg = commitMessageFromTask(task);
-  const commitResult = await commitAll(commitMsg);
+  const commitResult = await commitAll(commitMsg, null, { exclude: gitCtx.preexisting || [] });
   if (!commitResult.committed) {
     logger.info("incrementalPush: no changes to commit");
     return null;
@@ -246,8 +283,18 @@ export async function incrementalPush({ gitCtx, task, logger, session }) {
   return { commits };
 }
 
-export async function finalizeGitAutomation({ config, gitCtx, task, logger, session, stageResults = null }) {
+const DEFAULT_PR_SIZE_LIMIT = 200;
+
+export async function finalizeGitAutomation({ config, gitCtx, task, logger, session, stageResults = null, review = null, measureSize = branchSize }) {
   if (!gitCtx?.enabled) return { git: "disabled", commits: [] };
+  // KJC-BUG-0297 (#1993): the pipeline commits only what a reviewer approved. An
+  // approval that reviewed nothing (reviewer disabled) stamps no verdict and
+  // commits nothing: the changes stay in the tree, and the log says why.
+  if (review && review.reviewed === false) {
+    logger.warn("No review, no commit: the reviewer was disabled, so the pipeline commits nothing; the changes stay in the tree for a review (kj review --staged)");
+    await addCheckpoint(session, { stage: "git-commit", committed: false, skipped: "unreviewed" });
+    return { committed: false, branch: gitCtx.branch, prUrl: null, pr: null, commits: [], unreviewed: true };
+  }
 
   // Take a snapshot of pending paths BEFORE staging so we can decide
   // whether what's about to be committed is just Karajan scaffolding
@@ -268,13 +315,31 @@ export async function finalizeGitAutomation({ config, gitCtx, task, logger, sess
 
   let committed = false;
   const commits = [];
+  // KJC-BUG-0299 (#1993): the PR budget is applied BEFORE the commit, with the
+  // CI gate's own count (kj pr-size), over what this commit will contain. A
+  // step planned at 150 lines once committed 960. Where the branch cannot be
+  // measured (a fresh repo with no base yet) kj says so and goes on.
   if (config.git.auto_commit) {
+    const limit = Number(config.git.pr_size_limit) > 0 ? Number(config.git.pr_size_limit) : DEFAULT_PR_SIZE_LIMIT;
+    let size = null;
+    try {
+      size = await measureSize({ projectDir: config.projectDir || process.cwd(), base: gitCtx.baseBranch, exclude: gitCtx.preexisting || [] });
+    } catch (err) {
+      logger.warn(`pr-size: the branch could not be measured (${err.message}); the budget is not checked for this commit`);
+    }
+    if (size && size.added > limit) {
+      logger.warn(`pr-size: ${size.added} line(s) added against ${gitCtx.baseBranch}, over the budget of ${limit}: nothing committed. Split the step (several commits, several HUs); the changes stay in the tree`);
+      await addCheckpoint(session, { stage: "git-commit", committed: false, skipped: "over-budget", added: size.added, limit });
+      return { committed: false, branch: gitCtx.branch, prUrl: null, pr: null, commits: [], overBudget: { added: size.added, limit } };
+    }
     // ENV-F1: this path only runs after the pipeline's reviewer approved,
     // so stamp that verdict for the staged diff — the v4 pre-commit gate
     // (when the repo opted in) accepts the pipeline's own commit.
     const commitResult = await commitAll(commitMsg, null, {
-      beforeCommit: () => stampStagedVerdict({
+      exclude: gitCtx.preexisting || [],
+      beforeCommit: ({ paths } = {}) => stampStagedVerdict({
         projectDir: config?.projectDir || process.cwd(),
+        paths,
         reviewer: config?.reviewer || "pipeline-reviewer",
         summary: `kj run session ${session?.id || ""}: reviewer approved`.trim(),
         // KJC-TSK-0838: the sonar stage result travels with the stamp.
@@ -285,7 +350,12 @@ export async function finalizeGitAutomation({ config, gitCtx, task, logger, sess
     if (commitResult.commit) {
       commits.push(commitResult.commit);
     }
-    await addCheckpoint(session, { stage: "git-commit", committed });
+    // KJC-BUG-0294: what was pending before the run stays out of the commit and is named;
+    // if the run also touched one of those files, its edit is in the tree, not in the commit.
+    if (commitResult.leftOut?.length) {
+      logger.warn(`Left out of the commit, pending before the run (review and commit them yourself): ${commitResult.leftOut.join(", ")}`);
+    }
+    await addCheckpoint(session, { stage: "git-commit", committed, leftOut: commitResult.leftOut || [] });
     logger.info(committed ? "Committed changes" : "No changes to commit");
   }
 
@@ -312,7 +382,12 @@ export async function finalizeGitAutomation({ config, gitCtx, task, logger, sess
   }
 
   if (remoteAvailable && (config.git.auto_push || config.git.auto_pr)) {
-    await pushBranch(gitCtx.branch);
+    // KJC-BUG-0248 (#1895): a refused push stops the run loudly, with its remedy.
+    try {
+      await pushBranch(gitCtx.branch);
+    } catch (err) {
+      throw new Error(`push of ${gitCtx.branch} failed: ${err.message}. ${pushRemedy(err.message, gitCtx.branch)}`, { cause: err });
+    }
     await addCheckpoint(session, { stage: "git-push", branch: gitCtx.branch });
     logger.info(`Pushed branch: ${gitCtx.branch}`);
   }

package/src/git/hu-automation.js

@@ -69,6 +69,33 @@ async function resolveExistingBranchRef(preferred) {
   return preferred; // give up; caller will surface the original error
 }
 
+/** Whether a branch name references the card, as a whole token (BB-002 is not BB-0022). */
+export function branchReferencesCard(branch, cardId) {
+  const id = String(cardId).replaceAll(/[.*+?^${}()|[\]\\]/g, String.raw`\$&`);
+  return new RegExp(`(^|[^a-z0-9])${id}([^a-z0-9]|$)`, "i").test(String(branch || ""));
+}
+
+async function cardBranch({ cardId, story, config, logger }) {
+  const head = await runCommand("git", ["rev-parse", "--abbrev-ref", "HEAD"], {});
+  const current = head.exitCode === 0 ? head.stdout.trim() : "";
+  if (branchReferencesCard(current, cardId)) {
+    logger.info(`HU ${story.id}: on '${current}', the branch of card ${cardId}`);
+    return current;
+  }
+  const branchName = buildHuBranchName(config.git?.branch_prefix || "feat/", { id: cardId, title: story.title });
+  // A card branch left by an earlier run keeps its commits: taken, never reset.
+  const exists = await runCommand("git", ["rev-parse", "--verify", "--quiet", branchName], {});
+  const base = exists.exitCode === 0 ? null : await resolveExistingBranchRef(config.base_branch || "main");
+  const how = base ? `created from '${base}'` : "taken";
+  const res = await runCommand("git", base ? ["checkout", "-b", branchName, base] : ["checkout", branchName], {});
+  if (res.exitCode !== 0) {
+    logger.warn(`HU git: branch ${branchName} could not be ${how}: ${res.stderr}`);
+    return null;
+  }
+  logger.info(`HU ${story.id}: branch '${branchName}' ${how} for card ${cardId}`);
+  return branchName;
+}
+
 /**
  * Create a branch for an HU starting from its resolved base.
  * Returns the branch name created (or null if git automation is disabled).
@@ -80,10 +107,22 @@ async function resolveExistingBranchRef(preferred) {
  * @param {object} params.logger
  * @returns {Promise<string|null>}
  */
-export async function prepareHuBranch({ story, huBranches, config, logger }) {
+export async function prepareHuBranch({ story, huBranches, config, logger, cardId = null }) {
   if (!config.git?.auto_commit && !config.git?.auto_push && !config.git?.auto_pr) {
     return null;
   }
+  // KJC-BUG-0249 (#1896): with a Planning Game card the run is that card's
+  // work and lives on ONE branch named after it: the current one when it
+  // already references the card, else feat/<CARD-ID>-<slug>, created once
+  // and shared by every HU. HU ids name branches only when there is no card.
+  if (cardId) {
+    const known = huBranches.get(cardId);
+    const branch = known ?? (await cardBranch({ cardId, story, config, logger }));
+    if (!branch) return null;
+    huBranches.set(cardId, branch);
+    huBranches.set(story.id, branch);
+    return branch;
+  }
   const baseBranch = resolveHuBase(story, huBranches, config.base_branch || "main");
   const effectiveBase = await resolveExistingBranchRef(baseBranch);
   if (effectiveBase !== baseBranch) {
@@ -103,18 +142,37 @@ export async function prepareHuBranch({ story, huBranches, config, logger }) {
   return branchName;
 }
 
+/**
+ * KJC-BUG-0248 (#1895): the remedy for a push git refused, read from its
+ * message. GitHub refuses a push that adds or changes a workflow file when
+ * the token lacks the `workflow` scope; that one has an exact fix.
+ */
+export function pushRemedy(message, branch) {
+  if (/workflow/i.test(message) && /scope/i.test(message)) {
+    return `the token lacks the workflow scope: run gh auth refresh -h github.com -s workflow, then git push -u origin ${branch}`;
+  }
+  return `push the branch yourself: git push -u origin ${branch}`;
+}
+
+/** The warnings a run reports when the push or the PR of any HU failed. */
+export function collectGitWarnings(results) {
+  return results.flatMap((r) => (r.result?.git?.errors ?? []).map((e) => `${r.huId}: ${e.step} failed: ${e.message}. ${e.remedy}`));
+}
+
 /**
  * After an HU is approved, commit its changes and optionally push + create PR.
+ * A push or PR that fails is not only a warn line: it travels in `errors`
+ * with its remedy, so the run's result says it (KJC-BUG-0248).
  *
  * @param {object} params
  * @param {object} params.story
  * @param {string} params.branchName
  * @param {object} params.config
  * @param {object} params.logger
- * @returns {Promise<{committed: boolean, pushed: boolean, prUrl: string|null}>}
+ * @returns {Promise<{committed: boolean, pushed: boolean, prUrl: string|null, branch: string|null, errors: Array<{step: string, message: string, remedy: string}>}>}
  */
 export async function finalizeHuCommit({ story, branchName, config, logger, cwd = null }) {
-  const result = { committed: false, pushed: false, prUrl: null };
+  const result = { committed: false, pushed: false, prUrl: null, branch: branchName || null, errors: [] };
   if (!branchName) return result;
 
   const changed = await hasChanges(cwd);
@@ -139,7 +197,9 @@ export async function finalizeHuCommit({ story, branchName, config, logger, cwd
       result.pushed = true;
       logger.info(`HU ${story.id}: pushed '${branchName}'`);
     } catch (err) {
-      logger.warn(`HU ${story.id}: push failed: ${err.message}`);
+      const remedy = pushRemedy(err.message, branchName);
+      result.errors.push({ step: "push", message: err.message, remedy });
+      logger.warn(`HU ${story.id}: push failed: ${err.message} (${remedy})`);
     }
   }
 
@@ -163,7 +223,9 @@ export async function finalizeHuCommit({ story, branchName, config, logger, cwd
       result.prUrl = url;
       logger.info(`HU ${story.id}: PR created ${url}`);
     } catch (err) {
-      logger.warn(`HU ${story.id}: PR creation failed: ${err.message}`);
+      const remedy = `open the PR yourself: gh pr create --base ${config.base_branch || "main"} --head ${branchName}`;
+      result.errors.push({ step: "pr", message: err.message, remedy });
+      logger.warn(`HU ${story.id}: PR creation failed: ${err.message} (${remedy})`);
     }
   }
 

package/src/git/run-identity.js

@@ -0,0 +1,48 @@
+/**
+ * KJC-BUG-0246 (#1893): one git identity for the whole run.
+ *
+ * Of five commits of one run, three carried one account and two another: the
+ * pipeline let git resolve the author at every commit, and the host works with
+ * several global identities that other sessions switch at will. The identity
+ * is resolved ONCE, before the first commit, in a fixed order: the clone's
+ * declaration (`kj identity set`, .karajan/identity.local.yml), else the
+ * repository's own config, else the global one. Nothing resolvable is null,
+ * never a guess: git itself refuses the commit loudly in that case.
+ */
+import { execFileSync } from "node:child_process";
+import { readIdentity } from "../identity/store.js";
+
+const defaultGitFn = (projectDir, args) =>
+  execFileSync("git", ["config", ...args], { cwd: projectDir, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] });
+
+const configValue = (gitFn, projectDir, args) => {
+  try {
+    const out = String(gitFn(projectDir, args) || "").trim();
+    return out.length > 0 ? out : null;
+  } catch {
+    return null;
+  }
+};
+
+/**
+ * @param {{projectDir: string, gitFn?: (projectDir: string, args: string[]) => string}} opts
+ * @returns {{name: string, email: string, source: "declared"|"repo"|"global"}|null}
+ */
+export function resolveRunIdentity({ projectDir, gitFn = defaultGitFn }) {
+  const declared = readIdentity(projectDir);
+  const local = (key) => configValue(gitFn, projectDir, ["--local", "--get", `user.${key}`]);
+  const effective = (key) => configValue(gitFn, projectDir, ["--get", `user.${key}`]);
+  const localEmail = local("email");
+  const email = declared?.git_email ?? localEmail ?? effective("email");
+  const name = local("name") ?? effective("name");
+  if (!email || !name) return null;
+  let source = "global";
+  if (declared) source = "declared";
+  else if (localEmail) source = "repo";
+  return { name, email, source };
+}
+
+/** The environment that pins author and committer for one git command. */
+export const identityEnv = ({ name, email }) => ({
+  GIT_AUTHOR_NAME: name, GIT_AUTHOR_EMAIL: email, GIT_COMMITTER_NAME: name, GIT_COMMITTER_EMAIL: email,
+});

package/src/harden/hook-templates.js

@@ -133,6 +133,12 @@ export function hookBody(hook, cmds = {}, { globalHooksDir = null, baseBranch =
         `if git diff --cached -- . ':(exclude).github/workflows/kj-no-ai-attribution.yml' ':(exclude)src/harden/hook-templates.js' ':(exclude)src/harden/workflow-templates.js' ':(exclude)src/harden/sentinel-hooks.js' ':(exclude)scripts/ai-attribution-guard.yml' ':(exclude)tests/harden/attribution-guard.test.js' ':(exclude)tests/harden/sentinel-hooks.test.js' ':(exclude).karajan/hooks/pre-commit' ':(exclude).karajan/hooks/commit-msg' ':(exclude).karajan/harness/' | grep '^+' | grep -qiE '${AI_ATTRIBUTION}|generated with \\[?claude'; then`,
         "  echo 'kj harden: AI attribution is not allowed in committed content'; exit 1",
         "fi",
+        "# KJC-BUG-0296 (issue #1989): the host agent's runtime and local state never",
+        "# enter a commit, however they were staged (a blanket `git add -A` put a",
+        "# Claude scheduler lock into main). Checked on the staged list itself.",
+        "if git diff --cached --name-only | grep -qE '^(\\.claude/[^/]*\\.lock|\\.claude/scheduled_tasks\\.lock|\\.kj/|\\.karajan/identity\\.local\\.yml|\\.karajan/harness/sentinel-state\\.json)'; then",
+        "  echo 'kj harden: agent runtime files are staged (.claude/*.lock, .kj/, identity.local.yml, sentinel-state.json) — unstage them: git restore --staged <path>'; exit 1",
+        "fi",
         "# v4 review gate (ENV-C1, opt-in via `kj review --install-gate`):",
         "# a staged diff only enters with a recorded cross-AI approved verdict.",
         "# KJC-BUG-0165: the gate is active once the marker is COMMITTED (HEAD),",

package/src/harden/phone-invite.js

@@ -0,0 +1,53 @@
+/**
+ * KJC-TSK-0986 (HUM-F, ADR 0018): whoever runs kj without a phone enrolled
+ * learns it once per version, not the day the maximum level (HUM-D) refuses a
+ * seal. One text, used by the SessionStart notice, by `kj doctor` and, when
+ * HUM-D lands, by the deny itself: what the signature protects, how to enroll,
+ * and how one proceeds today without it.
+ */
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+
+import { isPhoneEnrolled } from "./phone-sign.js";
+import { STRATEGY } from "../checks/types.js";
+
+export const PHONE_INVITE =
+  "El móvil no está enrolado: los sellos (kj harden --commit), las aprobaciones y los comandos del catálogo se firman hoy con un código tecleado, con menos garantía. Enrólalo con kj identity enroll-phone <clave pública de la app>: cada acto queda atado a tu clave privada, que nunca sale del móvil (ADR 0018).";
+
+const markerPath = (home) => join(home ?? homedir(), ".karajan", "phone-invite.json");
+
+/**
+ * The invitation, once per kj version, or null (phone enrolled, or already said
+ * for this version). Saying it records it; a marker that cannot be written
+ * never silences the invitation.
+ * @param {{home?: string, version?: string}} [opts]
+ * @returns {string|null}
+ */
+export function phoneInvite({ home, version = "unknown" } = {}) {
+  if (isPhoneEnrolled({ home })) return null;
+  let seen = null;
+  try { seen = JSON.parse(readFileSync(markerPath(home), "utf8")).version; } catch { /* never invited */ }
+  if (seen === version) return null;
+  try {
+    mkdirSync(dirname(markerPath(home)), { recursive: true });
+    writeFileSync(markerPath(home), `${JSON.stringify({ version, at: new Date().toISOString() })}\n`, "utf8");
+  } catch { /* the invitation still goes out */ }
+  return PHONE_INVITE;
+}
+
+/** `kj doctor`: WARN while the phone is not enrolled, with the same text. */
+export function createPhoneCheck({ home } = {}) {
+  return {
+    name: "phone-enrolled",
+    label: "móvil enrolado (firma de sellos y aprobaciones)",
+    strategy: STRATEGY.MANUAL,
+    describe: "Whether a phone's public key is enrolled for the supervisor seal and approvals (ADR 0018)",
+    async detect() {
+      if (isPhoneEnrolled({ home })) return { ok: true, severity: "info", detail: "clave pública en ~/.karajan/supervisor-phone.json" };
+      return { ok: false, severity: "warn", detail: PHONE_INVITE, fix: "kj identity enroll-phone <clave pública de la app>" };
+    },
+  };
+}
+
+export const getPhoneChecks = (opts) => [createPhoneCheck(opts)];

package/src/harden/sentinel/sessionstart.mjs

@@ -38,6 +38,11 @@ process.stdin.on("end", () => {
       lines.push("Karajan (reglas que la compactación se lleva):", ...RULES, `Estado: rama ${branch}, card ${card}${unmoved}.`);
     }
     if (drift) lines.push(`Karajan: ${drift}`);
+    // KJC-TSK-0986 (HUM-F, ADR 0018): once per kj version, the invitation to
+    // enroll the phone when none is; kj decides and remembers, the hook relays.
+    const invite = spawnSync("kj", ["identity", "phone-invite"], { encoding: "utf8", timeout: 8000 });
+    const inviteText = invite.status === 0 ? String(invite.stdout || "").trim() : "";
+    if (inviteText) lines.push(`Karajan: ${inviteText}`);
     if (lines.length === 0) process.exit(0);
     process.stdout.write(JSON.stringify({ hookSpecificOutput: { hookEventName: "SessionStart", additionalContext: lines.join("\n") } }));
   } catch { /* never fails a session */ }

package/src/harden/sentinel-hooks.js

@@ -570,6 +570,25 @@ process.stdin.on("end", () => {
         }
       }
     }
+    // KJC-BUG-0252 (#1899): una issue para karajan-code sale por kj report-issue
+    // (sanitiza y busca duplicados), nunca por gh issue create a mano.
+    {
+      const ghIssue = String(input.command || "");
+      if (tool === "Bash" && /(^|[^a-zA-Z])gh([^a-zA-Z]|$)/.test(ghIssue) && /(^|[^a-z])issue([^a-z]|$)/.test(ghIssue) && /(^|[^a-z])create([^a-z]|$)/.test(ghIssue)) {
+        // The target: --repo/-R, an inline or inherited GH_REPO, else the
+        // checkout's own origin, which is what gh takes (review catches).
+        const inlineRepo = /(^|[^A-Z_])GH_REPO=([^ ]+)/.exec(ghIssue);
+        let target = optionValues(ghIssue, ["--repo", "-R"]).at(-1) || (inlineRepo ? inlineRepo[2] : "") || String(process.env.GH_REPO || "");
+        if (!target) {
+          const origin = spawnSync("git", ["config", "--get", "remote.origin.url"], { cwd: ROOT, encoding: "utf8" });
+          target = String(origin.stdout || "").trim();
+        }
+        if (/karajan-code([^a-z0-9]|$)/i.test(target)) {
+          console.error("karajan sentinel: las issues para karajan-code salen por kj report-issue (sanitiza y busca issues parecidas), no por gh issue create." + doc("report-issue"));
+          process.exit(2);
+        }
+      }
+    }
     // KJC-TSK-0822 v1.1: enrolar (o pisar) la clave del movil es acto humano
     // — si un agente pudiera enrolar una clave SUYA, contestaria la capa 5 el
     // solo. Ni el comando ni el fichero de enrolamiento desde la sesion.
@@ -1096,6 +1115,39 @@ process.stdin.on("end", () => {
         console.error("karajan sentinel: el gate de commit no se apaga con una bandera — el review cruzado y la policy corren en el hook, y saltarselos deja el diff sin veredicto. Si el hook esta roto, arreglalo; si de verdad hace falta saltarlo, lo hace tu usuario en su terminal." + doc("escapes"));
         process.exit(2);
       }
+      // KJC-BUG-0296 (#1989): the staged set is reviewed by name. A blanket
+      // git add -A / git add . / git add -u put a Claude scheduler lock into
+      // main; and the agent's runtime files (.claude/*.lock, .kj/, the local
+      // identity, the Sentinel state, the harness) are never staged at all.
+      // (No backticks in this template: they would end the string.)
+      const RUNTIME = /^(\\.\\/)?(\\.claude\\/[^/]*\\.lock|\\.kj\\/|\\.karajan\\/identity\\.local\\.yml|\\.karajan\\/harness\\/sentinel-state\\.json)/;
+      for (const ws of shellSegments(cmd)) {
+        const gi = ws.findIndex((x) => x.slice(x.lastIndexOf("/") + 1) === "git");
+        if (gi < 0) continue;
+        // git's own options come before the verb: -C <dir>, -c k=v, --git-dir=…
+        let vi = gi + 1;
+        while (vi < ws.length && ws[vi].startsWith("-")) vi += ws[vi] === "-C" || ws[vi] === "-c" ? 2 : 1;
+        if (ws[vi] !== "add") continue;
+        const args = ws.slice(vi + 1);
+        // The pathspec: after "--" if present, else every non-option word. "." is
+        // the whole tree whichever way it is written; -A/-u with no pathspec too.
+        const dash = args.indexOf("--");
+        const spec = dash >= 0 ? args.slice(dash + 1) : args.filter((a) => !a.startsWith("-"));
+        const whole = spec.some((a) => a === "." || a === "./");
+        const blanket = whole || (args.some((a) => a === "-A" || a === "--all" || a === "-u" || a === "--update") && spec.length === 0);
+        if (blanket) {
+          console.error("karajan sentinel: git add -A / . / -u stagea lo que no has revisado — stagea por nombre (git add -- <ruta>...) y mira git diff --cached --stat antes de commitear." + doc("commit-gate"));
+          process.exit(2);
+        }
+        // Directories too: .kj is runtime whole; .claude and .karajan hold the
+        // contract, so only a forced add (-f, past the ignore) reaches their locks.
+        const force = args.some((a) => a === "-f" || a === "--force");
+        const runtime = spec.find((a) => RUNTIME.test(a) || /^(\\.\\/)?\\.kj\\/?$/.test(a) || (force && /^(\\.\\/)?(\\.claude|\\.karajan)\\/?$/.test(a)));
+        if (runtime) {
+          console.error("karajan sentinel: " + runtime + " es runtime del agente (locks de .claude, .kj/, identidad local, estado del Sentinel) y no se commitea — fuera del stage." + doc("commit-gate"));
+          process.exit(2);
+        }
+      }
       const MERGE = /\\bgh\\s+pr\\s+merge(\\s+(\\d+))?/;
       const ADVANCE = /\\bgit\\s+commit\\b|\\bgit\\s+push\\b|\\bgh\\s+pr\\s+create\\b/; // push also falls under violations() — explicit here too (review catch)
       const mergeM = cmd.match(MERGE);

package/src/orchestrator/config-init.js

@@ -360,10 +360,12 @@ export function applyAutoSimplify({ pipelineFlags, triageLevel, config, flags, l
   if (flags.mode) return false;
   if (flags.enableReviewer !== undefined || flags.enableTester !== undefined) return false;
 
-  pipelineFlags.reviewerEnabled = false;
+  // KJC-BUG-0297 (#1993): a simple task still gets its cross-AI review. With
+  // the reviewer off, the gate's stub read as an approval and the pipeline
+  // stamped a verdict nobody gave and committed it. Only the tester is lighter.
   pipelineFlags.testerEnabled = false;
 
-  const disabledRoles = ["reviewer", "tester"];
+  const disabledRoles = ["tester"];
   logger.info(`Simple task (${triageLevel}) — lightweight pipeline (disabled: ${disabledRoles.join(", ")})`);
   emitProgress(
     emitter,

package/src/orchestrator/drivers/iteration-phases/quality-gates.js

@@ -21,6 +21,7 @@ import {
 import { runImpeccableStage } from "../../post-loop-stages.js";
 import { runPerfStage } from "../../stages/perf-stage.js";
 import { runTddDisciplineStage } from "../../stages/tdd-discipline-stage.js";
+import { runSuiteGreenStage } from "../../stages/suite-green-stage.js";
 import { runToolJudgeStage } from "../../stages/tool-judge-stage.js";
 import { tryCiComment } from "../../ci-integration.js";
 
@@ -29,6 +30,12 @@ export async function runQualityGateStages({ config, logger, emitter, eventBase,
   if (tddResult.action === "pause") return { action: "return", result: tddResult.result };
   if (tddResult.action === "continue") return { action: "continue" };
 
+  // KJC-BUG-0298 (#1993): with TDD, a red suite never reaches the reviewer.
+  if (config.development?.methodology === "tdd" && config.development?.require_green_suite !== false && config?.testHarness?.disableSuiteGreenStage !== true) {
+    const green = await runSuiteGreenStage({ config, logger, emitter, eventBase, session, iteration: i });
+    if (green.action === "continue") return { action: "continue" };
+  }
+
   // KJC-TSK-0398 PR3: opt-in red-then-green check.
   if (config.development?.require_red_then_green) {
     const disc = await runTddDisciplineStage({

package/src/orchestrator/drivers/iteration-phases/reviewer-gate.js

@@ -29,9 +29,11 @@ export async function runReviewerGateStage({ pipelineFlags, reviewerRole, config
   };
   const reviewerResult = await runStage(stageRegistry.get("reviewer"), reviewerCtx);
   if (reviewerResult === null) {
+    // KJC-BUG-0297 (#1993): `reviewed: false` so the pipeline never stamps a
+    // verdict nobody gave nor commits on it (finalizeGitAutomation).
     return {
       action: "ok",
-      review: { approved: true, blocking_issues: [], non_blocking_suggestions: [], summary: "Reviewer disabled by pipeline", confidence: 1 }
+      review: { approved: true, reviewed: false, blocking_issues: [], non_blocking_suggestions: [], summary: "Reviewer disabled by pipeline: nothing was reviewed", confidence: 0 }
     };
   }
   if (reviewerResult.action === "pause") return { action: "return", result: reviewerResult.result };

package/src/orchestrator/drivers/post-loop.js

@@ -107,7 +107,7 @@ export async function handlePostLoopStages({ config, session, emitter, eventBase
 }
 
 export async function finalizeApprovedSession({ config, gitCtx, task, logger, session, stageResults, emitter, eventBase, budgetSummary, pgCard, pgProject, review, i, rtkTracker }) {
-  const gitResult = await finalizeGitAutomation({ config, gitCtx, task, logger, session, stageResults });
+  const gitResult = await finalizeGitAutomation({ config, gitCtx, task, logger, session, stageResults, review });
 
   // Accumulate final commits for PG card lifecycle tracking
   if (gitResult?.commits?.length) {

package/src/orchestrator/drivers/run-hu-batch.js

@@ -57,7 +57,7 @@ export async function runHuBatch({ ctx, task, askQuestion, emitter, logger }) {
   // Per-HU pipeline: focused max_iterations, fresh Brain state, own git branch.
   const huMaxIterations = ctx.config.hu_max_iterations ?? 3;
   const huBranches = new Map();
-  const { prepareHuBranch, finalizeHuCommit } = await import("../../git/hu-automation.js");
+  const { prepareHuBranch, finalizeHuCommit, collectGitWarnings } = await import("../../git/hu-automation.js");
 
   // PR F (v2.7.5): the per-HU loop needs three pieces of plan context:
   //   • ADRs (loaded once from disk, applies to every HU on this plan)
@@ -142,7 +142,7 @@ export async function runHuBatch({ ctx, task, askQuestion, emitter, logger }) {
         branchName = `kj-hu-${story.id}`;
         huBranches.set(story.id, branchName);
       } else {
-        branchName = await prepareHuBranch({ story, huBranches, config: laneConfig, logger });
+        branchName = await prepareHuBranch({ story, huBranches, config: laneConfig, logger, cardId: ctx.session?.pg_task_id || null });
       }
 
       // KJC-TSK-0408 step 2: snapshot del workspace ANTES de invocar al
@@ -257,8 +257,8 @@ export async function runHuBatch({ ctx, task, askQuestion, emitter, logger }) {
             );
             if (pendingGherkinTests.length === 0) {
               logger.info(`HU ${story.id}: all shell acceptance tests PASSED, no Gherkin to translate — approved`);
-              await finalizeHuCommit({ story, branchName, config: laneConfig, logger, cwd: worktreePath });
-              return { approved: true, sessionId: laneSession.id, reason: "acceptance_tests_passed" };
+              const git = await finalizeHuCommit({ story, branchName, config: laneConfig, logger, cwd: worktreePath });
+              return { approved: true, sessionId: laneSession.id, reason: "acceptance_tests_passed", git };
             }
 
             // Shell tests passed; Gherkin needs translation. Invoke the
@@ -276,8 +276,8 @@ export async function runHuBatch({ ctx, task, askQuestion, emitter, logger }) {
             const testerStage = testerOutcome?.stageResult;
             if (testerOutcome?.action !== "continue" && testerStage?.verdict === "pass") {
               logger.info(`HU ${story.id}: tester translated Gherkin and verdict=pass — approved`);
-              await finalizeHuCommit({ story, branchName, config: laneConfig, logger, cwd: worktreePath });
-              return { approved: true, sessionId: laneSession.id, reason: "acceptance_tests_passed" };
+              const git = await finalizeHuCommit({ story, branchName, config: laneConfig, logger, cwd: worktreePath });
+              return { approved: true, sessionId: laneSession.id, reason: "acceptance_tests_passed", git };
             }
 
             // Tester rejected (translated tests failed or coverage
@@ -375,7 +375,10 @@ export async function runHuBatch({ ctx, task, askQuestion, emitter, logger }) {
       const laneCtx = { ...ctx, config: laneConfig, pipelineFlags: laneFlags, session: laneSession, brainCtx: laneBrain, plannedTask: lanePlannedTask };
       const result = await runIterationLoop(laneCtx, { task: huTask, askQuestion, emitter, logger });
       if (result?.approved) {
-        await finalizeHuCommit({ story, branchName, config: laneConfig, logger, cwd: worktreePath });
+        // KJC-BUG-0248: what the HU's push or PR said joins what the loop recorded.
+        const git = await finalizeHuCommit({ story, branchName, config: laneConfig, logger, cwd: worktreePath });
+        const prev = result.git ?? {};
+        return { ...result, git: { ...prev, prUrl: prev.prUrl ?? git.prUrl, errors: [...(prev.errors ?? []), ...git.errors] } };
       }
       return result;
     },
@@ -415,12 +418,17 @@ export async function runHuBatch({ ctx, task, askQuestion, emitter, logger }) {
     }
   }
 
+  // KJC-BUG-0248 (#1895): a push or a PR that failed is said in the result
+  // the host reads, not only in a warn line of the log.
+  const warnings = collectGitWarnings(subPipelineResult.results);
+  for (const w of warnings) logger.warn(`git automation: ${w}`);
   const finalResult = {
     approved: subPipelineResult.approved,
     sessionId: ctx.session.id,
     huResults: subPipelineResult.results,
     blockedIds: subPipelineResult.blockedIds,
-    planId: ctx.session._planRef?.planId || null
+    planId: ctx.session._planRef?.planId || null,
+    ...(warnings.length > 0 ? { warnings } : {})
   };
   await writeHistoryRecord({ sessionId: ctx.session.id, task, result: finalResult, logger });
   return { handled: true, result: finalResult };

package/src/orchestrator/hu-sub-pipeline.js

@@ -172,6 +172,8 @@ function buildHuOutcome({ story: _story, iterResult, status, startedAt, huBudget
   if (Array.isArray(r.deferredIssues)) {
     for (const d of r.deferredIssues) blockers.push(typeof d === "string" ? d : d.message || JSON.stringify(d));
   }
+  // KJC-BUG-0248: a push or PR that failed is a blocker the board shows.
+  for (const e of git.errors ?? []) blockers.push(`${e.step} failed: ${e.message}. ${e.remedy}`);
   // Plain-Spanish, one-or-two sentences.
   let summary;
   if (r.review?.summary) summary = String(r.review.summary);

package/src/orchestrator/preflight-checks.js

@@ -33,6 +33,7 @@ import { getMcpHealthChecks } from "../checks/mcp-health.js";
 import { getSkillsChecks } from "../checks/skills.js";
 import { getProjectChecks } from "../checks/project-checks.js";
 import { resolveTestHarness } from "../config/test-harness.js";
+import { collectGuaranteeFacts } from "../checks/guarantee-level.js";
 
 function parseJsonSafe(text) {
   try {
@@ -231,6 +232,26 @@ export async function runPreflightChecks({ config, logger, emitter, eventBase, r
     errors: [],
   };
 
+  // KJC-BUG-0252 (#1899): on a Claude host without the Sentinel harness nothing
+  // governs the host's own actions (issues by hand, commits, pushes, merges);
+  // a run reported Tier A OFF and the agent routed around every gate. kj never
+  // fakes that supervision: the run stops here, with the remedy.
+  const guarantee = collectGuaranteeFacts({ projectDir: config.projectDir || process.cwd() });
+  if (guarantee.host === "claude" && !guarantee.tierA.active) {
+    result.ok = false;
+    result.checks.push({ name: "sentinel-harness", ok: false, detail: guarantee.tierA.reason });
+    result.errors.push({
+      check: "sentinel-harness",
+      message: "Tier A tool-time is OFF: a Claude host without the Sentinel harness, so nothing governs the host's own actions outside this run.",
+      fix: "Run kj harden (kj init installs it) and seal it with kj harden --commit; then run again.",
+    });
+    logger.error("Preflight: Sentinel harness not installed on a Claude host — run kj harden");
+    emitProgress(emitter, makeEvent("preflight:end", { ...eventBase, stage: "preflight" }, {
+      status: "fail", message: "Preflight FAILED — Sentinel harness not installed", detail: result
+    }));
+    return result;
+  }
+
   // Resolve extended preflight opt-in early so the short-circuit below can see it.
   // Post-v2.7.5 this no longer reads globalThis directly — config.testHarness
   // is populated by the loader from the global or the default.

package/src/orchestrator/stages/suite-green-stage.js

@@ -0,0 +1,55 @@
+/**
+ * KJC-BUG-0298 (#1993): with TDD, a red suite never reaches the reviewer. A
+ * step whose test was added without its implementation was approved with one
+ * failing file, because nothing in the iteration RAN the tests: the
+ * verification gate counts changed lines, the TDD check asks that tests changed
+ * alongside sources, and the red-then-green discipline is opt-in. This stage
+ * runs the project's own test command (the one kj harden resolves: npm test, a
+ * known framework, pytest, go test) and hands a red suite back to the coder.
+ * Opt-out: `development.require_green_suite: false`.
+ */
+import { addCheckpoint, saveSession } from "../../session/store.js";
+import { setReviewerFeedback } from "../../session/mutators.js";
+import { emitProgress, makeEvent } from "../../utils/events.js";
+import { runCommand } from "../../utils/process.js";
+import { resolveCmds } from "../../commands/harden.js";
+
+const TAIL_CHARS = 2000;
+const DEFAULT_TIMEOUT_MS = 10 * 60 * 1000;
+
+/** @returns {Promise<{action: "ok"|"continue", result: object}>} */
+export async function runSuiteGreenStage({ config, logger, emitter, eventBase, session, iteration, resolveCmdsImpl = resolveCmds, runTestsImpl = null }) {
+  const projectDir = config?.projectDir || process.cwd();
+  let command = null;
+  try {
+    command = (await resolveCmdsImpl(projectDir))?.test || null;
+  } catch (err) {
+    logger?.warn?.(`suite-green: could not resolve the test command (${err.message})`);
+  }
+  if (!command) {
+    const message = "suite-green: no test command for this project (package.json scripts.test or a known framework): the suite was NOT run";
+    logger?.warn?.(message);
+    emitProgress(emitter, makeEvent("tests:result", { ...eventBase, stage: "tests" }, { status: "warn", message, detail: { ran: false } }));
+    return { action: "ok", result: { ran: false } };
+  }
+  const timeout = Number(config?.development?.test_timeout_ms) > 0 ? Number(config.development.test_timeout_ms) : DEFAULT_TIMEOUT_MS;
+  const run = runTestsImpl || (async () => {
+    const res = await runCommand("bash", ["-lc", command], { cwd: projectDir, timeout });
+    return { exitCode: res.exitCode ?? 1, output: `${res.stdout || ""}\n${res.stderr || ""}` };
+  });
+  const res = await run(command);
+  const ok = res.exitCode === 0;
+  const verdict = ok ? "green" : `red (exit ${res.exitCode})`;
+  emitProgress(emitter, makeEvent("tests:result", { ...eventBase, stage: "tests" }, {
+    status: ok ? "ok" : "fail",
+    message: `${command}: ${verdict}`,
+    detail: { ran: true, ok, command, exitCode: res.exitCode, executorType: "local" },
+  }));
+  await addCheckpoint(session, { stage: "suite-green", iteration, ok, command });
+  if (ok) return { action: "ok", result: { ran: true, ok: true, command } };
+  const tail = String(res.output || "").trim().slice(-TAIL_CHARS);
+  setReviewerFeedback(session, `The test suite is RED (${command}, exit ${res.exitCode}). Make it green before anything else:\n${tail}`);
+  await saveSession(session);
+  logger?.warn?.(`suite-green: ${command} exited ${res.exitCode}; back to the coder`);
+  return { action: "continue", result: { ran: true, ok: false, command, exitCode: res.exitCode } };
+}

package/src/planning-game/pipeline-adapter.js

@@ -195,10 +195,19 @@ export function accumulateCommit(session, commitInfo) {
 // --- Internal helpers ---
 
 async function markPgCardInProgress({ pgTaskId, pgProject, config, logger }) {
+  const { fetchCard, updateCard } = await import("./client.js");
+  // KJC-BUG-0247 (#1894): a card that cannot be read was one warn line and
+  // null, and the run went on without the card's acceptance criteria, invented
+  // its own HUs and said approved. With a card named, no card is a loud stop.
+  let pgCard;
   try {
-    const { fetchCard, updateCard } = await import("./client.js");
-    const pgCard = await fetchCard({ projectId: pgProject, cardId: pgTaskId });
-    if (pgCard && pgCard.status !== "In Progress") {
+    pgCard = await fetchCard({ projectId: pgProject, cardId: pgTaskId });
+  } catch (err) {
+    throw new Error(`Planning Game: card ${pgTaskId} could not be read (${err.message}): the run would implement without the card's acceptance criteria. Check PG_API_URL, or run without pgTask.`, { cause: err });
+  }
+  if (!pgCard) throw new Error(`Planning Game: card ${pgTaskId} not found in project ${pgProject}: the run would implement without the card's acceptance criteria. Check the id, or run without pgTask.`);
+  try {
+    if (pgCard.status !== "In Progress") {
       await updateCard({
         projectId: pgProject,
         cardId: pgTaskId,
@@ -212,11 +221,11 @@ async function markPgCardInProgress({ pgTaskId, pgProject, config, logger }) {
       });
       logger.info(`Planning Game: ${pgTaskId} → In Progress`);
     }
-    return pgCard;
   } catch (err) {
+    // The card was read: its criteria govern the run; the status move is best-effort.
     logger.warn(`Planning Game: could not update ${pgTaskId}: ${err.message}`);
-    return null;
   }
+  return pgCard;
 }
 
 /**

package/src/review/gate-gitignore.js

@@ -18,6 +18,8 @@ import { runCommand } from "../utils/process.js";
 // init and the orchestrator's autoInit write this same block instead of a
 // bare `.karajan/` exclude (which git cannot re-include children of).
 export const CONTRACT_BLOCK = [
+  // KJC-BUG-0296 (#1989): the host agent's runtime locks never travel.
+  ".claude/*.lock",
   ".karajan/*",
   "# …except the v4 environment contract, which the whole team inherits:",
   "!.karajan/review-gate",

package/src/review/verdict-store.js

@@ -98,14 +98,16 @@ export async function loadVerdict(projectDir, hash) {
  * (KJC-BUG-0115).
  * @returns {Promise<{stamped: boolean}>}
  */
-export async function stampStagedVerdict({ projectDir, reviewer, summary = "", sonar = null }) {
+export async function stampStagedVerdict({ projectDir, reviewer, summary = "", sonar = null, paths = null }) {
   const dir = projectDir || process.cwd();
   try {
     await fs.access(path.join(dir, ".karajan", "review-gate"));
   } catch {
     return { stamped: false };
   }
-  const res = await runCommand("git", ["diff", "--cached"], { cwd: dir });
+  // KJC-BUG-0294: the pipeline commits by path (`--only`); the verdict must bind
+  // to that diff, not to other files the person had staged.
+  const res = await runCommand("git", ["diff", "--cached", ...(paths?.length ? ["--", ...paths] : [])], { cwd: dir });
   if (res.exitCode !== 0 || !res.stdout?.trim()) return { stamped: false };
   await saveVerdict(dir, res.stdout, {
     verdict: "approved", reviewer, host: "kj-pipeline", issues: [], summary,

package/src/roles/domain-curator-role.js

@@ -42,20 +42,13 @@ export class DomainCuratorRole {
     // 3. Deduplicate (file domains take precedence over registry entries)
     const allDomains = deduplicateDomains(fileDomains, registryDomains);
 
-    // 4. No domains found
+    // 4. No domains found. KJC-BUG-0295 (#1992): this used to ASK the user
+    // ("do you have domain documents?") and then do nothing with the answer:
+    // a cryptic, English-only question with no consequence, raised even when
+    // the card already carried the acceptance criteria. A question that changes
+    // nothing is not asked; what kj uses instead is said.
     if (allDomains.length === 0) {
-      if (askQuestion?.interactive) {
-        const answer = await askQuestion({
-          message: "No domain knowledge found for this task.\nDo you have domain documents to provide, or should the pipeline continue without domain context?",
-          type: "confirm"
-        });
-        // For now, just log. Future: support document ingestion.
-        if (answer === true) {
-          this.logger.info("Domain Curator: user indicated domain documents available — future feature");
-        }
-      } else {
-        this.logger.warn("Domain Curator: no domain knowledge found, continuing without domain context");
-      }
+      this.logger.info("Domain Curator: no domain documents in .karajan/domains/ nor the registry; the task's own text, the card's acceptance criteria and the repo are the context");
 
       return {
         ok: true,

package/src/utils/git.js

@@ -1,5 +1,6 @@
 import { runCommand } from "./process.js";
 import { getRunContext } from "./run-context.js";
+import { identityEnv } from "../git/run-identity.js";
 
 /**
  * Module-scoped runner — legacy back-compat for callers outside a
@@ -162,9 +163,20 @@ export async function createBranch(branchName) {
   await runGit(["checkout", "-b", branchName]);
 }
 
-export function buildBranchName(prefix, task) {
+export async function checkoutBranch(branchName) {
+  await runGit(["checkout", branchName]);
+}
+
+/**
+ * KJC-BUG-0249 (#1896): with a Planning Game card the branch carries its id,
+ * `feat/<CARD-ID>-<slug>`, the name the card-first gate reads; the stamp is
+ * for a run with no card, where nothing else makes the name unique.
+ */
+export function buildBranchName(prefix, task, cardId = null) {
+  const slug = slugifyTask(task) || "task";
+  if (cardId) return `${prefix}${cardId}-${slug}`;
   const stamp = new Date().toISOString().replaceAll(/[:.]/g, "-").slice(0, 16);
-  return `${prefix}${slugifyTask(task) || "task"}-${stamp}`;
+  return `${prefix}${slug}-${stamp}`;
 }
 
 export async function hasChanges(cwd = null) {
@@ -189,25 +201,32 @@ export async function hasChanges(cwd = null) {
  * is structural here — without it the slice(3) below would crop one
  * character off the first path.
  */
-export async function listPendingPaths() {
-  const res = await run("git", ["status", "--porcelain"]);
+/**
+ * KJC-BUG-0294: the pending entries as `git status --porcelain -z` reports them,
+ * NUL-separated so a path with blanks or quotes arrives whole. A rename is one
+ * entry "R  new\0old": `path` is the new name, `oldPath` the one that goes away.
+ * @returns {Promise<{path: string, oldPath?: string}[]>}
+ */
+export async function listPendingEntries(cwd = null) {
+  const res = await run("git", ["status", "--porcelain", "-z"], cwd ? { cwd } : {});
   if (res.exitCode !== 0) {
     throw new Error(`git status --porcelain failed: ${res.stderr || res.stdout}`);
   }
-  const stdout = res.stdout;
-  if (!stdout) return [];
-  const lines = stdout.split("\n").map((l) => l.replace(/\r$/, "")).filter(Boolean);
+  const tokens = String(res.stdout || "").split("\0").filter(Boolean);
   const out = [];
-  for (const line of lines) {
-    // Each line is "XY <path>" (XY = 2-char status, space, path).
-    // Renames look like "R  old -> new"; we want the new path.
-    const after = line.slice(3);
-    const arrow = after.indexOf(" -> ");
-    out.push(arrow !== -1 ? after.slice(arrow + 4) : after);
+  for (let i = 0; i < tokens.length; i += 1) {
+    const entry = { path: tokens[i].slice(3) };
+    if (/^[RC]/.test(tokens[i]) || /^.[RC]/.test(tokens[i])) entry.oldPath = tokens[++i];
+    out.push(entry);
   }
   return out;
 }
 
+/** The pending paths; a rename contributes both its names (the old one is a pending deletion). */
+export async function listPendingPaths(cwd = null) {
+  return (await listPendingEntries(cwd)).flatMap((e) => (e.oldPath ? [e.oldPath, e.path] : [e.path]));
+}
+
 // Locale-tolerant detection of "git commit refused because the working
 // tree was already clean by the time we ran it". Observed in N4
 // dogfooding (2026-05-07) — `hasChanges()` reported true after `add -A`
@@ -229,17 +248,40 @@ function isNothingToCommit(message) {
   return NOTHING_TO_COMMIT_PATTERNS.some((re) => re.test(m));
 }
 
-export async function commitAll(message, cwd = null, { beforeCommit = null } = {}) {
+/**
+ * KJC-BUG-0294 (#1993): the pipeline commits what the run changed, never what
+ * was already dirty or untracked before it (`exclude`: the paths pending when
+ * the run started, the harness kj generates among them). `git add -A` staged
+ * 22 untracked files and 960 lines of contract into one step's commit.
+ */
+export async function commitAll(message, cwd = null, { beforeCommit = null, exclude = [] } = {}) {
   const opts = cwd ? { cwd } : {};
-  await runGit(["add", "-A"], opts);
-  const changed = await hasChanges(cwd);
-  if (!changed) return { committed: false };
+  const skip = new Set(exclude);
+  const pending = await listPendingEntries(cwd);
+  const names = (e) => (e.oldPath ? [e.oldPath, e.path] : [e.path]);
+  // A rename of a file that was dirty before the run is that file under a new name.
+  const theirs = (e) => names(e).some((p) => skip.has(p));
+  // A rename stages its old name too (the deletion), or git keeps the old file.
+  const paths = pending.filter((e) => !theirs(e)).flatMap(names);
+  // A path dirty before the run may hold the run's edits too; they cannot be told
+  // apart, so the path stays out and is NAMED (`leftOut`) for the person to commit.
+  const leftOut = pending.filter(theirs).flatMap(names);
+  const said = leftOut.length > 0 ? { leftOut } : {};
+  if (paths.length === 0) return { committed: false, ...said };
+  await runGit(["add", "--", ...paths], opts);
   // ENV-F1 (KJC-TSK-0643): runs between staging and committing — the only
   // window where the staged diff is exactly what the commit will contain
   // (used to stamp the pipeline's review verdict for the v4 gate).
-  if (beforeCommit) await beforeCommit();
+  // The callback learns the exact paths, so a verdict stamped there binds to the
+  // diff this commit will contain and not to whatever else the index holds.
+  if (beforeCommit) await beforeCommit({ paths });
+  // KJC-BUG-0246 (#1893): every commit of a run carries the identity the run
+  // resolved once (prepareGitAutomation), never what git resolves at that moment.
+  const identity = getRunContext()?.gitIdentity;
+  const commitOpts = identity ? { ...opts, env: { ...process.env, ...identityEnv(identity) } } : opts;
   try {
-    await runGit(["commit", "-m", message], opts);
+    // --only: these paths and nothing else; what the person had staged stays staged.
+    await runGit(["commit", "-m", message, "--only", "--", ...paths], commitOpts);
   } catch (err) {
     // `git status --porcelain` and `git commit` disagreed about whether
     // there was anything to commit. Don't escalate — the only outcome
@@ -252,7 +294,7 @@ export async function commitAll(message, cwd = null, { beforeCommit = null } = {
   }
   const raw = await runGit(["log", "-1", "--pretty=format:%H%x1f%s"], opts);
   const [hash, commitMessage] = raw.split("\x1f");
-  return { committed: true, commit: { hash, message: commitMessage } };
+  return { committed: true, commit: { hash, message: commitMessage }, ...said };
 }
 
 /**