@karajan-family/code 4.21.0

package/src/git/automation.js

@@ -0,0 +1,334 @@
+/**
+ * Git automation helpers for the pipeline.
+ * Extracted from orchestrator.js for testability and reuse.
+ */
+
+import { addCheckpoint } from "../session/store.js";
+import { stampStagedVerdict } from "../review/verdict-store.js";
+import {
+  ensureGitRepo,
+  currentBranch,
+  hasCommits,
+  fetchBase,
+  syncBaseBranch,
+  ensureBranchUpToDateWithBase,
+  createBranch,
+  buildBranchName,
+  commitAll,
+  pushBranch,
+  createPullRequest,
+  listPendingPaths,
+  hasRemote
+} from "../utils/git.js";
+
+/**
+ * Karajan writes / updates several internal directories during a pipeline
+ * run (the workspace scaffold + the session journal). When they're the
+ * ONLY thing pending at finalization, the post-loop commit shouldn't
+ * inherit the user task's `feat:` message — it should be a clear
+ * `chore: scaffold karajan workspace` so `git log --oneline` reads:
+ *
+ *     2d770aa  docs: add JSDoc comment to index.js
+ *     abc1234  chore: scaffold karajan workspace
+ *     8a95ef0  initial
+ *
+ * A path counts as scaffolding when it lives at one of these prefixes
+ * OR is the project's root `.gitignore` (we extend it to include
+ * stack-specific entries during triage).
+ */
+const KARAJAN_SCAFFOLD_PREFIXES = [
+  ".karajan/",
+  ".reviews/",
+  ".kj/",
+  ".agent/",
+];
+
+function isKarajanScaffoldPath(p) {
+  if (p === ".gitignore") return true;
+  return KARAJAN_SCAFFOLD_PREFIXES.some((prefix) => p.startsWith(prefix));
+}
+
+/**
+ * @param {string[]} paths
+ * @returns {boolean} true when every pending path is a Karajan internal
+ */
+export function pendingPathsAreOnlyKarajanScaffold(paths) {
+  if (!Array.isArray(paths) || paths.length === 0) return false;
+  return paths.every(isKarajanScaffoldPath);
+}
+
+/**
+ * Map the taskType (as classified by triage) to the matching
+ * Conventional Commits prefix. When triage hasn't run or the type is
+ * unknown we default to `feat:` (the pre-fix behaviour).
+ */
+const TASK_TYPE_TO_PREFIX = {
+  doc: "docs",
+  "add-tests": "test",
+  refactor: "refactor",
+  infra: "chore",
+  sw: "feat",
+};
+
+function prefixForTaskType(taskType) {
+  return TASK_TYPE_TO_PREFIX[taskType] || "feat";
+}
+
+export function commitMessageFromTask(task, taskType = null) {
+  const clean = String(task || "")
+    .replaceAll(/\s+/g, " ")
+    .trim();
+  const prefix = prefixForTaskType(taskType);
+  return `${prefix}: ${clean.slice(0, 72) || "karajan update"}`;
+}
+
+/**
+ * Build the message used by `finalizeGitAutomation` for the post-loop
+ * commit. Two paths:
+ *   - When the only pending changes are Karajan scaffold files
+ *     (.gitignore, .karajan/, .reviews/, ...), use a fixed
+ *     `chore: scaffold karajan workspace` message. This avoids the
+ *     "duplicate feat:" git log seen when triage extends .gitignore
+ *     for a freshly detected stack and the coder already committed
+ *     the user-visible change.
+ *   - Otherwise, fall back to `commitMessageFromTask(task, taskType)`,
+ *     respecting the type for the prefix.
+ */
+export function buildFinalizeCommitMessage({ task, taskType, pendingPaths }) {
+  if (pendingPathsAreOnlyKarajanScaffold(pendingPaths)) {
+    return "chore: scaffold karajan workspace";
+  }
+  return commitMessageFromTask(task, taskType);
+}
+
+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 };
+
+  if (!(await ensureGitRepo())) {
+    throw new Error("Git automation requested but current directory is not a git repository");
+  }
+
+  const baseBranch = config.base_branch;
+  const autoRebase = config.git.auto_rebase !== false;
+  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);
+    // 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 };
+  }
+
+  await fetchBase(baseBranch).catch(() => {
+    // No remote — skip fetch (new project without push)
+    logger.info("No remote configured — skipping fetch");
+  });
+
+  let branch;
+  try {
+    branch = await currentBranch();
+  } catch {
+    // HEAD exists but branch detection failed — unusual, treat as main
+    branch = baseBranch;
+  }
+
+  if (branch === baseBranch) {
+    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);
+    branch = created;
+    logger.info(`Created working branch: ${branch}`);
+    await addCheckpoint(session, { stage: "git-prep", branch, created: true });
+  } else {
+    await ensureBranchUpToDateWithBase({ branch, baseBranch, autoRebase }).catch(() => {
+      // No remote tracking — skip rebase for new projects
+      logger.info("No remote tracking — skipping rebase check");
+    });
+    await addCheckpoint(session, { stage: "git-prep", branch, created: false });
+  }
+
+  return { enabled: true, branch, baseBranch, autoRebase };
+}
+
+export function buildPrBody({ task: _task, stageResults }) {
+  const sections = ["Created by Karajan Code."];
+
+  const approach = stageResults?.planner?.approach;
+  if (approach) {
+    sections.push("", "## Approach", approach);
+  }
+
+  const steps = stageResults?.planner?.steps;
+  if (steps?.length) {
+    sections.push("", "## Steps");
+    for (let i = 0; i < steps.length; i++) {
+      sections.push(`${i + 1}. ${steps[i]}`);
+    }
+  }
+
+  const triageSubtasks = stageResults?.triage?.subtasks;
+  const shouldDecompose = stageResults?.triage?.shouldDecompose;
+  const pendingSubtasks = shouldDecompose && triageSubtasks?.length > 1 ? triageSubtasks.slice(1) : [];
+  if (pendingSubtasks.length > 0) {
+    sections.push("", "## Pending subtasks", "This PR addresses part of a larger task. The following subtasks were identified but not included:");
+    for (const subtask of pendingSubtasks) {
+      sections.push(`- [ ] ${subtask}`);
+    }
+  }
+
+  return sections.join("\n");
+}
+
+/**
+ * Create an early PR after the first coder iteration (Karajan CI flow).
+ * Commits, pushes, and creates a PR before the reviewer runs.
+ * Returns { prNumber, prUrl, commits } or null if nothing to commit.
+ */
+export async function earlyPrCreation({ gitCtx, task, logger, session, stageResults = null }) {
+  if (!gitCtx?.enabled) return null;
+
+  const commitMsg = commitMessageFromTask(task);
+  const commitResult = await commitAll(commitMsg);
+  if (!commitResult.committed) {
+    logger.info("earlyPrCreation: no changes to commit");
+    return null;
+  }
+
+  const commits = commitResult.commit ? [commitResult.commit] : [];
+  await addCheckpoint(session, { stage: "ci-commit", committed: true });
+
+  await pushBranch(gitCtx.branch);
+  await addCheckpoint(session, { stage: "ci-push", branch: gitCtx.branch });
+  logger.info(`Pushed branch for early PR: ${gitCtx.branch}`);
+
+  const body = buildPrBody({ task, stageResults });
+  const prUrl = await createPullRequest({
+    baseBranch: gitCtx.baseBranch,
+    branch: gitCtx.branch,
+    title: commitMessageFromTask(task),
+    body
+  });
+  await addCheckpoint(session, { stage: "ci-pr", branch: gitCtx.branch, pr: prUrl });
+  logger.info(`Early PR created: ${prUrl}`);
+
+  // Extract PR number from URL (e.g. https://github.com/owner/repo/pull/42)
+  const prNumber = Number.parseInt(prUrl.split("/").pop(), 10) || null;
+  return { prNumber, prUrl, commits };
+}
+
+/**
+ * Incremental push after each coder iteration (Karajan CI flow).
+ * Commits and pushes without creating a new PR.
+ */
+export async function incrementalPush({ gitCtx, task, logger, session }) {
+  if (!gitCtx?.enabled) return null;
+
+  const commitMsg = commitMessageFromTask(task);
+  const commitResult = await commitAll(commitMsg);
+  if (!commitResult.committed) {
+    logger.info("incrementalPush: no changes to commit");
+    return null;
+  }
+
+  const commits = commitResult.commit ? [commitResult.commit] : [];
+  await addCheckpoint(session, { stage: "ci-incremental-commit", committed: true });
+
+  await pushBranch(gitCtx.branch);
+  await addCheckpoint(session, { stage: "ci-incremental-push", branch: gitCtx.branch });
+  logger.info(`Incremental push: ${gitCtx.branch}`);
+
+  return { commits };
+}
+
+export async function finalizeGitAutomation({ config, gitCtx, task, logger, session, stageResults = null }) {
+  if (!gitCtx?.enabled) return { git: "disabled", commits: [] };
+
+  // Take a snapshot of pending paths BEFORE staging so we can decide
+  // whether what's about to be committed is just Karajan scaffolding
+  // (in which case we use `chore: scaffold karajan workspace`) or a
+  // real, user-visible change (in which case we honour the task's
+  // taskType for the Conventional Commits prefix).
+  const taskType = stageResults?.triage?.taskType ?? null;
+  let pendingPaths = [];
+  if (config.git.auto_commit) {
+    try {
+      pendingPaths = await listPendingPaths();
+    } catch { /* best-effort — fall back to default message */ }
+  }
+
+  const commitMsg =
+    config.git.commit_message
+    || buildFinalizeCommitMessage({ task, taskType, pendingPaths });
+
+  let committed = false;
+  const commits = [];
+  if (config.git.auto_commit) {
+    // 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({
+        projectDir: config?.projectDir || process.cwd(),
+        reviewer: config?.reviewer || "pipeline-reviewer",
+        summary: `kj run session ${session?.id || ""}: reviewer approved`.trim(),
+      }),
+    });
+    committed = commitResult.committed;
+    if (commitResult.commit) {
+      commits.push(commitResult.commit);
+    }
+    await addCheckpoint(session, { stage: "git-commit", committed });
+    logger.info(committed ? "Committed changes" : "No changes to commit");
+  }
+
+  // KJC-BUG-0112: without an `origin` remote (the quickstart scenario:
+  // fresh folder + git init) push/PR automation has nothing to talk to —
+  // fetchBase used to throw here and escalate to Solomon on EVERY
+  // iteration, burning the whole budget on an expected condition.
+  const remoteAvailable = (config.git.auto_push || config.git.auto_pr)
+    ? await hasRemote()
+    : false;
+  if ((config.git.auto_push || config.git.auto_pr) && !remoteAvailable) {
+    logger.info("No remote configured — skipping push/PR automation");
+    await addCheckpoint(session, { stage: "git-push", skipped: "no-remote" });
+  }
+
+  if (remoteAvailable && (config.git.auto_push || config.git.auto_pr)) {
+    await fetchBase(gitCtx.baseBranch);
+    await ensureBranchUpToDateWithBase({
+      branch: gitCtx.branch,
+      baseBranch: gitCtx.baseBranch,
+      autoRebase: gitCtx.autoRebase
+    });
+    await addCheckpoint(session, { stage: "git-rebase-check", branch: gitCtx.branch });
+  }
+
+  if (remoteAvailable && (config.git.auto_push || config.git.auto_pr)) {
+    await pushBranch(gitCtx.branch);
+    await addCheckpoint(session, { stage: "git-push", branch: gitCtx.branch });
+    logger.info(`Pushed branch: ${gitCtx.branch}`);
+  }
+
+  let prUrl = session.ci_pr_url || null;
+  if (remoteAvailable && config.git.auto_pr && !prUrl) {
+    const body = buildPrBody({ task, stageResults });
+    prUrl = await createPullRequest({
+      baseBranch: gitCtx.baseBranch,
+      branch: gitCtx.branch,
+      title: commitMessageFromTask(task),
+      body
+    });
+    await addCheckpoint(session, { stage: "git-pr", branch: gitCtx.branch, pr: prUrl });
+    logger.info("Pull request created");
+  } else if (prUrl) {
+    logger.info(`PR already exists (CI flow): ${prUrl}`);
+  }
+
+  return { committed, branch: gitCtx.branch, prUrl, pr: prUrl, commits };
+}

package/src/git/hu-automation.js

@@ -0,0 +1,171 @@
+/**
+ * Per-HU git automation: branch, commit, push, PR per HU story.
+ * Called from the HU sub-pipeline wrapper in orchestrator.js.
+ */
+import { commitAll, pushBranch, createPullRequest, hasChanges } from "../utils/git.js";
+import { runCommand } from "../utils/process.js";
+
+/**
+ * Build a git-safe branch name for an HU story.
+ * @param {string} prefix - e.g. "feat/"
+ * @param {object} story - HU story {id, title}
+ * @returns {string}
+ */
+export function buildHuBranchName(prefix, story) {
+  const baseSlug = String(story.title || story.id || "hu")
+    .toLowerCase()
+    .replaceAll(/[^a-z0-9]+/g, "-")
+    .replaceAll(/^-+|-+$/g, "")
+    .slice(0, 40);
+  return `${prefix}${story.id}-${baseSlug}`;
+}
+
+/**
+ * Resolve the base branch for a given HU based on its dependencies.
+ * If it has no blocked_by, uses config.base_branch.
+ * If it has parents, uses the last-created parent branch (assumes parents ran first).
+ *
+ * @param {object} story - the HU story
+ * @param {Map<string,string>} huBranches - map of huId → branchName (already created)
+ * @param {string} baseBranch - config.base_branch fallback
+ * @returns {string} base branch name
+ */
+export function resolveHuBase(story, huBranches, baseBranch) {
+  const parents = story.blocked_by || [];
+  if (parents.length === 0) return baseBranch;
+  // Walk parents in reverse order of declaration to find the most recent one
+  for (let i = parents.length - 1; i >= 0; i--) {
+    const parentBranch = huBranches.get(parents[i]);
+    if (parentBranch) return parentBranch;
+  }
+  return baseBranch;
+}
+
+/**
+ * Resolve to an actually-existing local ref. Tries the preferred branch
+ * first, then `main` and `master`, then plain `HEAD` as last resort.
+ *
+ * Why: N6 plan-flow dogfooding (2026-05-07) on a `git init -q` repo
+ * with `init.defaultBranch=master` produced 7 identical warnings:
+ *   `failed to create branch feat/...-001 from main:
+ *    fatal: 'main' is not a commit and a branch can't be created`.
+ * Every HU then fell back to running on the original branch, which
+ * defeats the per-HU isolation the sub-pipeline was supposed to give.
+ *
+ * The configured base_branch is honoured when it exists; otherwise we
+ * pick the most likely default. HEAD always exists once the repo has
+ * any commit, so the fallback never throws past the gate.
+ *
+ * @param {string} preferred
+ * @returns {Promise<string>}
+ */
+async function resolveExistingBranchRef(preferred) {
+  const candidates = [preferred, "main", "master", "HEAD"]
+    .filter((c, i, arr) => c && arr.indexOf(c) === i); // unique, truthy
+  for (const ref of candidates) {
+    const probe = await runCommand("git", ["rev-parse", "--verify", "--quiet", ref], {});
+    if (probe.exitCode === 0) return ref;
+  }
+  return preferred; // give up; caller will surface the original error
+}
+
+/**
+ * Create a branch for an HU starting from its resolved base.
+ * Returns the branch name created (or null if git automation is disabled).
+ *
+ * @param {object} params
+ * @param {object} params.story
+ * @param {Map} params.huBranches
+ * @param {object} params.config
+ * @param {object} params.logger
+ * @returns {Promise<string|null>}
+ */
+export async function prepareHuBranch({ story, huBranches, config, logger }) {
+  if (!config.git?.auto_commit && !config.git?.auto_push && !config.git?.auto_pr) {
+    return null;
+  }
+  const baseBranch = resolveHuBase(story, huBranches, config.base_branch || "main");
+  const effectiveBase = await resolveExistingBranchRef(baseBranch);
+  if (effectiveBase !== baseBranch) {
+    logger.info(`HU git: configured base '${baseBranch}' not found locally — using '${effectiveBase}' instead`);
+  }
+  const prefix = config.git?.branch_prefix || "feat/";
+  const branchName = buildHuBranchName(prefix, story);
+
+  // Checkout from the resolved base. Use `git checkout -B` to overwrite if rerun.
+  const res = await runCommand("git", ["checkout", "-B", branchName, effectiveBase], {});
+  if (res.exitCode !== 0) {
+    logger.warn(`HU git: failed to create branch ${branchName} from ${effectiveBase}: ${res.stderr}`);
+    return null;
+  }
+  huBranches.set(story.id, branchName);
+  logger.info(`HU ${story.id}: branch '${branchName}' from '${effectiveBase}'`);
+  return branchName;
+}
+
+/**
+ * After an HU is approved, commit its changes and optionally push + create PR.
+ *
+ * @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}>}
+ */
+export async function finalizeHuCommit({ story, branchName, config, logger, cwd = null }) {
+  const result = { committed: false, pushed: false, prUrl: null };
+  if (!branchName) return result;
+
+  const changed = await hasChanges(cwd);
+  if (!changed) {
+    logger.info(`HU ${story.id}: no changes to commit`);
+    return result;
+  }
+
+  const title = story.title || story.id;
+  const commitMsg = `feat(${story.id}): ${title}`;
+  if (config.git?.auto_commit) {
+    const commitRes = await commitAll(commitMsg, cwd);
+    if (commitRes) {
+      result.committed = true;
+      logger.info(`HU ${story.id}: committed on '${branchName}'`);
+    }
+  }
+
+  if (config.git?.auto_push && result.committed) {
+    try {
+      await pushBranch(branchName, cwd);
+      result.pushed = true;
+      logger.info(`HU ${story.id}: pushed '${branchName}'`);
+    } catch (err) {
+      logger.warn(`HU ${story.id}: push failed: ${err.message}`);
+    }
+  }
+
+  if (config.git?.auto_pr && result.pushed) {
+    try {
+      const prBody = [
+        `## HU ${story.id}: ${title}`,
+        "",
+        story.certified?.text || "",
+        "",
+        "### Acceptance criteria",
+        ...(story.acceptance_criteria || []).map(c => `- ${c}`)
+      ].join("\n");
+      const url = await createPullRequest({
+        baseBranch: config.base_branch || "main",
+        branch: branchName,
+        title: commitMsg,
+        body: prBody,
+        cwd
+      });
+      result.prUrl = url;
+      logger.info(`HU ${story.id}: PR created ${url}`);
+    } catch (err) {
+      logger.warn(`HU ${story.id}: PR creation failed: ${err.message}`);
+    }
+  }
+
+  return result;
+}

package/src/git/hu-snapshot.js

@@ -0,0 +1,10 @@
+// Shim de compatibilidad: hu-snapshot vive ahora en karajan-core.
+// Mantenemos esta ruta para que callers internos del CLI (orchestrator,
+// runners) sigan funcionando sin tocar imports.
+export {
+  snapshotRefForHu,
+  createHuSnapshot,
+  hasHuSnapshot,
+  restoreHuSnapshot,
+  removeHuSnapshot,
+} from "karajan-core/hu-snapshot";

package/src/golden/asserter.js

@@ -0,0 +1,92 @@
+/**
+ * Golden tasks asserter (KJC-TSK-0374). Parses a `summary.md` produced
+ * by a real `kj run` and compares it against a GoldenTask's structural
+ * expectations. Pure: no I/O, no subprocess. Subprocess driver lands
+ * in PR-3a; the 3 fixtures + baseline + spec land in PR-3b.
+ *
+ * Three of the five assertion families live here (the ones derivable
+ * from summary.md alone): expected_commits_min, expected_audit_status,
+ * expected_plan_adherence_min. expected_test_files and
+ * allowed_loc_range need filesystem access — PR-3a wires those.
+ */
+
+import { escapeRegExp } from "../utils/escape-regexp.js";
+
+const COMMIT_LINE = /^- `([^`]+)`\s+(.*)$/;
+const SCORE_LINE = /^\*\*Score\*\*:\s*(\d+)\s*\/\s*100/m;
+const AUDIT_ROW = /^\|\s*`audit`\s*\|\s*([^|]+?)\s*\|/m;
+
+function extractSection(content, heading) {
+  const re = new RegExp(`^## ${escapeRegExp(heading)}\\s*$([\\s\\S]*?)(?=^## |\\Z)`, "m");
+  const m = content.match(re);
+  return m ? m[1].trim() : "";
+}
+
+function parseCommits(content) {
+  const section = extractSection(content, "Commits");
+  if (!section || /No commits/.test(section)) return [];
+  return section
+    .split("\n")
+    .map((line) => line.match(COMMIT_LINE))
+    .filter(Boolean)
+    .map(([, hash, message]) => ({ hash, message }));
+}
+
+function parseAuditStatus(content) {
+  const m = content.match(AUDIT_ROW);
+  if (!m) return null;
+  const cell = m[1];
+  if (/✅|pass/i.test(cell)) return "pass";
+  if (/❌|fail/i.test(cell)) return "fail";
+  if (/⚠|warn/i.test(cell)) return "warning";
+  return null;
+}
+
+function parsePlanAdherence(content) {
+  const section = extractSection(content, "Plan adherence");
+  if (!section) return null;
+  const m = section.match(SCORE_LINE);
+  if (!m) return null;
+  const score = Number(m[1]);
+  return Number.isFinite(score) ? score : null;
+}
+
+export function parseSummary(content) {
+  const text = String(content || "");
+  return {
+    commits: parseCommits(text),
+    auditStatus: parseAuditStatus(text),
+    planAdherenceScore: parsePlanAdherence(text),
+  };
+}
+
+export function assertFromSummary(task, parsed) {
+  const failures = [];
+
+  const fail = (kind, expected, actual, message) => failures.push({ kind, expected, actual, message });
+
+  if (parsed.commits.length < task.expected_commits_min) {
+    fail("commits_min", `>= ${task.expected_commits_min}`, parsed.commits.length,
+      `expected at least ${task.expected_commits_min} commit(s); got ${parsed.commits.length}`);
+  }
+
+  if (parsed.auditStatus !== task.expected_audit_status) {
+    const got = parsed.auditStatus === null ? "no audit row in summary" : `"${parsed.auditStatus}"`;
+    fail("audit_status", task.expected_audit_status, parsed.auditStatus,
+      `expected audit "${task.expected_audit_status}"; got ${got}`);
+  }
+
+  if (typeof task.expected_plan_adherence_min === "number") {
+    const score = parsed.planAdherenceScore;
+    const min = task.expected_plan_adherence_min;
+    if (score === null) {
+      fail("plan_adherence_missing", `>= ${min}`, null,
+        `expected plan adherence >= ${min}; summary has no Plan adherence section`);
+    } else if (score < min) {
+      fail("plan_adherence_below", `>= ${min}`, score,
+        `expected plan adherence >= ${min}; got ${score}`);
+    }
+  }
+
+  return { ok: failures.length === 0, failures };
+}

package/src/golden/loader.js

@@ -0,0 +1,52 @@
+/**
+ * Golden tasks loader (KJC-TSK-0374). Reads + validates JSON files
+ * under a directory; aggregates errors; rejects duplicate ids.
+ */
+
+import fs from "node:fs/promises";
+import path from "node:path";
+import { safeParseGoldenTask } from "./schema.js";
+
+export async function loadGoldenTasks(dir) {
+  const entries = await fs.readdir(dir, { withFileTypes: true }).catch((err) => {
+    throw new Error(`golden tasks directory not readable: ${dir} (${err.code || err.message})`);
+  });
+  const jsonFiles = entries
+    .filter((e) => e.isFile() && e.name.endsWith(".json"))
+    .map((e) => path.join(dir, e.name))
+    .sort();
+
+  const tasks = [];
+  const errors = [];
+  const seenIds = new Map();
+
+  for (const filePath of jsonFiles) {
+    let raw;
+    try {
+      const content = await fs.readFile(filePath, "utf8");
+      raw = JSON.parse(content);
+    } catch (err) {
+      errors.push(`${path.basename(filePath)}: invalid JSON (${err.message})`);
+      continue;
+    }
+    const result = safeParseGoldenTask(raw);
+    if (!result.ok) {
+      const summary = result.issues.map((iss) => `  - ${iss.path || "(root)"}: ${iss.message}`).join("\n");
+      errors.push(`${path.basename(filePath)}:\n${summary}`);
+      continue;
+    }
+    const existing = seenIds.get(result.task.id);
+    if (existing) {
+      errors.push(`${path.basename(filePath)}: duplicate id "${result.task.id}" (also in ${existing})`);
+      continue;
+    }
+    seenIds.set(result.task.id, path.basename(filePath));
+    tasks.push(result.task);
+  }
+
+  if (errors.length > 0) {
+    throw new Error(`golden tasks failed validation:\n${errors.join("\n")}`);
+  }
+
+  return { tasks };
+}