docs(guardrails): add operator policy packs + rollout preview

Author: ashsolei

docs/guardrails/README.md

@@ -0,0 +1,26 @@
+# Operator Guardrails (experimental)
+
+Minimum delighter slice for the "operator guardrails and policy UX" P1
+backlog item. Ships three opinionated policy packs so admins can pick one and
+preview how commands will be constrained before rollout.
+
+## Policy packs
+
+| Pack | Posture | Default command handling | Approval required |
+|---|---|---|---|
+| `observer` | least privilege | dry-run everything; block side effects | every `write` |
+| `standard` | balanced | allow read + common ops; deny destructive | `delete`, `chmod`, network egress |
+| `power-user` | broad | allow most commands | only for irreversible ops |
+
+See `observer.yaml`, `standard.yaml`, and `power-user.yaml` for the full rule
+shape. Each pack documents, in plain text, exactly which command categories
+are allowed, denied, or quarantined for approval.
+
+## Rollout preview
+
+The rollout preview is currently docs-only: before enabling a pack in a real
+environment, an admin can read the pack's YAML and the corresponding
+`preview/*.txt` file to see a sample of how 20 representative commands would
+be classified.
+
+Wiring the preview into a runtime checker is tracked as the next pass.

docs/guardrails/observer.yaml

@@ -0,0 +1,20 @@
+name: observer
+description: Least-privilege pack. Dry-run all commands, block everything with side effects, queue writes for explicit approval.
+allow:
+  - read
+  - list
+  - stat
+deny:
+  - delete
+  - chmod
+  - chown
+  - network_egress
+  - package_install
+  - kernel_module
+approval_required:
+  - write
+  - create
+audit:
+  log_stdout: true
+  log_stderr: true
+  log_approvals: true

docs/guardrails/power-user.yaml

@@ -0,0 +1,21 @@
+name: power-user
+description: Broad pack. Most commands allowed; only irreversible or system-level changes require approval.
+allow:
+  - read
+  - list
+  - stat
+  - write
+  - create
+  - delete
+  - chmod
+  - network_egress
+  - package_install
+deny:
+  - kernel_module
+approval_required:
+  - rm_rf_root
+  - drop_database
+audit:
+  log_stdout: true
+  log_stderr: true
+  log_approvals: true

docs/guardrails/preview/observer.txt

@@ -0,0 +1,22 @@
+Observer pack — sample classification of 20 common commands
+============================================================
+ls /etc                        -> ALLOW (read)
+cat /etc/hosts                 -> ALLOW (read)
+stat /var/log/syslog           -> ALLOW (stat)
+echo hi > /tmp/x               -> APPROVAL (write)
+touch /tmp/x                   -> APPROVAL (create)
+rm /tmp/x                      -> DENY (delete)
+rm -rf /                       -> DENY (delete)
+chmod 777 /etc/shadow          -> DENY (chmod)
+chown root /etc/hosts          -> DENY (chown)
+curl https://example.com       -> DENY (network_egress)
+wget https://example.com       -> DENY (network_egress)
+apt-get install nginx          -> DENY (package_install)
+pip install requests           -> DENY (package_install)
+modprobe foo                   -> DENY (kernel_module)
+uname -a                       -> ALLOW (read)
+ps aux                         -> ALLOW (read)
+df -h                          -> ALLOW (read)
+mkdir /tmp/new                 -> APPROVAL (create)
+mv /tmp/a /tmp/b               -> APPROVAL (write)
+diff /etc/a /etc/b             -> ALLOW (read)

docs/guardrails/standard.yaml

@@ -0,0 +1,20 @@
+name: standard
+description: Balanced pack. Reads and common operations allowed, destructive or high-risk commands denied or queued for approval.
+allow:
+  - read
+  - list
+  - stat
+  - write
+  - create
+deny:
+  - delete
+  - chmod
+  - chown
+  - kernel_module
+approval_required:
+  - network_egress
+  - package_install
+audit:
+  log_stdout: true
+  log_stderr: true
+  log_approvals: true