Fix resume skipping missing module docs when overview.md exists

run_module_agent (caw and pydantic-ai backends) and
generate_parent_module_docs returned early whenever overview.md was
present. overview.md only proves the ROOT module is done, so on a
resume after a partial run every nested module and parent without its
own doc file was silently skipped. Gate the overview.md check on the
root module (empty module_path) and let each module be checked against
its own doc file.

Also mechanical ruff cleanup on the touched files (Dict/List -> dict/
list, import sorting, format) so the changed-files lint job passes.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: anhnh2002

codewiki/src/be/caw_backend.py

@@ -23,7 +23,7 @@
 import logging
 import os
 import shutil
-from typing import Any, Dict, List
+from typing import Any
 
 from caw import Agent as CawAgent
 from caw import ToolGroup
@@ -170,7 +170,7 @@ def _with_allowed_tools(cmd):
         allowed = ",".join(f"mcp__{s}" for s in servers)
         logger.info("Injected --allowedTools for MCP servers: %s", servers)
         return list(cmd) + ["--allowedTools", allowed]
-    except Exception as e:  # never break the spawn on a patch hiccup
+    except Exception as e:  # noqa: BLE001 — never break the spawn on a patch hiccup
         logger.warning("claude allowedTools patch skipped: %s", e)
         return cmd
 
@@ -266,11 +266,11 @@ def complete(
     async def run_module_agent(
         self,
         module_name: str,
-        components: Dict[str, Node],
-        core_component_ids: List[str],
-        module_path: List[str],
+        components: dict[str, Node],
+        core_component_ids: list[str],
+        module_path: list[str],
         working_dir: str,
-    ) -> Dict[str, Any]:
+    ) -> dict[str, Any]:
         # caw.completion shells out to a subprocess and blocks the calling
         # thread.  Push it off the event loop so the rest of the async
         # pipeline keeps moving.
@@ -293,13 +293,13 @@ async def run_module_agent(
     def _run_module_agent_sync(
         self,
         module_name: str,
-        components: Dict[str, Node],
-        core_component_ids: List[str],
-        module_path: List[str],
+        components: dict[str, Node],
+        core_component_ids: list[str],
+        module_path: list[str],
         working_dir: str,
         start_depth: int = 1,
-        module_tree: Dict[str, Any] | None = None,
-    ) -> Dict[str, Any]:
+        module_tree: dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
         # ``start_depth`` lets the recursion preserve max_depth across nested
         # _run_module_agent_sync calls — each fresh deps object would otherwise
         # reset current_depth to 1 and silently bypass max_depth guards.
@@ -314,10 +314,15 @@ def _run_module_agent_sync(
         if module_tree is None:
             module_tree = file_manager.load_json(module_tree_path)
 
-        overview_docs_path = os.path.join(working_dir, OVERVIEW_FILENAME)
-        if os.path.exists(overview_docs_path):
-            logger.info("✓ Overview docs already exists at %s", overview_docs_path)
-            return module_tree
+        # overview.md is the root module's own doc (renamed from
+        # {repo_name}.md), so its presence only proves the root is done —
+        # nested modules must still be checked against their own doc file,
+        # or a resume after a partial run silently skips every missing one.
+        if not module_path:
+            overview_docs_path = os.path.join(working_dir, OVERVIEW_FILENAME)
+            if os.path.exists(overview_docs_path):
+                logger.info("✓ Overview docs already exists at %s", overview_docs_path)
+                return module_tree
         docs_path = os.path.join(working_dir, f"{module_name}.md")
         if os.path.exists(docs_path):
             logger.info("✓ Module docs already exists at %s", docs_path)
@@ -333,16 +338,16 @@ def _run_module_agent_sync(
         # agent call per sub-spec even when a single leaf write would suffice.
         # See generate_sub_module_documentation_tool for the pydantic-ai
         # equivalent.
-        _, components_with_code = format_potential_core_components(
-            core_component_ids, components
-        )
+        _, components_with_code = format_potential_core_components(core_component_ids, components)
         num_tokens = count_tokens(components_with_code)
         can_delegate = (
             is_complex_module(components, core_component_ids)
             and start_depth < config.max_depth
             and num_tokens >= config.max_token_per_leaf_module
         )
-        logger.info(f"Module {module_name} can delegate: {can_delegate} - is_complex_module: {is_complex_module(components, core_component_ids)} - start_depth: {start_depth} - num_tokens: {num_tokens} - max_depth: {config.max_depth} - max_token_per_leaf_module: {config.max_token_per_leaf_module}")
+        logger.info(
+            f"Module {module_name} can delegate: {can_delegate} - is_complex_module: {is_complex_module(components, core_component_ids)} - start_depth: {start_depth} - num_tokens: {num_tokens} - max_depth: {config.max_depth} - max_token_per_leaf_module: {config.max_token_per_leaf_module}"
+        )
 
         if can_delegate:
             system_prompt = format_system_prompt(module_name, custom_instructions)

codewiki/src/be/documentation_generator.py

@@ -297,13 +297,10 @@ async def generate_parent_module_docs(
         module_tree_path = os.path.join(working_dir, MODULE_TREE_FILENAME)
         module_tree = file_manager.load_json(module_tree_path)
 
-        # check if overview docs already exists
-        overview_docs_path = os.path.join(working_dir, OVERVIEW_FILENAME)
-        if os.path.exists(overview_docs_path):
-            logger.info(f"✓ Overview docs already exists at {overview_docs_path}")
-            return module_tree
-
-        # check if parent docs already exists
+        # check if parent docs already exists (for the root module the doc
+        # path below resolves to overview.md, so a blanket "overview exists →
+        # skip" check is not needed here and would mask missing parent docs
+        # on resume)
         parent_docs_path = os.path.join(
             working_dir,
             f"{module_name if len(module_path) >= 1 else OVERVIEW_FILENAME.replace('.md', '')}.md",

codewiki/src/be/pydantic_ai_backend.py

@@ -11,7 +11,7 @@
 import logging
 import os
 import traceback
-from typing import Any, Dict, List
+from typing import Any
 
 from pydantic_ai import Agent
 
@@ -55,19 +55,24 @@ def complete(
     async def run_module_agent(
         self,
         module_name: str,
-        components: Dict[str, Node],
-        core_component_ids: List[str],
-        module_path: List[str],
+        components: dict[str, Node],
+        core_component_ids: list[str],
+        module_path: list[str],
         working_dir: str,
-    ) -> Dict[str, Any]:
+    ) -> dict[str, Any]:
         config = self._config
         module_tree_path = os.path.join(working_dir, MODULE_TREE_FILENAME)
         module_tree = file_manager.load_json(module_tree_path)
 
-        overview_docs_path = os.path.join(working_dir, OVERVIEW_FILENAME)
-        if os.path.exists(overview_docs_path):
-            logger.info("✓ Overview docs already exists at %s", overview_docs_path)
-            return module_tree
+        # overview.md is the root module's own doc (renamed from
+        # {repo_name}.md), so its presence only proves the root is done —
+        # nested modules must still be checked against their own doc file,
+        # or a resume after a partial run silently skips every missing one.
+        if not module_path:
+            overview_docs_path = os.path.join(working_dir, OVERVIEW_FILENAME)
+            if os.path.exists(overview_docs_path):
+                logger.info("✓ Overview docs already exists at %s", overview_docs_path)
+                return module_tree
         docs_path = os.path.join(working_dir, f"{module_name}.md")
         if os.path.exists(docs_path):
             logger.info("✓ Module docs already exists at %s", docs_path)