From 288cb606ea0a29f3d720e01a131c350a9d3c9016 Mon Sep 17 00:00:00 2001
From: pi agent <pi@agent.local>
Date: Thu, 3 Sep 2026 07:57:26 +0200
Subject: [PATCH] chore(scripts): teach add-spdx-headers.sh about markdown
 files

Add *.md to the discovery glob and a frontmatter-aware HTML-comment
header case, so AGENTS.md-style documents and pi-rules
.github/instructions rule files can be licensed with the same tooling
as the source files.

The markdown case inserts the header after the YAML frontmatter
closing delimiter when a file leads with frontmatter: rule files must
keep their frontmatter at position zero or tooling downstream
(pi-rules) stops recognizing globs and the rule never injects again.
Unterminated frontmatter falls back to plain-markdown handling.

Tested against: frontmatter rule file, plain markdown, already
headered file (skip), unterminated frontmatter, nested tree.

Co-authored-by: glm-5.3 (neuralwatt)
---
 scripts/add-spdx-headers.sh | 34 +++++++++++++++++++++++++++++++---
 1 file changed, 31 insertions(+), 3 deletions(-)

diff --git a/scripts/add-spdx-headers.sh b/scripts/add-spdx-headers.sh
index 58d5e9cf4..3e256d7f4 100755
--- a/scripts/add-spdx-headers.sh
+++ b/scripts/add-spdx-headers.sh
@@ -14,12 +14,14 @@ if [ "$YEAR" != "2024" ]; then
     COPYRIGHT="Copyright (C) 2024-$YEAR Breakdown RS Contributors"
 fi
 
-# Find supported source files recursively. Covers the Rust backend and the
-# frontend-flutter tree (Dart, Gherkin .feature, YAML).
+# Find supported source files recursively. Covers the Rust backend, the
+# frontend-flutter tree (Dart, Gherkin .feature, YAML) and Markdown docs
+# (AGENTS.md, pi-rules instruction files, ADRs, issue notes).
 find "${1:-.}" -type f \
     \( -name "*.rs" -o -name "*.typ" -o -name "*.sh" \
        -o -name "*.dart" -o -name "*.feature" \
-       -o -name "*.yaml" -o -name "*.yml" \) | while read -r file; do
+       -o -name "*.yaml" -o -name "*.yml" \
+       -o -name "*.md" \) | while read -r file; do
     # Check if header already exists
     if grep -q "SPDX-License-Identifier" "$file"; then
         echo "⏭️  Skipping (already has header): $file"
@@ -45,6 +47,32 @@ find "${1:-.}" -type f \
             echo "" >> "$temp_file"
             cat "$file" >> "$temp_file"
             ;;
+        *.md)
+            # Markdown: HTML comments. Files may start with YAML frontmatter
+            # (e.g. pi-rules .github/instructions rule files); the header MUST
+            # go after the closing "---" delimiter, or downstream tools would
+            # parse the frontmatter as plain body text (a rule file would lose
+            # its glob frontmatter and stop matching entirely).
+            frontmatter_end=0
+            if [ "$(head -n 1 "$file")" = "---" ]; then
+                frontmatter_end=$(awk 'NR > 1 && $0 == "---" { print NR; exit }' "$file")
+                frontmatter_end=${frontmatter_end:-0}
+            fi
+            if [ "$frontmatter_end" -gt 0 ]; then
+                head -n "$frontmatter_end" "$file" > "$temp_file"
+                echo "" >> "$temp_file"
+            else
+                : > "$temp_file"
+            fi
+            echo "<!-- SPDX-License-Identifier: $LICENSE -->" >> "$temp_file"
+            echo "<!-- $COPYRIGHT -->" >> "$temp_file"
+            echo "" >> "$temp_file"
+            if [ "$frontmatter_end" -gt 0 ]; then
+                tail -n +$((frontmatter_end + 1)) "$file" >> "$temp_file"
+            else
+                cat "$file" >> "$temp_file"
+            fi
+            ;;
         *)
             echo "⚠️  Unsupported file type: $file"
             continue