Explain every serialized status section

AGENT_GUIDE.md

@@ -138,6 +138,7 @@ CI watching must be bounded. Do not loop indefinitely.
 - `status --json` and related JSON/MCP payloads currently expose the trust fields documented in `README.md` and `DEVELOPER_GUIDE.md`, including `fold_ready`, `fold_ready_reason`, `graph_table_available`, `graph_data_current`, `index_complete`, `index_incomplete_reasons`, `issues_table_available`, `file_issues_data_current`, `migration_in_progress`, `sql_graph_contract_ready`, `sql_graph_contract_degraded_reason`, `hotspot_family_ready`, `hotspot_family_degraded_reason`, `language_readiness`, `csharp_symbol_name_ready`, `csharp_metadata_target_ready`, `csharp_metadata_target_degraded_reason`, `indexed_head_commit`, `worktree_head_changed`, `indexed_head_sha`, `indexed_head_branch`, `indexed_head_timestamp`, `commits_ahead_of_indexed_head`, `head_freshness`, `index_writer_version`, `index_newer_than_reader`, `index_newer_than_reader_reason`, `unknown_extension_file_count`, `unknown_extension_files`, `unknown_extension_files_truncated`, `unknown_extension_file_path_limit`, `unknown_extension_extension_counts`, `unknown_extension_category_counts`, `unknown_extension_groups`, `extractors`, `git_executable`, `path_case_sensitive`, `data_dir`, `data_dir_source`, `data_dir_mode`, `db_file_mode`, `database_permission_policy`, `database_permission_diagnostics`, `mac_profile`, `mac_profile_diagnostics`, `db_size_bytes`, `wal_size_bytes`, `db_pragma_settings` (`journal_mode`, `synchronous`, `wal_autocheckpoint`, `busy_timeout_ms`, `page_count`, `freelist_count`, `page_size`, `auto_vacuum`), `prepared_command_cache` (`count`, `capacity`, `hit_count`, `miss_count`, `eviction_count`), `maintenance_guidance`, WAL checkpoint diagnostics (`read_only_fallback`, `wal_checkpoint_attempted`, `wal_checkpoint_succeeded`, `wal_checkpoint_skipped_reason`, `wal_checkpoint_failure_reason`, `wal_checkpoint_busy`, `wal_checkpoint_log_page_count`, `wal_checkpoint_checkpointed_page_count`, `wal_checkpoint_remaining_page_count`, `read_only_immutable_fallback`, `wal_stale_snapshot_risk`, `wal_stale_snapshot_reason`), `symbol_kinds`, `symbols_by_language`, status kind cap metadata (`symbol_kind_limit`, `symbol_kind_name_limit`, `symbol_kind_total_count`, `symbol_kind_omitted_count`, `symbol_kind_names_truncated`, `symbols_by_language_kind_total_counts`, `symbols_by_language_kind_omitted_counts`, `symbols_by_language_kind_names_truncated`), `process`, `last_index_run`, `last_failed_or_partial_index_run`, `last_failed_or_partial_index_run.progress_persisted`, `last_failed_or_partial_index_run.recovery_hint`, `last_failed_or_partial_index_run.file_errors`, `last_workspace_freshened_at`, `hooks`, `hook_diagnostics`, `trust_overrides`, MCP-only `mcp_session`, `mcp.rate_limit.bucket_limit`, `mcp.rate_limit.bucket_limit_rejection_count`, and the `status --check`-only `stale_after_seconds` / `index_age_seconds` threshold audit fields and `repair_commands`.
 - `maintenance_guidance.fts_optimization` is the shared, read-only recommendation contract for status, explain, optimize preview, and optimize execution. Keep `recommended`, `action`, `reason`, `threshold_writes`, `observed_writes`, and `state` synchronized; stale or unavailable snapshots must not recommend mutation.
 - A valid CLI `status --stale-after <duration>` implies the workspace check. Check-mode JSON includes `query_context.check_mode` (`explicit` or `implied_by_stale_after`) and `query_context.stale_after_seconds`; ordinary status JSON omits `query_context`.
+- `status --explain` derives accepted top-level keys from the same source-generated `StatusResult` serializer metadata as `status --json`, excludes ignored properties, and supports bounded dot-separated member paths without reading runtime values. Major readiness, trust, extension, maintenance, and cap-hit sections return structured meaning, source, dependencies, interpretation, and repair guidance; unknown input is sanitized and returns bounded valid candidates. Bounded status explain envelopes also omit database paths, timings, indexed HEADs, and stable-at timestamps.
 - `database_size_attribution` is part of the synchronized status contract. Preserve its read-only main/WAL/SHM separation; exact logical reconciliation across object, freelist, and unexplained-residual bytes; table/index and page-type subtotals; 20-object/128-character sanitized bounds; and explicit `available=false` / stable `unavailable_reason` behavior without zero-valued unavailable object metrics.
 - Explicit WAL truncate-checkpoint diagnostics must preserve SQLite's `(busy, log, checkpointed)` result, treat non-zero `busy` or positive remaining pages as unsuccessful with bounded machine reasons, accept `(0, -1, -1)` as the successful non-WAL no-op, and never expose raw exception text or paths.
 - When any readiness field is degraded, the CLI adds `degraded_root_cause`, `degraded_reason`, `recommended_action`, `alternative_action`, and `readiness_degradations[]`. `degraded_root_cause` is the primary stable machine code; `readiness_degradations[]` lists every degraded field with `root_cause`, human reason, and remediation strings.

DEVELOPER_GUIDE.md

@@ -1756,6 +1756,21 @@ access.
 | MCP-only session diagnostics | `mcp_session`, `mcp_session.metrics`, `mcp_session.audit_log`, `mcp.rate_limit.bucket_limit`, and `mcp.rate_limit.bucket_limit_rejection_count`. `mcp_session` is session-scoped diagnostics rather than persisted DB state. It contains `log_level`, bounded `roots`, optional `client_info`, bounded optional `client_capabilities`, an always-present `metrics` object, and `audit_log` when audit emission is enabled. When advertised roots are capped, `roots_truncated`, `root_count`, `root_limit`, and `root_uri_length_limit` describe the truncation. When client capabilities are capped, `client_capabilities_truncated`, `client_capabilities_truncation_reason`, `client_capabilities_serialized_bytes`, `client_capabilities_byte_limit`, and `client_capabilities_depth_limit` describe the retained diagnostic subset. `mcp_session.metrics` is `{"enabled":false}` when unconfigured. An enabled metrics sink contains `enabled`, `path`, `max_bytes`, `bytes_written`, `disposed`, `degraded`, `queue_capacity`, `queue_depth`, `queued_event_count`, `written_event_count`, `dropped_event_count`, `queue_full_drop_count`, `serialization_failure_count`, `write_failure_count`, `rotation_failure_count`, `batch_flush_count`, `consecutive_failure_count`, and `recovery_count`, plus optional `next_retry_at`, `last_recovery_at`, and `last_failure`. MCP ping always mirrors the metrics object as `metrics`; metrics degradation is intentionally excluded from its top-level liveness result. The audit status fields and their health semantics are defined in [MCP audit log emission](#mcp-audit-log-emission). `mcp.rate_limit.bucket_limit` is the configured process-local cap across normalized `(partition, caller)` buckets: every direct call uses one fixed caller-wide coarse partition, canonical known tools additionally use secondary per-tool partitions, and unknown `batch_query` slots share one fixed invalid-slot partition per caller. `mcp.rate_limit.bucket_limit_rejection_count` counts calls denied because creating a new bucket would exceed that cap. |
 | Documentation sync | Keep this list synchronized with `README.md` and `AGENT_GUIDE.md`; `DocumentationStatusContractTests` fails when any required field is missing from one of those docs. |
 
+`status --explain` resolves top-level keys through the source-generated
+`StatusResult` `JsonTypeInfo` used by `status --json`; ignored properties are
+excluded, and a coverage test requires every serialized top-level property to
+produce an explanation. Explicit registry metadata supplies useful meaning,
+source, dependencies, interpretation, and repair guidance for major readiness,
+trust, extension, maintenance, and cap-hit sections. Other serialized scalar
+fields receive a bounded contract explanation instead of becoming unknown as
+the DTO evolves. Dotted paths resolve against the same source-generated nested
+metadata (including collection element DTOs), while unknown paths receive
+bounded valid candidates. Explain responses contain static contract metadata
+only, cap known fields and dependencies, sanitize unknown input, and never
+include runtime field values or paths. Bounded `--fields` /
+`--max-json-bytes` envelopes also omit database paths, timings, indexed HEADs,
+and stable-at timestamps.
+
 `head_freshness` is a compact summary for machine consumers. `state=fresh`
 requires a successful complete `status --check` workspace comparison,
 `state=fresh_but_incomplete` separates matching-workspace freshness from failed-file coverage, and `state=head_current`
@@ -5169,6 +5184,19 @@ help はすべてこのレジストリを参照します。field 名は大文字
 | MCP-only session diagnostics | `mcp_session`、`mcp_session.metrics`、`mcp_session.audit_log`、`mcp.rate_limit.bucket_limit`、`mcp.rate_limit.bucket_limit_rejection_count`。`mcp_session` は persisted DB state ではなく session-scoped diagnostics で、`log_level`、上限付きの `roots`、任意の `client_info`、上限付きの任意の `client_capabilities`、常設の `metrics` object、audit 出力が有効な場合の `audit_log` を含みます。advertised root が切り詰められた場合は `roots_truncated`、`root_count`、`root_limit`、`root_uri_length_limit` が切り詰め内容を示します。client capabilities が切り詰められた場合は `client_capabilities_truncated`、`client_capabilities_truncation_reason`、`client_capabilities_serialized_bytes`、`client_capabilities_byte_limit`、`client_capabilities_depth_limit` が保持された診断 subset を示します。未設定時の `mcp_session.metrics` は `{"enabled":false}` です。有効な metrics sink は `enabled`、`path`、`max_bytes`、`bytes_written`、`disposed`、`degraded`、`queue_capacity`、`queue_depth`、`queued_event_count`、`written_event_count`、`dropped_event_count`、`queue_full_drop_count`、`serialization_failure_count`、`write_failure_count`、`rotation_failure_count`、`batch_flush_count`、`consecutive_failure_count`、`recovery_count` に加え、任意の `next_retry_at`、`last_recovery_at`、`last_failure` を追加します。MCP ping は常に metrics object を `metrics` として返し、metrics の degradation は意図的に top-level liveness result へ反映しません。audit status field と health semantics は [MCP 監査ログの出力](#mcp-監査ログの出力) に定義します。`mcp.rate_limit.bucket_limit` は normalized な `(partition, caller)` bucket 全体に対する process-local 上限で、direct call はすべて caller-wide の固定 coarse partition、canonical な既知 tool は追加の secondary per-tool partition、unknown な `batch_query` slot は caller ごとの 1 つの固定 invalid-slot partition を使います。`mcp.rate_limit.bucket_limit_rejection_count` は新規 bucket 作成がその上限を超えるため拒否された呼び出し数です。 |
 | documentation sync | この一覧は `README.md` と `AGENT_GUIDE.md` と同期してください。必須 field がそれらの docs から欠けると `DocumentationStatusContractTests` が失敗します。 |
 
+`status --explain` の top-level key は `status --json` と同じ source-generated
+`StatusResult` `JsonTypeInfo` で解決します。ignored property は除外し、coverage test で
+serialized top-level property がすべて説明を返すことを固定します。主要な readiness、
+trust、extension、maintenance、cap-hit section には、明示的な registry metadata として
+meaning、source、dependencies、interpretation、repair guidance を付けます。それ以外の
+serialized scalar field も、DTO 拡張時に unknown へ戻らず上限付き contract explanation を返します。
+dot 区切り path は collection element DTO を含む同じ source-generated nested metadata で解決し、
+unknown path には上限付きの有効な candidate を返します。explain response は static contract
+metadata だけを含み、known field と dependency の件数を制限し、unknown input を sanitize し、
+runtime field value や path を含めません。bounded `--fields` /
+`--max-json-bytes` envelope も database path、timing、indexed HEAD、
+stable-at timestamp を省略します。
+
 `head_freshness` は machine consumer 向けの compact summary です。
 `state=fresh` は complete な index に対する `status --check` の workspace 比較成功が必要で、
 `state=fresh_but_incomplete` は workspace freshness と failed-file coverage を分離し、

README.md

@@ -238,7 +238,17 @@ fields, including readiness fields and runtime diagnostics such as
 `path_case_sensitive`. `cdidx status --explain sqlite_connection_policy`
 describes the active SQLite open mode, immutable-URI choice, timeout,
 cancellation, and WAL snapshot-risk diagnostics.
-`cdidx status --explain maintenance_guidance` describes the shared FTS
+Accepted top-level explain keys come from the same source-generated
+`StatusResult` serializer registry as `status --json`, so every serialized
+top-level field remains explainable as the response evolves. Major composite
+sections such as `trust_overrides`, `extractors`, `hooks`,
+`maintenance_guidance`, and `reference_extraction_cap_hits` add structured
+meaning, source, dependencies, interpretation, and repair guidance. Dotted
+member paths such as `maintenance_guidance.recommended_command` are also
+accepted; explain output is bounded contract metadata and never includes live
+runtime values or paths. Bounded `--fields` / `--max-json-bytes` envelopes also
+omit database paths, timings, indexed HEADs, and stable-at timestamps.
+`cdidx status --explain maintenance_guidance` also describes the shared FTS
 optimization recommendation used by status and optimize.
 
 | Field group | Fields |
@@ -691,7 +701,16 @@ visible な status field の簡潔な説明は `cdidx status --explain <field>`
 readiness field に加えて、`path_case_sensitive` などの runtime diagnostic field も対象です。
 `cdidx status --explain sqlite_connection_policy` は、有効な SQLite open mode、
 immutable URI の選択、timeout、cancellation、WAL snapshot risk の diagnostic を説明します。
-`cdidx status --explain maintenance_guidance` は、status と optimize が共有する
+top-level の explain key は `status --json` と同じ source-generated
+`StatusResult` serializer registry から生成されるため、response が拡張されても serialized
+top-level field はすべて説明可能な状態を維持します。`trust_overrides`、`extractors`、
+`hooks`、`maintenance_guidance`、`reference_extraction_cap_hits` などの主要な composite
+section は、meaning、source、dependencies、interpretation、repair guidance を構造化して返します。
+`maintenance_guidance.recommended_command` のような dot 区切り member path も受理します。
+explain output は上限付きの contract metadata だけで、live runtime value や path は含みません。
+bounded `--fields` / `--max-json-bytes` envelope も database path、timing、
+indexed HEAD、stable-at timestamp を省略します。
+`cdidx status --explain maintenance_guidance` はさらに、status と optimize が共有する
 FTS optimization recommendation を説明します。
 
 | field group | fields |