@hjr15/blaze-board 0.2.0

package/AGENTS.md

@@ -0,0 +1,141 @@
+# Driving Blaze with an agent
+
+Blaze is a file-based issue tracker. **A ticket's status is the directory it sits
+in** — `projects/<KEY>/<status>/<KEY>-<n>-slug.md` — there is no `status:` field, so
+it cannot drift. Any coding agent can drive it with ordinary file tools (`ls`,
+`grep`, `git mv`), or with the `blaze` CLI, which is the recommended path since it
+validates every write against the schema below and commits scoped to the files it
+touched.
+
+## Types & workflow
+
+Every ticket has a `type`. Each type follows one of three workflows — its own
+sequence of statuses:
+
+| Type | Parent | Required fields | Workflow | Statuses (initial → terminal) |
+|---|---|---|---|---|
+| `goal` | — | title, description | `goal` | `defined → in-progress → achieved` |
+| `epic` | goal | title, description | `delivery` | `defined → in-progress → in-review → done` |
+| `story` / `task` / `bug` | epic | title, description, **estimate** | `delivery` | `defined → in-progress → in-review → done` |
+| `subtask` | story/task/bug | title, description | `delivery` | `defined → in-progress → in-review → done` |
+| `risk` | goal or epic | title, description, likelihood, impact | `risk` | `identified → mitigated` / `accepted` / `obsolete` |
+
+A terminal move auto-sets `resolution` (`done` for `achieved`/`done`/`mitigated`/
+`accepted`; `wont-do` for `obsolete`). Use `blaze resolve <id> <resolution>` for a
+non-default resolution (`wont-do`, `duplicate`, `cannot-reproduce`) without moving
+the file. These are the engine's **defaults**, defined once in
+`scripts/model/schema.mjs` / `workflows.mjs`. A project's `project.json` can carry
+a `workflowOverrides` field reserved for future per-project workflow
+customisation (see Configuration below) — it is not yet consumed by the engine,
+so every project uses the table above unconditionally today.
+
+## The loop
+
+1. **Create**: `blaze new --project <KEY> --type <type> "<title>" [--estimate m]
+   [--parent ID]`. It lands in the type's initial status (`defined` or
+   `identified`).
+2. **You** move it forward by hand — `blaze move <id> <status>` — when you commit
+   to working it (intent is a human/agent decision, not automatic).
+3. If the project has a `codeRepos` entry, `blaze reconcile` takes over for
+   **delivery-workflow tickets only** (epic/story/task/bug/subtask): a branch
+   embedding the ticket's key moves it to `in-progress`; opening its PR moves it to
+   `in-review`; merging moves it to `done`. Goals and risks are always manual.
+   Never hand-move a delivery ticket through the reconcile-owned statuses once a
+   branch/PR exists for it — let reconcile own it.
+
+## The join key
+
+The only coupling between the tracker and code is the branch name: it must embed
+`<KEY>-<n>`, e.g. `KEY-12-add-export`. `reconcile` greps `KEY-12` out of every
+branch/PR head ref in the project's `codeRepos` and matches it to
+`projects/KEY/*/KEY-12-*.md`. No API, no webhook, no stored id.
+
+## Frontmatter
+
+Field order as written by the engine: `id`, `title`, `type`, `project`,
+`priority`, `resolution`, `parent`, `assignee`, `labels`, `components`,
+`estimate`, `worklog`, `links`, `likelihood`, `impact`, `branch`, `pr`, `created`,
+`updated`.
+
+- `id` — `<KEY>-<n>`, matches the filename, sequential, never reused.
+- `priority` — one of `highest`/`high`/`medium`/`low`/`lowest`/`none`/`urgent`.
+- `resolution` — `null` until terminal; one of `done`/`wont-do`/`duplicate`/
+  `cannot-reproduce`.
+- `parent` — another ticket's `id`; must satisfy the parent-type rule in the table
+  above (validated, including cycle detection).
+- `labels` / `components` — free-form; keep to whatever taxonomy the project sets
+  in `project.json` (`defaultLabels` in `blaze.config.json` is the tracker-wide
+  fallback).
+- `estimate` — minutes, rounded to the nearest 5 (`blaze new --estimate`).
+- `worklog` — list of `{ date, minutes, note? }`, appended by `blaze log`; minutes
+  round to the nearest whole minute.
+- `likelihood` / `impact` — risk-only fields.
+- `branch` / `pr` — filled by `reconcile`; don't hand-edit.
+
+## Data-root ladder
+
+The engine (this install) and the data (`blaze.config.json` + `projects/` + the git
+history tickets commit into) can live in different trees. Every command resolves
+roots the same way:
+
+1. `BLAZE_PROJECTS_DIR` env — an explicit `projects/` directory; the data root is
+   its parent.
+2. `./projects` under the current working directory — running from inside the
+   data repo.
+3. The engine tree itself — single-tree back-compat only, and **only when the
+   engine isn't installed under `node_modules`**. For a global/npx install
+   (the normal packaged case), if neither rung 1 nor 2 matched, `resolveRoots`
+   throws `blaze: no data dir found — set BLAZE_PROJECTS_DIR or run from a
+   directory containing projects/` instead of silently falling back to the
+   engine's own tree.
+
+## Commit modes
+
+`blaze.config.json`'s `commitMode` decides how CLI verbs commit:
+
+- `per-op` (default) — each `new`/`move`/`log`/`resolve`/`edit` commits immediately,
+  scoped to exactly the file(s) it touched (never a broad `git add -A`).
+- `batch` — the op is appended to `.blaze/pending-commit.jsonl` instead; run
+  `blaze commit` to flush everything queued into one commit (subject = a per-op
+  count summary, body = one line per queued op).
+
+## Querying the board
+
+```bash
+for s in defined in-progress in-review; do echo "## $s"; ls projects/*/$s/*.md 2>/dev/null; done
+grep -rl '^priority: urgent' --include='*.md' projects/
+blaze rollup            # every goal/epic's rolled-up estimate + logged time
+blaze rollup KEY-12      # one ticket's own vs. rolled totals, with child breakdown
+```
+
+## Grooming rules
+
+When grooming a freshly-captured ticket (in its type's initial status), make these
+and only these edits to its `.md` file, then stop:
+
+- **Type & priority**: set `type` and `priority` from the ticket's content.
+- **Labels**: add labels from the project's configured taxonomy that match the
+  area/intent. Do not invent new labels.
+- **Acceptance criteria**: if the `## Acceptance Criteria` list is empty or a
+  placeholder, draft 2–4 concrete, testable checkboxes from the context.
+- **Duplicates**: if the ticket clearly duplicates another, note it in `## Notes`
+  pointing at the surviving id (do not move or delete it — that stays a human
+  decision).
+- **Links**: in `## Notes`, link closely related tickets by id.
+
+Bump `updated:` to today on any edit. Never touch `id`, never change the
+directory, never edit code or any file outside the tracker.
+
+## Configuration
+
+`blaze.config.json` (data-repo root): `key`, `projects` (array of project keys the
+board renders), `commitMode`, `port`, and more.
+
+`projects/<KEY>/project.json` (optional, per project): `labels`, `components`,
+`codeRepos` (repos `reconcile` mirrors for this project),
+`requireWorklogBeforeTerminal` (default `false` — when `true`, a leaf ticket
+(story/task/bug/subtask) needs at least one `worklog` entry before it can enter a
+terminal status; epics/goals/risks are exempt since their time rolls up from
+children), and `workflowOverrides` (reserved for a future per-type
+statuses/transitions override — currently stored but not read by the engine, so
+it has no effect yet).

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jordan Lyons
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,111 @@
+<p align="center">
+  <img src="brand/readme_graphic.jpg" alt="Blaze" width="420">
+</p>
+
+<p align="center"><b>Agentic AI for App Development</b><br>
+A file-based, git-native issue tracker built for AI coding agents to drive.</p>
+
+---
+
+Blaze is plain files, all the way down:
+
+- **A ticket is a markdown file** — frontmatter + a body. No database, no login.
+- **A ticket's status is the directory it sits in.** There is no `status:` field, so
+  it cannot drift out of sync with reality.
+- **Git is the history.** `git log --follow` on a ticket file is its full audit trail;
+  every mutation is a small, revertable commit.
+- **The board is a rendering, never a second source of truth** — `blaze board` reads
+  the same files you'd `ls` / `grep` / `git mv` by hand.
+
+It's built AI-first: an agent drives the tracker with the file tools it already has,
+or with the `blaze` CLI. No API client, no auth, no SDK required either way.
+
+## Install
+
+```bash
+npm i -g @hjr15/blaze-board
+# or, without installing:
+npx @hjr15/blaze-board <command>
+```
+
+Requires Node 20+ and `git` on `PATH`.
+
+## The engine ⟂ data split
+
+This package is the **engine** — the `blaze` CLI and its web board. Your tickets
+live in a separate **data repo**: a `blaze.config.json` plus a
+`projects/<KEY>/<status>/` tree, versioned in its own git history.
+
+Attach the engine to a data repo one of two ways:
+
+- run `blaze` from inside the data repo (it looks for a `projects/` directory in
+  the current working directory), **or**
+- set `BLAZE_PROJECTS_DIR` to the data repo's `projects/` directory, from anywhere.
+
+One global `npm i -g @hjr15/blaze-board` install can drive any number of unrelated
+data repos this way — upgrade the engine once, keep every board's ticket history in
+its own repo.
+
+## Quickstart
+
+```bash
+# 1. a data repo — just a directory with its own git history
+mkdir my-tracker && cd my-tracker && git init
+
+# 2. the engine needs a key and at least one project
+mkdir -p projects/ENG
+cat > blaze.config.json <<'EOF'
+{ "key": "ENG", "projects": ["ENG"] }
+EOF
+git add -A && git commit -m "init board"
+
+# 3. create a ticket — task/story/bug require --estimate; every type gets a
+#    scaffolded description body
+blaze new --project ENG --type task "Fix the export bug" --estimate 30
+
+# 4. open the board
+blaze board   # → http://localhost:4321
+```
+
+`blaze new` writes the ticket, validates it against the schema, and commits it — one
+small commit per ticket, scoped to the files it actually touched.
+
+## CLI verbs
+
+| Command | Does |
+|---|---|
+| `blaze new --project <KEY> --type <type> "<title>" [--estimate m] [--parent ID] [--priority p] [--labels a,b]` | Create a ticket in its type's initial status |
+| `blaze move <id> <status>` | Change status (validates the transition; auto-sets `resolution` on a terminal status) |
+| `blaze resolve <id> <done\|wont-do\|duplicate\|cannot-reproduce>` | Set a non-default resolution without moving the file |
+| `blaze log <id> <minutes>` | Append a worklog entry |
+| `blaze rollup [<id>]` | Print rolled-up estimate/logged time for one node, or a summary of every goal/epic |
+| `blaze reconcile [--apply] [--fetch]` | Mirror a linked code repo's branch/PR state onto delivery-workflow tickets (dry-run by default) |
+| `blaze edit <id> ...` | Edit ticket fields |
+| `blaze reindex` | Rebuild/validate the on-disk index |
+| `blaze commit` | Flush queued ops into one commit (`commitMode: batch`) |
+| `blaze migrate [--dry-run\|--live] [--project <KEY>]` | Import tickets from an external tracker via a reviewed disposition ledger (`--project` optional — falls back to `blaze.config.json`'s `projects` list) |
+| `blaze board` | Serve the read-only kanban view |
+
+See [`AGENTS.md`](AGENTS.md) for the full contract — types, workflows, the git join
+key, and how an agent should drive the board.
+
+## Configuration
+
+`blaze.config.json` lives at the data repo's root. Minimally:
+
+```json
+{ "key": "ENG", "projects": ["ENG"] }
+```
+
+`key` is the ticket id prefix (`ENG-1`, `ENG-2`, ...); `projects` lists which
+`projects/<KEY>/` directories the board renders. Per-project settings (labels,
+`codeRepos` to mirror, `requireWorklogBeforeTerminal`, `workflowOverrides`) live in
+`projects/<KEY>/project.json` — see [`AGENTS.md`](AGENTS.md#configuration).
+
+## Origin
+
+This is a public continuation of [`sychyoboN/blaze`](https://github.com/sychyoboN/blaze).
+
+## License
+
+MIT.

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@hjr15/blaze-board",
+  "version": "0.2.0",
+  "description": "A file-based, git-native issue board that AI coding agents can drive. Tickets are markdown; status is the directory.",
+  "type": "module",
+  "bin": {
+    "blaze": "scripts/cli.mjs"
+  },
+  "files": [
+    "scripts/",
+    "AGENTS.md",
+    "LICENSE",
+    "README.md"
+  ],
+  "scripts": {
+    "start": "node scripts/supervisor.mjs",
+    "board": "node scripts/serve.mjs",
+    "reconcile": "node scripts/reconcile.mjs",
+    "groom": "node scripts/loops/groomer.mjs",
+    "commit": "node scripts/commit-runner.mjs",
+    "test": "node --test",
+    "test:coverage": "c8 node --test --test-concurrency=1"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hjr15/blaze.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT",
+  "devDependencies": {
+    "c8": "11.0.0"
+  }
+}

package/scripts/cli.mjs

@@ -0,0 +1,31 @@
+#!/usr/bin/env node
+// cli.mjs — the `blaze` command. Dispatches to the scripts.
+import { spawnSync } from "node:child_process";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const here = dirname(fileURLToPath(import.meta.url));
+const [cmd, ...rest] = process.argv.slice(2);
+const node = (file, args = []) => spawnSync(process.execPath, [join(here, file), ...args], { stdio: "inherit" });
+
+let r;
+switch (cmd) {
+  case undefined:
+  case "start": r = node("supervisor.mjs"); break;
+  case "board": r = node("serve.mjs"); break;
+  case "reconcile": r = node("reconcile.mjs", rest); break;
+  case "groom": r = node("loops/groomer.mjs", rest); break;
+  case "new": r = node("new-runner.mjs", rest); break;
+  case "reindex": r = node("reindex.mjs", rest); break;
+  case "move": r = node("move-runner.mjs", rest); break;
+  case "edit": r = node("edit-runner.mjs", rest); break;
+  case "resolve": r = node("resolve-runner.mjs", rest); break;
+  case "log": r = node("log-runner.mjs", rest); break;
+  case "commit": r = node("commit-runner.mjs", rest); break;
+  case "rollup": r = node("rollup-runner.mjs", rest); break;
+  case "migrate": r = node("migrate-runner.mjs", rest); break;
+  default:
+    console.log("usage: blaze [start|board|reconcile|groom|new|reindex|move|edit|resolve|log|commit|rollup|migrate]");
+    process.exit(1);
+}
+process.exit(r.status ?? 0);

package/scripts/commit-or-queue.mjs

@@ -0,0 +1,22 @@
+// scripts/commit-or-queue.mjs — single decision point for board-mutating CLI
+// verbs: in `batch` mode queue the op onto the pending ledger; otherwise commit
+// scoped to exactly the touched files (never `git add -A`).
+import { relative } from "node:path";
+import { commitFile } from "./serve-commit.mjs";
+import { appendEntry } from "./pending-ledger.mjs";
+
+export function commitOrQueue({ root, mode, op, id, message, files }) {
+  const unique = [...new Set(files)];
+  if (mode === "batch") {
+    appendEntry(root, {
+      id,
+      op,
+      message,
+      files: unique.map((f) => relative(root, f)),
+      ts: new Date().toISOString(),
+    });
+    return { ok: true, queued: true };
+  }
+  const [first, ...rest] = unique;
+  return commitFile(root, first, message, rest);
+}

package/scripts/commit-runner.mjs

@@ -0,0 +1,40 @@
+// scripts/commit-runner.mjs — `blaze commit`: drain .blaze/pending-commit.jsonl
+// into ONE commit (subject summary + per-op body), staging only recorded files.
+import { spawnSync } from "node:child_process";
+import { readEntries, clearLedger } from "./pending-ledger.mjs";
+import { resolveRoots } from "./config.mjs";
+
+const { dataRoot } = resolveRoots();
+
+const entries = readEntries(dataRoot);
+if (entries.length === 0) {
+  console.log("blaze commit: nothing to flush");
+  process.exit(0);
+}
+
+// Counts by op → "2 new, 3 logged, 1 moved, 1 resolved"
+const LABEL = { new: "new", log: "logged", move: "moved", resolve: "resolved" };
+const counts = {};
+for (const e of entries) counts[e.op] = (counts[e.op] || 0) + 1;
+const summary = Object.entries(counts)
+  .map(([op, n]) => `${n} ${LABEL[op] || op}`)
+  .join(", ");
+
+const date = new Date().toISOString().slice(0, 10);
+const subject = `blaze: ${date} board update (${summary})`;
+const body = entries.map((e) => `- ${e.message}`).join("\n");
+
+const files = [...new Set(entries.flatMap((e) => e.files))];
+
+const add = spawnSync("git", ["-C", dataRoot, "add", "--", ...files], { stdio: "ignore" });
+if (add.status !== 0) {
+  console.error(`blaze commit: git add failed (status ${add.status}) — ledger kept, resolve manually`);
+  process.exit(1);
+}
+const commit = spawnSync("git", ["-C", dataRoot, "commit", "-m", subject, "-m", body, "--", ...files], { stdio: "inherit" });
+if (commit.status !== 0) {
+  console.error(`blaze commit: git commit failed (status ${commit.status}) — ledger kept, resolve manually`);
+  process.exit(1);
+}
+clearLedger(dataRoot);
+console.log(`blaze commit: flushed ${entries.length} op(s) → ${subject}`);

package/scripts/config.mjs

@@ -0,0 +1,135 @@
+// config.mjs — load blaze.config.json with defaults + env overrides, and derive
+// the key-based regexes that reconcile.mjs and new-runner.mjs share.
+import { readFileSync, existsSync } from "node:fs";
+import { join, dirname, isAbsolute, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+export const ROOT = join(dirname(fileURLToPath(import.meta.url)), "..");
+
+const DEFAULTS = {
+  key: "TASK",
+  projects: [],
+  codeRepos: [],
+  boardTitle: "Blaze",
+  codeRepo: null,
+  provider: "github",
+  columns: ["backlog", "todo", "in-progress", "in-review", "done", "canceled", "duplicate"],
+  terminal: ["done", "canceled", "duplicate"],
+  defaultLabels: ["frontend", "backend", "infra", "docs", "bug", "chore"],
+  port: 4321,
+  agentCommand: "claude -p",
+  commitMode: "per-op",
+  loops: {
+    reconcile: { enabled: true, intervalSec: 60 },
+    groomer: { enabled: true, intervalSec: 300, columns: ["backlog"] },
+  },
+};
+
+export function loadConfig({ root = ROOT, env = process.env, fileName = "blaze.config.json" } = {}) {
+  const path = join(root, fileName);
+  let file = {};
+  if (existsSync(path)) {
+    try {
+      file = JSON.parse(readFileSync(path, "utf8"));
+    } catch (e) {
+      throw new Error(`blaze: cannot parse ${fileName}: ${e.message}`);
+    }
+  }
+
+  const cfg = { ...DEFAULTS, ...file };
+  cfg.loops = {
+    reconcile: { ...DEFAULTS.loops.reconcile, ...(file.loops && file.loops.reconcile) },
+    groomer: { ...DEFAULTS.loops.groomer, ...(file.loops && file.loops.groomer) },
+  };
+
+  // Env overrides (highest precedence).
+  if (env.BLAZE_KEY) cfg.key = env.BLAZE_KEY;
+  if (env.BLAZE_PORT) cfg.port = Number(env.BLAZE_PORT);
+  if (env.BLAZE_AGENT_COMMAND) cfg.agentCommand = env.BLAZE_AGENT_COMMAND;
+  if (env.BLAZE_COMMIT_MODE) cfg.commitMode = env.BLAZE_COMMIT_MODE;
+  if (env.BLAZE_CODE_REPO !== undefined) cfg.codeRepo = env.BLAZE_CODE_REPO || null;
+
+  // Derived values.
+  cfg.codeRepoPath = cfg.codeRepo
+    ? (isAbsolute(cfg.codeRepo) ? cfg.codeRepo : resolve(root, cfg.codeRepo))
+    : null;
+  cfg.idRegex = new RegExp("\\b" + cfg.key + "-(\\d+)", "i");
+  cfg.idFromRef = (ref) => {
+    const m = cfg.idRegex.exec(ref || "");
+    return m ? `${cfg.key}-${m[1]}` : null;
+  };
+  cfg.fileRegex = new RegExp("^" + cfg.key + "-\\d+.*\\.md$");
+  cfg.idLineRegex = new RegExp(`^id:\\s*(${cfg.key}-\\d+)`, "m");
+
+  return Object.freeze(cfg);
+}
+
+// --- dataRoot resolution -----------------------------------------------------
+// The engine (this install) and the data (blaze.config.json + projects/ +
+// .blaze/ + the git repo commits land in) may live in different trees.
+// Resolution ladder:
+//   1. BLAZE_PROJECTS_DIR env — explicit projects dir; dataRoot is its parent
+//   2. ./projects under CWD — running from a data repo checkout
+//   3. the engine tree itself — single-tree back-compat (pre-split behaviour),
+//      but only when engineRoot isn't under node_modules; a packaged install
+//      with no data dir found throws instead of silently falling back
+export function resolveRoots({ env = process.env, cwd = process.cwd(), engineRoot = ROOT } = {}) {
+  if (env.BLAZE_PROJECTS_DIR) {
+    const projectsDir = resolve(cwd, env.BLAZE_PROJECTS_DIR);
+    return Object.freeze({ engineRoot, dataRoot: dirname(projectsDir), projectsDir });
+  }
+  if (existsSync(join(cwd, "projects"))) {
+    return Object.freeze({ engineRoot, dataRoot: cwd, projectsDir: join(cwd, "projects") });
+  }
+  if (engineRoot.includes("/node_modules/")) {
+    throw new Error("blaze: no data dir found — set BLAZE_PROJECTS_DIR or run from a directory containing projects/");
+  }
+  return Object.freeze({ engineRoot, dataRoot: engineRoot, projectsDir: join(engineRoot, "projects") });
+}
+
+// CLI: `node scripts/config.mjs --get <field>` prints one resolved config field —
+// for scripts/tooling that need a config value directly in shell.
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+  const i = process.argv.indexOf("--get");
+  if (i !== -1) {
+    const cfg = loadConfig({ root: resolveRoots().dataRoot });
+    const v = cfg[process.argv[i + 1]];
+    console.log(v === undefined || v === null ? "" : v);
+  }
+}
+
+// --- multi-project layer (Phase 3) -----------------------------------------
+// The legacy single-board config above is retained as harmless defaults so the
+// existing loops keep loading; the project API below is authoritative for the
+// projects/<KEY>/<status>/ layout.
+import { isAbsolute as _isAbsolute, resolve as _resolve } from "node:path";
+
+const PROJECT_DEFAULTS = {
+  components: [],
+  labels: [],
+  codeRepos: [],
+  requireWorklogBeforeTerminal: false,
+  workflowOverrides: null,
+};
+
+export function listProjects(cfg, { root = ROOT } = {}) {
+  const c = cfg || loadConfig({ root });
+  return Array.isArray(c.projects) ? c.projects.slice() : [];
+}
+
+export function loadProject(key, { root = ROOT, projectsDir = join(root, "projects") } = {}) {
+  const cfg = loadConfig({ root });
+  const path = join(projectsDir, key, "project.json");
+  let file = {};
+  if (existsSync(path)) {
+    try { file = JSON.parse(readFileSync(path, "utf8")); }
+    catch (e) { throw new Error(`blaze: cannot parse projects/${key}/project.json: ${e.message}`); }
+  }
+  const merged = { ...PROJECT_DEFAULTS, ...file, key };
+  const repos = merged.codeRepos.length ? merged.codeRepos : (cfg.codeRepos || []);
+  merged.codeRepoPaths = repos.map((r) => (_isAbsolute(r) ? r : _resolve(root, r)));
+  merged.idRegex = new RegExp("\\b" + key + "-(\\d+)", "i");
+  merged.idFromRef = (ref) => { const m = merged.idRegex.exec(ref || ""); return m ? `${key}-${m[1]}` : null; };
+  merged.fileRegex = new RegExp("^" + key + "-\\d+.*\\.md$");
+  return Object.freeze(merged);
+}

package/scripts/edit-runner.mjs

@@ -0,0 +1,18 @@
+// scripts/edit-runner.mjs — CLI entry for `blaze edit <id> <field> <value>`:
+// applyEdit against the resolved data tree, then commit only the touched file.
+import { applyEdit } from "./edit.mjs";
+import { commitFile } from "./serve-commit.mjs";
+import { resolveRoots } from "./config.mjs";
+
+const { dataRoot, projectsDir } = resolveRoots();
+const [id, field, ...valueParts] = process.argv.slice(2);
+if (!id || !field || valueParts.length === 0) {
+  console.error("usage: blaze edit <id> <field> <value>"); process.exit(1);
+}
+const value = valueParts.join(" ");
+const today = new Date().toISOString().slice(0, 10);
+const r = applyEdit(projectsDir, id, { [field]: value }, { today });
+if (!r.ok) { console.error(`blaze edit failed:\n  ${r.errors.join("\n  ")}`); process.exit(1); }
+const c = commitFile(dataRoot, r.file, `${id}: edit ${field}`);
+if (!c.ok) { console.error(`blaze edit: file written but commit failed (status ${c.status}) — commit manually`); process.exit(1); }
+console.log(`${id}: ${field} = ${value}`);

package/scripts/edit.mjs

@@ -0,0 +1,85 @@
+// scripts/edit.mjs — validated in-place field edits and AC-checkbox toggling.
+// fs-only (no git); the board/CLI wrappers commit. All business rules come from
+// model/ — this file only marshals a patch through validateTicket before writing.
+import { writeFileSync } from "node:fs";
+import { basename, dirname } from "node:path";
+import { walkTickets } from "./model/index.mjs";
+import { serializeTicket } from "./model/ticket.mjs";
+import { validateTicket } from "./model/rules.mjs";
+import { roundEstimate } from "./model/time.mjs";
+
+const EDITABLE = new Set(["assignee", "priority", "labels", "components", "estimate", "parent", "likelihood", "impact"]);
+
+// Same id resolution as move.mjs/log.mjs: prefer the project-dir-matching id.
+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;
+}
+
+function asArray(v) {
+  if (Array.isArray(v)) return v;
+  if (typeof v === "string") return v.split(",").map((s) => s.trim()).filter(Boolean);
+  return v == null ? [] : [v];
+}
+
+export function applyEdit(projectsDir, id, patch, opts = {}) {
+  const { today = null } = opts;
+  const bad = Object.keys(patch).filter((k) => !EDITABLE.has(k));
+  if (bad.length) return { ok: false, errors: [`field(s) not editable: ${bad.join(", ")}`] };
+
+  const found = locate(projectsDir, id);
+  if (!found) return { ok: false, errors: [`ticket not found: ${id}`] };
+
+  const fm = { ...found.frontmatter };
+  for (const [k, v] of Object.entries(patch)) {
+    if (k === "estimate") fm.estimate = roundEstimate(v);
+    else if (k === "labels" || k === "components") fm[k] = asArray(v);
+    else fm[k] = v === "" ? null : v;
+  }
+
+  // Validate the merged ticket. lookup spans every ticket for parent-pair + cycle checks.
+  const all = new Map();
+  for (const t of walkTickets(projectsDir)) all.set(t.frontmatter.id, { frontmatter: t.frontmatter, body: t.body });
+  all.set(id, { frontmatter: fm, body: found.body });
+  const errors = validateTicket({ frontmatter: fm, body: found.body }, (pid) => all.get(pid) || null);
+  if (errors.length) return { ok: false, errors };
+
+  if (today) fm.updated = today;
+  writeFileSync(found.file, serializeTicket({ frontmatter: fm, body: found.body }));
+  return { ok: true, id, file: found.file };
+}
+
+// Flip one checkbox under the `## Acceptance Criteria` heading, by ordinal.
+// Only lines within that section count; a `- [ ]` elsewhere in the body is ignored.
+export function applyToggleAc(projectsDir, id, { index, checked }, opts = {}) {
+  const { today = null } = opts;
+  const found = locate(projectsDir, id);
+  if (!found) return { ok: false, errors: [`ticket not found: ${id}`] };
+
+  const lines = found.body.split("\n");
+  const isHeading = (l) => /^\s{0,3}#{1,6}\s/.test(l);
+  const start = lines.findIndex((l) => /^\s{0,3}#{1,6}\s+acceptance criteria\s*$/i.test(l));
+  if (start === -1) return { ok: false, errors: ["ticket has no ## Acceptance Criteria section"] };
+
+  const acLineIdx = [];
+  for (let i = start + 1; i < lines.length; i++) {
+    if (isHeading(lines[i])) break;                 // next section ends AC
+    if (/^\s*- \[[ xX]\]\s/.test(lines[i])) acLineIdx.push(i);
+  }
+  if (index < 0 || index >= acLineIdx.length) {
+    return { ok: false, errors: [`AC index ${index} out of range (0..${acLineIdx.length - 1})`] };
+  }
+  const li = acLineIdx[index];
+  lines[li] = lines[li].replace(/^(\s*- )\[[ xX]\]/, `$1[${checked ? "x" : " "}]`);
+
+  const fm = { ...found.frontmatter };
+  if (today) fm.updated = today;
+  writeFileSync(found.file, serializeTicket({ frontmatter: fm, body: lines.join("\n") }));
+  return { ok: true, id, file: found.file };
+}

package/scripts/event-bus.mjs

@@ -0,0 +1,16 @@
+// event-bus.mjs — a tiny synchronous in-process pub/sub for the activity feed.
+export function createBus() {
+  const subs = new Set();
+  return {
+    publish(evt) {
+      for (const fn of subs) {
+        try { fn(evt); } catch { /* one bad subscriber must not break the rest */ }
+      }
+    },
+    subscribe(fn) {
+      subs.add(fn);
+      return () => subs.delete(fn);
+    },
+    size() { return subs.size; },
+  };
+}