ss-tools/specs/043-dashboard-scenario-editor/spec.md

#region ScenarioEditor.Spec [C:3] [TYPE ADR] [SEMANTICS spec,requirements,ux,scenario,editor,visual,agent] @BRIEF User-facing Scenario Editor: view and edit a persisted scenario with a hybrid (C) editing model — manual business fields/parameters, constrained assertions, visual dependency editing, read-only generated executable, and agent-assisted complex changes. @RELATION DEPENDS_ON -> [Doc.Adr.ADR0001] @RELATION DEPENDS_ON -> [Doc.Adr.ADR0006] @RELATION DEPENDS_ON -> [ScenarioRegistry.Spec] @RELATION DEPENDS_ON -> [DashboardScenarioModel.Spec] @RATIONALE 038 defines the DTOs but no lifecycle editing UX. A scenario must be viewable and editable outside the agent chat, with every durable edit producing a new immutable revision and delegated policy determining whether an inline approval is required. @REJECTED Agent-only editing (no visual surface) — rejected because users need to review and adjust a scenario without re-prompting the agent each time. @REJECTED Unconstrained free-form DAG/assertion editor — rejected because it could inject SQL/raw baselines/unsafe paths, violating 038 safety invariants; assertions use constrained editors and generated executable stays read-only.

Navigation (DSA Indexer keywords)

@SEMANTICS: spec, requirements, feature, ux, scenario, editor, visual, revision, agent

Feature Branch: 043-dashboard-scenario-editor Created: 2026-08-07 | Status: Draft Input: "Provide a first-class Scenario Editor for viewing and editing persisted scenarios: business metadata and parameter definitions editable manually, assertions via constrained editors, dependencies via visual DAG editing, generated executable read-only, and complex changes delegated to 'Edit with agent'. Metadata changes use a registry metadata version; executable changes create immutable revisions."

User Scenarios

Story 1 — View Scenario in an Editor (P1)

Why P1: Users must inspect a scenario as a structured document, not a chat transcript.

Independent Test: Load a persisted scenario into the editor and verify graph, steps, parameters, baselines, and assertions render read-only by default.

Acceptance:

1. Given a scenario is opened When the editor renders Then steps, dependencies (graph), parameters, baselines, and assertions are shown; generated executable artifacts are read-only.
2. Given a step is opened When inspected Then inputs, outputs, expected result, baseline, automation mode, and evidence requirements are visible.
3. Given no edit session is active When the page loads Then the view is read-only and no revision is created.

---

Story 2 — Edit Business Fields and Parameters Manually (P1)

Why P1: Name, description, tags, and parameter values are safe to edit directly.

Independent Test: Modify a scenario name and verify metadata_version advances without a revision; modify a parameter default and verify a new executable revision is produced.

Acceptance:

1. Given the user edits business fields (name/description/tags) When saved Then only ScenarioRegistryEntry.metadata_version advances; no executable revision is created.
2. Given the user edits a parameter definition default When validated Then type validation and dependent-step readiness update, and a new executable revision is created.
3. Given a durable edit is requested When it passes policy evaluation Then it is saved as an immutable revision or rendered as an inline ActionApprovalGate; an agent-saved revision retains delegated provenance.

---

Story 3 — Edit Assertions With a Constrained Editor (P2)

Why P2: Assertions must change without allowing SQL/raw baselines to be injected.

Independent Test: Change an assertion's comparison operator and threshold via the constrained editor and verify the graph stays safe.

Acceptance:

1. Given an assertion is edited When the constrained editor is used Then only registered operators/baseline references are selectable; free-form SQL/raw values are forbidden.
2. Given an invalid assertion is submitted When validated Then it is rejected with the 038 validator findings, never saved as-is.

---

Story 4 — Edit Dependencies Visually (P2)

Why P2: Reordering/adding/removing step dependencies is a graph operation best done visually.

Independent Test: Re-parent a step in the visual DAG editor and verify dependency validation and a new revision.

Acceptance:

1. Given the user drags a dependency edge When changed Then the graph revalidates for cycles/duplicate outputs per 038 rules.
2. Given a step is added/removed When saved Then affected step ids/order change only as needed and a new revision records the change.

---

Story 5 — Agent-Assisted Complex Edit (P3)

Why P3: Some changes (new checklist case, complex assertion) are easier described in natural language.

Independent Test: Request "add XLSX comparison" via Edit-with-agent and verify the agent creates a validated WorkingDraft and saves a revision when delegated policy permits.

Acceptance:

1. Given a complex change request When "Edit with agent" runs Then the agent creates a server-stored EditProposal.
2. Given the proposal is accepted When its base revision is still current Then it becomes a WorkingDraft; a policy-authorized analyst or agent save creates the revision. A stale proposal never saves; a non-delegated action waits at an inline gate.

---

Story 6 — Revalidate a Stale Scenario (P2) (#9)

Why P2: A scenario that references changed charts/filters must migrate cleanly, not just flip a lifecycle flag.

Independent Test: Mark a scenario stale via 042, run revalidate, and verify a proposed r18 with automatic mappings, manual conflicts, and a diff for approval.

Acceptance:

1. Given a scenario is stale When "Revalidate" runs Then affected refs (chart/filter/metric) are listed and mapped against the current dashboard (038 validator + 037/041).
2. Given some mappings are ambiguous When conflicts exist Then they are surfaced for manual resolution, not auto-accepted.
3. Given a proposal is generated When shown Then a diff (r17→r18) is displayed; the agent may save it after validation if delegated policy allows, otherwise the linked inline gate decides it.

---

Edge & Failure Cases

#	Scenario	Expected Behavior	Recovery
E1	Concurrent edit (409)	Persistent conflict panel with reload/compare/discard	Reload / compare / discard
E2	Invalid assertion/SQL/raw baseline	Rejected with validator findings	Correct via constrained editor
E3	Cycle introduced by dependency edit	Rejected with cycle path	Revert edge
E4	Agent proposes unsafe revision	Blocked by validator before save	Describe differently / manual edit
E5	RBAC edit denied	403 permission_denied, no confirm control	Contact admin

Requirements

Functional

• SCEDIT-FR-001: The editor MUST render a persisted scenario as a structured document with steps, dependency graph, parameters, baselines, assertions, and read-only generated executable.
• SCEDIT-FR-002: Metadata fields (name, description, tags) MUST be editable manually through metadata_version without creating an executable revision; ParameterDefinition/default and graph edits MUST create one.
• SCEDIT-FR-003: Assertion editing MUST use a constrained editor (registered operators + baseline references); free-form SQL, shell, paths, and raw numeric baseline literals MUST be forbidden.
• SCEDIT-FR-004: Dependency editing MUST be visual (graph), with 038 cycle/duplicate-output validation on every change.
• SCEDIT-FR-005: Every durable executable graph edit MUST produce a new immutable revision; metadata uses metadata_version concurrency. Deterministic policy decides whether the actor/agent may save immediately or must obtain an inline ActionApprovalGate.
• SCEDIT-FR-005a: Every proposal/diff MUST expose Verification Program changes: SqlEvidenceSpec template/hash/relation refs, TransformSpec operations, assertions, AgentEvaluationSpec and DecisionPolicy. A runtime finding can only change this content through a new validated proposal and revision.
• SCEDIT-FR-006: "Edit with agent" MUST create a server-stored validated proposal/draft with a diff. A delegated agent MAY save the revision; no agent edit may bypass 038 validation, 042 revision provenance, or a required gate.
• SCEDIT-FR-009: Every save MUST use a server-stored WorkingDraft (draft_id + digest); the client MUST NOT return the full graph to save (no arbitrary-draft bypass). Save re-validates/canonicalizes/hashes server-side.
• SCEDIT-FR-010: A stale scenario MUST be revalidatable: affected refs mapped against the current dashboard, conflicts surfaced manually, a proposed revision + diff shown for approval (Scenario Migration workflow).
• SCEDIT-FR-007: RBAC MUST enforce scenario:edit separately from scenario:run.
• SCEDIT-FR-008: All UI MUST follow Svelte 5 runes/model-first conventions and remain keyboard-accessible.

Key Entities

• ScenarioEditorModel: Frontend screen model (.svelte.ts) holding the open scenario revision, edit buffer, dirty state, and revision save actions.
• ConstrainedAssertionEditor: Editor restricting assertion edits to registered operators and baseline references.
• VisualDagEditor: Graph canvas for step/dependency editing with validation feedback.
• EditRevisionResult: New revision + change summary + diff produced by a durable edit.

Success Criteria

• SC-001: A persisted scenario renders read-only by default and enters edit mode only on an explicit action.
• SC-002: Manual field/parameter edits produce a new immutable revision with change summary in model tests.
• SC-003: 100% of attempted SQL/raw-baseline/path injections via the assertion editor are rejected.
• SC-004: Dependency edits that introduce a cycle or duplicate output are rejected with a precise error.
• SC-005: Every durable edit is immutable, validated and fully attributed; agent edits expose their diff/provenance and are either policy-authorized or ActionApprovalGate-bound.
• SC-006: Edit model C (hybrid) is enforced: manual fields/params, constrained assertions, visual deps, read-only generated executable.

Clarifications

Session 2026-08-07

• Q: Which edit model? → A: C (hybrid) — business fields/params manual, assertions constrained, dependencies visual, generated executable read-only, complex changes "Edit with agent".
• Q: May the agent save a revision? → A: Yes, after deterministic validation when delegated policy permits. It always creates an immutable revision with agent/delegator/case provenance; policy-gated actions use an inline ActionApprovalGate.
• Q: Does this replace 039 workspace? → A: No. 039 is the create flow in agent chat; 043 is the post-save edit surface over the registry.

Implementation Status & MVP Debt (audit 2026-08-07)

Facts (code check):

• 🟡 038 DTOs exist (DashboardTestScenario, ScenarioStep, ScenarioParameter, ScenarioRef, ScenarioValidationResult); no dedicated editor UI/model.
• 🔴 No visual DAG editor or constrained assertion editor exists.
• 🟡 resolve (038) supports parameter/selector/manual edits but is agent-tool-bound; a registry-backed edit surface is absent until 042 lands.

#endregion ScenarioEditor.Spec