@golden-frijoles/kit 0.0.0 → 0.2.0

package/dist/lib/standup-deck.mjs

@@ -0,0 +1,120 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import {
+  formatTelegramHtmlLink,
+  telegramHtmlVisibleLength,
+  truncateForTelegram,
+} from './telegram-format.mjs';
+import { buildDocViewerUrl } from './pmo-templates.mjs';
+import { kitRoot } from './project-root.mjs';
+
+const TEMPLATE_PATH = join(kitRoot(), 'standup', 'templates', 'daily-story-deck.md'); // D2: a kit asset
+const TELEGRAM_MAX_CHARS = 4096;
+
+export const STANDUP_DECK_ASPECT_RATIO = '16:9';
+
+function shortRepo(repo) {
+  return repo.split('/')[1] || repo;
+}
+
+function decodeTelegramEntities(text) {
+  return String(text ?? '')
+    .replace(/&lt;/g, '<')
+    .replace(/&gt;/g, '>')
+    .replace(/&amp;/g, '&');
+}
+
+export function telegramHtmlToMarkdown(text) {
+  return decodeTelegramEntities(
+    String(text ?? '')
+      .replace(/<b>(.*?)<\/b>/g, '**$1**')
+      .replace(/<[^>]*>/g, '')
+  );
+}
+
+function bulletList(lines, fallback) {
+  const items = lines.filter(Boolean);
+  if (!items.length) return `- ${fallback}`;
+  return items.map((line) => `- ${line}`).join('\n');
+}
+
+function getPath(obj, path) {
+  return path.split('.').reduce((cur, part) => (cur == null ? undefined : cur[part]), obj);
+}
+
+export function fillStandupTemplate(template, data) {
+  return template.replace(/\{\{\s*([A-Za-z0-9_.]+)\s*\}\}/g, (match, key) => {
+    const value = getPath(data, key);
+    return value === undefined ? match : String(value);
+  });
+}
+
+export function buildStandupDeckData({ snapshot, deltaLines = [], generatedAt = new Date() }) {
+  const date = String(snapshot?.ts || generatedAt.toISOString()).slice(0, 10);
+  const repos = Object.entries(snapshot?.repos || {}).map(([repo, state]) => {
+    if (!state) return `**${shortRepo(repo)}:** unavailable`;
+    return (
+      `**${shortRepo(repo)}:** ${state.openNumbers?.length || 0} open; ` +
+      `${state.failingOpenNumbers?.length || 0} red; ${state.conflictingOpenNumbers?.length || 0} conflicts`
+    );
+  });
+  const smoke = snapshot?.smoke
+    ? `${snapshot.smoke.conclusion || snapshot.smoke.status || 'unknown'} (${String(snapshot.smoke.createdAt || '').slice(0, 10) || 'no date'})`
+    : 'unavailable';
+  const stalePreviews = snapshot?.stalePreviews == null ? 'unavailable' : String(snapshot.stalePreviews);
+  return {
+    deck: {
+      aspectRatio: STANDUP_DECK_ASPECT_RATIO,
+    },
+    window: {
+      date,
+      generatedDate: generatedAt.toISOString().slice(0, 10),
+    },
+    summary: {
+      bullets: bulletList(
+        deltaLines.map(telegramHtmlToMarkdown),
+        'Quiet night - nothing new since the last standup.'
+      ),
+    },
+    repos: {
+      bullets: bulletList(repos, 'Repository signals unavailable.'),
+    },
+    guards: {
+      browserSmoke: smoke,
+      buildOrder: snapshot?.buildOrderDrifted ? 'drift detected' : 'up to date',
+      stalePreviews,
+    },
+  };
+}
+
+export function loadStandupDeckTemplate() {
+  return readFileSync(TEMPLATE_PATH, 'utf8');
+}
+
+export function buildStandupDeckMarkdown(options) {
+  return fillStandupTemplate(loadStandupDeckTemplate(), buildStandupDeckData(options));
+}
+
+// No viewer configured → no artifact. The Telegram text is the canonical read; the deck is an optional
+// extra, and an extra must never be faked with someone else's hosting.
+export function buildStandupArtifacts({ docViewerUrl, ...options } = {}) {
+  if (!docViewerUrl) return [];
+  const markdown = buildStandupDeckMarkdown(options);
+  return [
+    {
+      name: 'standup',
+      markdown,
+      url: buildDocViewerUrl(markdown, { baseUrl: docViewerUrl, present: true }),
+    },
+  ];
+}
+
+export function appendStandupArtifactsToMessage(message, artifacts, maxChars = TELEGRAM_MAX_CHARS) {
+  if (!artifacts.length) return truncateForTelegram(message, maxChars);
+  const suffix = `\n\n${artifacts
+    .map((artifact) => `Deck ${artifact.name}: ${formatTelegramHtmlLink('open daily story', artifact.url)}`)
+    .join('\n')}`;
+  const suffixVisibleLength = telegramHtmlVisibleLength(suffix);
+  if (suffixVisibleLength >= maxChars) return truncateForTelegram(message, maxChars);
+  return `${truncateForTelegram(message, maxChars - suffixVisibleLength)}${suffix}`;
+}

package/dist/lib/telegram-format.mjs

@@ -0,0 +1,91 @@
+// telegram-format.mjs — shared message-formatting safety nets for Telegram's hard 4096-char
+// sendMessage limit. Used by both standup.mjs and weekly-recap.mjs (originally built for weekly-recap,
+// moved here 2026-07-03 after standup.mjs hit the exact same failure mode live: a missing/wiped delta
+// log made it enumerate gh's entire recent-PR history as "new," overflowing the limit and dying before
+// ever posting or persisting its own log).
+
+function esc(s) {
+  return String(s ?? '')
+    .replace(/&/g, '&')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;');
+}
+
+function escAttr(s) {
+  return esc(s).replace(/"/g, '&quot;');
+}
+
+function decodeHtmlEntities(s) {
+  return String(s ?? '')
+    .replace(/&quot;/g, '"')
+    .replace(/&#39;/g, "'")
+    .replace(/&lt;/g, '<')
+    .replace(/&gt;/g, '>')
+    .replace(/&amp;/g, '&');
+}
+
+export function formatTelegramHtmlLink(label, url) {
+  return `<a href="${escAttr(url)}">${esc(label)}</a>`;
+}
+
+export function telegramHtmlVisibleText(text) {
+  return decodeHtmlEntities(
+    String(text ?? '')
+      .replace(/<a\s+href="[^"]*">([\s\S]*?)<\/a>/g, '$1')
+      .replace(/<[^>]*>/g, '')
+  );
+}
+
+export function telegramHtmlVisibleLength(text) {
+  return telegramHtmlVisibleText(text).length;
+}
+
+export function telegramHtmlToConsoleText(text) {
+  return decodeHtmlEntities(
+    String(text ?? '')
+      .replace(/<a\s+href="([^"]*)">([\s\S]*?)<\/a>/g, '$2 ($1)')
+      .replace(/<[^>]*>/g, '')
+  );
+}
+
+// Pure — caps a list of {number, title} PRs to maxItems titles before it can dominate a message on a
+// busy day/week, folding the rest into a "…and N more" tail. The caller's own section-header count is
+// never capped, only the listed titles are.
+export function formatPrList(prs, maxItems) {
+  const shown = prs
+    .slice(0, maxItems)
+    .map((p) => `#${p.number} ${esc(p.title)}`)
+    .join('; ');
+  const rest = prs.length - maxItems;
+  return rest > 0 ? `${shown}; …and ${rest} more` : shown;
+}
+
+// Pure — a last-resort safety net for Telegram's hard 4096-char sendMessage limit. formatPrList (or an
+// equivalent per-caller cap) should already keep a normal message well under this; this only bites an
+// extreme outlier so the API call never gets rejected outright instead of silently never posting. Two
+// HTML-safety steps, since the only tags these scripts emit are `<b>`/`</b>` and an unbalanced/incomplete
+// one would make Telegram reject the whole message as invalid HTML — defeating the safety net's purpose:
+// (1) strip a trailing PARTIAL tag first (the cut landing mid-`<b>`/`</b>` itself, e.g. a dangling `<b`),
+// (2) then close any remaining fully-formed-but-unclosed `<b>`. Appending closing tags can itself push
+// the result back OVER `limit` — iterate, shrinking the cut point by however much was appended, until the
+// FINAL (post-closing-tags) length actually fits. Bounded to a few iterations (closing tags are 4 chars
+// each, so this converges immediately in every realistic case); a hard fallback strips all tags entirely
+// if it somehow doesn't, guaranteeing the contract ("result never exceeds limit") holds regardless.
+export function truncateForTelegram(text, limit) {
+  if (text.length <= limit) return text;
+  let cut = limit - 1; // room for the ellipsis
+  for (let i = 0; i < 10; i += 1) {
+    const sliced = text.slice(0, cut).replace(/<[^>]*$/, '');
+    const candidate = `${sliced.trim()}…`;
+    const opens = (candidate.match(/<b>/g) || []).length;
+    const closes = (candidate.match(/<\/b>/g) || []).length;
+    const closingTags = opens > closes ? '</b>'.repeat(opens - closes) : '';
+    const final = `${candidate}${closingTags}`;
+    if (final.length <= limit) return final;
+    cut -= Math.max(closingTags.length, 1);
+  }
+  return `${text
+    .replace(/<[^>]*>/g, '')
+    .slice(0, limit - 1)
+    .trim()}…`;
+}

package/dist/live-smoke.mjs

@@ -0,0 +1,303 @@
+#!/usr/bin/env node
+/**
+ * live-smoke — the scripted, cross-agent-usable default for verifying real, rendered behavior against
+ * local/preview/staging/prod, unauthed or authed.
+ *
+ * Ported from the origin project's app-local script by plugin-audit-and-extraction S1 (D3: port, don't
+ * drop). Every project-specific value — the app dir, the environment URLs, the role flows, the auth
+ * provider's key names — moved to `live-smoke.config.json` at the repo root. The refusals the origin
+ * learned the hard way are kept: authed flows never run against an env marked unsupported (auth providers
+ * reject testing tokens for production keys by design), and keys that look like production keys are
+ * refused even at --env=local.
+ *
+ * Wraps the app's existing Playwright harness (`<appDir>/playwright.config.ts`'s `browser` project) — no
+ * new browser-driving logic, just env resolution + a structured result an agent can parse.
+ *
+ * Three modes (exactly one):
+ *   --path <url-path> [--flow unauthed|<role>]   ad-hoc: runs e2e/_live/ad-hoc.browser.spec.ts on ONE path
+ *   --spec <name>                                 a COMMITTED *.browser.spec.ts whose TEST TITLE matches
+ *   --file <path>                                 every test in a committed spec, by file path
+ *
+ * --env: any key under `envs` in the config, plus `preview` (needs --preview-url). This script starts
+ * nothing itself — the target must already be running.
+ *
+ * Output: exit code (0 = pass), <appDir>/test-results/live-smoke/report.json and screenshot.png for a
+ * --path run. Read both back — a 0 with an unexpected screenshot is still worth flagging.
+ *
+ *   node scripts/live-smoke.mjs --env=local --path=/
+ *   node scripts/live-smoke.mjs --env=prod  --path=/pricing
+ *   node scripts/live-smoke.mjs --env=local --flow=admin --path=/admin
+ *   node scripts/live-smoke.mjs --env=local --spec="home renders"
+ */
+import { parseArgs } from 'node:util';
+import { spawnSync } from 'node:child_process';
+import { existsSync, readFileSync, rmSync, realpathSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { join, isAbsolute, normalize } from 'node:path';
+import { projectRoot } from './lib/project-root.mjs';
+
+const REPO_ROOT = projectRoot(); // D2
+export const CONFIG_FILENAME = 'live-smoke.config.json';
+const OUT_DIR = process.env.LIVE_SMOKE_OUT ?? 'test-results/live-smoke';
+
+/** Strip a matching pair of surrounding quotes (single or double), if present. */
+function unquote(value) {
+  if (value.length >= 2) {
+    const first = value[0];
+    const last = value[value.length - 1];
+    if ((first === '"' && last === '"') || (first === "'" && last === "'")) return value.slice(1, -1);
+  }
+  return value;
+}
+
+/**
+ * Pure — parse a .env-style file without printing values or mutating process.env. Handles a leading
+ * `export ` and quoted values (both common in a hand-edited .env.local): a plain `KEY=value` parse would
+ * pass a literal `"sk_test_..."` (quotes included) to the auth provider and fail with a confusing error.
+ */
+export function parseDotEnv(text) {
+  const out = {};
+  for (const line of text.split('\n')) {
+    let trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith('#')) continue;
+    if (trimmed.startsWith('export ')) trimmed = trimmed.slice('export '.length).trim();
+    const eq = trimmed.indexOf('=');
+    if (eq === -1) continue;
+    out[trimmed.slice(0, eq).trim()] = unquote(trimmed.slice(eq + 1).trim());
+  }
+  return out;
+}
+
+/** Pure — validate the config shape. Throws with the offending key named. */
+export function validateConfig(raw, path = CONFIG_FILENAME) {
+  const fail = (m) => {
+    throw new Error(`${path}: ${m}`);
+  };
+  if (!raw || typeof raw !== 'object') fail('must be a JSON object');
+  if (typeof raw.appDir !== 'string' || !raw.appDir)
+    fail('"appDir" must name the app directory (e.g. "apps/web")');
+  // Relative and inside the repo: live-smoke reads <appDir>/.env.local, so an appDir that climbs out of the
+  // repo would read some other tree's secrets. (Cross-review finding on PR #20.)
+  if (isAbsolute(raw.appDir) || normalize(raw.appDir).split(/[\\/]/)[0] === '..') {
+    fail('"appDir" must be a relative path inside the repo (e.g. "apps/web")');
+  }
+  const envs = raw.envs ?? {};
+  if (!Object.keys(envs).length) fail('"envs" must map at least one env name to a base URL');
+  for (const [k, v] of Object.entries(envs)) {
+    if (k === 'preview') fail('"envs.preview" is reserved — preview URLs come from --preview-url');
+    if (!/^https?:\/\//.test(v)) fail(`"envs.${k}" must be an http(s) URL`);
+  }
+  const flows = raw.flows ?? {};
+  for (const [k, v] of Object.entries(flows)) {
+    if (k === 'unauthed') fail('"flows.unauthed" is implicit — list only role flows');
+    if (!v || typeof v.identityEnv !== 'string')
+      fail(`"flows.${k}.identityEnv" must name the env var holding that role's test identity`);
+  }
+  const auth = raw.auth ?? {};
+  return {
+    appDir: raw.appDir,
+    envs,
+    flows,
+    auth: {
+      requiredEnv: auth.requiredEnv ?? [],
+      forbidKeyPattern: auth.forbidKeyPattern ?? null,
+      unsupportedEnvs: auth.unsupportedEnvs ?? [],
+    },
+    previewBypassEnv: raw.previewBypassEnv ?? null,
+  };
+}
+
+function sameOrigin(path) {
+  const probe = 'https://target.invalid';
+  try {
+    return new URL(path, probe).origin === probe;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Pure — turn args + config + the resolvable environment into a run plan, or an error string. Every
+ * refusal the script makes is decided here so a test can pin it without spawning a browser.
+ */
+export function planRun({ args, config, env = {}, dotenv = {} }) {
+  const flow = args.flow ?? 'unauthed';
+  const flowNames = ['unauthed', ...Object.keys(config.flows)];
+  if (!flowNames.includes(flow))
+    return { error: `--flow must be one of ${flowNames.join('|')} (got "${flow}")` };
+
+  // A path, not a URL: `//host/x` is protocol-relative and would silently smoke a DIFFERENT host than the
+  // resolved --env, and a scheme would override it outright. (Cross-review finding on PR #20.)
+  // Checked by RESOLUTION, not by prefix: `/\\host` resolves to another origin too (WHATWG treats `\\` as
+  // `/`), so the rule is simply that the path must land on the base URL's own origin.
+  if (
+    args.path != null &&
+    (typeof args.path !== 'string' || !args.path.startsWith('/') || !sameOrigin(args.path))
+  ) {
+    return {
+      error: `--path must be a path on the target env, starting with a single "/" (got "${args.path}")`,
+    };
+  }
+
+  const modes = [args.path, args.spec, args.file].filter(Boolean);
+  if (modes.length === 0)
+    return { error: 'pass --path=<url-path> (ad-hoc), --spec=<name>, or --file=<path> (a committed spec)' };
+  if (modes.length > 1) return { error: 'pass exactly one of --path, --spec, --file' };
+
+  const envName = args.env ?? Object.keys(config.envs)[0];
+  let baseURL;
+  if (envName === 'preview') {
+    if (!args['preview-url']) return { error: '--env=preview requires --preview-url=<https://...>' };
+    baseURL = args['preview-url'];
+  } else {
+    baseURL = config.envs[envName];
+    if (!baseURL)
+      return {
+        error: `unknown --env "${envName}" (expected ${[...Object.keys(config.envs), 'preview'].join('|')})`,
+      };
+  }
+
+  const childEnv = { PLAYWRIGHT_BASE_URL: baseURL };
+  if (envName === 'preview' && config.previewBypassEnv) {
+    const bypass = env[config.previewBypassEnv];
+    if (!bypass)
+      return { error: `--env=preview needs ${config.previewBypassEnv} set in the shell environment` };
+    childEnv[config.previewBypassEnv] = bypass;
+  }
+
+  if (flow !== 'unauthed') {
+    // The env constraint FIRST — a specific refusal beats a generic "need keys" message when both apply.
+    if (config.auth.unsupportedEnvs.includes(envName)) {
+      return {
+        error:
+          `--flow=${flow} against --env=${envName} is not supported — auth providers reject testing tokens ` +
+          'for production keys by design. Use a dev/test environment for authed flows.',
+      };
+    }
+    for (const key of config.auth.requiredEnv) {
+      const value = env[key] ?? dotenv[key];
+      if (!value)
+        return { error: `an authed --flow needs ${key} resolvable from the shell or <appDir>/.env.local` };
+      // Defense-in-depth beyond the env check: the same rejection happens at --env=local when .env.local
+      // carries production keys. Catch it here with a clear message, not deep inside a sign-in helper.
+      if (config.auth.forbidKeyPattern && value.includes(config.auth.forbidKeyPattern)) {
+        return {
+          error:
+            `${key} looks like a PRODUCTION key (contains "${config.auth.forbidKeyPattern}") — authed ` +
+            'live-smoke flows only work with a dev/test auth instance.',
+        };
+      }
+      childEnv[key] = value;
+    }
+    const identityEnv = config.flows[flow].identityEnv;
+    const identity = env[identityEnv] ?? dotenv[identityEnv];
+    if (identity) childEnv[identityEnv] = identity;
+    childEnv[`LIVE_SMOKE_IDENTITY_ENV_${flow.toUpperCase()}`] = identityEnv;
+  }
+
+  let playwrightArgs;
+  if (args.path) {
+    Object.assign(childEnv, { LIVE_SMOKE_PATH: args.path, LIVE_SMOKE_FLOW: flow, LIVE_SMOKE_OUT: OUT_DIR });
+    playwrightArgs = ['playwright', 'test', '--project=browser', 'e2e/_live/ad-hoc.browser.spec.ts'];
+  } else if (args.spec) {
+    playwrightArgs = ['playwright', 'test', '--project=browser', '-g', args.spec];
+  } else {
+    playwrightArgs = ['playwright', 'test', '--project=browser', args.file];
+  }
+  return { envName, baseURL, flow, childEnv, playwrightArgs };
+}
+
+export function loadConfig({ root = REPO_ROOT } = {}) {
+  const path = join(root, CONFIG_FILENAME);
+  if (!existsSync(path)) {
+    throw new Error(
+      `${path} not found — live-smoke refuses to guess which app and which URLs to smoke.\n` +
+        `  Copy live-smoke.config.example.json to ${CONFIG_FILENAME}, fill it in, and commit it.`
+    );
+  }
+  return validateConfig(JSON.parse(readFileSync(path, 'utf8')), path);
+}
+
+function die(message) {
+  console.error(`live-smoke: ${message}`);
+  process.exit(2);
+}
+
+function main() {
+  const { values: args } = parseArgs({
+    options: {
+      env: { type: 'string' },
+      flow: { type: 'string', default: 'unauthed' },
+      path: { type: 'string' },
+      spec: { type: 'string' },
+      file: { type: 'string' },
+      'preview-url': { type: 'string' },
+    },
+  });
+  let config;
+  try {
+    config = loadConfig();
+  } catch (e) {
+    die(e.message);
+  }
+  const appRoot = join(REPO_ROOT, config.appDir);
+  if (
+    !existsSync(join(appRoot, 'playwright.config.ts')) &&
+    !existsSync(join(appRoot, 'playwright.config.js'))
+  ) {
+    die(`${config.appDir} has no playwright.config — live-smoke wraps the app's own Playwright harness`);
+  }
+  const dotenvPath = join(appRoot, '.env.local');
+  const dotenv = existsSync(dotenvPath) ? parseDotEnv(readFileSync(dotenvPath, 'utf8')) : {};
+
+  const plan = planRun({ args, config, env: process.env, dotenv });
+  if (plan.error) die(plan.error);
+
+  if (args.path) {
+    // Clear a PREVIOUS run's evidence first — a skipped or crashed-before-navigating run leaves no fresh
+    // report, and the readback below would otherwise present stale evidence as current.
+    rmSync(join(appRoot, OUT_DIR, 'report.json'), { force: true });
+    rmSync(join(appRoot, OUT_DIR, 'screenshot.png'), { force: true });
+  }
+
+  const target = args.path ? `path=${args.path}` : args.spec ? `spec="${args.spec}"` : `file=${args.file}`;
+  console.log(`live-smoke: env=${plan.envName} baseURL=${plan.baseURL} flow=${plan.flow} ${target}`);
+
+  const result = spawnSync('npx', plan.playwrightArgs, {
+    cwd: appRoot,
+    env: { ...process.env, ...plan.childEnv },
+    stdio: 'inherit',
+  });
+
+  if (args.path) {
+    const reportPath = join(appRoot, OUT_DIR, 'report.json');
+    if (existsSync(reportPath)) {
+      const report = JSON.parse(readFileSync(reportPath, 'utf8'));
+      console.log(`live-smoke: report at ${reportPath}`);
+      console.log(
+        `live-smoke: screenshot at ${report.screenshot ? join(appRoot, report.screenshot) : '(none)'}`
+      );
+      if (report.consoleErrors?.length) {
+        console.log(
+          `live-smoke: ${report.consoleErrors.length} browser console error(s) captured — see report.json`
+        );
+      }
+    } else {
+      console.log(
+        'live-smoke: no report.json written (the spec likely skipped or crashed before navigating)'
+      );
+    }
+  }
+  process.exit(result.status ?? 1);
+}
+
+// realpath, not resolve: on macOS a temp or symlinked path (/var → /private/var) never equals the module
+// URL, and a plain comparison makes the CLI a silent no-op.
+const isMain = (() => {
+  try {
+    return !!process.argv[1] && realpathSync(process.argv[1]) === fileURLToPath(import.meta.url);
+  } catch {
+    return false;
+  }
+})();
+if (isMain) main();

package/dist/pmo/benchmarks.json

@@ -0,0 +1,77 @@
+{
+  "schema": "pmo-benchmarks-v1",
+  "generatedAt": "2026-07-13",
+  "framing": "Differential, not a controlled experiment. DORA/Four Keys thresholds are used only for comparable delivery signals; throughput and doc-ops remain internal PMO signals.",
+  "figures": {
+    "deploysPerWeekDailyThreshold": {
+      "label": "Daily deployment-frequency threshold",
+      "value": 3,
+      "unit": "deployment days per week",
+      "direction": "higher_is_better",
+      "source": {
+        "title": "Four Keys Metrics - Deployment Frequency",
+        "publisher": "DORA / Four Keys",
+        "url": "https://github.com/dora-team/fourkeys/blob/main/METRICS.md#deployment-frequency",
+        "publishedDate": "2024-01-23",
+        "accessedDate": "2026-07-13",
+        "note": "Daily bucket: median number of days per week with deployments is >= 3."
+      }
+    },
+    "prCycleMedianHoursOneDayThreshold": {
+      "label": "One-day lead-time threshold",
+      "value": 24,
+      "unit": "hours",
+      "direction": "lower_is_better",
+      "source": {
+        "title": "Four Keys Metrics - Lead Time for Changes",
+        "publisher": "DORA / Four Keys",
+        "url": "https://github.com/dora-team/fourkeys/blob/main/METRICS.md#lead-time-for-changes",
+        "publishedDate": "2024-01-23",
+        "accessedDate": "2026-07-13",
+        "note": "One-day bucket: median lead time to change < 24 * 60 minutes. PMO uses this as a proxy comparator for PR open-to-merge cycle time, not as an identical metric."
+      }
+    },
+    "epicLeadMedianDaysOneWeekThreshold": {
+      "label": "One-week lead-time threshold",
+      "value": 7,
+      "unit": "days",
+      "direction": "lower_is_better",
+      "source": {
+        "title": "Four Keys Metrics - Lead Time for Changes",
+        "publisher": "DORA / Four Keys",
+        "url": "https://github.com/dora-team/fourkeys/blob/main/METRICS.md#lead-time-for-changes",
+        "publishedDate": "2024-01-23",
+        "accessedDate": "2026-07-13",
+        "note": "One-week bucket: median lead time to change < 168 * 60 minutes. PMO uses this as a coarse comparator for epic scaffold-to-shipped lead time."
+      }
+    },
+    "changeFailureRateMaxPercent": {
+      "label": "Top change-failure-rate bucket",
+      "value": 15,
+      "unit": "percent",
+      "direction": "lower_is_better",
+      "source": {
+        "title": "Four Keys Metrics - Change Failure Rate",
+        "publisher": "DORA / Four Keys",
+        "url": "https://github.com/dora-team/fourkeys/blob/main/METRICS.md#change-failure-rate",
+        "publishedDate": "2024-01-23",
+        "accessedDate": "2026-07-13",
+        "note": "Top bucket is 0-15% failures per deployments."
+      }
+    },
+    "restoreTimeHoursOneDayThreshold": {
+      "label": "One-day time-to-restore threshold",
+      "value": 24,
+      "unit": "hours",
+      "direction": "lower_is_better",
+      "source": {
+        "title": "Four Keys Metrics - Time to Restore Services",
+        "publisher": "DORA / Four Keys",
+        "url": "https://github.com/dora-team/fourkeys/blob/main/METRICS.md#time-to-restore-services",
+        "publishedDate": "2024-01-23",
+        "accessedDate": "2026-07-13",
+        "note": "One-day bucket: median time to resolve < 24 hours. Included for future incident reporting; Sprint 2 templates do not yet render MTTR."
+      }
+    }
+  }
+}

package/dist/pmo/templates/metrics-sheet.md

@@ -0,0 +1,27 @@
+---
+title: "PMO metrics sheet - {{window.label}}"
+styles:
+  fontFamily: "Inter"
+  baseFontSize: 15
+  lineHeight: 1.6
+---
+
+# PMO metrics sheet - {{window.label}}
+
+```cells
+Metric,Value,Benchmark,Direction,Differential
+Deploys per week,{{deploys.perWeek}},{{benchmarks.deploysPerWeek}},higher is better,=B2-C2
+PR cycle median hours,{{cycle.medianHours}},{{benchmarks.prCycleMedianHours}},lower is better,=B3-C3
+Epic lead median days,{{epics.medianDays}},{{benchmarks.epicLeadMedianDays}},lower is better,=B4-C4
+Change-failure proxy %,{{quality.changeFailureRatePercent}},{{benchmarks.changeFailureRatePercent}},lower is better,=B5-C5
+Stories shipped,{{throughput.shippedStories}},0,internal signal,=B6-C6
+Epics shipped,{{throughput.shippedEpics}},0,internal signal,=B7-C7
+LEARNINGS promotions,{{docOps.learningsPromotions}},0,internal signal,=B8-C8
+Retro coverage %,{{docOps.retroPercent}},0,internal signal,=B9-C9
+```
+
+Notes:
+
+- The formulas export to a spreadsheet as live formulas.
+- Benchmark source: {{benchmarks.sourceLine}}.
+- {{benchmarks.framing}}

package/dist/pmo/templates/monthly-stakeholder-packet.md

@@ -0,0 +1,53 @@
+---
+title: "PMO monthly - {{window.label}}"
+styles:
+  fontFamily: "Inter"
+  baseFontSize: 15
+  lineHeight: 1.65
+  h1: { fontSize: 2.0, fontWeight: 700 }
+  h2: { fontSize: 1.25, fontWeight: 600 }
+---
+
+# PMO monthly - {{window.label}}
+
+## Executive summary
+
+This packet reports operational performance in PMO terms: flow, DORA, quality and documentation discipline.
+The external comparison is a differential, not a controlled experiment.
+
+## Indicators
+
+| Indicator | Value |
+|---|---:|
+| Stories shipped | {{throughput.shippedStories}} |
+| Epics shipped | {{throughput.shippedEpics}} |
+| Deploys per week | {{deploys.perWeek}} |
+| Median PR cycle | {{cycle.medianHours}}h |
+| Median epic lead time | {{epics.medianDays}} days |
+| Change-failure proxy | {{quality.changeFailureRatePercent}}% |
+| LEARNINGS promotions | {{docOps.learningsPromotions}} |
+| Retro coverage | {{docOps.retroCovered}}/{{docOps.retroTotal}} |
+
+## External benchmarks
+
+| Comparable signal | PMO | Benchmark | Reading |
+|---|---:|---:|---|
+| Deploys per week | {{deploys.perWeek}} | {{benchmarks.deploysPerWeek}} | Higher is better |
+| Median PR cycle | {{cycle.medianHours}}h | {{benchmarks.prCycleMedianHours}}h | Lower is better |
+| Median epic lead | {{epics.medianDays}} days | {{benchmarks.epicLeadMedianDays}} days | Lower is better |
+| Change-failure proxy | {{quality.changeFailureRatePercent}}% | {{benchmarks.changeFailureRatePercent}}% | Lower is better |
+
+Source: {{benchmarks.sourceLine}}. {{benchmarks.framing}}
+
+## Visual evidence
+
+```chart
+{"type":"bar","title":"PMO monthly","labels":["Stories","Epics","Deploys","Doc ops"],"values":[{{throughput.shippedStories}},{{throughput.shippedEpics}},{{deploys.total}},{{docOps.learningsPromotions}}],"color":"#2563eb"}
+```
+
+## Reading
+
+- Throughput is inferred from real history, not story points.
+- Deploy frequency equals merges to `main`, as WAYS-OF-WORKING defines it.
+- The change-fail proxy counts reverts/hotfixes.
+- Doc-ops measures the breadth of Roadmap, LEARNINGS and retrospective activity.