@jenga-ai/agent 3.1.1 → 3.4.0

package/project/app/api/parsers/git-log.js

@@ -0,0 +1,52 @@
+/**
+ * @file project/app/api/parsers/git-log.js
+ * Reads git log history as an array of commit objects.
+ */
+
+const { execFile } = require('child_process');
+const { resolveProjectRoot } = require('../lib/resolve-project-root');
+
+// Resolved relative to the invoking project's own root (E47_S02_T01/T02), not a fixed __dirname
+// climb — see project/app/api/lib/resolve-project-root.js.
+const REPO_ROOT = resolveProjectRoot();
+const SEP = '|||';
+const FORMAT = `%H${SEP}%an${SEP}%aI${SEP}%s${SEP}%b`;
+
+/**
+ * Run git log and return parsed commit entries.
+ * Returns [] if not a git repo or git is unavailable.
+ * @returns {Promise<Object[]>}
+ */
+function readGitLog() {
+  return new Promise((resolve) => {
+    execFile(
+      'git',
+      ['log', `--format=${FORMAT}`, '--max-count=200'],
+      { cwd: REPO_ROOT, timeout: 10000 },
+      (err, stdout) => {
+        if (err) {
+          // Not a git repo or git unavailable — return empty
+          return resolve([]);
+        }
+        const commits = stdout
+          .split('\n')
+          .filter((line) => line.includes(SEP))
+          .map((line) => {
+            const [sha, author, date, subject, ...bodyParts] = line.split(SEP);
+            return {
+              type: 'git_commit',
+              sha: sha.trim(),
+              author: author.trim(),
+              date: date.trim(),
+              subject: subject.trim(),
+              body: bodyParts.join(SEP).trim(),
+            };
+          })
+          .filter((c) => c.sha);
+        resolve(commits);
+      }
+    );
+  });
+}
+
+module.exports = { readGitLog };

package/project/app/api/parsers/ideas.js

@@ -0,0 +1,62 @@
+/**
+ * @file project/app/api/parsers/ideas.js
+ * Parses project/ideas.md — a single flat file (one idea per line, written by the /idea skill)
+ * with no YAML frontmatter — into entries shaped consistently with the directory-reader entries
+ * from E58_S01_T01, so both can be merged into the same aggregate list.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { resolveProjectRoot } = require('../lib/resolve-project-root');
+
+// Resolved relative to the invoking project's own root (E47_S02_T01/T02), not a fixed __dirname
+// climb — see project/app/api/lib/resolve-project-root.js.
+const IDEAS_FILE = path.join(resolveProjectRoot(), 'project', 'ideas.md');
+
+/**
+ * Determine whether a (trimmed) line should be skipped rather than treated as an idea entry.
+ * Mirrors scripts/idea_manager.sh's `real_entries()` filter — blank lines, markdown headers
+ * (`#`), and HTML comments (`<!--`) are structural/template scaffolding, not idea content.
+ * @param {string} trimmedLine
+ * @returns {boolean}
+ */
+function isSkippableLine(trimmedLine) {
+  return trimmedLine === '' || trimmedLine.startsWith('#') || trimmedLine.startsWith('<!--');
+}
+
+/**
+ * Read project/ideas.md and return one entry per non-blank idea line.
+ * Returns [] if project/ideas.md does not exist (same non-throwing precedent as the other parsers).
+ * @returns {Promise<Object[]>}
+ */
+async function readIdeas() {
+  if (!fs.existsSync(IDEAS_FILE)) return [];
+
+  let raw;
+  try {
+    raw = fs.readFileSync(IDEAS_FILE, 'utf8');
+  } catch (err) {
+    console.warn(`[ideas] Skipping unreadable file: ${IDEAS_FILE} — ${err.message}`);
+    return [];
+  }
+
+  const lines = raw.split('\n');
+  const results = [];
+
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (isSkippableLine(trimmed)) continue;
+
+    results.push({
+      file: 'ideas.md',
+      data: {},
+      content: trimmed,
+      category: 'idea',
+      date: null,
+    });
+  }
+
+  return results;
+}
+
+module.exports = { readIdeas };

package/project/app/api/parsers/knowledge-graph.js

@@ -0,0 +1,73 @@
+/**
+ * @file project/app/api/parsers/knowledge-graph.js
+ * Reads `project/knowledge-graph/graph.json` (E20_S09) and transforms it into the UI-facing
+ * `{nodes:[{id,label,type}], edges:[{from,to,label}]}` shape consumed by the Architecture tab's
+ * SAD map — see `project/knowledge-graph/STUB_SCHEMA.md` for the on-disk node/edge shape this
+ * reads from (id/type/label/description/source/status?/superseded_by? for nodes;
+ * id/from/to/type/description for edges).
+ *
+ * Kept deliberately defensive: the stub schema is explicitly throwaway (pending E20_S01's real
+ * schema), so this reader tolerates a missing file, an empty/malformed file, or unexpected field
+ * shapes by degrading to an empty map rather than throwing.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { resolveProjectRoot } = require('../lib/resolve-project-root');
+
+// Resolved relative to the invoking project's own root, not a fixed __dirname climb — same fix as
+// the other 4 parsers (E47_S02_T01/T02). Not one of the 4 files originally named in E47_S02_T02's
+// scope, but it has the identical defect and directly feeds architecture.js's sad_map field, which
+// the story's own Acceptance Criteria names explicitly ("architecture" data must resolve relative
+// to the invoking project) — see E47_S02_T02-plan.md's "Scope addition" section for the full
+// reasoning.
+const ROOT = resolveProjectRoot();
+const GRAPH_JSON_PATH = path.join(ROOT, 'project/knowledge-graph/graph.json');
+
+/**
+ * Safely read and parse a JSON file, returning null on any error (including a missing file).
+ * @param {string} filePath
+ * @returns {Object|null}
+ */
+function readJsonSafe(filePath) {
+  try {
+    return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Read and transform `project/knowledge-graph/graph.json` into the UI-facing SAD map shape.
+ * `status: superseded` nodes are excluded. Never throws — returns `{ nodes: [], edges: [] }` for
+ * a missing, empty, or malformed graph.json.
+ * @returns {{ nodes: Array<{id: string, label: string, type: string}>, edges: Array<{from: string, to: string, label: string}> }}
+ */
+function readSADMap() {
+  try {
+    const graph = readJsonSafe(GRAPH_JSON_PATH);
+
+    const rawNodes = graph && Array.isArray(graph.nodes) ? graph.nodes : [];
+    const rawEdges = graph && Array.isArray(graph.edges) ? graph.edges : [];
+
+    const nodes = rawNodes
+      .filter((node) => node && node.status !== 'superseded')
+      .map((node) => ({
+        id: node.id,
+        label: node.label,
+        type: node.type,
+      }));
+
+    const edges = rawEdges.map((edge) => ({
+      from: edge.from,
+      to: edge.to,
+      label: edge.description || edge.type,
+    }));
+
+    return { nodes, edges };
+  } catch {
+    return { nodes: [], edges: [] };
+  }
+}
+
+module.exports = { readSADMap };

package/project/app/api/parsers/lib/markdown-dir-reader.js

@@ -0,0 +1,163 @@
+/**
+ * @file project/app/api/parsers/lib/markdown-dir-reader.js
+ * Shared recursive markdown-directory reader with frontmatter parsing and caller-derived
+ * categorization.
+ *
+ * Generalizes two pre-existing, independently-written directory readers in this codebase:
+ *   - `board.js`'s `readMarkdownDir()` — non-recursive, parses frontmatter + content via
+ *     `gray-matter`, but only reads a single flat directory (epics/stories/tasks are each read
+ *     separately).
+ *   - `rapports.js`'s `listMdFiles()` — recursively walks a directory tree, but only collects file
+ *     paths; frontmatter/content extraction happens separately in `readRapports()`.
+ *
+ * This module merges both: a single recursive walk that also parses frontmatter/content per file,
+ * plus a category derived from a mapping supplied by the caller (this module never hardcodes any
+ * category name — different consumers need different taxonomies from the same walk/parse logic).
+ *
+ * ---------------------------------------------------------------------------------------------
+ * RETURN SHAPE CONTRACT (depended on by E58_S01_T03 [rapports.js] and E58_S01_T04
+ * [documentation.js] — do not change without updating both):
+ *
+ *   readMarkdownDirRecursive(rootDir, categorize) -> Array<{
+ *     file: string,     // path relative to rootDir, POSIX-style separators (e.g. "problems/foo.md"
+ *                        // or "foo.md" for a file directly under rootDir). Never an absolute path.
+ *     data: Object,      // gray-matter-parsed frontmatter object (`{}` if the file has none).
+ *     content: string,   // full markdown body, `gray-matter`'s `content` field with leading/
+ *                        // trailing whitespace trimmed (`.trim()`). Never truncated.
+ *     category: string,  // derived via the caller-supplied `categorize` argument — see below.
+ *   }>
+ *
+ * `categorize` contract:
+ *   - May be a function: `(topLevelSegment, relativeFilePath) => string`
+ *       `topLevelSegment` is the first path segment of the file's path relative to `rootDir`
+ *       (e.g. "problems" for "problems/foo.md"), or `null` when the file sits directly under
+ *       `rootDir` with no subdirectory (e.g. "foo.md").
+ *       `relativeFilePath` is the same POSIX-style relative path that ends up in the returned
+ *       entry's `file` field, in case a consumer needs finer-grained categorization than the
+ *       top-level segment alone.
+ *       The function's return value is used verbatim as `category`.
+ *   - May be a plain lookup object: `{ [topLevelSegment]: categoryString }`. Looked up by the
+ *     file's top-level segment; if the segment is `null` (file directly under rootDir) or has no
+ *     matching key, falls back to the object's own `_default` key if present, else `'uncategorized'`.
+ *   - May be omitted entirely, in which case every entry gets `category: 'uncategorized'`.
+ *
+ * Malformed files (parse errors) are skipped with a `console.warn` — matching the existing
+ * `board.js`/`rapports.js` pattern — rather than aborting the whole walk. A root directory that
+ * does not exist returns `[]` rather than throwing (matches the existing `fs.existsSync` guard
+ * used by both `board.js` and `rapports.js`).
+ * ---------------------------------------------------------------------------------------------
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const matter = require('gray-matter');
+
+const DEFAULT_CATEGORY = 'uncategorized';
+
+/**
+ * Recursively collect absolute paths of every `.md` file under `dir`.
+ * Mirrors rapports.js's listMdFiles(), kept private to this module.
+ * @param {string} dir
+ * @returns {string[]} absolute file paths
+ */
+function listMdFilesRecursive(dir) {
+  const entries = fs.readdirSync(dir, { withFileTypes: true });
+  const files = [];
+  for (const entry of entries) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      files.push(...listMdFilesRecursive(full));
+    } else if (entry.isFile() && entry.name.endsWith('.md')) {
+      files.push(full);
+    }
+  }
+  return files;
+}
+
+/**
+ * Normalize a relative path to POSIX-style separators so API payloads never leak `\` on Windows
+ * dev environments.
+ * @param {string} relPath
+ * @returns {string}
+ */
+function toPosixPath(relPath) {
+  return relPath.split(path.sep).join('/');
+}
+
+/**
+ * Derive the top-level subdirectory segment of a POSIX-style relative path, or `null` if the file
+ * sits directly under the root with no subdirectory.
+ * @param {string} posixRelPath
+ * @returns {string|null}
+ */
+function topLevelSegmentOf(posixRelPath) {
+  const idx = posixRelPath.indexOf('/');
+  return idx === -1 ? null : posixRelPath.slice(0, idx);
+}
+
+/**
+ * Resolve a category string for a file given the caller-supplied `categorize` mapping.
+ * @param {Function|Object|undefined} categorize
+ * @param {string|null} topLevelSegment
+ * @param {string} posixRelPath
+ * @returns {string}
+ */
+function resolveCategory(categorize, topLevelSegment, posixRelPath) {
+  if (typeof categorize === 'function') {
+    const result = categorize(topLevelSegment, posixRelPath);
+    return typeof result === 'string' && result.length > 0 ? result : DEFAULT_CATEGORY;
+  }
+  if (categorize && typeof categorize === 'object') {
+    if (topLevelSegment !== null && Object.prototype.hasOwnProperty.call(categorize, topLevelSegment)) {
+      return categorize[topLevelSegment];
+    }
+    if (Object.prototype.hasOwnProperty.call(categorize, '_default')) {
+      return categorize._default;
+    }
+    return DEFAULT_CATEGORY;
+  }
+  return DEFAULT_CATEGORY;
+}
+
+/**
+ * Recursively read all `.md` files under `rootDir`, parsing frontmatter + content via
+ * `gray-matter` and deriving a `category` per file via the caller-supplied `categorize` mapping.
+ *
+ * Returns `[]` if `rootDir` does not exist. Skips (with `console.warn`) any file that fails to
+ * read or parse, rather than aborting the whole walk.
+ *
+ * @param {string} rootDir - absolute path to the directory to walk.
+ * @param {Function|Object} [categorize] - see module-level JSDoc for the full contract.
+ * @returns {{ file: string, data: Object, content: string, category: string }[]}
+ */
+function readMarkdownDirRecursive(rootDir, categorize) {
+  if (!fs.existsSync(rootDir)) return [];
+
+  const absolutePaths = listMdFilesRecursive(rootDir);
+  const results = [];
+
+  for (const absPath of absolutePaths) {
+    try {
+      const raw = fs.readFileSync(absPath, 'utf8');
+      const parsed = matter(raw);
+      const posixRelPath = toPosixPath(path.relative(rootDir, absPath));
+      const topLevelSegment = topLevelSegmentOf(posixRelPath);
+      const category = resolveCategory(categorize, topLevelSegment, posixRelPath);
+
+      results.push({
+        file: posixRelPath,
+        data: parsed.data,
+        content: parsed.content.trim(),
+        category,
+      });
+    } catch (err) {
+      console.warn(`[markdown-dir-reader] Skipping malformed file: ${absPath} — ${err.message}`);
+    }
+  }
+
+  return results;
+}
+
+module.exports = { readMarkdownDirRecursive };

package/project/app/api/parsers/rapports.js

@@ -0,0 +1,148 @@
+/**
+ * @file project/app/api/parsers/rapports.js
+ * Lists rapport markdown files and extracts summary metadata.
+ *
+ * Also exports `readRapportsFull()` (E58_S01_T03) — a full-content, 6-category aggregate built
+ * on `./lib/markdown-dir-reader`'s `readMarkdownDirRecursive()` (E58_S01_T01) and `./ideas`'s
+ * `readIdeas()` (E58_S01_T02), covering `project/rapports/{analysis,problems,tests}`,
+ * `project/documentation/{summaries,plans}`, and `project/ideas.md`. This coexists with, and does
+ * not alter, the original `readRapports()` below — that function and its truncated
+ * `content_summary` shape are `GET /v1/history`'s exclusive, unchanged dependency.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const matter = require('gray-matter');
+const { resolveProjectRoot } = require('../lib/resolve-project-root');
+const { readMarkdownDirRecursive } = require('./lib/markdown-dir-reader');
+const { readIdeas } = require('./ideas');
+
+// Resolved relative to the invoking project's own root (E47_S02_T01/T02), not a fixed __dirname
+// climb — see project/app/api/lib/resolve-project-root.js.
+const RAPPORTS_ROOT = path.join(resolveProjectRoot(), 'project', 'rapports');
+const DOCUMENTATION_SUMMARIES_ROOT = path.join(
+  resolveProjectRoot(),
+  'project',
+  'documentation',
+  'summaries'
+);
+const DOCUMENTATION_PLANS_ROOT = path.join(
+  resolveProjectRoot(),
+  'project',
+  'documentation',
+  'plans'
+);
+const DATE_PATTERN = /(\d{4}-\d{2}-\d{2})/;
+
+// Maps project/rapports/*'s top-level subdirectories onto the 6-category taxonomy named in
+// E58_S01's story description ("Rapports: analysis/problems/tests/summaries/plans/ideas").
+const RAPPORTS_CATEGORIZE = { analysis: 'analysis', problems: 'problems', tests: 'tests' };
+
+/**
+ * Recursively list .md files under a directory.
+ * @param {string} dir
+ * @returns {string[]} absolute file paths
+ */
+function listMdFiles(dir) {
+  if (!fs.existsSync(dir)) return [];
+  const entries = fs.readdirSync(dir, { withFileTypes: true });
+  const files = [];
+  for (const entry of entries) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      files.push(...listMdFiles(full));
+    } else if (entry.isFile() && entry.name.endsWith('.md')) {
+      files.push(full);
+    }
+  }
+  return files;
+}
+
+/**
+ * Read rapport files and return summary objects.
+ * Returns [] if the rapports directory does not exist.
+ * @returns {Promise<Object[]>}
+ */
+async function readRapports() {
+  if (!fs.existsSync(RAPPORTS_ROOT)) return [];
+
+  const files = listMdFiles(RAPPORTS_ROOT);
+  const results = [];
+
+  for (const filePath of files) {
+    try {
+      const raw = fs.readFileSync(filePath, 'utf8');
+      const { data: frontmatter, content } = matter(raw);
+      const filename = path.relative(RAPPORTS_ROOT, filePath);
+
+      // Date: prefer frontmatter, then extract from filename
+      let date = frontmatter.date || null;
+      if (!date) {
+        const match = DATE_PATTERN.exec(path.basename(filePath));
+        if (match) date = match[1];
+      }
+
+      const content_summary = content.trim().slice(0, 300);
+
+      results.push({
+        type: 'rapport',
+        filename,
+        date: date ? String(date) : null,
+        content_summary,
+      });
+    } catch (err) {
+      console.warn(`[rapports] Skipping malformed file: ${filePath} — ${err.message}`);
+    }
+  }
+
+  return results;
+}
+
+/**
+ * Resolve a `date` field for a `readMarkdownDirRecursive()` entry, mirroring the exact
+ * frontmatter-then-filename fallback rule `readRapports()` already uses above — factored out here
+ * so `readRapportsFull()` can apply the identical rule across all of its directory-reader sources
+ * without duplicating it per call site. Does not alter `readRapports()` itself.
+ * @param {Object} data - gray-matter-parsed frontmatter object.
+ * @param {string} relFile - path relative to the source root (used for filename-based fallback).
+ * @returns {string|null}
+ */
+function extractDate(data, relFile) {
+  let date = (data && data.date) || null;
+  if (!date) {
+    const match = DATE_PATTERN.exec(path.basename(relFile));
+    if (match) date = match[1];
+  }
+  return date ? String(date) : null;
+}
+
+/**
+ * Aggregate full (untruncated) content across the 6-category taxonomy named in E58_S01's story
+ * description: `analysis`/`problems`/`tests` (from `project/rapports/*`), `summaries`/`plans`
+ * (from `project/documentation/*`), and `idea` (from `project/ideas.md`).
+ *
+ * Each entry carries: `{ file, data, content, category, date }` — `file` is a path relative to
+ * its own source root (POSIX-style, per `readMarkdownDirRecursive()`'s contract), `data` is the
+ * parsed frontmatter object (`{}` if none), `content` is the full untruncated markdown body, and
+ * `date` follows the same frontmatter-then-filename fallback rule as `readRapports()`. A missing
+ * source directory/file contributes zero entries rather than throwing (inherited from
+ * `readMarkdownDirRecursive()`'s and `readIdeas()`'s own non-throwing guards).
+ *
+ * Does not alter `readRapports()` or its truncated `content_summary` shape — `GET /v1/history`
+ * is unaffected by this function's existence.
+ * @returns {Promise<Object[]>}
+ */
+async function readRapportsFull() {
+  const withDates = (entries) => entries.map((e) => ({ ...e, date: extractDate(e.data, e.file) }));
+
+  const rapportEntries = withDates(readMarkdownDirRecursive(RAPPORTS_ROOT, RAPPORTS_CATEGORIZE));
+  const summaryEntries = withDates(
+    readMarkdownDirRecursive(DOCUMENTATION_SUMMARIES_ROOT, () => 'summaries')
+  );
+  const planEntries = withDates(readMarkdownDirRecursive(DOCUMENTATION_PLANS_ROOT, () => 'plans'));
+  const ideaEntries = await readIdeas();
+
+  return [...rapportEntries, ...summaryEntries, ...planEntries, ...ideaEntries];
+}
+
+module.exports = { readRapports, readRapportsFull };

package/project/app/api/parsers/todo.js

@@ -0,0 +1,179 @@
+/**
+ * @file project/app/api/parsers/todo.js
+ *
+ * Reads the invoking project's `project/todo.md` and extracts the board refs its **active**
+ * (non-comment) entries name, so the dashboard can tell which board items the user has already
+ * queued for execution. Consumed by `parsers/board.js`, which tags each matching epic/story/task
+ * with `_queued: true` (E06_S05_T04) — the Active Sprint tab's In Progress column promotes those
+ * items even though their board status hasn't moved yet.
+ *
+ * ── Path resolution ───────────────────────────────────────────────────────────────────────────
+ * `todo.md` is resolved via `resolveProjectRoot()` (`../lib/resolve-project-root.js`), exactly the
+ * way `parsers/board.js` resolves `BOARD_ROOT` — never a fixed `path.resolve(__dirname, '../../..')`
+ * climb. A `__dirname` climb only ever lands correctly inside this monorepo's own checkout; from a
+ * consumer's `node_modules/@jenga-ai/agent/` it lands inside or above `node_modules` and silently
+ * reads the wrong file (or none). That is the exact E46 / E47_S02 defect pattern.
+ *
+ * Unlike `board.js`, the path is resolved **inside** `readTodoRefs()` rather than at module load.
+ * Two reasons: requiring this module can then never throw at import time (a board read must not be
+ * taken down by an unresolvable root before the route handler can even produce an error envelope),
+ * and tests can pass an explicit path without touching `JENGA_PROJECT_ROOT`. Since `server.js`
+ * pins the resolved root into that env var before any parser loads, the per-call resolution is a
+ * cheap env-var read, not a repeated filesystem walk.
+ *
+ * ── Line shapes in the real file ──────────────────────────────────────────────────────────────
+ * `project/todo.md`'s documented format is `<mission title>: <E##_S##>` with the ref **optional**
+ * (its own header comment says so). The live file contains all of these, and all of them must be
+ * handled:
+ *
+ *   1. `Implement set-break.sh and clear-break.sh: E44_S01_T02`     → task ref, extracted
+ *   2. `Handoff document schema & ... checkpoint: E23_S01`          → story ref, extracted
+ *   3. `invoke /brainstorm project/rapports/analysis/...md`         → no ref, ignored
+ *   4. `<!-- RECONCILED: ...: E32_S01_T01 -->`                      → comment, skipped entirely
+ *   5. `# Todo` / `<!-- Format: ... -->` / blank lines               → ignored
+ *   6. `Fix hardcoded project/ paths ... (see project/rapports/problems/E31_S05_T01-hidden-mode-path-resolution-gaps.md, F1/F2): E34`
+ *
+ * Shape 6 is why the ref pattern is **end-anchored and colon-preceded** rather than "any ref
+ * anywhere in the line": that single real line both embeds `E31_S05_T01` inside a rapport filename
+ * and ends in the epic-only ref `E34`. A loose `/E\d+_S\d+(_T\d+)?/g` scan would spuriously report
+ * `E31_S05_T01` as queued — a board item that line is merely *citing*, not queueing.
+ *
+ * ── Epic-only refs are deliberately not matched ───────────────────────────────────────────────
+ * A trailing `E##` (e.g. `E34`, `E15_S04` is a story so it matches, but bare `E34` does not) is
+ * ignored. E06_S05_T04's Acceptance Criteria scope resolvable refs to `E##_S##` / `E##_S##_T##`,
+ * and its Description states a ref "may point at a story or at a task". Promoting a whole epic off
+ * a single queued line would also drag an item with a much wider blast radius into the In Progress
+ * column than the user queued. This is a decision, not an oversight.
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { resolveProjectRoot } = require('../lib/resolve-project-root');
+
+/**
+ * Matches a whole line of the documented `<mission title>: <ref>` form, where `<ref>` is a story or
+ * task id and is the last non-whitespace token on the line. `.*?` for the title is lazy but the
+ * `$` anchor forces the ref to be the final token regardless. Case-insensitive so a hand-typed
+ * `e06_s05_t04` still resolves; refs are upper-cased on the way out and `board.js` matches ids
+ * case-insensitively too, so the whole path is case-agnostic.
+ */
+const TODO_ENTRY_PATTERN = /^(.*?):[ \t]*(E\d+_S\d+(?:_T\d+)?)[ \t]*$/i;
+
+/** A balanced HTML comment block, `s`-flag-free so it works on older Node too. */
+const HTML_COMMENT_BLOCK = /<!--[\s\S]*?-->/g;
+
+/**
+ * Removes every balanced `<!-- ... -->` block, then drops everything from an unterminated trailing
+ * `<!--` onward (matching how a browser/markdown renderer treats it: the rest of the document is
+ * commented out). Blocks are replaced with a single space rather than deleted so a comment that
+ * opens mid-line can't silently glue the surrounding text into a fake `title: ref` pair.
+ *
+ * The replacement is **newline-preserving**: a block spanning N newlines is replaced with a space
+ * followed by those N newlines, so every surviving line keeps its original 1-based line number and
+ * any text trailing a multi-line comment's `-->` stays on the line it was actually written on.
+ * Collapsing the block to a bare space instead (the original behavior) shifted every subsequent
+ * line up by N, which made `parseTodoContent`'s `entries[].line` wrong for any file containing a
+ * multi-line comment — and `project/todo.md` contains several.
+ *
+ * The dangling-open truncation needs no equivalent treatment: it only ever discards lines *after*
+ * the unterminated `<!--`, so the line numbers of everything that survives are untouched.
+ *
+ * @param {string} content
+ * @returns {string}
+ */
+function stripComments(content) {
+  const withoutBalanced = String(content == null ? '' : content).replace(
+    HTML_COMMENT_BLOCK,
+    (block) => ' ' + '\n'.repeat((block.match(/\n/g) || []).length)
+  );
+  const danglingOpen = withoutBalanced.indexOf('<!--');
+  return danglingOpen === -1 ? withoutBalanced : withoutBalanced.slice(0, danglingOpen);
+}
+
+/**
+ * Pure parse of `todo.md` content into the board refs its active entries name.
+ *
+ * @param {string} content raw file content
+ * @returns {{ refs: string[], entries: { title: string, ref: string, line: number }[] }}
+ *   `refs` is upper-cased and de-duplicated, in first-appearance order. `entries` keeps every
+ *   matching line for debuggability; its 1-based `line` numbers always match the original content,
+ *   since `stripComments` preserves the newlines of the blocks it removes.
+ */
+function parseTodoContent(content) {
+  const lines = stripComments(content).split(/\r?\n/);
+  const entries = [];
+  const seen = new Set();
+  const refs = [];
+
+  lines.forEach((rawLine, index) => {
+    const line = rawLine.trim();
+    if (!line || line.startsWith('#')) return;
+
+    const match = TODO_ENTRY_PATTERN.exec(line);
+    if (!match) return;
+
+    const title = match[1].trim();
+    const ref = match[2].toUpperCase();
+
+    entries.push({ title, ref, line: index + 1 });
+    if (!seen.has(ref)) {
+      seen.add(ref);
+      refs.push(ref);
+    }
+  });
+
+  return { refs, entries };
+}
+
+/**
+ * Absolute path to the invoking project's `project/todo.md`.
+ * @returns {string}
+ */
+function resolveTodoPath() {
+  return path.join(resolveProjectRoot(), 'project', 'todo.md');
+}
+
+/**
+ * Read and parse the project's `todo.md`.
+ *
+ * A missing file is a first-class, non-exceptional case: it returns `{ exists: false, refs: [] }`,
+ * which makes every downstream consumer behave exactly as it did before this feature existed. An
+ * unreadable file (permissions, a directory where a file was expected) is likewise reported as
+ * `exists: false` with the reason attached, never thrown — a broken `todo.md` must not be able to
+ * take down `GET /v1/board`.
+ *
+ * @param {string} [filePath] explicit path; defaults to `<projectRoot>/project/todo.md`
+ * @returns {{ exists: boolean, path: string, refs: string[], entries: Object[], error?: string }}
+ */
+function readTodoRefs(filePath) {
+  let todoPath;
+  try {
+    todoPath = filePath || resolveTodoPath();
+  } catch (err) {
+    return { exists: false, path: '', refs: [], entries: [], error: err.message };
+  }
+
+  let raw;
+  try {
+    raw = fs.readFileSync(todoPath, 'utf8');
+  } catch (err) {
+    if (err.code !== 'ENOENT') {
+      console.warn(`[todo] Could not read ${todoPath} — ${err.message}`);
+      return { exists: false, path: todoPath, refs: [], entries: [], error: err.message };
+    }
+    return { exists: false, path: todoPath, refs: [], entries: [] };
+  }
+
+  const { refs, entries } = parseTodoContent(raw);
+  return { exists: true, path: todoPath, refs, entries };
+}
+
+module.exports = {
+  readTodoRefs,
+  parseTodoContent,
+  stripComments,
+  resolveTodoPath,
+  TODO_ENTRY_PATTERN,
+};