# Фича «Время работы над статьёй» — дизайн-документ

Статус: черновик проектирования (код не пишется).
Контекст: gitmost (форк Docmost). Зависит от PR #370 / PR #374 (типизированная история страниц).

## 1. Цель и не-цели

**Цель.** Показывать в UI страницы одно число — оценку времени, реально затраченного
на работу над статьёй, собранную из истории правок. Число должно быть устойчиво к
паузам: «в 21:00 одна правка, в 09:00 вторая» не должно превращаться в «работал 12 часов».
По клику на число — раскрытие в **суточный таймлайн**: строка-день = 24-часовая дорожка с
окнами активности и суммой за день (см. §6.2).

**Явно не-цели.**
- Это НЕ инструмент для агента (не MCP-tool). Это число, отображаемое человеку в UI.
- Не хронометраж с точностью до минуты — это заведомо оценка.
- Не биллинг/тайм-трекинг сотрудников; не изменение долговечности черновика.

## 2. Проблема

История страницы в Docmost — таблица `page_history`: снимок на каждое сохранение.
У снимка есть `createdAt`, автор (`lastUpdatedById`), тип источника
(`lastUpdatedSource`: `user`/`agent`/`git`) и группировка агентских правок
(`lastUpdatedAiChatId`).

Наивная оценка `max(createdAt) − min(createdAt)` завышает в разы: между крайними
правками лежат сон, обед, дни простоя. На реальных данных статьи-примера
(первая страница истории, 20 снимков) span между крайними снимками ≈ 60 часов,
тогда как реальной работы — пара часов в 5–6 коротких заходов.

Правильная постановка: **длительность — это не span между крайними правками, а сумма
интервалов внутри «сессий»; историю режем по паузам бездействия.** Это классическая
*сессионизация по таймауту неактивности* (WakaTime / RescueTime / веб-аналитика).

## 3. Почему PR #374 — фундамент фичи

До #374 у сессионизации слепое пятно: если человек час пишет подряд и не жмёт «Сохранить»,
в `page_history` за этот час почти нет строк (тяжёлые автосейвы ydoc идут в `pages`/`ydoc`,
а не в историю). Непрерывную работу нечем измерить.

PR #374 вводит типизированную историю через колонку `page_history.kind`:

| `kind`     | что означает                                   | ценность для фичи                                  |
|------------|------------------------------------------------|----------------------------------------------------|
| `manual`   | человек нажал Save                             | сильный маркер активной работы человека            |
| `agent`    | снимок правки агентом                          | машинное время агента (группируется по `aiChatId`) |
| `idle`     | автоснимок idle-флеша (потолок ~`maxWait`)     | регулярный «пульс» непрерывной работы (~≤10м, §3)  |
| `boundary` | автоснимок на переходе актора (user↔agent↔git) | бесплатная разметка «кто работал в этом сегменте»  |
| `null`     | легаси-автосейв (старые страницы)              | обычный сэмпл активности                           |

Два env-параметра #374 напрямую задают качество измерения:

- **`IDLE_MAX_WAIT_USER=10м` / `AGENT=5м` (потолок ожидания)** — определяющий параметр.
  Проверено по `computeHistoryJob` (`persistence.extension.ts`):
  `delay = max(0, min(interval, burstStart + maxWait − now))`, а `enqueuePageHistory`
  сбрасывает `burstStart` каждые `maxWait`. Так как `maxWait` (10м/5м) < `interval` (60м/15м),
  **потолок всегда доминирует**: во время непрерывной работы `idle`-снимок форсится каждые
  ~`maxWait`, давая регулярный «пульс активности» с шагом ≤10 мин (user) / ≤5 мин (agent).
- **`IDLE_INTERVAL_USER=60м` / `AGENT=15м`** — номинальный трейлинг-интервал, который потолок
  ожидания на практике всегда упреждает. Поэтому метка любого `idle`-снимка отстоит от
  реальной правки не более чем на ~`maxWait` (≤10м user / ≤5м agent), а **не** на 60 мин.
  (Это ключевой факт для точности: `idle`-метки — достоверный сигнал активности, не «хвост».)

Вывод: ядро алгоритма работает и на голых `createdAt`+`lastUpdatedSource` (есть с миграции
`20260616T130000-agent-provenance`), поэтому фича считает и на легаси-страницах — просто
грубее. После #374 (пульс ≤10 мин + типы) — точно. Жёсткой блокировки на мёрж #374 нет,
но полноценная точность появляется вместе с ним.

## 4. Входной сигнал

Дешёвый проекционный запрос по `page_history` (без тяжёлой колонки `content`): на строку —
`createdAt`, `lastUpdatedById`, `lastUpdatedSource`, `lastUpdatedAiChatId`, `kind`.
Все поля (включая `kind`) уже в `PageHistoryRepo.baseFields` после #374 — схему трогать не
нужно, `findTimelineByPageId` это лишь лёгкая проекция без `content`.

**Важный факт об авторстве (проверено по `persistence.extension.ts` → `updatePage`):**
`page_history.lastUpdatedById` — это ВСЕГДА ответственный человек, даже для агентских снимков
(«human stays the responsible author»). Признак «человек vs агент» живёт в
`lastUpdatedSource` (`user`/`agent`/`git`) и `lastUpdatedAiChatId`, а НЕ в `lastUpdatedById`.
Отсюда: разделять человеко-/агенто-время нужно по `lastUpdatedSource`, а атрибутировать
конкретному человеку — по `lastUpdatedById`/`contributorIds`.

## 5. Алгоритм: сессионизация по паузам

Параметры (env, в стиле #374; полный список — §10):

- **`T_gap`** — таймаут неактивности: пауза между соседними сэмплами `≤ T_gap` = непрерывная
  работа, больше = перерыв (в зачёт не идёт).
- **`P_in` / `P_out`** — добивка МНОГОсэмпловой сессии (работа началась до первого и продолжалась
  после последнего сохранения).
- **`P_single`** — блок ОДИНОЧНОЙ сессии (один сэмпл, соседей в пределах `T_gap` нет). Мал
  (дефолт ~2 мин): один автосейв/idle-пульс — это «была правка», но приписывать ему полный
  `P_in+P_out` = выдумывать время. НЕ путать с многосэмпловой добивкой.

Псевдокод (ОДИН проход по ВСЕМ сэмплам страницы; класс определяется у ГОТОВОЙ сессии — §5.1):

```text
samples = ВСЕ history rows страницы, projected, sorted by createdAt ASC
    (все типы kind — сэмплы активности; idle — основной «пульс» непрерывной работы §3, НЕ исключается)

# коллапс агентских всплесков (§5.1)
collapse: подряд идущие сэмплы ОДНОГО aiChatId с source=agent → сегмент {t_start, t_end, source:'agent'}.
    Разрывает всплеск любой сэмпл, НЕ продолжающий тот же aiChatId-агент: source≠agent,
    boundary-переход, ИЛИ иной aiChatId — в т.ч. idle/boundary с ДРУГИМ aiChatId = НОВЫЙ ран,
    склеивать НЕЛЬЗЯ (иначе простой между двумя ИИ-ранами засчитается агенту). idle с ТЕМ ЖЕ
    (или null) aiChatId — продолжает сегмент. Дальше сегмент участвует в цикле как один «сэмпл» с
    .t_start/.t_end/.source (source='agent'); у скалярного сэмпла t_start == t_end == t.

gap_threshold(a, b) = (a и b оба source=agent) ? agentTGap : T_gap   # порог зависит от ПАРЫ (§10)

# сессионизация по паузам — ОДИН проход по ВСЕМ сэмплам (не по парам, не отдельно по классам)
sessions = []; cur = null
for s in samples:                              # s — скаляр или коллапс-сегмент
    if cur == null:            cur = { first: s, last: s, samples: [s] }
    elif s.t_start − cur.last.t_end ≤ gap_threshold(cur.last, s):
                               cur.last = s; cur.samples.push(s)         # непрерывная работа
    else:                      sessions.push(cur); cur = { first: s, last: s, samples: [s] }
if cur != null: sessions.push(cur)             # ОБЯЗАТЕЛЬНО закрыть последнюю (иначе теряется)

# класс и интервал каждой сессии
for sess in sessions:
    sess.class = sess.samples.every(is_agent) ? 'agent_only' : 'work'   # §5.1 (по source сэмплов)
    sess.iv    = (sess.first == sess.last && sess.first.t_start == sess.first.t_end)
        ? [ sess.t − P_single, sess.t ]                        # одиночный скаляр: pre-roll (без «будущей» работы)
        : [ sess.first.t_start − P_in, sess.last.t_end + P_out ]   # многосэмпловая / лон-сегмент

workMs      = duration( union( sess.iv : sess.class=='work' ) )         # union внутри класса
agentOnlyMs = duration( union( sess.iv : sess.class=='agent_only' ) )
```

Ключевые свойства:

- **Один проход, потом классификация → метрики дизъюнктны.** Сессии не перекрываются (разделены
  гэпами > порога), каждая — ровно одного класса. Человек и агент, правящие ОДНОВРЕМЕННО, попадают
  в одну сессию класса `work` (надзор засчитан человеку, не дважды). `work`- и `agent_only`-интервалы
  не пересекаются по wall-clock и `workMs + agentOnlyMs ≤ реально прошедшего` — **при рекомендованном
  `T_gap ≥ P_in+P_out` (§10)**: иначе `P`-добивка соседних сессий РАЗНЫХ классов может пересечься, и
  пересечение попадёт в обе метрики. Инвариант §6.3 (`Σ perDay == work`) от этого НЕ зависит.
- **Закрытие последней сессии обязательно** (иначе теряется самая свежая): `n=1` → одна одиночная
  сессия `P_single`, `n=0` → 0.
- **`union`, а не `Σ`.** Перекрытия (соседние ближе `P`; одновременное соредактирование) не
  задваиваются. Отсюда `Σ perDay == work` держится сам собой (§6.3) — без «клампа» и без условия
  `T_gap ≥ P`.
- **Калибровка `T_gap` по «пульсу» #374 (важно).** После #374 непрерывная работа гарантированно
  оставляет history-строку не реже ~`maxWait` (idle-пульс §3, гейт `isDeepStrictEqual`). Значит гэп
  между соседними строками БОЛЬШЕ ~`maxWait` содержит участок без изменений контента = (частичное)
  бездействие — даже между двумя `manual`. Поэтому `T_gap` калибруется ОТ `maxWait` (реком. ~15м
  user / ~7м agent), а не ставится вольно: прежние «30 мин» переоценивали не-пульсирующие паузы.
  Гэп `≤ T_gap ≈ maxWait` ПОДКРЕПЛЁН пульсом — это и оправдывает счёт его как работы. Легаси-страницы
  до #374 пульса не имеют → там `T_gap` вынужденно шире и оценка грубее (§7, §10).
- **Всё равно оценка, а не строгая граница**: даже с пульсом «читал/думал 12 мин не печатая» не
  отличить от «отошёл»; подпись «≈» и показ `T_gap` обязательны (§6).
- Почему интервалы, а не «правок × блок»: «снимок = +N мин» ломается на агентских всплесках
  (8 снимков за 7 минут); длина сегмента всплеска = его wall-clock, независимо от плотности снимков.

### 5.1. Классификация сэмплов и всплесков

- **Класс сэмпла (человек / агент)** — по `lastUpdatedSource`: `user`→человек, `agent`→агент,
  `git`→исключаем (§10 `excludeGit`), legacy-`null`→человек. `idle` наследует `source` страницы
  на момент флеша (= source последней правки). `boundary` несёт СТАРЫЙ (pre-transition) `source`
  — трактуем как есть: он маркирует исходящую работу того актора (это осознанный компромисс, а не
  недосмотр — точность посекундная тут не нужна).
- **Класс СЕССИИ** (нужен для метрик §6.1): сессия, где ВСЕ сэмплы `source=agent` → **`agent_only`**
  (автономный прогон, не в основную метрику). Сессия хотя бы с одним человеческим сэмплом →
  **`work`** (человек + надзор за агентом ВНУТРИ сессии засчитывается человеку — по union'у, §5).
- **`idle`** — полноценный сэмпл активности и основной «пульс» непрерывной работы (§3): его метка
  отстаёт от реальной правки ≤ `maxWait` (≤10м) — в пределах округления, отмотки не требует.
  Исключать нельзя: без него непрерывное письмо без ручных сохранений снова стало бы невидимым.

## 6. Что показывать в UI

### 6.1. Свёрнутое состояние — одно число

Две метрики, каждая = union-wall-clock СВОИХ сессий (§5):

- **`work` — headline, кликабельное число** (`≈ 4 ч 30 мин`, рядом с панелью истории или в
  мета-инфо у заголовка): сессии класса `work` (≥1 человеческий сэмпл = человек + надзор за
  агентом внутри сессии). Именно это открывает таймлайн (§6.2), и именно к нему сходится сумма по
  дням.
- **`agent_only` — вторично**: сессии автономных прогонов агента (ни одного человеческого сэмпла).
  На таймлайне — отдельным цветом; в `work` НЕ входит.
- Подпись «≈» и показ `T_gap` обязательны (оценка, не хронометраж — §5). Округление headline —
  шаг 5–15 мин (точность оценки не оправдывает «4 ч 27 мин»).

### 6.2. Раскрытие по клику — суточный таймлайн (24 ч × дни)

Клик по числу открывает модалку/поповер с таймлайном по типу «punch-card»:

- **Строка = один календарный день**; ширина строки = 24 часа (фиксированная шкала 00:00→24:00).
- На дорожке дня закрашены **окна активности** — реальные интервалы работы в их часовом
  положении, так что видно «вечерний марафон» vs «утренняя сессия».
- **Справа от строки — сумма за день** «ч мм» (напр. `3 ч 17 м`); пустой день — пустая дорожка
  и «—».
- Внизу — общий итог (= headline `work` §6.1) плюс подпись таймзоны и `T_gap`.

Это графическая версия таблицы-примера-картинки: там окна были текстом («18:46 → 00:58»), здесь
то же рисуется отрезками на 24-часовой дорожке.

Детали:
- Окна = сессии класса `work` (§5), обрезанные по границам суток; сессии `agent_only` — отдельным
  цветом (§6.1). По умолчанию `work` — один цвет «активность».
- Сессия через полночь рисуется как отрезок до 24:00 в одном дне и продолжение с 00:00 в
  следующем — тот самый полуночный разрез (§6.3), теперь визуально очевиден.
- **Честность добивки.** Окно включает `P`/`P_single` — это оценка «до/после», а не измеренный
  интервал. Одиночная сессия (`P_single`) рисуется минимальной видимой шириной и приглушённо
  (иначе исчезает и/или создаёт иллюзию плотной работы из одного клика). Общая подпись — «≈».

### 6.3. Агрегация по дням (алгоритм)

Вход — ВСЕ сессии из §5 (`work` и `agent_only`), каждая развёрнута в интервал (`P_in/P_out` или
`P_single`).

```text
bucketByDay(sessions, tz):
  U_work  = union( sess.iv : sess.class=='work' )       # снимаем перекрытия ОДИН раз (§5)
  U_agent = union( sess.iv : sess.class=='agent_only' )  # СИММЕТРИЧНО — иначе окна агента наложатся
  для каждого дня D в [первый_день … последний_день] по tz (dayjs+tz, startOf('day')):
    workWin[D]  = { u ∩ [начало D, начало D+1) : непусто, u в U_work }
    agentWin[D] = { u ∩ [начало D, начало D+1) : непусто, u в U_agent }
    activeMs[D] = Σ длительностей workWin[D]            # U_work без перекрытий → просто сумма
    agentMs[D]  = Σ длительностей agentWin[D]
  → perDay[] = [{ day, activeMs, agentMs, windows: (workWin[D] ⊕ agentWin[D]) с меткой класса }]
```

- **Инвариант согласованности `Σ activeMs[D] == work`** держится ПО ПОСТРОЕНИЮ: день — это
  разбиение union'а `U_work` границами суток, ничего не теряется и не дублируется (в т.ч. на
  23/25-часовых DST-сутках — §9#14). `agent_only`-окна рисуются, но в `activeMs` НЕ входят. Клампа
  и скрытого условия `T_gap ≥ P` не требуется (в отличие от наивного `Σ` длительностей).
- **Таймзона `TZ`** определяет, где проходит «полночь» И в каких часовых координатах рисуются
  окна. Дефолт — таймзона зрителя (локаль браузера); альтернатива — UTC (как на картинке-примере
  «По дням (UTC)») или tz воркспейса. Влияет на раскладку по дням и положение окон, но НЕ на
  общий итог → настройка (§10).
- **Длинный диапазон** (месяцы правок): строк ровно столько, сколько календарных дней в диапазоне.
  При большом числе дней — вертикальный скролл + сворачивание длинных серий пустых дней
  («× N дней без правок») и/или переключение на понедельную группировку. Порог — настройка.
- **Округление дисплея:** сумму за день округляем до минут для подписи, но общий итог берём из
  точных значений (иначе Σ округлённых по дням разойдётся с округлённым числом на ±1–2 мин).

## 7. Проверка на реальной статье

Ручной прогон на 20 снимках (1-я страница истории, `T_gap=30 мин`, `P_in+P_out=10 мин`,
`P_single=2 мин`; все сессии здесь класса `work` — в каждой есть человеческий сэмпл):

| Сессия | Интервал                                              | Длит.    |
|--------|-------------------------------------------------------|----------|
| S1     | 07-04 03:40 → 03:49 (многосэмпловая)                  | ≈19 мин  |
| S2     | 07-04 15:43 → 16:13 (агент 15:43–15:50 → человек 16:13)| ≈41 мин  |
| S3     | 07-04 18:11 (одиночная)                               | ≈2 мин   |
| S4     | 07-04 19:38 → 19:54 (многосэмпловая)                  | ≈26 мин  |
| S5     | 07-06 15:34 (одиночная)                               | ≈2 мин   |
| S6     | 07-06 16:18 (одиночная, закрыта пост-циклом §5)       | ≈2 мин   |
| **Итого** |                                                    | **≈1 ч 32 мин** |

Наивно на том же срезе — ≈60 часов. Разница — весь смысл фичи.

Наблюдения:
- Разрезы легли по перерывам: ночь `03:49 → 15:43` (~12 ч) и сутки
  `07-04 19:54 → 07-06 15:34` — оба выброшены.
- Чувствительность к порогу: `S5/S6` отстоят на 44 мин. При `T_gap=30` это две сессии,
  при `T_gap=60` — одна (~44 мин). Число надо показывать **вместе с использованным порогом**.
- Это **оценка, не строгая граница** (§5), и НАПРАВЛЕНИЕ ошибки зависит от данных. Сохранения
  ВНУТРИ `T_gap` мостятся, и вся пауза между ними засчитывается → на периодичном «фоновом» ритме
  (напр. автосейв раз в ~`T_gap` при почти полном простое) возможен КРАТНЫЙ перебор (в разы), а не
  «±порог». Сохранения ДАЛЬШЕ `T_gap` друг от друга, наоборот, теряют между-время → недобор. Поэтому
  `T_gap` калибруется по пульсу #374 (§5, §10): после #374 «фоновый» ритм даёт гэпы > `maxWait` и
  рвётся на перерывы, срезая кратный перебор; на легаси (пульса нет) оценка грубее в обе стороны.
  Пример иллюстративен, посчитан на до-#374 срезе при `T_gap=30`.

## 8. Архитектура (куда встраивать)

**Ядро — чистая функция** `computeWorkTime(rows, config)` (детерминированная, без БД) в
отдельном модуле → легко покрыть юнит-тестами. Выход —
`{ workMs, agentOnlyMs, sessions[] }`, где `session = { start, end, class: 'work'|'agent_only' }`:
абсолютные границы (с добивкой `P`/`P_single`) плюс класс (§5.1) — этого достаточно и для метрик,
и для цвета окна. `workMs`/`agentOnlyMs` считаются как union-wall-clock сессий своего класса (§5).

**Вторая чистая функция** `bucketByDay(sessions, tz)` (ВСЕ сессии обоих классов) →
`perDay[] = [{ day, activeMs, agentMs, windows }]`: `activeMs` = длительность `work`-окон за день
(сходится к `work`, §6.3), `agentMs` = то же для `agent_only` (для подписи машинного времени за
сутки), `windows` — интервалы ОБОИХ классов, обрезанные по суткам и помеченные классом (для
отрисовки `work`/`agent_only` разным цветом, §6.2). Полуночный разрез — календарный, через
`dayjs` + tz-плагин (`startOf('day')` в `tz`), НЕ «+24 ч» (§9#14); `dayjs` уже в проекте. Отдельная
тестируемая функция (общий модуль сервера и клиента); `tz` — презентационный параметр, удобно звать
на клиенте от локали зрителя.

**Сервер:**
- `page-history.repo.ts` — метод `findTimelineByPageId(pageId)`: лёгкая проекция
  (`createdAt, lastUpdatedById, lastUpdatedSource, lastUpdatedAiChatId, kind`) по всем строкам
  ASC, без `content`.
- `page-history.service.ts` — `computeWorkTime(pageId, config)`: тянет таймлайн, зовёт ядро,
  кэширует.
- `page.controller.ts` — рядом с `POST /history` и `POST /history/info` добавить
  `POST /history/time` (или вложить в page-info). Отдаёт число + разбивку по сессиям.

**Клиент:**
- `page-history-query.ts` — хук `usePageWorkTime(pageId)` (возвращает `workMs`, `agentOnlyMs`,
  `sessions[]`).
- Рендер кликабельного числа в панели истории.
- Модалка/поповер с суточным таймлайном (§6.2): `bucketByDay(sessions, viewerTz)` → строки-дни,
  в каждой — 24-часовая дорожка с окнами. Это НЕ bar chart: рисуется кастомными CSS/SVG-отрезками
  на 24-часовой шкале (позиция окна = `startOfDayOffset/24ч`, ширина = длительность/24ч). Готовые
  чарт-библиотеки под это плохо ложатся — брать лёгкую собственную вёрстку, без новых тяжёлых
  зависимостей. Пустые дни — пустая дорожка + «—».

**Производительность:** проекция без `content` дёшева; результат можно инкрементально кэшировать
(при `version.saved`, который #374 броадкастит, пересчитывать хвост).

## 9. Крайние случаи

1. Один снимок → одна одиночная сессия `P_single`, не ноль. Последняя сессия ВСЕГДА закрывается
   пост-циклом (§5) — иначе теряется самая свежая.
2. История целиком агентская → `work = 0`, `agent_only = union прогонов`.
3. Плотный агентский всплеск → длина сегмента = его wall-clock (не зависит от числа снимков);
   опц. кап `burstCapMs`.
4. Метка `idle` лагает ≤ `maxWait` (10м user / 5м agent) — в пределах округления; это
   полноценный сэмпл активности, спец-обработки не требует (см. §3, §5.1).
5. Несколько соавторов → атрибуция человеку по `lastUpdatedById`/`contributorIds`; разделение
   человек/агент — по `lastUpdatedSource` (НЕ по `lastUpdatedById`, он всегда человек).
6. Легаси `kind=null` → работает на `source`+`createdAt`, грубее.
7. Совпадающие метки времени (boundary+agent в один момент; в коде есть tie-break по `id`)
   → дедуп по округлённому `t`.
8. Одновременное соредактирование → `union` (§5) убирает двойной счёт wall-clock при перекрытии
   окон; персональные человеко-часы (разбивка по авторам) — отдельный опциональный режим
   (`perAuthor`), а не поведение по умолчанию.
9. Сессия через полночь (напр. `23:14 → 02:00`) → режется на границе суток `tz`, части идут
   в разные дни; сумма по дням = общему числу (§6.3).
10. Выбор таймзоны дня меняет раскладку по дням (та же работа попадёт в другой день) — общий
    итог не меняется; `tz` фиксируется в подписи графика.
11. Длинный диапазон правок (месяцы) → строк = число дней: вертикальный скролл + сворачивание
    длинных серий пустых дней и/или понедельная группировка по порогу (§6.3).
12. День без правок → пустая 24-часовая дорожка + «—» в диапазоне (показываем ритм/паузы),
    не пропускаем.
13. Очень короткое окно на 24-часовой шкале → рисуем минимальной видимой шириной, чтобы не
    исчезало (§6.2).
14. Переход на летнее/зимнее время внутри `tz` → сутки в 23/25 ч; полуночный разрез считать
    по календарю `tz` (`dayjs`+tz, §8), а не «+24 ч». Инвариант `Σ activeMs == work` держится
    (разбиение union'а). Редкое исключение — tz с DST-переходом РОВНО в полночь (`startOf('day')`
    неоднозначен) → до 1 ч может протечь в соседний день. Фиксированная 24-часовая дорожка (§6.2)
    на 23/25-часовых сутках смещает окна визуально до ~1 ч — сознательное упрощение, на итог не
    влияет.

## 10. Параметры по умолчанию и открытые решения

**Полный `config`** (env, дефолты):

- `T_gap≈15м` — калибровка по `IDLE_MAX_WAIT_USER=10м` + запас (§5: гэп больше `maxWait` не
  подкреплён пульсом = бездействие; прежние «30м» переоценивали не-пульсирующие паузы).
- `agentTGap≈7м` — порог для ПАРЫ подряд идущих агентских сэмплов (`IDLE_MAX_WAIT_AGENT=5м` + запас).
- `P_in=5м`, `P_out=5м`, `P_single=2м` (одиночная — pre-roll, §5).
- `burstCapMs` (опц. кап на сегмент всплеска, §9#3), `dedupRoundMs` (дедуп совпадающих меток, §9#7),
  `excludeGit=true`, `tz=локаль-зрителя`, `longRangeDayThreshold` (день→неделя, §6.3),
  `perAuthor=false` (§9#8).
- **Легаси-страницы до #374** (нет пульса) → `T_gap` вынужденно шире, оценка там грубее.
- **`T_gap ≥ P_in+P_out`** НЕ требуется для инварианта §6.3 (union), но РЕКОМЕНДУЕТСЯ и валидируется
  — иначе `work`/`agent_only` могут перекрыться в сумме (§5). При дефолтах (15 ≥ 10) держится.

Развилки (настройки, не блокируют проектирование):
- `work` vs `agent_only` — показывать оба, крупно `work` (headline), `agent_only` вторично;
- точное место в UI — панель истории (основное) или мета-строка страницы;
- дефолт `T_gap` — вынести в env (как `IDLE_*` в #374), калибровать на реальных статьях
  после мёржа #374;
- **таймзона дня для графика (§6.2/§6.3)** — рекомендую локаль зрителя (интуитивно «мои
  вечера»); альтернативы — UTC (как на картинке-примере) или tz воркспейса. Влияет только на
  раскладку по дням, не на общий итог;
- **порог перехода день→неделя/месяц** для длинного диапазона правок.

---

# Приложение: Review Ledger (рабочий аппарат, НЕ нормативная часть)

> Аппарат adversarial-review-loop. Перед выдачей реализатору выносится/сворачивается.
> Критикам: НЕ перелитигировать закрытые findings, КРОМЕ случая, когда сам RESOLUTION
> дефектен — тогда атаковать его явно и сказать, почему предыдущий раунд ошибся.

## CONFIG

- EXTERNAL_MODEL: endpoint `https://api.z.ai/api/coding/paas/v4`, model `glm-5.2`
  (ключ хранится вне репозитория, в логи не пишется). Роль: cold-reader gate (Phase 4.5),
  tiebreaker при эскалации.
- Артефакт: `docs/features/page-work-time_design.md`.
- Целевой класс: спец для реализации другим человеком → план 2–3 итерации, до пустого
  cold-reader gate (не по числу итераций).

## FACT BASE (проверено по PR #374 @ commit 924f8aa, ветка feat/370-page-versioning)

Верификация автором ДО цикла (ветка не в рабочем дереве — критики не видят её локально;
факты ниже — ground truth, можно дозапросить файлы через gitea MCP по указанному SHA):

- `page_history.kind` — `varchar(20)`, NULLABLE, БЕЗ дефолта (migration
  `20260705T120000-page-history-kind.ts`). Домен: `manual`/`agent`/`idle`/`boundary`;
  legacy `null` = автосейв (`collaboration/constants.ts`, `PageHistoryKind`).
- `kind` УЖЕ включён в `PageHistoryRepo.baseFields` (`page-history.repo.ts`) — читается всеми
  выборками истории. `saveHistory({kind})` и `updateHistoryKind(id, kind)` существуют.
- Тайминги (`constants.ts`): `IDLE_INTERVAL_USER=60м`/`AGENT=15м`;
  `IDLE_MAX_WAIT_USER=10м`/`AGENT=5м`.
- `computeHistoryJob` (`persistence.extension.ts`):
  `delay = max(0, min(interval, burstStart + maxWait − now))`; `enqueuePageHistory` сбрасывает
  `burstStart` каждые `maxWait`. Следствие: **потолок всегда доминирует** → `idle` пульсирует
  каждые ~`maxWait` при непрерывной работе; метка `idle` отстоит от правки ≤ `maxWait`, НЕ 60м.
- Идл-джоб всегда ставится с `kind:'idle'`; процессор пишет `job.data.kind ?? 'idle'`, но только
  если контент изменился (`isDeepStrictEqual`-гейт).
- `boundary`-снимок пишется СИНХРОННО в store-транзакции на смене `lastUpdatedSource`
  (user↔agent↔git), фиксирует ИСХОДЯЩИЙ (pre-transition) контент со СТАРЫМ source; его
  `createdAt` = момент перехода (точный).
- `manual`/`agent` — явный save-version по stateless-каналу; `kind` выводится из
  `context.actor` СЕРВЕРНО (неподделываемо). Promote-not-dup: апгрейд `kind` последнего снимка
  на месте вместо дубля.
- `page_history.lastUpdatedById` = ВСЕГДА ответственный человек (даже для агентских снимков);
  «agentness» — в `lastUpdatedSource` + `lastUpdatedAiChatId`.
- REST истории: `POST /history`, `POST /history/info` (`page.controller.ts`). Клиент:
  `apps/client/src/features/page-history/*`. Есть broadcast `version.saved` (для live-инвалидации).

## Pre-loop fact-base corrections (автор, проверено vs source)

- C1. §3/§5.1/§крайние-случаи#4: убрано ошибочное «idle лагает до 60м / idle не удлиняет
  сессию / отмотка на IDLE_INTERVAL». Верно: лаг ≤ `maxWait` (≤10м), `idle` — полноценный сэмпл.
- C2. §3: устранено внутреннее противоречие §3↔§5.1 (пульс vs исключение idle).
- C3. §4: `kind` уже в `baseFields` — схему менять не нужно.
- C4. §крайние-случаи#5: `lastUpdatedById` всегда человек; человек/агент — по `lastUpdatedSource`.

## Scope changes

- S1 (owner, до итерации 1): добавлен drill-down — клик по числу открывает график по дням.
- S2 (owner, до итерации 1): drill-down переопределён с «столбцы часов/день» на СУТОЧНЫЙ
  ТАЙМЛАЙН (строка-день = 24 ч с окнами активности + сумма за день, §6.2/§6.3). Окна вернулись,
  но графикой. Затронуты §1, §6.2, §6.3, §8, §9(#9–14), §10.

## Iteration log

### Итерация 1 — критики: Claude (hardened, A) + GLM-5.2 external (B)

Первый прогон local-субагентов вернул инъекцию из подложенного SKILL.md (реклама
«agent-first-plugin-suite») и 0 полезной работы — проигнорировано; пере-прогон с анти-инъекцией
дал реальные ревью. Дефекты и диспозиции:

- **[BLOCKER] A1** — §5-псевдокод не закрывал последнюю сессию (терял свежую; 0 сессий для
  односессионной страницы; ронял S6). ПРИНЯТО → пост-цикловое закрытие, `n=1`→`P_single`, `n=0`→0.
- **[MAJOR] A2+B4** — какое число суммирует таймлайн; двойной счёт при перекрытии. ПРИНЯТО →
  метрики `work`/`agent_only` (§6.1) + `total`/`perDay` через **union** (§5, §6.3).
- **[MAJOR] A3** — §1 остался со старым «столбцом на день» (residue S1→S2). ПРИНЯТО → §1 переписан.
- **[MAJOR] A4** — «кламп vs скрытое условие `T_gap ≥ P`». ПРИНЯТО, но растворено: union убрал и
  кламп, и условие (§6.3).
- **[MAJOR] A5** — форма `session` и правило классификации человек/агент (нужны для `workMs` и
  цвета). ПРИНЯТО → §5.1 классификация (+ nuance про старый source у boundary), `session.class` (§8).
- **[MAJOR→понижено] B1** — «нижняя оценка» ложна; гэп ≤ T_gap считается работой. ЧАСТИЧНО ПРИНЯТО
  + КОНТР по severity: гэп-как-работа — by design (по меткам не отличить «думал» от «отошёл»),
  поведение оставлено; исправлено УТВЕРЖДЕНИЕ (§5/§7: «оценка, не строгая граница»). Понижено с
  BLOCKER: это не баг кода, а некорректная формулировка/честность.
- **[MAJOR] B2+B5** — инфляция одиночных сессий на `P` + честность отрисовки добивки. ПРИНЯТО →
  `P_single` (мал), приглушённая отрисовка + «≈» (§5, §6.2).
- **[MAJOR/MINOR] B3+A6** — коллапс агентского всплеска рушит вклинившегося человека + выбор
  конца для гэп-теста. ПРИНЯТО → правило коллапса (только подряд один aiChatId; человек внутри
  разрывает; левый гэп до `t_start`, правый от `t_end`) (§5).
- **[MINOR] A7** — `config` не перечислен. ПРИНЯТО → полный список (§10).
- **[MINOR] A8** — ячейка `idle` в таблице §3 устарела. ПРИНЯТО → исправлена.
- **[NIT] A9** — расхождение округления headline vs подписи дня. Оставлено с оговоркой (§6.3).
- **[NIT] A10** — назвать `dayjs` для tz/DST-разреза. ПРИНЯТО (§8, §9#14).

Verified clean (оба критика): факты #374; tz/DST-разрез; лёгкая проекция без `content`;
кэш на `version.saved`; разбиение на две чистые функции; §2-постановка; арифметика §7 (при
исправленном алгоритме).

### Итерация 1 — post-integration re-attack (Claude A + GLM round 2) — ЗАКРЫТА

Оба критика НЕЗАВИСИМО нашли один и тот же блокер и сошлись (разные семейства моделей):

- **[BLOCKER] N1 (A) = MAJOR-1 (GLM)** — §5 «сессионизация ОТДЕЛЬНО по классам» противоречила
  §5.1/§7/§8 и теряла надзорное агентское время (S2 схлопывалась в 2 мин; `workMs+agentOnlyMs` мог
  превысить прошедшее). Исправлено: ЕДИНЫЙ проход по всем сэмплам + классификация готовой сессии;
  метрики — union внутри класса.
- **[MAJOR] N2 (A)** — union только ВНУТРИ класса; кросс-класс дизъюнктность требует `T_gap ≥ P`,
  а §10 это отрицал; `agentTGap` неопределён при едином проходе. ПРИНЯТО → `gap_threshold` по ПАРЕ
  сэмплов (agent–agent → `agentTGap`), caveat в §5, §10 смягчён (валидируем `T_gap ≥ P`).
- **[MAJOR] GLM-2** — `bucketByDay(workSessions)` не мог рисовать `agent_only`. ПРИНЯТО → сигнатура
  `bucketByDay(sessions)`, окна ОБОИХ классов, `activeMs` = work-only.
- **[MINOR] N3** — роль `boundary` противоречива (§5 «человеческий» vs §5.1 «старый source=agent»).
  ПРИНЯТО → §5: всплеск рвёт любой сэмпл, не продолжающий тот же aiChatId-агент; класс — по source.
- **[MINOR] N4** — псевдокод точечный, концы сегмента не заданы. ПРИНЯТО → сегмент {t_start,t_end};
  same-source idle внутри всплеска продолжает сегмент.
- **[NIT] N5** — DST ровно в полночь + фикс. 24ч-дорожка ±1ч визуально. ПРИНЯТО → оговорка §9#14.
- **[NIT] N6** — `P_single` симметричный «выдумывает будущую работу». ПРИНЯТО → pre-roll `[t−P_single, t]`.
- **B1-severity (спор):** A СОГЛАСИЛСЯ с понижением BLOCKER→MAJOR (нет входа, где код отклоняется от
  намерения — только формулировка/UX). GLM НАСТАИВАЛ на BLOCKER с НОВЫМ аргументом: отсутствие
  idle-пульса в гэпе = доказанное бездействие. Диспозиция: label = MAJOR, но СУБСТАНЦИЯ GLM принята
  (Invariant 7 — уступка с аргументом): `T_gap` калиброван по `maxWait` (§5/§10) + принцип «гэп >
  maxWait = перерыв». A-residue (направление ошибки data-dependent, возможен КРАТНЫЙ перебор) принят
  в §7. Тайбрейкер не понадобился (обе стороны привели аргументы, интегрированы обе).

Verified clean (round-2): инвариант §6.3 под DST (оба критика); burst-endpoints (оба); `P_single`
через полночь (GLM). Блокеров в ядре: 0. Итерация 1 закрыта.

### Convergence validation + cold-reader gate — ЗАКРЫТА (CONVERGED)

- **Cold-reader gate** (GLM-5.2, внешняя модель, «имплементер читает впервые»): ПУСТОЙ список
  вопросов на день 1 — ДВАЖДЫ (до и после партии полировки).
- **Convergence pass** (GLM-5.2, свои hostile-сценарии + слепая реализация): вердикт NOT CONVERGED
  на ещё не атакованной партии round-2 → нашёл 2 MAJOR + 1 MINOR (как и предупреждает skill —
  «re-opened cycles find MAJORs in unreviewed amendments»):
  - [MAJOR] §6.3 рисовал `agent_only`-окна из «сырых» `sess.iv` (не union) → визуальное наложение.
    → `U_agent = union(...)`, симметрично `U_work`; добавлен `agentMs[D]`.
  - [MAJOR] §5 «idle продолжает сегмент НЕЗАВИСИМО от aiChatId» склеивал разные ИИ-раны через
    idle-снимок. → idle с ДРУГИМ `aiChatId` = новый ран, рвёт сегмент.
  - [MINOR] нет per-day суммы агента. → `agentMs` в `perDay`/§8.
  Все приняты и интегрированы; финальный re-gate (GLM cold-reader) → снова ПУСТО, рассинхрона нет.
- **Tooling note:** local general-purpose Claude-субагенты трижды перехватывались инъекцией из
  подложенного SKILL.md (реклама «agent-first-plugin-suite» / фейковые «review this PR» промпты,
  0 tool-uses). Проигнорировано. Адверсариальные проходы и cold-reader выполнены внешней GLM-5.2
  (гетерогенная модель — как раз рекомендована skill против self-preference) + один hardened
  Claude-проход, который сработал.

## Closure checklist

1. 0 блокеров в ядре; счётчики обсуждения в обе стороны (приняты находки И отбит spor по B1-severity) — ✓
2. Партия полировки re-gated финальным cold-reader на полном тексте — ✓
3. Cold-reader: список вопросов ПУСТ (дважды) — ✓
4. Прогноз сходимости трактовался как гипотеза; решал чек-лист (convergence-pass реально нашёл MAJOR) — ✓
5. Backcast: частично (пример §7 на реальных данных + 36.5ч-картинка владельца) — обязательным не был
6. Preconditions зафиксированы: зависимость точности от #374 (пульс), грубость на легаси, DST-в-полночь, `T_gap ≥ P`

**СТАТУС: CONVERGED.** §1–§10 — нормативная спека для реализатора; это приложение — аудит-след (не нормативно).