initial commit

docs/ARCHITECTURE.md

@@ -0,0 +1,42 @@
+# Архитектурные границы
+
+Это целевое разделение; modules ещё предстоит реализовать после выбора стека.
+
+```text
+UI components / routes
+        ↓ commands                 ↑ view models
+Application use cases / lifecycle
+        ↓ ports
+Domain models / pure policies
+        ↕ adapters
+IndexedDB / XMPP WSS / crypto worker / media worker / browser APIs
+        ↕
+External XMPP + upload + TURN + maps + push gateway
+```
+
+## Каталоги реализации
+
+- `src/domain/`: модели и pure policies без UI/network.
+- `src/application/`: use cases, event reducers, account-bound operation context.
+- `src/ports/`: интерфейсы, errors, capability contracts.
+- `src/adapters/`: xmpp, storage, crypto, media, notifications.
+- `src/ui/`: tokens, primitive components, feature views, routes.
+- `src/workers/`: crypto/media off-main work.
+- `src/platform/`: browser lifecycle, permission, multi-tab coordination.
+- `services/push/`: минимальный Web Push gateway; не messaging backend и не OMEMO endpoint.
+- `infra/`: local fixtures/server/HTTPS/WSS/turn and deployment configuration.
+- `tests/`: unit, contract, integration, browser, interoperability, security, tooling.
+
+Расширения файлов/commands определяет accepted stack ADR. В карточках scope без расширения обозначает logical module stem: после ADR создаётся файл с принятым расширением, не файл без расширения.
+
+## Направления зависимостей
+
+Domain не импортирует adapters/UI. UI вызывает application commands, не Signal/session/network internals. Adapters реализуют ports. Event содержит accountId, conversationId/eventId и generation/cancellation context; поздний результат старого аккаунта отбрасывается.
+
+Durable history mutations и checkpoint — одна transaction boundary. Внешняя доставка и локальная запись не образуют общей distributed transaction: retries должны учитывать факт возможной успешной отправки.
+
+Gateway хранит только необходимые push subscription/registration metadata; encrypted message plaintext ему недоступен. CORS не обходится скрытым decrypting proxy.
+
+## Governance
+
+Любое изменение shared contract требует ADR/contract update и focused contract tests. До этого downstream owner не угадывает поля интерфейса. Интерфейсы сначала фиксируются в S01, затем implementers добавляют concrete code.

docs/AUTOMATION.md

@@ -0,0 +1,69 @@
+# Автоматический цикл агентов
+
+## Однократная настройка
+
+Скопировать `runner.example.json` в `runner.local.json` и заменить `argv` на команду своего **агентного CLI с доступом к файлам и инструментам**. Обычный текстовый вызов модели без execution harness не сможет выполнять задачи.
+
+Команда запускается без shell из project root; полный новый prompt поступает в stdin UTF-8. Дополнительно доступны placeholders `{root}`, `{task}`, `{role}`, `{agent}`, `{action}`, `{prompt_file}` в аргументах и environment variables `LUMA_PROJECT_ROOT`, `LUMA_TASK_ID`, `LUMA_ROLE`, `LUMA_AGENT_ID`, `LUMA_ACTION`, `LUMA_PROMPT_FILE`.
+
+Пример формы настройки (имя/флаги заменить реальными для вашего harness):
+
+```json
+{"argv": ["your-agent-cli", "--prompt-file", "{prompt_file}"], "max_sessions": 1000, "timeout_seconds": 1800, "max_prompt_chars": 80000}
+```
+
+`commands_by_role` позволяет указать другую argv-array для отдельных ролей, например crypto/security. Не хранить secrets в аргументах/JSON; использовать безопасное окружение harness. Конкретная модель и команда не выдумываются автоматически.
+
+Harness обязан запускать новую conversation/session для каждого процесса, исполнять file/tool commands, соблюдать project sandbox и завершаться после submit/review/escalate. Не использовать флаги resume/thread reuse и auto-next-task внутри harness.
+
+## Запуск
+
+```sh
+python3 scripts/runner.py --dry-run
+python3 scripts/runner.py --config runner.local.json
+# Ограничить согласованным этапом:
+python3 scripts/runner.py --config runner.local.json --stage S00
+```
+
+Dry run не назначает tasks, не пишет state и работает без настроенной модели. Он показывает первую задачу и размер prompt. После настройки один обычный запуск последовательно выполняет очередь: executor → новый reviewer → следующий executor. Каждый subprocess имеет новый agent id и читает master prompt заново.
+
+## Blocker flow
+
+1. Текущий агент записывает handoff/issue, `escalate`, заканчивает работу.
+2. Оригинал blocked, resolver todo с ограниченным scope и исходными prerequisites. Resolver не зависит от blocked оригинала.
+3. Runner приоритетно запускает нового resolver-агента.
+4. Другой новый процесс проверяет resolver.
+5. Только done resolver автоматически снимает блокировку оригинала. Оригинал возвращается в todo либо review, прежний reporter id retired.
+6. Новый executor/reviewer читает исходную карточку и handoff; потом продолжается обычная очередь.
+
+Nested blocker проходит тот же процесс. Глубина выше 3 или 6 remediation на одну root task автоматически переводит очередную remediation в ожидание внешнего решения. Так не возникает бесконечного создания одинаковых задач/процессов.
+
+## Когда требуется пользователь
+
+Credentials/оплата/неопределённое продуктовое решение/действие внешнего администратора, достигнутый blocker limit, нарушение scope или ненастроенный CLI. `requires_user_input` не означает автоматическое done; задача ждёт конкретного input.
+
+После внешнего исправления:
+
+```sh
+python3 scripts/tasks.py release-external <RESOLVER-ID> --agent coordinator-new --role orchestrator \
+  --reason 'Конкретное условие выполнено; ссылка на безопасное подтверждение'
+python3 scripts/runner.py --config runner.local.json
+```
+
+Release только делает resolver готовым к проверяемой реализации, не завершает его и не снимает блокировку оригинала.
+
+## Остановка и безопасность исполнения
+
+`max_sessions` ограничивает число новых процессов за invocation; exhaustion возвращает summary, не done. Runner наблюдает terminal transition: после escalate/submit/approve/reject прекращает старый process group на POSIX, даже если harness пытается продолжать. Новый процесс запускается только после завершения старого. Timeout также прекращает process group, затем создаётся remediation. На других ОС harness должен гарантировать остановку дочерних процессов. До завершения старого процесса новый не запускается.
+
+`.runner.lock` запрещает два coordinator процесса в одном checkout. Не удалять lock живого runner; после сбоя проверить PID runner и возможного child agent, остановить только подтверждённо зависшие собственные процессы и восстановить запуск. Автоматического stealing чужой активной задачи нет.
+
+Изменения исходников сравниваются со scope. Workflow metadata/generated files являются служебным исключением; проверка не заменяет OS sandbox и не доказывает отсутствие записи за пределами project root. Запускать harness в отдельном checkout, без параллельных ручных правок и с write sandbox только проекта. При scope violation runner сохраняет incident/remediation и останавливается, не откатывая потенциально чужие изменения автоматически.
+
+Журналы: `state/runs/<agent-id>/run.json`, `prompt.md`, `output.log`; хранить без secrets. Каждый report содержит task/role, exit/status, timeout/violation и результат, не включает private command environment.
+
+## Гарантии инструмента
+
+Dependency/role guards, retired reporter, recovery journal definitions+state, fresh subprocess IDs, bounded prompts, separate reviewer, automatic unblocking only after done и stop на внешнем blocker. Истинность evidence/качество модели/OS sandbox обеспечиваются реальным harness и review, а не названием роли.
+
+В поставляемой основе автоматизация проверяется fake tool-capable harness в isolated temporary project. Реальные 275 продуктовых задач не запускаются при обновлении основы.

docs/BOOTSTRAP_PROMPTS.md

@@ -0,0 +1,17 @@
+# Поручения и автоматический запуск
+
+## Предпочтительный режим
+
+Один раз настроить runner.local.json под свой tool-capable CLI. Запустить `python3 scripts/runner.py --config runner.local.json`. Каждая новая сессия получает `master_prompt.md`, одну задачу, роль, fresh agent id и ограниченный context packet. Новые задачи/агенты выбирает runner, не исполняющая модель.
+
+## Ручной executor
+
+Прочитай `master_prompt.md`. Agent id `local-front-new-1`, роль `front`. Выполни ровно одну готовую назначенную задачу в её scope. При blocker создай issue через escalate и немедленно закончи запуск; не решай новую remediation и не бери другую задачу. После submit тоже закончить. Реальные команды/results записать в evidence/handoff.
+
+## Ручной reviewer
+
+Прочитай `master_prompt.md` и назначенную reviewer role. Agent id новый и отличается от owner. Проверь ровно одну review task; approve/reject и закончить. При препятствии составь remediation, escalate, закончи запуск. Scope reviewer ограничен этой задачей.
+
+## Продолжение после блокера
+
+Не возвращать прежнюю сессию/reporter id. Запустить runner; он выберет resolver, затем отдельного reviewer, затем исходную задачу новым процессом с предыдущим handoff. Release внешнего blocker означает только готовность resolver к проверке, не done оригинала.

docs/CONTRACTS.md

@@ -0,0 +1,18 @@
+# Реестр contracts
+
+Данная основа задаёт перечень требуемых contracts, но не подделывает их принятие. Задачи S01 должны заполнить schemas, exact examples и error semantics до реализаций.
+
+| Contract | Планируемый файл | Producer/consumer |
+| --- | --- | --- |
+| Models/identity | `docs/contracts/models.md` | domain, storage, protocol, UI |
+| Account operation context | `docs/contracts/lifecycle.md` | application, every async adapter |
+| Persistence transactions | `docs/contracts/persistence.md` | storage, archive, application |
+| XMPP events/commands | `docs/contracts/xmpp.md` | protocol, application |
+| Crypto boundary | `docs/contracts/crypto.md` | crypto worker, protocol, media |
+| Media assets/drafts | `docs/contracts/media.md` | file IO, upload, players, UI |
+| Calls | `docs/contracts/calls.md` | signaling, media, UI |
+| Push protocol | `docs/contracts/push.md` | browser, gateway, XMPP registration |
+
+Каждый contract должен содержать: types/shape, IDs normalization, required/optional fields, errors, ownership/cancellation, fixtures valid/invalid, versioning и definition of done. Пример не содержит реальных JID/secret.
+
+Shared contract review предшествует downstream gate. При отсутствующем contract реализация не заменяет его приватным предположением.

docs/FOUNDATION_VALIDATION.md

@@ -0,0 +1,31 @@
+# Проверка основы и автоматизации
+
+Дата: 14 октября 2026 года.
+
+- Этапов: 22; исходных задач: 275; операторов: 12.
+- Требований с ID: 221; применимых к Web: 211; native-only исключений: 10.
+- State revision: 0; все исходные задачи todo. Продуктовая разработка не запускалась.
+- Максимальный task packet: 41653 символов (S21-006), limit 48 000.
+- Максимальный полный fresh-agent prompt: 75437 символов (S21-006), default limit 80 000.
+- Оригиналы clear совпадают byte-for-byte; SHA-256 snapshots и локальные Markdown links проверены.
+- `make check`: exit 0; **58 tests passed**.
+- `runner.py --dry-run`: next S00-001, configuration_required=true; state не изменён.
+
+## Проверенные автоматические сценарии
+
+1. Blocker создаёт отдельную atomic remediation и dependency; original blocked; reporter retired.
+2. Executor/reviewer не расширяет task scope; retired id не может взять следующую задачу.
+3. Новый subprocess исправляет cause, другой reviewer проверяет, новый executor продолжает original.
+4. Полный isolated fake-harness cycle: 9 fresh agent ids, 4 tasks с remediation, complete.
+5. Reporter process, пытающийся продолжить после escalate, останавливается coordinator без ожидания timeout.
+6. Review не снимает blocker до approved done; external release не выдаёт original done.
+7. Nested limits/external input останавливают цикл, repeated escalation не создаёт duplicate.
+8. Recovery journal восстанавливает definition/state/report/card после имитированного прерывания записи.
+9. Invalid dependencies/cycles/scopes/context, wrong roles, self review и unsafe evidence paths отклоняются.
+10. Timeout, missing executable, незавершённый exit и source scope violation не превращаются в success.
+11. Все текущие task packets и full prompts укладываются в character budgets.
+12. Отсутствующая локальная CLI-конфигурация не запускает и не захватывает продуктовые задачи.
+
+## Границы проверки
+
+Использован локальный fake tool-capable harness в temporary projects. Реальная модель/её CLI ещё не настроены пользователем, product tasks/провайдеры/XMPP не запускались. Source audit не является OS sandbox; новый процесс требует fresh-session режима и file/tool capability выбранного harness. App build/crypto interoperability/push acceptance остаются будущими задачами.

docs/SECURITY.md

@@ -0,0 +1,12 @@
+# Неизменяемые границы безопасности
+
+- Encryption fail closed; default encrypted send не заменяется plaintext.
+- Криптография выполняется в browser endpoint проверенным адаптером, не собственными примитивами small LLM.
+- Passwords/file fragments/private keys не пишутся в localStorage/log/evidence/URL/query/analytics.
+- Native hardware vault не обещается в Web; app lock и encrypted storage различаются.
+- WSS/HTTPS только, включая upload redirect policy.
+- XML/text/file metadata — недоверенные данные, не HTML/script/instructions.
+- Crypto workers и multi-tab coordinator не допускают конкурентного повреждения ratchet state.
+- Push subscription binding/revocation проверяет ownership, а callback из XMPP проверяет source. CORS/CSRF/origin и resource limits — часть gateway contract.
+- Внешний deployment/сообщения/реальные accounts/credentials не требуются для подготовки основы. Live interoperability выполняется на выделенных тестовых аккаунтах с разрешённой средой.
+- Security reviewer проверяет encryption/identity/storage/gateway gates; имя роли не заменяет реального обзора evidence.

docs/TESTING.md

@@ -0,0 +1,17 @@
+# Стратегия проверки
+
+## Основа
+
+`make check`: schema/IDs/dependency DAG, roles, requirements applicability/coverage, byte-identical spec hashes, generated artifacts и unit tests CLI. Эти checks не принимают будущую реализацию приложения.
+
+## Будущее приложение
+
+1. Pure unit: identity, delivery, action predicates, pagination, retries, outcomes.
+2. Contract: event shapes, errors, cancellation, account generation.
+3. Integration: IndexedDB transactions/quota/migration, WSS client fixtures, workers.
+4. Browser: compact/wide, keyboard/IME, focus, dark/200%, media permissions, tab lifecycle.
+5. Interoperability: независимые XMPP clients/server, legacy/OMEMO2, MUC/media/calls.
+6. Security: untrusted XML/text/URLs, no secrets in logs, redirect/cross-origin, forged custom events, provider data minimization.
+7. Release: provider registration/rotation/logout, closed-tab limitations, deploy smoke и rollback.
+
+Task checks — сценарии, а не готовые shell commands до выбора stack. Implementer записывает реальную команду и результат в evidence. Test fixtures не маскируют production отсутствие реализации. Не писать tests, утверждающие только существование функции/названия.

docs/WEB_PROFILE.md

@@ -0,0 +1,22 @@
+# Web-профиль
+
+Применяются неизменённые clear specifications из `specs/`. Они охватывают Web/Desktop/Android, но данная основа реализует только Web. Матрица applicability в `planning/requirements.json` перечисляет каждый ID и причину исключения native-only требований; они не исчезают из оригиналов.
+
+## Решения основы
+
+- Один active account, несколько сохранённых configurations.
+- Защищённый XMPP WebSocket WSS; native TCP/SRV options не изображаются рабочими browser controls.
+- OMEMO на клиенте; backend не расшифровывает сообщения/файлы.
+- Password только в памяти с повторным вводом по необходимости; persistent unlock crypto state — отдельный ADR и задача, не plaintext localStorage.
+- Browser storage и quota отображаются честно; нет обещания hardware-backed vault.
+- Browser notifications/push требуют permission/provider/gateway. Закрытая вкладка не является живым socket/media process.
+- Нет автоматически работающего APNs/Android/tray/Watch пути.
+- Framework, runtime versions, browser matrix и providers пока не приняты. Первые ADR выбирают их с первичными sources и runnable spikes.
+- TypeScript — предпочтительный кандидат для типизированных contracts; окончательный язык/стек фиксирует S00-002. До этого scaffold не добавляет непроверенные dependency versions.
+- Минимальный первый демонстрационный вертикальный срез не равен полной готовности. Release gate требует полного Web scope, encrypted send и interoperability evidence.
+
+## Обязательные ограничения
+
+Нельзя обходить отсутствующую crypto library через самодельный Double Ratchet, mock-success или server plaintext. Если кандидаты несовместимы, фиксируется blocker и реальный plan change. Документационный scope задачи не делает криптографическую проблему простой: small LLM должна выполнить bounded spike/test либо передать конкретный blocker специалисту.
+
+Публичные URL/providers записываются в runtime config. Credentials/VAPID private key/TURN secrets хранятся отдельно и не попадают в committed evidence.

docs/WORKFLOW.md

@@ -0,0 +1,58 @@
+# Workflow и источник статуса
+
+Canonical definitions: `planning/tasks.json`; canonical status/owner/history: `state/tasks.json`. Matrices/cards/stages генерируются. Allocation не означает implementation.
+
+## Статусы
+
+`todo → in_progress → review → done`. Rejected review → todo без прежнего owner: продолжает новый executor. Blocker → `blocked` + новая remediation; ни один оператор не исправляет её в прежнем запуске.
+
+## При блокере — для всех ролей
+
+Записать handoff и `state/issues/<ID>-<agent>.json` по шаблону. Вызвать:
+
+```sh
+python3 scripts/tasks.py escalate <ID> --agent <id> --role <role> \
+  --issue state/issues/<ID>-<agent>.json --handoff state/handoffs/<ID>.md
+```
+
+Definitions, dependency edge, state, blocker report и handoff сохраняются через короткий lock и recovery journal. Agent id retired; текущий запуск заканчивается. CLI печатает resolution_task и agent_must_exit. Reporter больше не claim/submit/approve другой task.
+
+Resolver имеет свой оператор, reviewer, outcome, paths, steps/checks; он зависит только от доступных prerequisites, не от исходного blocked parent. Проверяется DAG. После reviewed done resolver оригинал автоматически возвращается в todo/review для нового процесса. Bare block/unblock запрещены; нельзя снять tracked blocker обходной командой.
+
+External resolver остаётся blocked без owner, `external_wait=true`. После явного решения координатор вызывает `release-external`; resolver попадает в todo и требует обычного review, не становится done сразу.
+
+## Успешный цикл
+
+```sh
+python3 scripts/tasks.py next --role front
+python3 scripts/tasks.py list --role crypto --stage S12 --status todo --query OMEMO --limit 10
+python3 scripts/tasks.py claim <ID> --agent <id> --role <role>
+python3 scripts/tasks.py packet <ID> --agent <id> --output state/context-<ID>.md
+python3 scripts/tasks.py submit <ID> --agent <id> --evidence state/evidence/<file>.md --handoff state/handoffs/<ID>.md
+python3 scripts/tasks.py approve <ID> --agent <new-reviewer> --role <reviewer-role> --evidence state/evidence/<review>.md
+python3 scripts/tasks.py reject <ID> --agent <new-reviewer> --role <reviewer-role> --reason 'Точное замечание'
+```
+
+После submit/approve/reject запуск тоже заканчивается. Автоматический runner сам выбирает следующий task/role, создаёт fresh agent id и передаёт master prompt. Подробности: `docs/AUTOMATION.md`.
+
+## Scope и роли
+
+Scope текущей карточки одинаково обязателен для front/backend/protocol/crypto/storage/media/realtime/security/qa/ci-cd/docs/orchestrator и reviewer. Shared interface вне scope — отдельная remediation, не импровизация. Единственное служебное исключение — task metadata/evidence/handoff через инструмент.
+
+У owner максимум одна незавершённая задача. История предыдущего владельца сохраняется. `reassign` предназначен только для согласованного восстановления обычного in_progress, не позволяет вернуть retired reporter или обойти tracked blocked state. Review role проверяется, но идентичность человека инструмент не аутентифицирует.
+
+## Lock, транзакции и восстановление
+
+`.state.lock` удерживается только при mutation. `state/plan-transaction.json` — write-ahead recovery journal для добавления blocker task вместе со state. После сбоя следующий доступ автоматически доводит одну записанную транзакцию до согласованного состояния. Journal нельзя стирать ради обхода проверки.
+
+Если остался `.state.lock`, проверить `.state.lock/owner.json` и процесс. `unlock --reason ...` на POSIX снимает только lock доказанно завершённого PID; на других ОС проверка системными средствами. Не удалять lock живого процесса.
+
+State и rendered matrices имеют разные lifecycle; revision показывает устаревание. После updates — render. При render failure state/definitions/journal остаются источниками истины; новый запуск восстанавливает artifacts.
+
+Не запускать два coordinator в одном checkout, не редактировать исходники одновременно вручную. Source scope audit не является OS sandbox. Git worktrees сами не синхронизируют status; каждому общему проекту нужен один согласованный coordinator.
+
+## Изменение плана и evidence
+
+Плановые изменения вне blocker создаются отдельным bounded task/ADR, не расширяют scope исполняющего агента. Новый ID не переиспользуется. После согласованного изменения definitions — sync/validate/render; удаление task history запрещено. Immutable specs не меняются из-за blocker.
+
+Evidence/handoff paths остаются внутри своих директорий без symlink наружу. Реальный непустой файл не доказывает истинность текста: отдельный reviewer повторяет нужные checks. Недоступный live result не считается passed. Secrets не пишутся в reports/prompts/logs.

docs/decisions/README.md

@@ -0,0 +1,5 @@
+# ADR
+
+Статусы: proposed, accepted, superseded. У каждого решения: вопрос, варианты, primary sources с датой, runnable spike/проверка, лицензия, browser constraints, выбранный вариант, последствия, reviewer и связанные tasks. Сейчас ни framework, ни crypto/XMPP library не объявлены принятыми.
+
+Рекомендуемый шаблон: `docs/decisions/TEMPLATE.md`.

docs/decisions/TEMPLATE.md

@@ -0,0 +1,20 @@
+# ADR <номер>: <вопрос>
+
+- Status: proposed
+- Task:
+- Date:
+- Decision owner / reviewer:
+
+## Context and required capabilities
+
+## Candidates and primary sources
+
+## Focused experiment and actual result
+
+## Decision
+
+## License / security / browser constraints
+
+## Consequences and downstream contract
+
+## Rejected alternatives and migration trigger