bmad-plus 0.20.0 → 0.21.0

package/src/bmad-plus/packs/pack-seo/scripts/seo_fetch.py

@@ -3,7 +3,8 @@
 SEO Fetch — Secure HTTP page fetcher for SEO analysis.
 
 Features:
-- SSRF protection (blocks private/loopback/reserved IPs)
+- SSRF protection (blocks private/loopback/reserved IPs, re-checked on every
+  redirect hop, connection pinned to the validated address)
 - Multi-UA support (standard, Googlebot, GPTBot, ClaudeBot)
 - Redirect chain tracking
 - Cookie handling
@@ -16,12 +17,16 @@ License: MIT
 import argparse
 import ipaddress
 import json
+import os
 import socket
 import sys
+import time
 from urllib.parse import urljoin, urlparse
 
 try:
     import requests
+    from requests.adapters import DEFAULT_POOLBLOCK, HTTPAdapter
+    from urllib3 import PoolManager
 except ImportError:
     print("Error: requests library required. Install: pip install requests", file=sys.stderr)
     sys.exit(1)
@@ -61,10 +66,37 @@ DEFAULT_HEADERS = {
 
 # ── Security: SSRF Prevention ──────────────────────────────────────
 
+ALLOWED_SCHEMES = frozenset({"http", "https"})
+
+# RFC 6052 well-known NAT64 prefix: the last 32 bits are the IPv4 host the
+# translator will reach, so the address is only as safe as that IPv4 host.
+_NAT64_PREFIX = ipaddress.ip_network("64:ff9b::/96")
+
+
+class UnsafeURLError(requests.exceptions.InvalidURL):
+    """A URL, or the address it resolves to, must never be fetched."""
+
+
 def _ip_is_blocked(ip: "ipaddress._BaseAddress") -> bool:
-    """Return True if an IP falls in any range that must never be reached."""
+    """Return True if an IP falls in any range that must never be reached.
+
+    Anything that is not globally routable is refused: private, loopback,
+    link-local (cloud metadata at 169.254.169.254), carrier-grade NAT
+    (100.64.0.0/10, e.g. Alibaba metadata at 100.100.100.200), documentation
+    and benchmarking ranges, multicast and reserved space. IPv6 forms that
+    embed an IPv4 destination are judged by that destination.
+    """
+    if ip.version == 6:
+        embedded = ip.ipv4_mapped
+        if embedded is None and ip in _NAT64_PREFIX:
+            embedded = ipaddress.IPv4Address(int(ip) & 0xFFFFFFFF)
+        if embedded is not None:
+            return _ip_is_blocked(embedded)
+        if ip.is_site_local:
+            return True
     return bool(
-        ip.is_private
+        not ip.is_global
+        or ip.is_private
         or ip.is_loopback
         or ip.is_reserved
         or ip.is_link_local
@@ -73,47 +105,152 @@ def _ip_is_blocked(ip: "ipaddress._BaseAddress") -> bool:
     )
 
 
-def is_safe_url(url: str) -> bool:
-    """Block requests to private, loopback, and reserved IP addresses.
+def check_url(url: str) -> str:
+    """Apply the URL-level rules and return the hostname, without resolving it.
 
-    Fails CLOSED: a missing host, a non-HTTP(S) scheme, a DNS resolution
-    error, or an unparseable/blocked address all cause the URL to be
-    rejected. Every resolved address (IPv4 and IPv6) must be public.
+    Fails CLOSED with UnsafeURLError: a scheme outside http/https, embedded
+    credentials, a missing host or an invalid port rejects the URL.
     """
     parsed = urlparse(url)
+    if parsed.scheme not in ALLOWED_SCHEMES:
+        raise UnsafeURLError(f"scheme not allowed: {parsed.scheme or '(none)'}")
+    # "user:pass@" would be sent as an Authorization header and makes
+    # "https://trusted.example@evil.example/" style URLs misleading.
+    if parsed.username is not None or parsed.password is not None:
+        raise UnsafeURLError("credentials in URL are not allowed")
     hostname = parsed.hostname
-
     if not hostname:
-        return False
+        raise UnsafeURLError("URL has no host")
+    try:
+        parsed.port
+    except ValueError:
+        raise UnsafeURLError("URL has an invalid port") from None
+    return hostname
 
-    if parsed.scheme not in ("http", "https"):
-        return False
 
+def resolve_public_address(hostname: str) -> str:
+    """Resolve a hostname and return the public address to connect to.
+
+    Fails CLOSED with UnsafeURLError on a DNS error or when any resolved
+    address (IPv4 or IPv6) is not public: every address the name resolves to
+    must be public, so the returned one is safe whichever the resolver would
+    have preferred.
+    """
     try:
-        # Resolve ALL IP addresses (IPv4 and IPv6) via getaddrinfo
         addrinfo = socket.getaddrinfo(hostname, None)
-    except socket.gaierror:
-        return False  # Fail closed: unresolvable host is treated as unsafe
-
-    if not addrinfo:
-        return False  # Fail closed: no addresses resolved
+    except (socket.gaierror, UnicodeError):
+        raise UnsafeURLError(f"cannot resolve host {hostname}") from None
 
+    addresses = []
     for entry in addrinfo:
-        ip_str = entry[4][0]  # sockaddr[0] contains the IP string
         try:
-            ip = ipaddress.ip_address(ip_str)
+            ip = ipaddress.ip_address(entry[4][0])
         except ValueError:
-            return False  # Fail closed: unparseable address
-        # IPv4-mapped IPv6 (::ffff:a.b.c.d) must be checked as its IPv4 form
-        mapped = getattr(ip, "ipv4_mapped", None)
-        if mapped is not None and _ip_is_blocked(mapped):
-            return False
+            raise UnsafeURLError(f"{hostname} resolved to an unparseable address") from None
         if _ip_is_blocked(ip):
-            return False
+            raise UnsafeURLError(f"{hostname} resolves to a private/internal address ({ip})")
+        addresses.append(ip)
+    if not addresses:
+        raise UnsafeURLError(f"cannot resolve host {hostname}")
+
+    # A pinned connection cannot fall back to another address, and IPv6 routes
+    # are often missing in containers and CI: prefer IPv4 on dual-stack hosts.
+    preferred = next((ip for ip in addresses if ip.version == 4), addresses[0])
+    return str(preferred)
+
 
+def resolve_target(url: str) -> "tuple[str, str]":
+    """Validate a URL and return ``(hostname, address)`` to connect to.
+
+    Combines check_url() and resolve_public_address(); see their rules.
+    """
+    hostname = check_url(url)
+    return hostname, resolve_public_address(hostname)
+
+
+def is_safe_url(url: str) -> bool:
+    """Return True when resolve_target() accepts the URL (see its rules)."""
+    try:
+        resolve_target(url)
+    except UnsafeURLError:
+        return False
     return True
 
 
+class _PinnedPoolManager(PoolManager):
+    """urllib3 pool manager that only opens pools on validated IP literals.
+
+    Every requests version reaches the network through
+    PoolManager.connection_from_host (directly, or via connection_from_url),
+    whatever adapter hook it calls first. Validating here, instead of in a
+    requests hook that has been renamed across releases, keeps the guard
+    closed on old and future requests versions alike.
+    """
+
+    def connection_from_host(self, host, port=None, scheme="http", pool_kwargs=None):
+        hostname = (host or "").strip("[]")
+        if not hostname:
+            raise UnsafeURLError("URL has no host")
+        address = resolve_public_address(hostname)
+        if scheme == "https":
+            pool_kwargs = dict(pool_kwargs or {})
+            pool_kwargs["server_hostname"] = hostname
+            pool_kwargs["assert_hostname"] = hostname
+        return super().connection_from_host(
+            address, port=port, scheme=scheme, pool_kwargs=pool_kwargs
+        )
+
+
+class PinnedAddressAdapter(HTTPAdapter):
+    """Transport adapter that connects to the exact address it validated.
+
+    A plain requests call resolves the host again when urllib3 opens the
+    socket, so a hostile DNS server can answer a public address to the SSRF
+    check and a private one to the connection (DNS rebinding). This adapter's
+    pool manager resolves and validates each host itself, then opens the
+    connection pool on that IP literal. The Host header, TLS SNI and the
+    certificate hostname check still use the original name, so HTTPS
+    verification is unchanged. Proxies are refused: a proxy would resolve the
+    name itself and bypass the pinned address.
+    """
+
+    def init_poolmanager(self, connections, maxsize, block=DEFAULT_POOLBLOCK, **pool_kwargs):
+        super().init_poolmanager(connections, maxsize, block, **pool_kwargs)
+        # Rebuild with the exact settings requests chose for this version.
+        self.poolmanager = _PinnedPoolManager(
+            num_pools=connections, **self.poolmanager.connection_pool_kw
+        )
+
+    def proxy_manager_for(self, proxy, **proxy_kwargs):
+        raise UnsafeURLError("proxies are not supported by the pinned transport")
+
+    def send(self, request, **kwargs):
+        check_url(request.url)
+        # urllib3 would derive Host from the pool's IP literal; keep the name.
+        if "Host" not in request.headers:
+            request.headers["Host"] = urlparse(request.url).netloc.rpartition("@")[2]
+        return super().send(request, **kwargs)
+
+
+def create_session() -> requests.Session:
+    """Build a requests session whose every connection is SSRF-checked and pinned.
+
+    Environment proxies and ~/.netrc credentials are ignored: a proxy defeats
+    address pinning and netrc would attach credentials to attacker-chosen hosts.
+    A custom CA bundle named by REQUESTS_CA_BUNDLE or CURL_CA_BUNDLE (corporate
+    TLS inspection) is still honoured, since it does not weaken pinning.
+    """
+    session = requests.Session()
+    session.trust_env = False
+    ca_bundle = os.environ.get("REQUESTS_CA_BUNDLE") or os.environ.get("CURL_CA_BUNDLE")
+    if ca_bundle:
+        session.verify = ca_bundle
+    adapter = PinnedAddressAdapter()
+    session.mount("http://", adapter)
+    session.mount("https://", adapter)
+    return session
+
+
 # ── Core Fetcher ───────────────────────────────────────────────────
 
 def fetch_page(
@@ -147,37 +284,24 @@ def fetch_page(
         url = f"https://{url}"
         parsed = urlparse(url)
 
-    if parsed.scheme not in ("http", "https"):
+    if parsed.scheme not in ALLOWED_SCHEMES:
         result["error"] = f"Invalid URL scheme: {parsed.scheme}"
         return result
 
-    # SSRF check
-    if not is_safe_url(url):
-        resolved = "unknown"
-        try:
-            # Use getaddrinfo for consistent multi-address resolution
-            addrinfo = socket.getaddrinfo(parsed.hostname, None)
-            resolved = ", ".join(set(entry[4][0] for entry in addrinfo))
-        except Exception:
-            pass
-        result["error"] = f"Blocked: URL resolves to private/internal IP ({resolved})"
-        return result
-
+    current_url = url
     try:
-        session = requests.Session()
+        session = create_session()
 
         headers = dict(DEFAULT_HEADERS)
         ua_string = USER_AGENTS.get(user_agent, user_agent)
         headers["User-Agent"] = ua_string
 
-        import time
         start = time.monotonic()
 
-        # Follow redirects manually so is_safe_url() runs on EVERY hop.
-        # Letting requests follow redirects internally would allow a
-        # public URL to redirect (302) to an internal/metadata endpoint
-        # (redirect-based SSRF), bypassing the initial check.
-        current_url = url
+        # Follow redirects manually so every hop goes back through the pinned
+        # adapter, which validates the target before connecting. Letting
+        # requests follow redirects internally would hide the hop count and
+        # the chain; the adapter still guards each connection either way.
         redirect_chain = []
         hops = 0
         response = None
@@ -198,19 +322,9 @@ def fetch_page(
                 break
 
             next_url = urljoin(current_url, location)
-            next_parsed = urlparse(next_url)
-
-            if next_parsed.scheme not in ("http", "https"):
-                result["error"] = (
-                    f"Blocked redirect to non-HTTP(S) scheme: {next_parsed.scheme}"
-                )
-                return result
-
-            # Re-validate the redirect target (blocks redirect-based SSRF)
-            if not is_safe_url(next_url):
-                result["error"] = (
-                    f"Blocked: redirect to private/internal URL ({next_url})"
-                )
+            next_scheme = urlparse(next_url).scheme
+            if next_scheme not in ALLOWED_SCHEMES:
+                result["error"] = f"Blocked redirect to non-HTTP(S) scheme: {next_scheme}"
                 return result
 
             hops += 1
@@ -221,6 +335,7 @@ def fetch_page(
             redirect_chain.append(
                 {"url": current_url, "status": response.status_code}
             )
+            response.close()
             current_url = next_url
 
         elapsed_ms = round((time.monotonic() - start) * 1000)
@@ -233,6 +348,11 @@ def fetch_page(
         result["response_time_ms"] = elapsed_ms
         result["redirect_chain"] = redirect_chain
 
+    except UnsafeURLError as e:
+        if current_url == url:
+            result["error"] = f"Blocked: {e}"
+        else:
+            result["error"] = f"Blocked: redirect to private/internal URL ({current_url}): {e}"
     except requests.exceptions.Timeout:
         result["error"] = f"Request timed out after {timeout}s"
     except requests.exceptions.TooManyRedirects:

package/tools/cli/commands/review.js

@@ -7,7 +7,7 @@ const review = require('../lib/review');
 const reviewRules = require('../lib/review-rules');
 
 const ID = /^[a-z0-9][a-z0-9.-]{0,80}$/;
-const ACTIONS = ['scope', 'anchor', 'gate', 'compare', 'rules'];
+const ACTIONS = ['scope', 'anchor', 'gate', 'continue', 'compare', 'rules'];
 
 function fail(message) {
   throw new Error(message);
@@ -28,6 +28,48 @@ function writeJson(file, value) {
   fs.writeFileSync(file, `${JSON.stringify(value, null, 2)}\n`);
 }
 
+/** A reader of the file sees the previous version or the new one, never half of it. */
+function writeAtomically(file, text) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const temporary = `${file}.${process.pid}.tmp`;
+  fs.writeFileSync(temporary, text, { flag: 'wx' });
+  try {
+    fs.renameSync(temporary, file);
+  } catch (error) {
+    fs.rmSync(temporary, { force: true });
+    throw error;
+  }
+}
+
+const inside = (dir, file) => {
+  const relative = path.relative(dir, file);
+  return relative !== '' && !relative.startsWith('..') && !path.isAbsolute(relative);
+};
+
+/**
+ * Where `--emit-check` writes: a JSON file, resolved against the project, never the evidence
+ * itself. A working-tree scope selects untracked files, so its check stays in the review
+ * folder or out of the project: anywhere else it would enter the change it reports on.
+ */
+function checkTarget(projectDir, value, paths, scope) {
+  const file = path.resolve(projectDir, value);
+  if (!/\.json$/i.test(file)) fail('--emit-check writes a .json file');
+  const evidence = Object.entries(paths).filter(([key]) => key !== 'root');
+  if (evidence.some(([, taken]) => path.relative(taken, file) === ''))
+    fail('--emit-check must not overwrite the review evidence');
+  if (
+    scope.identity.workspace &&
+    inside(projectDir, file) &&
+    !inside(path.dirname(paths.root), file)
+  )
+    fail(
+      `--emit-check: a working-tree review writes its check in ${path.relative(projectDir, path.dirname(paths.root)) || '.'} or outside the project, where it cannot enter the reviewed change`
+    );
+  if (fs.existsSync(file) && !fs.statSync(file).isFile())
+    fail(`--emit-check: ${file} is not a file`);
+  return file;
+}
+
 function print(json, payload, lines) {
   if (json) console.log(JSON.stringify({ schemaVersion: 1, ...payload }, null, 2));
   else for (const line of lines) console.log(line);
@@ -46,6 +88,75 @@ function loadReview(projectDir, dir, id) {
   return { paths, scope };
 }
 
+/** One line of observed usage: what the host reported, nothing estimated. */
+function describeUsage(stop, usage) {
+  const parts = [
+    `stopped: ${stop || 'unstated'}`,
+    `${usage.passes ?? '?'}/${usage.plannedPasses ?? '?'} pass(es)`,
+    `${usage.unitsAttempted}/${usage.units} unit(s) attempted in ${usage.attempts} attempt(s), ${usage.failedAttempts} failed`,
+  ];
+  if (usage.tokens !== undefined) parts.push(`${usage.tokens} tokens`);
+  if (usage.durationMs !== undefined) parts.push(`${Math.round(usage.durationMs / 1000)} s`);
+  return parts.join(', ');
+}
+
+/**
+ * `review continue <id>`: what an interrupted review still owes, against the same sealed
+ * scope. Refused when the code or the rules moved — a new scope and a compare answer that.
+ */
+function continueAction(projectDir, dir, id, paths, scope, json) {
+  const drift = review.scopeDrift(projectDir, scope, {
+    ruleset: reviewRules.loadRuleset(projectDir),
+    outputDir: dir,
+  });
+  if (drift.length) {
+    const next = [
+      `bmad-plus review scope <new-id> (same options as ${id})`,
+      `bmad-plus review compare <new-id> --since ${id}`,
+    ];
+    print(json, { action: 'continue', id, status: 'moved', drift, next }, [
+      `${id} cannot continue: the sealed scope no longer describes the code.`,
+      ...drift.map((reason) => `  - ${reason}`),
+      `  Seal a new scope and compare: ${next.join(', then ')}.`,
+    ]);
+    process.exitCode = 3;
+    return undefined;
+  }
+  const coverage = readJson(paths.coverage, 'coverage.json');
+  const coverageErrors = coverage ? review.validateCoverage(coverage, scope) : [];
+  if (coverageErrors.length) {
+    print(json, { action: 'continue', id, status: 'error', errors: coverageErrors }, [
+      `${id}: coverage.json must be valid before the review continues`,
+      ...coverageErrors.map((e) => `  error   ${e}`),
+    ]);
+    process.exitCode = 3;
+    return undefined;
+  }
+  const findings = readJson(paths.findings, 'findings.json');
+  const findingErrors = findings ? review.validateFindings(findings, scope) : [];
+  const anchored =
+    findings && !findingErrors.length ? review.anchorFindings(projectDir, scope, findings) : null;
+  const packet = review.remainingWork({ scope, coverage, anchored, findingErrors });
+  writeJson(paths.continue, packet);
+  const c = packet.counts;
+  const nothing = !c.files && !c.requote && !c.findingErrors && !c.passes;
+  print(json, { action: 'continue', id, status: 'ready', file: paths.continue, counts: c }, [
+    `${paths.continue} — same scope ${scope.sha256.slice(0, 12)}`,
+    `${c.files} file(s) in ${c.units} unit(s) to review, ${c.requote} finding(s) to requote, ${c.passes} pass(es) left`,
+    ...packet.units.map((unit) => `  ${unit.id.padEnd(5)} ${unit.paths.join(', ')}`),
+    ...packet.abandoned.map(
+      (file) => `  abandoned ${file.path} (${file.unit}): three failed attempts; it stays failed`
+    ),
+    ...packet.requote.map((f) => `  requote ${f.id} ${f.path} (${f.status})`),
+    ...packet.findingErrors.map((e) => `  fix     ${e}`),
+    nothing
+      ? `Nothing remains: once coverage.json records the run as completed, run bmad-plus review gate ${id}.`
+      : 'Add to the same coverage.json and findings.json; set run.stop when this session ends.',
+  ]);
+  process.exitCode = 0;
+  return undefined;
+}
+
 /** `review rules [path]`: the effective rule set, or the rules one path would get. */
 function rulesAction(projectDir, target, json) {
   const ruleset = reviewRules.loadRuleset(projectDir);
@@ -60,9 +171,10 @@ function rulesAction(projectDir, target, json) {
       sha256: ruleset.sha256,
       projectFile: ruleset.projectFile,
       disabled: ruleset.disabled,
-      rules: listed.map(({ id, title, layer, globs, source }) => ({
+      rules: listed.map(({ id, title, group, layer, globs, source }) => ({
         id,
         title,
+        group,
         layer,
         globs,
         source,
@@ -72,7 +184,8 @@ function rulesAction(projectDir, target, json) {
       `rule set ${ruleset.sha256.slice(0, 12)}${ruleset.projectFile ? ` (built-in + ${ruleset.projectFile})` : ' (built-in)'}`,
       ...(file ? [`${file} gets ${listed.length} rule(s):`] : []),
       ...listed.map(
-        (rule) => `  ${rule.id.padEnd(24)} ${rule.layer.padEnd(8)} ${rule.globs.join(' ')}`
+        (rule) =>
+          `  ${rule.id.padEnd(24)} ${rule.group.padEnd(12)} ${rule.layer.padEnd(8)} ${rule.globs.join(' ')}`
       ),
       ...ruleset.disabled.map((id) => `  ${id.padEnd(24)} disabled by the project`),
     ]
@@ -81,7 +194,7 @@ function rulesAction(projectDir, target, json) {
 
 module.exports = {
   command: 'review <action> [id]',
-  description: 'Code review evidence: scope, anchor, gate, compare, rules',
+  description: 'Code review evidence: scope, anchor, gate, continue, compare, rules',
   options: [
     ['-d, --directory <path>', 'Project directory'],
     ['--dir <path>', 'Review folder inside the project', review.DEFAULT_DIR],
@@ -95,6 +208,7 @@ module.exports = {
       `Review depth: ${Object.keys(review.EFFORTS).join(', ')} (default medium)`,
     ],
     ['--since <id>', 'compare: the earlier review to compare against'],
+    ['--emit-check <file>', 'gate: also write the verdict as a JSON check result for CI'],
     ['--json', 'Machine-readable output'],
   ],
   action: (action, id, options = {}) => {
@@ -116,6 +230,7 @@ module.exports = {
           include: options.include,
           exclude: options.exclude,
           effort: options.effort,
+          outputDir: dir,
           ruleset,
         });
         const paths = review.layout(projectDir, dir, id);
@@ -201,21 +316,33 @@ module.exports = {
         if (findings && !review.validateFindings(findings, scope).length)
           anchored = review.anchorFindings(projectDir, scope, findings);
         const verdict = review.reviewGate({ scope, findings, coverage, anchored });
+        let check = null;
+        if (options.emitCheck) {
+          check = checkTarget(projectDir, options.emitCheck, paths, scope);
+          writeAtomically(
+            check,
+            `${JSON.stringify(review.checkResult({ id, scope, verdict, anchored }), null, 2)}\n`
+          );
+        }
         print(
           json,
-          { action, id, ...verdict },
+          { action, id, ...verdict, check },
           [
             `${id}: ${verdict.status} — coverage ${verdict.coverage.completed}/${verdict.coverage.selected} completed (${verdict.coverage.waived} waived), ${verdict.findings.open} open finding(s), ${verdict.findings.refuted} refuted`,
             ...verdict.reasons.map((reason) => `  - ${reason}`),
+            verdict.usage ? `  run: ${describeUsage(verdict.stop, verdict.usage)}` : '',
+            check ? `  check: ${check}` : '',
             verdict.status === 'clean'
               ? '  clean: no open finding within a fully covered scope. It does not prove the code correct.'
               : '',
           ].filter(Boolean)
         );
-        process.exitCode = { clean: 0, findings: 1, incomplete: 2 }[verdict.status];
+        process.exitCode = review.GATE_EXIT[verdict.status];
         return undefined;
       }
 
+      if (action === 'continue') return continueAction(projectDir, dir, id, paths, scope, json);
+
       // compare: this review against an earlier one.
       const sinceId = requireId(options.since, '--since <earlier review id>');
       if (sinceId === id) fail('--since must name a different review');

package/tools/cli/lib/packs.js

@@ -191,7 +191,7 @@ const DERIVED = {
   "product": {
     "code": "bmad-plus",
     "displayName": "BMAD+",
-    "version": "0.20.0",
+    "version": "0.21.0",
     "derivedFrom": "BMAD-METHOD v6.6.0"
   },
   "packOrder": [

package/tools/cli/lib/review-rules.js

@@ -16,7 +16,7 @@ const SCHEMA = 'bmad-plus/review-rules/1';
 const BUILTIN_DIR = path.join(__dirname, '..', 'review-rules');
 const PROJECT_FILE = path.join('_bmad', 'review-rules.yaml');
 const RULE_ID = /^[a-z0-9][a-z0-9-]{0,60}$/;
-const RULE_KEYS = ['id', 'title', 'globs', 'doc'];
+const RULE_KEYS = ['id', 'title', 'group', 'globs', 'doc'];
 const MAX_DOC_BYTES = 64 * 1024;
 const MAX_INDEX_BYTES = 256 * 1024;
 
@@ -60,11 +60,13 @@ function parseLayer(root, indexName, layer) {
     if (!rule || typeof rule !== 'object') throw new Error(`${at}: must be a mapping`);
     const unknown = Object.keys(rule).filter((key) => !RULE_KEYS.includes(key));
     if (unknown.length) throw new Error(`${at}: unknown key(s) ${unknown.join(', ')}`);
-    if (!RULE_ID.test(String(rule.id))) throw new Error(`${at}: invalid id`);
+    if (typeof rule.id !== 'string' || !RULE_ID.test(rule.id)) throw new Error(`${at}: invalid id`);
     if (seen.has(rule.id)) throw new Error(`${at}: duplicate id`);
     seen.add(rule.id);
     if (typeof rule.title !== 'string' || !rule.title.trim())
       throw new Error(`${at}: title is required`);
+    if (rule.group !== undefined && !(typeof rule.group === 'string' && RULE_ID.test(rule.group)))
+      throw new Error(`${at}: invalid group`);
     if (
       !Array.isArray(rule.globs) ||
       !rule.globs.length ||
@@ -78,6 +80,8 @@ function parseLayer(root, indexName, layer) {
     return {
       id: rule.id,
       title: rule.title.trim(),
+      // A rule family reviewers can split by; a rule without one is a family of its own.
+      group: rule.group === undefined ? rule.id : rule.group,
       globs: [...rule.globs],
       layer,
       source: rule.doc,
@@ -107,7 +111,13 @@ function loadRuleset(projectDir, { builtinDir = BUILTIN_DIR } = {}) {
     for (const id of disabled) ordered.delete(id);
   }
   const list = [...ordered.values()];
-  const fingerprint = list.map((rule) => [rule.id, rule.layer, rule.globs, sha256(rule.text)]);
+  const fingerprint = list.map((rule) => [
+    rule.id,
+    rule.group,
+    rule.layer,
+    rule.globs,
+    sha256(rule.text),
+  ]);
   return {
     rules: list,
     disabled,
@@ -121,6 +131,16 @@ function rulesFor(ruleset, file) {
   return ruleset.rules.filter((rule) => matchesAny(file, rule.globs)).map((rule) => rule.id);
 }
 
+/** The rule families of a set of rule ids, each with its rules, in rule order. */
+function groupsOf(ruleset, ids) {
+  const groups = new Map();
+  for (const rule of ruleset.rules) {
+    if (!ids.includes(rule.id)) continue;
+    groups.set(rule.group, [...(groups.get(rule.group) || []), rule.id]);
+  }
+  return [...groups].map(([id, rules]) => ({ id, rules }));
+}
+
 /**
  * The reviewer's checklist for a scope: each applicable rule once, with the files it
  * covers. Rules that match nothing in the scope are left out.
@@ -136,6 +156,8 @@ function checklist(ruleset, byPath, { title = 'Review checklist' } = {}) {
       [
         `## ${rule.title} \`${rule.id}\`${rule.layer === 'project' ? ' (project rule)' : ''}`,
         '',
+        `Group: \`${rule.group}\``,
+        '',
         `Applies to: ${files
           .get(rule.id)
           .map((file) => `\`${file}\``)
@@ -153,4 +175,12 @@ function checklist(ruleset, byPath, { title = 'Review checklist' } = {}) {
   ].join('\n');
 }
 
-module.exports = { SCHEMA, BUILTIN_DIR, PROJECT_FILE, loadRuleset, rulesFor, checklist };
+module.exports = {
+  SCHEMA,
+  BUILTIN_DIR,
+  PROJECT_FILE,
+  loadRuleset,
+  rulesFor,
+  groupsOf,
+  checklist,
+};