feat(154): deterministic Gemini prompt scaffold for infographic quality stability

Root cause (5 Whys): infographic image quality degraded because the agent
rewrote the template's fixed visual directives (dark navy background,
severity colors, typography) when constructing the Gemini prompt. The
architecture split data extraction (deterministic) from prompt construction
(fully LLM-driven) with no guardrails on the styling scaffold.

Option D implementation: the Python extraction script now reads each
template file, extracts the Gemini prompt section, and splits it at the
"DATA CONTENT" marker into a locked preamble (opening aesthetic + IMPORTANT
note + STYLING DIRECTIVES) and postamble (FOOTER + closing). These go into
the JSON output as `prompt_scaffold.preamble` and `prompt_scaffold.postamble`.

The agent instructions now require VERBATIM use of the scaffold — the agent
fills only the DATA CONTENT sections from JSON data. This locks the visual
design (dark navy, 3D effects, severity colors) while preserving LLM
flexibility for data narrative descriptions.

Changes:
- scripts/extract-infographic-data.py: add extract_prompt_scaffold() that
  reads template files and splits at "DATA CONTENT (render this" marker,
  include prompt_scaffold in JSON output via build_json_output()
- .claude/agents/tachi/threat-infographic.md: add "Gemini Prompt
  Construction — Scaffold" section with MANDATORY verbatim-use protocol
- .claude/skills/tachi-infographics/references/gemini-prompt-construction.md:
  replace "Design Template Loading" with "Prompt Scaffold (Option D)"
  protocol, document preamble/postamble usage, add fallback for templates
  without scaffolds (executive-architecture)
- Golden baselines regenerated for all 5 templates
- 47/47 tests pass

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: davidmatousek

.claude/agents/tachi/threat-infographic.md

@@ -215,10 +215,16 @@ The script outputs a JSON file with this top-level structure:
   "top_findings": [
     { "id": "S-001", "component": "API Gateway", "threat": "...", "risk_level": "Critical", "score": 9.2 }
   ],
-  "template_data": { }
+  "template_data": { },
+  "prompt_scaffold": {
+    "preamble": "Create a premium, professional... [locked styling scaffold]",
+    "postamble": "FOOTER: ... [locked closing statement]"
+  }
 }
 ```
 
+When `prompt_scaffold` is present, it contains the **locked visual design directives** extracted from the infographic template file. See "Gemini Prompt Construction — Scaffold" below for how to use it.
+
 The complete JSON schema is defined in `specs/071-deterministic-infographic-extraction/data-model.md`. The `template_data` object varies by template -- see the data model for `baseball-card`, `system-architecture`, and `risk-funnel` schemas.
 
 ---
@@ -235,6 +241,20 @@ The output `threat-{template-name}-spec.md` contains YAML frontmatter and 6 requ
 
 ---
 
+## Gemini Prompt Construction — Scaffold
+
+**MANDATORY**: Read `.claude/skills/tachi-infographics/references/gemini-prompt-construction.md` Section "Design Template Loading — Prompt Scaffold (Option D)" for the full protocol.
+
+When the JSON output contains a `prompt_scaffold` object, you **MUST** use it:
+
+1. **Copy `prompt_scaffold.preamble` VERBATIM** — do NOT rewrite any part of it (background color, styling directives, aesthetic target are LOCKED)
+2. **Write DATA CONTENT sections** from JSON data (severity counts, findings, heat map, scores) — this is where you have creative flexibility
+3. **Copy `prompt_scaffold.postamble` VERBATIM** — do NOT rewrite the footer or closing statement
+
+This ensures every run uses the same dark-navy (or template-appropriate) background, severity colors, and layout directives. Without the scaffold, previous runs produced white-background flat images instead of the premium dark-themed 3D visuals.
+
+---
+
 ## Executive-Architecture Gemini Prompt Construction
 
 When generating the `threat-executive-architecture.jpg` image via Gemini API, the prompt MUST instruct Gemini to:

.claude/skills/tachi-infographics/references/gemini-prompt-construction.md

@@ -4,11 +4,33 @@ Rules and patterns for constructing Gemini API image generation prompts from inf
 
 ---
 
-## Design Template Loading
+## Design Template Loading — Prompt Scaffold (Option D)
 
-After generating the specification (`threat-{template-name}-spec.md`), construct a Gemini image generation prompt using the active design template.
+The extraction script (`scripts/extract-infographic-data.py`) outputs a `prompt_scaffold` object in the JSON with two fields:
+- **`preamble`**: the opening aesthetic instruction, IMPORTANT note, and STYLING DIRECTIVES block — everything up to and including the "DATA CONTENT (render this as visible text):" header.
+- **`postamble`**: the FOOTER specification and closing aesthetic instruction.
 
-### Template Location
+### MANDATORY: Use Scaffold Verbatim
+
+When `prompt_scaffold` is present in the JSON output, you **MUST** construct the Gemini prompt by:
+
+1. **Copy `prompt_scaffold.preamble` VERBATIM** as the start of the prompt. Do NOT rewrite, paraphrase, or modify ANY part of it — the background color, styling directives, layout instructions, and aesthetic target are locked.
+2. **Write the DATA CONTENT sections** using data from the JSON (severity counts, findings, heat map grid, etc.). This is the ONLY section where you have creative control.
+3. **Copy `prompt_scaffold.postamble` VERBATIM** as the end of the prompt. Do NOT rewrite the footer text or closing instructions.
+
+```
+[preamble — VERBATIM from JSON, includes opening + IMPORTANT + STYLING DIRECTIVES + "DATA CONTENT" header]
+
+[Your DATA CONTENT sections — written from JSON data, with specific counts, scores, finding descriptions]
+
+[postamble — VERBATIM from JSON, includes FOOTER + closing aesthetic instruction]
+```
+
+**Why this matters**: The scaffold locks the visual design (dark navy background, severity colors, typography, layout). Previous runs where the agent rewrote the scaffold produced white-background flat images instead of the premium dark-themed 3D visuals the templates specify.
+
+### Fallback (no scaffold)
+
+If `prompt_scaffold` is NOT present in the JSON (e.g., executive-architecture template, or older script version):
 
 Load `templates/tachi/infographics/infographic-{name}.md` and use its **Gemini Prompt Template** section. Replace all `{placeholders}` with actual data from the infographic spec.
 

scripts/extract-infographic-data.py

@@ -78,6 +78,125 @@ def _canonical_severity(finding):
     return ""
 
 
+# =============================================================================
+# Gemini Prompt Scaffold Extraction
+# =============================================================================
+
+# Templates that have a Gemini prompt section with the standard
+# PREAMBLE → DATA CONTENT → POSTAMBLE structure.
+_SCAFFOLD_TEMPLATES = frozenset({
+    "baseball-card", "risk-funnel", "system-architecture",
+    "maestro-stack", "maestro-heatmap",
+})
+
+_TEMPLATE_FILES = {
+    "baseball-card": "infographic-baseball-card.md",
+    "risk-funnel": "infographic-risk-funnel.md",
+    "system-architecture": "infographic-system-architecture.md",
+    "maestro-stack": "infographic-maestro-stack.md",
+    "maestro-heatmap": "infographic-maestro-heatmap.md",
+}
+
+
+def extract_prompt_scaffold(template_name: str, repo_root: Path = None) -> dict:
+    """Extract the fixed Gemini prompt scaffold from an infographic template.
+
+    Reads the template file, locates the Gemini prompt section (between
+    triple-backtick fences), and splits it at the "DATA CONTENT" marker.
+
+    Returns:
+        Dict with:
+        - preamble: everything from prompt start through "DATA CONTENT (render
+          this as visible text):" — includes opening aesthetic instruction,
+          IMPORTANT note, and STYLING DIRECTIVES block.
+        - postamble: the FOOTER line through the closing aesthetic instruction.
+        - found: True if scaffold was successfully extracted.
+
+    If the template file or prompt section is not found, returns
+    found=False with empty strings (graceful degradation — agent falls
+    back to its own prompt construction).
+    """
+    result = {"preamble": "", "postamble": "", "found": False}
+
+    if template_name not in _SCAFFOLD_TEMPLATES:
+        return result
+
+    if repo_root is None:
+        repo_root = Path(__file__).resolve().parent.parent
+
+    template_path = repo_root / "templates" / "tachi" / "infographics" / _TEMPLATE_FILES[template_name]
+    if not template_path.exists():
+        return result
+
+    content = template_path.read_text(encoding="utf-8")
+
+    # Extract the Gemini prompt block (first triple-backtick fence after
+    # a heading containing "Gemini" and "Prompt")
+    prompt_text = None
+    lines = content.split("\n")
+    in_prompt_section = False
+    in_fence = False
+    fence_lines = []
+
+    for line in lines:
+        stripped = line.strip()
+        if re.match(r"^#{1,4}\s+.*[Gg]emini.*[Pp]rompt", stripped):
+            in_prompt_section = True
+            continue
+        if in_prompt_section and not in_fence and stripped.startswith("```"):
+            in_fence = True
+            continue
+        if in_fence and stripped.startswith("```"):
+            prompt_text = "\n".join(fence_lines)
+            break
+        if in_fence:
+            fence_lines.append(line)
+
+    if not prompt_text:
+        return result
+
+    # Split at the standalone "DATA CONTENT" section marker.
+    # The phrase "DATA CONTENT" also appears inside the IMPORTANT note
+    # ("...specified in the DATA CONTENT sections."), so we match the
+    # full section header form to avoid a false-positive split.
+    data_marker = "DATA CONTENT (render this"
+    marker_idx = prompt_text.find(data_marker)
+    if marker_idx == -1:
+        # Fallback: try bare marker at start of line
+        for m in re.finditer(r"^DATA CONTENT", prompt_text, re.MULTILINE):
+            # Skip if this is the IMPORTANT note reference
+            line_end = prompt_text.find("\n", m.start())
+            line = prompt_text[m.start():line_end if line_end != -1 else len(prompt_text)]
+            if "sections." not in line:
+                marker_idx = m.start()
+                break
+    if marker_idx == -1:
+        return result
+
+    # Find the full marker line end
+    marker_line_end = prompt_text.find("\n", marker_idx)
+    if marker_line_end == -1:
+        marker_line_end = len(prompt_text)
+
+    preamble = prompt_text[:marker_line_end + 1].rstrip() + "\n"
+
+    # Postamble: from "FOOTER" to end of prompt
+    footer_marker = "\nFOOTER"
+    footer_idx = prompt_text.find(footer_marker)
+    if footer_idx == -1:
+        # Try without leading newline
+        footer_idx = prompt_text.find("FOOTER")
+    if footer_idx != -1:
+        postamble = prompt_text[footer_idx:].strip()
+    else:
+        postamble = ""
+
+    result["preamble"] = preamble
+    result["postamble"] = postamble
+    result["found"] = True
+    return result
+
+
 # =============================================================================
 # T009: Largest Remainder Method
 # =============================================================================
@@ -1395,6 +1514,10 @@ def build_json_output(data, template):
     if "delta" in data:
         output["delta"] = data["delta"]
 
+    # Add prompt scaffold when extracted from template
+    if "prompt_scaffold" in data:
+        output["prompt_scaffold"] = data["prompt_scaffold"]
+
     # Add template to metadata
     output["metadata"]["template"] = template
 
@@ -1611,6 +1734,14 @@ def main():
             "delta_counts": compute_delta_counts(findings, resolved),
         }
 
+    # Extract prompt scaffold from template file (Option D: locked styling,
+    # flexible data narrative). The scaffold contains the opening aesthetic
+    # instruction, STYLING DIRECTIVES, and closing statement — all the fixed
+    # visual directives that must not be rewritten by the agent.
+    scaffold = extract_prompt_scaffold(args.template)
+    if scaffold["found"]:
+        print(f"Prompt scaffold extracted from template ({args.template})", file=sys.stderr)
+
     # Assemble data dict
     data = {
         "metadata": metadata,
@@ -1620,6 +1751,11 @@ def main():
         "findings_ids": findings_ids,
         "template_data": template_data,
     }
+    if scaffold["found"]:
+        data["prompt_scaffold"] = {
+            "preamble": scaffold["preamble"],
+            "postamble": scaffold["postamble"],
+        }
     if delta_data:
         data["delta"] = delta_data
 

tests/scripts/fixtures/golden/baseball-card.json

@@ -69,6 +69,10 @@
     "tier": 1,
     "total_findings": 34
   },
+  "prompt_scaffold": {
+    "postamble": "FOOTER: \"Generated by Tachi Threat Modeling Framework \u2014 STRIDE + AI Threat Analysis\" in small light gray text, centered.\n\nThe overall impression should be a polished professional report \u2014 confident, clear, and visually sophisticated. No hex codes, color values, or technical specifications should appear as visible text. Render the dashboard as a flat, full-bleed graphic filling the entire 16:9 frame. No perspective, no 3D, no boardroom, no table, no environmental context.",
+    "preamble": "Create a premium, professional security risk dashboard with a polished, modern dark-theme aesthetic. This should look like a professionally designed Figma dashboard \u2014 not a data table or spreadsheet. The overall feel should be confident, sophisticated, and visually impressive \u2014 a formal security report artifact, not a presentation slide or boardroom scene. Render ONLY the dashboard itself as a flat document \u2014 no perspective, no 3D effects, no room or table context, no environmental background. The image should be the report, not a photo of the report.\n\nIMPORTANT: The styling directives below are for your interpretation only. Do NOT render any hex color codes, pixel values, font sizes, or technical CSS specifications as visible text in the image. Only render the data labels, numbers, and natural-language text specified in the DATA CONTENT sections.\n\nSTYLING DIRECTIVES (interpret these, do not display them):\n- Background: dark navy\n- Severity color mapping: Critical = red, High = orange, Medium = amber/yellow, Low = blue\n- All text on dark background: white or light gray\n- Cards and panels: rounded corners, subtle drop shadows, generous whitespace\n- Layout: 16:9 landscape\n- Empty heat map cells: subtle dark gray\n\nDATA CONTENT (render this as visible text):\n"
+  },
   "severity_distribution": [
     {
       "color": "#DC2626",

tests/scripts/fixtures/golden/maestro-heatmap.json

@@ -69,6 +69,10 @@
     "tier": 1,
     "total_findings": 34
   },
+  "prompt_scaffold": {
+    "postamble": "FOOTER: \"Generated by Tachi Threat Modeling Framework \u2014 CSA MAESTRO Layer Analysis\" in small light gray text, centered.\n\nThe overall impression should be a polished professional report \u2014 confident, clear, and visually sophisticated. No hex codes, color values, or technical specifications should appear as visible text. Render the dashboard as a flat, full-bleed graphic filling the entire 16:9 frame. No perspective, no 3D, no boardroom, no table, no environmental context.",
+    "preamble": "Create a premium, professional MAESTRO component-layer heatmap dashboard with a polished, modern dark-theme aesthetic. This should look like a professionally designed Figma dashboard \u2014 not a data table or spreadsheet. The overall feel should be confident, sophisticated, and visually impressive \u2014 a formal security report artifact, not a presentation slide or boardroom scene. Render ONLY the dashboard itself as a flat document \u2014 no perspective, no 3D effects, no room or table context, no environmental background. The image should be the report, not a photo of the report.\n\nIMPORTANT: The styling directives below are for your interpretation only. Do NOT render any hex color codes, pixel values, font sizes, or technical CSS specifications as visible text in the image. Only render the data labels, numbers, and natural-language text specified in the DATA CONTENT sections.\n\nSTYLING DIRECTIVES (interpret these, do not display them):\n- Background: dark navy\n- Severity color mapping: Critical = red, High = orange, Medium = amber/yellow, Low = blue\n- Empty grid cells: subtle dark gray rounded rectangles\n- All text on dark background: white or light gray\n- Grid cells: rounded rectangles with generous padding\n- Legend panel: right side, visually distinct section with color swatches\n- Layout: 16:9 landscape\n\nDATA CONTENT (render this as visible text):\n"
+  },
   "severity_distribution": [
     {
       "color": "#DC2626",

tests/scripts/fixtures/golden/maestro-stack.json

@@ -69,6 +69,10 @@
     "tier": 1,
     "total_findings": 34
   },
+  "prompt_scaffold": {
+    "postamble": "FOOTER: \"Generated by Tachi Threat Modeling Framework \u2014 CSA MAESTRO Layer Analysis\" in small light gray text, centered.\n\nThe overall impression should be a polished professional report \u2014 confident, clear, and visually sophisticated. No hex codes, color values, or technical specifications should appear as visible text. Render the dashboard as a flat, full-bleed graphic filling the entire 16:9 frame. No perspective, no 3D, no boardroom, no table, no environmental context.",
+    "preamble": "Create a premium, professional security risk dashboard with a polished, modern dark-theme aesthetic. This should look like a professionally designed Figma dashboard \u2014 not a data table or spreadsheet. The overall feel should be confident, sophisticated, and visually impressive \u2014 a formal security report artifact, not a presentation slide or boardroom scene. Render ONLY the dashboard itself as a flat document \u2014 no perspective, no 3D effects, no room or table context, no environmental background. The image should be the report, not a photo of the report.\n\nIMPORTANT: The styling directives below are for your interpretation only. Do NOT render any hex color codes, pixel values, font sizes, or technical CSS specifications as visible text in the image. Only render the data labels, numbers, and natural-language text specified in the DATA CONTENT sections.\n\nSTYLING DIRECTIVES (interpret these, do not display them):\n- Background: dark navy\n- Severity color mapping: Critical = red, High = orange, Medium = amber/yellow, Low = blue\n- All text on dark background: white or light gray\n- Cards and bands: rounded corners, subtle drop shadows, generous whitespace\n- Layout: 16:9 landscape, 3-zone (top header, main body split into stack + sidebar, footer)\n- Layer bands: horizontal bars stacked vertically, L7 at top through L1 at bottom\n- Most-exposed layer band: brighter background, wider left border accent\n- Empty layer bands: muted, darker background, grayed text\n\nDATA CONTENT (render this as visible text):\n"
+  },
   "severity_distribution": [
     {
       "color": "#DC2626",

tests/scripts/fixtures/golden/risk-funnel.json

@@ -69,6 +69,10 @@
     "tier": 1,
     "total_findings": 34
   },
+  "prompt_scaffold": {
+    "postamble": "FOOTER (bottom): \"Generated by Tachi Threat Modeling Framework \u2014 Risk Reduction Funnel\" in small light gray text, centered.\n\nThe overall impression should be a polished, premium risk reduction narrative \u2014 confident, clear, and visually sophisticated. Professional business language throughout, no technical jargon or color codes. Render as a flat, full-bleed graphic filling the entire 16:9 frame.",
+    "preamble": "Create a premium, photorealistic 3D risk reduction funnel with glass-like translucent material, soft ambient lighting, and executive boardroom quality. This should look like a professionally designed data visualization for a CISO's board presentation \u2014 sophisticated, confident, and visually impressive. Render ONLY the infographic itself as a flat document \u2014 no perspective, no room context, no environmental background.\n\nIMPORTANT: The styling directives below are for your interpretation only. Do NOT render any hex color codes, pixel values, font sizes, percentages-of-height, or technical CSS specifications as visible text in the image. Only render the data labels, numbers, and natural-language text specified in the DATA CONTENT sections.\n\nSTYLING DIRECTIVES (interpret these, do not display them):\n- Background: dark navy\n- Severity color mapping: Critical = red, High = orange, Medium = amber/yellow, Low = blue\n- Ghost tier style: translucent gray with dashed border\n- All text on dark background: white or light gray\n- Panels: rounded corners, subtle drop shadows, generous whitespace\n- Layout: 16:9 landscape, premium executive aesthetic\n- Funnel tiers: translucent 3D trapezoids with glass-like material, soft ambient lighting, gradient connectors between tiers\n- CONFIDENTIAL badge: red pill with white text\n\nDATA CONTENT (render this as visible text):\n"
+  },
   "severity_distribution": [
     {
       "color": "#DC2626",