docs(validation): update agent configs, skills, ADRs, specs
- qa-tester: add validation v2 testing checklist - speckit.plan: add component reuse scan for frontend - molecular-cot-logging: add Svelte logger + CLI reader - semantics-svelte: add RSM model-first protocol, frontend stack - templates: update plan/tasks/ux-reference templates - ADR-0004: add llm_dashboard_validation plugin registration - ADR-0008: add assistant tool registry for v2 validation - Specs: update 017 tasks from 51 to 99
This commit is contained in:
@@ -17,12 +17,13 @@
|
||||
the iteration process.
|
||||
-->
|
||||
|
||||
**Language/Version**: Python 3.13+ (backend), JavaScript/TypeScript (frontend Svelte 5)
|
||||
**Primary Dependencies**: FastAPI, SQLAlchemy, APScheduler (backend); SvelteKit, Vite, Tailwind CSS (frontend)
|
||||
**Language/Version**: Python 3.13+ (backend), TypeScript (frontend Svelte 5 runes-only)
|
||||
**Primary Dependencies**: FastAPI, SQLAlchemy, APScheduler (backend); SvelteKit 5, Vite, Tailwind CSS (frontend)
|
||||
**Storage**: PostgreSQL 16
|
||||
**Testing**: pytest (backend), vitest + @testing-library/svelte (frontend)
|
||||
**Testing**: pytest (backend), vitest (L1 model tests without render + L2 UX tests with @testing-library/svelte)
|
||||
**Target Platform**: Linux server (Docker), modern browsers
|
||||
**Project Type**: web application (FastAPI REST + WebSocket backend, SvelteKit SPA frontend)
|
||||
**Frontend Architecture**: TypeScript-first, model-first (Screen Models via `.svelte.ts`), runes-only (`$state`, `$derived`, `$effect`), typed callback props (no `createEventDispatcher`)
|
||||
**Performance Goals**: [domain-specific, e.g., <200ms p95 API latency, 60fps UI]
|
||||
**Constraints**: [domain-specific, e.g., <100MB memory per container, RBAC enforcement, offline-capable Docker bundle]
|
||||
**Scale/Scope**: [domain-specific, e.g., 50 concurrent users, 1000 dashboards, 10 plugins]
|
||||
@@ -31,7 +32,7 @@
|
||||
|
||||
*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*
|
||||
|
||||
[Evaluate against constitution.md and semantics.md. Explicitly confirm semantic protocol compliance, complexity-driven contract coverage, UX-state compatibility (Svelte 5 runes), async boundaries (FastAPI), API-wrapper rules, RBAC/security constraints (local auth + ADFS SSO), plugin lifecycle rules, and any required belief-state/logging constraints for Complexity 4/5 Python modules.]
|
||||
[Evaluate against constitution.md and semantics.md. Explicitly confirm semantic protocol compliance, complexity-driven contract coverage, TypeScript-first frontend with typed Screen Models (`.svelte.ts`), UX-state compatibility (Svelte 5 runes-only), async boundaries (FastAPI), API-wrapper rules, RBAC/security constraints (local auth + ADFS SSO), plugin lifecycle rules, and any required belief-state/logging constraints for Complexity 4/5 Python modules.]
|
||||
|
||||
## Project Structure
|
||||
|
||||
@@ -64,10 +65,12 @@ frontend/
|
||||
├── src/
|
||||
│ ├── routes/ # SvelteKit pages
|
||||
│ ├── lib/
|
||||
│ │ ├── components/ # Reusable Svelte 5 components
|
||||
│ │ ├── stores/ # Svelte rune stores ($state, $derived)
|
||||
│ │ └── api/ # API client modules
|
||||
│ └── i18n/ # Internationalization
|
||||
│ │ ├── components/ # Reusable Svelte 5 components (thin rendering layer)
|
||||
│ │ ├── models/ # Screen Models (.svelte.ts — typed, Svelte-reactive state machines)
|
||||
│ │ ├── stores/ # Svelte stores (cross-route state: auth, notifications)
|
||||
│ │ └── api/ # API client modules (fetchApi/requestApi wrappers)
|
||||
│ ├── types/ # TypeScript DTOs — MUST match backend Pydantic schemas
|
||||
│ └── services/ # Service layer (gitService, taskService)
|
||||
└── tests/ # vitest tests
|
||||
|
||||
docker/ # Docker configurations
|
||||
@@ -79,18 +82,23 @@ docker/ # Docker configurations
|
||||
|
||||
> Use this section to drive Phase 1 artifacts, especially `contracts/modules.md`.
|
||||
|
||||
- Classify each planned module/component with `@COMPLEXITY: 1..5`.
|
||||
- Use comment-anchor syntax appropriate for each context:
|
||||
- Python: `# [DEF:id:Type]`
|
||||
- Svelte markup: `<!-- [DEF:id:Type] -->`
|
||||
- Svelte script: `// [DEF:id:Type]`
|
||||
- Classify each planned module/component/model with `[C:N]` complexity in the `#region` anchor.
|
||||
- Use canonical anchor syntax appropriate for each context:
|
||||
- Python: `# #region ContractId [C:N] [TYPE TypeName] [SEMANTICS tags]` / `# #endregion ContractId`
|
||||
- Svelte markup: `<!-- #region ContractId [C:N] [TYPE Component] [SEMANTICS tags] -->` / `<!-- #endregion ContractId -->`
|
||||
- Svelte/TypeScript model: `// #region ModelName [C:N] [TYPE Model] [SEMANTICS tags]` / `// #endregion ModelName`
|
||||
- Markdown/ADR: `## @{ ContractId [C:N] [TYPE TypeName]` / `## @} ContractId`
|
||||
- **Legacy `[DEF:id:Type]` syntax is deprecated** — use `#region` format exclusively.
|
||||
- **Model files use `.svelte.ts` extension** — canonical format for contracts with Svelte reactive primitives (`$state`, `$derived`, `$effect`).
|
||||
- Match contract density to complexity:
|
||||
- Complexity 1: anchors only (DTOs, simple constants)
|
||||
- Complexity 2: `@PURPOSE` (utility functions, pure helpers)
|
||||
- Complexity 3: `@PURPOSE`, `@RELATION`; Svelte components also `@UX_STATE`
|
||||
- Complexity 4: `@PURPOSE`, `@RELATION`, `@PRE`, `@POST`, `@SIDE_EFFECT`; Python also `belief_scope`/`reason`/`reflect` markers; Svelte also `@UX_FEEDBACK`, `@UX_RECOVERY`, `@UX_REACTIVITY`
|
||||
- Complexity 5: level 4 + `@DATA_CONTRACT`, `@INVARIANT` + `@RATIONALE`/`@REJECTED` decision memory
|
||||
- C1: anchors only (DTOs, simple constants)
|
||||
- C2: typically adds `@BRIEF` (utility functions, pure helpers)
|
||||
- C3: typically adds `@RELATION`; Svelte also `@UX_STATE`; TypeScript also `@STATE`/`@ACTION`
|
||||
- C4: typically adds `@PRE`, `@POST`, `@SIDE_EFFECT`; Python also `belief_scope`/`reason`/`reflect` markers; Svelte also `@UX_FEEDBACK`, `@UX_RECOVERY`, `@UX_REACTIVITY`
|
||||
- C5: C4 + `@DATA_CONTRACT`, `@INVARIANT` + `@RATIONALE`/`@REJECTED` decision memory
|
||||
- **Screen Models** (`[TYPE Model]`) are C4/C5 contracts that declare screen-level state, invariants, and actions. A component that reads/writes model state declares `@RELATION BINDS_TO -> [ModelId]`. See `semantics-svelte` §IIIa.
|
||||
- Write relations only in canonical form: `@RELATION PREDICATE -> TARGET_ID`
|
||||
- Allowed predicates: `DEPENDS_ON`, `CALLS`, `INHERITS`, `IMPLEMENTS`, `DISPATCHES`, `BINDS_TO`, `CALLED_BY`, `VERIFIES`.
|
||||
- If any relation target, DTO, or contract dependency is unknown, emit `[NEED_CONTEXT: target]` instead of inventing placeholders.
|
||||
|
||||
## Complexity Tracking
|
||||
|
||||
@@ -82,18 +82,23 @@ Examples of foundational tasks (adjust based on your project):
|
||||
### Tests for User Story 1 (OPTIONAL - only if tests requested) ⚠️
|
||||
|
||||
> **NOTE: Write these tests FIRST, ensure they FAIL before implementation**
|
||||
> **For frontend stories: L1 model tests (no render) come BEFORE L2 component tests (with render).**
|
||||
|
||||
- [ ] T010 [P] [US1] Contract test for [endpoint] in tests/contract/test_[name].py
|
||||
- [ ] T011 [P] [US1] Integration test for [user journey] in tests/integration/test_[name].py
|
||||
- [ ] T010 [P] [US1] L1 model test for [ModelName] invariants in frontend/src/lib/models/__tests__/[ModelName].test.ts
|
||||
- [ ] T011 [P] [US1] L2 UX test for [Component] in frontend/src/routes/[path]/__tests__/[page].ux.test.ts
|
||||
- [ ] T012 [P] [US1] Contract test for [endpoint] in tests/contract/test_[name].py
|
||||
- [ ] T013 [P] [US1] Integration test for [user journey] in tests/integration/test_[name].py
|
||||
|
||||
### Implementation for User Story 1
|
||||
|
||||
- [ ] T012 [P] [US1] Create [Entity1] model in src/models/[entity1].py
|
||||
- [ ] T013 [P] [US1] Create [Entity2] model in src/models/[entity2].py
|
||||
- [ ] T014 [US1] Implement [Service] in src/services/[service].py (depends on T012, T013)
|
||||
- [ ] T015 [US1] Implement [endpoint/feature] in src/[location]/[file].py
|
||||
- [ ] T016 [US1] Add validation and error handling
|
||||
- [ ] T017 [US1] Add logging for user story 1 operations
|
||||
- [ ] T014 [P] [US1] Define TypeScript types in frontend/src/types/[feature].ts (DTOs matching backend Pydantic schemas)
|
||||
- [ ] T015 [P] [US1] Create [ScreenName]Model in frontend/src/lib/models/[ScreenName]Model.svelte.ts
|
||||
- [ ] T016 [P] [US1] Create [Entity] model in backend/src/models/[entity].py
|
||||
- [ ] T017 [US1] Implement [Service] in backend/src/services/[service].py
|
||||
- [ ] T018 [US1] Implement [endpoint/feature] in backend/src/api/[file].py
|
||||
- [ ] T019 [US1] Create [Component] as thin rendering layer in frontend/src/routes/[...] (binds to model via @RELATION BINDS_TO -> [ModelId])
|
||||
- [ ] T020 [US1] Add @INVARIANT validation in model actions
|
||||
- [ ] T021 [US1] Add belief-runtime instrumentation in model actions for C4/C5 flows
|
||||
|
||||
**Checkpoint**: At this point, User Story 1 should be fully functional and testable independently
|
||||
|
||||
@@ -253,3 +258,7 @@ With multiple developers:
|
||||
- For Complexity 4/5 Python modules, include tasks for belief-state logging paths with `logger.reason()`, `logger.reflect()`, and `belief_scope` where required
|
||||
- For Complexity 5 or explicitly test-governed contracts, include tasks that cover `@TEST_CONTRACT`, `@TEST_SCENARIO`, `@TEST_FIXTURE`, `@TEST_EDGE`, and `@TEST_INVARIANT`
|
||||
- Never create tasks from legacy `@TIER` alone; complexity is the primary execution signal
|
||||
- **Model-first frontend tasks follow this order: types → model → L1 model tests → component → L2 UX tests**
|
||||
- **Screen Models use `.svelte.ts` extension** — create them in `frontend/src/lib/models/`
|
||||
- **Two-layer testing: L1 (model invariants, no render, ~27ms) comes BEFORE L2 (UX contracts, with render)**
|
||||
- **Backend tasks are pinned to `backend/src/`, frontend tasks to `frontend/src/`** — cross-stack tasks reference both
|
||||
|
||||
@@ -40,10 +40,11 @@ $ command --flag value
|
||||
* **[Button Name]**: Primary action. Color: Blue.
|
||||
* **[Input Field]**: Placeholder text: "Enter your name...". Validation: Real-time.
|
||||
* **Contract Mapping**:
|
||||
* **`@UX_STATE`**: Enumerate the explicit UI states that must appear later in `contracts/modules.md`
|
||||
* **`@UX_STATE`**: Enumerate the explicit UI states that must appear later in `contracts/modules.md`. For complex screens, these derive from the Screen Model's `@STATE` declarations.
|
||||
* **`@UX_FEEDBACK`**: Define visible system reactions for success, validation, and failure
|
||||
* **`@UX_RECOVERY`**: Define what the user can do after failure or degraded state
|
||||
* **`@UX_REACTIVITY`**: Note expected Svelte rune bindings with `$state`, `$derived`, `$effect`, `$props`
|
||||
* **`@UX_REACTIVITY`**: Note the model-driven reactive chain: Model atoms (`$state`, `$derived`) → component props → DOM binding. For route-level data loading, use SvelteKit `load()` functions; `$effect` is for browser-side side effects only.
|
||||
* **Screen Model**: For screens with cross-widget logic, reference the planned `[TYPE Model]` (`.svelte.ts` file in `frontend/src/lib/models/`). The model declares `@STATE`, `@ACTION`, and `@INVARIANT`. Components bind to the model via `@RELATION BINDS_TO -> [ModelId]`.
|
||||
* **States**:
|
||||
* **Idle/Default**: Clean state, waiting for input.
|
||||
* **Loading**: Skeleton loader replaces content area.
|
||||
|
||||
Reference in New Issue
Block a user