bmad-plus 0.17.1 → 0.19.0

package/tools/cli/lib/review.js

@@ -0,0 +1,522 @@
+/**
+ * Code review evidence: a sealed scope, findings anchored on quoted code, and a gate that
+ * derives the verdict from coverage — never from how many findings were written.
+ *
+ * The host agent reviews; this module only establishes what must be reviewed, where each
+ * finding really is, and whether every selected file was accounted for. Design taken from
+ * the open-code-review study (docs/research/open-code-review-2026-09-25): deterministic
+ * selection with named exclusion reasons, verbatim-snippet anchoring, coverage-derived
+ * disposition. No model call, no network, no write outside the review folder.
+ */
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const crypto = require('node:crypto');
+const { spawnSync } = require('node:child_process');
+
+const SCOPE_SCHEMA = 'bmad-plus/review-scope/1';
+const FINDINGS_SCHEMA = 'bmad-plus/review-findings/1';
+const COVERAGE_SCHEMA = 'bmad-plus/review-coverage/1';
+const DEFAULT_DIR = '_bmad-output/review';
+
+const SEVERITIES = ['critical', 'high', 'medium', 'low'];
+const CATEGORIES = [
+  'correctness',
+  'security',
+  'data-loss',
+  'concurrency',
+  'performance',
+  'error-handling',
+  'compatibility',
+  'test-gap',
+  'maintainability',
+  'documentation',
+];
+const DISPOSITIONS = ['confirmed', 'refuted', 'unresolved'];
+const CONFIDENCE = ['high', 'medium', 'low'];
+const OUTCOMES = ['completed', 'failed', 'waived'];
+
+/** Files whose content must never reach a review packet, whatever an include pattern says. */
+const SECRET_PATTERNS = [
+  '**/.env',
+  '**/.env.*',
+  '**/*.pem',
+  '**/*.key',
+  '**/*.p12',
+  '**/*.pfx',
+  '**/id_rsa*',
+  '**/id_ed25519*',
+  '**/.credentials/**',
+  '**/credentials/**',
+  '**/secrets/**',
+  '**/*.keystore',
+  '**/.npmrc',
+  '**/.netrc',
+];
+const GENERATED_PATTERNS = [
+  '**/node_modules/**',
+  '**/dist/**',
+  '**/build/**',
+  '**/coverage/**',
+  '**/vendor/**',
+  '**/*.min.js',
+  '**/*.min.css',
+  '**/*.map',
+  '**/package-lock.json',
+  '**/yarn.lock',
+  '**/pnpm-lock.yaml',
+  '**/Cargo.lock',
+  '**/go.sum',
+  '**/poetry.lock',
+];
+const UNIT_LIMITS = { files: 8, lines: 400 };
+
+const sha256 = (value) => crypto.createHash('sha256').update(value).digest('hex');
+
+/** A small glob: `**` spans directories, `*` stays within one, `?` is one character. Case-sensitive. */
+function globToRegExp(glob) {
+  let source = '';
+  for (let i = 0; i < glob.length; i++) {
+    const c = glob[i];
+    if (c === '*' && glob[i + 1] === '*') {
+      const slash = glob[i + 2] === '/';
+      source += slash ? '(?:.*/)?' : '.*';
+      i += slash ? 2 : 1;
+    } else if (c === '*') source += '[^/]*';
+    else if (c === '?') source += '[^/]';
+    else source += c.replace(/[.+^${}()|[\]\\]/g, '\\$&');
+  }
+  return new RegExp(`^${source}$`);
+}
+const matchesAny = (file, patterns) => patterns.some((glob) => globToRegExp(glob).test(file));
+
+function git(projectDir, args) {
+  const result = spawnSync('git', args, {
+    cwd: projectDir,
+    encoding: 'utf8',
+    maxBuffer: 64 * 1024 * 1024,
+    windowsHide: true,
+    shell: false,
+  });
+  if (result.error) throw new Error(`git is unavailable: ${result.error.message}`);
+  if (result.status !== 0)
+    throw new Error(`git ${args[0]} failed: ${(result.stderr || '').trim().split('\n')[0]}`);
+  return result.stdout;
+}
+
+/** A ref given on the command line is resolved to a commit or refused; it never reaches git as an option. */
+function resolveCommit(projectDir, ref) {
+  if (typeof ref !== 'string' || !ref || ref.startsWith('-'))
+    throw new Error(`invalid ref "${ref}"`);
+  return git(projectDir, ['rev-parse', '--verify', '--end-of-options', `${ref}^{commit}`]).trim();
+}
+
+/** `git diff --numstat -z` entries: {path, oldPath?, added, removed, binary}. */
+function parseNumstat(output) {
+  const parts = output.split('\0');
+  const entries = [];
+  for (let i = 0; i < parts.length; i++) {
+    const head = parts[i];
+    if (!head) continue;
+    const match = /^(-|\d+)\t(-|\d+)\t(.*)$/.exec(head);
+    if (!match) continue;
+    const [, added, removed, rest] = match;
+    const binary = added === '-' || removed === '-';
+    if (rest === '') {
+      // Rename or copy: old path and new path follow as separate fields.
+      const oldPath = parts[++i];
+      const newPath = parts[++i];
+      entries.push({ path: newPath, oldPath, added: +added || 0, removed: +removed || 0, binary });
+    } else {
+      entries.push({ path: rest, added: +added || 0, removed: +removed || 0, binary });
+    }
+  }
+  return entries;
+}
+
+function nameStatus(output) {
+  const parts = output.split('\0');
+  const status = new Map();
+  for (let i = 0; i < parts.length; i++) {
+    const code = parts[i];
+    if (!code) continue;
+    const kind = code[0];
+    if (kind === 'R' || kind === 'C') {
+      i += 2;
+      status.set(parts[i], kind === 'R' ? 'renamed' : 'copied');
+    } else {
+      i += 1;
+      status.set(
+        parts[i],
+        { A: 'added', D: 'deleted', M: 'modified', T: 'modified' }[kind] || 'modified'
+      );
+    }
+  }
+  return status;
+}
+
+/** Deterministic review units: files grouped by directory, cut at the file and line limits, in path order. */
+function planUnits(selected, limits = UNIT_LIMITS) {
+  const units = [];
+  let current = null;
+  const flush = () => {
+    if (current && current.paths.length) units.push(current);
+    current = null;
+  };
+  for (const item of selected) {
+    const dir = path.posix.dirname(item.path);
+    const lines = item.added + item.removed;
+    if (
+      !current ||
+      current.dir !== dir ||
+      current.paths.length >= limits.files ||
+      (current.lines + lines > limits.lines && current.paths.length > 0)
+    ) {
+      flush();
+      current = { dir, paths: [], lines: 0 };
+    }
+    current.paths.push(item.path);
+    current.lines += lines;
+  }
+  flush();
+  return units.map((unit, index) => ({
+    id: `u${index + 1}`,
+    paths: unit.paths,
+    lines: unit.lines,
+  }));
+}
+
+/**
+ * The review scope: what changed between base and head (or the working tree), which files
+ * are selected, and why every other changed file is not. Secrets are excluded before any
+ * include pattern is considered.
+ */
+function buildScope(projectDir, options = {}) {
+  const head = options.workspace ? null : resolveCommit(projectDir, options.head || 'HEAD');
+  const base = resolveCommit(projectDir, options.base || 'HEAD~1');
+  const mergeBase = git(projectDir, ['merge-base', base, head || 'HEAD']).trim();
+  const range = options.workspace ? [mergeBase] : [mergeBase, head];
+  const numstat = parseNumstat(
+    git(projectDir, ['diff', '--numstat', '-z', '--find-renames', ...range, '--'])
+  );
+  const statuses = nameStatus(
+    git(projectDir, ['diff', '--name-status', '-z', '--find-renames', ...range, '--'])
+  );
+  const changed = numstat.map((entry) => ({
+    ...entry,
+    status: statuses.get(entry.path) || 'modified',
+  }));
+  if (options.workspace) {
+    const untracked = git(projectDir, ['ls-files', '--others', '--exclude-standard', '-z'])
+      .split('\0')
+      .filter(Boolean);
+    for (const file of untracked) {
+      if (changed.some((entry) => entry.path === file)) continue;
+      let lines = 0;
+      let binary;
+      try {
+        const bytes = fs.readFileSync(path.join(projectDir, file));
+        binary = bytes.includes(0);
+        lines = binary ? 0 : bytes.toString('utf8').split('\n').length;
+      } catch {
+        binary = true;
+      }
+      changed.push({ path: file, added: lines, removed: 0, binary, status: 'added' });
+    }
+  }
+  changed.sort((a, b) => a.path.localeCompare(b.path));
+
+  const include = options.include || [];
+  const exclude = options.exclude || [];
+  const selected = [];
+  const excluded = [];
+  for (const entry of changed) {
+    const file = entry.path;
+    let reason = null;
+    if (matchesAny(file, SECRET_PATTERNS)) reason = 'secret';
+    else if (entry.binary) reason = 'binary';
+    else if (entry.status === 'deleted') reason = 'deleted';
+    else if (matchesAny(file, exclude)) reason = 'excluded-by-pattern';
+    else if (matchesAny(file, GENERATED_PATTERNS) && !matchesAny(file, include))
+      reason = 'generated-or-vendored';
+    else if (include.length && !matchesAny(file, include)) reason = 'not-included';
+    if (reason) excluded.push({ path: file, reason, status: entry.status });
+    else
+      selected.push({
+        path: file,
+        status: entry.status,
+        added: entry.added,
+        removed: entry.removed,
+        ...(entry.oldPath ? { oldPath: entry.oldPath } : {}),
+      });
+  }
+  const identity = {
+    base,
+    head: head || 'WORKTREE',
+    mergeBase,
+    workspace: Boolean(options.workspace),
+    include,
+    exclude,
+  };
+  const units = planUnits(selected, options.unitLimits);
+  const lines = selected.reduce((n, item) => n + item.added + item.removed, 0);
+  const body = { identity, selected, excluded, units };
+  return {
+    schema: SCOPE_SCHEMA,
+    id: options.id,
+    ...body,
+    totals: {
+      changed: changed.length,
+      selected: selected.length,
+      excluded: excluded.length,
+      lines,
+    },
+    sha256: sha256(JSON.stringify(body)),
+  };
+}
+
+// ── Findings ──────────────────────────────────────────────────────────────────
+
+const FINDING_KEYS = [
+  'id',
+  'path',
+  'existing_code',
+  'content',
+  'category',
+  'severity',
+  'confidence',
+  'disposition',
+  'trigger',
+  'consequence',
+  'evidence',
+  'refutation',
+  'fix',
+];
+
+/** Unknown values are errors, never coerced: a wrong enum is a wrong finding. */
+function validateFindings(doc, scope) {
+  const errors = [];
+  if (!doc || doc.schema !== FINDINGS_SCHEMA) errors.push(`schema must be "${FINDINGS_SCHEMA}"`);
+  if (scope && doc && doc.scopeSha256 !== scope.sha256)
+    errors.push(
+      'scopeSha256 does not match the current scope — the findings answer another review'
+    );
+  const ids = new Set();
+  for (const [index, finding] of ((doc && doc.findings) || []).entries()) {
+    const at = `finding ${finding?.id ?? index}`;
+    for (const key of Object.keys(finding || {}))
+      if (!FINDING_KEYS.includes(key)) errors.push(`${at}: unknown key "${key}"`);
+    if (!finding.id || ids.has(finding.id)) errors.push(`${at}: id missing or duplicated`);
+    ids.add(finding.id);
+    if (typeof finding.path !== 'string' || !finding.path) errors.push(`${at}: path is required`);
+    if (typeof finding.existing_code !== 'string' || !finding.existing_code.trim())
+      errors.push(
+        `${at}: existing_code is required — quote the code the finding is about, verbatim`
+      );
+    if (typeof finding.content !== 'string' || !finding.content.trim())
+      errors.push(`${at}: content is required`);
+    if (!CATEGORIES.includes(finding.category))
+      errors.push(`${at}: category "${finding.category}" is not one of ${CATEGORIES.join('|')}`);
+    if (!SEVERITIES.includes(finding.severity))
+      errors.push(`${at}: severity "${finding.severity}" is not one of ${SEVERITIES.join('|')}`);
+    if (!CONFIDENCE.includes(finding.confidence))
+      errors.push(
+        `${at}: confidence "${finding.confidence}" is not one of ${CONFIDENCE.join('|')}`
+      );
+    if (!DISPOSITIONS.includes(finding.disposition))
+      errors.push(
+        `${at}: disposition "${finding.disposition}" is not one of ${DISPOSITIONS.join('|')}`
+      );
+    if (finding.disposition === 'refuted' && !String(finding.refutation || '').trim())
+      errors.push(`${at}: a refuted finding keeps its refutation — the quoted ground`);
+    if (finding.disposition === 'confirmed' && !String(finding.evidence || '').trim())
+      errors.push(`${at}: a confirmed finding needs evidence`);
+    if (scope && finding.path && !scope.selected.some((item) => item.path === finding.path))
+      errors.push(`${at}: ${finding.path} is not in the review scope`);
+  }
+  return errors;
+}
+
+const normalizeLine = (line) => line.replace(/\r$/, '').replace(/\s+/g, ' ').trim();
+
+/**
+ * Where a quoted snippet is in a file: every place its lines appear consecutively, compared
+ * after whitespace normalisation. The model's line numbers are never used.
+ */
+function locate(fileText, snippet) {
+  const fileLines = fileText.split('\n').map(normalizeLine);
+  const wanted = snippet
+    .split('\n')
+    .map(normalizeLine)
+    .filter((line, index, all) => line || (index > 0 && index < all.length - 1));
+  while (wanted.length && !wanted[0]) wanted.shift();
+  while (wanted.length && !wanted[wanted.length - 1]) wanted.pop();
+  if (!wanted.length) return [];
+  const hits = [];
+  for (let i = 0; i + wanted.length <= fileLines.length; i++) {
+    let ok = true;
+    for (let j = 0; j < wanted.length; j++) {
+      if (fileLines[i + j] !== wanted[j]) {
+        ok = false;
+        break;
+      }
+    }
+    if (ok) hits.push({ lineStart: i + 1, lineEnd: i + wanted.length });
+  }
+  return hits;
+}
+
+function readAtHead(projectDir, scope, file) {
+  if (scope.identity.workspace) return fs.readFileSync(path.join(projectDir, file), 'utf8');
+  return git(projectDir, ['show', `${scope.identity.head}:${file}`]);
+}
+
+/** Every finding gets a location status: located (unique), ambiguous (several), unlocated (none). */
+function anchorFindings(projectDir, scope, doc) {
+  const cache = new Map();
+  const anchored = doc.findings.map((finding) => {
+    let text = cache.get(finding.path);
+    if (text === undefined) {
+      try {
+        text = readAtHead(projectDir, scope, finding.path);
+      } catch {
+        text = null;
+      }
+      cache.set(finding.path, text);
+    }
+    if (text === null)
+      return { ...finding, location: { status: 'unlocated', reason: 'file unreadable at head' } };
+    const hits = locate(text, finding.existing_code);
+    if (hits.length === 1) return { ...finding, location: { status: 'located', ...hits[0] } };
+    if (hits.length > 1)
+      return { ...finding, location: { status: 'ambiguous', candidates: hits.slice(0, 10) } };
+    return {
+      ...finding,
+      location: { status: 'unlocated', reason: 'the quoted code is not in the file' },
+    };
+  });
+  const counts = { located: 0, ambiguous: 0, unlocated: 0 };
+  for (const finding of anchored) counts[finding.location.status] += 1;
+  return { findings: anchored, counts };
+}
+
+// ── Coverage and gate ─────────────────────────────────────────────────────────
+
+function validateCoverage(doc, scope) {
+  const errors = [];
+  if (!doc || doc.schema !== COVERAGE_SCHEMA) errors.push(`schema must be "${COVERAGE_SCHEMA}"`);
+  if (doc && doc.scopeSha256 !== scope.sha256)
+    errors.push('scopeSha256 does not match the current scope');
+  const seen = new Set();
+  for (const item of (doc && doc.items) || []) {
+    if (!scope.selected.some((entry) => entry.path === item.path))
+      errors.push(`${item.path}: not in the review scope`);
+    if (seen.has(item.path)) errors.push(`${item.path}: listed twice`);
+    seen.add(item.path);
+    if (!OUTCOMES.includes(item.outcome))
+      errors.push(`${item.path}: outcome "${item.outcome}" is not one of ${OUTCOMES.join('|')}`);
+    if (
+      (item.outcome === 'waived' || item.outcome === 'failed') &&
+      !String(item.reason || '').trim()
+    )
+      errors.push(`${item.path}: a ${item.outcome} file needs a reason`);
+  }
+  return errors;
+}
+
+/**
+ * The review verdict. `incomplete` whenever a selected file was not accounted for, failed,
+ * or the evidence is invalid; otherwise `findings` or `clean` — the latter only means no
+ * confirmed or unresolved finding within a fully covered scope.
+ */
+function reviewGate({ scope, findings, coverage, anchored }) {
+  const reasons = [];
+  if (!coverage) reasons.push('no coverage.json: which files were reviewed is not established');
+  else reasons.push(...validateCoverage(coverage, scope));
+  if (!findings) reasons.push('no findings.json: write it even when there is nothing to report');
+  else reasons.push(...validateFindings(findings, scope));
+  const covered = new Map(((coverage && coverage.items) || []).map((item) => [item.path, item]));
+  const missing = scope.selected.filter((item) => !covered.has(item.path)).map((item) => item.path);
+  const failed = [...covered.values()]
+    .filter((item) => item.outcome === 'failed')
+    .map((item) => item.path);
+  const waived = [...covered.values()]
+    .filter((item) => item.outcome === 'waived')
+    .map((item) => item.path);
+  if (missing.length)
+    reasons.push(
+      `${missing.length} selected file(s) never accounted for: ${missing.slice(0, 5).join(', ')}${missing.length > 5 ? '…' : ''}`
+    );
+  if (failed.length)
+    reasons.push(`${failed.length} file(s) whose review failed: ${failed.slice(0, 5).join(', ')}`);
+  const open = ((anchored && anchored.findings) || []).filter((f) => f.disposition !== 'refuted');
+  const unlocated = open.filter((f) => f.location.status !== 'located');
+  if (unlocated.length)
+    reasons.push(
+      `${unlocated.length} open finding(s) not anchored on the code at head: ${unlocated
+        .map((f) => f.id)
+        .slice(0, 5)
+        .join(', ')}`
+    );
+  const total = scope.selected.length;
+  const done = [...covered.values()].filter((item) => item.outcome === 'completed').length;
+  const coverageRate = total ? Math.round((done / total) * 1000) / 10 : 100;
+  const status = reasons.length ? 'incomplete' : open.length ? 'findings' : 'clean';
+  return {
+    status,
+    reasons,
+    coverage: {
+      selected: total,
+      completed: done,
+      waived: waived.length,
+      failed: failed.length,
+      missing: missing.length,
+      rate: coverageRate,
+    },
+    findings: {
+      open: open.length,
+      confirmed: open.filter((f) => f.disposition === 'confirmed').length,
+      unresolved: open.filter((f) => f.disposition === 'unresolved').length,
+      refuted: ((anchored && anchored.findings) || []).length - open.length,
+      bySeverity: Object.fromEntries(
+        SEVERITIES.map((s) => [s, open.filter((f) => f.severity === s).length])
+      ),
+    },
+  };
+}
+
+function layout(projectDir, dir = DEFAULT_DIR, id) {
+  const root = path.resolve(projectDir, dir, id);
+  return {
+    root,
+    scope: path.join(root, 'scope.json'),
+    findings: path.join(root, 'findings.json'),
+    anchored: path.join(root, 'findings.anchored.json'),
+    coverage: path.join(root, 'coverage.json'),
+  };
+}
+
+module.exports = {
+  SCOPE_SCHEMA,
+  FINDINGS_SCHEMA,
+  COVERAGE_SCHEMA,
+  DEFAULT_DIR,
+  SEVERITIES,
+  CATEGORIES,
+  DISPOSITIONS,
+  CONFIDENCE,
+  OUTCOMES,
+  SECRET_PATTERNS,
+  GENERATED_PATTERNS,
+  globToRegExp,
+  parseNumstat,
+  planUnits,
+  buildScope,
+  validateFindings,
+  locate,
+  anchorFindings,
+  validateCoverage,
+  reviewGate,
+  layout,
+};

package/tools/cli/lib/uat.js

@@ -90,7 +90,7 @@ function readJson(file) {
   const stat = fs.lstatSync(file);
   if (stat.isSymbolicLink()) throw new Error(`${file} is a symbolic link; refused.`);
   if (stat.size > MAX_FILE) throw new Error(`${file} exceeds ${MAX_FILE} bytes.`);
-  return JSON.parse(fs.readFileSync(file, 'utf8'));
+  return JSON.parse(fs.readFileSync(file, 'utf8').replace(/^\uFEFF/, '')); // PowerShell 5.1 writes a BOM
 }
 
 // ── Spec: legacy adapter, validation, lint ────────────────────────────────────
@@ -472,8 +472,144 @@ function languageCode(value, strings = STRINGS) {
   return Object.keys(strings).find((code) => code.toLowerCase().split('-')[0] === base) || null;
 }
 
+/**
+ * What every built page guarantees a tester, by construction. Each entry names a
+ * behaviour the DOM suite exercises (tests/unit/uat-page.test.js) and the literal
+ * the template must carry for it. A template that lost one does not build: the
+ * FormaPro incident of 2026-09-25 (answers typed before any run existed, then lost
+ * on reload, with a "saved" status nobody had verified) came from exactly such a loss.
+ */
+const PAGE_GUARANTEES = [
+  {
+    id: 'hidden-before-start',
+    what: 'no answer field is shown before a run exists, whatever a class says about display',
+    // The rule must also be the LAST rule of the sheet: a later !important display rule would beat it.
+    markers: [
+      '[hidden] { display: none !important; }\n</style>',
+      '<main class="steps" id="steps" hidden>',
+    ],
+  },
+  {
+    id: 'no-answer-before-run',
+    what: 'a tick or a note before the run starts is refused and explained, never discarded in silence',
+    markers: [
+      'function requireRun(',
+      'T.startFirst',
+      '!requireRun(event)',
+      'if (!requireRun()) return;',
+    ],
+  },
+  {
+    id: 'verified-local-write',
+    what: 'a write to this browser counts only once it reads back; a refused write returns false',
+    markers: ['return localStorage.getItem(k) === v;', 'function saveLocal()'],
+  },
+  {
+    id: 'honest-save-status',
+    what: 'the status line reports the verified outcome, and names a failed save',
+    markers: ['function showSaveState(', 'T.saveFailed', 'T.remoteFailed', 'T.saving'],
+  },
+  {
+    id: 'save-on-every-change',
+    what: 'every tick and every keystroke in a note is saved at once, without waiting for blur, and a save never moves the cursor',
+    markers: [
+      'addEventListener("change"',
+      'addEventListener("input"',
+      'document.activeElement !== field',
+    ],
+  },
+  {
+    id: 'restore-before-capabilities',
+    what: 'the browser copy is restored synchronously, before any optional capability answers',
+    markers: ['function restoreLocal()'],
+    order: ['restoreLocal();', 'probe()'],
+  },
+  {
+    id: 'newer-copy-wins',
+    what: 'an older remote copy never overwrites a newer local one; a copy without a date is the oldest of all',
+    markers: ['function connectDb()', 'remoteNewer', 'function at(', 'function adopt('],
+  },
+  {
+    id: 'revision-guard',
+    what: 'a run that answered another revision is offered, explained and carried by an explicit rule, never poured in blindly',
+    markers: ['function sameRevision(', 'function carry(', 'T.otherRevision', 'T.continueHere'],
+  },
+  {
+    id: 'other-tab-notice',
+    what: 'two tabs on one run converge on the latest change, and the page says so',
+    markers: ['addEventListener("storage"', 'T.otherTab'],
+  },
+  {
+    id: 'unreadable-draft-kept',
+    what: 'a saved run that cannot be read is reported and exportable, never deleted',
+    markers: ['id="draft-problem"', 'T.draftUnreadable', 'id="btn-save-raw"'],
+  },
+  {
+    id: 'progress-accessible',
+    what: 'the share of lines answered is exposed with a progressbar role and value; answered is not passed',
+    markers: ['role="progressbar"', 'aria-valuenow', 'T.percentAnswered'],
+  },
+  {
+    id: 'storage-explained',
+    what: 'the page says where answers live and what can make them disappear',
+    markers: ['id="storage-note"', 'id="mode-note"'],
+  },
+  {
+    id: 'finished-is-not-accepted',
+    what: 'finishing keeps the date and says it is not an acceptance',
+    markers: ['T.finishedNote', 'run.finishedAt = new Date().toISOString();'],
+  },
+  {
+    id: 'unload-guard',
+    what: 'leaving with an unsaved run is questioned; pending remote writes are flushed',
+    markers: ['addEventListener("beforeunload"', 'addEventListener("pagehide"'],
+  },
+  {
+    id: 'utf8-and-escaped-diacritics',
+    what: 'the page declares UTF-8 and writes the combining-mark range as escapes',
+    markers: ['<meta charset="utf-8">', '\\u0300-\\u036f'],
+  },
+  {
+    id: 'export-is-the-run',
+    what: 'the exported JSON is the run as answered, and nothing is exported before a run exists',
+    markers: ['download(runId + ".json", JSON.stringify(run, null, 2))'],
+  },
+];
+
+/**
+ * Which guarantees a template carries: every marker present, in the required order where one
+ * is set. Checked on the TEMPLATE, never on the built page: a recipe's own text must not be
+ * able to satisfy or defeat a marker.
+ */
+function pageGuarantees(template) {
+  const missing = [];
+  for (const guarantee of PAGE_GUARANTEES) {
+    const lost = guarantee.markers.filter((marker) => !template.includes(marker));
+    if (!lost.length && guarantee.order) {
+      const positions = guarantee.order.map((marker) => template.indexOf(marker));
+      if (positions.some((at) => at < 0) || positions.some((at, i) => i && at < positions[i - 1]))
+        lost.push(`order ${guarantee.order.join(' → ')}`);
+    }
+    if (lost.length) missing.push({ id: guarantee.id, what: guarantee.what, lost });
+  }
+  const carried = PAGE_GUARANTEES.map((g) => g.id).filter(
+    (id) => !missing.some((entry) => entry.id === id)
+  );
+  return { ok: missing.length === 0, carried, missing };
+}
+
 function buildPage(spec, options = {}) {
   const template = options.template || fs.readFileSync(TEMPLATE, 'utf8');
+  // A page missing one guarantee is not a page: refusing here is what keeps a tester's
+  // answers safe in an installation that has no test suite of its own.
+  const guarantees = pageGuarantees(template);
+  if (!guarantees.ok) {
+    throw new Error(
+      `the page template (${options.template ? 'the template given' : TEMPLATE}) lost a guarantee — not built: ${guarantees.missing
+        .map((entry) => `${entry.id}: ${entry.what} — missing ${entry.lost.join(', ')}`)
+        .join('; ')}`
+    );
+  }
   const hash = specHash(spec);
   const json = canonical(spec).replace(/<\//g, '<\\/');
   const strings = options.strings || STRINGS;
@@ -502,7 +638,7 @@ function buildPage(spec, options = {}) {
       cause: error,
     });
   }
-  return { html, sha256: hash, language };
+  return { html, sha256: hash, language, guarantees: guarantees.carried };
 }
 
 // ── Runs: legacy adapter, normalisation, reading ──────────────────────────────
@@ -873,6 +1009,8 @@ module.exports = {
   lintSpec,
   screenLabels,
   buildPage,
+  PAGE_GUARANTEES,
+  pageGuarantees,
   languageCode,
   normalizeRun,
   readRuns,