Fix HEAD-scoped index freshness

SELF_IMPROVEMENT.md

@@ -39,11 +39,11 @@ The loop is not just "suggest ideas". It is:
 - Before every commit, explicitly work through `.codex/workflows/precommit.md`.
 - Before every commit, review README `# Code Search Rules` and `# コードベース検索ルール`; strengthen them if AI behavior should change.
 - After every commit, rebuild `cdidx` from the latest local source, run `dotnet ./src/CodeIndex/bin/Debug/net8.0/cdidx.dll status --check --json`, and refresh `.cdidx/codeindex.db` with that freshly built binary only when the check does not report `index_matches_workspace: true`.
-- Prefer the lightest truthful refresh mode: use `--files` only for known in-place edits or new files, use `--commits HEAD` after a normal commit because it tracks renames/deletes from git history, use `--changed-between <old-ref> <new-ref>` after branch switches when both refs are known, and reserve a full `cdidx . --json` scan for history-moving operations or cases where repo-wide stale files must be purged.
+- Prefer the lightest truthful refresh mode: use `--files` only for known in-place edits or new files, use `--commits HEAD` after a normal commit because it tracks renames/deletes from git history, use `--changed-between <old-ref> <new-ref>` after branch switches when both refs are known, and reserve `cdidx . --json` for full-workspace scans after history-moving operations or cases where repo-wide stale files must be purged. `cdidx . --json` is not a forced rebuild and may report `mode:"incremental"` while skipping unchanged files; if `status --check --json` still reports stale after that scan, escalate to `dotnet ./src/CodeIndex/bin/Debug/net8.0/cdidx.dll index . --rebuild --yes --json`.
 - Prefer the **locally built latest binary** (`dotnet ./src/CodeIndex/bin/Debug/net8.0/cdidx.dll`) over an older globally installed `cdidx` whenever the repository code has changed. **Never fall back to a global `cdidx`** — the global version may have an older DB schema, missing query features, or stale extraction logic that silently produces wrong results. This is enforced at the Claude Code harness level via the repo-tracked `.claude/settings.json`, which denies the full set of shell code-search and file-discovery commands: `rg`, `grep`, `egrep`, `fgrep`, `zgrep`, `rgrep`, `ripgrep`, `ag`, `ack`, `ack-grep`, `git grep`, `find`, `locate`, `mlocate`, `mdfind`, and `cdidx`. Use the built-in Grep / Glob tools or the locally built binary instead.
 - Treat repo-tracked `.claude/settings.json`, `.claude/hooks/bash-guard.py`, `.codex/hooks.json`, and `.codex/hooks/bash_guard.py` as tool-specific guard adapters. Do not edit them during ordinary self-improvement work unless the task is explicitly about agent guard behavior. Shared Bash command policy lives in `.agent_harness/command_guard_core.py`; update that shared core for common policy and review both adapters only when tool-specific behavior changes. The current guard is deny-oriented: it is intentionally permissive for routine `dotnet`, `git`, `gh`, `codex exec`, `/tmp` work, and read-only shell inspection, while still blocking dangerous shell patterns and sensitive local read paths.
 - Respect the current local-privacy boundary in Claude Code: home-directory personal areas and credential-like files are intentionally read-denied by policy. Do not weaken those restrictions as a convenience workaround for self-improvement tasks; if the task genuinely requires changing the guard, treat that as the task itself and update docs accordingly.
-- After `git switch`, re-index with the **locally built binary** using `dotnet ./src/CodeIndex/bin/Debug/net8.0/cdidx.dll index . --changed-between <old-ref> <new-ref> --json` when the workflow has both the previous and current refs; this updates only the files changed between branches while still purging rename/delete old paths included by git. If the refs are not available, or after `git reset`, `git rebase`, `git commit --amend`, or `git merge`, use `dotnet ./src/CodeIndex/bin/Debug/net8.0/cdidx.dll . --json` so stale files are purged against the current checkout.
+- After `git switch`, re-index with the **locally built binary** using `dotnet ./src/CodeIndex/bin/Debug/net8.0/cdidx.dll index . --changed-between <old-ref> <new-ref> --json` when the workflow has both the previous and current refs; this updates only the files changed between branches while still purging rename/delete old paths included by git. If the refs are not available, or after `git reset`, `git rebase`, `git commit --amend`, or `git merge`, use `dotnet ./src/CodeIndex/bin/Debug/net8.0/cdidx.dll . --json` so stale files are purged against the current checkout. If the follow-up status check remains stale, run `dotnet ./src/CodeIndex/bin/Debug/net8.0/cdidx.dll index . --rebuild --yes --json` instead of repeating `cdidx . --json`.
 - When searching and navigating code to investigate bugs, plan fixes, or verify changes, always use the **locally built binary** — not the globally installed version. This ensures query results reflect the latest extraction rules and DB schema from this branch.
 - If the **locally built binary** crashes, aborts unexpectedly, or exposes a new defect during this loop, do not silently work around it or fall back to an older/global binary. Notify the user with the concrete failure, explain that the self-improvement loop is now blocked or tainted by that defect, and propose fixing it as a separate task or as the next approved priority.
 - Treat the loop itself as ongoing regression coverage and light monkey testing. Do not limit yourself to only the safest or most standard workflows; actively exercise recent features, edge features, and less-traveled commands/options so the loop can indirectly surface crashes, bad assumptions, stale help text, and integration defects.
@@ -144,7 +144,7 @@ If `status --json` reports `fold_ready: false` and you only need Unicode-aware `
 dotnet ./src/CodeIndex/bin/Debug/net8.0/cdidx.dll backfill-fold --json
 ```
 
-Use a full `cdidx . --json` rebuild only when you need a fresh source scan, when history-moving git operations just happened, when branch-switch refs are unavailable, or when repo-wide stale-file purge matters more than speed. In the ordinary commit-to-commit loop, prefer `--commits` first; after branch switches with known refs, prefer `--changed-between`; and use `--files` only for in-place edits/new files where no old path needs purging.
+Use `cdidx . --json` as a full-workspace scan only when you need a fresh source scan, when history-moving git operations just happened, when branch-switch refs are unavailable, or when repo-wide stale-file purge matters more than speed. This path is not a forced rebuild: it may report `mode:"incremental"` and skip unchanged files. If `status --check --json` remains stale after that scan, run `dotnet ./src/CodeIndex/bin/Debug/net8.0/cdidx.dll index . --rebuild --yes --json`. In the ordinary commit-to-commit loop, prefer `--commits` first; after branch switches with known refs, prefer `--changed-between`; and use `--files` only for in-place edits/new files where no old path needs purging.
 
 Typical sequence:
 
@@ -369,11 +369,11 @@ Read `SELF_IMPROVEMENT.md`, inspect the current repo with cdidx itself, identify
 - 毎コミット前に、`.codex/workflows/precommit.md` を明示的に確認する。
 - 毎コミット前に、README の `# Code Search Rules` と `# コードベース検索ルール` を見直し、AIの検索行動を変えるべきなら強化する。
 - 毎コミット後に、ローカルソースの最新状態から `cdidx` を再ビルドし、`dotnet ./src/CodeIndex/bin/Debug/net8.0/cdidx.dll status --check --json` を実行する。`index_matches_workspace: true` でなければ、その新しいバイナリで `.cdidx/codeindex.db` を更新する。
-- 更新モードは「正しさを保てる範囲で最も軽いもの」を優先する。`--files` は把握している in-place 編集や新規追加だけに使い、通常のコミット後は rename/delete も拾える `--commits HEAD` を使う。ブランチ切り替え後は前後の ref が分かるなら `--changed-between <old-ref> <new-ref>` を使い、履歴を動かす操作や repo 全体で stale file を掃除したい場合だけ `cdidx . --json` のフルスキャンへ上げる。
+- 更新モードは「正しさを保てる範囲で最も軽いもの」を優先する。`--files` は把握している in-place 編集や新規追加だけに使い、通常のコミット後は rename/delete も拾える `--commits HEAD` を使う。ブランチ切り替え後は前後の ref が分かるなら `--changed-between <old-ref> <new-ref>` を使い、履歴を動かす操作や repo 全体で stale file を掃除したい場合だけ `cdidx . --json` の全 workspace scan へ上げる。`cdidx . --json` は強制 rebuild ではなく、`mode:"incremental"` と表示して unchanged file を skip する場合があるため、その後の `status --check --json` がまだ stale なら `dotnet ./src/CodeIndex/bin/Debug/net8.0/cdidx.dll index . --rebuild --yes --json` に上げる。
 - リポジトリのコードを変更した後は、古いグローバルインストール版ではなく **ローカルでビルドした最新版バイナリ** (`dotnet ./src/CodeIndex/bin/Debug/net8.0/cdidx.dll`) を使う。**グローバル版には絶対に戻らないこと** — グローバル版は DB スキーマが古い、クエリ機能が欠けている、抽出ロジックが古くて誤った結果を返す、といった問題が起こりうる。このルールはリポジトリ追跡の `.claude/settings.json` で harness レベルでも強制されており、shell のコード検索・ファイル探索系コマンドを網羅的に deny している（`rg`、`grep`、`egrep`、`fgrep`、`zgrep`、`rgrep`、`ripgrep`、`ag`、`ack`、`ack-grep`、`git grep`、`find`、`locate`、`mlocate`、`mdfind`、`cdidx`）。代わりに組み込みの Grep / Glob ツールかローカルビルド版を使うこと。
 - リポジトリ追跡の `.claude/settings.json` と `.claude/hooks/bash-guard.py` はポリシーファイルとして扱う。通常の自己改善作業では編集せず、Claude Code のガード挙動自体を変えるタスクのときだけ触る。現在のガードは deny ベースで、日常的な `dotnet`、`git`、`gh`、`codex exec`、`/tmp` 作業、読み取り中心の shell 確認は止めにくくしつつ、危険な shell パターンと機微なローカル read path は止める設計になっている。
 - Claude Code のローカルプライバシー境界を尊重すること。ホーム配下の私物領域や資格情報系ファイルはポリシーで read deny されているため、自己改善タスクを進めやすくする目的でそれを緩めない。もし guard の変更自体が本当に必要なら、それを独立したタスクとして扱い、関連ドキュメントも同じコミットで更新する。
-- `git switch` の後は、切り替え前後の ref が分かる場合、**ローカルビルド版** で `dotnet ./src/CodeIndex/bin/Debug/net8.0/cdidx.dll index . --changed-between <old-ref> <new-ref> --json` を実行する。これにより、ブランチ間で変わったファイルだけを更新しつつ、git が返す rename/delete の旧 path も purge できる。ref が分からない場合や、`git reset`、`git rebase`、`git commit --amend`、`git merge` の後は、`dotnet ./src/CodeIndex/bin/Debug/net8.0/cdidx.dll . --json` のフルスキャンで現在の checkout に対する stale file を掃除する。
+- `git switch` の後は、切り替え前後の ref が分かる場合、**ローカルビルド版** で `dotnet ./src/CodeIndex/bin/Debug/net8.0/cdidx.dll index . --changed-between <old-ref> <new-ref> --json` を実行する。これにより、ブランチ間で変わったファイルだけを更新しつつ、git が返す rename/delete の旧 path も purge できる。ref が分からない場合や、`git reset`、`git rebase`、`git commit --amend`、`git merge` の後は、`dotnet ./src/CodeIndex/bin/Debug/net8.0/cdidx.dll . --json` の full-workspace scan で現在の checkout に対する stale file を掃除する。その後も status check が stale なら、`cdidx . --json` を繰り返さず `dotnet ./src/CodeIndex/bin/Debug/net8.0/cdidx.dll index . --rebuild --yes --json` を実行する。
 - バグ調査、修正計画、変更検証のためにコード検索・ナビゲーションを行うときも、常に **ローカルビルド版** を使う。グローバルインストール版は使わない。これにより、このブランチの最新の抽出ルールと DB スキーマを反映した検索結果が得られる。
 - このループ中に **ローカルビルド版** がクラッシュしたり、異常終了したり、新しい不具合を露呈した場合は、黙って回避したり古い版・グローバル版へ逃げたりしないこと。具体的な失敗内容をユーザーに通知し、その不具合によって自己改善ループがブロックされている、または結果の信頼性が損なわれていることを説明したうえで、別タスクまたは次の承認済み優先事項として修正提案を出すこと。
 - このループ自体を、継続的なリグレッション確認と軽いモンキーテストとして扱うこと。最も安全で標準的なワークフローだけに偏らず、新しい機能、利用頻度の低い機能、枝葉末節のオプションも積極的に触り、間接的にクラッシュ、古いヘルプ文、想定漏れ、統合不具合をあぶり出すこと。
@@ -471,7 +471,7 @@ dotnet run --project src/CodeIndex -- . --json
 dotnet ./src/CodeIndex/bin/Debug/net8.0/cdidx.dll backfill-fold --json
 ```
 
-ソース再走査も必要なとき、履歴を動かす git 操作の直後、ブランチ切り替え前後の ref が分からないとき、または repo 全体で stale file を掃除したいときだけ、`cdidx . --json` のフル更新を使います。通常のコミット間ループでは rename/delete も追える `--commits`、ブランチ切り替えでは前後 ref を渡す `--changed-between` を先に考え、`--files` は in-place 編集や新規追加に限定してください。
+ソース再走査も必要なとき、履歴を動かす git 操作の直後、ブランチ切り替え前後の ref が分からないとき、または repo 全体で stale file を掃除したいときだけ、`cdidx . --json` の full-workspace scan を使います。この経路は強制 rebuild ではなく、`mode:"incremental"` と表示して unchanged file を skip する場合があります。その後の `status --check --json` がまだ stale なら、`dotnet ./src/CodeIndex/bin/Debug/net8.0/cdidx.dll index . --rebuild --yes --json` を実行してください。通常のコミット間ループでは rename/delete も追える `--commits`、ブランチ切り替えでは前後 ref を渡す `--changed-between` を先に考え、`--files` は in-place 編集や新規追加に限定してください。
 
 典型例:
 

changelog.d/unreleased/2809.fixed.md

@@ -0,0 +1,26 @@
+---
+category: fixed
+issues:
+  - 2809
+affected:
+  - src/CodeIndex/Cli/CliFlagSchema.cs
+  - src/CodeIndex/Cli/ConsoleUi.cs
+  - src/CodeIndex/Cli/GitHelper.cs
+  - src/CodeIndex/Cli/IndexCommandRunner.DryRun.cs
+  - src/CodeIndex/Cli/IndexCommandRunner.Parse.cs
+  - src/CodeIndex/Cli/IndexCommandRunner.cs
+  - src/CodeIndex/Cli/IndexCommandRunner.Update.cs
+  - src/CodeIndex/Cli/IndexCommandRunner.Validation.cs
+  - tests/CodeIndex.Tests/ConsoleUiTests.cs
+  - tests/CodeIndex.Tests/IndexCommandRunnerTests.cs
+  - tests/CodeIndex.Tests/ProgramCliTests.cs
+  - SELF_IMPROVEMENT.md
+---
+
+## English
+
+- **Branch-switch freshness now recognizes git-scoped refreshes at HEAD (#2809)** — `status --check` no longer stays stale after a successful `--commits HEAD` or `--changed-between <old-ref> HEAD` refresh, and the agent guidance now clarifies when to escalate from `cdidx . --json` to a forced rebuild.
+
+## 日本語
+
+- **ブランチ切り替え後の freshness が HEAD を対象にした git-scoped 更新を認識するようになりました (#2809)** — `--commits HEAD` または `--changed-between <old-ref> HEAD` の成功後に `status --check` が stale のまま残らないようにし、agent guidance では `cdidx . --json` から強制 rebuild へ上げる条件を明確化しました。

src/CodeIndex/Cli/CliFlagSchema.cs

@@ -289,7 +289,7 @@ private static IReadOnlyList<CliFlag> BuildAll()
             new() { Name = "--max-symbols-per-file", ValuePlaceholder = "<n>", Description = "Skip file content, symbols, and references when one file emits too many symbols", Commands = Set("index") },
             new() { Name = "--parallelism", ValuePlaceholder = "<n>", Description = "Full-scan extraction worker count (default: CPU count capped at 16; also honors CDIDX_INDEX_PARALLELISM)", Commands = Set("index") },
             new() { Name = "--memory-trace", Description = "Include phase memory samples in index JSON output", Commands = Set("index") },
-            new() { Name = "--commits", ValuePlaceholder = "<id>", Description = "Update files changed in given git commits", Commands = Set("index") },
+            new() { Name = "--commits", ValuePlaceholder = "<commit-ref>", Description = "Update files changed in given git commits", Commands = Set("index") },
             new() { Name = "--changed-between", ValuePlaceholder = "<old-ref> <new-ref>", Description = "Update files changed between two git refs", Commands = Set("index") },
             new() { Name = "--files", ValuePlaceholder = "<path>", Description = "Update only the specified files", Commands = Set("index") },
             new() { Name = "--watch", Description = "Continuous reindex on file changes (rejects --commits / --changed-between / --files / --dry-run)", Commands = Set("index") },