ss-tools/specs/038-dashboard-scenario-model/plan.md

Implementation Plan: Dashboard Scenario Model

Branch: 038-dashboard-scenario-model | Date: 2026-07-31 | Spec: spec.md | Status: Reworked per new speckit flow

Summary

Implement a backend Pydantic ScenarioGraph domain and deterministic compiler that maps the 19 normalized PDF checklist cases plus dashboard/baseline capabilities into a reviewable DAG. Validate all refs, cycles, tools, selectors, parameters, and baseline rules before compiling a draft pack through versioned safe templates and registering it with 036. Supply scenario/validation/coverage/parameter/artifact DTOs to 039 (scenario preview UI) and typed capture/VLM/disposition semantics (AGSCN-FR-010..012).

Technical Context

Language/Version: Python 3.13+ (backend), TypeScript DTOs (frontend, consumed by 039) Primary Dependencies: Pydantic 2, FastAPI, deterministic JSON/YAML serialization, existing 036/037 services Storage: Immutable request/graph/draft hashes; draft bytes via 036; no new DB table required for MVP beyond AgentRun event/artifact links Testing: pytest property/unit/contract, JSON Schema validation, golden snapshots; L1 (model, no render) + L2 (component/UX with render) per edge matrix ownership Frontend Architecture: TypeScript-first DTOs in frontend/src/types/ matching Pydantic schemas; UI rendering owned by 039, 038 supplies DTO contracts Performance Goals: validate 100-step graph under 100ms; resolve parameters under 200ms; byte-stable snapshots Constraints: DAG only; no raw baseline numbers; no SQL; no executable LLM output; all checklist cases classified; VLM findings advisory; disposition auditable Scale: 19 source cases, up to 100 steps, 50 parameters, 200 refs

Constitution Check

Principle	Result
I. Semantic Contract First	PASS — compiler, validator, serializer, pack generator, capture, VLM, disposition contracted (C3–C5)
II. Decision Memory	PASS — @RATIONALE/@REJECTED on compiler/validator/pack/VLM (direct-code, silent-repair, raw-VLM, one-size-fits-all rejected)
III. External Orchestrator	PASS — reads 037 query models/baselines; never calls Superset directly; writes drafts via 036
IV. Module Discipline	PASS — models/catalog/mapping/compiler/validator/serializer/templates/pack separated; no oversized compiler
V. RBAC Enforcement	PASS — scenario.compile/resolve/draft/execute scopes per ADR-0005; default-allow forbidden
VI. Svelte 5 Runes Only	PASS — UI is DTO-only for 039; no legacy Svelte introduced
VII. Test-Driven for C3+	PASS — invalid fixture matrix and rejected direct-code/SQL/VLM paths written first
VIII. Attention-Optimized	PASS — ScenarioGraph.* IDs, shared [SEMANTICS scenario,...], ATTN_1–4 gate applied

Project Structure

Documentation (this feature)

specs/038-dashboard-scenario-model/
├── spec.md              # Reworked: applicability, structured edge cases, Clarifications
├── ux_reference.md      # Reworked: edge/failure state matrix (24 classes)
├── research.md          # Phase 0 decisions (deterministic compiler boundary)
├── data-model.md        # Canonical graph/step/ref/parameter/validation models
├── quickstart.md        # Verification commands and exit gates
├── traceability.md      # REQUIRED RTM: Story → Screen+State → Model → operationId → Contract → Task → Test
├── checklist-catalog.md # Normalized 19-case catalog from the research PDF
├── checklists/          # Requirements-quality checklists
├── contracts/
│   ├── modules.md       # C3+ contracts (compiler, validator, resolver, pack, capture, VLM, disposition)
│   ├── openapi.yaml     # OpenAPI 3.1 — 7 operations, envelopes, RBAC, examples
│   ├── openapi-traceability.md  # operationId → spec → data-model → UX drift map
│   ├── dashboard-test-scenario.schema.json
│   ├── capture-profile.schema.json
│   └── ux/
│       ├── api-ux.md            # UI mapping for compile/validate/resolve/draft-pack
│       ├── scenario-graph-ux.md # Per-screen UX contract + edge/failure matrix
│       ├── decisions.md         # Final UX decisions
│       └── alternatives.md      # Design space explored
├── prototype/
│   ├── index.html       # Interactive HTML prototype (10 states, state switcher, responsive)
│   └── manifest.md      # State coverage + screen↔story traceability
└── validation.md        # Pre-implementation gate (/speckit.validate output)

Source Code (repository root)

backend/src/
├── api/routes/dashboard_scenarios.py   # compile/validate/resolve/draft-pack/capture/vlm/disposition
├── schemas/dashboard_scenario.py       # Pydantic request/response schemas (mirror openapi.yaml)
└── services/dashboard_testing/scenario/
    ├── models.py          # DashboardTestScenario, ScenarioStep, ScenarioParameter, ScenarioRef
    ├── checklist_catalog.py
    ├── capability_mapper.py
    ├── compiler.py
    ├── validator.py
    ├── serializer.py
    ├── resolver.py
    ├── pack_compiler.py
    ├── capture_profile.py
    ├── vlm.py             # typed VlmFinding, provenance, stale-prompt guard
    ├── disposition.py     # typed human disposition, double-disposition guard
    ├── templates/         # step-template catalog (declarative)
    ├── pack_templates/v1/ # scenario.yaml, runner.plan.json, report_template.md, evidence_manifest.json
    └── prompt_templates/v1/  # registered VLM prompt template + hash

backend/tests/services/dashboard_testing/scenario/
backend/tests/api/test_dashboard_scenarios.py
frontend/src/types/                     # DTOs matching Pydantic schemas (consumed by 039)
agent/src/ss_tools/agent/tools.py       # thin compile/validate/resolve/generate tools

Structure Decision: ScenarioGraph is a bounded intermediate boundary between agent intent and generated artifacts; all generation flows through registered templates.

Semantic Contract Guidance

Attention Compliance Gate (MANDATORY — validated)

Rule	Check	Why
ATTN_1	First anchor line packs [C:N] [TYPE] [SEMANTICS] on ONE line	CSA 4× pooling
ATTN_2	IDs hierarchical: ScenarioGraph.Compiler.Compile, ScenarioGraph.Validator.Validate	HCA 128×
ATTN_3	All scenario contracts share [SEMANTICS scenario,...] primary keyword	DSA grouping
ATTN_4	Contract ≤150 lines, module ≤400 lines	Sliding window

Function-Level Contracts (C3+)

Full #region headers for compiler, validator, resolver, serializer, pack_compiler, capture, vlm, disposition are defined in contracts/modules.md with @PRE/@POST/@SIDE_EFFECT/@DATA_CONTRACT/@TEST_EDGE. Cross-stack DTOs (VlmFinding, HumanDisposition, DraftPack) have matching @RELATION edges across the Pydantic ↔ TypeScript boundary.

Decision Memory (Global ADR Continuity)

ADR / Guardrail	Present in Plan	Propagated to Contracts	Propagated to Tasks	Verifying Tasks Exist	Rejected Path Protected
ADR-0001 module layout	✅	✅	✅	T001–T005	✅
ADR-0002 semantic protocol	✅	✅	✅	T036	✅
ADR-0005 RBAC scopes	✅	✅ (openapi security)	✅	T032	✅
037 no-direct-SQL invariant	✅	✅ (validator)	✅	T015, T034	✅
Direct LLM-to-code rejected	✅	✅ (compiler @REJECTED)	✅	T026, T034	✅
Raw baseline literals rejected	✅	✅ (validator)	✅	T003, T014	✅
VLM prose-as-state rejected	✅	✅ (vlm @REJECTED)	✅	T040–T041	✅
One-size-fits-all scripts rejected	✅	✅ (mapper @REJECTED)	✅	T008	✅

Delivery Phases

1. Machine schema, Pydantic models, normalized checklist catalog and fixtures.
2. Capability mapping and deterministic graph compiler.
3. Full validator and canonical serializer.
4. Parameter/selector/manual resolution with immutable revisions.
5. Safe template-based draft-pack compiler and 036 registration.
6. Screenshot capture, VLM analysis, human disposition (AGSCN-FR-010..012).
7. REST/agent tools, DTOs for 039, and regression gates (incl. /speckit.validate PASS).

API and Schema

• contracts/openapi.yaml is the canonical REST contract (7 operations, RBAC scopes, error envelopes).
• contracts/dashboard-test-scenario.schema.json and contracts/capture-profile.schema.json are the canonical graph/capture interchange contracts.
• contracts/openapi-traceability.md maps every operationId to spec/data-model/UX.

Traceability

traceability.md is REQUIRED and maps Story/Requirement → UX Screen+State → Screen Model → API operationId → Contract → Task → Test, with explicit N/A rationale and a coverage gate (see traceability.md).

Cross-Spec Boundary

• Reads 037 query models/baseline summaries; never calls Superset directly.
• Writes drafts and progress through 036.
• Supplies scenario, validation, coverage, parameter, and artifact manifest DTOs to 039.
• Screenshot capture/VLM/disposition depend on 036 Phase 8 (screenshot evidence artifacts) and 037 Phase 7 (visual baseline infrastructure).

Complexity Tracking

No exception planned. Checklist data remains declarative and versioned; do not turn the 19 cases into one large conditional compiler function. VLM findings are advisory — never asserted as deterministic truth.