Merge pull request #185 from BlueEventHorizon/fix/181-shared-numbering-duplicates

BlueEventHorizon · web-flow · commit faa62d42cde6 · 2026-07-07T14:57:03.000+09:00
[Fix] scan_spec_ids の duplicates を共有採番モードに追随させ同一履歴由来の誤報告を解消 (#181)
diff --git a/plugins/forge/skills/next-spec-id/SKILL.md b/plugins/forge/skills/next-spec-id/SKILL.md
@@ -65,6 +65,8 @@ python3 "$SCRIPT" ADR --share-prefixes ADR,DES
 
 #### 重複検出時
 
+`duplicates` に報告されるのは「**異なるファイルが同じ ID（共有採番モードでは同じ番号）を主張している**」衝突のみ。同一パスのファイルが複数ブランチに存在するだけの同一履歴由来ケースは報告されない（Issue #181）。共有採番モード（`--share-prefixes`）では、`ADR-032` と `DES-032` のような prefix 違い・同番号も衝突として報告される。
+
 ```json
 {
   "status": "ok",
@@ -77,16 +79,22 @@ python3 "$SCRIPT" ADR --share-prefixes ADR,DES
   "duplicates": [
     {
       "id": "SCR-013",
-      "branches": ["feature/edit_pickup", "origin/feature/print_letter"]
-    },
-    {
-      "id": "SCR-014",
-      "branches": ["feature/edit_pickup", "origin/feature/print_letter"]
+      "ids": ["SCR-013"],
+      "branches": ["feature/edit_pickup", "origin/feature/print_letter"],
+      "paths": [
+        "docs/specs/pickup/requirements/SCR-013_edit_pickup.md",
+        "docs/specs/letter/requirements/SCR-013_print_letter.md"
+      ]
     }
   ]
 }
 ```
 
+- `id`: 代表 ID（衝突に関与する ID の先頭）
+- `ids`: 衝突に関与する全 ID（共有採番モードでは `["ADR-032", "DES-032"]` のように複数になりうる）
+- `paths`: 同じ番号を主張している異なるファイルパス
+- `branches`: 該当ファイルが存在するブランチ
+
 #### エラー時
 
 ```json
@@ -143,5 +151,5 @@ ADR は設計書と同じディレクトリに配置するため、`.doc_structu
 4. ベースブランチから派生した全ブランチをスキャン（ローカル + リモート）
 5. `git ls-tree` で各ブランチの specs ディレクトリを走査
 6. 指定プレフィックスの最大番号を検出
-7. 重複があれば `duplicates` に記録
+7. 異なるファイルが同じ ID / 共有番号を主張する衝突があれば `duplicates` に記録（同一パス由来の複数ブランチ出現は正常として除外）
 8. 最大番号 + 1 を返す
diff --git a/plugins/forge/skills/next-spec-id/scripts/scan_spec_ids.py b/plugins/forge/skills/next-spec-id/scripts/scan_spec_ids.py
@@ -147,9 +147,11 @@ def scan_ids_in_branch(branch, prefix, scan_dirs, cwd=None):
     """1つのブランチから指定プレフィックスの ID を抽出する。
 
     Returns:
-        list[tuple[str, str]]: (id_string, branch_name) のリスト
+        list[tuple[str, str, str]]: (id_string, branch_name, file_path) のリスト
     """
-    pattern = re.compile(re.escape(prefix) + r'-(\d+)')
+    # `(?<![A-Za-z0-9-])`: prefix の直前に境界を設け、`COMMON-DES-001` のような
+    # 別名前空間の ID を `DES-001` として誤抽出しない（Issue #181 で検出）
+    pattern = re.compile(r'(?<![A-Za-z0-9-])' + re.escape(prefix) + r'-(\d+)')
     results = []
 
     unique_prefixes = sorted(set(
@@ -173,25 +175,50 @@ def scan_ids_in_branch(branch, prefix, scan_dirs, cwd=None):
             match = pattern.search(filepath)
             if match:
                 id_str = '{}-{}'.format(prefix, match.group(1))
-                results.append((id_str, branch))
+                results.append((id_str, branch, filepath))
 
     return results
 
 
-def find_duplicates(id_branch_pairs):
-    """異なるブランチで同じ ID が使用されているケースを検出する。"""
-    id_to_branches = {}
-    for id_str, branch in id_branch_pairs:
-        if id_str not in id_to_branches:
-            id_to_branches[id_str] = set()
-        id_to_branches[id_str].add(branch)
+def find_duplicates(id_entries, shared_numbering=False):
+    """異なる文書が同じ ID（共有採番モードでは同じ番号）を主張しているケースを検出する。
+
+    同一ファイルパスが複数ブランチに存在するのは同じコミット履歴に由来する
+    正常な状態であり、重複として扱わない（Issue #181）。重複と見なすのは、
+    同じ番号キーを **異なるファイルパス** が主張している場合のみ。
+
+    Args:
+        id_entries: (id_str, branch, file_path) のリスト
+        shared_numbering: True の場合、prefix を無視して番号のみをキーに衝突を見る
+            （--share-prefixes 指定時。`ADR-032` と `DES-032` は共有番号 032 の衝突として報告する）
+
+    Returns:
+        list[dict]: 各要素は {'id', 'ids', 'branches', 'paths'}。
+            'id' は代表 ID（後方互換）、'ids' は衝突に関与する全 ID。
+    """
+    id_num_pattern = re.compile(r'^(.+)-(\d+)$')
+    groups = {}
+    for id_str, branch, path in id_entries:
+        m = id_num_pattern.match(id_str)
+        if not m:
+            continue
+        prefix, num = m.group(1), int(m.group(2))
+        key = num if shared_numbering else (prefix, num)
+        group = groups.setdefault(key, {'ids': set(), 'branches': set(), 'paths': set()})
+        group['ids'].add(id_str)
+        group['branches'].add(branch)
+        group['paths'].add(path)
 
     duplicates = []
-    for id_str, branches in sorted(id_to_branches.items()):
-        if len(branches) > 1:
+    for key in sorted(groups):
+        group = groups[key]
+        if len(group['paths']) > 1:
+            ids = sorted(group['ids'])
             duplicates.append({
-                'id': id_str,
-                'branches': sorted(branches),
+                'id': ids[0],
+                'ids': ids,
+                'branches': sorted(group['branches']),
+                'paths': sorted(group['paths']),
             })
     return duplicates
 
@@ -232,7 +259,7 @@ def scan_spec_ids(prefix, project_root, doc_structure_path=None, cwd=None, share
     max_number = 0
     unique_ids = set()
 
-    for id_str, _ in all_pairs:
+    for id_str, _, _ in all_pairs:
         unique_ids.add(id_str)
         m = number_pattern.match(id_str)
         if m:
@@ -243,7 +270,7 @@ def scan_spec_ids(prefix, project_root, doc_structure_path=None, cwd=None, share
     next_number = max_number + 1
     next_id = '{}-{:03d}'.format(prefix, next_number)
 
-    duplicates = find_duplicates(all_pairs)
+    duplicates = find_duplicates(all_pairs, shared_numbering=bool(share_prefixes))
 
     result = {
         'status': 'ok',
diff --git a/plugins/forge/skills/start-design/SKILL.md b/plugins/forge/skills/start-design/SKILL.md
@@ -226,7 +226,7 @@ SCAN_SCRIPT="${CLAUDE_PLUGIN_ROOT}/skills/next-spec-id/scripts/scan_spec_ids.py"
 python3 "$SCAN_SCRIPT" DES --share-prefixes ADR,DES
 ```
 
-JSON 出力の `next_id` をファイル名・設計 ID として使用する。`duplicates` が空でない場合は警告を表示する。
+JSON 出力の `next_id` をファイル名・設計 ID として使用する。`duplicates` が空でない場合は警告を表示する（`duplicates` には「異なるファイルが同じ ID / 共有番号を主張している」実際の衝突のみが報告される。同一履歴由来の複数ブランチ出現はノイズとして除外済みのため、空でなければ必ずユーザーに提示する）。
 
 **ADR（アーキテクチャ決定記録）を作成する場合 [MANDATORY]**: 設計判断の根拠を ADR として新規作成する際も、ADR の ID は手動で決定せず、必ず `next-spec-id` で採番する（プレフィックスは `ADR`）。手動採番は並行ブランチでの番号衝突（同一 `ADR-NNN` が別内容で重複）の原因になる。ADR と DES は同一ディレクトリで通し番号を共有するため、必ず `--share-prefixes ADR,DES` を付与する:
 
diff --git a/tests/forge/scripts/test_scan_spec_ids.py b/tests/forge/scripts/test_scan_spec_ids.py
@@ -67,45 +67,97 @@ class TestFindDuplicates(unittest.TestCase):
     """find_duplicates のテスト"""
 
     def test_no_duplicates(self):
-        pairs = [
-            ('SCR-001', 'main'),
-            ('SCR-002', 'main'),
-            ('SCR-003', 'feature/foo'),
+        entries = [
+            ('SCR-001', 'main', 'specs/SCR-001_a.md'),
+            ('SCR-002', 'main', 'specs/SCR-002_b.md'),
+            ('SCR-003', 'feature/foo', 'specs/SCR-003_c.md'),
         ]
-        self.assertEqual(find_duplicates(pairs), [])
+        self.assertEqual(find_duplicates(entries), [])
 
     def test_same_id_same_branch(self):
-        pairs = [
-            ('SCR-001', 'main'),
-            ('SCR-001', 'main'),
+        entries = [
+            ('SCR-001', 'main', 'specs/SCR-001_a.md'),
+            ('SCR-001', 'main', 'specs/SCR-001_a.md'),
         ]
-        self.assertEqual(find_duplicates(pairs), [])
+        self.assertEqual(find_duplicates(entries), [])
+
+    def test_same_file_on_multiple_branches_is_not_duplicate(self):
+        """Issue #181: 同一履歴由来（同一パス）の ID が複数ブランチに見えるだけの
+        ケースは duplicate として報告しない"""
+        entries = [
+            ('SCR-001', 'develop', 'specs/SCR-001_a.md'),
+            ('SCR-001', 'feature/foo', 'specs/SCR-001_a.md'),
+            ('SCR-001', 'origin/develop', 'specs/SCR-001_a.md'),
+        ]
+        self.assertEqual(find_duplicates(entries), [])
 
     def test_duplicate_across_branches(self):
-        pairs = [
-            ('SCR-001', 'main'),
-            ('SCR-001', 'feature/foo'),
-            ('SCR-002', 'main'),
+        """異なるファイルが同じ ID を主張する場合は duplicate として報告する"""
+        entries = [
+            ('SCR-001', 'main', 'specs/SCR-001_a.md'),
+            ('SCR-001', 'feature/foo', 'specs/SCR-001_x.md'),
+            ('SCR-002', 'main', 'specs/SCR-002_b.md'),
         ]
-        result = find_duplicates(pairs)
+        result = find_duplicates(entries)
         self.assertEqual(len(result), 1)
         self.assertEqual(result[0]['id'], 'SCR-001')
         self.assertIn('main', result[0]['branches'])
         self.assertIn('feature/foo', result[0]['branches'])
+        self.assertEqual(
+            result[0]['paths'],
+            ['specs/SCR-001_a.md', 'specs/SCR-001_x.md'],
+        )
 
     def test_multiple_duplicates(self):
-        pairs = [
-            ('SCR-013', 'feature/a'),
-            ('SCR-013', 'origin/feature/b'),
-            ('SCR-014', 'feature/a'),
-            ('SCR-014', 'origin/feature/b'),
+        entries = [
+            ('SCR-013', 'feature/a', 'specs/SCR-013_a.md'),
+            ('SCR-013', 'origin/feature/b', 'specs/SCR-013_b.md'),
+            ('SCR-014', 'feature/a', 'specs/SCR-014_a.md'),
+            ('SCR-014', 'origin/feature/b', 'specs/SCR-014_b.md'),
         ]
-        result = find_duplicates(pairs)
+        result = find_duplicates(entries)
         self.assertEqual(len(result), 2)
         ids = [d['id'] for d in result]
         self.assertIn('SCR-013', ids)
         self.assertIn('SCR-014', ids)
 
+    def test_shared_numbering_detects_cross_prefix_collision(self):
+        """Issue #181: 共有採番モードでは ADR-032 と DES-032 を共有番号 032 の
+        衝突として検出する"""
+        entries = [
+            ('ADR-032', 'develop', 'specs/design/ADR-032_foo.md'),
+            ('DES-032', 'feature/x', 'specs/design/DES-032_bar.md'),
+        ]
+        result = find_duplicates(entries, shared_numbering=True)
+        self.assertEqual(len(result), 1)
+        self.assertEqual(result[0]['ids'], ['ADR-032', 'DES-032'])
+
+    def test_shared_numbering_cross_prefix_not_collision_without_flag(self):
+        """共有採番モードでなければ ADR-032 と DES-032 は独立した ID として扱う"""
+        entries = [
+            ('ADR-032', 'develop', 'specs/design/ADR-032_foo.md'),
+            ('DES-032', 'feature/x', 'specs/design/DES-032_bar.md'),
+        ]
+        self.assertEqual(find_duplicates(entries), [])
+
+    def test_shared_numbering_same_file_not_duplicate(self):
+        """共有採番モードでも同一パス由来は duplicate にならない"""
+        entries = [
+            ('ADR-032', 'develop', 'specs/design/ADR-032_foo.md'),
+            ('ADR-032', 'origin/develop', 'specs/design/ADR-032_foo.md'),
+        ]
+        self.assertEqual(find_duplicates(entries, shared_numbering=True), [])
+
+    def test_zero_padding_variants_group_by_number(self):
+        """番号は int 正規化して比較する（DES-032 と DES-32 は同じ番号の衝突）"""
+        entries = [
+            ('DES-032', 'develop', 'specs/design/DES-032_foo.md'),
+            ('DES-32', 'feature/x', 'specs/design/DES-32_bar.md'),
+        ]
+        result = find_duplicates(entries)
+        self.assertEqual(len(result), 1)
+        self.assertEqual(result[0]['ids'], ['DES-032', 'DES-32'])
+
     def test_empty_input(self):
         self.assertEqual(find_duplicates([]), [])
 
@@ -212,6 +264,23 @@ def test_glob_dirs_collapsed(self, mock_git):
         self.assertEqual(len(result), 1)
         self.assertEqual(result[0][0], 'SCR-001')
 
+    @patch('scan_spec_ids._run_git')
+    def test_namespaced_prefix_not_extracted(self, mock_git):
+        """Issue #181: COMMON-DES-001 のような別名前空間の ID を
+        DES として誤抽出しない（部分文字列マッチの防止）"""
+        mock_git.return_value = (
+            'docs/specs/common/design/COMMON-DES-001_skill_base.md\n'
+            'docs/specs/forge/design/DES-001_query_abstraction.md'
+        )
+        result = scan_ids_in_branch(
+            'main', 'DES', ['docs/specs/'], cwd='/tmp'
+        )
+        self.assertEqual(len(result), 1)
+        self.assertEqual(result[0][0], 'DES-001')
+        self.assertEqual(
+            result[0][2], 'docs/specs/forge/design/DES-001_query_abstraction.md'
+        )
+
     @patch('scan_spec_ids._run_git')
     def test_zero_padded_ids(self, mock_git):
         mock_git.return_value = (
@@ -267,9 +336,9 @@ def git_side_effect(*args, cwd=None):
         self.assertEqual(result['base_branch'], 'main')
         self.assertEqual(result['branches_scanned'], 2)
         self.assertEqual(result['ids_found'], 4)
-        # SCR-001 exists on both main and feature/foo (inherited via branch)
-        self.assertEqual(len(result['duplicates']), 1)
-        self.assertEqual(result['duplicates'][0]['id'], 'SCR-001')
+        # SCR-001 は同一パス specs/SCR-001_a.md が両ブランチに存在するだけ
+        # （同一履歴由来）なので duplicate ではない（Issue #181）
+        self.assertEqual(result['duplicates'], [])
 
     @patch('scan_spec_ids.get_scan_branches')
     @patch('scan_spec_ids.detect_base_branch')
@@ -431,6 +500,67 @@ def git_side_effect(*args, cwd=None):
         self.assertEqual(result['max_number'], 32)
         self.assertEqual(result['shared_with'], ['DES'])
 
+    @patch('scan_spec_ids.get_scan_branches')
+    @patch('scan_spec_ids.detect_base_branch')
+    @patch('scan_spec_ids._run_git')
+    @patch('scan_spec_ids.get_specs_root_dirs')
+    def test_share_prefixes_detects_shared_number_collision(
+        self, mock_dirs, mock_git, mock_base, mock_branches
+    ):
+        """Issue #181 受け入れ基準: ADR-032_foo.md と DES-032_bar.md がある場合、
+        --share-prefixes ADR,DES で共有番号衝突が検出される"""
+        mock_dirs.return_value = ['specs/design/']
+        mock_base.return_value = 'develop'
+        mock_branches.return_value = ['develop']
+
+        def git_side_effect(*args, cwd=None):
+            if args[0] == 'ls-tree':
+                return (
+                    'specs/design/ADR-032_foo.md\n'
+                    'specs/design/DES-032_bar.md'
+                )
+            return ''
+        mock_git.side_effect = git_side_effect
+
+        result = scan_spec_ids(
+            'DES', '/tmp/project', cwd='/tmp/project',
+            share_prefixes=['ADR', 'DES'],
+        )
+
+        self.assertEqual(len(result['duplicates']), 1)
+        self.assertEqual(result['duplicates'][0]['ids'], ['ADR-032', 'DES-032'])
+
+    @patch('scan_spec_ids.get_scan_branches')
+    @patch('scan_spec_ids.detect_base_branch')
+    @patch('scan_spec_ids._run_git')
+    @patch('scan_spec_ids.get_specs_root_dirs')
+    def test_share_prefixes_same_history_ids_not_reported(
+        self, mock_dirs, mock_git, mock_base, mock_branches
+    ):
+        """Issue #181 受け入れ基準: develop と current branch に同一ファイル由来で
+        存在する既存 ID は duplicate 警告にならない"""
+        mock_dirs.return_value = ['specs/design/']
+        mock_base.return_value = 'develop'
+        mock_branches.return_value = ['develop', 'feature/work', 'origin/develop']
+
+        def git_side_effect(*args, cwd=None):
+            if args[0] == 'ls-tree':
+                # 全ブランチに同一パスで存在（同一履歴由来）
+                return (
+                    'specs/design/ADR-032_foo.md\n'
+                    'specs/design/DES-031_bar.md'
+                )
+            return ''
+        mock_git.side_effect = git_side_effect
+
+        result = scan_spec_ids(
+            'DES', '/tmp/project', cwd='/tmp/project',
+            share_prefixes=['ADR', 'DES'],
+        )
+
+        self.assertEqual(result['duplicates'], [])
+        self.assertEqual(result['next_id'], 'DES-033')
+
     @patch('scan_spec_ids.get_scan_branches')
     @patch('scan_spec_ids.detect_base_branch')
     @patch('scan_spec_ids._run_git')
