Hard restore with X asks before dropping staged pins

X dropped staged pins without a question, including the selected
submodule's own pin, which the loss check didn't count. A staged pin is
a decision, and X sits one Shift away from x, so dropped staged pins now
count as a loss and make X ask (D31, amends D30).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

docs/actions.md

@@ -87,9 +87,10 @@ own, and for nested repositories that are on their pin. A repository that
 moves loses its staged pins either way (see above); then `x` → `c` and `X`
 end the same, but `c` asks first.
 
-The dropped staged pins are counted in the loss (`2 staged pins`), but
-alone they don't make restore ask: pressing `X` is the choice to drop them.
-If something else would be lost, the question lists them with it. The
+The dropped staged pins are counted in the loss (`2 staged pins`), the
+selected submodule's own staged pin included, and like any loss they make
+restore ask (D31): `Restore libs/staged to the committed pins? Discards 1
+staged pin.` The
 commits of a dropped pin stay in the submodule; if HEAD leaves them and no
 ref reaches them, they count as `commits on no branch`, as always.
 

docs/decisions.md

@@ -593,3 +593,18 @@ staged and committed pin is still useful there.
 the superproject. `restoreRepo` and `lossOf` take whether to keep staged
 pins; switch always keeps them. Without a committed pin (an added
 submodule), `X` uses the index pin.
+
+## D31 — Hard restore asks before dropping staged pins
+
+**Context.** D30 let `X` drop staged pins without a question: pressing `X`
+was the choice. In a usability walkthrough (see
+[notes/usability-plan.md](../notes/usability-plan.md)) `X` on `libs/staged`
+unstaged its pin silently. `X` is one Shift away from `x`, and users new to
+submodules don't know where to find the dropped commit again.
+**Decision.** Amends D30. Dropped staged pins are a loss like any other and
+make `X` ask: `Restore libs/staged to the committed pins? Discards 1 staged
+pin.` `RestoreLoss` with `RestoreHard` now also counts the selected
+submodule's own staged pin (in its parent's index), which `lossOf` doesn't
+see. The `c` answer of `x` stays silent: the user picked it in a question.
+**Consequences.** `X` asks more often, but only where it changes what is
+recorded. Without staged pins or other losses it still runs at once.

docs/requirements.md

@@ -150,7 +150,7 @@ commit hashes. It doesn't answer the questions users actually have:
   confirmation only if something would be lost. See [actions.md](actions.md#restore).
   `X` is a hard restore: it goes to the committed pins at every depth,
   without the pin question, and drops all staged pins below the selection
-  too. Dropped staged pins alone don't make it ask. See
+  too. Dropped staged pins count as a loss, so it asks first. See
   [actions.md](actions.md#hard-restore).
 
 - **F57** `b` opens a popup in the middle of the screen with a search line

docs/ux-guide.md

@@ -363,8 +363,9 @@ the term*.
 
 `y` restores, any other key cancels; the keys are not passed on while a
 question is open. After `c` the name reads `src/app to the committed pin`.
-`X` (hard restore) never asks for the pin; its name reads `src/app to the
-committed pins`, and dropped staged pins alone don't make it ask. Without a loss there is no question. Success flashes
+`X` (restore committed pins) never asks for the pin; its name reads
+`src/app to the committed pins`. Staged pins it drops count as a loss
+(`Discards 1 staged pin.`), so it asks (D31). Without a loss there is no question. Success flashes
 `restored src/app` in the footer. For the header the name is `the
 superproject`. This line takes precedence over the filter line and the
 problems-only notice.