feat: Enhance drift detection and validation mechanisms

- Added tests for frontmatter model defaults validation in drift-detection.test.mjs, ensuring that frontmatter models align with role defaults and do not conflict with tier-specific overrides.
- Implemented validation for payload model description semantics, ensuring that payload models are correctly defined and do not override frontmatter models.
- Updated orchestration-handoff-contract.test.mjs to include checks for outer dispatch contracts, ensuring separation of outer tool-call fields and payload-level models.
- Enhanced validation logic in validate.mjs to incorporate checks for frontmatter model defaults and payload model semantics.
- Revised project context documentation to reflect updated model routing roles for agents.
- Documented lessons learned in session outcomes regarding model routing and frontmatter defaults.
- Updated orchestrator delegation protocol schema to clarify payload model descriptions and their intended use.
- Introduced a new structural reference fixture in model-routing-alignment.json to ensure alignment across governance role defaults, direct-invocation frontmatter, and payload-level delegation schema.

Author: Smith

NOTES.md

@@ -2,6 +2,6 @@
 
 Repo-persistent active-objective state only. See `docs/agent-engineering/MEMORY-ARCHITECTURE.md` for the three-layer memory model; task-episodic history lives under `plans/artifacts/<task-slug>/`.
 
-- Active objective: Claude Code plugin implementation complete; awaiting user review.
+- Active objective: model-routing mismatch root-cause fix complete; awaiting user review of completion summary.
 - Blockers: none.
-- Pending: user review of final summary and any follow-up Claude CLI validation when available.
+- Pending: user review before any commit or merge action.

Orchestrator.agent.md

@@ -166,13 +166,13 @@ Before every `agent/runSubagent` call, regardless of dispatch context, apply thi
 4. Pass the resolved `primary` model string as the `model` parameter to `agent/runSubagent`. Never omit `model`.
 5. For initial planning dispatches before any plan `complexity_tier` exists, use the target role's top-level `primary` model. For replan/planning dispatches after a plan exists, use the active plan's `complexity_tier`. Never omit `model` because tier context is missing.
 
-This rule covers all dispatch paths without exception: Plan Review Gate reviewers (PlanAuditor, AssumptionVerifier, ExecutabilityVerifier), phase CodeReviewer dispatch, final CodeReviewer dispatch, needs_replan Planner dispatch, and Implementation Loop executor dispatch.
+This rule covers all dispatch paths without exception: Plan Review Gate reviewers (PlanAuditor, AssumptionVerifier, ExecutabilityVerifier), phase CodeReviewer dispatch, final CodeReviewer dispatch, failure-classification retry dispatch, needs_replan Planner dispatch, and Implementation Loop executor dispatch.
 
 ### Dispatch Tool-Call Contract (Required Fields)
 
 Every `agent/runSubagent` call must include these outer tool-call fields:
 - **`agentName`** — the verified target-agent field (string). Placing the agent name only inside prompt prose or a delegation payload is non-compliant.
-- **`model`** — the resolved primary model string from the Universal Model Resolution Rule. Never omit.
+- **`model`** — the resolved primary model string from the Universal Model Resolution Rule, passed as the outer `model` field at the tool-call boundary. Never omit. A payload-level `model` inside the prompt/delegation payload remains useful for schema validation and audit context, but it does not by itself select the runtime model and is not a substitute for this outer field.
 - **Prompt/context payload** — scope, deliverables, and relevant context references.
 
 #### Capable-Reviewer Model Routing

Planner.agent.md

@@ -50,7 +50,7 @@ For all other scopes, record applicability, impact, evidence source, and disposi
   4. Include selected skill file paths in each applicable phase's `skill_references` array.
   Implementation agents load referenced skills before executing phase tasks.
 6. Research (delegate CodeMapper-subagent/Researcher-subagent when scope is large).
-  - **Model Resolution:** For every `agent/runSubagent` dispatch to `CodeMapper-subagent` or `Researcher-subagent`, load `governance/model-routing.json`, resolve the subagent role via the top-level `agent_role_index`, then apply `roles[role].by_tier[complexity_tier]`. If the tier entry is `{ "inherit_from": "default" }`, inherit the role's default `primary` model and default `fallbacks`; otherwise use the tier-specific `primary` and tier-specific `fallbacks` when present. Pass the resolved `primary` as the `model` parameter. Only pass a fallback list if/when `agent/runSubagent` explicitly supports one; otherwise pass only the resolved primary model string.
+  - **Model Resolution:** For every `agent/runSubagent` dispatch to `CodeMapper-subagent` or `Researcher-subagent`, load `governance/model-routing.json`, resolve the subagent role via the top-level `agent_role_index`, then apply `roles[role].by_tier[complexity_tier]`. If the tier entry is `{ "inherit_from": "default" }`, inherit the role's default `primary` model and default `fallbacks`; otherwise use the tier-specific `primary` and tier-specific `fallbacks` when present. Every research dispatch must pass the exact target as the outer `agentName` field and the resolved `primary` as the outer `model` field. Only pass a fallback list if/when `agent/runSubagent` explicitly supports one; otherwise pass only the resolved primary model string. A payload-level `model` in the prompt/delegation payload is contract and audit context; it does not by itself select the runtime model and is not a substitute for the outer `model` field.
 7. Design (structured design decisions and diagram selection):
    - **Design Decisions Checklist** — Before proceeding to Planning (Step 8), explicitly address four dimensions:
      1. **Boundary changes** — Does the task change system boundaries, add new actors, or modify integration points? If no boundary changes, state "No boundary changes."

docs/agent-engineering/MODEL-ROUTING.md

@@ -1,7 +1,7 @@
 # Model Routing
 
 **Status:** Phase 4 spike (single-agent rollout)
-**File:** `governance/model-routing.json`
+**File:** `governance/model-routing.json` is the canonical source of truth for internal model selection.
 **trace_id:** 7d3f5a2e-1b4c-4e9f-9a8b-2c5d8e1f3a7b
 
 ## Purpose
@@ -25,7 +25,7 @@ Decouple agent definitions from hard-pinned model strings. Today every `*.agent.
 The 10 roles are:
 
 | Role | Consumers |
-|---|---|
+| --- | --- |
 | `orchestration-capable` | Orchestrator |
 | `capable-planner` | Planner |
 | `capable-implementer` | CoreImplementer, PlatformEngineer |
@@ -72,7 +72,11 @@ When Orchestrator or Planner dispatch a subagent via `agent/runSubagent`, they a
 1. They load `governance/model-routing.json`.
 2. They look up the target agent in `agent_role_index`.
 3. They apply the `by_tier` complexity rule to determine the required model string.
-4. They pass the resolved `primary` explicitly as the `model` parameter to `agent/runSubagent`, and MUST supply the verified target-agent field `agentName` at the tool-call boundary, overriding the agent's frontmatter at call time.
+4. They pass the resolved `primary` explicitly as the outer `model` parameter to `agent/runSubagent`, and MUST supply the verified target-agent field `agentName` at the outer tool-call boundary, overriding the agent's frontmatter at call time.
+
+### Delegation Payload Contract
+
+The schema definition in `schemas/orchestrator.delegation-protocol.schema.json` requires a nested payload-level `model` field in all delegation objects. These payload-level fields carry resolved model context for validation, audit, and prompt-visible traceability, but they do not by themselves enforce the runtime model override. The outer `model` parameter on the tool call is the strict enforcement point.
 
 While global VS Code Copilot execution (e.g., triggering an agent directly from chat) still relies on the frontmatter fallback, all internal orchestrated pipeline dispatches strictly enforce the logical routing graph dynamically. It is important to note that offline evals do not prove live `runSubagent` execution; we distinguish structural tests and tool/API-shape evidence from real live subagent dispatch (as proven by the existing model override spike).
 
@@ -114,17 +118,19 @@ fallback chain at every complexity tier.
 The prompt-driven runtime resolution module (Orchestrator/Planner dynamic lookup) is complete.
 
 Remaining prerequisites for Stage D (auto-tuning observability):
+
 - (a) accumulate ≥50 task telemetry entries via the NDJSON sink at `plans/artifacts/observability/`
 - (b) expand `governance/model-routing.json` schema with `inherit_from` targets beyond `"default"` (e.g., other roles or tier mixes)
 
 ### Stage C Cross-references
+
 - Phase 1 spike artifact: `plans/artifacts/model-routing-stage-c/phase-1-spike-result.md`
 - Validation helper: `evals/drift-checks.mjs` → `validateByTierShape`
 
 ## Cost/latency tier meanings
 
 | Tier | `cost_tier` | `latency_tier` |
-|---|---|---|
+| --- | --- | --- |
 | `low` | Inexpensive per-call; suitable for high-volume read-only or smoke tasks. | Sub-second to a few seconds typical first-token. |
 | `medium` | Mid-range per-call; default for implementer and review-readonly work. | A few seconds typical first-token. |
 | `high` | Expensive per-call; reserve for planning, deep review, or research. | `slow` — multi-second first-token; long completions expected. |

docs/tutorial-en/10-governance.md

@@ -13,7 +13,7 @@ Understand **which governance files regulate agent behavior** and how to change
 ## Governance Files
 
 | File | Purpose |
-|------|---------|
+| --- | --- |
 | `agent-grants.json` | Which agents can access which tools |
 | `tool-grants.json` | Which tools are exposed and their properties |
 | `runtime-policy.json` | Operational knobs: retry budgets, tier routing, approval policies |
@@ -45,46 +45,54 @@ The most important governance file. Orchestrator reads it as the **authoritative
 ### Key Sections
 
 **`approval_actions`** — which operations require user approval before execution:
-```
+
+```text
 ["delete_file", "drop_table", "git_push_force", "git_reset_hard", "run_destructive_migration"]
 ```
 
 **`review_pipeline_by_tier`** — which reviewers run for each tier:
-```
+
+```text
 TRIVIAL: []
 SMALL: [PlanAuditor]
 MEDIUM: [PlanAuditor, AssumptionVerifier]
 LARGE: [PlanAuditor, AssumptionVerifier, ExecutabilityVerifier]
 ```
+
 (plus `code_review: always` on all tiers)
 
 **`max_iterations_by_tier`** — review loop iteration cap:
-```
+
+```text
 TRIVIAL: 0, SMALL: 2, MEDIUM: 5, LARGE: 5
 ```
 
 **`retry_budgets`** — cumulative retry limit per phase and ceiling on consecutive identical failures:
-```
+
+```text
 per_phase: 5
 same_classification_ceiling: 3
 ```
 
 **`stagnation_detection`** — when to call a review loop "stuck":
-```
+
+```text
 min_iterations_before_check: 3
 min_improvement_percentage: 5
 ```
 
 **`plan_review_gate_trigger_conditions`** — PLAN_REVIEW activation conditions:
-```
+
+```text
 min_phases: 3
 confidence_threshold: 0.8
 destructive_operations: true
 unresolved_high_risks: true
 ```
 
 **`final_review_gate`** — optional final CodeReviewer pass:
-```
+
+```text
 enabled_by_default: true / false
 auto_trigger_tiers: ["LARGE"]
 max_fix_cycles: 1
@@ -95,7 +103,7 @@ max_fix_cycles: 1
 Controls memory quality enforcement thresholds and content standards:
 
 | Key | Value | Purpose |
-|-----|-------|---------|
+| --- | --- | --- |
 | `notes_md_max_lines` | 20 | NOTES.md size cap (CI-enforced by Pass 7) |
 | `archive_completed_plans_threshold_days` | 14 | Days before a closed plan is eligible for archival |
 | `archive_eligible_statuses` | `["DONE","SUPERSEDED","DEFERRED"]` | Plan statuses eligible for auto-archive |
@@ -109,17 +117,19 @@ Controls memory quality enforcement thresholds and content standards:
 Defines which LLM model handles which type of task. Does **not** contain API keys — only model names / capabilities.
 
 **Typical sections:**
-- `task_type_routing` — by task type (research, implementation, review, planning).
-- `tier_routing` — by complexity tier.
-- `fallback` — default model.
 
-**Who uses it:** Orchestrator and individual agents via the `model_role` field in schema outputs. See also [docs/agent-engineering/MODEL-ROUTING.md](../agent-engineering/MODEL-ROUTING.md).
+- `roles` — by role ID (e.g. `capable-planner`, `capable-implementer`), explicitly handling complexity tiers.
+- `by_tier` — explicit capability overrides for routing models dynamically by complexity tier.
+- `agent_role_index` — reverse-mapping index from agent name to active model role.
+
+**Who uses it:** Orchestrator and Planner actively read `model-routing.json` for internal dispatch resolution (e.g. `agent/runSubagent`) to pass the resolved model as an outer tool-call parameter overriding the fallback frontmatter. See [docs/agent-engineering/MODEL-ROUTING.md](../agent-engineering/MODEL-ROUTING.md).
 
 ## rename-allowlist.json
 
 Contains permitted file renames. Prevents accidental drift: if an agent tries to rename a file not on the allowlist — the drift check fails.
 
 **Typical structure:**
+
 ```json
 [{"from": "old-name.md", "to": "new-name.md", "reason": "..."}]
 ```
@@ -146,28 +156,28 @@ flowchart TD
     Schema --> Eval[cd evals && npm test]
     Eval -->|passed| Done[Change accepted]
     Eval -->|failed| Fix[Fix the issue]
-| What taxonomy types does repo memory use? | `runtime-policy.json → memory_hygiene.memory_content_types` |
     Fix --> Eval
 ```
 
 ## Knowledge Location Table
 
 | Question | Where to look |
-|----------|--------------|
+| --- | --- |
 | Which tools can an agent use? | `agent-grants.json` |
 | Which callers can use a tool? | `tool-grants.json` |
 | How many retries are allowed? | `runtime-policy.json → retry_budgets` |
 | When does PLAN_REVIEW fire? | `runtime-policy.json → plan_review_gate_trigger_conditions` |
 | Which model to use for which tier? | `model-routing.json` |
 | Can a file be renamed? | `rename-allowlist.json` |
 | What approval is required? | `runtime-policy.json → approval_actions` |
+| What taxonomy types does repo memory use? | `runtime-policy.json → memory_hygiene.memory_content_types` |
 
 ## Additional Governance Docs
 
 Authoritative policy documents in `docs/agent-engineering/`:
 
 | Document | Content |
-|----------|---------|
+| --- | --- |
 | `CLARIFICATION-POLICY.md` | When to call `vscode/askQuestions` vs NEEDS_INPUT |
 | `TOOL-ROUTING.md` | External tool routing rules (web/fetch, githubRepo, MCP) |
 | `SCORING-SPEC.md` | Quantitative scoring formula |

docs/tutorial-ru/10-governance.md

@@ -7,6 +7,7 @@
 ## Что такое governance в ControlFlow
 
 Governance — это **5 JSON-файлов** в `governance/`, фиксирующих:
+
 1. Какие тулзы каждый агент имеет право использовать.
 2. Какие runtime-параметры (retry, тиры, ревью-пайплайн) применяются.
 3. Какие модели маршрутизируются на какие роли.
@@ -17,7 +18,7 @@ Governance — это **5 JSON-файлов** в `governance/`, фиксирую
 ## Карта governance-файлов
 
 | Файл | Назначение | Меняется при |
-|------|-----------|--------------|
+| --- | --- | --- |
 | `agent-grants.json` | Канонические права тулз агента | Изменении тулз агента |
 | `tool-grants.json` | Single source для frontmatter `tools:` | Том же |
 | `runtime-policy.json` | Operational параметры Orchestrator-а | Изменении retry/тира/ревью |
@@ -34,6 +35,7 @@ Governance — это **5 JSON-файлов** в `governance/`, фиксирую
 **Eval-проверка:** drift-checker сверяет `tools:` frontmatter каждого агента с `tool-grants.json`. Расхождение = fail.
 
 **Пример (упрощённо):**
+
 ```json
 // agent-grants.json (концептуально)
 {
@@ -66,7 +68,7 @@ Governance — это **5 JSON-файлов** в `governance/`, фиксирую
 Определяет, какие ревьюеры активны на каждом тире:
 
 | Tier | Активные ревьюеры |
-|------|-------------------|
+| --- | --- |
 | TRIVIAL | none |
 | SMALL | `["PlanAuditor"]` |
 | MEDIUM | `["PlanAuditor", "AssumptionVerifier"]` |
@@ -79,7 +81,7 @@ Governance — это **5 JSON-файлов** в `governance/`, фиксирую
 Бюджет PLAN_REVIEW-итераций:
 
 | Tier | Max iterations |
-|------|---------------|
+| --- | --- |
 | TRIVIAL | — (skip) |
 | SMALL | 2 |
 | MEDIUM | 5 |
@@ -113,6 +115,7 @@ Governance — это **5 JSON-файлов** в `governance/`, фиксирую
 ### plan_review_gate_trigger_conditions
 
 Когда активировать PLAN_REVIEW:
+
 - `min_phases` — минимальное количество фаз для триггера.
 - `confidence_threshold` — порог confidence (например, 0.9).
 - Деструктивные операции в скоупе.
@@ -133,7 +136,7 @@ Governance — это **5 JSON-файлов** в `governance/`, фиксирую
 Пороговые значения и стандарты качества памяти:
 
 | Ключ | Значение | Назначение |
-|------|---------|-----------|
+| --- | --- | --- |
 | `notes_md_max_lines` | 20 | Максимум строк в NOTES.md (проверяется CI, Pass 7) |
 | `archive_completed_plans_threshold_days` | 14 | Дней до архивации закрытого плана |
 | `archive_eligible_statuses` | `["DONE","SUPERSEDED","DEFERRED"]` | Статусы планов, подлежащих авто-архивации |
@@ -145,34 +148,44 @@ Governance — это **5 JSON-файлов** в `governance/`, фиксирую
 ## model-routing.json — логические роли моделей
 
 Каждый агент в frontmatter имеет:
+
 - `model: GPT-5.4 (copilot)` — литеральная строка модели.
 - `model_role: research-capable` — логическая роль.
 
 `governance/model-routing.json` определяет роли:
+
 ```json
 {
   "research-capable": {
-    "default": "GPT-5.4 (copilot)",
+    "primary": "GPT-5.4 (copilot)",
+    "fallbacks": ["GPT-5.5 (copilot)", "Claude Opus 4.7 (copilot)"],
     "by_tier": {
-      "TRIVIAL": "GPT-5.4 mini (copilot)"
+      "TRIVIAL": {
+        "primary": "GPT-5.4 mini (copilot)",
+        "fallbacks": ["GPT-5.4 (copilot)", "Claude Sonnet 4.6 (copilot)"],
+        "cost_tier": "low",
+        "latency_tier": "fast"
+      }
     }
   }
 }
 ```
 
 **Зачем:** decoupling агентских файлов от хардкоженных моделей. Можно менять модель в одном месте, не трогая 13 агентов.
 
-**Сейчас:** runtime читает `model:` напрямую; `model_role` существует для логического индексирования, eval-выравнивания и будущей миграции.
+**Сейчас:** runtime читает `model:` напрямую при внешнем вызове (от пользователя); при внутреннем вызове Orchestrator/Planner используют `governance/model-routing.json` для вычисления нужной модели и передают её явно через параметр `model` внешних вызовов (например, `agent/runSubagent`). Поля `model_role` существуют для логического индексирования, eval-выравнивания и будущей миграции.
 
 **by_tier convention:**
-- Полный override на тир → `{"TRIVIAL": "..."}`.
-- Inherit → `{"TRIVIAL": "inherit_from: default"}`.
+
+- Полный override на тир → объектное значение (например, `{"TRIVIAL": { "primary": "GPT-5.5 (copilot)", "fallbacks": [...] }}`).
+- Inherit → объект с явным указанием `{"TRIVIAL": { "inherit_from": "default" }}`.
 
 См. [docs/agent-engineering/MODEL-ROUTING.md](../agent-engineering/MODEL-ROUTING.md).
 
 ## rename-allowlist.json
 
 Drift-чекер замечает, когда файлы появляются/исчезают. Без allowlist каждый намеренный rename ломал бы eval. Allowlist:
+
 ```json
 {
   "renames": [
@@ -211,7 +224,7 @@ flowchart TD
 ## Где жить какому знанию
 
 | Знание | Место |
-|--------|-------|
+| --- | --- |
 | Что агенту разрешено делать | `agent-grants.json` / `tool-grants.json` |
 | Сколько раз retry | `runtime-policy.json` → retry_budgets |
 | Какие ревьюеры на каком тире | `runtime-policy.json` → review_pipeline_by_tier |
@@ -223,6 +236,7 @@ flowchart TD
 ## Дополнительные governance-доки
 
 В `docs/agent-engineering/` (см. [главу 03](03-agent-roster.md) — список):
+
 - `PART-SPEC.md` — структура агентского файла.
 - `RELIABILITY-GATES.md` — verification gates (build/tests/lint).
 - `CLARIFICATION-POLICY.md` — 5 классов уточнений.