qmu/system-safety

System Safety

Prevents agents from modifying system-wide configuration (shell profiles, global packages, system services, etc.) unless the repository is specifically a provisioning repository.

1. Authorization Model

Repositories fall into two categories:

• Provisioning repository: A repository whose purpose is to configure a server, laptop, or environment (dotfiles, Ansible playbooks, Terraform, Nix configs, etc.). System-wide changes ARE authorized.
• Regular project: An application, library, plugin, or service. System-wide changes are NOT authorized.

If uncertain, treat as a regular project. False negatives (failing to detect a provisioning repo) are less harmful than false positives (allowing system changes in a regular project).

2. Provisioning Detection

Run the detection script at the start of implementation:

bash ${CLAUDE_PLUGIN_ROOT}/skills/system-safety/scripts/detect.sh

The script checks for provisioning indicators and outputs JSON:

{
  "is_provisioning": false,
  "signals": [],
  "system_changes_authorized": false
}

2-1. Provisioning Signals

The script checks for these indicators:

| Signal | Check | |--------|-------| | Repo name contains "dotfiles" | Directory name of repo root | | Ansible configuration | ansible.cfg or playbooks/ at root | | Vagrant configuration | Vagrantfile at root | | Chezmoi configuration | .chezmoi* files at root | | Terraform configuration | *.tf files at root | | Pulumi configuration | Pulumi.yaml at root | | Nix configuration | flake.nix or configuration.nix at root | | Brewfile | Brewfile at root with no package.json/Cargo.toml/go.mod | | Provisioning install script | install.sh or setup.sh at root with no application code |

Two or more signals confirm a provisioning repository. A single signal sets is_provisioning: true but the agent should verify with the user if the operation is significant.

3. Prohibited Operations

In regular projects, the following operations are NEVER allowed:

| Operation | Example | Risk | |-----------|---------|------| | Global package installs | npm install -g, pip install (without virtualenv), gem install (without bundler) | Modifies global package state | | Shell profile edits | Writing to ~/.bashrc, ~/.zshrc, ~/.profile, ~/.bash_profile | Alters user shell environment | | System config edits | Writing to /etc/* | Alters system-wide configuration | | System service management | systemctl enable/start/stop, launchctl load | Changes running services | | Environment variable exports in profiles | Appending export lines to shell profiles | Persistent environment changes | | Global tool configuration | Writing to ~/.gitconfig, ~/.npmrc, ~/.config/* (outside project) | Alters global tool behavior | | Privilege escalation | sudo commands | May modify system state |

3-1. Safe Alternatives

| Prohibited | Safe Alternative | |-----------|-----------------| | npm install -g <pkg> | npx <pkg> or add to project devDependencies | | pip install <pkg> | pip install <pkg> inside a virtualenv or uv pip install | | Editing ~/.bashrc | Use project-local .env or .envrc files | | sudo apt install | Document the dependency in README or check if already available | | systemctl start | Use docker compose up or project-local service management | | Writing to ~/.gitconfig | Use project-local .gitconfig or git -c flags |

4. Enforcement

This is a textual constraint enforced through agent instructions. Agents must:

1. Run the detection script before any implementation that may touch system configuration
2. If system_changes_authorized is false, refuse any operation from the prohibited list
3. If an implementation step requires a prohibited operation, propose a safe alternative instead
4. If no safe alternative exists, report the blocker to the user rather than proceeding