task-workflow.md

Git-жизненный цикл задачи

Этот документ описывает workflow-поведение поверх Task Core. За границы source-of-truth, ownership по файлам, статусную модель и cleanup-governance отвечает references/core-model.md.

Что считается нормой

После установки task-centric-knowledge задача ведётся одновременно в четырёх контурах:

• knowledge-контур: task.md, plan.md, sdd.md, worklog.md, registry.md;
• git-контур: текущая активная ветка рабочего контекста, commit-ы в пределах задачи и проверка diff перед завершением этапа;
• publish-контур: ## Контур публикации в task.md, delivery units, PR/MR и cleanup-состояние;
• testing-контур: максимально полный набор автоматических проверок, реально исполнимых в текущем проекте и допустимых его правилами, плюс единый итоговый список ручных проверок в общей задаче.

Все контуры должны быть синхронизированы. Нельзя держать task.md с одной веткой, а фактически работать в другой. Точно так же нельзя считать задачу оформленной, если автоматические проверки не спланированы, а ручные сценарии расползлись по нескольким файлам без одного итогового списка. Для сложной задачи этого тоже недостаточно: агент обязан зафиксировать полный invariant set и доказать покрытие artifacts/verification-matrix.md до ревью.

Перед git-действиями сначала нужно определить тип контекста:

• продолжение текущей задачи;
• новая подзадача внутри текущей задачи;
• новая задача.

Правила выбора вынесены в references/task-routing.md. Если работа связана именно с обновлением старой версии skill-а на новую, сначала применять references/upgrade-transition.md.

Стартовая ветка по умолчанию

Верхнеуровневая задача

• стартовая ветка по умолчанию: task/<task-id-lower>-<slug>;
• пример: task/task-2026-0004-task-centric-knowledge-git-flow.

Подзадача

• по умолчанию используется ветка родителя;
• отдельную ветку для подзадачи создавать только если из локального контекста ясно, что подзадача реально изолируется и не ломает общий поток работы.
• если родитель и подзадачи делят одну ветку, current-task в чистом дереве выбирает родителя как активный aggregate.
• если dirty-scope указывает на конкретную подзадачу, current-task выбирает эту подзадачу через branch+dirty.

Семантика поля Ветка

• Поле Ветка хранит текущую активную ветку рабочего контекста.
• На старте задачи это обычно task/....
• Во время поставки helper может перевести Ветка в delivery-ветку формата du/<task-id-lower>-uNN-<slug>.
• Для legacy-задач допустимо сохранение уже существующей task/...-ветки как активного контекста.

Первый task bootstrap после clean install

После самой первой установки knowledge-системы рабочее дерево уже может быть грязным:

• installer создал knowledge/;
• при отсутствии AGENTS.md появился snippet AGENTS.task-centric-knowledge.<profile>.md;
• оператор уже создал первые task.md / plan.md из шаблонов.

В такой ситуации helper не должен молча переключать ветку. Field validation подтвердила, что task-knowledge workflow sync --create-branch корректно останавливается на dirty tree.

Проверенный порядок для первой задачи:

1. Явно определить TASK-ID и slug.
2. Вручную создать task/... ветку:

git checkout -b task/<task-id-lower>-<slug>

3. Создать каталог задачи и заполнить task.md / plan.md из шаблонов.
4. Синхронизировать metadata и registry.md без попытки branch switch:

task-knowledge workflow sync --project-root /abs/project --task-dir knowledge/tasks/<TASK-ID>-<slug> --register-if-missing --summary "Краткое описание задачи"

5. Проверить operator UX:

task-knowledge --json task current --project-root /abs/project
task-knowledge --json task show --project-root /abs/project <TASK-ID>

Контур публикации

• Delivery unit живёт внутри task.md, а не в отдельном каталоге и не в отдельной строке registry.md.
• Один delivery unit соответствует одной head-ветке, одной публикации PR/MR или её отсутствию и одному итоговому результату merged или closed.
• В одном task.md допускается несколько delivery units.
• Канонические статусы delivery unit: planned, local, draft, review, merged, closed.
• Канонические значения Host: none, github, gitlab, generic.
• Канонические значения Тип публикации: none, pr, mr.
• Задача может быть завершена только после того, как все её delivery units доведены до merged или closed.

Что делать автоматически, если контекст ясен

• проверить git status и текущую ветку;
• при чистом рабочем дереве создать или переиспользовать стартовую task-ветку;
• синхронизировать поле Ветка в task.md и колонку Ветка в knowledge/tasks/registry.md;
• поддерживать ## Контур публикации в task.md и синхронизировать delivery units через helper;
• если задача сложная, завести sdd.md, выписать полный invariant set и вести artifacts/verification-matrix.md;
• планировать и запускать максимально полный набор автоматических проверок по backend, frontend, интеграциям и другим затронутым контурам, если они реально исполнимы в текущем проекте и не нарушают его правила и ограничения;
• для задачи с sdd.md до ревью доказать покрытие artifacts/verification-matrix.md фактически прогнанными тестами, командами или audit-gates;
• не включать в обязательные автопроверки сценарии, которые теоретически автоматизируемы, но недопустимы правилами проекта или текущей средой;
• оставлять ручные проверки только как остаток после автоматизации и собирать их в единый итоговый список общей задачи;
• делать осмысленные commit-ы по завершении этапа или значимой контрольной точки, если diff относится к одной задаче;
• прогонять git diff --check перед завершением задачи или этапа.

Если задача действительно завершена и локальный git-контекст безопасен, helper теперь может выполнить local-only finalize:

• сделать task-scoped commit со всеми локальными изменениями задачи;
• fast-forward влить task-ветку в base-ветку;
• переключить checkout на base-ветку;
• синхронизировать task.md и registry.md под итоговый локальный branch-state.

Когда нужно остановиться

• рабочее дерево грязное и в нём есть чужие или явно несвязанные изменения;
• текущая ветка уже привязана к другой задаче и безопасный способ продолжить не очевиден;
• для следующего шага нужно разрушающее git-действие: reset, clean, удаление ветки, переписывание истории;
• publish-helper не может надёжно определить состояние PR/MR, remote или host auth;
• невозможно надёжно определить, относится ли diff к одной задаче или к нескольким.
• невозможно однозначно определить, где должен жить итоговый ручной checklist общей задачи.

Вспомогательный скрипт

Предпочтительный детерминированный вход для синхронизации task-контекста:

task-knowledge workflow sync --project-root /abs/project --task-dir knowledge/tasks/TASK-2026-0001-zadacha --create-branch --register-if-missing --summary "Краткое описание задачи"

Для подзадачи с наследованием ветки родителя:

task-knowledge workflow sync --project-root /abs/project --task-dir knowledge/tasks/TASK-2026-0001-zadacha/subtasks/TASK-2026-0001.1-podzadacha --create-branch --inherit-branch-from-parent --register-if-missing --summary "Краткое описание подзадачи"

Для старта первой поставки:

task-knowledge workflow publish --project-root /abs/project --task-dir knowledge/tasks/TASK-2026-0001-zadacha --publish-action start --purpose "Первая поставка" --base-branch main

Для публикации и синхронизации PR/MR:

task-knowledge workflow publish --project-root /abs/project --task-dir knowledge/tasks/TASK-2026-0001-zadacha --publish-action publish --unit-id DU-01 --host github --url https://github.com/example/repo/pull/1 --status draft
task-knowledge workflow publish --project-root /abs/project --task-dir knowledge/tasks/TASK-2026-0001-zadacha --publish-action sync --unit-id DU-01 --sync-from-host
task-knowledge workflow publish --project-root /abs/project --task-dir knowledge/tasks/TASK-2026-0001-zadacha --publish-action merge --unit-id DU-01 --merge-commit abc1234

Для local-only finalize завершённой задачи:

• Legacy-команда: task-knowledge workflow finalize --project-root /abs/project --task-dir knowledge/tasks/TASK-2026-0001-zadacha --base-branch main
• Единый CLI: task-knowledge workflow finalize --project-root /abs/project --task-dir knowledge/tasks/TASK-2026-0001-zadacha --base-branch main

CLI операторских запросов

Для query/reporting-сценариев использовать отдельный read-only entrypoint:

task-knowledge --json task status --project-root /abs/project
task-knowledge --json task current --project-root /abs/project
task-knowledge task show --project-root /abs/project current
task-knowledge task show --project-root /abs/project TASK-2026-0001

Этот CLI:

• не мутирует git, task.md или registry.md;
• показывает task-oriented заголовок TASK-ID + Краткое имя + Человекочитаемое описание;
• для current-task сначала использует branch-match, затем безопасный task-scoped dirty fallback;
• при неоднозначности возвращает warning и список кандидатов вместо молчаливого выбора;
• на shared parent/subtask branch сворачивает кандидатов к родителю, если все они принадлежат одному parent aggregate;
• для несвязанных задач на одной ветке продолжает поднимать ambiguous/branch_tie.

Что делает вспомогательный скрипт

• определяет целевую ветку по task.md или по родительской задаче;
• создаёт или переключает стартовую task-ветку, если это безопасно;
• обновляет Ветка и Дата обновления в task.md;
• обновляет или создаёт строку в knowledge/tasks/registry.md.

В finalize-режиме helper дополнительно:

• валидирует, что запуск идёт из task-ветки, а не из base-ветки;
• блокирует finalize при открытых delivery units, branch mismatch и небезопасном non-fast-forward merge;
• делает local-only commit, fast-forward merge в base и checkout base;
• при блокере возвращает явный stop-report и список следующих действий без частичных git-мутаций.

В publish-режиме helper дополнительно:

• создаёт или переиспользует delivery unit в ## Контур публикации;
• синхронизирует Host, Тип публикации, Статус, URL, Merge commit, Cleanup;
• при start может создать и активировать du/...-ветку;
• при publish и sync может использовать host adapter для GitHub/GitLab, если есть валидный remote и доступная auth.

Что не делает вспомогательный скрипт

• не пушит ветки;
• не гарантирует создание PR/MR без валидной auth и поддерживаемого host adapter;
• не переписывает историю;
• не удаляет ветки;
• не делает push как часть local finalize;
• не завершает задачу при открытых delivery units или небезопасном merge-контексте;
• не обходит стоп-условия по грязному рабочему дереву, недоступному host auth и неоднозначному контексту.