@lamentis/naome 1.2.1 → 1.3.1

package/crates/naome-core/src/quality/adapter_ios.rs

@@ -0,0 +1,131 @@
+use super::adapters::{path_rule, test_file_limits};
+use super::types::{QualityLimitOverrides, QualityPathRule};
+
+pub(super) fn swift_path_rules() -> Vec<QualityPathRule> {
+    vec![path_rule(
+        "swift-source",
+        &["**/*.swift"],
+        source_limits(450, 300, 180, 100, 30, 10, 0.9),
+        &[],
+    )]
+}
+
+pub(super) fn xctest_path_rules() -> Vec<QualityPathRule> {
+    vec![path_rule(
+        "xctest-tests",
+        &[
+            "**/*Tests.swift",
+            "**/*UITests.swift",
+            "Tests/**/*.swift",
+            "**/Tests/**/*.swift",
+            "**/*Tests/**/*.swift",
+            "**/*UITests/**/*.swift",
+        ],
+        test_file_limits(80),
+        &[],
+    )]
+}
+
+pub(super) fn swiftui_path_rules() -> Vec<QualityPathRule> {
+    vec![path_rule(
+        "swiftui-views",
+        &[
+            "**/*View.swift",
+            "**/Views/**/*.swift",
+            "**/Preview Content/**",
+        ],
+        source_limits(360, 240, 160, 80, 24, 10, 0.92),
+        &[],
+    )]
+}
+
+pub(super) fn ios_app_structure_path_rules() -> Vec<QualityPathRule> {
+    vec![path_rule(
+        "ios-app-entrypoints",
+        &[
+            "**/*App.swift",
+            "**/AppDelegate.swift",
+            "**/SceneDelegate.swift",
+            "**/Info.plist",
+            "**/*.entitlements",
+        ],
+        source_limits(300, 220, 140, 80, 20, 10, 0.92),
+        &[],
+    )]
+}
+
+pub(super) fn swift_package_path_rules() -> Vec<QualityPathRule> {
+    vec![path_rule(
+        "swift-package-layout",
+        &["Package.swift", "Sources/**/*.swift", "Tests/**/*.swift"],
+        source_limits(450, 300, 180, 100, 30, 10, 0.9),
+        &[],
+    )]
+}
+
+pub(super) fn ios_resource_path_rules() -> Vec<QualityPathRule> {
+    vec![path_rule(
+        "ios-resources",
+        &[
+            "**/*.xcassets/**",
+            "**/*.strings",
+            "**/*.stringsdict",
+            "**/*.plist",
+            "**/*.entitlements",
+            "**/*.storyboard",
+            "**/*.xib",
+        ],
+        source_limits(700, 350, 250, 120, 80, 14, 0.96),
+        &["top-level-symbols", "function-length"],
+    )]
+}
+
+pub(super) fn generated_ios_path_rules() -> Vec<QualityPathRule> {
+    vec![path_rule(
+        "generated-ios",
+        GENERATED_IOS_PATHS,
+        source_limits(2_000, 2_000, 2_000, 300, 300, 30, 1.0),
+        &[
+            "file-length",
+            "new-file-length",
+            "diff-size",
+            "function-length",
+            "top-level-symbols",
+            "duplicate-blocks",
+            "near-duplicate-functions",
+        ],
+    )]
+}
+
+pub(super) const GENERATED_IOS_PATHS: &[&str] = &[
+    "Generated/**",
+    "**/Generated/**",
+    "SwiftGen/**",
+    "**/SwiftGen/**",
+    "Sourcery/**",
+    "**/Sourcery/**",
+    "**/*.generated.swift",
+    "**/*.pb.swift",
+    "**/*.grpc.swift",
+    "**/R.generated.swift",
+];
+
+fn source_limits(
+    max_file_lines: usize,
+    max_new_file_lines: usize,
+    max_diff_added_lines: usize,
+    max_function_lines: usize,
+    max_top_level_symbols: usize,
+    duplicate_block_lines: usize,
+    near_duplicate_similarity: f64,
+) -> QualityLimitOverrides {
+    QualityLimitOverrides {
+        max_file_lines: Some(max_file_lines),
+        max_new_file_lines: Some(max_new_file_lines),
+        max_diff_added_lines: Some(max_diff_added_lines),
+        max_function_lines: Some(max_function_lines),
+        max_top_level_symbols: Some(max_top_level_symbols),
+        duplicate_block_lines: Some(duplicate_block_lines),
+        near_duplicate_similarity: Some(near_duplicate_similarity),
+    }
+}

package/crates/naome-core/src/quality/adapter_support.rs

@@ -23,6 +23,25 @@ impl<'a> RepoSignals<'a> {
             .iter()
             .any(|path| extensions.iter().any(|extension| path.ends_with(extension)))
     }
+
+    pub(crate) fn has_path_containing(&self, fragments: &[&str]) -> bool {
+        self.paths.iter().any(|path| {
+            let lower = path.to_ascii_lowercase();
+            fragments.iter().any(|fragment| lower.contains(fragment))
+        })
+    }
+
+    pub(crate) fn has_file_name(&self, names: &[&str]) -> bool {
+        self.paths.iter().any(|path| {
+            let lower = path.to_ascii_lowercase();
+            path.rsplit('/').next().is_some_and(|file_name| {
+                names
+                    .iter()
+                    .any(|name| file_name.eq_ignore_ascii_case(name))
+                    || names.iter().any(|name| lower.ends_with(name))
+            })
+        })
+    }
 }
 
 pub(crate) trait AdapterDescriptor {
@@ -87,3 +106,51 @@ pub(crate) fn detects_javascript_typescript_project(signals: &RepoSignals<'_>) -
     signals.has_manifest("package.json")
         || signals.has_extension(&[".js", ".jsx", ".ts", ".tsx", ".mjs", ".cjs"])
 }
+
+pub(crate) fn detects_swift_project(signals: &RepoSignals<'_>) -> bool {
+    signals.has_manifest("Package.swift") || signals.has_extension(&[".swift"])
+}
+
+pub(crate) fn detects_xcode_project(signals: &RepoSignals<'_>) -> bool {
+    signals.has_path_containing(&[".xcodeproj/", ".xcworkspace/"])
+}
+
+pub(crate) fn detects_xctest_project(signals: &RepoSignals<'_>) -> bool {
+    signals.has_path_containing(&["tests/"])
+        && signals.has_file_name(&["tests.swift", "uitests.swift"])
+}
+
+pub(crate) fn detects_swiftui_project(signals: &RepoSignals<'_>) -> bool {
+    signals.has_file_name(&["view.swift", "app.swift"])
+        || signals.has_path_containing(&["preview content/"])
+}
+
+pub(crate) fn detects_ios_app_structure_project(signals: &RepoSignals<'_>) -> bool {
+    detects_xcode_project(signals)
+        || signals.has_file_name(&["appdelegate.swift", "scenedelegate.swift", "info.plist"])
+        || signals.has_path_containing(&[".xcassets/"])
+}
+
+pub(crate) fn detects_swift_package_project(signals: &RepoSignals<'_>) -> bool {
+    signals.has_manifest("Package.swift")
+        || signals.has_path_containing(&["sources/", "tests/"])
+            && signals.has_extension(&[".swift"])
+}
+
+pub(crate) fn detects_ios_resources_project(signals: &RepoSignals<'_>) -> bool {
+    signals.has_path_containing(&[".xcassets/"])
+        || signals.has_extension(&[
+            ".strings",
+            ".stringsdict",
+            ".plist",
+            ".entitlements",
+            ".storyboard",
+            ".xib",
+        ])
+}
+
+pub(crate) fn detects_generated_ios_project(signals: &RepoSignals<'_>) -> bool {
+    signals.has_path_containing(&["generated/", "swiftgen/", "sourcery/"])
+        || signals.has_file_name(&["r.generated.swift"])
+        || signals.has_extension(&[".generated.swift", ".pb.swift", ".grpc.swift"])
+}

package/crates/naome-core/src/quality/adapters.rs

@@ -1,8 +1,12 @@
 use crate::models::NaomeError;
 
+use super::adapter_ios;
 use super::adapter_support::{
-    detected_ids, detects_javascript_typescript_project, detects_rust_project, extend_unique,
-    find_adapter_by_id, validate_ids, AdapterDescriptor, RepoSignals,
+    detected_ids, detects_generated_ios_project, detects_ios_app_structure_project,
+    detects_ios_resources_project, detects_javascript_typescript_project, detects_rust_project,
+    detects_swift_package_project, detects_swift_project, detects_swiftui_project,
+    detects_xcode_project, detects_xctest_project, extend_unique, find_adapter_by_id, validate_ids,
+    AdapterDescriptor, RepoSignals,
 };
 use super::types::{QualityLimitOverrides, QualityPathRule, RepositoryQualityConfig};
 
@@ -49,21 +53,76 @@ pub(crate) fn validate_adapter_ids(ids: &[String]) -> Result<(), NaomeError> {
     validate_ids(ids, registry(), CONFIG_PATH)
 }
 
+const QUALITY_ADAPTERS: &[QualityAdapter] = &[
+    QualityAdapter {
+        id: "rust",
+        generated_paths: &[],
+        detect: detects_rust_project,
+        path_rules: rust_path_rules,
+    },
+    QualityAdapter {
+        id: "javascript-typescript",
+        generated_paths: &["coverage/**", "**/coverage/**", ".next/**", "**/.next/**"],
+        detect: detects_javascript_typescript_project,
+        path_rules: javascript_typescript_path_rules,
+    },
+    QualityAdapter {
+        id: "swift",
+        generated_paths: &[],
+        detect: detects_swift_project,
+        path_rules: adapter_ios::swift_path_rules,
+    },
+    QualityAdapter {
+        id: "xcode",
+        generated_paths: &[
+            "DerivedData/**",
+            "**/DerivedData/**",
+            "**/xcuserdata/**",
+            "**/*.xcuserstate",
+        ],
+        detect: detects_xcode_project,
+        path_rules: empty_path_rules,
+    },
+    QualityAdapter {
+        id: "xctest",
+        generated_paths: &[],
+        detect: detects_xctest_project,
+        path_rules: adapter_ios::xctest_path_rules,
+    },
+    QualityAdapter {
+        id: "swiftui",
+        generated_paths: &["**/Preview Content/**"],
+        detect: detects_swiftui_project,
+        path_rules: adapter_ios::swiftui_path_rules,
+    },
+    QualityAdapter {
+        id: "ios-app-structure",
+        generated_paths: &[],
+        detect: detects_ios_app_structure_project,
+        path_rules: adapter_ios::ios_app_structure_path_rules,
+    },
+    QualityAdapter {
+        id: "swift-package",
+        generated_paths: &[],
+        detect: detects_swift_package_project,
+        path_rules: adapter_ios::swift_package_path_rules,
+    },
+    QualityAdapter {
+        id: "ios-resources",
+        generated_paths: &[],
+        detect: detects_ios_resources_project,
+        path_rules: adapter_ios::ios_resource_path_rules,
+    },
+    QualityAdapter {
+        id: "generated-ios",
+        generated_paths: adapter_ios::GENERATED_IOS_PATHS,
+        detect: detects_generated_ios_project,
+        path_rules: adapter_ios::generated_ios_path_rules,
+    },
+];
+
 fn registry() -> &'static [QualityAdapter] {
-    &[
-        QualityAdapter {
-            id: "rust",
-            generated_paths: &[],
-            detect: detects_rust_project,
-            path_rules: rust_path_rules,
-        },
-        QualityAdapter {
-            id: "javascript-typescript",
-            generated_paths: &["coverage/**", "**/coverage/**", ".next/**", "**/.next/**"],
-            detect: detects_javascript_typescript_project,
-            path_rules: javascript_typescript_path_rules,
-        },
-    ]
+    QUALITY_ADAPTERS
 }
 
 fn rust_path_rules() -> Vec<QualityPathRule> {
@@ -84,6 +143,10 @@ fn javascript_typescript_path_rules() -> Vec<QualityPathRule> {
     }]
 }
 
+fn empty_path_rules() -> Vec<QualityPathRule> {
+    Vec::new()
+}
+
 fn javascript_typescript_test_paths() -> Vec<String> {
     let mut paths = Vec::new();
     for marker in ["test", "spec"] {
@@ -100,7 +163,7 @@ fn javascript_typescript_test_paths() -> Vec<String> {
     paths
 }
 
-fn test_file_limits(max_top_level_symbols: usize) -> QualityLimitOverrides {
+pub(super) fn test_file_limits(max_top_level_symbols: usize) -> QualityLimitOverrides {
     QualityLimitOverrides {
         max_file_lines: Some(650),
         max_diff_added_lines: Some(220),
@@ -112,7 +175,7 @@ fn test_file_limits(max_top_level_symbols: usize) -> QualityLimitOverrides {
     }
 }
 
-fn path_rule(
+pub(super) fn path_rule(
     id: &str,
     paths: &[&str],
     limits: QualityLimitOverrides,

package/crates/naome-core/src/quality/baseline.rs

@@ -73,3 +73,11 @@ pub fn write_baseline(root: &Path, violations: &[QualityViolation]) -> Result<bo
     }
     Ok(changed)
 }
+
+pub fn write_empty_baseline_if_missing(root: &Path) -> Result<bool, NaomeError> {
+    let path = root.join(BASELINE_RELATIVE_PATH);
+    if path.is_file() {
+        return Ok(false);
+    }
+    write_baseline(root, &[])
+}

package/crates/naome-core/src/quality/cache.rs

@@ -0,0 +1,151 @@
+use std::fs;
+use std::path::{Path, PathBuf};
+
+use serde::{Deserialize, Serialize};
+use sha2::{Digest, Sha256};
+
+use crate::models::NaomeError;
+
+use super::scanner::FileAnalysis;
+use super::types::RepositoryQualityConfig;
+
+const CACHE_RELATIVE_PATH: &str = ".naome/cache/quality";
+const CACHE_SCHEMA: &str = "naome.quality-cache-entry.v1";
+const ADAPTER_VERSION: &str = "quality-core-v1";
+
+#[derive(Debug, Clone)]
+pub(crate) struct QualityCache {
+    root: PathBuf,
+    config_hash: String,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+struct CacheEntry {
+    schema: String,
+    naome_version: String,
+    config_hash: String,
+    adapter_version: String,
+    path: String,
+    content_hash: String,
+    analysis: FileAnalysis,
+}
+
+#[derive(Debug, Clone, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct QualityCacheStatus {
+    pub schema: String,
+    pub path: String,
+    pub entry_count: usize,
+    pub bytes: u64,
+}
+
+impl QualityCache {
+    pub(crate) fn new(root: &Path, config: &RepositoryQualityConfig) -> Self {
+        Self {
+            root: root.to_path_buf(),
+            config_hash: config_hash(config),
+        }
+    }
+
+    pub(crate) fn read(&self, path: &str, content_hash: &str) -> Option<FileAnalysis> {
+        let entry = fs::read_to_string(self.entry_path(path, content_hash)).ok()?;
+        let entry: CacheEntry = serde_json::from_str(&entry).ok()?;
+        if entry.schema == CACHE_SCHEMA
+            && entry.naome_version == env!("CARGO_PKG_VERSION")
+            && entry.config_hash == self.config_hash
+            && entry.adapter_version == ADAPTER_VERSION
+            && entry.path == path
+            && entry.content_hash == content_hash
+        {
+            Some(entry.analysis)
+        } else {
+            None
+        }
+    }
+
+    pub(crate) fn write(
+        &self,
+        path: &str,
+        content_hash: &str,
+        analysis: &FileAnalysis,
+    ) -> Result<(), NaomeError> {
+        let cache_path = self.entry_path(path, content_hash);
+        if let Some(parent) = cache_path.parent() {
+            fs::create_dir_all(parent)?;
+        }
+        let entry = CacheEntry {
+            schema: CACHE_SCHEMA.to_string(),
+            naome_version: env!("CARGO_PKG_VERSION").to_string(),
+            config_hash: self.config_hash.clone(),
+            adapter_version: ADAPTER_VERSION.to_string(),
+            path: path.to_string(),
+            content_hash: content_hash.to_string(),
+            analysis: analysis.clone(),
+        };
+        let content = format!("{}\n", serde_json::to_string(&entry)?);
+        if fs::read_to_string(&cache_path).map_or(true, |current| current != content) {
+            fs::write(cache_path, content)?;
+        }
+        Ok(())
+    }
+
+    fn entry_path(&self, path: &str, content_hash: &str) -> PathBuf {
+        self.root.join(CACHE_RELATIVE_PATH).join(stable_key(&[
+            env!("CARGO_PKG_VERSION"),
+            &self.config_hash,
+            ADAPTER_VERSION,
+            path,
+            content_hash,
+        ]))
+    }
+}
+
+pub fn quality_cache_status(root: &Path) -> Result<QualityCacheStatus, NaomeError> {
+    let path = root.join(CACHE_RELATIVE_PATH);
+    let mut entry_count = 0;
+    let mut bytes = 0;
+    if path.is_dir() {
+        for entry in fs::read_dir(&path)? {
+            let entry = entry?;
+            let metadata = entry.metadata()?;
+            if metadata.is_file() {
+                entry_count += 1;
+                bytes += metadata.len();
+            }
+        }
+    }
+    Ok(QualityCacheStatus {
+        schema: "naome.quality-cache-status.v1".to_string(),
+        path: CACHE_RELATIVE_PATH.to_string(),
+        entry_count,
+        bytes,
+    })
+}
+
+pub fn clear_quality_cache(root: &Path) -> Result<QualityCacheStatus, NaomeError> {
+    let path = root.join(CACHE_RELATIVE_PATH);
+    if path.exists() {
+        fs::remove_dir_all(&path)?;
+    }
+    quality_cache_status(root)
+}
+
+pub(crate) fn content_hash(content: &str) -> String {
+    stable_key(&[content])
+}
+
+fn config_hash(config: &RepositoryQualityConfig) -> String {
+    serde_json::to_string(config)
+        .map(|content| stable_key(&[&content]))
+        .unwrap_or_else(|_| stable_key(&["invalid-config"]))
+}
+
+fn stable_key(parts: &[&str]) -> String {
+    let mut hasher = Sha256::new();
+    for part in parts {
+        hasher.update(part.as_bytes());
+        hasher.update(b"\0");
+    }
+    format!("{:x}.json", hasher.finalize())
+}

package/crates/naome-core/src/quality/checks/duplicate_blocks.rs

@@ -1,6 +1,8 @@
 use std::collections::{HashMap, HashSet};
 
-use super::super::scanner::{stable_fingerprint, QualityContext};
+use sha2::{Digest, Sha256};
+
+use super::super::scanner::{stable_fingerprint, NormalizedLine, QualityContext};
 use super::super::types::QualityViolation;
 use super::{is_code_like_path, QualityCheck};
 
@@ -12,8 +14,11 @@ impl QualityCheck for DuplicateBlockCheck {
     }
 
     fn evaluate(&self, context: &QualityContext, violations: &mut Vec<QualityViolation>) {
+        if context.mode == super::super::types::QualityMode::Report {
+            return;
+        }
         let mut occurrences: HashMap<String, Vec<DuplicateOccurrence>> = HashMap::new();
-        for file in context.files.iter().filter(|file| {
+        for file in context.comparison_candidate_files().filter(|file| {
             is_code_like_path(&file.path)
                 && context.config.check_enabled_for_path(self.id(), &file.path)
         }) {
@@ -22,12 +27,7 @@ impl QualityCheck for DuplicateBlockCheck {
                 continue;
             }
             for lines in file.normalized_lines.windows(window) {
-                let joined = lines
-                    .iter()
-                    .map(|line| line.value.as_str())
-                    .collect::<Vec<_>>()
-                    .join("\n");
-                let fingerprint = stable_fingerprint(&[self.id(), &joined]);
+                let fingerprint = window_fingerprint(self.id(), lines);
                 occurrences
                     .entry(fingerprint.clone())
                     .or_default()
@@ -72,6 +72,17 @@ impl QualityCheck for DuplicateBlockCheck {
     }
 }
 
+fn window_fingerprint(check_id: &str, lines: &[NormalizedLine]) -> String {
+    let mut hasher = Sha256::new();
+    hasher.update(check_id.as_bytes());
+    hasher.update(b"\0");
+    for line in lines {
+        hasher.update(line.value.as_bytes());
+        hasher.update(b"\n");
+    }
+    format!("sha256:{:x}", hasher.finalize())
+}
+
 #[derive(Debug, Clone)]
 struct DuplicateOccurrence {
     path: String,

package/crates/naome-core/src/quality/checks/near_duplicates.rs

@@ -12,6 +12,9 @@ impl QualityCheck for NearDuplicateFunctionCheck {
     }
 
     fn evaluate(&self, context: &QualityContext, violations: &mut Vec<QualityViolation>) {
+        if context.mode == super::super::types::QualityMode::Report {
+            return;
+        }
         let symbols = collect_function_occurrences(context, self.id());
         let mut emitted = HashSet::new();
 
@@ -59,8 +62,7 @@ fn collect_function_occurrences<'a>(
     check_id: &str,
 ) -> Vec<FunctionOccurrence<'a>> {
     context
-        .files
-        .iter()
+        .comparison_candidate_files()
         .filter(|file| {
             is_code_like_path(&file.path)
                 && context.config.check_enabled_for_path(check_id, &file.path)

package/crates/naome-core/src/quality/checks.rs

@@ -4,7 +4,7 @@ mod near_duplicates;
 use std::collections::HashSet;
 
 use super::scanner::{stable_fingerprint, QualityContext};
-use super::types::{QualityMode, QualityViolation};
+use super::types::QualityViolation;
 use duplicate_blocks::DuplicateBlockCheck;
 use near_duplicates::NearDuplicateFunctionCheck;
 
@@ -64,12 +64,11 @@ impl QualityCheck for FileLengthCheck {
             .filter(|file| context.check_applies_to(self.id(), &file.path))
         {
             let limits = context.limits_for(&file.path);
-            let limit =
-                if context.mode == QualityMode::Changed && file.added_lines == file.line_count {
-                    limits.max_new_file_lines
-                } else {
-                    limits.max_file_lines
-                };
+            let limit = if context.mode.is_changed() && file.added_lines == file.line_count {
+                limits.max_new_file_lines
+            } else {
+                limits.max_file_lines
+            };
             if file.line_count > limit {
                 violations.push(violation(
                     self.id(),
@@ -96,7 +95,7 @@ impl QualityCheck for DiffGrowthCheck {
     }
 
     fn evaluate(&self, context: &QualityContext, violations: &mut Vec<QualityViolation>) {
-        if context.mode != QualityMode::Changed {
+        if !context.mode.is_changed() {
             return;
         }
         for file in context

package/crates/naome-core/src/quality/cleanup.rs

@@ -68,17 +68,50 @@ pub fn cleanup_route_for_path(
     } else {
         "repository quality"
     };
+    let agent_instructions = cleanup_instructions(path, topic, &violations);
     QualityCleanupRoute {
         schema: "naome.quality-cleanup-route.v1".to_string(),
         path: path.to_string(),
         violations,
         related_paths,
-        agent_instructions: format!(
-            "Reduce or split {path} until every {topic} violation is gone. Prefer named modules and reusable helpers/components over dumping logic into generic directories. Keep behavior unchanged, add or preserve focused tests, then run naome quality check --changed before task completion."
-        ),
+        agent_instructions,
         required_checks: vec![
             "naome quality check --changed".to_string(),
             "git diff --check".to_string(),
         ],
     }
 }
+
+fn cleanup_instructions(path: &str, topic: &str, violations: &[QualityViolation]) -> String {
+    let mut instructions = Vec::new();
+    instructions.push(format!(
+        "Clean up {path} until every {topic} violation is gone while preserving behavior."
+    ));
+    for check_id in violations
+        .iter()
+        .map(|violation| violation.check_id.as_str())
+        .collect::<BTreeSet<_>>()
+    {
+        instructions.push(match check_id {
+            "test-source-pairing" => "Create or update a nearby or module-matched test that exercises the changed source behavior.".to_string(),
+            "dumping-ground-directory" => "Move feature logic out of generic utils/helpers/common/shared directories into a named module, or extract a reusable helper with a clear owner.".to_string(),
+            "directory-role-mixing" => "Separate source, generated, artifact, and dependency/vendor roles into directories that match repository policy.".to_string(),
+            "misplaced-file-role" => "Move the file to a configured root for its role, such as source, test, docs, config, or script.".to_string(),
+            "root-file-sprawl" => "Move new root-level work into an existing module, docs, config, or script directory unless it is a recognized root manifest.".to_string(),
+            "directory-size" => "Split the directory by module or responsibility until direct file count is below the configured limit.".to_string(),
+            "path-depth" => "Shorten the path by moving the file closer to its owning module boundary.".to_string(),
+            "case-collision" => "Rename colliding paths so they are distinct on case-insensitive filesystems.".to_string(),
+            "file-length" => "Reduce or split the file into focused modules with stable public behavior.".to_string(),
+            "function-length" => "Extract cohesive helper functions or components until each function fits the configured limit.".to_string(),
+            "top-level-symbols" => "Group related symbols into smaller modules and export only the intended public surface.".to_string(),
+            "duplicate-block" | "near-duplicate-function" => "Extract shared behavior into a reusable helper, fixture, builder, or component used by all duplicate call sites.".to_string(),
+            "diff-growth" => "Reduce the diff by narrowing scope, splitting generated changes, or moving unrelated cleanup to a separate task.".to_string(),
+            _ => format!("Resolve the {check_id} finding without weakening generic policy."),
+        });
+    }
+    instructions.push(
+        "Run naome quality check --changed and git diff --check before task completion."
+            .to_string(),
+    );
+    instructions.join(" ")
+}