[P0][UX] 非エンジニア向けに復旧action付きエラー体験を統一する

[tuzuminami]

背景 / 現状

起動、sidecar、recording、Finder file access、import、SQLite、export、privacy guardの失敗は層ごとに異なる文面・例外・再試行可否で返る。技術詳細だけでは非エンジニアが次に何をすればよいか判断できず、逆に詳細をそのまま出すとlocal path、event内容、secretを漏らす危険がある。

目的

ユーザーがエラーの種類を理解し、安全な次の一手をUIだけで選べる。一方で診断に必要なtechnical evidenceはprivacy-safeに分離する。

対象

• desktop起動/sidecar、recording、Finder選択、import、analysis、export、SQLite/recovery、network guard、permission、deleteの共通error contract
• stable error code、severity、retryable、recovery action、localized user copy、safe technical detail
• retry、再選択、記録停止、アプリ再起動、競合プロセス終了案内、diagnostics、support bundleへの導線
• UIのinline/banner/modal/toastの使い分け、accessibility、日英同期
• failure injectionとcritical journey UI test

非対象

• remote support、telemetry、crash upload、LLMによる自動解決
• raw stack trace、raw path、event本文、token、session secretを通常UIへ表示すること
• 故障を握りつぶしてsuccessに見せるfallback

Claude Code実装契約

1. backend/agent/Tauri/UIで共有するerror envelopeを定義する。少なくとも code、severity、retryable、recovery_action、user_message_key、safeなcontextだけを持ち、driver/stack traceを外部contractに流さない。
2. recovery_action は実行可能な有限集合にする。例: retry、再選択、recording停止、アプリ再起動、競合プロセスを閉じる、diagnosticsを開く、safe logを保存、設定を開く。存在しないactionや危険な自動修復を提示しない。
3. 同じ失敗は同じcode/actionへ正規化する。storage uncertain/recovery-required、permission denied、file scope expired、invalid import、cancelled、port conflict、disk full、network policy violation、sidecar unavailableを最低限定義する。
4. retry前に入力、project scope、mutation revision、delete challengeの安全性を再検証する。破壊的mutationを自動再送しない。[P0][Storage] 永続化commit失敗時のin-memory phantom stateを排除し全mutationをatomicにする #117/#122のwrite/revision modelを迂回しない。
5. 日英文面は「何が起きたか」「データへの影響」「今すぐ行う操作」「解決しない場合」を分け、専門用語/Terminal操作を必須にしない。日本語キーの欠落はbuild/testでfailする。
6. technical detailは明示操作でのみ表示し、safe DTOを通す。diagnostics/support bundleにはerror code、時刻、component、action結果のみを基本とし、PII・raw path・secretを出さない（[P1][Operations UX] ワンクリックのprivacy-safe診断レポートと復旧導線を提供する #55/[P0][Privacy] maskingを安全なデータ境界にしraw PIIをAPI・保存・exportから除去する #76/[P1][Audit] privacy-preserving local監査logと明示生成support bundleを実装する #94）。
7. focus移動、ARIA live announcement、キーボード操作、colorだけに依存しないseverity表示を満たす（[P1][Accessibility] キーボード・VoiceOver・視覚的理解で主要journeyを完走可能にする #59）。同時に複数errorが起きても最も安全なactionを優先し、画面を操作不能にしない。

受け入れ条件

• critical journey（起動、record、import、analyze、export、delete、quit）の代表失敗が、日英でcode・安全なnext action・data impactを表示する。
• invalid CSV、Finder scope失効、DB locked/disk full、sidecar crash/port conflict、permission denied、cancel、storage recovery-required、network guard failureの各fixtureで、生の例外、PII、path、secretがUI/log/exportに出ない。
• retryable errorは入力を失わず、non-retryable/destructive errorは再送せず、reopen後もdata stateが説明と一致する。
• error UIはmouseなしで操作でき、screen readerに状態と推奨actionが読まれる。
• unknown errorはfail closedし、汎用safe message + diagnostics actionを出す。success表示やsilent ignoreにならない。

検証

• API/agent/Tauri/UIのerror-contract snapshot test
• fault injection、translation completeness、PII sentinel scan、keyboard/VoiceOver smoke
• failed retry/cancel/restart後のDB/recording state確認
• ./scripts/test.sh、./scripts/lint.sh、./scripts/check_licenses.sh、./scripts/check_no_external_network.sh

依存関係

• 参照: [P1][Operations UX] ワンクリックのprivacy-safe診断レポートと復旧導線を提供する #55、[P1][Accessibility] キーボード・VoiceOver・視覚的理解で主要journeyを完走可能にする #59、[P1][i18n] 日英の用語・翻訳完全性・表示品質をrelease gate化する #60、[P0][Privacy] maskingを安全なデータ境界にしraw PIIをAPI・保存・exportから除去する #76、[P0][macOS] backendと記録agentを同梱した自己完結.appのlifecycleを実装する #78、[P1][Reliability] crash・orphan process・SQLite corruptionをlocal recovery flowで復旧する #87、[P1][Recording] sleep/wake・clock change・agent crashでもsessionを正しく復旧する #95、[P1][Quality] critical-path coverage・failure-injection・test skip policyをrelease gate化する #115、[P0][Storage] 永続化commit失敗時のin-memory phantom stateを排除し全mutationをatomicにする #117、[P1][Storage][UX] stale revisionを拒否するmutation receiptとoptimistic concurrencyを実装する #122
• 先行/並行可: [P0][Storage] project/案件単位でデータセットを完全分離する #40。project scope errorの最終contractは#40後に統合する。
• packaged UIでの最終受入は[P0][Quality] packaged .appのclean Mac E2Eとv1 release acceptanceを強制する #85。

PR運用

1 Issue = 1 branch / PR。新規error code、recovery action、変更したuser copy、テストfixture、残余riskをPR本文に記載する。runtime外部通信や自動uploadを追加しない。

[tuzuminami]

Claude Code実装契約（v1.0 P0）

GitHub label と #105 を優先し、本Issueは P0 release blocker として扱う。本文の Priority: P1 は旧記載。

• error contractをstable code、user-safe summary、technical detail、retryability、suggested action、correlation IDに分ける。raw event、window title、URL、memo、token、absolute user path、stack traceは通常UI/clipboard/exportへ出さない。
• startup/runtime/permission/recording/import/schema/restore/export/space/integrity/network-policyごとに、再試行、診断、Finder再選択、設定変更、safe stop、support bundleなどの正しい次アクションを一意にする。
• retryはidempotency/cancel stateを尊重し、既存dataに二重import・二重recording・partial exportを作らない。詳細診断は[P1][Operations UX] ワンクリックのprivacy-safe診断レポートと復旧導線を提供する #55/#94の明示生成に統合する。
• 日英のmessage keyを同じerror codeから描画し、actionがdisabledな理由も説明する。[P0][macOS] backendと記録agentを同梱した自己完結.appのlifecycleを実装する #78/[P0][UX] Finder file picker・drag and drop・save dialogでpath入力を不要にする #79/[P1][Reliability] crash・orphan process・SQLite corruptionをlocal recovery flowで復旧する #87/#97のrecovery contractと重複させない。

追加受け入れ条件

• representative failure matrixで、非エンジニアがtechnical logを読まずに復旧または安全に停止できる。
• PII/secret/path sentinel、retry/cancel、offline、corrupt DB、permission deny、sidecar unavailableをUI/E2Eで検証する。