@jenga-ai/agent 3.1.1 → 3.4.0

package/scripts/populate-knowledge-graph.js

@@ -0,0 +1,429 @@
+#!/usr/bin/env node
+/**
+ * scripts/populate-knowledge-graph.js — Mechanical Board-to-Graph Populator (E20_S09_T02)
+ *
+ * Reads `project/board/epics/*.md` and `project/board/stories/*.md` frontmatter (read-only) and
+ * writes/updates nodes and edges into `project/knowledge-graph/graph.json`, per
+ * `project/knowledge-graph/STUB_SCHEMA.md`'s node/edge shape, using `source: "board"` (defined in
+ * E20_S09_T01 — see STUB_SCHEMA.md's "Where `board` Fits" section for its exact semantics: lowest
+ * precedence, one-way superseded-by relationship, never supersedes human/ast nodes).
+ *
+ * Scope, by design (see STUB_SCHEMA.md and E20_S09's story):
+ *   - One node per Epic, one node per Story. Tasks are never nodes via this populator.
+ *   - Containment edges (Epic -> Story) and `depends_on`-derived dependency edges only — nothing
+ *     fabricated beyond what board frontmatter actually states.
+ *   - Idempotent on `id`: re-running merges into the existing graph rather than duplicating or
+ *     blindly overwriting unrelated content.
+ *   - Strictly read-only against `project/board/` — this script never creates, modifies, or
+ *     deletes anything under it.
+ *   - No network calls, no external dependencies. The repo root `package.json` has no runtime
+ *     `dependencies` (verified) — every other script under `scripts/`/`lib/` is dependency-free
+ *     Node ESM using only `node:*` builtins (e.g. `postinstall.js`, `generate-legacy-shipped-paths.js`),
+ *     so this script follows the same convention with its own small hand-rolled frontmatter parser
+ *     rather than adding `gray-matter` (only present in the separate `project/app/` workspace) as a
+ *     new root-level dependency for a single script.
+ *
+ * Note: `scripts/e25_s01_extract_board_graph.py` is an existing throwaway spike with its own
+ * hand-rolled frontmatter parser, explicitly marked "Do not import" in its own header comment. It
+ * was consulted only as prior art on the shape of the problem — nothing from it is imported or
+ * reused here.
+ *
+ * CLI:
+ *   node scripts/populate-knowledge-graph.js [--project-root <path>] [--dry-run]
+ *
+ *   --project-root  Path to a directory containing board/ and knowledge-graph/ (default: the
+ *                    repo's own `project/` directory, resolved relative to this script). Lets
+ *                    E20_S09_T03's test coverage point the populator at fixture board directories
+ *                    without touching the real board.
+ *   --dry-run        Compute the merged graph and report whether it would change, but never write
+ *                    to disk.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = path.join(__dirname, '..');
+
+const EPIC_ID_RE = /^E\d+$/;
+const STORY_ID_RE = /^E\d+_S\d+$/;
+
+const NODE_KEY_ORDER = ['id', 'type', 'label', 'description', 'source', 'status', 'superseded_by'];
+const EDGE_KEY_ORDER = ['id', 'from', 'to', 'type', 'description'];
+
+// ── CLI args ────────────────────────────────────────────────────────────────
+
+function parseArgs(argv) {
+  const args = { projectRoot: path.join(REPO_ROOT, 'project'), dryRun: false };
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === '--project-root') {
+      args.projectRoot = path.resolve(argv[++i] ?? '');
+    } else if (arg.startsWith('--project-root=')) {
+      args.projectRoot = path.resolve(arg.slice('--project-root='.length));
+    } else if (arg === '--dry-run') {
+      args.dryRun = true;
+    }
+  }
+  return args;
+}
+
+// ── Minimal frontmatter parsing ────────────────────────────────────────────
+// Tailored to this project's actual board schema: flat `key: value` scalar pairs, plus one
+// multi-line list shape (`  - item` continuation lines under a bare `key:`). Verified against
+// every epic/story file in this repo before writing — no general YAML support is attempted.
+
+function unquote(value) {
+  const text = value.trim();
+  if (
+    (text.startsWith('"') && text.endsWith('"') && text.length >= 2) ||
+    (text.startsWith("'") && text.endsWith("'") && text.length >= 2)
+  ) {
+    return text.slice(1, -1);
+  }
+  return text;
+}
+
+function parseFrontmatter(raw) {
+  if (!raw.startsWith('---\n') && raw !== '---') {
+    return { frontmatter: {}, body: raw };
+  }
+  const closeIdx = raw.indexOf('\n---', 4);
+  if (closeIdx === -1) {
+    return { frontmatter: {}, body: raw };
+  }
+  const rawFrontmatter = raw.slice(4, closeIdx);
+  // Body starts after the closing `---` line.
+  const afterClose = raw.indexOf('\n', closeIdx + 1);
+  const body = afterClose === -1 ? '' : raw.slice(afterClose + 1);
+
+  const frontmatter = {};
+  let currentListKey = null;
+  for (const line of rawFrontmatter.split('\n')) {
+    if (line.trim() === '') continue;
+    if (/^\s+-\s?/.test(line) && currentListKey) {
+      const item = unquote(line.replace(/^\s+-\s?/, ''));
+      frontmatter[currentListKey].push(item);
+      continue;
+    }
+    const colonIdx = line.indexOf(':');
+    if (colonIdx === -1) {
+      currentListKey = null;
+      continue;
+    }
+    const key = line.slice(0, colonIdx).trim();
+    const rawValue = line.slice(colonIdx + 1).trim();
+    if (rawValue === '') {
+      // Could be the start of a list (`stories:` followed by `  - E20_S01`) or a genuinely
+      // empty scalar field (e.g. `date_completed:`). Assume list; if no `- item` lines follow,
+      // it naturally stays an empty array, which is falsy-equivalent for our purposes.
+      frontmatter[key] = [];
+      currentListKey = key;
+    } else {
+      frontmatter[key] = unquote(rawValue);
+      currentListKey = null;
+    }
+  }
+  return { frontmatter, body };
+}
+
+// ── Description derivation ─────────────────────────────────────────────────
+
+function firstParagraphAfterHeading(body) {
+  const lines = body.split('\n');
+  let idx = 0;
+  while (idx < lines.length && !lines[idx].trim().startsWith('# ')) idx++;
+  if (idx < lines.length) idx++; // past the heading line itself
+  while (idx < lines.length && lines[idx].trim() === '') idx++;
+  const paragraph = [];
+  while (idx < lines.length && lines[idx].trim() !== '' && !lines[idx].trim().startsWith('#')) {
+    paragraph.push(lines[idx].trim());
+    idx++;
+  }
+  return paragraph.join(' ').trim();
+}
+
+function purposeSection(body) {
+  const headingMatch = body.match(/^##\s*Purpose\s*$/m);
+  if (!headingMatch) return null;
+  const rest = body.slice(headingMatch.index + headingMatch[0].length);
+  const nextHeadingMatch = rest.match(/\n##\s/);
+  const section = nextHeadingMatch ? rest.slice(0, nextHeadingMatch.index) : rest;
+  return section.trim();
+}
+
+function epicDescription(body) {
+  const purpose = purposeSection(body);
+  if (purpose) return purpose;
+  // Fallback for board files that predate the `## Purpose` convention (e.g. E24).
+  return firstParagraphAfterHeading(body);
+}
+
+function storyDescription(body) {
+  return firstParagraphAfterHeading(body);
+}
+
+// ── Board scan ──────────────────────────────────────────────────────────────
+
+function listMarkdownFiles(dir) {
+  let entries;
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch (err) {
+    if (err.code === 'ENOENT') return [];
+    throw err;
+  }
+  return entries
+    .filter((entry) => entry.isFile() && entry.name.endsWith('.md'))
+    .map((entry) => path.join(dir, entry.name))
+    .sort();
+}
+
+function scanEpics(boardDir) {
+  const files = listMarkdownFiles(path.join(boardDir, 'epics'));
+  const epics = [];
+  for (const file of files) {
+    const raw = fs.readFileSync(file, 'utf8');
+    const { frontmatter, body } = parseFrontmatter(raw);
+    if (!frontmatter.id || !EPIC_ID_RE.test(frontmatter.id)) continue;
+    epics.push({
+      id: frontmatter.id,
+      title: frontmatter.title ?? '',
+      description: epicDescription(body),
+    });
+  }
+  return epics;
+}
+
+function scanStories(boardDir) {
+  const files = listMarkdownFiles(path.join(boardDir, 'stories'));
+  const stories = [];
+  for (const file of files) {
+    const raw = fs.readFileSync(file, 'utf8');
+    const { frontmatter, body } = parseFrontmatter(raw);
+    if (!frontmatter.id || !STORY_ID_RE.test(frontmatter.id)) continue;
+    stories.push({
+      id: frontmatter.id,
+      title: frontmatter.title ?? '',
+      description: storyDescription(body),
+      epicId: typeof frontmatter.epic_id === 'string' ? frontmatter.epic_id : '',
+      dependsOn: typeof frontmatter.depends_on === 'string' ? frontmatter.depends_on : '',
+    });
+  }
+  return stories;
+}
+
+function parseDependsOn(raw) {
+  if (!raw) return [];
+  return raw
+    .split(',')
+    .map((token) => token.trim())
+    .filter((token) => token !== '' && token.toLowerCase() !== 'none');
+}
+
+// ── Node/edge derivation ────────────────────────────────────────────────────
+
+function deriveNodesAndEdges(epics, stories) {
+  const nodes = new Map();
+  const edges = new Map();
+
+  for (const epic of epics) {
+    nodes.set(epic.id, {
+      id: epic.id,
+      type: 'epic',
+      label: epic.title,
+      description: epic.description,
+      source: 'board',
+    });
+  }
+  for (const story of stories) {
+    nodes.set(story.id, {
+      id: story.id,
+      type: 'story',
+      label: story.title,
+      description: story.description,
+      source: 'board',
+    });
+  }
+
+  const epicIds = new Set(epics.map((e) => e.id));
+  const storyIds = new Set(stories.map((s) => s.id));
+  const knownIds = new Set([...epicIds, ...storyIds]);
+
+  // Containment: derived from each story's own `epic_id` field (not the epic's `stories:` list),
+  // so a stale/out-of-sync list on the epic side can never produce a dangling edge.
+  for (const story of stories) {
+    if (story.epicId && epicIds.has(story.epicId)) {
+      const edgeId = `board:contains:${story.epicId}:${story.id}`;
+      edges.set(edgeId, {
+        id: edgeId,
+        from: story.epicId,
+        to: story.id,
+        type: 'contains',
+        description: `${story.epicId} contains ${story.id}.`,
+      });
+    }
+  }
+
+  // Dependency edges: only for targets that resolve to a real, known Epic or Story node — a
+  // `depends_on` referencing a Task (or any unrecognised id) is skipped rather than fabricated.
+  for (const story of stories) {
+    for (const targetId of parseDependsOn(story.dependsOn)) {
+      if (!knownIds.has(targetId)) continue;
+      const edgeId = `board:depends-on:${story.id}:${targetId}`;
+      edges.set(edgeId, {
+        id: edgeId,
+        from: story.id,
+        to: targetId,
+        type: 'depends-on',
+        description: `${story.id} depends on ${targetId} (per board depends_on frontmatter).`,
+      });
+    }
+  }
+
+  return { nodes, edges };
+}
+
+// ── Merge into existing graph.json ─────────────────────────────────────────
+
+function canonicalizeKeys(obj, order) {
+  const result = {};
+  for (const key of order) {
+    if (key in obj) result[key] = obj[key];
+  }
+  for (const key of Object.keys(obj)) {
+    if (!(key in result)) result[key] = obj[key];
+  }
+  return result;
+}
+
+function loadExistingGraph(graphPath) {
+  let raw;
+  try {
+    raw = fs.readFileSync(graphPath, 'utf8');
+  } catch (err) {
+    if (err.code === 'ENOENT') return { nodes: [], edges: [] };
+    throw err;
+  }
+  try {
+    const parsed = JSON.parse(raw);
+    return {
+      nodes: Array.isArray(parsed.nodes) ? parsed.nodes : [],
+      edges: Array.isArray(parsed.edges) ? parsed.edges : [],
+    };
+  } catch {
+    // Unparsable existing file: treat as empty rather than crash. This is a graceful-degradation
+    // choice, not silent data loss — the populator only ever writes back a superset (merge), and a
+    // corrupt file was already not a valid graph to begin with.
+    return { nodes: [], edges: [] };
+  }
+}
+
+const BOARD_EDGE_ID_PREFIXES = ['board:contains:', 'board:depends-on:'];
+
+function isBoardOwnedEdgeId(id) {
+  return BOARD_EDGE_ID_PREFIXES.some((prefix) => id.startsWith(prefix));
+}
+
+function mergeGraph(existing, computed) {
+  const nodeMap = new Map(existing.nodes.map((node) => [node.id, node]));
+  // Prune stale populator-owned nodes no longer produced this run (e.g. an Epic or Story board
+  // file was deleted or renamed, so its id no longer appears in the current board scan). Only
+  // nodes this populator itself owns — `source: "board"` — are ever eligible for pruning; a
+  // `human`- or `ast`-sourced node is never touched here, mirroring the edge-pruning namespace
+  // guard below (E20_S09_T02 rapport: a stale board node was previously left behind forever while
+  // its containment edge was correctly pruned on the same re-run — this closes that gap).
+  for (const [id, node] of [...nodeMap.entries()]) {
+    if (node.source === 'board' && !computed.nodes.has(id)) {
+      nodeMap.delete(id);
+    }
+  }
+  for (const [id, computedNode] of computed.nodes) {
+    const merged = { ...(nodeMap.get(id) ?? {}), ...computedNode };
+    nodeMap.set(id, canonicalizeKeys(merged, NODE_KEY_ORDER));
+  }
+
+  const edgeMap = new Map(existing.edges.map((edge) => [edge.id, edge]));
+  // Prune stale populator-owned edges no longer produced this run (e.g. a `depends_on` was
+  // removed from a story). Only ids in this populator's own `board:contains:`/`board:depends-on:`
+  // namespace are ever touched — never a node, and never an edge belonging to another source.
+  for (const id of [...edgeMap.keys()]) {
+    if (isBoardOwnedEdgeId(id) && !computed.edges.has(id)) {
+      edgeMap.delete(id);
+    }
+  }
+  for (const [id, computedEdge] of computed.edges) {
+    const merged = { ...(edgeMap.get(id) ?? {}), ...computedEdge };
+    edgeMap.set(id, canonicalizeKeys(merged, EDGE_KEY_ORDER));
+  }
+
+  const nodes = [...nodeMap.values()].sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+  const edges = [...edgeMap.values()].sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+  return { nodes, edges };
+}
+
+// ── Main ─────────────────────────────────────────────────────────────────
+
+function run(argv) {
+  const args = parseArgs(argv);
+  const boardDir = path.join(args.projectRoot, 'board');
+  const graphPath = path.join(args.projectRoot, 'knowledge-graph', 'graph.json');
+
+  const epics = scanEpics(boardDir);
+  const stories = scanStories(boardDir);
+  const computed = deriveNodesAndEdges(epics, stories);
+
+  const existing = loadExistingGraph(graphPath);
+  const merged = mergeGraph(existing, computed);
+  const nextContent = `${JSON.stringify(merged, null, 2)}\n`;
+
+  let currentContent = null;
+  try {
+    currentContent = fs.readFileSync(graphPath, 'utf8');
+  } catch (err) {
+    if (err.code !== 'ENOENT') throw err;
+  }
+
+  const changed = currentContent !== nextContent;
+
+  if (args.dryRun) {
+    process.stdout.write(
+      changed
+        ? `[dry-run] graph.json would change (${merged.nodes.length} nodes, ${merged.edges.length} edges).\n`
+        : `[dry-run] graph.json is already up to date (${merged.nodes.length} nodes, ${merged.edges.length} edges).\n`,
+    );
+    return 0;
+  }
+
+  if (changed) {
+    fs.mkdirSync(path.dirname(graphPath), { recursive: true });
+    fs.writeFileSync(graphPath, nextContent);
+    process.stdout.write(
+      `Wrote ${graphPath} (${merged.nodes.length} nodes, ${merged.edges.length} edges).\n`,
+    );
+  } else {
+    process.stdout.write(
+      `${graphPath} already up to date (${merged.nodes.length} nodes, ${merged.edges.length} edges) — no write.\n`,
+    );
+  }
+  return 0;
+}
+
+const invokedPath = process.argv[1] ? fs.realpathSync(process.argv[1]) : null;
+if (invokedPath === fileURLToPath(import.meta.url)) {
+  process.exitCode = run(process.argv.slice(2));
+}
+
+export {
+  parseFrontmatter,
+  epicDescription,
+  storyDescription,
+  scanEpics,
+  scanStories,
+  parseDependsOn,
+  deriveNodesAndEdges,
+  loadExistingGraph,
+  mergeGraph,
+  run,
+};

package/scripts/release-concurrency-slot.sh

@@ -0,0 +1,129 @@
+#!/usr/bin/env bash
+# ---------------------------------------------------------------------------
+# scripts/release-concurrency-slot.sh
+#
+# Release a role-scoped concurrency slot previously acquired via
+# scripts/acquire-concurrency-slot.sh, for E32_S15 (Per-Session Concurrency
+# Cap for Developer/Tester Dispatch). Removes the caller's holder entry from
+# project/queue/concurrency-slots-<session_id>.json, unconditionally and
+# idempotently — mirroring scripts/with-lock.sh's own idempotent-cleanup
+# discipline (no error if the counter file, the role, or the holder entry is
+# already absent).
+#
+# The counter file belongs to exactly the session_id in its own filename.
+# This script never reads or writes a counter file for any session_id other
+# than the one passed as its own argument.
+#
+# Usage:
+#   scripts/release-concurrency-slot.sh <role> <holder-id> <session_id>
+#
+# Exit codes:
+#   0  released (or already absent — idempotent no-op is still success)
+#   1  usage error (bad arguments)
+#   2  scripts/with-lock.sh could not acquire the lock within its timeout
+#   5  environment error (jq missing)
+# ---------------------------------------------------------------------------
+
+set -euo pipefail
+
+SELF="$(basename "$0")"
+
+die() {
+  local code="$1"; shift
+  printf '%s: error: %s\n' "$SELF" "$*" >&2
+  exit "$code"
+}
+
+usage() {
+  echo "Usage: $0 <role> <holder-id> <session_id>" >&2
+  exit 1
+}
+
+# Mirrors scripts/acquire-concurrency-slot.sh's own project-root resolution
+# (and scripts/write-context-digest.sh's before it) for consistency.
+resolve_project_dir() {
+  if [ -n "${JENGA_PROJECT_DIR:-}" ]; then
+    printf '%s\n' "$JENGA_PROJECT_DIR"
+    return 0
+  fi
+  if [ -n "${CLAUDE_PROJECT_DIR:-}" ]; then
+    printf '%s\n' "$CLAUDE_PROJECT_DIR"
+    return 0
+  fi
+  git rev-parse --show-toplevel 2>/dev/null || pwd
+}
+
+SCRIPT_ABS_PATH="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/$(basename "${BASH_SOURCE[0]}")"
+
+# ---------------------------------------------------------------------------
+# Internal locked-mutation entrypoint. Not intended to be invoked directly —
+# scripts/with-lock.sh calls back into this same script with this hidden
+# subcommand once the lock on the counter file is held.
+# ---------------------------------------------------------------------------
+if [ "${1:-}" = "__locked-release" ]; then
+  shift
+  ROLE="$1"
+  HOLDER_ID="$2"
+  COUNTER_FILE="$3"
+
+  command -v jq >/dev/null 2>&1 || die 5 "jq is required but not found on PATH"
+
+  # Race: the file may have been removed between the outer existence check
+  # and actually acquiring the lock. That's still a no-op success, not an
+  # error — release is idempotent by contract.
+  [ -f "$COUNTER_FILE" ] || exit 0
+
+  TMP_FILE="$(mktemp "${COUNTER_FILE}.tmp.XXXXXX")"
+  jq \
+    --arg role "$ROLE" \
+    --arg holder "$HOLDER_ID" \
+    '
+    if has($role) then
+      .[$role].holders |= ((. // {}) | del(.[$holder]))
+    else
+      .
+    end
+    ' "$COUNTER_FILE" > "$TMP_FILE"
+  mv "$TMP_FILE" "$COUNTER_FILE"
+  exit 0
+fi
+
+# ---------------------------------------------------------------------------
+# Public entrypoint
+# ---------------------------------------------------------------------------
+[ "$#" -eq 3 ] || usage
+
+ROLE="$1"
+HOLDER_ID="$2"
+SESSION_ID="$3"
+
+case "$ROLE" in
+  developer|tester) ;;
+  *) die 1 "invalid role '$ROLE' (expected developer or tester)" ;;
+esac
+
+[ -n "$HOLDER_ID" ] || die 1 "<holder-id> must not be empty"
+[ -n "$SESSION_ID" ] || die 1 "<session_id> must not be empty"
+
+case "$SESSION_ID" in
+  */*|*..*) die 1 "invalid <session_id> '$SESSION_ID': must not contain '/' or '..'" ;;
+esac
+
+PROJECT_DIR="$(resolve_project_dir)"
+COUNTER_FILE="$PROJECT_DIR/project/queue/concurrency-slots-${SESSION_ID}.json"
+
+command -v jq >/dev/null 2>&1 || die 5 "jq is required but not found on PATH"
+[ -f "$PROJECT_DIR/scripts/with-lock.sh" ] \
+  || die 5 "scripts/with-lock.sh not found at $PROJECT_DIR/scripts/with-lock.sh"
+
+# No counter file at all yet: nothing to release, idempotent no-op, no lock
+# needed.
+[ -f "$COUNTER_FILE" ] || exit 0
+
+set +e
+"$PROJECT_DIR/scripts/with-lock.sh" "$COUNTER_FILE" -- \
+  "$SCRIPT_ABS_PATH" __locked-release "$ROLE" "$HOLDER_ID" "$COUNTER_FILE"
+STATUS=$?
+set -e
+
+exit "$STATUS"

package/scripts/validate-board.sh

@@ -66,6 +66,14 @@ CLOSE_STORY_KEYS = {
     "actual_files_changed", "actual_lines_delta", "scope_divergence_flag", "divergence_flag",
 }
 
+# E51_S05_T02. Written by scripts/mark-deployed.sh in the same locked write window a ticket is
+# set to status: Deployed to Prod (never on a Deployed to Stage-only write). Allow-listed for
+# epic, story, AND task per this field's own AC, even though in practice only tasks (and
+# occasionally stories) are expected to ever carry it.
+DEPLOY_KEYS = {
+    "date_deployed_prod",
+}
+
 # E39 tiered item-level caution/escalation fields. OPTIONAL and story/task-only — epics do not
 # carry these; an epic's risk gating is already handled by epic_scope_approval. See
 # templates/SCRUM_BOARD_SCHEMA.md.
@@ -90,18 +98,19 @@ ALLOWED_KEYS = {
         # (value: backfilled). Absence means the epic was authored normally, so every existing
         # epic that omits it stays valid. See templates/SCRUM_BOARD_SCHEMA.md.
         "provenance",
+        *DEPLOY_KEYS,
     },
     "story": {
         "id", "epic_id", "title", "status", "date_created", "date_started", "date_completed",
         "dates_previously_completed", "reopened_on", "reopened_reason", "tasks", "docs",
         "priority", "depends_on",
-        *CRUCIAL_KEYS,
+        *CRUCIAL_KEYS, *DEPLOY_KEYS,
     },
     "task": {
         "id", "story_id", "epic_id", "title", "status", "date_created", "date_started", "date_completed",
         "dates_previously_completed", "reopened_on", "reopened_reason", "assigned_to", "docs",
         "depends_on",
-        *EXECUTION_SCOPE_KEYS, *CLOSE_STORY_KEYS, *CRUCIAL_KEYS,
+        *EXECUTION_SCOPE_KEYS, *CLOSE_STORY_KEYS, *CRUCIAL_KEYS, *DEPLOY_KEYS,
     },
 }
 
@@ -196,9 +205,58 @@ def validate_docs(source: Path, docs):
         ):
             raise ValueError(f"{source}: docs entry must be repo-relative without leading './' or '/' ({entry})")
 
+def assert_parses_as_yaml(lines: list[str], source: Path) -> None:
+    """Reject frontmatter that a real YAML parser cannot read.
+
+    parse_frontmatter() below is a hand-rolled line splitter, and it is far more
+    lenient than YAML itself. That gap was not theoretical: 36 board files
+    accumulated frontmatter this script called valid but every real consumer --
+    the dashboard's board parser among them -- silently skipped, so the board
+    under-reported itself with no error surfaced anywhere. The three shapes that
+    got through were an unquoted colon in a scalar (`title: Adopt j: prefix`), a
+    value merely starting with a quote (`title: "Merged" Status via /self-sync`),
+    and a duplicated key.
+
+    PyYAML is stdlib-adjacent but not guaranteed present on every consumer, so a
+    missing import degrades to a skip rather than a hard failure -- the targeted
+    checks below still run either way.
+    """
+    body = "\n".join(lines)
+    try:
+        import yaml
+    except ImportError:
+        pass
+    else:
+        try:
+            yaml.safe_load(body)
+        except yaml.YAMLError as exc:
+            detail = str(exc).splitlines()[0]
+            raise ValueError(
+                f"{source}: frontmatter is not valid YAML ({detail}). "
+                "Free-text values containing ':' must be quoted, and multiple "
+                "reopen reasons must be a YAML list -- see "
+                "templates/SCRUM_BOARD_SCHEMA.md's Reopen Tracking Fields."
+            )
+
+    # Duplicate keys are legal-ish to some YAML loaders (last wins) but always a
+    # board-authoring bug: one of the two values is being silently discarded.
+    seen = set()
+    for line in lines:
+        match = re.match(r"^([A-Za-z_][A-Za-z0-9_]*):", line)
+        if not match:
+            continue
+        key = match.group(1)
+        if key in seen:
+            raise ValueError(
+                f"{source}: duplicated frontmatter key '{key}' -- one of its two "
+                "values is silently discarded; merge them into a single entry"
+            )
+        seen.add(key)
+
 def validate_file(source: Path):
     text = source.read_text(encoding="utf-8")
     frontmatter_lines = extract_frontmatter(text, source)
+    assert_parses_as_yaml(frontmatter_lines, source)
     data = parse_frontmatter(frontmatter_lines, source)
 
     item_id = data.get("id")