@lamentis/naome 1.3.13 → 1.3.14

package/Cargo.lock

@@ -76,7 +76,7 @@ checksum = "f8ca58f447f06ed17d5fc4043ce1b10dd205e060fb3ce5b979b8ed8e59ff3f79"
 
 [[package]]
 name = "naome-cli"
-version = "1.3.13"
+version = "1.3.14"
 dependencies = [
  "naome-core",
  "serde_json",
@@ -84,7 +84,7 @@ dependencies = [
 
 [[package]]
 name = "naome-core"
-version = "1.3.13"
+version = "1.3.14"
 dependencies = [
  "serde",
  "serde_json",

package/crates/naome-cli/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "naome-cli"
-version = "1.3.13"
+version = "1.3.14"
 edition.workspace = true
 license.workspace = true
 repository.workspace = true

package/crates/naome-cli/src/architecture_commands.rs

@@ -53,7 +53,7 @@ fn run_arch_explain(root: &Path, args: &[String]) -> Result<(), Box<dyn std::err
                 "layers": scan.config.layers.keys().collect::<Vec<_>>(),
                 "contexts": scan.config.contexts.keys().collect::<Vec<_>>(),
                 "rules": ARCHITECTURE_RULE_IDS,
-                "extractors": ["path", "typescript", "javascript", "rust", "python", "go"]
+                "extractors": ["path", "typescript", "javascript", "rust", "python", "go", "swift"]
             }))?
         );
     } else {

package/crates/naome-core/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "naome-core"
-version = "1.3.13"
+version = "1.3.14"
 edition.workspace = true
 license.workspace = true
 repository.workspace = true

package/crates/naome-core/src/architecture/output.rs

@@ -54,6 +54,8 @@ pub struct ArchitectureValidation {
     pub rules_executed: Vec<String>,
     pub changed_only_requested: bool,
     pub changed_only_degraded_to_full_scan: bool,
+    pub changed_only_mode: String,
+    pub changed_only_degradation_reason: Option<String>,
     pub violations: Vec<ArchitectureViolation>,
     #[serde(rename = "agent_feedback")]
     pub agent_feedback: Vec<ArchitectureAgentFeedback>,
@@ -134,7 +136,15 @@ pub fn format_architecture_validation(report: &ArchitectureValidation) -> String
     ];
 
     if report.changed_only_degraded_to_full_scan {
-        lines.push("changed-only requested: degraded to full scan for soundness".to_string());
+        let reason = report
+            .changed_only_degradation_reason
+            .as_deref()
+            .unwrap_or("soundness");
+        lines.push(format!(
+            "changed-only requested: degraded to full scan for soundness ({reason})"
+        ));
+    } else if report.changed_only_requested {
+        lines.push("changed-only requested: using incremental architecture cache".to_string());
     }
 
     for violation in report.violations.iter().take(10) {
@@ -152,12 +162,24 @@ pub fn format_architecture_validation(report: &ArchitectureValidation) -> String
 }
 
 pub fn format_architecture_scan(report: &ArchitectureScanReport) -> String {
-    format!(
+    let mut output = format!(
         "NAOME architecture scan\nfiles scanned: {}\ngraph nodes: {}\ngraph edges: {}\n",
         report.files_scanned,
         report.graph.nodes.len(),
         report.graph.edges.len()
-    )
+    );
+    if report.changed_only_degraded_to_full_scan {
+        let reason = report
+            .changed_only_degradation_reason
+            .as_deref()
+            .unwrap_or("soundness");
+        output.push_str(&format!(
+            "changed-only requested: degraded to full scan for soundness ({reason})\n"
+        ));
+    } else if report.changed_only_requested {
+        output.push_str("changed-only requested: using incremental architecture cache\n");
+    }
+    output
 }
 
 pub fn format_architecture_explain(scan: &ArchitectureScanReport) -> String {
@@ -176,7 +198,7 @@ pub fn format_architecture_explain(scan: &ArchitectureScanReport) -> String {
         .collect::<Vec<_>>()
         .join(", ");
     format!(
-        "NAOME Architecture Fitness\nrules: {}\nlayers: {}\ncontexts: {}\npath extractor: enabled for every repository\nimport extractors: typescript, javascript, rust, python, go\n",
+        "NAOME Architecture Fitness\nrules: {}\nlayers: {}\ncontexts: {}\npath extractor: enabled for every repository\nimport extractors: typescript, javascript, rust, python, go, swift\n",
         ARCHITECTURE_RULE_IDS.join(", "),
         empty_label(&layers),
         empty_label(&contexts)

package/crates/naome-core/src/architecture/rules.rs

@@ -55,6 +55,8 @@ pub fn validate_scan(scan: ArchitectureScanReport) -> ArchitectureValidation {
         rules_executed,
         changed_only_requested: scan.changed_only_requested,
         changed_only_degraded_to_full_scan: scan.changed_only_degraded_to_full_scan,
+        changed_only_mode: scan.changed_only_mode,
+        changed_only_degradation_reason: scan.changed_only_degradation_reason,
         violations,
         agent_feedback,
     }

package/crates/naome-core/src/architecture/scan/cache.rs

@@ -0,0 +1,145 @@
+use std::collections::{BTreeMap, BTreeSet};
+use std::fs;
+use std::path::Path;
+
+use serde::{Deserialize, Serialize};
+use sha2::{Digest, Sha256};
+
+use super::FileFact;
+use crate::models::NaomeError;
+
+const CACHE_SCHEMA: &str = "naome.architecture-cache.v1";
+const EXTRACTOR_VERSION: &str = "architecture-cache-v1.3.14";
+const CACHE_PATH: &str = ".naome/cache/architecture/cache.json";
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub(super) struct ArchitectureCache {
+    pub schema: String,
+    pub extractor_version: String,
+    pub config_hash: String,
+    pub file_list_hash: String,
+    pub files: BTreeMap<String, CachedFileFact>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub(super) struct CachedFileFact {
+    pub content_hash: String,
+    pub fact: FileFact,
+}
+
+impl ArchitectureCache {
+    pub(super) fn is_compatible(&self, config_hash: &str, file_list_hash: &str) -> CacheStatus {
+        if self.schema != CACHE_SCHEMA || self.extractor_version != EXTRACTOR_VERSION {
+            return CacheStatus::Miss("cache_miss");
+        }
+        if self.config_hash != config_hash {
+            return CacheStatus::Miss("config_changed");
+        }
+        if self.file_list_hash != file_list_hash {
+            return CacheStatus::Miss("file_set_changed");
+        }
+        CacheStatus::Hit
+    }
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub(super) enum CacheStatus {
+    Hit,
+    Miss(&'static str),
+}
+
+pub(super) fn read(root: &Path) -> Option<ArchitectureCache> {
+    let content = fs::read_to_string(root.join(CACHE_PATH)).ok()?;
+    serde_json::from_str(&content).ok()
+}
+
+pub(super) fn write(
+    root: &Path,
+    config_hash: String,
+    file_list_hash: String,
+    file_facts: &BTreeMap<String, FileFact>,
+) -> Result<(), NaomeError> {
+    let cache = ArchitectureCache {
+        schema: CACHE_SCHEMA.to_string(),
+        extractor_version: EXTRACTOR_VERSION.to_string(),
+        config_hash,
+        file_list_hash,
+        files: file_facts
+            .iter()
+            .filter_map(|(path, fact)| {
+                let content_hash = content_hash(root, path).ok()?;
+                Some((
+                    path.clone(),
+                    CachedFileFact {
+                        content_hash,
+                        fact: fact.clone(),
+                    },
+                ))
+            })
+            .collect(),
+    };
+    let path = root.join(CACHE_PATH);
+    if let Some(parent) = path.parent() {
+        fs::create_dir_all(parent)?;
+    }
+    fs::write(path, serde_json::to_string_pretty(&cache)?)?;
+    Ok(())
+}
+
+pub(super) fn config_hash(
+    root: &Path,
+    explicit_path: Option<&Path>,
+    default_content: &str,
+) -> Result<String, NaomeError> {
+    let path = explicit_path
+        .map(Path::to_path_buf)
+        .unwrap_or_else(|| root.join("naome.arch.yaml"));
+    let source = if path.exists() {
+        fs::read_to_string(&path)?
+    } else {
+        default_content.to_string()
+    };
+    let label = display_path(root, &path);
+    Ok(stable_hash([
+        b"architecture-config-v1".as_slice(),
+        label.as_bytes(),
+        source.as_bytes(),
+    ]))
+}
+
+pub(super) fn file_list_hash(files: &[String]) -> String {
+    let mut hasher = Sha256::new();
+    hasher.update(b"architecture-file-list-v1");
+    for path in files {
+        hasher.update([0]);
+        hasher.update(path.as_bytes());
+    }
+    format!("sha256:{:x}", hasher.finalize())
+}
+
+pub(super) fn content_hash(root: &Path, path: &str) -> Result<String, NaomeError> {
+    let bytes = fs::read(root.join(path))?;
+    Ok(stable_hash([b"architecture-file-v1".as_slice(), &bytes]))
+}
+
+pub(super) fn changed_set(changed_paths: &[String]) -> BTreeSet<String> {
+    changed_paths.iter().cloned().collect()
+}
+
+fn stable_hash<'a>(parts: impl IntoIterator<Item = &'a [u8]>) -> String {
+    let mut hasher = Sha256::new();
+    for part in parts {
+        hasher.update(part);
+        hasher.update([0]);
+    }
+    format!("sha256:{:x}", hasher.finalize())
+}
+
+fn display_path(root: &Path, path: &Path) -> String {
+    path.strip_prefix(root)
+        .unwrap_or(path)
+        .to_string_lossy()
+        .replace('\\', "/")
+}

package/crates/naome-core/src/architecture/scan/graph_builder.rs

@@ -18,25 +18,46 @@ pub(super) fn build_path_graph(
     config: &ArchitectureConfig,
     manifests: &[ManifestFact],
 ) -> (ArchitectureGraph, BTreeMap<String, FileFact>) {
-    let mut graph = ArchitectureGraph::default();
     let mut file_facts = BTreeMap::new();
-    let mut emitted_external_nodes = BTreeSet::new();
     let file_set = files.iter().cloned().collect::<BTreeSet<_>>();
+    for path in &files {
+        file_facts.insert(path.clone(), scan_file_fact(root, path, config, &file_set));
+    }
+    let graph = build_graph_from_facts(&files, &file_facts, config, manifests);
+    (graph, file_facts)
+}
+
+pub(super) fn scan_file_fact(
+    root: &Path,
+    path: &str,
+    config: &ArchitectureConfig,
+    file_set: &BTreeSet<String>,
+) -> FileFact {
+    let content = fs::read_to_string(root.join(path)).unwrap_or_default();
+    let mut fact = facts::file_fact(path, &content, config);
+    fact.imports = imports::extract_imports(root, path, &content, file_set);
+    fact
+}
+
+pub(super) fn build_graph_from_facts(
+    files: &[String],
+    file_facts: &BTreeMap<String, FileFact>,
+    config: &ArchitectureConfig,
+    manifests: &[ManifestFact],
+) -> ArchitectureGraph {
+    let mut graph = ArchitectureGraph::default();
+    let mut emitted_external_nodes = BTreeSet::new();
 
     push_repository_and_policy_nodes(&mut graph, config);
-    push_directories(&mut graph, &files);
+    push_directories(&mut graph, files);
     push_manifests(&mut graph, manifests, &mut emitted_external_nodes);
 
-    for path in files {
-        let content = fs::read_to_string(root.join(&path)).unwrap_or_default();
-        let mut fact = facts::file_fact(&path, &content, config);
-        fact.imports = imports::extract_imports(root, &path, &content, &file_set);
+    for fact in file_facts.values() {
         push_file(&mut graph, &fact);
-        file_facts.insert(path, fact);
     }
 
-    push_imports(&mut graph, &file_facts, &mut emitted_external_nodes);
-    (graph, file_facts)
+    push_imports(&mut graph, file_facts, &mut emitted_external_nodes);
+    graph
 }
 
 fn push_repository_and_policy_nodes(graph: &mut ArchitectureGraph, config: &ArchitectureConfig) {

package/crates/naome-core/src/architecture/scan.rs

@@ -1,14 +1,19 @@
 use std::collections::BTreeMap;
 use std::path::{Path, PathBuf};
 
-use serde::Serialize;
+use serde::{Deserialize, Serialize};
 
 use crate::git;
 use crate::models::NaomeError;
 
-use super::config::{read_architecture_config, ArchitectureConfig};
+use cache::CacheStatus;
+
+use super::config::{
+    default_architecture_config_text, read_architecture_config, ArchitectureConfig,
+};
 use super::model::ArchitectureGraph;
 
+mod cache;
 mod graph_builder;
 mod imports;
 mod manifest;
@@ -28,6 +33,8 @@ pub struct ArchitectureScanReport {
     pub files_scanned: usize,
     pub changed_only_requested: bool,
     pub changed_only_degraded_to_full_scan: bool,
+    pub changed_only_mode: String,
+    pub changed_only_degradation_reason: Option<String>,
     pub changed_paths: Vec<String>,
     #[serde(skip_serializing)]
     pub config: ArchitectureConfig,
@@ -37,7 +44,7 @@ pub struct ArchitectureScanReport {
     pub manifest_facts: Vec<ManifestFact>,
 }
 
-#[derive(Debug, Clone, Serialize)]
+#[derive(Debug, Clone, Serialize, Deserialize)]
 #[serde(rename_all = "camelCase")]
 pub struct FileFact {
     pub path: String,
@@ -49,7 +56,7 @@ pub struct FileFact {
     pub imports: Vec<ImportFact>,
 }
 
-#[derive(Debug, Clone, Serialize)]
+#[derive(Debug, Clone, Serialize, Deserialize)]
 #[serde(rename_all = "camelCase")]
 pub struct ImportFact {
     pub specifier: String,
@@ -59,7 +66,7 @@ pub struct ImportFact {
     pub extractor: String,
 }
 
-#[derive(Debug, Clone, Serialize, PartialEq, Eq)]
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
 #[serde(rename_all = "camelCase")]
 pub enum ImportTarget {
     File(String),
@@ -67,7 +74,7 @@ pub enum ImportTarget {
     Unknown(String),
 }
 
-#[derive(Debug, Clone, Serialize)]
+#[derive(Debug, Clone, Serialize, Deserialize)]
 #[serde(rename_all = "camelCase")]
 pub struct ManifestFact {
     pub path: String,
@@ -78,7 +85,7 @@ pub struct ManifestFact {
     pub extractor: String,
 }
 
-#[derive(Debug, Clone, Serialize)]
+#[derive(Debug, Clone, Serialize, Deserialize)]
 #[serde(rename_all = "camelCase")]
 pub struct ManifestDependency {
     pub name: String,
@@ -94,24 +101,235 @@ pub fn scan_architecture(
     let config = read_architecture_config(root, options.config_path.as_deref())?;
     let changed_paths = changed_paths(root, options.changed_only)?;
     let files = path_scan::repository_files(root, &config)?;
+    let config_hash = cache::config_hash(
+        root,
+        options.config_path.as_deref(),
+        default_architecture_config_text(),
+    )?;
+    let file_list_hash = cache::file_list_hash(&files);
     let manifest_facts = manifest::extract_manifests(root, &files);
-    let (mut graph, file_facts) =
-        graph_builder::build_path_graph(root, files, &config, &manifest_facts);
 
+    let scan = if options.changed_only {
+        changed_only_scan(
+            root,
+            files,
+            &config,
+            &manifest_facts,
+            &changed_paths,
+            config_hash,
+            file_list_hash,
+        )?
+    } else {
+        full_scan(
+            root,
+            files,
+            &config,
+            &manifest_facts,
+            config_hash,
+            file_list_hash,
+            false,
+            None,
+            "full_scan",
+        )?
+    };
+
+    Ok(scan.with_changed_paths(changed_paths))
+}
+
+fn changed_only_scan(
+    root: &Path,
+    files: Vec<String>,
+    config: &ArchitectureConfig,
+    manifest_facts: &[ManifestFact],
+    changed_paths: &[String],
+    config_hash: String,
+    file_list_hash: String,
+) -> Result<ArchitectureScanReport, NaomeError> {
+    let Some(cache) = cache::read(root) else {
+        return degraded_full_scan(
+            root,
+            files,
+            config,
+            manifest_facts,
+            config_hash,
+            file_list_hash,
+            "cache_miss",
+        );
+    };
+    match cache.is_compatible(&config_hash, &file_list_hash) {
+        CacheStatus::Miss(reason) => degraded_full_scan(
+            root,
+            files,
+            config,
+            manifest_facts,
+            config_hash,
+            file_list_hash,
+            reason,
+        ),
+        CacheStatus::Hit => incremental_scan(
+            root,
+            files,
+            config,
+            manifest_facts,
+            changed_paths,
+            config_hash,
+            file_list_hash,
+            cache,
+        ),
+    }
+}
+
+fn incremental_scan(
+    root: &Path,
+    files: Vec<String>,
+    config: &ArchitectureConfig,
+    manifest_facts: &[ManifestFact],
+    changed_paths: &[String],
+    config_hash: String,
+    file_list_hash: String,
+    cache: cache::ArchitectureCache,
+) -> Result<ArchitectureScanReport, NaomeError> {
+    let file_set = files.iter().cloned().collect();
+    let changed = cache::changed_set(changed_paths);
+    if import_resolver_context_changed(changed_paths) {
+        return degraded_full_scan(
+            root,
+            files,
+            config,
+            manifest_facts,
+            config_hash,
+            file_list_hash,
+            "resolver_context_changed",
+        );
+    }
+    if cached_clean_content_changed(root, &files, &changed, &cache) {
+        return degraded_full_scan(
+            root,
+            files,
+            config,
+            manifest_facts,
+            config_hash,
+            file_list_hash,
+            "content_changed",
+        );
+    }
+    let mut file_facts = BTreeMap::new();
+    let mut scanned = 0;
+
+    for path in &files {
+        if changed.contains(path) || !cache.files.contains_key(path) {
+            let fact = graph_builder::scan_file_fact(root, path, config, &file_set);
+            scanned += 1;
+            file_facts.insert(path.clone(), fact);
+        } else if let Some(cached) = cache.files.get(path) {
+            file_facts.insert(path.clone(), cached.fact.clone());
+        }
+    }
+
+    let mut graph =
+        graph_builder::build_graph_from_facts(&files, &file_facts, config, manifest_facts);
     graph.sort_stable();
+    let _ = cache::write(root, config_hash, file_list_hash, &file_facts);
     Ok(ArchitectureScanReport {
         schema: "naome.arch.scan.v1".to_string(),
-        files_scanned: file_facts.len(),
+        files_scanned: scanned,
         graph,
-        changed_only_requested: options.changed_only,
-        changed_only_degraded_to_full_scan: options.changed_only,
-        changed_paths,
-        config,
+        changed_only_requested: true,
+        changed_only_degraded_to_full_scan: false,
+        changed_only_mode: "incremental_cache".to_string(),
+        changed_only_degradation_reason: None,
+        changed_paths: Vec::new(),
+        config: config.clone(),
         file_facts,
+        manifest_facts: manifest_facts.to_vec(),
+    })
+}
+
+fn cached_clean_content_changed(
+    root: &Path,
+    files: &[String],
+    changed: &std::collections::BTreeSet<String>,
+    cache: &cache::ArchitectureCache,
+) -> bool {
+    files.iter().any(|path| {
+        !changed.contains(path)
+            && cache.files.get(path).is_some_and(|cached| {
+                cache::content_hash(root, path)
+                    .map(|current| current != cached.content_hash)
+                    .unwrap_or(true)
+            })
+    })
+}
+
+fn import_resolver_context_changed(changed_paths: &[String]) -> bool {
+    changed_paths.iter().any(|path| {
+        Path::new(path)
+            .file_name()
+            .and_then(|value| value.to_str())
+            .is_some_and(|name| matches!(name, "go.mod" | "tsconfig.json" | "jsconfig.json"))
+    })
+}
+
+fn degraded_full_scan(
+    root: &Path,
+    files: Vec<String>,
+    config: &ArchitectureConfig,
+    manifest_facts: &[ManifestFact],
+    config_hash: String,
+    file_list_hash: String,
+    reason: &'static str,
+) -> Result<ArchitectureScanReport, NaomeError> {
+    full_scan(
+        root,
+        files,
+        config,
         manifest_facts,
+        config_hash,
+        file_list_hash,
+        true,
+        Some(reason),
+        "degraded_full_scan",
+    )
+}
+
+fn full_scan(
+    root: &Path,
+    files: Vec<String>,
+    config: &ArchitectureConfig,
+    manifest_facts: &[ManifestFact],
+    config_hash: String,
+    file_list_hash: String,
+    changed_only_degraded_to_full_scan: bool,
+    changed_only_degradation_reason: Option<&str>,
+    changed_only_mode: &str,
+) -> Result<ArchitectureScanReport, NaomeError> {
+    let (mut graph, file_facts) =
+        graph_builder::build_path_graph(root, files, config, manifest_facts);
+    graph.sort_stable();
+    let files_scanned = file_facts.len();
+    let _ = cache::write(root, config_hash, file_list_hash, &file_facts);
+    Ok(ArchitectureScanReport {
+        schema: "naome.arch.scan.v1".to_string(),
+        files_scanned,
+        graph,
+        changed_only_requested: changed_only_degraded_to_full_scan,
+        changed_only_degraded_to_full_scan,
+        changed_only_mode: changed_only_mode.to_string(),
+        changed_only_degradation_reason: changed_only_degradation_reason.map(str::to_string),
+        changed_paths: Vec::new(),
+        config: config.clone(),
+        file_facts,
+        manifest_facts: manifest_facts.to_vec(),
     })
 }
 
+impl ArchitectureScanReport {
+    fn with_changed_paths(mut self, changed_paths: Vec<String>) -> Self {
+        self.changed_paths = changed_paths;
+        self
+    }
+}
+
 fn changed_paths(root: &Path, changed_only: bool) -> Result<Vec<String>, NaomeError> {
     if changed_only {
         git::changed_paths(root)

package/crates/naome-core/tests/architecture_cache.rs

@@ -0,0 +1,212 @@
+use naome_core::{validate_architecture, ArchitectureScanOptions};
+use std::path::Path;
+use std::process::Command;
+
+mod architecture_support;
+
+use architecture_support::FixtureRepo;
+
+#[test]
+fn changed_only_uses_incremental_cache_after_initial_safe_full_scan() {
+    let repo = FixtureRepo::new();
+    repo.write(
+        "naome.arch.yaml",
+        forbidden_domain_to_infrastructure_config(),
+    );
+    repo.write("src/domain/event.ts", "export const event = 1;\n");
+    repo.write("src/infrastructure/db.ts", "export const db = 1;\n");
+    repo.init_git();
+
+    let initial = validate_architecture(repo.path(), changed_only()).unwrap();
+
+    assert!(initial.changed_only_requested);
+    assert!(initial.changed_only_degraded_to_full_scan);
+    assert_eq!(initial.changed_only_mode, "degraded_full_scan");
+    assert_eq!(
+        initial.changed_only_degradation_reason.as_deref(),
+        Some("cache_miss")
+    );
+
+    repo.write(
+        "src/domain/event.ts",
+        "import { db } from '../infrastructure/db';\nexport const event = db;\n",
+    );
+
+    let incremental = validate_architecture(repo.path(), changed_only()).unwrap();
+
+    assert!(incremental.changed_only_requested);
+    assert!(!incremental.changed_only_degraded_to_full_scan);
+    assert_eq!(incremental.changed_only_mode, "incremental_cache");
+    assert_eq!(incremental.changed_only_degradation_reason, None);
+    assert_eq!(incremental.files_scanned, 1);
+    assert_eq!(incremental.summary.errors, 1);
+    assert_eq!(
+        incremental.violations[0].path.as_deref(),
+        Some("src/domain/event.ts")
+    );
+}
+
+#[test]
+fn changed_only_degrades_when_architecture_config_changes() {
+    let repo = FixtureRepo::new();
+    repo.write(
+        "naome.arch.yaml",
+        forbidden_domain_to_infrastructure_config(),
+    );
+    repo.write("src/domain/event.ts", "export const event = 1;\n");
+    repo.write("src/infrastructure/db.ts", "export const db = 1;\n");
+    repo.init_git();
+    validate_architecture(repo.path(), changed_only()).unwrap();
+
+    repo.write(
+        "naome.arch.yaml",
+        "layers:\n  application:\n    paths:\n      - \"src/**\"\n",
+    );
+
+    let report = validate_architecture(repo.path(), changed_only()).unwrap();
+
+    assert!(report.changed_only_degraded_to_full_scan);
+    assert_eq!(report.changed_only_mode, "degraded_full_scan");
+    assert_eq!(
+        report.changed_only_degradation_reason.as_deref(),
+        Some("config_changed")
+    );
+}
+
+#[test]
+fn changed_only_degrades_when_repository_file_set_changes() {
+    let repo = FixtureRepo::new();
+    repo.write(
+        "naome.arch.yaml",
+        forbidden_domain_to_infrastructure_config(),
+    );
+    repo.write("src/domain/event.ts", "export const event = 1;\n");
+    repo.write("src/infrastructure/db.ts", "export const db = 1;\n");
+    repo.init_git();
+    validate_architecture(repo.path(), changed_only()).unwrap();
+
+    repo.write("src/domain/new.ts", "export const fresh = 1;\n");
+
+    let report = validate_architecture(repo.path(), changed_only()).unwrap();
+
+    assert!(report.changed_only_degraded_to_full_scan);
+    assert_eq!(report.changed_only_mode, "degraded_full_scan");
+    assert_eq!(
+        report.changed_only_degradation_reason.as_deref(),
+        Some("file_set_changed")
+    );
+}
+
+#[test]
+fn changed_only_degrades_when_cached_clean_file_content_changed() {
+    let repo = FixtureRepo::new();
+    repo.write(
+        "naome.arch.yaml",
+        forbidden_domain_to_infrastructure_config(),
+    );
+    repo.write("src/domain/event.ts", "export const event = 1;\n");
+    repo.write("src/infrastructure/db.ts", "export const db = 1;\n");
+    repo.init_git();
+    validate_architecture(repo.path(), changed_only()).unwrap();
+
+    repo.write(
+        "src/domain/event.ts",
+        "import { db } from '../infrastructure/db';\nexport const event = db;\n",
+    );
+    commit_all(repo.path(), "content change after cache");
+
+    let report = validate_architecture(repo.path(), changed_only()).unwrap();
+
+    assert!(report.changed_only_requested);
+    assert!(report.changed_only_degraded_to_full_scan);
+    assert_eq!(report.changed_only_mode, "degraded_full_scan");
+    assert_eq!(
+        report.changed_only_degradation_reason.as_deref(),
+        Some("content_changed")
+    );
+    assert_eq!(report.summary.errors, 1);
+}
+
+#[test]
+fn changed_only_degrades_when_go_module_context_changes() {
+    let repo = FixtureRepo::new();
+    repo.write(
+        "naome.arch.yaml",
+        forbidden_domain_to_infrastructure_config(),
+    );
+    repo.write("go.mod", "module example.com/old\n\ngo 1.22\n");
+    repo.write(
+        "src/domain/event.go",
+        "package domain\n\nimport \"example.com/new/src/infrastructure/db\"\n\nvar Event = db.Value\n",
+    );
+    repo.write(
+        "src/infrastructure/db/db.go",
+        "package db\n\nvar Value = 1\n",
+    );
+    repo.init_git();
+    let initial = validate_architecture(repo.path(), changed_only()).unwrap();
+    assert_eq!(initial.summary.errors, 0);
+
+    repo.write("go.mod", "module example.com/new\n\ngo 1.22\n");
+
+    let report = validate_architecture(repo.path(), changed_only()).unwrap();
+
+    assert!(report.changed_only_requested);
+    assert!(report.changed_only_degraded_to_full_scan);
+    assert_eq!(report.changed_only_mode, "degraded_full_scan");
+    assert_eq!(
+        report.changed_only_degradation_reason.as_deref(),
+        Some("resolver_context_changed")
+    );
+    assert_eq!(report.summary.errors, 1);
+    assert_eq!(
+        report.violations[0].path.as_deref(),
+        Some("src/domain/event.go")
+    );
+}
+
+fn changed_only() -> ArchitectureScanOptions {
+    ArchitectureScanOptions {
+        changed_only: true,
+        ..ArchitectureScanOptions::default()
+    }
+}
+
+fn forbidden_domain_to_infrastructure_config() -> &'static str {
+    r#"layers:
+  domain:
+    paths:
+      - "src/domain/**"
+  infrastructure:
+    paths:
+      - "src/infrastructure/**"
+allowed_dependencies:
+  domain:
+  infrastructure:
+    - domain
+rules:
+  no_forbidden_layer_dependencies:
+    enabled: true
+    severity: error
+"#
+}
+
+fn commit_all(root: &Path, message: &str) {
+    run_git(root, &["add", "."]);
+    run_git(root, &["commit", "-m", message]);
+}
+
+fn run_git(root: &Path, args: &[&str]) {
+    let output = Command::new("git")
+        .args(args)
+        .current_dir(root)
+        .output()
+        .unwrap();
+    assert!(
+        output.status.success(),
+        "git {:?} failed: {}{}",
+        args,
+        String::from_utf8_lossy(&output.stdout),
+        String::from_utf8_lossy(&output.stderr)
+    );
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lamentis/naome",
-  "version": "1.3.13",
+  "version": "1.3.14",
   "description": "Native-first CLI for the NAOME agent harness.",
   "license": "Apache-2.0",
   "type": "module",

package/templates/naome-root/.naome/manifest.json

@@ -9,7 +9,7 @@
     ".naome/task-contract.schema.json": "sha256:1b3b62350328d0d6d660e36d1d1baaa2b88718530db774f9ab2a9e2fcba369c8",
     "AGENTS.md": "sha256:e8b2fc786c1c72b69ba8f2b2ffce4f459e799c7453ce9ff4a9f6448a8f9e6b4f",
     "docs/naome/agent-workflow.md": "sha256:0be1c29adfbcd3fd73c4f904080ffc67237692fe413871a30243538c4db38ac7",
-    "docs/naome/architecture-fitness.md": "sha256:26f04884c3ada083380bee5c3cb1aa3f39d8c8a1cc31ccc84c4ae795c594de5b",
+    "docs/naome/architecture-fitness.md": "sha256:88aa979f61f82c2802c416af2c374ba041c94157189d59048d6889b07034d394",
     "docs/naome/context-economy.md": "sha256:3ed5075815ecf4ada46a5e65438769310307c35759fcd46b13dc0b96e02bebd9",
     "docs/naome/execution.md": "sha256:bfc5d55838942ec8e3d790b59e3c634ff5bf6a2298265cef3dca9788a097eafb",
     "docs/naome/first-run.md": "sha256:1466ce8c65e19a1514885f917db14e8a772350e3f6d1c03a66326963365919e1",

package/templates/naome-root/docs/naome/architecture-fitness.md

@@ -14,8 +14,9 @@ facts instead of prompt text.
 - `naome arch validate` runs architecture rules with human output.
 - `naome arch validate --json` emits stable machine-readable output.
 - `naome arch validate --agent-feedback` emits compact repair instructions.
-- `naome arch validate --changed-only` uses changed paths when available and
-  safely degrades to a full scan for graph-level soundness.
+- `naome arch validate --changed-only` uses changed paths with the persistent
+  architecture cache when available and safely degrades to a full scan when the
+  cache cannot prove graph-level soundness.
 
 ## Graph Model
 
@@ -127,17 +128,37 @@ ignore:
 Agents should run `naome arch validate --changed-only --json` after changing
 source or template files. JSON output includes status, severity counts,
 violations, concrete suggestions, and `agentFeedback` entries optimized for
-repair loops.
+repair loops. It also reports `changedOnlyMode` and
+`changedOnlyDegradationReason`, so agents can distinguish an incremental cache
+run from a deliberate full-scan fallback.
+
+## Incremental Cache
+
+NAOME stores architecture file facts in `.naome/cache/architecture/cache.json`.
+Cache entries are keyed by file path and content hash, and the cache is tied to
+the effective architecture config hash plus the repository file-list hash.
+
+Changed-only validation is sound by construction:
+
+- the first run without a compatible cache performs a full scan and records
+  `changedOnlyMode: "degraded_full_scan"` with reason `cache_miss`;
+- config changes perform a full scan with reason `config_changed`;
+- added or deleted repository files perform a full scan with reason
+  `file_set_changed`;
+- when config and file set are unchanged, NAOME reuses cached facts for
+  untouched files, rescans changed files, rebuilds the full graph, and runs all
+  graph-level rules against that graph.
 
 ## CI Integration
 
 Use `node .naome/bin/naome.js arch validate --changed-only` as a fast gate.
-The first foundation release reports warnings for existing file-size debt and
-fails only on configured error rules.
+The command is deterministic in both cache-backed and fallback modes; CI can
+inspect the JSON fields above when it needs to distinguish performance from
+soundness fallbacks.
 
 ## Language Support
 
-The v1.3.13 foundation classifies TypeScript, JavaScript, Rust, Python, Go,
+The v1.3.14 foundation classifies TypeScript, JavaScript, Rust, Python, Go,
 Java, Kotlin, and Swift files by path extension. It extracts import facts for
 TypeScript, JavaScript, Rust, Python, Go, and Swift, resolves relative imports
 and simple repository-absolute aliases where the language supports them, and
@@ -158,5 +179,5 @@ policies.
 
 This release intentionally keeps validation file-graph based. Manifest
 extractors are dependency-owner oriented and do not yet parse every build-tool
-feature. SARIF output, persistent scan caching, and deeper symbol-level call
-analysis remain planned follow-up slices before v1.4.0.
+feature. SARIF output and deeper symbol-level call analysis remain planned
+follow-up slices before v1.4.0.