docs: define model fallback explanation contract (br-36d)

Author: dmoliveira

CHANGELOG.md

@@ -36,6 +36,7 @@ All notable changes to this project are documented in this file.
 - Added recovery workflow planning in `scripts/context_resilience.py` with resume hints, safe fallback steps, and diagnostics payloads.
 - Added `scripts/context_resilience_command.py` with `/resilience status` and `/resilience doctor` stress diagnostics.
 - Added `instructions/context_resilience_tuning.md` with practical tuning guidance and operating playbook.
+- Added `instructions/model_fallback_explanation_model.md` defining provider/model fallback trace structure, output levels, and redaction rules for Epic 12 Task 12.1.
 
 ### Changes
 - Documented extension evaluation outcomes and when each tool is the better fit.

IMPLEMENTATION_ROADMAP.md

@@ -48,7 +48,7 @@ Use this map to avoid overlapping implementations.
 | E9 | Conditional Rules Injector | done | High | E1 | bd-1q8, bd-3rj, bd-fo8, bd-2ik | Enforce project conventions with scoped rules |
 | E10 | Auto Slash Command Detector | paused | Medium | E1, E8 | TBD | Resume only if intent precision stays high in prototypes |
 | E11 | Context-Window Resilience Toolkit | done | High | E4 | bd-2tj, bd-n9y, bd-2t0, bd-18e | Improve long-session stability and recovery |
-| E12 | Provider/Model Fallback Visibility | planned | Medium | E5 | TBD | Explain why model routing decisions happen |
+| E12 | Provider/Model Fallback Visibility | in_progress | Medium | E5 | bd-1jq | Explain why model routing decisions happen |
 | E13 | Browser Automation Profile Switching | planned | Medium | E1 | TBD | Toggle Playwright/agent-browser with checks |
 | E14 | Plan-to-Execution Bridge Command | planned | Medium | E2, E3 | TBD | Execute validated plans with progress tracking |
 | E15 | Todo Enforcer and Plan Compliance | planned | High | E14 | TBD | Keep execution aligned with approved checklists |
@@ -499,15 +499,16 @@ Every command-oriented epic must ship all of the following:
 
 ## Epic 12 - Provider/Model Fallback Visibility
 
-**Status:** `planned`
+**Status:** `in_progress`
 **Priority:** Medium
 **Goal:** Make model routing and provider fallback decisions observable and explainable.
 **Depends on:** Epic 5
 
-- [ ] Task 12.1: Define explanation model
-  - [ ] Subtask 12.1.1: Define resolution trace format (requested -> attempted -> selected)
-  - [ ] Subtask 12.1.2: Define compact vs verbose output levels
-  - [ ] Subtask 12.1.3: Define redaction rules for sensitive provider details
+- [x] Task 12.1: Define explanation model
+  - [x] Subtask 12.1.1: Define resolution trace format (requested -> attempted -> selected)
+  - [x] Subtask 12.1.2: Define compact vs verbose output levels
+  - [x] Subtask 12.1.3: Define redaction rules for sensitive provider details
+  - [x] Notes: Added `instructions/model_fallback_explanation_model.md` defining fallback trace shape, output levels, redaction policy, and deterministic reason-code requirements.
 - [ ] Task 12.2: Implement resolution tracing
   - [ ] Subtask 12.2.1: Capture fallback chain attempts in runtime
   - [ ] Subtask 12.2.2: Store latest trace per command/session

README.md

@@ -438,6 +438,12 @@ Fallback behavior is deterministic:
 - unknown category -> `default_category`
 - unavailable model -> `default_category`
 
+Fallback explanation contract (Epic 12 Task 12.1):
+- `instructions/model_fallback_explanation_model.md`
+- trace stages: `requested -> attempted -> selected`
+- output levels: `compact` and `verbose`
+- redaction policy for sensitive provider details
+
 Resolution precedence (Task 5.2):
 1. `system_defaults`
 2. selected category defaults

instructions/model_fallback_explanation_model.md

@@ -0,0 +1,90 @@
+# Provider/Model Fallback Explanation Model
+
+Epic 12 Task 12.1 defines the trace contract for explaining model and provider fallback decisions.
+
+## Goals
+
+- make every routing decision explainable in deterministic order
+- keep default output readable while preserving deep diagnostics for debugging
+- avoid exposing secrets or sensitive provider identifiers in normal traces
+
+## Trace structure
+
+A trace represents one routing decision in three stages:
+
+1. `requested`: what the caller asked for
+2. `attempted`: ordered candidates that were evaluated
+3. `selected`: final model/provider outcome
+
+Reference shape:
+
+```json
+{
+  "requested": {
+    "category": "deep",
+    "model": "openai/gpt-5.3-codex",
+    "source": "user_override"
+  },
+  "attempted": [
+    {
+      "rank": 1,
+      "model": "openai/gpt-5.3-codex",
+      "provider": "openai",
+      "result": "unavailable",
+      "reason": "model_not_in_available_set"
+    },
+    {
+      "rank": 2,
+      "model": "openai/gpt-5-mini",
+      "provider": "openai",
+      "result": "accepted",
+      "reason": "category_default_fallback"
+    }
+  ],
+  "selected": {
+    "model": "openai/gpt-5-mini",
+    "provider": "openai",
+    "reason": "fallback_unavailable_model_to_category"
+  }
+}
+```
+
+## Output levels
+
+### Compact (default)
+
+- include only `requested.model/category`, final `selected`, and 1-line fallback reason
+- include attempted count but not full per-attempt details
+- optimized for `/routing status` and routine debugging
+
+### Verbose
+
+- include full `attempted` chain with rank and rejection reason per candidate
+- include resolution source metadata (`system_default`, `category_default`, `user_override`)
+- include deterministic timestamps or sequence ids when available
+
+## Redaction rules
+
+Always redact in both compact and verbose modes:
+
+- API keys, tokens, bearer strings, authorization headers
+- full endpoint query strings containing credentials
+- account-scoped identifiers that can reveal tenant internals
+
+Redaction behavior:
+
+- preserve structural placeholders (`***redacted***`) so traces remain parseable
+- keep provider class labels (`openai`, `anthropic`, etc.) unless explicitly marked sensitive
+- if a field is fully sensitive, replace value and attach a redaction reason code
+
+## Determinism requirements
+
+- attempted candidates must be listed in exact evaluation order
+- fallback reason codes must use stable identifiers (no free-form prose)
+- identical inputs and availability state must yield identical trace output
+
+## Integration targets
+
+Task 12.2 should emit this trace model from runtime routing.
+Task 12.3 should expose compact and verbose views via user-facing commands.
+Task 12.4 should verify deterministic traces and redaction safety.