docs: resolve story 3.6 Draft and MCP scope
This commit is contained in:
1 parent
7ffde8885d
commit
7c53faa727
1 file changed
+164
@@ -0,0 +1,164 @@
|
||||
---
|
||||
title: '3.6 — Сохранять typed static Resource Drafts'
|
||||
type: feature
|
||||
created: '2026-10-01'
|
||||
status: blocked
|
||||
review_loop_iteration: 0
|
||||
followup_review_recommended: false
|
||||
context:
|
||||
- '{project-root}/_bmad-output/implementation-artifacts/epic-3-context.md'
|
||||
warnings: [oversized]
|
||||
deferred: []
|
||||
---
|
||||
|
||||
<intent-contract>
|
||||
|
||||
## Intent
|
||||
|
||||
**Problem:** Администратору необходимо безопасно сохранять text, JSON и binary Resource Drafts с typed contract, bounded artifact и безопасным preview.
|
||||
|
||||
**Approach:** Создать отдельный typed Resource aggregate и persistence/API для Draft, сохраняя content bytes в существующем content-addressed artifact store. AC ниже уточнены решением пользователя: эта story ограничена Draft/Admin preview и безопасным download; MCP read и negotiated representation реализуются и проверяются в Story 3.8.
|
||||
|
||||
## Boundaries & Constraints
|
||||
|
||||
**Always:** Отдельные Resource ID/version/lifecycle, CapabilityKind::Resource и sensitivity; immutable Published contract; bounded bytes, exact digest и metadata; стабильные URI/name; UTF-8 и JSON validation без изменения semantics; безопасные preview/download и ошибки без content leakage. Следовать существующим Rust, registry, migration и API conventions.
|
||||
|
||||
**Never:** Untyped Operation subtype, универсальный JSON blob, filesystem paths/upload filenames/mutable external references в published contract; исполнение HTML/SVG в origin Crank; unbounded content в DOM/logs/errors. Не писать и не откатывать sprint-status.yaml. Не реализовывать соседние stories без разрешённой границы intent.
|
||||
|
||||
<frozen-after-approval>
|
||||
|
||||
### Согласованная граница Story 3.6
|
||||
|
||||
Решение пользователя от 2026-10-01 (вариант 1): Story 3.6 сохраняет typed static Resource Drafts и предоставляет Draft/Admin preview и безопасный download. Для binary проверяются MIME, точный byte size, bounded opaque bytes и безопасная выдача без text decoding, без unbounded bytes в DOM/telemetry и без content в logs/errors.
|
||||
|
||||
`resources/list`, `resources/read`, MCP version adapter, negotiated binary representation и их wire qualification относятся к Story 3.8. Publication и exact Agent binding остаются в Story 3.7; Story 3.6 задаёт typed domain/persistence contract, но не реализует эти lifecycle действия ради MCP read. Условие завершения Story 3.6 не требует MCP surface или будущей qualification. Эта граница определяет чтение AC ниже и исходной формулировки binary AC в epics.md.
|
||||
|
||||
</frozen-after-approval>
|
||||
|
||||
## I/O & Edge-Case Matrix
|
||||
|
||||
| Scenario | Input / State | Expected Output / Behavior | Error Handling |
|
||||
|----------|--------------|---------------------------|----------------|
|
||||
| Text | Bounded UTF-8 | Exact bytes и digest | Invalid UTF-8/oversize: stable finding, без truncation |
|
||||
| JSON | Bounded valid JSON | Сохранение data semantics и exact artifact | Malformed/oversize отклоняются до publication |
|
||||
| Binary Draft/Admin preview/download | Bounded opaque bytes + MIME | Точные MIME/byte size, inert metadata preview и безопасная binary выдача без text decoding; без unbounded bytes в DOM/telemetry | Safe finding, без content в logs/errors |
|
||||
| MCP read / negotiated representation | Bound Published Resource Version | Реализация и wire qualification в Story 3.8 после Story 3.7; не критерий завершения 3.6 | Не добавлять MCP surface в 3.6 |
|
||||
| Active content | HTML/SVG | Inert preview либо безопасный attachment | Safe Content-Type, nosniff, CSP/sandbox, sanitized filename |
|
||||
| Integrity | Несовпадение digest/metadata | Fail closed | Safe error без filesystem/content leakage |
|
||||
|
||||
</intent-contract>
|
||||
|
||||
## Code Map
|
||||
|
||||
- `crates/crank-core/src/ids.rs` — существующий define_id! pattern; ResourceId/ResourceVersionId отсутствуют.
|
||||
- `crates/crank-core/src/lib.rs`, `crates/crank-registry/src/model.rs` — domain exports и PublishedAgentTool; отдельного Resource aggregate и CapabilityKind нет.
|
||||
- `crates/crank-artifacts/src/store.rs`, `model.rs` — ArtifactStore put/read API и ArtifactRef с digest; reuse для exact bytes.
|
||||
- `crates/crank-registry/src/model/artifact_source.rs` — ArtifactSourceSensitivity относится к OpenAPI, не является готовым Resource sensitivity contract.
|
||||
- `crates/crank-registry/src/migrations.rs`, `migrations/` — canonical authority, versioned SQL/Rust migrations; Resource tables отсутствуют.
|
||||
- `apps/admin-api/src/routes/agents.rs`, `service/agents.rs`, `dto.rs` — Draft lifecycle и DTO conventions.
|
||||
- `apps/admin-api/src/service/imports/verified_preview.rs` — существующий artifact preview pattern.
|
||||
- `apps/ui/js/openapi-import.js`, `i18n.js` — vanilla JS preview и RU/EN conventions; Resource UI отсутствует.
|
||||
- `crates/crank-community-mcp/src/jsonrpc.rs:3` — supported revisions 2025-03-26, 2025-06-18, 2025-11-25; negotiation есть, Resource version adapter отсутствует.
|
||||
- `crates/crank-community-mcp/src/app.rs:827` — method dispatch без resources/list/read; `:1378` — capabilities только tools, listChanged=false.
|
||||
- `apps/mcp-server/tests/integration/transport_protocol.rs`, `catalog_access.rs` — существующие wire integration surfaces; Resource evidence отсутствует.
|
||||
- `justfile:59` — обязательный just verify.
|
||||
- `_bmad-output/planning-artifacts/epics.md:2462` — read-only исходный intent 3.6; `:2520` — 3.7 publication/binding; `:2568` — 3.8 MCP read.
|
||||
|
||||
## Tasks & Acceptance
|
||||
|
||||
**Execution (предварительно; gate не пройден):**
|
||||
- [ ] `crates/crank-core/src/ids.rs`, `lib.rs`, новый Resource domain module — typed identity/kinds/lifecycle/sensitivity и bounded validation.
|
||||
- [ ] `crates/crank-registry/src/model.rs`, `repository.rs`, `postgres/`, `migrations/`, `docs/schemas/migration-sequence.json` — отдельная typed Draft persistence и canonical migration contract.
|
||||
- [ ] `crates/crank-artifacts/src/`, `tests/` — reuse digest storage и проверить Resource artifact integrity.
|
||||
- [ ] `apps/admin-api/src/routes/`, `service/`, `dto.rs` — authenticated Draft create/update/upload/preview с stable findings и safe download headers.
|
||||
- [ ] `apps/ui/js/`, `apps/ui/css/`, `apps/ui/tests/` — безопасный Resource preview/download согласно согласованной границе.
|
||||
- [ ] `crates/crank-core/tests/`, `crates/crank-registry/tests/`, `apps/admin-api/tests/` — domain/artifact/API edge cases; regression cases до fix.
|
||||
|
||||
MCP implementation и wire tests не входят в задачи 3.6: `crates/crank-community-mcp/src/` и `apps/mcp-server/tests/` для Resource read/version adapter относятся к 3.8.
|
||||
|
||||
**Acceptance Criteria (с уточнённой пользователем границей Draft/Admin):**
|
||||
**Given** Resource domain model
|
||||
**When** добавляется persistence и API contract
|
||||
**Then** Resource является отдельным typed aggregate с собственными ID/version/lifecycle, `CapabilityKind::Resource`, sensitivity и immutable Published Version
|
||||
**And** не хранится как untyped Operation subtype или универсальный JSON blob.
|
||||
|
||||
**Given** новый Resource Draft
|
||||
**When** администратор выбирает static text, JSON или binary kind
|
||||
**Then** задаются URI, name, description, MIME type, sensitivity и bounded content
|
||||
**And** URI и name валидируются как стабильные capability identifiers.
|
||||
|
||||
**Given** static content
|
||||
**When** оно сохраняется
|
||||
**Then** bytes размещаются в content-addressed artifact store, а Resource Version хранит exact digest и metadata
|
||||
**And** filesystem path, raw upload filename или mutable external reference не входит в published contract.
|
||||
|
||||
**Given** JSON Resource
|
||||
**When** Draft сохраняется или preview-ится
|
||||
**Then** content валидируется как JSON и возвращается без изменения data semantics
|
||||
**And** malformed либо oversized JSON отклоняется до publication.
|
||||
|
||||
**Given** text Resource
|
||||
**When** content принимается
|
||||
**Then** он сохраняет валидный UTF-8 в пределах configured size
|
||||
**And** invalid encoding или unsafe truncation отклоняются с stable finding.
|
||||
|
||||
**Given** binary Resource
|
||||
**When** Draft preview-ится или скачивается через Admin API/UI
|
||||
**Then** соблюдаются MIME, точный byte size и configured size limit; preview показывает inert metadata, а download безопасно возвращает exact binary bytes
|
||||
**And** content не декодируется как text, unbounded bytes не попадают в DOM/telemetry, content не попадает в logs/errors.
|
||||
|
||||
MCP read, version adapter и negotiated binary representation реализуются и проверяются в Story 3.8; они не являются AC завершения Story 3.6.
|
||||
|
||||
**Given** Resource с active либо browser-renderable content type, включая HTML или SVG
|
||||
**When** Admin UI показывает preview/download
|
||||
**Then** untrusted bytes не исполняются в origin Crank: используется inert text/metadata, sandboxed isolated preview либо attachment download по explicit allowlist
|
||||
**And** response применяет safe `Content-Type`, `nosniff`, CSP/sandbox и filename sanitization без content sniffing.
|
||||
|
||||
**Given** static Resource Draft suite
|
||||
**When** выполняются domain, artifact и API tests
|
||||
**Then** покрыты text/JSON/binary validation, MIME/size, active-content preview, malformed encoding и artifact integrity
|
||||
**And** `just verify` проходит.
|
||||
|
||||
## Spec Change Log
|
||||
|
||||
- 2026-10-01 — пользователь выбрал вариант 1 в bmad-loop-resolve: 3.6 ограничена Draft/Admin preview/download; MCP read/version adapter/negotiated representation закреплены за 3.8. Уточнены frozen intent, binary AC, матрица и verification scope; статус оставлен оркестратору.
|
||||
|
||||
## Review Triage Log
|
||||
|
||||
## Design Notes
|
||||
|
||||
### Разрешённая граница intent
|
||||
|
||||
Исходный binary AC объединял Admin preview и MCP read, хотя цепочка зависимостей 3.6 → 3.7 → 3.8 относит publication/binding к 3.7, а MCP discovery/read и version adapter к 3.8. Пользователь выбрал вариант 1: в 3.6 проверяются только Draft/Admin preview/download, в 3.8 — exact published MCP read и negotiated representation. Frozen intent и AC выше фиксируют это решение; первоначальные результаты остановок ниже сохранены как история, а не актуальное требование MCP scope.
|
||||
|
||||
## Verification
|
||||
|
||||
Для повторного запуска 3.6: domain/artifact/registry/Admin API tests для text/JSON/binary Drafts, exact bytes/digest, MIME/size, encoding, safe preview/download и integrity; `just verify`, UI проверки при UI изменениях. MCP wire tests всех supported revisions, включая negotiated representation, выполняются в 3.8. В resolve-сессии код не реализовывался и тесты не запускались; исторические результаты предыдущих запусков приведены ниже.
|
||||
|
||||
## Auto Run Result
|
||||
|
||||
Status: blocked
|
||||
Blocking condition: intent gap
|
||||
|
||||
- Workflow остановлен на step-02 Plan по правилу intent gaps; код не изменён, реализация/ревью/проверка AC не выполнены.
|
||||
- Baseline получен напрямую через `git rev-parse HEAD`: `7ffde8885ddd7c0196134f6085330536911a72be`.
|
||||
- Исходное рабочее дерево чистое, ветка соответствует story; `git add --refresh -- .` завершился успешно.
|
||||
- Составлен Epic 3 context и read-only Code Map; ведущий проверил MCP dispatch, capabilities и negotiation непосредственно в коде.
|
||||
- Нет действий AC, требующих покупки/настройки внешнего сервиса человеком. `awaiting-operator` неприменим: препятствие — противоречие границ спецификации внутри repo.
|
||||
- `sprint-status.yaml` не изменён и не использован как доказательство верификации.
|
||||
- Неразрешённый вопрос: должна ли 3.6 включать MCP binary read, или этот AC ограничивается Draft/Admin preview, а MCP проверяется в 3.8?
|
||||
|
||||
- Финальные проверки: `git diff --check` успешен, tracked working tree чистое. Документы `_bmad-output` игнорируются Git; commit кода не создавался.
|
||||
- Read-only Pi завершил handoff; его tmux/Pi-сессия остановлена после завершения инструментов.
|
||||
- `docker volume prune -f` завершён, освобождено 0B; активные контейнеры и именованные тома не удалялись. Повторные `docker system df`, `df -h /`, `btrfs filesystem usage /`: доступно около 110 ГБ, Metadata DUP 998.34 MiB / 7.01 GiB, global reserve used=0. Подробный per-device usage недоступен без root, общий запас metadata достаточен.
|
||||
|
||||
### Повторный запуск 2026-10-01
|
||||
|
||||
Status: blocked
|
||||
Blocking condition: blocked spec supplied
|
||||
|
||||
- При маршрутизации story найдена существующая спецификация со статусом `blocked`; решение о границе Draft/Admin preview и MCP read не предоставлено. По HALT workflow реализация и ревью не запускались.
|
||||
- Это нерешённая граница intent внутри репозитория, а не HUMAN-only operator action; статус `awaiting-operator` неприменим.
|
||||
- Текущая ревизия: `7ffde8885ddd7c0196134f6085330536911a72be`. Код и `sprint-status.yaml` не изменялись; commit не создавался.
|
||||
- `git diff --check` успешен, tracked working tree чистое. Тесты не запускались, фоновые исполнители не создавались.
|
||||
- `docker volume prune -f` завершён (0B); последующие `docker system df`, `df -h /` и `btrfs filesystem usage /` успешны. Свободно около 110 ГБ, Metadata DUP использует 998.16 MiB из 7.01 GiB, global reserve used=0; подробный per-device usage недоступен без root.
|
||||
Reference in new issue
Block a user