feat(speckit): workflow architecture upgrades + rework 038 spec per new flow

Add prototype/openapi/validate/resume commands, wire edge-failure matrix into UX,
enforce traceability + validation gates, mandate C4/C5 belief-runtime verification.
Rework 038-dashboard-scenario-model artifacts: applicability, structured edge cases,
24-class UX state matrix, interactive HTML prototype, standardized OpenAPI 3.1 (7 ops),
full RTM with coverage gate, 56-task backlog, and PASS validation report.

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

@@ -14,6 +14,8 @@
 # @RELATION DEPENDS_ON -> [ScenarioGraph.Validator]
 # @RELATION DEPENDS_ON -> [ScenarioGraph.Resolver]
 # @RELATION DEPENDS_ON -> [ScenarioGraph.PackCompiler]
+# @RATIONALE A thin REST surface exposes the deterministic scenario operations to 039 and agent tools without leaking compiler internals.
+# @REJECTED Exposing raw Pydantic models over the API — request schemas must forbid code/SQL/paths to keep the boundary safe.
 # @INVARIANT Request schemas forbid executable code, SQL, raw baseline values, and local paths.
 # #endregion ScenarioGraph.Api
 
@@ -25,6 +27,8 @@
 # @SIDE_EFFECT Bounded package-resource read.
 # @DATA_CONTRACT CatalogResource -> ChecklistCase[19]
 # @INVARIANT Historic PDF outcomes are source notes, not expected values.
+# @RATIONALE Versioned declarative catalog keeps the 19 PDF cases reusable and auditable across dashboards.
+# @REJECTED Embedding the checklist as Python conditionals — mixed intent/data makes coverage unverifiable.
 # @TEST_EDGE missing_case -> startup/catalog validation failure.
 # @TEST_EDGE sql_template_for_technical_case -> rejected.
 # #endregion ScenarioGraph.Catalog.Load
@@ -80,6 +84,9 @@
 # @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.
+# @SIDE_EFFECT Logging (REASON/REFLECT markers required around revision emission).
+# @RATIONALE Immutable revisions preserve auditability and byte-stable determinism for downstream pack compilation.
+# @REJECTED In-place graph mutation — destroys revision history and breaks parent_revision_hash linkage.
 # @DATA_CONTRACT ResolveScenarioRequest + BaseScenario -> DashboardTestScenario
 # @TEST_EDGE stale_base_revision -> 409.
 # @TEST_EDGE invalid_parameter_type -> 422.
@@ -91,6 +98,9 @@
 # @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.
+# @SIDE_EFFECT Logging (REASON marker before canonicalization; REFLECT with hash after).
+# @RATIONALE Canonical serialization is the revision-identity boundary; volatile display fields must never enter the hash.
+# @REJECTED Pretty-printed human-first serialization — non-deterministic key ordering breaks byte-stable snapshots.
 # @DATA_CONTRACT DashboardTestScenario -> CanonicalBytes + SHA256
 # @TEST_EDGE shuffled_dicts -> identical bytes.
 # @TEST_EDGE timestamp_display_field -> excluded from revision identity.
@@ -117,6 +127,9 @@
 # @PRE CaptureSpec is valid; dashboard and environment are accessible.
 # @POST ScreenshotEvidence DraftArtifact registered; evidence_captured event emitted.
 # @SIDE_EFFECT Browser capture via existing ScreenshotService; draft storage via AgentRuns.Artifacts.Register.
+# @SIDE_EFFECT Logging (REASON before capture; REFLECT with artifact ids after).
+# @RATIONALE Reusing the 036 Evidence bridge keeps capture consistent with the rest of agent evidence lifecycle.
+# @REJECTED Direct Playwright screenshot calls inside the compiler — couples compile to browser availability and bypasses artifact registry.
 # @DATA_CONTRACT ScreenshotCaptureSpec + AgentRun -> DraftArtifactRef[]
 # @RELATION DEPENDS_ON -> [AgentRuns.Evidence.Adapter]
 # @INVARIANT Step output refs link to artifact ids, not filesystem paths.
@@ -130,6 +143,7 @@
 # @PRE Screenshot artifact is valid (not invalid); VlmAnalysis profile is registered and current.
 # @POST Returns typed VlmFinding[] with model/prompt provenance; raw response stored under redaction.
 # @SIDE_EFFECT External VLM API call; raw response persisted as separate DraftArtifact.
+# @SIDE_EFFECT Logging (REASON before submission; REFLECT with finding count after).
 # @DATA_CONTRACT DraftArtifactRef + VlmAnalysis -> VlmFinding[]
 # @INVARIANT VLM findings are advisory observations, not deterministic assertions; they must not alter metric baseline truth.
 # @INVARIANT Prompt template version and hash are recorded per analysis; stale prompts block analysis.
@@ -146,6 +160,9 @@
 # @PRE Human checkpoint step is active; finding ids are unresolved.
 # @POST Each finding disposition is set exactly once; step transitions according to policy.
 # @SIDE_EFFECT Audit record of disposition decision.
+# @SIDE_EFFECT Logging (REASON before disposition; REFLECT with outcome after).
+# @RATIONALE Typed dispositions keep VLM review auditable while preserving graph immutability.
+# @REJECTED Free-text disposition with no audit record — unreviewable and non-reproducible.
 # @DATA_CONTRACT HumanDispositionRequest -> ScenarioStep (updated)
 # @TEST_EDGE double_disposition -> 409.
 # @TEST_EDGE disposition_blank -> accepted for dismiss/inconclusive; confirm requires non-blank comment.
@@ -155,6 +172,8 @@
 # #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]
+# @RATIONALE Agent tools stay thin: the agent explains intent, the deterministic compiler owns the graph.
+# @REJECTED Agent-side graph construction with free-form tool selection — bypasses validation and determinism.
 # @INVARIANT Agent cannot submit executable code, custom tool categories, raw expected metrics, or artifact paths.
 # #endregion AgentChat.Tools.ScenarioGraph