fix: fall back to body H1 when frontmatter title missing, implement pad filter

When an ADR has YAML frontmatter but omits the `title` field, the parser
now extracts the title from the first H1 heading in the body instead of
silently dropping the ADR. Also implements the `pad` template filter
documented in templates.md and corrects the `number` variable description.

Closes #185, closes #186

Author: joshrotenberg

book/src/templates.md

@@ -103,7 +103,7 @@ Create custom templates using [Jinja2](https://jinja.palletsprojects.com/) synta
 
 | Variable | Description | Example |
 |----------|-------------|---------|
-| `number` | ADR number (padded) | `0001` |
+| `number` | ADR number | `1` |
 | `title` | ADR title | `Use PostgreSQL` |
 | `date` | Current date | `2024-01-15` |
 | `status` | Initial status | `Proposed` |
@@ -169,7 +169,7 @@ Use Jinja2 conditionals for optional content:
 ## Related Decisions
 
 {% for link in links %}
-* {{ link.kind }} [ADR {{ link.target }}]({{ link.target | pad(4) }}-*.md)
+* {{ link.kind }} [ADR {{ link.target }}]({{ link.target | pad(width=4) }}-*.md)
 {% endfor %}
 {% endif %}
 ```

crates/adrs-core/src/parse.rs

@@ -67,6 +67,16 @@ impl Parser {
         // Parse frontmatter
         let mut adr: Adr = serde_yaml::from_str(yaml)?;
 
+        // If title is missing from frontmatter, try to extract from body H1
+        if adr.title.is_empty()
+            && let Some((num, title)) = extract_h1_title(body)
+        {
+            adr.title = title;
+            if adr.number == 0 {
+                adr.number = num;
+            }
+        }
+
         // Parse body sections
         let sections = self.parse_sections(body);
         if let Some(context) = sections.get("context") {
@@ -90,14 +100,9 @@ impl Parser {
         let sections = self.extract_sections_raw(content);
 
         // Parse H1 title
-        if let Some(title_line) = content.lines().find(|l| l.starts_with("# ")) {
-            let title_str = title_line.trim_start_matches("# ").trim();
-            if let Some((num, title)) = parse_numbered_title(title_str) {
-                adr.number = num;
-                adr.title = title;
-            } else {
-                adr.title = title_str.to_string();
-            }
+        if let Some((num, title)) = extract_h1_title(content) {
+            adr.number = num;
+            adr.title = title;
         }
 
         // Apply sections
@@ -252,6 +257,23 @@ impl Parser {
     }
 }
 
+/// Extract a title from the first H1 heading in markdown content.
+///
+/// Returns `(number, title)` where number is extracted from patterns like `# 1. Title`,
+/// or `0` if the H1 has no number prefix.
+fn extract_h1_title(content: &str) -> Option<(u32, String)> {
+    let title_line = content.lines().find(|l| l.starts_with("# "))?;
+    let title_str = title_line.trim_start_matches("# ").trim();
+    if title_str.is_empty() {
+        return None;
+    }
+    if let Some((num, title)) = parse_numbered_title(title_str) {
+        Some((num, title))
+    } else {
+        Some((0, title_str.to_string()))
+    }
+}
+
 /// Parse a numbered title like "1. Use Rust" into (1, "Use Rust").
 fn parse_numbered_title(title: &str) -> Option<(u32, String)> {
     let parts: Vec<&str> = title.splitn(2, ". ").collect();
@@ -1313,4 +1335,81 @@ Context.
         assert_eq!(adr.links[0].kind, LinkKind::Supersedes);
         assert_eq!(adr.links[1].kind, LinkKind::Amends);
     }
+
+    // ========== Frontmatter Title Fallback (#186) ==========
+
+    #[test]
+    fn test_parse_frontmatter_title_from_body_h1() {
+        let content = r#"---
+number: 2
+date: 2024-01-15
+status: proposed
+---
+
+# My Decision Title
+
+## Context
+
+Context.
+
+## Decision
+
+Decision.
+
+## Consequences
+
+Consequences.
+"#;
+
+        let parser = Parser::new();
+        let adr = parser.parse(content).unwrap();
+
+        assert_eq!(adr.number, 2);
+        assert_eq!(adr.title, "My Decision Title");
+        assert_eq!(adr.status, AdrStatus::Proposed);
+    }
+
+    #[test]
+    fn test_parse_frontmatter_title_from_body_h1_numbered() {
+        let content = r#"---
+number: 2
+date: 2024-01-15
+status: proposed
+---
+
+# 2. My Numbered Title
+
+## Context
+
+Context.
+"#;
+
+        let parser = Parser::new();
+        let adr = parser.parse(content).unwrap();
+
+        assert_eq!(adr.number, 2);
+        assert_eq!(adr.title, "My Numbered Title");
+    }
+
+    #[test]
+    fn test_parse_frontmatter_title_prefers_frontmatter() {
+        let content = r#"---
+number: 2
+title: Frontmatter Title
+date: 2024-01-15
+status: proposed
+---
+
+# Body Title
+
+## Context
+
+Context.
+"#;
+
+        let parser = Parser::new();
+        let adr = parser.parse(content).unwrap();
+
+        assert_eq!(adr.title, "Frontmatter Title");
+    }
 }

crates/adrs-core/src/template.rs

@@ -84,6 +84,19 @@ impl std::str::FromStr for TemplateVariant {
     }
 }
 
+/// Zero-pad a number to a given width (default 4).
+///
+/// Used in templates as `{{ number | pad }}` or `{{ number | pad(width=6) }}`.
+fn pad_filter(
+    value: u32,
+    kwargs: minijinja::value::Kwargs,
+) -> std::result::Result<String, minijinja::Error> {
+    let width: Option<u32> = kwargs.get("width")?;
+    kwargs.assert_all_used()?;
+    let w = width.unwrap_or(4) as usize;
+    Ok(format!("{value:0>w$}"))
+}
+
 /// A template for generating ADRs.
 #[derive(Debug, Clone)]
 pub struct Template {
@@ -170,6 +183,7 @@ impl Template {
         use crate::LinkKind;
 
         let mut env = Environment::new();
+        env.add_filter("pad", pad_filter);
         env.add_template(&self.name, &self.content)
             .map_err(|e| Error::TemplateError(e.to_string()))?;
 
@@ -1496,4 +1510,26 @@ Links: {% for link in links %}{{ link.kind }} {{ link.target }}{% endfor %}"#,
         // No tags section when tags are empty
         assert!(!output.contains("tags:"));
     }
+
+    // ========== Pad Filter Tests (#185) ==========
+
+    #[test]
+    fn test_pad_filter_default_width() {
+        let template = Template::from_string("test", "{{ number | pad }}");
+        let adr = Adr::new(1, "Test");
+        let config = Config::default();
+        let output = template.render(&adr, &config, &no_link_titles()).unwrap();
+
+        assert_eq!(output, "0001");
+    }
+
+    #[test]
+    fn test_pad_filter_custom_width() {
+        let template = Template::from_string("test", "{{ number | pad(width=6) }}");
+        let adr = Adr::new(1, "Test");
+        let config = Config::default();
+        let output = template.render(&adr, &config, &no_link_titles()).unwrap();
+
+        assert_eq!(output, "000001");
+    }
 }

crates/adrs-core/src/types.rs

@@ -11,6 +11,7 @@ pub struct Adr {
     pub number: u32,
 
     /// The title of the decision.
+    #[serde(default)]
     pub title: String,
 
     /// The date the decision was made.