tasks ready 1

2026-06-09 09:43:34 +03:00
parent 8e8a3c3235
commit a7fb06cd8e
23 changed files with 2179 additions and 45 deletions
--- a/.opencode/command/speckit.plan.md
+++ b/.opencode/command/speckit.plan.md
@@ -36,6 +36,9 @@ You **MUST** consider the user input before proceeding (if not empty).
   - `.opencode/skills/semantics-svelte/SKILL.md`
   - `.opencode/skills/semantics-testing/SKILL.md`
   - `.specify/templates/plan-template.md`
+   - `FEATURE_DIR/contracts/ux/screen-models.md` (if `/speckit.ux` was run)
+   - `FEATURE_DIR/contracts/ux/api-ux.md` (if `/speckit.ux` was run)
+   - `FEATURE_DIR/contracts/ux/*-ux.md` (per-screen UX contracts)
   - relevant `docs/adr/*.md`

 3. **Execute the planning workflow** using the template structure:
@@ -44,6 +47,7 @@ You **MUST** consider the user input before proceeding (if not empty).
    - ERROR if a blocking constitutional or semantic conflict is discovered and cannot be justified.
    - Phase 0: generate `research.md` in `FEATURE_DIR`, resolving all material unknowns.
    - Phase 1: generate `data-model.md`, `contracts/modules.md`, optional machine-readable contract artifacts, and `quickstart.md` in `FEATURE_DIR`.
+    - Phase 1: if UX contracts exist, generate `traceability.md` — a requirements traceability matrix mapping Story → Model → API → Task → Test.
    - Materialize blocking ADR references and planning decisions inside the plan and downstream contracts.
    - Run `.specify/scripts/bash/update-agent-context.sh kilocode` after planning artifacts are written.

@@ -63,6 +67,12 @@ Research must resolve only implementation-shaping unknowns that matter for this
 - belief runtime instrumentation for C4/C5 flows
 - semantic validation boundaries and static verification workflow

+**If `/speckit.ux` was run before plan:**
+- `screen-models.md` defines Model inventory → use directly, don't re-discover
+- `api-ux.md` defines API shapes → use as @DATA_CONTRACT source for backend Pydantic schemas
+- `<screen>-ux.md` defines UX contracts → use as @UX_STATE/@UX_FEEDBACK source for component contracts
+- Generated `.svelte.ts` model files in `frontend/src/lib/models/` → DO NOT regenerate; reference them via `@RELATION BINDS_TO` from component contracts
+
 Write `research.md` with concise sections:
 - Decision
 - Rationale
@@ -230,6 +240,93 @@ Generate its full `#region` header in `contracts/modules.md` under its parent mo

 If a planned contract depends on unknown schema, relation target, or ADR identity, emit `[NEED_CONTEXT: target]` instead of fabricating placeholders.

+### Fixture Generation (MANDATORY for C3+ contracts with @TEST_EDGE)
+
+For every C3+ contract that declares `@TEST_EDGE`, `@POST`, or `@REJECTED` guardrails, generate **canonical test fixtures** in `FEATURE_DIR/fixtures/`. Canonical fixtures live beside the spec — they are the design-time source of truth. Executable fixtures are materialized into `tests/` later by `/speckit.tasks`.
+
+**Output structure:**
+
+```text
+specs/<feature>/fixtures/
+├── manifest.md              # Fixture index with GRACE contracts
+├── api/
+│   ├── <contract>_valid.json
+│   ├── <contract>_missing_field.json
+│   ├── <contract>_invalid_type.json
+│   ├── <contract>_external_fail.json
+│   └── <contract>_rejected_path.json
+└── model/
+    ├── <model>_valid.json
+    ├── <model>_edge_case.json
+    └── <model>_invariant.json
+```
+
+**`manifest.md` — fixture index with GRACE contracts:**
+
+```markdown
+#region FixtureManifest [C:3] [TYPE ADR] [SEMANTICS test,fixture,[DOMAIN]]
+@defgroup Fixtures Canonical test fixtures for [FEATURE].
+
+## @{ Fixture FX_Auth.Login.Valid [C:2] [TYPE Block] [SEMANTICS test,auth,fixture]
+@BRIEF Valid login request/response pair.
+@RELATION VERIFIES -> [Api.Auth.Login]
+@TEST_FIXTURE: valid_login -> fixtures/api/auth_login_valid.json
+@TEST_INVARIANT: TokenIssued -> VERIFIED_BY: [Test.Api.Auth]
+## @} Fixture FX_Auth.Login.Valid
+
+## @{ Fixture FX_Auth.Login.MissingPassword [C:2] [TYPE Block] [SEMANTICS test,auth,fixture]
+@BRIEF Missing password field — @TEST_EDGE: missing_field.
+@RELATION VERIFIES -> [Api.Auth.Login]
+@TEST_EDGE: missing_field -> 422 VALIDATION_ERROR
+@TEST_FIXTURE: missing_password -> fixtures/api/auth_login_missing_field.json
+## @} Fixture FX_Auth.Login.MissingPassword
+
+## @{ Fixture FX_Migration.EnvReset [C:2] [TYPE Block] [SEMANTICS test,migration,fixture]
+@BRIEF Model invariant: changing source env resets selection.
+@RELATION VERIFIES -> [Migration.Model]
+@TEST_INVARIANT: env_reset_selection -> VERIFIED_BY: [Test.Migration.Model]
+@TEST_FIXTURE: env_reset -> fixtures/model/migration_env_reset.json
+## @} Fixture FX_Migration.EnvReset
+```
+
+**JSON fixture format:**
+
+```json
+{
+  "fixture_id": "FX_Auth.Login.MissingPassword",
+  "verifies": "Api.Auth.Login",
+  "edge": "missing_field",
+  "input": {
+    "username": "admin"
+  },
+  "expected": {
+    "status": 422,
+    "error_code": "VALIDATION_ERROR",
+    "error_detail": "Field 'password' is required"
+  }
+}
+```
+
+**Generation rules:**
+- **One JSON file per fixture** — named `<contract_snake>_<edge>.json`
+- **Minimum 5 per C3+ contract**: valid, missing_field, invalid_type, external_fail, rejected_path
+- **Expected values ALWAYS hardcoded** — never derived from implementation (anti-tautology)
+- **Input values are concrete** — real strings, numbers, objects, not pseudocode
+- **Fixture ID format**: `FX_<Domain>.<Name>` — hierarchical, matches contract hierarchy
+- **@TEST_FIXTURE in manifest** points to the JSON file path
+- **@RELATION VERIFIES** links fixture to production contract
+- For `@REJECTED` paths: expected MUST include error/failure, proving the path is unreachable
+- For model invariants: input = state before action, expected = state after action
+- Do NOT generate executable test files here — only canonical JSON fixtures
+
+### Fixture Traceability
+
+Extend `traceability.md` with a Fixture column:
+
+| Story | Model | Fixture | Task | Test |
+|-------|-------|---------|------|------|
+| US1 | Api.Auth.Login | FX_Auth.Login.Valid | T017 | Test.Api.Auth
+
 ### Quickstart Output

 Generate `quickstart.md` using real repository verification paths:
@@ -239,6 +336,41 @@ Generate `quickstart.md` using real repository verification paths:
 - Frontend lint: `cd frontend && npm run lint`
 - Docker: `docker compose up --build`

+### Traceability Matrix Output
+
+If UX contracts exist (`contracts/ux/` was generated by `/speckit.ux`), generate `traceability.md` — a requirements traceability matrix (RTM) mapping every user story through its implementation chain:
+
+```markdown
+#region Traceability [C:3] [TYPE ADR] [SEMANTICS traceability,rtm,[DOMAIN]]
+@defgroup Trace Matrix Requirements → Model → API → Task → Test for [FEATURE].
+
+## Traceability Matrix
+
+| Story | Screen | Model | Fixture | API Endpoint | Backend Task | Frontend Task | Test |
+|-------|--------|-------|---------|-------------|-------------|--------------|------|
+| US1: [Title] | /route | Domain.Model | FX_Domain.Valid | GET /api/... | T017 | T015 | Test.Domain |
+| US1: [Title] | /route | Domain.Model | FX_Domain.MissingField | POST /api/... | T018 | T019 | Test.Domain.Edge |
+
+## Impact Analysis Quick Reference
+
+| If you change... | These fixtures verify it | These tests verify it | These screens depend |
+|-----------------|------------------------|----------------------|---------------------|
+| `GET /api/dashboards` | FX_Dashboards.Hub.* | Test.Dashboards.Hub | /dashboards, /migration |
+| `Dashboards.Hub` model | FX_Dashboards.EnvReset | Test.Dashboards.Hub | /dashboards |
+
+#endregion Traceability
+```
+
+**Generation rules:**
+- One row per unique (Story, API Endpoint, Screen) tuple
+- Model column: `[TYPE Model]` contract ID from `screen-models.md`
+- API column: endpoint from `api-ux.md` or `contracts/modules.md`
+- Task columns: task IDs from `tasks.md` (to be filled after `/speckit.tasks` — leave as `T???` if tasks not yet generated)
+- Test column: test contract ID pattern `Test.<Domain>.<Name>`
+- Impact table: derived from `@RELATION` edges in contracts — invert the dependency graph
+- Grep-friendly: `grep "Dashboards.Hub" traceability.md` → all rows for that model
+- Agent zombie mode: without MCP tools, `grep "<contract>" traceability.md` replaces `impact_analysis`
+
 ## Key Rules

 - Use absolute paths in workflow execution.