[gobby-cli-#1007] feat: per-category render versions for codewiki

Replace the single global CODEWIKI_RENDER_VERSION with per-category
constants (file, module, repo, architecture, infrastructure, features,
deprecations, misc, curated, changes) so a template change in one
renderer only invalidates that category's pages instead of forcing a
full wiki regeneration. All categories start at 20 for backward compat
with existing _meta/codewiki.json.

Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>

Author: joshwilhelmi

crates/gcode/src/commands/codewiki/io.rs

@@ -195,7 +195,7 @@ impl<'a> DocSink<'a> {
             && meta.ai_route == ai_outcome.route_label()
             && meta.ai_fallback == ai_outcome.fallback
             && meta.ai_generation_status == ai_outcome.status.as_str()
-            && meta.render_version == CODEWIKI_RENDER_VERSION
+            && meta.render_version == render_version_for_path(&doc.path)
             && !meta.source_hashes.is_empty()
             && (doc.summary.is_none() || meta.summary.is_some())
             && meta
@@ -236,7 +236,7 @@ impl<'a> DocSink<'a> {
                     && meta.ai_route == ai_outcome.route_label()
                     && meta.ai_fallback == ai_outcome.fallback
                     && meta.ai_generation_status == ai_outcome.status.as_str()
-                    && meta.render_version == CODEWIKI_RENDER_VERSION
+                    && meta.render_version == render_version_for_path(&doc.path)
                     && match &doc.invalidation_key {
                         Some(key) => {
                             meta.invalidation_key.as_deref() == Some(key.as_str())
@@ -267,7 +267,7 @@ impl<'a> DocSink<'a> {
                     && meta.ai_route == ai_outcome.route_label()
                     && meta.ai_fallback == ai_outcome.fallback
                     && meta.ai_generation_status == ai_outcome.status.as_str()
-                    && meta.render_version == CODEWIKI_RENDER_VERSION
+                    && meta.render_version == render_version_for_path(&doc.path)
                     && source_hash_key_sets_match(&meta.source_hashes, &source_hashes)
                     && source_hash_key_sets_match(&meta.neighbor_hashes, &neighbor_hashes)
                     && (doc.summary.is_none() || meta.summary.is_some())
@@ -310,7 +310,7 @@ impl<'a> DocSink<'a> {
                 ai_route: write_outcome.route_label().to_string(),
                 ai_fallback: write_outcome.fallback,
                 ai_generation_status: write_outcome.status.as_str().to_string(),
-                render_version: CODEWIKI_RENDER_VERSION,
+                render_version: render_version_for_path(&doc.path),
                 neighbor_hashes,
                 invalidation_key: doc.invalidation_key.clone(),
                 lane: lane.lane,

crates/gcode/src/commands/codewiki/mod.rs

@@ -61,7 +61,55 @@ const MAX_EDGE_LIMIT: usize = 100_000;
 // Workflows/Getting Started/Operations/Data Model/CLI-API/Troubleshooting),
 // semantic cross-directory concept-cluster names, and an enumerable `Reference |
 // Summary` table on curated pages, so prior narrative/concept pages re-render.
-const CODEWIKI_RENDER_VERSION: u32 = 20;
+//
+// Per-category render versions (#1007): the single global version was replaced
+// by per-category constants so a template change in one renderer only
+// invalidates the pages it affects. All categories start at 20 (the prior
+// global value) for backward compatibility with existing _meta/codewiki.json.
+const RENDER_VERSION_DEFAULT: u32 = 20;
+const RENDER_VERSION_FILE: u32 = 20;
+const RENDER_VERSION_MODULE: u32 = 20;
+const RENDER_VERSION_REPO: u32 = 20;
+const RENDER_VERSION_ARCHITECTURE: u32 = 20;
+const RENDER_VERSION_INFRASTRUCTURE: u32 = 20;
+const RENDER_VERSION_FEATURES: u32 = 20;
+const RENDER_VERSION_DEPRECATIONS: u32 = 20;
+const RENDER_VERSION_MISC: u32 = 20;
+const RENDER_VERSION_CURATED: u32 = 20;
+const RENDER_VERSION_CHANGES: u32 = 20;
+
+/// Returns the render-version constant for a doc page path. Each page category
+/// (file docs, module docs, architecture, curated narrative, etc.) has its own
+/// version so a template change in one renderer only invalidates the pages it
+/// affects, instead of forcing a full wiki regeneration.
+pub(crate) fn render_version_for_path(path: &str) -> u32 {
+    if path.starts_with("code/files/") {
+        RENDER_VERSION_FILE
+    } else if path.starts_with("code/modules/") {
+        RENDER_VERSION_MODULE
+    } else if path.starts_with("code/concepts/") || path.starts_with("code/narrative/") {
+        RENDER_VERSION_CURATED
+    } else if path == "code/repo.md" {
+        RENDER_VERSION_REPO
+    } else if path == "code/_architecture.md" {
+        RENDER_VERSION_ARCHITECTURE
+    } else if path == "code/infrastructure.md" {
+        RENDER_VERSION_INFRASTRUCTURE
+    } else if path == "code/features.md" {
+        RENDER_VERSION_FEATURES
+    } else if path == "code/deprecations.md" {
+        RENDER_VERSION_DEPRECATIONS
+    } else if path == "code/_changes.md" {
+        RENDER_VERSION_CHANGES
+    } else if path == "code/_onboarding.md"
+        || path == "code/_hotspots.md"
+        || path == "code/_ownership.md"
+    {
+        RENDER_VERSION_MISC
+    } else {
+        RENDER_VERSION_DEFAULT
+    }
+}
 
 /// Default daemon feature profile for the grounded verification pass (#904):
 /// `feature_mid` (sonnet) runs the "is this claim supported by the cited

crates/gcode/src/commands/codewiki/reuse.rs

@@ -2,7 +2,7 @@ use std::collections::{BTreeMap, BTreeSet};
 use std::path::{Path, PathBuf};
 
 use super::io::{read_codewiki_meta, safe_doc_path};
-use super::{BuiltDoc, CODEWIKI_RENDER_VERSION, CodewikiAiOutcome, CodewikiDocMeta, SourceSpan};
+use super::{BuiltDoc, CodewikiAiOutcome, CodewikiDocMeta, SourceSpan, render_version_for_path};
 use crate::index::hasher;
 
 /// Decides whether a doc's previous content can be reused without any LLM
@@ -124,7 +124,7 @@ impl ReusePlan {
         if entry.degraded
             || entry.ai_mode != self.ai_mode
             || !entry_matches_ai_outcome(entry, ai_outcome)
-            || entry.render_version != CODEWIKI_RENDER_VERSION
+            || entry.render_version != render_version_for_path(doc_path)
             || entry.invalidation_key.as_deref() != Some(invalidation_key)
         {
             return None;
@@ -235,7 +235,7 @@ impl ReusePlan {
         if entry.degraded
             || entry.ai_mode != self.ai_mode
             || !entry_matches_ai_outcome(entry, ai_outcome)
-            || entry.render_version != CODEWIKI_RENDER_VERSION
+            || entry.render_version != render_version_for_path(doc_path)
             || entry.source_hashes.is_empty()
         {
             return false;

crates/gcode/src/commands/codewiki/tests/reuse.rs

@@ -192,6 +192,117 @@ fn stale_render_version_disables_reuse() {
     );
 }
 
+#[test]
+fn per_category_render_version_isolates_invalidation() {
+    let (project, input) = reuse_project();
+    let out_dir = project.path().join("codewiki");
+
+    let mut first_generator = |_prompt: &str, system: &str, _tier: PromptTier| {
+        if system == prompts::CURATED_NAVIGATION_SYSTEM {
+            Some(test_curated_navigation_json())
+        } else if system == prompts::CONCEPT_PAGE_SYSTEM {
+            Some(test_concept_handbook_body())
+        } else if system == prompts::NARRATIVE_PAGE_SYSTEM {
+            Some(test_narrative_handbook_body())
+        } else {
+            Some("Generated prose.".to_string())
+        }
+    };
+    let mut progress = CodewikiProgress::silent();
+    let first = generate_hierarchical_docs_with_progress(
+        &input,
+        Some(&mut first_generator),
+        AiDepth::Symbols,
+        &mut progress,
+    );
+    write_incremental_doc_set_with_snapshot(
+        project.path(),
+        &out_dir,
+        &first,
+        None,
+        "symbols",
+        DocPruneScope::unscoped(),
+    )
+    .expect("first write");
+
+    // Stale only the architecture page's render version. Every other category
+    // keeps version 20 and must reuse; only code/_architecture.md regenerates.
+    let meta_path = out_dir.join("_meta/codewiki.json");
+    let raw_meta = std::fs::read_to_string(&meta_path).expect("read meta");
+    let mut meta: serde_json::Value = serde_json::from_str(&raw_meta).expect("parse meta");
+    if let Some(arch) = meta["docs"]
+        .as_object_mut()
+        .expect("docs object")
+        .get_mut("code/_architecture.md")
+    {
+        arch["render_version"] = serde_json::json!(1);
+    }
+    std::fs::write(
+        &meta_path,
+        format!(
+            "{}\n",
+            serde_json::to_string_pretty(&meta).expect("serialize meta")
+        ),
+    )
+    .expect("write stale meta");
+
+    let mut regenerated_paths = Vec::new();
+    let mut second_generator = |_prompt: &str, system: &str, _tier: PromptTier| {
+        if system == prompts::CURATED_NAVIGATION_SYSTEM {
+            Some(test_curated_navigation_json())
+        } else if system == prompts::CONCEPT_PAGE_SYSTEM {
+            Some(test_concept_handbook_body())
+        } else if system == prompts::NARRATIVE_PAGE_SYSTEM {
+            Some(test_narrative_handbook_body())
+        } else {
+            Some("Regenerated prose.".to_string())
+        }
+    };
+    let mut plan = ReusePlan::load(project.path(), &out_dir, "symbols").expect("reuse plan loads");
+    let mut reuse = Some(&mut plan);
+    let mut progress = CodewikiProgress::silent();
+    let second = generate_hierarchical_docs_with_reuse(
+        &input,
+        Some(&mut second_generator),
+        AiDepth::Symbols,
+        &mut reuse,
+        &mut progress,
+    );
+
+    // Collect paths whose content changed (regenerated, not reused).
+    for doc in &second {
+        let prev = first.iter().find(|d| d.path == doc.path);
+        if prev.is_none_or(|p| p.content != doc.content) {
+            regenerated_paths.push(doc.path.as_str());
+        }
+    }
+
+    // Architecture must regenerate.
+    assert!(
+        regenerated_paths.contains(&"code/_architecture.md"),
+        "architecture page must regenerate when its render version is stale, got: {regenerated_paths:?}"
+    );
+
+    // File docs and module docs must NOT regenerate — their render versions are
+    // still valid.
+    let file_or_module_regen = regenerated_paths
+        .iter()
+        .any(|p| p.starts_with("code/files/") || p.starts_with("code/modules/"));
+    assert!(
+        !file_or_module_regen,
+        "file/module pages must reuse when only architecture render version is stale, regenerated: {regenerated_paths:?}"
+    );
+
+    // Curated pages must NOT regenerate.
+    let curated_regen = regenerated_paths
+        .iter()
+        .any(|p| p.starts_with("code/concepts/") || p.starts_with("code/narrative/"));
+    assert!(
+        !curated_regen,
+        "curated pages must reuse when only architecture render version is stale, regenerated: {regenerated_paths:?}"
+    );
+}
+
 #[test]
 fn reused_docs_feed_recorded_summaries_into_parent_prompts() {
     let (project, input) = reuse_project();

crates/gcode/src/commands/codewiki/types.rs

@@ -580,7 +580,10 @@ pub(crate) struct CodewikiDocMeta {
     #[serde(default, skip_serializing_if = "String::is_empty")]
     pub(crate) ai_generation_status: String,
     /// Render-template version for deterministic markdown emitted after model
-    /// generation. Missing versions force a one-time rewrite on upgrade.
+    /// generation. Per-category: each page type (file, module, architecture,
+    /// curated, etc.) has its own version constant so a template change in one
+    /// renderer only invalidates that category's pages (#1007). Missing or
+    /// stale versions force a rewrite of the affected category only.
     #[serde(default)]
     pub(crate) render_version: u32,
     /// Cross-file neighbor source hashes (#885, Leaf H). A source-file page