Add conservative audit baselines and local review annotations

DEVELOPER_GUIDE.md

@@ -2,6 +2,14 @@
 
 > **[日本語版はこちら / Japanese version](#開発者ガイド)**
 
+## Audit baseline contract
+
+Workspace identity comes from the indexed project root, independently of the database location. Saved size/symlink policy participates in scope comparison. For prior paths that no longer have indexed rows, reuse indexing path filters and sparse-checkout evidence: only verified physical deletions within the current indexing scope may resolve. Existing excluded files and unverifiable paths make comparison unknown. Reject contradictory truncation/count metadata; missing coverage fields and empty incomparable comparisons remain partial (exit `11`).
+
+`AuditBaselineStore` implements the local v1 baseline schema; `QueryCommandRunner.AuditBaseline.cs` consumes the same bounded recipe runs as `audit --all`. The `baseline-export`, `baseline-compare`, and `baseline-review` audit subcommands do not migrate SQLite or use GitHub. Preserve SHA-256 match/context identities without line coordinates, canonical case-preserving relative paths, schema/identity versions, effective scope and recipe fingerprints, workspace and index-generation provenance, coverage reasons, and count authority. Index generations may differ after a valid refresh; workspace/scope/recipe/identity contracts must match. Missing legacy provenance degrades comparison conservatively.
+
+Absence can become resolved only when both snapshots have complete coverage. Retain unknown classifications for capped, stale, partial, failed, cancelled, changed-scope, changed-recipe, insufficient-evidence, duplicate, or possible-rename cases. Review annotations bind actor/reason/time to the stored context; changed evidence cannot inherit a safe decision. Comparison counts distinct identity groups and separately exposes observation counts. Bound files to 8 MiB, depth to 16, observations to 10,000, and comparison rows to 200 with exact omission accounting. Baselines omit source snippets, use the existing atomic sensitive writer, and require explicit overwrite. Windows paths emitted by the index already use slash separators; ambiguous literal backslashes fail closed. Keep command help, contextual completions, README, and behavioral tests synchronized.
+
 ## Indexed file-size policy
 
 For indexing, a nonblank invalid environment value retains the existing warning-and-default behavior; an explicit valid limit still takes precedence.
@@ -4328,6 +4336,14 @@ For symmetry, the MCP server no longer echoes raw `Exception.Message` content in
 <a id="開発者ガイド"></a>
 # 開発者ガイド
 
+## 監査 baseline 契約
+
+ワークスペースの識別には DB の保存先とは独立した索引対象のプロジェクトルートを使用します。保存済みサイズ・シンボリックリンク方針も範囲比較に含めます。以前のパスが索引行を失った場合は索引のパスフィルターと sparse-checkout の情報を再利用し、現在の索引範囲内で確認できた物理的削除だけを解決済みとします。存在する除外ファイルや検証不能なパスは不明扱いです。省略・件数の矛盾したメタデータは拒否し、完全性情報の欠落や空の比較不能結果も部分結果（終了コード `11`）とします。
+
+`AuditBaselineStore` がローカル v1 baseline スキーマを実装し、`QueryCommandRunner.AuditBaseline.cs` は `audit --all` と同じ上限付きレシピ実行を利用します。audit の `baseline-export`、`baseline-compare`、`baseline-review` サブコマンドは SQLite の移行や GitHub 接続を行いません。行番号を含まない SHA-256 の一致・文脈識別、大小文字を保持する正規相対パス、スキーマ・識別バージョン、実効範囲・レシピの指紋、ワークスペース・索引世代の由来、完全性の理由、件数の確実性を維持してください。正しい索引更新後の世代差は許容しますが、ワークスペース・範囲・レシピ・識別契約は一致必須です。旧データの由来情報が欠ける場合は保守的に比較を降格します。
+
+不在を解決済みとできるのは両スナップショットが完全な場合だけです。上限到達・古い索引・部分実行・失敗・取消・範囲変更・レシピ変更・証拠不足・重複・リネーム候補は不明のまま保持します。注釈は担当者・理由・時刻を保存された文脈に結び付け、証拠変更後は安全判定を継承しません。比較では識別グループ数と観測数を別々に示します。ファイル8 MiB、深度16、10,000観測、比較出力200行の上限と正確な省略数を維持してください。ソース抜粋は保存せず、既存のアトミックな機密ファイル保存処理と明示的な上書きを使用します。索引の Windows パスは既にスラッシュ区切りであり、曖昧なリテラルのバックスラッシュは拒否します。ヘルプ・文脈別補完・README・振る舞いのテストを同期してください。
+
 `audit --all --progress` は `ConsoleUi.AuditProgress` を使い、単調増加時計と同期された timer により、逐次実行する子 query の処理中も進捗を通知します。開始／終了通知を除く heartbeat は毎秒最大1回で、ASCII payload は最大256文字です。recipe/query は番号だけを出力し、カスタム識別子からの機密情報漏洩を防ぎます。stderr 自身の端末状態を確認し、再描画は端末幅で切り詰め、取得用の行は flush し、破棄前に gate 内で通知を停止します。出力のシリアライズ後に終了状態を決定するため、byte 上限の失敗と `--allow-partial` で許可された不完全な結果も区別します。既存の quiet と animation 無効化指定は明示的な progress より優先され、recipe matching、SQLite cancellation、audit deadline は維持されます。
 
 ### 索引のファイルサイズ方針

README.md

@@ -18,6 +18,18 @@
 agents, MCP clients, and LSP-native editors can run fast full-text, symbol,
 dependency, and inspection queries without rescanning the same tree for every query.
 
+## Local audit baselines
+
+Changing index exclusions cannot turn an existing excluded file into a resolution. Comparison verifies prior path coverage, distinguishes physical deletion from sparse/ignored paths, and detects when the same database location now indexes another project. Empty incomparable comparisons also return exit `11`.
+
+`cdidx audit baseline-export .cdidx/audit-baseline.json --recipe risky-code` runs the existing audit engine and saves a local baseline. Omit `--recipe` to select all registered recipes. Refresh the index after source changes, then run `cdidx audit baseline-compare .cdidx/audit-baseline.json --recipe risky-code --json`. Use the same filters and limits for comparable runs. Each command accepts `--db`, `--lang`, `--path`, `--exclude-path`, `--exclude-tests`, `--audit-scope`, `--since`, `--limit`, and `--total-limit` as shown in command help; defaults are 1,000 rows per query and 10,000 total rows.
+
+Comparison reports bounded `new`, `unchanged`, `resolved`, and `unknown` identity groups, totals, observation counts, and omissions. Missing findings stay `unknown` when either run is stale, partial, capped, failed, cancelled, or has different recipes, filters, workspace, or identity contracts. Duplicate evidence and possible renames are never guessed. Line numbers are excluded from identity; changed context requires review. Exit `11` identifies incomplete coverage or unknown classifications; export may save an incomplete baseline, explicitly marked as such. Cancellation never publishes an export.
+
+To record a safe finding, copy its `id` from the baseline or comparison and run `cdidx audit baseline-review .cdidx/audit-baseline.json <id> --actor <name> --reason <text> --overwrite`. This requires a complete baseline and an unambiguous entry. The reason, actor, time, and evidence remain traceable; `review_applies` is true only for unchanged compatible evidence. Compare never edits the baseline. Export refuses replacement without `--overwrite`; explicit replacement starts a new baseline without previous annotations.
+
+Files contain hashes of bounded match/context evidence, normalized relative paths, effective filters, and index/recipe provenance, with no source snippets. Store them under `.cdidx/` or outside the indexed source scope. Limits are 8 MiB, JSON depth 16, 10,000 observations, and 200 comparison rows with omission counts. Writes are atomic and use POSIX mode `0600` (Windows inherits directory ACLs). Paths retain case; ambiguous backslashes, absolute paths, and parent segments are rejected. This CLI-only workflow needs neither GitHub credentials nor a database migration. Regenerate installed shell completions after upgrading.
+
 ## Audit progress
 
 For captured audit liveness, use `cdidx audit --all --summary-only --json --progress`. Progress goes to stderr while stdout retains JSON/NDJSON. `--quiet` and `--no-progress` override it regardless of argument order. See [audit progress](USER_GUIDE.md#audit-progress).
@@ -291,6 +303,18 @@ For commercial use, integration, and naming guidance, see
 
 # cdidx（日本語）
 
+### ローカル監査 baseline
+
+索引の除外設定を変更しても、存在する除外ファイルを解決済みとは判定しません。以前のパスの対象範囲を確認し、物理的削除と sparse／除外パスを区別し、同じ DB 保存先が別プロジェクトの索引に置き換わった場合も検出します。空の比較不能結果も終了コード `11` を返します。
+
+`cdidx audit baseline-export .cdidx/audit-baseline.json --recipe risky-code` は既存の監査エンジンを実行し、ローカル baseline を保存します。`--recipe` を省略すると登録済みの全レシピが対象です。ソース変更後に索引を更新し、`cdidx audit baseline-compare .cdidx/audit-baseline.json --recipe risky-code --json` で比較します。比較時は同じフィルターと上限を指定してください。各コマンドはヘルプ記載の `--db`、`--lang`、`--path`、`--exclude-path`、`--exclude-tests`、`--audit-scope`、`--since`、`--limit`、`--total-limit` に対応します。既定値はクエリごとに1,000行、全体で10,000行です。
+
+比較は `new`、`unchanged`、`resolved`、`unknown` の識別グループ、総数、観測数、省略数を返します。どちらかの実行が古い、不完全、上限到達、失敗、取消済み、またはレシピ・フィルター・ワークスペース・識別契約が異なる場合、消えた検出結果は `unknown` のままです。重複した証拠やリネーム候補を推測で対応付けません。行番号は識別から除外し、文脈が変化した場合は再レビューが必要です。不完全な監査または不明な分類は終了コード `11` となります。export は不完全であることを明記した baseline を保存できますが、取消時は公開しません。
+
+安全確認済みの記録には baseline または比較結果の `id` を用い、`cdidx audit baseline-review .cdidx/audit-baseline.json <id> --actor <name> --reason <text> --overwrite` を実行します。完全な baseline 内の一意な検出結果だけが対象です。理由・担当者・時刻・証拠を保存し、互換性のある証拠が変わっていない場合だけ `review_applies` が真になります。compare は baseline を変更しません。export による置換には `--overwrite` が必要で、明示的な置換後は以前の注釈を含まない新しい baseline になります。
+
+ファイルには上限付きの一致・文脈のハッシュ、正規化した相対パス、実効フィルター、索引・レシピの由来を記録し、ソースの抜粋は保存しません。`.cdidx/` または索引対象外に保存してください。上限は8 MiB、JSON 深度16、10,000観測、比較出力200行で、省略数を明示します。保存はアトミックで、POSIX は `0600`、Windows は親ディレクトリの ACL を継承します。パスの大文字小文字を保持し、曖昧なバックスラッシュ・絶対パス・親ディレクトリ要素は拒否します。CLI 専用で、GitHub 認証や DB 移行は不要です。更新後はインストール済みのシェル補完を再生成してください。
+
 audit の出力を取得しながら実行状況を確認するには、`cdidx audit --all --summary-only --json --progress` を使います。進捗は stderr に出力し、stdout の JSON/NDJSON を維持します。`--quiet` と `--no-progress` は引数の順序に関係なく優先されます。[audit の進捗](USER_GUIDE.md#audit-の進捗)を参照してください。
 
 ### ファイルサイズ上限と鮮度チェック

TESTING_GUIDE.md

@@ -8,6 +8,10 @@ If you change test code, test helpers, test execution flow, or testing conventio
 
 ## Quick Start
 
+Baseline review regressions also exercise indexing exclusion changes, a different indexed root at the same DB path, contradictory/missing omission metadata, and the partial exit code for empty incomparable snapshots.
+
+`AuditBaselineIssue5261Tests` covers compatible deltas, moved lines, changed reviewed evidence, incomplete/legacy metadata, ambiguous duplicates/renames, bounded counts, private atomic writes, invalid paths and malformed/oversized input, plus actual index/recipe CLI export and compare. Keep human/JSON error identity and contextual help/completion checks on both net8.0 and net9.0. Use the console-sensitive collection for CLI capture and isolated temporary projects for baseline files.
+
 The #5260 redraw test also pauses the renderer, proves later timer ticks emit nothing during result output, and checks that clearing precedes the result and the terminal notification follows it.
 
 Issue #5260 coverage in `QueryCommandRunnerAuditProgressIssue5260Tests` waits for a real heartbeat while a child query is held, verifies JSON/NDJSON stdout and private-identifier exclusion, and exercises cancellation, query/output failures, the deadline, global quiet/no-progress precedence, flag scope, and deterministic monotonic rate/redraw/disposal behavior on both frameworks. Keep console mutations inside the console-sensitive collection and restore captured writers and test budgets in `finally`.
@@ -1182,6 +1186,10 @@ Check the following:
 <a id="テストガイド"></a>
 # テストガイド
 
+baseline レビューの回帰テストでは、索引除外設定の変更、同一 DB パスでの索引ルートの変更、矛盾・欠落した省略メタデータ、空の比較不能スナップショットの部分終了コードも検証します。
+
+`AuditBaselineIssue5261Tests` は互換性のある差分、行移動、レビュー済み証拠の変化、不完全・旧形式のメタデータ、曖昧な重複・リネーム、上限付き件数、機密ファイルのアトミック保存、不正パス・壊れた入力・過大入力、および実際の索引・レシピによる CLI 保存と比較を検証します。human／JSON のエラー識別と文脈別ヘルプ・補完を net8.0 と net9.0 の両方で維持してください。CLI 出力の捕捉は console-sensitive コレクションに置き、baseline は分離した一時プロジェクトに保存してください。
+
 #5260 の再描画テストは、renderer の一時停止後の timer tick が結果出力中に何も書かないことと、行消去・結果出力・終了通知の順序も確認します。
 
 Issue #5260 の `QueryCommandRunnerAuditProgressIssue5260Tests` は子 query を待機させて実際の heartbeat を確認し、stdout の JSON/NDJSON とカスタム識別子の非公開、取消、query／出力の失敗、deadline、quiet/no-progress の優先順位、flag の適用範囲、単調増加時計による通知頻度と再描画／破棄を両 framework で検証します。console の変更は console-sensitive collection 内で行い、writer とテスト用 budget を `finally` で復元してください。

changelog.d/unreleased/5261.added.md

@@ -0,0 +1,16 @@
+---
+category: added
+issues:
+  - 5261
+affected:
+  - src/CodeIndex/Cli/AuditBaselineStore.cs
+  - src/CodeIndex/Cli/QueryCommandRunner.AuditBaseline.cs
+---
+
+## English
+
+- Added local audit baseline export, comparison, and reviewed-safe annotations. Versioned private files retain evidence hashes and coverage provenance; incomplete or ambiguous absence remains unknown, changed evidence requires review, and bounded comparison output reports new, unchanged, resolved, and unknown totals with omissions.
+
+## 日本語
+
+- ローカル監査 baseline の保存・比較・安全確認済み注釈を追加しました。バージョン付きの非公開ファイルに証拠ハッシュと完全性の由来を記録し、不完全または曖昧な不在は不明のまま扱い、証拠変更時は再レビューを必要とします。上限付き比較出力には新規・変更なし・解決済み・不明の総数と省略数を表示します。