docs(specs): complete speckit packages 036-039

specs/038-dashboard-scenario-model/contracts/modules.md

@@ -0,0 +1,114 @@
+#region DashboardScenarioModel.Modules [C:5] [TYPE ADR] [SEMANTICS contracts,scenario,graph,validator,compiler]
+@BRIEF C3+ contracts for checklist mapping, deterministic graph compilation, validation, resolution, serialization, and safe draft packs.
+@RELATION DEPENDS_ON -> [DashboardScenarioModel.DataModel]
+@RELATION DEPENDS_ON -> [DashboardScenarioModel.ChecklistCatalog]
+@RELATION DEPENDS_ON -> [SupersetBaselineEngine.Modules]
+@RELATION DEPENDS_ON -> [AgentRuns.Artifacts.Register]
+
+# #region ScenarioGraph.Api [C:4] [TYPE Module] [SEMANTICS scenario,api,compile,validate]
+# @defgroup ScenarioGraph REST surface for compile, validate, resolve, and draft-pack operations.
+# @LAYER API
+# @RELATION DEPENDS_ON -> [ScenarioGraph.Compiler]
+# @RELATION DEPENDS_ON -> [ScenarioGraph.Validator]
+# @RELATION DEPENDS_ON -> [ScenarioGraph.Resolver]
+# @RELATION DEPENDS_ON -> [ScenarioGraph.PackCompiler]
+# @INVARIANT Request schemas forbid executable code, SQL, raw baseline values, and local paths.
+# #endregion ScenarioGraph.Api
+
+# #region ScenarioGraph.Catalog.Load [C:4] [TYPE Function] [SEMANTICS scenario,checklist,catalog,version]
+# @ingroup ScenarioGraph
+# @BRIEF Load the versioned 19-case declarative catalog and validate ids/capability/template references.
+# @PRE Bundled catalog version is supported.
+# @POST Returns exactly B01–B09, C01–C07, T01–T03 in stable order.
+# @SIDE_EFFECT Bounded package-resource read.
+# @DATA_CONTRACT CatalogResource -> ChecklistCase[19]
+# @INVARIANT Historic PDF outcomes are source notes, not expected values.
+# @TEST_EDGE missing_case -> startup/catalog validation failure.
+# @TEST_EDGE sql_template_for_technical_case -> rejected.
+# #endregion ScenarioGraph.Catalog.Load
+
+# #region ScenarioGraph.CapabilityMapper.Map [C:5] [TYPE Function] [SEMANTICS scenario,capability,mapping,coverage]
+# @ingroup ScenarioGraph
+# @BRIEF Classify every checklist case for a dashboard and select one allowed step template.
+# @PRE Query model, baseline summary, and capability registry validate.
+# @POST Every catalog case is automated, human_checkpoint, unsupported, or needs_context with rationale.
+# @SIDE_EFFECT None.
+# @DATA_CONTRACT ChecklistCase[] + DashboardCapabilities -> CapabilityMapping[]
+# @INVARIANT No case is dropped and no tool is selected outside its registered capabilities.
+# @TEST_EDGE xlsx_unavailable -> C04–C06 manual/unsupported with rationale.
+# @TEST_EDGE technical_without_dataset_fields -> human checkpoint, no SQL.
+# #endregion ScenarioGraph.CapabilityMapper.Map
+
+# #region ScenarioGraph.Compiler.Compile [C:5] [TYPE Function] [SEMANTICS scenario,compiler,deterministic,dag]
+# @ingroup ScenarioGraph
+# @BRIEF Compile canonical inputs and mappings into a stable dashboard-specific DAG.
+# @PRE Intent, query model, catalog, baseline summary, and parameters have valid fingerprints.
+# @POST Same canonical inputs/compiler version yield byte-identical graph and stable ids/order.
+# @SIDE_EFFECT None.
+# @DATA_CONTRACT CompileScenarioRequest -> DashboardTestScenario
+# @INVARIANT Steps consume only context/parameter/baseline/earlier-step refs.
+# @TEST_INVARIANT Deterministic_Graph -> VERIFIED_BY: repeated_compile, shuffled_input_order.
+# @TEST_EDGE missing_selector -> NEEDS_SELECTOR step and save blocker.
+# @TEST_EDGE missing_baseline -> NEEDS_BASELINE; no embedded numeric truth.
+# @RATIONALE Rule/template compilation makes the agent a planner/explainer, not an executable-code generator.
+# @REJECTED LLM-generated ids/dependencies/code — non-deterministic and unsafe.
+# #endregion ScenarioGraph.Compiler.Compile
+
+# #region ScenarioGraph.Validator.Validate [C:5] [TYPE Function] [SEMANTICS scenario,validator,graph,safety]
+# @ingroup ScenarioGraph
+# @BRIEF Return complete deterministic findings for schema, DAG, refs, parameters, baselines, tools, safety, and coverage.
+# @PRE Candidate graph parses against supported schema version.
+# @POST Valid is true only with zero errors/blockers; findings are stably ordered and actionable.
+# @SIDE_EFFECT None.
+# @DATA_CONTRACT DashboardTestScenario -> ScenarioValidationResult
+# @INVARIANT Cycles, missing/duplicate refs, unregistered tools, SQL, raw metric truth, and path traversal block compilation.
+# @TEST_EDGE cycle -> error contains cycle path.
+# @TEST_EDGE duplicate_output -> both producer ids reported.
+# @TEST_EDGE raw_metric_expected -> forbidden baseline literal error.
+# @TEST_EDGE unreachable_step -> warning/error according to required coverage.
+# #endregion ScenarioGraph.Validator.Validate
+
+# #region ScenarioGraph.Resolver.Resolve [C:4] [TYPE Function] [SEMANTICS scenario,resolve,parameter,revision]
+# @ingroup ScenarioGraph
+# @BRIEF Apply typed parameter/selector/manual resolutions and emit an immutable scenario revision.
+# @PRE Base revision hash matches; changes target declared unresolved items.
+# @POST Unrelated step ids/order remain unchanged; new parent/revision hashes link revisions.
+# @SIDE_EFFECT None.
+# @DATA_CONTRACT ResolveScenarioRequest + BaseScenario -> DashboardTestScenario
+# @TEST_EDGE stale_base_revision -> 409.
+# @TEST_EDGE invalid_parameter_type -> 422.
+# @TEST_EDGE unrelated_graph_change -> invariant failure.
+# #endregion ScenarioGraph.Resolver.Resolve
+
+# #region ScenarioGraph.Serializer.Canonical [C:4] [TYPE Function] [SEMANTICS scenario,serialize,json,yaml]
+# @ingroup ScenarioGraph
+# @BRIEF Serialize graph to canonical JSON/YAML and compute revision hash.
+# @POST Key/order/decimal/date/newline rules are stable across runs; JSON and YAML represent equal domain data.
+# @SIDE_EFFECT None.
+# @DATA_CONTRACT DashboardTestScenario -> CanonicalBytes + SHA256
+# @TEST_EDGE shuffled_dicts -> identical bytes.
+# @TEST_EDGE timestamp_display_field -> excluded from revision identity.
+# #endregion ScenarioGraph.Serializer.Canonical
+
+# #region ScenarioGraph.PackCompiler.Generate [C:5] [TYPE Function] [SEMANTICS scenario,artifact,template,draft]
+# @ingroup ScenarioGraph
+# @BRIEF Generate a preview-only or save-eligible draft pack using registered versioned templates.
+# @PRE Scenario validation result available; template ids registered; target paths safe.
+# @POST Outputs match ArtifactPlan, contain no LLM executable bodies, and are registered as 036 drafts.
+# @SIDE_EFFECT Renders bounded templates and calls AgentRuns.Artifacts.Register.
+# @DATA_CONTRACT DashboardTestScenario + ValidationResult -> DraftPack
+# @INVARIANT Errors/unresolved required inputs make pack preview_only; direct code/path input is impossible.
+# @TEST_INVARIANT No_LLM_To_Code -> VERIFIED_BY: injected_code_field, template_registry_only.
+# @TEST_EDGE unknown_template -> blocked.
+# @TEST_EDGE path_traversal -> blocked before artifact registration.
+# @RATIONALE Versioned templates make generated behavior reviewable and reproducible.
+# @REJECTED Generate arbitrary Playwright/Python code then scan it — scanners cannot prove semantic safety.
+# #endregion ScenarioGraph.PackCompiler.Generate
+
+# #region AgentChat.Tools.ScenarioGraph [C:4] [TYPE Module] [SEMANTICS scenario,agent,tools,compiler]
+# @defgroup ScenarioGraph Thin agent tools that submit bounded intent and display compiler/validator results.
+# @RELATION DEPENDS_ON -> [ScenarioGraph.Api]
+# @INVARIANT Agent cannot submit executable code, custom tool categories, raw expected metrics, or artifact paths.
+# #endregion AgentChat.Tools.ScenarioGraph
+
+#endregion DashboardScenarioModel.Modules