trace-first-starter

HL — TFW-15: Pipeline Formalization

Дата: 2026-04-01 Автор: Coordinator (AI) Статус: 📝 HL_DRAFT — Ожидает ревью (updated after RES)

1. Проблема

Текущий pipeline TFW имеет три связанные проблемы:

1.1 Статусы = документы

Pipeline смешивает процессные статусы с типами документов:

Статус	Документ	Проблема
🔵 HL	HL.md	Статус = документ. «🔵 HL» = мы пишем HL или HL уже готов? ❌
🟡 TS	TS.md	Статус = документ ❌

Конкретные проблемы:

HL используется дважды: draft при написании, финальный после RESEARCH. Нет отдельного статуса.
Phase 3.5 — костыль из TFW-11, потому что не было места в нумерации.

1.2 Статусы нигде не определены формально

Нет единого реестра статусов (список, emoji, описания)
Нет определения, кто какой статус может ставить (role → status)
Переходы описаны текстом в разных файлах, нет state machine

1.3 Концепции смешаны

Document Type vs Template — не разделены (HL = и тип артефакта, и файл шаблона)
Workflow vs Adapter Command (skill, slash-command) — синонимы без определений
Status — определён как emoji-label, но не как формальный объект

2. Целевое состояние

2.1 Новый pipeline (Variant D — 8 statuses)

⬜ TODO → 📝 HL_DRAFT → 🔬 RES → 🟡 TS_DRAFT → 🟠 ONB → 🟢 RF → 🔍 REV → ✅ DONE
                          (skip: 📝 HL_DRAFT ··· 🟡 TS_DRAFT)

Логика Variant D:

Статусов остаётся 8 (проверенное количество), не считая BLOCKED
HL_DRAFT и TS_DRAFT — самодокументирующиеся имена. Агент видит _DRAFT и понимает: документ пишется/обсуждается
🔵 HL и 📋 PLAN убраны — нет двойного использования HL, нет мёртвого статуса «HL approved»
Approval implicit: переход HL_DRAFT → RES или HL_DRAFT → TS_DRAFT = HL утверждён

Ключевые переходы:

📝 HL_DRAFT → 🔬 RES → 🟡 TS_DRAFT     # research done, HL finalized
📝 HL_DRAFT ··· 🟡 TS_DRAFT              # research skipped, HL confirmed

2.2 Status Registry (PROJECT_CONFIG.yaml)

Единый реестр статусов с role field:

tfw:
  statuses:
    - id: TODO
      emoji: "⬜"
      description: "Task registered, work not started"
    - id: HL_DRAFT
      emoji: "📝"
      description: "HL being drafted or discussed"
      role: coordinator
    - id: RES
      emoji: "🔬"
      description: "Research in progress (optional)"
      role: coordinator
    - id: TS_DRAFT
      emoji: "🟡"
      description: "TS written, awaiting approval"
      role: coordinator
    - id: ONB
      emoji: "🟠"
      description: "Executor onboarding"
      role: executor
    - id: RF
      emoji: "🟢"
      description: "Execution complete, RF written"
      role: executor
    - id: REV
      emoji: "🔍"
      description: "Review in progress"
      role: reviewer
    - id: DONE
      emoji: "✅"
      description: "Task closed"
    - id: BLOCKED
      emoji: "❌"
      description: "Blocked by dependency"

Дизайн-решения (RES D4, E6):

id IS the label. Нет отдельного поля label (KISS)
role связывает статус с ролью — кто отвечает за этот этап
transitions не включены — deferred. Переходы описаны в conventions.md prose
TODO / DONE / BLOCKED — boundary states, без role

2.3 Transition Matrix

From	To	Role	Trigger
⬜ TODO	📝 HL_DRAFT	Coordinator	`/tfw-plan` creates HL draft
📝 HL_DRAFT	🔬 RES	Coordinator	User approves HL draft, research recommended
📝 HL_DRAFT	🟡 TS_DRAFT	Coordinator	User approves HL draft, research skipped
🔬 RES	🟡 TS_DRAFT	Coordinator	Research done, HL finalized, TS written
🟡 TS_DRAFT	🟠 ONB	Executor	`/tfw-handoff` starts, ONB written
🟠 ONB	🟢 RF	Executor	Implementation done, RF written
🟢 RF	🔍 REV	Reviewer	`/tfw-review` starts
🔍 REV	✅ DONE	Reviewer	APPROVE verdict
🔍 REV	🟢 RF	Reviewer	REVISE verdict (back to executor)
🔍 REV	🛑 User decision	Reviewer	REJECT verdict
*	❌ BLOCKED	Any	External dependency blocks progress

REJECT = branching point (RES C6, D5):

🔍 REV → ❌ REJECT → 🛑 User decides:
                        (a) → 📝 HL_DRAFT (rework HL)
                        (b) → 🔬 RES (new research)
                        (c) → 🟡 TS_DRAFT (HL fine, rewrite TS)

2.4 Concept Taxonomy (TODO — full formalization deferred)

Концепция	Определение	Где живёт
Document Type	Тип артефакта: HL, RES, TS, ONB, RF, REVIEW	glossary.md
Template	Канонический формат для документа	`.tfw/templates/`
Workflow	Tool-agnostic процесс (plan, research, handoff…)	`.tfw/workflows/`
Adapter Command	Tool-specific вызов workflow (slash-command, skill)	`.claude/commands/`, `.agent/workflows/`
Status	Процессный статус задачи на борде	PROJECT_CONFIG.yaml `tfw.statuses`

Document Status (DRAFT/APPROVED в header файла) — deferred (RES D7). Не в скоупе TFW-15. Файловые headers обновляются только чтобы соответствовать новым именам статусов.

2.5 Phase 3.5 → Phase 4

plan.md фазы перенумеровываются:

Phase 1: Research & Analysis
Phase 2: Write HL (draft) → борд 📝 HL_DRAFT
Phase 3: Review & Refine
Phase 4: RESEARCH Gate (бывший 3.5)
Phase 5: Decide Scope & Write TS (бывший Phase 4) → борд 🟡 TS_DRAFT

Step numbering fix (RES E3, D6): plan.md имеет пропуск (step 8 отсутствует). Починить in-passing.

3. Скоуп изменений

Живые файлы (нужно менять)

#	Файл	Действие	Описание
1	`.tfw/PROJECT_CONFIG.yaml`	MODIFY	Добавить `tfw.statuses` registry с `role` field
2	`.tfw/conventions.md`	MODIFY	§5: новый pipeline, status table (HL_DRAFT/TS_DRAFT), REJECT branching
3	`.tfw/glossary.md`	MODIFY	Concept Taxonomy определения, pipeline diagram
4	`.tfw/README.md`	MODIFY	Pipeline diagram + Task Lifecycle section
5	`.tfw/workflows/plan.md`	MODIFY	Phase 3.5 → Phase 4, renumber, step numbering fix, status refs
6	`.tfw/workflows/research.md`	MODIFY	Status Transitions section
7	`README.md` (root)	MODIFY	Key Concepts pipeline string + task board legend
8	`.tfw/templates/HL.md`	MODIFY	`🔵 HL — Ожидает ревью` → `📝 HL_DRAFT — Ожидает ревью`
9	`.tfw/templates/TS.md`	MODIFY	`🟡 TS — Ожидает апрува` → `🟡 TS_DRAFT — Ожидает апрува`

Архивные файлы (НЕ меняем)

Файлы в tasks/TFW-{1..14}/ — исторические артефакты. Менять = фальсифицировать.

Файлы вне скоупа

Адаптеры (.claude/, .agent/) — ссылаются на workflow файлы, не на статусы
Templates (ONB, RF, REVIEW, RES) — не содержат pipeline строк
.tfw/CHANGELOG.md — Phase 3.5 упоминания исторические, не трогаем

Бюджет: 0 новых файлов, 9 модификаций.

4. Definition of Done

5. Definition of Failure

❌ Архивные файлы (tasks/) или CHANGELOG.md переписаны — фальсификация истории
❌ Status registry рассинхронизировалась с conventions/glossary
❌ Adapter commands сломались
❌ Статусов стало больше 10 — раздувание

6. Зависимости

Зависимость	Статус
TFW-14 (research interaction model)	✅ DONE
TFW-12 (config centralization)	✅ DONE

7. Принципы

Statuses ≠ Documents — процессные статусы описывают фазу работы, не тип артефакта
Single Source of Truth — статусы определены в PROJECT_CONFIG.yaml, остальные файлы ссылаются
Implicit Approval — переход к следующему статусу = предыдущий этап утверждён
Same count, better names — 8 статусов (проверенное количество), только имена чётче

8. Риски

Риск	Вероятность	Влияние	Mitigation
Config раздувается	Низкая	Низкое	statuses — фиксированный список
Agent не читает config	Средняя	Среднее	conventions.md содержит transition matrix inline
`_DRAFT` suffix длинный на борде	Низкая	Низкое	Emoji делает visual scan, текст вторичен (RES C5)

*HL — TFW-15: Pipeline Formalization

2026-04-01*

This site is open source. Improve this page.