bmad-plus 0.20.0 → 0.22.0

package/src/bmad-plus/packs/pack-dev-studio/categories/implementation/code-review.md

@@ -29,7 +29,9 @@ arbitrary branch. Read the intended behavior and applicable project constraints.
    beside the scope: it holds, once each, the review rules that apply to the
    selected paths — built-in rules by language and file kind, plus the project's
    own from `_bmad/review-rules.yaml`, which can add, replace or disable rules.
-   `bmad-plus review rules <path>` shows which rules a file gets. Inventory
+   `bmad-plus review rules <path>` shows which rules a file gets. Each unit
+   lists its rule groups (`code`, `data`, `delivery` or the project's own):
+   parallel reviewers may split a unit by group. Inventory
    related callers, tests and requirements. Preserve existing edits and record
    unavailable context. A supplied diff may omit the surrounding behavior needed
    to evaluate it.
@@ -73,8 +75,20 @@ arbitrary branch. Read the intended behavior and applicable project constraints.
    when a selected file is unaccounted for or a finding is not anchored, `findings`
    or `clean` otherwise. `clean` covers the reviewed scope only. A finding that
    applies a checklist rule names it in `rule`; the CLI refuses a rule that does
-   not apply to that path. The anchored record replaces credential-like values
-   quoted in a finding with `[REDACTED]` and counts them.
+   not apply to that path. A finding that breaks a compliance control lists it in
+   `controls`, chosen among the controls `scope.json` records for that file; the
+   CLI refuses any other and carries them into the check result. The anchored record replaces credential-like values
+   quoted in a finding with `[REDACTED]` and counts them. Record the session in
+   `coverage.json` under `run`: `stop` (`completed`, `budget`, `time-limit`,
+   `failure-streak` or `interrupted`, with a `detail` unless completed), the
+   `passes` actually run, every unit attempt in order (`unit`, the rule `group`
+   when reviewers split by group, `completed` or `failed` with a reason), and
+   tokens or duration only when the host reports them — never estimate them.
+   After three failed attempts in a row on the same unit or group, stop
+   retrying it: mark its files failed. A stopped review is never clean. In CI,
+   `bmad-plus review gate <id> --emit-check <file.json>` also writes the verdict
+   as a check result (`bmad-plus/review-check/1`, with a GitHub check-runs
+   payload); the exit code stays the verdict.
 9. On a second review of the same work, compare it with the earlier one:
    `bmad-plus review compare <id> --since <earlier-id>` writes `compare.json`
    with each finding new, persisting, refuted, resolved or not reviewed. An
@@ -95,7 +109,14 @@ or an untested requirement.
 
 ## Continue
 
-Compare the current diff and input hashes with the reviewed snapshot. Preserve
-prior findings and check their resolution against actual changes. Re-review
+With a sealed scope, run `bmad-plus review continue <id>` first. When the code,
+its head ref or the review rules moved, it refuses: seal a new scope and compare
+it with this one (step 9) instead of continuing. Otherwise `continue.json` lists
+the units, files and rule groups still owed, the files abandoned after three
+failures (they stay failed), the findings to requote and the passes left; add to
+the same `coverage.json` and `findings.json` and record the new `run.stop`.
+
+Without a sealed scope, compare the current diff and input hashes with the
+reviewed snapshot. Preserve prior findings and check their resolution against actual changes. Re-review
 affected behavior and invalidate conclusions that relied on changed inputs;
 do not rerun unchanged checks merely to refresh the report date.

package/src/bmad-plus/packs/pack-seo/SKILL.md

@@ -100,7 +100,9 @@ Run Scout and Judge **simultaneously** on each discovered page:
 **Optional**: Run `scripts/seo_apis.py --all <url>` for live PageSpeed + CrUX data.
 
 Use `scripts/seo_parse.py <file> --url <url> --json` on fetched HTML.
-Use `scripts/seo_screenshot.py <url> --viewport mobile` for visual audit.
+Use `scripts/seo_screenshot.py <url> --viewport mobile` for visual audit. The browser only
+reaches the audited host: third-party resources are blocked and listed in `blocked_requests`,
+so judge a missing CDN image or font as an effect of the capture, not of the site.
 
 ### Phase 3 — AI Readiness & GEO
 **Agent**: Judge (GEO Analyst role)

package/src/bmad-plus/packs/pack-seo/ref/cwv-thresholds.md

@@ -73,8 +73,8 @@
 
 ## API Tools
 ```bash
-# PageSpeed Insights API
-curl "https://www.googleapis.com/pagespeedonline/v5/runPagespeed?url=URL&key=API_KEY"
+# PageSpeed Insights API: the key goes in a header, never in the URL (or use scripts/seo_apis.py)
+curl -H "x-goog-api-key: $GOOGLE_API_KEY" "https://www.googleapis.com/pagespeedonline/v5/runPagespeed?url=URL"
 
 # Lighthouse CLI
 npx lighthouse URL --output json --output-path report.json

package/src/bmad-plus/packs/pack-seo/requirements.txt

@@ -14,4 +14,4 @@ lxml==6.1.1
 
 # Screenshot capture (optional — only for seo_screenshot.py)
 # Uncomment and run: playwright install chromium
-# playwright>=1.40.0
+# playwright>=1.48.0  # route_web_socket guards WebSockets

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

@@ -10,6 +10,9 @@ Connects to:
 Requires: GOOGLE_API_KEY environment variable (free, no OAuth).
 Get one at: https://console.cloud.google.com/apis/credentials
 
+The key travels in the x-goog-api-key header only: never in a request URL, where proxies
+and server logs keep it, and never in a result, a log line or an error message.
+
 Author: Laurent Rochetta
 License: MIT
 """
@@ -17,6 +20,7 @@ License: MIT
 import argparse
 import json
 import os
+import re
 import sys
 from typing import Optional
 
@@ -27,12 +31,56 @@ except ImportError:
     sys.exit(1)
 
 
-API_KEY = os.environ.get("GOOGLE_API_KEY", "")
+API_KEY = os.environ.get("GOOGLE_API_KEY", "").strip()
+KEY_HEADER = "x-goog-api-key"
+# Printable ASCII without spaces: anything else cannot be a header value, and the error
+# requests would raise for it quotes the value.
+KEY_SHAPE = re.compile(r"[\x21-\x7e]+")
 
 PSI_ENDPOINT = "https://www.googleapis.com/pagespeedonline/v5/runPagespeed"
 CRUX_ENDPOINT = "https://chromeuxreport.googleapis.com/v1/records:queryRecord"
 RICH_RESULTS_ENDPOINT = "https://searchconsole.googleapis.com/v1/urlTestingTools/mobileFriendlyTest:run"
 
+SESSION = requests.Session()
+
+
+def _key_problem() -> Optional[str]:
+    """Why no request can be sent, without ever quoting the key; None when it can."""
+    if not API_KEY:
+        return "GOOGLE_API_KEY not set. Get one at https://console.cloud.google.com/apis/credentials"
+    if not KEY_SHAPE.fullmatch(API_KEY):
+        return "GOOGLE_API_KEY is malformed: an API key is printable ASCII without spaces"
+    return None
+
+
+def _redact(text: str) -> str:
+    """Remove the key from text headed for a result, a log or the terminal."""
+    return text.replace(API_KEY, "[GOOGLE_API_KEY]") if API_KEY else text
+
+
+def _failure(api: str, error: Exception) -> dict:
+    return {"error": _redact(f"{api} request failed: {error}")}
+
+
+def _send(method: str, endpoint: str, timeout: int, **body):
+    """
+    Send one request to a Google API with the key in its header.
+
+    Redirects are refused, not followed: requests would carry this header to whatever host
+    a redirect names (it strips only Authorization), and no Google API answers with one.
+    """
+    response = SESSION.request(
+        method,
+        endpoint,
+        headers={KEY_HEADER: API_KEY},
+        timeout=timeout,
+        allow_redirects=False,
+        **body,
+    )
+    if 300 <= response.status_code < 400:
+        raise requests.HTTPError(f"unexpected redirect ({response.status_code}), not followed", response=response)
+    return response
+
 
 # ── PageSpeed Insights ─────────────────────────────────────────────
 
@@ -48,25 +96,25 @@ def run_pagespeed(url: str, strategy: str = "mobile", categories: Optional[list]
     Returns:
         Structured result with scores, audits, and opportunities
     """
-    if not API_KEY:
-        return {"error": "GOOGLE_API_KEY not set. Get one at https://console.cloud.google.com/apis/credentials"}
+    problem = _key_problem()
+    if problem:
+        return {"error": problem}
 
     if categories is None:
         categories = ["PERFORMANCE", "ACCESSIBILITY", "BEST_PRACTICES", "SEO"]
 
     params = {
         "url": url,
-        "key": API_KEY,
         "strategy": strategy,
         "category": categories,
     }
 
     try:
-        response = requests.get(PSI_ENDPOINT, params=params, timeout=120)
+        response = _send("GET", PSI_ENDPOINT, 120, params=params)
         response.raise_for_status()
         data = response.json()
-    except requests.RequestException as e:
-        return {"error": f"PSI API request failed: {e}"}
+    except (requests.RequestException, ValueError) as e:
+        return _failure("PSI API", e)
 
     # Extract scores
     result = {
@@ -161,8 +209,9 @@ def run_crux(url: str, form_factor: str = "PHONE") -> dict:
     Returns:
         Field CWV data at 75th percentile
     """
-    if not API_KEY:
-        return {"error": "GOOGLE_API_KEY not set"}
+    problem = _key_problem()
+    if problem:
+        return {"error": problem}
 
     # Try URL-level first, fall back to origin
     from urllib.parse import urlparse
@@ -175,28 +224,20 @@ def run_crux(url: str, form_factor: str = "PHONE") -> dict:
     }
 
     try:
-        response = requests.post(
-            f"{CRUX_ENDPOINT}?key={API_KEY}",
-            json=payload,
-            timeout=30,
-        )
+        response = _send("POST", CRUX_ENDPOINT, 30, json=payload)
 
         if response.status_code == 404:
             # No URL-level data, try origin
             payload = {"origin": origin, "formFactor": form_factor}
-            response = requests.post(
-                f"{CRUX_ENDPOINT}?key={API_KEY}",
-                json=payload,
-                timeout=30,
-            )
+            response = _send("POST", CRUX_ENDPOINT, 30, json=payload)
 
         if response.status_code == 404:
             return {"error": f"No CrUX data available for {url} (not enough traffic)"}
 
         response.raise_for_status()
         data = response.json()
-    except requests.RequestException as e:
-        return {"error": f"CrUX API request failed: {e}"}
+    except (requests.RequestException, ValueError) as e:
+        return _failure("CrUX API", e)
 
     result = {
         "url": url,
@@ -264,21 +305,18 @@ def run_rich_results_test(url: str) -> dict:
     Returns:
         Mobile-friendly status and detected structured data
     """
-    if not API_KEY:
-        return {"error": "GOOGLE_API_KEY not set"}
+    problem = _key_problem()
+    if problem:
+        return {"error": problem}
 
     payload = {"url": url}
 
     try:
-        response = requests.post(
-            f"{RICH_RESULTS_ENDPOINT}?key={API_KEY}",
-            json=payload,
-            timeout=60,
-        )
+        response = _send("POST", RICH_RESULTS_ENDPOINT, 60, json=payload)
         response.raise_for_status()
         data = response.json()
-    except requests.RequestException as e:
-        return {"error": f"URL Testing API request failed: {e}"}
+    except (requests.RequestException, ValueError) as e:
+        return _failure("URL Testing API", e)
 
     result = {
         "url": url,
@@ -383,6 +421,10 @@ def main():
         print("   Enable: PageSpeed Insights API + Chrome UX Report API", file=sys.stderr)
         print("   Set: export GOOGLE_API_KEY=your_key", file=sys.stderr)
         sys.exit(1)
+    problem = _key_problem()
+    if problem:
+        print(f"⚠️  {problem}", file=sys.stderr)
+        sys.exit(1)
 
     if args.all:
         result = run_all(args.url)

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

@@ -32,13 +32,14 @@ except ImportError:
     )
     sys.exit(1)
 
-# Reuse the hardened SSRF guard from seo_fetch (same package/directory).
+# Reuse the hardened SSRF guard and pinned transport from seo_fetch
+# (same package/directory).
 sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
 try:
-    from seo_fetch import is_safe_url
+    from seo_fetch import ALLOWED_SCHEMES, UnsafeURLError, create_session
 except ImportError:
     print(
-        "Error: seo_fetch.is_safe_url is required (SSRF protection). "
+        "Error: seo_fetch.create_session is required (SSRF protection). "
         "Ensure seo_fetch.py is present alongside seo_crawl.py.",
         file=sys.stderr,
     )
@@ -65,6 +66,8 @@ USER_AGENT = (
     "(KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36 BMADSEOEngine/2.0"
 )
 
+MAX_REDIRECTS = 5
+
 
 class SEOCrawler:
     """Recursive mini-crawler for SEO site structure analysis."""
@@ -82,6 +85,7 @@ class SEOCrawler:
         self.sitemap_urls: list = []
         self.robots_txt: Optional[str] = None
         self.errors: list = []
+        self.session = create_session()
 
     def normalize_url(self, url: str) -> str:
         """Normalize URL for deduplication."""
@@ -96,42 +100,50 @@ class SEOCrawler:
     def _safe_get(self, url: str, error_prefix: str = "Blocked"):
         """GET a URL, following redirects manually with per-hop SSRF revalidation.
 
-        Redirects are followed with allow_redirects=False so is_safe_url() runs on
-        EVERY hop: a public URL that 302s to an internal/metadata endpoint
-        (redirect-based SSRF) is refused. Returns the final requests.Response, or
-        None (with an entry appended to self.errors) when a hop is unsafe or too
-        many redirects occur. Used by fetch(), fetch_robots_txt() and
-        parse_sitemap() so every network path shares the same guard.
+        Every request goes through the pinned session from seo_fetch, which
+        validates the target and connects to the address it validated (no DNS
+        rebinding between check and connect). Redirects are followed with
+        allow_redirects=False so each hop is validated the same way: a public URL
+        that 302s to an internal/metadata endpoint (redirect-based SSRF) is
+        refused. Returns the final requests.Response, or None (with an entry
+        appended to self.errors) when a hop is unsafe or too many redirects
+        occur. Used by fetch(), fetch_robots_txt() and parse_sitemap() so every
+        network path shares the same guard.
         """
-        if not is_safe_url(url):
-            self.errors.append(
-                {"url": url, "error": f"{error_prefix}: private/internal URL (SSRF protection)"}
-            )
-            return None
         current_url = url
         hops = 0
         while True:
-            response = requests.get(
-                current_url,
-                headers={"User-Agent": USER_AGENT},
-                timeout=self.timeout,
-                allow_redirects=False,
-            )
+            try:
+                response = self.session.get(
+                    current_url,
+                    headers={"User-Agent": USER_AGENT},
+                    timeout=self.timeout,
+                    allow_redirects=False,
+                )
+            except UnsafeURLError as e:
+                prefix = error_prefix if current_url == url else f"{error_prefix} redirect"
+                self.errors.append(
+                    {"url": current_url, "error": f"{prefix}: {e} (SSRF protection)"}
+                )
+                return None
             if not response.is_redirect:
                 return response
             location = response.headers.get("Location")
             if not location:
                 return response
+            response.close()
             next_url = urljoin(current_url, location)
-            if urlparse(next_url).scheme not in ("http", "https") or not is_safe_url(next_url):
+            if urlparse(next_url).scheme not in ALLOWED_SCHEMES:
                 self.errors.append(
                     {"url": next_url,
-                     "error": f"{error_prefix} redirect: non-HTTP(S) or private/internal URL (SSRF protection)"}
+                     "error": f"{error_prefix} redirect: non-HTTP(S) URL (SSRF protection)"}
                 )
                 return None
             hops += 1
-            if hops > 5:
-                self.errors.append({"url": current_url, "error": "Too many redirects (max 5)"})
+            if hops > MAX_REDIRECTS:
+                self.errors.append(
+                    {"url": current_url, "error": f"Too many redirects (max {MAX_REDIRECTS})"}
+                )
                 return None
             current_url = next_url