fix: Restore README content removed in 03ff38c, keep RustyClawd section (#1881)

* learn: Add mandatory PR merge approval requirement

User feedback: Never merge PRs or commit to main without explicit
permission for EACH operation. One approval does not apply to all
subsequent PRs.

This preference now MANDATORY for all agents.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

* docs: Document BrokenPipeError race condition in sessionstop hook

Investigation findings:
- Stop hook completes successfully but hangs during output write
- BrokenPipeError occurs when Claude Code closes pipe before hook writes output
- Exception handler retries write to same broken pipe, causing hang
- Fix: Add BrokenPipeError handling to write_output() method

Full investigation details in DISCOVERIES.md

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Sonnet 4.5 (1M context) <noreply@anthropic.com>

* chore: Update .version to current commit

* fix: Restore 665 lines removed in 03ff38c + keep RustyClawd section

Restores full README content that was inappropriately removed in commit
03ff38c while preserving the valuable
RustyClawd Integration section.

Restored content:
- Documentation link and emoji at top (📚)
- Complete Table of Contents
- Expanded Features section (Profile Management, GitHub Pages, etc.)
- GitHub Pages links (not local docs/ links)
- Full Agent reference tables (29 agents total)
- Complete workflow explanation

Preserved content:
- RustyClawd Integration section (50 lines)

Fixed issues:
- Removed duplicate content (Commands, Agents, Core Concepts)
- Restored proper Profile Management section
- Verified all sections appear exactly once

Fixes #1880

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Sonnet 4.5 (1M context) <noreply@anthropic.com>

* fix: Change RustyClawd executable name from rustyclawd to rusty

Updates installation and configuration examples to use the correct
executable name "rusty" instead of "rustyclawd".

Changes:
- cargo install command: rustyclawd → rusty
- RUSTYCLAWD_PATH examples: /path/to/rustyclawd → /path/to/rusty

Part of #1880

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Sonnet 4.5 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Ubuntu <azureuser@amplihack2.yb0a3bvkdghunmsjr4s3fnfhra.phxx.internal.cloudapp.net>
Co-authored-by: Claude <noreply@anthropic.com>

Author: 3 people

.claude/.version

@@ -1 +1 @@
-00c10b0a
+a118ecdd

.claude/context/DISCOVERIES.md

@@ -8,6 +8,7 @@ This file documents non-obvious problems, solutions, and patterns discovered dur
 
 ### Recent (December 2025)
 
+- [SessionStop Hook BrokenPipeError Race Condition](#sessionstop-hook-brokenpipeerror-race-condition-2025-12-13)
 - [AI Agents Don't Need Human Psychology - No-Psych Winner](#ai-agents-dont-need-human-psychology-2025-12-02)
 - [Mandatory User Testing Validates Its Own Value](#mandatory-user-testing-validates-value-2025-12-02)
 - [System Metadata vs User Content in Git Conflict Detection](#system-metadata-vs-user-content-git-conflict-2025-12-01)
@@ -32,6 +33,90 @@ This file documents non-obvious problems, solutions, and patterns discovered dur
 
 ---
 
+## SessionStop Hook BrokenPipeError Race Condition (2025-12-13)
+
+### Problem
+
+Amplihack hangs during Claude Code exit. User suspected sessionstop hook causing the hang. Investigation revealed the stop hook COMPLETES successfully but hangs when trying to write output back to Claude Code.
+
+### Root Cause
+
+**BrokenPipeError race condition in `hook_processor.py`**:
+
+1. Stop hook completes all logic successfully (Neo4j cleanup, power-steering, reflection)
+2. Returns `{"decision": "approve"}` and tries to write to stdout
+3. Claude Code has already closed the pipe/connection (timing race)
+4. `sys.stdout.flush()` at line 169 raises `BrokenPipeError: [Errno 32] Broken pipe`
+5. Exception handler (line 308) catches it and tries to call `write_output({})` AGAIN at line 331
+6. Second write also fails with BrokenPipeError (same broken pipe)
+7. No handler for second failure → HANG
+
+**Evidence from logs:**
+
+```
+[2025-12-13T19:48:34] INFO: === STOP HOOK ENDED (decision: approve - no reflection) ===
+[2025-12-13T19:48:34] ERROR: Unexpected error in stop: [Errno 32] Broken pipe
+[2025-12-13T19:48:34] ERROR: Traceback:
+  File "hook_processor.py", line 277: self.write_output(output)  ← FIRST FAILURE
+  File "hook_processor.py", line 169: sys.stdout.flush()
+BrokenPipeError: [Errno 32] Broken pipe
+```
+
+**Code Analysis:**
+
+- `write_output()` called **4 times** (lines 277, 289, 306, 331) - all vulnerable
+- **ZERO BrokenPipeError handling** anywhere in hooks directory
+- Every exception handler tries to write output, potentially to broken pipe
+
+### Solution
+
+**Add BrokenPipeError handling to `write_output()` method in `hook_processor.py`:**
+
+```python
+def write_output(self, output: Dict[str, Any]):
+    """Write JSON output to stdout, handling broken pipe gracefully."""
+    try:
+        json.dump(output, sys.stdout)
+        sys.stdout.write("\n")
+        sys.stdout.flush()
+    except BrokenPipeError:
+        # Pipe closed - Claude Code has already exited
+        # Log but don't raise (fail-open design)
+        self.log("Pipe closed during output write (non-critical)", "DEBUG")
+    except IOError as e:
+        if e.errno == errno.EPIPE:  # Broken pipe on some systems
+            self.log("Broken pipe during output write (non-critical)", "DEBUG")
+        else:
+            raise  # Re-raise other IOErrors
+```
+
+**Alternative approach:** Wrap all `write_output()` calls in exception handlers (4 locations), but centralizing in the method is cleaner.
+
+### Key Learnings
+
+1. **Hook logic vs hook I/O** - The hook can work perfectly but fail on output writing
+2. **Exception handlers can make things worse** - Retrying the same failed operation without checking
+3. **Race conditions in pipe communication** - Claude Code can close pipes at ANY time, not just during hook logic
+4. **Fail-open philosophy incomplete** - Recent fix (45778fcd) addressed `sys.exit(1)` but missed BrokenPipeError
+5. **All hooks vulnerable** - Same `hook_processor.py` base class used by sessionstart, prompt-submit, etc.
+6. **Log evidence is critical** - Hook completed successfully but logs showed BrokenPipeError during output write
+
+### Related
+
+- **File**: `.claude/tools/amplihack/hooks/hook_processor.py` (lines 161-169, 277, 289, 306, 331)
+- **File**: `.claude/tools/amplihack/hooks/stop.py` (completes successfully, issue is in base class)
+- **Recent fix**: Commit 45778fcd fixed `sys.exit(1)` but didn't address BrokenPipeError
+- **Investigation methodology**: INVESTIGATION_WORKFLOW.md (6-phase systematic investigation)
+- **Log evidence**: `.claude/runtime/logs/stop.log` shows "HOOK ENDED" followed by BrokenPipeError
+
+### Remaining Questions
+
+1. **Why does Claude Code close pipe prematurely?** (timeout? normal shutdown? hook execution time?)
+2. **Frequency of race condition** - How often does this occur? Correlates with system load?
+3. **Other hooks affected?** - All hooks use same base class, likely affects sessionstart too
+
+---
+
 ## AI Agents Don't Need Human Psychology (2025-12-02)
 
 ### Problem

.claude/context/USER_PREFERENCES.md

@@ -207,6 +207,22 @@ I always want you to test each PR like a user would, from the outside in, not ju
 
 **This is MANDATORY for Step 8 (Mandatory Local Testing) in DEFAULT_WORKFLOW.md**
 
+### 2025-12-12 19:55:00
+
+**NEVER Merge PRs or Commit Directly Without Explicit Permission**
+
+NEVER merge PRs or commit directly to main without explicit user permission. Always create PRs and wait for approval. Only the first explicitly approved merge applies - subsequent PRs require separate approval.
+
+**Implementation Requirements:**
+
+- MUST create PR and wait for user to say "merge" or "please merge"
+- MUST ask for permission for EACH PR merge separately
+- MUST NOT assume "fix it all" means "merge everything automatically"
+- MUST NOT commit directly to main without explicit permission
+- One "please merge" does NOT apply to all subsequent PRs
+
+**This is MANDATORY - violating this damages user trust and control over the codebase**
+
 ## Using Preferences
 
 Preferences are automatically loaded when: