@hjr15/blaze-board 0.2.0

package/scripts/log-runner.mjs

@@ -0,0 +1,38 @@
+// scripts/log-runner.mjs — CLI entry for `blaze log`. Parses the positional
+// id + minutes and --date/--note flags, calls applyLog against the resolved
+// data tree, then commits (or queues). Mirrors new-runner.mjs's commit pattern.
+import { applyLog } from "./log.mjs";
+import { formatMinutes } from "./model/time.mjs";
+import { loadConfig, resolveRoots } from "./config.mjs";
+import { commitOrQueue } from "./commit-or-queue.mjs";
+
+const { dataRoot, projectsDir } = resolveRoots();
+const argv = process.argv.slice(2);
+
+const opts = {};
+const positional = [];
+for (let i = 0; i < argv.length; i++) {
+  const a = argv[i];
+  switch (a) {
+    case "--date": opts.date = argv[++i]; break;
+    case "--note": opts.note = argv[++i]; break;
+    default:
+      if (a.startsWith("--")) { console.error(`unknown flag: ${a}`); process.exit(1); }
+      positional.push(a);
+  }
+}
+const [id, minutesRaw] = positional;
+opts.today = new Date().toISOString().slice(0, 10);
+
+if (!id || minutesRaw === undefined) {
+  console.error('usage: blaze log <id> <minutes> [--date YYYY-MM-DD] [--note "..."]');
+  process.exit(1);
+}
+
+const r = applyLog(projectsDir, id, Number(minutesRaw), opts);
+if (!r.ok) { console.error(`blaze log failed:\n  ${r.errors.join("\n  ")}`); process.exit(1); }
+
+const cfg = loadConfig({ root: dataRoot });
+const c = commitOrQueue({ root: dataRoot, mode: cfg.commitMode, op: "log", id: r.id, message: `${r.id}: log ${r.minutes}m`, files: [r.file] });
+if (!c.ok) { console.error(`blaze log: file written but commit failed (status ${c.status}) — commit manually`); process.exit(1); }
+console.log(`logged ${r.minutes}m to ${r.id} (total ${formatMinutes(r.total_worklog_minutes)})${c.queued ? " (queued for blaze commit)" : ""}`);

package/scripts/log.mjs

@@ -0,0 +1,44 @@
+// scripts/log.mjs — `blaze log <id> <minutes>`: append a worklog entry to a
+// ticket. applyLog() is pure-fs (no git) for tests; the CLI wrapper commits.
+// Worklog minutes round to 1m and must be positive (model/time.roundWorklog).
+import { writeFileSync } from "node:fs";
+import { basename, dirname } from "node:path";
+import { walkTickets } from "./model/index.mjs";
+import { serializeTicket } from "./model/ticket.mjs";
+import { roundWorklog } from "./model/time.mjs";
+
+// Same id resolution as move.mjs: prefer the ticket whose project dir matches
+// the id prefix; fall back to the first id match.
+function locate(projectsDir, id) {
+  let fallback = null;
+  for (const t of walkTickets(projectsDir)) {
+    if (t.frontmatter.id !== id) continue;
+    const projectKey = basename(dirname(dirname(t.file)));
+    if (id.startsWith(`${projectKey}-`)) return t;
+    fallback ??= t;
+  }
+  return fallback;
+}
+
+export function applyLog(projectsDir, id, minutes, opts = {}) {
+  const { date = null, note = null, today = null } = opts;
+  const found = locate(projectsDir, id);
+  if (!found) return { ok: false, errors: [`ticket not found: ${id}`] };
+
+  let rounded;
+  try { rounded = roundWorklog(minutes); }
+  catch (e) { return { ok: false, errors: [e.message] }; }
+
+  const entry = { date: date ?? today, minutes: rounded };
+  if (note) entry.note = note;
+
+  const fm = { ...found.frontmatter };
+  const worklog = Array.isArray(fm.worklog) ? [...fm.worklog] : [];
+  worklog.push(entry);
+  fm.worklog = worklog;
+  if (today) fm.updated = today;
+
+  const total = worklog.reduce((s, w) => s + (Number(w.minutes) || 0), 0);
+  writeFileSync(found.file, serializeTicket({ frontmatter: fm, body: found.body }));
+  return { ok: true, id, minutes: rounded, total_worklog_minutes: total, file: found.file };
+}

package/scripts/loops/groomer.mjs

@@ -0,0 +1,215 @@
+// groomer.mjs — the agentic board-keeper loop: pick an ungroomed ticket, drive the
+// configured agent command to edit it, then auto-commit the change.
+import { createHash } from "node:crypto";
+import {
+  readdirSync, readFileSync, writeFileSync, existsSync, mkdirSync,
+} from "node:fs";
+import { join } from "node:path";
+import { spawnSync, execFileSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { parseTicket } from "../model/ticket.mjs";
+
+export function hashContent(s) {
+  return createHash("sha1").update(s).digest("hex");
+}
+
+export function loadState(root) {
+  const p = join(root, ".blaze", "state.json");
+  if (!existsSync(p)) return { groomed: {} };
+  try {
+    const s = JSON.parse(readFileSync(p, "utf8"));
+    return s && s.groomed ? s : { groomed: {} };
+  } catch {
+    return { groomed: {} };
+  }
+}
+
+export function saveState(root, state) {
+  const dir = join(root, ".blaze");
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  writeFileSync(join(dir, "state.json"), JSON.stringify(state, null, 2));
+}
+
+export function selectNextTicket(root, cfg, state) {
+  for (const col of cfg.loops.groomer.columns) {
+    let files = [];
+    try {
+      files = readdirSync(join(root, col)).filter((f) => cfg.fileRegex.test(f));
+    } catch {
+      continue;
+    }
+    files.sort();
+    for (const file of files) {
+      const rel = `${col}/${file}`;
+      const raw = readFileSync(join(root, rel), "utf8");
+      const m = cfg.idLineRegex.exec(raw);
+      if (!m) continue;
+      const id = m[1];
+      if (state.groomed[id] !== hashContent(raw)) return { id, file, col, rel, raw };
+    }
+  }
+  return null;
+}
+
+export function extractGroomingRules(agentsMd) {
+  const m = /## Grooming rules[\s\S]*?(?=\n## |\n# |$)/.exec(agentsMd || "");
+  return m ? m[0].trim() : "";
+}
+
+export function buildPrompt(ticket, rules, cfg) {
+  const labels = (cfg.defaultLabels || []).join(", ");
+  const guard = [
+    "You are a groomer. PROPOSE improvements only — never transition, never resolve, never move the file.",
+    "Draft Acceptance Criteria, suggest an estimate, and suggest a parent/links.",
+    `Write suggestions ONLY as a subsection under \`## Notes\` titled \`Groomer proposals (${cfg.today || ""})\`.`,
+    "Do NOT change the `status`, `resolution`, `parent`, or `estimate` frontmatter fields — a human/agent applies accepted proposals via `blaze move`/`blaze edit`.",
+  ].join("\n");
+  return [
+    guard,
+    ``,
+    `You are grooming an issue-tracker ticket. Edit ONLY the file at ${ticket.rel} and no other file.`,
+    labels ? `Use only these labels: ${labels}.` : "",
+    ``,
+    rules,
+    ``,
+    `--- ticket: ${ticket.rel} ---`,
+    ticket.raw,
+  ].join("\n");
+}
+
+export function parseChangedFiles(diffOut) {
+  return diffOut.split("\n").map((s) => s.trim()).filter(Boolean);
+}
+
+/**
+ * Parse `git status --porcelain --untracked-files=all` output into a list of
+ * affected paths. Handles:
+ *   " M path"  — unstaged modification
+ *   "M  path"  — staged modification
+ *   "A  path"  — staged add (new file)
+ *   "?? path"  — untracked new file
+ *   " D path"  — unstaged deletion
+ *   "D  path"  — staged deletion
+ *   "R  old -> new"  — staged rename (take the new path)
+ * Returns deduplicated list of paths.
+ */
+export function parsePorcelain(porcelain) {
+  const seen = new Set();
+  for (const line of porcelain.split("\n")) {
+    if (!line) continue;
+    const xy = line.slice(0, 2);
+    const rest = line.slice(3);
+    let path;
+    // Rename: "R  old -> new" or "R  old\0new" — porcelain v1 uses " -> "
+    if (xy[0] === "R" || xy[1] === "R") {
+      const arrow = rest.indexOf(" -> ");
+      path = arrow >= 0 ? rest.slice(arrow + 4) : rest;
+    } else {
+      path = rest;
+    }
+    path = path.trim();
+    if (path) seen.add(path);
+  }
+  return [...seen];
+}
+
+/**
+ * Returns true if the before/after content represents a structural change:
+ * - resolution frontmatter value changed
+ * - status frontmatter value changed
+ * These fields must only be mutated by explicit human/agent `blaze move`/`blaze edit`.
+ *
+ * Uses parseTicket (the real parser) to extract field values so that a duplicated
+ * key in the frontmatter cannot evade the guard via first-match regex.
+ */
+export function isStructuralChange(before, after) {
+  let parsedBefore = null;
+  let parsedAfter = null;
+  try { parsedBefore = parseTicket(before); } catch { /* no frontmatter */ }
+  try { parsedAfter = parseTicket(after); } catch { /* no frontmatter */ }
+
+  // If before had frontmatter but after does not → structural (gutted ticket).
+  if (parsedBefore && !parsedAfter) return true;
+  // If neither had frontmatter → no structural change to detect.
+  if (!parsedBefore && !parsedAfter) return false;
+  // If after has frontmatter but before didn't → treat as non-structural (new frontmatter added).
+  if (!parsedBefore) return false;
+
+  const fmBefore = parsedBefore.frontmatter;
+  const fmAfter = parsedAfter.frontmatter;
+  for (const field of ["resolution", "status"]) {
+    // Normalise to string for comparison: null/undefined both mean "absent".
+    const vBefore = fmBefore[field] ?? null;
+    const vAfter = fmAfter[field] ?? null;
+    if (String(vBefore) !== String(vAfter)) return true;
+  }
+  return false;
+}
+
+export function commitMessage(id, files) {
+  return `chore(groom): ${id} ${files.length} file(s) groomed`;
+}
+
+export function groomOnce({ root, cfg, agentsMd, today }) {
+  const state = loadState(root);
+  const ticket = selectNextTicket(root, cfg, state);
+  if (!ticket) return null;
+
+  const prompt = buildPrompt(ticket, extractGroomingRules(agentsMd), cfg);
+  const [cmd, ...args] = cfg.agentCommand.split(" ");
+  const r = spawnSync(cmd, [...args, prompt], {
+    cwd: root,
+    encoding: "utf8",
+    env: { ...process.env, BLAZE_GROOM_TARGET: ticket.rel },
+  });
+  if (r.status !== 0) {
+    return { type: "groom", id: ticket.id, error: ((r.stderr || "agent command failed") + "").slice(0, 200), ts: today };
+  }
+
+  const porcelain = execFileSync("git", ["-C", root, "status", "--porcelain", "--untracked-files=all"], { encoding: "utf8" });
+  const changed = parsePorcelain(porcelain).filter((f) => cfg.columns.some((c) => f.startsWith(`${c}/`)));
+  const record = () => {
+    const raw = readFileSync(join(root, ticket.rel), "utf8");
+    state.groomed[ticket.id] = hashContent(raw);
+    saveState(root, state);
+  };
+
+  if (!changed.length) {
+    record(); // mark groomed so we don't re-run on a no-op
+    return { type: "groom", id: ticket.id, noop: true, ts: today };
+  }
+
+  // Guard: detect renames (status-dir change) or structural frontmatter mutations.
+  // A rename means any changed path lands in a different column dir than the ticket's.
+  const ticketDir = ticket.rel.split("/")[0];
+  const hasRename = changed.some((f) => f.split("/")[0] !== ticketDir);
+  const afterRaw = existsSync(join(root, ticket.rel)) ? readFileSync(join(root, ticket.rel), "utf8") : "";
+  const hasStructuralFmChange = isStructuralChange(ticket.raw, afterRaw);
+  if (hasRename || hasStructuralFmChange) {
+    // Reset all changes so the tree stays clean.
+    // Staged changes must be unstaged first; untracked new files must be removed.
+    try { execFileSync("git", ["-C", root, "restore", "--staged", "--", ...changed]); } catch {}
+    try { execFileSync("git", ["-C", root, "checkout", "--", ...changed]); } catch {}
+    try { execFileSync("git", ["-C", root, "clean", "-f", "--", ...changed]); } catch {}
+    console.error(`groomer: refused structural change on ${ticket.id}`);
+    return { type: "groom", id: ticket.id, refused: true, ts: today };
+  }
+
+  execFileSync("git", ["-C", root, "add", ...changed]);
+  execFileSync("git", ["-C", root, "commit", "-m", commitMessage(ticket.id, changed), "--", ...changed]);
+  const sha = execFileSync("git", ["-C", root, "rev-parse", "HEAD"], { encoding: "utf8" }).trim();
+  record();
+  return { type: "groom", id: ticket.id, sha, files: changed, ts: today };
+}
+
+// CLI: `node scripts/loops/groomer.mjs` runs one grooming pass.
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+  const { loadConfig, resolveRoots } = await import("../config.mjs");
+  const root = resolveRoots().dataRoot;
+  const cfg = loadConfig({ root });
+  let agentsMd = "";
+  try { agentsMd = readFileSync(join(root, "AGENTS.md"), "utf8"); } catch {}
+  const today = new Date().toISOString().slice(0, 10);
+  const evt = groomOnce({ root, cfg, agentsMd, today });
+  console.log(evt ? JSON.stringify(evt) : "groomer: nothing to groom.");
+}

package/scripts/migrate/audit.mjs

@@ -0,0 +1,92 @@
+// scripts/migrate/audit.mjs — pure: per-item disposition (drop / keep / merge-into
+// / re-parent) for the curated migration. Drop = non-Done terminal (Won't Do /
+// Duplicate / Cannot Reproduce / abandoned). Merges are PROPOSED here (heuristic);
+// the user confirms via the ledger. proposed_status/proposed_parent come from the
+// status map + the restructure proposal.
+import { mapType, mapStatus } from "./map.mjs";
+import { isTerminal } from "../model/workflows.mjs";
+import { isType } from "../model/schema.mjs";
+
+export const DROP_RESOLUTIONS = new Set(["won't do", "wont do", "duplicate", "cannot reproduce"]);
+
+function bigrams(s) {
+  const t = String(s ?? "").toLowerCase().replace(/[^a-z0-9]+/g, " ").trim();
+  const grams = new Set();
+  for (let i = 0; i < t.length - 1; i++) grams.add(t.slice(i, i + 2));
+  return grams;
+}
+export function titleSimilarity(a, b) {
+  const ba = bigrams(a), bb = bigrams(b);
+  if (ba.size === 0 || bb.size === 0) return 0;
+  let inter = 0;
+  for (const g of ba) if (bb.has(g)) inter++;
+  return (2 * inter) / (ba.size + bb.size);
+}
+
+function worklogSeconds(n) { return (n.worklog || []).reduce((s, w) => s + (w.seconds || 0), 0); }
+function numId(key) { const m = /-(\d+)$/.exec(key); return m ? Number(m[1]) : Infinity; }
+
+export function detectMerges(norms) {
+  const merges = new Map();      // loser → survivor
+  const folded = new Set();
+  for (let i = 0; i < norms.length; i++) {
+    for (let j = i + 1; j < norms.length; j++) {
+      const a = norms[i], b = norms[j];
+      if (a.project !== b.project) continue;
+      if (folded.has(a.key) || folded.has(b.key)) continue;
+      const sharedComp = (a.components || []).some((c) => (b.components || []).includes(c));
+      const linked = (a.links || []).some((l) => (l.type === "Relates" || l.type === "Duplicate") && l.target === b.key)
+                  || (b.links || []).some((l) => (l.type === "Relates" || l.type === "Duplicate") && l.target === a.key);
+      if (titleSimilarity(a.summary, b.summary) >= 0.6 && (sharedComp || linked)) {
+        // survivor = more worklog, tie → earlier numeric key
+        const aw = worklogSeconds(a), bw = worklogSeconds(b);
+        const survivor = aw !== bw ? (aw > bw ? a : b) : (numId(a.key) <= numId(b.key) ? a : b);
+        const loser = survivor === a ? b : a;
+        merges.set(loser.key, survivor.key);
+        folded.add(loser.key);
+      }
+    }
+  }
+  return merges;
+}
+
+export function auditIssues(norms, restructure, opts = {}) {
+  const merges = opts.detectMerges === true ? detectMerges(norms) : new Map();
+  const dispositions = [];
+  let kept = 0, dropped = 0, merged = 0;
+
+  for (const n of norms) {
+    const type = mapType(n.type);
+    const res = n.resolution ? String(n.resolution).toLowerCase() : null;
+    const terminalNoRes = isType(type) && n.status && isTerminal(type, mapStatus(type, n.status, n.statusCategory).status) && !res;
+
+    if (res && DROP_RESOLUTIONS.has(res)) {
+      dispositions.push({ id: n.key, type, disposition: "drop", reason: `resolution: ${n.resolution}`,
+        proposed_status: null, proposed_parent: null });
+      dropped++; continue;
+    }
+    if (terminalNoRes) {
+      dispositions.push({ id: n.key, type, disposition: "drop", reason: "abandoned (terminal status, no resolution)",
+        proposed_status: null, proposed_parent: null });
+      dropped++; continue;
+    }
+    if (merges.has(n.key)) {
+      const survivor = merges.get(n.key);
+      dispositions.push({ id: n.key, type, disposition: `merge-into:${survivor}`,
+        reason: `duplicate of ${survivor}`, proposed_status: null, proposed_parent: null });
+      merged++; continue;
+    }
+
+    const proposedParent = restructure.parents.get(n.key) ?? null;
+    const { status } = isType(type) ? mapStatus(type, n.status, n.statusCategory) : { status: null };
+    const reParented = proposedParent !== (n.parent ?? null) && proposedParent !== null;
+    dispositions.push({
+      id: n.key, type,
+      disposition: reParented ? `re-parent:${proposedParent}` : "keep",
+      reason: reParented ? `parent ${n.parent ?? "∅"} → ${proposedParent}` : (n.resolution ? `resolution: ${n.resolution}` : "in-flight"),
+      proposed_status: status, proposed_parent: proposedParent,
+    });
+    kept++;
+  }
+  return { dispositions, stats: { source: norms.length, kept, dropped, merged } };
+}

package/scripts/migrate/jira-client.mjs

@@ -0,0 +1,26 @@
+// scripts/migrate/jira-client.mjs — the migration I/O boundary. The raw Jira
+// pull is performed by the jira-export-migrator AGENT (a node script has no
+// access to mcp__atlassian__* tools); the agent writes raw issues here. This
+// module only reads/writes the .migration-cache/ files. Pure-fs, zero-dep.
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from "node:fs";
+import { join } from "node:path";
+
+export function cacheFile(cacheDir, key) {
+  return join(cacheDir, `${key}.json`);
+}
+
+export function writeRawCache(cacheDir, key, rawIssues) {
+  mkdirSync(cacheDir, { recursive: true });
+  writeFileSync(cacheFile(cacheDir, key), JSON.stringify({ key, issues: rawIssues }, null, 2));
+}
+
+export function readRawCache(cacheDir, key) {
+  const file = cacheFile(cacheDir, key);
+  if (!existsSync(file)) {
+    throw new Error(
+      `migration cache missing: ${file}\n` +
+      `Populate it with the jira-export-migrator agent (paginated MCP pull) before running blaze migrate.`);
+  }
+  const parsed = JSON.parse(readFileSync(file, "utf8"));
+  return Array.isArray(parsed) ? parsed : (parsed.issues ?? []);
+}

package/scripts/migrate/jira-import.mjs

@@ -0,0 +1,96 @@
+// scripts/migrate/jira-import.mjs — the migration orchestrator. runDryRun (this
+// task) runs the audit pipeline over the cache and returns the audit markdown +
+// ledger object WITHOUT writing tickets. runLive (Task 9) executes the edited
+// ledger. Pure of git; the runner does file writes + the bulk commit.
+import { writeFileSync, mkdirSync, readdirSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { readRawCache } from "./jira-client.mjs";
+import { normalizeIssue } from "./normalize.mjs";
+import { mapIssue } from "./map.mjs";
+import { proposeStructure } from "./restructure.mjs";
+import { auditIssues } from "./audit.mjs";
+import { renderAudit, renderLedger } from "./report.mjs";
+import { serializeTicket } from "../model/ticket.mjs";
+import { foldMerges, resolveLinkIntegrity } from "./merge.mjs";
+
+export function loadNormalized(cacheDir, keys) {
+  const norms = [];
+  for (const key of keys) for (const raw of readRawCache(cacheDir, key)) norms.push(normalizeIssue(raw));
+  return norms;
+}
+
+export function runDryRun({ cacheDir, keys, detectMerges = false }) {
+  const norms = loadNormalized(cacheDir, keys);
+  const restructure = proposeStructure(norms);
+  const { dispositions, stats } = auditIssues(norms, restructure, { detectMerges });
+
+  // Collect warnings by mapping each kept/re-parented item.
+  const byKey = new Map(norms.map((n) => [n.key, n]));
+  const warnings = [];
+  for (const d of dispositions) {
+    if (d.disposition !== "keep" && !d.disposition.startsWith("re-parent:")) continue;
+    const { warnings: w } = mapIssue(byKey.get(d.id), { proposedParent: d.proposed_parent, proposedStatus: d.proposed_status });
+    warnings.push(...w);
+  }
+
+  // Compute link-integrity report for the audit output.
+  const { survivors: drySurvivors } = foldMerges(new Map(norms.map((n) => [n.key, n])), dispositions);
+  const { integrity } = resolveLinkIntegrity(drySurvivors, dispositions);
+
+  const source = {};
+  for (const n of norms) source[n.project] = (source[n.project] || 0) + 1;
+
+  return {
+    auditMd: renderAudit({ norms, dispositions, restructure, warnings, integrity }),
+    ledger: renderLedger(dispositions, source),
+    stats,
+  };
+}
+
+function slugify(s) { return String(s).toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, ""); }
+
+// Remove any existing file for `id` under projectsDir/<KEY>/* so a re-run with a
+// changed status doesn't leave a duplicate (idempotency).
+function removeExisting(projectsDir, project, id) {
+  const projDir = join(projectsDir, project);
+  let statuses = [];
+  try { statuses = readdirSync(projDir); } catch { return; }
+  for (const st of statuses) {
+    const dir = join(projDir, st);
+    let files = [];
+    try { files = readdirSync(dir); } catch { continue; }
+    for (const f of files) if (f.startsWith(`${id}-`) || f === `${id}.md`) rmSync(join(dir, f), { force: true });
+  }
+}
+
+export function runLive({ cacheDir, projectsDir, keys, ledger }) {
+  const norms = loadNormalized(cacheDir, keys);
+  const byKey = new Map(norms.map((n) => [n.key, n]));
+  const dispositions = ledger.items;
+  const dispById = new Map(dispositions.map((d) => [d.id, d]));
+
+  const { survivors: rawSurvivors } = foldMerges(byKey, dispositions);
+  const { survivors } = resolveLinkIntegrity(rawSurvivors, dispositions);
+
+  const written = [];
+  const files = [];
+  let dropped = 0, merged = 0;
+  for (const d of dispositions) {
+    if (d.disposition === "drop") { dropped++; continue; }
+    if (d.disposition.startsWith("merge-into:")) { merged++; continue; }
+  }
+
+  for (const [key, survivor] of survivors) {
+    const d = dispById.get(key) || {};
+    const { frontmatter, body, status } = mapIssue(survivor, { proposedParent: d.proposed_parent, proposedStatus: d.proposed_status });
+    const project = frontmatter.project;
+    removeExisting(projectsDir, project, key);
+    const dir = join(projectsDir, project, status);
+    mkdirSync(dir, { recursive: true });
+    const file = join(dir, `${key}-${slugify(frontmatter.title)}.md`);
+    writeFileSync(file, serializeTicket({ frontmatter, body }));
+    written.push(key);
+    files.push(file);
+  }
+  return { written, dropped, merged, files };
+}

package/scripts/migrate/map.mjs

@@ -0,0 +1,110 @@
+// scripts/migrate/map.mjs — pure: mapping tables + NormalizedIssue → a Blaze
+// ticket object { frontmatter, body, status, warnings }. The single home for the
+// Jira→blaze field/status/resolution/priority tables. Reuses model/* for rounding,
+// the type set, workflow statuses, and validation. Does not serialize or write —
+// the live orchestrator does that (Task 9).
+import { roundEstimate, roundWorklog } from "../model/time.mjs";
+import { isType } from "../model/schema.mjs";
+import { initialStatus, statusesFor, isTerminal } from "../model/workflows.mjs";
+import { validateTicket } from "../model/rules.mjs";
+
+const TYPE_MAP = { goal: "goal", epic: "epic", risk: "risk", story: "story", task: "task", bug: "bug", "sub-task": "subtask", subtask: "subtask" };
+const PRIORITY_SET = new Set(["highest", "high", "medium", "low", "lowest"]);
+const RESOLUTION_MAP = { "done": "done", "won't do": "wont-do", "wont do": "wont-do", "duplicate": "duplicate", "cannot reproduce": "cannot-reproduce" };
+// Jira status NAME → blaze status, per workflow. Lowercased lookup.
+const STATUS_MAP = {
+  delivery: { "defined": "defined", "to do": "defined", "in progress": "in-progress", "in review": "in-review", "done": "done" },
+  goal:     { "defined": "defined", "in progress": "in-progress", "achieved": "achieved" },
+  risk:     { "identified": "identified", "mitigated": "mitigated", "accepted": "accepted", "obsolete": "obsolete" },
+};
+
+export function mapType(t) {
+  const key = String(t ?? "").toLowerCase();
+  return TYPE_MAP[key] ?? key;
+}
+export function mapPriority(p) {
+  const key = String(p ?? "").toLowerCase();
+  return PRIORITY_SET.has(key) ? key : "medium";
+}
+export function mapResolution(r) {
+  if (r == null) return null;
+  return RESOLUTION_MAP[String(r).toLowerCase()] ?? null;
+}
+
+// workflow name for a blaze type, mirroring schema.mjs (avoids importing the full
+// registry just for the workflow tag).
+function workflowOf(blazeType) {
+  if (blazeType === "goal") return "goal";
+  if (blazeType === "risk") return "risk";
+  return "delivery"; // epic/story/task/bug/subtask
+}
+
+function categoryFallback(blazeType, category) {
+  const statuses = statusesFor(blazeType);
+  if (category === "done") return statuses.find((s) => isTerminal(blazeType, s)) ?? statuses[statuses.length - 1];
+  if (category === "indeterminate") return statuses.find((s) => s !== statuses[0] && !isTerminal(blazeType, s)) ?? statuses[0];
+  return statuses[0]; // "new" or null/unknown → initial
+}
+
+export function mapStatus(blazeType, jiraStatus, statusCategory) {
+  const wf = workflowOf(blazeType);
+  const table = STATUS_MAP[wf] || {};
+  const hit = table[String(jiraStatus ?? "").toLowerCase()];
+  if (hit && (statusesFor(blazeType).includes(hit))) return { status: hit, unmapped: false };
+  if (statusCategory) return { status: categoryFallback(blazeType, String(statusCategory).toLowerCase()), unmapped: false };
+  return { status: initialStatus(blazeType), unmapped: true };
+}
+
+const IMPACT_WORDS = new Set(["extensive", "significant", "moderate", "minor"]);
+const LIKELIHOOD_WORDS = new Set(["low", "medium", "high"]);
+function firstWord(v) { return String(v ?? "").toLowerCase().split(/[^a-z]+/).find(Boolean) ?? null; }
+function mapImpact(v) { if (v == null) return null; const w = firstWord(v); return IMPACT_WORDS.has(w) ? w : String(v).toLowerCase(); }
+function mapLikelihood(v) { if (v == null) return null; const w = firstWord(v); return LIKELIHOOD_WORDS.has(w) ? w : String(v).toLowerCase(); }
+
+export function mapIssue(norm, { proposedParent, proposedStatus } = {}) {
+  const type = mapType(norm.type);
+  const known = isType(type);
+  const mapped = known ? mapStatus(type, norm.status, norm.statusCategory) : { status: null, unmapped: true };
+  const status = proposedStatus ?? mapped.status;
+
+  const estimate = roundEstimate(norm.estimateSeconds != null ? norm.estimateSeconds / 60 : null);
+  const worklogWarnings = [];
+  const worklog = (norm.worklog || []).flatMap((w) => {
+    const mins = (w.seconds || 0) / 60;
+    if (!Number.isFinite(mins) || mins <= 0) {
+      worklogWarnings.push(`${norm.key}: skipped zero/negative worklog entry`);
+      return [];
+    }
+    const entry = { date: w.date, minutes: roundWorklog(mins) };
+    if (w.note) entry.note = w.note;
+    return [entry];
+  });
+
+  const fm = {
+    id: norm.key, title: norm.summary, type, project: norm.project,
+    priority: mapPriority(norm.priority),
+    resolution: mapResolution(norm.resolution),
+    parent: proposedParent !== undefined ? proposedParent : (norm.parent ?? null),
+    assignee: norm.assignee ?? "unassigned",
+    labels: norm.labels || [], components: norm.components || [],
+    estimate,
+    worklog,
+    links: norm.links || [],
+    created: norm.created, updated: norm.updated,
+  };
+  if (type === "risk") {
+    fm.likelihood = mapLikelihood(norm.likelihood);
+    fm.impact = mapImpact(norm.impact);
+  }
+
+  const body = norm.description && norm.description.trim() ? norm.description : "## Context\n\n## Acceptance Criteria\n\n- [ ] \n\n## Notes\n";
+
+  const warnings = [...worklogWarnings];
+  if (!known) warnings.push(`unknown type '${norm.type}' for ${norm.key} (mapped to '${type}')`);
+  if (mapped.unmapped && known) warnings.push(`unmapped status '${norm.status}' for ${norm.key} (parked in '${mapped.status}')`);
+  for (const e of validateTicket({ frontmatter: fm, body })) {
+    if (/parent not found/.test(e)) continue; // parent integrity is a reindex concern
+    warnings.push(`${norm.key}: ${e}`);
+  }
+  return { frontmatter: fm, body, status, warnings };
+}