<!-- markdownlint-disable MD024 -->

# User Stories: Rigor Global Configuration

## US-RGC-01: Global Config Resolution in DESConfig

### Problem

Ale Donnarumma works across 5 projects simultaneously (nWave-dev, nwave-ai, client-A, client-B, personal-tools) and uses a custom rigor profile (opus agent, sonnet reviewer, double review, full TDD, no mutation). He finds it tedious to run `/nw:rigor custom` in every new project and configure the same 6 settings each time. His workaround is manually copying des-config.json between projects, which is error-prone and easy to forget.

### Who

- Multi-project developer | Works across 3-5 repos daily | Wants a single rigor preference that follows them

### Solution

DESConfig cascades config resolution: project `.nwave/des-config.json` rigor block (if present) takes full precedence; otherwise, fall through to `~/.nwave/global-config.json` rigor block; otherwise, use hardcoded standard defaults.

### Domain Examples

#### 1: Ale opens a fresh project with no rigor configured

Ale Donnarumma clones a new repo `client-C` and runs `nwave-ai install`. The installer creates `.nwave/des-config.json` with audit/update-check settings but no `rigor` key. Ale runs `/nw:deliver "add health check endpoint"`. DESConfig finds no rigor key in `.nwave/des-config.json`, loads `~/.nwave/global-config.json`, finds rigor.profile = "custom" with opus/sonnet/double-review, and applies those settings. Ale never ran `/nw:rigor` in this project.

#### 2: Project rigor overrides global

Ale has global rigor set to custom (opus). In `nwave-ai` (the public package), he has explicitly set rigor to "lean" via `/nw:rigor lean` because changes there are mostly documentation. When Ale runs `/nw:deliver` in nwave-ai, DESConfig finds rigor.profile = "lean" in the project config and uses it entirely. The global opus config is never consulted.

#### 3: No global config exists, no project rigor key

Tomasz Kowalski (a new nWave user) has never run `/nw:rigor` anywhere. His `~/.nwave/global-config.json` does not exist. His project `.nwave/des-config.json` has no rigor key. DESConfig falls through both levels and returns standard defaults: sonnet agent, haiku reviewer, full 5-phase TDD, single review.

### UAT Scenarios (BDD)

#### Scenario 1: Project rigor present -- use project, ignore global

Given Ale has global rigor set to profile "custom" with agent_model "opus" in ~/.nwave/global-config.json
And project .nwave/des-config.json contains rigor with profile "lean" and agent_model "haiku"
When DESConfig loads rigor configuration
Then rigor_profile returns "lean"
And rigor_agent_model returns "haiku"
And ~/.nwave/global-config.json is not read for rigor

#### Scenario 2: No project rigor -- cascade to global

Given project .nwave/des-config.json exists but has no "rigor" key
And ~/.nwave/global-config.json contains rigor with profile "custom" and agent_model "opus"
When DESConfig loads rigor configuration
Then rigor_profile returns "custom"
And rigor_agent_model returns "opus"

#### Scenario 3: No project rigor, no global config file -- use defaults

Given project .nwave/des-config.json exists but has no "rigor" key
And ~/.nwave/global-config.json does not exist
When DESConfig loads rigor configuration
Then rigor_profile returns "standard"
And rigor_agent_model returns "sonnet"
And rigor_reviewer_model returns "haiku"
And rigor_tdd_phases returns the full 5-phase tuple

#### Scenario 4: No project rigor, global config exists but has no rigor key -- use defaults

Given project .nwave/des-config.json exists but has no "rigor" key
And ~/.nwave/global-config.json exists but has no "rigor" key
When DESConfig loads rigor configuration
Then rigor_profile returns "standard"
And rigor_agent_model returns "sonnet"

#### Scenario 5: Global config file is corrupted JSON -- use defaults

Given project .nwave/des-config.json exists but has no "rigor" key
And ~/.nwave/global-config.json contains invalid JSON
When DESConfig loads rigor configuration
Then rigor_profile returns "standard"
And DESConfig does not raise an exception

### Acceptance Criteria

- [ ] DESConfig checks project rigor first; if present, returns project values without reading global
- [ ] DESConfig cascades to `~/.nwave/global-config.json` only when project config has no `rigor` key
- [ ] DESConfig falls back to hardcoded standard defaults when both project and global lack rigor
- [ ] Corrupted or missing global config file is handled silently (no crash, no user-visible error)
- [ ] Resolution is full-block: if project has `rigor` key, ALL global rigor fields are ignored (no per-field merge)

### Outcome KPIs

- **Who**: Multi-project nWave users
- **Does what**: Stop running `/nw:rigor` in every new project
- **By how much**: Zero manual rigor configuration for projects using the global default
- **Measured by**: Number of `/nw:rigor` invocations per user per week (expect reduction)
- **Baseline**: 1 invocation per new project (currently)

### Technical Notes

- DESConfig constructor currently accepts `config_path` or resolves from `cwd`. Add optional `global_config_path` parameter (default: `Path.home() / ".nwave" / "global-config.json"`)
- Global config loading uses the same `_load_configuration` pattern (JSON parse with fallback to empty dict)
- The `_rigor()` private method is the single point to modify: check project first, then global
- No env var override for rigor resolution (per ADR-001)
- Existing `rigor_*` properties remain unchanged -- they call `_rigor()` which now cascades

---

## US-RGC-02: Scope Selection in /nw:rigor Command

### Problem

Ale Donnarumma runs `/nw:rigor` to set his custom profile. Today, the profile always saves to `.nwave/des-config.json` (project-level). When Ale wants the same profile across all projects, he has no way to save it globally. He must re-run `/nw:rigor custom` and answer 6 questions in every new project, which takes about 2 minutes of repetitive interaction each time.

### Who

- Multi-project developer | Sets rigor once for personal preference | Wants that preference to persist across all projects

### Solution

Add a scope selection question at the start of `/nw:rigor`: "Save globally or for this project only?" When global is selected, write the rigor block to `~/.nwave/global-config.json` instead of `.nwave/des-config.json`.

### Domain Examples

#### 1: Ale saves custom profile globally

Ale runs `/nw:rigor` in nWave-dev. The command shows his current project profile ("custom") and current global profile ("none set"). It asks "Save globally or for this project?" Ale selects "Globally". He picks "custom", configures opus/sonnet/double-review, confirms. The rigor block is written to `~/.nwave/global-config.json`. The project's des-config.json is not modified. Summary shows "Scope: global".

#### 2: Priya overrides global with project-specific lean

Priya Sharma has a global profile of "standard". In her documentation-only repo `docs-site`, she runs `/nw:rigor lean`. The scope question appears. She selects "This project only". The lean profile is written to `docs-site/.nwave/des-config.json`. Her global "standard" is untouched. Summary shows "Scope: project (overrides global)".

#### 3: Quick switch respects scope

Ale runs `/nw:rigor lean` (quick switch with argument). Since he is switching quickly, the command asks scope: "Save globally or for this project?" Ale picks "Globally". The lean profile replaces his previous global custom profile.

### UAT Scenarios (BDD)

#### Scenario 1: Scope question appears before profile selection

Given Ale runs /nw:rigor in a project with des-config.json present
When the command starts
Then the command displays current project profile and current global profile
And asks "Where do you want to save this configuration?" with options "Globally" and "This project only"

#### Scenario 2: Global scope writes to ~/.nwave/global-config.json

Given Ale selects scope "Globally"
And Ale selects profile "custom" with agent_model "opus" and reviewer_model "sonnet"
When Ale confirms the profile
Then ~/.nwave/global-config.json contains rigor.profile = "custom" and rigor.agent_model = "opus"
And project .nwave/des-config.json rigor key is unchanged (or absent)
And the summary displays "Scope: global (~/.nwave/global-config.json)"

#### Scenario 3: Project scope writes to .nwave/des-config.json

Given Priya selects scope "This project only"
And Priya selects profile "lean"
When Priya confirms the profile
Then .nwave/des-config.json contains rigor.profile = "lean"
And ~/.nwave/global-config.json is not modified
And the summary displays "Scope: project (.nwave/des-config.json)"

#### Scenario 4: Quick switch also asks scope

Given Ale runs /nw:rigor lean (with argument)
When the command starts
Then the command asks scope before showing the diff
And Ale can select "Globally" or "This project only"

#### Scenario 5: Global config directory created if missing

Given ~/.nwave/ directory does not exist
When Ale selects scope "Globally" and confirms a profile
Then ~/.nwave/ directory is created
And ~/.nwave/global-config.json is created with the rigor block

### Acceptance Criteria

- [ ] `/nw:rigor` displays current project profile AND current global profile at startup
- [ ] Scope question ("Globally" vs "This project only") appears before profile selection in all modes (interactive, quick switch, custom)
- [ ] Selecting "Globally" writes rigor block to `~/.nwave/global-config.json` using read-modify-write
- [ ] Selecting "This project only" writes to `.nwave/des-config.json` (existing behavior)
- [ ] `~/.nwave/` directory is created automatically if it does not exist when saving globally
- [ ] Summary output includes the scope and file path

### Outcome KPIs

- **Who**: Multi-project nWave users
- **Does what**: Save rigor profile to global scope
- **By how much**: 100% of global-scope saves persist across projects without re-configuration
- **Measured by**: Presence of `~/.nwave/global-config.json` with rigor key after `/nw:rigor` global save
- **Baseline**: Not possible today (no global save option)

### Technical Notes

- `/nw:rigor` is a markdown command file (`nWave/tasks/nw/rigor.md`) -- the main Claude instance executes it
- The scope question uses AskUserQuestion with 2 options
- Global config uses same read-modify-write pattern as project config (preserve other keys)
- The `~/.nwave/` directory is NOT created by the installer -- only by `/nw:rigor` when user explicitly saves globally
- Dependency: US-RGC-01 (DESConfig must be able to read global config for the "current global profile" display)

---

## US-RGC-03: Global Config Handling During Uninstall

### Problem

Ale Donnarumma has been using nWave with a carefully tuned global rigor profile in `~/.nwave/global-config.json`. He needs to uninstall and reinstall nWave (e.g., after a major version upgrade). If the uninstaller silently deletes `~/.nwave/`, Ale loses his global config and must reconfigure rigor from scratch. If the uninstaller silently keeps it, Ale might have stale config after a breaking change.

### Who

- Existing nWave user | Has global config with personal preferences | Needs control over what happens during uninstall

### Solution

The `nwave-ai uninstall` command checks for `~/.nwave/global-config.json`. If found, it prompts the user to keep or delete the global config before proceeding with uninstallation.

### Domain Examples

#### 1: Ale keeps global config during reinstall

Ale runs `nwave-ai uninstall` to upgrade. The uninstaller detects `~/.nwave/global-config.json` and asks: "Keep global config for future installations?" Ale selects "Keep". The uninstaller removes project-level `.nwave/` artifacts and Claude Code hooks but leaves `~/.nwave/global-config.json` untouched. After reinstalling, Ale's rigor profile is already active.

#### 2: Tomasz deletes everything on full uninstall

Tomasz Kowalski is removing nWave entirely. The uninstaller detects `~/.nwave/global-config.json` and asks about it. Tomasz selects "Delete". The global config file is removed. If `~/.nwave/` is now empty, the directory is also removed.

#### 3: No global config exists -- no prompt

Priya Sharma never set a global config. She runs `nwave-ai uninstall`. The uninstaller does not find `~/.nwave/global-config.json` and skips the prompt entirely. Uninstall proceeds normally.

### UAT Scenarios (BDD)

#### Scenario 1: Global config found -- prompt to keep or delete

Given ~/.nwave/global-config.json exists with rigor configuration
When Ale runs nwave-ai uninstall
Then the uninstaller displays "Global configuration found at ~/.nwave/global-config.json"
And asks "Keep global config (for future installations)?" with options "Keep" and "Delete"

#### Scenario 2: User chooses keep -- file preserved

Given ~/.nwave/global-config.json exists
When Ale selects "Keep" during uninstall
Then ~/.nwave/global-config.json is not modified or deleted
And the rest of the uninstall proceeds normally

#### Scenario 3: User chooses delete -- file removed

Given ~/.nwave/global-config.json exists
When Tomasz selects "Delete" during uninstall
Then ~/.nwave/global-config.json is deleted
And if ~/.nwave/ directory is empty, it is also removed

#### Scenario 4: No global config -- no prompt shown

Given ~/.nwave/global-config.json does not exist
When Priya runs nwave-ai uninstall
Then no prompt about global configuration is displayed
And the uninstall proceeds normally

### Acceptance Criteria

- [ ] Uninstall checks for `~/.nwave/global-config.json` before removing nWave artifacts
- [ ] If found, user is prompted with "Keep" or "Delete" options
- [ ] "Keep" preserves the file and directory untouched
- [ ] "Delete" removes the file; removes `~/.nwave/` if empty afterward
- [ ] If global config does not exist, no prompt is shown
- [ ] Dry-run mode shows what would happen without modifying files

### Outcome KPIs

- **Who**: nWave users who uninstall/reinstall
- **Does what**: Retain global preferences across install cycles
- **By how much**: Zero preference loss during reinstall when "Keep" is chosen
- **Measured by**: Presence of global-config.json after uninstall+reinstall cycle
- **Baseline**: Not applicable (global config does not exist today)

### Technical Notes

- Uninstall logic lives in `nwave_ai/cli.py` (the `uninstall` command)
- The prompt should use the same `click.prompt` or `click.confirm` pattern as other CLI interactions
- `~/.nwave/` directory is user-owned (not project-owned) -- different lifecycle from `.nwave/`
- Dependency: US-RGC-02 (global config must exist for this to be relevant)
