fix: high-priority DX improvements from dogfood feedback (#168)

* fix: improve header matching, score diagnostics, and frontmatter parsing (#166, #167, #161, #164)

- Accept common header variations in Public API (Exports, Public, Export)
  instead of requiring exact "Exported" keyword (#166)
- Score suggestions now show point impact per category (e.g., "Sections (-6pts):
  missing ## Invariants, Error Cases") for clear diagnosis (#167)
- Add --explain flag to score command for color-coded subscore breakdown
- Strip inline YAML comments from frontmatter values (#161)
- Handle tab indentation and trailing whitespace in frontmatter
- --fix now renames near-miss headers to canonical form before adding exports (#164)

Closes #166, closes #167, closes #161, closes #164

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* fix: apply cargo fmt formatting

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* fix: add stub detection, source-attributed export warnings, and requirements companion validation (#162, #165, #163)

- Detect stub/placeholder sections (TBD, N/A, TODO, Coming soon, etc.)
  that previously inflated content depth scores to undeserved A grades
- Show source file attribution for undocumented export warnings
  (e.g. "Undocumented export 'foo' from src/bar.ts")
- Warn when requirements appear inline in spec body instead of
  companion requirements.md, and when requirements.md is missing
- Shared stub detection in parser.rs used by both scoring and validator

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* fix: apply cargo fmt formatting

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* chore: bump version to v3.5.0 and update CHANGELOG

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: corvid-agent

CHANGELOG.md

@@ -7,6 +7,21 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [3.5.0] - 2026-04-08
+
+### Added
+
+- **Stub/placeholder detection** — sections containing only "TBD", "N/A", "TODO", "Coming soon", or similar placeholders are now flagged as warnings and no longer inflate quality scores (#162).
+- **Source-attributed export warnings** — undocumented export warnings now show which source file the export comes from, making them actionable in large codebases (#165).
+- **Requirements companion validation** — warns when specs contain inline requirements sections (should be in `requirements.md`) and when companion files are missing (#163).
+- **Score diagnostics** — `specsync score` now shows per-category breakdowns (completeness, structure, cross-references) with actionable improvement suggestions (#167).
+
+### Fixed
+
+- **Header matching flexibility** — fuzzy matching for common header variations like "Public API" → "Exports", "Tech Stack" → "Dependencies", reducing false negatives (#166).
+- **Frontmatter parser edge cases** — correctly handles tabs, trailing whitespace, and inline YAML comments in spec frontmatter (#161).
+- **`--fix` header renaming** — near-miss headers are now renamed in-place instead of duplicating the section (#164).
+
 ## [3.4.1] - 2026-04-07
 
 ### Fixed
@@ -290,6 +305,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   phantom documentation for non-existent exports (errors).
 - Dependency spec cross-referencing and Consumed By section validation.
 
+[3.4.1]: https://github.com/CorvidLabs/spec-sync/releases/tag/v3.4.1
+[3.5.0]: https://github.com/CorvidLabs/spec-sync/releases/tag/v3.5.0
 [3.4.1]: https://github.com/CorvidLabs/spec-sync/releases/tag/v3.4.1
 [3.4.0]: https://github.com/CorvidLabs/spec-sync/releases/tag/v3.4.0
 [3.1.0]: https://github.com/CorvidLabs/spec-sync/releases/tag/v3.1.0

Cargo.lock

@@ -1,6 +1,6 @@
 [package]
 name = "specsync"
-version = "3.4.1"
+version = "3.5.0"
 edition = "2024"
 rust-version = "1.85"
 description = "Bidirectional spec-to-code validation with schema column checking — 11 languages, single binary"

Cargo.toml

@@ -68,7 +68,11 @@ pub enum Command {
     /// Create a specsync.json config file
     Init,
     /// Score spec quality (0-100) with letter grades and improvement suggestions
-    Score,
+    Score {
+        /// Show detailed per-category breakdown explaining exactly why each spec lost points
+        #[arg(long)]
+        explain: bool,
+    },
     /// Watch spec and source files, re-running check on changes
     Watch,
     /// Run as an MCP (Model Context Protocol) server over stdio

src/cli.rs

@@ -372,6 +372,80 @@ fn auto_regen_stale_specs(
 
 // ─── Auto-fix: add undocumented exports to spec ─────────────────────────
 
+/// Normalize near-miss export headers within ## Public API.
+/// E.g., "### Exportd Functions" → "### Exported Functions"
+/// Returns true if the content was modified.
+fn fix_near_miss_headers(content: &mut String) -> bool {
+    use regex::Regex;
+    let re = Regex::new(r"(?m)^(### )(.+)$").unwrap();
+
+    // Find the Public API section bounds
+    let api_start = match content.find("## Public API") {
+        Some(pos) => pos,
+        None => return false,
+    };
+    let after = &content[api_start..];
+    let api_end = after[1..]
+        .find("\n## ")
+        .map(|p| api_start + 1 + p)
+        .unwrap_or(content.len());
+
+    let api_section = content[api_start..api_end].to_string();
+    let mut modified = false;
+
+    // Known canonical headers and their near-miss patterns
+    let canonical_map: &[(&[&str], &str)] = &[
+        (
+            &[
+                "exportd function",
+                "exportd func",
+                "exproted function",
+                "expported function",
+            ],
+            "Exported Functions",
+        ),
+        (
+            &["exportd type", "exproted type", "expported type"],
+            "Exported Types",
+        ),
+        (&["exportd class", "exproted class"], "Exported Classes"),
+        (
+            &["exportd constant", "exportd const", "exproted constant"],
+            "Exported Constants",
+        ),
+    ];
+
+    let mut new_section = api_section.clone();
+    for cap in re.captures_iter(&api_section) {
+        let header_text = cap.get(2).unwrap().as_str();
+        let lower = header_text.to_ascii_lowercase();
+
+        // Skip headers that already match via is_export_header
+        if crate::parser::is_export_header(&format!("### {header_text}")) {
+            continue;
+        }
+
+        // Check for near-miss (Levenshtein distance ≤ 2 from any canonical)
+        for (patterns, canonical) in canonical_map {
+            for pattern in *patterns {
+                if lower.contains(pattern) {
+                    let old = format!("### {header_text}");
+                    let new = format!("### {canonical}");
+                    new_section = new_section.replacen(&old, &new, 1);
+                    modified = true;
+                    break;
+                }
+            }
+        }
+    }
+
+    if modified {
+        content.replace_range(api_start..api_end, &new_section);
+    }
+
+    modified
+}
+
 fn auto_fix_specs(root: &Path, spec_files: &[PathBuf], config: &types::SpecSyncConfig) -> usize {
     use crate::exports::get_exported_symbols_with_level;
     use crate::parser::{get_spec_symbols, parse_frontmatter};
@@ -384,6 +458,17 @@ fn auto_fix_specs(root: &Path, spec_files: &[PathBuf], config: &types::SpecSyncC
             Err(_) => continue,
         };
 
+        // First pass: fix near-miss headers
+        let mut content = content;
+        if fix_near_miss_headers(&mut content) {
+            let rel = spec_file.strip_prefix(root).unwrap_or(spec_file).display();
+            println!(
+                "  {} {rel}: renamed near-miss header(s) to canonical form",
+                "✓".green()
+            );
+            let _ = fs::write(spec_file, &content);
+        }
+
         let parsed = match parse_frontmatter(&content) {
             Some(p) => p,
             None => continue,

src/commands/check.rs

@@ -202,7 +202,7 @@ pub fn run_validation(
         let undocumented: Vec<&str> = result
             .warnings
             .iter()
-            .filter(|w| w.starts_with("Export '"))
+            .filter(|w| w.starts_with("Export '") || w.starts_with("Undocumented export '"))
             .map(|s| s.as_str())
             .collect();
         for w in &undocumented {
@@ -233,8 +233,26 @@ pub fn run_validation(
             println!("  {} {w}", "⚠".yellow());
         }
 
-        // Show fix suggestions when there are errors
-        if !result.fixes.is_empty() && !result.errors.is_empty() {
+        // Stub section warnings
+        for w in result
+            .warnings
+            .iter()
+            .filter(|w| w.starts_with("Section ##") && w.contains("stub"))
+        {
+            println!("  {} {w}", "⚠".yellow());
+        }
+
+        // Requirements companion file warnings
+        for w in result
+            .warnings
+            .iter()
+            .filter(|w| w.contains("requirements"))
+        {
+            println!("  {} {w}", "⚠".yellow());
+        }
+
+        // Show fix suggestions when there are errors or warnings with fixes
+        if !result.fixes.is_empty() && (!result.errors.is_empty() || !result.warnings.is_empty()) {
             println!("  {}", "Suggested fixes:".cyan());
             for fix in &result.fixes {
                 println!("    {} {fix}", "->".cyan());

src/commands/mod.rs

@@ -6,7 +6,7 @@ use crate::types;
 
 use super::load_and_discover;
 
-pub fn cmd_score(root: &Path, format: types::OutputFormat) {
+pub fn cmd_score(root: &Path, format: types::OutputFormat, explain: bool) {
     let json = matches!(format, types::OutputFormat::Json);
     let (config, spec_files) = load_and_discover(root, false);
     let scores: Vec<scoring::SpecScore> = spec_files
@@ -70,10 +70,33 @@ pub fn cmd_score(root: &Path, format: types::OutputFormat) {
             grade_colored,
             s.total
         );
-        println!(
-            "    Frontmatter: {}/20  Sections: {}/20  API: {}/20  Depth: {}/20  Fresh: {}/20",
-            s.frontmatter_score, s.sections_score, s.api_score, s.depth_score, s.freshness_score
-        );
+
+        if explain {
+            // Show color-coded per-category bars
+            println!(
+                "    {} {}/20  {} {}/20  {} {}/20  {} {}/20  {} {}/20",
+                "Frontmatter:".dimmed(),
+                colorize_subscore(s.frontmatter_score),
+                "Sections:".dimmed(),
+                colorize_subscore(s.sections_score),
+                "API:".dimmed(),
+                colorize_subscore(s.api_score),
+                "Depth:".dimmed(),
+                colorize_subscore(s.depth_score),
+                "Fresh:".dimmed(),
+                colorize_subscore(s.freshness_score),
+            );
+        } else {
+            println!(
+                "    Frontmatter: {}/20  Sections: {}/20  API: {}/20  Depth: {}/20  Fresh: {}/20",
+                s.frontmatter_score,
+                s.sections_score,
+                s.api_score,
+                s.depth_score,
+                s.freshness_score
+            );
+        }
+
         if !s.suggestions.is_empty() {
             for suggestion in &s.suggestions {
                 println!("    {} {suggestion}", "->".cyan());
@@ -103,3 +126,13 @@ pub fn cmd_score(root: &Path, format: types::OutputFormat) {
         project.grade_distribution[4]
     );
 }
+
+/// Colorize a subscore (out of 20) — green for 20, yellow for 10-19, red for <10.
+fn colorize_subscore(score: u32) -> String {
+    let s = score.to_string();
+    match score {
+        20 => s.green().to_string(),
+        10..=19 => s.yellow().to_string(),
+        _ => s.red().to_string(),
+    }
+}

src/commands/score.rs

@@ -104,7 +104,7 @@ fn run() {
             format,
             provider,
         ),
-        Command::Score => commands::score::cmd_score(&root, format),
+        Command::Score { explain } => commands::score::cmd_score(&root, format, explain),
         Command::Watch => watch::run_watch(&root, cli.strict, cli.require_coverage),
         Command::Mcp => mcp::run_mcp_server(&root),
         Command::AddSpec { name } => commands::scaffold::cmd_add_spec(&root, &name),