From 432a3c8ebfb50d465b09b147256c74fe10ab0b04 Mon Sep 17 00:00:00 2001
From: Logan Kleier <lkleier@amazon.com>
Date: Thu, 1 Oct 2026 13:08:47 -0700
Subject: [PATCH 01/10] fix(aws-startup-advisor): reject migration reports that
 skip the decision core

REPORT_OK treated section IDs as completeness, so a thin HTML report could pass without the verdict, flip conditions, or architecture section. The shared validator now checks those artifact-backed fields for GCP and Azure, and the Heroku validator checks the flip list and what-if columns.

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 .../fixtures/migration-report-reference.html  |   6 +
 ...validate_migration_report_decision_core.py |  93 ++++++++
 .../scripts/validate-migration-report.py      | 210 ++++++++++++++++++
 .../generate/generate-artifacts-report.md     |  16 +-
 .../references/phases/generate/generate.md    |   2 +-
 .../generate/generate-artifacts-report.md     |  18 +-
 .../references/phases/generate/generate.md    |   2 +-
 .../shared/validate-migration-report.md       |  12 +-
 .../phases/generate/generate-report.md        |  11 +-
 .../test_validate_heroku_migration_report.py  |  57 +++++
 .../validate-heroku-migration-report.py       |  42 ++++
 11 files changed, 455 insertions(+), 14 deletions(-)
 create mode 100644 plugins/aws-startup-advisor/scripts/test_validate_migration_report_decision_core.py

diff --git a/plugins/aws-startup-advisor/fixtures/migration-report-reference.html b/plugins/aws-startup-advisor/fixtures/migration-report-reference.html
index 6f6b0a3b3..aa1027f49 100644
--- a/plugins/aws-startup-advisor/fixtures/migration-report-reference.html
+++ b/plugins/aws-startup-advisor/fixtures/migration-report-reference.html
@@ -170,6 +170,12 @@ <h3>Stay entirely if</h3>
         <li>Cost is the only metric and a dual-run period must be avoided</li>
       </ul>
 
+      <h3>What would flip this</h3>
+      <ul class="compact">
+        <li>Single-AZ acceptable: AWS estimate drops further, strengthens go</li>
+        <li>BigQuery must cut over in the same window: defer for specialist evidence</li>
+      </ul>
+
       <h3>Key decisions ahead</h3>
       <ol class="compact">
         <li>Target region and deployment model (Fargate vs EKS)</li>
diff --git a/plugins/aws-startup-advisor/scripts/test_validate_migration_report_decision_core.py b/plugins/aws-startup-advisor/scripts/test_validate_migration_report_decision_core.py
new file mode 100644
index 000000000..da8f879e1
--- /dev/null
+++ b/plugins/aws-startup-advisor/scripts/test_validate_migration_report_decision_core.py
@@ -0,0 +1,93 @@
+"""Decision-core content checks for the shared migration-report validator.
+
+A report used to pass when the section IDs existed, even if it never rendered
+the verdict headline, flip conditions, specialist callout, or architecture
+section. These tests lock the artifact-gated checks that reject that report.
+"""
+
+from __future__ import annotations
+
+import importlib.util
+import json
+from pathlib import Path
+
+PLUGIN = Path(__file__).resolve().parent.parent
+SCRIPT = PLUGIN / "scripts" / "validate-migration-report.py"
+FIXTURES = PLUGIN / "fixtures"
+
+
+def _load():
+    spec = importlib.util.spec_from_file_location("validate_migration_report", SCRIPT)
+    module = importlib.util.module_from_spec(spec)
+    assert spec.loader is not None
+    spec.loader.exec_module(module)
+    return module
+
+
+def _reference_html() -> str:
+    return (FIXTURES / "migration-report-reference.html").read_text(encoding="utf-8")
+
+
+def _reference_estimate() -> dict:
+    return json.loads(
+        (FIXTURES / "estimation-infra-reference.json").read_text(encoding="utf-8")
+    )
+
+
+def test_reference_fixture_still_passes() -> None:
+    validator = _load()
+    ai = json.loads((FIXTURES / "estimation-ai-reference.json").read_text(encoding="utf-8"))
+    errors = validator.validate_report(
+        _reference_html(),
+        _reference_estimate(),
+        ai,
+    )
+    assert errors == [], errors
+
+
+def test_missing_would_flip_list_fails() -> None:
+    validator = _load()
+    html = _reference_html().replace("<h3>What would flip this</h3>", "<h3>Notes</h3>")
+    errors = validator.validate_report(html, _reference_estimate(), None)
+    assert any("would_flip" in err for err in errors), errors
+
+
+def test_deferred_service_without_callout_fails() -> None:
+    validator = _load()
+    html = _reference_html().replace("specialist engagement", "analytics follow-up")
+    html = html.replace("Specialist engagement", "Analytics follow-up")
+    design = {
+        "clusters": [
+            {
+                "resources": [
+                    {"aws_service": "Deferred — specialist engagement"},
+                ]
+            }
+        ]
+    }
+    errors = validator.validate_report(html, _reference_estimate(), None, design)
+    assert any("specialist" in err.lower() for err in errors), errors
+
+
+def test_clusters_without_architecture_section_fail() -> None:
+    validator = _load()
+    html = _reference_html().replace('id="exec-architecture"', 'id="not-architecture"')
+    design = {"clusters": [{"resources": [{"aws_service": "Amazon S3"}]}]}
+    errors = validator.validate_report(html, _reference_estimate(), None, design)
+    assert any("exec-architecture" in err for err in errors), errors
+
+
+def test_decision_fixture_still_passes() -> None:
+    validator = _load()
+    root = FIXTURES / "gcp-decision-gate" / "after-decide-complete"
+    html = (root / "decision-report.html").read_text(encoding="utf-8")
+    estimate = json.loads((root / "estimation-infra.json").read_text(encoding="utf-8"))
+    errors = validator.validate_report(
+        html,
+        estimate,
+        None,
+        None,
+        migration_dir=root,
+        mode="decision",
+    )
+    assert errors == [], errors
diff --git a/plugins/aws-startup-advisor/scripts/validate-migration-report.py b/plugins/aws-startup-advisor/scripts/validate-migration-report.py
index 1a77146da..d64f803d9 100644
--- a/plugins/aws-startup-advisor/scripts/validate-migration-report.py
+++ b/plugins/aws-startup-advisor/scripts/validate-migration-report.py
@@ -1246,6 +1246,14 @@ def _validate_appendix_config(html: str) -> list[str]:
         errors.append(
             'appendix-config table must include a "Question" or "Assumption" column (from preferences.prompt)'
         )
+    if "choice" not in hdr_text:
+        errors.append(
+            'appendix-config table must include a "Your choice" column (the value the reader confirmed)'
+        )
+    if "source" not in hdr_text:
+        errors.append(
+            'appendix-config table must include a "Source" column (user answer, extracted, or default)'
+        )
     if "consequence" not in hdr_text:
         errors.append(
             "appendix-config table must include a Design consequence column (from preferences.design_consequence)"
@@ -1646,6 +1654,194 @@ def _validate_fixture_bleed(html: str, migration_dir: Path | None) -> list[str]:
     return errors
 
 
+def _plain_text(fragment: str) -> str:
+    """Decoded visible text, with dashes folded so artifact prose can be matched."""
+    text = unescape(re.sub(r"<[^>]+>", " ", fragment))
+    text = text.replace("\u2014", "-").replace("\u2013", "-")
+    return re.sub(r"\s+", " ", text).strip().lower()
+
+
+def _word_shingles(text: str, size: int = 4) -> set[str]:
+    """Word phrases used to recognize a rendered condition without requiring a verbatim copy."""
+    words = re.findall(r"[a-z0-9]+", text.lower())
+    if not words:
+        return set()
+    if len(words) <= size:
+        return {" ".join(words)}
+    return {" ".join(words[i : i + size]) for i in range(len(words) - size + 1)}
+
+
+def _iter_aws_services(node: object):
+    if isinstance(node, dict):
+        service = node.get("aws_service")
+        if isinstance(service, str):
+            yield service
+        for value in node.values():
+            yield from _iter_aws_services(value)
+    elif isinstance(node, list):
+        for item in node:
+            yield from _iter_aws_services(item)
+
+
+def _design_has_clusters(aws_design: dict | None) -> bool:
+    if not aws_design:
+        return False
+    clusters = aws_design.get("clusters")
+    return isinstance(clusters, list) and len(clusters) > 0
+
+
+def _design_has_deferred_service(aws_design: dict | None) -> bool:
+    if not aws_design:
+        return False
+    return any(
+        service.strip().lower().startswith("deferred")
+        for service in _iter_aws_services(aws_design)
+    )
+
+
+def _what_if_column_errors(section: str) -> list[str]:
+    """Workshop compare tables must carry the decision-core column set."""
+    header = re.search(r"<thead\b.*?</thead>", section, re.DOTALL | re.IGNORECASE)
+    if not header:
+        return [
+            "what-if-scenarios must contain a table whose header includes "
+            "Scenario, Region, HA, Compute, Arch, the three monthly tiers, and Complexity"
+        ]
+    text = _plain_text(header.group(0))
+    missing: list[str] = []
+    for label, present in (
+        ("Scenario", "scenario" in text),
+        ("Region", "region" in text),
+        ("HA", "ha" in text or "availability" in text),
+        ("Compute", "compute" in text),
+        ("Arch", "arch" in text),
+        ("Complexity", "complexity" in text),
+    ):
+        if not present:
+            missing.append(label)
+    if not ("premium" in text and "balanced" in text and "optimized" in text):
+        missing.append("Premium/Balanced/Optimized")
+    if not missing:
+        return []
+    return [
+        "what-if-scenarios table is missing decision-core column(s): "
+        + ", ".join(missing)
+        + " (report-decision-core.md Section 3b)"
+    ]
+
+
+def _validate_decision_core_render(
+    html: str,
+    estimation_infra: dict | None,
+    aws_design: dict | None,
+    *,
+    mode: str,
+    migration_dir: Path | None,
+) -> list[str]:
+    """Fail when artifact fields that the decision core requires are not rendered.
+
+    REPORT_OK used to mean "the section IDs exist." A report can satisfy that
+    and still omit the verdict headline, hero metrics, flip conditions, the
+    specialist callout, and the architecture section. These checks fire only
+    when the corresponding artifact data was passed in, so a pre-extension
+    estimate is not rejected for fields it does not have.
+    """
+    if mode not in ("full", "decision"):
+        return []
+    errors: list[str] = []
+    summary = _section_html(html, "decision-summary") or ""
+    summary_text = _plain_text(summary)
+    recommendation = (estimation_infra or {}).get("recommendation") or {}
+
+    if recommendation:
+        if not re.search(r"\bmetric-hero\b", summary, re.IGNORECASE):
+            errors.append(
+                "recommendation block exists but decision-summary has no hero metric "
+                '(render the AWS run rate and migration shape with class="metric-hero")'
+            )
+        outcome = recommendation.get("outcome") or recommendation.get("outcome_label")
+        if outcome and not re.search(r"\bverdict-headline\b", summary, re.IGNORECASE):
+            errors.append(
+                "recommendation.outcome exists but decision-summary has no "
+                'verdict-headline (render outcome_label as <p class="verdict-headline">)'
+            )
+
+    flips = recommendation.get("would_flip_if")
+    if isinstance(flips, list) and flips and "what would flip" not in summary_text:
+        errors.append(
+            "recommendation.would_flip_if is non-empty but decision-summary has no "
+            '"What would flip this" list'
+        )
+
+    tracks = recommendation.get("track_outcomes")
+    if isinstance(tracks, list) and tracks and "by track" not in summary_text:
+        errors.append(
+            "recommendation.track_outcomes exists but decision-summary has no "
+            '"By track" disposition line'
+        )
+
+    conditions = recommendation.get("conditions")
+    if (
+        recommendation.get("outcome") == "conditional_go"
+        and isinstance(conditions, list)
+        and conditions
+    ):
+        summary_shingles = _word_shingles(summary_text)
+        for condition in conditions:
+            shingles = _word_shingles(_plain_text(str(condition)))
+            if shingles and not (shingles & summary_shingles):
+                errors.append(
+                    "recommendation.conditions is non-empty but decision-summary does "
+                    "not render that condition as a checklist (a shared phrase from the "
+                    "artifact condition is missing)"
+                )
+                break
+
+    if _design_has_deferred_service(aws_design) and "specialist engagement" not in summary_text:
+        errors.append(
+            'aws-design.json maps a service to "Deferred — specialist engagement" but '
+            "decision-summary has no specialist-engagement callout"
+        )
+
+    if mode == "full" and _design_has_clusters(aws_design):
+        if _section_html(html, "exec-architecture") is None:
+            errors.append(
+                'aws-design.json has clusters but no <section id="exec-architecture"> '
+                "(the architecture overview is required in full mode)"
+            )
+
+    risks = re.search(r'<section\b[^>]*\bid=["\']exec-risks["\']', html, re.IGNORECASE)
+    assumptions = re.search(
+        r'<section\b[^>]*\bid=["\']exec-assumptions["\']', html, re.IGNORECASE
+    )
+    if risks and assumptions and assumptions.start() < risks.start():
+        errors.append(
+            "exec-assumptions must follow exec-risks — the assumptions panel is the "
+            "last executive section (report-decision-core.md Section 8)"
+        )
+
+    risks_html = _section_html(html, "exec-risks")
+    if risks_html is not None and not re.search(r"<table\b", risks_html, re.IGNORECASE):
+        errors.append(
+            "exec-risks must render risks in a table (impact, likelihood, mitigation), "
+            "not a bullet list"
+        )
+
+    if migration_dir is not None:
+        index_path = migration_dir / "scenarios" / "index.json"
+        if index_path.is_file():
+            try:
+                index = json.loads(index_path.read_text(encoding="utf-8"))
+            except (OSError, json.JSONDecodeError):
+                index = None
+            scenarios = (index or {}).get("scenarios") or []
+            section = _section_html(html, "what-if-scenarios")
+            if len(scenarios) >= 2 and section is not None:
+                errors.extend(_what_if_column_errors(section))
+
+    return errors
+
+
 def validate_report(
     html: str,
     estimation_infra: dict | None = None,
@@ -1772,6 +1968,20 @@ def validate_report(
         )
     )
 
+    # Decision-core content. --no-require-toc remains the escape hatch for
+    # minimal unit fixtures; a normal Generate or Decision report must render
+    # the artifact fields, not only the section IDs.
+    if require_toc:
+        errors.extend(
+            _validate_decision_core_render(
+                html,
+                estimation_infra,
+                aws_design,
+                mode=mode,
+                migration_dir=migration_dir,
+            )
+        )
+
     # Catch verbatim copies of the reference fixture into a real run.
     errors.extend(_validate_fixture_bleed(html, migration_dir))
 
diff --git a/plugins/aws-startup-advisor/skills/azure-to-aws/references/phases/generate/generate-artifacts-report.md b/plugins/aws-startup-advisor/skills/azure-to-aws/references/phases/generate/generate-artifacts-report.md
index 69a72cf10..c302d9f17 100644
--- a/plugins/aws-startup-advisor/skills/azure-to-aws/references/phases/generate/generate-artifacts-report.md
+++ b/plugins/aws-startup-advisor/skills/azure-to-aws/references/phases/generate/generate-artifacts-report.md
@@ -183,9 +183,19 @@ migration plan, and that figures are estimates to validate before decisions.
 
 ## Step 5: Validate the rendered report (REQUIRED — mandatory gate)
 
-The prose above is not self-enforcing. Run the plugin's report validator, which is
-source-cloud-agnostic and already present at plugin root — resolve it the same way the
-`tf-best-practices` policy checker is resolved:
+The prose above is not self-enforcing. Render the report from
+`references/shared/report-decision-core.md` in **full** mode (or AI-only mode
+when there is no infra track) before you write HTML. `REPORT_OK` is not a
+substitute for that file: the shared validator rejects a report that has the
+right section IDs but omits decision-core content the artifacts require
+(verdict headline, hero metrics, per-track line, conditions, "What would flip
+this", the specialist-engagement callout, the architecture section when the
+design has clusters, assumptions after risks, a risk table, and the what-if
+columns Region / HA / Compute / Arch when two or more scenarios exist).
+
+Run the plugin's report validator, which is source-cloud-agnostic and already
+present at plugin root — resolve it the same way the `tf-best-practices` policy
+checker is resolved:
 
 ```bash
 python3 "$PLUGIN_ROOT/scripts/validate-migration-report.py" \
diff --git a/plugins/aws-startup-advisor/skills/azure-to-aws/references/phases/generate/generate.md b/plugins/aws-startup-advisor/skills/azure-to-aws/references/phases/generate/generate.md
index 0d865e9ef..c9df53f93 100644
--- a/plugins/aws-startup-advisor/skills/azure-to-aws/references/phases/generate/generate.md
+++ b/plugins/aws-startup-advisor/skills/azure-to-aws/references/phases/generate/generate.md
@@ -60,7 +60,7 @@ _postconditions:
     _on_failure: _halt_and_inform
   - _assert: "WHEN the run has an infra track: terraform/main.tf has a valid provider configuration; terraform/variables.tf declares at least an aws_region variable; at least one domain .tf file exists beyond the core files; and MIGRATION_GUIDE.md has Prerequisites and Verification sections. WHEN AI-only: vacuously satisfied (no terraform/ or MIGRATION_GUIDE.md on this path). README.md lists the generated artifacts on every path."
     _on_failure: _halt_and_inform
-  - _assert: "migration-report.html ALWAYS exists (it is a required _produces artifact on every path — an infra/mixed run and an AI-only app-code run alike; a completed Generate with no report is a gate failure, never a silent skip). It was rendered from references/shared/report-decision-core.md and PASSES $PLUGIN_ROOT/scripts/validate-migration-report.py (REPORT_OK, exit 0), which is the authority for required section IDs, TOC integrity, the CSS readability contract, and accessibility. Infra/mixed runs render full mode (validated default mode); an AI-only run (no aws-design.json / estimation-infra.json) renders AI-only mode and is validated with --mode ai_only --estimation-ai estimation-ai.json. A REPORT_FAIL leaves migration-report.incomplete.html and blocks completion. Additionally, for a run with an infra track: the report leads with cluster-level architecture rationale, the per-resource mapping table appears only in an appendix, and a draft-for-review footer is present"
+  - _assert: "migration-report.html ALWAYS exists (it is a required _produces artifact on every path — an infra/mixed run and an AI-only app-code run alike; a completed Generate with no report is a gate failure, never a silent skip). It was rendered from references/shared/report-decision-core.md and PASSES $PLUGIN_ROOT/scripts/validate-migration-report.py (REPORT_OK, exit 0), which enforces required section IDs, TOC integrity, the CSS readability contract, accessibility, and the decision-core content checks (verdict headline, hero metrics, flip conditions, specialist callout, architecture section, what-if columns) when the artifacts contain that data. REPORT_OK does not replace rendering references/shared/report-decision-core.md. Infra/mixed runs render full mode (validated default mode); an AI-only run (no aws-design.json / estimation-infra.json) renders AI-only mode and is validated with --mode ai_only --estimation-ai estimation-ai.json. A REPORT_FAIL leaves migration-report.incomplete.html and blocks completion. Additionally, for a run with an infra track: the report leads with cluster-level architecture rationale, the per-resource mapping table appears only in an appendix, and a draft-for-review footer is present"
     _on_failure: _halt_and_inform
   - _assert: "if scenarios/index.json has at least 2 scenarios, migration-report.html includes the what-if comparison"
     _on_failure: _halt_and_inform
diff --git a/plugins/aws-startup-advisor/skills/gcp-to-aws/references/phases/generate/generate-artifacts-report.md b/plugins/aws-startup-advisor/skills/gcp-to-aws/references/phases/generate/generate-artifacts-report.md
index e3fd70935..4b42c56ad 100644
--- a/plugins/aws-startup-advisor/skills/gcp-to-aws/references/phases/generate/generate-artifacts-report.md
+++ b/plugins/aws-startup-advisor/skills/gcp-to-aws/references/phases/generate/generate-artifacts-report.md
@@ -721,10 +721,20 @@ After generating the HTML file, verify:
 
 Load `shared/validate-migration-report.md`. Resolve script from plugin root: `$PLUGIN_ROOT/scripts/validate-migration-report.py`.
 
-The validator is **stdlib Python only**. It is the sole quality gate for generated
-reports. Do **not** ask the user to install Vale, Pa11y, axe, Lighthouse,
-Chromium, or any other prose/accessibility tooling. Do **not** skip validation
-because those tools are missing — they are never required.
+The validator is **stdlib Python only**. Do **not** ask the user to install Vale,
+Pa11y, axe, Lighthouse, Chromium, or any other prose/accessibility tooling. Do
+**not** skip validation because those tools are missing — they are never required.
+
+`REPORT_OK` is not a substitute for this file or for
+`references/shared/report-decision-core.md`. Load the decision core and render
+it in **full** mode before writing HTML. The validator then rejects a report
+that has the right section IDs but omits the decision-core content those
+artifacts require: the verdict headline, hero metrics, the per-track line, the
+conditions checklist, "What would flip this", the specialist-engagement
+callout, the architecture section when the design has clusters, the
+assumptions panel after risks, a risk table, and the what-if column set
+(Region, HA, Compute, Arch) when two or more scenarios exist. A report written
+only to satisfy an older structural gate will fail.
 
 ```bash
 python3 "$PLUGIN_ROOT/scripts/validate-migration-report.py" \
diff --git a/plugins/aws-startup-advisor/skills/gcp-to-aws/references/phases/generate/generate.md b/plugins/aws-startup-advisor/skills/gcp-to-aws/references/phases/generate/generate.md
index adfe5870f..f1a8e7143 100644
--- a/plugins/aws-startup-advisor/skills/gcp-to-aws/references/phases/generate/generate.md
+++ b/plugins/aws-startup-advisor/skills/gcp-to-aws/references/phases/generate/generate.md
@@ -162,7 +162,7 @@ Produces: `migration-report.html`
 
 **Validation gate:** Report generation runs `shared/validate-artifacts.md` first. If validation emits `GATE_FAIL`: log the failure to the user, **do not write** `migration-report.html`, and continue to Phase Completion (report is optional output; validation failure is not a silent skip). Do **NOT** patch artifacts to pass validation.
 
-After writing `migration-report.html`, run `shared/validate-migration-report.md` (automated script). Branch on the shell exit code per that doc's table — `0` (`REPORT_OK`), `1` (`REPORT_FAIL`: remove or rename incomplete HTML and warn the user — do not present a stub report as complete), or anything else (validator did not run, e.g. `python3` missing — tell the user validation was skipped, do not treat it as pass or fail).
+After writing `migration-report.html`, run `shared/validate-migration-report.md` (automated script). `REPORT_OK` means the decision-core content checks passed, not that the section IDs alone were present — the HTML must still have been rendered from `references/shared/report-decision-core.md`. Branch on the shell exit code per that doc's table — `0` (`REPORT_OK`), `1` (`REPORT_FAIL`: remove or rename incomplete HTML and warn the user — do not present a stub report as complete), or anything else (validator did not run, e.g. `python3` missing — tell the user validation was skipped, do not treat it as pass or fail).
 
 ## Phase Completion
 
diff --git a/plugins/aws-startup-advisor/skills/gcp-to-aws/references/shared/validate-migration-report.md b/plugins/aws-startup-advisor/skills/gcp-to-aws/references/shared/validate-migration-report.md
index 15966cd1f..a2c8b8443 100644
--- a/plugins/aws-startup-advisor/skills/gcp-to-aws/references/shared/validate-migration-report.md
+++ b/plugins/aws-startup-advisor/skills/gcp-to-aws/references/shared/validate-migration-report.md
@@ -48,8 +48,13 @@ Handle exactly three outcomes:
 
 ## Scope
 
-This validator is a **structural + content + visual-readability completeness
-gate**. The visual contract is intentionally capability-based rather than
+This validator is a **structural + decision-core + visual-readability completeness
+gate**. `REPORT_OK` does not replace loading `report-decision-core.md` and
+rendering it before the HTML is written. When the estimate or design passed
+on the command line contains the data, the script also rejects a report that
+omits the verdict headline, hero metrics, the per-track line, the conditions
+checklist, "What would flip this", the specialist-engagement callout, the
+architecture section, a risk table, or the what-if column set. The visual contract is intentionally capability-based rather than
 pixel-perfect: reports must preserve the shared contrasting page shell,
 bordered section cards, responsive metric grid, mobile breakpoint, keyboard
 focus state, and print rules from `generate-artifacts-report.md`. Colors and
@@ -87,7 +92,7 @@ decision reports.
 | 14 | No fixture bleed                   | With `--migration-dir`: the reference canary migration ID does not appear in a real run, and the report's migration ID matches the run folder                                                                                                                                                                                                                                                                                                                                                                                           |
 | 15 | Readability — reader vocabulary    | No artifact filename (`*.json`) or Terraform resource ID (`aws_<resource>.<name>`) inside any `exec-*` / `decision-summary` section. The executive flow names what the reader controls; those identifiers live only in the appendices                                                                                                                                                                                                                                                                                                   |
 | 16 | Ordered action lists               | When `Key decisions ahead` or `Next steps` headings exist in `decision-summary`, the following list is `<ol>`, not `<ul>`                                                                                                                                                                                                                                                                                                                                                                                                               |
-| 17 | Configuration provenance           | When `<section id="appendix-config">` exists: table includes Question/Assumption and Design consequence columns; ≥2 data rows                                                                                                                                                                                                                                                                                                                                                                                                           |
+| 17 | Configuration provenance           | When `<section id="appendix-config">` exists: table includes Question/Assumption, Your choice, Source, and Design consequence columns; ≥2 data rows                                                                                                                                                                                                                                                                                                                                                                                    |
 | 18 | What-if scenarios                  | With `--migration-dir`: if `scenarios/index.json` lists ≥2 scenarios, exactly one `<section id="what-if-scenarios">` (workshop compare table)                                                                                                                                                                                                                                                                                                                                                                                           |
 | 19 | Activate action link               | If `decision-summary` mentions AWS Activate, that section includes a clickable link to `https://aws.amazon.com/startups/credits/`; an appendix-only link is insufficient                                                                                                                                                                                                                                                                                                                                                                |
 | 20 | Glossary appendix                  | Full reports contain `<section id="appendix-glossary">` with a bordered `<table class="glossary-table">`, `Term` and `Meaning` columns, and at least three rows                                                                                                                                                                                                                                                                                                                                                                         |
@@ -96,6 +101,7 @@ decision reports.
 | 23 | Leadership brief                   | When an estimation artifact is passed, `exec-share` contains a static, copy-ready `share-card` without scripts or controls                                                                                                                                                                                                                                                                                                                                                                                                              |
 | 24 | Accessibility semantics            | Normal generated reports declare document language, contain exactly one `<h1>`, caption every table, scope table headers, and give every figure an image role, accessible name, and text alternative                                                                                                                                                                                                                                                                                                                                    |
 | 25 | Cost Optimization section          | If `optimization_opportunities[]` is non-empty: exactly one `exec-optimization` (TOC-linked) comparing Balanced on-demand vs Savings Plans / RI, plus (full mode only) a standalone `appendix-optimization` table with Optimization / Target / Monthly savings / Commitment / Effort columns. A table buried only in `appendix-costs` fails. Do not add SP/RI savings on top of Optimized. If RDS/Aurora/Fargate/Lambda is in `--aws-design` or opportunity targets, the section must include a Savings Plans or Reserved Instances row |
+| 26 | Decision-core render               | When `--estimation-infra` has a `recommendation`: hero metrics (`metric-hero`) and, when the fields exist, a `verdict-headline`, a "By track" line, a conditions checklist, and "What would flip this". When `--aws-design` has a deferred service: a specialist-engagement callout in `decision-summary`. Full mode with `clusters`: `<section id="exec-architecture">`. `exec-assumptions` follows `exec-risks`. `exec-risks` is a table. With ≥2 scenarios, the what-if table includes Region, HA, Compute, Arch, and Complexity |
 
 Checks 10, 11, and 15 scan the `<body>` with `<style>` stripped, so CSS class names (e.g. `.rubric`) and selectors never trip them. The same readability scan rejects customer-facing "TCO" because modeled cloud charges do not include staffing or operating labor. Check 15 scopes to executive-flow sections only — appendices may carry artifact filenames and resource IDs by design. Disable checks 10, 11, and 15 with `--no-readability` only for non-customer fixtures. Check 14 is inert without `--migration-dir`, so validating the reference fixture (which legitimately contains the canary ID) never self-trips. Checks 16–17 apply whenever the corresponding sections/headings exist.
 
diff --git a/plugins/aws-startup-advisor/skills/heroku-to-aws/references/phases/generate/generate-report.md b/plugins/aws-startup-advisor/skills/heroku-to-aws/references/phases/generate/generate-report.md
index 92f26a3ee..ba78471ef 100644
--- a/plugins/aws-startup-advisor/skills/heroku-to-aws/references/phases/generate/generate-report.md
+++ b/plugins/aws-startup-advisor/skills/heroku-to-aws/references/phases/generate/generate-report.md
@@ -269,6 +269,12 @@ python3 "<SKILL_BASE>/scripts/validate-heroku-migration-report.py" \
   "$MIGRATION_DIR/migration-report.html" --mode full --migration-dir "$MIGRATION_DIR"
 ```
 
+`REPORT_OK` means the validator's decision-core checks passed. It is not a substitute for the content
+rules in this file: when `recommendation.would_flip_if` is non-empty the
+summary must include "What would flip this", and when two or more scenarios
+exist the what-if table must include Region, HA, Compute, Arch, and Complexity.
+A report written only to satisfy the section-ID list will fail.
+
 `REPORT_OK` → the report gate passes. `REPORT_FAIL` → the main-window step emits `GATE_FAIL` **and
 pastes the validator's `errors[]` verbatim**; the gate does not edit the HTML itself. The pasted
 errors are what make recovery actionable — a bare "re-run Generate" is not a fix, since re-dispatch
@@ -277,8 +283,9 @@ re-authors the report under this shell-less worker. On `REPORT_OK` the finish st
 hand-edit of the report from those errors + a direct validator re-run and re-stamp (or a maintainer
 re-running Generate for a clean rebuild).
 The validator enforces the required sections, the `draft for review` footer, the typography-first
-verdict rules, non-empty `cost-optimization`, and the a11y subset the report emits (`<th scope>`,
-`<figure>` labels).
+verdict rules, "What would flip this" when `would_flip_if` is present, the what-if
+column set when two or more scenarios exist, non-empty `cost-optimization`, and the
+a11y subset the report emits (`<th scope>`, `<figure>` labels).
 
 ---
 
diff --git a/plugins/aws-startup-advisor/skills/heroku-to-aws/scripts/test_validate_heroku_migration_report.py b/plugins/aws-startup-advisor/skills/heroku-to-aws/scripts/test_validate_heroku_migration_report.py
index 33199ba45..5ab8154aa 100644
--- a/plugins/aws-startup-advisor/skills/heroku-to-aws/scripts/test_validate_heroku_migration_report.py
+++ b/plugins/aws-startup-advisor/skills/heroku-to-aws/scripts/test_validate_heroku_migration_report.py
@@ -119,6 +119,63 @@ def test_verdict_headline_not_required_without_recommendation() -> None:
     assert "REPORT_OK" in out
 
 
+def test_would_flip_required_when_artifact_has_it() -> None:
+    html = GOOD.replace(
+        '<p class="verdict-headline">Go, with conditions</p>',
+        '<p class="verdict-headline">Go, with conditions</p>'
+        "<h3>What would flip this</h3><ul><li>A published rate above the Heroku bill.</li></ul>",
+    )
+    with tempfile.TemporaryDirectory() as tmp:
+        d = Path(tmp)
+        (d / "estimation-infra.json").write_text(
+            json.dumps(
+                {
+                    "recommendation": {
+                        "outcome": "go_conditional",
+                        "would_flip_if": ["A published rate above the Heroku bill."],
+                    }
+                }
+            ),
+            encoding="utf-8",
+        )
+        missing, out = run(GOOD, migration_dir=d)
+        present, ok = run(html, migration_dir=d)
+    assert missing == 1, out
+    assert "would_flip" in out
+    assert present == 0, ok
+
+
+def test_what_if_columns_required_when_section_present() -> None:
+    thin = GOOD.replace(
+        '<section id="next-steps">',
+        '<section id="what-if-scenarios"><table><thead><tr>'
+        '<th scope="col">Scenario</th><th scope="col">Monthly</th>'
+        "</tr></thead><tbody><tr><td>Baseline</td><td>$1</td></tr></tbody></table></section>"
+        '<section id="next-steps">',
+    )
+    full = GOOD.replace(
+        '<section id="next-steps">',
+        '<section id="what-if-scenarios"><table><thead><tr>'
+        '<th scope="col">Scenario</th><th scope="col">Region</th><th scope="col">HA</th>'
+        '<th scope="col">Compute</th><th scope="col">Arch</th>'
+        '<th scope="col">Complexity</th></tr></thead>'
+        "<tbody><tr><td>Baseline</td><td>us-east-1</td><td>Multi-AZ</td>"
+        "<td>Fargate</td><td>mixed</td><td>Large</td></tr></tbody></table></section>"
+        '<section id="next-steps">',
+    )
+    with tempfile.TemporaryDirectory() as tmp:
+        d = Path(tmp)
+        (d / "scenarios").mkdir()
+        (d / "scenarios" / "index.json").write_text(
+            json.dumps({"scenarios": [{"id": "a"}, {"id": "b"}]}), encoding="utf-8"
+        )
+        bad, bad_out = run(thin, migration_dir=d)
+        good, good_out = run(full, migration_dir=d)
+    assert bad == 1, bad_out
+    assert "Region" in bad_out
+    assert good == 0, good_out
+
+
 def test_what_if_required_when_two_scenarios() -> None:
     with tempfile.TemporaryDirectory() as tmp:
         d = Path(tmp)
diff --git a/plugins/aws-startup-advisor/skills/heroku-to-aws/scripts/validate-heroku-migration-report.py b/plugins/aws-startup-advisor/skills/heroku-to-aws/scripts/validate-heroku-migration-report.py
index 5a6fa7f0e..f56145e45 100644
--- a/plugins/aws-startup-advisor/skills/heroku-to-aws/scripts/validate-heroku-migration-report.py
+++ b/plugins/aws-startup-advisor/skills/heroku-to-aws/scripts/validate-heroku-migration-report.py
@@ -821,6 +821,7 @@ def _validate_verdict(html: str, migration_dir: Path | None) -> list[str]:
 
     # When Estimate declared a recommendation outcome, the verdict headline is required.
     recommendation_outcome = False
+    flips: list = []
     if migration_dir is not None:
         est_path = migration_dir / "estimation-infra.json"
         if est_path.is_file():
@@ -828,6 +829,8 @@ def _validate_verdict(html: str, migration_dir: Path | None) -> list[str]:
                 est = json.loads(est_path.read_text(encoding="utf-8"))
                 rec = (est or {}).get("recommendation") or {}
                 recommendation_outcome = bool(rec.get("outcome"))
+                raw_flips = rec.get("would_flip_if") or []
+                flips = raw_flips if isinstance(raw_flips, list) else []
             except (OSError, json.JSONDecodeError):
                 # Fail open on ambiguity: a missing/corrupt estimate does not force the
                 # verdict-headline requirement (we can't confirm an outcome was declared).
@@ -838,6 +841,13 @@ def _validate_verdict(html: str, migration_dir: Path | None) -> list[str]:
             "decision-summary has no verdict-headline element "
             '(render outcome_label as <p class="verdict-headline">…</p>)'
         )
+    if flips:
+        visible = re.sub(r"<[^>]+>", " ", summary).lower()
+        if "what would flip" not in visible:
+            errors.append(
+                "estimation-infra.json declares recommendation.would_flip_if but "
+                'decision-summary has no "What would flip this" list'
+            )
     return errors
 
 
@@ -956,6 +966,35 @@ def _validate_accessibility(html: str) -> list[str]:
     return errors
 
 
+def _what_if_column_errors(section: str) -> list[str]:
+    """Workshop compare tables use the same column set as generate-report.md."""
+    header = re.search(r"<thead\b.*?</thead>", section, re.DOTALL | re.IGNORECASE)
+    if not header:
+        return [
+            "what-if-scenarios must contain a table headed "
+            "Scenario, Region, HA, Compute, Arch, and Complexity"
+        ]
+    text = re.sub(r"<[^>]+>", " ", header.group(0)).lower()
+    missing = [
+        label
+        for label, present in (
+            ("Region", "region" in text),
+            ("HA", "ha" in text or "availability" in text),
+            ("Compute", "compute" in text),
+            ("Arch", re.search(r"\barch\b", text) is not None),
+            ("Complexity", "complexity" in text),
+        )
+        if not present
+    ]
+    if not missing:
+        return []
+    return [
+        "what-if-scenarios table is missing column(s): "
+        + ", ".join(missing)
+        + " (generate-report.md what-if table)"
+    ]
+
+
 def validate(html: str, migration_dir: Path | None, mode: str = "full") -> list[str]:
     errors: list[str] = []
     counts = _section_counts(html)
@@ -1011,6 +1050,9 @@ def validate(html: str, migration_dir: Path | None, mode: str = "full") -> list[
                     'scenarios/index.json has ≥2 scenarios but no '
                     '<section id="what-if-scenarios">'
                 )
+            elif len(scenarios) >= 2:
+                section = _section_html(html, "what-if-scenarios") or ""
+                errors.extend(_what_if_column_errors(section))
 
         # generate-report.md / report-decision-core.md § decision-basis: when Estimate
         # declared decision_basis (evidence/assumptions behind the verdict), the report

From 3428cc66f96b639368fcd1c9e63ff17f874d5bc9 Mon Sep 17 00:00:00 2001
From: Logan Kleier <lkleier@amazon.com>
Date: Thu, 1 Oct 2026 14:17:35 -0700
Subject: [PATCH 02/10] fix(report-validator): drop inert subtrees in
 _plain_text; correct stale 'structural-only' docs
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Address two should-fix review findings on PR #396:

1. [Completeness] The shared validator's _plain_text kept <template> content, so a
   'What would flip this' block hidden inside <template> satisfied the flip check
   even though a browser never renders it (the Heroku validator already rejected
   this). _plain_text now strips HTML comments and inert script/style/template
   subtrees before the text scan, matching the Heroku decoded-text semantics.
   Added test_would_flip_list_only_in_template_fails as a regression (confirmed it
   fails against the pre-fix _plain_text).

2. [Contradictions] Four Graviton doc files + estimate-infra.md still described the
   report validator as 'structural-only' / 'structural/readability gate', which the
   new decision-core checks contradict. Reworded to 'checks structure and
   decision-core content but does not (yet) audit dollar figures' — preserving the
   accurate part (the architecture_comparison numeric assertion is still a tracked
   follow-up).
---
 ...t_validate_migration_report_decision_core.py | 13 +++++++++++++
 .../scripts/validate-migration-report.py        | 17 +++++++++++++++--
 .../azure-to-aws/references/shared/graviton.md  |  2 +-
 .../references/shared/schema-graviton.md        |  2 +-
 .../phases/estimate/estimate-infra.md           |  2 +-
 .../gcp-to-aws/references/shared/graviton.md    |  2 +-
 .../references/shared/schema-graviton.md        |  2 +-
 7 files changed, 33 insertions(+), 7 deletions(-)

diff --git a/plugins/aws-startup-advisor/scripts/test_validate_migration_report_decision_core.py b/plugins/aws-startup-advisor/scripts/test_validate_migration_report_decision_core.py
index da8f879e1..5ae18a798 100644
--- a/plugins/aws-startup-advisor/scripts/test_validate_migration_report_decision_core.py
+++ b/plugins/aws-startup-advisor/scripts/test_validate_migration_report_decision_core.py
@@ -52,6 +52,19 @@ def test_missing_would_flip_list_fails() -> None:
     assert any("would_flip" in err for err in errors), errors
 
 
+def test_would_flip_list_only_in_template_fails() -> None:
+    # A browser never renders <template> contents, so a flip heading hidden there
+    # must not satisfy the check (regression for the shared validator keeping
+    # <template> text; the Heroku validator already rejected this input).
+    validator = _load()
+    html = _reference_html().replace(
+        "<h3>What would flip this</h3>",
+        "<template><h3>What would flip this</h3></template>",
+    )
+    errors = validator.validate_report(html, _reference_estimate(), None)
+    assert any("would_flip" in err for err in errors), errors
+
+
 def test_deferred_service_without_callout_fails() -> None:
     validator = _load()
     html = _reference_html().replace("specialist engagement", "analytics follow-up")
diff --git a/plugins/aws-startup-advisor/scripts/validate-migration-report.py b/plugins/aws-startup-advisor/scripts/validate-migration-report.py
index d64f803d9..ef870e2b7 100644
--- a/plugins/aws-startup-advisor/scripts/validate-migration-report.py
+++ b/plugins/aws-startup-advisor/scripts/validate-migration-report.py
@@ -1655,8 +1655,21 @@ def _validate_fixture_bleed(html: str, migration_dir: Path | None) -> list[str]:
 
 
 def _plain_text(fragment: str) -> str:
-    """Decoded visible text, with dashes folded so artifact prose can be matched."""
-    text = unescape(re.sub(r"<[^>]+>", " ", fragment))
+    """Decoded visible text, with dashes folded so artifact prose can be matched.
+
+    Inert subtrees (`<script>`, `<style>`, `<template>`) and HTML comments are
+    dropped first: the browser does not render their contents, so a decision-core
+    heading or condition hidden inside a `<template>` must not count as rendered.
+    This matches the Heroku validator's decoded-text semantics.
+    """
+    stripped = re.sub(r"<!--.*?-->", " ", fragment, flags=re.DOTALL)
+    stripped = re.sub(
+        r"<(script|style|template)\b[^>]*>.*?</\1\s*>",
+        " ",
+        stripped,
+        flags=re.DOTALL | re.IGNORECASE,
+    )
+    text = unescape(re.sub(r"<[^>]+>", " ", stripped))
     text = text.replace("\u2014", "-").replace("\u2013", "-")
     return re.sub(r"\s+", " ", text).strip().lower()
 
diff --git a/plugins/aws-startup-advisor/skills/azure-to-aws/references/shared/graviton.md b/plugins/aws-startup-advisor/skills/azure-to-aws/references/shared/graviton.md
index 0c63479b4..e62205304 100644
--- a/plugins/aws-startup-advisor/skills/azure-to-aws/references/shared/graviton.md
+++ b/plugins/aws-startup-advisor/skills/azure-to-aws/references/shared/graviton.md
@@ -83,7 +83,7 @@ Model **only** the hourly price discount. Use `pricing-cache.md` Graviton rows w
 The cost report should surface Graviton savings, but the report generator and its validator (`generate-artifacts-report.md`, `shared/validate-migration-report.md`, `scripts/validate-migration-report.py`) do not yet carry it. A follow-up should:
 
 - Render `architecture_comparison` in the report's cost breakdown / decision summary (a "Graviton savings" line: `graviton_monthly` vs `x86_equivalent_monthly`, `savings_percent`), reusing the report's existing section-ID and table conventions.
-- Add a numeric assertion to `validate-migration-report.py` that the rendered Graviton savings match `estimation-infra.json` → `architecture_comparison` (`savings_amount` / `savings_percent`). That validator is intentionally structural-only today, so this is a net-new check, not a modification of existing behavior.
+- Add a numeric assertion to `validate-migration-report.py` that the rendered Graviton savings match `estimation-infra.json` → `architecture_comparison` (`savings_amount` / `savings_percent`). That validator checks structure and decision-core content but does not yet audit dollar figures, so this is a net-new check, not a modification of existing behavior.
 
 Until then, numeric agreement between report and `architecture_comparison` is a manual self-check.
 
diff --git a/plugins/aws-startup-advisor/skills/azure-to-aws/references/shared/schema-graviton.md b/plugins/aws-startup-advisor/skills/azure-to-aws/references/shared/schema-graviton.md
index f5b7ab107..34f540f47 100644
--- a/plugins/aws-startup-advisor/skills/azure-to-aws/references/shared/schema-graviton.md
+++ b/plugins/aws-startup-advisor/skills/azure-to-aws/references/shared/schema-graviton.md
@@ -121,4 +121,4 @@ When all compute services are `tier: ready` and the user is not asked, write `va
 | `savings_percent`        | `savings_amount / x86_equivalent_monthly × 100`, one decimal |
 | `note`                   | Required; states that only hourly price discount is modeled  |
 
-**Report consistency:** when the migration report renders Graviton savings, the figures MUST equal these fields (no recomputation in the report layer). This is a **manual self-check** today; the post-write report validator is structural/readability only and does not audit dollar figures. An automated numeric assertion is a tracked follow-up (see `shared/graviton.md` → "Report rendering").
+**Report consistency:** when the migration report renders Graviton savings, the figures MUST equal these fields (no recomputation in the report layer). This is a **manual self-check** today; the post-write report validator checks structure and decision-core content but does not audit dollar figures. An automated numeric assertion is a tracked follow-up (see `shared/graviton.md` → "Report rendering").
diff --git a/plugins/aws-startup-advisor/skills/gcp-to-aws/references/phases/estimate/estimate-infra.md b/plugins/aws-startup-advisor/skills/gcp-to-aws/references/phases/estimate/estimate-infra.md
index f376c9ad5..77312e5ae 100644
--- a/plugins/aws-startup-advisor/skills/gcp-to-aws/references/phases/estimate/estimate-infra.md
+++ b/plugins/aws-startup-advisor/skills/gcp-to-aws/references/phases/estimate/estimate-infra.md
@@ -340,7 +340,7 @@ Model **only the hourly price discount** — never the performance uplift. For t
 
 Emit an `architecture_comparison` block in `estimation-infra.json` per the `schema-graviton.md` schema. This is **not** a fourth pricing tier — Graviton is the architecture within the Balanced/Premium/Optimized tiers, and the Balanced tier totals already reflect Graviton pricing when selected.
 
-**Report consistency:** the migration report must render these exact figures (no recomputation in the report layer). Numeric agreement is currently a **manual self-check** — the post-write report validator (`shared/validate-migration-report.md`) is a structural/readability gate and explicitly does not audit dollar figures. Rendering the Graviton savings in the report and adding an automated `architecture_comparison` numeric assertion to `validate-migration-report.py` are tracked as a **follow-up** (see `shared/graviton.md` → "Report rendering").
+**Report consistency:** the migration report must render these exact figures (no recomputation in the report layer). Numeric agreement is currently a **manual self-check** — the post-write report validator (`shared/validate-migration-report.md`) gates structure and decision-core content but explicitly does not audit dollar figures. Rendering the Graviton savings in the report and adding an automated `architecture_comparison` numeric assertion to `validate-migration-report.py` are tracked as a **follow-up** (see `shared/graviton.md` → "Report rendering").
 
 ---
 
diff --git a/plugins/aws-startup-advisor/skills/gcp-to-aws/references/shared/graviton.md b/plugins/aws-startup-advisor/skills/gcp-to-aws/references/shared/graviton.md
index b4cb3ba49..1e56c9a72 100644
--- a/plugins/aws-startup-advisor/skills/gcp-to-aws/references/shared/graviton.md
+++ b/plugins/aws-startup-advisor/skills/gcp-to-aws/references/shared/graviton.md
@@ -83,7 +83,7 @@ Model **only** the hourly price discount. Use `pricing-cache.md` Graviton rows w
 The cost report should surface Graviton savings, but the report generator and its validator (`generate-artifacts-report.md`, `shared/validate-migration-report.md`, `scripts/validate-migration-report.py`) do not cover `architecture_comparison` today. A follow-up should:
 
 - Render `architecture_comparison` in the report's cost breakdown / decision summary (a "Graviton savings" line: `graviton_monthly` vs `x86_equivalent_monthly`, `savings_percent`), reusing the report generator's existing section-ID and table conventions.
-- Add a numeric assertion to `validate-migration-report.py` that the rendered Graviton savings match `estimation-infra.json` → `architecture_comparison` (`savings_amount` / `savings_percent`). That validator is intentionally structural-only today, so this is a net-new check, not a modification of existing behavior.
+- Add a numeric assertion to `validate-migration-report.py` that the rendered Graviton savings match `estimation-infra.json` → `architecture_comparison` (`savings_amount` / `savings_percent`). That validator checks structure and decision-core content but does not yet audit dollar figures, so this is a net-new check, not a modification of existing behavior.
 
 Until then, numeric agreement between report and `architecture_comparison` is a manual self-check.
 
diff --git a/plugins/aws-startup-advisor/skills/gcp-to-aws/references/shared/schema-graviton.md b/plugins/aws-startup-advisor/skills/gcp-to-aws/references/shared/schema-graviton.md
index f5b7ab107..34f540f47 100644
--- a/plugins/aws-startup-advisor/skills/gcp-to-aws/references/shared/schema-graviton.md
+++ b/plugins/aws-startup-advisor/skills/gcp-to-aws/references/shared/schema-graviton.md
@@ -121,4 +121,4 @@ When all compute services are `tier: ready` and the user is not asked, write `va
 | `savings_percent`        | `savings_amount / x86_equivalent_monthly × 100`, one decimal |
 | `note`                   | Required; states that only hourly price discount is modeled  |
 
-**Report consistency:** when the migration report renders Graviton savings, the figures MUST equal these fields (no recomputation in the report layer). This is a **manual self-check** today; the post-write report validator is structural/readability only and does not audit dollar figures. An automated numeric assertion is a tracked follow-up (see `shared/graviton.md` → "Report rendering").
+**Report consistency:** when the migration report renders Graviton savings, the figures MUST equal these fields (no recomputation in the report layer). This is a **manual self-check** today; the post-write report validator checks structure and decision-core content but does not audit dollar figures. An automated numeric assertion is a tracked follow-up (see `shared/graviton.md` → "Report rendering").

From 4141a531079421d7090d90598dad77380ef3118c Mon Sep 17 00:00:00 2001
From: Logan Kleier <lkleier@amazon.com>
Date: Fri, 2 Oct 2026 10:47:43 -0700
Subject: [PATCH 03/10] =?UTF-8?q?fix(aws-startup-advisor):=20validate-migr?=
 =?UTF-8?q?ation-report=20=E2=80=94=20match=20short=20conditions,=20requir?=
 =?UTF-8?q?e=20populated=20flip=20list,=20ignore=20inert=20markup?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Three decision-core checks accepted the wrong thing:

- conditional_go conditions of one to three words could never match: the
  condition collapsed to a single shingle while the summary was cut into
  four-word shingles, so the sets never intersected. _phrase_rendered now
  cuts both sides at the condition's own token width (capped at four).
- "What would flip this" was satisfied by the heading alone; an empty or
  partial <ul> passed with a populated would_flip_if. The list that follows
  the heading is now parsed and every artifact entry must render as an item.
- metric-hero / verdict-headline were regex-searched in the raw summary, so
  a class inside <template> counted. Class tokens are now read from rendered
  start tags only.

_RenderedFragmentParser flattens the summary into rendered text runs, list
items and class tokens, skipping script/style/template subtrees and comments,
with inline tags kept as one phrase. Tests cover each repro: short rendered
conditions pass, omitted short/long conditions fail, empty/partial/template
flip lists fail, a complete list with inline markup and entities passes,
template-only headline and hero fail, unquoted class attribute passes.
---
 ...validate_migration_report_decision_core.py | 138 ++++++++++++++++
 .../scripts/validate-migration-report.py      | 156 ++++++++++++++++--
 2 files changed, 284 insertions(+), 10 deletions(-)

diff --git a/plugins/aws-startup-advisor/scripts/test_validate_migration_report_decision_core.py b/plugins/aws-startup-advisor/scripts/test_validate_migration_report_decision_core.py
index 5ae18a798..44b9f68b9 100644
--- a/plugins/aws-startup-advisor/scripts/test_validate_migration_report_decision_core.py
+++ b/plugins/aws-startup-advisor/scripts/test_validate_migration_report_decision_core.py
@@ -65,6 +65,144 @@ def test_would_flip_list_only_in_template_fails() -> None:
     assert any("would_flip" in err for err in errors), errors
 
 
+FLIP_BLOCK = """      <h3>What would flip this</h3>
+      <ul class="compact">
+        <li>Single-AZ acceptable: AWS estimate drops further, strengthens go</li>
+        <li>BigQuery must cut over in the same window: defer for specialist evidence</li>
+      </ul>"""
+
+
+def _flip_errors(html: str) -> list[str]:
+    validator = _load()
+    return [e for e in validator.validate_report(html, _reference_estimate(), None) if "flip" in e]
+
+
+def test_would_flip_heading_with_empty_list_fails() -> None:
+    # The heading alone is not the content: an empty <ul> under "What would flip
+    # this" renders none of recommendation.would_flip_if and must fail.
+    html = _reference_html().replace(
+        FLIP_BLOCK, '      <h3>What would flip this</h3>\n      <ul class="compact"></ul>'
+    )
+    assert html != _reference_html()
+    errors = _flip_errors(html)
+    assert errors, "empty flip list passed"
+    assert "0 of 2" in errors[0], errors
+
+
+def test_would_flip_partial_list_fails() -> None:
+    html = _reference_html().replace(
+        "        <li>BigQuery must cut over in the same window: defer for specialist evidence</li>\n",
+        "",
+    )
+    assert html != _reference_html()
+    errors = _flip_errors(html)
+    assert errors, "partial flip list passed"
+    assert "1 of 2" in errors[0] and "BigQuery" in errors[0], errors
+
+
+def test_would_flip_items_only_in_template_fail() -> None:
+    html = _reference_html().replace(
+        "      <ul class=\"compact\">\n        <li>Single-AZ acceptable",
+        "      <ul class=\"compact\"><template><li>hidden</li></template>\n        <li>Single-AZ acceptable",
+    )
+    html = html.replace(
+        "        <li>BigQuery must cut over in the same window: defer for specialist evidence</li>\n",
+        "        <template><li>BigQuery must cut over in the same window: defer for specialist evidence</li></template>\n",
+    )
+    assert html != _reference_html()
+    errors = _flip_errors(html)
+    assert errors and "BigQuery" in errors[0], errors
+
+
+def test_would_flip_complete_list_passes_with_inline_markup() -> None:
+    # Inline tags and entities inside the heading and the items are what the
+    # reader sees as one phrase; they must not break recognition.
+    html = _reference_html().replace(
+        FLIP_BLOCK,
+        """      <h3>What&nbsp;<em>would</em>\n flip this</h3>
+      <ul class="compact">
+        <li><strong>Single-AZ</strong> acceptable: AWS estimate drops further, strengthens go</li>
+        <li>BigQuery must cut over in the same window: defer for specialist evidence</li>
+      </ul>""",
+    )
+    assert html != _reference_html()
+    assert _flip_errors(html) == []
+
+
+def _with_condition(condition: str, *, rendered: bool) -> tuple[str, dict]:
+    estimate = _reference_estimate()
+    estimate["recommendation"]["conditions"] = [condition]
+    html = _reference_html()
+    if rendered:
+        html = html.replace(
+            "<li>Condition: confirm CUD expiration date before committing a migration start date</li>",
+            f"<li>Condition: {condition}</li>",
+        )
+        assert html != _reference_html()
+    return html, estimate
+
+
+def test_short_rendered_conditions_pass() -> None:
+    # One-to-three-word conditions are a single phrase narrower than the old
+    # fixed four-word shingle; they must match when rendered verbatim.
+    validator = _load()
+    for condition in ("Confirm capacity", "Complete load testing", "Confirm"):
+        html, estimate = _with_condition(condition, rendered=True)
+        errors = [e for e in validator.validate_report(html, estimate, None) if "condition" in e]
+        assert errors == [], (condition, errors)
+
+
+def test_omitted_short_condition_fails() -> None:
+    validator = _load()
+    html, estimate = _with_condition("Confirm capacity", rendered=False)
+    errors = [e for e in validator.validate_report(html, estimate, None) if "condition" in e]
+    assert errors, "omitted condition passed"
+
+
+def test_omitted_long_condition_fails() -> None:
+    validator = _load()
+    html, estimate = _with_condition(
+        "Complete a load test against the Balanced sizing before cutover", rendered=False
+    )
+    errors = [e for e in validator.validate_report(html, estimate, None) if "condition" in e]
+    assert errors, "omitted condition passed"
+
+
+def test_verdict_headline_only_in_template_fails() -> None:
+    validator = _load()
+    html = _reference_html().replace(
+        '<p class="verdict-headline">Go, with conditions</p>',
+        '<template><p class="verdict-headline">Go, with conditions</p></template>',
+    )
+    assert html != _reference_html()
+    errors = validator.validate_report(html, _reference_estimate(), None)
+    assert any("verdict-headline" in err for err in errors), errors
+
+
+def test_metric_hero_only_in_template_fails() -> None:
+    validator = _load()
+    html = _reference_html().replace('<div class="metric metric-hero">', '<div class="metric">')
+    html = html.replace(
+        '<div class="metrics">',
+        '<template><div class="metric metric-hero"></div></template>\n      <div class="metrics">',
+    )
+    assert html.count("metric-hero") >= 1
+    errors = validator.validate_report(html, _reference_estimate(), None)
+    assert any("metric-hero" in err for err in errors), errors
+
+
+def test_metric_hero_unquoted_class_passes() -> None:
+    # Class tokens are read from the parsed attribute, not a literal regex, so
+    # any legal spelling of the attribute counts as rendered.
+    validator = _load()
+    html = _reference_html().replace(
+        '<div class="metric metric-hero">', "<div class='metric metric-hero'>"
+    )
+    assert html != _reference_html()
+    errors = validator.validate_report(html, _reference_estimate(), None)
+    assert not any("metric-hero" in err for err in errors), errors
+
+
 def test_deferred_service_without_callout_fails() -> None:
     validator = _load()
     html = _reference_html().replace("specialist engagement", "analytics follow-up")
diff --git a/plugins/aws-startup-advisor/scripts/validate-migration-report.py b/plugins/aws-startup-advisor/scripts/validate-migration-report.py
index ef870e2b7..157edd768 100644
--- a/plugins/aws-startup-advisor/scripts/validate-migration-report.py
+++ b/plugins/aws-startup-advisor/scripts/validate-migration-report.py
@@ -1684,6 +1684,124 @@ def _word_shingles(text: str, size: int = 4) -> set[str]:
     return {" ".join(words[i : i + size]) for i in range(len(words) - size + 1)}
 
 
+def _phrase_rendered(phrase: str, rendered_text: str, max_width: int = 4) -> bool:
+    """True when `rendered_text` shares a word phrase with the artifact `phrase`.
+
+    The shingle width is the phrase's own token count, capped at `max_width`:
+    a one-to-three-word condition such as "Confirm capacity" is a single
+    shingle, and the rendered text must be cut at that same width or the two
+    sets can never intersect (a fixed four-word cut only ever matched
+    conditions of four or more words). An empty phrase has nothing to render.
+    """
+    words = re.findall(r"[a-z0-9]+", _plain_text(phrase))
+    if not words:
+        return True
+    width = min(len(words), max_width)
+    return bool(_word_shingles(" ".join(words), width) & _word_shingles(rendered_text, width))
+
+
+class _RenderedFragmentParser(HTMLParser):
+    """Flatten a fragment into what the browser would show, in document order.
+
+    Produces `entries` — `("text", run)` for prose outside a list item and
+    `("li", item)` for each list item, both decoded, lower-cased, whitespace-
+    collapsed and dash-folded like `_plain_text` — plus `class_tokens`, the set
+    of class attribute tokens on rendered start tags. Inert subtrees
+    (`<script>`, `<style>`, `<template>`) and comments are skipped entirely, so
+    a heading, list item or class that exists only there is not counted as
+    rendered. Inline tags do not split a run ("What <em>would</em> flip this"
+    stays one phrase); every other tag closes the current run.
+    """
+
+    _INLINE_TAGS = _DecodedTextRunParser._INLINE_TAGS
+    _INERT_TAGS = _DecodedTextRunParser._INERT_TAGS
+
+    def __init__(self) -> None:
+        super().__init__(convert_charrefs=True)
+        self.entries: list[tuple[str, str]] = []
+        self.class_tokens: set[str] = set()
+        self._inert_depth = 0
+        self._li_depth = 0
+        self._buf: list[str] = []
+
+    def _flush(self) -> None:
+        text = _plain_text(" ".join(self._buf))
+        self._buf = []
+        if text:
+            self.entries.append(("li" if self._li_depth else "text", text))
+
+    def _record_classes(self, attrs: list[tuple[str, str | None]]) -> None:
+        for name, value in attrs:
+            if name == "class" and value:
+                self.class_tokens.update(value.split())
+
+    def handle_starttag(self, tag: str, attrs: list[tuple[str, str | None]]) -> None:
+        if tag in self._INERT_TAGS:
+            self._inert_depth += 1
+            return
+        if self._inert_depth > 0:
+            return
+        self._record_classes(attrs)
+        if tag not in self._INLINE_TAGS:
+            self._flush()
+        if tag == "li":
+            self._li_depth += 1
+
+    def handle_startendtag(self, tag: str, attrs: list[tuple[str, str | None]]) -> None:
+        if tag in self._INERT_TAGS or self._inert_depth > 0:
+            return
+        self._record_classes(attrs)
+        if tag not in self._INLINE_TAGS:
+            self._flush()
+
+    def handle_endtag(self, tag: str) -> None:
+        if tag in self._INERT_TAGS:
+            if self._inert_depth > 0:
+                self._inert_depth -= 1
+            return
+        if self._inert_depth > 0:
+            return
+        if tag not in self._INLINE_TAGS:
+            self._flush()
+        if tag == "li" and self._li_depth > 0:
+            self._li_depth -= 1
+
+    def handle_data(self, data: str) -> None:
+        if self._inert_depth == 0:
+            self._buf.append(data)
+
+    def close(self) -> None:
+        super().close()
+        self._flush()
+
+
+def _rendered_fragment(fragment: str) -> _RenderedFragmentParser:
+    parser = _RenderedFragmentParser()
+    parser.feed(fragment)
+    parser.close()
+    return parser
+
+
+def _rendered_list_after_heading(
+    entries: list[tuple[str, str]], heading_phrase: str
+) -> list[str] | None:
+    """Items of the list that follows the first rendered run containing `heading_phrase`.
+
+    Returns None when no rendered run carries the heading, and an empty list
+    when the heading is present but no list item follows it before the next
+    prose run — the "heading only, empty <ul>" shape.
+    """
+    for index, (kind, text) in enumerate(entries):
+        if kind == "text" and heading_phrase in text:
+            items: list[str] = []
+            for next_kind, next_text in entries[index + 1 :]:
+                if next_kind != "li":
+                    break
+                items.append(next_text)
+            return items
+    return None
+
+
 def _iter_aws_services(node: object):
     if isinstance(node, dict):
         service = node.get("aws_service")
@@ -1764,27 +1882,47 @@ def _validate_decision_core_render(
     errors: list[str] = []
     summary = _section_html(html, "decision-summary") or ""
     summary_text = _plain_text(summary)
+    # Rendered view of the summary: class tokens and list items are read from
+    # elements the browser shows, so markup that exists only inside a
+    # <template> (or a comment) cannot satisfy a check.
+    rendered = _rendered_fragment(summary)
     recommendation = (estimation_infra or {}).get("recommendation") or {}
 
     if recommendation:
-        if not re.search(r"\bmetric-hero\b", summary, re.IGNORECASE):
+        if "metric-hero" not in rendered.class_tokens:
             errors.append(
                 "recommendation block exists but decision-summary has no hero metric "
                 '(render the AWS run rate and migration shape with class="metric-hero")'
             )
         outcome = recommendation.get("outcome") or recommendation.get("outcome_label")
-        if outcome and not re.search(r"\bverdict-headline\b", summary, re.IGNORECASE):
+        if outcome and "verdict-headline" not in rendered.class_tokens:
             errors.append(
                 "recommendation.outcome exists but decision-summary has no "
                 'verdict-headline (render outcome_label as <p class="verdict-headline">)'
             )
 
     flips = recommendation.get("would_flip_if")
-    if isinstance(flips, list) and flips and "what would flip" not in summary_text:
-        errors.append(
-            "recommendation.would_flip_if is non-empty but decision-summary has no "
-            '"What would flip this" list'
-        )
+    if isinstance(flips, list) and flips:
+        items = _rendered_list_after_heading(rendered.entries, "what would flip")
+        if items is None:
+            errors.append(
+                "recommendation.would_flip_if is non-empty but decision-summary has no "
+                '"What would flip this" list'
+            )
+        else:
+            # The heading alone is not the content: every artifact flip condition
+            # must appear as a rendered item of that list.
+            missing = [
+                str(flip)
+                for flip in flips
+                if not any(_phrase_rendered(str(flip), item) for item in items)
+            ]
+            if missing:
+                errors.append(
+                    f'"What would flip this" list renders {len(flips) - len(missing)} of '
+                    f"{len(flips)} recommendation.would_flip_if entries — missing: "
+                    + "; ".join(f'"{flip}"' for flip in missing)
+                )
 
     tracks = recommendation.get("track_outcomes")
     if isinstance(tracks, list) and tracks and "by track" not in summary_text:
@@ -1799,10 +1937,8 @@ def _validate_decision_core_render(
         and isinstance(conditions, list)
         and conditions
     ):
-        summary_shingles = _word_shingles(summary_text)
         for condition in conditions:
-            shingles = _word_shingles(_plain_text(str(condition)))
-            if shingles and not (shingles & summary_shingles):
+            if not _phrase_rendered(str(condition), summary_text):
                 errors.append(
                     "recommendation.conditions is non-empty but decision-summary does "
                     "not render that condition as a checklist (a shared phrase from the "

From 346a8a257332ea78b8bf21ccfe8e68ea30e26ee0 Mon Sep 17 00:00:00 2001
From: Logan Kleier <lkleier@amazon.com>
Date: Fri, 2 Oct 2026 10:47:57 -0700
Subject: [PATCH 04/10] =?UTF-8?q?fix(aws-startup-advisor):=20validate-hero?=
 =?UTF-8?q?ku-migration-report=20=E2=80=94=20normalize=20flip=20heading=20?=
 =?UTF-8?q?text,=20require=20populated=20list?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The would_flip_if check stripped tags with a regex and looked for the literal
"what would flip": a heading written as "What\nwould\nflip this",
"What&nbsp;would&nbsp;flip this" or "What <em>would</em> flip this" was
rejected, and the heading over an empty <ul> was accepted.

Port the shared validator's rendered-fragment parser: decoded, whitespace-
collapsed visible text with inert subtrees and comments dropped and inline
tags kept as one phrase. Match the heading on that text, then require every
recommendation.would_flip_if entry to render as an item of the list that
follows it. generate-report.md now states the populated-list rule.

Tests: the four equivalent heading spellings pass; comment-only and
template-only headings fail; empty and partial lists fail; complete list passes.
---
 .../phases/generate/generate-report.md        |   6 +-
 .../test_validate_heroku_migration_report.py  |  64 +++++++++
 .../validate-heroku-migration-report.py       | 133 +++++++++++++++++-
 3 files changed, 199 insertions(+), 4 deletions(-)

diff --git a/plugins/aws-startup-advisor/skills/heroku-to-aws/references/phases/generate/generate-report.md b/plugins/aws-startup-advisor/skills/heroku-to-aws/references/phases/generate/generate-report.md
index ba78471ef..ffe959357 100644
--- a/plugins/aws-startup-advisor/skills/heroku-to-aws/references/phases/generate/generate-report.md
+++ b/plugins/aws-startup-advisor/skills/heroku-to-aws/references/phases/generate/generate-report.md
@@ -271,7 +271,9 @@ python3 "<SKILL_BASE>/scripts/validate-heroku-migration-report.py" \
 
 `REPORT_OK` means the validator's decision-core checks passed. It is not a substitute for the content
 rules in this file: when `recommendation.would_flip_if` is non-empty the
-summary must include "What would flip this", and when two or more scenarios
+summary must include a "What would flip this" list whose items render every
+entry (the heading over an empty or partial list fails; content inside
+`<template>` or comments does not count), and when two or more scenarios
 exist the what-if table must include Region, HA, Compute, Arch, and Complexity.
 A report written only to satisfy the section-ID list will fail.
 
@@ -283,7 +285,7 @@ re-authors the report under this shell-less worker. On `REPORT_OK` the finish st
 hand-edit of the report from those errors + a direct validator re-run and re-stamp (or a maintainer
 re-running Generate for a clean rebuild).
 The validator enforces the required sections, the `draft for review` footer, the typography-first
-verdict rules, "What would flip this" when `would_flip_if` is present, the what-if
+verdict rules, the populated "What would flip this" list when `would_flip_if` is present, the what-if
 column set when two or more scenarios exist, non-empty `cost-optimization`, and the
 a11y subset the report emits (`<th scope>`, `<figure>` labels).
 
diff --git a/plugins/aws-startup-advisor/skills/heroku-to-aws/scripts/test_validate_heroku_migration_report.py b/plugins/aws-startup-advisor/skills/heroku-to-aws/scripts/test_validate_heroku_migration_report.py
index 5ab8154aa..44652259c 100644
--- a/plugins/aws-startup-advisor/skills/heroku-to-aws/scripts/test_validate_heroku_migration_report.py
+++ b/plugins/aws-startup-advisor/skills/heroku-to-aws/scripts/test_validate_heroku_migration_report.py
@@ -145,6 +145,70 @@ def test_would_flip_required_when_artifact_has_it() -> None:
     assert present == 0, ok
 
 
+VERDICT = '<p class="verdict-headline">Go, with conditions</p>'
+FLIPS = ["A published rate above the Heroku bill.", "Dyno count doubles before cutover."]
+FLIP_ITEMS = "".join(f"<li>{flip}</li>" for flip in FLIPS)
+
+
+def _run_with_flips(html: str) -> tuple[int, str]:
+    with tempfile.TemporaryDirectory() as tmp:
+        d = Path(tmp)
+        (d / "estimation-infra.json").write_text(
+            json.dumps(
+                {"recommendation": {"outcome": "go_conditional", "would_flip_if": FLIPS}}
+            ),
+            encoding="utf-8",
+        )
+        return run(html, migration_dir=d)
+
+
+def test_would_flip_heading_accepts_equivalent_visible_spellings() -> None:
+    # Line breaks, &nbsp; entities and inline markup inside the heading all read
+    # as "What would flip this" to the reader and must match.
+    for heading in (
+        "<h3>What would flip this</h3>",
+        "<h3>What\nwould\nflip this</h3>",
+        "<h3>What&nbsp;would&nbsp;flip this</h3>",
+        "<h3>What <em>would</em> flip this</h3>",
+    ):
+        code, out = _run_with_flips(GOOD.replace(VERDICT, VERDICT + heading + f"<ul>{FLIP_ITEMS}</ul>"))
+        assert code == 0, (heading, out)
+
+
+def test_would_flip_heading_in_comment_or_template_fails() -> None:
+    for inert in (
+        "<!-- What would flip this -->",
+        "<template><h3>What would flip this</h3></template>",
+    ):
+        code, out = _run_with_flips(GOOD.replace(VERDICT, VERDICT + inert + f"<ul>{FLIP_ITEMS}</ul>"))
+        assert code == 1, (inert, out)
+        assert "would_flip" in out
+
+
+def test_would_flip_empty_list_fails() -> None:
+    code, out = _run_with_flips(
+        GOOD.replace(VERDICT, VERDICT + "<h3>What would flip this</h3><ul></ul>")
+    )
+    assert code == 1, out
+    assert "0 of 2" in out, out
+
+
+def test_would_flip_partial_list_fails() -> None:
+    code, out = _run_with_flips(
+        GOOD.replace(VERDICT, VERDICT + f"<h3>What would flip this</h3><ul><li>{FLIPS[0]}</li></ul>")
+    )
+    assert code == 1, out
+    assert "1 of 2" in out and "Dyno count" in out, out
+
+
+def test_would_flip_complete_list_passes() -> None:
+    code, out = _run_with_flips(
+        GOOD.replace(VERDICT, VERDICT + f"<h3>What would flip this</h3><ul>{FLIP_ITEMS}</ul>")
+    )
+    assert code == 0, out
+    assert "REPORT_OK" in out
+
+
 def test_what_if_columns_required_when_section_present() -> None:
     thin = GOOD.replace(
         '<section id="next-steps">',
diff --git a/plugins/aws-startup-advisor/skills/heroku-to-aws/scripts/validate-heroku-migration-report.py b/plugins/aws-startup-advisor/skills/heroku-to-aws/scripts/validate-heroku-migration-report.py
index f56145e45..c42f0bd91 100644
--- a/plugins/aws-startup-advisor/skills/heroku-to-aws/scripts/validate-heroku-migration-report.py
+++ b/plugins/aws-startup-advisor/skills/heroku-to-aws/scripts/validate-heroku-migration-report.py
@@ -802,6 +802,119 @@ def _class_tokens(html_fragment: str) -> set[str]:
     return tokens
 
 
+def _normalize_phrase(text: str) -> str:
+    """Lower-cased, whitespace-collapsed, dash-folded rendered text, so a heading
+    written as `What&nbsp;would\nflip this` compares equal to the plain spelling."""
+    text = text.replace("\u2014", "-").replace("\u2013", "-")
+    return re.sub(r"\s+", " ", text).strip().lower()
+
+
+def _word_shingles(text: str, size: int) -> set[str]:
+    words = re.findall(r"[a-z0-9]+", text.lower())
+    if not words:
+        return set()
+    if len(words) <= size:
+        return {" ".join(words)}
+    return {" ".join(words[i : i + size]) for i in range(len(words) - size + 1)}
+
+
+def _phrase_rendered(phrase: str, rendered_text: str, max_width: int = 4) -> bool:
+    """Ported from validate-migration-report.py — True when `rendered_text`
+    shares a word phrase with the artifact `phrase`, cut at the phrase's own
+    token width (capped at four) so one-to-three-word entries can match."""
+    words = re.findall(r"[a-z0-9]+", _normalize_phrase(phrase))
+    if not words:
+        return True
+    width = min(len(words), max_width)
+    return bool(_word_shingles(" ".join(words), width) & _word_shingles(rendered_text, width))
+
+
+class _RenderedFragmentParser(HTMLParser):
+    """Ported from validate-migration-report.py — flatten a fragment into what
+    the browser shows, in document order: `("text", run)` for prose outside a
+    list item and `("li", item)` per list item, each decoded and normalized via
+    _normalize_phrase. Inert subtrees and comments are skipped (same rule as
+    _DecodedTextParser / _TagAttrCollector), and inline tags do not split a run,
+    so `What <em>would</em> flip this` is one phrase."""
+
+    _INLINE_TAGS = _DecodedTextParser._INLINE_TAGS
+    _INERT_TAGS = _DecodedTextParser._INERT_TAGS
+
+    def __init__(self) -> None:
+        super().__init__(convert_charrefs=True)
+        self.entries: list[tuple[str, str]] = []
+        self._inert_depth = 0
+        self._li_depth = 0
+        self._buf: list[str] = []
+
+    def _flush(self) -> None:
+        text = _normalize_phrase(" ".join(self._buf))
+        self._buf = []
+        if text:
+            self.entries.append(("li" if self._li_depth else "text", text))
+
+    def handle_starttag(self, tag: str, attrs: list[tuple[str, str | None]]) -> None:
+        if tag in self._INERT_TAGS:
+            self._inert_depth += 1
+            return
+        if self._inert_depth > 0:
+            return
+        if tag not in self._INLINE_TAGS:
+            self._flush()
+        if tag == "li":
+            self._li_depth += 1
+
+    def handle_startendtag(self, tag: str, attrs: list[tuple[str, str | None]]) -> None:
+        if tag in self._INERT_TAGS or self._inert_depth > 0:
+            return
+        if tag not in self._INLINE_TAGS:
+            self._flush()
+
+    def handle_endtag(self, tag: str) -> None:
+        if tag in self._INERT_TAGS:
+            if self._inert_depth > 0:
+                self._inert_depth -= 1
+            return
+        if self._inert_depth > 0:
+            return
+        if tag not in self._INLINE_TAGS:
+            self._flush()
+        if tag == "li" and self._li_depth > 0:
+            self._li_depth -= 1
+
+    def handle_data(self, data: str) -> None:
+        if self._inert_depth == 0:
+            self._buf.append(data)
+
+    def close(self) -> None:
+        super().close()
+        self._flush()
+
+
+def _rendered_entries(fragment: str) -> list[tuple[str, str]]:
+    parser = _RenderedFragmentParser()
+    parser.feed(fragment)
+    parser.close()
+    return parser.entries
+
+
+def _rendered_list_after_heading(
+    entries: list[tuple[str, str]], heading_phrase: str
+) -> list[str] | None:
+    """Items of the list following the first rendered run that contains
+    `heading_phrase`; None when no rendered run carries the heading, [] when the
+    heading is present but no list item follows it (heading-only / empty <ul>)."""
+    for index, (kind, text) in enumerate(entries):
+        if kind == "text" and heading_phrase in text:
+            items: list[str] = []
+            for next_kind, next_text in entries[index + 1 :]:
+                if next_kind != "li":
+                    break
+                items.append(next_text)
+            return items
+    return None
+
+
 def _validate_verdict(html: str, migration_dir: Path | None) -> list[str]:
     """Typography-first verdict rules (skill: verdict is the section thesis and
     must never be a colored-pill row)."""
@@ -842,12 +955,28 @@ def _validate_verdict(html: str, migration_dir: Path | None) -> list[str]:
             '(render outcome_label as <p class="verdict-headline">…</p>)'
         )
     if flips:
-        visible = re.sub(r"<[^>]+>", " ", summary).lower()
-        if "what would flip" not in visible:
+        # Match the heading on decoded, whitespace-normalized visible text (entities,
+        # line breaks and inline markup are all one phrase to the reader; comments and
+        # <template> content are not rendered), then require every artifact flip
+        # condition to appear as an item of the list that follows it.
+        items = _rendered_list_after_heading(_rendered_entries(summary), "what would flip")
+        if items is None:
             errors.append(
                 "estimation-infra.json declares recommendation.would_flip_if but "
                 'decision-summary has no "What would flip this" list'
             )
+        else:
+            missing = [
+                str(flip)
+                for flip in flips
+                if not any(_phrase_rendered(str(flip), item) for item in items)
+            ]
+            if missing:
+                errors.append(
+                    f'"What would flip this" list renders {len(flips) - len(missing)} of '
+                    f"{len(flips)} recommendation.would_flip_if entries — missing: "
+                    + "; ".join(f'"{flip}"' for flip in missing)
+                )
     return errors
 
 

From d42c1acb72e00f791aeae7359d077f6929429fb9 Mon Sep 17 00:00:00 2001
From: Logan Kleier <lkleier@amazon.com>
Date: Fri, 2 Oct 2026 10:48:12 -0700
Subject: [PATCH 05/10] docs(aws-startup-advisor): pass --aws-design on the
 Azure report gate and --migration-dir on the Decision path

The validator reads only the artifacts named on its command line, so two
documented callers never armed the checks this PR added:

- azure-to-aws generate-artifacts-report.md Step 5 omitted --aws-design, so
  the architecture-section and specialist-callout checks ran with
  aws_design=None. A report missing both returned REPORT_OK on the documented
  command and REPORT_FAIL once --aws-design was added. The AI-only path still
  omits it (no aws-design.json exists there).
- gcp-to-aws estimate.md choice A and the shared decision-core recipe (gcp and
  azure copies) omitted --migration-dir, so scenarios/index.json was never
  read and a two-scenario Decision report with Scenario/Balanced-only headers
  passed. The flag is now in the recipe and documented as required on real
  runs in shared/validate-migration-report.md; the reference fixture remains
  the only case that omits it.

Check 26 in shared/validate-migration-report.md now describes the populated
flip list, token-width condition matching and rendered-only markup rules.
---
 .../phases/generate/generate-artifacts-report.md         | 5 +++--
 .../references/shared/report-decision-core.md            | 2 +-
 .../gcp-to-aws/references/phases/estimate/estimate.md    | 7 +++++--
 .../gcp-to-aws/references/shared/report-decision-core.md | 2 +-
 .../references/shared/validate-migration-report.md       | 9 +++++----
 5 files changed, 15 insertions(+), 10 deletions(-)

diff --git a/plugins/aws-startup-advisor/skills/azure-to-aws/references/phases/generate/generate-artifacts-report.md b/plugins/aws-startup-advisor/skills/azure-to-aws/references/phases/generate/generate-artifacts-report.md
index c302d9f17..5ef2a500e 100644
--- a/plugins/aws-startup-advisor/skills/azure-to-aws/references/phases/generate/generate-artifacts-report.md
+++ b/plugins/aws-startup-advisor/skills/azure-to-aws/references/phases/generate/generate-artifacts-report.md
@@ -202,12 +202,13 @@ python3 "$PLUGIN_ROOT/scripts/validate-migration-report.py" \
   "$MIGRATION_DIR/migration-report.html" \
   --estimation-infra "$MIGRATION_DIR/estimation-infra.json" \
   --estimation-ai "$MIGRATION_DIR/estimation-ai.json" \
+  --aws-design "$MIGRATION_DIR/aws-design.json" \
   --migration-dir "$MIGRATION_DIR"
 ```
 
-Pass `--estimation-infra` / `--estimation-ai` only when those files exist in `$MIGRATION_DIR`.
+Pass `--estimation-infra` / `--estimation-ai` / `--aws-design` only when those files exist in `$MIGRATION_DIR` (absolute paths — cwd must not be load-bearing). The validator does not read `aws-design.json` from `--migration-dir`; the architecture-section and specialist-callout checks fire only when `--aws-design` is passed, so omitting it on an infra run leaves those omissions undetected.
 
-**AI-only path:** when there is no infra track (no `estimation-infra.json`), add `--mode ai_only` so the validator requires the AI-only section set (`decision-summary`, `exec-assumptions`, `exec-risks`, `appendix-ai`, `appendix-artifacts`, `appendix-config`, `appendix-glossary`) instead of the infra sections. Pass `--estimation-ai "$MIGRATION_DIR/estimation-ai.json"`.
+**AI-only path:** when there is no infra track (no `estimation-infra.json`), add `--mode ai_only` so the validator requires the AI-only section set (`decision-summary`, `exec-assumptions`, `exec-risks`, `appendix-ai`, `appendix-artifacts`, `appendix-config`, `appendix-glossary`) instead of the infra sections. Pass `--estimation-ai "$MIGRATION_DIR/estimation-ai.json"`; there is no `aws-design.json` on this path, so `--aws-design` is omitted.
 
 Branch on the exit code, exactly as gcp-to-aws's `generate.md` does:
 
diff --git a/plugins/aws-startup-advisor/skills/azure-to-aws/references/shared/report-decision-core.md b/plugins/aws-startup-advisor/skills/azure-to-aws/references/shared/report-decision-core.md
index 5ab7feee5..353899866 100644
--- a/plugins/aws-startup-advisor/skills/azure-to-aws/references/shared/report-decision-core.md
+++ b/plugins/aws-startup-advisor/skills/azure-to-aws/references/shared/report-decision-core.md
@@ -20,7 +20,7 @@ output lives in the JSON artifacts.
 - **HTML shell:** same `<head>` (charset, viewport, inline CSS) and CSS specification as the full report (see `generate-artifacts-report.md` Step 3), title "Azure to AWS Migration Assessment — Decision Report". Body contains ONLY the `executive-summary` div with the exec sections and TOC (TOC links only to sections present; `nav.toc` carries `id="toc"` and every section `<h2>` ends with the `↑ contents` toplink per the nav-aids CSS spec). Opening order follows the hero-is-the-thesis rule: `decision-summary` first, TOC after it. Required section IDs in decision mode: `decision-summary`, `exec-assumptions`, `exec-services`, `exec-costs`, `exec-timeline`, `exec-risks` (+ conditional `exec-share`, `exec-tco`, `exec-architecture`, `exec-security-teaser`, `exec-optimization`, `what-if-scenarios` per their triggers).
 - **CTA footer (required, after the last section):** `<section id="decision-cta">` — "**Ready to execute?** Say \"generate the Terraform and migration scripts\" and I'll produce the full execution pack (Terraform, migration scripts, rollback runbook, fill-in checklist) from this same analysis." Plus one line: "This decision report was generated without execution artifacts; the full migration report replaces it if you proceed."
 - **`DECISION.md` (required twin):** same content as the HTML, as plain Markdown (Slack/GitHub-friendly): verdict headline, cost table, migrate-if/stay-if lists, timeline band, top risks, assumptions, CTA line. No HTML tags.
-- **Validation:** run `scripts/validate-migration-report.py $MIGRATION_DIR/decision-report.html --mode decision [--estimation-infra ...] [--estimation-ai ...] [--aws-design ...]` and fix failures before presenting. Pass the estimation (and design) files when they exist so the Cost Optimization gate can fire.
+- **Validation:** run `scripts/validate-migration-report.py $MIGRATION_DIR/decision-report.html --mode decision --migration-dir "$MIGRATION_DIR" [--estimation-infra ...] [--estimation-ai ...] [--aws-design ...]` and fix failures before presenting. Pass the estimation (and design) files when they exist so the Cost Optimization gate can fire. `--migration-dir` is required on a real run — the validator reads `scenarios/index.json` from it, and the Section 3b what-if column check only fires when that index lists two or more scenarios; omit it only when validating a checked-in fixture.
 - **Cost-figure anchor (machine-checkable, decision mode too):** the
   `data-cost-key="aws_monthly_balanced"` anchor required by
   `generate-artifacts-report.md` Step 2 applies here unchanged — wrap the Balanced dollar
diff --git a/plugins/aws-startup-advisor/skills/gcp-to-aws/references/phases/estimate/estimate.md b/plugins/aws-startup-advisor/skills/gcp-to-aws/references/phases/estimate/estimate.md
index ea0e11a25..616d62259 100644
--- a/plugins/aws-startup-advisor/skills/gcp-to-aws/references/phases/estimate/estimate.md
+++ b/plugins/aws-startup-advisor/skills/gcp-to-aws/references/phases/estimate/estimate.md
@@ -178,11 +178,14 @@ commit." Suggest at most one.
      `$MIGRATION_DIR/decision-report.html` and `$MIGRATION_DIR/DECISION.md`
      per that file's decision-mode rules (no appendices, no Terraform, CTA
      footer). Validate with
-     `python3 "$PLUGIN_ROOT/scripts/validate-migration-report.py" "$MIGRATION_DIR/decision-report.html" --mode decision`
+     `python3 "$PLUGIN_ROOT/scripts/validate-migration-report.py" "$MIGRATION_DIR/decision-report.html" --mode decision --migration-dir "$MIGRATION_DIR"`
      and pass `--estimation-infra` / `--estimation-ai` / `--aws-design` when
      those files exist so the Cost Optimization gate can fire
      (absolute paths — cwd must not be load-bearing) and fix failures before
-     presenting.
+     presenting. `--migration-dir` is required on a real run: it is how the
+     validator finds `scenarios/index.json`, so the what-if column check
+     (Region, HA, Compute, Arch, the three tiers, Complexity) fires when
+     Workshop produced two or more scenarios before the user chose A.
   2. Set `run_mode: "decide"` and `current_phase: "complete"` in
      `.phase-status.json` (`phases.generate` **stays** `"pending"` — this
      combination means "decision complete, execution available on request";
diff --git a/plugins/aws-startup-advisor/skills/gcp-to-aws/references/shared/report-decision-core.md b/plugins/aws-startup-advisor/skills/gcp-to-aws/references/shared/report-decision-core.md
index 9feb3793c..58e0adbcd 100644
--- a/plugins/aws-startup-advisor/skills/gcp-to-aws/references/shared/report-decision-core.md
+++ b/plugins/aws-startup-advisor/skills/gcp-to-aws/references/shared/report-decision-core.md
@@ -20,7 +20,7 @@ output lives in the JSON artifacts.
 - **HTML shell:** same `<head>` (charset, viewport, inline CSS) and CSS specification as the full report (see `generate-artifacts-report.md` Step 3), title "GCP to AWS Migration Assessment — Decision Report". Body contains ONLY the `executive-summary` div with the exec sections and TOC (TOC links only to sections present; `nav.toc` carries `id="toc"` and every section `<h2>` ends with the `↑ contents` toplink per the nav-aids CSS spec). Opening order follows the hero-is-the-thesis rule: `decision-summary` first, TOC after it. Required section IDs in decision mode: `decision-summary`, `exec-assumptions`, `exec-services`, `exec-costs`, `exec-timeline`, `exec-risks` (+ conditional `exec-share`, `exec-tco`, `exec-architecture`, `exec-security-teaser`, `exec-optimization`, `what-if-scenarios` per their triggers).
 - **CTA footer (required, after the last section):** `<section id="decision-cta">` — "**Ready to execute?** Say \"generate the Terraform and migration scripts\" and I'll produce the full execution pack (Terraform, migration scripts, rollback runbook, fill-in checklist) from this same analysis." Plus one line: "This decision report was generated without execution artifacts; the full migration report replaces it if you proceed."
 - **`DECISION.md` (required twin):** same content as the HTML, as plain Markdown (Slack/GitHub-friendly): verdict headline, cost table, migrate-if/stay-if lists, timeline band, top risks, assumptions, CTA line. No HTML tags.
-- **Validation:** run `scripts/validate-migration-report.py $MIGRATION_DIR/decision-report.html --mode decision [--estimation-infra ...] [--estimation-ai ...] [--aws-design ...]` and fix failures before presenting. Pass the estimation (and design) files when they exist so the Cost Optimization gate can fire.
+- **Validation:** run `scripts/validate-migration-report.py $MIGRATION_DIR/decision-report.html --mode decision --migration-dir "$MIGRATION_DIR" [--estimation-infra ...] [--estimation-ai ...] [--aws-design ...]` and fix failures before presenting. Pass the estimation (and design) files when they exist so the Cost Optimization gate can fire. `--migration-dir` is required on a real run — the validator reads `scenarios/index.json` from it, and the Section 3b what-if column check only fires when that index lists two or more scenarios; omit it only when validating a checked-in fixture.
 - All content rules below apply unchanged: baseline-quality badge + not-comparable rule, cost labeling ("Est."), readability (no artifact filenames in exec sections, no "Section N" headings, ordered action lists), Activate wording rules.
 
 ---
diff --git a/plugins/aws-startup-advisor/skills/gcp-to-aws/references/shared/validate-migration-report.md b/plugins/aws-startup-advisor/skills/gcp-to-aws/references/shared/validate-migration-report.md
index a2c8b8443..b552dde6c 100644
--- a/plugins/aws-startup-advisor/skills/gcp-to-aws/references/shared/validate-migration-report.md
+++ b/plugins/aws-startup-advisor/skills/gcp-to-aws/references/shared/validate-migration-report.md
@@ -23,12 +23,13 @@ python3 "$PLUGIN_ROOT/scripts/validate-migration-report.py" \
   "$MIGRATION_DIR/migration-report.html" \
   --estimation-infra "$MIGRATION_DIR/estimation-infra.json" \
   --estimation-ai "$MIGRATION_DIR/estimation-ai.json" \
-  --aws-design "$MIGRATION_DIR/aws-design.json"
+  --aws-design "$MIGRATION_DIR/aws-design.json" \
+  --migration-dir "$MIGRATION_DIR"
 ```
 
-Pass `--estimation-infra` / `--estimation-ai` / `--aws-design` only when those files exist. Flags:
+Pass `--estimation-infra` / `--estimation-ai` / `--aws-design` only when those files exist. The validator reads only the files named on the command line — it does not discover `aws-design.json` or the estimates from `--migration-dir` — so an omitted artifact flag silently disables the checks that depend on it. Flags:
 
-- `--migration-dir "$MIGRATION_DIR"` — enables **fixture-bleed detection** on real runs (the reference canary ID must not appear, and the report's migration ID must match the run folder). Omit it when validating the reference fixture itself.
+- `--migration-dir "$MIGRATION_DIR"` — **required on every real run** (full and `--mode decision` alike). It enables **fixture-bleed detection** (the reference canary ID must not appear, and the report's migration ID must match the run folder) and is where the validator reads `scenarios/index.json`: the what-if column check (`report-decision-core.md` Section 3b) only fires when that index lists two or more scenarios, so a Decision report validated without this flag is never checked for the Region / HA / Compute / Arch / tier / Complexity columns. Omit it only when validating the reference fixture by itself (it has no run folder).
 - `--no-require-toc` — skip the TOC requirement (for minimal test fixtures only).
 - `--no-readability` — skip the customer-facing readability checks (escape hatch; not for normal Generate runs).
 
@@ -101,7 +102,7 @@ decision reports.
 | 23 | Leadership brief                   | When an estimation artifact is passed, `exec-share` contains a static, copy-ready `share-card` without scripts or controls                                                                                                                                                                                                                                                                                                                                                                                                              |
 | 24 | Accessibility semantics            | Normal generated reports declare document language, contain exactly one `<h1>`, caption every table, scope table headers, and give every figure an image role, accessible name, and text alternative                                                                                                                                                                                                                                                                                                                                    |
 | 25 | Cost Optimization section          | If `optimization_opportunities[]` is non-empty: exactly one `exec-optimization` (TOC-linked) comparing Balanced on-demand vs Savings Plans / RI, plus (full mode only) a standalone `appendix-optimization` table with Optimization / Target / Monthly savings / Commitment / Effort columns. A table buried only in `appendix-costs` fails. Do not add SP/RI savings on top of Optimized. If RDS/Aurora/Fargate/Lambda is in `--aws-design` or opportunity targets, the section must include a Savings Plans or Reserved Instances row |
-| 26 | Decision-core render               | When `--estimation-infra` has a `recommendation`: hero metrics (`metric-hero`) and, when the fields exist, a `verdict-headline`, a "By track" line, a conditions checklist, and "What would flip this". When `--aws-design` has a deferred service: a specialist-engagement callout in `decision-summary`. Full mode with `clusters`: `<section id="exec-architecture">`. `exec-assumptions` follows `exec-risks`. `exec-risks` is a table. With ≥2 scenarios, the what-if table includes Region, HA, Compute, Arch, and Complexity |
+| 26 | Decision-core render               | When `--estimation-infra` has a `recommendation`: hero metrics (`metric-hero`) and, when the fields exist, a `verdict-headline`, a "By track" line, a conditions checklist (each condition shares a phrase with the rendered text, matched at the condition's own word count), and a "What would flip this" list whose items render every `would_flip_if[]` entry — the heading alone, or an empty/partial list, fails. Only rendered markup counts: class tokens, headings, and list items inside `<template>`/`<script>`/`<style>` or comments are ignored. When `--aws-design` has a deferred service: a specialist-engagement callout in `decision-summary`. Full mode with `clusters`: `<section id="exec-architecture">`. `exec-assumptions` follows `exec-risks`. `exec-risks` is a table. With `--migration-dir` and ≥2 scenarios, the what-if table includes Region, HA, Compute, Arch, the three tiers, and Complexity |
 
 Checks 10, 11, and 15 scan the `<body>` with `<style>` stripped, so CSS class names (e.g. `.rubric`) and selectors never trip them. The same readability scan rejects customer-facing "TCO" because modeled cloud charges do not include staffing or operating labor. Check 15 scopes to executive-flow sections only — appendices may carry artifact filenames and resource IDs by design. Disable checks 10, 11, and 15 with `--no-readability` only for non-customer fixtures. Check 14 is inert without `--migration-dir`, so validating the reference fixture (which legitimately contains the canary ID) never self-trips. Checks 16–17 apply whenever the corresponding sections/headings exist.
 

From e3d1bfeeb998545f1a7465ea52a307fea37754ee Mon Sep 17 00:00:00 2001
From: Logan Kleier <lkleier@amazon.com>
Date: Fri, 2 Oct 2026 11:12:23 -0700
Subject: [PATCH 06/10] =?UTF-8?q?fix(aws-startup-advisor):=20validate-migr?=
 =?UTF-8?q?ation-report=20=E2=80=94=20accept=20inline-label=20and=20lead-i?=
 =?UTF-8?q?n=20flip=20lists,=20scope=20conditions=20to=20the=20checklist?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The flip-list matcher only recognised a heading run followed directly by
<li>s. Two legitimate shapes failed closed: the heroku-decision-gate
fixtures' <li>What would flip this: …</li> (reported as 'no list') and a
lead-in <p> between the heading and the <ul> (reported as '0 of N
missing' although every item was rendered). The parser now tags h1-h6
runs as headings; the matcher prefers a heading, then prose, then an
inline-labelled item, skips lead-in prose until the first item, bounds the
search at the next heading, and treats the labelled item's remainder plus
its siblings as the list. Same change ported to the Heroku validator.

The conditional_go condition scan is scoped to rendered list items (the
spec renders conditions[] as a checklist, and the error already says so):
a one-word condition was satisfied by that word anywhere in the summary
prose and could never be reported as omitted.
---
 ...validate_migration_report_decision_core.py | 99 +++++++++++++++++++
 .../scripts/validate-migration-report.py      | 91 ++++++++++++-----
 .../test_validate_heroku_migration_report.py  | 78 +++++++++++++++
 .../validate-heroku-migration-report.py       | 69 +++++++++----
 4 files changed, 297 insertions(+), 40 deletions(-)

diff --git a/plugins/aws-startup-advisor/scripts/test_validate_migration_report_decision_core.py b/plugins/aws-startup-advisor/scripts/test_validate_migration_report_decision_core.py
index 44b9f68b9..11a1811a4 100644
--- a/plugins/aws-startup-advisor/scripts/test_validate_migration_report_decision_core.py
+++ b/plugins/aws-startup-advisor/scripts/test_validate_migration_report_decision_core.py
@@ -129,6 +129,68 @@ def test_would_flip_complete_list_passes_with_inline_markup() -> None:
     assert _flip_errors(html) == []
 
 
+LEAD_IN = '      <p class="muted">Any of these would change the verdict:</p>\n'
+
+
+def test_would_flip_lead_in_paragraph_before_list_passes() -> None:
+    # A one-sentence lead-in between the heading and the <ul> is legitimate
+    # output; the items below it are rendered and must be found (regression for
+    # the matcher stopping at the first non-item run and reporting "0 of 2").
+    html = _reference_html().replace(
+        "      <h3>What would flip this</h3>\n", "      <h3>What would flip this</h3>\n" + LEAD_IN
+    )
+    assert html != _reference_html()
+    assert _flip_errors(html) == []
+
+
+def test_would_flip_lead_in_paragraph_with_empty_list_fails() -> None:
+    html = _reference_html().replace(
+        FLIP_BLOCK,
+        "      <h3>What would flip this</h3>\n" + LEAD_IN + '      <ul class="compact"></ul>',
+    )
+    assert html != _reference_html()
+    errors = _flip_errors(html)
+    assert errors and "0 of 2" in errors[0], errors
+
+
+def test_would_flip_another_heading_before_any_item_is_empty_list() -> None:
+    # Prose is skipped, but the search is bounded by the next heading: a flip
+    # heading with no items before "Key decisions ahead" renders none of them.
+    html = _reference_html().replace(
+        FLIP_BLOCK, "      <h3>What would flip this</h3>\n      <p>See below.</p>"
+    )
+    assert html != _reference_html()
+    errors = _flip_errors(html)
+    assert errors and "0 of 2" in errors[0], errors
+
+
+INLINE_LABEL_BLOCK = """      <ul class="compact">
+        <li>What would flip this: Single-AZ acceptable: AWS estimate drops further, strengthens go</li>
+        <li>BigQuery must cut over in the same window: defer for specialist evidence</li>
+      </ul>"""
+
+
+def test_would_flip_inline_label_item_passes() -> None:
+    # The specs only ask for a "short unordered list"; the Heroku decision
+    # fixtures render the label inside the first item with no separate heading.
+    # That item's remainder plus its siblings are the list.
+    html = _reference_html().replace(FLIP_BLOCK, INLINE_LABEL_BLOCK)
+    assert html != _reference_html()
+    assert _flip_errors(html) == []
+
+
+def test_would_flip_inline_label_partial_list_fails() -> None:
+    html = _reference_html().replace(
+        FLIP_BLOCK, INLINE_LABEL_BLOCK.replace(
+            "        <li>BigQuery must cut over in the same window: defer for specialist evidence</li>\n",
+            "",
+        )
+    )
+    assert html != _reference_html()
+    errors = _flip_errors(html)
+    assert errors and "1 of 2" in errors[0] and "BigQuery" in errors[0], errors
+
+
 def _with_condition(condition: str, *, rendered: bool) -> tuple[str, dict]:
     estimate = _reference_estimate()
     estimate["recommendation"]["conditions"] = [condition]
@@ -168,6 +230,43 @@ def test_omitted_long_condition_fails() -> None:
     assert errors, "omitted condition passed"
 
 
+def _without_confirm_in_checklist(html: str) -> str:
+    # Reword every list item of the reference summary that happens to contain
+    # "confirm", so the word survives only in prose.
+    html = html.replace("<li>Condition: confirm", "<li>Condition: verify")
+    html = html.replace("not confirmed", "not verified")
+    html = html.replace("<li>Confirm Bedrock", "<li>Verify Bedrock")
+    return html.replace(
+        '<p class="verdict-headline">Go, with conditions</p>',
+        '<p class="verdict-headline">Go, with conditions</p>\n'
+        "      <p>Confirm these before cutover.</p>",
+    )
+
+
+def test_one_word_condition_only_in_prose_fails() -> None:
+    # Conditions render as a checklist, so the scan is scoped to rendered list
+    # items. A one-word condition used to be satisfied by that word anywhere in
+    # the summary prose and could never be reported as omitted.
+    validator = _load()
+    html, estimate = _with_condition("Confirm", rendered=False)
+    html = _without_confirm_in_checklist(html)
+    rendered = validator._rendered_fragment(validator._section_html(html, "decision-summary"))
+    assert any("confirm" in text for kind, text in rendered.entries if kind != "li")
+    assert not any("confirm" in text for kind, text in rendered.entries if kind == "li")
+    errors = [e for e in validator.validate_report(html, estimate, None) if "condition" in e]
+    assert errors, "one-word condition rendered only in prose passed"
+
+
+def test_one_word_condition_in_checklist_passes() -> None:
+    validator = _load()
+    html, estimate = _with_condition("Confirm", rendered=False)
+    html = _without_confirm_in_checklist(html).replace(
+        "<li>Condition: verify CUD", "<li>Condition: Confirm CUD"
+    )
+    errors = [e for e in validator.validate_report(html, estimate, None) if "condition" in e]
+    assert errors == [], errors
+
+
 def test_verdict_headline_only_in_template_fails() -> None:
     validator = _load()
     html = _reference_html().replace(
diff --git a/plugins/aws-startup-advisor/scripts/validate-migration-report.py b/plugins/aws-startup-advisor/scripts/validate-migration-report.py
index 157edd768..a3f944f3c 100644
--- a/plugins/aws-startup-advisor/scripts/validate-migration-report.py
+++ b/plugins/aws-startup-advisor/scripts/validate-migration-report.py
@@ -1703,18 +1703,20 @@ def _phrase_rendered(phrase: str, rendered_text: str, max_width: int = 4) -> boo
 class _RenderedFragmentParser(HTMLParser):
     """Flatten a fragment into what the browser would show, in document order.
 
-    Produces `entries` — `("text", run)` for prose outside a list item and
-    `("li", item)` for each list item, both decoded, lower-cased, whitespace-
-    collapsed and dash-folded like `_plain_text` — plus `class_tokens`, the set
-    of class attribute tokens on rendered start tags. Inert subtrees
-    (`<script>`, `<style>`, `<template>`) and comments are skipped entirely, so
-    a heading, list item or class that exists only there is not counted as
-    rendered. Inline tags do not split a run ("What <em>would</em> flip this"
-    stays one phrase); every other tag closes the current run.
+    Produces `entries` — `("heading", run)` for an `<h1>`–`<h6>`, `("li", item)`
+    for each list item and `("text", run)` for any other prose, all decoded,
+    lower-cased, whitespace-collapsed and dash-folded like `_plain_text` — plus
+    `class_tokens`, the set of class attribute tokens on rendered start tags.
+    Inert subtrees (`<script>`, `<style>`, `<template>`) and comments are
+    skipped entirely, so a heading, list item or class that exists only there
+    is not counted as rendered. Inline tags do not split a run ("What
+    <em>would</em> flip this" stays one phrase); every other tag closes the
+    current run.
     """
 
     _INLINE_TAGS = _DecodedTextRunParser._INLINE_TAGS
     _INERT_TAGS = _DecodedTextRunParser._INERT_TAGS
+    _HEADING_TAGS = {"h1", "h2", "h3", "h4", "h5", "h6"}
 
     def __init__(self) -> None:
         super().__init__(convert_charrefs=True)
@@ -1722,13 +1724,21 @@ def __init__(self) -> None:
         self.class_tokens: set[str] = set()
         self._inert_depth = 0
         self._li_depth = 0
+        self._heading_depth = 0
         self._buf: list[str] = []
 
     def _flush(self) -> None:
         text = _plain_text(" ".join(self._buf))
         self._buf = []
-        if text:
-            self.entries.append(("li" if self._li_depth else "text", text))
+        if not text:
+            return
+        if self._li_depth:
+            kind = "li"
+        elif self._heading_depth:
+            kind = "heading"
+        else:
+            kind = "text"
+        self.entries.append((kind, text))
 
     def _record_classes(self, attrs: list[tuple[str, str | None]]) -> None:
         for name, value in attrs:
@@ -1746,6 +1756,8 @@ def handle_starttag(self, tag: str, attrs: list[tuple[str, str | None]]) -> None
             self._flush()
         if tag == "li":
             self._li_depth += 1
+        elif tag in self._HEADING_TAGS:
+            self._heading_depth += 1
 
     def handle_startendtag(self, tag: str, attrs: list[tuple[str, str | None]]) -> None:
         if tag in self._INERT_TAGS or self._inert_depth > 0:
@@ -1765,6 +1777,8 @@ def handle_endtag(self, tag: str) -> None:
             self._flush()
         if tag == "li" and self._li_depth > 0:
             self._li_depth -= 1
+        elif tag in self._HEADING_TAGS and self._heading_depth > 0:
+            self._heading_depth -= 1
 
     def handle_data(self, data: str) -> None:
         if self._inert_depth == 0:
@@ -1785,20 +1799,46 @@ def _rendered_fragment(fragment: str) -> _RenderedFragmentParser:
 def _rendered_list_after_heading(
     entries: list[tuple[str, str]], heading_phrase: str
 ) -> list[str] | None:
-    """Items of the list that follows the first rendered run containing `heading_phrase`.
-
-    Returns None when no rendered run carries the heading, and an empty list
-    when the heading is present but no list item follows it before the next
-    prose run — the "heading only, empty <ul>" shape.
+    """Items of the rendered list that `heading_phrase` introduces.
+
+    Two rendered shapes introduce the list, both legitimate under the report
+    specs ("short unordered list"):
+
+    - a heading (preferred) or prose run carrying the phrase, such as
+      `<h3>What would flip this</h3>`, then the list. Lead-in prose between the
+      heading and the first `<li>` is skipped; the items run ends at the first
+      non-item entry after it, and reaching another heading before any item
+      means the list is empty.
+    - a list item carrying the phrase as an inline label, such as
+      `<li>What would flip this: …</li>`. The remainder of that item plus its
+      following sibling items are the list.
+
+    Returns None when no rendered run carries the phrase, and an empty list when
+    the phrase is present but no item renders under it (heading only, empty
+    `<ul>`).
     """
-    for index, (kind, text) in enumerate(entries):
-        if kind == "text" and heading_phrase in text:
-            items: list[str] = []
-            for next_kind, next_text in entries[index + 1 :]:
-                if next_kind != "li":
+
+    def items_from(start: int) -> list[str]:
+        items: list[str] = []
+        for kind, text in entries[start:]:
+            if kind != "li":
+                break
+            items.append(text)
+        return items
+
+    for wanted in ("heading", "text", "li"):
+        for index, (kind, text) in enumerate(entries):
+            if kind != wanted or heading_phrase not in text:
+                continue
+            if kind == "li":
+                remainder = text.split(heading_phrase, 1)[1].lstrip(" :;,.-")
+                return ([remainder] if remainder else []) + items_from(index + 1)
+            for offset, (next_kind, _next_text) in enumerate(entries[index + 1 :], index + 1):
+                if next_kind == "li":
+                    return items_from(offset)
+                if next_kind == "heading":
                     break
-                items.append(next_text)
-            return items
+            return []
     return None
 
 
@@ -1937,8 +1977,13 @@ def _validate_decision_core_render(
         and isinstance(conditions, list)
         and conditions
     ):
+        # The spec renders conditions[] as a checklist, so match each condition
+        # against the rendered list items only. Scanning the whole summary let a
+        # one-word condition ("Confirm") be satisfied by that word anywhere in
+        # the verdict prose, so it could never be reported as omitted.
+        checklist = [text for kind, text in rendered.entries if kind == "li"]
         for condition in conditions:
-            if not _phrase_rendered(str(condition), summary_text):
+            if not any(_phrase_rendered(str(condition), item) for item in checklist):
                 errors.append(
                     "recommendation.conditions is non-empty but decision-summary does "
                     "not render that condition as a checklist (a shared phrase from the "
diff --git a/plugins/aws-startup-advisor/skills/heroku-to-aws/scripts/test_validate_heroku_migration_report.py b/plugins/aws-startup-advisor/skills/heroku-to-aws/scripts/test_validate_heroku_migration_report.py
index 44652259c..d97c77182 100644
--- a/plugins/aws-startup-advisor/skills/heroku-to-aws/scripts/test_validate_heroku_migration_report.py
+++ b/plugins/aws-startup-advisor/skills/heroku-to-aws/scripts/test_validate_heroku_migration_report.py
@@ -209,6 +209,84 @@ def test_would_flip_complete_list_passes() -> None:
     assert "REPORT_OK" in out
 
 
+def test_would_flip_lead_in_paragraph_before_list_passes() -> None:
+    # A one-sentence lead-in between the heading and the <ul> is legitimate
+    # output; the items below it are rendered and must be found (regression for
+    # the matcher stopping at the first non-item run and reporting "0 of N").
+    code, out = _run_with_flips(
+        GOOD.replace(
+            VERDICT,
+            VERDICT
+            + "<h3>What would flip this</h3>"
+            + '<p class="muted">Any of these would change the verdict:</p>'
+            + f"<ul>{FLIP_ITEMS}</ul>",
+        )
+    )
+    assert code == 0, out
+    assert "REPORT_OK" in out
+
+
+def test_would_flip_lead_in_paragraph_with_empty_list_fails() -> None:
+    code, out = _run_with_flips(
+        GOOD.replace(
+            VERDICT,
+            VERDICT
+            + "<h3>What would flip this</h3>"
+            + '<p class="muted">Any of these would change the verdict:</p><ul></ul>',
+        )
+    )
+    assert code == 1, out
+    assert "0 of 2" in out, out
+
+
+def test_would_flip_inline_label_item_passes() -> None:
+    # generate-report.md only asks for a "short unordered list"; the
+    # heroku-decision-gate fixtures render the label inside the first item
+    # (`<li>What would flip this: …</li>`) with no separate heading. That item's
+    # remainder plus its siblings are the list.
+    code, out = _run_with_flips(
+        GOOD.replace(
+            VERDICT,
+            VERDICT + f"<ul><li>What would flip this: {FLIPS[0]}</li><li>{FLIPS[1]}</li></ul>",
+        )
+    )
+    assert code == 0, out
+    assert "REPORT_OK" in out
+
+
+def test_would_flip_inline_label_partial_list_fails() -> None:
+    code, out = _run_with_flips(
+        GOOD.replace(VERDICT, VERDICT + f"<ul><li>What would flip this: {FLIPS[0]}</li></ul>")
+    )
+    assert code == 1, out
+    assert "1 of 2" in out and "Dyno count" in out, out
+
+
+def test_decision_gate_fixtures_render_their_flip_condition() -> None:
+    # The checked-in decision fixtures declare would_flip_if and render it in the
+    # inline-label shape; they must keep passing --mode decision so the fixture
+    # asserters (check_expected_decide*.py) exercise the flip check for real.
+    fixtures = SCRIPT.parents[3] / "fixtures" / "heroku-decision-gate"
+    for name in ("after-decide-complete", "retained-execution-pack"):
+        run_dir = fixtures / name
+        estimate = json.loads((run_dir / "estimation-infra.json").read_text(encoding="utf-8"))
+        assert estimate["recommendation"]["would_flip_if"], name
+        result = subprocess.run(  # nosec B603
+            [
+                sys.executable,
+                str(SCRIPT),
+                str(run_dir / "decision-report.html"),
+                "--mode",
+                "decision",
+                "--migration-dir",
+                str(run_dir),
+            ],
+            capture_output=True,
+            text=True,
+        )
+        assert result.returncode == 0, (name, result.stdout + result.stderr)
+
+
 def test_what_if_columns_required_when_section_present() -> None:
     thin = GOOD.replace(
         '<section id="next-steps">',
diff --git a/plugins/aws-startup-advisor/skills/heroku-to-aws/scripts/validate-heroku-migration-report.py b/plugins/aws-startup-advisor/skills/heroku-to-aws/scripts/validate-heroku-migration-report.py
index c42f0bd91..45204f5a3 100644
--- a/plugins/aws-startup-advisor/skills/heroku-to-aws/scripts/validate-heroku-migration-report.py
+++ b/plugins/aws-startup-advisor/skills/heroku-to-aws/scripts/validate-heroku-migration-report.py
@@ -831,27 +831,37 @@ def _phrase_rendered(phrase: str, rendered_text: str, max_width: int = 4) -> boo
 
 class _RenderedFragmentParser(HTMLParser):
     """Ported from validate-migration-report.py — flatten a fragment into what
-    the browser shows, in document order: `("text", run)` for prose outside a
-    list item and `("li", item)` per list item, each decoded and normalized via
-    _normalize_phrase. Inert subtrees and comments are skipped (same rule as
-    _DecodedTextParser / _TagAttrCollector), and inline tags do not split a run,
-    so `What <em>would</em> flip this` is one phrase."""
+    the browser shows, in document order: `("heading", run)` for an <h1>–<h6>,
+    `("li", item)` per list item and `("text", run)` for any other prose, each
+    decoded and normalized via _normalize_phrase. Inert subtrees and comments
+    are skipped (same rule as _DecodedTextParser / _TagAttrCollector), and
+    inline tags do not split a run, so `What <em>would</em> flip this` is one
+    phrase."""
 
     _INLINE_TAGS = _DecodedTextParser._INLINE_TAGS
     _INERT_TAGS = _DecodedTextParser._INERT_TAGS
+    _HEADING_TAGS = {"h1", "h2", "h3", "h4", "h5", "h6"}
 
     def __init__(self) -> None:
         super().__init__(convert_charrefs=True)
         self.entries: list[tuple[str, str]] = []
         self._inert_depth = 0
         self._li_depth = 0
+        self._heading_depth = 0
         self._buf: list[str] = []
 
     def _flush(self) -> None:
         text = _normalize_phrase(" ".join(self._buf))
         self._buf = []
-        if text:
-            self.entries.append(("li" if self._li_depth else "text", text))
+        if not text:
+            return
+        if self._li_depth:
+            kind = "li"
+        elif self._heading_depth:
+            kind = "heading"
+        else:
+            kind = "text"
+        self.entries.append((kind, text))
 
     def handle_starttag(self, tag: str, attrs: list[tuple[str, str | None]]) -> None:
         if tag in self._INERT_TAGS:
@@ -863,6 +873,8 @@ def handle_starttag(self, tag: str, attrs: list[tuple[str, str | None]]) -> None
             self._flush()
         if tag == "li":
             self._li_depth += 1
+        elif tag in self._HEADING_TAGS:
+            self._heading_depth += 1
 
     def handle_startendtag(self, tag: str, attrs: list[tuple[str, str | None]]) -> None:
         if tag in self._INERT_TAGS or self._inert_depth > 0:
@@ -881,6 +893,8 @@ def handle_endtag(self, tag: str) -> None:
             self._flush()
         if tag == "li" and self._li_depth > 0:
             self._li_depth -= 1
+        elif tag in self._HEADING_TAGS and self._heading_depth > 0:
+            self._heading_depth -= 1
 
     def handle_data(self, data: str) -> None:
         if self._inert_depth == 0:
@@ -901,17 +915,38 @@ def _rendered_entries(fragment: str) -> list[tuple[str, str]]:
 def _rendered_list_after_heading(
     entries: list[tuple[str, str]], heading_phrase: str
 ) -> list[str] | None:
-    """Items of the list following the first rendered run that contains
-    `heading_phrase`; None when no rendered run carries the heading, [] when the
-    heading is present but no list item follows it (heading-only / empty <ul>)."""
-    for index, (kind, text) in enumerate(entries):
-        if kind == "text" and heading_phrase in text:
-            items: list[str] = []
-            for next_kind, next_text in entries[index + 1 :]:
-                if next_kind != "li":
+    """Ported from validate-migration-report.py — items of the rendered list
+    that `heading_phrase` introduces. Two shapes are accepted, both legitimate
+    under generate-report.md's "short unordered list": a heading (preferred) or
+    prose run carrying the phrase (`<h3>What would flip this</h3>`), with any
+    lead-in prose before the first <li> skipped and another heading before any
+    item meaning an empty list; or a list item carrying the phrase as an inline
+    label (`<li>What would flip this: …</li>`, the shape the heroku-decision-gate
+    fixtures render), whose remainder plus following sibling items are the
+    list. None when no rendered run carries the phrase, [] when it does but no
+    item renders under it (heading-only / empty <ul>)."""
+
+    def items_from(start: int) -> list[str]:
+        items: list[str] = []
+        for kind, text in entries[start:]:
+            if kind != "li":
+                break
+            items.append(text)
+        return items
+
+    for wanted in ("heading", "text", "li"):
+        for index, (kind, text) in enumerate(entries):
+            if kind != wanted or heading_phrase not in text:
+                continue
+            if kind == "li":
+                remainder = text.split(heading_phrase, 1)[1].lstrip(" :;,.-")
+                return ([remainder] if remainder else []) + items_from(index + 1)
+            for offset, (next_kind, _next_text) in enumerate(entries[index + 1 :], index + 1):
+                if next_kind == "li":
+                    return items_from(offset)
+                if next_kind == "heading":
                     break
-                items.append(next_text)
-            return items
+            return []
     return None
 
 

From aa73aa47363ffe68b9ace34513c70cb1f210aaa6 Mon Sep 17 00:00:00 2001
From: Logan Kleier <lkleier@amazon.com>
Date: Fri, 2 Oct 2026 11:12:23 -0700
Subject: [PATCH 07/10] test(aws-startup-advisor): declare would_flip_if in the
 Heroku decision fixtures; document accepted flip-list shapes

The fixtures already render 'What would flip this' in DECISION.md and the
report but their estimation-infra.json omitted would_flip_if, so
check_expected_decide*.py never exercised the flip check. Check 26 and the
Heroku report gate now state that the label may head the list or lead its
first item, and that conditions match against list items only.
---
 .../after-decide-complete/estimation-infra.json                | 3 +++
 .../retained-execution-pack/estimation-infra.json              | 3 +++
 .../gcp-to-aws/references/shared/validate-migration-report.md  | 2 +-
 .../references/phases/generate/generate-report.md              | 3 ++-
 4 files changed, 9 insertions(+), 2 deletions(-)

diff --git a/plugins/aws-startup-advisor/fixtures/heroku-decision-gate/after-decide-complete/estimation-infra.json b/plugins/aws-startup-advisor/fixtures/heroku-decision-gate/after-decide-complete/estimation-infra.json
index a1e13789d..436c14d71 100644
--- a/plugins/aws-startup-advisor/fixtures/heroku-decision-gate/after-decide-complete/estimation-infra.json
+++ b/plugins/aws-startup-advisor/fixtures/heroku-decision-gate/after-decide-complete/estimation-infra.json
@@ -48,6 +48,9 @@
     ],
     "stay_if": [
       "need Heroku DX indefinitely"
+    ],
+    "would_flip_if": [
+      "A confirmed always-on traffic pattern would raise the AWS compute estimate materially."
     ]
   },
   "workshop": {
diff --git a/plugins/aws-startup-advisor/fixtures/heroku-decision-gate/retained-execution-pack/estimation-infra.json b/plugins/aws-startup-advisor/fixtures/heroku-decision-gate/retained-execution-pack/estimation-infra.json
index a1e13789d..436c14d71 100644
--- a/plugins/aws-startup-advisor/fixtures/heroku-decision-gate/retained-execution-pack/estimation-infra.json
+++ b/plugins/aws-startup-advisor/fixtures/heroku-decision-gate/retained-execution-pack/estimation-infra.json
@@ -48,6 +48,9 @@
     ],
     "stay_if": [
       "need Heroku DX indefinitely"
+    ],
+    "would_flip_if": [
+      "A confirmed always-on traffic pattern would raise the AWS compute estimate materially."
     ]
   },
   "workshop": {
diff --git a/plugins/aws-startup-advisor/skills/gcp-to-aws/references/shared/validate-migration-report.md b/plugins/aws-startup-advisor/skills/gcp-to-aws/references/shared/validate-migration-report.md
index b552dde6c..49250d1e6 100644
--- a/plugins/aws-startup-advisor/skills/gcp-to-aws/references/shared/validate-migration-report.md
+++ b/plugins/aws-startup-advisor/skills/gcp-to-aws/references/shared/validate-migration-report.md
@@ -102,7 +102,7 @@ decision reports.
 | 23 | Leadership brief                   | When an estimation artifact is passed, `exec-share` contains a static, copy-ready `share-card` without scripts or controls                                                                                                                                                                                                                                                                                                                                                                                                              |
 | 24 | Accessibility semantics            | Normal generated reports declare document language, contain exactly one `<h1>`, caption every table, scope table headers, and give every figure an image role, accessible name, and text alternative                                                                                                                                                                                                                                                                                                                                    |
 | 25 | Cost Optimization section          | If `optimization_opportunities[]` is non-empty: exactly one `exec-optimization` (TOC-linked) comparing Balanced on-demand vs Savings Plans / RI, plus (full mode only) a standalone `appendix-optimization` table with Optimization / Target / Monthly savings / Commitment / Effort columns. A table buried only in `appendix-costs` fails. Do not add SP/RI savings on top of Optimized. If RDS/Aurora/Fargate/Lambda is in `--aws-design` or opportunity targets, the section must include a Savings Plans or Reserved Instances row |
-| 26 | Decision-core render               | When `--estimation-infra` has a `recommendation`: hero metrics (`metric-hero`) and, when the fields exist, a `verdict-headline`, a "By track" line, a conditions checklist (each condition shares a phrase with the rendered text, matched at the condition's own word count), and a "What would flip this" list whose items render every `would_flip_if[]` entry — the heading alone, or an empty/partial list, fails. Only rendered markup counts: class tokens, headings, and list items inside `<template>`/`<script>`/`<style>` or comments are ignored. When `--aws-design` has a deferred service: a specialist-engagement callout in `decision-summary`. Full mode with `clusters`: `<section id="exec-architecture">`. `exec-assumptions` follows `exec-risks`. `exec-risks` is a table. With `--migration-dir` and ≥2 scenarios, the what-if table includes Region, HA, Compute, Arch, the three tiers, and Complexity |
+| 26 | Decision-core render               | When `--estimation-infra` has a `recommendation`: hero metrics (`metric-hero`) and, when the fields exist, a `verdict-headline`, a "By track" line, a conditions checklist (each condition shares a phrase with a rendered list item, matched at the condition's own word count — prose outside a list item does not count), and a "What would flip this" list whose items render every `would_flip_if[]` entry — the heading alone, or an empty/partial list, fails. The label may be a heading over the list (a lead-in sentence between them is fine) or the start of the first list item (`<li>What would flip this: …</li>`). Only rendered markup counts: class tokens, headings, and list items inside `<template>`/`<script>`/`<style>` or comments are ignored. When `--aws-design` has a deferred service: a specialist-engagement callout in `decision-summary`. Full mode with `clusters`: `<section id="exec-architecture">`. `exec-assumptions` follows `exec-risks`. `exec-risks` is a table. With `--migration-dir` and ≥2 scenarios, the what-if table includes Region, HA, Compute, Arch, the three tiers, and Complexity |
 
 Checks 10, 11, and 15 scan the `<body>` with `<style>` stripped, so CSS class names (e.g. `.rubric`) and selectors never trip them. The same readability scan rejects customer-facing "TCO" because modeled cloud charges do not include staffing or operating labor. Check 15 scopes to executive-flow sections only — appendices may carry artifact filenames and resource IDs by design. Disable checks 10, 11, and 15 with `--no-readability` only for non-customer fixtures. Check 14 is inert without `--migration-dir`, so validating the reference fixture (which legitimately contains the canary ID) never self-trips. Checks 16–17 apply whenever the corresponding sections/headings exist.
 
diff --git a/plugins/aws-startup-advisor/skills/heroku-to-aws/references/phases/generate/generate-report.md b/plugins/aws-startup-advisor/skills/heroku-to-aws/references/phases/generate/generate-report.md
index ffe959357..ed86cdbc0 100644
--- a/plugins/aws-startup-advisor/skills/heroku-to-aws/references/phases/generate/generate-report.md
+++ b/plugins/aws-startup-advisor/skills/heroku-to-aws/references/phases/generate/generate-report.md
@@ -273,7 +273,8 @@ python3 "<SKILL_BASE>/scripts/validate-heroku-migration-report.py" \
 rules in this file: when `recommendation.would_flip_if` is non-empty the
 summary must include a "What would flip this" list whose items render every
 entry (the heading over an empty or partial list fails; content inside
-`<template>` or comments does not count), and when two or more scenarios
+`<template>` or comments does not count; the label may be a heading over the
+list or lead its first item, `<li>What would flip this: …</li>`), and when two or more scenarios
 exist the what-if table must include Region, HA, Compute, Arch, and Complexity.
 A report written only to satisfy the section-ID list will fail.
 

From 5398c8288f616d54ddef824550a9ec018aa9418a Mon Sep 17 00:00:00 2001
From: Logan Kleier <lkleier@amazon.com>
Date: Fri, 2 Oct 2026 13:05:12 -0700
Subject: [PATCH 08/10] test(aws-startup-advisor): cover migration-dir-gated
 scenario check in shared validator

Addresses AI review finding on PR #396: the GCP Decision scenario-column
check (--migration-dir required for scenarios/index.json) had test coverage
in the Heroku validator's test file but none in
test_validate_migration_report_decision_core.py. The behavior itself was
already correct (fixed by prior commits on this branch); this adds the
missing regression test.
---
 ...validate_migration_report_decision_core.py | 30 +++++++++++++++++++
 1 file changed, 30 insertions(+)

diff --git a/plugins/aws-startup-advisor/scripts/test_validate_migration_report_decision_core.py b/plugins/aws-startup-advisor/scripts/test_validate_migration_report_decision_core.py
index 11a1811a4..7a7bd3075 100644
--- a/plugins/aws-startup-advisor/scripts/test_validate_migration_report_decision_core.py
+++ b/plugins/aws-startup-advisor/scripts/test_validate_migration_report_decision_core.py
@@ -327,6 +327,36 @@ def test_clusters_without_architecture_section_fail() -> None:
     assert any("exec-architecture" in err for err in errors), errors
 
 
+def test_scenario_column_check_requires_migration_dir() -> None:
+    # The what-if column check reads scenarios/index.json via --migration-dir.
+    # Without that flag the check never fires, even with >=2 scenarios and a
+    # thin what-if-scenarios table missing the decision-core columns.
+    validator = _load()
+    html = _reference_html().replace(
+        '<section id="exec-timeline">',
+        '<section id="what-if-scenarios"><table><caption>Scenarios</caption><thead><tr>'
+        '<th scope="col">Scenario</th><th scope="col">Monthly</th>'
+        "</tr></thead><tbody><tr><td>Baseline</td><td>$1</td></tr></tbody></table></section>"
+        '<section id="exec-timeline">',
+    )
+    ai = json.loads((FIXTURES / "estimation-ai-reference.json").read_text(encoding="utf-8"))
+    errors_without_dir = validator.validate_report(html, _reference_estimate(), ai)
+    assert errors_without_dir == [], errors_without_dir
+
+    import tempfile
+
+    with tempfile.TemporaryDirectory() as tmp:
+        root = Path(tmp)
+        (root / "scenarios").mkdir()
+        (root / "scenarios" / "index.json").write_text(
+            json.dumps({"scenarios": [{"id": "a"}, {"id": "b"}]}), encoding="utf-8"
+        )
+        errors_with_dir = validator.validate_report(
+            html, _reference_estimate(), ai, migration_dir=root
+        )
+    assert any("Region" in err for err in errors_with_dir), errors_with_dir
+
+
 def test_decision_fixture_still_passes() -> None:
     validator = _load()
     root = FIXTURES / "gcp-decision-gate" / "after-decide-complete"

From 6a79b887e7bf49a62a93852b6e87a8f11f42505b Mon Sep 17 00:00:00 2001
From: Logan Kleier <lkleier@amazon.com>
Date: Fri, 2 Oct 2026 20:34:26 -0700
Subject: [PATCH 09/10] fix: require distinct flip condition items

---
 ...validate_migration_report_decision_core.py | 39 +++++++++++++++
 .../scripts/validate-migration-report.py      | 28 +++++++++--
 .../test_validate_heroku_migration_report.py  | 47 +++++++++++++++++++
 .../validate-heroku-migration-report.py       | 28 +++++++++--
 4 files changed, 132 insertions(+), 10 deletions(-)

diff --git a/plugins/aws-startup-advisor/scripts/test_validate_migration_report_decision_core.py b/plugins/aws-startup-advisor/scripts/test_validate_migration_report_decision_core.py
index 7a7bd3075..1fb297335 100644
--- a/plugins/aws-startup-advisor/scripts/test_validate_migration_report_decision_core.py
+++ b/plugins/aws-startup-advisor/scripts/test_validate_migration_report_decision_core.py
@@ -100,6 +100,45 @@ def test_would_flip_partial_list_fails() -> None:
     assert "1 of 2" in errors[0] and "BigQuery" in errors[0], errors
 
 
+def test_would_flip_shared_suffix_cannot_cross_satisfy_items() -> None:
+    estimate = _reference_estimate()
+    estimate["recommendation"]["would_flip_if"] = [
+        "Database changes require specialist evidence",
+        "Compute changes require specialist evidence",
+    ]
+    html = _reference_html().replace(
+        FLIP_BLOCK,
+        """      <h3>What would flip this</h3>
+      <ul class="compact">
+        <li>Database changes require specialist evidence</li>
+      </ul>""",
+    )
+    errors = _flip_errors_for_estimate(html, estimate)
+    assert errors and "1 of 2" in errors[0] and "Compute" in errors[0], errors
+
+
+def test_would_flip_shared_suffix_complete_items_pass() -> None:
+    estimate = _reference_estimate()
+    estimate["recommendation"]["would_flip_if"] = [
+        "Database changes require specialist evidence",
+        "Compute changes require specialist evidence",
+    ]
+    html = _reference_html().replace(
+        FLIP_BLOCK,
+        """      <h3>What would flip this</h3>
+      <ul class="compact">
+        <li>Database changes require specialist evidence</li>
+        <li>Compute changes require specialist evidence</li>
+      </ul>""",
+    )
+    assert _flip_errors_for_estimate(html, estimate) == []
+
+
+def _flip_errors_for_estimate(html: str, estimate: dict) -> list[str]:
+    validator = _load()
+    return [e for e in validator.validate_report(html, estimate, None) if "flip" in e]
+
+
 def test_would_flip_items_only_in_template_fail() -> None:
     html = _reference_html().replace(
         "      <ul class=\"compact\">\n        <li>Single-AZ acceptable",
diff --git a/plugins/aws-startup-advisor/scripts/validate-migration-report.py b/plugins/aws-startup-advisor/scripts/validate-migration-report.py
index a3f944f3c..82b0febd9 100644
--- a/plugins/aws-startup-advisor/scripts/validate-migration-report.py
+++ b/plugins/aws-startup-advisor/scripts/validate-migration-report.py
@@ -1700,6 +1700,28 @@ def _phrase_rendered(phrase: str, rendered_text: str, max_width: int = 4) -> boo
     return bool(_word_shingles(" ".join(words), width) & _word_shingles(rendered_text, width))
 
 
+def _unmatched_phrases(phrases: list[object], rendered_items: list[str]) -> list[str]:
+    """Return artifact phrases that cannot be assigned distinct rendered items."""
+    matched_items: dict[int, int] = {}
+
+    def assign(phrase_index: int, seen_items: set[int]) -> bool:
+        phrase = str(phrases[phrase_index])
+        for item_index, item in enumerate(rendered_items):
+            if item_index in seen_items or not _phrase_rendered(phrase, item):
+                continue
+            seen_items.add(item_index)
+            previous = matched_items.get(item_index)
+            if previous is None or assign(previous, seen_items):
+                matched_items[item_index] = phrase_index
+                return True
+        return False
+
+    for phrase_index in range(len(phrases)):
+        assign(phrase_index, set())
+    matched_phrases = set(matched_items.values())
+    return [str(phrase) for index, phrase in enumerate(phrases) if index not in matched_phrases]
+
+
 class _RenderedFragmentParser(HTMLParser):
     """Flatten a fragment into what the browser would show, in document order.
 
@@ -1952,11 +1974,7 @@ def _validate_decision_core_render(
         else:
             # The heading alone is not the content: every artifact flip condition
             # must appear as a rendered item of that list.
-            missing = [
-                str(flip)
-                for flip in flips
-                if not any(_phrase_rendered(str(flip), item) for item in items)
-            ]
+            missing = _unmatched_phrases(flips, items)
             if missing:
                 errors.append(
                     f'"What would flip this" list renders {len(flips) - len(missing)} of '
diff --git a/plugins/aws-startup-advisor/skills/heroku-to-aws/scripts/test_validate_heroku_migration_report.py b/plugins/aws-startup-advisor/skills/heroku-to-aws/scripts/test_validate_heroku_migration_report.py
index d97c77182..b4da569ac 100644
--- a/plugins/aws-startup-advisor/skills/heroku-to-aws/scripts/test_validate_heroku_migration_report.py
+++ b/plugins/aws-startup-advisor/skills/heroku-to-aws/scripts/test_validate_heroku_migration_report.py
@@ -201,6 +201,53 @@ def test_would_flip_partial_list_fails() -> None:
     assert "1 of 2" in out and "Dyno count" in out, out
 
 
+def _run_with_custom_flips(html: str, flips: list[str]) -> tuple[int, str]:
+    with tempfile.TemporaryDirectory() as tmp:
+        d = Path(tmp)
+        (d / "estimation-infra.json").write_text(
+            json.dumps(
+                {"recommendation": {"outcome": "go_conditional", "would_flip_if": flips}}
+            ),
+            encoding="utf-8",
+        )
+        return run(html, migration_dir=d)
+
+
+def test_would_flip_shared_suffix_cannot_cross_satisfy_items() -> None:
+    flips = [
+        "Database changes require specialist evidence",
+        "Compute changes require specialist evidence",
+    ]
+    html = GOOD.replace(
+        VERDICT,
+        VERDICT
+        + "<h3>What would flip this</h3>"
+        + "<ul><li>Database changes require specialist evidence</li></ul>",
+    )
+    code, out = _run_with_custom_flips(html, flips)
+    assert code == 1, out
+    assert "1 of 2" in out and "Compute" in out, out
+
+
+def test_would_flip_shared_suffix_complete_items_pass() -> None:
+    flips = [
+        "Database changes require specialist evidence",
+        "Compute changes require specialist evidence",
+    ]
+    html = GOOD.replace(
+        VERDICT,
+        VERDICT
+        + "<h3>What would flip this</h3>"
+        + "<ul>"
+        "<li>Database changes require specialist evidence</li>"
+        "<li>Compute changes require specialist evidence</li>"
+        "</ul>",
+    )
+    code, out = _run_with_custom_flips(html, flips)
+    assert code == 0, out
+    assert "REPORT_OK" in out
+
+
 def test_would_flip_complete_list_passes() -> None:
     code, out = _run_with_flips(
         GOOD.replace(VERDICT, VERDICT + f"<h3>What would flip this</h3><ul>{FLIP_ITEMS}</ul>")
diff --git a/plugins/aws-startup-advisor/skills/heroku-to-aws/scripts/validate-heroku-migration-report.py b/plugins/aws-startup-advisor/skills/heroku-to-aws/scripts/validate-heroku-migration-report.py
index 45204f5a3..0feb78544 100644
--- a/plugins/aws-startup-advisor/skills/heroku-to-aws/scripts/validate-heroku-migration-report.py
+++ b/plugins/aws-startup-advisor/skills/heroku-to-aws/scripts/validate-heroku-migration-report.py
@@ -829,6 +829,28 @@ def _phrase_rendered(phrase: str, rendered_text: str, max_width: int = 4) -> boo
     return bool(_word_shingles(" ".join(words), width) & _word_shingles(rendered_text, width))
 
 
+def _unmatched_phrases(phrases: list[object], rendered_items: list[str]) -> list[str]:
+    """Return artifact phrases that cannot be assigned distinct rendered items."""
+    matched_items: dict[int, int] = {}
+
+    def assign(phrase_index: int, seen_items: set[int]) -> bool:
+        phrase = str(phrases[phrase_index])
+        for item_index, item in enumerate(rendered_items):
+            if item_index in seen_items or not _phrase_rendered(phrase, item):
+                continue
+            seen_items.add(item_index)
+            previous = matched_items.get(item_index)
+            if previous is None or assign(previous, seen_items):
+                matched_items[item_index] = phrase_index
+                return True
+        return False
+
+    for phrase_index in range(len(phrases)):
+        assign(phrase_index, set())
+    matched_phrases = set(matched_items.values())
+    return [str(phrase) for index, phrase in enumerate(phrases) if index not in matched_phrases]
+
+
 class _RenderedFragmentParser(HTMLParser):
     """Ported from validate-migration-report.py — flatten a fragment into what
     the browser shows, in document order: `("heading", run)` for an <h1>–<h6>,
@@ -1001,11 +1023,7 @@ def _validate_verdict(html: str, migration_dir: Path | None) -> list[str]:
                 'decision-summary has no "What would flip this" list'
             )
         else:
-            missing = [
-                str(flip)
-                for flip in flips
-                if not any(_phrase_rendered(str(flip), item) for item in items)
-            ]
+            missing = _unmatched_phrases(flips, items)
             if missing:
                 errors.append(
                     f'"What would flip this" list renders {len(flips) - len(missing)} of '

From 72559b3cf4f54c205af3f5702ec60b263bc1b948 Mon Sep 17 00:00:00 2001
From: Logan Kleier <lkleier@amazon.com>
Date: Fri, 2 Oct 2026 20:42:54 -0700
Subject: [PATCH 10/10] fix: ignore hidden decision content

---
 ...validate_migration_report_decision_core.py |  37 ++++++
 .../scripts/validate-migration-report.py      | 118 +++++++++++++++---
 .../test_validate_heroku_migration_report.py  |  25 ++++
 .../validate-heroku-migration-report.py       | 111 ++++++++++++++--
 4 files changed, 267 insertions(+), 24 deletions(-)

diff --git a/plugins/aws-startup-advisor/scripts/test_validate_migration_report_decision_core.py b/plugins/aws-startup-advisor/scripts/test_validate_migration_report_decision_core.py
index 1fb297335..b0b74b5b9 100644
--- a/plugins/aws-startup-advisor/scripts/test_validate_migration_report_decision_core.py
+++ b/plugins/aws-startup-advisor/scripts/test_validate_migration_report_decision_core.py
@@ -329,6 +329,30 @@ def test_metric_hero_only_in_template_fails() -> None:
     assert any("metric-hero" in err for err in errors), errors
 
 
+def test_verdict_headline_only_in_hidden_element_or_ancestor_fails() -> None:
+    validator = _load()
+    for replacement in (
+        '<p hidden class="verdict-headline">Go, with conditions</p>',
+        '<div hidden><p class="verdict-headline">Go, with conditions</p></div>',
+    ):
+        html = _reference_html().replace(
+            '<p class="verdict-headline">Go, with conditions</p>', replacement
+        )
+        errors = validator.validate_report(html, _reference_estimate(), None)
+        assert any("verdict-headline" in err for err in errors), (replacement, errors)
+
+
+def test_metric_hero_only_in_hidden_ancestor_fails() -> None:
+    validator = _load()
+    html = _reference_html().replace('<div class="metric metric-hero">', '<div class="metric">')
+    html = html.replace(
+        '<div class="metrics">',
+        '<div hidden><div class="metric metric-hero"></div></div>\n      <div class="metrics">',
+    )
+    errors = validator.validate_report(html, _reference_estimate(), None)
+    assert any("metric-hero" in err for err in errors), errors
+
+
 def test_metric_hero_unquoted_class_passes() -> None:
     # Class tokens are read from the parsed attribute, not a literal regex, so
     # any legal spelling of the attribute counts as rendered.
@@ -341,6 +365,19 @@ def test_metric_hero_unquoted_class_passes() -> None:
     assert not any("metric-hero" in err for err in errors), errors
 
 
+def test_would_flip_populated_list_only_in_hidden_element_or_ancestor_fails() -> None:
+    for replacement in (
+        '      <h3>What would flip this</h3>\n      <ul hidden>\n'
+        '        <li>Single-AZ acceptable: AWS estimate drops further, strengthens go</li>\n'
+        '        <li>BigQuery must cut over in the same window: defer for specialist evidence</li>\n'
+        '      </ul>',
+        '<div hidden>' + FLIP_BLOCK + '</div>',
+    ):
+        html = _reference_html().replace(FLIP_BLOCK, replacement)
+        errors = _flip_errors(html)
+        assert errors, replacement
+
+
 def test_deferred_service_without_callout_fails() -> None:
     validator = _load()
     html = _reference_html().replace("specialist engagement", "analytics follow-up")
diff --git a/plugins/aws-startup-advisor/scripts/validate-migration-report.py b/plugins/aws-startup-advisor/scripts/validate-migration-report.py
index 82b0febd9..32ce7f378 100644
--- a/plugins/aws-startup-advisor/scripts/validate-migration-report.py
+++ b/plugins/aws-startup-advisor/scripts/validate-migration-report.py
@@ -1654,22 +1654,82 @@ def _validate_fixture_bleed(html: str, migration_dir: Path | None) -> list[str]:
     return errors
 
 
+class _VisibleTextParser(HTMLParser):
+    """Collect decoded text from rendered content, excluding hidden ancestors."""
+
+    _INERT_TAGS = {"script", "style", "template"}
+    _INLINE_TAGS = {
+        "a", "abbr", "b", "bdi", "bdo", "cite", "code", "data", "dfn", "em",
+        "i", "kbd", "mark", "q", "s", "samp", "small", "span", "strong",
+        "sub", "sup", "time", "u", "var", "wbr",
+    }
+    _VOID_TAGS = {
+        "area", "base", "br", "col", "embed", "hr", "img", "input",
+        "link", "meta", "param", "source", "track", "wbr",
+    }
+
+    def __init__(self) -> None:
+        super().__init__(convert_charrefs=True)
+        self.parts: list[str] = []
+        self._inert_depth = 0
+        self._stack: list[dict[str, object]] = []
+
+    def _hidden(self) -> bool:
+        return bool(self._stack and self._stack[-1]["hidden"])
+
+    @staticmethod
+    def _is_hidden(attrs: list[tuple[str, str | None]]) -> bool:
+        return "hidden" in dict(attrs)
+
+    def handle_starttag(self, tag: str, attrs: list[tuple[str, str | None]]) -> None:
+        if tag in self._INERT_TAGS:
+            self._inert_depth += 1
+            return
+        if self._inert_depth > 0:
+            return
+        hidden = self._hidden() or self._is_hidden(attrs)
+        if tag not in self._INLINE_TAGS:
+            self.parts.append(" ")
+        if tag not in self._VOID_TAGS:
+            self._stack.append({"tag": tag, "hidden": hidden})
+
+    def handle_startendtag(self, tag: str, attrs: list[tuple[str, str | None]]) -> None:
+        return
+
+    def handle_endtag(self, tag: str) -> None:
+        if tag in self._INERT_TAGS:
+            if self._inert_depth > 0:
+                self._inert_depth -= 1
+            return
+        if self._inert_depth > 0:
+            return
+        hidden = False
+        for index in range(len(self._stack) - 1, -1, -1):
+            if self._stack[index]["tag"] == tag:
+                hidden = any(bool(frame["hidden"]) for frame in self._stack[index:])
+                del self._stack[index:]
+                break
+        if tag not in self._INLINE_TAGS:
+            self.parts.append(" ")
+        if hidden:
+            return
+
+    def handle_data(self, data: str) -> None:
+        if self._inert_depth == 0 and not self._hidden():
+            self.parts.append(data)
+
+
 def _plain_text(fragment: str) -> str:
     """Decoded visible text, with dashes folded so artifact prose can be matched.
 
-    Inert subtrees (`<script>`, `<style>`, `<template>`) and HTML comments are
-    dropped first: the browser does not render their contents, so a decision-core
-    heading or condition hidden inside a `<template>` must not count as rendered.
-    This matches the Heroku validator's decoded-text semantics.
+    Inert subtrees (`<script>`, `<style>`, `<template>`), native-hidden
+    subtrees, and HTML comments are excluded because the browser does not render
+    their contents.
     """
-    stripped = re.sub(r"<!--.*?-->", " ", fragment, flags=re.DOTALL)
-    stripped = re.sub(
-        r"<(script|style|template)\b[^>]*>.*?</\1\s*>",
-        " ",
-        stripped,
-        flags=re.DOTALL | re.IGNORECASE,
-    )
-    text = unescape(re.sub(r"<[^>]+>", " ", stripped))
+    parser = _VisibleTextParser()
+    parser.feed(fragment)
+    parser.close()
+    text = "".join(parser.parts)
     text = text.replace("\u2014", "-").replace("\u2013", "-")
     return re.sub(r"\s+", " ", text).strip().lower()
 
@@ -1739,16 +1799,36 @@ class _RenderedFragmentParser(HTMLParser):
     _INLINE_TAGS = _DecodedTextRunParser._INLINE_TAGS
     _INERT_TAGS = _DecodedTextRunParser._INERT_TAGS
     _HEADING_TAGS = {"h1", "h2", "h3", "h4", "h5", "h6"}
+    _VOID_TAGS = {
+        "area", "base", "br", "col", "embed", "hr", "img", "input",
+        "link", "meta", "param", "source", "track", "wbr",
+    }
 
     def __init__(self) -> None:
         super().__init__(convert_charrefs=True)
         self.entries: list[tuple[str, str]] = []
         self.class_tokens: set[str] = set()
         self._inert_depth = 0
+        self._stack: list[dict[str, object]] = []
         self._li_depth = 0
         self._heading_depth = 0
         self._buf: list[str] = []
 
+    def _hidden(self) -> bool:
+        return bool(self._stack and self._stack[-1]["hidden"])
+
+    @staticmethod
+    def _is_hidden(attrs: list[tuple[str, str | None]]) -> bool:
+        return "hidden" in dict(attrs)
+
+    def _pop_to(self, tag: str) -> bool:
+        for index in range(len(self._stack) - 1, -1, -1):
+            if self._stack[index]["tag"] == tag:
+                popped = self._stack[index:]
+                del self._stack[index:]
+                return any(bool(frame["hidden"]) for frame in popped)
+        return False
+
     def _flush(self) -> None:
         text = _plain_text(" ".join(self._buf))
         self._buf = []
@@ -1773,6 +1853,11 @@ def handle_starttag(self, tag: str, attrs: list[tuple[str, str | None]]) -> None
             return
         if self._inert_depth > 0:
             return
+        hidden = self._hidden() or self._is_hidden(attrs)
+        if tag not in self._VOID_TAGS:
+            self._stack.append({"tag": tag, "hidden": hidden})
+        if hidden:
+            return
         self._record_classes(attrs)
         if tag not in self._INLINE_TAGS:
             self._flush()
@@ -1782,7 +1867,9 @@ def handle_starttag(self, tag: str, attrs: list[tuple[str, str | None]]) -> None
             self._heading_depth += 1
 
     def handle_startendtag(self, tag: str, attrs: list[tuple[str, str | None]]) -> None:
-        if tag in self._INERT_TAGS or self._inert_depth > 0:
+        if tag in self._INERT_TAGS or self._inert_depth > 0 or self._hidden():
+            return
+        if self._is_hidden(attrs):
             return
         self._record_classes(attrs)
         if tag not in self._INLINE_TAGS:
@@ -1795,6 +1882,9 @@ def handle_endtag(self, tag: str) -> None:
             return
         if self._inert_depth > 0:
             return
+        hidden = self._pop_to(tag)
+        if hidden or self._hidden():
+            return
         if tag not in self._INLINE_TAGS:
             self._flush()
         if tag == "li" and self._li_depth > 0:
@@ -1803,7 +1893,7 @@ def handle_endtag(self, tag: str) -> None:
             self._heading_depth -= 1
 
     def handle_data(self, data: str) -> None:
-        if self._inert_depth == 0:
+        if self._inert_depth == 0 and not self._hidden():
             self._buf.append(data)
 
     def close(self) -> None:
diff --git a/plugins/aws-startup-advisor/skills/heroku-to-aws/scripts/test_validate_heroku_migration_report.py b/plugins/aws-startup-advisor/skills/heroku-to-aws/scripts/test_validate_heroku_migration_report.py
index b4da569ac..234a69d55 100644
--- a/plugins/aws-startup-advisor/skills/heroku-to-aws/scripts/test_validate_heroku_migration_report.py
+++ b/plugins/aws-startup-advisor/skills/heroku-to-aws/scripts/test_validate_heroku_migration_report.py
@@ -808,6 +808,31 @@ def test_th_inside_template_not_audited_for_scope() -> None:
     assert "REPORT_OK" in out
 
 
+def test_verdict_headline_only_in_hidden_element_or_ancestor_fails() -> None:
+    for replacement in (
+        '<p hidden class="verdict-headline">Go, with conditions</p>',
+        '<div hidden><p class="verdict-headline">Go, with conditions</p></div>',
+    ):
+        html = GOOD.replace(
+            '<p class="verdict-headline">Go, with conditions</p>', replacement
+        )
+        with tempfile.TemporaryDirectory() as tmp:
+            code, out = run(html, migration_dir=_rec_dir(tmp))
+        assert code == 1, (replacement, out)
+        assert "verdict-headline" in out.lower()
+
+
+def test_would_flip_populated_list_only_in_hidden_element_or_ancestor_fails() -> None:
+    for replacement in (
+        '<h3>What would flip this</h3><ul hidden>'
+        f'{FLIP_ITEMS}</ul>',
+        f'<div hidden><h3>What would flip this</h3><ul>{FLIP_ITEMS}</ul></div>',
+    ):
+        code, out = _run_with_flips(GOOD.replace(VERDICT, VERDICT + replacement))
+        assert code == 1, (replacement, out)
+        assert "would_flip" in out
+
+
 # --- Section-parser regressions (09-22 P2): section identity/counts come from the
 # stdlib parser, so comments and inert (script/style/template) subtrees never satisfy
 # a section gate, real quoted/unquoted/spaced ids pass, and data-id is not the id. ---
diff --git a/plugins/aws-startup-advisor/skills/heroku-to-aws/scripts/validate-heroku-migration-report.py b/plugins/aws-startup-advisor/skills/heroku-to-aws/scripts/validate-heroku-migration-report.py
index 0feb78544..1e07fefa2 100644
--- a/plugins/aws-startup-advisor/skills/heroku-to-aws/scripts/validate-heroku-migration-report.py
+++ b/plugins/aws-startup-advisor/skills/heroku-to-aws/scripts/validate-heroku-migration-report.py
@@ -494,11 +494,16 @@ class docstring for the full rationale). No Calculation/Notes column
         "sub", "sup", "time", "u", "var", "wbr",
     }
     _INERT_TAGS = {"script", "style", "template"}
+    _VOID_TAGS = {
+        "area", "base", "br", "col", "embed", "hr", "img", "input",
+        "link", "meta", "param", "source", "track", "wbr",
+    }
 
     def __init__(self) -> None:
         super().__init__(convert_charrefs=True)
         self._parts: list[str] = []
         self._inert_depth = 0
+        self._stack: list[dict[str, object]] = []
         # Absolute offsets (into text()) of every block-level separator — a
         # rate-suffix match must never read past one of these into unrelated
         # content from a different cell/row/paragraph (see
@@ -515,15 +520,43 @@ def _append(self, text: str, *, is_boundary: bool = False) -> None:
             self._boundaries.append(sum(len(p) for p in self._parts))
         self._parts.append(text)
 
+    def _hidden(self) -> bool:
+        return bool(self._stack and self._stack[-1]["hidden"])
+
+    @staticmethod
+    def _is_hidden(attrs: list[tuple[str, str | None]]) -> bool:
+        return "hidden" in dict(attrs)
+
+    def _pop_to(self, tag: str) -> bool:
+        for index in range(len(self._stack) - 1, -1, -1):
+            if self._stack[index]["tag"] == tag:
+                popped = self._stack[index:]
+                del self._stack[index:]
+                return any(bool(frame["hidden"]) for frame in popped)
+        return False
+
     def handle_starttag(self, tag: str, attrs: list[tuple[str, str | None]]) -> None:
         if tag in self._INERT_TAGS:
             self._inert_depth += 1
             return
-        if self._inert_depth == 0 and tag not in self._INLINE_TAGS:
+        if self._inert_depth > 0:
+            return
+        hidden = self._hidden() or self._is_hidden(attrs)
+        if tag not in self._VOID_TAGS:
+            self._stack.append({"tag": tag, "hidden": hidden})
+        if hidden:
+            if tag not in self._INLINE_TAGS:
+                self._append(" ", is_boundary=True)
+            return
+        if tag not in self._INLINE_TAGS:
             self._append(" ", is_boundary=True)
 
     def handle_startendtag(self, tag: str, attrs: list[tuple[str, str | None]]) -> None:
-        if tag not in self._INLINE_TAGS and tag not in self._INERT_TAGS:
+        if tag in self._INERT_TAGS or self._inert_depth > 0 or self._hidden():
+            return
+        if self._is_hidden(attrs):
+            return
+        if tag not in self._INLINE_TAGS:
             self._append(" ", is_boundary=True)
 
     def handle_endtag(self, tag: str) -> None:
@@ -531,11 +564,18 @@ def handle_endtag(self, tag: str) -> None:
             if self._inert_depth > 0:
                 self._inert_depth -= 1
             return
-        if self._inert_depth == 0 and tag not in self._INLINE_TAGS:
+        if self._inert_depth > 0:
+            return
+        hidden = self._pop_to(tag)
+        if hidden or self._hidden():
+            if tag not in self._INLINE_TAGS:
+                self._append(" ", is_boundary=True)
+            return
+        if tag not in self._INLINE_TAGS:
             self._append(" ", is_boundary=True)
 
     def handle_data(self, data: str) -> None:
-        if self._inert_depth == 0:
+        if self._inert_depth == 0 and not self._hidden():
             self._append(data)
 
     def text(self) -> str:
@@ -598,30 +638,54 @@ class _TagAttrCollector(HTMLParser):
     "is this rendered?" check in this file agrees on the answer."""
 
     _INERT_TAGS = {"script", "style", "template"}
+    _VOID_TAGS = {
+        "area", "base", "br", "col", "embed", "hr", "img", "input",
+        "link", "meta", "param", "source", "track", "wbr",
+    }
 
     def __init__(self) -> None:
         super().__init__(convert_charrefs=True)
         self.tags: list[tuple[str, dict[str, str | None], bool]] = []
         self._inert_depth = 0
+        self._stack: list[dict[str, object]] = []
+
+    def _hidden(self) -> bool:
+        return bool(self._stack and self._stack[-1]["hidden"])
+
+    @staticmethod
+    def _is_hidden(attrs: list[tuple[str, str | None]]) -> bool:
+        return "hidden" in dict(attrs)
 
     def handle_starttag(self, tag: str, attrs: list[tuple[str, str | None]]) -> None:
         if tag in self._INERT_TAGS:
             self._inert_depth += 1
             return
-        if self._inert_depth == 0:
+        if self._inert_depth > 0:
+            return
+        hidden = self._hidden() or self._is_hidden(attrs)
+        if tag not in self._VOID_TAGS:
+            self._stack.append({"tag": tag, "hidden": hidden})
+        if not hidden:
             self.tags.append((tag, dict(attrs), False))
 
     def handle_startendtag(self, tag: str, attrs: list[tuple[str, str | None]]) -> None:
         # A self-closed inert tag opens no subtree; a self-closed normal tag is a
-        # rendered element (unless nested in an inert subtree).
-        if tag in self._INERT_TAGS:
+        # rendered element unless nested in an inert or hidden subtree.
+        if tag in self._INERT_TAGS or self._inert_depth > 0 or self._hidden():
             return
-        if self._inert_depth == 0:
+        if not self._is_hidden(attrs):
             self.tags.append((tag, dict(attrs), True))
 
     def handle_endtag(self, tag: str) -> None:
         if tag in self._INERT_TAGS and self._inert_depth > 0:
             self._inert_depth -= 1
+            return
+        if self._inert_depth > 0:
+            return
+        for index in range(len(self._stack) - 1, -1, -1):
+            if self._stack[index]["tag"] == tag:
+                del self._stack[index:]
+                return
 
 
 def _collect_tags(html: str) -> list[tuple[str, dict[str, str | None], bool]]:
@@ -863,15 +927,32 @@ class _RenderedFragmentParser(HTMLParser):
     _INLINE_TAGS = _DecodedTextParser._INLINE_TAGS
     _INERT_TAGS = _DecodedTextParser._INERT_TAGS
     _HEADING_TAGS = {"h1", "h2", "h3", "h4", "h5", "h6"}
+    _VOID_TAGS = _DecodedTextParser._VOID_TAGS
 
     def __init__(self) -> None:
         super().__init__(convert_charrefs=True)
         self.entries: list[tuple[str, str]] = []
         self._inert_depth = 0
+        self._stack: list[dict[str, object]] = []
         self._li_depth = 0
         self._heading_depth = 0
         self._buf: list[str] = []
 
+    def _hidden(self) -> bool:
+        return bool(self._stack and self._stack[-1]["hidden"])
+
+    @staticmethod
+    def _is_hidden(attrs: list[tuple[str, str | None]]) -> bool:
+        return "hidden" in dict(attrs)
+
+    def _pop_to(self, tag: str) -> bool:
+        for index in range(len(self._stack) - 1, -1, -1):
+            if self._stack[index]["tag"] == tag:
+                popped = self._stack[index:]
+                del self._stack[index:]
+                return any(bool(frame["hidden"]) for frame in popped)
+        return False
+
     def _flush(self) -> None:
         text = _normalize_phrase(" ".join(self._buf))
         self._buf = []
@@ -891,6 +972,11 @@ def handle_starttag(self, tag: str, attrs: list[tuple[str, str | None]]) -> None
             return
         if self._inert_depth > 0:
             return
+        hidden = self._hidden() or self._is_hidden(attrs)
+        if tag not in self._VOID_TAGS:
+            self._stack.append({"tag": tag, "hidden": hidden})
+        if hidden:
+            return
         if tag not in self._INLINE_TAGS:
             self._flush()
         if tag == "li":
@@ -899,7 +985,9 @@ def handle_starttag(self, tag: str, attrs: list[tuple[str, str | None]]) -> None
             self._heading_depth += 1
 
     def handle_startendtag(self, tag: str, attrs: list[tuple[str, str | None]]) -> None:
-        if tag in self._INERT_TAGS or self._inert_depth > 0:
+        if tag in self._INERT_TAGS or self._inert_depth > 0 or self._hidden():
+            return
+        if self._is_hidden(attrs):
             return
         if tag not in self._INLINE_TAGS:
             self._flush()
@@ -911,6 +999,9 @@ def handle_endtag(self, tag: str) -> None:
             return
         if self._inert_depth > 0:
             return
+        hidden = self._pop_to(tag)
+        if hidden or self._hidden():
+            return
         if tag not in self._INLINE_TAGS:
             self._flush()
         if tag == "li" and self._li_depth > 0:
@@ -919,7 +1010,7 @@ def handle_endtag(self, tag: str) -> None:
             self._heading_depth -= 1
 
     def handle_data(self, data: str) -> None:
-        if self._inert_depth == 0:
+        if self._inert_depth == 0 and not self._hidden():
             self._buf.append(data)
 
     def close(self) -> None: