dcg

<!-- TOC: Core Insight | THE EXACT WORKFLOW | Quick Reference | Safe Alternatives | What Gets Blocked | Anti-Patterns | Configuration | References -->

# DCG: When You Get Blocked

> **Core Insight:** Blocks are checkpoints, not errors. A safe alternative almost always exists. Find it before mentioning override.

## Constraints

- Never request, generate, or run an allow-once bypass because only the human may authorize and execute the exact blocked command.
- Preserve the user's intended outcome with the narrowest reversible alternative because the guard protects state, not merely command spelling.
- Explain the matched rule and surviving risk before asking for judgment; never retry, obfuscate, or route around a DCG block.

## Quick Navigation

| I need to... | Go to |
|--------------|-------|
| Handle a block right now | [THE EXACT WORKFLOW](#the-exact-workflow) |
| Find a safe alternative | [Safe Alternatives](#safe-alternatives) |
| See all CLI commands | [COMMANDS.md](references/COMMANDS.md) |
| Enable more rule packs | [PACKS.md](references/PACKS.md) |
| Configure per-project | [CONFIG.md](references/CONFIG.md) |
| Debug hook issues | [TROUBLESHOOTING.md](references/TROUBLESHOOTING.md) |

---

## THE EXACT WORKFLOW

When blocked, follow this sequence every time:

```
1. Run `dcg explain "cmd"` → Understand why (see trace)
2. Check Safe Alternatives table → Use if exists (DON'T mention override)
3. No alternative? → Explain risk clearly, let human decide
4. Human approves? → THEY run: dcg allow-once CODE
```

**Never:** Ask for override first. Never retry silently. Never circumvent.

### Risk-tiered approval counts

When no safe alternative exists and the human must decide, the number of
distinct human approvals scales with what the command can destroy:

| Tier | Blast radius | Approvals required |
|------|--------------|--------------------|
| Recoverable | undoable via reflog/stash/trash/backup | 1 allow-once for this exact command |
| Destructive-local | permanently deletes local, uncommitted, or unbacked state | 1 allow-once, granted only after you name the exact state lost and confirm no backup exists |
| Destructive-shared | shared history, remote branches, databases, namespaces others use | 1 approval per individual command occurrence — never batched, never pattern-widened |

Stop conditions: never present a tier-2 or tier-3 command as tier-1; never
convert several pending blocks into one blanket approval. A single "yes" that
gets spent across multiple destructive commands is the **approval laundering**
failure mode — each allow-once code is bound to one command in one directory,
and the workflow must keep it that way.

**Example block output:**
```
BLOCKED: git reset --hard HEAD
Rule: core.git:reset-hard
Reason: Discards uncommitted changes permanently
Allow-once code: ab12
Safer alternative: git stash
```

**Good response:**
> "I wanted to discard changes but `git reset --hard` was blocked. Let me use `git stash` instead—recoverable if needed." [proceeds with stash]

## Safe Alternatives

| Blocked | Use Instead | Why |
|---------|-------------|-----|
| `git reset --hard` | `git stash` | Recoverable |
| `git checkout -- file` | `git stash push file` | Preserves changes |
| `git push --force` | `git push --force-with-lease` | Checks remote unchanged |
| `git clean -fd` | `git clean -fdn` (preview) | Shows what would delete |
| `git stash drop` | `git stash list` first | Verify which stash |
| `rm -rf /path` | `rm -ri /path` or verify path | Interactive/confirm |
| `kubectl delete namespace` | `kubectl delete -l app=X` | Selective deletion |
| `DROP DATABASE` | Backup first | Human approves |
| `docker system prune -a` | `docker system df` first | See what's used |

## Quick Reference

```bash
dcg doctor              # Health check — hook registered?
dcg explain "cmd"       # WHY is it blocked? (with trace)
dcg test "cmd"          # Would this be blocked? (dry-run)
dcg allow-once CODE     # Human approves (THEY run this)
dcg packs               # List available rule packs
dcg scan --staged       # Pre-commit: scan for issues
```

---

## What Gets Blocked

| Category | Patterns | Safe Variants |
|----------|----------|---------------|
| Git destructive | `reset --hard`, `checkout --` | `stash`, `restore --staged` |
| Git history | `push --force`, `branch -D` | `--force-with-lease`, `-d` |
| Git stash | `stash drop`, `stash clear` | `stash list` first |
| Filesystem | `rm -rf` (dangerous paths) | `/tmp/*` allowed |
| Database | `DROP`, `TRUNCATE`, `DELETE` w/o WHERE | Add WHERE clause |
| K8s | `delete namespace`, `delete --all` | `-l` label selector |

**Context-aware (measured on dcg 0.5.6):** the temp carve-out allows `rm -rf`
under `/tmp`, `/private/tmp`, `/var/tmp`, and the literal `$TMPDIR` form.
Everything else — `rm -rf ./build` and other relative paths
(`core.filesystem:rm-rf-general`), absolute paths like `/home/...` and `/`
(`core.filesystem:rm-rf-root-home`), and even `/private/var/tmp` — is blocked.
Unresolved variables other than `$TMPDIR` are not treated as temp.

**`dcg explain` example (7-step pipeline):**
```bash
$ dcg explain "git reset --hard HEAD"
BLOCKED by core.git:reset-hard

Evaluation trace:
  1. Config allow overrides: no match
  2. Config block overrides: no match
  3. Heredoc detection: not applicable
  4. Quick reject: triggered (contains "reset")
  5. Context sanitization: no changes
  6. Normalization: git reset --hard HEAD
  7. Pack evaluation:
     - Safe patterns: no match
     - Destructive: MATCH "reset --hard"

Suggestion: Use `git stash` to preserve changes
```

## Anti-Patterns

```
❌ "Command blocked. Run dcg allow-once ab12"  → Find alternative first!
❌ *Retrying silently or circumventing*         → Always acknowledge blocks
❌ Treating blocks as errors                    → They're checkpoints
❌ Asking user to allow-once without explaining → They need context
```

## Configuration

```toml
# .dcg.toml — enable rule packs per-project
[pac