Merge pull request #199 from BlueEventHorizon/fix/196-next-spec-id-branch-scan

BlueEventHorizon · web-flow · commit b018521c7bb2 · 2026-07-13T09:49:49.000+09:00
[Fix] next-spec-id のブランチスキャンから is-ancestor フィルタを撤廃 (#196)
diff --git a/.claude/.doc-advisor/toc/forge-rules-ca07acbf88c2/.toc_checksums.yaml b/.claude/.doc-advisor/toc/forge-rules-ca07acbf88c2/.toc_checksums.yaml
@@ -1,6 +1,6 @@
 # ToC checksums for key: forge-rules
 # Auto-generated - do not edit
-generated_at: 2026-07-10T07:40:30Z
+generated_at: 2026-07-13T00:41:52Z
 file_count: 38
 checksums:
   plugins/forge/docs/additive_development_spec.md: ff45c1401227966ba98bab5f10bb40d3c5ff09a536aa3e79857f879974e3421f
@@ -12,7 +12,7 @@ checksums:
   plugins/forge/docs/document_style_guide.md: aa047d3620a2a020aa4cf12aaa00f21a61279e5db3e3281c61c5a5cd12333b65
   plugins/forge/docs/forge_anti_patterns.md: 2315e4bf39c55d2367f9cccc51236915cafadff1d79e50c5d8d8efd8896530d4
   plugins/forge/docs/plan_format.md: a06d5398b02f4d605a9a76e4f7e949e9fc3af6f0bbc190ff9ddb15014084d946
-  plugins/forge/docs/plan_principles_spec.md: 4a22c4dfaa68b560b7ee3ee27e55dc94363ea14016f31ab3f51b560009ee9596
+  plugins/forge/docs/plan_principles_spec.md: 65ee603af38e876c4976c85ff27543d10c6bc3c1ebb54b3d4af42c419d6ac23d
   plugins/forge/docs/requirement_format.md: 400ae580d36cec62c77cbba3255f26bba329e8b21cbf9dacbac53d6cff0f58ff
   plugins/forge/docs/review_priorities_spec.md: 797518b97a8dca2002639fa2afe0727c0ef1b30ae8eec2c24b4c73b5e1ee4119
   plugins/forge/docs/scope_proportionality_spec.md: d32e77754e8d2d06a2cbafda52e745e95baec08b89be34ff56604e7aabb3ab9b
@@ -21,7 +21,7 @@ checksums:
   plugins/forge/docs/spec_format.md: a764056bd3dc434db6e0cc3a18761503aa89b463623c7ceb938354e589cd6b6d
   plugins/forge/docs/spec_priorities_spec.md: 9ccba91f19c15cd8613d6ed5bca58fd5bd3f6679ac38f80294540d5918a1abac
   plugins/forge/docs/strategy_formulation_spec.md: b77a8920147a4e847c7612adc2aa51c79efa4c7857b4c52edb92d0b88a9acdf1
-  plugins/forge/docs/task_execution_spec.md: 7d373c42062812c25873dc7bd14ecdd9e3447d72fdca91a12db17221976ca0fb
+  plugins/forge/docs/task_execution_spec.md: 72556bf3c8dad8cda1a7aee05186df8318c555c372214e6da97625789cd93bf3
   plugins/forge/docs/version_migration_spec.md: accb3b2f52c7bc199f110d3f19ac533610bd4d49fc9b7f00173445f4bc97df70
   plugins/forge/skills/clean-rules/docs/taxonomy.md: cbe025933f39f74be1d11707b0a4c376c9aab7faa99973f6bfa1a6c09ee9b39a
   plugins/forge/skills/review/docs/review_criteria_code.md: 9e7066ad7dd3a9bc7891f9261af5babbfc63b24fc096c57df8cdf6db2a9ac49a
diff --git a/.claude/.doc-advisor/toc/forge-rules-ca07acbf88c2/toc.yaml b/.claude/.doc-advisor/toc/forge-rules-ca07acbf88c2/toc.yaml
diff --git a/docs/readme/forge/guide_implement.md b/docs/readme/forge/guide_implement.md
@@ -84,6 +84,8 @@ Executor behavior:
 3. Verify with build and tests
 4. Report results
 
+When a strategy document (`{feature}_strategy.md`) exists, it is passed as required reading so the executor understands the implementation approach, phase intent, and risk mitigation before working on the single assigned task.
+
 #### Constraints
 
 - **One task per execution** — no touching adjacent tasks
diff --git a/docs/specs/forge/design/DES-019_create_plan_workflow_design.md b/docs/specs/forge/design/DES-019_create_plan_workflow_design.md
@@ -128,6 +128,8 @@ flowchart TD
 | 4.3  | フォーマット適用（`plan_format.md` に準拠）                            |
 | 4.4  | 完全性チェック [MANDATORY]                                             |
 
+各タスクの `required_reading` には `{feature}_strategy.md` を必ず含める。executor が単一タスクだけを実装する場合でも、全体戦略・フェーズ意図・リスク対策を理解したうえで実装判断できるようにする。
+
 **タスク粒度 [MANDATORY]:**
 
 - 1 Agent が単独で実行・完結できる単位
diff --git a/docs/specs/forge/design/DES-027_plan_strategy_phase_adr.md b/docs/specs/forge/design/DES-027_plan_strategy_phase_adr.md
@@ -117,4 +117,4 @@ plan.yaml は構造化データ（YAML）であり、`start-implement` が機械
 ### 変更不要
 
 - `plan_format.md` — plan.yaml のスキーマは変更なし
-- `start-implement` — タスク実行ロジックは影響なし（strategy.md は参考文書として required_reading に含めうる）
+- `start-implement` — タスク実行ロジックは影響なし。ただし executor が全体戦略・フェーズ意図・リスク対策を理解できるよう、strategy.md は全タスクの `required_reading` に含め、executor への必読文書として渡す
diff --git a/plugins/anvil/skills/impl-issue/SKILL.md b/plugins/anvil/skills/impl-issue/SKILL.md
@@ -354,6 +354,11 @@ Phase 8 で作成する成果物は次の 2 つ。**用途・出力先・参照
 **書き込む内容**: 解決内容（対策・実装計画・TODO）のみを Issue に追記する。
 背景 / 現象・原因はすでに記載済みのため、上書きしない。
 
+> [!WARNING]
+> `gh issue edit --body-file` は本文の**完全置換**であり追記コマンドではない。実装計画のみを書いたファイルを
+> そのまま渡すと既存の背景・現象・原因が消える。**必ず既存本文を取得してから実装計画を末尾に結合した全文**を
+> `--body-file` に渡す（手順は `references/phase-09-issue-update.md` 参照）。
+
 実装計画を Issue に記載する。参照は GitHub / Figma で開けるもののみ記載する。
 
 **Issue 更新前に必ず [`references/phase-09-issue-update.md`](references/phase-09-issue-update.md) を読む。**
diff --git a/plugins/anvil/skills/impl-issue/assets/TEMPLATE.md b/plugins/anvil/skills/impl-issue/assets/TEMPLATE.md
@@ -71,12 +71,4 @@
 
 ## gh コマンド例
 
-特殊文字（バッククォート・`$` 等）に強い `--body-file` 経由で更新する。詳細手順とエンコード規約は [`references/phase-09-issue-update.md`](../references/phase-09-issue-update.md) を参照。
-
-```bash
-tee /tmp/issue_body.md <<'BODY'
-<上記テンプレートの内容>
-BODY
-
-gh issue edit <issue番号> --repo <owner>/<repo> --body-file /tmp/issue_body.md
-```
+`gh issue edit --body-file` は本文の**完全置換**であり追記ではない。既存本文の取得・検証・結合・更新の具体手順とエンコード規約は [`references/phase-09-issue-update.md`](../references/phase-09-issue-update.md) を参照（本ファイルにコマンド例は重複させない）。
diff --git a/plugins/anvil/skills/impl-issue/references/phase-09-issue-update.md b/plugins/anvil/skills/impl-issue/references/phase-09-issue-update.md
@@ -38,23 +38,67 @@ Issue に記載する参照は **GitHub / Figma で開けるものだけ** に
 
 `<owner>/<repo>` は Phase 0 で解決した値を使用する。
 
-1. ユーザーに計画内容を提示し確認する
-2. 本文を一時ファイルに書き出してから `--body-file` で渡す（特殊文字・バッククォート・`$` が含まれても安全）：
+### `gh issue edit --body-file` は本文の完全置換である [MANDATORY]
+
+`gh issue edit --body-file` に diff/追記の概念はない。渡したファイルの内容が Issue 本文を**丸ごと置き換える**。
+「解決内容（対策・実装計画・TODO）のみを追記する」という本 Phase の原則を守るには、**既存本文を取得してから
+末尾に実装計画を結合した「全文」を組み立てて渡す**必要がある。既存本文を持たないファイル（実装計画セクションのみ）を
+そのまま `--body-file` に渡すと、背景・現象・原因（`/anvil:create-issue` が作成した課題の内容）を消してしまう。
+
+0. **実行ごとに一意な作業ディレクトリを作る [MANDATORY]**: `/tmp/issue_body*.md` のような固定パスは、並行実行
+   （複数セッション・複数 Issue の同時作業）や前回異常終了時の残骸ファイルと衝突し、**別 Issue の本文を誤って
+   結合・上書きするリスク**がある。`mktemp -d` で実行ごとに一意なディレクトリを作り、`trap` でスクリプト終了時に
+   確実に削除する：
+
+   ```bash
+   workdir=$(mktemp -d)
+   trap 'rm -rf "$workdir"' EXIT
+   ```
+
+   以降の Step ではこの `$workdir` 配下のパスのみを使用する（固定パスを直接書かない）。
+
+1. 計画内容を提示したうえで、`AskUserQuestion` を使用して Issue 更新を実行するか確認する。承認後のみ Step 2 へ進む
+2. **既存本文を取得し、成否を検証する**（更新前に必ず実行。取得を飛ばして新規ファイルだけを渡さない）：
+
+   **取得結果を検証する [MANDATORY]**: `gh` コマンドの失敗（認証切れ・レート制限・ネットワーク断）や本文が
+   null の場合でも、シェルのリダイレクトは空（または `null` という文字列）のファイルをそのまま作成してしまう。
+   取得コマンドの exit code と出力ファイルの非空を、**取得コマンドと同じシェル実行内で**確認し、失敗または空の
+   場合は Step 3 へ進まず中断してユーザーに報告する（別のコマンド実行に分けると `$?` が別コマンドの結果に
+   上書きされ検証が機能しなくなるため、1 ブロックで実行する）：
 
    ```bash
-   tee /tmp/issue_body.md <<'BODY'
-   <本文>
+   gh issue view <issue番号> --repo <owner>/<repo> --json body --jq '.body' > "$workdir/issue_body_original.md"
+   rc=$?
+   if [ $rc -ne 0 ] || [ ! -s "$workdir/issue_body_original.md" ] || [ "$(cat "$workdir/issue_body_original.md")" = "null" ]; then
+     echo "既存本文の取得に失敗しました。Issue 番号・権限・ネットワークを確認してください。" >&2
+     exit 1
+   fi
+   ```
+
+3. 既存本文 + 実装計画（テンプレート）を**1 つのファイルに結合**する。既存本文の内容は変更・削除・要約しない、そのまま末尾に追記する：
+
+   ```bash
+   cat "$workdir/issue_body_original.md" > "$workdir/issue_body.md"
+   echo "" >> "$workdir/issue_body.md"
+   tee -a "$workdir/issue_body.md" <<'BODY'
+   <実装計画テンプレートの内容>
    BODY
+   ```
+
+4. 結合後のファイルを `--body-file` で渡す：
 
-   gh issue edit <issue番号> --repo <owner>/<repo> --body-file /tmp/issue_body.md
+   ```bash
+   gh issue edit <issue番号> --repo <owner>/<repo> --body-file "$workdir/issue_body.md"
    ```
 
-3. 更新後、内容を確認する：
+5. **更新後、本文全体を確認し、既存の背景・現象・原因セクションが残っていることを検証する**（実装計画セクションの追加だけでなく、削れていないかを見る）：
 
    ```bash
    gh issue view <issue番号> --repo <owner>/<repo>
    ```
 
+   既存セクションが失われていた場合は、直前の Issue 内容（本 Phase 開始前に取得したコメント・本文）から手作業で復元し、再度 `--body-file` で修正する。
+
 ## Issue 更新テンプレート
 
 [assets/TEMPLATE.md](../assets/TEMPLATE.md) を参照。
diff --git a/plugins/forge/docs/plan_principles_spec.md b/plugins/forge/docs/plan_principles_spec.md
@@ -58,9 +58,12 @@
 ```yaml
 required_reading:
   - specs/feature/design/DES-001_foo_design.md
+  - specs/feature/plan/feature_strategy.md
   - rules/architecture/domain_core.md
 ```
 
+**実装戦略書 [MANDATORY]**: `/forge:start-plan` が `{feature}_strategy.md` を作成した場合、すべてのタスクの `required_reading` にその戦略書パスを含める。戦略書は executor が全体戦略・フェーズ意図・リスク対策を理解するための必読文書である。
+
 **誤った例**:
 
 - `foo_design` ❌（曖昧名）
diff --git a/plugins/forge/docs/task_execution_spec.md b/plugins/forge/docs/task_execution_spec.md
@@ -46,15 +46,15 @@ Step 5: 完了処理（結果報告、終了）
 
 オーケストレーターから以下の情報が提供される:
 
-| 項目     | 内容                                               |
-| -------- | -------------------------------------------------- |
-| タスクID | 実装するタスクの識別子                             |
-| タスク名 | タスクのタイトル                                   |
-| 優先度   | タスクの優先度（数値）                             |
-| 実装内容 | やるべき内容の詳細リスト                           |
-| 必読文書 | 設計書、要件定義書、ルール文書、参照コードのリスト |
-| 実装指示 | タスク固有の実装方針                               |
-| 検証要件 | ビルド確認・テスト実行の要否とスキップ理由         |
+| 項目     | 内容                                                       |
+| -------- | ---------------------------------------------------------- |
+| タスクID | 実装するタスクの識別子                                     |
+| タスク名 | タスクのタイトル                                           |
+| 優先度   | タスクの優先度（数値）                                     |
+| 実装内容 | やるべき内容の詳細リスト                                   |
+| 必読文書 | 設計書、要件定義書、戦略書、ルール文書、参照コードのリスト |
+| 実装指示 | タスク固有の実装方針                                       |
+| 検証要件 | ビルド確認・テスト実行の要否とスキップ理由                 |
 
 ---
 
@@ -66,8 +66,9 @@ Step 5: 完了処理（結果報告、終了）
 
 1. **設計書**（必須）: タスクの直接根拠。最優先で全文読了
 2. **要件定義書**（必須）: 仕様の確認用。関連仕様が離れた場所に記載されている可能性あり
-3. **ルール文書**（必須）: 実装ルール・コーディング規約
-4. **参照コード**（推奨）: 既存の関連コードを網羅的に確認。量が多い場合は実装に直接関連する部分を優先
+3. **戦略書**（必須）: 全体戦略・フェーズ意図・リスク対策を把握し、指定タスク内の実装判断に反映
+4. **ルール文書**（必須）: 実装ルール・コーディング規約
+5. **参照コード**（推奨）: 既存の関連コードを網羅的に確認。量が多い場合は実装に直接関連する部分を優先
 
 ### 2.2 既存コード確認 [MANDATORY]
 
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
@@ -29,7 +29,6 @@
 from resolve_doc_structure import (
     find_project_root,
     load_doc_structure,
-    parse_config,
 )
 
 FALLBACK_SPECS_DIRS = ['specs/']
@@ -89,8 +88,6 @@ def detect_base_branch(cwd=None):
         'refs/heads/main',
         'refs/remotes/origin/main',
     ]:
-        result = _run_git('show-ref', '--verify', '--quiet', ref, cwd=cwd)
-        # show-ref --quiet は見つかれば exit 0
         try:
             proc = subprocess.run(
                 ['git', 'show-ref', '--verify', '--quiet', ref],
@@ -108,7 +105,14 @@ def detect_base_branch(cwd=None):
 
 
 def get_scan_branches(base_branch, cwd=None):
-    """ベースブランチから派生した全ブランチを取得する。"""
+    """ローカル + リモートの全ブランチを取得する。
+
+    ID 衝突検出の目的では「base に追従しているか」は無関係であり、むしろ
+    base から分岐したまま追従していないブランチほど衝突リスクが高い
+    （Issue #196）。そのため is-ancestor によるフィルタは行わず、
+    refs/heads/ + refs/remotes/origin/ から取得した全ブランチを無条件で
+    スキャン対象にする。
+    """
     output = _run_git(
         'for-each-ref', '--format=%(refname:short)',
         'refs/heads/', 'refs/remotes/origin/',
@@ -123,24 +127,7 @@ def get_scan_branches(base_branch, cwd=None):
     ]
     all_branches = sorted(set(all_branches))
 
-    scan = []
-    for branch in all_branches:
-        if branch == base_branch:
-            scan.append(branch)
-            continue
-        try:
-            proc = subprocess.run(
-                ['git', 'merge-base', '--is-ancestor', base_branch, branch],
-                capture_output=True,
-                cwd=cwd,
-                timeout=10,
-            )
-            if proc.returncode == 0:
-                scan.append(branch)
-        except (subprocess.TimeoutExpired, FileNotFoundError):
-            continue
-
-    return scan if scan else [base_branch]
+    return all_branches if all_branches else [base_branch]
 
 
 def scan_ids_in_branch(branch, prefix, scan_dirs, cwd=None):
@@ -236,8 +223,10 @@ def scan_spec_ids(prefix, project_root, doc_structure_path=None, cwd=None, share
 
     scan_dirs = get_specs_root_dirs(project_root, doc_structure_path)
 
-    # リモートをフェッチ
-    _run_git('fetch', '--quiet', cwd=cwd)
+    # リモートをフェッチ（--prune: 削除済み remote branch の stale ref を除去。
+    # 全ブランチ無条件スキャン方式では、stale ref が残ると存在しないブランチの
+    # 高番 ID が永久に next_id を押し上げてしまうため必須）
+    _run_git('fetch', '--quiet', '--prune', cwd=cwd)
 
     base_branch = detect_base_branch(cwd=cwd)
     branches = get_scan_branches(base_branch, cwd=cwd)
diff --git a/plugins/forge/skills/start-implement/SKILL.md b/plugins/forge/skills/start-implement/SKILL.md
@@ -184,6 +184,8 @@ prompt:
 
 タスクの `required_reading` 配列が空配列 `[]` でない場合、記載された各ファイルパスを追加の必読文書として executor に渡す。`required_reading` は YAML のタスクフィールドであり、Markdown table の「列」ではない点に注意する。
 
+`{feature}_strategy.md` が `required_reading` に含まれている場合は、**戦略書**として分類して executor に渡す。含まれていない場合でも、計画書と同じディレクトリに `{feature}_strategy.md` が存在するなら追加の必読文書として executor に渡す。executor は全体戦略・フェーズ意図・リスク対策を理解したうえで、指定された単一タスクだけを実装する。
+
 ### 3.2 統合・表示
 
 全 agent 完了後、agent の return value (実装ルール / 既存コード) と直接特定した文書 (設計書 / 要件定義書) を統合して表示する:
@@ -202,6 +204,12 @@ prompt:
 
 **code (N件)**
 - `src/xxx/YYY.ts` — 既存実装
+
+**戦略書**
+- `specs/{feature}/plan/{feature}_strategy.md` — 実装戦略
+
+**追加必読文書**
+- `specs/{feature}/rules/extra_context.md` — 計画書 required_reading（戦略書以外）
 ```
 
 5件以下は全件表示、6件以上は先頭3件+省略。
@@ -251,10 +259,14 @@ ${CLAUDE_PLUGIN_ROOT}/docs/task_execution_spec.md を Read して手順に従う
   - {設計書ファイルパス}
 - 要件定義書:
   - {関連する全ての要件定義書}
+- 戦略書:
+  - {feature_strategy.md のパス}
 - ルール文書:
   - {関連する全てのルール文書}
 - 参照コード:
   - {関連する全ての既存実装}
+- 追加必読文書:
+  - {required_reading に含まれる戦略書以外の文書}
 
 ## 実装指示
 
diff --git a/plugins/forge/skills/start-plan/SKILL.md b/plugins/forge/skills/start-plan/SKILL.md
@@ -222,6 +222,8 @@ Agent 完了後:
 3. 同一フェーズ内で依存関係を整理（依存される側から先に実装）
 4. 並列実行可能なタスクを識別（依存関係がないタスク群）
 
+**実装戦略書の必読化 [MANDATORY]**: すべてのタスクの `required_reading` に `{output_dir}/{feature}_strategy.md` を含める。executor が単一タスクだけを実装する場合でも、全体戦略・フェーズ意図・リスク対策を理解したうえで実装判断できるようにするため。
+
 **タスクの粒度**:
 
 | 基準   | 内容                                                   |
@@ -287,6 +289,7 @@ JSON 出力の `next_id` を起点に連番を使用する。`duplicates` が空
 - [ ] `tasks[]` の各要素が必須フィールドをすべて持つ: `task_id` / `title` / `priority` / `status` / `design_id` / `depends_on` / `group_id` / `build_check` / `description` / `acceptance_criteria` / `required_reading`
 - [ ] `tasks[].design_id` は文字列か `null`（`-` や `"-"` ではない）
 - [ ] `tasks[].depends_on` / `required_reading` は配列（なければ `[]`、`null` でも `-` でもない）
+- [ ] すべての `tasks[].required_reading` に `{output_dir}/{feature}_strategy.md` が含まれている
 - [ ] `tasks[].build_check` の値は `per_task` / `skip` / `on_group_complete` のいずれか
 - [ ] `tasks[].status` の値は `pending` / `in_progress` / `completed` のいずれか
 - [ ] `requirements_traceability[].status` の値は `pending` / `completed` のいずれか
diff --git a/plugins/forge/toc/rules/.toc_checksums.yaml b/plugins/forge/toc/rules/.toc_checksums.yaml
diff --git a/plugins/forge/toc/rules/rules_toc.yaml b/plugins/forge/toc/rules/rules_toc.yaml
diff --git a/tests/forge/scripts/test_scan_spec_ids.py b/tests/forge/scripts/test_scan_spec_ids.py
