# Autopilot Roadmap — от manual review к full auto-fix

> **North Star.** `auto_dispatch_rate ≥ 85%`, `coord_touches ≤ 0.3` — AI
> обрабатывает заявку end-to-end без человека. Полный автопилот **включаем
> только когда система отлажена** (4 недели stable metrics).
>
> **Текущее состояние.** Reviewer AI (07ca) **только flag'ает** ошибки —
> add reason_codes + verdict=review_required. Человек смотрит в UI
> (Dashboard «Требует внимания»), правит вручную. Это **Phase 1**.
>
> **Следующие уровни** — ниже. Каждый следующий level включается
> **отдельной feature flag** per reason_code → точечно разрешаем AI
> подправлять когда уверены в качестве detection.

---

## Phase 1 — Manual approve (СЕЙЧАС, 2026-04-21)

**Как работает:**
```
Builder AI (07-enrich) → builds ai_work_items, ai_materials_needed
  ↓
Deterministic (07b/c/bb) → строит смету (цены, кол-во, регионы)
  ↓
Reviewer AI (07ca) → reads смету + 7 pitfalls prompt → verdict
  если есть pitfall → reason_code + verdict=review_required
  ↓
human → видит в Dashboard «Требует внимания» → clicks «Исправить» в UI
  → manually adds missing item (напр. «Вывоз мусора»)
  → saves → pipeline recalcs
```

**Что видит owner:**
- Dashboard «Сегодня» → блок «Низкий catalog match» + «Pitfalls flagged»
- Заявка → Pipeline Flow → 07ca → list reason_codes

**KPI:** сколько из flagged реально требовали human fix (precision),
сколько pitfalls AI пропустил (recall).

**Artefacts этой фазы** (сделано):
- `lib/estimate-review-contract.mjs::buildAiAuditPrompt` с 7 pitfalls
- 7 reason_codes в output schema
- Инвариант в `PIPELINE_INVARIANTS.md`

---

## Phase 2 — AI suggest (planned, нужен baseline 2-4 недели)

**Как работает (изменения):**
```
... Reviewer AI видит missing_waste_disposal
  ↓ (новое)
Suggest AI (07cb-auto-fix) → пробует построить suggested_patch:
  {
    action: "add_work_item",
    name: "Вывоз и утилизация строительного мусора",
    qty: 2, unit: "рейс",
    matched_catalog_id: 9398,
    rationale: "Detected demolition without disposal",
    reviewer_confidence: "high"
  }
  ↓
UI → Dashboard карточка «AI предлагает исправление»
  ↓ human:
    - «Принять» → applied to estimate, saved
    - «Отклонить» → logged as false-positive (feedback loop)
    - «Отредактировать» → human corrects qty/price before apply
```

**Gates перед включением:**
1. Phase 1 precision ≥ 80% (flags are accurate)
2. AI предлагает patch **с ссылкой на catalog_id** (не freeform text)
3. D1-D6 rules всё ещё проверяют patched estimate — если D-rule fail после patch, patch **отбрасывается**

**Feature flag:** `autopilot.suggest_enabled_per_reason_code`
Включаем постепенно: waste_disposal → surface_prep → ... (не все сразу).

**Что нужно сделать:**
- Новая stage `07cb-auto-fix` после 07ca (AI)
- API endpoint `POST /api/estimate/:id/suggestions/accept|reject`
- UI: новая карточка в 07ca review block
- Feedback log в `estimate_review_feedback` table
- Feature flag loader `isEnabled('autopilot.suggest_waste_disposal')`

---

## Phase 3 — AI auto-fix под gating (planned, нужен baseline Phase 2)

**Как работает:**
```
... Reviewer AI → missing_waste_disposal
  ↓
Auto-fix (gated per reason_code feature flag):
  if flag['autopilot.auto_fix.waste_disposal'] === true
     AND reviewer_confidence === 'high'
     AND catalog_id linked
     AND D-rules pass after patch
     → automatically applied без UI
  else → fall back to Phase 2 (suggest)
```

**UI signal:** в Pipeline Flow видно «AI auto-fixed: add Вывоз мусора 2 рейса» — как event в audit log, без требования approval.

**Gates:**
1. Phase 2 suggest accept_rate ≥ 90% для этого reason_code (4 недели)
2. 0 incidents где auto-fix испортил смету

**Feature flags** per reason_code:
- `autopilot.auto_fix.waste_disposal`
- `autopilot.auto_fix.surface_prep`
- ... (7 штук)

Можно также по клиенту: `autopilot.auto_fix.waste_disposal.client=brs` (для tested clients first).

---

## Phase 4 — Full autopilot (long-term goal)

**Как работает:**
- Все 7 reason_codes → auto-fix enabled по default
- Reviewer AI → Auto-fix → Dispatch (без human)
- Human касается только через `kill switch` (AI pause) или dispatch override

**North Star metrics достигнуты:**
- `auto_dispatch_rate ≥ 85%`
- `coord_touches ≤ 0.3 per issue`
- `tech_income_per_hour` растёт

**Что следить:**
- AI hallucination rate (добавил несуществующую работу)
- Client complaints (смета неадекватная)
- Rollback path — kill switch disables autopilot мгновенно

---

## Roadmap checklist (track progress)

### Phase 1 (DONE — 2026-04-21)
- [x] Reviewer AI flag 7 pitfalls
- [x] Pipeline_budget_log записывает reason_codes
- [x] Dashboard показывает «Требует внимания» с причинами
- [x] **UI чек-лист** в Справочники → ✅ Чек-лист Ревью (7 pitfalls + 13 legacy reason_codes с объяснениями when/fix/severity)
- [ ] **TODO:** tooltip прямо в Pipeline Flow 07ca reason_codes — при hover показывать `when` / `fix` из `/api/admin/pitfalls`. Сейчас только в Справочники.
- [ ] **TODO:** собрать baseline — 2 недели traffic → что AI flag'ает, что действительно требует fix (precision/recall)

### Phase 2 (planned, starts after 2-week baseline)
- [ ] `07cb-auto-fix` stage skeleton
- [ ] API endpoints `POST /api/estimate/:id/suggestions/accept|reject`
- [ ] UI карточка «AI предлагает исправление» в Pipeline Flow → 07ca block
- [ ] Feature flag: `autopilot.suggest_enabled_per_reason_code`
- [ ] Migration: `estimate_review_feedback` table
- [ ] 1 reason_code выбран для pilot (predлагаю `missing_waste_disposal` — самый простой, качество высокое)

### Phase 3 (planned, after Phase 2 stable 4 weeks)
- [ ] Auto-fix skeleton — применяет suggested_patch без UI
- [ ] D-rules проверяют patched estimate
- [ ] Per-client + per-reason_code feature flags
- [ ] Audit log events «AI auto-fixed»

### Phase 4 (long-term goal)
- [ ] All 7 reason_codes auto-fix enabled by default
- [ ] Metrics North Star met (≥ 85% / ≤ 0.3 / tech_income↑)
- [ ] Incident kill switch tested

---

## Связанные файлы
- `lib/estimate-review-contract.mjs` — Reviewer AI prompt + reason_codes
- `lib/feature-flags.mjs` — runtime флаги (autopilot.* будут здесь)
- `docs/ai/reference/PIPELINE_INVARIANTS.md` — invariants текущей фазы
- `~/.claude/projects/*/memory/project_north_star.md` — bigger picture

## История изменений
- **2026-04-21** — Roadmap создан. Phase 1 active. Owner reminder:
  «на полный автопилот включать систему когда отлажена».