karajan-code 2.4.1 → 2.6.0

package/src/plan/plan-executor.js

@@ -0,0 +1,69 @@
+/**
+ * Plan Executor — bridge between v2 plans and hu-sub-pipeline.
+ * Converts plan.hus into the format expected by runHuSubPipeline,
+ * and syncs execution results back to the plan file.
+ */
+
+import { isPlanV2 } from "./plan-schema.js";
+import { updateHuStatus } from "./plan-hu-ops.js";
+
+/**
+ * Convert a v2 plan's HUs into the stageResults.huReviewer format
+ * expected by needsSubPipeline + runHuSubPipeline.
+ * @param {object} plan - v2 plan with plan.hus
+ * @returns {object} { ok, stories, total, certified, batchSessionId, planId }
+ */
+export function planToHuBatch(plan) {
+  if (!isPlanV2(plan) || !plan.hus?.length) {
+    return { ok: false, stories: [], total: 0, certified: 0 };
+  }
+
+  const stories = plan.hus.map(hu => ({
+    id: hu.id,
+    title: hu.title,
+    task_type: hu.task_type || "sw",
+    status: hu.status === "certified" ? "certified" : hu.status,
+    blocked_by: hu.blocked_by || [],
+    certified: { text: hu.scope || hu.title },
+    acceptance_criteria: hu.acceptance_criteria || [],
+    acceptance_tests: hu.acceptance_tests || [],
+    original: { text: hu.scope || hu.title }
+  }));
+
+  const certified = stories.filter(s => s.status === "certified").length;
+
+  return {
+    ok: certified > 0,
+    stories,
+    total: stories.length,
+    certified,
+    batchSessionId: `plan-${plan.planId}`,
+    planId: plan.planId,
+    auto_generated: false,
+    source: { plan: true, planId: plan.planId }
+  };
+}
+
+/**
+ * Sync execution results from hu-sub-pipeline back to the plan file.
+ * Updates each HU's status based on the sub-pipeline results.
+ * @param {object} plan - v2 plan (mutated in place)
+ * @param {object} subPipelineResult - { results: [{huId, approved}], blockedIds }
+ */
+export function syncResultsToPlan(plan, subPipelineResult) {
+  if (!isPlanV2(plan)) return;
+
+  for (const r of subPipelineResult.results || []) {
+    const status = r.approved ? "done" : "failed";
+    updateHuStatus(plan, r.huId, status);
+  }
+
+  for (const blockedId of subPipelineResult.blockedIds || []) {
+    updateHuStatus(plan, blockedId, "blocked");
+  }
+
+  const allDone = plan.hus.every(h => h.status === "done");
+  const anyFailed = plan.hus.some(h => h.status === "failed");
+  plan.status = allDone ? "done" : anyFailed ? "failed" : "running";
+  plan.updatedAt = new Date().toISOString();
+}

package/src/plan/plan-hu-ops.js

@@ -0,0 +1,134 @@
+/**
+ * HU CRUD operations on a v2 plan.
+ * All functions mutate the plan in-place and return it.
+ */
+
+import { generateHuId } from "./plan-id.js";
+
+/**
+ * Get the next sequential HU number for this plan.
+ */
+function nextSeq(plan) {
+  if (!plan.hus || plan.hus.length === 0) return 1;
+  const nums = plan.hus
+    .map(h => {
+      const m = h.id.match(/_(\d+)$/);
+      return m ? Number(m[1]) : 0;
+    })
+    .filter(n => n > 0);
+  return nums.length > 0 ? Math.max(...nums) + 1 : plan.hus.length + 1;
+}
+
+/**
+ * Add an HU to the plan. Auto-generates a globally unique ID.
+ * @param {object} plan - v2 plan
+ * @param {object} huData - { title, task_type?, scope?, acceptance_criteria?, acceptance_tests?, blocked_by? }
+ * @returns {object} the created HU (with id assigned)
+ */
+export function addHu(plan, huData) {
+  const seq = nextSeq(plan);
+  const id = generateHuId(plan.planId, seq);
+  const hu = {
+    id,
+    title: huData.title,
+    task_type: huData.task_type || "sw",
+    status: "pending",
+    blocked_by: huData.blocked_by || [],
+    scope: huData.scope || null,
+    acceptance_criteria: huData.acceptance_criteria || [],
+    acceptance_tests: huData.acceptance_tests || [],
+    createdAt: new Date().toISOString(),
+    updatedAt: new Date().toISOString()
+  };
+  plan.hus.push(hu);
+  plan.updatedAt = new Date().toISOString();
+  return hu;
+}
+
+/**
+ * Remove an HU from the plan. Also cleans blocked_by references.
+ * @returns {boolean} true if removed
+ */
+export function removeHu(plan, huId) {
+  const idx = plan.hus.findIndex(h => h.id === huId);
+  if (idx === -1) return false;
+  plan.hus.splice(idx, 1);
+  // Clean up blocked_by refs
+  for (const hu of plan.hus) {
+    hu.blocked_by = (hu.blocked_by || []).filter(dep => dep !== huId);
+  }
+  plan.updatedAt = new Date().toISOString();
+  return true;
+}
+
+/**
+ * Partial update of an HU.
+ * @param {object} plan
+ * @param {string} huId
+ * @param {object} patch - fields to update (title, scope, task_type, acceptance_criteria, acceptance_tests, blocked_by)
+ * @returns {object|null} updated HU or null if not found
+ */
+export function updateHu(plan, huId, patch) {
+  const hu = plan.hus.find(h => h.id === huId);
+  if (!hu) return null;
+  const allowed = ["title", "task_type", "scope", "acceptance_criteria", "acceptance_tests", "blocked_by"];
+  for (const key of allowed) {
+    if (patch[key] !== undefined) hu[key] = patch[key];
+  }
+  hu.updatedAt = new Date().toISOString();
+  plan.updatedAt = new Date().toISOString();
+  return hu;
+}
+
+/**
+ * Update HU status.
+ * @returns {boolean} true if updated
+ */
+export function updateHuStatus(plan, huId, status) {
+  const hu = plan.hus.find(h => h.id === huId);
+  if (!hu) return false;
+  hu.status = status;
+  hu.updatedAt = new Date().toISOString();
+  plan.updatedAt = new Date().toISOString();
+  return true;
+}
+
+/**
+ * Mark all pending HUs as certified (ready to execute).
+ * Sets plan status to "ready".
+ * @returns {number} count of certified HUs
+ */
+export function certifyAllHus(plan) {
+  let count = 0;
+  for (const hu of plan.hus) {
+    if (hu.status === "pending") {
+      hu.status = "certified";
+      hu.updatedAt = new Date().toISOString();
+      count++;
+    }
+  }
+  plan.status = "ready";
+  plan.updatedAt = new Date().toISOString();
+  return count;
+}
+
+/**
+ * Reorder HUs by providing an ordered list of IDs.
+ * Updates blocked_by to reflect the linear order.
+ * @param {object} plan
+ * @param {string[]} orderedIds
+ */
+export function reorderHus(plan, orderedIds) {
+  const map = new Map(plan.hus.map(h => [h.id, h]));
+  const reordered = [];
+  for (const id of orderedIds) {
+    const hu = map.get(id);
+    if (hu) reordered.push(hu);
+  }
+  // Add any HUs not in the ordered list at the end
+  for (const hu of plan.hus) {
+    if (!orderedIds.includes(hu.id)) reordered.push(hu);
+  }
+  plan.hus = reordered;
+  plan.updatedAt = new Date().toISOString();
+}

package/src/plan/plan-id.js

@@ -0,0 +1,25 @@
+/**
+ * Plan + HU ID generation.
+ * Globally unique IDs that never collide across plans.
+ */
+
+/**
+ * Generate a unique plan ID: plan-<YYYYMMDDHHMMSS>-<4-char random>
+ */
+export function generatePlanId() {
+  const now = new Date();
+  const ts = now.toISOString().replace(/[-:T]/g, "").replace(/\.\d+Z$/, "");
+  const rand = Math.random().toString(36).slice(2, 6);
+  return `plan-${ts}-${rand}`;
+}
+
+/**
+ * Generate a globally unique HU ID scoped to a plan.
+ * Format: hu_<planId>_<3-digit sequence>
+ * @param {string} planId
+ * @param {number} seq - 1-based sequence number
+ * @returns {string}
+ */
+export function generateHuId(planId, seq) {
+  return `hu_${planId}_${String(seq).padStart(3, "0")}`;
+}

package/src/plan/plan-schema.js

@@ -0,0 +1,139 @@
+/**
+ * Plan v2 schema: plans with embedded HUs.
+ * v1 = text-only plans (approach + steps + risks)
+ * v2 = plans + executable HUs with acceptance tests
+ */
+
+import { generatePlanId, generateHuId } from "./plan-id.js";
+
+const VALID_PLAN_STATUSES = new Set(["draft", "ready", "running", "done", "failed"]);
+const VALID_HU_STATUSES = new Set(["pending", "certified", "coding", "reviewing", "done", "failed", "blocked"]);
+const VALID_TASK_TYPES = new Set(["sw", "infra", "doc", "add-tests", "refactor", "nocode"]);
+
+/**
+ * Check if a plan uses v2 schema (has version field + hus array).
+ */
+export function isPlanV2(plan) {
+  return plan?.version === 2 && Array.isArray(plan.hus);
+}
+
+/**
+ * Create an empty v2 plan.
+ * @param {string} task - original task description
+ * @param {object} [context] - research/architect/triage context
+ * @returns {object} v2 plan with empty hus array
+ */
+export function createPlanV2(task, context = {}) {
+  const planId = generatePlanId();
+  return {
+    planId,
+    version: 2,
+    task,
+    name: null, // set by caller via deriveProjectName or manually
+    status: "draft",
+    createdAt: new Date().toISOString(),
+    updatedAt: new Date().toISOString(),
+    createdBy: "planner",
+    context: {
+      researchContext: context.researchContext || null,
+      architectContext: context.architectContext || null,
+      triageLevel: context.triageLevel || null,
+      domain: context.domain || null
+    },
+    approach: null,
+    risks: [],
+    outOfScope: [],
+    hus: []
+  };
+}
+
+/**
+ * Migrate a v1 plan to v2 schema. Preserves all existing data.
+ * v1 plans have no HUs — they become v2 with empty hus array.
+ * @param {object} v1plan
+ * @returns {object} v2 plan
+ */
+export function migratePlanV1toV2(v1plan) {
+  if (isPlanV2(v1plan)) return v1plan; // already v2
+  return {
+    planId: v1plan.planId,
+    version: 2,
+    task: v1plan.task || null,
+    name: null,
+    status: "draft",
+    createdAt: v1plan.createdAt || new Date().toISOString(),
+    updatedAt: new Date().toISOString(),
+    createdBy: "migrated",
+    context: {
+      researchContext: v1plan.researchContext || null,
+      architectContext: v1plan.architectContext || null,
+      triageLevel: null,
+      domain: null
+    },
+    approach: v1plan.plan?.approach || (typeof v1plan.plan === "string" ? v1plan.plan : null),
+    risks: v1plan.plan?.risks || [],
+    outOfScope: v1plan.plan?.outOfScope || [],
+    hus: [],
+    _v1: { raw: v1plan.raw, plan: v1plan.plan } // preserve original for reference
+  };
+}
+
+/**
+ * Validate a v2 plan. Returns { valid: true } or { valid: false, errors: string[] }.
+ */
+export function validatePlan(plan) {
+  const errors = [];
+
+  if (!plan.planId) errors.push("Missing planId");
+  if (plan.version !== 2) errors.push(`Expected version 2, got ${plan.version}`);
+  if (!plan.task) errors.push("Missing task");
+  if (!VALID_PLAN_STATUSES.has(plan.status)) errors.push(`Invalid status: ${plan.status}`);
+  if (!Array.isArray(plan.hus)) errors.push("hus must be an array");
+
+  const huIds = new Set();
+  for (const hu of plan.hus || []) {
+    if (!hu.id) { errors.push("HU missing id"); continue; }
+    if (huIds.has(hu.id)) errors.push(`Duplicate HU id: ${hu.id}`);
+    huIds.add(hu.id);
+    if (!hu.title) errors.push(`HU ${hu.id}: missing title`);
+    if (!VALID_HU_STATUSES.has(hu.status)) errors.push(`HU ${hu.id}: invalid status ${hu.status}`);
+    if (hu.task_type && !VALID_TASK_TYPES.has(hu.task_type)) errors.push(`HU ${hu.id}: invalid task_type ${hu.task_type}`);
+    // Check blocked_by references exist
+    for (const dep of hu.blocked_by || []) {
+      if (!huIds.has(dep) && !(plan.hus || []).some(h => h.id === dep)) {
+        errors.push(`HU ${hu.id}: blocked_by references unknown HU ${dep}`);
+      }
+    }
+  }
+
+  // Check for circular dependencies
+  try {
+    topoSort(plan.hus || []);
+  } catch {
+    errors.push("Circular dependency detected in HU blocked_by graph");
+  }
+
+  return errors.length === 0 ? { valid: true } : { valid: false, errors };
+}
+
+/** Simple topological sort for cycle detection. */
+function topoSort(hus) {
+  const visited = new Set();
+  const visiting = new Set();
+  const order = [];
+  const map = new Map(hus.map(h => [h.id, h]));
+
+  function visit(id) {
+    if (visited.has(id)) return;
+    if (visiting.has(id)) throw new Error("cycle");
+    visiting.add(id);
+    const hu = map.get(id);
+    for (const dep of hu?.blocked_by || []) visit(dep);
+    visiting.delete(id);
+    visited.add(id);
+    order.push(id);
+  }
+
+  for (const hu of hus) visit(hu.id);
+  return order;
+}

package/src/plan/plan-store.js

@@ -1,11 +1,14 @@
 /**
- * Plan persistence — save, load, list plans generated by kj_plan.
+ * Plan persistence — save, load, list, update, delete plans.
  * Plans are stored at ~/.kj/plans/<projectSlug>/<planId>.json
+ * Supports v1 (text-only) and v2 (plans + HUs) schemas.
  */
 
 import fs from "node:fs/promises";
 import path from "node:path";
 import os from "node:os";
+import { generatePlanId } from "./plan-id.js";
+import { isPlanV2, migratePlanV1toV2 } from "./plan-schema.js";
 
 function getKjHome() {
   return process.env.KJ_HOME || path.join(os.homedir(), ".kj");
@@ -19,28 +22,30 @@ function projectSlug(projectDir) {
     .slice(0, 120);
 }
 
-function plansDir(projectDir) {
+export function plansDir(projectDir) {
   return path.join(getKjHome(), "plans", projectSlug(projectDir));
 }
 
-function generatePlanId() {
-  const now = new Date();
-  const ts = now.toISOString().replace(/[-:T]/g, "").replace(/\.\d+Z$/, "");
-  const rand = Math.random().toString(36).slice(2, 6);
-  return `plan-${ts}-${rand}`;
-}
-
 /**
- * Save a plan result to disk.
- * @param {string} projectDir - Absolute path to the project
- * @param {object} planResult - { task, researchContext, architectContext, plan, raw }
+ * Save a plan to disk. Accepts both v1 and v2 schemas.
+ * @param {string} projectDir
+ * @param {object} planResult - v1 { task, plan, raw } or v2 { planId, version, hus, ... }
  * @returns {Promise<string>} planId
  */
 export async function savePlan(projectDir, planResult) {
   const dir = plansDir(projectDir);
   await fs.mkdir(dir, { recursive: true });
 
-  const planId = generatePlanId();
+  // v2 plans already have planId and full schema
+  if (isPlanV2(planResult)) {
+    const filePath = path.join(dir, `${planResult.planId}.json`);
+    planResult.updatedAt = new Date().toISOString();
+    await fs.writeFile(filePath, JSON.stringify(planResult, null, 2), "utf8");
+    return planResult.planId;
+  }
+
+  // v1: generate planId and wrap
+  const planId = planResult.planId || generatePlanId();
   const record = {
     planId,
     task: planResult.task || null,
@@ -57,25 +62,51 @@ export async function savePlan(projectDir, planResult) {
 }
 
 /**
- * Load a saved plan by ID.
- * @param {string} projectDir
- * @param {string} planId
- * @returns {Promise<object|null>} { planId, task, researchContext, architectContext, plan, createdAt } or null
+ * Load a plan by ID. Auto-migrates v1 to v2 on read (lazy).
+ * @returns {Promise<object|null>} v2 plan or null
  */
 export async function loadPlan(projectDir, planId) {
   const filePath = path.join(plansDir(projectDir), `${planId}.json`);
   try {
     const data = await fs.readFile(filePath, "utf8");
-    return JSON.parse(data);
+    const plan = JSON.parse(data);
+    if (!isPlanV2(plan)) return migratePlanV1toV2(plan);
+    return plan;
   } catch {
     return null;
   }
 }
 
 /**
- * List all plans for a project, sorted by creation time (newest first).
- * @param {string} projectDir
- * @returns {Promise<Array<{planId: string, task: string, createdAt: string}>>}
+ * Update a plan on disk (partial merge).
+ * @returns {Promise<boolean>}
+ */
+export async function updatePlan(projectDir, planId, patch) {
+  const plan = await loadPlan(projectDir, planId);
+  if (!plan) return false;
+  Object.assign(plan, patch);
+  plan.updatedAt = new Date().toISOString();
+  const filePath = path.join(plansDir(projectDir), `${planId}.json`);
+  await fs.writeFile(filePath, JSON.stringify(plan, null, 2), "utf8");
+  return true;
+}
+
+/**
+ * Delete a plan from disk.
+ * @returns {Promise<boolean>}
+ */
+export async function deletePlan(projectDir, planId) {
+  const filePath = path.join(plansDir(projectDir), `${planId}.json`);
+  try {
+    await fs.unlink(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * List all plans for a project, sorted newest first.
  */
 export async function listPlans(projectDir) {
   const dir = plansDir(projectDir);
@@ -95,9 +126,13 @@ export async function listPlans(projectDir) {
       plans.push({
         planId: record.planId,
         task: record.task,
+        name: record.name || null,
+        status: record.status || "draft",
+        version: record.version || 1,
+        huCount: Array.isArray(record.hus) ? record.hus.length : 0,
         createdAt: record.createdAt
       });
-    } catch { /* skip corrupt files */ }
+    } catch { /* skip corrupt */ }
   }
 
   plans.sort((a, b) => (b.createdAt || "").localeCompare(a.createdAt || ""));
@@ -105,9 +140,7 @@ export async function listPlans(projectDir) {
 }
 
 /**
- * Get the most recent plan for a project.
- * @param {string} projectDir
- * @returns {Promise<object|null>}
+ * Get the most recent plan.
  */
 export async function getLatestPlan(projectDir) {
   const all = await listPlans(projectDir);

package/src/prompts/architect.js

@@ -9,7 +9,7 @@ const SUBAGENT_PREAMBLE = [
 
 export const VALID_VERDICTS = new Set(["ready", "needs_clarification"]);
 
-export async function buildArchitectPrompt({ task, instructions, researchContext = null, productContext = null, domainContext = null, projectDir = null, language = "en" }) {
+export async function buildArchitectPrompt({ task, instructions, researchContext = null, productContext = null, domainContext = null, projectDir = null, language = "en", provider = null }) {
   const langInstruction = getLanguageInstruction(language);
   const sections = [SUBAGENT_PREAMBLE, ...(langInstruction ? [langInstruction] : [])];
 
@@ -51,7 +51,7 @@ export async function buildArchitectPrompt({ task, instructions, researchContext
 
   if (projectDir) {
     const skills = await loadAvailableSkills(projectDir);
-    const skillSection = buildSkillSection(skills);
+    const skillSection = buildSkillSection(skills, { provider, role: "architect" });
     if (skillSection) {
       sections.push(skillSection);
     }

package/src/prompts/coder.js

@@ -33,7 +33,7 @@ const SERENA_INSTRUCTIONS = [
   "Fall back to reading files only when Serena tools are not sufficient."
 ].join("\n");
 
-export async function buildCoderPrompt({ task, reviewerFeedback = null, sonarSummary = null, coderRules = null, methodology = "tdd", serenaEnabled = false, rtkAvailable = false, deferredContext = null, productContext = null, domainContext = null, plan = null, projectDir = null, language = "en" }) {
+export async function buildCoderPrompt({ task, reviewerFeedback = null, sonarSummary = null, coderRules = null, methodology = "tdd", serenaEnabled = false, rtkAvailable = false, deferredContext = null, productContext = null, domainContext = null, plan = null, projectDir = null, language = "en", provider = null }) {
   const langInstruction = getLanguageInstruction(language);
   const sections = [
     serenaEnabled ? SUBAGENT_PREAMBLE_SERENA : SUBAGENT_PREAMBLE,
@@ -108,7 +108,7 @@ export async function buildCoderPrompt({ task, reviewerFeedback = null, sonarSum
 
   if (projectDir) {
     const skills = await loadAvailableSkills(projectDir);
-    const skillSection = buildSkillSection(skills);
+    const skillSection = buildSkillSection(skills, { provider });
     if (skillSection) {
       sections.push(skillSection);
     }

package/src/prompts/prompt-resolver.js

@@ -0,0 +1,127 @@
+/**
+ * Provider-aware role template resolver.
+ *
+ * Extends the legacy `resolveRoleMdPath()` contract from base-role.js to
+ * support per-provider variants without breaking existing consumers.
+ *
+ * Lookup order (first match wins):
+ *
+ *   1. <projectDir>/.karajan/roles/{role}/{provider}.md   project override, per provider
+ *   2. <projectDir>/.karajan/roles/{role}/default.md      project override, default
+ *   3. <projectDir>/.karajan/roles/{role}.md              project override, legacy flat
+ *   4. <karajanHome>/roles/{role}/{provider}.md           user home, per provider
+ *   5. <karajanHome>/roles/{role}/default.md              user home, default
+ *   6. <karajanHome>/roles/{role}.md                      user home, legacy flat
+ *   7. <built-in>/templates/roles/{role}/{provider}.md    built-in, per provider
+ *   8. <built-in>/templates/roles/{role}/default.md       built-in, default
+ *   9. <built-in>/templates/roles/{role}.md               built-in, legacy flat (back-compat)
+ *
+ * When `provider` is undefined/null the per-provider entries are skipped and
+ * only the default + legacy tiers are tried.
+ *
+ * If a provider is supplied but no per-provider file exists, we emit a
+ * one-time `prompt-resolver:fallback` event/log entry so the user knows their
+ * config asked for a variant that isn't present.
+ */
+
+import fs from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { getKarajanHome } from "../utils/paths.js";
+import { normalizeProvider } from "../utils/provider-env.js";
+
+/**
+ * Compute the full list of candidate file paths for a role template.
+ *
+ * @param {string} role                - role slug (e.g. "coder")
+ * @param {string|null|undefined} provider - provider slug or CLI name;
+ *                                           normalized internally
+ * @param {string|null|undefined} projectDir
+ * @returns {{ perProvider: string[], default: string[], legacy: string[], all: string[], provider: string|null }}
+ */
+export function resolveRolePromptPaths(role, provider, projectDir) {
+  if (!role || typeof role !== "string") {
+    throw new Error("resolveRolePromptPaths: role name is required");
+  }
+  const normalized = provider ? normalizeProvider(provider) : null;
+  const canonical = normalized && normalized.length > 0 ? normalized : null;
+
+  const homes = [];
+  if (projectDir) homes.push(path.join(projectDir, ".karajan", "roles"));
+  homes.push(path.join(getKarajanHome(), "roles"));
+
+  const builtInRoot = path.resolve(
+    path.dirname(fileURLToPath(import.meta.url)),
+    "..",
+    "..",
+    "templates",
+    "roles"
+  );
+  homes.push(builtInRoot);
+
+  const perProvider = [];
+  const defaults = [];
+  const legacy = [];
+
+  for (const home of homes) {
+    if (canonical) {
+      perProvider.push(path.join(home, role, `${canonical}.md`));
+    }
+    defaults.push(path.join(home, role, "default.md"));
+    legacy.push(path.join(home, `${role}.md`));
+  }
+
+  // Interleave: for each home, try per-provider first, then default, then
+  // legacy. This gives the user's project override precedence over the
+  // built-in default even when they only supplied a legacy flat file.
+  const all = [];
+  for (const home of homes) {
+    if (canonical) all.push(path.join(home, role, `${canonical}.md`));
+    all.push(path.join(home, role, "default.md"));
+    all.push(path.join(home, `${role}.md`));
+  }
+
+  return { perProvider, default: defaults, legacy, all, provider: canonical };
+}
+
+/**
+ * Return the contents of the first existing candidate path. Returns null if
+ * no template is found.
+ *
+ * @param {string[]} paths
+ * @returns {Promise<{content: string, path: string}|null>}
+ */
+export async function readFirstExisting(paths) {
+  for (const p of paths) {
+    try {
+      const content = await fs.readFile(p, "utf8");
+      return { content, path: p };
+    } catch { /* file not found, keep trying */ }
+  }
+  return null;
+}
+
+/**
+ * Load role instructions resolved for a specific provider.
+ *
+ * @param {Object} args
+ * @param {string} args.role
+ * @param {string|null|undefined} args.provider
+ * @param {string|null|undefined} args.projectDir
+ * @param {{ warn?: Function, debug?: Function }} [args.logger]
+ * @returns {Promise<{ instructions: string|null, path: string|null, resolvedProvider: string|null, fellBack: boolean }>}
+ */
+export async function loadRoleInstructions({ role, provider, projectDir, logger } = {}) {
+  const { all, provider: canonical } = resolveRolePromptPaths(role, provider, projectDir);
+  const hit = await readFirstExisting(all);
+  if (!hit) {
+    return { instructions: null, path: null, resolvedProvider: canonical, fellBack: !!canonical };
+  }
+  // Detect fallback: if the user asked for a provider but we matched a path
+  // that is NOT a per-provider file, we consider it a fallback and warn.
+  const fellBack = !!canonical && !hit.path.endsWith(`${canonical}.md`);
+  if (fellBack && logger?.debug) {
+    logger.debug(`prompt-resolver: role "${role}" has no "${canonical}" variant, using ${path.basename(hit.path)}`);
+  }
+  return { instructions: hit.content, path: hit.path, resolvedProvider: canonical, fellBack };
+}