claude-dev-env 1.93.1 → 1.95.0

package/rules/CLAUDE.md

@@ -12,6 +12,7 @@ Rule files installed into `~/.claude/rules/` by `bin/install.mjs`. Claude Code l
 | File | Rule |
 |---|---|
 | `agent-spawn-protocol.md` | Protocol for spawning subagents: context sufficiency check, prompt generation via `/prompt-generator`, then spawn |
+| `anti-corollary-tests.md` | Tests must carry information: no corollary matrices over canonical reductions, no suite that only matches a dead-implementation default, stated mutation in the audit lane |
 | `ask-user-question-required.md` | Every user-directed question goes through the `AskUserQuestion` tool — no plain-text questions |
 | `bdd.md` | BDD discovery-driven development workflow and Example Mapping reference |
 | `claude-md-orphan-file.md` | Every backticked bare filename in a per-directory `CLAUDE.md` table's first column names a file in that directory's subtree |

package/rules/anti-corollary-tests.md

@@ -0,0 +1,69 @@
+---
+paths:
+  - "**/test_*.py"
+  - "**/*_test.py"
+  - "**/*.test.*"
+  - "**/*.spec.*"
+  - "**/conftest.py"
+  - "**/tests/**"
+---
+
+# Anti-Corollary Tests
+
+**When this applies:** Any Write or Edit that adds or changes tests.
+
+## Rule
+
+A large green suite can prove almost nothing. Before you keep a case, answer three questions. If any answer fails, cut the case or replace it with one that carries information.
+
+## The three questions
+
+### 1. Is this a corollary?
+
+When the code reduces each input to a canonical form and then compares the forms, every pairwise combination of input spellings follows once the reduction is proven canonical. Walking the full N×N matrix restates that fact. It adds cases and runtime, and it buries the few cases that carry information.
+
+**Do this:** test the reduction once. Test the comparison with a few discriminating cases. Do not walk the cross product of spellings.
+
+### 2. Could this test pass if the mechanism were dead?
+
+Name the degenerate value a dead implementation would return — empty string, `None`, `False`, a blanket refusal, an empty collection. When the test's expected value equals that default, the test passes whether the mechanism works or not. On its own it proves nothing.
+
+**Do this:** keep at least one case that expects the **non-default** answer, and drive the real code path — not a mock that only records that a call happened.
+
+### 3. What single change to the code would make this test fail?
+
+When the honest answer is "none," or "only a change that also breaks everything else," the test is decoration. Drop it or rewrite it so one named mutation kills it.
+
+## What a mechanism with a degenerate failure mode needs
+
+1. **At least one non-default case** that exercises the live path and expects the non-default answer.
+2. **A stated mutation (audit lane):** name one specific change to the code and record how many tests it kills. A mutation that kills zero tests means the suite proves nothing. A reviewer or an audit skill checks this; a hook does not compute it.
+3. **A few discriminating cases** in place of a large matrix.
+
+## Worked shape (sanitized)
+
+A write guard decides whether a write is about to hit a production database. It reduces each database URL to a canonical endpoint identity, then compares identities.
+
+Two independent mutations show the two halves of a useful suite:
+
+- Gut the reduction so it always returns the empty string: the guard fails **closed** and refuses everything. Only the *allow*-expecting cases die.
+- Abandon the reduction and compare raw hostnames: the guard fails **open** and allows a production write. Only the *refuse*-expecting cases die.
+
+Opposite breaks kill opposite halves. A suite with only one half cannot see one of those breaks. Build both halves; skip the spelling matrix once the reduction is covered.
+
+## What this is not
+
+A structural hook is the wrong tool here. "Is this a corollary?" and "would this pass against a dead implementation?" need the intent of the code under test. A hook that pattern-matches `parametrize` breadth or counts assertions fires on correct suites and trains people to ignore it. A false-positive gate on a judgment call is worse than no gate. This rule stays judgment-only, with the stated-mutation check in the audit lane — the same pattern as other judgment rules in this package that have no Write/Edit blocker.
+
+## Sibling rules
+
+| Rule | Role |
+|---|---|
+| `tdd.md` | Write a failing test before production code |
+| `testing.md` | Mocks and test infrastructure standards |
+| `paired-test-coverage.md` | Every public function in an established suite gets a behavioral test |
+| `anti-corollary-tests.md` | Each test carries information; no corollary matrices; no suite that only matches the dead default |
+
+## Enforcement
+
+The AI review lane and audit skills carry this rule: an agent applies it to the test lines a PR changes. No blocking hook backs it, because corollary and dead-default judgments need meaning a regex cannot read.

package/rules/bdd.md

@@ -2,8 +2,6 @@
 
 **Canonical detail:** `~/.claude/system-prompts/software-engineer.xml` → `<behavior_protocol>`.
 
-**On-demand depth:** `@~/.claude/skills/bdd-protocol/SKILL.md` (Example Mapping §6.4, §7.6 catalog, solo patterns). Tracking design: [jl-cmd/claude-dev-env#82](https://github.com/jl-cmd/claude-dev-env/issues/82).
-
 **Optional long-form references (load when needed):**
 
 - `@~/.claude/docs/BDD_SCENARIO_QUALITY.md` — seven scenario quality patterns (§7.6-style)
@@ -21,7 +19,7 @@ Conversation is the essential practice: if discovery is skipped, structured form
 
 ## Solo developer
 
-You are often the stakeholder. Use **Example Mapping** in chat ("the one where …", probes, parking lot). Load **`bdd-protocol`** when you need the full algorithm and anti-pattern list.
+You are often the stakeholder. Use **Example Mapping** in chat ("the one where …", probes, parking lot). See the optional long-form references above for the full algorithm and anti-pattern list.
 
 ## Naming
 

package/rules/code-reviews.md

@@ -2,7 +2,7 @@
 
 **When this applies:** GitHub PR review feedback on a branch you are fixing.
 
-**MANDATORY PROTOCOL (use pr-review-responder skill):**
+**MANDATORY PROTOCOL:**
 
 1. Fetch ALL reviewer comments BEFORE any fixes
 2. Create TodoWrite checklist - One item per comment

package/rules/gh-paginate.md

@@ -1,3 +1,3 @@
 # gh API Pagination
 
-Every `gh api` read of a paginated GitHub list endpoint (PR `reviews`/`comments`/`files`, issue `comments`, `pulls`, `issues`) uses `--paginate --slurp` piped to **external** `jq` — `gh`'s built-in `--jq` runs per page, so cross-page operations like `sort_by | last` give wrong-but-confident results. Single-object endpoints (`pulls/<n>`, `issues/<n>`) skip pagination and may use `--jq` directly. Full safe patterns (single-page bounds, newest-first walks): gh-paginate skill.
+Every `gh api` read of a paginated GitHub list endpoint (PR `reviews`/`comments`/`files`, issue `comments`, `pulls`, `issues`) uses `--paginate --slurp` piped to **external** `jq` — `gh`'s built-in `--jq` runs per page, so cross-page operations like `sort_by | last` give wrong-but-confident results. Single-object endpoints (`pulls/<n>`, `issues/<n>`) skip pagination and may use `--jq` directly. For a newest-first walk, sort the slurped array and take the last element; for single-page bounds, cap with a `per_page` query parameter.

package/rules/plain-language.md

@@ -3,3 +3,5 @@
 All prose a person reads (chat, `AskUserQuestion`, docs, PR/issue bodies, commits): everyday words, short active sentences, lead with the answer, define jargon on first use, and give only the detail the reader needs to act (progressive disclosure). Aim for first-pass readability by a non-specialist. Exact identifiers, file paths, and API names stay exact; code is out of scope.
 
 The `plain_language_blocker` PreToolUse hook (AskUserQuestion + `.md` Write/Edit/MultiEdit) blocks a heavy word and names the everyday swap; code fences, inline code, blockquotes, URLs, and file paths are skipped.
+
+A project can keep its own domain words out of the check with a `.claude/plain-language-allow.json` file: a JSON array of terms. An exact, case-insensitive, whole-word match on any term passes. The hook reads this file only from inside the project tree, up to the repository root, so each project's allowlist stays with its own code.

package/scripts/CLAUDE.md

@@ -21,6 +21,7 @@ Utility scripts installed into `~/.claude/scripts/` by `bin/install.mjs`. Each s
 | `Install-SweepEmptyDirs.ps1` | Registers `sweep_empty_dirs.py` as a scheduled task on Windows |
 | `check.ps1` | Runs the full code-quality check suite |
 | `Show-Asset.ps1` | Opens files on screen, sizing each image window to the image's pixel dimensions (scaled to fit the screen); non-image files open in their default application |
+| `Get-SessionAccount.ps1` | Reports which Claude account the current session is actually logged into by comparing `~/.claude.json`'s CLI login against a `CLAUDE_USER_DATA_DIR` desktop profile's `lastKnownAccountUuid`, recovering the desktop account's email from profile storage when the two accounts differ |
 
 ## Subdirectories
 
@@ -28,10 +29,18 @@ Utility scripts installed into `~/.claude/scripts/` by `bin/install.mjs`. Each s
 |---|---|
 | `dev_env_scripts_constants/` | Named constants (`timing.py`) for scripts in this directory |
 | `sync_to_cursor/` | Package that builds Cursor `.mdc` files from Claude rules and docs |
-| `tests/` | pytest suite for the Python scripts in this directory |
+| `tests/` | pytest suite for the Python scripts and Pester (`*.Tests.ps1`) suite for the PowerShell scripts in this directory |
 
 ## Running tests
 
+Python scripts (pytest):
+
 ```bash
 python -m pytest packages/claude-dev-env/scripts/tests/
 ```
+
+PowerShell scripts (Pester 5+, `*.Tests.ps1`):
+
+```powershell
+Invoke-Pester -Path packages/claude-dev-env/scripts/tests/
+```

package/scripts/Get-SessionAccount.ps1

@@ -0,0 +1,210 @@
+#!/usr/bin/env pwsh
+[CmdletBinding()]
+param(
+    [switch]$AsJson
+)
+
+$noiseEmailPatterns = @(
+    '@example\.(com|org|net)$',
+    '(@|\.)sentry\.io$',
+    '@anthropic\.',
+    '^Claude@\d'
+)
+
+$isoLatin1CodePage = 28591
+
+$profileStorageDirectoryNames = @('sentry', 'IndexedDB', 'Session Storage', 'WebStorage')
+
+$emailAddressPattern = '(?<![a-zA-Z0-9._%+-])[a-zA-Z0-9][a-zA-Z0-9._%+-]*@[a-zA-Z0-9-]+(\.[a-zA-Z0-9-]+)+(?![a-zA-Z0-9-])'
+
+$maximumStorageFileBytes = 50MB
+
+function Test-NoiseEmail {
+    param([string]$Email)
+    foreach ($pattern in $noiseEmailPatterns) {
+        if ($Email -imatch $pattern) { return $true }
+    }
+    return $false
+}
+
+function Get-EncodingAgnosticTextView {
+    param([string]$FilePath)
+    try {
+        $fileBytes = [System.IO.File]::ReadAllBytes($FilePath)
+        if ($fileBytes.Length -eq 0) { return @() }
+        $isoLatin1Encoding = [System.Text.Encoding]::GetEncoding($isoLatin1CodePage)
+        return @(
+            $isoLatin1Encoding.GetString($fileBytes),
+            [System.Text.Encoding]::Unicode.GetString($fileBytes)
+        )
+    }
+    catch {
+        return @()
+    }
+}
+
+function Get-EmailCandidatesFromProfile {
+    param(
+        [string]$ProfileDirectory,
+        [string]$ExcludeEmail
+    )
+    $scanDirectories = $profileStorageDirectoryNames |
+        ForEach-Object { Join-Path $ProfileDirectory $_ } |
+        Where-Object { Test-Path -LiteralPath $_ }
+    $foundEmails = [System.Collections.Generic.HashSet[string]]::new([System.StringComparer]::OrdinalIgnoreCase)
+
+    foreach ($scanDirectory in $scanDirectories) {
+        $candidateFiles = Get-ChildItem -LiteralPath $scanDirectory -Recurse -File -ErrorAction SilentlyContinue |
+            Where-Object { $_.Length -lt $maximumStorageFileBytes }
+        foreach ($candidateFile in $candidateFiles) {
+            $decodedTextViews = Get-EncodingAgnosticTextView -FilePath $candidateFile.FullName
+            foreach ($decodedText in $decodedTextViews) {
+                foreach ($match in [regex]::Matches($decodedText, $emailAddressPattern)) {
+                    $candidateEmail = $match.Value
+                    $isKnownCliEmail = $ExcludeEmail -and ($candidateEmail -ieq $ExcludeEmail)
+                    if (-not (Test-NoiseEmail -Email $candidateEmail) -and -not $isKnownCliEmail) {
+                        [void]$foundEmails.Add($candidateEmail)
+                    }
+                }
+            }
+        }
+    }
+    return $foundEmails
+}
+
+function Write-AccountResult {
+    param(
+        [string]$Email,
+        [string]$AccountUuid,
+        [string]$Source,
+        [string]$CliEmail,
+        [string]$CliAccountUuid,
+        [switch]$AsJson
+    )
+    if ($AsJson) {
+        [pscustomobject]@{
+            account        = $Email
+            accountUuid    = $AccountUuid
+            source         = $Source
+            cliAccount     = $CliEmail
+            cliAccountUuid = $CliAccountUuid
+        } | ConvertTo-Json
+        return
+    }
+    Write-Output "Account: $Email"
+    Write-Output "AccountUuid: $AccountUuid"
+    Write-Output "Source: $Source"
+    if ($CliEmail) {
+        Write-Output "CliAccount: $CliEmail"
+        Write-Output "CliAccountUuid: $CliAccountUuid"
+    }
+}
+
+function Get-SessionAccountResult {
+    param(
+        [int]$ExitCode,
+        [string]$Email = $null,
+        [string]$AccountUuid = $null,
+        [string]$Source = $null,
+        [string]$CliEmail = $null,
+        [string]$CliAccountUuid = $null,
+        [string]$ErrorMessage = $null
+    )
+    [pscustomobject]@{
+        ExitCode       = $ExitCode
+        Email          = $Email
+        AccountUuid    = $AccountUuid
+        Source         = $Source
+        CliEmail       = $CliEmail
+        CliAccountUuid = $CliAccountUuid
+        ErrorMessage   = $ErrorMessage
+    }
+}
+
+function Resolve-SessionAccount {
+    param(
+        [string]$CliConfigPath,
+        [string]$ProfileDirectory
+    )
+    if (-not (Test-Path -LiteralPath $CliConfigPath)) {
+        return Get-SessionAccountResult -ExitCode 2 -ErrorMessage "CLI config not found: $CliConfigPath"
+    }
+
+    try {
+        $cliConfig = Get-Content -LiteralPath $CliConfigPath -Raw -ErrorAction Stop | ConvertFrom-Json -AsHashtable -ErrorAction Stop
+    }
+    catch {
+        return Get-SessionAccountResult -ExitCode 2 -ErrorMessage "Failed to parse CLI config as JSON: $CliConfigPath"
+    }
+
+    if ($cliConfig -isnot [System.Collections.IDictionary]) {
+        return Get-SessionAccountResult -ExitCode 2 -ErrorMessage "CLI config top level is not a JSON object: $CliConfigPath"
+    }
+
+    $oauthAccount = $cliConfig['oauthAccount']
+    $cliEmail = if ($oauthAccount) { $oauthAccount['emailAddress'] } else { $null }
+    $cliAccountUuid = if ($oauthAccount) { $oauthAccount['accountUuid'] } else { $null }
+    if (-not $cliEmail -or -not $cliAccountUuid) {
+        return Get-SessionAccountResult -ExitCode 2 -ErrorMessage "CLI config is missing oauthAccount.emailAddress or oauthAccount.accountUuid: $CliConfigPath"
+    }
+
+    if (-not $ProfileDirectory -or -not (Test-Path -LiteralPath $ProfileDirectory)) {
+        return Get-SessionAccountResult -ExitCode 0 -Email $cliEmail -AccountUuid $cliAccountUuid -Source 'cli-config'
+    }
+
+    $profileConfigPath = Join-Path $ProfileDirectory 'config.json'
+    if (-not (Test-Path -LiteralPath $profileConfigPath)) {
+        return Get-SessionAccountResult -ExitCode 2 -ErrorMessage "Desktop profile config not found: $profileConfigPath"
+    }
+
+    try {
+        $profileConfig = Get-Content -LiteralPath $profileConfigPath -Raw -ErrorAction Stop | ConvertFrom-Json -AsHashtable -ErrorAction Stop
+    }
+    catch {
+        return Get-SessionAccountResult -ExitCode 2 -ErrorMessage "Failed to parse desktop profile config as JSON: $profileConfigPath"
+    }
+
+    if ($profileConfig -isnot [System.Collections.IDictionary]) {
+        return Get-SessionAccountResult -ExitCode 2 -ErrorMessage "Desktop profile config top level is not a JSON object: $profileConfigPath"
+    }
+
+    $profileAccountUuid = $profileConfig['lastKnownAccountUuid']
+    if (-not $profileAccountUuid) {
+        return Get-SessionAccountResult -ExitCode 2 -ErrorMessage "Desktop profile config is missing lastKnownAccountUuid: $profileConfigPath"
+    }
+
+    if ($profileAccountUuid -eq $cliAccountUuid) {
+        return Get-SessionAccountResult -ExitCode 0 -Email $cliEmail -AccountUuid $cliAccountUuid -Source 'desktop-profile (matches cli-config)'
+    }
+
+    $candidateEmails = @(Get-EmailCandidatesFromProfile -ProfileDirectory $ProfileDirectory -ExcludeEmail $cliEmail)
+    if ($candidateEmails.Count -eq 1) {
+        return Get-SessionAccountResult -ExitCode 0 -Email $candidateEmails[0] -AccountUuid $profileAccountUuid -Source 'desktop-profile (differs from cli-config)' -CliEmail $cliEmail -CliAccountUuid $cliAccountUuid
+    }
+
+    if ($candidateEmails.Count -eq 0) {
+        return Get-SessionAccountResult -ExitCode 1 -ErrorMessage "Desktop profile account ($profileAccountUuid) differs from CLI config, but no candidate email was recovered from profile storage: $ProfileDirectory"
+    }
+
+    return Get-SessionAccountResult -ExitCode 1 -ErrorMessage "Desktop profile account ($profileAccountUuid) differs from CLI config, and multiple candidate emails were found in profile storage: $($candidateEmails -join ', ')"
+}
+
+function Invoke-GetSessionAccount {
+    param(
+        [switch]$AsJson
+    )
+    $cliConfigPath = Join-Path $HOME '.claude.json'
+    $sessionAccount = Resolve-SessionAccount -CliConfigPath $cliConfigPath -ProfileDirectory $env:CLAUDE_USER_DATA_DIR
+    if ($sessionAccount.ErrorMessage) {
+        Write-Error $sessionAccount.ErrorMessage -ErrorAction Continue
+        exit $sessionAccount.ExitCode
+    }
+    Write-AccountResult -Email $sessionAccount.Email -AccountUuid $sessionAccount.AccountUuid -Source $sessionAccount.Source -CliEmail $sessionAccount.CliEmail -CliAccountUuid $sessionAccount.CliAccountUuid -AsJson:$AsJson
+    exit $sessionAccount.ExitCode
+}
+
+if ($MyInvocation.InvocationName -ne '.') {
+    Set-StrictMode -Version Latest
+    $ErrorActionPreference = 'Stop'
+    Invoke-GetSessionAccount -AsJson:$AsJson
+}

package/scripts/tests/CLAUDE.md

@@ -1,6 +1,6 @@
 # scripts/tests
 
-pytest suite for the Python scripts in `scripts/`.
+pytest suite for the Python scripts and Pester suite for the PowerShell scripts in `scripts/`.
 
 ## Test files
 
@@ -11,8 +11,22 @@ pytest suite for the Python scripts in `scripts/`.
 | `test_sweep_empty_dirs.py` | `sweep_empty_dirs.py` — age check, one-shot mode, and continuous-watch behavior |
 | `test_sync_to_cursor.py` | `sync_to_cursor/` package — mapping, hashing, manifest, and path resolution |
 
+## PowerShell test files
+
+| File | Covers |
+|---|---|
+| `Get-SessionAccount.Tests.ps1` | `Get-SessionAccount.ps1` — noise filtering, profile-storage email recovery, CLI-vs-desktop account resolution, and output formatting |
+
 ## Running
 
+Python scripts (pytest):
+
 ```bash
 python -m pytest packages/claude-dev-env/scripts/tests/
 ```
+
+PowerShell scripts (Pester 5+, `*.Tests.ps1`):
+
+```powershell
+Invoke-Pester -Path packages/claude-dev-env/scripts/tests/
+```