Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@docs/design/page-structure.md`:
- Line 301: The controllers/pages list is out of sync: after adding the
/workflows/editor page entry you must also add WorkflowController to the
Controller-to-Page Map and update the controller-count statement near the top to
reflect the new total; locate the Controller-to-Page Map section and insert an
entry mapping WorkflowController to /workflows/editor (or the appropriate page
name), and increment the controller count text at the document header so the
counts and map remain consistent.

In `@src/synthorg/api/controllers/workflows.py`:
- Around line 281-298: The delete_workflow handler always returns 204 even when
no workflow was deleted; change this so that after calling
repo.delete(workflow_id) you check the boolean result and if False raise an
HTTPException(status_code=404) (or use Starlette/FastAPI's NotFound) so clients
get 404 for missing workflows, otherwise keep logging WORKFLOW_DEF_DELETED and
return 204 as before; adjust code in delete_workflow (function name:
delete_workflow, local var: deleted, repo:
state.app_state.persistence.workflow_definitions) to perform this conditional
raise.
- Around line 59-72: Replace the legacy tuple-except usage in the Workflow
controller blocks by switching from "except (ValueError, ValidationError) as
exc:" to the PEP 758 form without parentheses (e.g., "except ValueError,
ValidationError as exc:") in the try/except that validates nodes (the block that
sets updates["nodes"] = tuple(WorkflowNode.model_validate(n) for n in
data.nodes)) and apply the same change to the other two identical handlers
mentioned (the except clauses around the code at the other affected locations
referenced in the review).
- Around line 300-326: The controller method validate_workflow is shadowing the
imported validate_workflow from synthorg.engine.workflow.validation; update the
import to an alias (e.g., import validate_workflow as validate_workflow_def or
validate_definition) and change the call inside the controller (currently result
= validate_workflow(definition)) to use the new alias (e.g., result =
validate_workflow_def(definition)) so the engine function is unambiguously
referenced while keeping the controller method name unchanged.

In `@src/synthorg/api/dto.py`:
- Around line 611-618: Replace the loose dict-typed graph fields with explicit
Pydantic DTOs and use them as the Field types so malformed graphs fail at
parsing: define NodeDTO and EdgeDTO (or similarly named BaseModel classes)
capturing required node properties (id, type, metadata, etc.) and edge
properties (source, target, label, etc.), then change the nodes and edges
annotations from tuple[dict[str, object], ...] to tuple[NodeDTO, ...] and
tuple[EdgeDTO, ...] (and update the other similar occurrences), and add any
necessary Field validators (constrains/validators on ids, required keys, and
length limits) so validation happens at the API boundary instead of deeper
layers.

In `@src/synthorg/persistence/sqlite/workflow_definition_repo.py`:
- Around line 117-124: The except clauses in workflow_definition_repo.py are
using tuple-style exception grouping (except (sqlite3.Error, aiosqlite.Error) as
exc) which violates the project's PEP 758 style; update each occurrence to the
PEP 758 form (except sqlite3.Error, aiosqlite.Error:), capture the exception
variable appropriately where used (e.g., logger.exception(..., error=str(exc))
and raise QueryError(msg) from exc) and apply this fix for all listed sites
referenced in the file such as inside the save method handling (definition.id),
and the other handlers at the locations corresponding to lines near 151, 170,
222, 232, and 269 so the exception variable name remains available for logging
and re-raising.

In `@tests/unit/api/fakes.py`:
- Around line 572-595: Replace the liberal use of Any in
FakeWorkflowDefinitionRepository with the concrete domain types used across
other fakes: annotate self._definitions as dict[str, WorkflowDefinition]; change
method signatures to use WorkflowDefinition for save(definition:
WorkflowDefinition) -> None, get(definition_id: str) -> WorkflowDefinition |
None, list_definitions(..., workflow_type: WorkflowType | None) ->
tuple[WorkflowDefinition, ...], and delete(definition_id: str) -> bool; ensure
you import or forward-declare the WorkflowDefinition and WorkflowType symbols so
mypy strict mode passes and the repository matches the established pattern.

In `@tests/unit/engine/workflow/test_validation.py`:
- Around line 195-265: The three tests (test_missing_true_branch,
test_missing_false_branch, test_extra_non_conditional_outgoing) repeat the same
setup and assertions; refactor them into a single parametrized test using
pytest.mark.parametrize to supply different edges and expected
ValidationErrorCode values, keep using validate_workflow, _wf, _node, _edge and
WorkflowEdgeType to construct cases, and assert result.valid is False and that
the expected ValidationErrorCode is in {err.code for err in result.errors};
replace the three individual test_* methods with one parametrized test function
(e.g., test_conditional_branch_requirements) enumerating the three
edge/expected_code combos.

In `@tests/unit/persistence/test_protocol.py`:
- Around line 475-477: The test is missing an explicit protocol compliance
assertion for the new workflow_definitions property on _FakeBackend; add the
same protocol assertion used for other repos to verify that
_FakeWorkflowDefinitionRepository implements the WorkflowDefinitionRepository
protocol. Locate the test class where other fake repos are asserted and add an
assertion referencing _FakeBackend.workflow_definitions and
_FakeWorkflowDefinitionRepository against WorkflowDefinitionRepository so the
fake repository is checked for protocol conformance.
- Around line 368-380: Update the fake repository to use the actual protocol
types: replace the generic object annotations in class
_FakeWorkflowDefinitionRepository (methods save, get, list_definitions) with the
real WorkflowDefinition type (and use NotBlankStr already present for get), and
change list_definitions' return annotation from tuple[()] to
tuple[WorkflowDefinition, ...] (and type the workflow_type parameter as the
correct WorkflowType | None if applicable); import the WorkflowDefinition (and
WorkflowType if needed) from the module where the protocol is defined so the
fake matches the protocol signatures exactly while keeping save -> None, get ->
WorkflowDefinition | None, and list_definitions -> tuple[WorkflowDefinition,
...].

In `@web/src/pages/workflow-editor/AgentAssignmentNode.stories.tsx`:
- Around line 30-44: Add three additional Storybook variants alongside Default
to cover selected, error, and auto-strategy states: create stories named
Selected, WithError, and AutoStrategy that call the same Wrapper with a nodes
array (matching the Default node shape: id '1', type 'agent_assignment',
position {x:0,y:0}) but modify the data payload—Selected should include
selected: true in data, WithError should set hasError: true and a minimal/empty
config, and AutoStrategy should set config: { routing_strategy: 'auto' } (no
role_filter). Keep the node id/type/position consistent with the existing
Default story and export each as a StoryObj like Default.

In `@web/src/pages/workflow-editor/AgentAssignmentNode.tsx`:
- Around line 15-18: The role extraction in AgentAssignmentNodeComponent is
over-defensive: remove the redundant "|| undefined" on the role assignment and
just use const role = data.config?.role_filter as string; this relies on the
existing {role && ...} guard to handle missing or empty values and keeps
behavior identical while simplifying the code.

In `@web/src/pages/workflow-editor/ConditionalEdge.tsx`:
- Around line 26-35: The BaseEdge call is using the hardcoded enum
MarkerType.ArrowClosed which in `@xyflow/react` v12 expects a resolved SVG marker
URL string; replace the hardcoded value with the incoming resolved marker from
the edge props by setting markerEnd to props.markerEnd on the BaseEdge component
(keep id={props.id}, path={edgePath}, style as-is). Ensure marker types like
MarkerType.ArrowClosed are defined on your edge objects so React Flow resolves
them into the string that arrives in EdgeProps.markerEnd.

In `@web/src/pages/workflow-editor/ConditionalNode.stories.tsx`:
- Around line 23-26: Add a component reference to the Storybook meta (set
meta.component = ConditionalNode) so docs render correctly, and add two new
StoryObj exports (e.g., Selected and WithError) that render the Wrapper with a
nodes array containing a conditional node demonstrating the selected and
hasError states respectively (set node.data.selected = true for Selected and
node.data.hasError = true for WithError); ensure you import ConditionalNode and
StoryObj/Meta types and keep the existing default story intact.

In `@web/src/pages/workflow-editor/EndNode.tsx`:
- Line 19: The Handle components use incorrect Tailwind important modifier
suffix syntax (e.g., className "bg-border-bright! size-2!"); update the
className on Handle (the JSX element using Position.Top/Position.Bottom) to use
the important prefix form (e.g., "!bg-border-bright !size-2") so Tailwind
applies the ! importance correctly; apply the same fix across all workflow node
components that render Handle (StartNode, EndNode, ParallelSplitNode,
ParallelJoinNode, ConditionalNode, TaskNode, AgentAssignmentNode) to keep
styling consistent.

In `@web/src/pages/workflow-editor/TerminalNode.stories.tsx`:
- Line 11: Story container uses hardcoded pixel inline styles (style={{ width:
200, height: 150 }}) which violates spacing-token rules; replace the inline
style on the div in TerminalNode.stories.tsx with a className that uses Tailwind
utility classes or the project’s token-backed CSS class (e.g., a width/height
utility or design-token class provided by the dashboard design system) so
spacing is driven by tokens rather than fixed pixels; remove the style prop and
apply the appropriate className on the same div to match the intended 200x150
visual size using token-backed utilities.
- Around line 34-35: Extract the inline node arrays used in the story renders
into named constants (e.g., START_NODE, TERMINAL_NODE or NODES_START and
NODES_TERMINAL) at the top of TerminalNode.stories.tsx and replace the inline
objects passed to Wrapper (the nodes prop) with those constants; ensure the
constants are typed appropriately (matching the node type/interface used by the
Wrapper) and used for both occurrences (lines around the start and terminal
stories) to shorten lines and comply with TypeScript line-length rules.

In `@web/src/pages/workflow-editor/workflow-to-yaml.ts`:
- Around line 95-99: The task node conversion omits coordination_topology,
causing the client preview to differ from backend exports; update the logic
where node.type === 'task' (the block that reads config and sets
step.title/task_type/priority/complexity) to also copy
config.coordination_topology into step.coordination_topology when present so the
preview matches the backend's _TASK_CONFIG_KEYS handling.
- Around line 50-51: Move the module-level mutable variable lastSortHadCycle
into the local scope of generateYamlPreview: remove the top-level declaration of
lastSortHadCycle, declare and initialize a local let lastSortHadCycle = false at
the start of generateYamlPreview, and update the places where it’s assigned (the
topological sort code that currently sets lastSortHadCycle) and where it’s read
(the later conditional that checks lastSortHadCycle) to use the new local
variable so concurrent calls don’t share state.

In `@web/src/pages/workflow-editor/WorkflowEditorSkeleton.stories.tsx`:
- Line 13: The story wrapper currently uses an inline style height: 600 on the
div in WorkflowEditorSkeleton.stories.tsx; replace this hardcoded pixel height
with a design-token-backed class or a standard Tailwind spacing utility (e.g., a
dashboard height token class or h-... utility) on that div wrapper so spacing
follows the dashboard design tokens and avoids inline pixels — update the div
(the story wrapper element) to use the appropriate token/Tailwind class instead
of style={{ height: 600 }}.

In `@web/src/pages/workflow-editor/WorkflowNodeDrawer.stories.tsx`:
- Around line 6-9: The Storybook meta object named meta is missing the component
property which prevents autodocs; update the meta constant to include component:
WorkflowNodeDrawer (or the exported React component used by the stories) so
Storybook can generate autodocs automatically — locate the meta const in
WorkflowNodeDrawer.stories.tsx and add the component reference alongside title
and parameters.

In `@web/src/pages/workflow-editor/WorkflowNodeDrawer.tsx`:
- Around line 29-34: handleFieldChange is being recreated on every config change
because config is in the dependency array; change it to use a functional update
so the callback doesn't capture a stale config and remove config from deps.
Specifically, update handleFieldChange to call onConfigChange with a functional
updater (using previous config to merge in {[key]: value}) and memoize it with
useCallback that depends only on onConfigChange (or remove useCallback if
referential stability isn't needed). This keeps handleFieldChange stable while
still applying the latest config when updating.

In `@web/src/pages/workflow-editor/WorkflowToolbar.stories.tsx`:
- Around line 30-33: The meta object for the story is missing the component
property which prevents Storybook autodocs; update the meta (the Meta constant
named meta) to set component: WorkflowToolbar and also add a decorator supplying
ReactFlowProvider (e.g., decorators: [(Story) =>
<ReactFlowProvider><Story/></ReactFlowProvider>]) so the WorkflowToolbar
receives required context and Storybook can generate docs/controls.

In `@web/src/pages/workflow-editor/WorkflowYamlPreview.stories.tsx`:
- Around line 18-21: The Storybook meta object (meta) is missing the component
reference which prevents Storybook from generating docs and controls; import the
actual component used in this story (e.g., WorkflowYamlPreview) into
WorkflowYamlPreview.stories.tsx and add component: WorkflowYamlPreview to the
meta object so Storybook can wire up docs/controls correctly (ensure the Meta
type import stays intact).

In `@web/src/pages/workflow-editor/WorkflowYamlPreview.tsx`:
- Around line 19-31: The component WorkflowYamlPreview.tsx currently uses a
hardcoded id "yaml-preview-content" for the preview container and sets
aria-controls on the toggle button to that id, which will collide when the
component is rendered multiple times; change this to generate a unique id per
instance (e.g., via React's useId or a useRef + unique suffix) and use that
identifier for both the aria-controls on the button and the id on the div
(references: the toggle button that sets aria-controls and the div with id
"yaml-preview-content", and the LazyCodeMirrorEditor wrapper). Ensure the
generated id is stable across renders for the lifetime of the component.

In `@web/src/pages/WorkflowEditorPage.tsx`:
- Around line 247-249: The ARIA live region is empty and never updated, so it
doesn't announce editor actions; add a piece of state like announcement via
useState and update it in action handlers (e.g., handleSave, handleValidate,
handleExport or any functions that perform save/validate/export) by calling
setAnnouncement('...') after success/failure, then render that announcement
inside the existing <div className="sr-only"
aria-live="assertive">{announcement}</div>; alternatively, if your toast system
already performs proper ARIA announcements, remove the empty live region
instead.
- Around line 114-119: The handler handleAddNode uses Math.random() causing
non-deterministic placement; change it to compute the new node position
deterministically (e.g., derive an x/y offset from the current node count or an
incremental counter) before calling addNode(type, position). Update
handleAddNode to reference the existing node list or a stable counter (e.g.,
nodes.length or a useRef counter) to compute positions so each added node is
placed predictably; keep the function name handleAddNode and the addNode(type,
position) call unchanged. Ensure the logic uses WorkflowNodeType as before and
remains wrapped in useCallback with the same dependencies (update dependencies
if you read nodes or a counter).

In `@web/src/stores/workflow-editor.ts`:
- Around line 325-348: onNodesChange and onEdgesChange mark dirty and regenerate
yaml for position/remove changes but never record an undo snapshot, so node
drags and ReactFlow-initiated edge removals bypass undo; update both handlers
(onNodesChange, onEdgesChange) to, when hasMoves or hasRemoves is true, call the
editor's existing undo snapshot routine (e.g., pushUndoSnapshot /
createHistorySnapshot) before returning and pass the prior state (s.nodes,
s.edges, s.definition) so the previous layout/edges can be restored; keep the
applyNodeChanges/applyEdgeChanges usage and yamlPreview logic but ensure
snapshot capture happens using the state values from s (or a deep copy) so
drags/removals become undoable.
- Around line 371-386: In the redo handler, avoid shallow copies made with
[...nodes] and [...edges]; replace those with deep clones using structuredClone
when building the current WorkflowSnapshot (current) and when restoring
nodes/edges from the snapshot (i.e., where you set nodes: snapshot.nodes and
edges: snapshot.edges). Update usages in the redo function (redo, current
variable creation, and the set call) to use structuredClone(nodes),
structuredClone(edges), and
structuredClone(snapshot.nodes)/structuredClone(snapshot.edges) so state is
fully deep-copied and immutable.
- Around line 354-369: The undo handler creates a shallow redo snapshot using
current: WorkflowSnapshot = { nodes: [...nodes], edges: [...edges] } which keeps
references to nested node/edge data; replace that shallow copy with a deep clone
using structuredClone so the pushed redo snapshot is independent (e.g., create
current by calling structuredClone({ nodes, edges }) before using
get().redoStack), leaving other logic (regenerateYaml, set, undoStack update)
unchanged and referencing the same functions/variables (undo, redoStack,
WorkflowSnapshot, regenerateYaml, get, set).
- Around line 83-92: The nodeTypeToEdgeType function contains dead logic: the
conditional branch checks sourceHandle but returns 'conditional' for both cases;
either remove the unused sourceHandle parameter and its ternary (if conditional
edges truly share the same style) or implement distinct returns for conditional
handles (e.g., return 'conditional-true' when sourceHandle === 'true' and
'conditional-false' otherwise) so the function's behavior matches the intent;
update the function signature and all callers of nodeTypeToEdgeType accordingly.

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@docs/design/page-structure.md`:
- Around line 169-170: Update the node and edge type lists to match the enums:
replace the node list on lines referencing node types so it reads start, end,
task, agent_assignment, conditional, parallel_split, parallel_join (matching
WorkflowNodeType), and update the edge list to read sequential,
conditional_true, conditional_false, parallel_branch (matching
WorkflowEdgeType); ensure the old names notification, parallel_fork, and
parallel_join (for edges) are removed and the new explicit
conditional_true/conditional_false and parallel_branch names are used.

In `@src/synthorg/persistence/sqlite/workflow_definition_repo.py`:
- Line 236: The SQL builder currently appends a hardcoded " ORDER BY updated_at
DESC LIMIT 10000"; change this to a configurable limit or pagination parameter
by replacing the literal with a parameterized clause (e.g., " ORDER BY
updated_at DESC LIMIT :limit" or "LIMIT ?") and surface a new argument on the
repository method that builds this query (the method that defines the local
variable query and appends that string) such as
list_workflow_definitions/get_workflow_definitions, defaulting to a sensible
value and validating bounds; ensure the method passes the limit value into the
DB call, update any callers to accept the new optional parameter, and add tests
for custom limits and default behavior.
- Around line 77-84: Replace the parenthesized multi-exception clause with the
PEP 758 comma-separated form: change the line "except (ValueError,
ValidationError, json.JSONDecodeError, KeyError) as exc:" to "except ValueError,
ValidationError, json.JSONDecodeError, KeyError as exc:" in the deserialization
error-handling block around the logger.exception call for
PERSISTENCE_WORKFLOW_DEF_DESERIALIZE_FAILED (the block that builds msg =
f\"Failed to deserialize workflow definition {context_id!r}\" and raises
QueryError).

In `@tests/unit/api/controllers/test_workflows.py`:
- Around line 119-121: The test helper _seed directly mutates the repository
internals via repo._definitions which couples tests to implementation; change
_seed to call the repository's public save method (e.g., repo.save(defn) or
equivalent) to persist the definition, or if direct mutation is intentional for
performance, add a clear comment in _seed explaining it's a test-only shortcut
and why it bypasses repo.save. Ensure you reference repo and defn.id usage so
tests still return the expected id.

In `@tests/unit/api/fakes_workflow.py`:
- Around line 13-30: The fake repository currently stores and returns live
WorkflowDefinition instances which allows tests to mutate repository state;
import copy and deep-copy definitions at the persistence boundary: when saving
(in __init__/save ensure you store copy.deepcopy(definition)) and when returning
(in get and list_definitions return copy.deepcopy of stored items or copies of
the tuple), so callers receive independent objects and behavior matches
serialize/deserialize repos; update references to save, get, and
list_definitions accordingly.

In `@tests/unit/engine/workflow/test_validation.py`:
- Around line 10-18: The imports from the same module are duplicated;
consolidate the three separate import blocks into a single statement importing
make_edge, make_node, and make_workflow from tests.unit.engine.workflow.conftest
(use the existing aliases _edge, _node, _wf) so replace the multiple from ...
import blocks with one line that imports make_edge as _edge, make_node as _node,
and make_workflow as _wf to reduce redundancy and improve readability.

In `@tests/unit/persistence/sqlite/test_workflow_definition_repo.py`:
- Around line 147-168: Add a unit test that verifies
SQLiteWorkflowDefinitionRepository.save enforces optimistic concurrency by
rejecting an update whose incoming version is not exactly one greater than the
stored version: create an initial definition via _make_definition(version=1) and
await repo.save(...), then attempt to save a second definition for the same id
with a non-sequential version (e.g., version=3) and assert the repository does
not apply the update (repo.get("wf-001") still returns the original values and
version remains 1) or that save raises the expected rejection behavior; place
this as a new test function (e.g., test_save_rejects_on_version_mismatch)
alongside test_save_upsert_updates_existing.

In `@web/src/pages/workflow-editor/ConditionalNode.stories.tsx`:
- Line 10: The story wrapper in ConditionalNode.stories.tsx currently uses
inline pixel dimensions on the outer <div> (style={{ width: 300, height: 250
}}); replace that inline styling with Tailwind utility classes (e.g., use
appropriate w- and h- classes or design-token-based class names) so pixel
spacing isn’t hardcoded. Update the story’s wrapper element where the inline
style is applied (the outer div in the ConditionalNode story) to use
project-approved Tailwind/design-token classes consistent with other
web/src/**/*.tsx components.

In `@web/src/pages/workflow-editor/ParallelJoinNode.tsx`:
- Around line 29-42: The ParallelJoinNode currently hardcodes two incoming
handles (Handle elements with ids "branch-0" and "branch-1"), which prevents
representing 2+ branches; update ParallelJoinNode to render handles dynamically
by iterating over the node's incoming branches/count (use the prop or workflow
model that lists incoming branch ids), creating a Handle per branch with a
unique id like `branch-${i}` and computing the Position.Top `style.left` as
evenly spaced percentages (e.g., (i+1)/(n+1)*100%). Ensure each generated Handle
keeps the same type/position/className props so the canvas matches the persisted
model.

In `@web/src/pages/workflow-editor/ParallelSplitNode.tsx`:
- Around line 31-45: The ParallelSplitNode currently hardcodes two source
Handles ("branch-0" and "branch-1"), which enforces a binary split; update the
component (ParallelSplitNode) to render N handles dynamically by iterating over
the node's branch data (e.g., props.data.branches or node.data.outputs) and
creating a Handle for each branch with id `branch-{i}` and position computed as
an evenly spaced left percentage ((i+1)/(count+1) * 100%) so additional branches
produce unique ids and non-overlapping positions; ensure each Handle uses
type="source" and Position.Bottom and retains existing classes/styles.

In `@web/src/pages/workflow-editor/WorkflowNodeDrawer.tsx`:
- Around line 29-33: The handleFieldChange callback currently writes
Number(value) directly which can produce NaN; change it to parse the number and
only persist when finite: in handleFieldChange, when fieldType === 'number'
compute const num = Number(value) and use Number.isFinite(num) ? num : keep the
existing value from config[key] (or bail out without calling onConfigChange) so
NaN is never written to config; update the onConfigChange call to use the
guarded parsed value. Reference: handleFieldChange, config, onConfigChange.

In `@web/src/pages/workflow-editor/WorkflowYamlPreview.stories.tsx`:
- Around line 18-22: Update the generic typing so TypeScript infers props from
the component: change the meta declaration to use Meta<typeof
WorkflowYamlPreview> and any story objects to use StoryObj<typeof
WorkflowYamlPreview>, then export the meta and stories with those types (replace
plain Meta and StoryObj usages) so props, args and controls are strongly typed
for WorkflowYamlPreview.

In `@web/src/pages/workflow-editor/WorkflowYamlPreview.tsx`:
- Around line 23-27: The chevron icons are inverted: when the panel is collapsed
(variable collapsed) the UI shows <ChevronUp> but should show <ChevronDown> and
vice versa when expanded; update the JSX in WorkflowYamlPreview (the conditional
rendering that currently uses ChevronUp/ChevronDown) to swap the two components
so collapsed renders ChevronDown and expanded renders ChevronUp, keeping the
existing aria/label text intact.

In `@web/src/stores/workflow-editor.ts`:
- Around line 188-218: The saveDefinition flow clears validationResult after a
successful save which can leave validation stale; after updateWorkflow returns
(in saveDefinition) re-run the store's validation routine (e.g., call the
existing validateDefinition/validateWorkflow function or validation API) using
the updatedDef, and set validationResult to that returned result instead of null
(or set to null only if no validator exists), so users get up-to-date validation
immediately after saving.
- Around line 370-372: In the redo function, avoid assigning snapshot.nodes and
snapshot.edges directly—deep clone the restored snapshot before calling set to
prevent later mutations from corrupting undo history; mirror the pattern used
earlier where you deep-clone state before pushing to redo/undo (i.e., create
clones of snapshot.nodes and snapshot.edges and pass those clones into set
within the redo function).

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@src/synthorg/api/controllers/workflows.py`:
- Around line 257-277: The code uses existing.model_copy(update=updates) which
bypasses Pydantic v2 field coercion and `@model_validator` hooks (so
_validate_unique_ids, _validate_edge_references, _validate_terminal_nodes and
workflow_type coercion are skipped); instead merge the existing model dump with
updates (e.g., base = existing.model_dump()), apply updates to that dict, then
re-validate by calling WorkflowDefinition.model_validate(merged_dict) (or
existing.__class__.model_validate) and catch ValidationError/ValueError as
before; then pass the validated instance to repo.save(updated) so validators run
before persisting.

In `@src/synthorg/engine/workflow/validation.py`:
- Around line 178-242: _check_conditional_edges currently only ensures presence
of TRUE/FALSE but allows duplicates; update it to require exactly one
WorkflowEdgeType.CONDITIONAL_TRUE and exactly one
WorkflowEdgeType.CONDITIONAL_FALSE (use counts on out_types and emit
ValidationErrorCode.CONDITIONAL_MISSING_TRUE/CONDITIONAL_MISSING_FALSE when
count==0 and a new or existing error code like CONDITIONAL_DUPLICATE_TRUE/FALSE
when count>1 or reuse CONDITIONAL_EXTRA_OUTGOING) and still reject any edges not
in _CONDITIONAL_EDGE_TYPES; similarly, change _check_parallel_splits to not only
count WorkflowEdgeType.PARALLEL_BRANCH but also treat any outgoing edge types
that are not WorkflowEdgeType.PARALLEL_BRANCH as an error (emit
ValidationErrorCode.SPLIT_HAS_NON_PARALLEL_OUTGOING or reuse
SPLIT_TOO_FEW_BRANCHES/CONDITIONAL_EXTRA_OUTGOING as appropriate), so parallel
splits must have only parallel_branch edges and at least _MIN_SPLIT_BRANCHES of
them.

In `@src/synthorg/persistence/sqlite/schema.sql`:
- Around line 319-320: The version column currently defaults to 1 but lacks a
constraint preventing zero or negative values; update the schema definition for
the version column (the column named "version") to enforce a positive invariant
by adding a CHECK that version >= 1 (either as an inline CHECK on the "version"
column or a named table-level constraint such as "positive_version") so
optimistic concurrency assumptions cannot be violated.

In `@src/synthorg/persistence/sqlite/workflow_definition_repo.py`:
- Around line 121-162: The INSERT...ON CONFLICT with the optimistic-concurrency
WHERE clause can succeed as a no-op (zero rows affected) on version mismatch;
detect this by capturing the cursor returned from await self._db.execute(...)
(assign to a variable like cursor), check cursor.rowcount (or
cursor.get_changes() if using a different DB API) before committing, and if
rowcount == 0 then rollback the transaction (await self._db.rollback()),
log/raise a concurrency-specific error (e.g., raise QueryError or a new
ConcurrencyError) referencing definition.id to signal the optimistic concurrency
failure instead of committing and logging PERSISTENCE_WORKFLOW_DEF_SAVED; keep
the sqlite3.Error except block for actual DB errors.

In `@web/src/pages/workflow-editor/ConditionalNode.tsx`:
- Around line 15-16: The code reads data.config?.condition_expression as a
string without validation in ConditionalNodeComponent, which can render "[object
Object]" or throw; change the assignment for condition to first check typeof
data.config?.condition_expression === 'string', trim() that string, and if it's
empty or not a string fall back to data.label so only a validated string is
rendered (reference ConditionalNodeComponent and the condition
variable/data.config?.condition_expression).

In `@web/src/pages/workflow-editor/TaskNode.stories.tsx`:
- Line 10: The container div in TaskNode.stories.tsx currently uses hardcoded
inline pixel sizes (the element with style={{ width: 300, height: 200 }});
remove the inline style and replace it with the design-system/tailwind sizing
tokens via a className (use the project’s token scale equivalents for 300x200 —
e.g., the corresponding w- and h- tokens or design-system size tokens) so sizing
comes from the design system; ensure the className is applied to the same div
and verify the story layout remains visually identical in Storybook.

In `@web/src/pages/workflow-editor/TaskNode.tsx`:
- Line 35: Update the Tailwind important modifier to prefix form on the Handle
components: replace postfix classes like "bg-border-bright! size-1.5!" with the
prefix form "!bg-border-bright !size-1.5" so the styles are not ignored. Locate
the Handle usages (e.g., in TaskNode.tsx's Handle component and the equivalent
handles in ParallelJoinNode.tsx, StartNode.tsx, EndNode.tsx,
ParallelSplitNode.tsx) and update their className strings accordingly; ensure
all occurrences of trailing "!" modifiers are converted to leading "!" for each
utility.

In `@web/src/pages/workflow-editor/WorkflowNodeDrawer.tsx`:
- Around line 55-84: The JSX inside fields.map in WorkflowNodeDrawer.tsx is too
large; extract the per-field renderer into a new component or helper function
(e.g., FieldRenderer or renderConfigField) that accepts a ConfigField, current
value, and handleFieldChange callback and returns either the SelectField or
InputField JSX; replace the inline map body with fields.map(field =>
<FieldRenderer key={field.key} field={field} value={String(config[field.key] ??
'')} onChange={handleFieldChange} />) and ensure the new component uses
field.type, field.options, field.placeholder, SelectField, InputField, and calls
handleFieldChange(field.key, ...) maintaining the same props/behavior.

In `@web/src/pages/workflow-editor/WorkflowToolbar.tsx`:
- Around line 72-84: Extract the repeated JSX in the NODE_PALETTE.map into a
small reusable component (e.g., PaletteButton) to improve readability: create a
PaletteButton functional component that accepts props (type, label, icon, onAdd)
and renders the Button plus Icon, then replace the inline map body with
<PaletteButton key={type} ... onAdd={onAddNode} />; reference NODE_PALETTE,
onAddNode and the new PaletteButton in the change so the map becomes a single
call and the button rendering logic lives in PaletteButton.

In `@web/src/stores/workflow-editor.ts`:
- Around line 401-419: The validate and exportYaml handlers currently use only
definition.id and ignore unsaved canvas edits; update validate and exportYaml in
workflow-editor.ts to check the store's dirty flag (from get()) and either block
the action (set an error like 'Cannot validate/export while there are unsaved
changes') or, preferably, gather the current in-memory graph (nodes, edges,
yamlPreview from get()) and send that payload to the backend by calling
validateWorkflow and exportWorkflowYaml with the full definition object or a new
API overload that accepts the live graph; ensure you update set() calls to
toggle validating/exporting flags and keep existing error handling (use
getErrorMessage(err)) when network calls fail.
- Around line 128-135: loadDefinition() currently maps persisted edge types like
'parallel_branch' back to 'sequential', causing edge.type instability versus
edges created by onConnect() (which uses 'parallel_branch'); update the mapping
in the edges construction (the const edges: Edge[] block in loadDefinition()) to
preserve 'parallel_branch' (i.e., set type to 'parallel_branch' when e.type ===
'parallel_branch') and ensure the data.edgeType/sourceHandle/branch logic
remains consistent; also apply the same preservation change in the other mapping
block referenced (around lines 282-299) so persisted parallel edges keep the
same React Flow type as edges created by onConnect().

---

Duplicate comments:
In `@src/synthorg/api/dto.py`:
- Around line 611-618: The nodes and edges fields currently accept arbitrary
dict[str, object] which bypasses request-time validation; define explicit
Pydantic models (e.g., NodeDTO and EdgeDTO) with concrete fields (for example
NodeDTO: id: str, type: str, metadata: dict[str, Any] | None; EdgeDTO: id: str,
source: str, target: str, type: str, metadata: dict[str, Any] | None) and
replace the annotations on nodes and edges to tuple[NodeDTO, ...] and
tuple[EdgeDTO, ...]; keep the existing Field(...) metadata (description and max
length) or use conlist/typing constraints if you want strict length validation,
and update any imports so DTO parsing/validation happens at the API boundary
(referencing nodes and edges in src/synthorg/api/dto.py).

In `@tests/unit/api/controllers/test_workflows.py`:
- Around line 119-123: The test currently mutates the fake repository's private
storage (repo._definitions) which couples tests to implementation; add a
test-only synchronous seed method on the fake repository (e.g.,
FakeWorkflowDefinitionsRepository.seed(definition) or seed_definitions(dict))
and implement it to populate the internal store, then update the test to call
repo.seed(defn) (or repo.seed_definitions({defn.id: defn})) instead of touching
repo._definitions directly; keep the internal field name (e.g., _definitions)
private and let the new seed API encapsulate the mutation for Litestar
TestClient sync tests.

In `@web/src/pages/workflow-editor/AgentAssignmentNode.stories.tsx`:
- Line 10: The div in AgentAssignmentNode.stories.tsx uses an inline style prop
style={{ width: 300, height: 200 }} which hardcodes pixel spacing; remove the
style prop and replace it with the project's design-token-based utility classes
or spacing tokens (e.g., a className that uses the design system/Tailwind
utility or CSS variable-based token for width/height) so sizing comes from
approved tokens rather than raw pixels; update the JSX that renders the div in
AgentAssignmentNode.stories.tsx accordingly and ensure no other inline pixel
spacing remains.

In `@web/src/pages/workflow-editor/EndNode.tsx`:
- Line 19: The Tailwind important modifier is used with the suffix form
incorrectly on the Handle component in EndNode.tsx; update the className on the
Handle (the JSX <Handle ... />) to use the prefix form for important utilities
(e.g. replace any "bg-border-bright! size-2!" tokens with "!bg-border-bright
!size-2") so the important flag is applied correctly and ensure spacing between
utilities.

In `@web/src/pages/workflow-editor/ParallelJoinNode.tsx`:
- Around line 29-42: ParallelJoinNode currently renders only two fixed Handle
components (ids "branch-0" and "branch-1"); update the render to generate
Handles dynamically based on the actual incoming branch count (derive from
props.data.config.branch_count if present, or fallback to
props.incomingEdges.length or data.incoming.length) and map over that count to
create Handle elements with ids like `branch-{i}` and unique keys; compute each
Handle's left style using a distribution formula (e.g. (i+1)/(count+1) as a
percentage) so handles spread evenly, preserve type="target" and
position={Position.Top}, and keep existing classes (e.g. "bg-accent!
size-1.5!")—also ensure any event handlers or references expecting branch ids
are updated to accept the dynamic `branch-{i}` naming.

In `@web/src/pages/workflow-editor/ParallelNode.stories.tsx`:
- Line 11: The wrapper div in ParallelNode.stories.tsx uses inline px sizing
(style={{ width: 300, height: 200 }}); remove the hardcoded inline style and
replace it with token-backed sizing via Tailwind/design tokens (use a className
that references the project spacing tokens or the appropriate Tailwind utility
classes mapped to those tokens) so the story canvas follows the dashboard
spacing rules and avoids hardcoded pixel values; update the JSX wrapper div to
use the token-based className instead of style.

In `@web/src/pages/workflow-editor/ParallelSplitNode.tsx`:
- Around line 31-45: The component currently hardcodes two bottom source Handles
("branch-0" and "branch-1") using Position.Bottom which prevents >2 outgoing
edges; change ParallelSplitNode to iterate over the node's branch metadata/count
(e.g., the branches array or node.data.branches) and render a Handle per branch,
generating id `branch-${i}` and className/position using Position.Bottom, and
compute style.left dynamically (even spacing, e.g. (i+1)/(count+1) * 100%) so
each outgoing branch gets its own unique handle instead of reusing
branch-0/branch-1.

In `@web/src/pages/workflow-editor/WorkflowYamlPreview.tsx`:
- Around line 23-27: The disclosure icons are inverted: change the JSX in the
conditional using the collapsed boolean so that when collapsed is true it
renders <ChevronDown ... /> and when collapsed is false (expanded) it renders
<ChevronUp ... />; update the conditional around the collapsed variable (the JSX
that currently renders ChevronUp/ChevronDown) to swap the two icon components so
the visual chevron matches the collapsed/expanded state (keep existing props
like className and aria-hidden).

In `@web/src/pages/WorkflowEditorPage.tsx`:
- Around line 114-119: The handler handleAddNode currently uses Math.random()
for node coordinates which yields non-deterministic layouts; replace that with a
deterministic placement strategy (e.g., grid-snapping or offset by existing node
count) inside handleAddNode so new nodes added via addNode(type, coords) get
predictable positions; reference the addNode call in handleAddNode and compute
coords from a deterministic source (like nodes.length or a nextIndex counter)
rather than Math.random(), ensuring coordinates follow a consistent grid or
incremental offset strategy.