@hjr15/blaze-board 0.2.0

package/scripts/model/ticket.mjs

@@ -0,0 +1,136 @@
+// scripts/model/ticket.mjs — parse/serialize a Blaze ticket: a YAML-subset
+// frontmatter block + a markdown body. Zero-dependency; handles exactly the
+// field shapes Blaze uses (scalars, flow arrays [a,b], block lists of inline
+// {k: v} objects). Not a general YAML parser — round-trip safe for our schema.
+
+const DELIM = "---";
+
+function coerceScalar(raw) {
+  const s = raw.trim();
+  if (s === "" || s === "null" || s === "~") return null;
+  if (s === "true") return true;
+  if (s === "false") return false;
+  if (/^-?\d+$/.test(s)) return Number(s);
+  if (s.startsWith('"') && s.endsWith('"')) {
+    // Double-quoted: decode JSON escape sequences (dumpScalar uses JSON.stringify to
+    // quote strings containing commas, so we must reverse that here).
+    try { return JSON.parse(s); } catch { return s.slice(1, -1); }
+  }
+  if (s.startsWith("'") && s.endsWith("'")) {
+    return s.slice(1, -1);
+  }
+  return s;
+}
+
+function splitTopLevel(s, sep) {
+  const out = [];
+  let depth = 0, quote = null, cur = "";
+  for (const ch of s) {
+    if (quote) { if (ch === quote) quote = null; cur += ch; continue; }
+    if (ch === '"' || ch === "'") { quote = ch; cur += ch; continue; }
+    if (ch === "{" || ch === "[") depth++;
+    else if (ch === "}" || ch === "]") depth--;
+    if (ch === sep && depth === 0) { out.push(cur); cur = ""; continue; }
+    cur += ch;
+  }
+  if (cur.trim() !== "") out.push(cur);
+  return out;
+}
+
+function parseFlowArray(raw) {
+  const inner = raw.trim().slice(1, -1).trim();
+  if (inner === "") return [];
+  return splitTopLevel(inner, ",").map(coerceScalar);
+}
+
+// Note: inline-object values containing a comma must be quoted in the source file
+// (e.g. `{ k: "a, b" }`). The serializer (dumpScalar) always quotes such values;
+// hand-written files must do the same — an unquoted comma splits the value.
+function parseInlineObject(raw) {
+  const inner = raw.trim().slice(1, -1).trim();
+  const obj = {};
+  for (const part of splitTopLevel(inner, ",")) {
+    const idx = part.indexOf(":");
+    if (idx === -1) continue;
+    obj[part.slice(0, idx).trim()] = coerceScalar(part.slice(idx + 1));
+  }
+  return obj;
+}
+
+export function parseTicket(text) {
+  const lines = text.split("\n");
+  if (lines[0].trim() !== DELIM) throw new Error("ticket: missing frontmatter (--- on line 1)");
+  const fm = {};
+  let i = 1;
+  for (; i < lines.length; i++) {
+    const line = lines[i];
+    if (line.trim() === DELIM) { i++; break; }
+    if (line.trim() === "" || line.trimStart().startsWith("#")) continue;
+    // Only identifier-style keys (alphanumeric + underscore) are matched.
+    // Hyphenated YAML keys (e.g. "some-key") are intentionally ignored — they
+    // are not part of the Blaze schema.
+    const m = /^([A-Za-z0-9_]+):(.*)$/.exec(line);
+    if (!m) continue;
+    const key = m[1];
+    const rest = m[2].trim();
+    if (rest === "") {
+      const items = [];
+      let j = i + 1;
+      while (j < lines.length && /^\s+-\s+/.test(lines[j])) {
+        const itemRaw = lines[j].replace(/^\s+-\s+/, "").trim();
+        items.push(itemRaw.startsWith("{") ? parseInlineObject(itemRaw) : coerceScalar(itemRaw));
+        j++;
+      }
+      if (items.length > 0) { fm[key] = items; i = j - 1; } else fm[key] = null;
+    } else if (rest.startsWith("[")) {
+      fm[key] = parseFlowArray(rest);
+    } else {
+      fm[key] = coerceScalar(rest);
+    }
+  }
+  const body = lines.slice(i).join("\n").replace(/^\n+/, "");
+  return { frontmatter: fm, body };
+}
+
+const FIELD_ORDER = [
+  "id", "title", "type", "project", "priority", "resolution", "parent",
+  "assignee", "labels", "components", "estimate", "worklog", "links",
+  "likelihood", "impact", "branch", "pr", "created", "updated",
+];
+
+function dumpScalar(v) {
+  if (v === null || v === undefined) return "";
+  if (typeof v === "number" || typeof v === "boolean") return String(v);
+  const s = String(v);
+  // Quote strings containing a comma — an unquoted comma would break re-parse of a
+  // flow array [a, b] or an inline object { k: v, ... }. Colons in values are fine.
+  return s.includes(",") ? JSON.stringify(s) : s;
+}
+
+function dumpInlineObject(obj) {
+  return `{ ${Object.entries(obj).map(([k, v]) => `${k}: ${dumpScalar(v)}`).join(", ")} }`;
+}
+
+export function serializeTicket({ frontmatter, body }) {
+  const keys = [
+    ...FIELD_ORDER.filter((k) => k in frontmatter),
+    ...Object.keys(frontmatter).filter((k) => !FIELD_ORDER.includes(k)),
+  ];
+  const out = [DELIM];
+  for (const key of keys) {
+    const v = frontmatter[key];
+    if (Array.isArray(v)) {
+      if (v.length === 0) { out.push(`${key}: []`); continue; }
+      if (typeof v[0] === "object" && v[0] !== null) {
+        out.push(`${key}:`);
+        for (const item of v) out.push(`  - ${dumpInlineObject(item)}`);
+      } else {
+        out.push(`${key}: [${v.map(dumpScalar).join(", ")}]`);
+      }
+    } else {
+      out.push(`${key}: ${dumpScalar(v)}`);
+    }
+  }
+  out.push(DELIM, "", body.replace(/\n+$/, ""), "");
+  return out.join("\n");
+}

package/scripts/model/time.mjs

@@ -0,0 +1,38 @@
+// scripts/model/time.mjs — the single home for Blaze time policy: estimate
+// rounding (5m), worklog rounding (1m, positive-only), and human formatting.
+// Pure, zero-dependency. Consumed by new.mjs (estimate at create), log.mjs
+// (worklog), and the rollup/board display.
+
+// Estimate: round to the nearest 5 minutes. null/absent/non-finite/≤0 → null.
+// A positive value that would round to 0 is bumped to 5 — a positive estimate
+// never silently becomes "no estimate". (Spec §4.1.)
+export function roundEstimate(min) {
+  const n = Number(min);
+  if (!Number.isFinite(n) || n <= 0) return null;
+  const r = Math.round(n / 5) * 5;
+  return r === 0 ? 5 : r;
+}
+
+// Worklog: round to the nearest whole minute. Positive-only — throws on ≤0 or
+// non-finite (the positive-minutes guard for `blaze log`). (Spec §4.1.)
+export function roundWorklog(min) {
+  const n = Number(min);
+  if (!Number.isFinite(n) || n <= 0) {
+    throw new RangeError(`worklog minutes must be a positive number, got: ${min}`);
+  }
+  return Math.round(n);
+}
+
+// Human display: "1h 30m" / "45m" / "2h". null/undefined → "" (board renders
+// blank); 0 → "0m".
+export function formatMinutes(min) {
+  if (min === null || min === undefined) return "";
+  const n = Number(min);
+  if (!Number.isFinite(n)) return "";
+  if (n === 0) return "0m";
+  const h = Math.floor(n / 60);
+  const m = n % 60;
+  if (h === 0) return `${m}m`;
+  if (m === 0) return `${h}h`;
+  return `${h}h ${m}m`;
+}

package/scripts/model/workflows.mjs

@@ -0,0 +1,54 @@
+// scripts/model/workflows.mjs — Blaze type-scoped workflow definitions and
+// the pure resolvers over them (statuses, terminal, transitions, resolution
+// post-function). Config-driven; no I/O. Consumes the schema's type→workflow map.
+import { workflowFor } from "./schema.mjs";
+
+export const RESOLUTIONS = ["done", "wont-do", "duplicate", "cannot-reproduce"];
+
+export const WORKFLOWS = {
+  delivery: {
+    statuses: ["defined", "in-progress", "in-review", "done"],
+    terminal: ["done"],
+    transitions: [["defined", "in-progress"], ["in-progress", "in-review"], ["in-review", "done"]],
+    reopenTo: "defined",
+    resolutionOnTerminal: { done: "done" },
+  },
+  goal: {
+    statuses: ["defined", "in-progress", "achieved"],
+    terminal: ["achieved"],
+    transitions: [["defined", "in-progress"], ["in-progress", "achieved"]],
+    reopenTo: "defined",
+    resolutionOnTerminal: { achieved: "done" },
+  },
+  risk: {
+    statuses: ["identified", "mitigated", "accepted", "obsolete"],
+    terminal: ["mitigated", "accepted", "obsolete"],
+    transitions: [["identified", "mitigated"], ["identified", "accepted"], ["identified", "obsolete"]],
+    reopenTo: "identified",
+    resolutionOnTerminal: { mitigated: "done", accepted: "done", obsolete: "wont-do" },
+  },
+};
+
+export function workflowDef(type) {
+  const name = workflowFor(type); // throws on unknown type
+  const def = WORKFLOWS[name];
+  if (!def) throw new Error(`no workflow definition for "${name}" (type "${type}")`);
+  return def;
+}
+
+export function statusesFor(type) { return workflowDef(type).statuses; }
+export function isTerminal(type, status) { return workflowDef(type).terminal.includes(status); }
+export function initialStatus(type) { return workflowDef(type).statuses[0]; }
+
+export function canTransition(type, from, to) {
+  const def = workflowDef(type);
+  if (!def.statuses.includes(to)) return false;
+  if (to === def.reopenTo && from !== to) return true; // reopen from any other status
+  return def.transitions.some(([f, t]) => f === from && t === to);
+}
+
+export function resolutionForTerminal(type, status) {
+  const def = workflowDef(type);
+  return Object.prototype.hasOwnProperty.call(def.resolutionOnTerminal, status)
+    ? def.resolutionOnTerminal[status] : null;
+}

package/scripts/move-runner.mjs

@@ -0,0 +1,18 @@
+// scripts/move-runner.mjs — CLI entry for `blaze move <id> <status>`: applyMove
+// against the resolved data tree, then commit (or queue) the relocation.
+import { applyMove } from "./move.mjs";
+import { loadConfig, resolveRoots } from "./config.mjs";
+import { commitOrQueue } from "./commit-or-queue.mjs";
+
+const { dataRoot, projectsDir } = resolveRoots();
+const [id, toStatus] = process.argv.slice(2);
+if (!id || !toStatus) { console.error("usage: blaze move <id> <status>"); process.exit(1); }
+
+const today = new Date().toISOString().slice(0, 10);
+const r = applyMove(projectsDir, id, toStatus, { today });
+if (!r.ok) { console.error(`blaze move failed:\n  ${r.errors.join("\n  ")}`); process.exit(1); }
+
+const cfg = loadConfig({ root: dataRoot });
+const c = commitOrQueue({ root: dataRoot, mode: cfg.commitMode, op: "move", id, message: `${id}: ${r.from} → ${r.to}`, files: [r.fromFile, r.file] });
+if (!c.ok) { console.error(`blaze move: file relocated but commit failed (status ${c.status}) — commit manually`); process.exit(1); }
+console.log(`${id}: ${r.from} → ${r.to}${r.resolution ? ` (resolution: ${r.resolution})` : ""}${c.queued ? " (queued for blaze commit)" : ""}`);

package/scripts/move.mjs

@@ -0,0 +1,56 @@
+// scripts/move.mjs — `blaze move <id> <status>`: validate the transition, set
+// resolution on terminal entry, rewrite frontmatter, and relocate the ticket file
+// between status directories. applyMove() is pure-ish (fs only, no git) for tests;
+// the CLI wrapper adds git add/commit.
+import { writeFileSync, renameSync, mkdirSync } from "node:fs";
+import { join, dirname, basename } from "node:path";
+import { walkTickets } from "./model/index.mjs";
+import { serializeTicket } from "./model/ticket.mjs";
+import { planMove } from "./model/move-plan.mjs";
+import { loadProject } from "./config.mjs";
+
+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))); // projects/<KEY>/<status>/<file>
+    if (id.startsWith(`${projectKey}-`)) return t; // canonical: id prefix matches project dir
+    fallback ??= t;
+  }
+  return fallback;
+}
+
+export function applyMove(projectsDir, id, toStatus, opts = {}) {
+  const { today = null } = opts;
+  const found = locate(projectsDir, id);
+  if (!found) return { ok: false, errors: [`ticket not found: ${id}`] };
+
+  // requireWorklog: explicit opt wins; otherwise read the ticket's project config.
+  let requireWorklog = opts.requireWorklog;
+  if (requireWorklog === undefined) {
+    try {
+      const proj = loadProject(found.frontmatter.project, { root: dirname(projectsDir), projectsDir });
+      requireWorklog = proj.requireWorklogBeforeTerminal;
+    } catch { requireWorklog = false; }
+  }
+
+  const hasWorklog = Array.isArray(found.frontmatter.worklog) && found.frontmatter.worklog.length > 0;
+  const plan = planMove({ frontmatter: found.frontmatter, body: found.body }, found.status, toStatus,
+    { hasWorklog, requireWorklog });
+  if (!plan.ok) return { ok: false, errors: plan.errors };
+
+  const fm = { ...plan.frontmatter };
+  if (today) fm.updated = today;
+  const text = serializeTicket({ frontmatter: fm, body: plan.body });
+
+  // project key = the directory two levels up from the file (projects/<KEY>/<status>/file)
+  const statusDir = dirname(found.file);
+  const projectDir = dirname(statusDir);
+  const destDir = join(projectDir, toStatus);
+  const destFile = join(destDir, basename(found.file));
+  mkdirSync(destDir, { recursive: true });
+  writeFileSync(found.file, text);
+  if (destFile !== found.file) renameSync(found.file, destFile);
+
+  return { ok: true, id, from: found.status, to: toStatus, fromFile: found.file, file: destFile, resolution: plan.resolution };
+}

package/scripts/new-runner.mjs

@@ -0,0 +1,43 @@
+// scripts/new-runner.mjs — CLI entry for `blaze new`. Parses flags, calls
+// applyNew against the resolved data tree, then commits (or queues) the ticket.
+import { applyNew } from "./new.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 = { priority: "medium", labels: [], extra: {} };
+const positional = [];
+for (let i = 0; i < argv.length; i++) {
+  const a = argv[i];
+  switch (a) {
+    case "--project":  opts.project = argv[++i]; break;
+    case "--type":     opts.type = argv[++i]; break;
+    case "--priority": opts.priority = argv[++i]; break;
+    case "--labels":   opts.labels = argv[++i].split(",").map((s) => s.trim()).filter(Boolean); break;
+    case "--estimate": opts.extra.estimate = Number(argv[++i]); break;
+    case "--parent":   opts.extra.parent = argv[++i]; break;
+    case "--assignee": opts.extra.assignee = argv[++i]; break;
+    case "--likelihood": opts.extra.likelihood = argv[++i]; break;
+    case "--impact":   opts.extra.impact = argv[++i]; break;
+    default:
+      if (a.startsWith("--")) { console.error(`unknown flag: ${a}`); process.exit(1); }
+      positional.push(a);
+  }
+}
+opts.title = positional.join(" ");
+opts.today = new Date().toISOString().slice(0, 10);
+
+if (!opts.project || !opts.type || !opts.title) {
+  console.error('usage: blaze new --project <KEY> --type <type> "<title>" [--priority p] [--labels a,b] [--estimate m] [--parent ID]');
+  process.exit(1);
+}
+
+const r = applyNew(projectsDir, opts);
+if (!r.ok) { console.error(`blaze new failed:\n  ${r.errors.join("\n  ")}`); process.exit(1); }
+
+const cfg = loadConfig({ root: dataRoot });
+const c = commitOrQueue({ root: dataRoot, mode: cfg.commitMode, op: "new", id: r.id, message: `${r.id}: create ${r.type}`, files: [r.file] });
+if (!c.ok) { console.error(`blaze new: file written but commit failed (status ${c.status}) — commit manually`); process.exit(1); }
+console.log(`created ${r.id} → ${r.file}${c.queued ? " (queued for blaze commit)" : ""}`);

package/scripts/new.mjs

@@ -0,0 +1,54 @@
+// scripts/new.mjs — `blaze new`: allocate the next per-project id, build a
+// schema-correct ticket, validate it, and write it into the type's initial
+// status dir. Pure-fs (no git); the CLI wrapper adds the commit.
+import { writeFileSync, mkdirSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { nextId } from "./model/ids.mjs";
+import { isType } from "./model/schema.mjs";
+import { initialStatus } from "./model/workflows.mjs";
+import { serializeTicket } from "./model/ticket.mjs";
+import { validateTicket } from "./model/rules.mjs";
+import { roundEstimate } from "./model/time.mjs";
+
+function slugify(s) {
+  return String(s).toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+}
+
+export function applyNew(projectsDir, opts = {}) {
+  const { project, type, title, priority = "medium", labels = [], today = null, extra = {} } = opts;
+  const pre = [];
+  if (!project) pre.push("missing project (use --project <KEY>)");
+  if (!isType(type)) pre.push(`unknown or missing type: ${type}`);
+  if (!title) pre.push("missing title");
+  if (pre.length) return { ok: false, errors: pre };
+
+  const id = nextId(projectsDir, project);
+  const status = initialStatus(type);
+  const frontmatter = {
+    id, title, type, project, priority,
+    resolution: null,
+    parent: extra.parent ?? null,
+    assignee: extra.assignee ?? "unassigned",
+    labels, components: extra.components ?? [],
+    estimate: roundEstimate(extra.estimate),
+    likelihood: extra.likelihood ?? undefined,
+    impact: extra.impact ?? undefined,
+    created: today, updated: today,
+  };
+  // Drop undefined risk-only keys so they don't serialize for non-risk types.
+  if (frontmatter.likelihood === undefined) delete frontmatter.likelihood;
+  if (frontmatter.impact === undefined) delete frontmatter.impact;
+
+  const body = "## Context\n\n## Acceptance Criteria\n\n- [ ] \n\n## Notes\n";
+  // Validate everything except parent-existence (parent integrity is a reindex
+  // concern; at create time the parent may legitimately be created later).
+  const errors = validateTicket({ frontmatter, body }).filter((e) => !/parent not found/.test(e));
+  if (errors.length) return { ok: false, errors };
+
+  const dir = join(projectsDir, project, status);
+  mkdirSync(dir, { recursive: true });
+  const file = join(dir, `${id}-${slugify(title)}.md`);
+  if (existsSync(file)) return { ok: false, errors: [`refusing to overwrite ${file}`] };
+  writeFileSync(file, serializeTicket({ frontmatter, body }));
+  return { ok: true, id, type, project, status, file };
+}

package/scripts/pending-ledger.mjs

@@ -0,0 +1,36 @@
+// scripts/pending-ledger.mjs — append-only JSONL ledger of pending board ops
+// for batch commit mode. Lives in .blaze/ (gitignored); drained by `blaze commit`.
+import { appendFileSync, readFileSync, writeFileSync, existsSync, mkdirSync } from "node:fs";
+import { join, dirname } from "node:path";
+
+export function ledgerPath(root) {
+  return join(root, ".blaze", "pending-commit.jsonl");
+}
+
+export function appendEntry(root, entry) {
+  const path = ledgerPath(root);
+  mkdirSync(dirname(path), { recursive: true });
+  appendFileSync(path, JSON.stringify(entry) + "\n"); // append-mode: atomic for the small single-line writes this ledger produces
+}
+
+export function readEntries(root) {
+  const path = ledgerPath(root);
+  if (!existsSync(path)) return [];
+  const out = [];
+  for (const line of readFileSync(path, "utf8").split("\n")) {
+    if (line.trim() === "") continue;
+    try {
+      out.push(JSON.parse(line));
+    } catch {
+      // A partial final line (process killed mid-append) or a corrupt line:
+      // skip rather than throw so a good ledger still drains. Warn so the drop is visible.
+      process.stderr.write("blaze: skipping unparseable pending-commit ledger line\n");
+    }
+  }
+  return out;
+}
+
+export function clearLedger(root) {
+  const path = ledgerPath(root);
+  if (existsSync(path)) writeFileSync(path, "");
+}

package/scripts/reconcile.mjs

@@ -0,0 +1,181 @@
+#!/usr/bin/env node
+// reconcile.mjs — make the board mirror git/PR state across every project and
+// every repo a project spans. Git is the source of truth; the board is a live
+// mirror. The join key is the <KEY>-<n> in each branch/PR head ref, resolved
+// per project. (Phase-3 design §3.)
+//
+//   node scripts/reconcile.mjs            # dry-run: print would-be moves (default)
+//   node scripts/reconcile.mjs --apply    # commit locally (never pushes)
+//   node scripts/reconcile.mjs --fetch    # fetch from remotes before reconciling
+//   node scripts/reconcile.mjs --quiet    # print only on change
+//
+// Only DELIVERY-workflow types (epic/story/task/bug) mirror git state; goal/risk
+// are manual. A ticket with no branch and no PR is never touched. Terminal status
+// is sticky (a done ticket stays done). With no projects configured, it's a no-op.
+//
+// Zero dependencies — Node built-ins + shelling to `git`/`gh`.
+
+import { execFileSync } from "node:child_process";
+import { writeFileSync, renameSync, mkdirSync, existsSync } from "node:fs";
+import { join, dirname, basename } from "node:path";
+import { fileURLToPath } from "node:url";
+import { loadConfig, listProjects, loadProject, resolveRoots } from "./config.mjs";
+import { walkTickets } from "./model/index.mjs";
+import { serializeTicket } from "./model/ticket.mjs";
+import { isType, workflowFor } from "./model/schema.mjs";
+import { isTerminal, resolutionForTerminal } from "./model/workflows.mjs";
+
+const PR_RANK = { MERGED: 3, OPEN: 2, CLOSED: 1 };
+
+function sh(cmd, args, opts = {}) {
+  try {
+    return execFileSync(cmd, args, {
+      encoding: "utf8", stdio: ["ignore", "pipe", "ignore"],
+      maxBuffer: 64 * 1024 * 1024, ...opts,
+    }).trim();
+  } catch { return null; }
+}
+
+// --- pure decision: git signal + current status + type → target status --------
+export function decide({ pr, branch }, currentStatus, type) {
+  // Only delivery-workflow types mirror git state; goal/risk stay manual.
+  if (!isType(type) || workflowFor(type) !== "delivery") {
+    return { target: currentStatus, branchVal: null, prVal: null, moved: false, skip: true, resolution: undefined };
+  }
+  let target, branchVal = null, prVal = null;
+  if (pr) {
+    // Delivery workflow middle statuses ("in-review"/"in-progress") are intentional literals here;
+    // this function is already delivery-guarded above, so there's no need to re-derive them from rules.
+    target = pr.state === "MERGED" ? "done" : pr.state === "OPEN" ? "in-review" : "in-progress";
+    branchVal = pr.headRefName;
+    prVal = `#${pr.number} — ${pr.url}`;
+  } else if (branch) {
+    target = "in-progress";
+    branchVal = branch;
+  } else {
+    return { target: currentStatus, branchVal: null, prVal: null, moved: false, skip: true, resolution: undefined };
+  }
+  // Terminal-sticky: never pull a ticket out of a terminal status automatically.
+  if (isTerminal(type, currentStatus)) target = currentStatus;
+  const moved = target !== currentStatus;
+  const resolution = isTerminal(type, target) ? resolutionForTerminal(type, target) : undefined;
+  return { target, branchVal, prVal, moved, skip: false, resolution };
+}
+
+// --- gather one repo's PR + branch signal, keyed by a project's idFromRef ------
+function gatherRepo(repoPath, idFromRef, { fetch }) {
+  const empty = { prMap: new Map(), branchMap: new Map() };
+  if (!existsSync(repoPath) || !existsSync(join(repoPath, ".git"))) return empty;
+  if (fetch) sh("git", ["-C", repoPath, "fetch", "--prune", "--quiet"], { timeout: 30000 });
+
+  const prMap = new Map();
+  const prJson = sh("gh", ["pr", "list", "--state", "all", "--limit", "1000",
+    "--json", "number,url,headRefName,state"], { cwd: repoPath });
+  for (const pr of JSON.parse(prJson || "[]")) {
+    const id = idFromRef(pr.headRefName);
+    if (!id) continue;
+    const cur = prMap.get(id);
+    const better = !cur || (PR_RANK[pr.state] || 0) > (PR_RANK[cur.state] || 0) ||
+      ((PR_RANK[pr.state] || 0) === (PR_RANK[cur.state] || 0) && pr.number > cur.number);
+    if (better) prMap.set(id, pr);
+  }
+
+  const branchMap = new Map();
+  const refs = sh("git", ["-C", repoPath, "for-each-ref", "--format=%(refname:short)",
+    "refs/heads", "refs/remotes/origin"]) || "";
+  for (let ref of refs.split("\n")) {
+    ref = ref.replace(/^origin\//, "").trim();
+    if (!ref || ref === "HEAD") continue;
+    const id = idFromRef(ref);
+    if (id && !branchMap.has(id)) branchMap.set(id, ref);
+  }
+  return { prMap, branchMap };
+}
+
+// --- aggregate the most-advanced signal across all of a project's repos -------
+function gatherProject(project, { fetch }) {
+  const prMap = new Map(), branchMap = new Map();
+  for (const repo of project.codeRepoPaths) {
+    const r = gatherRepo(repo, project.idFromRef, { fetch });
+    for (const [id, pr] of r.prMap) {
+      const cur = prMap.get(id);
+      if (!cur || (PR_RANK[pr.state] || 0) > (PR_RANK[cur.state] || 0)) prMap.set(id, pr);
+    }
+    for (const [id, b] of r.branchMap) if (!branchMap.has(id)) branchMap.set(id, b);
+  }
+  return { prMap, branchMap };
+}
+
+// --- the reconcile pass -------------------------------------------------------
+export function reconcile({
+  fetch = false, commit = false, push = false, dryRun = true, root, projectsDir,
+} = {}) {
+  // root left unset → honour BOTH resolved values (dataRoot + projectsDir, even
+  // when custom-named via BLAZE_PROJECTS_DIR). An explicit root (existing
+  // callers/tests) keeps the pre-existing join(root, "projects") behaviour.
+  const explicitRoot = root !== undefined;
+  const resolved = resolveRoots();
+  root ??= resolved.dataRoot;
+  projectsDir ??= explicitRoot ? join(root, "projects") : resolved.projectsDir;
+
+  const today = new Date().toISOString().slice(0, 10);
+  const cfg = loadConfig({ root });
+  const keys = listProjects(cfg);
+  if (!keys.length) return { ok: true, standalone: true, changes: [], committed: false, pushed: false };
+
+  const sig = new Map();
+  for (const key of keys) sig.set(key, gatherProject(loadProject(key, { root, projectsDir }), { fetch }));
+
+  const changes = [];
+  for (const t of walkTickets(projectsDir)) {
+    const type = t.frontmatter.type;
+    const s = sig.get(t.frontmatter.project);
+    if (!s) continue;
+    const d = decide({ pr: s.prMap.get(t.frontmatter.id), branch: s.branchMap.get(t.frontmatter.id) }, t.status, type);
+    if (d.skip) continue;
+
+    const fm = { ...t.frontmatter };
+    let dirty = false;
+    if (d.branchVal && fm.branch !== d.branchVal) { fm.branch = d.branchVal; dirty = true; }
+    if (d.prVal && fm.pr !== d.prVal) { fm.pr = d.prVal; dirty = true; }
+    if (d.resolution !== undefined && fm.resolution !== d.resolution) { fm.resolution = d.resolution; dirty = true; }
+    if (d.moved) { fm.updated = today; dirty = true; }
+    if (!dirty) continue;
+
+    // Always record the would-be change; only write files when not a dry-run
+    changes.push({ id: t.frontmatter.id, from: t.status, to: d.target, moved: d.moved });
+
+    if (!dryRun) {
+      writeFileSync(t.file, serializeTicket({ frontmatter: fm, body: t.body }));
+      if (d.moved) {
+        const projectDir = dirname(dirname(t.file));
+        const destDir = join(projectDir, d.target);
+        mkdirSync(destDir, { recursive: true });
+        const dest = join(destDir, basename(t.file));
+        if (dest !== t.file) renameSync(t.file, dest);
+      }
+    }
+  }
+
+  let committed = false;
+  if (!dryRun && commit && changes.length) {
+    sh("git", ["-C", root, "add", "-A"]);
+    committed = sh("git", ["-C", root, "commit", "-m",
+      `chore(board): reconcile ${changes.length} ticket(s) to git state`]) !== null;
+  }
+  // push is never performed — hardcoded false regardless of the push param
+  return { ok: true, changes, committed, pushed: false };
+}
+
+// --- CLI ----------------------------------------------------------------------
+if (process.argv[1] && process.argv[1] === fileURLToPath(import.meta.url)) {
+  const args = process.argv.slice(2);
+  const apply = args.includes("--apply");
+  const quiet = args.includes("--quiet");
+  const r = reconcile({ fetch: args.includes("--fetch"), commit: apply, push: false, dryRun: !apply });
+  if (!r.ok) { console.error(`reconcile: ${r.error}`); process.exit(1); }
+  if (r.standalone) { if (!quiet) console.log("reconcile: no projects configured — nothing to reconcile."); process.exit(0); }
+  if (!r.changes.length) { if (!quiet) console.log("reconcile: already in sync — nothing to do."); process.exit(0); }
+  for (const c of r.changes) console.log(`${apply ? "moved" : "would move"} ${c.id}: ${c.from} → ${c.to}`);
+  if (!apply) console.log(`(dry-run: ${r.changes.length} change(s); rerun with --apply to write locally — reconcile never pushes)`);
+}

package/scripts/reindex.mjs

@@ -0,0 +1,22 @@
+// scripts/reindex.mjs — rebuild the derived index from projects/ markdown and
+// cache it to .blaze/index.json. Run: node scripts/reindex.mjs [projectsDir]
+import { mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { buildIndex } from "./model/index.mjs";
+import { resolveRoots } from "./config.mjs";
+
+const { dataRoot, projectsDir: defaultProjectsDir } = resolveRoots();
+const projectsDir = process.argv[2] || defaultProjectsDir;
+const dbDir = process.env.BLAZE_DB_DIR || join(dataRoot, ".blaze");
+
+try {
+  mkdirSync(dbDir, { recursive: true });
+  const idx = buildIndex(projectsDir);
+  const out = join(dbDir, "index.json");
+  writeFileSync(out, JSON.stringify(idx.toJSON(), null, 2));
+  const c = idx.count();
+  console.log(`indexed ${c} ticket${c === 1 ? "" : "s"} → ${out}`);
+} catch (e) {
+  console.error(`blaze reindex failed: ${e.message}`);
+  process.exit(1);
+}

package/scripts/resolve-runner.mjs

@@ -0,0 +1,17 @@
+// scripts/resolve-runner.mjs — CLI entry for `blaze resolve <id> <resolution>`.
+import { applyResolve } from "./resolve.mjs";
+import { loadConfig, resolveRoots } from "./config.mjs";
+import { commitOrQueue } from "./commit-or-queue.mjs";
+
+const { dataRoot, projectsDir } = resolveRoots();
+const [id, resolution] = process.argv.slice(2);
+if (!id || !resolution) { console.error("usage: blaze resolve <id> <resolution>"); process.exit(1); }
+
+const today = new Date().toISOString().slice(0, 10);
+const r = applyResolve(projectsDir, id, resolution, { today });
+if (!r.ok) { console.error(`blaze resolve failed:\n  ${r.errors.join("\n  ")}`); process.exit(1); }
+
+const cfg = loadConfig({ root: dataRoot });
+const c = commitOrQueue({ root: dataRoot, mode: cfg.commitMode, op: "resolve", id, message: `${id}: resolution → ${resolution}`, files: [r.file] });
+if (!c.ok) { console.error(`blaze resolve: file updated but commit failed (status ${c.status}) — commit manually`); process.exit(1); }
+console.log(`${id}: resolution → ${resolution}${c.queued ? " (queued for blaze commit)" : ""}`);