fix(154): PDF report — attack trees, MAESTRO headings, landscape whitespace (#155)

Three downstream rendering bugs surfaced in second-brain-mcp's generated
security-report.pdf. Two share a root cause; one is an independent template
bug.

Root cause A — scripts/ missing from INSTALL_MANIFEST.md
The install manifest never distributed scripts/extract-report-data.py,
scripts/extract-infographic-data.py, or scripts/tachi_parsers.py to target
projects. When /tachi.security-report ran in a downstream project, the
report-assembler agent's `python3 scripts/extract-report-data.py` invocation
failed silently and the agent fell through to a legacy LLM-based inline
extraction path, producing report-data.typ with has-image: false on every
attack-tree entry (skipping the Mermaid visuals) and empty layer-id /
layer-name on MAESTRO findings-by-layer groups (collapsing headings to bare
"—"). The PDF compiled cleanly, so failures were invisible to users.

Fixes for root cause A:
- INSTALL_MANIFEST.md: add scripts/extract-report-data.py,
  scripts/extract-infographic-data.py, scripts/tachi_parsers.py to both the
  human-readable Distributable Directories table and the machine-parseable
  <!-- BEGIN MANIFEST --> section. Add a new "Script Files" section
  documenting the distribution requirement and explicitly flagging the
  silent-failure mode so it cannot recur.
- .claude/agents/tachi/report-assembler.md: add a mandatory Step 2b
  preflight check (`test -f scripts/extract-report-data.py && test -f
  scripts/tachi_parsers.py`) that hard-fails with an install.sh pointer
  when the scripts are missing. Renumber subsequent steps (old 2b to 2c,
  old 2c to 2d, old 2d to 2e). Add exit code 127 to the exit-code table.
  Rewrite the legacy-reference paragraph as a "Deprecated inline extraction
  path — DO NOT USE" warning that enumerates the observed failure modes
  (missing has-image, empty MAESTRO fields).
- .claude/agents/tachi/threat-infographic.md: add a symmetric preflight
  check for scripts/extract-infographic-data.py and scripts/tachi_parsers.py.

Root cause B — landscape infographic whitespace
Feature 128 introduced a fixed-height 7.5in block in full-bleed.typ's
infographic-page() to accommodate the portrait executive-architecture
infographic (912x1168). Landscape 1376x768 infographics (risk-funnel,
baseball-card, system-architecture, maestro-stack, maestro-heatmap) scale
to ~3.6in tall and were vertically centered inside the 7.5in block by
`fit: "contain"`, producing ~1.9in of wasted whitespace above and below the
image with the border stretched around the dead space.

Fix for root cause B:
- templates/tachi/security-report/full-bleed.typ: add is-portrait parameter
  (default false). For landscape, use a block with width: 100% and no
  height constraint so the block hugs the image's natural aspect height.
  For portrait, keep the 7.5in height cap to prevent overflow and center
  the block horizontally via align(). Both paths use inset: 0pt so the
  border wraps tightly around the image.
- templates/tachi/security-report/main.typ: pass is-portrait: true only to
  the executive-architecture infographic-page call; all other landscape
  calls keep the default.

Verification:
- examples/agentic-app/sample-report/security-report.pdf regenerated
  (SOURCE_DATE_EPOCH=1700000000) — executive-architecture portrait page
  and five landscape infographic pages all render with tight borders and
  no dead whitespace; MAESTRO Layer Analysis headings show full canonical
  names (L1 Foundation Model, L5 Evaluation and Observability, etc.);
  17/17 attack tree Mermaid PNGs rendered inline on their respective
  Attack Path Analysis pages.
- All 47 tests in tests/scripts/ pass.
- All 5 backward-compat baselines remain byte-identical under the
  preserved SOURCE_DATE_EPOCH=1700000000 contract (web-app, microservices,
  ascii-web-api, mermaid-agentic-app, free-text-microservice): none of
  these examples use infographic-page() so the template change has no
  rendering side effect, and the unchanged main.typ call sites produce
  identical compiled output.

Closes #154

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

Author: davidmatousek

.claude/agents/tachi/report-assembler.md

@@ -117,7 +117,40 @@ Check for a user-provided `report-config.typ` in the target directory:
    - Ensure the default `templates/tachi/security-report/report-config.typ` exists (it ships with the templates)
    - Log: `"Using default report configuration"`
 
-### 2b. Invoke Extraction Script
+### 2b. Preflight: Verify Script Exists
+
+**MANDATORY HARD-FAIL CHECK** — before invoking the extraction script, verify it exists on disk:
+
+```bash
+test -f scripts/extract-report-data.py && test -f scripts/tachi_parsers.py
+```
+
+If either file is missing, abort with this exact error and do NOT fall through to any alternate extraction path:
+
+```
+EXTRACTION SCRIPT MISSING
+
+Required files not found:
+  - scripts/extract-report-data.py
+  - scripts/tachi_parsers.py
+
+These files are distributed by tachi's scripts/install.sh and must exist
+in the project's scripts/ directory. If this project was installed before
+PR #154, re-run the installer:
+
+  ~/Projects/tachi/scripts/install.sh
+
+Or manually copy the missing files from the tachi source tree.
+
+DO NOT generate report-data.typ inline — the deterministic Python
+extraction is the only supported path. LLM-based inline extraction
+silently produces field-incomplete output (missing attack-tree images,
+empty MAESTRO layer headings, missing MAESTRO data).
+```
+
+Return failure to the command. Do NOT proceed to Step 2c, Step 2d, or Step 3 under any circumstances when the scripts are missing.
+
+### 2c. Invoke Extraction Script
 
 Run the deterministic extraction script:
 
@@ -131,23 +164,24 @@ python3 scripts/extract-report-data.py \
 
 Include `--title` only if the command provided a title override.
 
-### 2c. Handle Exit Codes
+### 2d. Handle Exit Codes
 
 | Exit Code | Meaning | Agent Action |
 |-----------|---------|-------------|
 | 0 | Success | Proceed to Step 3 (Compilation) |
 | 1 | Missing required artifact | Display stderr message and abort: `"Error: {message}"` |
 | 2 | Validation failure | Display stderr details and abort: `"Validation error: {details}"` |
+| 127 | `python3` or script not found | Display: `"Error: extraction script invocation failed. Verify scripts/extract-report-data.py is executable and python3 is on PATH. Re-run scripts/install.sh if the script is missing."` and abort |
 
-If the script exits with code 1 or 2, do NOT proceed to compilation. Display the error and return failure to the command.
+If the script exits non-zero for any reason, do NOT proceed to compilation. Do NOT fall back to inline LLM extraction. Display the error and return failure to the command.
 
-### 2d. Report Results
+### 2e. Report Results
 
 Display: `"report-data.typ generated — proceeding to compilation"`
 
 ---
 
-**Legacy reference**: The previous Steps 2-3 performed LLM-based markdown parsing and Typst generation inline. The Python script (`scripts/extract-report-data.py`) replaces this with deterministic regex-based extraction. The Typst variable contract is identical -- all variable names, types, and structure match the templates. For the full variable specification, see `specs/067-deterministic-report-data/data-model.md`.
+**Deprecated inline extraction path — DO NOT USE**: Versions of this agent before PR #154 documented an LLM-based fallback for Steps 2-3 that parsed artifacts inline and generated `report-data.typ` by prompting the model. That path is deprecated and unsupported: it silently omits `has-image` on attack-tree entries (producing attack-path pages with no Mermaid visuals), emits empty `layer-id`/`layer-name` fields in MAESTRO findings-by-layer groups (producing headings that render as bare em-dashes), and skips other derived fields. The deterministic Python script (`scripts/extract-report-data.py`) is the only supported extraction path. For the full variable specification, see `specs/067-deterministic-report-data/data-model.md`.
 
 ---
 

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

@@ -138,6 +138,28 @@ Data extraction is performed by a deterministic Python script that replaces the
 
 ### Script Invocation
 
+**Preflight (MANDATORY)**: Verify the extraction script and its parser helpers exist before invoking:
+
+```bash
+test -f scripts/extract-infographic-data.py && test -f scripts/tachi_parsers.py
+```
+
+If either file is missing, abort with:
+
+```
+EXTRACTION SCRIPT MISSING
+
+Required files not found:
+  - scripts/extract-infographic-data.py
+  - scripts/tachi_parsers.py
+
+Re-run the tachi installer to distribute these files:
+
+  ~/Projects/tachi/scripts/install.sh
+
+DO NOT attempt LLM-based inline extraction as a fallback.
+```
+
 Run the extraction script before generating the specification:
 
 ```bash

INSTALL_MANIFEST.md

@@ -12,6 +12,7 @@ Canonical list of files and directories that must be copied when installing tach
 | `templates/tachi/output-schemas/` | Canonical output format templates | orchestrator, risk-scorer, control-analyzer, threat-report |
 | `templates/tachi/infographics/` | Infographic design templates | threat-infographic |
 | `templates/tachi/security-report/` | Typst PDF report templates | report-assembler |
+| `scripts/` (3 Python files) | Deterministic extraction scripts | report-assembler, threat-infographic |
 | `adapters/claude-code/agents/references/` | SARIF generation and validation guides | risk-scorer, control-analyzer |
 | `brand/` | Logo assets for branded PDF reports | report-assembler |
 | `docs/guides/DEVELOPER_GUIDE_TACHI.md` | Full walkthrough with worked examples | User reference |
@@ -53,6 +54,22 @@ Copy the entire `.claude/agents/tachi/` directory. Current agents:
 | `threat-infographic.md` | Visual infographic generator |
 | `report-assembler.md` | PDF report assembler |
 
+## Script Files
+
+Copy these 3 Python files from `scripts/` to the target project's `scripts/`:
+
+| File | Purpose | Invoked By |
+|------|---------|------------|
+| `extract-report-data.py` | Parses tachi artifacts and generates `report-data.typ` for Typst compilation; also renders attack-tree Mermaid blocks to PNG via mmdc | report-assembler (via `/tachi.security-report`) |
+| `extract-infographic-data.py` | Parses tachi artifacts and generates infographic specification JSON | threat-infographic (via `/tachi.infographic`) |
+| `tachi_parsers.py` | Shared parser helpers imported by both extraction scripts | extract-report-data.py, extract-infographic-data.py |
+
+Scripts use stdlib-only imports — no pip dependencies required in the target project.
+
+**Critical**: If these scripts are missing, the report-assembler and threat-infographic agents will silently fall through to LLM-based inline extraction, producing technically-compiling but field-incomplete outputs (missing attack-tree images, empty MAESTRO layer headings, missing infographic data). Always include these files when distributing tachi.
+
+Other files in `scripts/` (`check.sh`, `install.sh`, `generate-adapter-version.sh`, `polish-release-notes.sh`, `sync-upstream.sh`) are tachi-internal and are NOT distributed to target projects.
+
 ## Schema Files
 
 Copy the entire `schemas/` directory. Current schemas:
@@ -80,6 +97,9 @@ The install script parses this section automatically. One path per line — dire
 .claude/commands/tachi.architecture.md
 schemas/
 templates/tachi/
+scripts/extract-report-data.py
+scripts/extract-infographic-data.py
+scripts/tachi_parsers.py
 adapters/claude-code/agents/references/
 brand/
 docs/guides/DEVELOPER_GUIDE_TACHI.md
@@ -95,6 +115,7 @@ When adding a new feature, check whether it requires updates to:
 - [ ] A new output template in `templates/tachi/output-schemas/`
 - [ ] A new infographic template in `templates/tachi/infographics/`
 - [ ] New report page templates in `templates/tachi/security-report/`
+- [ ] A new distributable Python script in `scripts/` -- add to script table above
 - [ ] New reference docs in `adapters/claude-code/agents/references/`
 - [ ] Update install instructions in `README.md` and `docs/guides/DEVELOPER_GUIDE_TACHI.md`
 - [ ] Update the machine-parseable manifest section (`<!-- BEGIN MANIFEST -->` / `<!-- END MANIFEST -->`)

examples/agentic-app/sample-report/security-report.pdf

@@ -36,12 +36,23 @@
 //   section-name   (content|none) — heading text for the page and TOC.
 //   classification (string|none)  — classification marking for header bar.
 //   description    (content|none) — explanatory text rendered below the image.
+//   is-portrait    (bool)         — true for portrait-aspect images (e.g.,
+//                                    executive-architecture 912×1168); false
+//                                    (default) for landscape 16:9 infographics
+//                                    (1376×768) like risk-funnel, baseball-card,
+//                                    maestro-stack, maestro-heatmap, etc.
+//                                    Landscape images are sized by content
+//                                    width so the border hugs the image and
+//                                    no dead whitespace surrounds it. Portrait
+//                                    images are capped at 7.5in tall to avoid
+//                                    page overflow.
 
 #let infographic-page(
   image-path,
   section-name: none,
   classification: none,
   description: none,
+  is-portrait: false,
 ) = {
   page(
     width: page-width,
@@ -62,19 +73,32 @@
       heading(level: 1)[#section-name]
     }
 
-    // Image with rounded corners and subtle border, proportionally scaled.
-    // Height is constrained so portrait-aspect images (e.g., executive-architecture)
-    // don't overflow onto subsequent pages. `fit: "contain"` preserves aspect ratio
-    // within the 100% x 7.5in bounding box.
-    #block(
-      width: 100%,
-      height: 7.5in,
-      radius: 4pt,
-      clip: true,
-      stroke: 0.5pt + color-rule,
-    )[
-      #image(image-path, width: 100%, height: 100%, fit: "contain")
-    ]
+    // Image block: orientation-aware sizing so the border hugs the image
+    // without leaving dead whitespace above or below.
+    //   - Landscape: block fills content width; height derives from image aspect
+    //   - Portrait:  block capped at 7.5in tall; width derives from image aspect
+    #if is-portrait {
+      align(center,
+        block(
+          radius: 4pt,
+          clip: true,
+          stroke: 0.5pt + color-rule,
+          inset: 0pt,
+        )[
+          #image(image-path, height: 7.5in)
+        ],
+      )
+    } else {
+      block(
+        width: 100%,
+        radius: 4pt,
+        clip: true,
+        stroke: 0.5pt + color-rule,
+        inset: 0pt,
+      )[
+        #image(image-path, width: 100%)
+      ]
+    }
 
     // Explanatory text below the image.
     #if description != none {

templates/tachi/security-report/full-bleed.typ

@@ -204,6 +204,7 @@
     executive-architecture-image-path,
     section-name: "Executive Threat Architecture",
     classification: classification,
+    is-portrait: true,
     description: [
       Layered system architecture with critical and high severity threats annotated as narrative callouts. This visualization highlights where the most exposed components sit in the system and what kind of attack each layer is most vulnerable to.
     ],