docs(ai): adopt task-driven scoped context

This commit is contained in:
2026-09-09 16:23:11 +03:00
parent 7166ee51d1
commit b7a56b1eb5
17 changed files with 502 additions and 676 deletions
+13 -40
View File
@@ -1,44 +1,17 @@
# Docs
## Назначение и authority
Здесь живут as-built факты, проектные решения и общие engineering conventions.
Работай напрямую по задаче пользователя; обязательного SDD lifecycle нет.
Этот репозиторий хранит durable as-built документацию WealthLedger. Shared SDD
policy, common reading pointers, audit routing и `../references/**` policy
задаёт root `AGENTS.md`.
Для поиска проектного источника начни с [AI_INDEX](AI_INDEX.md). Если задача
уже указывает точный документ (например, правка опечатки), читай его напрямую.
Architecture/features описывают текущее поведение,
ADR сохраняют rationale; audits и прежнее Completion Evidence — история.
Изменение утверждённого архитектурного решения фиксируется successor ADR,
но не требует создания OpenSpec artifacts.
Для SDD roles, approvals и ownership читайте
[governance](development/engineering-governance.md); native planning и completion
в store `wealth-ledger-specs` —
[lifecycle](development/openspec-authority-and-lifecycle.md); recovery, fingerprints
и evidence reuse — [context authority](development/agent-token-efficiency.md).
Audit-derived работа начинается с найденной записи
[remediation registry](development/audit-remediation.md). Optional agent adapters
не требуются.
Docs фиксирует проверенное as-built состояние. Planning и Completion Evidence
принадлежат canonical `../specs/openspec`; docs не хранит их параллельную копию.
## Canonical gate
Перед Node-командами активировать `.nvmrc` через `nvm use --silent`; это выбирает
Node 22. Не запускать отдельную проверку версии, кроме диагностики runtime issue.
После lockfile install:
```bash
npm ci
npm run verify
```
Gate non-mutating запускает committed Markdown rules и `git diff --check`. Auto-fix и network/browser link checking в gate не входят; local links affected documentation проверяются scoped review.
Актуальные scripts проверять в `package.json`/`npm run`.
## Boundaries
- `architecture/` — текущее устройство, `features/` — поставленное поведение,
`adr/` — устойчивые решения, `development/` — процесс и navigation к canonical
evidence, `audits/` — immutable snapshots. Legacy dated evidence не переписывается.
- Indexes должны вести к новым документам.
- Feature docs описывают фактический поток, API и ограничения, но не повторяют OpenSpec requirements/design/tasks.
- Для диаграмм использовать Mermaid в Markdown. Не хранить application code, secrets или competing SDD artifacts.
Markdown lint и whitespace checks — hard guardrails. Стилистические пожелания без локального checker являются guidance.
Перед Node-командами: `nvm use --silent`. После `npm ci` запускай
`npm run verify` (Markdown lint + `git diff --check`, без auto-fix).
Проверь links/anchors затронутых документов отдельно. Новые документы должны
быть доступны через соответствующий index. Runtime facts сверяй с code/config;
не копируй framework docs, secrets или один контракт в несколько owners.