From 39782ce843699a0931ca68773411f2befe6e374e Mon Sep 17 00:00:00 2001
From: Ethanfel <ethan.fel@ts-pc.fr>
Date: Wed, 1 Jul 2026 15:47:05 +0200
Subject: [PATCH] Document scene layer seed simplification

---
 .../2026-07-01-scene-layer-seed-design.md     | 68 +++++++++++++++++++
 1 file changed, 68 insertions(+)
 create mode 100644 docs/superpowers/specs/2026-07-01-scene-layer-seed-design.md

diff --git a/docs/superpowers/specs/2026-07-01-scene-layer-seed-design.md b/docs/superpowers/specs/2026-07-01-scene-layer-seed-design.md
new file mode 100644
index 0000000..6653bf4
--- /dev/null
+++ b/docs/superpowers/specs/2026-07-01-scene-layer-seed-design.md
@@ -0,0 +1,68 @@
+# Scene Layer Seed Design
+
+## Problem
+
+`SxCPSceneLayerSeedOptions` currently has a confusing double-seed behavior. When
+`seed_mode=random`, the node displays one seed in the widget, but the build
+method replaces it with a hidden `SystemRandom` value. The generated prompt may
+therefore use a clothing/content seed that is not visible in the workflow after
+the run.
+
+This makes softcore branch clothing hard to reproduce. In a scene pair, the
+woman's softcore outfit is selected from the softcore branch content seed, then
+the hardcore branch may inherit that outfit through clothing continuity. If the
+resolved content seed is hidden, the user cannot reliably answer which seed
+picked the clothes.
+
+## Approved Behavior
+
+The visible `seed` field in `SxCPSceneLayerSeedOptions` is the authoritative
+seed. `seed_mode=random` must no longer replace it with a hidden random value.
+For layer-seed behavior:
+
+- `follow_global`: use the scene seed.
+- `fixed`: use the visible node `seed`.
+- `random`: use the visible node `seed`.
+- `disabled`: apply no layer seed.
+
+The `random` option can remain in the UI for compatibility, but it behaves like
+an explicit seed mode. If a user wants a new random value, they should randomize
+the visible seed field in the node or use ComfyUI's widget randomization.
+
+## Seed Reporting
+
+The existing scene `seed_trace` remains the source of truth for resolved prompt
+axis seeds. For softcore branch clothing, the relevant trace is usually:
+
+- layer: `softcore_branch`
+- reroll axis: `content` or `content_pose`
+- affected axes: `content_seed`, and for `content_pose` also `pose_seed` and
+  `role_seed`
+
+Scene pair metadata should continue to include the full softcore and hardcore
+scene chain so `seed_trace` is preserved in `metadata_json` and
+`scene_metadata_json`.
+
+## Non-Goals
+
+This change does not introduce a separate `clothing_seed` axis. Clothing is still
+part of the existing content axis. Splitting clothing from content would be a
+larger behavior change and should be handled separately if needed.
+
+This change does not alter image sampler seeds. KSampler/image seeds remain
+separate from prompt layer seeds.
+
+## Testing
+
+Add or update smoke coverage for `SxCPSceneLayerSeedOptions`:
+
+- A `random` mode layer seed emits the visible widget seed in its metadata.
+- A `fixed` mode layer seed emits the same seed as `random` when given the same
+  visible seed.
+- A softcore branch `content` or `content_pose` seed appears in the generated
+  softcore row `seed_config`.
+- The generated softcore outfit can be traced to that visible content seed.
+
+Existing scene pair tests should continue to verify that softcore branch seeds do
+not leak into hardcore pose/content seeds unless explicitly applied to the hard
+branch.