Report persisted index completeness consistently

AGENT_GUIDE.md

@@ -142,6 +142,7 @@ CI watching must be bounded. Do not loop indefinitely.
 - `hotspot_family_degraded_reason` currently uses `hotspot_family_support_not_indexed`, `hotspot_family_metadata_stale`, `hotspot_family_disabled_at_index_time`, `partial_family_key_population`, and `hotspot_family_marker_fingerprint_incomplete`; the incomplete marker fingerprint code means marker traversal hit safety caps and should stay synchronized with README / developer-guide recovery notes.
 - `issues_table_available` reports physical `file_issues` table presence only. `file_issues_data_current` reports whether the table is also stamped current for the active index generation.
 - `graph_table_available` reports a queryable persisted reference generation, while `graph_data_current`, `reference_graph_complete`, and `index_complete` report current-generation coverage. Reference extraction is bounded at 50,000 lookup symbols, 20,000 lookup lines, 512 names per line, and 20,000 container candidates; `reference_extraction_limits`, `reference_graph_incomplete_reasons`, and `reference_extraction_cap_hits` publish cap state, and `last_index_run.reference_extraction_cap_hits` snapshots it per run. Cap hits persist per file and propagate degraded, non-authoritative absence semantics to callers, callees, deps, and impact. Indexed Crystal, Groovy, Tcl, Prolog, or `ambiguous_pl` rows with a missing or stale extractor stamp add `dynamic_reference_graph_contract_stale` to `reference_graph_incomplete_reasons` and keep graph readiness false until a normal index refresh rewrites them. A per-file extraction failure keeps successful graph rows queryable, stamps completeness false with bounded `last_failed_or_partial_index_run.file_errors`, and returns exit `11` unless `index --allow-partial` explicitly opts into exit `0`. While such file failures remain unresolved, a later scoped update automatically uses the normal incremental full-scan path so unrelated targets cannot clear the failure and successful recovery can restore every workspace-wide readiness contract without `--rebuild`.
+- Successful CLI full/update indexing, immediate status/workspace status, and MCP indexing/status must derive `index_complete`, `index_incomplete_reasons`, `reference_graph_complete`, and `reference_graph_incomplete_reasons` from the same persisted-readiness snapshot. Symbols-only runs and persisted file-size, symbol-count, reference-count, extractor-failure, or reference-cap evidence make the generation incomplete. Legacy databases keep the complete compatibility default only when persisted rows do not prove an omission.
 - `index_writer_version` records the `cdidx` version that last wrote to the DB (stamped into `codeindex_meta` as `cdidx_writer_version` on every full scan, update, and MCP index). `index_newer_than_reader` flips to `true` whenever any persisted numeric contract stamp in `codeindex_meta` (or unknown `PRAGMA user_version` readiness bits) exceeds the current binary's compiled maximum, so an older CLI re-opening a DB written by a newer CLI degrades loudly with an audit trail instead of silently dropping back to text-search fallbacks. `index_newer_than_reader_reason` enumerates the specific newer-than-reader stamps.
 - `status` also surfaces indexed-HEAD freshness via `indexed_head_sha`, `indexed_head_branch`, `indexed_head_timestamp`, `commits_ahead_of_indexed_head`, and the compact `head_freshness` summary. They are stamped by `cdidx index` on every successful run (full scan AND partial update, distinct from `indexed_head_commit` which is full-scan only) on a best-effort basis (never blocks an otherwise-successful index) and omitted on non-git workspaces, detached HEAD (branch only), or legacy DBs created before this contract. `worktree_head_changed` compares runtime HEAD with this latest stamp when available and falls back to `indexed_head_commit` only for legacy DBs. `head_freshness.state=fresh` requires `status --check` to match the workspace, `fresh_but_incomplete` keeps matching-workspace freshness distinct from incomplete extraction coverage, and `state=head_current` only means the runtime HEAD matches the `indexed_head` selected by `indexed_head_source`.
 - `status` also surfaces unknown-extension scan coverage via `unknown_extension_file_count`, stamped by successful full-repository index runs (`cdidx index <projectPath>` and MCP `index_project`) as the number of non-indexed files with non-empty extensions that do not map to a known language. Current scans also stamp `unknown_extension_files` as a path sample bounded by `unknown_extension_file_path_limit` items and the string-list decoded-character budget, `unknown_extension_files_truncated` when more paths existed than were emitted for either bound, and `unknown_extension_file_path_limit` as the item cap rather than a guarantee that that many paths are returned. Newer scans also expose `unknown_extension_extension_counts`, `unknown_extension_category_counts`, and `unknown_extension_groups`; groups classify common non-code buckets such as repository metadata, licenses, binary assets, configuration, structural metadata, and language-support candidates, and include `recommended_action` values of `ignore_configuration`, `first_class_structural_extraction`, or `language_support`. These fields are omitted on legacy DBs or before a current full scan has stamped them.

DEVELOPER_GUIDE.md

@@ -743,6 +743,17 @@ filters remain exact, so `--kind import` does not include local type declaration
 
 `status --json` emits structured readiness guidance whenever any trust field is degraded. The top-level `degraded_root_cause` is a stable machine-readable primary code, while `readiness_degradations[]` lists every degraded field with `root_cause`, human `degraded_reason`, `recommended_action`, and `alternative_action`. `migration_in_progress` is set from the active batch marker so clients can distinguish a temporary writer/migration window from a permanently degraded index. `issues_table_available` means the physical `file_issues` table exists; `file_issues_data_current` is the freshness/trust bit consumers should use before treating validate rows as authoritative.
 
+Index-generation completeness is computed by one persisted-readiness reader and
+reused by the successful full/update index response, immediate status and
+workspace status, and MCP indexing/status responses. Persisted omission evidence
+from symbols-only runs, `file_too_large`, `symbol_count_exceeded`,
+`reference_count_exceeded`, extractor failures, and reference safety caps makes
+`index_complete=false` with stable `index_incomplete_reasons`.
+`reference_graph_complete` additionally requires an available, current graph
+generation and repeats graph-specific stable reasons. A legacy database without
+the completeness metadata keeps the compatibility default unless its persisted
+rows prove that work was omitted.
+
 Reference extraction publishes its fixed safety limits through CLI
 `languages --json` / `status --json` and the corresponding MCP responses:
 50,000 lookup symbols, 20,000 lookup lines, 512 names per
@@ -801,7 +812,9 @@ Current stable codes and triggers:
 | `hotspot_family_marker_fingerprint_incomplete` | hotspot-family marker fingerprint traversal hit a safety cap, so family trust was not stamped authoritative | reduce generated/ignored marker trees or raise the cap in code, then run `cdidx index <projectPath> --rebuild` |
 | `partial_family_key_population` | hotspot-family metadata is stamped but some indexed symbols still have NULL `family_key` values | `cdidx index <projectPath> --rebuild` |
 | `graph_table_available=false` | `symbol_references` is missing or not graph-ready | `cdidx index <projectPath>` |
-| `reference_graph_complete=false` | a reference-extraction safety cap was reached, or legacy storage cannot report cap state | narrow/exclude the reported generated or pathological files, then run `cdidx index <projectPath>` |
+| `symbols_only_graph_omitted` | the last symbols-only generation intentionally omitted reference-graph rows | run `cdidx index <projectPath>` without `--symbols-only` |
+| `reference_graph_complete=false` | the graph generation is unavailable/stale, a symbols-only run omitted it, or persisted file/extractor/cap evidence makes the index generation incomplete | address the reported stable reasons, then run `cdidx index <projectPath>` |
+| `index_complete=false` | a symbols-only run or persisted file-size, symbol-count, reference-count, extractor-failure, or safety-cap evidence proves that indexing work was omitted | address `index_incomplete_reasons`, then run `cdidx index <projectPath>` |
 | `issues_table_available=false` | `file_issues` is missing or not issue-ready | `cdidx index <projectPath>` |
 | `csharp_symbol_name_ready=false` | C# canonical symbol-name stamps are stale | `cdidx index <projectPath>` |
 | `csharp_metadata_target_ready=false` | C# metadata-target stamps are stale | `cdidx index <projectPath>` |
@@ -3821,6 +3834,16 @@ filter、downstream JSON consumer が同じ値を理解できるようにして
 
 `status --json` は trust field のいずれかが degraded の場合に structured readiness guidance を出す。トップレベルの `degraded_root_cause` は primary の安定した machine-readable code で、`readiness_degradations[]` は degraded な各 field と `root_cause`、人間向け `degraded_reason`、`recommended_action`、`alternative_action` を列挙する。`migration_in_progress` は active batch marker から設定し、一時的な writer/migration window と恒久的な degraded index をクライアントが区別できるようにする。`issues_table_available` は物理的な `file_issues` table の存在を意味し、validate rows を authoritative として扱う前の freshness/trust bit は `file_issues_data_current` を使う。
 
+index generation の completeness は単一の persisted-readiness reader で計算し、
+成功した full/update index response、直後の status / workspace status、MCP の
+indexing/status response で再利用します。symbols-only run、`file_too_large`、
+`symbol_count_exceeded`、`reference_count_exceeded`、extractor failure、
+reference safety cap の永続化済み省略証拠がある場合は
+`index_complete=false` となり、安定した `index_incomplete_reasons` を返します。
+`reference_graph_complete` はさらに利用可能かつ current な graph generation を要求し、
+graph 固有の安定した理由を返します。completeness metadata を持たない legacy database は、
+永続化済み row が処理の省略を証明しない限り compatibility default を維持します。
+
 reference extraction の固定 safety limit は lookup symbol 50,000件、lookup line
 20,000行、1行あたりの name 512件、container candidate 20,000件で、CLI の
 `languages --json` / `status --json` と対応する MCP response に公開します。cap diagnostic は file ごとの `file_issues`
@@ -3898,7 +3921,9 @@ alternative action を同じ場所へ追加してください。
 | `hotspot_family_marker_fingerprint_incomplete` | hotspot-family marker fingerprint traversal が safety cap に到達し、family trust が authoritative に stamp されなかった | generated / ignored marker tree を減らすか code 側の cap を上げてから `cdidx index <projectPath> --rebuild` |
 | `partial_family_key_population` | hotspot-family metadata は stamp 済みだが、一部の indexed symbol で `family_key` が NULL | `cdidx index <projectPath> --rebuild` |
 | `graph_table_available=false` | `symbol_references` が無い、または graph-ready ではない | `cdidx index <projectPath>` |
-| `reference_graph_complete=false` | reference-extraction safety cap に到達した、または legacy storage で cap state を報告できない | 報告された generated / pathological file を絞り込むか除外してから `cdidx index <projectPath>` |
+| `symbols_only_graph_omitted` | 直前の symbols-only generation が reference-graph row を意図的に省略した | `--symbols-only` を付けずに `cdidx index <projectPath>` を実行 |
+| `reference_graph_complete=false` | graph generation が unavailable/stale、symbols-only run で省略、または永続化済み file/extractor/cap 証拠により index generation が incomplete | 報告された安定理由に対処してから `cdidx index <projectPath>` |
+| `index_complete=false` | symbols-only run、または永続化済みの file-size / symbol-count / reference-count / extractor-failure / safety-cap 証拠により indexing work の省略が判明 | `index_incomplete_reasons` に対処してから `cdidx index <projectPath>` |
 | `issues_table_available=false` | `file_issues` が無い、または issue-ready ではない | `cdidx index <projectPath>` |
 | `csharp_symbol_name_ready=false` | C# canonical symbol-name stamp が stale | `cdidx index <projectPath>` |
 | `csharp_metadata_target_ready=false` | C# metadata-target stamp が stale | `cdidx index <projectPath>` |

README.md

@@ -223,6 +223,16 @@ Check-mode JSON includes `query_context.check_mode` (`explicit` or
 `implied_by_stale_after`) and the effective `query_context.stale_after_seconds`;
 ordinary status JSON omits `query_context`.
 
+Index-generation readiness is derived from persisted evidence and is shared by
+the index command result, immediate `status` / workspace status, and MCP
+responses. `index_complete=false` identifies omitted input or extraction work,
+including symbols-only runs, file-size / symbol-count / reference-count limits,
+and extractor failures or safety caps; `index_incomplete_reasons` contains the
+stable reasons. `reference_graph_complete` additionally requires an available,
+current graph generation and reports its own stable reasons. Legacy databases
+without the newer metadata remain readable, while persisted omission evidence
+still prevents a false complete result.
+
 Reference extraction has fixed safety limits of 50,000 lookup symbols, 20,000
 lookup lines, 512 names per line, and 20,000 container candidates. CLI
 `languages --json` / `status --json` and the corresponding MCP responses publish
@@ -621,6 +631,15 @@ check mode の JSON は `query_context.check_mode`（`explicit` または
 `implied_by_stale_after`）と有効な `query_context.stale_after_seconds` を含み、
 通常の status JSON では `query_context` を省略します。
 
+index generation の readiness は永続化済みの証拠から導出し、index command の結果、
+直後の `status` / workspace status、MCP response で同じ snapshot を共有します。
+symbols-only run、file size / symbol count / reference count の上限、extractor failure、
+safety cap などで入力または抽出処理を省略した場合は `index_complete=false` となり、
+`index_incomplete_reasons` に安定した理由を返します。
+`reference_graph_complete` はさらに利用可能かつ current な graph generation を要求し、
+専用の安定した理由を返します。新しい metadata を持たない legacy database も読み取り可能な
+ままですが、永続化済みの省略証拠がある場合は誤って complete と報告しません。
+
 reference extraction の固定 safety limit は lookup symbol 50,000件、lookup line
 20,000行、1行あたりの name 512件、container candidate 20,000件です。
 CLI の `languages --json` / `status --json` と対応する MCP response は