# Configuration File Safety Rules

## appsettings*.json Protection

### MANDATORY Rules

1. **NEVER use Write tool on `appsettings*.json`** — ALWAYS use Edit for targeted changes
2. **NEVER remove existing top-level sections** — only add or modify values within existing structure
3. **NEVER delete configuration keys** — replace secret VALUES with `<CONFIGURE_HERE>` placeholder
4. **When adding a new section**, use Edit to insert at the correct location (before the closing `}`)

### WHY

Claude's Write tool replaces the entire file. If you read a 200-line appsettings.json but only reproduce 150 lines in the Write, 50 lines of configuration are permanently lost. This has caused production incidents where entire authentication, logging, or integration sections disappeared.

### Correct Patterns

| Action | Tool | Approach |
|--------|------|----------|
| Add new section | Edit | Find closing `}`, replace with new section + `}` |
| Modify a value | Edit | Target the specific key-value pair |
| Add a key to section | Edit | Find the section's closing `}`, add key before it |
| Replace secrets | Edit | Replace the VALUE only, keep the key |

### Example: Adding a New Section

```
// Use Edit tool with:
// old_string:   "Serilog": { ... }\n}
// new_string:   "Serilog": { ... },\n  "NewSection": { "Key": "<CONFIGURE_HERE>" }\n}
```

### Secret Value Handling

```json
// WRONG - removing the key entirely
"Jwt": { }

// WRONG - deleting the section
// (section missing from file)

// CORRECT - placeholder value preserving structure
"Jwt": {
  "SecretKey": "<CONFIGURE_HERE>",
  "Issuer": "<CONFIGURE_HERE>",
  "Audience": "<CONFIGURE_HERE>",
  "ExpirationMinutes": 60
}
```

### Exception: New File Creation

Write is acceptable ONLY when creating a NEW `appsettings.*.json` file that does not yet exist on disk (e.g., `appsettings.Local.json` during `/gitflow start`). The PreToolUse hook automatically allows this case.

### Protection Layers

| Layer | Mechanism | When |
|-------|-----------|------|
| Hook `appsettings-guard.sh` | PreToolUse on Write | Blocks Write if top-level sections would be lost |
| Commit agent step 2b | During `/gitflow commit` | Detects section removal vs HEAD before staging |
| These instructions | During development | Prevents the issue from occurring |
