4 files changed, 509 insertions, 1881 deletions

diff --git a/docs/explanation/architecture.md b/docs/explanation/architecture.md
index ebf7a74..3fb895c 100644
--- a/docs/explanation/architecture.md
+++ b/docs/explanation/architecture.md
@@ -2,16 +2,16 @@
 
 ## Executive Summary
 
-`ngit-grasp` implements the GRASP protocol in Rust with **inline authorization** rather than Git hooks. The key architectural insight is that the `git-http-backend` Rust crate provides sufficient flexibility to intercept and validate Git push operations before they reach the Git repository, eliminating the need for pre-receive hooks.
+`ngit-grasp` implements the GRASP protocol in Rust with **inline authorization** rather than Git hooks. The key architectural insight is that we can intercept and validate Git push operations at the HTTP handler level before reaching the Git repository, eliminating the need for pre-receive hooks.
 
 ## Architectural Decision: Inline vs. Hook-Based Authorization
 
 ### Investigation Summary
 
-After examining both the reference implementation and the `git-http-backend` Rust crate, we have two options:
+After examining both the reference implementation and HTTP server options, we have two options:
 
 #### Option 1: Hook-Based (Reference Implementation Approach)
-- Use `git-http-backend` crate as-is
+- Use standard Git HTTP backend
 - Create pre-receive and post-receive hooks
 - Hooks query the Nostr relay and validate pushes
 - **Pros**: Follows reference implementation closely
@@ -28,7 +28,7 @@ After examining both the reference implementation and the `git-http-backend` Rus
 
 **Rationale:**
 
-1. **The `git-http-backend` crate is sufficiently flexible**: Examining `src/actix/git_receive_pack.rs` shows it spawns `git receive-pack` as a subprocess and streams data. We can intercept this.
+1. **Full control over HTTP layer**: Using Hyper directly gives us complete control over request handling, WebSocket upgrades, and CORS headers.
 
 2. **Better Developer Experience**: 
    - Validation errors can be returned as proper HTTP responses
@@ -56,7 +56,7 @@ After examining both the reference implementation and the `git-http-backend` Rus
 │                                                             │
 │  ┌──────────────────┐              ┌──────────────────┐   │
 │  │   HTTP Router    │              │  Nostr Relay     │   │
-│  │   (actix-web)    │              │  (nostr-relay-   │   │
+│  │     (Hyper)      │              │  (nostr-relay-   │   │
 │  │                  │              │   builder)       │   │
 │  └────────┬─────────┘              └────────┬─────────┘   │
 │           │                                 │             │
@@ -90,299 +90,149 @@ After examining both the reference implementation and the `git-http-backend` Rus
 
 ## Component Design
 
-### 1. Main Server (`src/main.rs`)
+### 1. Main Server ([`src/main.rs`](src/main.rs))
 
 **Responsibilities:**
-- Initialize configuration from environment
-- Set up actix-web HTTP server
-- Initialize Nostr relay builder
-- Set up shared storage
-- Configure routes for both Git and Nostr endpoints
+- Initialize configuration from environment (clap + dotenvy)
+- Set up Hyper HTTP server with request routing
+- Initialize Nostr relay builder with custom [`Nip34WritePolicy`](src/nostr/builder.rs:51)
+- Set up shared storage (LMDB, NostrDB, or Memory)
+- Handle WebSocket upgrades for Nostr relay
 - Handle graceful shutdown
 
 **Key Dependencies:**
 ```rust
-actix-web = "4"
+hyper = "1"
 tokio = { version = "1", features = ["full"] }
 nostr-relay-builder = "0.43"
 nostr-sdk = "0.43"
+nostr-lmdb = "0.43"
 ```
 
-### 2. Git Module (`src/git/`)
+### 2. HTTP Module ([`src/http/mod.rs`](src/http/mod.rs))
 
-#### `handler.rs` - Git HTTP Handlers
+**Responsibilities:**
+- Route HTTP requests to appropriate handlers
+- WebSocket upgrade for Nostr relay at `/`
+- Git Smart HTTP endpoints at `/<npub>/<identifier>.git/*`
+- Landing pages and NIP-11 document serving
+- CORS headers on all responses (GRASP-01 requirement)
 
-Implements actix-web handlers for Git Smart HTTP protocol:
+**Key Implementation Details:**
 
 ```rust
-// GET /<npub>/<identifier>.git/info/refs?service=git-upload-pack
-async fn info_refs_upload_pack(
-    req: HttpRequest,
-    state: web::Data<AppState>,
-) -> Result<HttpResponse>
-
-// POST /<npub>/<identifier>.git/git-upload-pack
-async fn git_upload_pack(
-    req: HttpRequest,
-    body: web::Payload,
-    state: web::Data<AppState>,
-) -> Result<HttpResponse>
-
-// GET /<npub>/<identifier>.git/info/refs?service=git-receive-pack
-async fn info_refs_receive_pack(
-    req: HttpRequest,
-    state: web::Data<AppState>,
-) -> Result<HttpResponse>
-
-// POST /<npub>/<identifier>.git/git-receive-pack
-// THIS IS WHERE THE MAGIC HAPPENS
-async fn git_receive_pack(
-    req: HttpRequest,
-    body: web::Payload,
-    state: web::Data<AppState>,
-) -> Result<HttpResponse>
+// CORS headers required by GRASP-01 specification
+const CORS_ALLOW_ORIGIN: &str = "*";
+const CORS_ALLOW_METHODS: &str = "GET, POST";
+const CORS_ALLOW_HEADERS: &str = "Content-Type";
+
+/// Add CORS headers to a response builder
+fn add_cors_headers(builder: http::response::Builder) -> http::response::Builder {
+    builder
+        .header("Access-Control-Allow-Origin", CORS_ALLOW_ORIGIN)
+        .header("Access-Control-Allow-Methods", CORS_ALLOW_METHODS)
+        .header("Access-Control-Allow-Headers", CORS_ALLOW_HEADERS)
+}
 ```
 
-#### `authorization.rs` - Push Validation
+See [`src/http/mod.rs:29-84`](src/http/mod.rs:29-84) for the full CORS implementation.
 
-**Core Logic:**
+### 3. Git Module ([`src/git/`](src/git/))
 
-```rust
-pub struct PushValidator {
-    nostr_client: Arc<Client>,
-    relay_url: String,
-}
+#### [`handlers.rs`](src/git/handlers.rs) - Git HTTP Handlers
 
-impl PushValidator {
-    /// Validate a push operation against Nostr state
-    pub async fn validate_push(
-        &self,
-        npub: &str,
-        identifier: &str,
-        ref_updates: Vec<RefUpdate>,
-    ) -> Result<ValidationResult> {
-        // 1. Fetch announcement and state events from local relay
-        let events = self.fetch_events(identifier).await?;
-        
-        // 2. Extract pubkey from npub
-        let pubkey = decode_npub(npub)?;
-        
-        // 3. Get recursive maintainer set
-        let maintainers = get_maintainers(&events, &pubkey, identifier);
-        
-        // 4. Get latest state from maintainers
-        let state = get_state_from_maintainers(&events, &maintainers)?;
-        
-        // 5. Validate each ref update
-        for ref_update in ref_updates {
-            if ref_update.ref_name.starts_with("refs/nostr/") {
-                // Allow refs/nostr/<event-id> for PRs
-                validate_pr_ref(&ref_update)?;
-            } else if ref_update.ref_name.starts_with("refs/heads/pr/") {
-                // Reject pr/* branches - should use refs/nostr/
-                return Err(Error::InvalidRef("pr/* branches must use refs/nostr/"));
-            } else {
-                // Validate against state event
-                validate_state_ref(&state, &ref_update)?;
-            }
-        }
-        
-        Ok(ValidationResult::Accept)
-    }
-}
-```
-
-**Key Functions:**
+Implements handlers for Git Smart HTTP protocol:
 
 ```rust
-/// Parse ref updates from git-receive-pack request body
-fn parse_ref_updates(body: &[u8]) -> Result<Vec<RefUpdate>>
-
-/// Recursively find all maintainers
-fn get_maintainers(
-    events: &[Event],
-    pubkey: &str,
+/// Handle GET /info/refs?service=git-{upload,receive}-pack
+pub async fn handle_info_refs(
+    repo_path: PathBuf,
+    service: GitService,
+) -> Result<Response<Full<Bytes>>, GitError>
+
+/// Handle POST /git-upload-pack (clone/fetch)
+pub async fn handle_upload_pack(
+    repo_path: PathBuf,
+    body: Bytes,
+) -> Result<Response<Full<Bytes>>, GitError>
+
+/// Handle POST /git-receive-pack (push)
+/// THIS IS WHERE THE MAGIC HAPPENS - validates against state before accepting
+pub async fn handle_receive_pack(
+    repo_path: PathBuf,
+    body: Bytes,
+    database: SharedDatabase,
+    npub: &str,
     identifier: &str,
-) -> Vec<String>
-
-/// Get latest state from maintainer set
-fn get_state_from_maintainers(
-    events: &[Event],
-    maintainers: &[String],
-) -> Result<RepositoryState>
-
-/// Validate a ref matches the state event
-fn validate_state_ref(
-    state: &RepositoryState,
-    ref_update: &RefUpdate,
-) -> Result<()>
+) -> Result<Response<Full<Bytes>>, GitError>
 ```
 
-### 3. Nostr Module (`src/nostr/`)
+See [`src/git/handlers.rs:22-98`](src/git/handlers.rs:22-98) for the info-refs implementation.
 
-#### `relay.rs` - Relay Configuration
+#### [`authorization.rs`](src/git/authorization.rs) - Push Validation
 
-```rust
-pub async fn build_relay(config: &Config) -> Result<LocalRelay> {
-    let builder = RelayBuilder::default()
-        .write_policy(RepositoryAnnouncementPolicy::new(config.domain.clone()))
-        .write_policy(RelatedEventsPolicy::new())
-        .query_policy(StandardQueryPolicy::new())
-        .on_event_saved(create_repository_hook(config.git_data_path.clone()));
-    
-    // Configure storage backend (LMDB or NDB)
-    let relay = LocalRelay::run(builder).await?;
-    
-    Ok(relay)
-}
-```
-
-#### `events.rs` - Event Handlers
+**Core Logic:**
 
 ```rust
-/// Hook called when events are saved
-pub fn create_repository_hook(
-    git_data_path: PathBuf,
-) -> impl Fn(&Event) -> BoxFuture<'static, ()> {
-    move |event: &Event| {
-        let git_path = git_data_path.clone();
-        Box::pin(async move {
-            if event.kind == Kind::RepositoryAnnouncement {
-                handle_repository_announcement(event, &git_path).await;
-            } else if event.kind == Kind::RepositoryState {
-                handle_repository_state(event, &git_path).await;
-            }
-        })
-    }
-}
+/// Get authorization info for a repository owner
+pub async fn get_authorization_for_owner(
+    database: &SharedDatabase,
+    pubkey: &PublicKey,
+    identifier: &str,
+) -> Result<AuthorizationResult, AuthorizationError>
 
-async fn handle_repository_announcement(event: &Event, git_path: &Path) {
-    // 1. Parse repository from event
-    // 2. Check if listed in clone and relays tags
-    // 3. Create empty bare Git repository
-    // 4. Configure uploadpack.allowTipSHA1InWant
-    // 5. Configure uploadpack.allowUnreachable
-    // 6. Configure http.receivepack
-}
+/// Validate that pushed refs match the authorized state
+pub fn validate_push_refs(
+    pushed_refs: &[PushedRef],
+    state: &RepositoryState,
+) -> Result<(), AuthorizationError>
 
-async fn handle_repository_state(event: &Event, git_path: &Path) {
-    // 1. Parse state from event
-    // 2. Update repository HEAD if needed
-    // 3. Trigger proactive sync (GRASP-02)
-}
+/// Validate refs/nostr/<event-id> pushes
+pub fn validate_nostr_ref_pushes(
+    pushed_refs: &[PushedRef],
+    database: &SharedDatabase,
+) -> Result<(), AuthorizationError>
 ```
 
-**Write Policies:**
+### 4. Nostr Module ([`src/nostr/`](src/nostr/))
 
-```rust
-/// Accept repository announcements that list this instance
-pub struct RepositoryAnnouncementPolicy {
-    domain: String,
-}
-
-impl WritePolicy for RepositoryAnnouncementPolicy {
-    fn admit_event(&self, event: &Event, _addr: &SocketAddr) 
-        -> BoxFuture<PolicyResult> 
-    {
-        Box::pin(async move {
-            if event.kind != Kind::RepositoryAnnouncement {
-                return PolicyResult::Accept; // Not our concern
-            }
-            
-            // Check if this instance is in clone and relays tags
-            let has_clone = event.tags.iter()
-                .any(|t| t.kind() == "clone" && t.content() == Some(&self.domain));
-            let has_relay = event.tags.iter()
-                .any(|t| t.kind() == "relays" && t.content() == Some(&self.domain));
-            
-            if has_clone && has_relay {
-                PolicyResult::Accept
-            } else {
-                PolicyResult::Reject("instance not listed in clone and relays".into())
-            }
-        })
-    }
-}
+#### [`builder.rs`](src/nostr/builder.rs) - Relay Configuration
 
-/// Accept events related to stored announcements/issues/patches
-pub struct RelatedEventsPolicy;
+The [`Nip34WritePolicy`](src/nostr/builder.rs:51) is the core event validation logic:
 
-impl WritePolicy for RelatedEventsPolicy {
-    fn admit_event(&self, event: &Event, _addr: &SocketAddr) 
-        -> BoxFuture<PolicyResult> 
-    {
-        // Accept if event tags or is tagged by stored events
-        // Implementation requires querying the event store
-    }
+```rust
+/// NIP-34 Write Policy with Full GRASP-01 Event Validation
+///
+/// Validates all events according to GRASP-01 specification:
+/// - Repository announcements must list service in clone and relays tags
+///   EXCEPTION: Recursive maintainer announcements are accepted even without
+///   listing the service, to enable maintainer chain discovery and GRASP-02 sync
+/// - Repository state announcements must have valid structure
+/// - Other events must reference accepted repositories or events
+/// - Forward references are supported (events referenced by accepted events)
+/// - Orphan events with no valid references are rejected
+pub struct Nip34WritePolicy {
+    domain: String,
+    database: SharedDatabase,
+    git_data_path: PathBuf,
 }
 ```
 
-### 4. Storage Module (`src/storage/`)
+See [`src/nostr/builder.rs:38-78`](src/nostr/builder.rs:38-78) for the full policy struct.
 
-#### `repository.rs` - Repository Management
+#### [`events.rs`](src/nostr/events.rs) - Event Parsing
+
+Provides structures for parsing NIP-34 events:
 
 ```rust
-pub struct RepositoryManager {
-    git_data_path: PathBuf,
-}
+/// Parsed repository announcement (Kind 30617)
+pub struct RepositoryAnnouncement { ... }
 
-impl RepositoryManager {
-    /// Create a new bare Git repository
-    pub async fn create_repository(
-        &self,
-        npub: &str,
-        identifier: &str,
-    ) -> Result<PathBuf> {
-        let repo_path = self.git_data_path
-            .join(npub)
-            .join(format!("{}.git", identifier));
-        
-        // Create directory
-        tokio::fs::create_dir_all(&repo_path).await?;
-        
-        // Initialize bare repo
-        Command::new("git")
-            .args(&["init", "--bare"])
-            .arg(&repo_path)
-            .output()
-            .await?;
-        
-        // Configure
-        self.configure_repository(&repo_path).await?;
-        
-        Ok(repo_path)
-    }
-    
-    async fn configure_repository(&self, repo_path: &Path) -> Result<()> {
-        // Enable unauthenticated push (we handle auth ourselves)
-        git_config(repo_path, "http.receivepack", "true").await?;
-        
-        // Enable tip SHA1 fetching (required for ngit)
-        git_config(repo_path, "uploadpack.allowTipSHA1InWant", "true").await?;
-        
-        // Enable unreachable object fetching
-        git_config(repo_path, "uploadpack.allowUnreachable", "true").await?;
-        
-        Ok(())
-    }
-    
-    /// Check if repository exists
-    pub async fn repository_exists(
-        &self,
-        npub: &str,
-        identifier: &str,
-    ) -> bool {
-        let repo_path = self.git_data_path
-            .join(npub)
-            .join(format!("{}.git", identifier));
-        
-        repo_path.join("HEAD").exists() && 
-        repo_path.join("config").exists()
-    }
-}
+/// Parsed repository state (Kind 30618)  
+pub struct RepositoryState { ... }
 ```
 
-### 5. Configuration (`src/config.rs`)
+### 5. Configuration ([`src/config.rs`](src/config.rs))
 
 ```rust
 pub struct Config {
@@ -393,34 +243,18 @@ pub struct Config {
     pub git_data_path: PathBuf,
     pub relay_data_path: PathBuf,
     pub bind_address: SocketAddr,
-    pub log_level: String,
+    pub database_backend: DatabaseBackend,
 }
 
-impl Config {
-    pub fn from_env() -> Result<Self> {
-        Ok(Config {
-            domain: env::var("NGIT_DOMAIN")?,
-            owner_npub: env::var("NGIT_OWNER_NPUB")?,
-            relay_name: env::var("NGIT_RELAY_NAME")?,
-            relay_description: env::var("NGIT_RELAY_DESCRIPTION")?,
-            git_data_path: PathBuf::from(
-                env::var("NGIT_GIT_DATA_PATH")
-                    .unwrap_or_else(|_| "./data/git".to_string())
-            ),
-            relay_data_path: PathBuf::from(
-                env::var("NGIT_RELAY_DATA_PATH")
-                    .unwrap_or_else(|_| "./data/relay".to_string())
-            ),
-            bind_address: env::var("NGIT_BIND_ADDRESS")
-                .unwrap_or_else(|_| "127.0.0.1:8080".to_string())
-                .parse()?,
-            log_level: env::var("RUST_LOG")
-                .unwrap_or_else(|_| "info".to_string()),
-        })
-    }
+pub enum DatabaseBackend {
+    Lmdb,    // Default, production use
+    NostrDb, // Alternative
+    Memory,  // Testing
 }
 ```
 
+Configuration is loaded via **clap CLI > environment variables > .env > defaults**.
+
 ## Data Flow
 
 ### Push Operation Flow
@@ -428,327 +262,120 @@ impl Config {
 ```
 1. Git Client → POST /<npub>/<id>.git/git-receive-pack
                 ↓
-2. git_receive_pack handler receives request
+2. HttpService routes to git::handlers::handle_receive_pack()
                 ↓
-3. Parse ref updates from request body
+3. Parse ref updates from request body (pkt-line format)
                 ↓
 4. Extract npub and identifier from URL
                 ↓
-5. PushValidator::validate_push()
-   ├─ Fetch events from local Nostr relay
-   ├─ Get maintainers recursively
-   ├─ Get latest state from maintainers
-   └─ Validate each ref update
+5. authorization::get_authorization_for_owner()
+   ├─ Query database for announcements
+   ├─ Build recursive maintainer set
+   └─ Get latest authorized state
+                ↓
+6. authorization::validate_push_refs()
+   ├─ Check each ref matches state
+   └─ Validate refs/nostr/ pushes
                 ↓
-6. If VALID:
+7. If VALID:
    ├─ Spawn git-receive-pack subprocess
    ├─ Stream request body to git stdin
    └─ Stream git stdout back to client
                 ↓
-7. If INVALID:
+8. If INVALID:
    └─ Return HTTP 403 with error message
 ```
 
 ### Repository Announcement Flow
 
 ```
-1. Nostr Client → EVENT (Kind 30317)
+1. Nostr Client → EVENT (Kind 30617)
                 ↓
 2. Nostr relay receives event
                 ↓
-3. RepositoryAnnouncementPolicy::admit_event()
+3. Nip34WritePolicy::admit_event()
    ├─ Check if instance in clone tags
    ├─ Check if instance in relays tags
+   ├─ OR: Check if recursive maintainer
    └─ Accept or reject
                 ↓
 4. If ACCEPTED:
-   ├─ Event saved to store
-   └─ on_event_saved hook triggered
+   ├─ Event saved to database
+   └─ ensure_bare_repository() called
                 ↓
-5. handle_repository_announcement()
-   ├─ Parse repository details
-   ├─ Create Git repository directory
-   ├─ Initialize bare Git repo
-   └─ Configure Git settings
-```
-
-## Key Implementation Details
-
-### 1. Parsing Git Receive-Pack Protocol
-
-The Git receive-pack protocol uses a pkt-line format. We need to parse:
-
-```
-0000-0000-0000-0000 0000-0000-0000-0000 refs/heads/main\0 report-status
-0000-0000-0000-0000 0000-0000-0000-0000 refs/heads/dev
-```
-
-Each line has:
-- Old SHA (40 hex chars)
-- Space
-- New SHA (40 hex chars)
-- Space
-- Ref name
-- Optional capabilities (first line only, after \0)
-
-```rust
-pub struct RefUpdate {
-    pub old_sha: String,
-    pub new_sha: String,
-    pub ref_name: String,
-}
-
-pub fn parse_ref_updates(body: &[u8]) -> Result<Vec<RefUpdate>> {
-    // Parse pkt-line format
-    // Extract ref updates
-    // Return structured data
-}
+5. Bare Git repository created at
+   <git_data_path>/<npub>/<identifier>.git
 ```
 
-### 2. Maintainer Recursion
-
-The maintainer resolution must handle cycles and correctly build the set:
+### State Event Flow
 
-```rust
-fn get_maintainers_recursive(
-    events: &[Event],
-    pubkey: &str,
-    identifier: &str,
-    visited: &mut HashSet<String>,
-) -> HashSet<String> {
-    if visited.contains(pubkey) {
-        return HashSet::new();
-    }
-    
-    visited.insert(pubkey.to_string());
-    
-    let announcement = find_announcement(events, pubkey, identifier);
-    if announcement.is_none() {
-        return HashSet::new();
-    }
-    
-    let repo = parse_repository(announcement.unwrap());
-    
-    for maintainer in repo.maintainers {
-        get_maintainers_recursive(events, &maintainer, identifier, visited);
-    }
-    
-    visited.clone()
-}
 ```
-
-### 3. State Event Validation
-
-```rust
-fn validate_state_ref(
-    state: &RepositoryState,
-    ref_update: &RefUpdate,
-) -> Result<()> {
-    if ref_update.ref_name.starts_with("refs/heads/") {
-        let branch_name = &ref_update.ref_name[11..];
-        if let Some(commit) = state.branches.get(branch_name) {
-            if commit == &ref_update.new_sha {
-                return Ok(());
-            }
-            return Err(Error::StateMismatch {
-                ref_name: ref_update.ref_name.clone(),
-                expected: commit.clone(),
-                got: ref_update.new_sha.clone(),
-            });
-        }
-        return Err(Error::RefNotInState(ref_update.ref_name.clone()));
-    }
-    
-    if ref_update.ref_name.starts_with("refs/tags/") {
-        let tag_name = &ref_update.ref_name[10..];
-        if let Some(commit) = state.tags.get(tag_name) {
-            if commit == &ref_update.new_sha {
-                return Ok(());
-            }
-            return Err(Error::StateMismatch {
-                ref_name: ref_update.ref_name.clone(),
-                expected: commit.clone(),
-                got: ref_update.new_sha.clone(),
-            });
-        }
-        return Err(Error::RefNotInState(ref_update.ref_name.clone()));
-    }
-    
-    Err(Error::InvalidRef(ref_update.ref_name.clone()))
-}
-```
-
-### 4. CORS Support
-
-As per GRASP-01, we must support CORS:
-
-```rust
-use actix_cors::Cors;
-
-fn configure_cors() -> Cors {
-    Cors::default()
-        .allow_any_origin()
-        .allowed_methods(vec!["GET", "POST", "OPTIONS"])
-        .allowed_headers(vec!["Content-Type"])
-        .max_age(3600)
-}
-
-// In main.rs
-App::new()
-    .wrap(configure_cors())
-    .configure(git_routes)
-    .configure(nostr_routes)
+1. Nostr Client → EVENT (Kind 30618)
+                ↓
+2. Nostr relay receives event
+                ↓
+3. Nip34WritePolicy::admit_event()
+   ├─ Check author is in maintainer set
+   ├─ Validate state structure
+   └─ Accept or reject
+                ↓
+4. If ACCEPTED and is latest state:
+   ├─ Align repository refs to match state
+   ├─ Create/update/delete refs as needed
+   └─ Set HEAD if commit available
 ```
 
 ## Testing Strategy
 
-See [TEST_STRATEGY.md](TEST_STRATEGY.md) for comprehensive testing documentation, including:
-
-- **GRASP Compliance Testing Tool**: Reusable test suite that validates any GRASP implementation against the spec
-- **Spec-Mirrored Tests**: Test structure matches GRASP protocol documents exactly
-- **Clear Failure Messages**: Test failures cite exact spec lines (e.g., "GRASP-01:12-13")
-- **Multiple Test Levels**: Unit, integration, compliance, and end-to-end tests
+See [test-strategy.md](../reference/test-strategy.md) for comprehensive testing documentation.
 
 ### Quick Overview
 
-```rust
-// Unit Tests - Individual functions
-#[test]
-fn test_parse_ref_updates() {
-    let body = b"0000... 0000... refs/heads/main\0report-status\n";
-    let updates = parse_ref_updates(body).unwrap();
-    assert_eq!(updates.len(), 1);
-    assert_eq!(updates[0].ref_name, "refs/heads/main");
-}
+**Integration Tests** ([`tests/`](tests/)):
+- Use [`TestRelay`](tests/common/relay.rs:14) fixture for automatic relay lifecycle
+- Each test file in [`tests/`](tests/) covers a GRASP-01 requirement
 
-// Integration Tests - Component interaction
-#[tokio::test]
-async fn test_full_push_flow() {
-    let app = test_app().await;
-    let (announcement, state) = app.create_repo_with_state()
-        .branch("main", "commit-123")
-        .build()
-        .await;
-    
-    let result = app.git_push("main", "commit-123").await;
-    assert!(result.success);
-}
+**Audit Tests** ([`grasp-audit/`](grasp-audit/)):
+- Reusable compliance testing for any GRASP implementation
+- Spec-mirrored structure in [`grasp-audit/src/specs/grasp01/`](grasp-audit/src/specs/grasp01/)
 
-// Compliance Tests - GRASP spec validation
+```rust
+// Example: tests/nip01_compliance.rs
 #[tokio::test]
-async fn test_grasp_01_compliance() {
-    use grasp_compliance_tests::{TestContext, Grasp01Spec};
-    
-    let ctx = TestContext::builder()
-        .base_url(&server.url())
-        .build();
-    
-    let results = Grasp01Spec::test_compliance(&ctx).await;
-    assert!(results.all_passed(), "{}", results.report());
+async fn test_nip01_websocket_connection() {
+    let relay = TestRelay::start().await;
+    // Test NIP-01 compliance...
+    relay.stop().await;
 }
 ```
 
-The compliance testing tool is designed as a **standalone crate** that can be:
-- Used by ngit-grasp for self-validation
-- Published for other GRASP implementations to use
-- Updated as new GRASP specs are released
-- Run in CI/CD for continuous compliance verification
-
 ## Performance Considerations
 
 ### 1. Async All The Way
 
 - Use `tokio` for all I/O
-- Non-blocking Git subprocess spawning
+- Non-blocking Git subprocess spawning via [`GitSubprocess`](src/git/subprocess.rs)
 - Stream large pack files without buffering
 
-### 2. Connection Pooling
-
-- Reuse Nostr relay connections
-- Connection pool for internal relay queries
-
-### 3. Caching
+### 2. Shared Database
 
-- Cache parsed state events (with TTL)
-- Cache maintainer sets
-- Invalidate on new state events
+- Single database instance shared between relay and Git handlers
+- Direct queries for push authorization (no WebSocket round-trip)
 
-```rust
-pub struct StateCache {
-    cache: Arc<RwLock<HashMap<String, CachedState>>>,
-}
-
-struct CachedState {
-    state: RepositoryState,
-    maintainers: Vec<String>,
-    timestamp: Instant,
-}
+### 3. Write Policy Caching
 
-impl StateCache {
-    pub async fn get_or_fetch(
-        &self,
-        identifier: &str,
-        fetcher: impl Future<Output = Result<(RepositoryState, Vec<String>)>>,
-    ) -> Result<(RepositoryState, Vec<String>)> {
-        // Check cache
-        // Return if fresh
-        // Otherwise fetch and cache
-    }
-}
-```
+- Maintainer sets computed once per event validation
+- State lookups use database indexes
 
 ## Future Extensions
 
 ### GRASP-02: Proactive Sync
 
-Add background tasks:
-
-```rust
-pub struct ProactiveSyncTask {
-    relay_client: Client,
-    git_manager: RepositoryManager,
-}
-
-impl ProactiveSyncTask {
-    pub async fn run(&self) {
-        loop {
-            tokio::time::sleep(Duration::from_secs(3600)).await;
-            
-            // Fetch all announcements from our relay
-            let announcements = self.fetch_announcements().await;
-            
-            for ann in announcements {
-                // Sync events from listed relays
-                self.sync_events(&ann).await;
-                
-                // Sync git data from listed clones
-                self.sync_git_data(&ann).await;
-                
-                // Fetch PR data
-                self.sync_pr_data(&ann).await;
-            }
-        }
-    }
-}
-```
+See [grasp-02-proactive-sync.md](grasp-02-proactive-sync.md) for detailed design.
 
 ### GRASP-05: Archive
 
-Relax the policy:
-
-```rust
-pub struct ArchiveAnnouncementPolicy;
-
-impl WritePolicy for ArchiveAnnouncementPolicy {
-    fn admit_event(&self, event: &Event, _addr: &SocketAddr) 
-        -> BoxFuture<PolicyResult> 
-    {
-        // Accept all repository announcements
-        // Don't check clone/relays tags
-        PolicyResult::Accept
-    }
-}
-```
+Relax the write policy to accept all repository announcements regardless of clone/relays tags.
 
 ## Deployment
 
@@ -756,7 +383,7 @@ impl WritePolicy for ArchiveAnnouncementPolicy {
 
 ```bash
 cargo build --release
-./target/release/ngit-grasp
+./target/release/ngit-grasp --domain example.com --owner-npub npub1...
 ```
 
 ### Docker
@@ -799,10 +426,17 @@ WantedBy=multi-user.target
 2. **Path Traversal**: Prevent directory traversal in repository paths
 3. **DoS Protection**: Rate limiting on both HTTP and WebSocket
 4. **Resource Limits**: Limit pack file sizes, event sizes
-5. **Nostr Event Validation**: Strict signature verification
+5. **Nostr Event Validation**: Strict signature verification (handled by nostr-relay-builder)
 
 ## Conclusion
 
-The inline authorization approach provides a cleaner, more maintainable architecture than hook-based authorization while maintaining full GRASP-01 compliance. The Rust ecosystem provides excellent libraries for both Git and Nostr protocols, enabling a high-performance, type-safe implementation.
+The inline authorization approach provides a cleaner, more maintainable architecture than hook-based authorization while maintaining full GRASP-01 compliance. Using Hyper for the HTTP layer gives us complete control over request handling, WebSocket upgrades, and CORS headers.
 
 The key insight is that we don't need to rely on Git's hook mechanism when we have full control over the HTTP layer that Git operates through. By intercepting at the HTTP handler level, we gain better error handling, easier testing, and tighter integration between the Git and Nostr components.
+
+## Related Documentation
+
+- [Inline Authorization Explanation](inline-authorization.md) - Why we chose this approach
+- [GRASP-02 Proactive Sync](grasp-02-proactive-sync.md) - Future work design
+- [Test Strategy](../reference/test-strategy.md) - Comprehensive testing documentation
+- [GRASP-01 Implementation Learnings](../learnings/grasp-01-implementation.md) - Patterns and lessons learned
\ No newline at end of file
diff --git a/docs/explanation/inline-authorization.md b/docs/explanation/inline-authorization.md
index 98f6e5a..4538602 100644
--- a/docs/explanation/inline-authorization.md
+++ b/docs/explanation/inline-authorization.md
@@ -150,14 +150,17 @@ rm -rf /tmp/test-repo
 ```rust
 #[tokio::test]
 async fn test_unauthorized_push() {
-    let state = create_test_state().await;
+    let relay = TestRelay::start().await;
     let result = validate_push(&state, "refs/heads/main", alice_pubkey).await;
     assert!(result.is_err());
+    relay.stop().await;
 }
 ```
 
 **Result:** Pure Rust unit tests, no shell scripts, no Git setup.
 
+See [`tests/push_authorization.rs`](tests/push_authorization.rs) for actual test examples.
+
 ### 4. Shared State and Types
 
 **With hooks:**
@@ -168,19 +171,17 @@ async fn test_unauthorized_push() {
 
 **With inline authorization:**
 ```rust
-pub struct GitHandler {
-    nostr_relay: Arc<NostrRelay>,  // Shared!
-    state_cache: Arc<StateCache>,   // Shared!
-}
-
-impl GitHandler {
-    async fn validate_push(&self, refs: &[RefUpdate]) -> Result<()> {
-        // Direct access to Nostr state
-        let state = self.state_cache.get_latest().await?;
-        // Validate using shared types
-        state.validate_refs(refs)?;
-        Ok(())
-    }
+// From src/git/handlers.rs
+pub async fn handle_receive_pack(
+    repo_path: PathBuf,
+    body: Bytes,
+    database: SharedDatabase,  // Shared with Nostr relay!
+    npub: &str,
+    identifier: &str,
+) -> Result<Response<Full<Bytes>>, GitError> {
+    // Direct database access for authorization
+    let auth = get_authorization_for_owner(&database, pubkey, identifier).await?;
+    // ...
 }
 ```
 
@@ -208,9 +209,9 @@ Setup steps:
 **With inline authorization (ngit-grasp):**
 ```
 Single Rust binary:
-  - HTTP server (actix-web)
+  - HTTP server (Hyper)
   - Git protocol handler
-  - Nostr relay
+  - Nostr relay (nostr-relay-builder)
   - Authorization logic
   
 Setup steps:
@@ -235,44 +236,38 @@ Content-Type: application/x-git-receive-pack-request
 0000000000000000000000000000000000000000 abc123... refs/heads/main\0 report-status
 ```
 
-We parse this **before** spawning Git:
+We parse this **before** spawning Git. See [`src/git/authorization.rs`](src/git/authorization.rs) for the implementation:
 
 ```rust
-pub async fn git_receive_pack(
-    req: HttpRequest,
-    body: web::Bytes,
-) -> Result<HttpResponse, Error> {
-    // 1. Parse ref updates from request body
-    let ref_updates = parse_ref_updates(&body)?;
-    
-    // 2. Validate against Nostr state
-    let state = get_latest_state(&repo).await?;
-    validate_push(&state, &ref_updates).await?;
-    
-    // 3. If valid, spawn git-receive-pack
-    spawn_git_receive_pack(req, body).await
+/// Parse ref updates from git-receive-pack request body
+pub fn parse_pushed_refs(body: &[u8]) -> Result<Vec<PushedRef>, AuthorizationError> {
+    // Parse pkt-line format
+    // Extract ref updates
+    // Return structured data
 }
 ```
 
 ### How We Validate
 
-Validation checks:
+Validation checks (from [`src/git/authorization.rs`](src/git/authorization.rs)):
+
 1. Does pusher's pubkey have write access?
 2. Are they listed as a maintainer in the latest state event?
-3. Do maintainer sets form a valid chain?
+3. Do the refs match the state event?
 
 ```rust
-async fn validate_push(
-    state: &RepoState,
-    refs: &[RefUpdate],
-) -> Result<()> {
-    for ref_update in refs {
-        // Check if pusher is authorized for this ref
-        if !state.is_authorized(&ref_update.name, pusher_pubkey) {
-            return Err(Error::Unauthorized {
-                ref_name: ref_update.name.clone(),
-                pubkey: pusher_pubkey,
-            });
+/// Validate that pushed refs match the authorized state
+pub fn validate_push_refs(
+    pushed_refs: &[PushedRef],
+    state: &RepositoryState,
+) -> Result<(), AuthorizationError> {
+    for pushed_ref in pushed_refs {
+        if pushed_ref.ref_name.starts_with("refs/heads/") {
+            // Validate branch against state
+        } else if pushed_ref.ref_name.starts_with("refs/tags/") {
+            // Validate tag against state
+        } else if pushed_ref.ref_name.starts_with("refs/nostr/") {
+            // Allow refs/nostr/<event-id> for PRs
         }
     }
     Ok(())
@@ -291,7 +286,7 @@ async fn validate_push(
 | **Performance** | Spawns Git first | Validates first |
 | **Testing** | Shell scripts + Go tests | Pure Rust tests |
 | **Deployment** | Docker + supervisord | Single binary |
-| **State sharing** | WebSocket query | Direct memory access |
+| **State sharing** | WebSocket query | Direct database access |
 
 Both are GRASP-compliant, but inline authorization is simpler and more efficient.
 
@@ -314,34 +309,25 @@ Both are GRASP-compliant, but inline authorization is simpler and more efficient
 ### Is It Worth It?
 
 **Yes**, because:
-1. The `git-http-backend` crate handles protocol parsing
+1. We handle protocol parsing in [`src/git/protocol.rs`](src/git/protocol.rs)
 2. GRASP is already non-standard (Nostr authorization)
 3. Benefits far outweigh the coupling cost
 4. We can still add hook support later if needed
 
 ---
 
-## Alternative Considered: Hybrid Approach
-
-We could use **both** inline validation and hooks:
-
-```rust
-// Inline: Fast path for common cases
-if !quick_validate(pusher).await? {
-    return Err(Error::Unauthorized);
-}
-
-// Hook: Detailed validation
-spawn_git_with_hook().await?;
-```
+## Implementation References
 
-**Why we didn't choose this:**
-- Added complexity
-- Redundant validation
-- Slower (two validation steps)
-- Harder to maintain
+Key files in the ngit-grasp implementation:
 
-If inline validation is sufficient, why add hooks?
+| Component | Location |
+|-----------|----------|
+| HTTP routing | [`src/http/mod.rs`](src/http/mod.rs) |
+| Git handlers | [`src/git/handlers.rs`](src/git/handlers.rs) |
+| Push authorization | [`src/git/authorization.rs`](src/git/authorization.rs) |
+| Git protocol parsing | [`src/git/protocol.rs`](src/git/protocol.rs) |
+| Subprocess management | [`src/git/subprocess.rs`](src/git/subprocess.rs) |
+| Event acceptance policy | [`src/nostr/builder.rs:51`](src/nostr/builder.rs:51) - `Nip34WritePolicy` |
 
 ---
 
@@ -365,9 +351,8 @@ This would allow:
 
 ### If Git Protocol Changes
 
-The `git-http-backend` crate abstracts protocol details. If the Git protocol changes:
-- Update the crate dependency
-- Adjust our ref parsing if needed
+The protocol parsing is isolated in [`src/git/protocol.rs`](src/git/protocol.rs). If the Git protocol changes:
+- Update the protocol module
 - Tests will catch any breakage
 
 ---
@@ -380,11 +365,11 @@ The `git-http-backend` crate abstracts protocol details. If the Git protocol cha
 2. It's more performant (early rejection)
 3. It's easier to test (pure Rust)
 4. It's simpler to deploy (single binary)
-5. It enables better integration (shared state)
+5. It enables better integration (shared database)
 
 The trade-off (coupling to Git HTTP protocol) is acceptable because:
 - The protocol is stable and well-specified
-- The `git-http-backend` crate abstracts details
+- Protocol handling is isolated in one module
 - Benefits far outweigh the cost
 
 This decision aligns with our goal of creating a **developer-friendly, production-ready GRASP implementation**.
@@ -397,7 +382,8 @@ This decision aligns with our goal of creating a **developer-friendly, productio
 - [Design Decisions](decisions.md) - All architectural choices
 - [Comparison with ngit-relay](comparison.md) - Detailed comparison
 - [Git Protocol Reference](../reference/git-protocol.md) - Protocol details
+- [Test Strategy](../reference/test-strategy.md) - How we test this
 
 ---
 
-*Part of the [ngit-grasp explanation docs](./)*
+*Part of the [ngit-grasp explanation docs](./)*
\ No newline at end of file
diff --git a/docs/learnings/grasp-audit.md b/docs/learnings/grasp-audit.md
index 14e5a2b..f4620d9 100644
--- a/docs/learnings/grasp-audit.md
+++ b/docs/learnings/grasp-audit.md
@@ -1,13 +1,13 @@
 # GRASP Audit Tool - Patterns and Learnings
 
 **Purpose:** Document grasp-audit architecture, patterns, and lessons learned  
-**Last Updated:** November 4, 2025
+**Last Updated:** December 4, 2025
 
 ---
 
 ## Overview
 
-`grasp-audit` is a compliance testing tool for GRASP (Git Relays Authorized via Signed-Nostr Proofs) protocol implementations. It tests both Nostr relay compliance (NIP-01) and GRASP-specific functionality.
+`grasp-audit` is a **fully implemented** compliance testing tool for GRASP (Git Relays Authorized via Signed-Nostr Proofs) protocol implementations. It tests both Nostr relay compliance (NIP-01) and GRASP-specific functionality.
 
 ---
 
@@ -32,10 +32,10 @@
 
 **Problem:** Test events pollute the relay and need cleanup without deletion events.
 
-**Solution:** Use special tags to mark audit events:
+**Solution:** Use special tags to mark audit events (implemented in [`grasp-audit/src/audit.rs`](grasp-audit/src/audit.rs)):
 
 ```rust
-// Every audit event includes these tags
+// Every audit event includes these tags (added automatically)
 [
     ["t", "grasp-audit-test-event"],           // Marker
     ["t", "audit-{run-id}"],                   // Run isolation
@@ -78,6 +78,8 @@
 
 ### Audit Configuration
 
+From [`grasp-audit/src/audit.rs`](grasp-audit/src/audit.rs):
+
 ```rust
 use grasp_audit::audit::AuditConfig;
 
@@ -101,100 +103,41 @@ let config = AuditConfig::shared();
 
 ### Creating Audit Events
 
-```rust
-use grasp_audit::audit::{AuditConfig, AuditEventBuilder};
-use nostr_sdk::prelude::*;
-
-let config = AuditConfig::isolated();
-let keys = Keys::generate();
-
-// Create audit event
-let event = AuditEventBuilder::new(&config, Kind::TextNote, "test content")
-    .build(&keys)?;
-
-// Event automatically includes:
-// - Audit marker tag
-// - Run ID tag
-// - Cleanup timestamp tag
-```
-
----
-
-### Querying Audit Events
+From [`grasp-audit/src/client.rs`](grasp-audit/src/client.rs):
 
 ```rust
 use grasp_audit::client::AuditClient;
 use grasp_audit::audit::AuditConfig;
 
 let config = AuditConfig::isolated();
-let client = AuditClient::new(config, keys);
-
-// Connect to relay
-client.add_relay("ws://localhost:7000").await?;
-client.connect().await;
-
-// Query audit events for this run
-let events = client.query().await?;
-
-// Events are filtered by:
-// - "grasp-audit-test-event" marker
-// - Current run ID
-```
-
----
-
-### Test Isolation
-
-**Each test run is isolated by unique run ID:**
-
-```rust
-// CI mode generates unique UUID per run
-let config1 = AuditConfig::isolated();
-let config2 = AuditConfig::isolated();
-
-// config1.run_id != config2.run_id
-// Tests won't interfere with each other
-```
-
-**Benefits:**
+let client = AuditClient::new("ws://localhost:8080", config).await?;
 
-- ✅ Parallel CI/CD runs don't conflict
-- ✅ Can run multiple test suites simultaneously
-- ✅ Easy to identify which run created which events
-- ✅ Cleanup can target specific runs
-
----
-
-### Cleanup Strategy
-
-**Two-phase cleanup:**
-
-1. **Automatic expiry** via cleanup timestamp tag
-2. **Manual cleanup** by querying and deleting
-
-```rust
-// Events include cleanup timestamp
-["t", "audit-cleanup-after-1730707200"]
+// Create and send an event - cleanup tags are added automatically
+let event = client.event_builder()
+    .kind(Kind::TextNote)
+    .content("test content")
+    .build(&keys)?;
 
-// Cleanup process:
-// 1. Query events with expired cleanup timestamp
-// 2. Delete from database directly (no KIND 5)
-// 3. Avoid deletion event pollution
+client.send_event(event).await?;
 ```
 
-**Implementation:** To be built in relay (not in audit tool)
-
 ---
 
-## Testing Strategy
+### Test Suites
 
-### Test Organization
+From [`grasp-audit/src/specs/grasp01/mod.rs`](grasp-audit/src/specs/grasp01/mod.rs):
 
 ```
-grasp-audit/src/specs/
-├── nip01_smoke.rs      # NIP-01 basic functionality
-├── grasp_01_relay.rs   # GRASP-01 relay requirements (planned)
-└── mod.rs              # Test suite registry
+grasp-audit/src/specs/grasp01/
+├── mod.rs                    # Module exports
+├── nip01_smoke.rs            # NIP-01 basic functionality
+├── nip11_document.rs         # NIP-11 document tests
+├── event_acceptance_policy.rs # GRASP-01 event rules
+├── cors.rs                   # CORS header tests
+├── git_clone.rs              # Git clone operations
+├── push_authorization.rs     # Push validation tests
+├── repository_creation.rs    # Repository lifecycle
+└── spec_requirements.rs      # Requirement definitions
 ```
 
 ### Unit vs Integration Tests
@@ -229,17 +172,18 @@ mod tests {
 
 ```bash
 # Unit tests (fast, no dependencies)
-cargo test --lib
+cd grasp-audit && nix develop -c cargo test --lib
 
-# Integration tests (requires relay)
-docker run --rm -p 7000:7000 scsibug/nostr-rs-relay
-cargo test -- --ignored
+# Integration tests (requires relay via test-ngit-relay.sh)
+cd grasp-audit && nix develop -c bash test-ngit-relay.sh --mode test
 ```
 
 ---
 
 ### Test Result Reporting
 
+From [`grasp-audit/src/result.rs`](grasp-audit/src/result.rs):
+
 ```rust
 use grasp_audit::result::AuditResult;
 
@@ -255,7 +199,7 @@ for result in &results {
 }
 
 // Summary
-let passed = results.iter().filter(|r| r.is_pass()).count();
+let passed = results.iter().filter(|r| r.passed).count();
 let total = results.len();
 println!("Results: {}/{} passed ({:.1}%)",
     passed, total, (passed as f64 / total as f64) * 100.0);
@@ -291,7 +235,7 @@ grasp-audit audit \
 grasp-audit audit \
   --relay wss://relay.example.com \
   --mode production \
-  --run-id "audit-2025-11-04" \
+  --run-id "audit-2025-12-04" \
   --verbose
 
 # Test all specs
@@ -366,25 +310,23 @@ let events = client.query().await?;
 
 ---
 
-## Future Enhancements
+## What's Implemented
 
-### Planned Features
-
-- [ ] **GRASP-01 Test Suite**: Repository announcement and state event tests
-- [ ] **Test Report Generation**: JSON/HTML output for CI/CD
-- [ ] **Performance Benchmarks**: Measure relay performance
-- [ ] **Relay Comparison**: Side-by-side compliance comparison
-- [ ] **Continuous Monitoring**: Periodic production audits
+### Completed Features
 
----
+- ✅ **GRASP-01 Test Suites**: All NIP-01, NIP-11, CORS, event acceptance tests
+- ✅ **Spec Requirements Database**: Machine-readable requirements in [`spec_requirements.rs`](grasp-audit/src/specs/grasp01/spec_requirements.rs)
+- ✅ **Automatic Cleanup Tags**: Production-safe event tagging
+- ✅ **Test Isolation**: UUID run IDs for parallel execution
+- ✅ **AuditClient**: Nostr client wrapper with audit features
+- ✅ **Fixture Helpers**: Event creation helpers in [`fixtures.rs`](grasp-audit/src/fixtures.rs)
 
-### Possible Improvements
+### Future Enhancements
 
-- [ ] **Parallel Test Execution**: Run specs in parallel
-- [ ] **Retry Logic**: Handle transient failures
-- [ ] **Custom Assertions**: Domain-specific test helpers
-- [ ] **Event Diff Tool**: Compare expected vs actual events
-- [ ] **Cleanup Automation**: Auto-cleanup after tests
+- [ ] **GRASP-02 Test Suite**: Proactive sync tests
+- [ ] **HTML Report Generation**: Rich CI/CD reports
+- [ ] **Performance Benchmarks**: Measure relay performance
+- [ ] **Relay Comparison**: Side-by-side compliance comparison
 
 ---
 
@@ -403,14 +345,12 @@ let events = client.query().await?;
 **Solution:**
 
 ```bash
-# Start relay
-docker run --rm -p 7000:7000 scsibug/nostr-rs-relay
-
-# Verify relay is running
-curl http://localhost:7000
+# Use test-ngit-relay.sh for automated relay management
+cd grasp-audit && nix develop -c bash test-ngit-relay.sh --mode test
 
-# Run tests
-cargo test -- --ignored
+# Or manually:
+docker run --rm -p 18081:8081 ghcr.io/danconwaydev/ngit-relay:latest
+RELAY_URL="ws://localhost:18081" nix develop -c cargo test --lib -- --ignored
 ```
 
 ---
@@ -471,46 +411,39 @@ let config = AuditConfig::isolated();
 let config = AuditConfig::shared();
 ```
 
-### Event Creation
-
-```rust
-let event = AuditEventBuilder::new(&config, kind, content)
-    .build(&keys)?;
-```
-
 ### Client Usage
 
 ```rust
-let client = AuditClient::new(config, keys);
-client.add_relay("ws://localhost:7000").await?;
-client.connect().await;
-let events = client.query().await?;
+let client = AuditClient::new("ws://localhost:7000", config).await?;
+assert!(client.is_connected().await);
 ```
 
 ### Running Tests
 
 ```bash
-# Unit tests
-cargo test --lib
+# Unit tests (from grasp-audit/)
+nix develop -c cargo test --lib
 
-# Integration tests
-cargo test -- --ignored
+# Integration tests with ngit-relay
+nix develop -c bash test-ngit-relay.sh --mode test
 
-# CLI
-cargo run -- audit --relay ws://localhost:7000
+# CLI audit
+nix develop -c cargo run -- audit --relay ws://localhost:7000
 ```
 
----
-
-## References
+### Key Files
 
-- **GRASP Protocol**: https://gitworkshop.dev/danconwaydev.com/grasp
-- **NIP-01**: https://github.com/nostr-protocol/nips/blob/master/01.md
-- **NIP-34**: https://github.com/nostr-protocol/nips/blob/master/34.md
-- **grasp-audit README**: `grasp-audit/README.md`
-- **Tag Migration**: `docs/archive/2025-11-04-tag-migration.md`
+| File | Purpose |
+|------|---------|
+| [`grasp-audit/src/lib.rs`](grasp-audit/src/lib.rs) | Public API |
+| [`grasp-audit/src/client.rs`](grasp-audit/src/client.rs) | AuditClient implementation |
+| [`grasp-audit/src/audit.rs`](grasp-audit/src/audit.rs) | AuditConfig, cleanup tags |
+| [`grasp-audit/src/specs/grasp01/mod.rs`](grasp-audit/src/specs/grasp01/mod.rs) | Test suite registry |
+| [`grasp-audit/src/specs/grasp01/spec_requirements.rs`](grasp-audit/src/specs/grasp01/spec_requirements.rs) | Requirement database |
 
 ---
 
-_Last updated: November 4, 2025_  
-_Status: Living document - update as grasp-audit evolves_
+## Related Documentation
+
+- [Test Strategy](../reference/test-strategy.md) - Overall testing approach
+- [GRASP-01 Implementation](grasp-01-implementation.md) - Main project learnings
\ No newline at end of file
diff --git a/docs/reference/test-strategy.md b/docs/reference/test-strategy.md
index cc1d5b0..7a31bdf 100644
--- a/docs/reference/test-strategy.md
+++ b/docs/reference/test-strategy.md
@@ -2,15 +2,15 @@
 
 ## Overview
 
-This document outlines the comprehensive testing strategy for ngit-grasp, including a **reusable GRASP compliance testing tool** that can validate any GRASP implementation against the protocol specification.
+This document describes the testing strategy for ngit-grasp, including the **grasp-audit** reusable compliance testing tool and the **integration tests** in the main repository.
 
 ## Testing Philosophy
 
-1. **Specification-Driven**: Tests mirror the GRASP protocol structure exactly
+1. **Specification-Driven**: Tests mirror GRASP-01 protocol structure exactly
 2. **Compliance-First**: Every requirement in the spec has a corresponding test
-3. **Reusable**: Compliance tests can validate any GRASP implementation
-4. **Clear Failures**: Test failures cite exact spec lines/sections
-5. **Comprehensive**: Unit, integration, and compliance testing
+3. **Reusable**: The grasp-audit tool can validate any GRASP implementation
+4. **Isolated**: Each test runs with its own relay instance via [`TestRelay`](tests/common/relay.rs:14)
+5. **Clear Failures**: Test failures cite exact spec requirements
 
 ## Test Pyramid
 
@@ -20,1219 +20,294 @@ This document outlines the comprehensive testing strategy for ngit-grasp, includ
                   ╱ E2E╲              ~ 10%  End-to-end with real Git
                  ╱──────╲
                 ╱        ╲
-               ╱Compliance╲           ~ 20%  GRASP spec validation
-              ╱────────────╲
+               ╱Compliance╲           ~ 30%  GRASP-01 spec validation
+              ╱────────────╲                  (grasp-audit)
              ╱              ╲
             ╱  Integration   ╲        ~ 30%  Component interaction
-           ╱──────────────────╲
+           ╱──────────────────╲              (tests/)
           ╱                    ╲
-         ╱   Unit Tests         ╲     ~ 40%  Individual functions
-        ╱────────────────────────╲
+         ╱   Unit Tests         ╲     ~ 30%  Individual functions
+        ╱────────────────────────╲           (src/**/tests)
 ```
 
-## GRASP Compliance Testing Tool
+## Project Structure
 
-### Design Goals
-
-1. **Reusable**: Can test ngit-grasp or any other GRASP implementation
-2. **Spec-Mirrored**: Test structure matches GRASP protocol documents
-3. **Clear Reporting**: Failures cite exact spec requirements
-4. **Automated**: Can run in CI/CD
-5. **Extensible**: Easy to add new GRASP versions (GRASP-02, GRASP-05)
-
-### Project Structure
+### Actual Test Layout
 
 ```
-grasp-compliance-tests/
-├── Cargo.toml                    # Standalone crate
-├── README.md                     # Usage instructions
-├── src/
-│   ├── lib.rs                    # Public API
-│   ├── client.rs                 # Test client utilities
-│   ├── assertions.rs             # Spec-based assertions
-│   └── specs/
-│       ├── mod.rs                # Spec registry
-│       ├── grasp_01.rs           # GRASP-01 tests
-│       ├── grasp_02.rs           # GRASP-02 tests
-│       └── grasp_05.rs           # GRASP-05 tests
-├── fixtures/
-│   ├── repos/                    # Test repositories
-│   ├── events/                   # Nostr event fixtures
-│   └── keys/                     # Test keypairs
-└── examples/
-    └── test_implementation.rs    # Example usage
+ngit-grasp/
+├── tests/                          # Integration tests for ngit-grasp
+│   ├── common/
+│   │   ├── mod.rs                  # Test utilities module
+│   │   └── relay.rs                # TestRelay fixture
+│   ├── nip01_compliance.rs         # NIP-01 relay compliance
+│   ├── nip11_document.rs           # NIP-11 document tests
+│   ├── nip34_announcements.rs      # Repository announcement tests
+│   ├── repository_creation.rs      # Git repo creation tests
+│   ├── push_authorization.rs       # Push validation tests
+│   ├── cors.rs                     # CORS header tests
+│   └── git_clone.rs                # Git clone tests
+│
+└── grasp-audit/                    # Reusable GRASP compliance tool
+    ├── Cargo.toml
+    ├── flake.nix
+    └── src/
+        ├── lib.rs                  # Public API
+        ├── client.rs               # AuditClient
+        ├── audit.rs                # AuditConfig, cleanup tags
+        ├── fixtures.rs             # Test fixtures
+        └── specs/
+            └── grasp01/            # GRASP-01 specification tests
+                ├── mod.rs          # Module exports
+                ├── nip01_smoke.rs  # NIP-01 smoke tests
+                ├── nip11_document.rs
+                ├── event_acceptance_policy.rs
+                ├── cors.rs
+                ├── git_clone.rs
+                ├── push_authorization.rs
+                ├── repository_creation.rs
+                └── spec_requirements.rs  # Requirement definitions
 ```
 
-### Spec-Mirrored Test Structure
+## Integration Tests (tests/)
+
+### TestRelay Fixture
 
-Each GRASP spec document maps to a test module with identical structure:
+The [`TestRelay`](tests/common/relay.rs:14) fixture provides automatic relay lifecycle management:
 
 ```rust
-// src/specs/grasp_01.rs
-
-use crate::{TestContext, SpecRequirement, ComplianceResult};
-
-/// GRASP-01 - Core Service Requirements
-/// Reference: https://gitworkshop.dev/danconwaydev.com/grasp/01.md
-pub struct Grasp01Spec;
-
-impl Grasp01Spec {
-    /// Run all GRASP-01 compliance tests
-    pub async fn test_compliance(ctx: &TestContext) -> ComplianceResult {
-        let mut results = ComplianceResult::new("GRASP-01");
-        
-        // Section: Nostr Relay
-        results.add(Self::test_nostr_relay_nip01_compliance(ctx).await);
-        results.add(Self::test_accepts_repository_announcements(ctx).await);
-        results.add(Self::test_accepts_repository_state_announcements(ctx).await);
-        results.add(Self::test_rejects_unlisted_announcements(ctx).await);
-        results.add(Self::test_accepts_related_events(ctx).await);
-        results.add(Self::test_serves_nip11_document(ctx).await);
-        results.add(Self::test_nip11_has_supported_grasps(ctx).await);
-        results.add(Self::test_nip11_has_repo_acceptance_criteria(ctx).await);
-        results.add(Self::test_nip11_has_curation_policy(ctx).await);
-        
-        // Section: Git Smart HTTP Service
-        results.add(Self::test_serves_git_at_correct_path(ctx).await);
-        results.add(Self::test_accepts_matching_pushes(ctx).await);
-        results.add(Self::test_rejects_mismatched_pushes(ctx).await);
-        results.add(Self::test_respects_recursive_maintainers(ctx).await);
-        results.add(Self::test_sets_head_from_state(ctx).await);
-        results.add(Self::test_accepts_nostr_refs(ctx).await);
-        results.add(Self::test_rejects_pr_branches(ctx).await);
-        results.add(Self::test_deletes_orphaned_nostr_refs(ctx).await);
-        results.add(Self::test_allows_reachable_sha1_in_want(ctx).await);
-        results.add(Self::test_allows_tip_sha1_in_want(ctx).await);
-        results.add(Self::test_serves_webpage(ctx).await);
-        
-        // Section: CORS Support
-        results.add(Self::test_cors_allow_origin(ctx).await);
-        results.add(Self::test_cors_allow_methods(ctx).await);
-        results.add(Self::test_cors_allow_headers(ctx).await);
-        results.add(Self::test_cors_options_request(ctx).await);
-        
-        results
-    }
-    
-    // ================================================================
-    // NOSTR RELAY TESTS
-    // ================================================================
-    
-    /// MUST serve a NIP-01 compliant nostr relay at `/`
-    /// 
-    /// Spec: GRASP-01, Line 9-10
-    /// > MUST serve a [NIP-01](https://nips.nostr.com/1) compliant nostr 
-    /// > relay at `/` that accepts [git repository announcements]...
-    async fn test_nostr_relay_nip01_compliance(ctx: &TestContext) -> TestResult {
-        TestResult::new(
-            "nostr_relay_nip01_compliance",
-            "GRASP-01:9-10",
-            "MUST serve a NIP-01 compliant nostr relay at `/`",
-        )
-        .run(async {
-            // Test WebSocket upgrade at /
-            let ws = ctx.connect_websocket("/").await?;
-            
-            // Test NIP-01 REQ/EVENT/CLOSE/NOTICE messages
-            ws.send_req("test-sub", vec![]).await?;
-            let response = ws.recv().await?;
-            assert_nip01_eose(response)?;
-            
-            Ok(())
-        })
-        .await
-    }
-    
-    /// MUST reject announcements that do not list the service in both 
-    /// `clone` and `relays` tags unless implementing `GRASP-05`
-    ///
-    /// Spec: GRASP-01, Line 12-13
-    /// > MUST reject [git repository announcements] that do not list the 
-    /// > service in both `clone` and `relays` tags unless implementing `GRASP-05`.
-    async fn test_rejects_unlisted_announcements(ctx: &TestContext) -> TestResult {
-        TestResult::new(
-            "rejects_unlisted_announcements",
-            "GRASP-01:12-13",
-            "MUST reject announcements not listing service in clone and relays",
-        )
-        .run(async {
-            let event = ctx.create_announcement()
-                .without_clone_tag(ctx.domain())
-                .build()
-                .await?;
-            
-            let result = ctx.send_event(event).await?;
-            
-            assert_eq!(
-                result.ok, false,
-                "Expected rejection of announcement without clone tag"
-            );
-            assert!(
-                result.message.contains("clone") || result.message.contains("relays"),
-                "Expected rejection message to mention clone/relays requirement"
-            );
-            
-            Ok(())
-        })
-        .await
-    }
-    
-    /// MUST accept other events that tag, or are tagged by, accepted announcements
-    ///
-    /// Spec: GRASP-01, Line 17-20
-    /// > MUST accept other events that tag, or are tagged by, either:
-    /// > 1. accepted [git repository announcements]; or
-    /// > 2. accepted [issues] or [patches]
-    async fn test_accepts_related_events(ctx: &TestContext) -> TestResult {
-        TestResult::new(
-            "accepts_related_events",
-            "GRASP-01:17-20",
-            "MUST accept events that tag or are tagged by accepted announcements",
-        )
-        .run(async {
-            // First, create and accept an announcement
-            let announcement = ctx.create_announcement()
-                .with_clone_tag(ctx.domain())
-                .with_relay_tag(ctx.domain())
-                .build()
-                .await?;
-            
-            ctx.send_event(announcement.clone()).await?;
-            
-            // Now send an issue that tags the announcement
-            let issue = ctx.create_issue()
-                .tag_announcement(&announcement)
-                .build()
-                .await?;
-            
-            let result = ctx.send_event(issue).await?;
-            
-            assert_eq!(
-                result.ok, true,
-                "Expected acceptance of issue tagging accepted announcement"
-            );
-            
-            Ok(())
-        })
-        .await
-    }
-    
-    /// MUST serve a NIP-11 document with required fields
-    ///
-    /// Spec: GRASP-01, Line 24-27
-    /// > MUST serve a [NIP-11] document:
-    /// > 1. MUST list each supported GRASP under `supported_grasps`
-    /// > 2. MUST list repository acceptance criteria under `repo_acceptance_criteria`
-    /// > 3. MUST list curation policy under `curation` if events are curated
-    async fn test_serves_nip11_document(ctx: &TestContext) -> TestResult {
-        TestResult::new(
-            "serves_nip11_document",
-            "GRASP-01:24-27",
-            "MUST serve a NIP-11 document",
-        )
-        .run(async {
-            let nip11 = ctx.fetch_nip11().await?;
-            
-            assert!(
-                nip11.contains_key("supported_nips"),
-                "NIP-11 document must have supported_nips"
-            );
-            
-            Ok(())
-        })
-        .await
-    }
-    
-    /// NIP-11 MUST list supported GRASPs
-    ///
-    /// Spec: GRASP-01, Line 25
-    /// > 1. MUST list each supported GRASP under `supported_grasps` 
-    /// >    in format `GRASP-XX` eg `GRASP-01` as a string array
-    async fn test_nip11_has_supported_grasps(ctx: &TestContext) -> TestResult {
-        TestResult::new(
-            "nip11_has_supported_grasps",
-            "GRASP-01:25",
-            "NIP-11 MUST list supported_grasps as string array",
-        )
-        .run(async {
-            let nip11 = ctx.fetch_nip11().await?;
-            
-            let grasps = nip11.get("supported_grasps")
-                .ok_or("NIP-11 missing supported_grasps field")?
-                .as_array()
-                .ok_or("supported_grasps must be an array")?;
-            
-            assert!(
-                grasps.iter().any(|g| g.as_str() == Some("GRASP-01")),
-                "supported_grasps must include 'GRASP-01'"
-            );
-            
-            // Validate format: GRASP-XX
-            for grasp in grasps {
-                let s = grasp.as_str().ok_or("GRASP must be a string")?;
-                assert!(
-                    s.starts_with("GRASP-") && s.len() >= 8,
-                    "GRASP format must be 'GRASP-XX', got: {}", s
-                );
-            }
-            
-            Ok(())
-        })
-        .await
-    }
-    
-    // ================================================================
-    // GIT SMART HTTP SERVICE TESTS
-    // ================================================================
-    
-    /// MUST serve a git repository via git smart http at /<npub>/<identifier>.git
-    ///
-    /// Spec: GRASP-01, Line 31-32
-    /// > MUST serve a git repository via an unauthenticated [git smart http service]
-    /// > at `/<npub>/<identifier>.git` for each accepted announcement
-    async fn test_serves_git_at_correct_path(ctx: &TestContext) -> TestResult {
-        TestResult::new(
-            "serves_git_at_correct_path",
-            "GRASP-01:31-32",
-            "MUST serve git at /<npub>/<identifier>.git",
-        )
-        .run(async {
-            // Create and send announcement
-            let announcement = ctx.create_announcement()
-                .with_identifier("test-repo")
-                .with_clone_tag(ctx.domain())
-                .with_relay_tag(ctx.domain())
-                .build()
-                .await?;
-            
-            let npub = announcement.author_npub();
-            ctx.send_event(announcement).await?;
-            
-            // Wait for repo creation
-            tokio::time::sleep(Duration::from_secs(2)).await;
-            
-            // Test git info/refs endpoint
-            let path = format!("/{}/test-repo.git/info/refs?service=git-upload-pack", npub);
-            let response = ctx.http_get(&path).await?;
-            
-            assert_eq!(
-                response.status(), 200,
-                "Git info/refs must return 200 OK"
-            );
-            
-            assert_eq!(
-                response.headers().get("content-type").unwrap(),
-                "application/x-git-upload-pack-advertisement",
-                "Git info/refs must have correct content-type"
-            );
-            
-            Ok(())
-        })
-        .await
-    }
-    
-    /// MUST accept pushes that match the latest state announcement
-    ///
-    /// Spec: GRASP-01, Line 34-35
-    /// > MUST accept pushes via this service that match the latest 
-    /// > [repo state announcement] on the relay, respecting the recursive maintainer set.
-    async fn test_accepts_matching_pushes(ctx: &TestContext) -> TestResult {
-        TestResult::new(
-            "accepts_matching_pushes",
-            "GRASP-01:34-35",
-            "MUST accept pushes matching latest state announcement",
-        )
-        .run(async {
-            // Setup: Create repo with announcement and state
-            let (announcement, state) = ctx.create_repo_with_state()
-                .branch("main", "a1b2c3d4...")
-                .build()
-                .await?;
-            
-            // Push matching state
-            let result = ctx.git_push(&announcement, "main", "a1b2c3d4...").await?;
-            
-            assert!(
-                result.success,
-                "Push matching state must succeed, got: {}", result.stderr
-            );
-            
-            Ok(())
-        })
-        .await
-    }
-    
-    /// MUST reject pushes that don't match the state announcement
-    ///
-    /// Spec: GRASP-01, Line 34-35 (inverse requirement)
-    /// Implied by "MUST accept pushes... that match"
-    async fn test_rejects_mismatched_pushes(ctx: &TestContext) -> TestResult {
-        TestResult::new(
-            "rejects_mismatched_pushes",
-            "GRASP-01:34-35",
-            "MUST reject pushes not matching state announcement",
-        )
-        .run(async {
-            // Setup: Create repo with state pointing to commit A
-            let (announcement, state) = ctx.create_repo_with_state()
-                .branch("main", "aaaa1111...")
-                .build()
-                .await?;
-            
-            // Try to push different commit B
-            let result = ctx.git_push(&announcement, "main", "bbbb2222...").await;
-            
-            assert!(
-                result.is_err() || !result.unwrap().success,
-                "Push not matching state must be rejected"
-            );
-            
-            Ok(())
-        })
-        .await
-    }
-    
-    /// MUST accept pushes to refs/nostr/<event-id>
-    ///
-    /// Spec: GRASP-01, Line 42-44
-    /// > MUST accept pushes via this service to `refs/nostr/<event-id>` but 
-    /// > SHOULD reject if event exists on relay listing a different tip
-    async fn test_accepts_nostr_refs(ctx: &TestContext) -> TestResult {
-        TestResult::new(
-            "accepts_nostr_refs",
-            "GRASP-01:42-44",
-            "MUST accept pushes to refs/nostr/<event-id>",
-        )
-        .run(async {
-            let (announcement, _) = ctx.create_repo_with_state().build().await?;
-            
-            // Create a PR event
-            let pr_event = ctx.create_pr_event()
-                .for_repo(&announcement)
-                .build()
-                .await?;
-            
-            let event_id = pr_event.id();
-            
-            // Push to refs/nostr/<event-id>
-            let result = ctx.git_push(
-                &announcement,
-                &format!("refs/nostr/{}", event_id),
-                "commit-sha..."
-            ).await?;
-            
-            assert!(
-                result.success,
-                "Push to refs/nostr/<event-id> must succeed"
-            );
-            
-            Ok(())
-        })
-        .await
-    }
-    
-    /// MUST reject pr/* branches
-    ///
-    /// Spec: GRASP-01, Line 42-44 (implied)
-    /// PRs should use refs/nostr/, not refs/heads/pr/*
-    async fn test_rejects_pr_branches(ctx: &TestContext) -> TestResult {
-        TestResult::new(
-            "rejects_pr_branches",
-            "GRASP-01:42-44",
-            "MUST reject refs/heads/pr/* (use refs/nostr/ instead)",
-        )
-        .run(async {
-            let (announcement, _) = ctx.create_repo_with_state().build().await?;
-            
-            // Try to push to pr/* branch
-            let result = ctx.git_push(
-                &announcement,
-                "refs/heads/pr/123",
-                "commit-sha..."
-            ).await;
-            
-            assert!(
-                result.is_err() || !result.unwrap().success,
-                "Push to refs/heads/pr/* must be rejected"
-            );
-            
-            Ok(())
-        })
-        .await
-    }
-    
-    /// MUST include allow-reachable-sha1-in-want and allow-tip-sha1-in-want
-    ///
-    /// Spec: GRASP-01, Line 48-49
-    /// > MUST include `allow-reachable-sha1-in-want` and `allow-tip-sha1-in-want` 
-    /// > in advertisement and serve available oids.
-    async fn test_allows_tip_sha1_in_want(ctx: &TestContext) -> TestResult {
-        TestResult::new(
-            "allows_tip_sha1_in_want",
-            "GRASP-01:48-49",
-            "MUST advertise and support allow-tip-sha1-in-want",
-        )
-        .run(async {
-            let (announcement, _) = ctx.create_repo_with_state()
-                .branch("main", "a1b2c3d4...")
-                .build()
-                .await?;
-            
-            // Fetch git capabilities
-            let caps = ctx.git_capabilities(&announcement).await?;
-            
-            assert!(
-                caps.contains("allow-tip-sha1-in-want"),
-                "Git advertisement must include allow-tip-sha1-in-want"
-            );
-            
-            assert!(
-                caps.contains("allow-reachable-sha1-in-want"),
-                "Git advertisement must include allow-reachable-sha1-in-want"
-            );
-            
-            Ok(())
-        })
-        .await
-    }
+// From tests/common/relay.rs
+
+/// Test relay fixture that manages relay lifecycle
+///
+/// Automatically starts and stops the ngit-grasp relay for testing.
+/// Uses a random port to avoid conflicts and cleans up created repositories.
+pub struct TestRelay {
+    process: Child,
+    url: String,
+    port: u16,
+}
+
+impl TestRelay {
+    /// Start a test relay instance
+    pub async fn start() -> Self { ... }
     
-    // ================================================================
-    // CORS SUPPORT TESTS
-    // ================================================================
+    /// Get the relay WebSocket URL
+    pub fn url(&self) -> &str { ... }
     
-    /// MUST set Access-Control-Allow-Origin: * on ALL responses
-    ///
-    /// Spec: GRASP-01, Line 57
-    /// > 1. Set `Access-Control-Allow-Origin: *` on ALL responses
-    async fn test_cors_allow_origin(ctx: &TestContext) -> TestResult {
-        TestResult::new(
-            "cors_allow_origin",
-            "GRASP-01:57",
-            "MUST set Access-Control-Allow-Origin: * on ALL responses",
-        )
-        .run(async {
-            let paths = vec![
-                "/",
-                "/test-npub/test-repo.git/info/refs?service=git-upload-pack",
-            ];
-            
-            for path in paths {
-                let response = ctx.http_get(path).await?;
-                
-                assert_eq!(
-                    response.headers().get("access-control-allow-origin").unwrap(),
-                    "*",
-                    "Path {} must have Access-Control-Allow-Origin: *", path
-                );
-            }
-            
-            Ok(())
-        })
-        .await
-    }
+    /// Get the relay domain (host:port)
+    pub fn domain(&self) -> String { ... }
     
-    /// MUST respond to OPTIONS requests with 204 No Content
-    ///
-    /// Spec: GRASP-01, Line 60
-    /// > 4. Respond to OPTIONS requests with 204 No Content
-    async fn test_cors_options_request(ctx: &TestContext) -> TestResult {
-        TestResult::new(
-            "cors_options_request",
-            "GRASP-01:60",
-            "MUST respond to OPTIONS with 204 No Content",
-        )
-        .run(async {
-            let response = ctx.http_options("/test-npub/test-repo.git/info/refs").await?;
-            
-            assert_eq!(
-                response.status(), 204,
-                "OPTIONS request must return 204 No Content"
-            );
-            
-            Ok(())
-        })
-        .await
-    }
+    /// Stop the relay
+    pub async fn stop(mut self) { ... }
 }
 ```
 
-### Test Result Reporting
+### Using TestRelay in Integration Tests
+
+From [`tests/nip01_compliance.rs`](tests/nip01_compliance.rs):
 
 ```rust
-/// Test result with spec citation
-pub struct TestResult {
-    pub name: String,
-    pub spec_ref: String,        // e.g., "GRASP-01:12-13"
-    pub requirement: String,      // Exact text from spec
-    pub passed: bool,
-    pub error: Option<String>,
-    pub duration: Duration,
-}
+use common::TestRelay;
+use grasp_audit::*;
 
-impl TestResult {
-    /// Create a new test result
-    pub fn new(name: &str, spec_ref: &str, requirement: &str) -> Self {
-        TestResult {
-            name: name.to_string(),
-            spec_ref: spec_ref.to_string(),
-            requirement: requirement.to_string(),
-            passed: false,
-            error: None,
-            duration: Duration::default(),
-        }
-    }
-    
-    /// Run the test
-    pub async fn run<F, Fut>(mut self, test_fn: F) -> Self 
-    where
-        F: FnOnce() -> Fut,
-        Fut: Future<Output = Result<(), String>>,
-    {
-        let start = Instant::now();
-        
-        match test_fn().await {
-            Ok(()) => {
-                self.passed = true;
-            }
-            Err(e) => {
-                self.passed = false;
-                self.error = Some(e);
-            }
-        }
-        
-        self.duration = start.elapsed();
-        self
-    }
-}
+/// Macro to generate isolated integration tests
+macro_rules! isolated_test {
+    ($test_name:ident) => {
+        #[tokio::test]
+        async fn $test_name() {
+            let relay = TestRelay::start().await;
+            let config = AuditConfig::isolated();
+            let client = AuditClient::new(relay.url(), config)
+                .await
+                .expect("Failed to create audit client");
 
-/// Collection of test results for a spec
-pub struct ComplianceResult {
-    pub spec: String,
-    pub results: Vec<TestResult>,
-}
+            let result = specs::Nip01SmokeTests::$test_name(&client).await;
+
+            relay.stop().await;
 
-impl ComplianceResult {
-    pub fn report(&self) -> String {
-        let mut output = String::new();
-        
-        output.push_str(&format!("\n{} Compliance Report\n", self.spec));
-        output.push_str(&"=".repeat(60));
-        output.push_str("\n\n");
-        
-        let passed = self.results.iter().filter(|r| r.passed).count();
-        let total = self.results.len();
-        
-        output.push_str(&format!("Results: {}/{} passed\n\n", passed, total));
-        
-        for result in &self.results {
-            let status = if result.passed { "✓" } else { "✗" };
-            
-            output.push_str(&format!(
-                "{} {} ({})\n",
-                status, result.name, result.spec_ref
-            ));
-            
-            output.push_str(&format!("  Requirement: {}\n", result.requirement));
-            
-            if let Some(error) = &result.error {
-                output.push_str(&format!("  Error: {}\n", error));
-            }
-            
-            output.push_str(&format!("  Duration: {:?}\n\n", result.duration));
+            assert!(
+                result.passed,
+                "{} failed: {}",
+                stringify!($test_name),
+                result.error.as_deref().unwrap_or("unknown error")
+            );
         }
-        
-        output
-    }
+    };
 }
-```
 
-### Usage Example
-
-```rust
-// examples/test_implementation.rs
-
-use grasp_compliance_tests::{TestContext, Grasp01Spec};
-
-#[tokio::main]
-async fn main() {
-    // Configure the implementation to test
-    let ctx = TestContext::builder()
-        .base_url("http://localhost:8080")
-        .websocket_url("ws://localhost:8080")
-        .domain("localhost:8080")
-        .build();
-    
-    // Run GRASP-01 compliance tests
-    let results = Grasp01Spec::test_compliance(&ctx).await;
-    
-    // Print report
-    println!("{}", results.report());
-    
-    // Exit with error if any tests failed
-    if !results.all_passed() {
-        std::process::exit(1);
-    }
-}
+// Generate isolated tests for all NIP-01 smoke tests
+isolated_test!(test_websocket_connection);
+isolated_test!(test_send_receive_event);
+isolated_test!(test_create_subscription);
 ```
 
-### Integration with ngit-grasp
+### Running Integration Tests
 
-In `ngit-grasp/tests/compliance.rs`:
+```bash
+# Run all integration tests
+cargo test --test '*'
 
-```rust
-use grasp_compliance_tests::{TestContext, Grasp01Spec};
+# Run specific test file
+cargo test --test nip01_compliance
 
-#[tokio::test]
-async fn test_grasp_01_compliance() {
-    // Start test server
-    let server = start_test_server().await;
-    
-    // Configure test context
-    let ctx = TestContext::builder()
-        .base_url(&server.url())
-        .websocket_url(&server.ws_url())
-        .domain(&server.domain())
-        .build();
-    
-    // Run compliance tests
-    let results = Grasp01Spec::test_compliance(&ctx).await;
-    
-    // Assert all tests passed
-    assert!(
-        results.all_passed(),
-        "GRASP-01 compliance failed:\n{}", 
-        results.report()
-    );
-}
+# Run with output
+cargo test --test nip01_compliance -- --nocapture
 ```
 
-## Unit Testing Strategy
+## GRASP Audit Tool (grasp-audit/)
 
-### Git Module Tests
+### Purpose
 
-```rust
-// src/git/parser.rs tests
+The grasp-audit tool is a **reusable GRASP compliance testing library** that can:
 
-#[cfg(test)]
-mod tests {
-    use super::*;
-    
-    #[test]
-    fn test_parse_pkt_line() {
-        let data = b"0006a\n";
-        let (length, payload) = parse_pkt_line(data).unwrap();
-        assert_eq!(length, 6);
-        assert_eq!(payload, b"a\n");
-    }
-    
-    #[test]
-    fn test_parse_flush_packet() {
-        let data = b"0000";
-        let result = parse_pkt_line(data).unwrap();
-        assert_eq!(result.0, 0);
-    }
-    
-    #[test]
-    fn test_parse_ref_updates() {
-        let body = b"00820000000000000000000000000000000000000000 \
-                     a1b2c3d4e5f6789012345678901234567890abcd \
-                     refs/heads/main\0 report-status\n\
-                     0000";
-        
-        let updates = parse_ref_updates(body).unwrap();
-        assert_eq!(updates.len(), 1);
-        assert_eq!(updates[0].ref_name, "refs/heads/main");
-    }
-}
-```
+- Test ngit-grasp for self-validation
+- Test any other GRASP implementation (like ngit-relay)
+- Run in CI/CD for continuous compliance verification
+- Generate compliance reports
 
-### Authorization Module Tests
+### Test Suites
 
-```rust
-// src/git/authorization.rs tests
+From [`grasp-audit/src/specs/grasp01/mod.rs`](grasp-audit/src/specs/grasp01/mod.rs):
 
-#[cfg(test)]
-mod tests {
-    use super::*;
-    
-    #[test]
-    fn test_get_maintainers_single() {
-        let events = vec![
-            create_test_announcement("alice", "repo1", vec![]),
-        ];
-        
-        let maintainers = get_maintainers(&events, "alice", "repo1");
-        assert_eq!(maintainers, vec!["alice"]);
-    }
-    
-    #[test]
-    fn test_get_maintainers_recursive() {
-        let events = vec![
-            create_test_announcement("alice", "repo1", vec!["bob"]),
-            create_test_announcement("bob", "repo1", vec![]),
-        ];
-        
-        let maintainers = get_maintainers(&events, "alice", "repo1");
-        assert!(maintainers.contains(&"alice".to_string()));
-        assert!(maintainers.contains(&"bob".to_string()));
-    }
-    
-    #[test]
-    fn test_get_maintainers_circular() {
-        let events = vec![
-            create_test_announcement("alice", "repo1", vec!["bob"]),
-            create_test_announcement("bob", "repo1", vec!["alice"]),
-        ];
-        
-        let maintainers = get_maintainers(&events, "alice", "repo1");
-        assert_eq!(maintainers.len(), 2);
-    }
-    
-    #[test]
-    fn test_validate_state_ref_matching() {
-        let state = RepositoryState {
-            branches: HashMap::from([
-                ("main".into(), "a1b2c3d4...".into()),
-            ]),
-            tags: HashMap::new(),
-        };
-        
-        let update = RefUpdate {
-            old_oid: "0000...".into(),
-            new_oid: "a1b2c3d4...".into(),
-            ref_name: "refs/heads/main".into(),
-        };
-        
-        assert!(validate_state_ref(&state, &update).is_ok());
-    }
-    
-    #[test]
-    fn test_validate_state_ref_mismatch() {
-        let state = RepositoryState {
-            branches: HashMap::from([
-                ("main".into(), "aaaa1111...".into()),
-            ]),
-            tags: HashMap::new(),
-        };
-        
-        let update = RefUpdate {
-            old_oid: "0000...".into(),
-            new_oid: "bbbb2222...".into(),
-            ref_name: "refs/heads/main".into(),
-        };
-        
-        assert!(validate_state_ref(&state, &update).is_err());
-    }
-}
-```
+| Suite | Description | Requirements |
+|-------|-------------|--------------|
+| [`Nip01SmokeTests`](grasp-audit/src/specs/grasp01/nip01_smoke.rs) | Basic NIP-01 relay functionality | WebSocket only |
+| [`Nip11DocumentTests`](grasp-audit/src/specs/grasp01/nip11_document.rs) | NIP-11 relay information document | WebSocket only |
+| [`EventAcceptancePolicyTests`](grasp-audit/src/specs/grasp01/event_acceptance_policy.rs) | Event acceptance rules | WebSocket only |
+| [`CorsTests`](grasp-audit/src/specs/grasp01/cors.rs) | CORS headers on Git HTTP endpoints | git-data-dir |
+| [`GitCloneTests`](grasp-audit/src/specs/grasp01/git_clone.rs) | Git clone operations | git-data-dir |
+| [`PushAuthorizationTests`](grasp-audit/src/specs/grasp01/push_authorization.rs) | Push authorization | git-data-dir |
+| [`RepositoryCreationTests`](grasp-audit/src/specs/grasp01/repository_creation.rs) | Repository creation | git-data-dir |
 
-## Integration Testing Strategy
+### Spec Requirements Database
 
-### Repository Lifecycle Tests
+From [`grasp-audit/src/specs/grasp01/spec_requirements.rs`](grasp-audit/src/specs/grasp01/spec_requirements.rs):
 
 ```rust
-// tests/integration/repository_lifecycle.rs
-
-#[tokio::test]
-async fn test_repository_creation_on_announcement() {
-    let app = test_app().await;
-    
-    // Send repository announcement
-    let announcement = create_announcement()
-        .with_identifier("test-repo")
-        .with_clone_tag(app.domain())
-        .with_relay_tag(app.domain())
-        .sign()
-        .await;
-    
-    app.send_event(announcement).await.unwrap();
-    
-    // Wait for async processing
-    tokio::time::sleep(Duration::from_secs(1)).await;
-    
-    // Verify repository was created
-    let repo_path = app.git_data_path()
-        .join(announcement.author_npub())
-        .join("test-repo.git");
-    
-    assert!(repo_path.exists());
-    assert!(repo_path.join("HEAD").exists());
-    assert!(repo_path.join("config").exists());
+pub struct SpecRequirement {
+    pub id: &'static str,           // e.g., "GRASP-01:L9"
+    pub section: &'static str,      // e.g., "Nostr Relay"
+    pub level: RequirementLevel,    // MUST, SHOULD, MAY
+    pub text: &'static str,         // Exact text from spec
+    pub line: u32,                  // Line number in spec
 }
 
-#[tokio::test]
-async fn test_push_validation_flow() {
-    let app = test_app().await;
-    
-    // Create repository with state
-    let (announcement, state) = app.create_repo_with_state()
-        .branch("main", "commit-sha-123")
-        .build()
-        .await;
-    
-    // Attempt push matching state
-    let result = app.git_push("main", "commit-sha-123").await;
-    assert!(result.success);
-    
-    // Attempt push NOT matching state
-    let result = app.git_push("main", "different-sha-456").await;
-    assert!(!result.success);
-    assert!(result.stderr.contains("state event"));
+pub enum RequirementLevel {
+    Must,
+    Should,
+    May,
 }
 ```
 
-### Multi-Maintainer Tests
+### Automatic Cleanup Tags
+
+All audit events include cleanup tags for production safety (from [`grasp-audit/src/audit.rs`](grasp-audit/src/audit.rs)):
 
 ```rust
-#[tokio::test]
-async fn test_multi_maintainer_push() {
-    let app = test_app().await;
-    
-    // Alice creates repo, lists Bob as maintainer
-    let alice_announcement = create_announcement()
-        .author("alice")
-        .maintainers(vec!["bob"])
-        .build();
-    
-    app.send_event(alice_announcement).await.unwrap();
-    
-    // Bob creates state event
-    let bob_state = create_state()
-        .author("bob")
-        .branch("main", "commit-123")
-        .build();
-    
-    app.send_event(bob_state).await.unwrap();
-    
-    // Bob's push should succeed
-    let result = app.git_push_as("bob", "main", "commit-123").await;
-    assert!(result.success);
-}
+// Automatically added to EVERY audit event:
+["t", "grasp-audit-test-event"]              // Marker
+["t", "audit-{run_id}"]                      // Run isolation  
+["t", "audit-cleanup-after-{unix_timestamp}"] // Cleanup time
 ```
 
-## End-to-End Testing
+### Running grasp-audit
 
-### Real Git Client Tests
+**Testing the reference implementation (ngit-relay):**
 
-```rust
-// tests/e2e/git_client.rs
-
-#[tokio::test]
-async fn test_real_git_clone() {
-    let app = test_app().await;
-    
-    // Setup repository
-    let (announcement, _) = app.create_repo_with_commits()
-        .commit("Initial commit", "file.txt", "content")
-        .build()
-        .await;
-    
-    // Clone with real git client
-    let temp_dir = TempDir::new().unwrap();
-    let clone_url = format!(
-        "http://{}/{}/{}.git",
-        app.domain(),
-        announcement.author_npub(),
-        announcement.identifier()
-    );
-    
-    let output = Command::new("git")
-        .args(&["clone", &clone_url])
-        .current_dir(&temp_dir)
-        .output()
-        .await
-        .unwrap();
-    
-    assert!(output.status.success());
-    assert!(temp_dir.path().join(announcement.identifier()).exists());
-}
+```bash
+# Use test-ngit-relay.sh for automated relay management
+cd grasp-audit && nix develop -c bash test-ngit-relay.sh --mode test
 
-#[tokio::test]
-async fn test_real_git_push() {
-    let app = test_app().await;
-    
-    // Create repository
-    let (announcement, keys) = app.create_repo().await;
-    
-    // Clone it
-    let temp_dir = TempDir::new().unwrap();
-    git_clone(&app, &announcement, &temp_dir).await;
-    
-    // Make changes
-    let repo_dir = temp_dir.path().join(announcement.identifier());
-    tokio::fs::write(repo_dir.join("new-file.txt"), "content").await.unwrap();
-    
-    // Commit
-    git_commit(&repo_dir, "Add new file").await;
-    
-    // Send state event for new commit
-    let new_commit = git_rev_parse(&repo_dir, "HEAD").await;
-    app.send_state(&announcement, "main", &new_commit, &keys).await;
-    
-    // Push
-    let output = Command::new("git")
-        .args(&["push", "origin", "main"])
-        .current_dir(&repo_dir)
-        .output()
-        .await
-        .unwrap();
-    
-    assert!(output.status.success());
-}
+# Or manually:
+docker run --rm -p 18081:8081 ghcr.io/danconwaydev/ngit-relay:latest
+cd grasp-audit
+RELAY_URL="ws://localhost:18081" nix develop -c cargo test --lib -- --ignored --nocapture
 ```
 
-## Performance Testing
+**Testing ngit-grasp (the main project):**
 
-### Load Tests
+```bash
+# Integration tests use TestRelay fixture - just run:
+cargo test --test '*'
+```
 
-```rust
-// tests/performance/load.rs
+## Test Patterns
 
-#[tokio::test]
-async fn test_concurrent_pushes() {
-    let app = test_app().await;
-    
-    let num_concurrent = 100;
-    let mut handles = vec![];
-    
-    for i in 0..num_concurrent {
-        let app = app.clone();
-        let handle = tokio::spawn(async move {
-            let (announcement, state) = app.create_repo_with_state()
-                .branch("main", &format!("commit-{}", i))
-                .build()
-                .await;
-            
-            app.git_push("main", &format!("commit-{}", i)).await
-        });
-        handles.push(handle);
-    }
-    
-    let results = futures::future::join_all(handles).await;
-    
-    // All should succeed
-    for result in results {
-        assert!(result.unwrap().success);
-    }
-}
+### Isolated Test Pattern
+
+Each test runs with its own fresh relay instance:
 
+```rust
 #[tokio::test]
-async fn test_event_ingestion_throughput() {
-    let app = test_app().await;
-    
-    let num_events = 1000;
-    let start = Instant::now();
-    
-    for i in 0..num_events {
-        let event = create_announcement()
-            .with_identifier(&format!("repo-{}", i))
-            .build();
-        app.send_event(event).await.unwrap();
-    }
+async fn test_something() {
+    // Start fresh relay
+    let relay = TestRelay::start().await;
     
-    let duration = start.elapsed();
-    let throughput = num_events as f64 / duration.as_secs_f64();
+    // Run test
+    let client = AuditClient::new(relay.url(), AuditConfig::isolated()).await?;
+    // ... test logic ...
     
-    println!("Event throughput: {:.2} events/sec", throughput);
-    assert!(throughput > 100.0, "Throughput too low");
+    // Cleanup
+    relay.stop().await;
 }
 ```
 
-## Test Utilities
+### Macro-Based Test Generation
 
-### Test Fixtures
+For test suites that follow the same pattern, use macros:
 
 ```rust
-// tests/common/fixtures.rs
-
-pub struct TestEventBuilder {
-    kind: Kind,
-    content: String,
-    tags: Vec<Tag>,
-    keys: Option<Keys>,
-}
-
-impl TestEventBuilder {
-    pub fn announcement() -> Self {
-        TestEventBuilder {
-            kind: Kind::RepositoryAnnouncement,
-            content: String::new(),
-            tags: vec![],
-            keys: None,
+macro_rules! isolated_test {
+    ($test_name:ident) => {
+        #[tokio::test]
+        async fn $test_name() {
+            let relay = TestRelay::start().await;
+            // ... standard setup and teardown ...
         }
-    }
-    
-    pub fn with_identifier(mut self, id: &str) -> Self {
-        self.tags.push(Tag::Identifier(id.to_string()));
-        self
-    }
-    
-    pub fn with_clone_tag(mut self, url: &str) -> Self {
-        self.tags.push(Tag::new("clone", vec![url]));
-        self
-    }
-    
-    pub async fn build(self) -> Event {
-        let keys = self.keys.unwrap_or_else(|| Keys::generate());
-        EventBuilder::new(self.kind, self.content, self.tags)
-            .to_event(&keys)
-            .await
-            .unwrap()
-    }
-}
-```
-
-### Test Server
-
-```rust
-// tests/common/server.rs
-
-pub struct TestServer {
-    addr: SocketAddr,
-    handle: JoinHandle<()>,
-}
-
-impl TestServer {
-    pub async fn start() -> Self {
-        let config = Config {
-            domain: "localhost:0".to_string(),
-            git_data_path: TempDir::new().unwrap().into_path(),
-            relay_data_path: TempDir::new().unwrap().into_path(),
-            // ... other config
-        };
-        
-        let app = create_app(config).await;
-        let listener = TcpListener::bind("127.0.0.1:0").await.unwrap();
-        let addr = listener.local_addr().unwrap();
-        
-        let handle = tokio::spawn(async move {
-            axum::serve(listener, app).await.unwrap();
-        });
-        
-        // Wait for server to be ready
-        tokio::time::sleep(Duration::from_millis(100)).await;
-        
-        TestServer { addr, handle }
-    }
-    
-    pub fn url(&self) -> String {
-        format!("http://{}", self.addr)
-    }
-    
-    pub fn ws_url(&self) -> String {
-        format!("ws://{}", self.addr)
-    }
+    };
 }
-```
 
-## CI/CD Integration
-
-### GitHub Actions Workflow
-
-```yaml
-# .github/workflows/test.yml
-
-name: Test
-
-on: [push, pull_request]
-
-jobs:
-  unit-tests:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v3
-      - uses: actions-rs/toolchain@v1
-        with:
-          toolchain: stable
-      - name: Run unit tests
-        run: cargo test --lib
-  
-  integration-tests:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v3
-      - uses: actions-rs/toolchain@v1
-        with:
-          toolchain: stable
-      - name: Install Git
-        run: sudo apt-get install -y git
-      - name: Run integration tests
-        run: cargo test --test '*'
-  
-  compliance-tests:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v3
-      - uses: actions-rs/toolchain@v1
-        with:
-          toolchain: stable
-      - name: Run GRASP-01 compliance tests
-        run: cargo test --test compliance
-      - name: Generate compliance report
-        run: cargo run --example compliance-report > compliance-report.txt
-      - name: Upload compliance report
-        uses: actions/upload-artifact@v3
-        with:
-          name: compliance-report
-          path: compliance-report.txt
+isolated_test!(test_websocket_connection);
+isolated_test!(test_send_receive_event);
 ```
 
-## Test Coverage
+## Coverage Targets
 
-### Target Coverage
+| Test Type | Coverage Target |
+|-----------|-----------------|
+| Unit Tests | >80% line coverage of `src/` |
+| Integration Tests | All critical user paths |
+| GRASP-01 Compliance | 100% of MUST requirements |
 
-- **Unit Tests**: >80% line coverage
-- **Integration Tests**: All critical paths
-- **Compliance Tests**: 100% of GRASP-01 requirements
-- **E2E Tests**: Key user workflows
+## CI/CD Integration
 
-### Measuring Coverage
+### Running All Tests
 
 ```bash
-# Install tarpaulin
-cargo install cargo-tarpaulin
+# Unit tests (fast, no external dependencies)
+cargo test --lib
 
-# Run with coverage
-cargo tarpaulin --out Html --output-dir coverage
+# Integration tests (requires relay binary built)
+cargo build --release
+cargo test --test '*'
 
-# View report
-open coverage/index.html
-```
-
-## Documentation Testing
-
-### Doc Tests
-
-```rust
-/// Parse a pkt-line from Git protocol
-///
-/// # Examples
-///
-/// ```
-/// use ngit_grasp::git::parse_pkt_line;
-///
-/// let data = b"0006a\n";
-/// let (length, payload) = parse_pkt_line(data).unwrap();
-/// assert_eq!(length, 6);
-/// assert_eq!(payload, b"a\n");
-/// ```
-pub fn parse_pkt_line(data: &[u8]) -> Result<(usize, &[u8])> {
-    // implementation
-}
+# Compliance tests against ngit-relay reference
+cd grasp-audit && nix develop -c bash test-ngit-relay.sh --mode test
 ```
 
 ## Summary
 
-This comprehensive test strategy ensures:
+| What | Where | Purpose |
+|------|-------|---------|
+| Unit tests | `src/**/tests` modules | Test individual functions |
+| Integration tests | `tests/*.rs` | Test ngit-grasp as a whole |
+| TestRelay fixture | [`tests/common/relay.rs`](tests/common/relay.rs) | Manage relay lifecycle |
+| GRASP audit library | `grasp-audit/` | Reusable compliance testing |
+| GRASP-01 specs | [`grasp-audit/src/specs/grasp01/`](grasp-audit/src/specs/grasp01/) | Spec requirement tests |
 
-1. **Spec Compliance**: Every GRASP requirement has a corresponding test
-2. **Reusability**: Compliance tests can validate any GRASP implementation
-3. **Clear Failures**: Test failures cite exact spec lines
-4. **Comprehensive Coverage**: Unit, integration, compliance, and E2E tests
-5. **Maintainability**: Tests mirror spec structure for easy updates
+## Related Documentation
 
-The compliance testing tool is a standalone crate that can be:
-- Used by ngit-grasp for self-validation
-- Published for other GRASP implementations to use
-- Updated as new GRASP specs are released (GRASP-02, GRASP-05)
-- Run in CI/CD for continuous compliance verification
+- [Architecture](../explanation/architecture.md) - System design
+- [GRASP-01 Implementation Learnings](../learnings/grasp-01-implementation.md) - Patterns and lessons
+- [GRASP Audit Learnings](../learnings/grasp-audit.md) - Audit tool patterns
\ No newline at end of file