Fix macOS symlink path bypass, doc corrections

- P1: cleanPath -> cleanPaths returns both cleaned and resolved paths.
  Policies now match against both forms, fixing macOS /etc -> /private/etc
  bypass where existing symlinked paths could skip path_matches rules.
- P2: README notify example uses correct schema (notify.url + on)
- P2: Claude Desktop guide uses require_approval instead of ask
- P2: ARCHITECTURE.md corrected to fail-open (matches actual behavior)
- P3: PRELOAD-SPEC.md updated to reflect shipped status (v0.1.5+)

All 15 test suites pass.

Author: peg

README.md

@@ -394,10 +394,9 @@ version: "1"
 default_action: allow
 
 notify:
-  webhook:
-    url: "https://discord.com/api/webhooks/your/webhook"
-    # Or Slack: "https://hooks.slack.com/services/your/webhook"
-    events: ["deny"]  # Only notify on denied commands (options: deny, log, ask, allow)
+  url: "https://discord.com/api/webhooks/your/webhook"
+  # Or Slack: "https://hooks.slack.com/services/your/webhook"
+  on: ["deny"]  # Only notify on denied commands (options: deny, log)
 
 policies:
   # ... your policies

docs/ARCHITECTURE.md

@@ -11,7 +11,7 @@ Agent → Tool Call → Rampart → Policy Engine → Allow / Deny / Log
 
 ## Design Decisions
 
-**Fail-closed.** If Rampart crashes, tool calls fail. The agent doesn't get unrestricted access. A security layer that fails open is a logging tool.
+**Fail-open by default.** If Rampart crashes or is unreachable, tool calls pass through. This is deliberate — fail-closed locks you out of your own machine. See the [threat model](THREAT-MODEL.md) for trade-offs and mitigations.
 
 **Custom YAML over OPA/Rego.** The domain is narrow — "should this tool call run?" — and doesn't need a general-purpose policy language. Three lines of YAML beats fifteen lines of Rego. The custom engine also evaluates in <10µs vs OPA's 0.1-1ms.
 

docs/PRELOAD-SPEC.md

@@ -1,8 +1,7 @@
 # Rampart Preload — Syscall-Level Agent Protection
 
-**Status:** Spec / Not yet implemented  
-**Target:** v0.2.0  
-**Effort:** 4-5 weeks
+**Status:** Shipped (v0.1.5+)  
+**See also:** `rampart preload --help`, [README](../README.md#ld_preload)
 
 ## Overview
 

docs/guides/securing-claude-desktop.md

@@ -161,7 +161,7 @@ policies:
     match:
       tool: ["write"]
     rules:
-      - action: ask
+      - action: require_approval
         when:
           path_matches: ["**/.*"]  # Hidden files
         message: "Writing to hidden file — approve?"

internal/engine/matcher.go

@@ -15,7 +15,6 @@ package engine
 
 import (
 	"fmt"
-	"os"
 	"path/filepath"
 	"regexp"
 	"strings"
@@ -28,20 +27,19 @@ import (
 // traversal tricks like "/etc/../etc/shadow" are normalized before
 // glob matching, regardless of which entry point (proxy, interceptor,
 // MCP, SDK) produced the path.
-func cleanPath(p string) string {
+// cleanPaths returns both the cleaned path and the symlink-resolved path.
+// On macOS, /etc -> /private/etc, so policies matching "/etc/**" need to
+// check both forms. For non-existent files, both values are the same.
+func cleanPaths(p string) (cleaned string, resolved string) {
 	if p == "" {
-		return p
+		return p, p
 	}
-	cleaned := filepath.Clean(p)
-	resolved, err := filepath.EvalSymlinks(cleaned)
+	cleaned = filepath.Clean(p)
+	r, err := filepath.EvalSymlinks(cleaned)
 	if err != nil {
-		// File may not exist yet (e.g. write to new path) — use Clean result.
-		if os.IsNotExist(err) {
-			return cleaned
-		}
-		return cleaned
+		return cleaned, cleaned
 	}
-	return resolved
+	return cleaned, r
 }
 
 // MatchGlob reports whether name matches the glob pattern.
@@ -192,11 +190,14 @@ func ExplainCondition(cond Condition, call ToolCall) (bool, string) {
 	}
 
 	if len(cond.PathMatches) > 0 {
-		path := cleanPath(call.Path())
-		if path == "" {
+		cleaned, resolved := cleanPaths(call.Path())
+		if cleaned == "" {
 			return false, ""
 		}
-		matched := matchFirst(cond.PathMatches, path)
+		matched := matchFirst(cond.PathMatches, cleaned)
+		if matched == "" && resolved != cleaned {
+			matched = matchFirst(cond.PathMatches, resolved)
+		}
 		if matched == "" {
 			return false, ""
 		}
@@ -259,11 +260,19 @@ func matchCondition(cond Condition, call ToolCall) bool {
 	// Path matching (for read/write tool calls).
 	// Canonicalize path to prevent traversal bypasses (e.g. /etc/../etc/shadow).
 	if len(cond.PathMatches) > 0 {
-		path := cleanPath(call.Path())
-		if path == "" || !matchAny(cond.PathMatches, path) {
+		cleaned, resolved := cleanPaths(call.Path())
+		if cleaned == "" {
+			return false
+		}
+		pathMatch := matchAny(cond.PathMatches, cleaned)
+		if !pathMatch && resolved != cleaned {
+			pathMatch = matchAny(cond.PathMatches, resolved)
+		}
+		if !pathMatch {
 			return false
 		}
-		if matchAny(cond.PathNotMatches, path) {
+		// Check exclusions against both forms too.
+		if matchAny(cond.PathNotMatches, cleaned) || (resolved != cleaned && matchAny(cond.PathNotMatches, resolved)) {
 			return false
 		}
 		matched = true

internal/engine/matcher_test.go

@@ -59,7 +59,7 @@ func TestMatchGlob(t *testing.T) {
 	}
 }
 
-func TestCleanPath(t *testing.T) {
+func TestCleanPaths(t *testing.T) {
 	tests := []struct {
 		input string
 		want  string
@@ -72,9 +72,9 @@ func TestCleanPath(t *testing.T) {
 	}
 	for _, tt := range tests {
 		t.Run(tt.input, func(t *testing.T) {
-			got := cleanPath(tt.input)
-			if got != tt.want {
-				t.Errorf("cleanPath(%q) = %q, want %q", tt.input, got, tt.want)
+			cleaned, _ := cleanPaths(tt.input)
+			if cleaned != tt.want {
+				t.Errorf("cleanPaths(%q) cleaned = %q, want %q", tt.input, cleaned, tt.want)
 			}
 		})
 	}