Severity Levels

Every check pattern in shellfirm has a severity level that indicates how dangerous the matched command is. Severity levels determine both which commands trigger challenges and how hard the challenge is — Critical severity commands automatically require typing "yes", while High severity commands require pressing Enter.

The five severity levels

Level	Description	Example patterns
Info	Informational -- low risk, but worth noting	(reserved for future use)
Low	Minor risk, usually reversible	`git add .`, `git stash pop`, `git tag -a`
Medium	Moderate risk, could cause inconvenience	`chmod`, `git rebase`, `heroku config:unset`, `docker network rm`
High	Significant risk, data loss or service disruption possible	`git push --force`, `git reset`, `docker system prune -a`, `aws ec2 terminate-instances`, `rm -rf` (strict)
Critical	Maximum risk, irreversible or catastrophic	`rm -rf /`, `DROP DATABASE`, `kubectl delete namespace`, `terraform apply -auto-approve`, `FLUSHALL`

Real examples by severity

Critical

Commands that can destroy entire systems, databases, or namespaces:

rm -rf /                          # Delete entire filesystem
kubectl delete ns production      # Destroy all resources in namespace
terraform apply -auto-approve     # Apply without review
DROP DATABASE customers;          # Permanent database deletion
docker rm -f $(docker ps -aq)     # Force-remove all containers
redis-cli FLUSHALL                # Delete all Redis data

High

Commands that can cause significant data loss or service disruption:

git push --force origin main      # Overwrite remote history
git reset --hard                  # Discard all local changes
aws ec2 terminate-instances       # Permanently destroy EC2 instances
docker volume rm mydata           # Delete persistent volume data
az group delete                   # Destroy Azure resource group
heroku apps:destroy               # Permanently destroy Heroku app

Medium

Commands that could cause issues but are often intentional:

chmod 755 script.sh               # Change file permissions
git rebase -i HEAD~5              # Rewrite recent history
docker stop $(docker ps -q)       # Stop all running containers
heroku config:unset API_KEY       # Remove config variable

Low

Minor operations that are usually safe but worth flagging in strict mode:

git add .                         # Stage all changes
git commit -a                     # Commit all modified files
git stash pop                     # Apply and remove stash
git tag -a v1.0                   # Create annotated tag

Severity-based challenge escalation

By default, shellfirm automatically escalates challenges based on the severity of the matched check. This means dangerous commands get harder challenges without any additional configuration:

Severity	Default challenge floor
Critical	Yes (type "yes")
High	Enter (press Enter)
Medium	Math (no escalation)
Low	Math (no escalation)
Info	Math (no escalation)

This is ON by default — a DROP DATABASE (Critical) always requires typing "yes", and git push --force (High) always requires pressing Enter, even on a local development machine with no special context signals.

Configuring severity escalation

You can customize the challenge floor for each severity level. Any omitted keys use their defaults, so you only need to specify what you want to change:

# In ~/.config/shellfirm/settings.yaml
severity_escalation:
  critical: "Yes"    # default
  high: Enter        # default
  # medium, low, info default to Math

Or via CLI:

shellfirm config escalation severity --high Yes     # High severity → Yes
shellfirm config escalation severity --medium Enter  # Medium severity → Enter

To disable severity escalation entirely (revert to pre-0.4 behavior where severity only controlled filtering):

severity_escalation:
  enabled: false

How severity escalation stacks

Severity escalation is one layer in the full escalation pipeline. It stacks with context escalation (SSH, root, production) and project policy overrides — each layer can only make the challenge harder, never easier. For example, a High severity check (floor: Enter) on a protected branch (context: Yes) results in a Yes challenge.

Protection presets

You can think of the min_severity setting as choosing a protection preset:

Preset name	min_severity setting	Triggers on	Use case
Paranoid	`null` (not set)	Info, Low, Medium, High, Critical	Maximum protection, every check fires
Balanced	`Medium`	Medium, High, Critical	Good default for most developers
Chill	`High`	High, Critical	Experienced developers who want less friction
YOLO	`Critical`	Critical only	Only the truly catastrophic commands

Configuring the threshold

# Paranoid -- everything triggers
shellfirm config severity all

# Balanced -- Medium and above
shellfirm config severity Medium

# Chill -- High and above
shellfirm config severity High

# YOLO -- Critical only
shellfirm config severity Critical

What happens to skipped checks

When a check matches but its severity is below your threshold, it is:

Not shown to you (no challenge prompt)
Logged in the audit trail with outcome Skipped
Visible in shellfirm audit show for compliance review

This means you always have full visibility into what shellfirm detected, even if it did not prompt you.

Severity in team policies

Project policies (.shellfirm.yaml) can override the challenge type for specific patterns but cannot lower the effective challenge. Severity escalation stacks with policy overrides — if a Critical severity check already requires Yes, a policy override trying to set Enter will be ignored. See Team Policies for details.

Severity and agent mode

When running in agent mode (for AI coding agents), the agent.auto_deny_severity setting controls which severity level triggers automatic denial:

# In settings.yaml
agent:
  auto_deny_severity: High   # default

Commands at or above this severity are automatically denied when run by an AI agent. See Agents and Automation for details.