Preserve status explain payloads in compact JSON

AGENT_GUIDE.md

@@ -149,7 +149,7 @@ CI watching must be bounded. Do not loop indefinitely.
 - A successful CLI or MCP `index --rebuild` evaluates the shared freelist warning threshold after the index transaction commits. Incremental-auto-vacuum databases may run bounded `PRAGMA incremental_vacuum`; legacy databases must skip automatic reclaim instead of running a full `VACUUM`. Preserve the immediate index-result and persisted `last_index_run.rebuild_reclaim` telemetry, stable states/reasons, before/after ratios and byte/page counts, and the rule that reclaim failure never reclassifies an already committed index run as failed.
 - 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`.
 - Every bounded `workspace_check` path list (`changed_files`, `missing_files`, `outside_sparse_cone_files`, `unindexed_files`, `unverifiable_files`, and `scan_errors`) carries an authoritative count plus matching `*_truncated`, `*_path_limit`, and `*_omitted_count` fields. List-only `--fields` projections must retain those signals automatically; compact output retains the signals without path arrays; and `--max-json-bytes` may remove only trailing paths while updating both the per-list omitted count and the envelope byte-limit signal. Human check diagnostics must label each displayed list as a sample or complete.
-- `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.
+- `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. Regular JSON preserves the full typed explanation. `--compact`, `--format compact`, and byte-bounded output without explicit `--fields` project it to the required `api_version`, `field`, `meaning`, `interpretation`, and `remediation` fields before applying the global byte limit; envelope metadata identifies the compact explanation schema and accounts for omitted optional fields by name and count. If the envelope plus one compact explanation cannot fit, return `E028_RESPONSE_BUDGET_TOO_SMALL` with measured minimum-size and retry guidance instead of an empty success. 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

@@ -2220,9 +2220,19 @@ 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.
+include runtime field values or paths. Regular JSON retains that full payload.
+`--compact`, `--format compact`, and bounded output without explicit `--fields`
+project the typed explanation to `api_version`, `field`, `meaning`,
+`interpretation`, and `remediation` before applying the global byte bound. The
+envelope sets `explanation_schema=compact`, publishes
+`explanation_required_fields`, and accounts for removed optional content with
+`explanation_omitted_optional_field_count` and
+`explanation_omitted_optional_fields`. Explicit `--fields` remains an
+operator-selected projection. If the complete envelope plus one compact
+explanation cannot fit, the command returns `E028_RESPONSE_BUDGET_TOO_SMALL`
+with measured minimum-size and retry guidance instead of an empty success.
+Bounded 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,
@@ -6095,9 +6105,16 @@ serialized scalar field も、DTO 拡張時に unknown へ戻らず上限付き
 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 を省略します。
+runtime field value や path を含めません。通常の JSON はこの完全な payload を維持します。
+`--compact`、`--format compact`、および明示的な `--fields` を伴わない bounded output は、
+typed explanation を `api_version`、`field`、`meaning`、`interpretation`、
+`remediation` へ投影してから global byte 上限を適用します。envelope は
+`explanation_schema=compact` と `explanation_required_fields` を返し、省略した任意内容を
+`explanation_omitted_optional_field_count` と `explanation_omitted_optional_fields` で
+集計します。明示的な `--fields` は operator が選択した投影のままです。完全な envelope と
+compact explanation 1件を収められない場合、空の成功ではなく、計測済み必要最小 size と
+retry guidance を含む `E028_RESPONSE_BUDGET_TOO_SMALL` を返します。bounded envelope は
+database path、timing、indexed HEAD、stable-at timestamp も省略します。
 
 `head_freshness` は machine consumer 向けの compact summary です。
 `state=fresh` は complete な index に対する `status --check` の workspace 比較成功が必要で、

README.md

@@ -182,6 +182,12 @@ Use `cdidx status --explain <field>` for bounded field guidance. Detailed
 semantics, repair-action structure, readiness degradation, SQLite/WAL handling,
 and MCP diagnostics live in the [Developer Guide](DEVELOPER_GUIDE.md#ai-integration);
 the everyday status workflow is in [Check status](USER_GUIDE.md#check-status).
+Regular JSON keeps the full explanation. `--compact`, `--format compact`, and a
+byte-bounded explanation without explicit `--fields` use the minimum compact
+schema `api_version`, `field`, `meaning`, `interpretation`, and `remediation`.
+Envelope metadata reports that schema plus the names and count of omitted
+optional fields; a budget too small for the envelope and one compact row returns
+an explicit response-budget error with minimum-size and retry guidance.
 Selecting one of these lists through `--fields` also retains its count and
 truncation signals. Compact output keeps the signals without the paths, and a
 JSON byte budget may shorten a path sample while increasing its omitted count.
@@ -387,6 +393,12 @@ field group を表に残します。
 repair action、readiness degradation、SQLite/WAL、MCP diagnostic の詳細は
 [開発者ガイド](DEVELOPER_GUIDE.md#ai連携)、日常的な使い方は
 [クイックスタート](USER_GUIDE.md#クイックスタート)を参照してください。
+通常の JSON は完全な説明を維持します。`--compact`、`--format compact`、および
+明示的な `--fields` を伴わない byte 上限付き説明は、`api_version`、`field`、
+`meaning`、`interpretation`、`remediation` の最小 compact schema を使います。
+envelope metadata は schema と省略した任意 field の名前・件数を返し、envelope と
+compact row 1件を収められない上限では、必要最小 size と retry guidance を含む
+明示的な response-budget error を返します。
 これらの一覧を `--fields` で選択した場合も count と truncation signal は残ります。
 compact 出力は path を省いて signal を維持し、JSON byte budget で path sample が
 さらに短縮された場合は omitted count が増加します。

TESTING_GUIDE.md

@@ -780,6 +780,8 @@ Candidate-ordered parallel-index recovery tests must prove that the fatal result
   End-to-end regression coverage for automatic verified backups before import replacement, managed backup list/restore by ID, mutation-free dry runs, rollback after an injected post-move failure, corrupt payload and insufficient-space rejection, older supported schema stamps, corrupt import archives, and Windows exclusive-lock behavior. The fixture uses the SQLite-pool-sensitive collection because it resets process-wide free-space and replacement hooks in `finally`.
 - `JsonOutputSnapshotTests.cs`, `JsonOutputSnapshotHelper.cs`
   Golden-file regression fixtures for the CLI `--json` output contracts (issue #1548). Each test runs one command (`status`, `search`, `references`, `impact`, `excerpt`) against a deterministic in-memory fixture, normalizes volatile fields (timestamps, absolute paths, commit SHAs, FTS5 scores, SQLite page counts), and diffs against the matching file under `tests/CodeIndex.Tests/golden/`. Renames, removals, reordered arrays, or new keys fail the snapshot so the contract change is forced to land alongside an intentional golden update. See "JSON `--json` output snapshots" below for the update procedure.
+- `ProjectionFieldRegistryIssue4836Tests.cs`
+  Bounded CLI projection-registry coverage, including the status-explanation contract. Keep the issue-5093 matrix together: full JSON, explicit and generated explanations, label aliases, `--compact` / `--format compact` parity, a comfortably fitting byte bound, an explicit too-small-budget recovery response, text output, and unknown-key errors. Compact successes must retain the five required explanation fields and account for every omitted optional top-level field in envelope metadata.
 - `QueryCommandRunnerBatchDbTests.cs`
   Batch database-context coverage in `QueryCommandRunnerBatchDbTests.cs` uses repositories and databases with distinct paths, file counts, commits, and runtime HEADs. Keep parent-only inheritance, child-explicit override (including after a `-- <query>` pass-through), parent/child/parent isolation, implicit-default path resolution, leading-dash database paths, dangling value-option error preservation, and text / regular JSON / compact JSON / JSON-summary assertions together so every available database, project-root, Git-provenance, and freshness field describes the selected database.
 - `QueryCommandRunnerBatchIssue4723Tests.cs`
@@ -1859,6 +1861,8 @@ dotnet test --filter "FullyQualifiedName~GitHelperTests"
   import の置換前に作成する自動検証済み backup、managed backup の list / ID 指定 restore、変更を伴わない dry-run、post-move failure 注入後の rollback、破損 payload と容量不足の拒否、対応する旧 schema stamp、破損 import archive、Windows の exclusive lock を end-to-end で検証します。process-wide の free-space hook と replacement hook を `finally` で戻すため、SQLite-pool-sensitive collection を使用します。
 - `JsonOutputSnapshotTests.cs`、`JsonOutputSnapshotHelper.cs`
   CLI の `--json` 出力契約に対するゴールデンファイル回帰フィクスチャ (issue #1548)。各テストは `status` / `search` / `references` / `impact` / `excerpt` を決定的なインメモリ fixture に対して実行し、揺らぐフィールド（timestamp、絶対パス、commit SHA、FTS5 score、SQLite page count など）を正規化したうえで `tests/CodeIndex.Tests/golden/` 配下のファイルと差分比較します。フィールドの rename / 削除 / 並び替え / 新規追加が起きると snapshot が失敗するため、契約変更は意図的な golden 更新と同じ PR で揃えざるを得ません。更新手順は下記「JSON `--json` 出力 snapshot」を参照してください。
+- `ProjectionFieldRegistryIssue4836Tests.cs`
+  status explanation 契約を含む、上限付き CLI projection registry の coverage です。Issue #5093 の matrix として、完全な JSON、明示定義・自動生成 explanation、label alias、`--compact` / `--format compact` parity、十分な byte 上限、明示的な上限不足 recovery response、text 出力、unknown key error を一緒に維持してください。compact success は必須の explanation field 5件を保持し、省略した任意 top-level field をすべて envelope metadata で集計する必要があります。
 - `QueryCommandRunnerBatchDbTests.cs`
   `QueryCommandRunnerBatchDbTests.cs` の batch database context coverage では、path、file count、commit、runtime HEAD が異なる repository / database を使います。利用可能な database、project-root、Git provenance、freshness の全 field が選択された database を記述するよう、親だけの継承、`-- <query>` pass-through 後を含む child 明示 override、parent / child / parent の isolation、暗黙 default の path resolution、先頭が dash の database path、値 option 欠落時の error 保持、text / regular JSON / compact JSON / JSON-summary assertion を一緒に維持してください。
 - `QueryCommandRunnerBatchIssue4723Tests.cs`

changelog.d/unreleased/5093.fixed.md

@@ -0,0 +1,20 @@
+---
+category: fixed
+issues:
+  - 5093
+affected:
+  - src/CodeIndex/Cli/JsonEnvelopeWrapper.Bounded.cs
+  - src/CodeIndex/Cli/ProjectionFieldRegistry.cs
+  - tests/CodeIndex.Tests/ProjectionFieldRegistryIssue4836Tests.cs
+  - README.md
+  - DEVELOPER_GUIDE.md
+  - TESTING_GUIDE.md
+---
+
+## English
+
+- **`status --explain` now preserves a useful payload in compact and byte-bounded JSON (#5093)** — compact explanations retain the field, meaning, interpretation, and remediation contract, bounded envelopes account for omitted optional fields, and undersized budgets return explicit minimum-size and retry guidance instead of an empty success.
+
+## 日本語
+
+- **`status --explain` が compact および byte 上限付き JSON でも有用な payload を維持するようになりました (#5093)** — compact explanation は field、meaning、interpretation、remediation の契約を保持し、bounded envelope は省略した任意 field を集計します。上限が小さすぎる場合は、空の成功ではなく必要最小 size と retry guidance を明示します。