Fix CLI option registry drift (#4861)

DEVELOPER_GUIDE.md

@@ -201,13 +201,16 @@ git status --short -- '**/packages.lock.json'
 
 `CliCommandCatalog` owns command and nested-subcommand names, including whether
 a nested verb is optional and parent flags must remain available, while
-`CliFlagSchema` owns primary flags, aliases, placeholders, descriptions, and
-command applicability. Every shell completion renderer consumes those shared
-definitions, and `ConsoleUi.PrintCommandUsage` uses them when the shared parser is
-the authoritative option inventory. Dedicated or nested parsers retain exact
-usage-specific syntax until their subcommand metadata is complete. Add new CLI
-metadata there first so parser validation, help, completion, and generated
-next-step flags stay aligned without emitting partial option lists. Every verb
+`CliFlagSchema` owns primary flags, aliases, placeholders, descriptions, command
+applicability, canonical value domains and value aliases, and safety/scope
+classification. Command usage placeholders, command and shared flag help,
+output-format validation, search origin/result-kind validation, and every shell
+completion renderer consume those shared definitions. Dedicated or nested
+parsers retain exact usage-specific syntax until their subcommand metadata is
+complete. Add or change CLI options and accepted values in the schema first;
+do not add parallel help, validation, or completion value lists. This keeps
+runtime validation, help, completion, and generated next-step flags aligned
+without emitting partial option lists. Every verb
 listed by `CliCommandCatalog.CommandSubcommands` must also resolve to a hidden,
 verb-specific `ConsoleUi` usage entry with its constraints, side effects, and
 an example; aggregate usage lines must enumerate accepted public flags.
@@ -3422,12 +3425,15 @@ git status --short -- '**/packages.lock.json'
 
 command と nested subcommand の名前、および nested verb が optional で親 command の
 flag も維持するかは `CliCommandCatalog`、primary flag、alias、
-placeholder、description、command applicability は `CliFlagSchema` が管理します。
-全 shell completion renderer はこの共有定義を参照し、共有 parser が option 一覧の
-正本である場合は `ConsoleUi.PrintCommandUsage` も参照します。専用 parser / nested parser
-は subcommand metadata が揃うまで usage 固有の正確な構文を維持します。新しい CLI
-metadata はまず共有定義へ追加し、不完全な option 一覧を出さずに parser validation、
-help、completion、生成される next-step flag の同期を維持してください。
+placeholder、description、command applicability、canonical value domain と value alias、
+safety / scope 分類は `CliFlagSchema` が管理します。command usage の placeholder、
+command / shared flag help、output-format validation、search の origin / result-kind
+validation、全 shell completion renderer はこの共有定義を参照します。専用 parser /
+nested parser は subcommand metadata が揃うまで usage 固有の正確な構文を維持します。
+CLI option や受理値を追加・変更するときは、まず schema を更新し、help、validation、
+completion に並行した value list を追加しないでください。これにより、不完全な option
+一覧を出さずに runtime validation、help、completion、生成される next-step flag の同期を
+維持します。
 `CliCommandCatalog.CommandSubcommands` に掲載するすべての verb は、制約、副作用、例を
 記載した hidden な verb 固有 `ConsoleUi` usage entry に解決させ、aggregate usage line
 には受理する公開 flag を漏れなく列挙してください。

TESTING_GUIDE.md

@@ -181,7 +181,7 @@ Use `docs/test-doc-maintenance-plan.md` before moving oversized suites or adding
 - `IndexCommandRunner*Tests.cs`, `QueryCommandRunner*Tests.cs`, `ProgramCliTests.cs`, `InstallScriptTests.cs`
   CLI parsing, command execution, and installer behavior. Index command coverage is split by run mode or feature area, and query command coverage is split by command family with partial test classes so shared console and fixture helpers stay centralized. Keep repeated query-result fixtures, such as overlapping chunk content used by multiple search deduplication tests, in narrow class-level helpers instead of duplicating local builders. `ProgramCliTests.cs` covers top-level entrypoint behavior that must be exercised through a subprocess, while `InstallScriptTests.cs` runs focused bash snippets against `install.sh` in library mode to lock in release-installer regressions without performing real network installs. Installer bundle-generation tests must also verify that `install.sh` is marked generated while every canonical `install_modules/` source remains unmarked.
   C# `unused` partial-family coverage must reuse one multi-file fixture across regular JSON, compact, `--by-bucket`, and `--actionable`; include top-level and nested partial types, genuinely unused private members, an unrelated same-named family, a containing-type generic-arity collision, and a family-external occurrence in a matched peer file so semantic membership cannot regress into name-only, flattened-qualified-name, or whole-file evidence sharing.
-  `ConsoleUiTests.cs` keeps each generated shell's complete long-flag catalog aligned with `CliFlagSchema` and checks every Fish command scope against the shared per-command completion projection. Add flags to the schema rather than weakening this Bash / Zsh / Fish / PowerShell parity contract.
+  `CliFlagSchemaTests.cs` and `ConsoleUiTests.cs` keep command help, runtime value validation, and each generated shell's option/value catalog aligned with `CliFlagSchema`, and check every Fish command scope against the shared per-command completion projection. When an accepted value or alias changes, assert its registry normalization plus command usage, runtime validation, and Bash / Zsh / Fish / PowerShell completion visibility; add the value to the schema instead of weakening this parity contract.
   `ProgramRunnerTests.cs` enumerates `CliCommandCatalog.CommandSubcommands` and requires every valid nested verb to resolve to verb-specific usage with an example. It also pins destructive index confirmation and aggregate dependency-filter help, plus the read-only GitHub duplicate-preflight boundary for suggestion exports. Installer cancellation coverage must wait until the PID file contains a complete positive integer before cancelling, using a bounded dedicated waiter instead of a fixed-delay timer so parallel load cannot expose a redirection-created empty file.
   Global-tool-log home-shorthand coverage resolves the normalized first candidate through the test-only no-write-probe seam, so sandbox permissions cannot turn an expansion assertion into a writability-fallback assertion.
   Grouped-search limit coverage must seed more matches and files than the returned page, then assert query-wide matched/group/file totals separately from grouped, emitted, and omitted row counts so a bounded page cannot report itself as complete.
@@ -1097,7 +1097,7 @@ dotnet test --filter "FullyQualifiedName~GitHelperTests"
 - `IndexCommandRunner*Tests.cs`、`QueryCommandRunner*Tests.cs`、`ProgramCliTests.cs`、`InstallScriptTests.cs`
   CLI の引数解析、コマンド実行、installer 挙動のテスト。Index command coverage は run mode または機能領域ごとの partial suite に分割し、Query command coverage は command family ごとの partial test class に分割して、共有 console / fixture helper は一箇所に保ちます。`ProgramCliTests.cs` はグローバル引数の解釈や完全な CLI 起動フローのように subprocess 経由で確認すべき Program エントリポイント挙動を扱い、`InstallScriptTests.cs` は `install.sh` を library mode で source した bash snippet を実行して、実ネットワーク install を行わずに release installer の回帰を固定する。installer bundle 生成テストでは、`install.sh` が generated と判定される一方、canonical な `install_modules/` source はすべて unmarked のままであることも検証してください。
   C# `unused` の partial-family coverage では、通常の JSON、compact、`--by-bucket`、`--actionable` で1つの multi-file fixture を共有してください。top-level / nested partial type、本当に未使用の private member、無関係な同名 family、containing type の generic-arity collision、matched peer file 内の family 外 occurrence を含め、semantic membership が name-only、平坦化された qualified name、または file 全体の evidence 共有へ戻らないことを固定します。
-  `ConsoleUiTests.cs` は各生成シェルの long flag 全カタログを `CliFlagSchema` と同期させ、Fish の全 command scope を共有の command 別 completion 射影と照合します。この Bash / Zsh / Fish / PowerShell parity 契約を弱めず、新しい flag は schema に追加してください。
+  `CliFlagSchemaTests.cs` と `ConsoleUiTests.cs` は command help、runtime value validation、各生成 shell の option / value 全カタログを `CliFlagSchema` と同期させ、Fish の全 command scope を共有の command 別 completion 射影と照合します。受理値または alias を変更するときは、registry normalization に加えて command usage、runtime validation、Bash / Zsh / Fish / PowerShell completion への露出を検証し、この parity 契約を弱めず schema に値を追加してください。
   `ProgramRunnerTests.cs` は `CliCommandCatalog.CommandSubcommands` を列挙し、すべての有効な nested verb が例を含む verb 固有 usage に解決されることを必須とします。さらに destructive な index confirmation、aggregate dependency filter help、suggestion export の read-only GitHub duplicate-preflight 境界を固定します。installer cancellation coverage は固定時間タイマーではなく上限付きの専用 waiter を使い、PID ファイルが完全な正の整数を含むまで待ってから cancel してください。これにより並列負荷下でも redirection によって作成された空ファイルを読みません。
   global tool log の home shorthand coverage は、test 専用の write probe なし seam から正規化済みの先頭 candidate を解決します。これにより sandbox permission の影響で、展開の assertion が writability fallback の assertion に変わることを防ぎます。
   grouped search の limit coverage では、返却 page より多い match と file を seed し、query 全体の match/group/file 総数と grouped、emitted、omitted row 数を別々に検証して、上限付き page が完了済みと報告できないようにしてください。

USER_GUIDE.md

@@ -177,6 +177,10 @@ The generated scripts complete subcommands, flags, and common flag values.
 `--lang` suggests supported languages, `--kind` suggests symbol/reference kinds,
 and path-like options such as `--db`, `--path`, and `--output` use shell file
 completion.
+Command-specific `--format` values, search origin filters, and `--result-kind`
+values come from the same registry as command help and runtime validation. For
+example, audit completion includes `sarif`, and search completion includes
+`schema_description` and `unknown`.
 
 Install the script in the startup file or completion directory for your shell:
 
@@ -303,7 +307,9 @@ the same filtered file set.
 
 Stable since values are intentionally not repeated in this guide because the
 release changelog is the source of truth for when each command first shipped.
-Run `cdidx --help` for the full syntax line for every command. For focused help,
+Run `cdidx --help-all` for the full syntax line for every command and
+`cdidx --help-flags` for global, safety/scope, index/update, and shared query
+options. For focused help,
 `cdidx help <command> [subcommand]` is equivalent to the existing
 `cdidx <command> [subcommand] --help` form and never executes that command.
 Known public command targets and supported command or nested aliases exit `0`;
@@ -3441,6 +3447,9 @@ read-write で mount してください。read-only query container では、fre
 生成されたスクリプトは subcommand、flag、よく使う flag 値を補完します。
 `--lang` は対応言語、`--kind` は symbol / reference kind を提示し、`--db`、
 `--path`、`--output` など path 系 option は shell の file completion を使います。
+command 固有の `--format` 値、search origin filter、`--result-kind` 値は command
+help と runtime validation と同じ registry から生成されます。たとえば audit の補完には
+`sarif`、search の補完には `schema_description` と `unknown` が含まれます。
 
 利用中の shell の startup file または completion directory にスクリプトを
 インストールしてください。
@@ -3555,8 +3564,10 @@ cdidx index . --quiet
 filter 済み file 集合を表します。
 
 Stable since の値はこのガイドでは重複管理しません。各コマンドがいつ入ったかは
-release changelog を source of truth とします。完全な syntax line は `cdidx --help`
-を参照してください。個別の help は `cdidx help <command> [subcommand]` を使え、既存の
+release changelog を source of truth とします。全 command の完全な syntax line は
+`cdidx --help-all`、global、safety / scope、index / update、共有 query option は
+`cdidx --help-flags` を参照してください。個別の help は
+`cdidx help <command> [subcommand]` を使え、既存の
 `cdidx <command> [subcommand] --help` と同じ内容を command を実行せずに表示します。
 既知の公開 command target と対応する command / nested alias は終了コード `0` を返し、
 内部 usage key は help target として受理しません。target の欠落・未検出は bounded な
@@ -4292,6 +4303,9 @@ Bash、Zsh、Fish、PowerShell です。生成されたスクリプトは subcom
 よく使う flag value を補完し、`--lang` は対応言語、`--kind` は symbol/reference
 kind、`--db` / `--path` / `--output` のような path 系 option は shell の file
 completion を使います。
+command 固有の `--format` 値、search origin filter、`--result-kind` 値は command
+help と runtime validation と同じ registry から生成されます。たとえば audit の補完には
+`sarif`、search の補完には `schema_description` と `unknown` が含まれます。
 
 使っている shell の startup file または completion directory に保存してください:
 

changelog.d/unreleased/4861.fixed.md

@@ -0,0 +1,20 @@
+---
+category: fixed
+issues:
+  - 4861
+affected:
+  - src/CodeIndex/Cli/CliFlagSchema.cs
+  - src/CodeIndex/Cli/ConsoleCompletionRenderer.cs
+  - tests/CodeIndex.Tests/CliFlagSchemaTests.cs
+  - USER_GUIDE.md
+---
+
+## English
+
+- Generate command-specific accepted option values from the CLI flag registry across usage/help, output-format and search projection validation, and Bash, Zsh, Fish, and PowerShell completions.
+- Surface audit SARIF, all search origin and result-kind values, hook-install dry-run, and global safety/scope flags, and stop advertising the rejected `goto --exact` option.
+
+## 日本語
+
+- command 固有の受理 option 値を CLI flag registry から生成し、usage / help、output-format と search projection の validation、Bash / Zsh / Fish / PowerShell completion を同期しました。
+- audit の SARIF、search の全 origin / result-kind 値、hook install の dry-run、global safety / scope flag を表示し、拒否される `goto --exact` の案内を削除しました。