feat: read default scope globs from a checked-in rep.toml

Cargo.toml

@@ -23,6 +23,7 @@ serde = { version = "1", features = ["derive"] }
 serde_json = "1"
 sha2 = "0.10"
 thiserror = "1.0"
+toml = "0.8"
 
 [dev-dependencies]
 tempfile = "3"

src/cli.rs

@@ -28,6 +28,8 @@ CONCEPTS:
               (e.g. --map OldName=NewName --map OLDNAME=NEWNAME).
   plan        a previewed, saved set of edits, identified by a <plan-id>.
   residual    leftover occurrences of the old token after applying.
+  rep.toml    optional checked-in scope defaults at the repo root ([scope]
+              include/exclude globs) for scan/plan/residual; --no-config skips.
 
 Exit codes are stable for scripts and agents (0 success, 2 no matches,
 8 residual found, ...). Run 'rep <command> --help' for per-command detail.";
@@ -82,6 +84,10 @@ token occurs and in which files, so you can decide what to rename.")]
         #[arg(long)]
         exclude: Vec<String>,
 
+        /// Ignore rep.toml scope defaults for this run
+        #[arg(long = "no-config")]
+        no_config: bool,
+
         /// Restrict to git-tracked files (always on in the minimal version)
         #[arg(long)]
         tracked_only: bool,
@@ -144,6 +150,10 @@ the renames, then re-plan from the recorded mappings and apply."
         #[arg(long)]
         exclude: Vec<String>,
 
+        /// Ignore rep.toml scope defaults for this run
+        #[arg(long = "no-config")]
+        no_config: bool,
+
         /// Restrict to git-tracked files (always on in the minimal version)
         #[arg(long)]
         tracked_only: bool,
@@ -206,6 +216,10 @@ if anything is left.")]
         #[arg(long)]
         exclude: Vec<String>,
 
+        /// Ignore rep.toml scope defaults for this run
+        #[arg(long = "no-config")]
+        no_config: bool,
+
         /// Restrict to git-tracked files (always on in the minimal version)
         #[arg(long)]
         tracked_only: bool,

src/config.rs

@@ -0,0 +1,74 @@
+//! `rep.toml` — checked-in scope defaults for scan / plan / residual.
+//!
+//! Lives at the repository root (not inside `.rep/`, which is the
+//! machine-managed plan store and always excluded from scope) so the policy
+//! is tracked and reviewed like any other project convention.
+
+use std::path::Path;
+
+use serde::Deserialize;
+
+use crate::error::{RepError, Result};
+
+/// File name of the scope config at the repository root.
+pub const CONFIG_FILE: &str = "rep.toml";
+
+#[derive(Debug, Default, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct Config {
+    #[serde(default)]
+    pub scope: ScopeConfig,
+}
+
+/// The `[scope]` table: globs applied before any CLI `--include`/`--exclude`.
+#[derive(Debug, Default, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct ScopeConfig {
+    #[serde(default)]
+    pub include: Vec<String>,
+    #[serde(default)]
+    pub exclude: Vec<String>,
+}
+
+/// Load `rep.toml` from the repository root; `Ok(None)` when absent.
+///
+/// Parse failures — including unknown keys, which are almost always typos of
+/// `include`/`exclude` — are usage errors (exit 10), not generic IO errors,
+/// so a broken config never silently widens the scope.
+pub fn load(root: &Path) -> Result<Option<Config>> {
+    let path = root.join(CONFIG_FILE);
+    if !path.exists() {
+        return Ok(None);
+    }
+    let data = std::fs::read_to_string(&path)?;
+    let config: Config = toml::from_str(&data)
+        .map_err(|e| RepError::InvalidArguments(format!("invalid {CONFIG_FILE}: {e}")))?;
+    Ok(Some(config))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn scope_table_parses() {
+        let config: Config =
+            toml::from_str("[scope]\nexclude = [\"vendor/**\"]\ninclude = [\"src/**\"]\n").unwrap();
+        assert_eq!(config.scope.exclude, vec!["vendor/**"]);
+        assert_eq!(config.scope.include, vec!["src/**"]);
+    }
+
+    #[test]
+    fn unknown_keys_are_rejected() {
+        // `exlude` is the typo this guard exists for.
+        assert!(toml::from_str::<Config>("[scope]\nexlude = [\"x\"]\n").is_err());
+        assert!(toml::from_str::<Config>("[scop]\n").is_err());
+    }
+
+    #[test]
+    fn empty_file_is_a_valid_empty_config() {
+        let config: Config = toml::from_str("").unwrap();
+        assert!(config.scope.exclude.is_empty());
+        assert!(config.scope.include.is_empty());
+    }
+}

src/lib.rs

@@ -7,6 +7,7 @@
 pub mod applier;
 pub mod artifacts;
 pub mod cli;
+pub mod config;
 pub mod error;
 pub mod git;
 pub mod globset;

src/main.rs

@@ -132,6 +132,7 @@ fn dispatch(cli: Cli) -> Result<i32> {
             case_insensitive,
             include,
             exclude,
+            no_config,
             tracked_only: _,
         } => scanner::run(
             token,
@@ -140,6 +141,8 @@ fn dispatch(cli: Cli) -> Result<i32> {
                 include,
                 exclude,
                 tracked_only: true,
+                no_config,
+                ..Default::default()
             },
             json,
         ),
@@ -152,6 +155,7 @@ fn dispatch(cli: Cli) -> Result<i32> {
             rename_paths,
             include,
             exclude,
+            no_config,
             tracked_only: _,
         } => {
             let mut maps = map
@@ -182,6 +186,8 @@ fn dispatch(cli: Cli) -> Result<i32> {
                         include,
                         exclude,
                         tracked_only: true,
+                        no_config,
+                        ..Default::default()
                     },
                 },
                 json,
@@ -199,6 +205,7 @@ fn dispatch(cli: Cli) -> Result<i32> {
             case_insensitive,
             include,
             exclude,
+            no_config,
             tracked_only: _,
         } => residual::run(
             ResidualOpts {
@@ -210,6 +217,8 @@ fn dispatch(cli: Cli) -> Result<i32> {
                     include,
                     exclude,
                     tracked_only: true,
+                    no_config,
+                    ..Default::default()
                 },
             },
             json,

src/planner.rs

@@ -55,8 +55,9 @@ pub struct PlanOpts {
 }
 
 /// Execute `rep plan`.
-pub fn run(opts: PlanOpts, json: bool) -> Result<i32> {
+pub fn run(mut opts: PlanOpts, json: bool) -> Result<i32> {
     let root = git::discover_root()?;
+    opts.scope = scope::resolve(&root, opts.scope)?;
     scope::reject_rep_dir(&opts.scope)?;
 
     // `--from-git-renames` alone may legitimately derive nothing (no staged

src/residual.rs

@@ -51,8 +51,9 @@ pub struct ResidualOpts {
 }
 
 /// Execute `rep residual`.
-pub fn run(opts: ResidualOpts, json: bool) -> Result<i32> {
+pub fn run(mut opts: ResidualOpts, json: bool) -> Result<i32> {
     let root = git::discover_root()?;
+    opts.scope = scope::resolve(&root, opts.scope)?;
     scope::reject_rep_dir(&opts.scope)?;
 
     let tokens = resolve_tokens(&root, &opts)?;

src/scanner.rs

@@ -41,6 +41,7 @@ struct ScanReport {
 /// Execute `rep scan`.
 pub fn run(token: String, case_insensitive: bool, opts: ScopeOpts, json: bool) -> Result<i32> {
     let root = git::discover_root()?;
+    let opts = scope::resolve(&root, opts)?;
     scope::reject_rep_dir(&opts)?;
     let gathered = scope::gather(&root, &opts)?;