zzet--gortex/AGENTS.md

AGENTS.md — Temporal dispatch allow-list (для корпоративного агента)

Этот файл — инструкция агенту, работающему в корпоративном форке gortex, по сопровождению распознавания Temporal-диспатча под ваш кодовой базы. Цель: повышать точность графа Temporal без утечки корпоративных имён в исходники / upstream.

Не путать с docs/agents.md (это про agent-адаптеры самого gortex). Здесь — только про Temporal allow-list и LLM-клининг.

---

1. Как устроено распознавание (три слоя)

Имя активности/воркфлоу в workflow.ExecuteActivity(ctx, <name>, …) часто приходит не литералом. Форк распознаёт его тремя слоями, по возрастанию доверия:

1. Generic-эвристика (recall, скрыто). Любой хелпер с env в имени — cfg.ActivityFromEnv("KEY", "Default") — распознаётся структурно: 2-й строковый аргумент берётся как дефолтное имя. Ребро садится на speculative 0.4 (temporal_env_source=heuristic), скрыто из обычных запросов. Вести ничего не нужно — работает само.
2. Allow-list (precision, видимо). Если имя хелпера в built-in списке (GetEnvOrDefault, GetEnvOrDefaultValue, EnvOr, GetenvDefault, GetEnvDefault) или в вашем репо-локальном allow-list — ребро повышается до inferred 0.6, видимо по умолчанию (temporal_env_source=allowlist). os.Getenv(...) / cmp.Or(...) тоже → 0.6.
3. LLM-клининг (опционально). Проход gortex analyze --kind temporal_verify отдаёт каждое рёбро уровня ≤0.65 вашей LLM, заземляя в реальном коде: confirmed → повышает и делает видимым, rejected → гасит (скрывает), uncertain → оставляет как есть. Register-confirmed (0.9) не трогает.

Главное: слой 1 жадный и безвредный (скрыт), слой 2 точечно повышает, слой 3 чистит. Поэтому не обязательно перечислять все хелперы — список нужен лишь чтобы сделать конкретный хелпер видимым по умолчанию.

---

2. Как вести allow-list

Файл git-ignored (см. .gitignore: .gortex/), читается только под env-гейтом.

1. Включить гейт: export GORTEX_ALLOW_LOCAL_TEMPORAL=1.
2. Создать .gortex/temporal-allowlist.yaml в корне репозитория:

# Имена ваших env-хелперов, по которым диспатч резолвится на дефолт.
# Сопоставление по имени функции (без пакета), регистронезависимо.
env_helpers:
  - GetActivityNameFromEnv
  - FetchActivityName
  - resolveActivity            # локальные/lowercase тоже годятся

3. Проверить эффект: gortex analyze --kind temporal_orphans --path . --format json (до/после) — часть broken_dispatch должна закрыться, env-сайты получить temporal_env_source=allowlist.

Что добавлять / чего нет:

• Добавлять: имена функций-обёрток «прочитать env и вернуть дефолт». Это generic-инфраструктура, не бизнес-данные.
• НЕ добавлять: имена активностей/воркфлоу/бизнес-логику. Они тут не нужны (распознаются структурно), и им не место даже в git-ignored файле.

---

3. Протокол анонимизации (не спалить корпоративное)

• Файл .gortex/temporal-allowlist.yaml git-ignored — не коммить его и не добавлять в PR.
• Имена env-хелперов сами по себе — generic infra (безопасны), но всё равно держим их только в локальном файле, а не в исходниках форка.
• Если делаешь фикстуры для передачи OSS-стороне — следуй docs/temporal-compare/temporal-gap-synthetic-fixtures.md (протокол: «сохраняем форму, стираем содержание»): repo-пути → example.com/app, имена активностей → ChargeActivity, env-ключи → FOO_ACTIVITY_ENV, тела → выкинуть.

---

4. LLM-клининг (precision-проход вашей моделью)

Требует настроенного llm.provider (например ваш custom-provider) в .gortex.yaml / ~/.config/gortex/config.yaml.

gortex analyze --kind temporal_verify --path . --format json

• Проверяет только низкодоверенные рёбра (speculative 0.4 + inferred 0.6) — набор маленький, стоимость ограничена. Register-confirmed 0.9 не трогает.
• Вердикты кэшируются в git-ignored .gortex/temporal-verify-cache.json по хэшу (модель + имя + исходник вызова + исходник кандидата) → повторный прогон детерминирован и бесплатен (годится для CI). Меняется код или модель — кэш промахивается и перепроверяет.
• Вывод: checked / confirmed / rejected / uncertain / errors (+ details в JSON с причинами).
• На каждом ребре остаются temporal_llm_verdict и temporal_llm_reason для аудита.

---

5. Что делать с тем, что всё ещё не резолвится

Для dispatch-шейпов, остающихся broken_dispatch и не закрытых ничем выше, — docs/temporal-compare/temporal-gap-synthetic-fixtures.md: какие минимальные анонимизированные фикстуры отдать OSS-стороне, чтобы дорезолвить либу.