MH BankStatement Docs

English

Русский
Bahasa Indonesia

English

Русский
Bahasa Indonesia

Appearance

Plane Task Execution Rules (AI Agents) ​

Правила выполнения Plane-задач AI-агентами в MyHoreca Pay. Дополняют корневой AGENTS.md и AI Agents Rules.

Шаблон задачи: Plane Task Template.

1. Task quality bar ​

Каждая Plane-задача для AI-агентов обязана включать:

SectionPurpose
ContextПочему задача существует
GoalИзмеримый результат
Scope / What To DoЧто делать
Out of Scope / Non-goalsЧто не делать
Acceptance CriteriaПроверяемые условия готовности
Test PlanКакие тесты запускать/добавлять
Documentation PlanКакие docs обновить
Security / Audit / SafetyОграничения по данным и audit
Definition of DoneHandoff и verification

Без этих секций задача считается не готовой к выполнению агентом. Используйте шаблон при создании issue или импорте (Import key обязателен).

2. Session start (mandatory read order) ​

  1. AGENTS.md
  2. codegraph/manifest.yaml
  3. docs/docs/ai-agents/project-prompt.md
  4. docs/docs/ai-agents/current-implementation-state.md
  5. docs/docs/ai-agents/current-plane-task.md
  6. Доменные файлы из задачи и manifest — только targeted inspection

3. Targeted repo inspection only ​

  • Открывать только файлы, релевантные задаче и codegraph.
  • Не выполнять broad scan всего репозитория «на всякий случай».
  • Сначала искать существующие реализации, тесты, docs и паттерны; расширять, а не дублировать.
  • Для API/UI/архитектуры: codegraph/manifest.yaml → api_surface, shared_symbols, test pointers.

4. Scope discipline ​

  • Не расширять scope без отдельной Plane-задачи или ADR.
  • Не менять unrelated-код, permissions, adapters, API/frontend, если задача этого не требует.
  • Не добавлять новые бизнес-решения без ADR.

5. Adapter changes ​

Если задача затрагивает bank adapter:

  • version/changelog обязательны;
  • sanitized fixtures обязательны;
  • adapter tests обязательны;
  • не ломать shared pipeline — новый формат через новый adapter.

Если adapter не меняется — в задаче явно: Bank Adapter Impact: None.

6. Permission / RBAC changes ​

Если задача меняет permissions или RBAC:

  • обновить permission matrix;
  • обновить seeds/policies/tests по существующему паттерну.

Если permissions не меняются — явно: Permission / RBAC Impact: None.

7. Data, secrets, and logging ​

Запрещено в коде, тестах, docs, логах и Plane-комментариях:

  • real bank files;
  • secrets, tokens, API keys, credential values;
  • raw bank lines;
  • full account numbers.

Использовать только sanitized fixtures (backend/tests/MyHoreca.Pay.UnitTests/Fixtures/BankStatements/). Raw exports — только в gitignored */samples/local/ или вне репозитория. Перед handoff: python tools/security/guard-bank-files.py .. Policy: Bank Statement Fixture Policy. При сомнении — блокировать файл и запросить sanitized copy.

Критичные/payment/Syrve действия должны быть audited.

8. Documentation obligations ​

Обновлять документацию при изменении:

  • API (docs/docs/backend/api.md, contracts, hooks);
  • frontend routes/hooks/contracts;
  • architecture/module boundaries (codegraph/manifest.yaml);
  • permissions/security behavior;
  • bank adapters (parsing doc, changelog, fixtures).

После каждой завершённой итерации — docs/docs/ai-agents/current-implementation-state.md.

9. Definition of Done (verification) ​

DoD обязан включать:

  • точные verification commands, которые агент запускал;
  • фактический результат каждой команды (pass / fail / not run + причина).

Правила:

  • Никогда не заявлять «тесты прошли», если команды не запускались.
  • Если verification невозможен из-за отсутствия .NET SDK, Node, Docker, network, credentials или permissions — явно указать это в handoff.
  • Предпочитать узкий targeted test, затем broader dotnet test / npm test / docs build по необходимости.

10. Handoff checklist ​

  • [ ] Scope и Acceptance Criteria выполнены
  • [ ] Commit message содержит [MHPAY-XXX] (см. Git / Plane Traceability)
  • [ ] current-implementation-state.md обновлён
  • [ ] codegraph/manifest.yaml обновлён (если применимо)
  • [ ] Plane issue: комментарий с кратким отчётом, verification summary и commit hash (если был коммит)
  • [ ] Plane issue: state → Done (или явная причина, почему нет)
  • [ ] Нет real bank data / secrets в diff

Workflow: direct commits to main; PR не обязателен. Подробности — Git / Plane Traceability.