fix: exit codes & CI gating across report/coverage/deps/score/resolve/diff/changelog (closes #418, closes #419, closes #422, closes #425, closes #430, closes #431, closes #441, closes #444)

src/changelog.rs

@@ -83,12 +83,60 @@ fn read_file_at_ref(root: &Path, git_ref: &str, file_path: &str) -> Option<Strin
 }
 
 /// Parse a range string like "v0.1..v0.2" or "HEAD~5..HEAD" into (from, to).
+#[cfg(test)]
 pub fn parse_range(range: &str) -> Option<(String, String)> {
-    let parts: Vec<&str> = range.splitn(2, "..").collect();
-    if parts.len() == 2 && !parts[0].is_empty() && !parts[1].is_empty() {
-        Some((parts[0].to_string(), parts[1].to_string()))
+    parse_range_full(range).map(|(from, to, _)| (from, to))
+}
+
+/// Parse a range into (from, to, three_dot). A three-dot range (`A...B`,
+/// changes since the merge-base) must be split on `...` FIRST — splitting on
+/// `..` mangles it into `A` / `.B`, and the bogus `.B` ref then silently
+/// produced fabricated "removed" entries (#418).
+pub fn parse_range_full(range: &str) -> Option<(String, String, bool)> {
+    if let Some((from, to)) = range.split_once("...") {
+        if !from.is_empty() && !to.is_empty() {
+            return Some((from.to_string(), to.to_string(), true));
+        }
+        return None;
+    }
+    let (from, to) = range.split_once("..")?;
+    if from.is_empty() || to.is_empty() {
+        return None;
+    }
+    Some((from.to_string(), to.to_string(), false))
+}
+
+/// Verify that a git ref resolves to a real commit (`git rev-parse --verify`).
+/// Returns the resolved full hash.
+pub fn resolve_ref(root: &Path, git_ref: &str) -> Result<String, String> {
+    let output = Command::new("git")
+        .args([
+            "rev-parse",
+            "--verify",
+            "--end-of-options",
+            &format!("{git_ref}^{{commit}}"),
+        ])
+        .current_dir(root)
+        .output()
+        .map_err(|e| format!("failed to run git rev-parse: {e}"))?;
+    if output.status.success() {
+        Ok(String::from_utf8_lossy(&output.stdout).trim().to_string())
     } else {
-        None
+        Err(format!("unknown revision '{git_ref}'"))
+    }
+}
+
+/// Compute the merge-base of two refs (`git merge-base`).
+pub fn merge_base(root: &Path, a: &str, b: &str) -> Result<String, String> {
+    let output = Command::new("git")
+        .args(["merge-base", "--end-of-options", a, b])
+        .current_dir(root)
+        .output()
+        .map_err(|e| format!("failed to run git merge-base: {e}"))?;
+    if output.status.success() {
+        Ok(String::from_utf8_lossy(&output.stdout).trim().to_string())
+    } else {
+        Err(format!("no merge-base between '{a}' and '{b}'"))
     }
 }
 

src/cli.rs

@@ -148,11 +148,11 @@ pub enum Command {
     },
     /// Show export changes since last commit (useful for CI/PR comments)
     Diff {
-        /// Git ref to compare against (default: HEAD).
-        /// In GitHub Actions PR context, auto-detects the base branch
-        /// from GITHUB_BASE_REF when set to HEAD.
-        #[arg(long, default_value = "HEAD")]
-        base: String,
+        /// Git ref to compare against (default: auto-detect the PR base from
+        /// GITHUB_BASE_REF in GitHub Actions pull_request* events, else HEAD).
+        /// An explicit value always wins over environment auto-detection.
+        #[arg(long)]
+        base: Option<String>,
     },
     /// Manage agent instruction files and git hooks for spec awareness
     Hooks {

src/commands/changelog.rs

@@ -7,7 +7,7 @@ use crate::config::load_config;
 use crate::types;
 
 pub fn cmd_changelog(root: &Path, range: &str, format: types::OutputFormat) {
-    let (from_ref, to_ref) = match changelog::parse_range(range) {
+    let (from_ref, to_ref, three_dot) = match changelog::parse_range_full(range) {
         Some(r) => r,
         None => {
             eprintln!(
@@ -18,6 +18,37 @@ pub fn cmd_changelog(root: &Path, range: &str, format: types::OutputFormat) {
         }
     };
 
+    // Validate BOTH endpoints before comparing: an unresolvable ref used to be
+    // silently treated as an empty tree, fabricating a plausible changelog
+    // with exit 0 — exactly the wrong output for CI (#418).
+    let to_ref = match changelog::resolve_ref(root, &to_ref) {
+        Ok(_) => to_ref,
+        Err(e) => {
+            eprintln!("{} {e}", "Error:".red().bold());
+            process::exit(1);
+        }
+    };
+    let from_ref = match changelog::resolve_ref(root, &from_ref) {
+        Ok(_) => from_ref,
+        Err(e) => {
+            eprintln!("{} {e}", "Error:".red().bold());
+            process::exit(1);
+        }
+    };
+
+    // Three-dot range (A...B): compare from the real merge-base, not from A.
+    let from_ref = if three_dot {
+        match changelog::merge_base(root, &from_ref, &to_ref) {
+            Ok(base) => base,
+            Err(e) => {
+                eprintln!("{} {e}", "Error:".red().bold());
+                process::exit(1);
+            }
+        }
+    } else {
+        from_ref
+    };
+
     let config = load_config(root);
     let report = changelog::generate_changelog(root, &config.specs_dir, &from_ref, &to_ref);
 

src/commands/check.rs

@@ -16,7 +16,8 @@ use crate::validator::{compute_coverage, get_schema_table_names};
 use crate::config::is_legacy_layout;
 
 use super::{
-    build_schema_columns, compute_exit_code, create_drift_issues, exit_with_status,
+    build_schema_columns, compute_exit_code, create_drift_issues, default_enforcement,
+    exit_with_status,
     filter_by_status, filter_specs, load_and_discover, run_validation,
 };
 
@@ -136,7 +137,7 @@ pub fn cmd_check(
     let enforcement = enforcement.unwrap_or(if strict {
         types::EnforcementMode::Strict
     } else {
-        config.enforcement
+        default_enforcement(&config)
     });
 
     // Spec name filters that matched nothing are an error — don't fall through

src/commands/comment.rs

@@ -9,7 +9,9 @@ use crate::ignore::IgnoreRules;
 use crate::types;
 use crate::validator::{compute_coverage, get_schema_table_names};
 
-use super::{build_schema_columns, compute_exit_code, load_and_discover, run_validation};
+use super::{
+    build_schema_columns, compute_exit_code, default_enforcement, load_and_discover, run_validation,
+};
 
 pub fn cmd_comment(
     root: &Path,
@@ -29,7 +31,7 @@ pub fn cmd_comment(
     let enforcement = enforcement.unwrap_or(if strict {
         types::EnforcementMode::Strict
     } else {
-        config.enforcement
+        default_enforcement(&config)
     });
 
     // Use the same validation pipeline as `check` for consistent results

src/commands/coverage.rs

@@ -6,7 +6,8 @@ use crate::types;
 use crate::validator::{compute_coverage, get_schema_table_names};
 
 use super::{
-    build_schema_columns, compute_exit_code, exit_with_status, load_and_discover, run_validation,
+    build_schema_columns, compute_exit_code, default_enforcement, exit_with_status,
+    load_and_discover, run_validation,
 };
 
 pub fn cmd_coverage(
@@ -26,7 +27,7 @@ pub fn cmd_coverage(
     let enforcement = enforcement.unwrap_or(if strict {
         types::EnforcementMode::Strict
     } else {
-        config.enforcement
+        default_enforcement(&config)
     });
     let schema_tables = get_schema_table_names(root, &config);
     let schema_columns = build_schema_columns(root, &config);
@@ -79,6 +80,7 @@ pub fn cmd_coverage(
             "loc_total": coverage.total_loc,
             "modules": modules,
             "uncovered_files": uncovered_files,
+            "missing_files": coverage.missing_files,
         });
         println!("{}", serde_json::to_string_pretty(&output).unwrap());
         // Gate the exit code for machine consumers too (was an unconditional

src/commands/deps.rs

@@ -6,7 +6,17 @@ use crate::config::load_config;
 use crate::deps;
 use crate::types;
 
-pub fn cmd_deps(root: &Path, strict: bool, format: types::OutputFormat, mermaid: bool, dot: bool) {
+use super::{compute_exit_code, default_enforcement, load_and_discover};
+
+pub fn cmd_deps(
+    root: &Path,
+    strict: bool,
+    enforcement: Option<types::EnforcementMode>,
+    require_coverage: Option<usize>,
+    format: types::OutputFormat,
+    mermaid: bool,
+    dot: bool,
+) {
     let config = load_config(root);
 
     // --mermaid or --dot: output graph visualization and exit
@@ -140,6 +150,37 @@ pub fn cmd_deps(root: &Path, strict: bool, format: types::OutputFormat, mermaid:
     if !report.errors.is_empty() || strict_fail {
         process::exit(1);
     }
+
+    // --require-coverage gate (#419): was completely inert. Evaluate the same
+    // coverage computation `specsync coverage` uses and fail below the
+    // threshold. Honored in every output format; JSON/machine formats gate
+    // silently via the exit code (handled by not printing here when Json).
+    if let Some(req) = require_coverage {
+        let (_, spec_files) = load_and_discover(root, true);
+        let coverage = crate::validator::compute_coverage(root, &spec_files, &config);
+        let enforcement =
+            enforcement.unwrap_or_else(|| default_enforcement(&config));
+        let code = compute_exit_code(0, 0, strict, enforcement, &coverage, Some(req));
+        if format != types::OutputFormat::Json {
+            if code == 0 {
+                println!(
+                    "  {} Coverage {}% meets --require-coverage {req}%",
+                    "✓".green(),
+                    coverage.coverage_percent
+                );
+            } else {
+                eprintln!(
+                    "{} {req}%: actual coverage is {}% ({} file(s) missing specs)",
+                    "--require-coverage".red(),
+                    coverage.coverage_percent,
+                    coverage.unspecced_files.len()
+                );
+            }
+        }
+        if code != 0 {
+            process::exit(code);
+        }
+    }
 }
 
 /// Render the dependency graph as a Mermaid flowchart diagram.

src/commands/diff.rs

@@ -9,15 +9,37 @@ use crate::types;
 
 use super::load_and_discover;
 
-pub fn cmd_diff(root: &Path, base: &str, format: types::OutputFormat) {
+pub fn cmd_diff(root: &Path, base: Option<&str>, format: types::OutputFormat, strict: bool) {
     let (config, spec_files) = load_and_discover(root, false);
 
-    // Auto-detect PR context: when base is default "HEAD" and we're in a GitHub
-    // Actions pull_request event, compare against the PR's base branch instead.
-    let effective_base = if base == "HEAD" {
-        detect_pr_base().unwrap_or_else(|| base.to_string())
-    } else {
-        base.to_string()
+    // An explicit --base always wins over environment auto-detection (a literal
+    // `--base HEAD` used to be hijacked by the PR-context fallback, since HEAD
+    // doubled as the "not specified" sentinel).
+    let effective_base = match base {
+        Some(b) => b.to_string(),
+        None => match detect_pr_base() {
+            Some(b) => b,
+            None => {
+                // Silent HEAD fallback = silent no-op in the default CI states
+                // (detached HEAD, push events): the working tree vs HEAD is
+                // empty by construction in a clean checkout, so nothing is
+                // ever compared while the run greens. Say so loudly.
+                eprintln!(
+                    "specsync: no PR base detected (GITHUB_EVENT_NAME is not a pull_request* event); comparing against HEAD"
+                );
+                eprintln!(
+                    "  In a clean CI checkout this compares nothing — pass --base <ref> to choose a real comparison base."
+                );
+                if strict {
+                    eprintln!(
+                        "{} no usable base ref and none given — refusing to silently diff HEAD",
+                        "--strict mode".red()
+                    );
+                    process::exit(1);
+                }
+                "HEAD".to_string()
+            }
+        },
     };
     let base = effective_base.as_str();
 
@@ -318,7 +340,8 @@ pub fn cmd_diff(root: &Path, base: &str, format: types::OutputFormat) {
 /// or `None` otherwise.
 fn detect_pr_base() -> Option<String> {
     let event = std::env::var("GITHUB_EVENT_NAME").ok()?;
-    if event != "pull_request" && event != "pull_request_target" {
+    // GitHub sets GITHUB_BASE_REF for all three PR-flavored events.
+    if event != "pull_request" && event != "pull_request_target" && event != "pull_request_review" {
         return None;
     }
     let base_ref = std::env::var("GITHUB_BASE_REF").ok()?;

src/commands/generate.rs

@@ -10,7 +10,8 @@ use crate::types;
 use crate::validator::{compute_coverage, get_schema_table_names};
 
 use super::{
-    build_schema_columns, compute_exit_code, exit_with_status, load_and_discover, run_validation,
+    build_schema_columns, compute_exit_code, default_enforcement, exit_with_status,
+    load_and_discover, run_validation,
 };
 
 #[allow(clippy::too_many_arguments)]
@@ -50,7 +51,7 @@ fn cmd_generate_all(
     let enforcement = enforcement.unwrap_or(if strict {
         types::EnforcementMode::Strict
     } else {
-        config.enforcement
+        default_enforcement(&config)
     });
     let schema_tables = get_schema_table_names(root, &config);
     let schema_columns = build_schema_columns(root, &config);
@@ -212,7 +213,7 @@ fn cmd_generate_batch(
     let enforcement = enforcement.unwrap_or(if strict {
         types::EnforcementMode::Strict
     } else {
-        config.enforcement
+        default_enforcement(&config)
     });
 
     let coverage = compute_coverage(root, &spec_files, &config);

src/commands/mod.rs

@@ -669,6 +669,24 @@ fn colorize_subscore(score: u32) -> String {
     }
 }
 
+/// Resolve the enforcement mode when the user did NOT pass `--enforcement`.
+///
+/// Consistent convention across all gate commands (`check`, `coverage`,
+/// `report`, `score`, `generate`, `comment`):
+/// - an explicit `enforcement` key in the config file is honored as-is
+///   (including `warn`, which always exits 0);
+/// - when enforcement is not configured anywhere, the default GATES ON
+///   ERRORS (`Strict`-like): validation errors exit 1. Warnings remain
+///   non-blocking unless `--strict` is also passed. This is the only safe
+///   default for CI — a command that prints "1 failed" must not exit 0.
+pub fn default_enforcement(config: &types::SpecSyncConfig) -> types::EnforcementMode {
+    if config.enforcement_set {
+        config.enforcement
+    } else {
+        types::EnforcementMode::Strict
+    }
+}
+
 /// Compute exit code without printing or exiting.
 pub fn compute_exit_code(
     total_errors: usize,