docs: record the responsive stacking bug with a deterministic repro

A pane added after a narrow->wide responsive cycle is absorbed into a stack,
because the tab stays pinned to the synthesized sl0p:responsive-expand layout,
which was generated for the pane count at synthesis time. Creating the session
wide and adding a pane is correct; creating it narrow, widening, then adding is
not. apply_responsive_layout only runs on resize, which is why resizing appears
to fix it.

Includes the instrumented step table and the geometry that proves the stack, so
the next session can start from the mechanism rather than the symptom.

1 files changed, 42 insertions, 0 deletions

diff --git a/docs/roadmap.md b/docs/roadmap.md
index d05e4e7..c260a5d 100644
--- a/docs/roadmap.md
+++ b/docs/roadmap.md
@@ -193,6 +193,48 @@ The fork bug is still there for anyone calling `zellij attach -b`, and the next
 step is to instrument `ScreenInstruction::RemoveClient` on a debug build to find
 why the removal never reaches `screen.connected_clients`.
 
+## Known issue: panes stack after a responsive collapse/expand cycle
+
+Reported as "a new pane starts collapsed even though the terminal is big
+enough", and it self-corrects after resizing the window.
+
+Reproduced deterministically on the test box (`responsive_min_cols 90`):
+
+| sequence | result |
+|---|---|
+| create the session **wide** (160 cols), add a pane | correct 22/22 split |
+| create it **narrow** (80), widen to 160, add a pane | **stacked** at 160 cols |
+
+Instrumented, the second sequence goes:
+
+| step | active swap layout | cols | panes |
+|---|---|---|---|
+| narrow, 1 pane | `None` | 80 | 1 |
+| narrow, +pane | `sl0p:responsive-collapse` | 80 | 1 |
+| widened | `sl0p:responsive-expand` | 160 | 2 |
+| wide, +pane | `sl0p:responsive-expand` | 160 | 3 |
+
+Both the collapse and the expand are correct. The damage is done afterwards: the
+tab stays pinned to the **synthesized** `sl0p:responsive-expand` layout, which
+was generated for the pane count at the time it was synthesized. Add a pane and
+that layout no longer describes the tab, so the extra pane is absorbed into a
+stack — geometry shows two panes sharing `y=0` while a third sits at `y=22`.
+
+`apply_responsive_layout` has exactly one caller (the whole-tab resize path) and
+returns early when already on the correct side of the threshold, so a pane
+count change never re-resolves the synthesized layout. Resizing the window is
+what re-runs it, which is why a resize "fixes" it.
+
+Likely fix: when the pane count changes and the active tiled layout is one of
+the synthesized responsive ones, re-synthesize it for the new count (or drop
+back to BASE when above the threshold). That is the same class of problem as
+`sl0p: keep expanding possible after the pane count changes`, so the existing
+tests around it are the place to start.
+
+Deliberately not fixed in the same session it was found: this is the most
+delicate part of the fork, and two quick fixes earlier in this session each
+looked right and turned out to be wrong under verification.
+
 ## Standing risks
 
 **`sl0ppij/target` is a symlink to `~/lol/zellij/target`.** Introduced when the