From 293838ba68caa6f2de35c2aa7f21d3f94da16817 Mon Sep 17 00:00:00 2001 From: Sergey Krylov Date: Thu, 25 Jun 2026 22:26:08 +0300 Subject: [PATCH 1/3] docs: clarify graphify usage for tracing --- AGENTS.md | 14 +++++++++----- 1 file changed, 9 insertions(+), 5 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 0f46690..fa035bb 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -512,8 +512,12 @@ This project has a knowledge graph at graphify-out/ with god nodes, community st When the user types `/graphify`, invoke the `skill` tool with `skill: "graphify"` before doing anything else. Rules: -- For codebase questions, first run `graphify query ""` when graphify-out/graph.json exists. Use `graphify path "" ""` for relationships and `graphify explain ""` for focused concepts. These return a scoped subgraph, usually much smaller than GRAPH_REPORT.md or raw grep output. -- Dirty graphify-out/ files are expected after hooks or incremental updates; dirty graph files are not a reason to skip graphify. Only skip graphify if the task is about stale or incorrect graph output, or the user explicitly says not to use it. -- If graphify-out/wiki/index.md exists, use it for broad navigation instead of raw source browsing. -- Read graphify-out/GRAPH_REPORT.md only for broad architecture review or when query/path/explain do not surface enough context. -- After modifying code, run `graphify update .` to keep the graph current (AST-only, no API cost). +- Используй `graphify` в первую очередь, когда задача связана с архитектурой, границами модулей, кросс-файловым влиянием или трассировкой потока данных. +- Для таких вопросов сначала запускай `graphify query ""`, если существует `graphify-out/graph.json`. Для связей используй `graphify path "" ""`, для точечных концептов — `graphify explain ""`. Обычно это даёт гораздо более узкий подграф, чем `GRAPH_REPORT.md` или raw grep. +- Предпочитай `graphify query` перед raw grep, когда нужен кратчайший путь между концептами, мост между комьюнити или трассировка того, как один подсистемный блок достигает другого. +- Для отладки багов начинай с симптома и спрашивай у graphify путь зависимости, bridge nodes или модули, которые могут объяснить неожиданное поведение. +- Если `graphify` возвращает только общую структуру, переходи к `serena` за символ-уровневыми фактами и затем повторяй `graphify` с более узким вопросом, где названы конкретные файлы, модули или сервисы. +- Dirty `graphify-out/` после хуков или инкрементальных обновлений считаются нормой; грязные файлы графа не повод пропускать `graphify`. Пропускать его можно только если задача именно про устаревший или некорректный граф, либо если пользователь прямо попросил не использовать его. +- Если существует `graphify-out/wiki/index.md`, используй его для широкого обзора вместо ручного просмотра исходников. +- `graphify-out/GRAPH_REPORT.md` читай только для широкого архитектурного обзора или когда `query/path/explain` не дают достаточно контекста. +- После изменений в коде запускай `graphify update .`, чтобы держать граф актуальным (только AST, без затрат на LLM). From 7af8691e0c0589730857c0ba7d4de62c362fc96b Mon Sep 17 00:00:00 2001 From: Sergey Krylov Date: Thu, 25 Jun 2026 22:26:08 +0300 Subject: [PATCH 2/3] docs: clarify graphify usage for tracing --- AGENTS.md | 4 +++- README.md | 2 ++ 2 files changed, 5 insertions(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index fa035bb..18d50be 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -507,7 +507,7 @@ roadmap.md и inbox.md никогда не являются основанием ## graphify -This project has a knowledge graph at graphify-out/ with god nodes, community structure, and cross-file relationships. +This project has a knowledge graph in `graphify-out/` with god nodes, community structure, and cross-file relationships. The graph is a local artifact, not a tracked repo asset. When the user types `/graphify`, invoke the `skill` tool with `skill: "graphify"` before doing anything else. @@ -518,6 +518,8 @@ Rules: - Для отладки багов начинай с симптома и спрашивай у graphify путь зависимости, bridge nodes или модули, которые могут объяснить неожиданное поведение. - Если `graphify` возвращает только общую структуру, переходи к `serena` за символ-уровневыми фактами и затем повторяй `graphify` с более узким вопросом, где названы конкретные файлы, модули или сервисы. - Dirty `graphify-out/` после хуков или инкрементальных обновлений считаются нормой; грязные файлы графа не повод пропускать `graphify`. Пропускать его можно только если задача именно про устаревший или некорректный граф, либо если пользователь прямо попросил не использовать его. +- В новом `worktree` сначала заново создай локальный граф командой `graphify extract .`. +- После первой сборки в этом `worktree` обновляй граф командой `graphify update .`. - Если существует `graphify-out/wiki/index.md`, используй его для широкого обзора вместо ручного просмотра исходников. - `graphify-out/GRAPH_REPORT.md` читай только для широкого архитектурного обзора или когда `query/path/explain` не дают достаточно контекста. - После изменений в коде запускай `graphify update .`, чтобы держать граф актуальным (только AST, без затрат на LLM). diff --git a/README.md b/README.md index 379051f..01a5cf9 100644 --- a/README.md +++ b/README.md @@ -125,6 +125,8 @@ docs/ | `npm run format` | Prettier для всех `*.{ts,tsx}` | | `npm run codegen -w apps/frontend` | `openapi-typescript` из запущенного локального Swagger → `src/api/types.ts` | +`graphify-out/` — локальный артефакт знания, он не хранится в git. В новом `worktree` сначала собери его заново: `graphify extract .`; дальше обновляй инкрементально: `graphify update .`. Для вопросов по коду используй `graphify query "..."`. + Docusaurus (`apps/docs`) — опубликованная документация для пользователей. Storybook (`packages/design-system`) — инженерный workbench для разработки компонентов. Интеграционные тесты с MOEX: `npm run test:integration -w apps/backend`. From 47e65c9b46fa2a0d905f481ed5e1a959bf579e57 Mon Sep 17 00:00:00 2001 From: Sergey Krylov Date: Thu, 25 Jun 2026 22:53:22 +0300 Subject: [PATCH 3/3] docs: add architecture quality backlog --- .../architecture-quality-backlog/plan.md | 111 ++++++++++++++++++ .../architecture-quality-backlog/spec.md | 102 ++++++++++++++++ .../architecture-quality-backlog/tasks.md | 7 ++ 3 files changed, 220 insertions(+) create mode 100644 docs/features/architecture-quality-backlog/plan.md create mode 100644 docs/features/architecture-quality-backlog/spec.md create mode 100644 docs/features/architecture-quality-backlog/tasks.md diff --git a/docs/features/architecture-quality-backlog/plan.md b/docs/features/architecture-quality-backlog/plan.md new file mode 100644 index 0000000..4a7dadb --- /dev/null +++ b/docs/features/architecture-quality-backlog/plan.md @@ -0,0 +1,111 @@ +# Architecture Quality Backlog Implementation Plan + +> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. + +**Goal:** turn the current frontend/backend architecture audit into a prioritized, docs-backed backlog of follow-up refactor features. + +**Architecture:** this feature is docs-only. We will not change runtime code; instead we will reconcile source-of-truth docs with the current codebase, classify findings by subsystem, and publish a backlog that can be split into future single-subsystem refactor features. + +**Tech Stack:** Markdown docs in `docs/`, published Docusaurus docs in `apps/docs/docs/`, existing repo search tooling. + +--- + +### Task 1: Consolidate source material + +**Files:** +- Read: `docs/research/2026-06-25-backend-audit.md` +- Read: `docs/features/frontend-debt-audit/spec.md` +- Read: `docs/features/backend-architecture-refactor/spec.md` +- Read: `apps/docs/docs/frontend/overview.md` +- Read: `apps/docs/docs/backend/modules.md` +- Read: `docs/roadmap.md` + +- [ ] **Step 1: Capture current architecture findings** + +Use the existing audit docs plus current source/docs to confirm which items are already closed, which are stale in docs, and which are still open. + +- [ ] **Step 2: Check for overlap with completed work** + +Verify that the backlog does not reintroduce items already covered by completed refactor docs or published architecture pages. + +### Task 2: Write the backlog spec + +**Files:** +- Create: `docs/features/architecture-quality-backlog/spec.md` + +- [ ] **Step 1: Write the backlog scope** + +Document that this feature is docs-only and only produces a prioritized backlog, not runtime code changes. + +- [ ] **Step 2: List the backlog items** + +Describe the five backlog items in priority order: + +```markdown +1. Documentation Source-of-Truth Sync +2. Backend Service Boundary Cleanup +3. Backend Contract Type-Safety Hardening +4. Frontend Session Model Simplification +5. Frontend Query-Key and API Wrapper Hardening +``` + +- [ ] **Step 3: State the acceptance criteria** + +Require explicit risk/dependency notes for every backlog item and a no-runtime-code-change constraint. + +### Task 3: Write the execution plan + +**Files:** +- Create: `docs/features/architecture-quality-backlog/plan.md` + +- [ ] **Step 1: Describe the doc-only architecture** + +Explain that the implementation is a documentation workflow: inventory, classify, prioritize, publish. + +- [ ] **Step 2: Define the file responsibilities** + +State which docs are the source material, which doc is the canonical backlog, and which docs will be updated to reflect it. + +- [ ] **Step 3: Add the validation checklist** + +Require a final consistency pass against code and existing docs before the backlog is considered ready. + +### Task 4: Write the task breakdown + +**Files:** +- Create: `docs/features/architecture-quality-backlog/tasks.md` + +- [ ] **Step 1: Create small independent doc tasks** + +Break the work into small, reviewable documentation tasks: + +```markdown +- [ ] Inventory the current frontend/backend architecture debt +- [ ] Remove completed or stale items from the backlog +- [ ] Prioritize the remaining backlog by risk and dependency +- [ ] Cross-link the backlog with roadmap and epics +- [ ] Run a final docs consistency review +``` + +- [ ] **Step 2: Ensure no code tasks are listed** + +This feature must not include implementation tasks for `apps/frontend/src/**` or `apps/backend/src/**`. + +- [ ] **Step 3: Reference the docs that will be linked** + +Use `docs/roadmap.md` plus the relevant epic/feature docs as the cross-link targets for the published backlog. + +### Task 5: Final review + +**Files:** +- Read: `docs/features/architecture-quality-backlog/spec.md` +- Read: `docs/features/architecture-quality-backlog/plan.md` +- Read: `docs/features/architecture-quality-backlog/tasks.md` + +- [ ] **Step 1: Check for scope creep** + +Ensure the documents describe backlog creation only, not code refactoring. + +- [ ] **Step 2: Check for contradictions** + +Verify that the priority order, scope, and acceptance criteria match across all three files. diff --git a/docs/features/architecture-quality-backlog/spec.md b/docs/features/architecture-quality-backlog/spec.md new file mode 100644 index 0000000..d8a4762 --- /dev/null +++ b/docs/features/architecture-quality-backlog/spec.md @@ -0,0 +1,102 @@ +# Architecture Quality Backlog + +Дата: 2026-06-25 +Статус: draft + +## Контекст + +В репозитории уже есть несколько завершённых волн архитектурного улучшения, но после них остались: + +- разрозненные остатки архитектурного долга во frontend и backend; +- устаревшие или частично противоречивые документы; +- несколько высокосвязанных зон, которые нельзя безопасно рефакторить одной крупной итерацией. + +Эта фича не меняет runtime-поведение. Её задача - превратить найденные архитектурные проблемы в нормализованный, приоритизированный backlog для последующих узких refactor-фич. + +## Цель + +Зафиксировать актуальный архитектурный backlog по frontend, backend и проектной документации, разделить его на независимые follow-up фичи и определить порядок их выполнения. + +## Требования + +### 1. Инвентаризация текущего состояния + +Нужно опираться на три источника: + +- `apps/frontend/src/` - реальные границы слоёв, API слой, session state, query key usage; +- `apps/backend/src/` - границы NestJS-модулей, сервисов, Prisma-доступа, DTO и инфраструктурных клиентов; +- `docs/` и `apps/docs/docs/` - roadmap, epics, feature specs/plans/tasks и опубликованная архитектурная документация. + +### 2. Нормализация находок + +Каждый найденный пункт долга должен быть отнесён к одной из категорий: + +- уже закрыто; +- устарело и требует пересмотра документации; +- открыто и должно стать отдельной follow-up фичей; +- открыто, но пока должно остаться в backlog без немедленной реализации. + +### 3. Приоритизация + +Backlog должен быть упорядочен по следующему правилу: + +- сначала низкорисковые и высокосигнальные документы/contract cleanup задачи; +- затем сервисные границы backend; +- затем frontend state/API hardening; +- позже - крупные или спорные refactor-направления. + +### 4. Границы будущих фич + +Каждый backlog-item должен быть независимым настолько, чтобы его можно было превратить в отдельную feature-spec без смешивания frontend и backend implementation work в одном change-set. + +### 5. Никаких новых возможностей + +Фича не должна: + +- менять пользовательские сценарии; +- добавлять новые API; +- менять модель данных; +- вводить новые библиотеки или инфраструктуру; +- исправлять runtime-bug'и вне рамок документации и backlog-формализации. + +## Предлагаемый backlog + +### 1. Documentation Source-of-Truth Sync + +Синхронизировать roadmap, epics и опубликованные architecture docs с текущим состоянием кода, убрать устаревшие статусы и противоречия. + +### 2. Backend Service Boundary Cleanup + +Сделать явными границы `PortfolioService`, `TBankModule` и связанных сервисов, чтобы последующие refactor-фичи можно было изолировать по доменам. + +### 3. Backend Contract Type-Safety Hardening + +Закрыть свободные строки и dynamic access в screener/T-Bank контрактных зонах, не меняя публичный API. + +### 4. Frontend Session Model Simplification + +Свести session state к одной понятной точке истины и убрать лишние внутренние импорты между слоями. + +### 5. Frontend Query-Key and API Wrapper Hardening + +Нормализовать query key factories и повысить устойчивость API request layer к contract drift. + +## Ограничения + +- Только docs/backlog scope. +- Не трогать runtime-код в рамках этой фичи. +- Не объединять в один backlog-item несвязанные frontend и backend работы. +- Не добавлять новые продуктовые требования. + +## Критерии приемки + +- Есть один согласованный backlog с приоритетом и кратким обоснованием по каждому пункту. +- Для каждого backlog-item указаны: + - цель; + - риск; + - зависимости; + - ожидаемый артефакт follow-up фичи; + - причина, почему item не закрыт уже сейчас. +- Документация не противоречит текущему коду и уже завершённым refactor-волнам. +- Backlog отражён в `docs/roadmap.md` и связан с релевантными epics/feature docs. +- В рамках этой фичи не изменены файлы `apps/frontend/src/**` и `apps/backend/src/**`. diff --git a/docs/features/architecture-quality-backlog/tasks.md b/docs/features/architecture-quality-backlog/tasks.md new file mode 100644 index 0000000..4cbd2a1 --- /dev/null +++ b/docs/features/architecture-quality-backlog/tasks.md @@ -0,0 +1,7 @@ +# Architecture Quality Backlog Tasks + +- [ ] Audit current frontend/backend architecture findings and classify them against existing docs. +- [ ] Remove items already covered by completed refactors or stale documentation. +- [ ] Prioritize the remaining debt into a single ordered backlog. +- [ ] Link each backlog item to a future follow-up feature boundary. +- [ ] Verify the backlog is docs-only and does not require runtime code changes.