fix(auth0-checkmate): mirror CodeRabbit fixes + align report templates with the sanitized skill

auth0-self-serve-monetization · claude · auth0-self-serve-monetization · commit c1bc2c8c7f7d · 2026-06-17T09:26:12.000-07:00
CodeRabbit's re-review of PR #127 flagged the vendored CLI README in the checkmate skill; these were the same latent issues already fixed on the healthcheck side (06b235d) in checkmate's sibling files: - scripts/render_pdf.sh: render to a temp file, promote only on a non-empty result (don't treat a stale PDF as a successful render) - references/auth0-cli-readme.md: markdownlint fences (MD031 blank lines, MD040 language tags) - references/report-template.{md,html}: bin/ -> scripts/ render path; strip {{...}} from instructional comments so they can't survive substitution and trip the fusion lint Also aligns the report templates with the skill's already-sanitized recommendation logic — the templates still rendered the removed sales fields: - header "Auth0 Fit / {{auth0_plan_recommendation}}" -> "Recommended Plan / {{recommended_plan}}"; Section 4 banner likewise (md + html) - source-of-truth notes now point to the Phase 3 company context (sanitized: no fit scores, no firmographics), with recommended_plan / a4aa_yes_no derived from use case + findings + auth0-pricing.md; corrected the flat-array report-shape note Passes `uvx skillsaw --strict` (0 errors, 0 warnings). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
diff --git a/plugins/auth0/skills/auth0-checkmate/references/auth0-cli-readme.md b/plugins/auth0/skills/auth0-checkmate/references/auth0-cli-readme.md
@@ -35,13 +35,17 @@ brew tap auth0/auth0-cli && brew install auth0
 Install via [cURL](https://curl.se/):
 
 1. Download the binary. It will be placed in `./auth0`:
+
    ```bash
    curl -sSfL https://raw.githubusercontent.com/auth0/auth0-cli/main/install.sh | sh -s -- -b .
    ```
+
 2. Optionally, if you want to be able to run the binary from any directory, make sure you move it to a place in your `$PATH`:
+
    ```bash
    sudo mv ./auth0 /usr/local/bin
    ```
+
    > **Tip:** On macOS, depending on the state of your current development environment you may have to first create the directory with `sudo mkdir -p /usr/local/bin`. Alternatively, you can move it to a directory of your choice and add that directory to your `$PATH`.
 
 ### Windows
@@ -56,17 +60,22 @@ scoop install auth0
 Install via [PowerShell](https://learn.microsoft.com/en-us/powershell/):
 
 1. Fetch latest release information with the following commands:
+
    ```powershell
    $latestRelease = Invoke-RestMethod -Uri "https://api.github.com/repos/auth0/auth0-cli/releases/latest"
    $latestVersion = $latestRelease.tag_name
    $version = $latestVersion -replace "^v"
    ```
+
 2. Download the binary to the current folder:
+
    ```powershell
    Invoke-WebRequest -Uri "https://github.com/auth0/auth0-cli/releases/download/${latestVersion}/auth0-cli_${version}_Windows_x86_64.zip" -OutFile ".\auth0.zip"
    Expand-Archive ".\auth0.zip" .\
    ```
+
 3. To be able to run the binary from any directory, add it to your `$PATH`:
+
    ```powershell
    [System.Environment]::SetEnvironmentVariable('PATH', $Env:PATH + ";${pwd}")
    ```
@@ -116,7 +125,7 @@ auth0 login --domain <domain> --client-id <client-id> --client-assertion-private
 
 When your access token expires, the CLI will prompt you to confirm whether to continue with your default tenant or select a different one:
 
-```
+```text
 Continue login with default tenant 'your-tenant.auth0.com'? [y/N]
 ```
 
@@ -203,7 +212,7 @@ The `auth0-cli` skill is part of the [auth0/agent-skills](https://github.com/aut
 
 **Claude Code plugin marketplace:**
 
-```
+```text
 /plugin marketplace add auth0/agent-skills
 /plugin install auth0@auth0-agent-skills
 ```
diff --git a/plugins/auth0/skills/auth0-checkmate/references/report-template.html b/plugins/auth0/skills/auth0-checkmate/references/report-template.html
@@ -1,9 +1,9 @@
 <!DOCTYPE html>
 <!--
   Locked HTML report template for the auth0-checkmate skill.
-  Phase 5 substitutes every {{placeholder}} with the same data feeding report-template.md.
+  Phase 5 substitutes every placeholder token with the same data feeding report-template.md.
   Visual design models the "Auth0 Platform Development Review" reference layout (orange brand accent, severity-coded chips, four-section structure).
-  Render to PDF with bin/render_pdf.sh (Chrome headless).
+  Render to PDF with scripts/render_pdf.sh (Chrome headless).
 -->
 <html lang="en">
 <head>
@@ -219,7 +219,7 @@
 <header class="header">
   <div>
     <h1>Auth0 Platform<br>Development Review</h1>
-    {{subtitle_html}}  <!-- '<div class="subtitle">Prepared by {{reviewer_org}}</div>' if reviewer_org is non-empty; emit empty string otherwise -->
+    {{subtitle_html}}  <!-- a subtitle div reading "Prepared by <org>" if reviewer_org is non-empty; emit empty string otherwise -->
   </div>
   <div class="header-right">
     <span class="plan-badge">{{plan_tag}}</span>
@@ -234,7 +234,7 @@ <h1>Auth0 Platform<br>Development Review</h1>
   <tr><th>Customer Account</th><td>{{customer_name}} ({{tenant_domain}})</td></tr>
   <tr><th>Current Auth0 Tier</th><td>{{tier}}</td></tr>
   <tr><th>Use Case Diagnosis</th><td>{{business_model}} — {{product_summary_short}}</td></tr>
-  <tr><th>Auth0 Fit</th><td>{{auth0_plan_recommendation}} · Auth for AI Agents: {{a4aa_yes_no}}</td></tr>
+  <tr><th>Recommended Plan</th><td>{{recommended_plan}} · Auth for AI Agents: {{a4aa_yes_no}}</td></tr>
 </table>
 
 <h2 class="section">1. Account Health</h2>
@@ -258,9 +258,8 @@ <h2 class="section">1. Account Health</h2>
   </tbody>
 </table>
 
-<!-- gaps_html: rendered from the included gap callouts. Each block:
-<div class="gap"><div class="gap-name">{{gap_name}}</div><p>{{gap_body}}</p></div>
-Only include gaps the data supports. -->
+<!-- gaps_html: rendered from the included gap callouts. Each block is a gap div with a
+     gap-name heading and a one-line body paragraph. Only include gaps the data supports. -->
 {{gaps_html}}
 
 <h2 class="section">2. Executive Summary</h2>
@@ -288,42 +287,36 @@ <h2 class="section">3. Strategic Opportunities &amp; Action Plan</h2>
     <tr><th>Feature Area</th><th>The Enterprise Challenge</th><th>The Solution</th><th>Strategic Impact</th></tr>
   </thead>
   <tbody>
-    <!-- opportunities_rows: one <tr> per included row. Template:
-    <tr>
-      <td class="feature">{{feature_area}}</td>
-      <td class="challenge">{{challenge_personalized}}</td>
-      <td class="solution">{{solution_label}}</td>
-      <td class="impact">{{strategic_impact}}</td>
-    </tr>
-    Every challenge cell MUST name a specific product, segment, or capability from enrichment.
-    -->
+    <!-- opportunities_rows: one table row per included row — feature area, a personalized
+         challenge cell, the solution label, and the strategic impact. Every challenge cell
+         MUST name a specific product, segment, or capability from the company context. -->
     {{opportunities_rows}}
   </tbody>
 </table>
 
 <h2 class="section">4. Recommended Roadmap &amp; Next Steps</h2>
 
-<p class="roadmap-banner">Recommended Plan: <em>{{auth0_plan_recommendation}}{{a4aa_addon_suffix}}</em></p>
+<p class="roadmap-banner">Recommended Plan: <em>{{recommended_plan}}{{a4aa_addon_suffix}}</em></p>
 
 <div class="roadmap">
   {{plan_recommendation_paragraphs_html}}
 </div>
 
 <p><strong>Immediate Actions — Available Today (Free)</strong></p>
 <ol class="actions">
-  <!-- immediate_actions_html: <li>{{action_text}}</li> per item. Each must name affected apps/connections explicitly. -->
+  <!-- immediate_actions_html: one list item per item. Each must name affected apps/connections explicitly. -->
   {{immediate_actions_html}}
 </ol>
 
 <p><strong>After Upgrading</strong></p>
 <ol class="actions">
-  <!-- after_upgrading_html: <li>{{action_text}}</li> per item. -->
+  <!-- after_upgrading_html: one list item per item. -->
   {{after_upgrading_html}}
 </ol>
 
 <p><strong>Key Documentation</strong></p>
 <div class="docs">
-  <!-- docs_html: <a href="{{url}}">{{label}}</a> per included row. Match Section 3 rows. -->
+  <!-- docs_html: one anchor link per included row. Match Section 3 rows. -->
   {{docs_html}}
 </div>
 
diff --git a/plugins/auth0/skills/auth0-checkmate/references/report-template.md b/plugins/auth0/skills/auth0-checkmate/references/report-template.md
@@ -1,22 +1,23 @@
 # Locked report skeleton (Auth0 Platform Development Review)
 
-This is the structural contract Phase 5 of the `auth0-checkmate` skill follows for the markdown brief. The HTML/PDF render uses the parallel template at [report-template.html](report-template.html) — same data, same sections, different presentation. Replace every `{{placeholder}}` with values from CheckMate JSON / enrichment JSON / tenant facts. Visual design models the "Auth0 Platform Development Review" reference layout (orange brand accent, severity-coded chips, four-section structure).
-
-Source-of-truth reminders (see SKILL.md Phase 5):
-- `{{tenant_domain}}` → `state/setup.json.tenant_domain` (from `auth0 tenants list --json`)
-- `{{customer_name}}`, `{{product_*}}`, `{{business_model}}`, `{{ai_use_case}}`, `{{auth0_plan_recommendation}}`, `{{a4aa_fit_score}}`, `{{integrations_*}}` → enrichment JSON
-- `{{reviewer_name}}`, `{{reviewer_org}}` → `state/operator.json.reviewer_name` / `.reviewer_org`
-- `{{plan_tag}}`, `{{tier}}` → `auth0 api get tenants/settings` (fallback "Free Plan")
-- `{{apps_count}}`, `{{apps_*}}` → `auth0 apps list --json`
-- `{{login_activity}}` → derived from `auth0 logs list --number 50`
-- `{{custom_domains_present}}`, `{{log_streams_present}}`, `{{mfa_configured}}`, etc. → tenant facts from Phase 4.4
-- `{{findings_*_count}}`, `{{findings_*_examples}}` → CheckMate `data.report.summary[]` grouped by severity
+This is the structural contract Phase 5 of the `auth0-checkmate` skill follows for the markdown brief. The HTML/PDF render uses the parallel template at [report-template.html](report-template.html) — same data, same sections, different presentation. Replace every placeholder token with values from the CheckMate report, the lightweight company context (Phase 3), and tenant facts. Visual design models the "Auth0 Platform Development Review" reference layout (orange brand accent, severity-coded chips, four-section structure).
+
+Source-of-truth reminders (see SKILL.md Phase 5) — placeholder → source:
+- tenant_domain → `state/setup.json.tenant_domain` (from `auth0 tenants list --json`); never from the company context
+- customer_name, product_*, business_model, ai_use_case, integrations_* → the company context (Phase 3; sanitized — no fit scores, no firmographics)
+- recommended_plan, a4aa_yes_no → DERIVED in Phase 4 from the use case + the findings + `auth0-pricing.md` (never a company score)
+- reviewer_name, reviewer_org → `state/operator.json.reviewer_name` / `.reviewer_org`
+- plan_tag, tier → `auth0 api get tenants/settings` (fallback "Free Plan")
+- apps_count, apps_* → `auth0 apps list --json`
+- login_activity → derived from `auth0 logs list --number 50`
+- custom_domains_present, log_streams_present, mfa_configured, etc. → tenant facts from Phase 4.4
+- findings_*_count, findings_*_examples → the CheckMate report (a flat array of finding objects), grouped by severity
 
 ---
 
 # Auth0 Platform Development Review
 
-{{prepared_by_line}}  <!-- "**Prepared by {{reviewer_org}}**" if reviewer_org is non-empty; OMIT this line entirely otherwise -->
+{{prepared_by_line}}  <!-- the "Prepared by <org>" line if reviewer_org is non-empty; OMIT this line entirely otherwise -->
 
 > **{{plan_tag}}** · {{customer_name}} · {{tenant_domain}} · {{review_date_long}}
 
@@ -27,7 +28,7 @@ Source-of-truth reminders (see SKILL.md Phase 5):
 | **Customer Account** | {{customer_name}} ({{tenant_domain}}) |
 | **Current Auth0 Tier** | {{tier}} |
 | **Use Case Diagnosis** | {{business_model}} — {{product_summary_short}} |
-| **Auth0 Fit** | {{auth0_plan_recommendation}} · Auth for AI Agents: {{a4aa_yes_no}} |
+| **Recommended Plan** | {{recommended_plan}} · Auth for AI Agents: {{a4aa_yes_no}} |
 
 ---
 
@@ -99,7 +100,7 @@ Include only the rows whose triggers are met. Rewrite the cell text to reference
 
 ## 4. RECOMMENDED ROADMAP & NEXT STEPS
 
-### Recommended Plan: **{{auth0_plan_recommendation}}**{{a4aa_addon_suffix}}
+### Recommended Plan: **{{recommended_plan}}**{{a4aa_addon_suffix}}
 
 {{plan_recommendation_paragraph}}
 
diff --git a/plugins/auth0/skills/auth0-checkmate/scripts/render_pdf.sh b/plugins/auth0/skills/auth0-checkmate/scripts/render_pdf.sh
@@ -82,23 +82,29 @@ done
 
 if [[ -n "$CHROME" ]]; then
   echo "render_pdf: using $CHROME" >&2
+  # Render to a temp file and only promote it on success — a stale PDF already
+  # sitting at OUTPUT_ABS must never be mistaken for a fresh, successful render.
+  TMP_PDF="$(mktemp -t render_pdf.XXXXXX 2>/dev/null || echo "${OUTPUT_ABS}.tmp.$$")"
   "$CHROME" \
     --headless=new \
     --disable-gpu \
     --no-pdf-header-footer \
-    --print-to-pdf="$OUTPUT_ABS" \
+    --print-to-pdf="$TMP_PDF" \
     "file://$INPUT_ABS" \
     >/dev/null 2>&1 \
     || "$CHROME" \
       --headless \
       --disable-gpu \
-      --print-to-pdf="$OUTPUT_ABS" \
+      --print-to-pdf="$TMP_PDF" \
       "file://$INPUT_ABS" \
       >/dev/null 2>&1 || true
-  if [[ -f "$OUTPUT_ABS" ]]; then
+  if [[ -s "$TMP_PDF" ]]; then
+    mv -f "$TMP_PDF" "$OUTPUT_ABS"
     echo "render_pdf: wrote $OUTPUT_ABS" >&2
     exit 0
   fi
+  rm -f "$TMP_PDF"
+  echo "render_pdf: Chrome produced no output; trying other renderers" >&2
 fi
 
 if command -v wkhtmltopdf >/dev/null 2>&1; then
