changeledger 0.3.0

package/src/commands/release.mjs

@@ -0,0 +1,138 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { withFileLock, writeFileAtomic } from '../atomic-write.mjs';
+import { nowUtc } from '../paths.mjs';
+import {
+  bumpVersion,
+  compareVersions,
+  parseVersion,
+  RELEASE_IMPACTS,
+  resolveReleasesDir,
+} from '../release.mjs';
+import { loadRepo } from '../repo.mjs';
+import { stringifyYaml } from '../yaml.mjs';
+
+const IMPACT_RANK = new Map(RELEASE_IMPACTS.map((impact, index) => [impact, index]));
+const ISO_UTC = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z$/;
+
+export function releasePlan(cwd = process.cwd()) {
+  const repo = loadRepo(cwd);
+  if (!repo.releases.length) {
+    throw new Error(
+      'Release history is not initialized. Run `changeledger release init <version>`.',
+    );
+  }
+
+  const currentVersion = latestVersion(repo.releases);
+  const releasedIds = new Set(
+    repo.releases.flatMap((release) => release.changes ?? []).map(String),
+  );
+  const changes = repo.changes
+    .filter((change) => change.frontmatter.status === 'done')
+    .filter((change) => !releasedIds.has(String(change.frontmatter.id)))
+    .map((change) => ({
+      id: String(change.frontmatter.id),
+      title: change.frontmatter.title,
+      type: change.frontmatter.type,
+      releaseImpact: effectiveImpact(change, repo.config),
+    }));
+
+  const impact = changes.reduce(
+    (highest, change) =>
+      IMPACT_RANK.get(change.releaseImpact) > IMPACT_RANK.get(highest)
+        ? change.releaseImpact
+        : highest,
+    'none',
+  );
+
+  return {
+    currentVersion,
+    nextVersion: impact === 'none' ? null : bumpVersion(currentVersion, impact),
+    impact,
+    releasable: impact !== 'none',
+    changes,
+  };
+}
+
+export function initReleaseHistory(version, cwd = process.cwd(), now = nowUtc()) {
+  parseVersion(version);
+  assertTimestamp(now);
+  const initial = loadRepo(cwd);
+  const releasesDir = resolveReleasesDir(initial.repoRoot);
+  fs.mkdirSync(releasesDir, { recursive: true });
+  const historyLock = path.join(releasesDir, '.history');
+
+  return withFileLock(historyLock, () => {
+    const repo = loadRepo(cwd);
+    if (repo.releases.length) throw new Error('Release history is already initialized.');
+    const manifest = {
+      version,
+      created: now,
+      baseline: true,
+      changes: repo.changes
+        .filter((change) => change.frontmatter.status === 'done')
+        .map((change) => String(change.frontmatter.id)),
+    };
+    const file = path.join(releasesDir, `${version}.yml`);
+    writeNewManifest(file, manifest);
+    return { file, manifest };
+  });
+}
+
+export function recordRelease(version, cwd = process.cwd(), now = nowUtc()) {
+  parseVersion(version);
+  assertTimestamp(now);
+  const initial = loadRepo(cwd);
+  const releasesDir = resolveReleasesDir(initial.repoRoot);
+  const historyLock = path.join(releasesDir, '.history');
+
+  return withFileLock(historyLock, () => {
+    const plan = releasePlan(cwd);
+    if (!plan.releasable) throw new Error('No releasable changes (highest impact is none).');
+    if (version !== plan.nextVersion) {
+      throw new Error(`Version "${version}" does not match the calculated ${plan.nextVersion}.`);
+    }
+    const manifest = {
+      version,
+      created: now,
+      changes: plan.changes.map((change) => change.id),
+    };
+    const file = path.join(releasesDir, `${version}.yml`);
+    writeNewManifest(file, manifest);
+    return { file, manifest, plan };
+  });
+}
+
+function latestVersion(releases) {
+  return [...releases]
+    .map((release) => release.version)
+    .sort(compareVersions)
+    .at(-1);
+}
+
+function effectiveImpact(change, config) {
+  const override = change.frontmatter.release_impact;
+  if (override !== undefined) {
+    if (!RELEASE_IMPACTS.includes(override)) {
+      throw new Error(`Change #${change.frontmatter.id} has invalid release_impact "${override}".`);
+    }
+    return override;
+  }
+  const impact = config.release?.impacts?.[change.frontmatter.type];
+  if (!RELEASE_IMPACTS.includes(impact)) {
+    throw new Error(
+      `Change #${change.frontmatter.id} type "${change.frontmatter.type}" has no valid release impact; configure release.impacts.${change.frontmatter.type} or set release_impact.`,
+    );
+  }
+  return impact;
+}
+
+function writeNewManifest(file, manifest) {
+  if (fs.existsSync(file))
+    throw new Error(`Release manifest already exists: ${path.basename(file)}`);
+  writeFileAtomic(file, stringifyYaml(manifest));
+}
+
+function assertTimestamp(value) {
+  if (!ISO_UTC.test(value)) throw new Error(`Invalid release timestamp "${value}"`);
+}

package/src/commands/view.mjs

@@ -0,0 +1,52 @@
+import { spawn } from 'node:child_process';
+import crypto from 'node:crypto';
+import http from 'node:http';
+import { resolveProjects } from '../viewer/domain.mjs';
+import { createRequestListener, staticFile } from '../viewer/server/router.mjs';
+import { hostnameOf, isAuthorizedWrite, isLocalHost } from '../viewer/server/security.mjs';
+
+export { changeStatus, resolveProjects, searchProjects, serialize } from '../viewer/domain.mjs';
+export { createRequestListener, hostnameOf, isAuthorizedWrite, isLocalHost, staticFile };
+
+export async function view(args = [], cwd = process.cwd()) {
+  const localOnly = args.includes('.');
+  resolveProjects(cwd, localOnly); // fail fast if local mode outside a repo
+
+  const token = crypto.randomBytes(16).toString('hex');
+  const server = http.createServer(createRequestListener(cwd, localOnly, token));
+  server.requestTimeout = 30_000;
+  server.headersTimeout = 10_000;
+
+  const host = '127.0.0.1';
+  const port = await listen(server, host, Number(args.find((a) => /^\d+$/.test(a))) || 4040);
+  const url = `http://${host}:${port}`;
+  console.log(`ChangeLedger viewer → ${url}  (Ctrl+C to stop)`);
+  openBrowser(url);
+}
+
+function listen(server, host, port, attempts = 10) {
+  return new Promise((resolve, reject) => {
+    const tryPort = (p, left) => {
+      server.once('error', (e) => {
+        if (e.code === 'EADDRINUSE' && left > 0) tryPort(p + 1, left - 1);
+        else reject(e);
+      });
+      server.listen(p, host, () => resolve(p));
+    };
+    tryPort(port, attempts);
+  });
+}
+
+function openBrowser(url) {
+  const cmd =
+    process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'start' : 'xdg-open';
+  try {
+    spawn(cmd, [url], {
+      stdio: 'ignore',
+      detached: true,
+      shell: process.platform === 'win32',
+    }).unref();
+  } catch {
+    // best-effort; the URL is printed above
+  }
+}

package/src/config.mjs

@@ -0,0 +1,76 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { parseYaml } from './yaml.mjs';
+
+// Walk up from `start` looking for a `.changeledger/` directory. Returns its absolute path
+// or null if none is found.
+export function findChangeledgerDir(start = process.cwd()) {
+  let dir = path.resolve(start);
+  for (;;) {
+    const candidate = path.join(dir, '.changeledger');
+    if (fs.existsSync(candidate) && fs.statSync(candidate).isDirectory()) return candidate;
+    const parent = path.dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+export function loadConfig(changeledgerDir) {
+  const file = path.join(changeledgerDir, 'config.yml');
+  if (!fs.existsSync(file)) throw new Error(`Missing config: ${file}`);
+  return parseYaml(fs.readFileSync(file, 'utf8'));
+}
+
+// Resolves a configured directory (changes_dir/specs_dir) against the repo root,
+// refusing any value that escapes it. A cloned repo's config is untrusted input:
+// running a command must not let it read or write outside the repo it discovered.
+// Absolute paths and `..` traversal are rejected by shape; symlinks are rejected
+// by comparing real paths. The target may not exist yet (a command is about to
+// create it), so we realpath the nearest existing ancestor: an intermediate
+// symlink leading outside is caught before any mkdir lands in the external
+// target. Returns the absolute, contained path.
+export function resolveRepoPath(repoRoot, configured, field) {
+  if (typeof configured !== 'string' || configured === '') {
+    throw new Error(`config "${field}" must be a non-empty relative path`);
+  }
+  if (path.isAbsolute(configured)) {
+    throw new Error(`config "${field}" must be relative to the repo root: ${configured}`);
+  }
+  const root = path.resolve(repoRoot);
+  const resolved = path.resolve(root, configured);
+  if (!isInside(root, resolved)) {
+    throw new Error(`config "${field}" escapes the repo root: ${configured}`);
+  }
+  const realRoot = fs.realpathSync(root);
+  const realAncestor = fs.realpathSync(nearestExisting(resolved));
+  if (!isInside(realRoot, realAncestor)) {
+    throw new Error(`config "${field}" resolves outside the repo via a symlink: ${configured}`);
+  }
+  return resolved;
+}
+
+// Nearest path component of `p` that exists on disk. The gap between it and `p`
+// is non-existent (so it cannot hide a symlink); the ancestor is what we realpath
+// to detect an intermediate symlink escaping the repo.
+function nearestExisting(p) {
+  let cur = p;
+  while (!fs.existsSync(cur)) {
+    const parent = path.dirname(cur);
+    if (parent === cur) break;
+    cur = parent;
+  }
+  return cur;
+}
+
+function isInside(root, target) {
+  return target === root || target.startsWith(root + path.sep);
+}
+
+// Single source of the specs directory: the configured `specs_dir` or the
+// default, always resolved through the containment guard. Shared by `loadRepo`
+// and `graduate` so a graduated spec lands where the repo will later read it.
+export const DEFAULT_SPECS_DIR = '.changeledger/specs';
+
+export function resolveSpecsDir(repoRoot, config) {
+  return resolveRepoPath(repoRoot, config.specs_dir ?? DEFAULT_SPECS_DIR, 'specs_dir');
+}

package/src/contract.mjs

@@ -0,0 +1,100 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { writeFileAtomic } from './atomic-write.mjs';
+import { agentsTemplate } from './paths.mjs';
+
+// The tool's contract (templates/AGENTS.md) is a tool artifact, not a project
+// artifact. Each repo links to the installed copy via `.changeledger/AGENTS.md` (a
+// per-machine, gitignored symlink) and points its own contract files at that
+// link. We never copy the contract (it would drift) nor commit the symlink (it
+// would dangle on another machine). See change #20260614-151759.
+
+// Project-owned contract files that should reference the linked contract. The
+// root AGENTS.md is required by `init`; CLAUDE.md is referenced when present.
+const CONTRACT_FILES = ['AGENTS.md', 'CLAUDE.md'];
+
+const MARKER = '<!-- changeledger -->';
+const REFERENCE = `${MARKER}
+> [!IMPORTANT]
+> This repo uses **ChangeLedger**. Read and follow \`.changeledger/AGENTS.md\` (the change
+> contract). If it is missing, run \`changeledger register\`.
+`;
+
+export const contractLink = (changeledgerDir) => path.join(changeledgerDir, 'AGENTS.md');
+export const rootContract = (repoRoot) => path.join(repoRoot, 'AGENTS.md');
+
+// A real, non-symlink file we may safely append to.
+function isPlainFile(file) {
+  try {
+    return fs.lstatSync(file).isFile();
+  } catch {
+    return false;
+  }
+}
+
+// Create (or refresh) the `.changeledger/AGENTS.md` symlink to the installed contract.
+// Idempotent and tolerant of a pre-existing/dangling link.
+export function linkContract(changeledgerDir) {
+  const link = contractLink(changeledgerDir);
+  try {
+    fs.lstatSync(link);
+    fs.unlinkSync(link);
+  } catch {
+    // no existing link — nothing to remove
+  }
+  try {
+    fs.symlinkSync(agentsTemplate, link);
+  } catch {
+    // Windows without Developer Mode/admin cannot create symlinks. Fall back to
+    // a copy so the contract is still present; `changeledger register` refreshes it if the
+    // installed contract changes.
+    writeFileAtomic(link, fs.readFileSync(agentsTemplate, 'utf8'));
+  }
+  return link;
+}
+
+// Append the reference block to each present, non-symlink contract file unless
+// already there. Symlinks are skipped (appending would write into their target).
+export function ensureReference(repoRoot) {
+  const touched = [];
+  for (const name of CONTRACT_FILES) {
+    const file = path.join(repoRoot, name);
+    if (!isPlainFile(file)) continue;
+    const text = fs.readFileSync(file, 'utf8');
+    if (text.includes(MARKER)) continue;
+    writeFileAtomic(file, `${text}${text.endsWith('\n') ? '' : '\n'}\n${REFERENCE}`);
+    touched.push(name);
+  }
+  return touched;
+}
+
+// Ensure `.changeledger/AGENTS.md` is gitignored (it is a per-machine artifact).
+export function ensureGitignore(repoRoot) {
+  const file = path.join(repoRoot, '.gitignore');
+  const entry = '.changeledger/AGENTS.md';
+  const text = fs.existsSync(file) ? fs.readFileSync(file, 'utf8') : '';
+  if (text.split('\n').some((l) => l.trim() === entry)) return false;
+  writeFileAtomic(file, `${text}${text && !text.endsWith('\n') ? '\n' : ''}${entry}\n`);
+  return true;
+}
+
+// IO-level discovery validation (repo-wide). Returns a list of error messages.
+export function checkContract(repoRoot, changeledgerDir) {
+  const errors = [];
+  const root = rootContract(repoRoot);
+  if (!fs.existsSync(root)) {
+    errors.push('missing AGENTS.md at the repo root (ChangeLedger contract reference lives here)');
+  }
+  // Every present, non-symlink contract file must carry the reference.
+  for (const name of CONTRACT_FILES) {
+    const file = path.join(repoRoot, name);
+    if (!isPlainFile(file)) continue;
+    if (!fs.readFileSync(file, 'utf8').includes(MARKER)) {
+      errors.push(`${name} has no ChangeLedger reference — run \`changeledger register\``);
+    }
+  }
+  if (!fs.existsSync(contractLink(changeledgerDir))) {
+    errors.push('`.changeledger/AGENTS.md` is missing or dangling — run `changeledger register`');
+  }
+  return errors;
+}

package/src/git.mjs

@@ -0,0 +1,73 @@
+// Links a change to git via its `[#<id>]` commit-message convention (AGENTS.md
+// §6.4). `run(args)` executes git and returns stdout; it is injectable so the
+// logic is testable without a real repo. Any git failure yields empty refs.
+
+import { execFileSync } from 'node:child_process';
+
+const SEP = String.fromCharCode(31); // ASCII unit separator — safe field delimiter
+
+function defaultRun(args, cwd) {
+  return execFileSync('git', args, { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
+}
+
+// Local git identity (`git config user.name`), or '' if unavailable. Tolerant.
+export function gitUser(cwd, run = defaultRun) {
+  try {
+    return run(['config', 'user.name'], cwd).trim();
+  } catch {
+    return '';
+  }
+}
+
+function defaultGhRun(args) {
+  return execFileSync('gh', args, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
+}
+
+// GitHub username via `gh api user --jq .login`, or '' if gh is missing,
+// unauthenticated, or offline. Tolerant by design.
+export function githubLogin(run = defaultGhRun) {
+  try {
+    return run(['api', 'user', '--jq', '.login']).trim();
+  } catch {
+    return '';
+  }
+}
+
+// Preferred owner handle when work starts: the GitHub login, falling back to the
+// local git user.name. Empty if neither is available.
+export function ownerHandle(cwd, run = defaultRun, ghRun = defaultGhRun) {
+  return githubLogin(ghRun) || gitUser(cwd, run);
+}
+
+export function gitRefs(repoRoot, id, run = defaultRun) {
+  const refs = { commits: [], branches: [] };
+  if (!id) return refs;
+
+  try {
+    const out = run(
+      ['log', '--all', '-n', '100', '-F', `--grep=[#${id}]`, `--pretty=format:%H${SEP}%s${SEP}%cI`],
+      repoRoot,
+    );
+    refs.commits = out
+      .split('\n')
+      .filter(Boolean)
+      .map((line) => {
+        const [sha, subject, date] = line.split(SEP);
+        return { sha, subject, date };
+      });
+  } catch {
+    // not a git repo, or git unavailable — leave commits empty
+  }
+
+  try {
+    const out = run(['branch', '--all', '--format=%(refname:short)'], repoRoot);
+    refs.branches = out
+      .split('\n')
+      .map((s) => s.trim())
+      .filter((name) => name?.includes(id));
+  } catch {
+    // leave branches empty
+  }
+
+  return refs;
+}

package/src/lifecycle.mjs

@@ -0,0 +1,57 @@
+// The change lifecycle as an explicit, testable graph — the single authority on
+// which status moves are legal. Shared by the CLI (`changeledger status`) and the viewer
+// so both decide validity the same way. The viewer layers an extra human-only
+// policy on top (approval plus final acceptance/rejection); it never relaxes
+// this graph.
+
+export const CANONICAL_STATUSES = [
+  'draft',
+  'approved',
+  'in-progress',
+  'in-review',
+  'in-validation',
+  'blocked',
+  'done',
+  'discarded',
+];
+
+// from → set of allowed next states. Forward progress plus the blocked round
+// trip and the review/validation gates; regressions, skips and self-loops are
+// absent and therefore rejected. `in-review` is optional by type;
+// `in-validation` is the universal human gate before done. Review or validation
+// may route back to in-progress, while review may also block. `discarded` is a
+// terminal tombstone reachable only before either closing gate.
+const TRANSITIONS = {
+  draft: ['approved', 'discarded'],
+  approved: ['in-progress', 'discarded'],
+  'in-progress': ['in-review', 'in-validation', 'blocked', 'discarded'],
+  'in-review': ['in-validation', 'in-progress', 'blocked'],
+  'in-validation': ['done', 'in-progress'],
+  blocked: ['in-progress', 'discarded'],
+  done: [],
+  discarded: [],
+};
+
+const canonical = new Set(CANONICAL_STATUSES);
+
+export function canTransition(from, to) {
+  return (TRANSITIONS[from] ?? []).includes(to);
+}
+
+// Throws when a move is illegal. Enforced only between canonical statuses; a
+// repo with custom statuses keeps the prior enum-only behavior, since this graph
+// cannot reason about states it does not model.
+//
+// The review gate: a `review_required` type cannot skip from in-progress to
+// human validation. All canonical changes must pass through `in-validation`
+// before done. `opts.reviewRequired` comes from the change's type in config.yml.
+export function assertTransition(from, to, { type, reviewRequired = false } = {}) {
+  if (!canonical.has(from) || !canonical.has(to)) return;
+  if (from === to) throw new Error(`change is already "${to}"`);
+  if (!canTransition(from, to)) {
+    throw new Error(`invalid lifecycle transition: ${from} → ${to}`);
+  }
+  if (reviewRequired && from === 'in-progress' && to === 'in-validation') {
+    throw new Error(`${type} changes must be reviewed before validation — move to in-review first`);
+  }
+}

package/src/metrics.mjs

@@ -0,0 +1,143 @@
+// Pure delivery metrics derived from change timestamps. No IO and no clock —
+// time-relative metrics (aging, live WIP durations) take `now` as a parameter.
+// Everything is reconstructed from `created` plus the `## Log` status
+// transitions. The viewer renders the result.
+
+const ACTIVE = ['approved', 'in-progress', 'in-review', 'in-validation', 'blocked'];
+
+function logBody(change) {
+  return (change.stages ?? []).find((s) => s.key === 'log')?.body ?? '';
+}
+
+function logTransition(line) {
+  const m = line.match(/\*\*([^*]+)\*\*\s*—\s*(?:status:.*|review|validation)\s*→\s*([a-z-]+)\b/);
+  if (!m) return null;
+  return { at: m[1].trim(), state: m[2].trim() };
+}
+
+// The moment a change reached `done`: the last lifecycle transition to done, or
+// null. Canonical done is written by a passed human validation.
+export function doneAt(change) {
+  let at = null;
+  for (const line of logBody(change).split('\n')) {
+    const event = logTransition(line);
+    if (event?.state === 'done') at = event.at;
+  }
+  return at;
+}
+
+// Ordered status transitions parsed from the Log: [{ at, state }]. Assumes the
+// change began in `draft` at `created`.
+function transitions(change) {
+  const created = change.frontmatter?.created;
+  if (!created) return [];
+  const events = [{ at: created, state: 'draft' }];
+  for (const line of logBody(change).split('\n')) {
+    const event = logTransition(line);
+    if (event) events.push(event);
+  }
+  return events;
+}
+
+// Time spent in each state: [{ state, ms }]. The final state runs until `now`
+// (or until it reached `done`).
+export function statusTimeline(change, now) {
+  const events = transitions(change);
+  if (!events.length) return [];
+  const segs = [];
+  for (let i = 0; i < events.length; i++) {
+    const start = Date.parse(events[i].at);
+    const endIso = events[i + 1]?.at ?? now;
+    const end = Date.parse(endIso);
+    if (Number.isNaN(start) || Number.isNaN(end)) continue;
+    // `done` is terminal — there is no meaningful dwell time in it.
+    if (events[i].state === 'done') continue;
+    segs.push({ state: events[i].state, ms: Math.max(0, end - start) });
+  }
+  return segs;
+}
+
+function median(sorted) {
+  if (!sorted.length) return 0;
+  const mid = Math.floor(sorted.length / 2);
+  return sorted.length % 2 ? sorted[mid] : Math.round((sorted[mid - 1] + sorted[mid]) / 2);
+}
+
+function avg(nums) {
+  return nums.length ? Math.round(nums.reduce((a, b) => a + b, 0) / nums.length) : 0;
+}
+
+export function computeMetrics(changes = [], { now } = {}) {
+  const nowIso = now ?? '9999-12-31T23:59:59Z';
+
+  const perChange = [];
+  const byDate = new Map();
+  const statusTotals = new Map(); // state → { ms, count }
+  const wip = {};
+  const aging = [];
+  let blockedMs = 0;
+  const byType = new Map(); // type → { closed, cycles:[] }
+
+  for (const c of changes) {
+    const status = c.frontmatter?.status;
+    const type = c.frontmatter?.type ?? 'unknown';
+    const created = c.frontmatter?.created;
+
+    if (ACTIVE.includes(status)) wip[status] = (wip[status] ?? 0) + 1;
+
+    const segs = statusTimeline(c, nowIso);
+    for (const s of segs) {
+      const t = statusTotals.get(s.state) ?? { ms: 0, count: 0 };
+      t.ms += s.ms;
+      t.count += 1;
+      statusTotals.set(s.state, t);
+      if (s.state === 'blocked') blockedMs += s.ms;
+    }
+
+    if (status === 'in-progress') {
+      const events = transitions(c);
+      const entered = [...events].reverse().find((e) => e.state === 'in-progress');
+      if (entered)
+        aging.push({ id: c.frontmatter.id, ms: Date.parse(nowIso) - Date.parse(entered.at) });
+    }
+
+    if (status === 'done' && created) {
+      const closed = doneAt(c);
+      const cycleMs = closed ? Date.parse(closed) - Date.parse(created) : NaN;
+      if (!Number.isNaN(cycleMs)) {
+        perChange.push({ id: c.frontmatter.id, cycleMs });
+        byDate.set(closed.slice(0, 10), (byDate.get(closed.slice(0, 10)) ?? 0) + 1);
+        const bt = byType.get(type) ?? { closed: 0, cycles: [] };
+        bt.closed += 1;
+        bt.cycles.push(cycleMs);
+        byType.set(type, bt);
+      }
+    }
+  }
+
+  const cycles = perChange.map((p) => p.cycleMs).sort((a, b) => a - b);
+  const throughput = [...byDate.entries()]
+    .map(([date, count]) => ({ date, count }))
+    .sort((a, b) => (a.date < b.date ? -1 : a.date > b.date ? 1 : 0));
+  const timeInStatus = [...statusTotals.entries()].map(([state, t]) => ({
+    state,
+    totalMs: t.ms,
+    avgMs: Math.round(t.ms / t.count),
+  }));
+  const byTypeArr = [...byType.entries()]
+    .map(([type, v]) => ({ type, closed: v.closed, avgCycleMs: avg(v.cycles) }))
+    .sort((a, b) => b.closed - a.closed);
+
+  return {
+    count: perChange.length,
+    avgCycleMs: avg(cycles),
+    medianCycleMs: median(cycles),
+    perChange,
+    throughput,
+    timeInStatus,
+    wip,
+    aging: aging.sort((a, b) => b.ms - a.ms),
+    blockedMs,
+    byType: byTypeArr,
+  };
+}

package/src/paths.mjs

@@ -0,0 +1,12 @@
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+export const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+export const templatesDir = path.join(packageRoot, 'templates');
+export const agentsTemplate = path.join(templatesDir, 'AGENTS.md');
+export const publicDir = path.join(packageRoot, 'src', 'viewer', 'public');
+
+// ISO 8601 UTC at second precision, matching the change `created`/task convention.
+export function nowUtc() {
+  return new Date().toISOString().replace(/\.\d{3}Z$/, 'Z');
+}