claude-dev-env 1.31.0 → 1.33.0

package/skills/logifix/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: logifix
+description: Restore the Logitech Gaming Software (LCore) tray icon when it disappears on Windows. Calls a PowerShell script that reproduces the verified Session 2 recovery procedure from 2026-04-25. Triggers on "logifix", "/logifix", "logitech tray icon missing", "LCore tray gone", "logitech is not loaded".
+---
+
+# logifix
+
+## Overview
+
+Restore the Logitech Gaming Software (LCore) tray icon by reproducing the verified recovery procedure documented in `sessions/System Support/2. Logitech Tray Icon Fix Recurrence.md`.
+
+**Announce at start:** "Running /logifix to restore the LCore tray icon."
+
+## What the script does
+
+`scripts/logifix.ps1` runs this sequence (verified during Session 2 on 2026-04-25):
+
+1. **State snapshot.** Explorer instances per session, Logitech services state, LCore process state.
+2. **Stop LCore in user context.** `Stop-Process -Name LCore -Force`.
+3. **Single elevated UAC step:**
+   - `Start-Service -Name LogiRegistryService` (handles the recurrence case where the service is Stopped).
+   - `Stop-Process -Name explorer -Force`.
+   - **Does NOT** call `Start-Process explorer` from inside the elevated block. Windows shell auto-respawn handles the user-session explorer cleanly. Skipping this line is the operative fix discovered in Session 2 — including it created a duplicate admin-context `explorer.exe` (no resolvable owner, parent = the admin pwsh) that blocked LCore tray registration.
+4. **Wait for Windows shell auto-respawn** (default 5 seconds).
+5. **Verify exactly one explorer in the user's session.**
+6. **Perform `LCoreRelaunchAttemptCount` full stop-then-launch cycles of `LCore.exe /minimized`** (default 2). The full count always runs — a responsive LCore on the first attempt does NOT imply the tray icon registered. Per Session 2 gotcha #2, the first relaunch can leave LCore responsive with no tray icon; only a second stop+launch reliably triggers `Shell_NotifyIcon` registration.
+7. **Final state snapshot.**
+
+## Invocation
+
+From Claude Code:
+
+```
+/logifix
+```
+
+Direct PowerShell:
+
+```
+pwsh -File "$HOME\.claude\skills\logifix\scripts\logifix.ps1"
+```
+
+Optional parameters (all have safe defaults):
+
+- `-ExplorerAutoRespawnWaitSeconds <int>` — wait after the elevated kill (default 5).
+- `-LCoreInitializationWaitSeconds <int>` — wait after each LCore relaunch before checking responsiveness (default 5).
+- `-LCoreRelaunchAttemptCount <int>` — number of LCore stop+launch cycles to perform (default 2). Always runs the full count.
+
+## When to use
+
+- LCore tray icon missing (also confirmed absent from the overflow `^` chevron).
+- LCore process is running but the tray icon never appears.
+- After resume from sleep, system restart, or a Logitech service crash that leaves LCore in a half-loaded state.
+
+## Fallback (if the script does not restore the icon)
+
+If `/logifix` reports that UAC was canceled, or LCore is still not responding after both relaunch cycles:
+
+1. **Ctrl+Shift+Esc** → Task Manager.
+2. Find **Windows Explorer** → right-click → **Restart**.
+3. Re-run `/logifix`.
+
+The Task Manager restart path is guaranteed to hit the correct interactive session and elevation context regardless of how the calling shell was launched. In Session 2, elevated calls from Claude Code's PowerShell tool could not be confirmed to reach the user's interactive Session 1 — Task Manager bypasses that ambiguity.
+
+## Source
+
+Procedure verified during Session 2 (Logitech Tray Icon Fix Recurrence), 2026-04-25. The session log lists the verified command set, the gotcha catalog, and the final process/service state.
+
+The "always run the full relaunch count" behavior was added on 2026-04-26 after `/logifix` reported success on the first responsive attempt but the tray icon never appeared — the original early-break optimization conflicted with documented Session 2 gotcha #2 (responsive LCore, no tray icon).

package/skills/logifix/scripts/logifix.ps1

@@ -0,0 +1,205 @@
+<#
+.SYNOPSIS
+Restores the Logitech Gaming Software (LCore) tray icon when it is missing on Windows.
+
+.DESCRIPTION
+Reproduces the verified recovery procedure from
+sessions/System Support/2. Logitech Tray Icon Fix Recurrence.md (2026-04-25):
+  1. Stops LCore in user context.
+  2. Single elevated UAC step:
+       - Starts LogiRegistryService (handles the case where it is Stopped).
+       - Stops explorer.exe and lets Windows shell auto-respawn rebuild it.
+     Deliberately omits Start-Process explorer from the elevated block to
+     avoid the duplicate admin-context explorer that blocked tray registration
+     during Session 2.
+  3. Waits for shell auto-respawn.
+  4. Verifies a single user-session explorer.
+  5. Performs LCoreRelaunchAttemptCount full stop-then-launch cycles of
+     LCore /minimized. Always runs the full count: a responsive LCore on the
+     first attempt does NOT imply Shell_NotifyIcon registered, per Session 2
+     gotcha #2 (responsive process, no tray icon).
+
+.PARAMETER ExplorerAutoRespawnWaitSeconds
+Seconds to wait after the elevated explorer kill before verifying respawn.
+
+.PARAMETER LCoreInitializationWaitSeconds
+Seconds to wait after each LCore relaunch before checking responsiveness.
+
+.PARAMETER LCoreRelaunchAttemptCount
+Total number of LCore relaunch cycles to perform (default 2). The full count
+always runs, because the documented failure mode is a responsive LCore that
+never registered a tray icon -- only a second stop+launch reliably triggers
+Shell_NotifyIcon registration.
+#>
+
+[CmdletBinding()]
+param(
+    [int] $ExplorerAutoRespawnWaitSeconds = 5,
+    [int] $LCoreInitializationWaitSeconds = 5,
+    [int] $LCoreRelaunchAttemptCount = 2
+)
+
+Set-StrictMode -Version Latest
+$ErrorActionPreference = 'Stop'
+
+$script:LCoreExecutablePath = 'C:\Program Files\Logitech Gaming Software\LCore.exe'
+$script:LCoreProcessName = 'LCore'
+
+function Get-CurrentInteractiveSessionId {
+    [OutputType([int])]
+    param()
+    return (Get-CimInstance Win32_Process -Filter "ProcessId=$PID").SessionId
+}
+
+function Get-ExplorerProcessesInSession {
+    [OutputType([object[]])]
+    param([Parameter(Mandatory)] [int] $TargetSessionId)
+    $allExplorers = Get-CimInstance Win32_Process -Filter "Name='explorer.exe'"
+    $matchingExplorers = @()
+    foreach ($eachExplorer in $allExplorers) {
+        if ($eachExplorer.SessionId -ne $TargetSessionId) { continue }
+        $ownerInfo = Invoke-CimMethod -InputObject $eachExplorer -MethodName GetOwner -ErrorAction SilentlyContinue
+        $matchingExplorers += [PSCustomObject]@{
+            ProcessId    = $eachExplorer.ProcessId
+            SessionId    = $eachExplorer.SessionId
+            OwnerUser    = if ($ownerInfo) { $ownerInfo.User } else { $null }
+            CreationDate = $eachExplorer.CreationDate
+        }
+    }
+    return ,$matchingExplorers
+}
+
+function Stop-LCoreIfRunning {
+    [OutputType([void])]
+    param()
+    $stopSettleMilliseconds = 500
+    Stop-Process -Name $script:LCoreProcessName -Force -ErrorAction SilentlyContinue
+    Start-Sleep -Milliseconds $stopSettleMilliseconds
+}
+
+function Invoke-ElevatedExplorerRebuild {
+    [OutputType([bool])]
+    param()
+    $elevatedScriptBlockText = @'
+Start-Service -Name LogiRegistryService -ErrorAction SilentlyContinue
+Stop-Process -Name explorer -Force -ErrorAction SilentlyContinue
+'@
+    $encodedElevatedCommand = [Convert]::ToBase64String([Text.Encoding]::Unicode.GetBytes($elevatedScriptBlockText))
+    try {
+        Start-Process -FilePath 'pwsh' `
+            -ArgumentList '-NoProfile', '-EncodedCommand', $encodedElevatedCommand `
+            -Verb RunAs `
+            -Wait `
+            -ErrorAction Stop
+        return $true
+    } catch {
+        Write-Warning "Elevated step did not run: $($_.Exception.Message)"
+        return $false
+    }
+}
+
+function Start-LCoreMinimized {
+    [OutputType([void])]
+    param()
+    $launchArguments = '/minimized'
+    Start-Process -FilePath $script:LCoreExecutablePath -ArgumentList $launchArguments
+}
+
+function Test-LCoreIsResponding {
+    [OutputType([bool])]
+    param([Parameter(Mandatory)] [int] $WaitSeconds)
+    Start-Sleep -Seconds $WaitSeconds
+    $lcoreProcesses = Get-Process -Name $script:LCoreProcessName -ErrorAction SilentlyContinue
+    if (-not $lcoreProcesses) { return $false }
+    foreach ($eachLCore in @($lcoreProcesses)) {
+        if (-not $eachLCore.Responding) { return $false }
+    }
+    return $true
+}
+
+function Write-StateSnapshot {
+    [OutputType([void])]
+    param([Parameter(Mandatory)] [string] $Label)
+    $logitechServiceNamesToVerify = @('LogiRegistryService', 'logi_lamparray_service')
+    Write-Host ""
+    Write-Host "=== $Label ==="
+    $sessionId = Get-CurrentInteractiveSessionId
+    $explorersInSession = Get-ExplorerProcessesInSession -TargetSessionId $sessionId
+    Write-Host "Explorer instances in session ${sessionId}: $($explorersInSession.Count)"
+    if ($explorersInSession.Count -gt 0) {
+        $explorersInSession | Format-Table ProcessId, OwnerUser, CreationDate -AutoSize | Out-String | Write-Host
+    }
+    $servicesObserved = Get-Service -Name $logitechServiceNamesToVerify -ErrorAction SilentlyContinue
+    if ($servicesObserved) {
+        $servicesObserved | Format-Table Name, Status -AutoSize | Out-String | Write-Host
+    }
+    $lcoreProcessesObserved = Get-Process -Name $script:LCoreProcessName -ErrorAction SilentlyContinue
+    if ($lcoreProcessesObserved) {
+        $lcoreProcessesObserved | Select-Object Id, Responding | Format-Table -AutoSize | Out-String | Write-Host
+    } else {
+        Write-Host "LCore not running."
+    }
+}
+
+function Invoke-LogifixRecovery {
+    [OutputType([void])]
+    param()
+
+    Write-StateSnapshot -Label 'Before'
+
+    if (-not (Test-Path -Path $script:LCoreExecutablePath)) {
+        Write-Error "LCore.exe not found at expected path: $script:LCoreExecutablePath"
+        return
+    }
+
+    Stop-LCoreIfRunning
+
+    $elevatedSucceeded = Invoke-ElevatedExplorerRebuild
+    if (-not $elevatedSucceeded) {
+        Write-Warning "UAC was canceled or the elevated step failed."
+        Write-Warning "Fallback: open Task Manager (Ctrl+Shift+Esc), find 'Windows Explorer', right-click, Restart. Then re-run /logifix."
+        return
+    }
+
+    Start-Sleep -Seconds $ExplorerAutoRespawnWaitSeconds
+
+    $sessionId = Get-CurrentInteractiveSessionId
+    $explorersAfterRespawn = Get-ExplorerProcessesInSession -TargetSessionId $sessionId
+    $explorerCountAfterRespawn = @($explorersAfterRespawn).Count
+    if ($explorerCountAfterRespawn -ne 1) {
+        if ($explorerCountAfterRespawn -eq 0) {
+            Write-Warning "No explorer.exe found in session $sessionId after $ExplorerAutoRespawnWaitSeconds-second wait."
+        } else {
+            Write-Warning "Expected exactly 1 explorer.exe in session $sessionId after shell auto-respawn, but found $explorerCountAfterRespawn."
+            Write-Warning "Multiple explorer.exe processes in the same session reproduce the Session 2 duplicate-explorer failure mode that blocks tray icon registration."
+            $explorersAfterRespawn | Format-Table ProcessId, OwnerUser, CreationDate -AutoSize | Out-String | Write-Host
+        }
+        Write-Warning "Restart Explorer manually via Task Manager (Ctrl+Shift+Esc, Windows Explorer, Restart), then re-run /logifix."
+        return
+    }
+
+    $lastAttemptResponded = $false
+    for ($attemptIndex = 1; $attemptIndex -le $LCoreRelaunchAttemptCount; $attemptIndex++) {
+        Stop-LCoreIfRunning
+        Start-LCoreMinimized
+        $lastAttemptResponded = Test-LCoreIsResponding -WaitSeconds $LCoreInitializationWaitSeconds
+        if ($lastAttemptResponded) {
+            Write-Host "LCore relaunch attempt ${attemptIndex}: process is responding."
+        } else {
+            Write-Warning "LCore relaunch attempt ${attemptIndex}: process not responding."
+        }
+    }
+
+    Write-StateSnapshot -Label 'After'
+
+    if (-not $lastAttemptResponded) {
+        Write-Warning "LCore did not respond after $LCoreRelaunchAttemptCount attempts."
+        Write-Warning "Use Task Manager to Restart Windows Explorer, then re-run /logifix."
+        return
+    }
+
+    Write-Host ""
+    Write-Host "Recovery complete ($LCoreRelaunchAttemptCount stop+launch cycles performed). If the tray icon is still not visible, use Task Manager to Restart Windows Explorer (guaranteed correct session/elevation), then re-run /logifix."
+}
+
+Invoke-LogifixRecovery

package/skills/rebase/SKILL.md

@@ -0,0 +1,164 @@
+---
+name: rebase
+description: Rebase a branch onto its base ref with the verification gates needed to catch logically broken results before pushing. Use when the user invokes `/rebase`, says "rebase this branch", "PR has merge conflicts", "rebase onto main", or asks for a force-push to update a remote branch's history. Critical for stacked PRs where the base merged via squash, and for any rebase that includes deletions or renames.
+---
+
+# /rebase
+
+Rebase the current branch (or a named branch's worktree) onto its correct base ref. Resolve conflicts. Verify the result is **logically correct**, not just textually clean. Push only after explicit authorization.
+
+The default failure mode is shipping a rebase that compiled but doesn't run. This skill exists to prevent that.
+
+## When to rebase vs. merge
+
+> **Decision thresholds**
+>
+> | Threshold | Value |
+> |---|---|
+> | Maximum commits for solo rebase | 5 |
+> | Divergence age that triggers merge-instead | 2 weeks |
+
+**Default to rebase** when:
+
+- Solo branch (you are the only author of the commits being rebased).
+- 1–5 commits ahead of base (see Decision thresholds above).
+- Stacked PR whose base just merged via squash.
+
+**Default to merge** when:
+
+- Branch has multiple authors (force-push would clobber their state).
+- More than 5 commits or more than 2 weeks of divergence (see Decision thresholds above; rebase complexity grows non-linearly).
+- The user said "merge", not "rebase".
+- Open PR with approving reviews already on the current SHA (force-push invalidates them).
+
+When in doubt, ask. Both work; the choice affects history shape, not correctness.
+
+## Phase 1 — Pre-rebase analysis
+
+1. **Resolve the canonical base.** Stacked-PR base refs change when the base PR merges. Always re-resolve:
+
+   ```
+   gh pr view <N> --json baseRefName,mergeable,mergeStateStatus
+   ```
+
+   Trust GitHub's `baseRefName`, not whatever the local branch was originally based on.
+
+2. **Identify the rebase scenario.** Three playbooks:
+
+   | Scenario | Signal | Approach |
+   |---|---|---|
+   | Stacked PR, base merged via squash | base PR `state: MERGED`, base ref redirected to main | Rebase onto main; expect to `--skip` the squash-absorbed commit |
+   | Stacked PR, base still open | base PR `state: OPEN` | Rebase onto base PR's tip, not main |
+   | Long-lived feature branch | many commits, no stacking | Straight `rebase origin/main` |
+
+3. **Fetch fresh.** `git fetch origin <base-ref> <head-ref>` before starting. Stale local refs cause false conflicts.
+
+4. **Read every rebased commit's message.** Author intent lives in commit messages ("removes orphan constants X, Y, Z"). For every named symbol mentioned as deleted or renamed, scan `origin/main` for new consumers — if main has new uses of those symbols, the rebase will produce broken state without conflicting at the textual level.
+
+   **Tool preference for symbol scans** (in order):
+
+   | Tool | Use when | Example |
+   |---|---|---|
+   | `mcp__serena__find_symbol` / `find_referencing_symbols` | Symbol-aware language server is available — definition vs. reference distinction matters, and you want call-site context | `find_referencing_symbols(symbol_name)` returns every caller with file/line and surrounding code |
+   | `mcp__zoekt__search_symbols` / `search` | Cross-repo or large codebase indexed in zoekt; faster than grep on big trees | `search(query)` returns ranked matches with snippets |
+   | `Grep` tool (ripgrep) | Local single-repo plain-text scan; no symbol awareness needed | `Grep(pattern, type="py")` — much faster than shell `grep` and respects `.gitignore` |
+   | `grep -rn` | Last resort; only when the above are unavailable | — |
+
+   The Grep tool is the default for plain-text scans (faster than shell grep, respects gitignore). Reach for serena when you need to distinguish "this name is defined here" from "this name is referenced here," which catches false positives from comments, docstrings, and string literals. Reach for zoekt for cross-repo scans.
+
+   This is the bug that hides best. Don't skip it.
+
+## Phase 2 — During rebase
+
+5. **`--skip` only after verifying content overlap.** When a commit fails to apply because main already has its content (squash-merge case), confirm the content is actually equivalent:
+
+   ```
+   git diff <skipped-commit> origin/<base> -- <files-touched-by-skipped-commit>
+   ```
+
+   Skip only after that diff shows the equivalent content lives in main. Don't skip on the heuristic "main is downstream."
+
+6. **Audit auto-merged files.** Files that git merged without conflict markers are not automatically correct. After each commit applies, run:
+
+   ```
+   git diff --name-only --diff-filter=M ORIG_HEAD
+   ```
+
+   Use `ORIG_HEAD`, which git sets at rebase start; the reflog index `HEAD@{1}` shifts as each rebase step runs and is unreliable mid-rebase. For each modified file with no conflict markers, eyeball the changes — auto-merge can produce duplicate blocks (when both sides added similar content) or silently drop content (when both sides removed adjacent lines). Pay extra attention to `config/`, `constants.*`, and `__init__.py` files where additions often sit near each other.
+
+7. **At every conflict, take both sides' intent seriously.** Read both, then decide based on the post-rebase logical state. Do not reflex-pick HEAD or `origin/main`. Document the resolution reasoning in the commit message if it is non-obvious.
+
+## Phase 3 — Verification gates (mandatory before push)
+
+`py_compile`, `tsc --noEmit`, `cargo check`, etc. validate **syntax and types**, not **import resolution and runtime correctness**. Run real checks:
+
+8. **Real import check.** For Python:
+
+   ```
+   python -m compileall -q <package>
+   ```
+
+   Follow immediately with the test-collection step below. `compileall` catches import-time failures across every module file; combined with `--collect-only` it surfaces `NameError`, `AttributeError`, and `ImportError` cases that a syntax-only check misses.
+
+9. **Test collection.** `pytest --collect-only -q` on the changed packages catches NameError, AttributeError, and ImportError surfaces beyond plain imports.
+
+10. **Targeted test run.** Run the test suite for every package the rebase touched. Do not push a rebase that dropped or broke test coverage that was passing pre-rebase.
+
+11. **Reference scan for removals/renames.** For every symbol the rebase deleted or renamed (per the commit messages from step 4), scan the post-rebase tree using the same tool-preference order as step 4:
+
+    - **Preferred:** `mcp__serena__find_referencing_symbols` (symbol-aware; ignores false matches in comments and string literals).
+    - **Fallback:** `mcp__zoekt__search` for cross-repo or large trees.
+    - **Then:** the `Grep` tool (e.g., `Grep(pattern="<symbol>", type="py")`) for fast in-repo scans.
+    - **Last resort:** `grep -rn "<symbol>" .` (let ripgrep defaults and `.gitignore` handle scoping)
+
+    Any reference outside the rebased commits' own changes is a stale reference. Either update it (with user authorization) or surface it and refuse to push.
+
+12. **"Unchanged" files are not safe.** A rebase can break files it never textually modified if their imports depend on something the rebase removed or renamed. List `git diff --name-only origin/<base>..HEAD`, then for every file NOT in that list but that imports from a file IN that list, manually verify the imports still resolve.
+
+## Phase 4 — Push
+
+13. **Force-push requires explicit authorization.** Auto mode does not bypass this. Before any `git push --force` or `--force-with-lease`:
+
+    - State the rewrite scope: "this rewrites N commits of remote history on branch `<name>`".
+    - State the branch's PR state: "PR #M is OPEN with K approving reviews on the current SHA" (force-push invalidates approvals).
+    - Ask for explicit authorization.
+    - If denied: leave the rebase result locally, report merge-instead as the alternative, stop.
+
+14. **Refuse to force-push** `main`, `master`, `release/*`, `production`, or any branch with more than one unique author. Count unique authors in a cross-platform way: `git log --format='%ae' origin/<branch> | python -c "import sys; print(len(set(sys.stdin)))"`. This form works on both Windows (PowerShell) and Unix without shell pipeline extensions. Surface the refusal; do not ask for authorization on these.
+
+15. **Always `--force-with-lease=<branch>:<sha>`**, never bare `--force`. Pin the lease to the SHA you started from so concurrent pushes are detected as a lease mismatch instead of clobbered.
+
+16. **Confirm mergeability** post-push:
+
+    ```
+    gh pr view <N> --json mergeable,mergeStateStatus,headRefOid
+    ```
+
+    Expect `mergeable: MERGEABLE`, `mergeStateStatus: CLEAN`. Anything else means the rebase didn't actually unblock the PR — investigate before declaring done.
+
+## Anti-patterns (the failure modes this skill prevents)
+
+- **`py_compile` exit 0 → "verified"**. Wrong. Syntax-clean is not import-clean. Always run a real `import` check.
+- **Skipping squash-absorbed commits without diff verification.** Heuristically usually right, occasionally wrong, never confirmed without the diff.
+- **Auditing only `git diff --name-only`.** Files unchanged by the rebase can still break if their imports depended on what the rebase removed.
+- **Force-pushing under "the user asked me to fix the conflicts" interpretation.** Force-push is a separate authorization from "fix this." Ask.
+- **Bare `--force` instead of `--force-with-lease=<branch>:<sha>`.** Loses the safety net against concurrent pushes.
+
+## Quick decision flowchart
+
+```
+Branch shared with others?  ──► merge instead
+Stacked PR, base merged?    ──► rebase onto main, expect --skip
+Stacked PR, base open?      ──► rebase onto base PR tip
+Solo, ≤5 commits ahead?     ──► straight rebase
+
+After rebase, BEFORE push:
+  python -c "import …"      ──► must succeed
+  pytest --collect-only     ──► must succeed
+  targeted pytest run       ──► must pass
+  symbol scan (serena → zoekt → Grep) ──► no stale references
+
+Push:
+  not main/master/release   ──► force-with-lease, ask first
+  main/master/release       ──► refuse
+```