fix: address v2.4 setup review findings

Author: thedoublejay

.gitignore

@@ -28,6 +28,9 @@ dist/
 # Local-only planning docs (superpowers plans, drafts, scratch)
 docs/superpowers/
 
+# Local release-note drafts
+release-notes/
+
 # Local-only Python private corpus benchmark inputs/results
 benchmark/python/private-corpus.local.yaml
 benchmark/python/private-results/

crates/gather-step-cli/src/commands/generate.rs

@@ -198,9 +198,10 @@ pub fn run_summary_pair(app: &AppContext) -> Result<()> {
             },
         )?;
     } else {
-        output.line("warning: skipped .claude/rules/ generation because no workspace index exists");
+        output
+            .line("Warning: Skipped generating .claude/rules/ because no workspace index exists.");
         output.line(
-            "hint: run `gather-step index`, then `gather-step generate claude-md --target rules`",
+            "Hint: Run `gather-step index`, then `gather-step generate claude-md --target rules`.",
         );
     }
     if let Some(bar) = &generation_bar {

crates/gather-step-cli/src/commands/index.rs

@@ -356,7 +356,7 @@ pub async fn run(app: &AppContext, args: IndexArgs) -> Result<()> {
         workspace = %app.workspace_path.display(),
         config = %config_path.display(),
         repos = config.repos.len(),
-        "indexing from directory started",
+        "Indexing from directory started.",
     );
 
     let mut repo_results = Vec::with_capacity(config.repos.len());
@@ -504,7 +504,7 @@ pub async fn run(app: &AppContext, args: IndexArgs) -> Result<()> {
                     files = authoritative_files,
                     symbols = authoritative_symbols,
                     edges = authoritative_edges,
-                    "indexing from directory finished",
+                    "Indexing from directory finished.",
                 );
 
                 let depth_level = config_ref
@@ -560,7 +560,7 @@ pub async fn run(app: &AppContext, args: IndexArgs) -> Result<()> {
                 info!(
                     repo = %repo.name,
                     path = %repo_root.display(),
-                    "indexing from directory started",
+                    "Indexing from directory started.",
                 );
                 let prepare_start = Instant::now();
                 let payload = indexer_ref
@@ -842,14 +842,20 @@ pub async fn run(app: &AppContext, args: IndexArgs) -> Result<()> {
         storage_root = %storage_root.display(),
         duration_ms = total_wall_ms,
         index_size_bytes,
-        "indexing from directory finished",
+        "Indexing from directory finished.",
     );
 
     output.emit(&payload)?;
+    let repo_label = if payload.stats.indexed_repos == 1 {
+        "repository"
+    } else {
+        "repositories"
+    };
     output.line(format!(
-        "\n  {} {} repo(s)  {}",
+        "\n  {} {} {}  {}",
         style("✓ Indexed").green().bold(),
         style(payload.stats.indexed_repos).cyan(),
+        repo_label,
         style(&payload.storage_root).dim()
     ));
     output.line(format!(
@@ -865,7 +871,7 @@ pub async fn run(app: &AppContext, args: IndexArgs) -> Result<()> {
         style(format_bytes(payload.index_size_bytes)).dim(),
     ));
     for warning in &payload.warnings {
-        output.line(format!("  {} {warning}", style("warning:").yellow().bold()));
+        output.line(format!("  {} {warning}", style("Warning:").yellow().bold()));
     }
 
     // When `--artifact-path` is set, persist the IndexOutput payload so release

crates/gather-step-cli/src/commands/init.rs

@@ -139,8 +139,9 @@ async fn run_wizard(app: &AppContext, args: InitArgs) -> Result<()> {
         ));
     }
     output.line(format!(
-        "\n  Found {} git repo(s)",
+        "\n  Found {} {}",
         style(repos.len()).cyan().bold(),
+        style(git_repository_count_label(repos.len())).dim(),
     ));
     let selected_repos = prompt_repo_selection(1, &repos, existing_config_repos.as_deref())?;
 
@@ -171,7 +172,11 @@ async fn run_wizard(app: &AppContext, args: InitArgs) -> Result<()> {
     } else if args.no_watch {
         false
     } else {
-        prompt_yes_no(5, "Enable auto-reindex on repository changes?", false)?
+        prompt_yes_no(
+            5,
+            "Watch for repository changes and re-index automatically?",
+            false,
+        )?
     };
 
     write_default_config_with_repos(app, &args, &selected_repos, existing_config.as_ref())?;
@@ -222,15 +227,15 @@ fn write_default_config_with_repos(
 
     if repos.is_empty() {
         bail!(
-            "No git repositories found under {}",
+            "No Git repositories found under {}.",
             app.workspace_path.display()
         );
     }
 
     let configured_repos = materialize_repo_config(repos, existing_config);
     let config = match existing_config {
         Some(existing) => GatherStepConfig {
-            allow_listed_repos: existing.allow_listed_repos.clone(),
+            allow_listed_repos: retain_allow_listed_repos_for_selected(existing, &configured_repos),
             repos: configured_repos,
             github: existing.github.clone(),
             jira: existing.jira.clone(),
@@ -273,21 +278,41 @@ fn materialize_repo_config(
     repos
         .iter()
         .map(|repo| {
-            existing_by_path
-                .get(repo.relative_path.as_str())
-                .or_else(|| existing_by_name.get(repo.name.as_str()))
-                .map_or_else(
-                    || RepoConfig {
-                        name: repo.name.clone(),
-                        path: repo.relative_path.clone(),
-                        depth: None,
-                    },
-                    |existing| (*existing).clone(),
-                )
+            if let Some(existing) = existing_by_path.get(repo.relative_path.as_str()) {
+                return (*existing).clone();
+            }
+            if let Some(existing) = existing_by_name.get(repo.name.as_str()) {
+                return RepoConfig {
+                    name: existing.name.clone(),
+                    path: repo.relative_path.clone(),
+                    depth: existing.depth,
+                };
+            }
+            RepoConfig {
+                name: repo.name.clone(),
+                path: repo.relative_path.clone(),
+                depth: None,
+            }
         })
         .collect()
 }
 
+fn retain_allow_listed_repos_for_selected(
+    existing_config: &GatherStepConfig,
+    selected_repos: &[RepoConfig],
+) -> Vec<String> {
+    let selected_names = selected_repos
+        .iter()
+        .map(|repo| repo.name.as_str())
+        .collect::<BTreeSet<_>>();
+    existing_config
+        .allow_listed_repos
+        .iter()
+        .filter(|repo_name| selected_names.contains(repo_name.as_str()))
+        .cloned()
+        .collect()
+}
+
 fn emit_config_summary(
     app: &AppContext,
     config_path: &Path,
@@ -317,7 +342,7 @@ fn emit_config_summary(
     output.line(format!(
         "  {} {}",
         style(payload.repo_count).cyan().bold(),
-        style("configured repository(ies)").dim()
+        style(repository_count_label(payload.repo_count)).dim()
     ));
     for repo in payload.repos {
         output.line(format!(
@@ -332,9 +357,9 @@ fn emit_config_summary(
 
 fn emit_setup_complete(output: &crate::app::Output) {
     output.line(format!(
-        "\n  {} Gather Step is ready. Start planning with your agent, for example: {}. Docs: {}",
+        "\n  {} Gather Step is ready. Start planning with your agent. Example: {}. Docs: {}",
         style("✓ Setup complete.").green().bold(),
-        style("\"Start planning for Task A, use gather-step\"").cyan(),
+        style("\"Start planning your next task with gather-step\"").cyan(),
         style("https://gatherstep.dev/reference/mcp-tools/").underlined()
     ));
 }
@@ -361,6 +386,22 @@ fn discovered_repos_from_config(config: &GatherStepConfig) -> Vec<DiscoveredRepo
         .collect()
 }
 
+fn repository_count_label(count: usize) -> &'static str {
+    if count == 1 {
+        "configured repository"
+    } else {
+        "configured repositories"
+    }
+}
+
+fn git_repository_count_label(count: usize) -> &'static str {
+    if count == 1 {
+        "Git repository"
+    } else {
+        "Git repositories"
+    }
+}
+
 fn prompt_yes_no(step: usize, message: &str, default: bool) -> Result<bool> {
     let suffix = if default { "[Y/n]" } else { "[y/N]" };
     let mut stdout = io::stdout().lock();
@@ -412,7 +453,7 @@ fn prompt_repo_selection(
     existing_config_repos: Option<&[DiscoveredRepo]>,
 ) -> Result<Vec<DiscoveredRepo>> {
     if repos.is_empty() {
-        bail!("No git repositories found under the workspace");
+        bail!("No Git repositories found under the workspace.");
     }
 
     let default_names = existing_config_repos.map(|repos| {
@@ -502,7 +543,7 @@ fn prompt_repo_selection(
     }
 
     if selected.is_empty() {
-        bail!("select at least one repository before continuing");
+        bail!("Select at least one repository before continuing.");
     }
 
     Ok(selected
@@ -707,7 +748,12 @@ mod tests {
 
     use pretty_assertions::assert_eq;
 
-    use super::discover_git_repos;
+    use gather_step_core::{DepthLevel, GatherStepConfig, IndexingConfig, RepoConfig};
+
+    use super::{
+        DiscoveredRepo, discover_git_repos, materialize_repo_config,
+        retain_allow_listed_repos_for_selected,
+    };
 
     static TEMP_COUNTER: AtomicU64 = AtomicU64::new(0);
 
@@ -788,4 +834,65 @@ mod tests {
             ]
         );
     }
+
+    #[test]
+    fn repo_config_merge_filters_allow_list_to_selected_repos() {
+        let existing = GatherStepConfig {
+            allow_listed_repos: vec!["api".to_owned(), "web".to_owned()],
+            repos: vec![
+                RepoConfig {
+                    name: "api".to_owned(),
+                    path: "apps/api".to_owned(),
+                    depth: Some(DepthLevel::Level2),
+                },
+                RepoConfig {
+                    name: "web".to_owned(),
+                    path: "apps/web".to_owned(),
+                    depth: Some(DepthLevel::Level1),
+                },
+            ],
+            github: None,
+            jira: None,
+            indexing: IndexingConfig::default(),
+        };
+        let selected = vec![DiscoveredRepo {
+            name: "api".to_owned(),
+            relative_path: "apps/api".to_owned(),
+        }];
+        let merged = materialize_repo_config(&selected, Some(&existing));
+
+        assert_eq!(
+            retain_allow_listed_repos_for_selected(&existing, &merged),
+            vec!["api".to_owned()]
+        );
+    }
+
+    #[test]
+    fn repo_config_name_match_keeps_discovered_path() {
+        let existing = GatherStepConfig {
+            allow_listed_repos: Vec::new(),
+            repos: vec![RepoConfig {
+                name: "api".to_owned(),
+                path: "old/api".to_owned(),
+                depth: Some(DepthLevel::Level2),
+            }],
+            github: None,
+            jira: None,
+            indexing: IndexingConfig::default(),
+        };
+        let selected = vec![DiscoveredRepo {
+            name: "api".to_owned(),
+            relative_path: "new/api".to_owned(),
+        }];
+        let merged = materialize_repo_config(&selected, Some(&existing));
+
+        assert_eq!(
+            merged,
+            vec![RepoConfig {
+                name: "api".to_owned(),
+                path: "new/api".to_owned(),
+                depth: Some(DepthLevel::Level2),
+            }]
+        );
+    }
 }

crates/gather-step-cli/src/commands/tui.rs

@@ -106,7 +106,7 @@ pub fn run(app: &AppContext, args: TuiArgs) -> Result<()> {
 pub fn run_with_options(app: &AppContext, args: TuiArgs) -> Result<()> {
     if !app.tui_is_available() {
         bail!(
-            "TUI requires an interactive terminal\nhint: run `gather-step status`, `gather-step watch`, or pass `--json` for scriptable output"
+            "TUI requires an interactive terminal.\nHint: Run `gather-step status`, `gather-step watch`, or pass `--json` for scriptable output."
         );
     }
 

crates/gather-step-cli/tests/cli_init.rs

@@ -90,7 +90,7 @@ fn init_generate_ai_files_without_index_writes_summaries_and_skips_rules() {
         String::from_utf8_lossy(&output.stderr)
     );
     let stdout = String::from_utf8_lossy(&output.stdout);
-    assert!(stdout.contains("warning: skipped .claude/rules/ generation"));
+    assert!(stdout.contains("Warning: Skipped generating .claude/rules/"));
     assert!(tmp.path().join("CLAUDE.gather.md").exists());
     assert!(tmp.path().join("AGENTS.gather.md").exists());
     assert!(!tmp.path().join(".claude/rules").exists());

crates/gather-step-parser/src/tree_sitter.rs

@@ -3037,7 +3037,7 @@ fn resolve_python_sibling_package_import(
                         package = package_name,
                         first_package_dir = %first_package_dir.display(),
                         duplicate_package_dir = %package_dir.display(),
-                        "multiple sibling Python packages matched import; leaving import unresolved"
+                        "Multiple sibling Python packages matched import; leaving import unresolved."
                     );
                     return None;
                 }