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

#region DashboardScenarioModel.Traceability [C:3] [TYPE ADR] [SEMANTICS traceability,rtm,scenario] @defgroup Trace Matrix Requirements → Screen+State → Model → API → Contract → Task → Test for feature 038.

Applicability

• Feature type: Fullstack (backend compiler/validator/resolver core + thin UI preview consumed by 039 + agent tools)
• UI surface: Yes — scenario graph preview, coverage, resolution, pack states (DTOs supplied to 039)
• API surface: Yes — 7 operations in contracts/openapi.yaml

Traceability Matrix

Story / Req	UX Screen + State	Screen Model	API operationId	Contract	Backend Task	Frontend Task	Test
US1: Build Scenario Graph	preview (loading → loaded)	N/A — DTO only	compileDashboardScenario	ScenarioGraph.Compiler.Compile	T009–T012	N/A — UI in 039	Test.Scenario.Compiler
AGSCN-FR-001/002/009	preview (loaded)	N/A — DTO only	compileDashboardScenario	ScenarioGraph.Compiler.Compile	T005–T012	N/A — UI in 039	Test.Scenario.Schema
US2: Validate Safety	preview (blocked)	N/A — DTO only	validateDashboardScenario	ScenarioGraph.Validator.Validate	T013–T017	N/A — UI in 039	Test.Scenario.Validator
AGSCN-FR-004/005	preview (blocked)	N/A — DTO only	validateDashboardScenario	ScenarioGraph.Validator.Validate	T014–T016	N/A — UI in 039	Test.Scenario.Validator.Edge
US3: Checklist Coverage	preview (coverage panel)	N/A — DTO only	compileDashboardScenario	ScenarioGraph.CapabilityMapper.Map	T006–T008	N/A — UI in 039	Test.Scenario.Capability
AGSCN-FR-006	preview (coverage panel)	N/A — DTO only	compileDashboardScenario	ScenarioGraph.Catalog.Load	T001–T004	N/A — UI in 039	Test.Scenario.Catalog
US4: Parameters/Checkpoints	preview (resolution)	N/A — DTO only	resolveDashboardScenario	ScenarioGraph.Resolver.Resolve	T022–T025	N/A — UI in 039	Test.Scenario.Resolver
AGSCN-FR-007/008	preview (resolution)	N/A — DTO only	resolveDashboardScenario + compile	ScenarioGraph.Serializer.Canonical	T018–T021	N/A — UI in 039	Test.Scenario.Serializer
US5: Capture/VLM/Disposition	preview (vlm findings)	N/A — DTO only	captureScenarioScreenshot, analyzeScenarioScreenshot, disposeVlmFindings	ScenarioGraph.Capture.Dispatch, ScenarioGraph.Vlm.Analyze, ScenarioGraph.Human.Disposition	T037–T047	N/A — UI in 039	Test.Scenario.Capture, Test.Scenario.Vlm, Test.Scenario.Disposition
AGSCN-FR-010	preview (capture)	N/A — DTO only	captureScenarioScreenshot	ScenarioGraph.Capture.Dispatch	T037–T039	N/A — UI in 039	Test.Scenario.Capture
AGSCN-FR-011	preview (vlm)	N/A — DTO only	analyzeScenarioScreenshot	ScenarioGraph.Vlm.Analyze	T040–T042	N/A — UI in 039	Test.Scenario.Vlm
AGSCN-FR-012	preview (disposition)	N/A — DTO only	disposeVlmFindings	ScenarioGraph.Human.Disposition	T043–T044	N/A — UI in 039	Test.Scenario.Disposition
Draft pack (pack compiler)	preview (preview_only / save_eligible)	N/A — DTO only	compileScenarioDraftPack	ScenarioGraph.PackCompiler.Generate	T026–T030	N/A — UI in 039	Test.Scenario.Pack
Edge E6 (409 stale)	preview (stale409 conflict panel)	N/A — DTO only	resolveDashboardScenario	ScenarioGraph.Resolver.Resolve	T023	N/A — UI in 039	Test.Scenario.Resolver.Edge
Edge E9 (429)	preview (rate limited)	N/A — DTO only	any scenario op	ScenarioGraph.Api	T031–T032	N/A — UI in 039	Test.Api.Scenarios.Edge
Edge E11 (malformed VLM)	preview (vlm inconclusive)	N/A — DTO only	analyzeScenarioScreenshot	ScenarioGraph.Vlm.Analyze	T040	N/A — UI in 039	Test.Scenario.Vlm.Edge
Edge E13 (injection)	preview (pack blocked)	N/A — DTO only	compileScenarioDraftPack	ScenarioGraph.PackCompiler.Generate	T026, T034	N/A — UI in 039	Test.Scenario.Pack.Security
NFR: determinism	N/A — infra	N/A — infra	N/A — no API	ScenarioGraph.Compiler.Compile	T012, T021	N/A — backend-only	Test.Scenario.Serializer
NFR: RBAC	N/A — infra	N/A — infra	N/A — security	ScenarioGraph.Api	T032	N/A — backend-only	Test.Api.Scenarios.Rbac

N/A Rationale Key

• N/A — UI in 039: 038 renders no UI; it supplies DTOs consumed by feature 039 preview
• N/A — DTO only: Screen Model pattern not needed; state lives in 039 components bound to 038 DTOs
• N/A — infra: Shared infrastructure, not user-facing
• N/A — no API: Determinism/RBAC are cross-cutting invariants, not endpoints
• N/A — backend-only: No frontend task for backend-only work

Impact Analysis Quick Reference

If you change...	These fixtures verify it	These tests verify it	These screens depend
ScenarioGraph.Compiler.Compile	FX_Scenario.Valid, FX_Scenario.Shuffled	Test.Scenario.Compiler, Test.Scenario.Serializer	preview (039)
ScenarioGraph.Validator.Validate	FX_Scenario.Cycle, FX_Scenario.MissingRef, FX_Scenario.RawBaseline	Test.Scenario.Validator	preview (039)
ScenarioGraph.PackCompiler.Generate	FX_Scenario.PreviewOnly, FX_Scenario.InjectedCode	Test.Scenario.Pack	preview (039)
ScenarioGraph.Vlm.Analyze	FX_Scenario.VlmTyped, FX_Scenario.VlmStalePrompt	Test.Scenario.Vlm	preview (039)
contracts/openapi.yaml	FX_Api.Compile.*	Test.Api.Scenarios	preview (039)
ScenarioGraph.Catalog.Load	FX_Scenario.Catalog19	Test.Scenario.Catalog	preview coverage (039)

Cross-Spec Pipeline Traceability

Stage / requirement	Authoritative contract	Downstream owner	Evidence
compile handle + canonical content hash	ScenarioGraph.Compiler.Compile, ScenarioGraph.Serializer.Canonical	042 ScenarioRevision	Test.Scenario.Compiler, Test.Scenario.Serializer
validation result bound to compiled hash	ScenarioGraph.Validator.Validate	038 pack eligibility	Test.Scenario.Validator, Test.Scenario.Validator.Edge
unresolved needs_context / needs_selector / needs_baseline	ScenarioGraph.ServerOwnedPipeline	042 save; 044 RunPreflight	Test.Scenario.Capability, Test.Scenario.Resolver, test_scenario_runner
draft-pack handle and server digest	ScenarioGraph.PackCompiler.Generate	042 server-owned save	Test.Scenario.Pack, Test.Scenario.Pack.Security, test_scenario_registry
no client graph/digest/runner plan authority	ScenarioGraph.ServerOwnedPipeline	050 MCP transport	injected-code, path-traversal, and MCP raw-graph rejection tests
persistent co-authoring and sandbox	ScenarioGraph.AgentAuthoringWorkspace	050 MCP -> 042 registry	session persistence, sandbox isolation/limits, receipt and CAS tests
proposal -> compile/validate -> review -> save	ScenarioGraph.AgentAuthoringWorkspace	042 ScenarioRegistry.SaveContinuation	typed-candidate, diff-review, promotion-boundary E2E

The 038 gate is necessary but not sufficient for the coordinated path: a validated compiler result cannot be released unless 042 save/revision evidence, 044 preflight/runner/evidence evidence, and 050 MCP parity evidence also pass.

Authoring E2E Release Gate

The coordinated authoring path is persistent workspace -> isolated exploration -> typed proposal -> 038 compile/validate -> user diff review -> 042 handle-based save -> immutable revision -> 044 run. Release is NO-GO if any stage accepts raw code, URLs, cookies, secrets, paths or caller digests, lacks CAS/idempotency or receipts, permits production sandbox effects, or lets a non-promoted artifact reach ScenarioRun. This gate is normative and does not claim implementation completion.

Coverage Gate

• Every user story (US1–US5) has at least one row
• Every functional requirement (AGSCN-FR-001..012) has at least one row
• Every API endpoint has at least one row for success AND at least one row for an error state (E6 409, E9 429, E11, E13)
• Every Screen Model column is N/A with rationale (038 is DTO-only; 039 owns rendering)
• Every N/A cell carries a rationale from the key above
• Every contract referenced appears in contracts/modules.md
• Every task ID (Txxx) appears in tasks.md
• Impact table covers every contract with downstream dependents

Module Reuse Annex (LLM verification tooling)

038 orchestration layers reuse existing plugin/service contracts — see research.md §9 and contracts/modules.md (ScenarioGraph.Capture.Dispatch, ScenarioGraph.Vlm.Analyze):

038 contract	Reused existing contract	Rationale
ScenarioGraph.Capture.Dispatch	Plugin.Service.ScreenshotService, Services.AgentRuns.Evidence	One Playwright/CDP capture path; evidence auditability
ScenarioGraph.Vlm.Analyze	Plugin.Service.LLMClient, Services.LlmProvider.LLMProviderService, Plugin.Service.RedactionService	One local provider client; multimodal-required validation; optional display redaction; secret-safe persistence

Production acceptance traceability — 2026-09-08

Historical rows above identify prior tests/code only; removed agent UI paths are retired. The following audited gates are implemented=false / OPEN, independent of local suite totals.

Requirement	Domain contract / DTO	Task	Falsifiable acceptance	State
AGSCN-FR-015	Canonical executable chain; data model	T060	Visual template expands complete browser/capture/artifact/compare/optional-evaluation/policy chain; missing producer or mandatory baseline rejects.	OPEN
AGSCN-FR-015	Canonical executable chain; data model	T061	Every browser action/alias maps to one descriptor; sql_evidence/transform enum parity and disabled capability fail before I/O.	OPEN
AGSCN-FR-015	Canonical executable chain; data model	T062	All 15 policy precedence rows, threshold equality, malformed output and criterion disagreement use hardcoded outcomes; no dynamic HumanCheckpoint.	OPEN
AGSCN-FR-015; external-MCP-only UI	manual editor/review; read-only evidence	production tasks	No frontend agent prompt/chat/assistant editing/proposal generation/workspace/start/handoff routes or requests; human approval remains usable.	OPEN
AGSCN-FR-016/023	action_inputs/editor/validator	T063-T064	Canonical inputs refs preserved; bounded action_inputs; embedded metric literal rejected; MCP parity.	CLOSED 2026-09-18 — 534d488f + f123210b; 602+12 green.
AGSCN-FR-019/020	capability mapper/compile	T066	New graph emits no human_checkpoint; unsafe/missing contexts unsupported; legacy runtime retained.	CLOSED — a59f5e3c, 1577 green.
AGSCN-FR-021/034	AgentEvaluationSpec/editor op	T067	set_step_evaluation pins strict spec and executable-code tokens reject.	CLOSED — 87a90f6f, 815 green.
AGSCN-FR-018	TransformSpec	T068	Bounded deterministic DSL runtime over declared refs; stable digest/resource bounds; no executable code.	OPEN.
AGSCN-FR-022	DecisionPolicy	T069	single-shot/best-of-N/quorum/tie/provider-error/confidence deterministic outcomes; no evidence-free PASS.	OPEN.
AGBASE-FR-016	Baseline selection schema	T070	≤50 curated gating coordinates; filter contexts/rationale/tolerance; observatory non-gating.	OPEN.

Sources: production gap, coverage gap, baseline gap. Spec schema/static checks prove contract structure only; live canary/runtime closure and optional approved performance baseline are not claimed.

#endregion DashboardScenarioModel.Traceability