portfolio-kanban-generator 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Gary Brooks
+
+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,162 @@
+# tools/kanban — shared per-project Kanban generator + drift-gate
+
+One generator, run inside each project repo, that builds a single **self-contained**
+implementation-Kanban board from the project's backlog and an optional content
+override, and a `--check` mode that fails CI if a committed board drifts from a fresh
+generation. This is the shared implementation of portfolio design **Option B+** (one
+generator; boards committed into each repo and published to each repo's own Pages,
+with a per-repo drift-gate), decision **D5** (generator + optional per-project
+content override), and decision **D6** (render stack — see
+[DECISION-render-stack.md](DECISION-render-stack.md)).
+
+Published to the public npm registry as
+**[`portfolio-kanban-generator`](https://www.npmjs.com/package/portfolio-kanban-generator)**
+so any project repo can run the drift-gate in CI via `npx` without vendoring the tool.
+The npm package has **zero runtime dependencies** (vanilla Node). The prompt-library
+source repo that hosts this directory stays private; only the npm package is public.
+
+## Usage
+
+```bash
+# run straight from npm — no install, pinned to an exact version (for CI)
+npx portfolio-kanban-generator@1.0.0 --check --dialect auth-table --project my-project
+
+# write / refresh the board (run from the project repo root)
+npx portfolio-kanban-generator@1.0.0 --project my-project
+```
+
+Or, from a checkout of this repo (development / the library's own gate):
+
+```bash
+# write / refresh the board (run from the project repo root)
+node path/to/tools/kanban/generate-kanban.mjs --project my-project
+
+# drift-gate: exit 1 if the committed board is stale or missing (for CI)
+node path/to/tools/kanban/generate-kanban.mjs --check --project my-project
+```
+
+### Options
+
+| Option | Default | Meaning |
+|---|---|---|
+| `--project <name>` | basename of `--cwd` | project id, used in the heading and board filename |
+| `--backlog <path>` | `docs/backlog.md` | the backlog file |
+| `--override <path>` | `docs/kanban-content.json` | optional ticket-body override |
+| `--adr <dir>` | `docs/adr` | ADR directory, for citation resolution |
+| `--dialect <name>` | `auth-table` | backlog adapter: `auth-table` or `risk-block` |
+| `--board <path>` | `{project}_implementation-kanban_v1.html` | output board |
+| `--title <text>` | `{project} — Implementation Kanban v1` | board heading |
+| `--cwd <dir>` | `process.cwd()` | base directory for all relative paths |
+
+`override_path` and `backlog_dialect` are also recorded per project in the library
+`registry.yml` `defaults:` block, so the per-repo gate can be wired consistently.
+
+## Where authority lives
+
+The board never authors its own truth. Status is **derived**, never transcribed:
+
+- the **backlog** owns which tickets are Done and which are Parked (human decisions);
+- the ticket **dependency graph** (`blockedBy`) owns readiness;
+- **Ready vs Backlog is authored by neither** — it is computed from the two above.
+
+Parked is scope, not progress: a parked ticket never becomes Ready however its
+blockers resolve (**scope beats dependency-readiness**). Readiness is never derived
+from `blocks`. This rule is carried over verbatim from the auth-separation exemplar's
+`scripts/sync-kanban-status.mjs`; see [lib/derive-status.mjs](lib/derive-status.mjs).
+
+## Input contract
+
+A **canonical ticket** has a header (from the backlog) and an optional body (from the
+override):
+
+- Header: `id`, `title`, `type?`, `priority?`, `score?` (0–30), `phase?`,
+  `blockedBy[]`, `blocks?[]`, `backlogStatus` (Done | Parked | Ready | Backlog),
+  `status` (derived).
+- Body (override only): `description?`, `acceptance[]?`, `spec?`, `adr[]?`
+  (each `ADR-nnnn`), `assignee?`.
+
+### Backlog adapters
+
+- **auth-table** (default, the shipping path): 7-column Markdown rows
+  `| ID | Ticket | Type | Priority | Tier | Blocked by | Status |`. A row is a
+  ticket iff its first cell is a backticked id and it has exactly seven cells.
+  Status is keyword-classified — **Parked** (tested first) > **Done** > **Ready** >
+  else **Backlog** — and `blockedBy` is read from the "Blocked by" cell. Ready/Backlog
+  are recomputed from the graph.
+- **risk-block** (scaffold only, pre-classified): templated
+  `#### Risk #N: title — Score: N` blocks with a `**Status:**` line mapping
+  COMPLETE → Done, IN PROGRESS → In Progress, READY START → Ready, BLOCKED → Backlog.
+  Risks have no dependency edges, so the authored status passes through unchanged.
+
+An adapter **fails loudly** on a backlog it cannot parse: parsing zero tickets is an
+error, never an empty success.
+
+### Content override (`docs/kanban-content.json`)
+
+A JSON object keyed by ticket id whose values carry **only** body fields. Rules,
+enforced (not merely documented):
+
+- an override id absent from the backlog is a **hard error**;
+- a backlog id with no override entry is fine (a header-only card);
+- an override entry carrying any header field (`status`, `backlogStatus`,
+  `blockedBy`, `title`, `type`, `priority`, `score`, …) is a **hard error**.
+
+## What fails a run or the gate
+
+Both modes fail (exit 1) on: an unparseable backlog, an override id absent from the
+backlog, an override carrying header fields, an unresolved ADR citation, or a
+non-deterministic render. `--check` additionally fails on a missing or stale board.
+
+## Layout
+
+```
+tools/kanban/
+  generate-kanban.mjs        CLI: default writes/refreshes; --check is the drift-gate
+  lib/derive-status.mjs      status derivation (verbatim rule) + stats recompute
+  lib/adapters.mjs           auth-table (required) + risk-block (scaffold)
+  lib/override.mjs           override load/validation, content merge, ADR resolution
+  lib/render.mjs             self-contained vanilla-JS board renderer + payload I/O
+  test/                      node:test suites + fixtures (auth-table, risk-block)
+  DECISION-render-stack.md   D6 measurement and decision
+```
+
+## Tests
+
+```bash
+cd tools/kanban && node --test
+```
+
+The suite covers the derive-status rule against its truth table, both adapters,
+override validation, ADR resolution, and end-to-end generation / drift / determinism
+over the fixtures. It also runs inside `python tools/check-library.py`
+(check `check_kanban`) and is guarded across the language boundary by
+`tools/tests/test_kanban_generator.py`.
+
+## Publishing (maintainers)
+
+This directory is its own npm package (`portfolio-kanban-generator`), independent of
+the private prompt-library root (which is `"private": true` and cannot publish). The
+published tarball is whitelisted to `generate-kanban.mjs`, `lib/`, `README.md`, and
+`LICENSE` — `test/` and its fixtures are excluded. Confirm the contents before a
+release with `npm pack --dry-run`.
+
+A release is cut by pushing a tag `kanban-v<version>` that matches the `version` in
+[package.json](package.json); the [`publish-kanban`](../../.github/workflows/publish-kanban.yml)
+workflow then runs the test suite and `npm publish --access public`. It needs a
+repository secret **`NPM_TOKEN`** (an npm automation token for an account that owns the
+package name).
+
+```bash
+# 1. bump tools/kanban/package.json "version", commit, merge to main
+# 2. cut the release
+git tag kanban-v1.0.0
+git push origin kanban-v1.0.0
+```
+
+To publish manually instead (from this directory, logged in to npm):
+
+```bash
+npm test
+npm pack --dry-run          # verify the file list
+npm publish --access public
+```

package/generate-kanban.mjs

@@ -0,0 +1,205 @@
+#!/usr/bin/env node
+/**
+ * generate-kanban.mjs — the shared per-project Kanban generator (T2) and its
+ * per-repo drift-gate (T5).
+ *
+ * One generator, run inside each project repo. It builds a single self-contained
+ * board from the project's backlog (via a pluggable adapter) and an optional
+ * content override, deriving every ticket's status from the backlog + dependency
+ * graph rather than trusting a hand-maintained column. The board is committed to
+ * the repo and published to its Pages site; a CI drift-gate (`--check`) fails if a
+ * commit lets the board diverge from a fresh generation — the same fourth-wall
+ * guard the exemplar's `npm run verify` provides.
+ *
+ * USAGE
+ *   node generate-kanban.mjs [options]           # write / refresh the board
+ *   node generate-kanban.mjs --check [options]    # fail (exit 1) if the board is stale
+ *
+ * OPTIONS (all optional; sensible defaults for a standard project layout)
+ *   --project <name>   project id (default: basename of --cwd)
+ *   --backlog <path>   backlog file       (default: docs/backlog.md)
+ *   --override <path>  content override   (default: docs/kanban-content.json)
+ *   --adr <dir>        ADR directory      (default: docs/adr)
+ *   --dialect <name>   backlog adapter    (default: auth-table; or risk-block)
+ *   --board <path>     board file         (default: {project}_implementation-kanban_v1.html)
+ *   --title <text>     board heading      (default: "{project} — Implementation Kanban v1")
+ *   --cwd <dir>        base directory for all relative paths (default: process.cwd())
+ *
+ * A run FAILS (exit 1) in either mode on any of: an unparseable backlog (adapter
+ * parsed zero tickets), an override id absent from the backlog, an override
+ * carrying header fields, an unresolved ADR citation, or a non-deterministic
+ * render. `--check` additionally fails on a missing or stale board.
+ */
+import { readFileSync, writeFileSync, existsSync } from 'node:fs';
+import { basename, resolve } from 'node:path';
+import { parseBacklog } from './lib/adapters.mjs';
+import { deriveAll, computeStats, IN_FLIGHT } from './lib/derive-status.mjs';
+import { loadOverride, validateOverride, mergeContent, resolveAdrCitations } from './lib/override.mjs';
+import { renderBoard, extractPayload } from './lib/render.mjs';
+
+const FIXED = '1970-01-01 00:00:00Z'; // stand-in timestamp for the determinism self-check
+
+export function parseArgs(argv) {
+  const opts = { check: false };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--check') opts.check = true;
+    else if (a.startsWith('--')) opts[a.slice(2)] = argv[++i];
+  }
+  return opts;
+}
+
+function stamp() {
+  return new Date().toISOString().replace('T', ' ').replace(/\.\d+Z$/, 'Z');
+}
+
+/**
+ * The board is always written with LF, but a committed board can arrive with CRLF
+ * (a repo with core.autocrlf, or an editor). The drift-gate compares CONTENT, not
+ * line-ending encoding, so both sides are normalised before comparison.
+ */
+function normalizeEol(s) {
+  return s.replace(/\r\n/g, '\n');
+}
+
+/**
+ * Build the derived tickets and stats from the current inputs. Returns everything
+ * the caller needs to render, plus any validation problems (empty = clean).
+ */
+function build(paths) {
+  const backlogText = readFileSync(paths.backlog, 'utf8');
+  const { tickets: header, graphDerived } = parseBacklog(backlogText, paths.dialect); // throws (fail loud) on unparseable / empty
+
+  const override = loadOverride(paths.override);
+  const problems = validateOverride(override, header.map((t) => t.id));
+
+  let derived;
+  if (graphDerived) {
+    // Graph-derived dialect: Ready/Backlog are recomputed. Preserve a human-set
+    // In Progress / In Review sourced from the committed board.
+    const prior = new Map();
+    if (existsSync(paths.board)) {
+      for (const t of extractPayload(readFileSync(paths.board, 'utf8'), 'payload-tickets')) {
+        if (IN_FLIGHT.has(t.status)) prior.set(t.id, t.status);
+      }
+    }
+    derived = deriveAll(header, prior);
+  } else {
+    // Pre-classified dialect: the adapter authored the final status; pass through.
+    derived = header.map((t) => ({ ...t }));
+  }
+  const tickets = mergeContent(derived, override);
+  const stats = computeStats(tickets);
+  problems.push(...resolveAdrCitations(tickets, paths.adr));
+
+  return { tickets, stats, problems };
+}
+
+function render(paths, tickets, stats, generatedAt) {
+  return renderBoard({ project: paths.project, title: paths.title, tickets, stats, generatedAt });
+}
+
+/** Concise human diff between a committed board and a freshly derived one. */
+function describeDrift(committedHtml, tickets, stats) {
+  const lines = [];
+  try {
+    const wasTickets = extractPayload(committedHtml, 'payload-tickets');
+    const wasById = new Map(wasTickets.map((t) => [t.id, t]));
+    const nowIds = new Set(tickets.map((t) => t.id));
+    for (const t of tickets) {
+      const was = wasById.get(t.id);
+      if (!was) lines.push(`[ticket] ${t.id} is new in the backlog and absent from the board`);
+      else if (was.status !== t.status) lines.push(`[status] ${t.id}: ${was.status} -> ${t.status}`);
+    }
+    for (const t of wasTickets) if (!nowIds.has(t.id)) lines.push(`[ticket] ${t.id} is on the board but gone from the backlog`);
+    const wasStats = extractPayload(committedHtml, 'payload-stats');
+    if (JSON.stringify(wasStats.byStatus) !== JSON.stringify(stats.byStatus)) {
+      lines.push(`[stats] byStatus ${JSON.stringify(wasStats.byStatus)} -> ${JSON.stringify(stats.byStatus)}`);
+    }
+  } catch {
+    lines.push('[board] committed board payloads could not be read for a detailed diff');
+  }
+  return lines;
+}
+
+export function run(argv, env = {}) {
+  const log = env.log || ((s) => console.log(s));
+  const err = env.err || ((s) => console.error(s));
+  const opts = parseArgs(argv);
+  const cwd = resolve(opts.cwd || env.cwd || process.cwd());
+  const project = opts.project || basename(cwd);
+  const paths = {
+    project,
+    title: opts.title,
+    dialect: opts.dialect || 'auth-table',
+    backlog: resolve(cwd, opts.backlog || 'docs/backlog.md'),
+    override: resolve(cwd, opts.override || 'docs/kanban-content.json'),
+    adr: resolve(cwd, opts.adr || 'docs/adr'),
+    board: resolve(cwd, opts.board || `${project}_implementation-kanban_v1.html`),
+  };
+
+  let result;
+  try {
+    result = build(paths);
+  } catch (e) {
+    err(`kanban: FAILED — ${e.message}`);
+    return 1;
+  }
+  const { tickets, stats, problems } = result;
+
+  // Determinism self-check: identical inputs must render byte-identical output
+  // (generatedAt excluded by holding it fixed). Guards against accidental
+  // nondeterministic ordering before anything is written or gated.
+  if (render(paths, tickets, stats, FIXED) !== render(paths, tickets, stats, FIXED)) {
+    err('kanban: FAILED — render is non-deterministic on unchanged inputs');
+    return 1;
+  }
+
+  for (const p of problems) log(`  [content] ${p}`);
+  if (problems.length) {
+    err(`\nkanban: FAILED — ${problems.length} content problem(s); the board was not ${opts.check ? 'gated' : 'written'}.`);
+    return 1;
+  }
+
+  const committed = existsSync(paths.board) ? readFileSync(paths.board, 'utf8') : null;
+
+  if (opts.check) {
+    if (committed === null) {
+      err(`kanban: FAILED — no committed board at ${paths.board}; run the generator and commit it.`);
+      return 1;
+    }
+    const committedAt = extractPayload(committed, 'payload-stats').generatedAt;
+    const fresh = render(paths, tickets, stats, committedAt); // reuse timestamp -> excluded from diff
+    if (normalizeEol(fresh) !== normalizeEol(committed)) {
+      for (const line of describeDrift(committed, tickets, stats)) log(`  ${line}`);
+      err(`\nkanban: FAILED — ${basename(paths.board)} is out of step with the backlog. Regenerate and commit.`);
+      return 1;
+    }
+    log(`kanban: in sync — ${tickets.length} ticket(s), ${statusSummary(stats)}.`);
+    return 0;
+  }
+
+  // Write mode: idempotent. If the only thing that would change is the timestamp,
+  // leave the board untouched so re-running never churns the diff.
+  if (committed !== null) {
+    const committedAt = extractPayload(committed, 'payload-stats').generatedAt;
+    if (normalizeEol(render(paths, tickets, stats, committedAt)) === normalizeEol(committed)) {
+      log(`kanban: already in sync — nothing to write (${tickets.length} ticket(s)).`);
+      return 0;
+    }
+  }
+  const drift = committed ? describeDrift(committed, tickets, stats) : [];
+  writeFileSync(paths.board, render(paths, tickets, stats, stamp()));
+  for (const line of drift) log(`  ${line}`);
+  log(`kanban: ${committed ? 'updated' : 'created'} ${basename(paths.board)} — ${tickets.length} ticket(s), ${statusSummary(stats)}.`);
+  return 0;
+}
+
+function statusSummary(stats) {
+  return Object.entries(stats.byStatus).map(([k, v]) => `${v} ${k}`).join(' / ');
+}
+
+// CLI entry (only when run directly, not when imported by tests).
+if (import.meta.url === `file://${process.argv[1]}` || process.argv[1]?.endsWith('generate-kanban.mjs')) {
+  process.exit(run(process.argv.slice(2)));
+}

package/lib/adapters.mjs

@@ -0,0 +1,164 @@
+/**
+ * Backlog adapters: turn a project's human-authored backlog into header tickets.
+ *
+ * An adapter is pluggable and MUST fail loudly on a backlog it cannot parse — a
+ * silently-empty board is the failure mode this whole tool exists to prevent, so
+ * "parsed zero tickets" is an error, never an empty success.
+ *
+ * A header ticket carries only what the backlog authors:
+ *   { id, title, type?, priority?, score?, phase?, blockedBy[], backlogStatus,
+ *     inFlight? }
+ * Body fields (description, acceptance, spec, adr, assignee) come from the
+ * optional content override, never from the backlog.
+ *
+ * `backlogStatus` is one of Done | Parked | Ready | Backlog.
+ *
+ * A dialect is either GRAPH-DERIVED or PRE-CLASSIFIED:
+ *   - graph-derived (auth-table): the backlog authors Done/Parked but NOT
+ *     Ready/Backlog; those are recomputed from the dependency graph by
+ *     derive-status.mjs. This is the shipping path.
+ *   - pre-classified (risk-block): the backlog authors the whole status directly
+ *     (a risk has no dependency edges, so "BLOCKED" is a human decision, not a
+ *     graph property). Such an adapter emits a final `status` and the generator
+ *     passes it through without graph recomputation.
+ */
+
+/** Pull every backticked `TOKEN` out of a table cell, in order. */
+function backtickedIds(cell) {
+  return [...cell.matchAll(/`([^`]+)`/g)].map((m) => m[1]);
+}
+
+/**
+ * auth-table (REQUIRED, the shipping dialect).
+ *
+ * Reads 7-column Markdown rows shaped exactly:
+ *   | ID | Ticket | Type | Priority | Tier | Blocked by | Status |
+ * A line is a ticket row iff its first cell is a single backticked id AND the row
+ * has exactly seven cells — which keeps us clear of closure-record tables, prose
+ * tables, and the summary tables that share the file.
+ *
+ * Status is keyword-classified, not matched exactly, because the Status cell
+ * carries dates, ADR references and explanatory clauses alongside the word.
+ * Parked is tested FIRST so "Parked (..., see ADR-0005)" cannot be misread as
+ * anything else; then Done, then Ready, else Backlog. blockedBy is read from the
+ * "Blocked by" cell (cell 6). Tier (cell 5) is informational and not carried:
+ * it duplicates Priority and is not a canonical ticket field.
+ *
+ * `phase` (D7) is derived structurally, not from a cell: the backlog groups its
+ * ticket tables under "Phase N" section headings (e.g. "### Phase 3 — Core
+ * implementation"). Scanning top-to-bottom, the most recent such heading sets the
+ * phase for every ticket row beneath it, until the next heading resets it. Rows
+ * before any Phase heading get no phase. `phase` is a backlog-owned header field,
+ * so it comes from here and never from the content override.
+ */
+export function authTable(text) {
+  const tickets = [];
+  let phase; // current phase from the most recent "Phase N" heading; unset before the first
+  for (const line of text.split(/\r?\n/)) {
+    const phaseHeading = line.match(/^#{1,4}\s+Phase\s+(\d+)\b/);
+    if (phaseHeading) {
+      phase = Number(phaseHeading[1]);
+      continue;
+    }
+    // Fast reject: first cell must open with a backticked id.
+    if (!/^\|\s*`[^`]+`\s*\|/.test(line)) continue;
+    const cells = line.trim().replace(/^\||\|$/g, '').split('|').map((c) => c.trim());
+    if (cells.length !== 7) continue;
+
+    const idMatch = cells[0].match(/^`([^`]+)`$/);
+    if (!idMatch) continue; // first cell is more than a bare id -> not a ticket row
+    const id = idMatch[1];
+
+    const statusCell = cells[6];
+    const backlogStatus = /\bParked\b/.test(statusCell)
+      ? 'Parked'
+      : /\bDone\b/.test(statusCell)
+        ? 'Done'
+        : /\bReady\b/.test(statusCell)
+          ? 'Ready'
+          : 'Backlog';
+
+    const emptyish = (s) => s === '' || s === '-' || s === '—'; // '' | '-' | em dash
+    tickets.push({
+      id,
+      title: cells[1],
+      ...(emptyish(cells[2]) ? {} : { type: cells[2] }),
+      ...(emptyish(cells[3]) ? {} : { priority: cells[3] }),
+      ...(phase !== undefined ? { phase } : {}),
+      blockedBy: emptyish(cells[5]) ? [] : backtickedIds(cells[5]),
+      backlogStatus,
+    });
+  }
+  return tickets;
+}
+
+/**
+ * risk-block (SCAFFOLD ONLY, PRE-CLASSIFIED — not the shipping path).
+ *
+ * Reads a templated risk backlog of the shape:
+ *   #### Risk #3: Some risk title — Score: 21
+ *   **Status:** IN PROGRESS
+ * Ids are synthesised as RISK-<N>. The authored status maps straight to a final
+ * column (no graph recomputation — a risk has no dependency edges):
+ *   COMPLETE    -> Done
+ *   IN PROGRESS -> In Progress
+ *   READY START -> Ready
+ *   BLOCKED     -> Backlog
+ * `backlogStatus` (the canonical four-value field) is set to the nearest of
+ * Done | Ready | Backlog for schema completeness.
+ *
+ * Scaffold status: parsing and mapping are implemented and unit-tested, but this
+ * dialect carries no phase and no dependency edges, so its boards are header-only
+ * queues. The drift-gate and every migrated repo use auth-table.
+ */
+export function riskBlock(text) {
+  const tickets = [];
+  const re = /^####\s+Risk\s+#(\d+):\s*(.+?)\s*[—-]\s*Score:\s*(\d+)\s*$/gm;
+  let m;
+  while ((m = re.exec(text)) !== null) {
+    const [, n, title, score] = m;
+    // The Status line is the first **Status:** after this heading.
+    const statusLine = text.slice(re.lastIndex).match(/^\s*\*\*Status:\*\*\s*(.+)$/m);
+    const word = statusLine ? statusLine[1].trim().toUpperCase() : '';
+    let status = 'Backlog';
+    let backlogStatus = 'Backlog';
+    if (/\bCOMPLETE\b/.test(word)) (status = 'Done'), (backlogStatus = 'Done');
+    else if (/\bIN\s+PROGRESS\b/.test(word)) (status = 'In Progress'), (backlogStatus = 'Ready');
+    else if (/\bREADY\s+START\b/.test(word)) (status = 'Ready'), (backlogStatus = 'Ready');
+    else if (/\bBLOCKED\b/.test(word)) (status = 'Backlog'), (backlogStatus = 'Backlog');
+    tickets.push({ id: `RISK-${n}`, title, score: Number(score), blockedBy: [], backlogStatus, status });
+  }
+  return tickets;
+}
+
+/**
+ * Adapter registry. `graphDerived` decides whether derive-status.mjs recomputes
+ * Ready/Backlog from the dependency graph (true) or the adapter's authored
+ * `status` is passed through unchanged (false).
+ */
+export const ADAPTERS = {
+  'auth-table': { parse: authTable, graphDerived: true },
+  'risk-block': { parse: riskBlock, graphDerived: false },
+};
+
+/**
+ * Run the named adapter and enforce the fail-loudly contract.
+ * @returns {{tickets:Array, graphDerived:boolean}}
+ * @throws if the dialect is unknown or the adapter parses zero tickets.
+ */
+export function parseBacklog(text, dialect) {
+  const adapter = ADAPTERS[dialect];
+  if (!adapter) {
+    throw new Error(
+      `unknown backlog dialect '${dialect}' — expected one of: ${Object.keys(ADAPTERS).join(', ')}`,
+    );
+  }
+  const tickets = adapter.parse(text);
+  if (tickets.length === 0) {
+    throw new Error(
+      `backlog dialect '${dialect}' parsed zero tickets — the backlog is unparseable or empty; ` +
+        'a silently-empty board is never an acceptable success.',
+    );
+  }
+  return { tickets, graphDerived: adapter.graphDerived };
+}

package/lib/derive-status.mjs

@@ -0,0 +1,96 @@
+/**
+ * Status derivation and stats recomputation for the shared Kanban generator.
+ *
+ * This is the load-bearing rule, carried over VERBATIM from the auth-separation
+ * exemplar's scripts/sync-kanban-status.mjs (see that file's header for the full
+ * rationale and the two hand-closure traps that produced it). The single change
+ * here is generalisation: the exemplar hard-codes `AUTH-` ids and reads a board
+ * payload; this module takes plain data so any project's backlog can drive it.
+ *
+ * WHERE AUTHORITY LIVES — unchanged from the exemplar:
+ *   the backlog       owns which tickets are Done and which are Parked (human
+ *                     decisions, classified by the adapter).
+ *   the content graph owns each ticket's dependency edges (blockedBy).
+ *   Ready vs Backlog  is authored by NEITHER — it is derived from the two above.
+ *
+ * PARKED is scope, not progress. A parked ticket never derives to Ready however
+ * its dependencies resolve, because dependency-readiness and being-in-scope are
+ * different questions. SCOPE BEATS DEPENDENCY-READINESS.
+ *
+ * Readiness is a property of the whole graph and must be computed, never
+ * transcribed, and it is NEVER derived from `blocks` — only from `blockedBy`.
+ */
+
+/**
+ * Column order, left to right. Parked sits after Done, outside the
+ * Backlog -> Done flow, because it is not a stage of that flow: parked tickets
+ * are out of scope, not queued. This order is mirrored by the board renderer.
+ */
+export const COLUMNS = ['Backlog', 'Ready', 'In Progress', 'In Review', 'Done', 'Parked'];
+
+/** Statuses a human sets deliberately (on the board, or in an in-flight-aware
+ *  backlog dialect); derivation preserves them rather than overwriting them. */
+export const IN_FLIGHT = new Set(['In Progress', 'In Review']);
+
+/**
+ * Derive one ticket's column.
+ *
+ * @param {{id:string, blockedBy:string[]}} ticket
+ * @param {Set<string>} done    ids the backlog marks Done
+ * @param {Set<string>} parked  ids the backlog marks Parked
+ * @param {string|undefined} prior  the ticket's previous board status, used only
+ *   to preserve a human-set In Progress / In Review; anything else is ignored.
+ * @returns {string} one of COLUMNS
+ */
+export function deriveStatus(ticket, done, parked, prior) {
+  if (done.has(ticket.id)) return 'Done';
+  // Scope beats dependency-readiness: an out-of-scope ticket is not startable
+  // no matter what its blockers have done.
+  if (parked.has(ticket.id)) return 'Parked';
+  // A human moved this card into an in-flight lane; never clobber that.
+  if (IN_FLIGHT.has(prior)) return prior;
+  // Readiness is computed from the graph, never transcribed, and only from
+  // blockedBy — never from `blocks`.
+  return ticket.blockedBy.every((d) => done.has(d)) ? 'Ready' : 'Backlog';
+}
+
+/**
+ * Apply {@link deriveStatus} across a ticket list, returning a new list with each
+ * ticket's `status` set. Input order is preserved (determinism).
+ *
+ * @param {Array} tickets  header tickets carrying id, blockedBy, backlogStatus
+ * @param {Map<string,string>} [prior]  id -> previous board status (in-flight preservation)
+ */
+export function deriveAll(tickets, prior = new Map()) {
+  const done = new Set(tickets.filter((t) => t.backlogStatus === 'Done').map((t) => t.id));
+  const parked = new Set(tickets.filter((t) => t.backlogStatus === 'Parked').map((t) => t.id));
+  return tickets.map((t) => ({ ...t, status: deriveStatus(t, done, parked, prior.get(t.id)) }));
+}
+
+/**
+ * Recompute the stats payload from derived tickets. Field order is fixed so the
+ * serialised JSON is deterministic. `generatedAt` is intentionally excluded here
+ * and stamped by the caller — it is the one field excluded from the drift diff.
+ *
+ * byStatus follows COLUMN order and omits empty columns. byPhase / byPriority /
+ * byType tally only tickets that carry that field (no `undefined` bucket).
+ */
+export function computeStats(tickets) {
+  const tally = (key) => {
+    const acc = {};
+    for (const t of tickets) {
+      const v = t[key];
+      if (v === undefined || v === null) continue;
+      acc[v] = (acc[v] ?? 0) + 1;
+    }
+    return acc;
+  };
+  const statusCounts = tally('status');
+  return {
+    total: tickets.length,
+    byStatus: Object.fromEntries(COLUMNS.filter((c) => statusCounts[c]).map((c) => [c, statusCounts[c]])),
+    byPhase: tally('phase'),
+    byPriority: tally('priority'),
+    byType: tally('type'),
+  };
+}

package/lib/override.mjs

@@ -0,0 +1,162 @@
+/**
+ * Content override: the optional, per-project body of each ticket.
+ *
+ * The backlog owns a ticket's header (id, title, type, priority, score, phase,
+ * dependency edges, status). The override — docs/kanban-content.json by default —
+ * owns only its BODY: the prose a card expands to. Keeping them apart is decision
+ * D5: one shared generator, plus an optional per-project content file, so a board
+ * can carry rich acceptance criteria without forking the generator.
+ *
+ * The split is enforced, not merely documented:
+ *   - an override entry for an id the backlog does not list is a HARD ERROR (a
+ *     card body with no card is always a mistake — a typo'd id, or content left
+ *     behind when a ticket was renamed);
+ *   - a backlog id with no override entry is FINE (a header-only card);
+ *   - an override entry may carry ONLY body fields. Any header field
+ *     (status, backlogStatus, blockedBy, title, type, priority, score, phase,
+ *     blocks, id) in the override is a hard error: it would let content quietly
+ *     contradict the backlog, which is exactly the drift this tool prevents.
+ */
+import { readFileSync, existsSync, readdirSync } from 'node:fs';
+
+/** The only keys an override entry may carry. */
+export const BODY_FIELDS = ['description', 'acceptance', 'spec', 'adr', 'assignee'];
+const BODY_SET = new Set(BODY_FIELDS);
+const ADR_ID_RE = /^ADR-\d{4}$/;
+
+/** Load and JSON-parse the override file. Absent file -> {} (overrides optional). */
+export function loadOverride(path) {
+  if (!existsSync(path)) return {};
+  let raw;
+  try {
+    raw = readFileSync(path, 'utf8');
+  } catch (e) {
+    throw new Error(`override: cannot read ${path}: ${e.message}`);
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (e) {
+    throw new Error(`override: ${path} is not valid JSON: ${e.message}`);
+  }
+  if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    throw new Error(`override: ${path} must be a JSON object keyed by ticket id`);
+  }
+  return parsed;
+}
+
+/**
+ * Validate the override against the set of backlog ids. Returns a list of problem
+ * strings (empty = clean); the caller decides that any problem fails the run.
+ */
+export function validateOverride(override, backlogIds) {
+  const ids = new Set(backlogIds);
+  const problems = [];
+  for (const [id, body] of Object.entries(override)) {
+    if (!ids.has(id)) {
+      problems.push(`override names ${id}, which is not a ticket in the backlog`);
+      continue;
+    }
+    if (body === null || typeof body !== 'object' || Array.isArray(body)) {
+      problems.push(`override entry ${id} must be an object of body fields`);
+      continue;
+    }
+    for (const key of Object.keys(body)) {
+      if (!BODY_SET.has(key)) {
+        problems.push(
+          `override entry ${id} carries non-body field '${key}' — the override may hold only ` +
+            `${BODY_FIELDS.join(', ')} (header fields are owned by the backlog)`,
+        );
+      }
+    }
+    if ('acceptance' in body && !(Array.isArray(body.acceptance) && body.acceptance.every((a) => typeof a === 'string'))) {
+      problems.push(`override entry ${id}: acceptance must be an array of strings`);
+    }
+    if ('adr' in body) {
+      if (!Array.isArray(body.adr)) {
+        problems.push(`override entry ${id}: adr must be an array of ADR-nnnn ids`);
+      } else {
+        for (const ref of body.adr) {
+          if (typeof ref !== 'string' || !ADR_ID_RE.test(ref)) {
+            problems.push(`override entry ${id}: adr entry '${ref}' must match ADR-nnnn (four digits)`);
+          }
+        }
+      }
+    }
+  }
+  return problems;
+}
+
+/**
+ * Merge body fields onto header tickets, and compute `blocks` as the reverse of
+ * the blockedBy graph. `blocks` is DISPLAY-ONLY: derive-status.mjs never reads it,
+ * so populating it cannot affect readiness. Output field order is fixed for
+ * deterministic serialisation.
+ */
+export function mergeContent(headerTickets, override) {
+  // Reverse edges: b in blocks[a] iff a in blockedBy[b].
+  const blocks = new Map(headerTickets.map((t) => [t.id, []]));
+  for (const t of headerTickets) {
+    for (const dep of t.blockedBy) {
+      if (blocks.has(dep)) blocks.get(dep).push(t.id);
+    }
+  }
+  return headerTickets.map((t) => {
+    const body = override[t.id] ?? {};
+    const out = {
+      id: t.id,
+      title: t.title,
+      ...(t.type !== undefined ? { type: t.type } : {}),
+      ...(t.priority !== undefined ? { priority: t.priority } : {}),
+      ...(t.score !== undefined ? { score: t.score } : {}),
+      ...(t.phase !== undefined ? { phase: t.phase } : {}),
+      blockedBy: t.blockedBy,
+      blocks: blocks.get(t.id),
+      backlogStatus: t.backlogStatus,
+      status: t.status,
+      ...(body.description !== undefined ? { description: body.description } : {}),
+      ...(body.acceptance !== undefined ? { acceptance: body.acceptance } : {}),
+      ...(body.spec !== undefined ? { spec: body.spec } : {}),
+      ...(body.adr !== undefined ? { adr: body.adr } : {}),
+      ...(body.assignee !== undefined ? { assignee: body.assignee } : {}),
+    };
+    return out;
+  });
+}
+
+/**
+ * Resolve every ADR citation to a file in the ADR directory. A citation is any
+ * `ADR-nnnn` appearing anywhere in a ticket (adr[] list, spec note, description).
+ * Ported from the exemplar's validate-kanban-content.mjs check 2: it catches
+ * typos, renumbering, and deletions.
+ *
+ * Returns a list of problem strings. If the ADR directory is absent, citations
+ * are a problem (they point nowhere); no citations and no directory is clean.
+ */
+export function resolveAdrCitations(tickets, adrDir) {
+  const cited = new Map(); // ADR-nnnn -> [ticket ids]
+  for (const t of tickets) {
+    for (const ref of new Set(JSON.stringify(t).match(/ADR-\d{4}/g) ?? [])) {
+      if (!cited.has(ref)) cited.set(ref, []);
+      cited.get(ref).push(t.id);
+    }
+  }
+  if (cited.size === 0) return [];
+
+  const adrFiles = existsSync(adrDir)
+    ? readdirSync(adrDir).filter((f) => /^\d{4}-.*\.md$/.test(f))
+    : null;
+  const problems = [];
+  for (const [ref, ids] of cited) {
+    const number = ref.slice(4); // strip "ADR-"
+    const exists = adrFiles && adrFiles.some((f) => f.startsWith(number));
+    if (!exists) {
+      problems.push(
+        adrFiles === null
+          ? `${ids.join(', ')} cite ${ref}, but no ADR directory exists at ${adrDir}/`
+          : `${ids.join(', ')} cite ${ref}, which has no file in ${adrDir}/`,
+      );
+    }
+  }
+  return problems;
+}

package/lib/render.mjs

@@ -0,0 +1,277 @@
+/**
+ * Self-contained board renderer.
+ *
+ * D6 decision (recorded in tools/kanban/DECISION-render-stack.md): the board is a
+ * single HTML file with a vanilla-JS renderer reading two embedded JSON payloads.
+ * No framework, no build step, no CDN, no vendored files — the exemplar's
+ * React + ~2.8MB babel-standalone stack could not satisfy the "one self-contained
+ * board" contract without inlining megabytes of transpiler into every repo's
+ * committed board. The status logic ported to vanilla with no rewrite.
+ *
+ * The two payload script blocks (`payload-tickets`, `payload-stats`) are the
+ * board's data of record and the anchor the drift-gate reads back, so their
+ * shape and ids match the exemplar exactly.
+ */
+
+export const PAYLOAD_IDS = ['payload-tickets', 'payload-stats'];
+
+/** Extract and parse an embedded JSON payload. Throws if the block is absent. */
+export function extractPayload(html, id) {
+  const m = html.match(new RegExp(`id="${id}" type="application/json">([\\s\\S]*?)</script>`));
+  if (!m) throw new Error(`no <script id="${id}"> payload found in board`);
+  return JSON.parse(m[1]);
+}
+
+/**
+ * Serialise a payload for embedding. `<` is escaped to its JSON unicode form so a
+ * ticket body containing "</script>" cannot break out of the script block; the
+ * result is still valid JSON and still deterministic.
+ */
+function embed(value) {
+  return JSON.stringify(value).replace(/</g, '\\u003c');
+}
+
+// The renderer that ships inside every board. Kept as a plain string so the
+// generator has no runtime dependency on a bundler. It reads the two payloads and
+// builds the DOM; every ticket field except id/title/status is treated as
+// optional so header-only cards (no override) render cleanly.
+const BOARD_SCRIPT = String.raw`
+(function () {
+  var TICKETS = JSON.parse(document.getElementById('payload-tickets').textContent);
+  var STATS = JSON.parse(document.getElementById('payload-stats').textContent);
+  var COLUMNS = ['Backlog', 'Ready', 'In Progress', 'In Review', 'Done', 'Parked'];
+  var PRIORITY_ORDER = { P0: 0, P1: 1, P2: 2, P3: 3 };
+  var byId = {};
+  TICKETS.forEach(function (t) { byId[t.id] = t; });
+
+  function esc(s) {
+    return String(s == null ? '' : s).replace(/[&<>"']/g, function (c) {
+      return { '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }[c];
+    });
+  }
+  function priClass(p) { return p ? 'tag-' + String(p).toLowerCase() : ''; }
+  function el(html) { var d = document.createElement('div'); d.innerHTML = html.trim(); return d.firstChild; }
+
+  var state = { phase: 'all', priority: 'all', type: 'all', search: '' };
+
+  function passes(t) {
+    if (state.phase !== 'all' && String(t.phase) !== state.phase) return false;
+    if (state.priority !== 'all' && t.priority !== state.priority) return false;
+    if (state.type !== 'all' && t.type !== state.type) return false;
+    var s = state.search.trim().toLowerCase();
+    if (s && [t.id, t.title, t.type, t.phase].join(' ').toLowerCase().indexOf(s) === -1) return false;
+    return true;
+  }
+
+  function cardHtml(t) {
+    var unmet = (t.blockedBy || []).filter(function (d) { return !(byId[d] && byId[d].status === 'Done'); });
+    var tags = '';
+    if (t.priority) tags += '<span class="tag ' + priClass(t.priority) + '">' + esc(t.priority) + '</span>';
+    if (t.type) tags += '<span class="tag tag-type">' + esc(t.type) + '</span>';
+    if (unmet.length) tags += '<span class="tag tag-blocked">Blocked: ' + unmet.length + '</span>';
+    var sub = [];
+    if (t.phase !== undefined) sub.push('Phase ' + esc(t.phase));
+    if (t.score !== undefined) sub.push('Score ' + esc(t.score));
+    return '<div class="card ' + (t.priority ? 'border-' + String(t.priority).toLowerCase() : '') + '" data-id="' + esc(t.id) + '">' +
+      '<div class="card-id">' + esc(t.id) + '</div>' +
+      '<div class="card-title">' + esc(t.title) + '</div>' +
+      (sub.length ? '<div class="card-feature">' + sub.join(' · ') + '</div>' : '') +
+      '<div class="card-tags">' + tags + '</div>' +
+      ((t.blockedBy && t.blockedBy.length) ? '<div class="card-deps">Blocked by: ' + esc(t.blockedBy.join(', ')) + '</div>' : '') +
+      '</div>';
+  }
+
+  function renderBoard() {
+    var shown = TICKETS.filter(passes);
+    var cols = document.getElementById('board');
+    cols.innerHTML = '';
+    COLUMNS.forEach(function (col) {
+      var items = shown.filter(function (t) { return t.status === col; }).sort(function (a, b) {
+        var p = (PRIORITY_ORDER[a.priority] == null ? 9 : PRIORITY_ORDER[a.priority]) -
+                (PRIORITY_ORDER[b.priority] == null ? 9 : PRIORITY_ORDER[b.priority]);
+        return p !== 0 ? p : a.id.localeCompare(b.id);
+      });
+      var body = items.map(cardHtml).join('');
+      cols.appendChild(el(
+        '<div class="column"><div class="column-head"><span class="name">' + esc(col) +
+        '</span><span class="count">' + items.length + '</span></div>' +
+        '<div class="column-body">' + body + '</div></div>'
+      ));
+    });
+    document.getElementById('shown-count').textContent = shown.length + ' of ' + TICKETS.length + ' shown';
+    Array.prototype.forEach.call(cols.querySelectorAll('.card'), function (c) {
+      c.addEventListener('click', function () { openModal(byId[c.getAttribute('data-id')]); });
+    });
+  }
+
+  function section(title, inner) { return inner ? '<h3>' + esc(title) + '</h3>' + inner : ''; }
+  function depPills(ids, met) {
+    if (!ids || !ids.length) return '<em>None</em>';
+    return ids.map(function (d) {
+      var dep = byId[d];
+      var cls = met === undefined ? 'dep-pill' : ('dep-pill ' + ((dep && dep.status === 'Done') ? 'dep-pill-met' : 'dep-pill-unmet'));
+      return '<span class="' + cls + '">' + esc(d) + (dep ? ' - ' + esc(dep.title) : '') + '</span>';
+    }).join('');
+  }
+
+  function openModal(t) {
+    if (!t) return;
+    var tags = '';
+    if (t.priority) tags += '<span class="tag ' + priClass(t.priority) + '">' + esc(t.priority) + '</span>';
+    if (t.type) tags += '<span class="tag tag-type">' + esc(t.type) + '</span>';
+    if (t.phase !== undefined) tags += '<span class="tag tag-phase">Phase ' + esc(t.phase) + '</span>';
+    var body =
+      section('Description', t.description ? '<p>' + esc(t.description) + '</p>' : '') +
+      section('Assignee', t.assignee ? '<p>' + esc(t.assignee) + '</p>' : '') +
+      '<h3>Status</h3><p>' + esc(t.status) + '</p>' +
+      section('Acceptance Criteria', (t.acceptance && t.acceptance.length) ? '<ul>' + t.acceptance.map(function (a) { return '<li>' + esc(a) + '</li>'; }).join('') + '</ul>' : '') +
+      section('Spec / Implementation Notes', t.spec ? '<p>' + esc(t.spec) + '</p>' : '') +
+      section('ADRs', (t.adr && t.adr.length) ? '<p>' + t.adr.map(esc).join(', ') + '</p>' : '') +
+      '<h3>Blocked By (' + ((t.blockedBy || []).length) + ')</h3><div>' + depPills(t.blockedBy, false) + '</div>' +
+      '<h3>Blocks (' + ((t.blocks || []).length) + ')</h3><div>' + depPills(t.blocks, undefined) + '</div>';
+    var modal = el(
+      '<div class="modal-bg"><div class="modal"><div class="modal-head"><div>' +
+      '<div class="card-id">' + esc(t.id) + (t.phase !== undefined ? ' · Phase ' + esc(t.phase) : '') + '</div>' +
+      '<div style="font-size:18px;font-weight:700;margin-top:4px">' + esc(t.title) + '</div>' +
+      '<div style="display:flex;gap:6px;margin-top:8px">' + tags + '</div></div>' +
+      '<button class="close-btn">Close</button></div>' +
+      '<div class="modal-body">' + body + '</div></div></div>'
+    );
+    function close() { document.body.removeChild(modal); }
+    modal.addEventListener('click', close);
+    modal.querySelector('.modal').addEventListener('click', function (e) { e.stopPropagation(); });
+    modal.querySelector('.close-btn').addEventListener('click', close);
+    document.body.appendChild(modal);
+  }
+
+  function optionList(sel, values, label) {
+    values.forEach(function (v) {
+      var o = document.createElement('option');
+      o.value = v; o.textContent = label ? label(v) : v; sel.appendChild(o);
+    });
+  }
+
+  var phases = Array.from(new Set(TICKETS.map(function (t) { return t.phase; }).filter(function (p) { return p !== undefined; }))).sort(function (a, b) { return a - b; });
+  var types = Array.from(new Set(TICKETS.map(function (t) { return t.type; }).filter(Boolean))).sort();
+  var priorities = Array.from(new Set(TICKETS.map(function (t) { return t.priority; }).filter(Boolean))).sort();
+
+  if (phases.length) { optionList(document.getElementById('f-phase'), phases, function (p) { return 'Phase ' + p; }); document.getElementById('w-phase').hidden = false; }
+  if (priorities.length) { optionList(document.getElementById('f-priority'), priorities); document.getElementById('w-priority').hidden = false; }
+  if (types.length) { optionList(document.getElementById('f-type'), types); document.getElementById('w-type').hidden = false; }
+
+  document.getElementById('f-phase').addEventListener('change', function (e) { state.phase = e.target.value; renderBoard(); });
+  document.getElementById('f-priority').addEventListener('change', function (e) { state.priority = e.target.value; renderBoard(); });
+  document.getElementById('f-type').addEventListener('change', function (e) { state.type = e.target.value; renderBoard(); });
+  document.getElementById('f-search').addEventListener('input', function (e) { state.search = e.target.value; renderBoard(); });
+
+  renderBoard();
+})();
+`;
+
+const STYLE = String.raw`
+    :root {
+      --bg:#f8fafc; --panel:#fff; --border:#e2e8f0; --text:#1e293b; --muted:#64748b; --accent:#1f3864;
+      --p0:#dc2626; --p0-bg:#fee2e2; --p1:#ea580c; --p1-bg:#ffedd5;
+      --p2:#2563eb; --p2-bg:#dbeafe; --p3:#6b7280; --p3-bg:#f3f4f6;
+    }
+    * { box-sizing:border-box; }
+    body { margin:0; font-family:-apple-system,BlinkMacSystemFont,'Segoe UI',Roboto,sans-serif; background:var(--bg); color:var(--text); }
+    header { background:var(--accent); color:#fff; padding:14px 24px; }
+    header h1 { margin:0; font-size:20px; font-weight:600; }
+    header p { margin:4px 0 0; font-size:12px; opacity:.85; }
+    .stats { display:flex; gap:16px; padding:12px 24px; background:#fff; border-bottom:1px solid var(--border); flex-wrap:wrap; font-size:12px; }
+    .stat { display:flex; align-items:center; gap:6px; }
+    .stat .num { font-weight:700; font-size:16px; color:var(--accent); }
+    .stat .lbl { color:var(--muted); text-transform:uppercase; letter-spacing:.05em; font-size:10px; }
+    .filters { padding:10px 24px; background:#fff; border-bottom:1px solid var(--border); display:flex; gap:12px; align-items:center; flex-wrap:wrap; font-size:12px; }
+    .filters label { color:var(--muted); margin-right:4px; }
+    .filters select, .filters input { padding:4px 8px; border:1px solid var(--border); border-radius:4px; font-size:12px; background:#fff; }
+    .board { display:flex; gap:12px; padding:16px 24px; overflow-x:auto; min-height:calc(100vh - 200px); }
+    .column { flex:1; min-width:240px; max-width:320px; background:#f1f5f9; border-radius:8px; border:1px solid var(--border); display:flex; flex-direction:column; }
+    .column-head { padding:10px 12px; border-bottom:1px solid var(--border); display:flex; justify-content:space-between; align-items:center; }
+    .column-head .name { font-weight:600; font-size:13px; }
+    .column-head .count { background:var(--accent); color:#fff; font-size:11px; padding:1px 8px; border-radius:10px; font-weight:600; }
+    .column-body { padding:8px; flex:1; overflow-y:auto; }
+    .card { background:#fff; border:1px solid var(--border); border-radius:6px; padding:10px; margin-bottom:8px; cursor:pointer; transition:all .15s; border-left-width:4px; }
+    .card:hover { box-shadow:0 2px 6px rgba(0,0,0,.08); transform:translateY(-1px); }
+    .card-id { font-family:'SF Mono',Consolas,monospace; font-size:10px; color:var(--muted); font-weight:600; }
+    .card-title { font-size:13px; font-weight:600; margin:4px 0 6px; line-height:1.3; }
+    .card-feature { font-size:11px; color:var(--muted); margin-bottom:6px; }
+    .card-tags { display:flex; gap:4px; flex-wrap:wrap; }
+    .tag { font-size:9px; font-weight:700; padding:2px 6px; border-radius:3px; text-transform:uppercase; letter-spacing:.04em; }
+    .tag-p0 { background:var(--p0-bg); color:var(--p0); } .tag-p1 { background:var(--p1-bg); color:var(--p1); }
+    .tag-p2 { background:var(--p2-bg); color:var(--p2); } .tag-p3 { background:var(--p3-bg); color:var(--p3); }
+    .tag-type { background:#e0e7ff; color:#3730a3; } .tag-phase { background:#f0fdf4; color:#166534; }
+    .tag-blocked { background:#fef3c7; color:#92400e; }
+    .card-deps { font-size:10px; color:var(--muted); margin-top:6px; }
+    .border-p0 { border-left-color:var(--p0); } .border-p1 { border-left-color:var(--p1); }
+    .border-p2 { border-left-color:var(--p2); } .border-p3 { border-left-color:var(--p3); }
+    .modal-bg { position:fixed; inset:0; background:rgba(15,23,42,.5); display:flex; align-items:center; justify-content:center; z-index:100; padding:20px; }
+    .modal { background:#fff; border-radius:8px; max-width:800px; width:100%; max-height:90vh; overflow-y:auto; box-shadow:0 20px 50px rgba(0,0,0,.3); }
+    .modal-head { padding:16px 20px; border-bottom:1px solid var(--border); display:flex; justify-content:space-between; align-items:flex-start; gap:12px; }
+    .modal-body { padding:20px; font-size:13px; line-height:1.6; }
+    .modal-body h3 { font-size:12px; text-transform:uppercase; letter-spacing:.05em; color:var(--muted); margin:16px 0 6px; font-weight:600; }
+    .modal-body p { margin:4px 0 12px; } .modal-body ul { margin:4px 0 12px; padding-left:20px; } .modal-body li { margin:4px 0; }
+    .close-btn { background:transparent; border:1px solid var(--border); color:var(--muted); padding:4px 10px; border-radius:4px; cursor:pointer; font-size:12px; }
+    .close-btn:hover { background:#f1f5f9; }
+    .dep-pill { display:inline-block; background:#f1f5f9; border:1px solid var(--border); font-family:'SF Mono',Consolas,monospace; font-size:11px; padding:2px 6px; border-radius:3px; margin:2px 4px 2px 0; }
+    .dep-pill-met { background:#dcfce7; border-color:#86efac; color:#166534; }
+    .dep-pill-unmet { background:#fef3c7; border-color:#fcd34d; color:#92400e; }
+`;
+
+/**
+ * Render a complete, self-contained board document.
+ * @param {{project:string, title?:string, tickets:Array, stats:object, generatedAt:string}} opts
+ */
+export function renderBoard({ project, title, tickets, stats, generatedAt }) {
+  const heading = title || `${project} — Implementation Kanban v1`;
+  const statsPayload = { ...stats, generatedAt, version: '1' };
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  <title>${escHtml(heading)}</title>
+  <!--
+    Generated by tools/kanban/generate-kanban.mjs from the project backlog and the
+    optional content override. Do NOT hand-edit: a per-repo drift-gate regenerates
+    this file and fails CI if a commit diverges from a fresh generation. To change
+    the board, change the backlog or docs/kanban-content.json and regenerate.
+    Self-contained by design (D6): no framework, no CDN, no vendored files.
+  -->
+  <style>${STYLE}  </style>
+</head>
+<body>
+  <header>
+    <h1>${escHtml(heading)}</h1>
+    <p>Generated from the project backlog. ${stats.total} ticket(s).</p>
+  </header>
+  <div class="stats" id="stats-bar">
+    <div class="stat"><span class="num">${stats.total}</span><span class="lbl">Total</span></div>
+${COLUMN_STAT_CELLS(stats)}    <div class="stat" style="margin-left:auto;color:var(--muted)"><span class="lbl">v${statsPayload.version} · ${escHtml(generatedAt)}</span></div>
+  </div>
+  <div class="filters">
+    <span id="w-phase" hidden><label>Phase:</label><select id="f-phase"><option value="all">All phases</option></select></span>
+    <span id="w-priority" hidden><label>Priority:</label><select id="f-priority"><option value="all">All priorities</option></select></span>
+    <span id="w-type" hidden><label>Type:</label><select id="f-type"><option value="all">All types</option></select></span>
+    <label>Search:</label><input id="f-search" type="text" placeholder="ID, title, type..." style="min-width:200px" />
+    <span id="shown-count" style="margin-left:auto;color:var(--muted)"></span>
+  </div>
+  <div class="board" id="board"></div>
+  <script id="payload-tickets" type="application/json">${embed(tickets)}</script>
+  <script id="payload-stats" type="application/json">${embed(statsPayload)}</script>
+  <script>${BOARD_SCRIPT}</script>
+</body>
+</html>
+`;
+}
+
+function COLUMN_STAT_CELLS(stats) {
+  return Object.entries(stats.byStatus)
+    .map(([c, n]) => `    <div class="stat"><span class="num">${n}</span><span class="lbl">${escHtml(c)}</span></div>\n`)
+    .join('');
+}
+
+function escHtml(s) {
+  return String(s == null ? '' : s).replace(/[&<>"']/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }[c]));
+}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "portfolio-kanban-generator",
+  "version": "1.0.0",
+  "description": "Self-contained per-project implementation-Kanban board generator with a CI drift-gate (--check). Derives every ticket's status from the backlog + dependency graph; zero runtime dependencies (vanilla Node).",
+  "type": "module",
+  "bin": {
+    "generate-kanban": "generate-kanban.mjs"
+  },
+  "exports": {
+    ".": "./generate-kanban.mjs",
+    "./lib/*": "./lib/*"
+  },
+  "files": [
+    "generate-kanban.mjs",
+    "lib/",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "test": "node --test"
+  },
+  "keywords": [
+    "kanban",
+    "backlog",
+    "board-generator",
+    "drift-gate",
+    "ci",
+    "static-html",
+    "zero-dependency",
+    "test-automation-portfolio"
+  ],
+  "author": {
+    "name": "Gary Brooks"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/NeoCognitus70/portfolio-prompts.git",
+    "directory": "tools/kanban"
+  },
+  "homepage": "https://github.com/NeoCognitus70/portfolio-prompts/tree/main/tools/kanban#readme",
+  "bugs": {
+    "url": "https://github.com/NeoCognitus70/portfolio-prompts/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}