PredicateSystems · rcholic · Feb 21, 2026 · Feb 21, 2026
diff --git a/README.md b/README.md
diff --git a/docs/MIGRATION_GUIDE.md b/docs/MIGRATION_GUIDE.md
diff --git a/docs/PRODUCTION_READINESS.md b/docs/PRODUCTION_READINESS.md
@@ -0,0 +1,134 @@
+# Production Readiness Checklist
+
+This document tracks production readiness criteria for the OpenClaw Predicate
+Provider. All items must be verified before GA release.
+
+**Status:** Ready for review
+**Last Updated:** 2026-02-20
+**Owner:** Platform Security
+
+## 1. Security Posture
+
+| Criteria | Status | Evidence |
+|----------|--------|----------|
+| Fail-closed default for high-risk actions | ✓ | `provider.ts` throws on sidecar errors |
+| No embedded signing keys in plugin | ✓ | Keys remain in sidecar/control plane |
+| Log redaction for sensitive values | ✓ | Tests in `audit-event-e2e.test.ts` |
+| SecurityError returns redacted reasons | ✓ | `errors.ts` implementation |
+| Path traversal protection | ✓ | Tests in `hack-vs-fix-demo.test.ts` |
+| Prompt injection blocking | ✓ | Tests in `hack-vs-fix-demo.test.ts` |
+
+**Security Signoff:** _________________ Date: _________
+
+## 2. Reliability
+
+| Criteria | Status | Evidence |
+|----------|--------|----------|
+| Circuit breaker for sidecar outages | ✓ | `circuit-breaker.ts` |
+| Exponential backoff with jitter | ✓ | `calculateBackoff()` function |
+| Configurable timeouts | ✓ | `config.ts` (300ms default) |
+| Graceful degradation on sync failure | ✓ | Local policy evaluation continues |
+| Load tested (100 sequential, 50 concurrent) | ✓ | `load-latency.test.ts` |
+
+## 3. Observability
+
+| Criteria | Status | Evidence |
+|----------|--------|----------|
+| Decision telemetry (allow/deny/error) | ✓ | `provider.ts` telemetry hooks |
+| Latency metrics | ✓ | `load-latency.test.ts` p50/p95 |
+| Circuit breaker state metrics | ✓ | `CircuitBreaker.getMetrics()` |
+| Audit export integration | ✓ | `audit-event-e2e.test.ts` |
+| Correlation IDs (session, tenant, trace) | ✓ | `multi-tenant-isolation.test.ts` |
+
+## 4. SLOs and Alerting
+
+| Criteria | Status | Evidence |
+|----------|--------|----------|
+| Latency SLOs defined (p50 <25ms, p95 <75ms) | ✓ | `docs/SLO_THRESHOLDS.md` |
+| Availability SLOs defined (99.9%) | ✓ | `docs/SLO_THRESHOLDS.md` |
+| Alert thresholds documented | ✓ | `docs/SLO_THRESHOLDS.md` |
+| Circuit breaker alert thresholds | ✓ | `docs/SLO_THRESHOLDS.md` |
+| Deny spike detection criteria | ✓ | `docs/SLO_THRESHOLDS.md` |
+
+## 5. Operations
+
+| Criteria | Status | Evidence |
+|----------|--------|----------|
+| Operational runbook | ✓ | `docs/OPERATIONAL_RUNBOOK.md` |
+| P1-P4 incident procedures | ✓ | `docs/OPERATIONAL_RUNBOOK.md` |
+| Health check endpoints | ✓ | Documented in runbook |
+| Restart/recovery procedures | ✓ | `docs/OPERATIONAL_RUNBOOK.md` |
+| Credential rotation procedures | ✓ | `docs/OPERATIONAL_RUNBOOK.md` |
+| Scaling guidance | ✓ | `docs/OPERATIONAL_RUNBOOK.md` |
+
+## 6. Testing
+
+| Criteria | Status | Evidence |
+|----------|--------|----------|
+| Unit tests | ✓ | 15 test files, all passing |
+| Integration tests (sidecar wire format) | ✓ | `provider.test.ts` |
+| Load/latency tests | ✓ | `load-latency.test.ts` |
+| Multi-tenant isolation tests | ✓ | `multi-tenant-isolation.test.ts` |
+| JWKS/key rotation tests | ✓ | `jwks-rotation.test.ts` |
+| Adversarial/security tests | ✓ | `hack-vs-fix-demo.test.ts` |
+| CI pipeline (Node 20/22) | ✓ | `.github/workflows/tests.yml` |
+
+## 7. Documentation
+
+| Criteria | Status | Evidence |
+|----------|--------|----------|
+| API contract documented | ✓ | Design doc action/resource mapping |
+| Fail-open/fail-closed policy table | ✓ | Design doc |
+| SLO documentation | ✓ | `docs/SLO_THRESHOLDS.md` |
+| Operational runbook | ✓ | `docs/OPERATIONAL_RUNBOOK.md` |
+| Docker adversarial test guide | ✓ | `examples/README.md` |
+
+## 8. Control Plane Integration
+
+| Criteria | Status | Evidence |
+|----------|--------|----------|
+| Policy sync client | ✓ | `control-plane-sync.ts` |
+| Revocation propagation | ✓ | `control-plane-sync.ts` |
+| Stale-sync observability | ✓ | `ControlPlaneSyncStatusTracker` |
+| Audit export wiring | ✓ | `audit-event-e2e.test.ts` |
+
+## 9. Known Limitations
+
+| Limitation | Impact | Planned Fix |
+|------------|--------|-------------|
+| `state_hash` not integrated into auth flow | Limits pre-execution state verification | Post-Phase 4 |
+| No automatic sidecar discovery | Requires manual `baseUrl` config | Future enhancement |
+
+## Sign-off
+
+### Engineering Review
+
+- [ ] All test suites passing
+- [ ] Code review completed
+- [ ] Performance benchmarks acceptable
+
+**Engineering Lead:** _________________ Date: _________
+
+### Security Review
+
+- [ ] Fail-closed behavior verified
+- [ ] Log redaction verified
+- [ ] No credential exposure risks
+
+**Security Lead:** _________________ Date: _________
+
+### Operations Review
+
+- [ ] Runbook reviewed and validated
+- [ ] Alerting configured
+- [ ] On-call procedures documented
+
+**Operations Lead:** _________________ Date: _________
+
+### Final Approval
+
+- [ ] All sections signed off
+- [ ] No blocking issues
+- [ ] Ready for GA release
+
+**Release Manager:** _________________ Date: _________
diff --git a/examples/policy/README.md b/examples/policy/README.md
@@ -0,0 +1,165 @@
+# Policy Starter Pack
+
+Ready-to-use policy templates for common OpenClaw security scenarios.
+
+## Quick Start
+
+1. Copy the relevant policy file to your sidecar config directory
+2. Customize paths and hosts for your environment
+3. Restart the sidecar to load the new policy
+
+```bash
+cp examples/policy/workspace-isolation.yaml ~/.predicate/policies/
+predicate-authorityd --policy-dir ~/.predicate/policies/
+```
+
+## Available Policies
+
+### 1. Workspace Isolation (`workspace-isolation.yaml`)
+
+Restricts file operations to a specific project directory. Ideal for:
+- Development agents working on a single project
+- CI/CD agents with bounded scope
+- Sandboxed coding assistants
+
+### 2. Sensitive Path Blocking (`sensitive-paths.yaml`)
+
+Blocks access to common sensitive paths:
+- SSH keys (`~/.ssh/*`)
+- Cloud credentials (`~/.aws/*`, `~/.gcloud/*`, `~/.azure/*`)
+- System configs (`/etc/*`)
+- Environment files (`.env`, `.env.*`)
+
+### 3. Source-Based Trust (`source-trust.yaml`)
+
+Different rules based on request source:
+- `trusted_ui` - Direct user interaction, more permissive
+- `untrusted_dm` - External messages, restrictive
+- `web_content` - Web page content, very restrictive
+
+### 4. Approved Hosts (`approved-hosts.yaml`)
+
+Allowlist for outbound HTTP requests:
+- Internal APIs
+- Known SaaS endpoints
+- Package registries
+
+### 5. Development Workflow (`dev-workflow.yaml`)
+
+Balanced policy for development agents:
+- Allow git, npm, cargo, etc.
+- Allow localhost HTTP
+- Block production endpoints
+- Block destructive commands
+
+### 6. Production Strict (`production-strict.yaml`)
+
+Maximum security for production agents:
+- Explicit allowlist only
+- No shell execution
+- Audit all decisions
+
+## Policy Syntax
+
+Policies use YAML format with the following structure:
+
+```yaml
+version: 1
+
+# Global defaults
+defaults:
+  effect: deny  # deny-by-default recommended
+
+# Rule definitions (evaluated in order)
+rules:
+  - id: unique_rule_id
+    effect: allow | deny
+    action: action.type | action.*
+    resource: path/pattern | [list, of, patterns]
+    when:                    # Optional conditions
+      source: trusted_ui
+      tenant_id: tenant-123
+
+# Metadata
+metadata:
+  name: Policy Name
+  description: What this policy does
+  version: 1.0.0
+```
+
+## Condition Reference
+
+### Source Labels
+
+| Source | Description | Trust Level |
+|--------|-------------|-------------|
+| `trusted_ui` | Direct user input from trusted UI | High |
+| `trusted_api` | Authenticated API request | High |
+| `untrusted_dm` | External message (DM, email) | Low |
+| `web_content` | Content from web pages | Very Low |
+| `system` | Internal system call | High |
+
+### Actions
+
+| Action | Description |
+|--------|-------------|
+| `shell.execute` | Run shell command |
+| `fs.read` | Read file |
+| `fs.write` | Write file |
+| `net.http` | HTTP request |
+
+### Resource Patterns
+
+- Exact match: `/path/to/file`
+- Glob: `/workspace/**/*.ts`
+- Home expansion: `~/.ssh/*`
+- List: `["/etc/*", "/var/*"]`
+
+## Combining Policies
+
+Policies can be split across multiple files. The sidecar merges them:
+
+```bash
+~/.predicate/policies/
+├── base.yaml           # Global defaults
+├── workspace.yaml      # Project-specific rules
+└── team-overrides.yaml # Team customizations
+```
+
+Rules are evaluated in filename order. Later files can override earlier ones.
+
+## Testing Policies
+
+Use the policy tester to validate rules before deployment:
+
+```bash
+# Test a specific authorization request
+predicate-authorityd policy test \
+  --policy examples/policy/workspace-isolation.yaml \
+  --principal "agent:test" \
+  --action "fs.read" \
+  --resource "/workspace/src/main.ts" \
+  --context '{"source": "trusted_ui"}'
+
+# Expected output:
+# Decision: ALLOW
+# Matched rule: allow_workspace_reads
+```
+
+## Migration from Other Systems
+
+### From OpenClaw Sandbox
+
+If currently using OpenClaw's built-in sandbox:
+
+1. Start with `workspace-isolation.yaml`
+2. Add your existing sandbox paths to the allow list
+3. Run in audit mode first to catch missing rules
+
+### From HITL-only
+
+If currently using human-in-the-loop for all sensitive actions:
+
+1. Start with `production-strict.yaml`
+2. Gradually add allow rules for common patterns
+3. Keep HITL for truly exceptional cases