fix(134): threat-report attack tree baseline, MAESTRO layer rendering, filename convention (#135)

Three related bugs in the tachi threat-report generation pipeline:

1. Attack tree baseline handling lost Mermaid content on UNCHANGED findings.
   Replaced the old "skip UNCHANGED" rule with a three-rule approach that
   copies baseline Mermaid when nothing changed, regenerates all trees when
   architecture shifted, and reconciles structurally-equivalent trees against
   the baseline to avoid diff noise.

2. MAESTRO layer context was dropped from Section 3 narratives and the
   threats.md Section 7 summary table despite the data being parsed into
   findings. Promoted MAESTRO layer references to mandatory on first mention
   of every finding and added a MAESTRO Layer column to the summary table.

3. Attack tree filename convention was stated once as a parenthetical and
   not enforced, leading to files like AG-1-no-hitl-stdio.md that the spec
   112 parser silently dropped. Added explicit convention block, dedicated
   skill section, and a validation checklist item.

Schema plumbing: schemas/report.yaml bumps 1.0 -> 1.1 with baseline_source,
baseline_date, delta_counts frontmatter fields and a conditional Section 8
Delta Summary. schemas/output.yaml adds status and maestro_layer columns.

Closes #134

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

Author: davidmatousek

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

@@ -118,7 +118,8 @@ Before finalizing the report, run the following checklist. Every check must pass
 #### Section Completeness
 
 - [ ] All 7 report sections are present with non-empty content
-- [ ] YAML frontmatter contains all 6 required fields (schema_version, date, source_file, finding_count, risk_distribution, attack_tree_count)
+- [ ] YAML frontmatter is the FIRST content in the report (before Section 1), enclosed in a fenced `yaml` code block between `---` delimiters
+- [ ] YAML frontmatter contains ALL required fields: schema_version, date, source_file, finding_count, risk_distribution, attack_tree_count, baseline_source, baseline_date, delta_counts (see template for full structure)
 - [ ] Section headings match `../../../schemas/report.yaml` exactly (## 1. Executive Summary through ## 7. Appendix: Finding Reference)
 
 #### Finding Traceability (Zero Loss Rule)
@@ -133,7 +134,7 @@ Before finalizing the report, run the following checklist. Every check must pass
 - [ ] Every High finding has an attack tree with minimum 2 levels of decomposition
 - [ ] No attack trees generated for Medium, Low, Note, or RESOLVED findings
 - [ ] Attack trees appear inline in Section 5 AND as standalone files in `attack-trees/`
-- [ ] Standalone file naming follows `{finding-id}-attack-tree.md` convention (lowercase, e.g., `ag-1-attack-tree.md`)
+- [ ] Standalone file naming follows `{finding-id}-attack-tree.md` convention — finding ID lowercased, `-attack-tree.md` suffix (e.g., `ag-1-attack-tree.md`, NOT `AG-1-attack-tree.md` or `AG-1-description-slug.md`)
 
 #### Mermaid Syntax Integrity
 
@@ -162,6 +163,10 @@ Before finalizing the report, run the following checklist. Every check must pass
 
 ## Report Generation Workflow
 
+### Step 0: YAML Frontmatter (MANDATORY — generate FIRST)
+
+**Before writing any section**, generate the YAML frontmatter block at the top of the report. Read `../../../templates/tachi/output-schemas/threat-report.md` for the exact field structure. The frontmatter MUST be the first content after the H1 heading, enclosed in a fenced `yaml` code block between `---` delimiters. Populate all fields from `threats.md`: schema_version (`"1.1"`), date, source_file, finding_count, risk_distribution (Critical/High/Medium/Low counts), attack_tree_count, baseline_source, baseline_date, and delta_counts. When no baseline exists, set baseline_source, baseline_date, and all delta_counts fields to `null`.
+
 ### Section 1: Executive Summary
 
 **MANDATORY**: Read `.claude/skills/tachi-threat-reporting/references/narrative-templates.md` for the 5 required elements, language rules, and remediation timeline tiers.
@@ -178,7 +183,9 @@ Generate the Architecture Overview deriving system context from `threats.md` Sec
 
 **MANDATORY**: Read `.claude/skills/tachi-threat-reporting/references/narrative-templates.md` for per-category subsection headers, per-finding narrative pattern, progressive depth rules, and large threat model handling.
 
-Generate the Threat Analysis with agent-by-agent narrative covering all 8 categories. When findings include a `maestro_layer` field, reference the architectural layer in finding narratives for additional context (e.g., "This threat targets the Agent Framework layer (L3)"). MAESTRO layer references are informational -- they do not change narrative structure, severity assessments, or attack tree construction.
+Generate the Threat Analysis with agent-by-agent narrative covering all 8 categories.
+
+**MAESTRO Layer References (MANDATORY when present)**: When findings include a `maestro_layer` field, you MUST reference the architectural layer in each finding's narrative. Include the layer designation on first mention of each finding — for example: "**S-1** targets the Agent Framework layer (L3), where..." or "Operating at the Data Operations layer (L2), **T-3** exploits...". Every finding narrative must include its MAESTRO layer context. These references are informational — they do not change narrative structure, severity assessments, or attack tree construction.
 
 ### Section 4: Cross-Cutting Themes
 
@@ -192,7 +199,20 @@ Scan all findings for emergent patterns across categories that reveal systemic i
 
 **MANDATORY**: Read `.claude/skills/tachi-threat-reporting/references/attack-tree-examples.md` before generating the first tree -- load once as reference patterns.
 
-Generate Mermaid attack trees for every Critical and High finding following Bruce Schneier's attack tree methodology. **Skip findings with delta_status RESOLVED** -- resolved threats are no longer active and must not receive attack trees. **ALWAYS generate fresh attack trees for UNCHANGED findings** -- do NOT produce placeholder text like "carried forward from baseline." An unchanged threat description does not mean the attack paths are static; adjacent components and techniques may have changed. Every active Critical/High finding gets a fully constructed Mermaid attack tree, regardless of delta_status.
+Generate Mermaid attack trees for every Critical and High finding following Bruce Schneier's attack tree methodology.
+
+**Attack tree delta handling (three rules):**
+
+First, check `delta_counts` from the `threats.md` frontmatter to determine which rule applies:
+
+**Rule 1 — All UNCHANGED (delta_counts: new=0, updated=0, resolved=0):** Architecture has not changed. For each UNCHANGED Critical/High finding, read and copy the full Mermaid content from the baseline at `{baseline_dir}/attack-trees/{finding-id}-attack-tree.md`. Derive `baseline_dir` from the `baseline.source` frontmatter path by dropping `threats.md`. Include the complete Mermaid code block in both inline (Section 5) and standalone file output. Do NOT output placeholder text without the diagram. If the baseline file is missing, generate fresh as fallback.
+
+**Rule 2 — Any NEW/UPDATED/RESOLVED (any delta_counts > 0):** Architecture shifted -- attack paths to all threats may have changed. Generate fresh attack trees for ALL Critical/High findings, including UNCHANGED ones. For UPDATED findings, add a note: _"Context changed since baseline -- attack tree regenerated."_
+
+**Rule 3 — Reconciliation (after Rule 2 only):** After generating all fresh trees, compare each UNCHANGED finding's fresh tree against its baseline version. If structurally similar (same nodes, same paths, minor wording only), use the baseline version for consistency. If materially different (new paths, removed nodes, structural changes), use the fresh version.
+
+**RESOLVED**: Skip entirely -- no attack tree.
+**No baseline**: Generate all trees fresh.
 
 ### Section 6: Remediation Roadmap
 
@@ -252,7 +272,14 @@ Embed each attack tree directly in the Attack Trees section using Mermaid code b
 
 ### Location 2: Standalone Files in attack-trees/
 
-Save each attack tree as an independent Markdown file in the `attack-trees/` directory within the output directory. File naming: `{finding-id}-attack-tree.md` (lowercase, e.g., `ag-1-attack-tree.md`).
+Save each attack tree as an independent Markdown file in the `attack-trees/` directory within the output directory.
+
+**File naming convention** (MUST follow exactly):
+- Pattern: `{finding-id}-attack-tree.md`
+- Case: **always lowercase** — the finding ID is lowercased in the filename
+- Suffix: **always `-attack-tree.md`** — never use a description slug
+- Examples: `AG-1` → `ag-1-attack-tree.md`, `LLM-2` → `llm-2-attack-tree.md`, `S-1` → `s-1-attack-tree.md`
+- **Wrong**: `AG-1-no-hitl-stdio.md`, `AG-1-attack-tree.md` (uppercase)
 
 Each standalone file contains: H1 heading with finding ID and threat description, a metadata table (Finding ID, Component, Risk Level, Threat, Correlation), and the Mermaid code block **identical** to the inline version in `threat-report.md`.
 

.claude/skills/tachi-threat-reporting/references/attack-tree-construction.md

@@ -137,6 +137,20 @@ Target a maximum of approximately **20 nodes** per tree for readability. If a tr
 
 ---
 
+## Standalone File Naming
+
+Each attack tree is saved as a standalone file in the `attack-trees/` directory. The filename MUST follow this convention exactly:
+
+- **Pattern**: `{finding-id}-attack-tree.md`
+- **Case**: The finding ID MUST be **lowercased** in the filename
+- **Suffix**: Always `-attack-tree.md` — never use a description slug or other suffix
+- **Examples**: Finding `AG-1` → filename `ag-1-attack-tree.md`, Finding `LLM-2` → filename `llm-2-attack-tree.md`, Finding `S-1` → filename `s-1-attack-tree.md`
+- **Wrong examples**: `AG-1-attack-tree.md` (uppercase), `ag-1-no-hitl-stdio.md` (description slug), `AG-1-no-hitl-stdio.md` (both wrong)
+
+To produce the filename: take the finding ID (e.g., `AG-1`), convert to lowercase (e.g., `ag-1`), append `-attack-tree.md`.
+
+---
+
 ## Validation Checklist
 
 Before including any Mermaid attack tree in the report or standalone file, run every check below. A tree that fails any check must be corrected before output.
@@ -178,6 +192,12 @@ Before including any Mermaid attack tree in the report or standalone file, run e
 - [ ] Leaf nodes assigned `leaf` class
 - [ ] Color values match the standard palette: goal=`#ff6b6b`, andGate=`#ffa500`, orGate=`#4ecdc4`, leaf=`#95e1d3`
 
+### Standalone File Naming
+
+- [ ] Filename is the finding ID lowercased plus `-attack-tree.md` (e.g., AG-1 → `ag-1-attack-tree.md`)
+- [ ] No uppercase letters in filename
+- [ ] No description slugs — suffix is always `-attack-tree.md`
+
 ### Readability
 
 - [ ] Total node count does not exceed ~20 nodes

.claude/skills/tachi-threat-reporting/references/narrative-templates.md

@@ -75,10 +75,11 @@ For each category, include all findings from the corresponding STRIDE or AI tabl
 
 For each finding, provide:
 1. **Finding reference**: State the finding ID (e.g., "**S-1**") as a bold reference
-2. **Component annotation**: Name the affected component
-3. **Threat description**: Explain the threat in context -- what could happen, how, and why it matters
-4. **Risk context**: State the likelihood, impact, and computed risk level
-5. **Mitigation summary**: Reference the recommended mitigation (the full mitigation text appears in the Remediation Roadmap)
+2. **MAESTRO layer context**: On first mention of each finding, include its MAESTRO architectural layer from the `maestro_layer` field. Integrate naturally into the sentence — for example: "**S-1** targets the Agent Framework layer (L3), where..." or "Operating at the Data Operations layer (L2), **T-3** exploits...". Every finding MUST include its MAESTRO layer on first reference.
+3. **Component annotation**: Name the affected component
+4. **Threat description**: Explain the threat in context -- what could happen, how, and why it matters
+5. **Risk context**: State the likelihood, impact, and computed risk level
+6. **Mitigation summary**: Reference the recommended mitigation (the full mitigation text appears in the Remediation Roadmap)
 
 ### Progressive Technical Depth Rules
 

schemas/output.yaml

@@ -143,7 +143,9 @@ output:
       sort_order: "risk_level descending"
       fields:
         - finding_id
+        - status
         - component
+        - maestro_layer
         - threat
         - risk_level
         - mitigation

schemas/report.yaml

@@ -9,7 +9,7 @@
 #
 # Version: 1.0
 
-schema_version: "1.0"
+schema_version: "1.1"
 
 report:
   output_file: threat-report.md
@@ -19,7 +19,7 @@ report:
     fields:
       schema_version:
         type: string
-        value: "1.0"
+        value: "1.1"
       date:
         type: string
         format: "YYYY-MM-DD"
@@ -51,6 +51,37 @@ report:
         description: >
           Number of generated attack trees (one per
           Critical/High finding).
+      baseline_source:
+        type: string
+        nullable: true
+        description: >
+          File path of the baseline threats.md used for delta
+          comparison. Null when no baseline (first run).
+      baseline_date:
+        type: string
+        nullable: true
+        format: "YYYY-MM-DD"
+        description: >
+          ISO date of the baseline run. Null when no baseline.
+      delta_counts:
+        type: object
+        nullable: true
+        description: >
+          Lifecycle breakdown counts. All values null when
+          no baseline (first run).
+        fields:
+          new:
+            type: integer
+            nullable: true
+          unchanged:
+            type: integer
+            nullable: true
+          updated:
+            type: integer
+            nullable: true
+          resolved:
+            type: integer
+            nullable: true
 
   required_sections:
     - name: "Executive Summary"
@@ -100,9 +131,26 @@ report:
       requirement: >
         Complete mapping — zero finding loss.
 
+    - name: "Delta Summary"
+      heading: "## 8. Delta Summary"
+      conditional: true
+      condition: >
+        Present only when baseline_source is non-null in
+        frontmatter. Omit entirely on first run.
+      required_elements:
+        - finding_lifecycle_breakdown
+        - remediation_progress
+        - baseline_reference
+
   attack_tree_files:
     directory: "attack-trees/"
     naming: "{finding-id}-attack-tree.md"
+    naming_rules:
+      case: lowercase
+      suffix: "-attack-tree.md"
+      description: >
+        Finding ID is lowercased for the filename. Example: finding AG-1
+        becomes ag-1-attack-tree.md, finding LLM-2 becomes llm-2-attack-tree.md.
     severity_filter:
       - Critical
       - High

templates/tachi/output-schemas/threat-report.md

@@ -196,12 +196,17 @@ flowchart TD
 >
 > **Correlated findings**: Each correlated finding receives its own individual tree with a cross-reference note to related finding IDs — not a single unified tree for the correlation group.
 >
-> **Baseline handling** (delta_status branching):
-> - **NEW**: Generate a fresh attack tree following all standard conventions above.
-> - **UPDATED**: Generate a fresh attack tree. Add a note below the tree: _"Context changed since baseline ({baseline_date}) — attack tree regenerated."_
-> - **UNCHANGED**: Do NOT generate an attack tree. Instead, note: _"Attack tree carried forward from baseline ({baseline_date}) — finding unchanged since last assessment."_
-> - **RESOLVED**: Not applicable — RESOLVED findings do not appear in Section 5. They appear only in Section 4b of the input threats.md.
-> - **No baseline**: When `baseline_source` is null in the input frontmatter, generate all attack trees fresh with no delta annotations. This is standard first-run behavior.
+> **Baseline handling** (three-rule approach):
+>
+> **Rule 1 — All UNCHANGED (no architecture change):** When `delta_counts` shows zero NEW, zero UPDATED, and zero RESOLVED findings, the architecture has not changed. For each UNCHANGED Critical/High finding, copy the full Mermaid attack tree content from the baseline's `attack-trees/{finding-id}-attack-tree.md` file. Derive the baseline directory from the `baseline.source` frontmatter field by dropping the `threats.md` filename. Include the complete Mermaid code block — do NOT output placeholder text without the actual diagram. If the baseline file is missing, generate a fresh tree as fallback.
+>
+> **Rule 2 — Any NEW/UPDATED/RESOLVED (architecture changed):** When `delta_counts` shows any non-zero value for `new`, `updated`, or `resolved`, the architecture has shifted and attack paths to all threats may have changed. Generate fresh attack trees for ALL Critical/High findings — including UNCHANGED ones — following all standard conventions above. For NEW findings, generate normally. For UPDATED findings, add a note below the tree: _"Context changed since baseline ({baseline_date}) — attack tree regenerated."_
+>
+> **Rule 3 — Post-generation reconciliation (applies only when Rule 2 fires):** After generating all fresh trees, compare each UNCHANGED finding's fresh tree against its baseline counterpart from `attack-trees/{finding-id}-attack-tree.md`. If they are structurally similar (same nodes, same paths, minor wording differences only), use the baseline version for consistency — this avoids noisy churn on trees that didn't actually change. If they are materially different (new attack paths, removed nodes, structural changes), use the fresh version. This ensures diffs between runs only show meaningful changes.
+>
+> **RESOLVED**: Not applicable — RESOLVED findings do not appear in Section 5. They appear only in Section 4b of the input threats.md.
+>
+> **No baseline**: When `baseline_source` is null in the input frontmatter, generate all attack trees fresh with no delta annotations. This is standard first-run behavior.
 
 _When no Critical or High findings exist:_