fix(OMN-13521): exclude nested worktrees from doc-freshness md collection

src/omnimarket/nodes/node_doc_freshness_sweep/handlers/handler_doc_freshness_sweep.py

@@ -70,7 +70,8 @@
     "onex_change_control",
 ]
 
-# Directories to exclude from scanning
+# Substrings excluded from scanning (matched against the doc's repo-relative
+# path). "docs/history" is intentionally a multi-segment substring match.
 _EXCLUDE_DIRS = frozenset(
     {
         "docs/history",
@@ -81,6 +82,26 @@
     }
 )
 
+# Path *segments* whose presence anywhere in the repo-relative path means the
+# doc lives inside a nested git worktree or a generated/dependency tree and is a
+# duplicate of the canonical source. Matched per-segment (not substring) so a
+# legitimately named file like ``docs/using_worktrees.md`` is NOT excluded —
+# only an actual ``worktrees`` directory segment is (OMN-13521).
+_EXCLUDE_PATH_SEGMENTS = frozenset(
+    {
+        ".claude",
+        "worktrees",
+        "omni_worktrees",
+        ".venv",
+        "node_modules",
+        "__pycache__",
+        ".git",
+        ".mypy_cache",
+        ".pytest_cache",
+        ".ruff_cache",
+    }
+)
+
 
 # ---------------------------------------------------------------------------
 # Models
@@ -136,10 +157,15 @@ def _collect_md_files(repo_root: Path, claude_md_only: bool) -> list[Path]:
 
     results: list[Path] = []
     for p in matches:
-        rel = str(p.relative_to(repo_root))
-        excluded = any(excl in rel for excl in _EXCLUDE_DIRS)
-        if not excluded:
-            results.append(p)
+        rel_path = p.relative_to(repo_root)
+        rel = str(rel_path)
+        # Substring exclusions (e.g. multi-segment "docs/history").
+        if any(excl in rel for excl in _EXCLUDE_DIRS):
+            continue
+        # Per-segment exclusions: skip nested worktrees / generated trees.
+        if any(seg in _EXCLUDE_PATH_SEGMENTS for seg in rel_path.parts):
+            continue
+        results.append(p)
     return results
 
 

tests/test_doc_freshness_worktree_exclusion.py

@@ -0,0 +1,84 @@
+"""Worktree-exclusion tests for node_doc_freshness_sweep (OMN-13521).
+
+The freshness sweep walks the canonical repo clones, which contain nested git
+worktrees under ``.claude/worktrees/`` and ``omni_worktrees/``. Those are
+duplicate copies of the same source tree; scanning them inflated the md-file
+count by ~50% (omniclaude) to ~90% (omnimarket) and multiplied the resolver
+cost. ``_collect_md_files`` must skip nested-worktree directories.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import pytest
+
+from omnimarket.nodes.node_doc_freshness_sweep.handlers.handler_doc_freshness_sweep import (
+    _collect_md_files,
+)
+
+
+@pytest.mark.unit
+class TestCollectMdFilesExcludesNestedWorktrees:
+    """`_collect_md_files` must not return docs from nested worktree copies."""
+
+    def test_excludes_claude_worktrees(self, tmp_path: Path) -> None:
+        repo = tmp_path / "repo"
+        canonical = repo / "docs" / "guide.md"
+        canonical.parent.mkdir(parents=True)
+        canonical.write_text("# guide\n", encoding="utf-8")
+
+        nested = repo / ".claude" / "worktrees" / "OMN-1" / "docs" / "guide.md"
+        nested.parent.mkdir(parents=True)
+        nested.write_text("# dup\n", encoding="utf-8")
+
+        out = _collect_md_files(repo, claude_md_only=False)
+        rels = {str(p.relative_to(repo)) for p in out}
+        assert "docs/guide.md" in rels
+        assert all(".claude/worktrees" not in r for r in rels)
+
+    def test_excludes_omni_worktrees(self, tmp_path: Path) -> None:
+        repo = tmp_path / "repo"
+        canonical = repo / "README.md"
+        canonical.parent.mkdir(parents=True, exist_ok=True)
+        canonical.write_text("# readme\n", encoding="utf-8")
+
+        nested = repo / "omni_worktrees" / "OMN-2" / "repo" / "README.md"
+        nested.parent.mkdir(parents=True)
+        nested.write_text("# dup\n", encoding="utf-8")
+
+        out = _collect_md_files(repo, claude_md_only=False)
+        rels = {str(p.relative_to(repo)) for p in out}
+        assert "README.md" in rels
+        assert all("omni_worktrees" not in r for r in rels)
+
+    def test_excludes_nested_claude_md_in_worktrees(self, tmp_path: Path) -> None:
+        """claude_md_only mode must also skip worktree copies of CLAUDE.md."""
+        repo = tmp_path / "repo"
+        canonical = repo / "CLAUDE.md"
+        canonical.parent.mkdir(parents=True, exist_ok=True)
+        canonical.write_text("# canonical\n", encoding="utf-8")
+
+        nested = repo / ".claude" / "worktrees" / "OMN-3" / "CLAUDE.md"
+        nested.parent.mkdir(parents=True)
+        nested.write_text("# dup\n", encoding="utf-8")
+
+        out = _collect_md_files(repo, claude_md_only=True)
+        rels = {str(p.relative_to(repo)) for p in out}
+        assert rels == {"CLAUDE.md"}
+
+    def test_top_level_doc_named_worktrees_kept(self, tmp_path: Path) -> None:
+        """A real doc whose name merely contains 'worktrees' is NOT excluded.
+
+        Exclusion is path-segment scoped, so ``docs/using_worktrees.md`` (a
+        legitimate doc) survives — only an actual ``worktrees`` directory
+        segment is pruned.
+        """
+        repo = tmp_path / "repo"
+        doc = repo / "docs" / "using_worktrees.md"
+        doc.parent.mkdir(parents=True)
+        doc.write_text("# worktrees guide\n", encoding="utf-8")
+
+        out = _collect_md_files(repo, claude_md_only=False)
+        rels = {str(p.relative_to(repo)) for p in out}
+        assert "docs/using_worktrees.md" in rels